接口契约

组件之间不直接调用，只通过 Kafka、S3、etcd 和少量 RPC 协作。这些是跨仓库改动时需要保持兼容的部分。

下文中 {version} 段是可选的。启用版本模式后，Kafka topic、S3 键和 etcd 键都会带上版本命名空间，用于在同一套基础设施上并行运行多个数据版本。

Kafka

内部 topic

写节点发布，leafage-evm 和 consistency-checker 消费。

项	值
默认命名	`nodex_pipeline_{chainID}` / `nodex_pipeline_{chainID}_{version}`
消息 Key	`NewBlock`
消息 Value	`BlockChangeNotification`，JSON + gzip
消息 Header	区块首次可见时间戳，用于端到端延迟打点
生产者配置	`RequiredAcks=all`，`BatchSize=1`（低延迟优先）

type BlockChangeNotification struct {
    ChangeType uint64         `json:"changeType"` // 1=新块, 2=重组
    NewBlocks  []BlockContext `json:"newBlocks"`  // 按高度升序
    DropBlocks []BlockContext `json:"dropBlocks"` // 重组时被丢弃的块
}

type BlockContext struct {
    Hash        common.Hash `json:"hash"`
    ParentHash  common.Hash `json:"parentHash"`
    BlockNumber uint64      `json:"blockNumber"`
    Timestamp   uint64      `json:"timestamp"`
}

内部 topic 承载的是全序区块流，必须使用单分区。leafage-evm 通过显式 assign 固定分区并自行持久化 offset（关闭自动提交），因此所有副本都能收到全部消息，而不是消费组内分摊。partition 由 --kafka-s3-config 里的 partition 字段指定。

外部 topic

consistency-checker 发布，外部消费者订阅。leafage-evm 不消费这个 topic。

项	值
惯例命名	singleton topic `pipeline_{chainID}`，version topic `pipeline_{chainID}_{version}`
消息 Key	`NewBlock`
消息 Value	`OuterBlockChangeNotification`，JSON + gzip

type OuterBlockChangeNotification struct {
    ChainID     int64       `json:"chain_id"`
    Hash        common.Hash `json:"block_id"`
    BlockNumber uint64      `json:"block_height"`
    Timestamp   uint64      `json:"block_timestamp"`
    IsFork      bool        `json:"is_fork"`
}

新块和被丢弃的块用同一个结构表达，靠 is_fork 区分。版本模式下 checker 同时写 version topic 和 singleton topic，后者只有持有 etcd 锁的 Leader 才写。

S3

两个桶按消费者划分，键都以 chainID 开头，因此多条链可以共用同一个桶。

内部桶（NodeX Bucket）

对象	键	编码
Header	`{chainID}[/{version}]/{blockHash}/block`	JSON + gzip
StateDiff	`{chainID}[/{version}]/{stateRoot}/stateDiff`	RLP

StateDiff 以 state root 而非区块哈希为键：state root 相同的相邻区块共享同一个对象，空块因此不产生新对象。leafage-evm 在父块与当前块 state root 相同时会跳过拉取，直接视为空差异。

type BlockStorageDiff struct {
    Hash            common.Hash          // 当前 state root
    ParentHash      common.Hash          // 父 state root
    NewAccounts     []NewAccount         // 新增或更新的账户
    DeletedAccounts []common.Hash        // 被删除的账户
    StorageDiff     []AccountStorageDiff // 存储变更
    NewCodes        []NewCode            // 新部署的合约代码
}

外部桶（ChainTable Bucket）

对象	键	编码
BlockFile	`{chainID}[/{version}]/{blockHash}`	JSON + gzip
BlockValidation	`{chainID}[/{version}]/{height}/{blockHash}`	JSON + gzip

BlockFile 包含区块、交易、调用追踪和事件日志，是外部消费者的主要数据来源。BlockValidation 是同一份数据的校验摘要，同时充当按高度的索引：

type BlockValidation struct {
    ValidationHash        int64 // 校验和
    IsFork                bool  // 由 consistency-checker 回写
    TxsCount              int
    EventsCount           int
    TracesCount           int
    ErrorEventsCount      int
    ErrorTracesCount      int
    StorageContractsCount int
}

前缀 {chainID}[/{version}]/{height}/ 下列出的对象即该高度的所有候选区块。两个组件依赖这个索引：

consistency-checker 把非规范的对象重写为 is_fork: true
leafage-evm 在 S3 追赶时用它把高度解析为规范区块哈希

字段完整定义见 pipeline 仓库的 docs/protocol.md。

etcd 键空间

所有键以 chainID 开头（可选 version 段），不同链天然隔离。

