> ## 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.

# 快速开始

> 在本地跑通最小 Leafage 链路，并发出第一个状态查询

最小链路只需要两个进程：一个写节点和一个 leafage-evm。用 HTTP 模式直连，跳过 Kafka 和 S3。这足以验证代码改动、调试新链适配，或者直观理解数据是怎么流的。

<Info>
  生产链路走 Kafka + S3，见[部署指南](/cn/guides/deployment)。本页的形态不具备水平扩展和一致性保障能力。
</Info>

## 前置

| 需要          | 说明                                                                                                   |
| ----------- | ---------------------------------------------------------------------------------------------------- |
| 写节点         | [Chaintable/go-ethereum](https://github.com/Chaintable/go-ethereum) 或目标链对应的分叉，需要 `trace_debankBlock` |
| leafage-evm | Rust 1.79+ 构建，或直接用容器镜像                                                                               |
| 磁盘          | 取决于链和同步进度；本地测试链只需要几 GB                                                                               |

## 步骤

<Steps>
  <Step title="构建 leafage-evm">
    ```bash theme={null}
    git clone https://github.com/Chaintable/leafage-evm
    cd leafage-evm
    cargo build --release
    ```

    也可以用镜像：`public.ecr.aws/b2h7a5c4/chaintable/leafage-evm-x`。
  </Step>

  <Step title="启动写节点并开放 trace 命名空间">
    ```bash theme={null}
    geth --datadir /data/geth \
      --syncmode full \
      --http --http.addr 0.0.0.0 --http.port 8545 \
      --http.api eth,debug,trace
    ```

    `trace` 命名空间提供 `trace_debankBlock`，leafage-evm 的 HTTP 模式依赖它。

    验证：

    ```bash theme={null}
    curl -s -X POST http://127.0.0.1:8545 \
      -H 'Content-Type: application/json' \
      -d '{"jsonrpc":"2.0","method":"trace_debankBlock","params":["latest"],"id":1}' \
      | head -c 300
    ```
  </Step>

  <Step title="启动 leafage-evm">
    ```bash theme={null}
    RUST_LOG=info ./target/release/leafage-evm standalone \
      --db-path /data/leafage \
      --listen-addr 0.0.0.0:8659 \
      --chain-cfg 1 \
      --evm-type mainnet \
      --rpc-addr http://127.0.0.1:8545
    ```

    | 参数            | 作用                                              |
    | ------------- | ----------------------------------------------- |
    | `--db-path`   | 状态数据库目录                                         |
    | `--chain-cfg` | 链 ID                                            |
    | `--evm-type`  | 执行器类型，见[支持的链](/cn/components/leafage-evm#多链执行器) |
    | `--rpc-addr`  | 写节点 RPC 地址，配置它即启用 HTTP 轮询模式                     |

    启动后它会轮询写节点，把新区块的状态差异应用到内存 StateTree。日志里 `updater` target 会显示追块进度。
  </Step>

  <Step title="发出第一个查询">
    ```bash theme={null}
    curl -s -X POST http://127.0.0.1:8659 \
      -H 'Content-Type: application/json' \
      -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
    ```

    执行一次合约调用：

    ```bash theme={null}
    curl -s -X POST http://127.0.0.1:8659 \
      -H 'Content-Type: application/json' \
      -d '{
        "jsonrpc":"2.0","id":1,"method":"eth_call",
        "params":[{
          "to":"0xdAC17F958D2ee523a2206206994597C13D831ec7",
          "data":"0x18160ddd"
        },"latest"]
      }'
    ```

    <Check>
      返回值与写节点上同一次 `eth_call` 一致，说明链路已经打通。
    </Check>
  </Step>
</Steps>

## 几个会遇到的情况

<AccordionGroup>
  <Accordion title="返回 -39006 StateBlockNotFound">
    请求的高度超出了 State 节点保留的状态范围。加 `--archive` 启动归档模式，或把查询目标改成 `latest`。生产环境由 nodex-proxy 自动转发到 Archive 节点。
  </Accordion>

  <Accordion title="区块查询返回空的 transactions">
    这是预期行为。leafage-evm 不存交易数据，区块接口只返回 header。交易数据在 S3 外部桶的 BlockFile 里。
  </Accordion>

  <Accordion title="estimateGas 找不到">
    gas 估算的方法名是 `estimateGas`（无命名空间前缀），不是 `eth_estimateGas`。完整方法列表见 [RPC 参考](/cn/reference/rpc)。
  </Accordion>

  <Accordion title="追块很慢或停滞">
    HTTP 模式是串行轮询，速度受写节点 RPC 限制，只适合开发验证。生产环境用 Kafka + S3，可以并行拉取。
  </Accordion>
</AccordionGroup>

## 下一步

<Columns cols={2}>
  <Card title="发送 RPC 请求" icon="send" href="/cn/guides/rpc-requests">
    批量调用、`blockCtx`、gas 估算与模拟的完整示例。
  </Card>

  <Card title="核心概念" icon="book-open" href="/cn/concepts/overview">
    刚跑通的链路里，每个角色和术语分别是什么。
  </Card>

  <Card title="架构总览" icon="layers" href="/cn/architecture/overview">
    理解五个组件如何协作。
  </Card>

  <Card title="部署指南" icon="server" href="/cn/guides/deployment">
    搭建带 Kafka + S3 的完整链路。
  </Card>

  <Card title="RPC 参考" icon="terminal" href="/cn/reference/rpc">
    可用方法与参数。
  </Card>

  <Card title="参与开发" icon="git-pull-request" href="/cn/guides/contributing">
    仓库地图与构建命令。
  </Card>
</Columns>