Follow Ethereum blocks from the CLI

The built-in block-summary processor is the smallest continuous Leani demo. It requests verified execution headers and bodies, so it can report the exact transaction count without waiting for a particular contract event. It does not download receipts.

Run it without configuring or starting a node:

leani subscribe blocks

First output can take several minutes while Leani finds serving peers and validates a current block. The included head is printed when it is available, followed by one line per new block:

2026-09-01T09:14:35Z  block=25881412  txs=187  gas=32.47M / 60.00M (54.1%)  base_fee=0.143592817 gwei  blobs=6  included

The summary contains the block number, hash and parent, timestamp, transaction count, encoded block size, gas limit and usage, base fee, blob gas, excess blob gas, and finality. Leani verifies the transaction and withdrawals roots from the body while keeping receipt acquisition out of this latency-sensitive path.

Use newline-delimited JSON for scripts:

leani subscribe blocks --format json |
  jq '{block: .blockNumber, transactions: .transactionCount, gas: .gasUsed, baseFee: .baseFeePerGas}'

Embedded startup can print a header-commitment-checked peer preview before the verified processor lane is ready. Those rows say preview; JSON reports finality: "preview". Rows from the verified lane say included or finalized. In embedded mode, use --finality finalized when the first result must be a block Ethereum consensus has finalized. Attached output follows the node’s configured source trust; a dataset’s finality label does not become a cryptographic proof simply by subscribing to it. Against a node that publishes included blocks, an attached --finality finalized subscription prints each block once the node’s finality marker covers it.

--once exits after the first summary, including a labelled preview, which is useful for startup timing:

time leani subscribe blocks --once

Attach to a prepared node

Create the compact block-summary configuration once:

mkdir leani-block-demo
cd leani-block-demo
leani init blocks

The generated product configuration is intentionally small:

config_version = 1
network = "ethereum-mainnet"
data_dir = "./data"

[finality]
checkpoint = "0x..."
checkpoint_slot = 15100000
endpoints = ["https://ethereum-beacon-api.publicnode.com/"]

[blocks]

[api]
bind = "127.0.0.1:18080"

Start the node in one terminal:

leani serve

Then subscribe in another terminal from the same directory:

leani subscribe blocks

Auto mode discovers the local config, detects the running API, reads a stable latest-block snapshot, and follows its resumable change stream. If no node is reachable, the same command starts the embedded runtime. Use --mode client or --mode embedded only when you need to force one behavior.

Reset just the embedded block feed when measuring a true cold start:

leani reset subscription blocks --yes

The configured node and embedded subscription use separate state directories, so both can be tested from the same project directory.