Forking Hedera Network for Local Testing

This guide explains how fork testing works on Hedera, how it differs from traditional EVM chains, and how the hedera-forking library enables local development with Hedera System Contracts.

---

What is Fork Testing?

Fork Testing (also known as Fixtures) is an Ethereum Development Environment feature that optimizes test execution for smart contracts. It enables:

• Snapshotting blockchain state - Avoiding recreation of the entire blockchain state for each test
• Using remote state locally - Any modifications only affect the local (forked) network
• No private key requirements - Test against remote network state without managing keys
• Debugging tools - Use console.log and other debugging features during testing

Popular Ethereum development environments that support fork testing include:

• Foundry (using Anvil)
• Hardhat (using EDR/EthereumJS)

---

Why is Hedera Different?

Standard EVM Contracts Work Out-of-the-Box

Fork testing works seamlessly for standard EVM smart contracts that don’t involve Hedera-specific services. The local test networks provided by development environments are replicas of the Ethereum network.

Hedera System Contracts Require Emulation

Fork testing does not work out-of-the-box for contracts that use Hedera-specific services like:

• Hedera Token Service (HTS) at address 0x167
• Exchange Rate at address 0x168
• PRNG at address 0x169
• Hedera Account Service at address 0x16a

This is because when the development environment tries to fetch the code at these addresses, the JSON-RPC Relay returns 0xfe (invalid opcode):

$ cast code --rpc-url https://mainnet.hashio.io/api 0x0000000000000000000000000000000000000167
0xfe

This leads to the error EvmError: InvalidFEOpcode when running tests. This is precisely where the hedera-forking library comes in to provide an emulation layer for Hedera System Contracts. For example, with Hardhat, the plugin intercepts JSON-RPC calls to return the appropriate bytecode and state for HTS and for Foundry, the library uses ffi to fetch state from the Mirror Node. This is explained in detail below.

---

How Hedera Forking Works

The hedera-forking project provides an emulation layer for Hedera System Contracts written in Solidity. Since it’s written in Solidity, it can be executed in any development network environment.

Architecture Overview

The project consists of two main components:

1. Solidity Contracts - Provide HTS emulation designed for forked networks
2. JS Package - Hooks into JSON-RPC layer to fetch appropriate data when HTS or Hedera Tokens are invoked (used by Hardhat)

Both the Foundry library and the Hardhat plugin use the main HtsSystemContract implementation. This contract provides the behavior of HTS, but it is state agnostic - meaning the HTS and token state must be provided elsewhere.

Given Foundry and Hardhat provide different capabilities, they differ significantly in how the state is provided to HTS.

---

How Token State is Retrieved

Foundry and Hardhat use different mechanisms to retrieve token state from the Mirror Node. Understanding these differences is important for troubleshooting and optimizing your fork testing workflow.

Foundry Library Approach

The Foundry library uses a proactive prefetch approach where token state is fetched within Solidity contracts before it’s needed.

Key Components:

• HtsSystemContractJson - Extends HtsSystemContract with JSON data source support
• MirrorNodeFFI - Fetches data from Mirror Node using Foundry’s ffi cheatcode

How it works:

1. When your test calls Hsc.htsSetup(), the library deploys HtsSystemContractJson at address 0x167
2. When you access token state (e.g., balanceOf), HtsSystemContractJson overrides the slot access
3. The contract calls MirrorNodeFFI which uses ffi to execute curl (or PowerShell on Windows) to fetch data from the Mirror Node
4. The fetched data is written to storage using vm.store cheatcode (not sstore) to avoid StateChangeDuringStaticCall errors
5. The data is then returned to your test

Why FFI is Required:

• Foundry does not allow creating a JSON-RPC forwarder like Hardhat
• However, Foundry allows hooking into internal contract calls via cheatcodes
• The ffi cheatcode enables executing external commands (like curl) from Solidity

Hardhat Plugin Approach

The Hardhat plugin uses a reactive interception approach where a Worker thread intercepts JSON-RPC calls made by Hardhat.

Key Components:

• JSON-RPC Forwarder - A Worker thread that intercepts eth_getCode and eth_getStorageAt calls
• MirrorNodeClient (JavaScript) - Fetches data from Mirror Node using the fetch API

How it works:

1. When your test runs, Hardhat makes JSON-RPC calls to fetch remote state
2. The Hardhat plugin’s Worker intercepts eth_getCode and eth_getStorageAt calls
3. For eth_getCode(0x167): Returns the compiled HtsSystemContract bytecode
4. For eth_getCode(tokenAddress): Returns the HIP-719 Token Proxy bytecode
5. For eth_getStorageAt(token, slot): Uses the storage layout to map the slot to a field, then fetches the value from Mirror Node
6. The fetched data is returned to Hardhat’s local network

Why a Worker Thread is Required:

• Hardhat does not allow hooking into internal contract calls (see issue #56)
• The plugin must intercept at the JSON-RPC level before Hardhat processes the requests
• The Worker thread runs asynchronously to handle the interception

Comparison: Foundry vs Hardhat Approaches

Aspect	Foundry Library	Hardhat Plugin
State Fetching	Proactive (prefetch in Solidity)	Reactive (intercept JSON-RPC)
Data Fetcher	MirrorNodeFFI (Solidity + curl)	MirrorNodeClient (JavaScript + fetch)
Hook Point	Internal contract calls via cheatcodes	JSON-RPC layer via Worker thread
Requirement	ffi = true in foundry. toml	chainId and workerPort in config
OS Dependency	curl (Unix) or PowerShell (Windows)	Node.js fetch API
Storage Writes	vm.store cheatcode	Returned via JSON-RPC response

---

HTS Supported Methods

The emulation layer supports a subset of HTS functionality. Refer to https://github.com/hashgraph/hedera-forking#hedera-token-service-supported-methods for the latest list.

---

Limitations and Important Notes

The HTS emulation contract SHOULD ONLY be used to ease development workflow when working with Hedera Tokens. The HTS emulation contract DOES NOT replicate Hedera Token Services fully. Behavior might differ when switching from local development to a real Hedera network.

Always test your contracts against a real Hedera network before launching your contracts.

Key Limitations

1. Behavior differences - Some edge cases may behave differently in emulation vs. the real Hedera network.

2. Block number considerations - When forking from a specific block, ensure your deployed contracts exist at that block number.

3. Rate limiting - When running many tests (especially fuzz tests), you may hit RPC rate limits. Consider lowering fuzz run counts.

4. Storage layout constraints - Solidity mappings compute storage slots that are not reversible, which required special handling in the emulation layer.

5. Foundry ffi requirement - The Foundry library requires ffi = true which allows executing external commands. This is necessary for curl calls to the Mirror Node.

6. Hardhat async limitations - The Hardhat plugin requires manual configuration of chainId and workerPort because Hardhat plugin loading is synchronous.

---

Development Framework Support

Foundry

The Foundry library uses ffi (Foreign Function Interface) to fetch remote state from the Mirror Node using curl (or PowerShell on Windows).

Key setup:

• Enable ffi = true in foundry.toml
• Call Hsc.htsSetup() in your test setup

How it fetches data:

import {Hsc} from "hedera-forking/Hsc.sol";

function setUp() public {
    Hsc.htsSetup(); // Deploys HtsSystemContractJson at 0x167
}

When you access token state, the library:

1. Intercepts the storage slot access
2. Uses MirrorNodeFFI to call curl via ffi
3. Parses the JSON response
4. Writes data using vm.store cheatcode

Hardhat

The Hardhat plugin intercepts JSON-RPC calls (eth_getCode and eth_getStorageAt) to provide HTS emulation.

Key setup:

• Install @hashgraph/system-contracts-forking
• Import the plugin in hardhat.config.ts
• Configure chainId and workerPort in forking config

Configuration example:

import "@hashgraph/system-contracts-forking/plugin";

// In your hardhat.config.ts
hardhat:  {
  forking: {
    url: "https://mainnet.hashio.io/api",
    blockNumber: 70531900,
    // @ts-ignore - custom properties for hedera-forking plugin
    chainId:  295, // Required: 295 (mainnet), 296 (testnet), 297 (previewnet)
    // @ts-ignore
    workerPort:  1235 // Required: Any free port
  }
}

---

Learn How to Fork the Hedera Network for Local Testing

How to Fork the Hedera Network with Hardhat - Basic ERC-20 Tutorial

How to Fork the Hedera Network with Hardhat - Advanced HTS Tutorial

How to Fork the Hedera Network with Foundry - Basic ERC-20 Tutorial

---

Further Resources

• hedera-forking GitHub Repository
• Internals Documentation
• FAQ
• HIP-719: Token Proxy Contract
• Foundry Fork Testing Documentation
• Hardhat Mainnet Forking Documentation

Writer: Kiran Pachhai, Developer Advocate

GitHub | LinkedIn