键	写入方	读取方	值
`{chainID}[/{version}]/nodes/{ip}_{port}`	leafage-evm 自注册；consistency-checker 更新状态	consistency-checker、nodex-proxy	节点信息 JSON
`{chainID}[/{version}]/lastBlockNumber`	consistency-checker	nodex-proxy	`{"latestBlockNumber":"0x..."}`
`{chainID}/nativeNodes/{nodeKey}`	运维	nodex-proxy	节点信息 JSON
`{chainID}/gateway`	运维 / nodex-proxy 管理 API	nodex-proxy	权重与方法路由
`{chainID}/mirror/{addrKey}`	运维 / nodex-proxy 管理 API	nodex-proxy	镜像目标
`{chainID}/version`	运维	consistency-checker、nodex-proxy	当前生效的版本号
`{chainID}[/{version}]/writers/{nodeID}`	pipeline（带租约）	nodex-proxy	写节点注册信息
`{chainID}[/{version}]/writers/leader`	pipeline	pipeline 各实例	当前 Leader 的 nodeID
`{chainID}/outer_block_notice`	consistency-checker	consistency-checker	singleton 发布权的分布式锁

节点信息的结构：

{
  "address": "10.0.90.11",
  "port": 8659,
  "nodeType": 1,
  "stateType": 1,
  "weight": 100,
  "source": "manual"
}

字段	取值
`nodeType`	`1` = State 节点，`2` = Archive 节点
`stateType`	`1` = 已追上链头，`2` = 落后，`3` = 离线
`weight`	负载均衡权重，缺省 `100`

节点生命周期的分工：leafage-evm 启动时把自己写成 stateType: 2（落后），之后由 consistency-checker 每轮轮询后改写为 1 或 2；节点离线且没有租约时，consistency-checker 直接删除该键。nodex-proxy 只 watch 这些键，自己不写入健康状态。

版本切换

{chainID}/version 是版本模式的控制点，两个组件同时读它：

consistency-checker 比较自身 version 配置与 etcd 中的值，一致时争抢 {chainID}/outer_block_notice 锁，成为向 singleton topic 发布的 Leader。
nodex-proxy 把请求里的基础 chainId 改写为 {chainId}-{version}，路由到版本化的节点池。

RPC 契约

`trace_debankBlock`

写节点提供，用于在没有 Kafka 的场景下获取单个区块的完整执行输出。leafage-evm 的 HTTP 回退模式依赖它。

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

返回 DebankOutPut，包含 BlockFile、Header、StateDiff 和 ValidationHash——与 S3 上四类对象的内容一一对应。

健康检查

调用方	目标	方法
consistency-checker	leafage-evm	`eth_blockNumber`
nodex-proxy	State / Archive 节点	`getLatestBlock`
nodex-proxy	Native 节点	`eth_blockNumber`

nodex-proxy 的健康检查每 5 秒重试一次，直到 node_health_check_max_wait（默认 300 秒）。只有通过检查的节点才会进入负载均衡池。

路由相关错误码

leafage-evm 返回这些错误码时，nodex-proxy 会自动改选节点池重试一次。

错误码	名称	含义	重试目标
`-39006`	`StateBlockNotFound`	请求的高度不在 State 节点的状态范围内	Archive 节点
`-39008`	`CosmosPrecompile`	调用触及需要原链能力的预编译	Native 节点

兼容性约定

改动跨组件接口时需要注意：

Kafka 消息结构只增字段、不改语义。消费者用 JSON 解码，多余字段会被忽略，但缺字段会导致零值误判。
S3 键格式是 leafage-evm、consistency-checker 和外部消费者共同依赖的硬编码约定，改动需要同步三方并考虑存量对象。
etcd 键格式同样硬编码在三个组件里，{chainID} 与 {version} 段的拼接方式必须一致。
错误码是路由行为的一部分，新增需要在 nodex-proxy 侧同步处理逻辑。

开始使用

架构

组件

指南

参考

Kafka

内部 topic

外部 topic

S3

内部桶（NodeX Bucket）

外部桶（ChainTable Bucket）

etcd 键空间

版本切换

RPC 契约

`trace_debankBlock`

健康检查

路由相关错误码

兼容性约定

​Kafka

​内部 topic

​外部 topic

​S3

​内部桶（NodeX Bucket）

​外部桶（ChainTable Bucket）

​etcd 键空间

​版本切换

​RPC 契约

​trace_debankBlock

​健康检查

​路由相关错误码

​兼容性约定

Kafka

内部 topic

外部 topic

S3

内部桶（NodeX Bucket）

外部桶（ChainTable Bucket）

etcd 键空间

版本切换

RPC 契约

`trace_debankBlock`

健康检查

路由相关错误码

兼容性约定