Write node

The write node is the only role in Leafage that takes part in P2P sync and block execution. It is the chain’s original execution client (ETH uses Chaintable/go-ethereum; other chains use their own forks), and Leafage only attaches a data export layer on top of it. For the client’s own usage, sync modes, and RPC, refer to the documentation of the corresponding upstream project. This page only covers the attached part.

Item	Value
ETH reference implementation	Chaintable/go-ethereum, currently merged up to upstream v1.17.4
Additions	pipeline tracer integration, `trace_debankBlock`, block change notifications, history pruning
Change size	About 2000 lines relative to upstream, concentrated in a few files
Other chains	Forks of op-geth, reth, nitro, erigon, etc., changed the same way; repository list

Added integration points

File	Additions
`core/tracing/hooks.go`	Adds two new hook types, `OnCommit` and `OnBlockDBStart`
`core/blockchain.go`	Dispatches the new hooks; computes the reorg and publishes the Kafka notification when the canonical head is determined
`core/state/statedb.go`	Adds `StateDiff()`, which exports the state changes in the commit set
`eth/api_debank.go`	`DebankAPI`, implements `trace_debankBlock`
`eth/backend.go`	Registers the `trace` namespace
`eth/tracers/live/pipeline.go`	Registers the pipeline tracer in `LiveDirectory`
`core/rawdb/chain_freezer.go`	Continuous pruning for `--ancient.prune`

Keeping the changes concentrated is deliberate: the fork has to follow upstream releases over the long term, and the fewer upstream files it touches, the smaller the merge conflicts. New capabilities go into the pipeline repository first; the client side keeps only the call sites.

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

When topic is omitted, it is generated from the chain ID as nodex_pipeline_{chainID}. See pipeline configuration for the full field descriptions. Once the tracer is attached, collection and upload both happen inside pipeline; the client is only responsible for calling the hooks at the right time. See the pipeline component documentation for the collection logic.

`trace_debankBlock`

Returns the complete execution output of a single block on demand (BlockFile + Header + StateDiff + ValidationHash), without depending on Kafka or S3.

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

It has two uses:

leafage-evm’s HTTP fallback mode polls it directly.
Comparing the StateDiff of a given block when debugging.

trace must be included in --http.api. Height 0 returns the genesis block — the genesis allocation, which has no transactions, is synthesized into transactions and traces so that downstream sees the same format as a normal block.

Block change notifications

The Kafka notification is not sent from the tracer but from writeBlockAndSetHead in core/blockchain.go: it is only sent once the new canonical head is determined, so that reorgs can be expressed correctly.

// Compare with the last published block to get the paths to drop and the paths to add
_, 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}
}

Publishing requires all three preconditions to hold:

The tracer is initialized.
The current instance is the Leader.
The height of the last published block is not higher than the current head. Nothing is sent on a rollback; it waits to send together with newer blocks.

History pruning

--ancient.prune makes the write node continuously prune historical block data; it requires --syncmode full:

Bodies and receipts are dropped once they leave the window of the most recent 90000 blocks.
Existing ancient data is deleted gradually in the background.
Headers and canonical hashes are always kept.

This switch targets Leafage’s scenario — downstream consumers read S3 and do not depend on the write node keeping historical block bodies.

pipeline

The tracer’s collection logic and data distribution.

Adding a new chain

Attach pipeline to other execution clients.

Getting started

Core concepts

Architecture

Components

Guides

Reference

Added integration points

Enabling the pipeline tracer

`trace_debankBlock`

Block change notifications

History pruning

pipeline

Adding a new chain

​Added integration points

​Enabling the pipeline tracer

​trace_debankBlock

​Block change notifications

​History pruning

​Related pages

pipeline

Adding a new chain

Added integration points

Enabling the pipeline tracer

`trace_debankBlock`

Block change notifications

History pruning

Related pages