Building a Reorg-Safe EVM Indexer with eth_getLogs and Checkpoints

A production design for ingesting EVM logs with bounded block ranges, canonical checkpoints and reversible derived state.

Store block identity, not only height

Every event record should include chain ID, block number, block hash, transaction hash, log index and removed state. A height without its hash cannot detect a canonical-chain replacement.

Advance a canonical checkpoint

Process bounded ranges and persist the highest block whose hash and parent relationship were verified. On restart, recheck several previous checkpoints before continuing.

Separate seen from finalized

Expose provisional events quickly but promote them only after the application’s chosen confirmation depth or finalized tag. Business actions should state which confidence level they require.

Rollback derived state deterministically

When a stored block hash disagrees, find the common ancestor, mark orphaned events and replay balances or aggregates. Append-only raw events plus reproducible projections make this tractable.

Adapt ranges to provider behavior

eth_getLogs limits vary by provider, address count and topic complexity. Shrink ranges on timeout, expand after stable success and record provider-specific gaps instead of silently skipping them.

Build dependable chain data

TierZero develops EVM bots, indexers and data pipelines and monitoring. The Ethereum JSON-RPC documentation defines the log filters; contact us for a production build.

Production checklist

Before launch, define ownership, test fixtures, failure states, alerts and a rollback procedure. For a scoped engineering review, use the TierZero project form.