Skip to content

rpc-api.md

Latest commit

 

History

History
154 lines (126 loc) · 29.2 KB

rpc-api.md

File metadata and controls

154 lines (126 loc) · 29.2 KB

As an implementation of HIP 419, the Hedera JSON RPC Relay provides some Ethereum JSON-RPC APIs which implement the JSON-RPC 2.0 Specification to support Ethereum tools interacting with Hedera nodes e.g. wallets, developer tools.

Requests

Requests to the Relay will take the form of HTTP calls to an endpoints method. A curl example to the eth_chainId takes the form Request

  curl ${RELAY_ENDPOINT_URL} -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":"2","method":"eth_chainId","params":[null]}'

Where

  • RELAY_ENDPOINT_URL - HTTP url endpoint, default http://localhost:7546

Result Schema

Result responses can take the form of success or error.

Success Response

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": "0x4b7"
}

Error Response

{
  "id": 2,
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params"
  }
}

The values can range from regular data types (String, int, array) to defined Ethereum objects such as:

Endpoints

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

Endpoint Tables

Below are comprehensive tables of all Ethereum JSON-RPC methods and additional non-standard methods.

Ethereum JSON-RPC Standard Methods

Below is a comprehensive table of all Ethereum JSON-RPC methods from the Ethereum JSON-RPC API specification and Ethereum JSON-RPC 2.0 specification.

Method Implementation Status Hedera Nodes Hedera Specifics
eth_accounts Implemented - Returns [] N/A Always returns empty array per Infura behavior
eth_blobBaseFee Implemented - Returns -32601 (Method not supported) N/A EIP-4844 blob transactions not supported
eth_blockNumber Implemented Mirror Node
eth_call Implemented Mirror Node
eth_chainId Implemented N/A Returns configured chain ID from environment
eth_coinbase Implemented - Returns -32601 (Method not supported) N/A Fixed zero address as Hedera has no traditional coinbase
eth_createAccessList Not Implemented - Returns -32601 (Method not found) N/A
eth_estimateGas Implemented Mirror Node Uses mirror node gas estimation
eth_feeHistory Implemented Mirror Node Returns Hedera gas prices and utilization data
eth_gasPrice Implemented Mirror Node Returns current Hedera gas price in tinybars converted to wei
eth_getBalance Implemented Mirror Node Returns HBAR balance converted to wei
eth_getBlockByHash Implemented Mirror Node
eth_getBlockByNumber Implemented Mirror Node
eth_getBlockReceipts Implemented Mirror Node
eth_getBlockTransactionCountByHash Implemented Mirror Node
eth_getBlockTransactionCountByNumber Implemented Mirror Node
eth_getCode Implemented Mirror Node
eth_getFilterChanges Implemented Mirror Node Filter state stored in configurable cache (LRU or Redis)
eth_getFilterLogs Implemented Mirror Node Filter state stored in configurable cache (LRU or Redis)
eth_getLogs Implemented Mirror Node Subject to Mirror Node query limits
eth_getProof Implemented - Returns -32601 (Method not supported) N/A Merkle proofs not supported
eth_createAccessList Implemented - Returns -32601 (Method not supported) N/A Generates an access list for a transaction
eth_getStorageAt Implemented Mirror Node
eth_getTransactionByBlockHashAndIndex Implemented Mirror Node
eth_getTransactionByBlockNumberAndIndex Implemented Mirror Node
eth_getTransactionByHash Implemented Mirror Node
eth_getTransactionCount Implemented Mirror Node Returns account nonce
eth_getTransactionReceipt Implemented Mirror Node
eth_getUncleByBlockHashAndIndex Implemented - Returns null N/A No uncle blocks in Hedera
eth_getUncleByBlockNumberAndIndex Implemented - Returns null N/A No uncle blocks in Hedera
eth_getUncleCountByBlockHash Implemented - Returns 0x0 N/A No uncle blocks in Hedera
eth_getUncleCountByBlockNumber Implemented - Returns 0x0 N/A No uncle blocks in Hedera
eth_getWork Implemented - Returns -32601 (Method not supported) N/A Mining not applicable to Hedera
eth_hashrate Implemented - Returns 0x0 N/A Mining not applicable to Hedera
eth_maxPriorityFeePerGas Implemented - Returns 0x0 N/A Returns same value as gasPrice since Hedera doesn't have priority fees
eth_mining Implemented - Returns false N/A Mining not applicable to Hedera
eth_newBlockFilter Implemented Mirror Node Filter state stored in configurable cache (LRU or Redis)
eth_newFilter Implemented Mirror Node Filter state stored in configurable cache (LRU or Redis)
eth_newPendingTransactionFilter Implemented Mirror Node Filter state stored in configurable cache (LRU or Redis)
eth_protocolVersion Implemented - Returns -32601 (Method not supported) N/A Not supported on Hedera
eth_sendRawTransaction Implemented Consensus Node, Mirror Node Submits to Consensus Node, polls Mirror Node for confirmation
eth_sendTransaction Implemented - Returns -32601 (Method not supported) N/A Account management not supported
eth_sign Implemented - Returns -32601 (Method not supported) N/A Account management not supported
eth_signTransaction Implemented - Returns -32601 (Method not supported) N/A Account management not supported
eth_signTypedData Implemented - Returns -32601 (Method not found) N/A Account management not supported
eth_simulateV1 Not Implemented N/A
eth_submitHashrate Implemented - Returns -32601 (Method not supported) N/A Mining not applicable to Hedera
eth_submitWork Implemented - Returns false N/A Mining not applicable to Hedera
eth_syncing Implemented - Returns false N/A Hedera network is always synced
eth_uninstallFilter Implemented N/A Filter state stored in configurable cache (LRU or Redis)
net_listening Implemented - Returns true N/A Relay always returns true for this
net_peerCount Implemented - Returns -32601 (Method not supported) N/A Relay doesn't maintain peer connections
net_version Implemented N/A Returns configured chain ID as string
web3_clientVersion Implemented N/A Returns relay version information
web3_sha3 Implemented N/A Computes Keccak-256 hash locally

