Follow your first Ethereum block

Install the current release first. This example follows real Ethereum Mainnet blocks with no API key and no configuration file. Run it from a fresh directory:

cd "$(mktemp -d)"

Follow Ethereum blocks

leani subscribe blocks

Start the embedded P2P subscription and follow labelled live blocks.Verified source

On first use, Leani asks independent public providers for a recent finalized checkpoint. At least two must agree before you can accept it. This is the starting trust anchor for subsequent verification.

Peer discovery can take several minutes, even on a later run with cached state. Leani prints progress to stderr, then one line per block, shaped like:

2026-09-07T12:11:59Z  block=25925396  txs=381  gas=43.17M / 60.00M (72.0%)  base_fee=0.069459109 gwei  blobs=3  unattested

Your block numbers and values will differ. Leani keeps following new blocks until you press Ctrl-C. Add --format json for scripts.

Read the finality label

Rows say unattested, attested or finalized; see finality levels. Use leani subscribe blocks --finality finalized when you need only blocks Ethereum consensus has finalized.

Prepare a node for your application

When you want an HTTP API and SDK subscriptions, initialize a reusable node:

Prepare a reusable block node

mkdir leani-blocks && cd leani-blocks
leani init blocks
leani serve
# In another terminal in this directory:
# leani subscribe blocks --format json

Initialize a compact processor config and serve its API.Verified source

Leave serve running. In another terminal, set up leani as described on the install page and change into the same leani-blocks directory. Then run:

leani subscribe blocks --format json

It attaches to the running node. The API is at http://127.0.0.1:18080 and JSON-RPC is at http://127.0.0.1:18545. Discover the configured processor with:

curl -s http://127.0.0.1:18080/v1/capabilities

Expect a block-summary processor with subscriptions: true. Keep each node’s data directory separate; do not start two nodes against the same writable data.

Choose your next example

• Index a small historical range to query decoded contract events.
• Query and follow with TypeScript to seed application state.
• Build a custom processor in Rust to run your own transformation using the Leani library.

For startup diagnostics and all CLI fields, see block subscriptions. Read known limitations before connecting production applications.