Skip to content

Configure a node

Leani reads strict, versioned TOML. Unknown fields are errors. Relative paths in a configuration file, such as data_dir or an archive source’s manifest, are relative to that file; path flags on the command line stay relative to the working directory. Version 1 has two first-class document shapes: a compact processor-oriented setup with sane network defaults, and the fully explicit advanced schema. Both become the same validated runtime configuration. The machine-readable contract is rendered in the configuration field reference; six complete advanced lifecycle profiles are checked under config/modes.

For a continuous block-following demo, generate the compact form and a current trusted checkpoint together:

Terminal window
leani init blocks
leani doctor

For a local Uniswap node, select one or more markets instead:

Terminal window
leani init uniswap-v3 ETH/USDC
leani doctor

init requires a strict majority of the configured checkpoint providers, at least two of the three defaults, to agree on one finalized slot and root, and fails closed if a responding provider reports another root at that slot. It shows every provider’s answer, asks before accepting the checkpoint, writes leani.toml, and never overwrites an existing file. A global --config PATH selects another output path. The node keeps its state in data, beside the configuration file, unless --data-dir names another directory; like any path flag, a relative --data-dir is relative to the working directory. The generated document contains only the choices an operator normally needs:

config_version = 1
network = "ethereum-mainnet"
data_dir = "./data"
[finality]
checkpoint = "0x..."
checkpoint_slot = 15100000
endpoints = [
"https://ethereum-beacon-api.publicnode.com/",
"https://lodestar-mainnet.chainsafe.io/",
]
[blocks]
[api]
bind = "127.0.0.1:18080"

