Blockchain Finality, Reorgs & Reliable Indexing

Finality, Reorganizations, and Indexing

Blockchains are often described as immutable, but the most recent blocks are not. Different nodes can briefly see different chain tips, and when the network converges, some recent blocks are reorganized out of the canonical chain — their transactions dropped or reordered. Only after finality — probabilistic for proof-of-work chains, economic for Ethereum's proof of stake — is history safe to treat as permanent.

Off-chain systems — exchanges crediting deposits, indexers powering dashboards, backends tracking NFT ownership or payments — must handle this explicitly. An indexer that assumes every block is final will eventually show balances that never existed, credit deposits that were reorganized away, or process the same event twice. Correct designs choose confirmation policies by risk, track block hashes to detect reorgs, roll back derived state, and process events idempotently.

TL;DR

Recent blocks can be reorganized; finality is when reversal becomes practically impossible or economically prohibitive.
Ethereum exposes latest, safe, and finalized blocks; finalization typically takes about two epochs (around 13 minutes).
Bitcoin uses confirmation counts (six is a common threshold for large amounts); Solana uses processed, confirmed, and finalized commitment.
Layer 2s have stages: sequencer confirmation, data posted to L1, and L1 finality — plus challenge periods for optimistic rollup withdrawals.
Choose confirmation policies by value and risk: show pending quickly, credit irreversibly only when final.
Indexers store block number and hash, detect reorgs via parent hashes, roll back to a common ancestor, and process events idempotently.

Quick Example

A reorg-aware indexing loop with web3.py: verify that the last indexed block is still canonical, roll back if not, index new blocks, and mark state final only up to the finalized block:

Core Concepts

Why Reorganizations Happen

Blocks propagate through a peer-to-peer network with delays. Two valid blocks can be produced for the same height, or a node can build on a block that most of the network later abandons. Fork-choice rules (longest or heaviest chain, LMD-GHOST in Ethereum) resolve the competition, and nodes that followed the losing branch reorganize. Short reorgs of one or two blocks at the chain tip happen routinely; deep reorgs are rare but possible, especially on smaller chains or during incidents.

Finality by Chain

See Ethereum, Solana, and Layer 2 Scaling.

Confirmation Policies

Make the policy explicit per action and per chain, and communicate states to users ("pending", "confirming", "complete").

Reorg-Aware Indexing

Indexers turn chain data into queryable state. To survive reorgs:

Store each processed block's number, hash, and parent hash.
Before processing a new block, check that its parent hash matches the stored previous block; if not, a reorg occurred.
Roll back derived state to the common ancestor, then re-apply the canonical blocks. Design storage so rollback is cheap: keep per-block change records, or rebuild aggregates from event tables.
Key events by (chain ID, transaction hash, log index) and upsert, so replays are idempotent. See Idempotency.
Subscriptions (eth_subscribe to logs) mark removed logs with removed: true during reorgs; handle them rather than ignoring them.

Indexing frameworks (The Graph, Ponder, Subsquid, Envio) implement much of this; understand their reorg handling and finality settings before trusting their data for money-moving decisions. The pattern resembles Change Data Capture: a stream of changes whose recent part may be revised.

Reconciliation

Even with careful indexing, verify: periodically compare indexed balances and totals against direct node queries (for example balanceOf at a finalized block), alert on differences, and keep the ability to reindex from a known block.

Best Practices

Separate Display From Settlement

Show fast, provisional states to users, and perform irreversible actions only on finalized data.

Store Hashes, Not Just Numbers

Block numbers repeat across forks; block hashes identify history uniquely.

Make Processing Idempotent and Reversible

Upsert by natural keys and keep enough history to roll back and replay.

Reconcile Against the Chain

Periodically compare derived state with direct node queries at finalized blocks.

Common Mistakes

Crediting on First Sight

Indexing by Block Number Only

Treating L2 Confirmations as L1 Finality

FAQ

What is a blockchain reorganization?

A change in the canonical chain where some recent blocks are replaced by a competing branch, removing or reordering the transactions they contained.

When is an Ethereum transaction final?

When its block is finalized by the proof-of-stake protocol, typically after about two epochs (roughly 13 minutes). Reverting finalized blocks would require a large share of staked ether to be slashed.

How many confirmations are enough on Bitcoin?

It depends on the value at risk. Small amounts are often accepted with one or a few confirmations; six confirmations is a common threshold for larger amounts.

How do indexers handle reorgs?

By storing block hashes, checking each new block's parent hash, rolling back derived data to the common ancestor when a mismatch is found, and re-applying canonical blocks idempotently.

Are layer-2 transactions final immediately?

No. Sequencer confirmations are fast but not final; L2 transactions become final once their data is posted and finalized on L1, and optimistic rollup withdrawals also wait for the challenge period.