接入新链

接入一条新链要做两件独立的事：让这条链的执行客户端导出数据（写侧），以及让 leafage-evm 能正确执行这条链的调用（读侧）。两侧可以分别推进。

如果新链使用的客户端已经在已适配列表里（例如又一条 OP Stack 链），写侧通常只需要新建部署，不需要改代码。

写侧：把 pipeline 接入执行客户端

选择适配路径

客户端是 Rust 写的吗？
    是 → Reth 适配（仅 RPC Tracer 模式）
    否 ↓
分叉里有 tracing.Hooks 和 tracers.LiveDirectory 吗？（Geth v1.14.0+）
    是 → 标准 Geth 适配
    否 → 遗留 Geth 适配

	标准（Geth v1.14.0+）	遗留（Geth < v1.14.0）	Reth
Tracer 接口	`tracing.Hooks`	`vm.EVMLogger`	`revm-inspectors`
pipeline 代码	Go 模块依赖	源码内嵌	Rust 重新实现
集成模式	Live Tracer + RPC	Live Tracer	仅 RPC
核心 EVM 改动	注入 hook	手动分发 hook	不需要

三份适配指南在 pipeline 仓库：标准、遗留、 Reth。

需要改动的位置

以标准 Geth 分叉为例：

扩展 tracing hooks

在 core/tracing/hooks.go 增加 OnCommit 和 OnBlockDBStart。

导出状态差异

在 core/state/statedb.go 增加 StateDiff()，把提交集转成 pipeline 的类型。

分发 hook

在 core/blockchain.go 的区块处理路径上调用新 hook，并在确定 canonical head 时计算 reorg、发布 Kafka 通知。

新建 eth/tracers/live/pipeline.go，把 pipeline tracer 注册进 LiveDirectory。

添加 RPC

实现 trace_debankBlock 并在 eth/backend.go 注册 trace 命名空间。

验证

go build ./... 通过后，实际跑一条链，比对 trace_debankBlock 的输出与 S3 上的对象。

参照实现是写节点相对上游的 diff，总量约 2000 行。

用 Claude Code 辅助适配

pipeline 仓库内置了适配技能，可以自动检测客户端类型并分阶段引导：

/adapt-pipeline /path/to/your-client

它会扫描 Cargo.toml、go.mod、tracing.Hooks、vm.EVMLogger 等特征判断类型，检查是否已有集成，然后路由到对应的专用技能（/adapt-pipeline-geth、/adapt-pipeline-legacy、/adapt-pipeline-reth）。每个阶段的流程是：探测代码结构 → 查阅指南 → 生成修改 → 运行 go build 或 cargo check 验证。

读侧：为 leafage-evm 增加执行器

如果新链的 EVM 行为与已支持的某条链完全一致，只需要用对应的 --evm-type 启动，配上正确的 --chain-cfg（链 ID）。行为有差异时才需要新增执行器。需要改动的位置：

位置	内容
`crates/leafage-evm-chains/src/{chain}/`	硬分叉规格与链特定预编译
`crates/leafage-evm-rpc/src/api_impl/{chain}/`	`EvmExecutor` trait 实现
`crates/leafage-evm-rpc/src/api_impl/core.rs`	`MultiChainCfgEnv` 增加分支
`crates/leafage-evm-rpc/src/api_impl/build.rs`	构建路径增加分支
`bin/leafage-evm/src/standalone.rs`	`--evm-type` 的取值列表与配置构造

一个典型的配置分支：

"citrea" => {
    let mut chain_cfg = CfgEnv::new_with_spec(CitreaHardfork::from(MainnetSpecId::AMSTERDAM));
    chain_cfg.disable_balance_check = true;
    chain_cfg.disable_eip3607 = true;
    chain_cfg.disable_block_gas_limit = true;
    chain_cfg.disable_base_fee = true;
    chain_cfg.chain_id = chain_id;
    chain_cfg.tx_gas_limit_cap = Some(gas_cap);
    Ok(MultiChainCfgEnv::Citrea(chain_cfg))
}

disable_* 这几项对状态查询是常规设置：eth_call 不需要校验余额、base fee 和区块 gas 上限。

先看 leafage-evm-chains 里最接近的那条链。OP Stack 系可以参照 base 或 mantle，EVM 兼容的独立链参照 citrea 或 iotex，需要自定义预编译的参照 bsc 或 cosmos。

历史区间缺数据

有些链存在无法获取 block diff 的历史区间（典型是 OP pre-bedrock）。用 --historical-rpc 指定外部 RPC，--historical-height 指定分叉高度，低于阈值的查询会被转发出去。

验证

比对状态

对同一批地址和存储槽，比较 leafage-evm 与该链官方全节点的 eth_getBalance、eth_getStorageAt、eth_getCode 返回值。

比对调用结果

用 leafage-bench 对同一份语料库同时打 leafage-evm 和全节点，对比 eth_call 的返回值与延迟。

./target/release/leafage-bench run \
  --corpus bin/leafage-bench/corpus/corpus.json \
  --target http://leafage-evm:8545 \
  --compare http://node:8545

观察重组

盯一段时间的 changeType: 2 通知，确认 leafage-evm 的链头跟随正确。reorg 较深的链需要相应调大 --catchup-safe-depth。

部署

新链的部署与已有链完全一致，只是 chainID 不同：Kafka topic、S3 前缀和 etcd 键都以链 ID 开头，天然隔离。nodex-proxy 不需要重启，通过 etcd 发现新链的节点即可。具体步骤见部署指南。

开始使用

架构

组件

指南

参考

写侧：把 pipeline 接入执行客户端

选择适配路径

需要改动的位置

用 Claude Code 辅助适配

读侧：为 leafage-evm 增加执行器

历史区间缺数据

验证

部署

​写侧：把 pipeline 接入执行客户端

​选择适配路径

​需要改动的位置

​用 Claude Code 辅助适配

​读侧：为 leafage-evm 增加执行器

​历史区间缺数据

​验证

​部署

写侧：把 pipeline 接入执行客户端

选择适配路径

需要改动的位置

用 Claude Code 辅助适配

读侧：为 leafage-evm 增加执行器

历史区间缺数据

验证

部署