The checkpoint and slot above are illustrative; the generator writes the live quorum result. The checkpoint is the trust root. PublicNode (https://ethereum-beacon-api.publicnode.com/) and Lodestar (https://lodestar-mainnet.chainsafe.io/) are ordinary, untrusted Beacon API transports in the compact profile’s managed transport pool; they do not provide execution blocks or Uniswap data. init writes that pool plus every responding checkpoint provider that also serves the Beacon light-client API, without duplicates. Leani queries the pool concurrently and verifies every response locally from the pinned checkpoint. After the first verified response it waits about two seconds for the others, then follows the highest finalized slot that minimum_agreement endpoints have reached or passed. With the compact profile’s default agreement of one, the most recent verified finality wins, and a stalled transport does not hold up node startup. Listing endpoints in the compact document replaces the managed defaults, which lets operators use only self-hosted transports. Compact Ethereum Mainnet configurations expand to:

Concern Default
execution native P2P, one-peer availability floor, 16-peer healthy target, 100-peer cap
history public Xatu source, on-demand processor scheduling
processor selected built-in feed, unattested publication, checkpointed state, 256-block undo safety
confirmation ChainSafe’s public Lodestar node behind the confirmed level; a [confirmation] section in the compact document replaces it
resources 512 MiB memory, 4 GiB temporary disk, four source and mapper tasks
retention full query output; 64 MiB or 24 hours of change delivery
listeners ephemeral P2P ports, RPC 127.0.0.1:18545/18546, API 127.0.0.1:18080

The reviewed expansion is checked in as config/defaults/ethereum-mainnet.toml. Use the advanced schema below when any expanded field needs an override.

network names any built-in chain entry by name or alias, such as ethereum-hoodi, base, op, arbitrum-one, or robinhood, and leani init blocks --network base writes one. The chain’s family picks the lanes. An Ethereum testnet follows its own beacon chain from the checkpoint in [finality]. An op-stack chain takes its blocks from execution P2P, checked against the sequencer’s signed block gossip on gossip port 9222 so that peers can dial in, and from the entry’s public JSON-RPC endpoints while no execution peer serves them; its history comes through the live lane. A Nitro chain takes its blocks from the entry’s public JSON-RPC endpoints, checked against its sequencer’s signed feed, with history from the sources the entry names: SonarX and then the endpoints for Arbitrum One, the endpoints for the others. On a rollup, [finality] holds the Ethereum Mainnet checkpoint its L1 anchor reads. Base Sepolia takes none: it settles on Ethereum Sepolia. Uniswap markets are Ethereum Mainnet’s.

Validate a file without opening its database or any network connection:

Terminal window
cp config/modes/windowed.toml leani.toml
leani doctor --json

Without --config, Leani uses ./leani.toml. Set LEANI_CONFIG when a service or shell should consistently use a configuration elsewhere. An explicit --config remains the highest-precedence override. Compact documents default operational tuning but never the chain identity, checkpoint trust root, or selected processor targets. Advanced documents keep every choice explicit.

Build a configuration from requirements

Instead of copying a profile and editing it, state what the application needs and let init build a complete advanced document:

Terminal window
leani init uniswap-v3 ETH/USDC --keep window --window-days 30 \
--follow finalized --memory 1GiB --disk 20GiB --bandwidth 100

--keep is everything, window, latest, result, stream, or live; --follow is head, finalized, or none, which builds a history-only node without a live lane or finality; --history-from-block starts a backfill; --memory, --disk, and --bandwidth (Mbit/s) state the host’s limits; and --tuning replaces the recipes the limits call for. --requirements FILE takes the same needs as JSON for any processor, including contract events and Wasm or custom processors. The builder writes every setting and comments each one it derived with the reason, using only the shipped profiles’ storage settings and the measured recipes of Sizing for bandwidth, memory, and disk. --network builds for another chain, as the compact network does; a window then keeps days by block age, because a rollup’s blocks come faster or at no fixed pace. --json prints the configuration, the derived settings with their reasons, warnings, and next steps. leani guide config describes the requirements, and a running node builds the same document at POST /admin/v1/config/build, which its /playground uses.

Advanced root fields

Field Type Meaning
config_version integer Must be 1.
data_dir path Writable node state. Use a distinct directory per deployment or test. A relative path is relative to the directory of the configuration file, not the working directory.
chain table A built-in chain entry’s name or alias. chain_id comes from the entry and, when given, must match it.
artifact_storage table Physical backend and bounded compaction policy for retained processor artifacts.
budgets table Hard memory, temporary disk, pending-delta, recent-input, and concurrency limits.
sources table Priority-ordered history sources and the optional live source.
finality table consensus_p2p, beacon_api, json_rpc, op_gossip, sequencer_feed, or disabled.
processors array One immutable processor kind/instance contract per entry.
rpc table HTTP/WS binds, browser origins, request and response limits, and bounded historical lookup behavior.
api table Native API bind, bearer-token environment variable, allowed hosts and browser origins, and delivery batching.

budgets.recent_raw_soft_bytes must not exceed budgets.recent_raw_hard_bytes. All byte budgets and concurrency values are positive. Each finality advance prunes finalized recent frames toward the soft limit. Live ingestion enforces the hard limit as it retains each frame: at the limit it waits, with live readiness down, until finality prunes (see the operations runbook’s storage pressure section).

Two budgets bound a history source read’s input. budgets.temporary_disk_bytes bounds what one read may acquire over its life: the objects, byte ranges, and responses it fetches, and the frames it builds from them. A read that would acquire more fails with an input_bytes budget error, and a local archive object larger than it is refused before it is read. budgets.memory_bytes bounds the raw input one read holds in memory at once: one line of a local archive object, which it verifies whole and then reads a line at a time; the selected columns of one Xatu Parquet row group; one batch of EraE byte ranges, including a prefetched window when both fit the budget; one window of execution P2P frames; or one retained raw-history record. EraE normally targets 16 MiB compressed windows independently of the decoded frame buffer, and shrinks them when the resident budget is smaller. Its frames may be at most memory_bytes, or 32 MiB when that is less. A read that would hold more fails with a resident_bytes budget error naming budgets.memory_bytes, and a backfill then tries its next configured source. A historical RPC request, which holds everything it returns, may acquire and hold at most memory_bytes divided by budgets.source_concurrency. Raw-history jobs acquire one segment’s worth per read, raw_history.maximum_segment_logical_bytes.

The bound is per read, not for the node. At once, the node runs up to budgets.history_pipeline.maximum_active_chunks backfill reads, one archive reconciliation read, the live lane, and one read per running raw-history job, and each may hold up to memory_bytes. What a read decodes is not counted here: decoded frames and mapped deltas have the budgets.history_material and pipeline budgets below, and memory_bytes is not a process RSS limit. On mainnet, a Xatu read of a 2023–24 transaction object, 1,000 blocks around blocks 18,000,000 to 19,430,000, holds about 80–110 MiB of compressed columns and decodes about 230–340 MiB. Keep memory_bytes above the largest of those, as the shipped 512 MiB is, and plan RAM for about maximum_active_chunks × 450 MiB during Xatu backfills, 3.6 GiB at the default 8. The allocator keeps memory a finished read freed for the next, so resident memory after a burst of reads stays near its peak: set a container’s memory limit for that peak, not for the budgets. On Linux, glibc gives each thread that allocates its own 64 MiB arena and returns little of what they free, so a long-running node grows: an rc.4 node on a 20-thread host held 5.7 GB, 4.7 GB of it in 57 such arenas. Over a 100,000-block blobs-money backfill from Xatu, glibc reached 1.5 GiB and kept it. The container image preloads jemalloc, which returns freed memory: the same backfill held 711 MiB and fell to 130 MiB when it finished. deploy/leani.service sets MALLOC_ARENA_MAX=2, which held it at 0.8–1.0 GiB. Wherever you run the binary yourself, set MALLOC_ARENA_MAX=2 or preload jemalloc (Debian’s libjemalloc2 with LD_PRELOAD=libjemalloc.so.2).

[budgets.history_material] is the sole budget for shared immutable source frames and acquisition reorder buffers. Chunks read ahead of the one a job is reading reserve memory only up to half of its memory_bytes, so size it to at least twice the largest expected frame. The half is checked as each frame is reserved: a chunk that another job joins, or that its reading job pauses and leaves while others wait for it, becomes read-ahead with the frames it already holds, so read-ahead can hold more than half. [budgets.history_pipeline] is separate: maximum_active_chunks caps physical history reads node-wide and maximum_mapped_bytes caps processor-owned mapped deltas across every active job. A job reads only its own planned chunks, so a backfill subscription smaller than maximum_active_chunks source chunks leaves read slots idle; the node logs a hint with a size that fills them, once per processor, and leani_history_material_active_acquisitions against leani_history_material_active_acquisitions_limit shows the slots in use. Its nested commit table flushes a contiguous SQLite transaction at the first configured block, domain-change, stable-encoded-byte, or elapsed-time limit: by default 128 blocks, 10,000 changes, 16 MiB, or 50 ms. A batch publishes its blocks’ delivery changes in the same transaction. Blocks not yet finalized, or that the live lane already applied or holds, commit one at a time, as do the blocks of a batch whose reducer reads windowed output or rewrites it unchanged. A source error or invalid frame ends a batch after the blocks before it commit. target_writer_hold, 250 ms by default, controls the adaptive block limit: the runtime halves the current limit when observed p95 historical writer hold time exceeds the target and cautiously grows it again below half the target. A hold includes the commit’s WAL sync, which a smaller batch does not shorten, so on a disk whose syncs are slow a low target shrinks batches to a block or two, and every commit rewrites the same pages for little data. On a Hetzner EX44 (RAID 1 over two NVMe drives, about 8 ms per sync), the former 20 ms target ran a rollup-txs backfill from Xatu at 53 blocks/s and wrote 104 KiB per block; the 250 ms target ran it at 799 blocks/s and wrote 11 KiB per block. A job holds at most maximum_buffered_frames_per_acquisition frames of [budgets.history_material], 1,024 by default, that it has not committed, so a longer maximum_delay makes acquisition wait instead of filling larger batches: a one-second delay ran the same backfill at 127 blocks/s when the default was 128 frames, and at 743 blocks/s with 1,024. A single mapped delta or single-block commit that exceeds its byte limit fails immediately because waiting cannot make that item fit. A backfill that reuses retained recent frames reads them in batches of at most commit.maximum_blocks blocks and maximum_mapped_bytes encoded bytes, each holding one active-chunk slot like a physical history read.

[budgets.store].maximum_physical_bytes is the emergency node-store admission bound shared by SQLite, its WAL, and configured processor-artifact segments. It is deliberately not nested under delivery: artifacts, materialized views, correctness metadata, and delivery share the same physical capacity. It measures allocated file bytes. Stores use SQLite incremental auto-vacuum, so pruning returns pages to the filesystem and admission recovers; a store created before that needs one leani db compact (see the operations runbook).

[budgets.artifacts] independently caps immutable finalized artifact bytes and unfinalized-block candidate bytes awaiting finality. A transaction that would exceed either logical limit rolls back without advancing processor coverage. Finality is the exception: when the retained limit is full, finality still advances, the finalized candidates stay pending with a logged warning, and a later finality advance promotes them once there is room. A processor’s window policy may prune its own instance below a tighter bound; the node-wide artifact budget still protects against the aggregate of many processors.

[artifact_storage] backend = "sqlite" retains those immutable artifacts as KV rows. The opt-in tiered_segments backend uses SQLite as the durable write buffer and continuously compacts complete segment_target_blocks ranges into checksummed seekable files under data_dir/processor-artifacts. Compression, single-item/segment hard limits, compaction cadence, and maximum segments per cycle are explicit. Only processors using artifacts.mode = "full" are eligible in the first tiered implementation; rolling windows remain in SQLite. Segment bytes do not receive a second budget: they count against the same [budgets.store].maximum_physical_bytes ceiling.

[raw_history] keeps finalized source frames in checksummed segment files under data_dir/raw-history, beside their own catalog. maximum_logical_bytes caps the frames retained, and maximum_physical_bytes the bytes on disk: segments, the partial files of segments being written, the catalog and its write-ahead log, and quarantined files. Before a segment is written, its maximum size and the catalog rows it will add are reserved: a fixed 64 KiB, and 512 bytes per locator row, one per block with block-hash locators and 256 per block with transaction-hash locators. A segment with more transactions still publishes its extra rows, so the catalog can exceed maximum_physical_bytes by that one segment’s extra rows, which the next segment’s admission counts. Reads of maximum_segment_logical_bytes, one segment’s worth, feed a raw-history job. A store already over either budget, for example after lowering it, still opens and serves its history, but admits no new segment until it is back under: its jobs pause at the storage limit, or fail when created with segment.onLimit: fail. A segment that fails verification moves to data_dir/raw-history/quarantine, which keeps at most 1 GiB, or one segment of maximum_segment_physical_bytes when that is larger: past that, the longest-quarantined files are deleted first, but never the newest (see the operations runbook).

[budgets.delivery] supplies the shared delivery envelope above independent per-stream limits. maximum_retained_bytes caps exact delivery payload bytes across live and history streams. maximum_history_retained_bytes is a lower, non-borrowable history ceiling so stalled backfills cannot consume live-lane headroom. The two values must satisfy history <= retained. Reaching a shared bound backpressures only the committing lane; ACK, pruning, queries, networking, and unrelated processors remain available. The backfill subscriptions of a replaced processor instance keep counting against the history ceiling until they are deleted (see the runbook’s Processor rebuild or rollback).

Sources and finality

[[sources.history]] requires id, kind, priority, and trust. Supported kinds are xatu, era_e, archive, json_rpc, and aws_public. xatu reads public Parquet history; validation refuses parquet, which no source reads. archive requires manifest; era_e accepts an https or file endpoint ending in /, and aws_public an https bucket mirror. A plain http endpoint is accepted on loopback, or elsewhere only with allow_insecure_http = true on that source, which accepts a mirror whose catalog and archive bytes anyone on the path can replace. xatu sources are Ethereum mainnet only: another chain.chain_id fails validation.

aws_public reads the chain entry’s public dataset on AWS Open Data: Ethereum mainnet from AWS’s own export, about a day behind, and Base and Arbitrum One from SonarX’s, about a week behind. It serves headers, receipts, and logs. Transaction bodies are left to other sources, because the exports store values as floating-point numbers. Rows are unsorted within a day: in October 2026 a day held about 2 GB for Ethereum, 1.5 GB for Arbitrum One, and 9 GB for Base. AWS’s Ethereum export has no page index, so each chunk downloads its whole UTC day, and chunk_blocks splits a day only by reading it again for each chunk. SonarX’s files index their pages, so a chunk downloads only the pages that hold its blocks: Base reads chunks of 2,000 blocks and Arbitrum One chunks of 100,000 unless chunk_blocks sets another size. The chunks of a day share the footers, page indexes, and dictionary pages of its files. The node keeps the byte ranges it reads in one temporary file in data_dir, at most budgets.temporary_disk_bytes for each bucket, which the system frees when the node exits, and downloads a range that several chunks need at once only once: for a log-filtered processor a Base day took about 4.3 GB, and an Arbitrum One day about 0.9 GB. A Base day’s ranges fill most of the default 4 GiB: with 2 GiB, chunks downloaded some again, and the day took 5 GB and ran 13% slower. What a chunk downloads counts against budgets.temporary_disk_bytes, and a chunk whose rows would decode to more than budgets.memory_bytes is refused before it downloads: an unfiltered Ethereum day took about 8.7 GB of memory. Each active chunk holds its own rows, so a Base backfill with the default eight active chunks peaked at about 7 GB of memory. Reads go out as parallel ranged requests, up to four per budgets.source_concurrency. With a log filter, only blocks whose logs bloom admits it are decoded.

History source order

A backfill splits its range into gaps of missing coverage and tries the configured history sources for each gap in priority order, lowest first. A source that fails on part of a gap passes only those blocks to the next source: a dataset hole, from its first to its last block in the chunk read, or the chunk whose read failed. It keeps the blocks before them, and the first source takes the gap back after them. A source that has not published the blocks, whose schema changed, or that fails again before committing a block passes the rest of the gap instead, and one that cannot fill the processor’s field groups is skipped for the job. Each backfill retries up to three times the number of sources, at least five times, before it fails. When every history source fails and the live source is execution P2P, P2P can serve the gap within sources.live.history_fallback_blocks.

The shipped profiles list eraE at priority 10 and Xatu at priority 20:

Source Serves Checks each block for Notes
era_e Whole blocks and receipts up to its mirror’s last catalog update Transactions and receipts roots against the header The public mirror’s catalog ended at block 24,518,655 (2026-02-26) when this was written
xatu Columnar projections, about one day behind the chain, until the day Glamsterdam activates Transaction rows against the beacon payload count; log rows without a gap Cannot prove a block’s last logs complete; Ethereum mainnet only
aws_public (opt-in) Headers, receipts, and logs: a whole UTC day per chunk on Ethereum, the pages of a chunk’s blocks on Base and Arbitrum One Receipts root and logs bloom against the header; the block hash, where the export has every header field (Base, Arbitrum One) The export names the canonical chain; no transaction bodies
P2P (live source) Recent and live blocks from peers Commitments of every header, body, and receipt Slowest for old history; peers may no longer serve very old blocks

So for blocks the eraE mirror covers, a backfill reads verified complete blocks; for later blocks, Xatu; and P2P fills what neither serves. Put Xatu first when bandwidth, not completeness, limits a backfill: its projections transfer fewer bytes per block for processors that read a few columns.

Sizing for bandwidth, memory, and disk

Measured with this release on a Hetzner EX44 (Intel i5-13500, 20 threads, 64 GB, RAID 1 over two NVMe drives, 1 Gbit/s) that other workloads share, 25,000-block backfills with one consumer and MALLOC_ARENA_MAX=2:

Backfill Source Downloaded per block 4 reads, 2 chunks 8 reads, 4 chunks
rollup-txs, Feb 2026 eraE 122 KiB 410–450 blocks/s, 180 MiB 560 blocks/s, 270–280 MiB
blobs-money, Feb 2026 eraE 122 KiB 410–450 blocks/s, 180 MiB 540–570 blocks/s, 280–290 MiB
rollup-txs, Feb 2026 Xatu 61 KiB 510–700 blocks/s, 310–320 MiB 820–1,010 blocks/s, 430–550 MiB
blobs-money, Feb 2026 Xatu 72 KiB 570–610 blocks/s, 600–670 MiB 620–640 blocks/s, 740–750 MiB
rollup-txs, Oct 2026 Xatu 56 KiB 730–770 blocks/s, 270–330 MiB 1,080 blocks/s, 400–410 MiB
blobs-money, Oct 2026 Xatu 46 KiB 650–800 blocks/s, 420–430 MiB 620–780 blocks/s, 680–860 MiB

“4 reads, 2 chunks” is source_concurrency = 4 and maximum_active_chunks = 2, as deploy/container.toml ships; the other shipped profiles read with 8 and keep the built-in 8 chunks. Each cell gives the speed and the peak memory. Ranges span repeated runs, which differed by up to a third with the archives’ throughput and the shared host’s load. With jemalloc, which the container image preloads, peak memory stayed within a fifth of these and fell back once a backfill finished. Execution P2P served 5,000 recent blocks at 43–55 blocks/s.

More reads and chunks made most backfills faster, at more memory. An eraE backfill is also limited by the frames each chunk may hold before the job commits them, maximum_buffered_frames_per_acquisition in [budgets.history_material]: with the former default of 128, the eraE backfills above ran at 320–340 blocks/s with 8 reads and 4 chunks. More than 1,024 frames, or a larger memory_bytes, made them no faster. Profiles:

  • Default: the shipped profiles, which try eraE before Xatu and read up to 8 chunks at once with 8 reads each.
  • Less memory: set maximum_active_chunks = 4, the “8 reads, 4 chunks” column. Xatu backfills then hold about half as much, and execution P2P backfills fetch about half as much at once.
  • Limited memory, such as a container under 1 GiB: use 4 reads and 2 chunks. eraE needs the least memory.
  • Limited bandwidth: a backfill downloads blocks per second times bytes per block, about 65 MiB/s from eraE at 550 blocks/s and 30–60 MiB/s from Xatu at the speeds above. On a slower link, the link sets the speed: at 100 Mbit/s, about 12 MiB/s, eraE reaches about 100 blocks/s and Xatu 170–270. There, list Xatu first for processors that read only transactions, such as rollup-txs and transaction-stats, and keep eraE first for processors that read logs, which Xatu cannot prove complete.
  • Slow disk syncs, such as network-attached volumes: keep target_writer_hold at 250 ms or raise it. A lower target shrinks batches (see Advanced root fields).

Xatu additionally accepts three acquisition-tuning controls. chunk_blocks sets the generic header, transaction, and log span, while blobs_chunk_blocks sets the wider span used by the five-table blobs join. Both must be non-zero multiples of Xatu’s physical 1,000-block execution partition. batch_rows controls the bounded Arrow/Parquet decode batch and is independent of history-source concurrency. The measured defaults are 1,000, 8,000, and 8,192 respectively. Increasing a span can reduce repeated daily object reads, but it also increases per-chunk memory and is not universally faster; tune it per projection rather than as a global block-size knob.

[sources.live] kind = "p2p" enables the shared persistent Reth peer manager. It requires verified beacon_api or consensus_p2p finality, or op_gossip on an op-stack chain. Stable production ports normally use listener_port = 30303, discovery_port = 30303, and discv5_port = 30304. Discv4 and Discv5 require distinct fixed UDP ports; zero selects an isolated ephemeral port for that protocol. stall_timeout_seconds, ten minutes by default and six minutes to 30 days, bounds how long the live lane may stay not ready while verified finality is ready, within one run of the network lanes: after it, the node exits with status 1 so that its process supervisor restarts it. A wait at the recent-frame hard limit does not count.

Reth owns the bounded dial queue and receives TCP/RLPx failures directly. A terminal failure immediately releases its slot to another eligible peer, while Reth’s per-peer backoff prevents rapid redials. Newly authenticated DNS/Discv candidates are added to that same queue. max_concurrent_dials remains the hard simultaneous dial ceiling; peer_refill_interval_ms is only a short safety-net poll for newly added candidates, not a network request rate. minimum_peers is the connected-session startup gate. A peer need not finish capability qualification before requests may use it: every response is still commitment-checked, and qualification ranks proven peers first. Background qualification continues concurrently until body_serving_peer_target distinct peers have served a commitment-valid body at the current target; the default target is four. Request health is tracked independently for headers, bodies, and receipts. A timeout or incomplete response cools only that material lane, so a peer that cannot serve one processor’s body request remains available to processors that can use its headers or receipts. Commitment-invalid data still bans the peer.

bootstrap_dns_tree may point at an optional EIP-1459 enrtree:// peer-hint tree. The public key embedded in that URL authenticates its ENRs. It does not make those peers trusted sources: Leani still commitment-checks every header, body, and receipt. This is the deployment hook for a future Leani/community pool of execution nodes prepared to accept indexing traffic; compact and advanced configurations leave it unset by default.

Finality checkpoints are bootstrap trust anchors, not evergreen config defaults. The first start needs a checkpoint at most 14 days old; later starts bootstrap from the newest verified anchor the node persisted (see the runbook’s checkpoint lifecycle). Enabled finality requires a recent 32-byte checkpoint root other than all zeros. consensus_p2p also requires its non-zero finalized beacon slot and a finality.minimum_peers of at most 24, the consensus peers dialed at once. beacon_api requires one or more endpoints, each transport listed once, and minimum_agreement within their count. Disabling finality is suitable for bounded finalized-dataset backfills, not verified head following: the live lane includes a block only once its ancestry reaches an execution header the sync committee attested, which the finality source verifies each slot, so validation refuses sources.live.kind = "p2p" with finality.kind = "disabled".

[confirmation] names the consensus nodes behind the confirmed level and JSON-RPC safe: Beacon API endpoints with Fast Confirmation enabled (Lighthouse --enable-fast-confirmation, Lodestar --chain.fastConfirmation), whose fast_confirmation event stream the node follows. They serve no chain data, and credentials in their URLs are kept out of logs and status.

[confirmation]
endpoints = ["http://127.0.0.1:5052/"]
minimum_agreement = 1

minimum_agreement of the endpoints, within their count and each listed once, must confirm a block. The section applies on an Ethereum chain with sources.live.kind = "p2p" and beacon_api or consensus_p2p finality; under other sources it is inert, with a warning at startup, and on a rollup it is refused. Compact Ethereum Mainnet configurations name ChainSafe’s public Lodestar node, a free third-party service: name your own node for production. An advanced configuration without the section, or any with endpoints = [], has no confirmed level, and publish = "confirmed" is then refused. The finality levels say what the level means, and the trust model what the endpoints are trusted with.

On an op-stack chain, such as Base, finality.kind = "op_gossip" follows the sequencer’s signed block gossip and needs no checkpoint. Every block the sequencer’s key signed becomes the attested head the P2P live lane follows: the chain entry’s key, a newer one the L1 anchor read, or finality.sequencer_signer when that is set, so blocks reach attested about as fast as unattested. Without an L1 anchor nothing finalizes a block unless finality.finalized_by = "json_rpc" takes the endpoints’ finalized block, so recent frames are pruned finality.settle_blocks below the newest signed head instead, about one hour of blocks when omitted, or sooner when that hour outgrows budgets.recent_raw_soft_bytes, as Base’s large blocks do; settled blocks keep their level. Gossip peers find the node through its discovery record: fixed, reachable finality.listen_port (TCP) and finality.discovery_port (UDP) let them dial in, which Base needs because its busy consensus nodes refuse new connections, and Unichain because its gossip peers are rarely found otherwise. Since only a few of them carry blocks to a new node, the node keeps the ones that did in op-gossip-peers.txt in its data directory and dials them first after a restart and again whenever signed blocks stop for 10 seconds. Peers whose handshake head lies far behind the signed head are syncing and are dropped while fewer than body_serving_peer_target peers serve the head.

Op-stack history comes from execution P2P through the live lane. A fresh store starts at the lowest start_block among processors with automatic history, and at most sources.live.history_fallback_blocks below the first signed head when that is set. The block before that start is proven by parent links down from the signed head, and the lane catches up along the head’s chain, so caught-up blocks are attested like the ones that follow. A restart resumes from the store’s tip. A processor’s status shows the catch-up’s progress in processedThrough. Blocks are not finalized until the L1 anchor reads the batches that carry them.

Few execution peers take a node they cannot dial back, so a fresh op-stack node behind NAT may find none. sources.live.kind then takes an ordered list, ["p2p", "json_rpc"], as compact configurations and leani init set it for op-stack chains: when no execution peer connects within sources.live.peer_recovery_timeout_seconds (60 there), the next lane run follows over the [sources.json_rpc] endpoints, the chain entry’s public ones unless public_endpoints = "none". Each block they serve must have the hash the sequencer signed or link to a block that does, and its transactions and receipts roots must hold, so one endpoint suffices (quorum defaults to 1). The catch-up is proven by parent links down from the signed head, as over P2P. Every five minutes the node asks whether execution peers serve it again, and the next run returns to P2P once they do. Each return that ends within ten minutes doubles that interval, up to an hour, and one that lasts resets it. kind = "p2p" keeps the node on execution P2P, which World Chain’s compact configuration does: no keyless endpoint serves its blocks’ receipts at a following pace, so the fallback there needs endpoints of your own.

Nitro chains (Arbitrum One and Nova, Robinhood Chain) run no public execution P2P, so sources.live.kind = "json_rpc" serves their blocks. With finality.kind = "sequencer_feed", the node follows the sequencer feed the chain entry names, whose every message carries a block’s hash signed by the chain’s batch poster. The endpoints then only carry blocks: one whose hash differs from the signed one is refused, and one that matches makes it and every block it links to attested, so a single endpoint is enough (the quorum defaults to 1). Near the head, the live lane asks one endpoint for each block the feed signs, with its receipts. It moves to the next endpoint when that one fails or still lacks the block a poll interval later, and asks the next one too while it is slow. The lanes start at a signed block the endpoints serve. A feed connection silent for 30 seconds is reopened. Feed relays replay only the last few minutes, so after a longer outage blocks become attested once the lane reaches the feed’s blocks again. Without [l1_anchor] nothing is finalized unless finality.finalized_by = "json_rpc", and recent frames settle finality.settle_blocks (default 3,600) below the tip.

When the processors need nothing of a block but its header and transactions, such as transaction-stats or block-summary, the live lane makes the blocks the sequencer built from signed transactions from the feed’s messages, each as soon as the feed signs it, and asks one endpoint for each block’s header alone: one call per block, where a block with its receipts takes two. Once the lane reaches blocks whose messages the feed kept, such as those signed while the node started, it makes them this way however far behind it is. The header’s transactions root checks the transactions made, with senders recovered from their signatures; the frames hold no receipts or logs. A block whose header names other transactions comes whole from the endpoint: a transaction that calls ArbRetryableTx through a contract makes ArbOS add a retry transaction that no message carries. So do the blocks of messages from L1, such as deposits, retryables, and batch posting reports (about one block in 200 on Arbitrum One), and of direct calls to ArbRetryableTx. After eight contradicted blocks in a row, the lane fetches every block whole from then on.

With sources.live.trust = "trusted_dataset", processors that take filtered material and need nothing but transactions’ bodies, calldata, and senders get the blocks made without their headers, so the live lane follows the head without JSON-RPC. Their transactions are then declared complete, not checked: they can lack the retry a contract’s redeem call adds, and the sequencer’s signature binds the block hash but not where a message’s fields end, so these frames trust the feed relay to pass messages on unchanged.

A fresh store under the feed catches up from the lowest start_block among processors with automatic history, at most sources.live.history_fallback_blocks below the first signed block when that is set. The node first walks the headers down from the signed block, hashing each itself, and keeps every 256th hash; each catch-up batch then ends at one of them, so no block reaches a processor before it is proven, and the caught-up blocks are attested. A restarted node proves the chain down to its stored tip the same way, and refuses a tip that is not on it. The walk costs one call per block, the catch-up two.

Below the finalized block, history comes from automatic backfills as on Ethereum. With [l1_anchor] that is the block of the assertion the anchor confirmed last, about 6.4 days old; without the anchor and the feed, the endpoints’ finalized block. Each processor with automatic history backfills from its start_block up to it from sources.history in priority order, and the live lane takes over just below it; under the feed it then catches up from there as above; without such a processor the lanes start without waiting for the anchor. A json_rpc history source reads the JSON-RPC endpoint pool below. Under the L1 anchor its blocks are proven by parent links down from the confirmed hash before a processor sees them, at one more call per block, so they are finalized without trusting any endpoint. A source that has not published the newest blocks keeps the ones it has and hands the rest to the next, so with SonarX first Arbitrum One’s history comes from AWS up to its last exported day and from the endpoints for the days after:

[[sources.history]]
id = "sonarx"
kind = "aws_public"
priority = 0
trust = "trusted_dataset"
[[sources.history]]
id = "rpc"
kind = "json_rpc"
priority = 1
trust = "verified_material"

The node keeps the newest confirmed hash in l1-anchor-confirmed.txt in its data directory, so a restart does not wait for the next confirmation.

The JSON-RPC lanes and history read a pool of endpoints: yours first, then public ones. sources.json_rpc.endpoints lists your own, such as a provider account’s keyed URL, paced at sources.json_rpc.calls_per_second (default 40). sources.json_rpc.public_endpoints names the public ones behind them:

public_endpoints Public endpoints Default
chainlist The chain entry’s vetted endpoints, then the keyless HTTPS endpoints chainlist.org lists for the chain whose operators state they track nothing or little (tracking none or limited) With finality.kind = "sequencer_feed"
bundled The chain entry’s vetted endpoints only Otherwise
none None: only your own endpoints
[sources.json_rpc]
endpoints = ["https://arb-mainnet.example.com/v2/<key>"]
public_endpoints = "chainlist" # or "bundled", or "none" for yours alone

Anyone can list an endpoint on chainlist.org, so its endpoints only carry blocks the node checks itself: chainlist needs the sequencer feed, and with json_rpc finality, where the endpoints vouch for the blocks, it is refused. The node fetches chainlist.org’s list at most once a day and keeps it in chainlist-endpoints.json in its data directory; when the list cannot be fetched, the kept one serves, and without one only your own and the bundled endpoints do. leani doctor shows the plan, and the lanes log the hosts they kept.

At start each endpoint must serve the configured chain and eth_getBlockReceipts, or it is dropped. Of the public ones, the bundled stay ahead of the listed ones, which go fastest first, eight public endpoints at most, so few operators see the node’s traffic. Your endpoints take work first and a range another endpoint fails goes to them first; the public ones take what yours leave: more parallel work than yours can hold, and ranges yours fail or rate-limit. Block ranges spread over all of them in parallel, a faster endpoint taking more. Each public endpoint is paced at 40 calls per second, or slower where its rate-limit headers announce a lower limit; it waits as long as a rate limit’s Retry-After asks, slows down on each rate limit, and recovers gradually. All lanes of the node share each endpoint’s pace. Public endpoints are shared and offered free, so list endpoints of your own for long backfills.

L1 anchor

A rollup’s blocks become final on Ethereum twice, and the opt-in [l1_anchor] table reads both: verified Ethereum finality ([l1_anchor.finality], beacon_api or consensus_p2p, as for an Ethereum node) names finalized L1 blocks, and execution P2P serves their bodies and receipts, checked against their roots. On an op-stack chain the anchor checks games against the sequencer’s gossip beside the P2P live lane, so sources.live.kind starts with p2p there.

finalized: the Ethereum block that carries a rollup block’s batch is finalized, so the block can no longer change, minutes after it was made (about two hours on Zora and Soneium, whose batchers post less often). finality.finalized_by says how the node learns it:

  • batches (the default under [l1_anchor]) reads the batches from the finalized L1 blocks. On an op-stack chain these are the successful transactions from the batcher to the batch inbox, both named in the chain entry’s [op_stack] (batch_inbox, batcher; the SystemConfig names later batchers). Their blobs come from the l1_anchor.finality Beacon APIs, each checked against the versioned hash its transaction names, so finality.kind must be beacon_api. A batch names the block it builds on; when that is this node’s block and the batch follows the ones before it, that block and every block below it are finalized, about one batch after their own. A batch counts only when its header passes the rules of derivation that need no transaction: its L1 origin is a finalized block the lane read, inside the sequencing window, and its blocks are timed at their slots, no earlier than their origin and within the sequencer’s drift of it. That the transactions in it are valid is left to the batcher. The blobs cost about 2.2 GB a day on Base and 0.8 GB on OP Mainnet. On a Nitro chain each call to the SequencerInbox the entry’s sequencer_inbox names counts the chain’s messages, and message n is block sequencer_feed.first_block + n; the block this node holds at the last one is finalized. Nothing in a Nitro block names the messages it came from, so this trusts the sequencer to post the messages it signed on the feed, as attested does; a confirmed assertion names the block’s hash, so settled does not. Batch reading starts where the node starts following; history keeps the trust of its source.
  • json_rpc takes the finalized block the chain’s JSON-RPC endpoints agree on, which trusts them: two of them must agree where there are two, or sources.json_rpc.quorum when that is set. It is the one that needs no [l1_anchor]; without the anchor the node follows no Ethereum blocks, and no block is settled.
  • settlement finalizes a block only when it settles.

Batches prove that a block’s transactions and order are fixed on Ethereum, not its execution: until it settles, its state root is the one the sequencer signed.

settled: the settlement contracts in the chain entry’s [l1_anchor] accepted a claim covering the block, days later. A settled block is also finalized. Nothing is fetched from an RPC endpoint.

  • Nitro chains (Arbitrum One and Nova, Robinhood Chain): a confirmed BoLD assertion names its block hash; that block is settled once this node holds it. Confirmation takes about 6.4 days. Recent frames are pruned finality.settle_blocks (default 3,600) below the tip while blocks wait for finality.
  • Op-stack chains: a game of the respected type is checked when it is created against the output root of the block the sequencer signed, and that block is settled once the anchor state registry moves to the game, about 3.5 days later on Soneium, five on Base, and seven on the others. OP Mainnet’s, Unichain’s, Ink’s, and Soneium’s games claim super roots (claims = "super_roots"): the creation call carries the super root’s preimage, which holds the chain’s output root at a time, and the anchor checks the preimage against the claim and that root against the block signed at that time. Soneium, Mode, Zora, and World Chain run permissioned games: only the chain’s proposer creates them, and only its challenger can dispute them.

The lane reads the receipts of the finalized L1 blocks whose logs bloom may hold the contracts’ logs, at most about 1 GB a day. Op-stack game creations and batches also need call data, so on op-stack chains, and on Nitro chains that read batches, it reads every block’s receipts and body, about 2 GB a day. Where it stopped survives restarts (l1-anchor-cursor.json); a cold start reads lookback_blocks (600 by default) below the first finalized block. Its execution P2P uses its own ports, listener_port, discovery_port, and discv5_port, and its own peer store.

On an op-stack chain the lane also follows the rollup’s own changes in the same finalized blocks. When the chain’s SystemConfig names a new unsafe block signer, gossip blocks are checked against that key from then on, and when the anchor state registry comes to respect another game type, the anchor reads that type’s games. What the lane learned stays in l1-anchor-cursor.json across restarts. A rotation from before the node first ran reaches it only through the chain entry or the configuration. The claim format stays the entry’s: after a move between output-root and super-root games, the anchor settles nothing until l1_anchor.claims names the new one. finality.sequencer_signer fixes the signer, and l1_anchor.factory, registry, game_type, and claims replace the entry’s contracts; a configured game_type stays when the registry respects another. On a chain whose entry names no dispute games, such as Base Sepolia, factory, registry, and game_type together name them.

Processor identity and publication

Every modern entry declares:

[[processors]]
id = "evm-events" # registered processor kind
instance = "weth-transfer-v1" # stable operator-selected identity
version = "1.1.0"
start_block = 12965000

Processor code, semantic version, settings, start point, and source identity are part of an instance’s immutable identity. The node refuses a change to any of them under an instance its store holds (processor instance … conflicts with its stored descriptor), before it upgrades an older store, so it never mutates an existing cursor namespace. Give the changed processor a new instance ID: it indexes from its start_block beside the old instance, whose rows stay in the store. Settle the old instance’s backfill subscriptions before and after the switch, as the runbook’s Processor rebuild or rollback describes. Lifecycle policies, such as retention and delivery limits, are not part of the identity and can change in place.

Publication values are:

  • unattested (default): publish apply/undo/finality transitions from the first level the live lane delivers, and keep an unfinalized undo window.
  • attested: publish apply/undo/finality transitions from attested on, and keep an unfinalized undo window.
  • finalized: publish only finalized apply records. Unfinalized changes wait in the store for verified finality, count against the delivery budget meanwhile, and undo is never published.
  • settled: on a rollup with an [l1_anchor], publish only apply records of settled blocks. Finalized changes wait in the store for settlement, days, and count against the delivery budget meanwhile.

[processors.delivery] emit = "job_result" replaces publish for a bounded backfill: it publishes its terminal aggregate and then becomes complete/reclaimable. Deletion remains explicit.

[processors.settings] belongs to the selected factory and is decoded strictly. doctor constructs every configured processor, so malformed ABI, address, pool, or custom settings fail before source or store I/O.

Live gap fill

After downtime the live lane resumes at the newest verified finalized anchor, so a block-local processor skips the blocks between its cursor and that anchor. Automatic history refills them. With history_mode = "on_demand" the lane only announces them, in a system.live_gap.put change, and whoever requests history fills them. [processors.live_gap_fill] lets the lane fill a short range itself:

[[processors]]
id = "blobs-money"
instance = "blobs-production"
history_control = "application_subscriptions"
history_mode = "on_demand"
# ...
[processors.delivery]
mode = "until_acknowledged"
on_limit = "pause" # the default, and the only value a fill accepts
# ...
[processors.live_gap_fill]
max_blocks = 7200 # fill a skipped range of up to about a day; announce longer ones

Before the lane applies the block that follows a skipped range, live or replayed at startup, it recovers the range from the processor’s history sources, 128 blocks at a time, and applies each block, oldest first, as a finalized apply with originKind: "live_recovery". Then it applies the block itself. The live stream stays contiguous and in block order, announces nothing for the range, and the processor’s coverage holds the filled blocks as finalized. The change protocol describes what a consumer sees, and Keep your application in sync what an application still does.

max_blocks is required and takes 1 to 7,200, about a day of slots. The table has no other setting. Validation refuses it for a processor that is not history_mode = "on_demand", because automatic history refills skipped blocks, and for an ordered processor, such as transaction-stats or uniswap-latest, which holds later blocks instead of skipping them. It also requires [processors.delivery] on_limit = "pause", which is the default: validation refuses fail and expire_and_reset, because a fill’s burst of blocks could fail the lane, or reset its consumers, where announcing the blocks would not. It is allowed under both history_control values.

The lane announces a range as it does without the table, and fetches nothing, when the range is longer than max_blocks, when no history source serves finalized blocks, or when the range is not finalized yet. The limit is all or nothing, because blocks filled at the top of a range could not link to the cursor. A fill that starts stops at the first block it cannot fill, and the lane announces from there. That happens when history fails or serves too few blocks; when a block is not finalized, does not link by parent hash to the one before it, is not the canonical block at its height, or lacks material the processor requires; and when the time limit passes. The limit is five minutes and is fixed. The fill starts no request after it and gives up a request still running at it, so a fill runs for at most five minutes plus applying the blocks of its last request. A filled block is as trusted as the same block delivered by a fill_missing subscription, which uses the same sources and verification policy. The filled blocks link by parent hash from the cursor’s block through the range and, when the fill completes, to the block that follows.

The sources are the processor’s history sources, in the order a history request tries them: retained raw history ([raw_history], when enabled), the configured [[sources.history]] by priority, and last the execution P2P bridge, within sources.live.history_fallback_blocks. The bridge is available to a fill during the replay that follows a restart, too. Bandwidth depends on the source. A dataset source such as Xatu serves only the material the processor needs, about a kilobyte per block for blobs-money. Execution P2P transfers whole bodies and receipts, on the order of a megabyte per block on Mainnet today, so a few thousand blocks are gigabytes. Configure a dataset source for a processor that sets the table. Requests run one after another and do not coalesce, so a fill is slower than a pipelined backfill subscription over the same range. sources.live.kind = "disabled" leaves no live lane, so the table does nothing, and require_retained_input = true limits a fill to retained raw history, which usually does not hold the range: the lane announces it.

The live lane is shared. While a fill runs, it takes no other block: every processor’s live lane waits, the head that JSON-RPC reports stops advancing, and WebSocket subscriptions publish nothing new. That happens after the live lane was not running for a while, and max_blocks and the time limit bound it. Several processors with the table fill one after another, and each fetches the blocks again.

Filled blocks are ordinary delivery records under the processor’s delivery policy, and count against delivery.max_bytes and the node-wide [budgets.delivery] and [budgets.store] limits. A lane that reaches one of those limits mid-fill stops there. It holds the block after the range and announces nothing. While the store would refuse that block, because the lane is paused above its stream’s resume mark (90 % of max_bytes), a node-wide budget has no room for it, or the lane is paused at a storage limit while storage stays above its low-water mark, the lane fetches no history. When finality prunes the frame of the block after the range during a long hold, the lane recovers that block from history once the store would take it, as any paused lane recovers its first unapplied block. After a restart of the live lanes, a lane held at a node-wide budget can fetch once more before it waits again. The lane continues the fill once the store would take the block: once consumers acknowledge and pruning brings its stream down to the resume mark, once pruning any stream gives a node-wide budget room, or once storage has room. The unfilled rest is recomputed from the processor’s cursor on resume, so a history commit that an application’s subscription lands above the cursor meanwhile can shorten what the lane fills or announces. That is rare, and idempotent writes and the application’s coverage diff cover it. A single filled block larger than the stream’s max_bytes fails the lane, as an equally large live block would: raise max_bytes or remove the table. A fill also makes a pause at a delivery or storage limit more likely, and a held block’s delta counts against the shared [budgets] pending_delta_bytes; when it does not fit, the lane fails (live_gap_marker_exceeds_pending_delta_budget) until the budget is raised and the lane reset. The runbook lists the log lines and the recovery.

The table is not part of the instance’s identity, so add, change, or remove it in place, as with the lifecycle policies below. A release that predates the table refuses a configuration that has it, so remove it before rolling back.

Orthogonal lifecycle policies

Every processor has six independent lifecycle policies. The pre-launch retention shorthand has been removed so artifact, output, delivery, state, checkpoint, and undo semantics cannot be inferred from one overloaded setting.

State

[processors.state] mode is durable or checkpointed. The store persists processor state in both modes, and [processors.checkpoint] alone decides whether recovery checkpoints are taken: checkpointed requires [processors.checkpoint] mode = "automatic". ephemeral is rejected, because no mode discards processor state.

Artifacts

[processors.artifacts] mode is none, window, or full. Artifacts are immutable finalized map results used for bulk scan, export, and compatible replay. They are independent of queryable output and delivery records; the default is none.

window requires exactly one [processors.artifacts.window] limit: max_blocks, max_age, or max_bytes. Full retention is removed only by an explicit artifact deletion operation.

Output

[processors.output] mode is:

  • none: retain no queryable entity material;
  • latest: retain the current entity value per key;
  • window: retain the declared block, wall-clock age, row, or byte window;
  • full: retain all selected queryable output.

window requires a [processors.output.window] table with exactly one limit: max_blocks, max_age, max_rows, or max_bytes. Validation refuses [processors.output] finalized_only, which was never applied; to publish only finalized blocks, set publish = "finalized".

How much latest keeps depends on the processor’s keys, not on the mode: an ordered aggregate such as transaction-stats writes one key and keeps one row, a per-pool processor keeps one row per pool, and a block-local processor such as evm-events usually writes new keys every block, one per event, so under latest its output grows as under full. leani doctor warns about latest on a block-local processor; use window to bound such output.

Delivery

[processors.delivery] mode is best_effort, window, or until_acknowledged. Byte sizes accept integers or B, KiB, MiB, GiB, KB, MB, and GB strings. Durations accept integer seconds or s, m, h, and d strings.

until_acknowledged requires at least one required [[processors.delivery.consumers]], each with a lease_ttl from one second to 100 years. Required consumers protect pruning until they are explicitly expired/reset; a temporarily lapsed lease does not silently advance the watermark. on_limit is pause, fail, or expire_and_reset. Paused instances automatically resume after acknowledgement/pruning moves below the low-water mark.

Pruning is cumulative and block-aligned:

[processors.delivery.pruning]
interval = "30s"
minimum_batch_blocks = 64
minimum_batch_changes = 10000
maximum_delete_changes = 10000
retain_finalized_blocks = 256
retain_acknowledged_age = "1h"

max_age and retain_acknowledged_age use durable node wall-clock enqueue/acknowledgement time, not Ethereum block timestamps, so the changes a backfill enqueues count as new.

A pass deletes at most maximum_delete_changes. A pass that deletes that many is followed at once by the next, and a stream that pauses at its limit is pruned at once, without waiting for interval.

Checkpoint and undo

[processors.checkpoint] mode is none or automatic. Automatic mode checkpoints processor state at most once per 1,000 finalized blocks, and again when a historical job completes, and keeps the newest positive keep count. A restore repairs state only when the processor’s cursor sits exactly on a checkpoint: a cadence block or the end of a completed job, even if finality reached that block later. A processor between checkpoints cannot be restored from one; restore a full-store backup or rebuild the processor. Portable savepoints are exports, created and deleted explicitly through the API; the node cannot restore them, and automatic checkpoint pruning does not cover them. Each processor instance keeps at most 16, and each new one counts against the physical store budget, which answers 507 when it does not fit. Editing lifecycle policies, for example to raise a limit, leaves existing checkpoints and savepoints valid.

[processors.undo] mode is none or unfinalized, and unattested and attested publication require unfinalized. Unfinalized blocks always keep their undo records, so a reorg can revert them in either mode. Once finality passes a block, unfinalized keeps its record for another safety_blocks blocks and none deletes it at once. Blocks applied as already finalized record no undo.

API and credentials

Set api.bearer_token_env to the name of an environment variable, never a token value. When configured, that one bearer protects native read, stream, consumer, and management routes on the API listener; operational health, metrics, and network-dashboard routes remain unauthenticated. serve fails to start when the variable is unset, holds fewer than 16 characters, or holds anything but printable ASCII without spaces; use a random value such as openssl rand -hex 32. Clients send Authorization: Bearer <token>, with the scheme in any case, and the node compares tokens in constant time. A consumer created through the API carries its own credential, and a backfill subscription’s consumer can; a new one holds 32 to 512 printable ASCII characters without spaces, such as openssl rand -hex 32. Every consumer-scoped call for a consumer with a credential, its streams included, then needs it in x-leani-consumer-credential besides the bearer, and gets 403 without it, so one client cannot move another consumer’s cursor. Listing, inspecting, and revoking consumers stay administrative: only the bearer protects them, so an operator can revoke a consumer whose credential is lost. Consumers declared under [[processors.delivery.consumers]] have no credential and need only the bearer. The store keeps credential hashes and session-token keys under a random per-store secret, which backups carry with the store. A backfill subscription’s credential also enters its idempotency identity, an unkeyed hash of the whole request, so use random credentials.

The native API, HTTP RPC, and WebSocket RPC binds must all differ. RPC has no built-in authentication. A bind beyond loopback, such as 0.0.0.0, fails validation unless it is protected or explicitly opted in:

Listener Beyond loopback requires
api.bind api.bearer_token_env, or api.allow_unauthenticated_remote = true
rpc.http_bind, rpc.ws_bind rpc.allow_unauthenticated_remote = true

Opt in only behind a trusted network or an authenticating proxy. Put remote listeners behind a TLS/authenticating proxy and restrict the unauthenticated operational routes to a monitoring network. The compact configuration has no bearer setting, so its [api] bind stays on loopback; use the advanced schema to serve beyond it.

Browser access

The listeners refuse most requests a web page could make through a visitor’s browser:

  • The native API answers a Host that is an IP address, localhost, or a name in api.allowed_hosts, and answers any other name with 421. A page that points its own name at 127.0.0.1 still sends that name; an address cannot be repointed, so health probes and scrapers that call the node by IP keep working. List every name clients use to reach the API, such as a compose service name or the name a reverse proxy forwards, without a scheme or port: allowed_hosts = ["leani", "indexer.internal"].
  • Browsers send an Origin header on CORS requests, such as fetch() calls to another origin, event streams, and WebSocket upgrades, and on POST and DELETE requests. They send none on navigations or on no-cors GET and HEAD requests, such as an image or script load. Both listeners accept requests without an Origin, and requests from loopback origins on any port. Any other origin gets 403. A browser application served from another origin, including one behind the same reverse proxy, needs its origin in api.allowed_origins or rpc.allowed_origins, such as ["https://app.example"]. The node sets no CORS headers; a cross-origin application still needs a proxy that adds them and allows the content-type and x-leani-request request headers.
  • The native API refuses, with 403 cross_site_request, a GET or HEAD without an Origin that the browser’s Fetch Metadata marks as coming from another site’s page (Sec-Fetch-Site: cross-site or same-site) and not as a navigation (Sec-Fetch-Mode other than navigate). A consumer’s live or backfill stream route refuses such a request even as a navigation, since opening the stream takes the consumer’s session lease. Current browsers send Fetch Metadata only to potentially trustworthy URLs, which are HTTPS, loopback addresses, and localhost; a node reached over plain HTTP by another name or address, such as a LAN IP with allow_unauthenticated_remote, gets none, and neither refusal applies there. The SDK and curl send none either, and pass.
  • A native API POST or DELETE needs content-type: application/json or the header x-leani-request: 1, and gets 415 otherwise. JSON-RPC calls need content-type: application/json. The SDK sends both. A cross-site page can send neither without a CORS preflight, which the node never grants.
  • Only POST /v1/processors/{processor}/collections/{collection}/entities creates a query snapshot. A GET without a cursor reads current output without one.

What still reaches the native API from a page: navigations from another site, including into a frame, to routes other than consumer streams, and GET or HEAD requests without Fetch Metadata: from browsers without it, or to a node served over plain HTTP by a name or address other than loopback or localhost. The page cannot read the responses, but without Fetch Metadata a GET that opens a consumer’s live or backfill stream takes that consumer’s session lease. A consumer’s credential keeps pages from opening its stream, and api.bearer_token_env keeps them from opening any; a browser adds neither header on its own.

When upgrading a relative data_dir, Leani refuses to start if its former working-directory location contains a database or embedded subscriptions while the location beside the configuration holds none: it would otherwise start on an empty store. Move the old state, or set an absolute path to select the intended store. When both locations hold state, it uses the one beside the configuration and warns, naming both. Equivalent paths and symlink aliases of the same directory count as one.

Node-side Wasm builds

api.allow_wasm_builds = true lets the node compile processor source sent to POST /admin/v1/wasm/build, which the playground’s editor uses; the compact profile takes it under [api] too. It is off by default and a development feature, not for production: rustc can read the host’s files while it compiles, and only a denylist of source constructs guards it. With it on, the node builds Rust only for requests from its own machine, an SSH tunnel included, and TypeScript for any client the API admits; it logs a warning when it starts, and leani doctor reports one. A request relayed with a Forwarded, X-Forwarded-For, X-Forwarded-Host, or X-Real-IP header, or addressed to another host name, is not the node’s own, but behind a reverse proxy on the same machine that sets none of them, a remote client’s request looks local. In production, build modules where you write them, or in CI, and configure the module file with its blake3 hash.

Processor changes through the API

api.allow_processor_changes = true lets POST /admin/v1/processors add a processor to the running node and DELETE /admin/v1/processors/{processor} remove one it added; the compact profile takes it under [api] too. The node keeps added processors in its data directory’s processors.toml, in the [[processors]] schema, and their Wasm modules in modules/, and loads that file after the configuration file on every start. An instance both configure runs as the configuration file says, with a warning. Each change restarts the network or JSON-RPC lanes in-process: a live pause for every processor. Off by default, as a node configured as code should not change beside its configuration.

Historical CLI and node backfill

leani backfill --processor INSTANCE --from-block N --to-block M uses the same history source assembly, configured pipeline, material coordinator and verified P2P fallback as node jobs. --processor defaults to the configuration’s only processor. When live P2P is enabled, the standalone command verifies the configured finality anchor and opens its own persistent peer pool. It checks the finalized upper bound and honors sources.live.history_fallback_blocks. No live listeners or processors are started. Disabled P2P and retained-input-only policies remain in force.

To use a running node and its existing peer pool:

Terminal window
leani backfill --endpoint http://127.0.0.1:18080 \
--processor INSTANCE --from-block N --to-block M

The command sends an authenticated materialization request and waits for its status. LEANI_API_TOKEN supplies the token without putting it in shell arguments. The token travels in an Authorization header, so across hosts use HTTPS, for example through a TLS-terminating reverse proxy; plain HTTP suits loopback or a private container network, and the command warns when it sends the token over plain HTTP beyond loopback. An optional endpoint path prefix is preserved. Ctrl-C cancels the submitted job. Without --endpoint, stop any process holding the data directory before starting standalone backfill. Ctrl-C cancels a standalone run, so the next serve does not resume it; a second Ctrl-C exits at once.

A standalone job is named by processor, chain and range. When an earlier run of the same range recorded another verification policy, for example before raw_history was enabled, the store refuses the new input as a different job. Delete the earlier one with DELETE /admin/v1/materialization-jobs/{id}, or submit through --endpoint, which uses a fresh key per submission.

Xatu exports have table-specific coverage. In particular, a recent beacon file does not prove that the execution-transaction file needed for receipts has been published. Missing or incomplete partitions can fall back to the verified P2P bridge; dataset-only configurations need another available history source. Finality or peer failures are reported rather than silently removing the configured bridge.

JSON-RPC limits

Each limit has a rpc setting:

Setting Default When exceeded
max_batch_requests 100 the batch is refused whole with one -32600 error
max_response_bytes 16MiB each call past the limit is answered with -32005
max_log_results 10000 eth_getLogs fails with -32005 and a smaller block range to retry
max_log_addresses 1000 the filter fails with -32602
max_log_topic_alternatives 1000 the filter fails with -32602
max_subscriptions_per_connection 128 eth_subscribe fails with -32005
max_websocket_connections 256 the WebSocket upgrade gets HTTP 503
max_outbound_bytes 64MiB queued notifications of all WebSocket connections; when full, the connection holding the most is closed with 1013
max_subscription_event_bytes 16MiB a WebSocket connection whose subscriptions produce more notification bytes for one chain event is closed with 1008, and one that leaves more unread with 1013

A closed WebSocket connection releases its slot and its subscriptions. Notifications are queued one at a time, so while earlier ones are still unsent, a connection can be closed with 1013 before one event’s notifications pass the limit that would close it with 1008. Each connection holds at most max_subscription_event_bytes of queued notifications and one response to a call; it reads its next call only once that response is sent, so a slow reader slows only itself. A connection that keeps more than a quarter of its notification room queued for 30 seconds is closed with 1013: it reads slower than its subscriptions produce. All WebSocket listeners also share max_outbound_bytes of queued or sending notifications (64 MiB by default). When that runs out, the connection holding the most of it is closed with 1013, not the one that notifies next; responses never use it. A send may take 30 seconds plus the time its payload needs at 64 KiB/s before the connection is closed. These are encoded-payload limits, not process RSS limits: at the defaults, responses add at most max_websocket_connections × max_response_bytes. max_outbound_bytes must be at least max_subscription_event_bytes and at most 4,294,967,295 bytes.

rpc.transaction_locator is deprecated and ignored: nothing reads it. The node still accepts it, with a warning in its log and in leani doctor; remove it.

Delivery batching

History and live delivery use independent transport limits under api.delivery.history_batches and api.delivery.live_batches. The defaults are byte-first (a 4MiB target in both), with hard encoded-byte, event, processed-block, and maximum-delay bounds; only the delay differs (50ms history, 10ms live). A live batch never waits for new blocks: at the head it holds one block, and for a consumer that is behind it packs the whole blocks already committed, reading on toward its target for at most maximum_delay. A block whose changes pass maximum_events or maximum_encoded_bytes arrives in several batches, which the consumer acknowledges only at the block’s end; one change larger than maximum_encoded_bytes ends the stream with single_change_exceeds_delivery_batch_limit until the limit is raised. A live batch also leaves room in maximum_buffered_bytes for its record’s own fields, so its changes stay below that buffer even when it is no larger than maximum_encoded_bytes. History subscriptions may request smaller effective limits; those values are persisted with the subscription and returned by its status endpoint. maximum_buffered_batches and maximum_buffered_bytes independently cap the per-connection encoder queue; backpressure stops the encoder producer before either bound is exceeded. SDK delivery sessions refuse an NDJSON record over 65 MiB with a non-retryable invalid_response error. A record carries up to maximum_encoded_bytes of changes plus its own fields, so for SDK clients keep each lane’s maximum_encoded_bytes at or below 64 MiB; raising it, and maximum_buffered_bytes with it, beyond that lets a record exceed what the SDK accepts. Opening a history stream may request only stricter byte/event/block/delay limits through query parameters; these are connection-local and do not mutate the durable subscription. A live stream, including one the SDK’s streamLive() opens, takes no such parameters and uses live_batches as configured. The SDK’s latency, balanced, and throughput profiles are convenience functions that expand to those concrete numbers and are resent after reconnect. compression = "gzip" is negotiated through Accept-Encoding; the response is one continuous gzip member with an explicit sync flush after every NDJSON record, so batches and heartbeats are observable immediately by streaming decoders. Set it to "none" to disable compression for that lane.

Pre-launch schema policy

The project is not live yet and has no compatibility contract for existing consumers, config files, or databases. Configuration, SDK, API, and SQLite schemas may be replaced when that produces a cleaner final design; development databases should be recreated after an announced incompatible change. Durable delivery and processor encodings remain explicitly versioned so upgrade-safe replay can become a launch requirement without changing the public cursor model.