区块通知与规范链

Leafage 的所有组件都围绕同一条区块流工作：写节点按执行顺序发布区块变更通知，查询节点和 consistency-checker 按同样的顺序消费。这条流里有三个需要分清的概念：通知、规范链与分叉块、已发布与已确认。

区块变更通知

写节点每确定一次新的 canonical head，就向 Kafka 内部 topic 发布一条 BlockChangeNotification：

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

通知里只有元信息，没有数据体。消费者拿到哈希后自己去 S3 取 Header 和 StateDiff。Kafka 因此只承担顺序和低延迟，大对象走 S3 可以并行拉取。

属性	值	含义
分区	单分区	全序区块流，所有消费者看到同样的顺序
发布者	仅 Leader 写节点	多个写节点不会发出重复或交错的通知
消费方式	每个查询节点独立 `assign` 分区并自管 offset	每个副本都收到全部消息，不是消费组内分摊
发布时机	`writeBlockAndSetHead` 确定 canonical head 后	此前的区块可能还会被重组

S3 上传与 Kafka 发布不是原子操作。消费者收到通知时对应的 S3 对象通常已就绪，但必须容忍短暂的 404 并重试。

规范链与分叉块

规范链是写节点当前 canonical head 所在的那条链。写节点发布通知前，把上一条已发布的区块与新 head 做共同祖先比较：

上次发布的 head: A ─ B ─ C
当前 head:       A ─ B ─ D ─ E

共同祖先 B
dropBlocks = [C]        changeType = 2
newBlocks  = [D, E]

只有新块时 changeType 为 1，newBlocks 按高度升序；存在被丢弃的分支时 changeType 为 2，同时带 dropBlocks 和 newBlocks。被丢弃的块就是分叉块。它们不会从系统里消失：

位置	分叉块的去向
S3	对象保留。写节点上传时不知道它会不会被丢弃，`BlockValidation` 的 `is_fork` 上传时恒为 `false`
查询节点内存	差异层保留在 `hash_diff_map`，从 `num_diff_map` 摘除；按哈希仍可查，按高度走新的规范链
consistency-checker	把 S3 上对应的 `BlockValidation` 重写为 `is_fork: true`，并向外部 topic 发出带 `is_fork: true` 的通知

同一高度在 S3 外部桶的前缀 {chainID}[/{version}]/{height}/ 下可能有多个对象，is_fork 是区分它们的唯一依据。查询节点冷启动追赶时靠它把高度解析成规范哈希。

已发布与已确认

写节点发布通知的那一刻，查询节点还没有应用这个区块。直接订阅内部 topic 的消费者会在“去查还查不到”的时候收到通知。consistency-checker 在中间加了一道确认：

	已发布	已确认
通知所在 topic	内部 topic `nodex_pipeline_{chainID}`	外部 topic `pipeline_{chainID}`
发布者	写节点 Leader	consistency-checker
含义	写节点已执行并上传	达到 `ready_ratio`（默认 0.8）的查询节点已追上该高度
消费者	leafage-evm、consistency-checker	索引器、分析平台等外部系统
消息结构	`BlockChangeNotification`	`OuterBlockChangeNotification`

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 先发 drop 通知，再发新块通知。外部消费者因此得到一个保证：收到通知时，去查询集群一定能读到这个区块。等待副本超过 check_timeout_ms（默认 2000 毫秒）仍未达标时，checker 不发布该区块并整体重试。

同一个区块，三处记录

一个区块被确认后，链路上有三个地方各自记着它，服务不同的读取者：

位置	记录内容	读取者
查询节点状态树	差异层，按哈希与高度索引	`eth_call` 等状态查询
consistency-checker 的 Pebble DB	`h{hash}` → 区块信息，`n{number}` → 哈希	`getLatestBlock`、`blockIsValid` 等确认状态查询
etcd `{chainID}[/{version}]/lastBlockNumber`	已确认的最新高度	nodex-proxy 的 State / Archive 路由

leafage-evm 和 consistency-checker 都提供 getLatestBlock / getBlockByHeight / getBlockById / blockIsValid，方法名相同但语义不同：前者返回本节点当前视图，后者返回已确认的区块。

小结

区块变更通知只含哈希、高度等元信息，单分区全序，仅 Leader 发布；数据体在 S3。
重组表达为 changeType: 2 加 dropBlocks；被丢弃的分叉块在 S3 和查询节点内存中都保留，由 consistency-checker 回写 is_fork。
已发布（内部 topic）与已确认（外部 topic）是两条不同的流，外部消费者应当只订阅后者。
已确认高度写在 etcd 的 lastBlockNumber，是 nodex-proxy 判断 State / Archive 的依据。

继续阅读：

区块上下文与路由：请求如何表达“要哪个区块”，以及已确认高度如何参与路由。
数据链路：reorg 在写节点、leafage-evm 与 checker 三处的处理细节。
接口契约：两个 topic 的命名、编码与生产者配置。

开始使用

核心概念

架构

组件

指南

参考

区块变更通知

规范链与分叉块

已发布与已确认

同一个区块，三处记录

小结

​区块变更通知

​规范链与分叉块

​已发布与已确认

​同一个区块，三处记录

​小结

区块变更通知

规范链与分叉块

已发布与已确认

同一个区块，三处记录

小结