Skip to main content

Ethereum JSON-RPC reference

Ethereum and native methods share the node's RPC endpoint. The local devnet uses http://127.0.0.1:30400 and ws://127.0.0.1:30400. Public hosts are proposed.

Use POST / with Content-Type: application/json. Parameters are positional arrays. Quantities use canonical hex (0x0, not 0x00); addresses and hashes are fixed-size hex data.

Common methods​

MethodParametersResult / notes
eth_chainId[]Hex chain ID
net_version[]Decimal chain-ID string
web3_clientVersion[]Client profile string
eth_blockNumber[]Committed height
eth_getBalance[address, blockTag?]JOLT in base units
eth_getTransactionCount[address, blockTag?]Nonce; pending (also as an EIP-1898 selector) includes consecutive pool transactions
eth_getCode[address, blockTag?]Runtime bytes
eth_getStorageAt[address, slot, blockTag?]Storage word
eth_call[callObject, blockTag?]Unsigned simulated output
eth_estimateGas[callObject, blockTag?]Succeeding gas estimate under the bounded search
eth_sendRawTransaction[signedEthereumEnvelope]Pool transaction hash; gas limit ≤ 1,000,000; no inclusion guarantee
eth_getTransactionByHash[hash]Transaction or null; pending block fields are null
eth_getTransactionReceipt[hash]Committed receipt or null
eth_getBlockByNumber[blockTag, fullTransactions]Block or null
eth_getBlockByHash[ethereumBlockHash, fullTransactions]Block or null
eth_getBlockReceipts[blockTag]Committed receipts
eth_getLogs[filter]Bounded address/topic-filtered logs
eth_gasPrice, eth_maxPriorityFeePerGas[]Development fee suggestion
eth_feeHistory[count, newestBlock, percentiles?]Bounded fee history
eth_subscribe[event, filter?]WebSocket-only subscription ID
eth_unsubscribe[subscriptionId]Boolean

Balance example​

curl http://127.0.0.1:30400 \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266","latest"]}'

Decode the result as a 256-bit base-unit quantity; divide by 10^18 for JOLT. The amount depends on genesis and prior activity.

Simulation example​

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "eth_estimateGas",
  "params": [{
    "from": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
    "to": "0x000000000000000000000000000000000000beef",
    "value": "0xde0b6b3a7640000"
  }]
}

A plain eligible value transfer estimates 21,000 gas (0x5208). Estimates are state-dependent and do not check signatures/account-policy authorization as a signed admission would. Reverts use error code 3 with revert bytes.

Other supported methods​

Block/transaction count and index lookup methods, uncle queries, web3_sha3, net_listening, net_peerCount, eth_syncing, eth_accounts, eth_mining, eth_hashrate, eth_blobBaseFee, and polling filter creation/change/log/uninstall methods are supported.

eth_accounts is empty, eth_syncing and eth_mining are false, and net_peerCount reports zero because peer ownership is outside this RPC service. No uncles exist. Polling filters are shared bounded state: at most 64 exist, the least recently polled is evicted first, and filters do not expire by time. Each poll covers at most 1,024 blocks and resumes at whole blocks. A log filter's fromBlock may name a future height and starts there. Persist your own event cursor.

Block tags and identifiers​

latest, safe, finalized and pending select the committed head; earliest selects genesis. EIP-1898 block-number/hash objects are accepted. Historical state requires retained trie nodes.

Ethereum block selectors use the Ethereum header hash. Native proofs use the different certified Joltzu block identifier, stored in the Ethereum header's extraData.

The EVM BLOCKHASH opcode uses persisted native identifiers for the preceding 256 blocks, rather than the Ethereum RPC header hashes. Keep these namespaces separate in on-chain/off-chain comparisons.

Compatibility boundaries​

  • Supported signed envelopes: legacy 0x0, access list 0x1, dynamic fee 0x2; native JZTX appears as type 0x4a in indexed results.
  • No blob transactions, EIP-7702 authorizations or base-fee market in this profile.
  • stateRoot commits Joltzu's native/EVM layout, not Ethereum's account trie.
  • eth_getProof, eth_createAccessList, node-side signing, debug_*, trace_* and txpool_* are unavailable.
  • State overrides are rejected. eth_call is simulation, not account-policy approval.
  • EVM execution uses Osaka with documented native host additions, including balance-preserving SELFDESTRUCT behavior.
  • Local browser web-page Origins are refused. Remote gateway authentication and limits are separate.

See errors and limits, event indexing and Porting from other EVM chains.

Ethereum method shapes follow the execution API specification, subject to the compatibility boundaries above.