> ## 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 参考

> leafage-evm、consistency-checker、nodex-proxy 和写节点对外暴露的接口

Leafage 里有四类 RPC 端点。客户端通常只需要访问 nodex-proxy，其余是组件间或运维接口。

| 端点                  | 提供者                 | 面向                     |
| ------------------- | ------------------- | ---------------------- |
| `POST /:chainId`    | nodex-proxy         | 应用客户端                  |
| JSON-RPC            | leafage-evm         | proxy 转发，也可直连调试        |
| JSON-RPC            | consistency-checker | 需要确认状态的内部服务            |
| `trace_debankBlock` | 写节点                 | leafage-evm HTTP 模式、调试 |

## leafage-evm

### `eth` 命名空间

| 方法                        | 参数                                                                        | 返回      |
| ------------------------- | ------------------------------------------------------------------------- | ------- |
| `eth_call`                | `request`, `blockNumber`, `stateOverride?`, `blockOverrides?`             | `Bytes` |
| `eth_multiCall`           | `requests[]`, `blockNumber`, `fastFail?`, `useParallel?`, `disableCache?` | 批量结果    |
| `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`                                                     | 区块头     |
| `eth_getBlockByHash`      | `blockHash`, `full`                                                       | 区块头     |
| `eth_chainId`             | —                                                                         | `U256`  |
| `eth_baseFee`             | `blockNumber?`                                                            | `u64`   |

<Warning>
  两个与标准 Geth 的差异：

  * 区块查询**只返回 header**，`transactions` 和 `uncles` 恒为空数组，`full` 参数不改变这一点。
  * **没有 `eth_estimateGas`**，gas 估算用下面的 `estimateGas`。
</Warning>

