RPC 参考

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`

两个与标准 Geth 的差异：

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

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` 参数

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

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

省略 blockCtx 等同于 latest。

`DebankBlock` 返回结构

{
  "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 的自动重试，见接口契约。

consistency-checker

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

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

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

错误统一返回 -39005。

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

nodex-proxy

数据接口

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。

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。

开始使用

架构

组件

指南

参考

leafage-evm

`eth` 命名空间

DeBank 命名空间

`blockCtx` 参数

`DebankBlock` 返回结构

`pre` 命名空间

`blockx` 命名空间

错误码

consistency-checker

nodex-proxy

数据接口

管理接口

写节点

`trace_debankBlock`

​leafage-evm

​eth 命名空间

​DeBank 命名空间

​blockCtx 参数

​DebankBlock 返回结构

​pre 命名空间

​blockx 命名空间

​错误码

​consistency-checker

​nodex-proxy

​数据接口

​管理接口

​写节点

​trace_debankBlock

leafage-evm

`eth` 命名空间

DeBank 命名空间

`blockCtx` 参数

`DebankBlock` 返回结构

`pre` 命名空间

`blockx` 命名空间

错误码

consistency-checker

nodex-proxy

数据接口

管理接口

写节点

`trace_debankBlock`