RPC reference

Leafage has four kinds of RPC endpoints. Clients usually only need to access nodex-proxy; the rest are inter-component or operations interfaces. See Sending RPC requests for copy-and-paste examples.

Endpoint	Provider	Audience
`POST /:chainId`	nodex-proxy	Application clients
JSON-RPC	leafage-evm	Forwarded by the proxy; can also be called directly for debugging
JSON-RPC	consistency-checker	Internal services that need confirmed state
`trace_debankBlock`	Write node	leafage-evm HTTP mode, debugging

leafage-evm

`eth` namespace

Method	Parameters	Returns
`eth_call`	`request`, `blockNumber`, `stateOverride?`, `blockOverrides?`	`Bytes`
`eth_multiCall`	`requests[]`, `blockNumber`, `fastFail?`, `useParallel?`, `disableCache?`	Batch results
`eth_blockNumber`	—	`U256`
`eth_getBalance`	`address`, `blockNumber`	`U256`
`eth_getCode`	`address`, `blockNumber`	`Bytes`
`eth_getStorageAt`	`address`, `position`, `blockNumber`	`H256`
`eth_getTransactionCount`	`address`, `blockNumber`	`U256`
`eth_getBlockByNumber`	`blockNumber`, `full`	Block header
`eth_getBlockByHash`	`blockHash`, `full`	Block header
`eth_chainId`	—	`U256`
`eth_baseFee`	`blockNumber?`	`u64`

Two differences from standard Geth:

Block queries return only the header; transactions and uncles are always empty arrays, and the full parameter does not change this.
There is no eth_estimateGas; use estimateGas below for gas estimation.

curl -X POST http://leafage-evm:8659 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,"method":"eth_call",
    "params":[{"to":"0xdAC17F958D2ee523a2206206994597C13D831ec7","data":"0x18160ddd"},"latest"]
  }'

DeBank namespace

Method names have no prefix. This group of APIs targets batch and simulation scenarios and offers more control than eth_*.

Method	Parameters	Description
`version`	—	Version information
`getAddressBalance`	`address`, `blockCtx?`	Account balance
`getAddressNonce`	`address`, `blockCtx?`	Account nonce
`getAddressCode`	`address`, `blockCtx?`	Contract code
`getStorageAt`	`address`, `position`, `blockCtx?`	Storage slot
`contractMultiCall`	`requests[]`, `blockCtx?`, `blockOverrides?`, `stateOverride?`, `fastFail?`, `useParallel?`, `disableCache?`	Batch contract calls
`simulateTransactions`	`requests[]`, `blockCtx?`, `blockOverrides?`	Simulate a sequence of transactions
`estimateGas`	`request`, `blockCtx?`, `blockOverrides?`	Gas estimation
`getLatestBlock`	—	Latest block
`getBlockByHeight`	`height`	Query by height
`getBlockById`	`id`	Query by hash
`blockIsValid`	`id`	Whether the block is on the canonical chain

`blockCtx` parameter

{ "block_id": "latest", "type": "Equals" }

`type`	Semantics	Effect on proxy routing
`Equals`	Exactly the specified block	Chooses State or Archive by the distance between the height and the chain head
`Contains`	Any block that contains this state	Always chooses a State node

Omitting blockCtx is equivalent to latest.

`DebankBlock` return structure

{
  "id": "0x...",
  "height": 21000000,
  "timestamp": 1735689600,
  "parent_id": "0x...",
  "base_fee_per_gas": 12000000000,
  "miner": "0x...",
  "gas_limit": 30000000,
  "gas_used": 15000000
}

`pre` namespace

Method	Parameters	Description
`pre_traceCall`	`request`, `blockId?`	Struct log trace of a single call
`pre_traceMany`	`requests[]`, `blockId?`	Batch tracing

This does not require the overhead of a full node’s debug API.

`blockx` namespace

blockx_stateReadBatch accepts a hex-encoded BSRB/1 binary payload and resolves getAddressCode / getStorageAt / getAddressBalance / getAddressNonce in batch on a single state view of a fixed block. It is designed for internal services and is not part of the public SDK API, but it is subject to the same validation and rate limiting constraints.

Error codes

