Skip to main content

​
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.

​
Key Relay Features

The relay offers several advanced features that enhance dApp development on Hedera:

​
Real-Time Data and Event Filtering

The relay provides robust support for real-time data streaming and event filtering through its WebSocket server and Filter API methods. This allows applications to listen for on-chain events and receive updates as they happen.
  • WebSocket Support (eth_subscribe): Developers can establish a WebSocket connection to the relay (default: ws://localhost:8546) to subscribe to logs and newHeads events. This is ideal for applications that need to react instantly to new blocks or specific contract events. This functionality is enabled by HIP-694.
  • Filter API Methods: The relay supports the standard Ethereum Filter API, including eth_newFilter, eth_getFilterChanges, and eth_getFilterLogs. These methods allow you to create and query filters for historical logs and pending transactions, providing a powerful way to track contract activity.

​
Paymaster Support for Gasless Transactions

The JSON-RPC relay supports a paymaster feature, enabling gasless transactions for users. When this feature is enabled, the relay operator can sponsor transaction fees, allowing dApp users to interact with smart contracts without needing to hold HBAR for gas. This is ideal for improving user onboarding and creating seamless application experiences. Key features of paymaster support include:
  • Gasless Transactions: Users can send transactions with a gas price of 0.
  • Operator-Sponsored Fees: The relay operator covers the HAPI and Ethereum fees.
  • Flexible Configuration: Operators can enable paymaster support for all transactions (wildcard) or restrict it to a whitelist of specific smart contract addresses.
💡For more details on how to configure and use the paymaster feature, please refer to the configuration details in the Hiero JSON RPC Relay repository.

​
Testing with Network Forking

Hedera now supports network forking, which allows you to test smart contracts against a live network’s state without executing transactions on the actual network. This is a feature for development and debugging, as it lets you simulate transactions and contract interactions in a realistic environment. You can fork the Hedera network using both Hardhat and Foundry. For detailed instructions and examples, please refer to our tutorials:

​
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.

​
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.
MethodStatic Response Value
eth_blockNumberN/A
eth_sendRawTransactionN/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.
MethodStatic Response Value
eth_getBalancen/a
eth_getStorageAtn/a
eth_getTransactionCountn/a
eth_getCoden/a
eth_calln/a
eth_estimateGasgenerates and returns an estimate of the gas required for 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.
MethodStatic Response Value
eth_getBlockTransactionCountByHashn/a
eth_getBlockTransactionCountByNumbern/a
eth_getUncleCountByBlockHashnull
eth_getUncleCountByBlockNumber0x0
eth_getBlockByHashstateRoot is always zero
eth_getBlockByNumberstateRoot is always zero
eth_getTransactionByHashn/a
eth_getTransactionByBlockHashAndIndexn/a
eth_getTransactionByBlockNumberAndIndexn/a
eth_getTransactionReceiptn/a
eth_getUncleByBlockHashAndIndexnull
eth_getUncleByBlockNumberAndIndexnull
💡See the full list of methods here.

​
Supported EVM Development Tools

Featureweb3jsTruffleethersHardhatRemix IDEFoundry
Transfer HBARS✅✅✅✅✅✅
Contract Deployment✅✅✅✅✅✅
Can use the contract instance after deploy without re-initialization✅✅✅✅✅✅
Contract View Function Call✅✅✅✅✅✅
Contract Function Call✅✅✅✅✅✅
Debug Operations**✅✅✅✅✅✅
**Debug operations are supported via the debug_traceTransaction and debug_traceBlockByNumber methods. To enable these methods, you must set DEBUG_API_ENABLED=true in your relay configuration. For more information, see the debugging documentation.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.

​
Additional Resources