JSON-RPC Relay and EVM Tooling

Overview

Hiero's JSON-RPC relay provides a familiar interface for EVM developers by supporting standard Ethereum JSON RPC methods. This compatibility means you can use popular EVM development tools (like Hardhat, Truffle, or Foundry) and wallets (like Metamask) to interact with Hedera’s network. However, Hedera’s unique state management model affects how you retrieve historical data and verify states, requiring a shift in approach from the standard EVM workflow.

---

Ethereum RPC API Behavior via JSON-RPC Relay

On Ethereum, methods like eth_getBlockByNumber return the true value of stateRoot that enables direct historical state verification. Hiero's JSON-RPC relay, however, returns the root hash of an empty Merkle trie for the stateRoot value for compatibility. Instead of relying on it, you should query Hedera’s mirror nodes for historical states, event logs, and transaction details.

Example JSON-RPC Query Request:

A request to eth_getBlockByNumber returns a stateRoot, but it’s not useful for historical verification on Hedera. Instead, use mirror node REST APIs to fetch the necessary historical information.

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
          "jsonrpc": "2.0",
          "method": "eth_getBlockByNumber",
          "params": [
              "0x1",
              false
          ],
          "id": 1
     }' \
     https://testnet.hashio.io/api

This returns the root hash of an empty Merkle trie for compatibility and not the actual stateRoot value.

---

Testing Without Snapshots

Hedera does not support contract snapshot feature commonly used in testing. Instead:

• Use modular test designs, deploying fresh contracts before each test.

• Leverage Hedera’s testnet or previewnet for integration testing.

• Query mirror nodes for state verification over time.

• Maintain isolated accounts for each test to ensure a clean environment.

Code Example: Modular Testing with Contract Redeployment

pragma solidity ^0.8.0;

contract TestContract {
    uint256 public value;

    function setValue(uint256 _value) public {
        value = _value;
    }

    function reset() public {
        value = 0;
    }
}

contract TestSuite {
    TestContract testContract;

    // Deploy a fresh contract for each test
    function deployNewContract() public {
        testContract = new TestContract();
    }

    // Example test: setValue
    function testSetValue(uint256 _value) public {
        testContract.setValue(_value);
        require(testContract.value() == _value, "Value not set correctly");
    }

    // Example test: reset
    function testReset() public {
        testContract.reset();
        require(testContract.value() == 0, "Value not reset correctly");
    }
}

---

Endpoints

The JSON RPC Relay methods implement a subset of the standard method:

Gossip Methods

These methods track the head of the chain. This is how transactions make their way around the network, find their way into blocks, and how clients find out about new blocks.

Method	Static Response Value
eth_blockNumber	N/A
eth_sendRawTransaction	N/A

State Methods

Methods that report the current state of all the data stored. The "state" is like one big shared piece of RAM, and includes account balances, contract data, and gas estimations.

Method	Static Response Value
eth_getBalance	N/A
eth_getStorageAt	N/A
eth_getTransactionCount	N/A
eth_getCode	N/A
eth_call	N/A
eth_estimateGas	Generates and returns an estimate of how much gas is necessary to allow the transaction to complete.

History Methods

Fetches historical records of every block back to genesis. This is like one large append-only file, and includes all block headers, block bodies, uncle blocks, and transaction receipts.

Method	Static Response Value
eth_getBlockTransactionCountByHash	N/A
eth_getBlockTransactionCountByNumber	N/A
eth_getUncleCountByBlockHash	null
eth_getUncleCountByBlockNumber	0x0
eth_getBlockByHash	Note that stateRoot value returned is always zero.
eth_getBlockByNumber	Note that stateRoot value returned is always zero.
eth_getTransactionByHash	N/A
eth_getTransactionByBlockHashAndIndex	N/A
eth_getTransactionByBlockNumberAndIndex	N/A
eth_getTransactionReceipt	N/A
eth_getUncleByBlockHashAndIndex	null
eth_getUncleByBlockNumberAndIndex	null

💡 See the full list of methods here.

---

Supported EVM Development Tools

Feature	web3js	Truffle	ethers	Hardhat	Remix IDE	Foundry
Transfer HBARS	✅	✅	✅	✅	✅	✅
Contract Deployment	✅	✅	✅	✅	✅	✅
Can use the contract instance after deploy without re-initialization	✅	✅	✅	✅	✅	✅
Contract View Function Call	✅	✅	✅	✅	✅	✅
Contract Function Call	✅	✅	✅	✅	✅	✅
Debug Operations*	❌	❌	❌	❌	❌	❌

*1: Debug operations are not supported yet.

Note: Development tools usually make a lot of requests to certain endpoints, especially during contract deployment. Be aware of rate limiting when deploying multiple large contracts.

Note: Enable development mode to correctly assert revert messages of contract calls with hardhat-chai-matchers.

💡 See the full list of supported EVM tools here.

---

Additional Resources

• Supported EVM Tooling
• JSON-RPC Relay Docs
• Hiero JSON-RPC Relay Repo