Quickstart

The minimal setup needs only two processes: a write node and a leafage-evm. Connect them directly in HTTP mode and skip Kafka and S3. This is enough to validate code changes, debug a new chain adaptation, or see directly how the data flows.

The production data path runs on Kafka + S3; see the deployment guide. The setup on this page provides neither horizontal scaling nor consistency guarantees.

Prerequisites

Requirement	Notes
Write node	Chaintable/go-ethereum or the matching fork for the target chain; `trace_debankBlock` is required
leafage-evm	Build with Rust 1.79+, or use the container image directly
Disk	Depends on the chain and sync progress; a local test chain needs only a few GB

Steps

Build leafage-evm

git clone https://github.com/Chaintable/leafage-evm
cd leafage-evm
cargo build --release

You can also use the image: public.ecr.aws/b2h7a5c4/chaintable/leafage-evm-x.

Start the write node and expose the trace namespace

geth --datadir /data/geth \
  --syncmode full \
  --http --http.addr 0.0.0.0 --http.port 8545 \
  --http.api eth,debug,trace

The trace namespace provides trace_debankBlock, which leafage-evm’s HTTP mode depends on.Verify:

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

Start leafage-evm

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

Flag	Purpose
`--db-path`	State database directory
`--chain-cfg`	Chain ID
`--evm-type`	Executor type, see supported chains
`--rpc-addr`	Write node RPC address; setting it enables HTTP polling mode

Once started, it polls the write node and applies each new block’s state diff to the in-memory StateTree. The updater target in the logs shows the block catch-up progress.

Send your first query

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}'

Execute a contract call:

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"]
  }'

If the result matches the same eth_call on the write node, the data path is working end to end.

Things you may run into

Returns -39006 StateBlockNotFound

The requested height is outside the state range kept by the State node. Add --archive to start in archive mode, or change the query target to latest. In production, nodex-proxy forwards these requests to Archive nodes automatically.

Block queries return empty transactions

This is expected behavior. leafage-evm does not store transaction data; the block APIs return only the header. Transaction data lives in the BlockFile in the S3 external bucket.

estimateGas not found

The gas estimation method is named estimateGas (no namespace prefix), not eth_estimateGas. See the RPC reference for the full method list.

Block catch-up is slow or stalled

HTTP mode polls serially and is limited by the write node’s RPC; it is only suitable for development validation. Production uses Kafka + S3, which can fetch in parallel.

Next steps

Sending RPC requests

Complete examples for batch calls, blockCtx, gas estimation, and simulation.

Core concepts

What each role and term in the pipeline you just ran actually means.

Architecture overview

Understand how the five components work together.

Deployment

Set up the full data path with Kafka + S3.

RPC reference

Available methods and parameters.

Contributing

Repository map and build commands.

Getting started

Core concepts

Architecture

Components

Guides

Reference

Prerequisites

Steps

Things you may run into

Next steps

Sending RPC requests

Core concepts

Architecture overview

Deployment

RPC reference

Contributing

​Prerequisites

​Steps

​Things you may run into

​Next steps

Sending RPC requests

Core concepts

Architecture overview

Deployment

RPC reference

Contributing

Prerequisites

Steps

Things you may run into

Next steps