```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 命名空间

方法名没有前缀。这组接口面向批量和模拟场景，比 `eth_*` 提供更多控制。

| 方法                     | 参数                                                                                                           | 说明       |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ | -------- |
| `version`              | —                                                                                                            | 版本信息     |
| `getAddressBalance`    | `address`, `blockCtx?`                                                                                       | 账户余额     |
| `getAddressNonce`      | `address`, `blockCtx?`                                                                                       | 账户 nonce |
| `getAddressCode`       | `address`, `blockCtx?`                                                                                       | 合约代码     |
| `getStorageAt`         | `address`, `position`, `blockCtx?`                                                                           | 存储槽      |
| `contractMultiCall`    | `requests[]`, `blockCtx?`, `blockOverrides?`, `stateOverride?`, `fastFail?`, `useParallel?`, `disableCache?` | 批量合约调用   |
| `simulateTransactions` | `requests[]`, `blockCtx?`, `blockOverrides?`                                                                 | 模拟交易序列   |
| `estimateGas`          | `request`, `blockCtx?`, `blockOverrides?`                                                                    | Gas 估算   |
| `getLatestBlock`       | —                                                                                                            | 最新区块     |
| `getBlockByHeight`     | `height`                                                                                                     | 按高度查询    |
| `getBlockById`         | `id`                                                                                                         | 按哈希查询    |
| `blockIsValid`         | `id`                                                                                                         | 是否在规范链上  |

#### `blockCtx` 参数

```json theme={null}
{ "block_id": "latest", "type": "Equals" }
```

| `type`     | 语义         | 对 proxy 路由的影响              |
| ---------- | ---------- | -------------------------- |
| `Equals`   | 精确指定的区块    | 按高度与链头的距离选 State 或 Archive |
| `Contains` | 任何包含该状态的区块 | 始终选 State 节点               |

省略 `blockCtx` 等同于 `latest`。

#### `DebankBlock` 返回结构

```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` 命名空间

| 方法              | 参数                       | 说明                  |
| --------------- | ------------------------ | ------------------- |
| `pre_traceCall` | `request`, `blockId?`    | 单个调用的 struct log 追踪 |
| `pre_traceMany` | `requests[]`, `blockId?` | 批量追踪                |

不需要全节点 debug API 的开销。

### `blockx` 命名空间

`blockx_stateReadBatch` 接受十六进制编码的 BSRB/1 二进制载荷，在固定区块的一个状态视图上批量解析 `getAddressCode` / `getStorageAt` / `getAddressBalance` / `getAddressNonce`。为内部服务设计，不属于公开 SDK 接口，但同样受校验和限流约束。

### 错误码

| 码        | 名称                      | 含义              |
| -------- | ----------------------- | --------------- |
| `-39000` | `EvmRevert`             | 执行 revert       |
| `-39001` | `GasExhausted`          | Gas 耗尽          |
| `-39002` | `BalanceExhausted`      | 余额不足            |
| `-39003` | `NonceError`            | nonce 错误        |
| `-39004` | `EvmFailed`             | EVM 执行失败        |
| `-39005` | `DataBaseFailed`        | 数据库错误           |
| `-39006` | `BlockNotFound`         | 请求的区块不在本节点状态范围内 |
| `-39007` | `InvalidBlockID`        | 区块标识非法          |
| `-39008` | `UnsupportedPrecompile` | 触及不支持的预编译       |

`-39006` 和 `-39008` 会触发 nodex-proxy 的自动重试，见[接口契约](/architecture/interfaces#路由相关错误码)。

## consistency-checker

监听地址由配置的 `listen` 决定（默认 `:8663`），同端口提供 `GET /metrics`。

| 方法                 | 参数       | 说明      |
| ------------------ | -------- | ------- |
| `getLatestBlock`   | —        | 最新已确认区块 |
| `getBlockByHeight` | `height` | 按高度查询   |
| `getBlockById`     | `hash`   | 按哈希查询   |
| `blockIsValid`     | `hash`   | 是否在规范链上 |

```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 }
}
```

错误统一返回 `-39005`。

<Note>
  这组方法名与 leafage-evm 的 DeBank 命名空间相同，但语义不同：checker 返回的是**已确认**的区块（副本已收敛），leafage-evm 返回的是本节点当前的视图。
</Note>

## nodex-proxy

### 数据接口

```text theme={null}
POST /:chainId
```

请求体是标准 JSON-RPC（支持批量）。`chainId` 十六进制会被规范化为十进制。版本模式下，基础链 ID 会按 etcd 中的 `{chainId}/version` 自动改写到版本化节点池。

常用请求头：

| 头                                                          | 作用               |
| ---------------------------------------------------------- | ---------------- |
| `client-id`                                                | 用量上报的聚合键         |
| `x-dbk-biz`、`x-dbk-source`、`x-dbk-source-host`、`x-dbk-env` | 来源标识，进入日志与 trace |

### 管理接口

与 JSON-RPC 共用 `8663` 端口，只应暴露在可信运维路径上。

| 接口                                    | 方法   | 说明                   |
| ------------------------------------- | ---- | -------------------- |
| `/getChains`                          | GET  | 已知链列表                |
| `/:chainId/getAllNodes`               | GET  | 节点池快照                |
| `/:chainId/debug_chooseOneNode`       | GET  | 返回当前条件下会被选中的节点，不转发请求 |
| `/:chainId/addNode`                   | POST | 新增节点（写 etcd）         |
| `/:chainId/updateNode/:nodeKey`       | POST | 更新节点                 |
| `/:chainId/deleteNode/:nodeKey`       | POST | 删除节点                 |
| `/:chainId/addLocalNode`              | POST | 只改内存                 |
| `/:chainId/deleteLocalNode/:nodeKey`  | POST | 只改内存                 |
| `/:chainId/setWeight`                 | POST | 设置权重                 |
| `/:chainId/getWeight`                 | GET  | 查看权重                 |
| `/:chainId/deleteWeight`              | POST | 删除权重                 |
| `/:chainId/addMethodRoute`            | POST | 新增方法路由规则             |
| `/:chainId/removeMethodRoute`         | POST | 移除规则                 |
| `/:chainId/deleteMethodRoute/:method` | POST | 删除某方法的全部规则           |
| `/:chainId/addMirror`                 | POST | 新增镜像目标               |
| `/:chainId/deleteMirror`              | POST | 删除镜像目标               |
| `/:chainId/deleteAllMirrors`          | POST | 清空镜像目标               |
| `/:chainId/writers`                   | GET  | 活跃写节点列表              |
| `/:chainId/writers/leader`            | GET  | 当前 pipeline Leader   |
| `/:chainId/writers/switchLeader`      | POST | 切换 Leader            |

## 写节点

### `trace_debankBlock`

返回单个区块的完整执行输出：`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}'
```

参数接受区块号（十六进制）、区块哈希或 `latest` / `earliest` 等标签。需要启用 `trace` 命名空间（`--http.api=...,trace`）。

高度为 0 时返回创世块的合成交易与 trace。