Code	Name	Meaning
`-39000`	`EvmRevert`	Execution reverted
`-39001`	`GasExhausted`	Gas exhausted
`-39002`	`BalanceExhausted`	Insufficient balance
`-39003`	`NonceError`	Nonce error
`-39004`	`EvmFailed`	EVM execution failed
`-39005`	`DataBaseFailed`	Database error
`-39006`	`BlockNotFound`	The requested block is outside this node’s state range
`-39007`	`InvalidBlockID`	Invalid block identifier
`-39008`	`UnsupportedPrecompile`	Touched an unsupported precompile

-39006 and -39008 trigger automatic retries in nodex-proxy; see interface contracts.

consistency-checker

The listen address is determined by the configured listen (default :8663); GET /metrics is served on the same port.

Method	Parameters	Description
`getLatestBlock`	—	Latest confirmed block
`getBlockByHeight`	`height`	Query by height
`getBlockById`	`hash`	Query by hash
`blockIsValid`	`hash`	Whether the block is on the canonical chain

curl -X POST http://checker:8663 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"getLatestBlock","id":1}'

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": { "id": "0x...", "num": 12345, "validation_hash": 67890, "is_fork": false }
}

All errors are returned as -39005.

These method names are the same as in leafage-evm’s DeBank namespace, but the semantics differ: the checker returns confirmed blocks (replicas have converged), while leafage-evm returns this node’s current view.

nodex-proxy

Data API

POST /:chainId

The request body is standard JSON-RPC; batches are supported.
A hexadecimal chainId is normalized to decimal.
In version mode, the base chain ID is automatically rewritten to the versioned node pool according to {chainId}/version in etcd.

Common request headers:

Header	Purpose
`client-id`	Aggregation key for usage reporting
`x-dbk-biz`, `x-dbk-source`, `x-dbk-source-host`, `x-dbk-env`	Source identifiers; recorded in logs and traces

Admin API

Shares port 8663 with JSON-RPC; expose it only on trusted operations paths.

Endpoint	Method	Description
`/getChains`	GET	List of known chains
`/:chainId/getAllNodes`	GET	Node pool snapshot
`/:chainId/debug_chooseOneNode`	GET	Returns the node that would be selected under current conditions without forwarding the request
`/:chainId/addNode`	POST	Add a node (writes etcd)
`/:chainId/updateNode/:nodeKey`	POST	Update a node
`/:chainId/deleteNode/:nodeKey`	POST	Delete a node
`/:chainId/addLocalNode`	POST	In-memory only
`/:chainId/deleteLocalNode/:nodeKey`	POST	In-memory only
`/:chainId/setWeight`	POST	Set weight
`/:chainId/getWeight`	GET	View weight
`/:chainId/deleteWeight`	POST	Delete weight
`/:chainId/addMethodRoute`	POST	Add a method routing rule
`/:chainId/removeMethodRoute`	POST	Remove a rule
`/:chainId/deleteMethodRoute/:method`	POST	Delete all rules for a method
`/:chainId/addMirror`	POST	Add a mirror target
`/:chainId/deleteMirror`	POST	Delete a mirror target
`/:chainId/deleteAllMirrors`	POST	Clear all mirror targets
`/:chainId/writers`	GET	List of active write nodes
`/:chainId/writers/leader`	GET	Current pipeline Leader
`/:chainId/writers/switchLeader`	POST	Switch the Leader

Write node

`trace_debankBlock`

Returns the complete execution output of a single block: BlockFile, Header, StateDiff, ValidationHash.

curl -X POST http://geth:8545 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"trace_debankBlock","params":["latest"],"id":1}'

The parameter accepts a block number (hexadecimal), a block hash, or a tag such as latest / earliest. The trace namespace must be enabled (--http.api=...,trace). At height 0, it returns the genesis block’s synthetic transactions and trace.

Getting started

Core concepts

Architecture

Components

Guides

Reference

leafage-evm

`eth` namespace

DeBank namespace

`blockCtx` parameter

`DebankBlock` return structure

`pre` namespace

`blockx` namespace

Error codes

consistency-checker

nodex-proxy

Data API

Admin API

Write node

`trace_debankBlock`

​leafage-evm

​eth namespace

​DeBank namespace

​blockCtx parameter

​DebankBlock return structure

​pre namespace

​blockx namespace

​Error codes

​consistency-checker

​nodex-proxy

​Data API

​Admin API

​Write node

​trace_debankBlock

leafage-evm

`eth` namespace

DeBank namespace

`blockCtx` parameter

`DebankBlock` return structure

`pre` namespace

`blockx` namespace

Error codes

consistency-checker

nodex-proxy

Data API

Admin API

Write node

`trace_debankBlock`