Follow your first Ethereum block

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

cd "$(mktemp -d)"

Follow Ethereum blocks

leani subscribe blocks --once

Start the embedded P2P subscription and inspect a labelled first result.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. Success is a line 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  included

Your block number and values will differ. --once exits after that first result. Remove it to keep following blocks, or add --format json for scripts.

Read the finality label

The first result may say preview: a peer supplied the block and Leani is still checking its place in Ethereum’s chain. JSON reports finality: "preview". Later rows say included (on the followed chain, a reorg can still remove them) or finalized. Use leani subscribe blocks --finality finalized --once when you need a result 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 alpha limitations before connecting production applications.