写节点

写节点是 Leafage 里唯一参与 P2P 同步和区块执行的角色。它就是这条链原本的执行客户端（ETH 用 Chaintable/go-ethereum，其他链用各自的分叉），Leafage 在它上面只附加了一层数据导出能力。客户端本身的用法、同步模式和 RPC 请参考对应上游项目的文档。本页只说明附加的部分。

项	值
ETH 参考实现	Chaintable/go-ethereum，当前合并到上游 v1.17.4
附加内容	pipeline tracer 集成、`trace_debankBlock`、区块变更通知、历史裁剪
改动规模	相对上游约 2000 行，集中在少数文件
其他链	op-geth、reth、nitro、erigon 等分叉，改动方式相同，仓库列表

附加的集成点

文件	附加内容
`core/tracing/hooks.go`	新增 `OnCommit` 和 `OnBlockDBStart` 两个 hook 类型
`core/blockchain.go`	分发新 hook；确定 canonical head 时计算 reorg 并发布 Kafka 通知
`core/state/statedb.go`	新增 `StateDiff()`，导出提交集里的状态变更
`eth/api_debank.go`	`DebankAPI`，实现 `trace_debankBlock`
`eth/backend.go`	注册 `trace` 命名空间
`eth/tracers/live/pipeline.go`	把 pipeline tracer 注册进 `LiveDirectory`
`core/rawdb/chain_freezer.go`	`--ancient.prune` 的持续裁剪

保持改动集中是有意的：分叉需要长期跟随上游发版，触碰的上游文件越少，合并冲突越小。新增能力优先放进 pipeline 仓库，客户端侧只留调用点。

启用 pipeline tracer

geth --vmtrace pipeline --vmtrace.jsonconfig '{
  "region": "ap-northeast-1",
  "node_x_bucket": "nodex-internal",
  "chain_table_bucket": "chaintable-pipeline",
  "brokers": ["kafka-1:9092"],
  "etcd_endpoints": ["http://etcd:2379"],
  "grace_period": 10
}'

省略 topic 时按链 ID 生成 nodex_pipeline_{chainID}。字段完整说明见 pipeline 配置。 tracer 挂载后，采集和上传都在 pipeline 内完成，客户端只负责在正确的时机调用 hook。采集逻辑见 pipeline 组件文档。

`trace_debankBlock`

按需返回单个区块的完整执行输出（BlockFile + Header + StateDiff + ValidationHash），不依赖 Kafka 和 S3。

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

两个用途：leafage-evm 的 HTTP 回退模式直接轮询它；调试时用来比对某个区块的 StateDiff。需要在 --http.api 中包含 trace。高度为 0 时返回创世块——没有交易的创世分配会被合成为交易和 trace，让下游看到的格式与普通区块一致。

区块变更通知

Kafka 通知不在 tracer 里发出，而是在 core/blockchain.go 的 writeBlockAndSetHead：只有确定了新的 canonical head 才发，这样重组才能被正确表达。

// 与上一条已发布的区块比较，得到需要丢弃和需要新增的路径
_, dropBlocks, newBlocks := bc.getCommonAncestor(*lastPushedBlock, currentBlock)

if len(dropBlocks) > 0 {
    blockChange = &ptypes.BlockChangeNotification{ChangeType: 2, NewBlocks: newBlocks, DropBlocks: dropBlocks}
} else if len(newBlocks) > 0 {
    blockChange = &ptypes.BlockChangeNotification{ChangeType: 1, NewBlocks: newBlocks}
}

三个前提：tracer 已初始化、当前实例是 Leader、上一条已发布区块的高度不高于当前 head（回退时不发，等更新的区块一起发）。

历史数据裁剪

--ancient.prune 让写节点持续裁剪历史区块数据：body 和 receipt 在离开最近 90000 个区块窗口后被丢弃，已有 ancient 数据在后台逐步删除，header 和 canonical hash 始终保留。需要 --syncmode full。这个开关针对 Leafage 的场景——下游消费者读 S3，不依赖写节点保留历史区块体。

pipeline

tracer 的采集逻辑与数据分发。

接入新链

把 pipeline 附加到其他执行客户端。

开始使用

架构

组件

指南

参考

附加的集成点

启用 pipeline tracer

`trace_debankBlock`

区块变更通知

历史数据裁剪

相关页面

pipeline

接入新链

​附加的集成点

​启用 pipeline tracer

​trace_debankBlock

​区块变更通知

​历史数据裁剪

​相关页面

pipeline

接入新链

附加的集成点

启用 pipeline tracer

`trace_debankBlock`

区块变更通知

历史数据裁剪

相关页面