Interface contracts

Components do not call each other directly; they cooperate only through Kafka, S3, etcd, and a small amount of RPC. These are the parts that must stay compatible when a change spans repositories.

The {version} segment below is optional. With version mode enabled, Kafka topics, S3 keys, and etcd keys all carry a version namespace, which lets multiple data versions run in parallel on the same infrastructure.

Kafka

Internal topic

Published by the write node, consumed by leafage-evm and consistency-checker.

Item	Value
Default naming	`nodex_pipeline_{chainID}` / `nodex_pipeline_{chainID}_{version}`
Message key	`NewBlock`
Message value	`BlockChangeNotification`, JSON + gzip
Message header	Timestamp of when the block was first seen, used for end-to-end latency instrumentation
Producer config	`RequiredAcks=all`, `BatchSize=1` (low latency first)

type BlockChangeNotification struct {
    ChangeType uint64         `json:"changeType"` // 1=new block, 2=reorg
    NewBlocks  []BlockContext `json:"newBlocks"`  // ascending by height
    DropBlocks []BlockContext `json:"dropBlocks"` // blocks dropped in the reorg
}

type BlockContext struct {
    Hash        common.Hash `json:"hash"`
    ParentHash  common.Hash `json:"parentHash"`
    BlockNumber uint64      `json:"blockNumber"`
    Timestamp   uint64      `json:"timestamp"`
}

The internal topic carries a totally ordered block stream and must use a single partition. The partition is specified by the partition field in --kafka-s3-config.leafage-evm pins the partition with an explicit assign and persists the offset itself (auto-commit disabled), so every replica receives all messages instead of sharing them within a consumer group.

External topic

Published by consistency-checker, subscribed to by external consumers. leafage-evm does not consume this topic.

Item	Value
Conventional naming	singleton topic `pipeline_{chainID}`, version topic `pipeline_{chainID}_{version}`
Message key	`NewBlock`
Message value	`OuterBlockChangeNotification`, JSON + gzip

type OuterBlockChangeNotification struct {
    ChainID     int64       `json:"chain_id"`
    Hash        common.Hash `json:"block_id"`
    BlockNumber uint64      `json:"block_height"`
    Timestamp   uint64      `json:"block_timestamp"`
    IsFork      bool        `json:"is_fork"`
}

New blocks and dropped blocks use the same structure, distinguished by is_fork. In version mode, the checker writes to both the version topic and the singleton topic; only the Leader holding the etcd lock writes to the latter.

S3

The two buckets are split by consumer. All keys start with chainID, so multiple chains can share the same bucket.

Internal bucket (NodeX bucket)

Object	Key	Encoding
Header	`{chainID}[/{version}]/{blockHash}/block`	JSON + gzip
StateDiff	`{chainID}[/{version}]/{stateRoot}/stateDiff`	RLP

StateDiff is keyed by state root rather than block hash: adjacent blocks with the same state root share one object, so empty blocks produce no new objects. When the parent and current block have the same state root, leafage-evm skips the fetch and treats it as an empty diff.

type BlockStorageDiff struct {
    Hash            common.Hash          // current state root
    ParentHash      common.Hash          // parent state root
    NewAccounts     []NewAccount         // added or updated accounts
    DeletedAccounts []common.Hash        // deleted accounts
    StorageDiff     []AccountStorageDiff // storage changes
    NewCodes        []NewCode            // newly deployed contract code
}

External bucket (ChainTable bucket)

Object	Key	Encoding
BlockFile	`{chainID}[/{version}]/{blockHash}`	JSON + gzip
BlockValidation	`{chainID}[/{version}]/{height}/{blockHash}`	JSON + gzip

BlockFile contains the block, transactions, call traces, and event logs, and is the main data source for external consumers. BlockValidation is a validation digest of the same data and also serves as the index by height:

type BlockValidation struct {
    ValidationHash        int64 // checksum
    IsFork                bool  // written back by consistency-checker
    TxsCount              int
    EventsCount           int
    TracesCount           int
    ErrorEventsCount      int
    ErrorTracesCount      int
    StorageContractsCount int
}

The objects listed under the prefix {chainID}[/{version}]/{height}/ are all the candidate blocks at that height. Two components rely on this index:

consistency-checker rewrites non-canonical objects as is_fork: true
leafage-evm uses it during S3 catch-up to resolve a height to the canonical block hash

See docs/protocol.md in the pipeline repository for the full field definitions.

etcd key space

All keys start with chainID (with an optional version segment), so different chains are naturally isolated.

