- Fork Hedera testnet using Foundry
- Deploy an ERC-20 contract to Hedera testnet
- Run Foundry tests on a fork of Hedera testnet
- Read and interact with an existing ERC-20 contract by its EVM address (e.g.,
balanceOf,name,symbol,transfer), with minimal setup - The process to set up and run tests is similar for mainnet as well
- Repo: hashgraph/hedera-forking
- Readme sections: Foundry library, Running your Tests
- Examples:
examples/foundry-hts/
For a deeper understanding of how Hedera forking works and its limitations,
see Forking Hedera Network for Local
Testing.
You can take a look at the complete code in the
basic-erc20-fork-test-foundry
repository.
Prerequisites
- Foundry installed
- ECDSA account from the Hedera Portal
- Basic understanding of Solidity
- A Hedera JSON-RPC endpoint:
- mainnet:
https://mainnet.hashio.io/api - testnet:
https://testnet.hashio.io/api
- mainnet:
Table of Contents
- Step 1: Project Setup
- Step 2: Create the ERC-20 Contract and Deploy to Testnet
- Step 3: Write Tests for the Forked Network
- Step 4: Run Tests on the Forked Network
Step 1: Project Setup
Initialize Project
Create a new directory and initialize the Foundry project:Install Dependencies
Install OpenZeppelin contracts and the Hedera forking library:Configure Remappings
Create or updateremappings.txt in your project root:
remappings.txt
Note that we are updating the
remappings.txt in our root directory of the
project and not in the lib directory where the dependencies are installed.Set Environment Variables
Create a.env file in your project root:
. env
Configure Foundry
Update yourfoundry.toml file in the root directory of your project. Open it and add profiles for the Hedera RPC endpoints.
foundry.toml
ffi to be true because on forked tests, the library uses curl (or PowerShell) to query Hedera Mirror Node for token state so that EVM calls like IERC721.ownerOf() can work as if the token were a normal EVM contract.
We will be removing the default contracts that comes with foundry default project:
Step 2: Create the ERC-20 Contract and Deploy to Testnet
Create the Contract
Create a new filesrc/ERC20Token.sol:
src/ERC20Token.sol
- Creates a basic ERC-20 token named “MyToken” with symbol “MTK”
- Mints 10,000 tokens to a recipient on deployment
- Has an
onlyOwnermintfunction for additional minting
Compile the Contract
Create Deployment Script
Create a new filescript/Deploy.s.sol:
script/Deploy.s.sol
Deploy to Testnet
Deploy your contract to Hedera testnet:Step 3: Write Tests for the Forked Network
Now we’ll write tests that interact with the already deployed contract on the forked testnet. This is the real power of fork testing - you can test against real deployed contracts without spending gas or affecting the live network. Create a new filetest/ERC20Token.t.sol:
Make sure to update the
DEPLOYED_CONTRACT constant below with the contract
address from your deployment.test/ERC20Token.t.sol
- Uses deployed contract - Tests bind to the already deployed contract address
- Impersonation with
vm.prank- Uses Foundry’s cheatcode to act as the real owner - Reads real state - Token info, balances, etc. come from the actual testnet deployment
- Local modifications - All transfers, mints happen only on the local fork
- No testnet changes - The real testnet is never modified
Step 4: Run Tests on the Forked Network
Run your tests against the forked Hedera testnet:Pin to a Specific Block
For reproducible tests, you can pin to a specific block number:29970059 for this testing because the contract from above(i.e. 0xfC7D2FB1D5a9Be5D6182cBf3F283140d007CdcD4 was deployed on block 29970059. If we tried to run our tests with block below this, it would fail such as:
Understanding Fork Testing with Deployed Contracts
Why Test Against Deployed Contracts?
- Real-world state - Test against actual balances, allowances, and state
- No deployment costs - Don’t spend gas deploying for every test run
- Impersonation - Act as any account (even the contract owner) without their private key
- Safe experimentation - Try anything without affecting the real network
How Impersonation Works in Foundry
Foundry provides cheatcodes for impersonation:Funding Accounts with vm.deal
Fund test accounts with native tokens:
Local vs. Remote State
Further Learning & Next Steps
- How to Fork Hedera with Foundry - Advanced HTS (Part 2)
Continue with HTS System Contracts and the hedera-forking emulation layer - Forking Hedera Network for Local Testing
Deep dive into how Hedera forking works under the hood - How to Fork Hedera with Hardhat (Part 1)
Learn fork testing with Hardhat framework - How to Fork Hedera with Hardhat - Advanced HTS
Compare the Hardhat approach to HTS fork testing - hedera-forking Repository
Explore examples and documentation