> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leafage.chaintable.com/llms.txt
> Use this file to discover all available pages before exploring further.
# RPC reference
> APIs exposed by leafage-evm, consistency-checker, nodex-proxy, and the write node
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](/en/guides/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.
```bash theme={null}
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
```json theme={null}
{ "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
```json theme={null}
{
"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](/en/architecture/interfaces#routing-related-error-codes).
## 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 |
```bash theme={null}
curl -X POST http://checker:8663 \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","method":"getLatestBlock","id":1}'
```
```json theme={null}
{
"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
```text theme={null}
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`.
```bash theme={null}
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.