Key	Writer	Reader	Value
`{chainID}[/{version}]/nodes/{ip}_{port}`	leafage-evm registers itself; consistency-checker updates the state	consistency-checker, nodex-proxy	Node info JSON
`{chainID}[/{version}]/lastBlockNumber`	consistency-checker	nodex-proxy	`{"latestBlockNumber":"0x..."}`
`{chainID}/nativeNodes/{nodeKey}`	Operators	nodex-proxy	Node info JSON
`{chainID}/gateway`	Operators / nodex-proxy admin API	nodex-proxy	Weights and method routing
`{chainID}/mirror/{addrKey}`	Operators / nodex-proxy admin API	nodex-proxy	Mirror targets
`{chainID}/version`	Operators	consistency-checker, nodex-proxy	Currently active version number
`{chainID}[/{version}]/writers/{nodeID}`	pipeline (with lease)	nodex-proxy	Write node registration info
`{chainID}[/{version}]/writers/leader`	pipeline	pipeline instances	nodeID of the current Leader
`{chainID}/outer_block_notice`	consistency-checker	consistency-checker	Distributed lock for the singleton publish right

Structure of the node info:

{
  "address": "10.0.90.11",
  "port": 8659,
  "nodeType": 1,
  "stateType": 1,
  "weight": 100,
  "source": "manual"
}

Field	Values
`nodeType`	`1` = State node, `2` = Archive node
`stateType`	`1` = caught up with the chain head, `2` = lagging, `3` = offline
`weight`	Load balancing weight, default `100`

The node lifecycle is maintained by three components, each with its own role:

leafage-evm writes itself as stateType: 2 (lagging) on startup.
consistency-checker rewrites it to 1 or 2 after each polling round; when a node is offline and has no lease, it deletes the key outright.
nodex-proxy only watches these keys and does not write health state itself.

Version switching

{chainID}/version is the control point for version mode; two components read it:

consistency-checker compares its own version config with the value in etcd; when they match, it contends for the {chainID}/outer_block_notice lock to become the Leader that publishes to the singleton topic.
nodex-proxy rewrites the base chainId in the request to {chainId}-{version} and routes to the versioned node pool.

RPC contracts

`trace_debankBlock`

Provided by the write node, used to obtain the complete execution output of a single block in setups without Kafka. leafage-evm’s HTTP fallback mode depends on it.

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

Returns DebankOutPut, which contains BlockFile, Header, StateDiff, and ValidationHash — corresponding one-to-one with the contents of the four object types on S3.

Health checks

Caller	Target	Method
consistency-checker	leafage-evm	`eth_blockNumber`
nodex-proxy	State / Archive nodes	`getLatestBlock`
nodex-proxy	Native nodes	`eth_blockNumber`

nodex-proxy’s health check retries every 5 seconds, up to node_health_check_max_wait (default 300 seconds). Only nodes that pass the check enter the load balancing pool. When leafage-evm returns these error codes, nodex-proxy automatically switches node pools and retries once.

Error code	Name	Meaning	Retry target
`-39006`	`StateBlockNotFound`	The requested height is outside the State node’s state range	Archive node
`-39008`	`CosmosPrecompile`	The call touches a precompile that requires native chain capabilities	Native node

Compatibility rules

When changing cross-component interfaces, keep in mind:

Kafka message structures only add fields and never change semantics. Consumers decode JSON; extra fields are ignored, but missing fields lead to zero values being misinterpreted.
S3 key formats are hard-coded conventions shared by leafage-evm, consistency-checker, and external consumers; changing them requires updating all three and accounting for existing objects.
etcd key formats are likewise hard-coded in three components; the way the {chainID} and {version} segments are joined must be consistent.
Error codes are part of routing behavior; adding one requires matching handling logic on the nodex-proxy side.

Getting started

Core concepts

Architecture

Components

Guides

Reference

Kafka

Internal topic

External topic

S3

Internal bucket (NodeX bucket)

External bucket (ChainTable bucket)

etcd key space

Version switching

RPC contracts

`trace_debankBlock`

Health checks

Compatibility rules

​Kafka

​Internal topic

​External topic

​S3

​Internal bucket (NodeX bucket)

​External bucket (ChainTable bucket)

​etcd key space

​Version switching

​RPC contracts

​trace_debankBlock

​Health checks

​Routing-related error codes

​Compatibility rules

Kafka

Internal topic

External topic

S3

Internal bucket (NodeX bucket)

External bucket (ChainTable bucket)

etcd key space

Version switching

RPC contracts

`trace_debankBlock`

Health checks

Routing-related error codes

Compatibility rules