Non-Standard / Extended Methods

These methods are extensions provided by various Ethereum clients but are not part of the core Ethereum JSON-RPC specification.

Method Implementation Status Hedera Nodes Hedera Specifics
admin_config Implemented N/A Returns relay and upstream dependency configuration
debug_getBadBlocks Implemented - Requires DEBUG_API_ENABLED=true N/A Always returns empty array
debug_getRawBlock Implemented - Requires DEBUG_API_ENABLED=true N/A
debug_getRawHeader Implemented - Requires DEBUG_API_ENABLED=true N/A
debug_getRawReceipts Implemented - Requires DEBUG_API_ENABLED=true N/A
debug_getRawTransaction Implemented - Requires DEBUG_API_ENABLED=true Mirror Node Returns RLP-encoded transaction or 0x if not found
debug_traceBlockByHash Implemented - Requires DEBUG_API_ENABLED=true Mirror Node Supports CallTracer and PrestateTracer, caches results
debug_traceBlockByNumber Implemented - Requires DEBUG_API_ENABLED=true Mirror Node Supports CallTracer and PrestateTracer, caches results
debug_traceTransaction Implemented - Requires DEBUG_API_ENABLED=true Mirror Node Supports CallTracer and OpcodeLogger tracers
engine_* Implemented - Returns -32601 (Method not supported) for all engine methods N/A Engine API not applicable to Hedera
trace_block Not Implemented N/A
trace_blockByNumber Not Implemented N/A
trace_transaction Not Implemented N/A
txpool_content Implemented - Requires TXPOOL_API_ENABLED=true and ENABLE_TX_POOL=true N/A
txpool_contentFrom Implemented - Requires TXPOOL_API_ENABLED=true and ENABLE_TX_POOL=true N/A
txpool_status Implemented - Requires TXPOOL_API_ENABLED=true and ENABLE_TX_POOL=true N/A

Live events API

Details for the Real-Time Events API can be found here

Open RPC Spec

The detailed schema specifications of the current methods offerred by the JSON RPC relay is captured in our Open RPC Specification
⚡