> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leafage.chaintable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 接入新链

> 为一条新的 EVM 兼容链打通写侧数据导出和读侧状态查询

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

<Info>
  如果新链使用的客户端已经在[已适配列表](https://github.com/Chaintable/leafage-evm#supported-write-node-repositories)里（例如又一条 OP Stack 链），写侧通常只需要新建部署，不需要改代码。
</Info>

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

### 选择适配路径

```text theme={null}
客户端是 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 仓库：
[标准](https://github.com/Chaintable/pipeline/blob/main/docs/skills/adapt-pipeline-geth/references/adaptation-guide.md)、
[遗留](https://github.com/Chaintable/pipeline/blob/main/docs/skills/adapt-pipeline-legacy/references/adaptation-guide-legacy.md)、
[Reth](https://github.com/Chaintable/pipeline/blob/main/docs/skills/adapt-pipeline-reth/references/adaptation-guide-reth.md)。

### 需要改动的位置

以标准 Geth 分叉为例：

<Steps>
  <Step title="扩展 tracing hooks">
    在 `core/tracing/hooks.go` 增加 `OnCommit` 和 `OnBlockDBStart`。
  </Step>

  <Step title="导出状态差异">
    在 `core/state/statedb.go` 增加 `StateDiff()`，把提交集转成 pipeline 的类型。
  </Step>

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

  <Step title="注册 live tracer">
    新建 `eth/tracers/live/pipeline.go`，把 pipeline tracer 注册进 `LiveDirectory`。
  </Step>

  <Step title="添加 RPC">
    实现 `trace_debankBlock` 并在 `eth/backend.go` 注册 `trace` 命名空间。
  </Step>

  <Step title="验证">
    `go build ./...` 通过后，实际跑一条链，比对 `trace_debankBlock` 的输出与 S3 上的对象。
  </Step>
</Steps>

参照实现是 [写节点](/components/go-ethereum-x#附加的集成点)相对上游的 diff，总量约 2000 行。

### 用 Claude Code 辅助适配

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

```text theme={null}
/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` 的取值列表与配置构造 |

一个典型的配置分支：

```rust theme={null}
"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 上限。

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

### 历史区间缺数据

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

## 验证

<Steps>
  <Step title="比对状态">
    对同一批地址和存储槽，比较 leafage-evm 与该链官方全节点的 `eth_getBalance`、`eth_getStorageAt`、`eth_getCode` 返回值。
  </Step>

  <Step title="比对调用结果">
    用 `leafage-bench` 对同一份语料库同时打 leafage-evm 和全节点，对比 `eth_call` 的返回值与延迟。

    ```bash theme={null}
    ./target/release/leafage-bench run \
      --corpus bin/leafage-bench/corpus/corpus.json \
      --target http://leafage-evm:8545 \
      --compare http://node:8545
    ```
  </Step>

  <Step title="观察重组">
    盯一段时间的 `changeType: 2` 通知，确认 leafage-evm 的链头跟随正确。reorg 较深的链需要相应调大 `--catchup-safe-depth`。
  </Step>
</Steps>

## 部署

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

具体步骤见[部署指南](/guides/deployment)。