Indexing and Reorgs

Author: Denham Preen, Co-Founder at Envio

TL;DR

• Envio HyperIndex detects chain reorganizations (reorgs) and rolls back your indexed data automatically. It's on by default (rollback_on_reorg: true), covers reorgs up to max_reorg_depth blocks below the chain head (200 on most chains), and needs no rollback logic in your handlers.
• Reorg detection is guaranteed when your indexer reads from HyperSync, the default data source on supported chains. HyperSync returns the logs and blocks for a range atomically, so block hashes and parent hashes always match the data returned.
• A rollback covers every entity in your schema. Side effects your handlers cause outside the database, such as calls to external APIs, are not rolled back.
• Reorgs only matter near the chain head, so a backfill of finalized history isn't affected by them.
• Stateful and multichain indexers are the hard cases. A reorg on one chain can mean rolling back state that events from other chains also touched.

In this article, we unpack the implications of chain reorganizations on consuming and aggregating onchain data, considerations in a multichain environment, and how to design for them. We also cover what HyperIndex does for you out of the box, and where its automatic handling stops.

We assume you have a strong understanding of what a chain reorganization is. If you want a refresher, skip to the bottom.

Note: Handling reorgs is only important if you are indexing at the head, or handling data within the range of the head and the network's finalized block.

How Envio Handles Reorgs Automatically

You don't need to write reorg handling into your indexer if you build it with HyperIndex. Reorg support is built in and enabled by default. HyperIndex keeps a history of entity changes for the blocks that could still be reorged. When it detects a reorg, it finds the block where the chains diverged, rolls every entity back to that point, and reprocesses events from the canonical chain. Your handlers stay the same.

Two settings in config.yaml control it.

rollback_on_reorg: true # default
chains:
  - id: 137 # Polygon
    max_reorg_depth: 250 # deeper than the default
  - id: 1 # Ethereum
    # uses the default depth

max_reorg_depth defaults to 200 blocks on most chains. On Arbitrum and OP Mainnet it defaults to 0, which means no rollbacks there until you set it yourself. A reorg deeper than that won't trigger a rollback, so raise it for high-value applications or chains with a history of deep reorgs.

There are three limits worth knowing before you rely on it in production.

• Data source. Detection is guaranteed when HyperIndex reads from HyperSync, which returns logs and blocks for a range atomically. With a custom RPC endpoint, logs and block headers come from separate requests, so there are some edge cases where a reorg can go unnoticed, as with any indexer that reads from RPC.
• Side effects. Everything your handlers write to the database is rolled back. API calls, external services, custom caches and files written outside HyperIndex are not, so keep handlers free of side effects you can't undo.
• Turning it off. Setting rollback_on_reorg: false disables rollbacks. We don't recommend that for production indexers.

The full reference, including per-chain examples, is in the reorg support docs.

Chain Reorgs and Independent Data

Independent data is data that does not require the previous state in order to process the current state. In an indexer, this means only "create" operations. If the only CRUD operations your handlers perform are writing entities, your indexer is handling stateless data, and handling reorgs is straightforward: delete all entities from orphaned blocks and re-ingest them with the canonical block's data. This is possible because stateless data allows for parallel processing.

In practice, we usually need to perform some aggregation on data to turn it into meaningful information. In that context, our indexer is dealing with stateful data.

Side tangent: Stateless indexing can be handled incredibly fast by parallelization, such as indexers like Flair that achieve impressive speed with only RPC.

Chain Reorgs and Stateful Data

Stateful data is data that depends on the previous state (think update and delete operations) in order to process the current state. When handling stateful data, your indexer needs to account for the current state of entities, and reorgs become notably more complex.

During a chain reorg, rather than simply replacing orphaned data, you need to revert previous operations or changes and ensure that the entity state is rolled back correctly. This requires tracking the history of changes to each entity so that when a reorg occurs, you can accurately undo or adjust state based on the adopted canonical chain's data.

Note: We can periodically prune the entity history, retaining only the changes relevant to unfinalized blocks.

This is the part HyperIndex automates. It records entity history for unfinalized blocks, prunes what falls outside the reorg window, and uses that history to roll back.

Reorgs and Multichain Indexing

When it comes to multichain indexing, we face additional complexity because we process events from multiple sources that interact and update the same entity state. When one chain undergoes a reorg, we need to roll back the state to a known correct point and reprocess any events from all chains that affected the state after the reorg on the affected chain.

By default, a reorg on one chain in a HyperIndex multichain indexer rolls back every chain, because entities can be shared across chains. If your chains don't share state, the per-chain data mode keeps rollbacks isolated. With disable_default_cross_chain: true set and no entity marked @crossChain, a reorg rolls back only the chain that triggered it.

Reorgs, Backfills and Data Completeness

A backfill is the historical sync from your start block up to the head. Almost all of that range sits below the finalized block, so reorgs don't apply there, and reorg handling only starts to matter once the indexer reaches the reorg window near the head.

Data completeness is a separate question. In rare cases a node can return an eth_getLogs response with logs missing, and reorg handling won't catch that because nothing about the chain changed. We covered documented cases, and how HyperSync checks for them on supported chains, in Nodes Silently Miss Events.

Reorgs in the Wild

In practice, different networks exhibit varying levels of exposure to reorgs based on their design. Some networks, like OP Mainnet, rarely reorg in practice because a single sequencer orders their blocks, though full finality still waits for Ethereum and exceptions do exist. On the other hand, networks like Polygon frequently experience deeper reorgs, where forked chains can extend over 10 blocks deep. One notable instance involved a reorg of 157 blocks. Block explorers such as Etherscan and Blockscout list the forked blocks their own nodes saw, so their counts depend on how closely those nodes follow the canonical chain and are best read as a rough guide. Etherscan's all-time count works out to just under 1% of Ethereum mainnet blocks, meaning that, assuming a 50/50 chance of a transaction being included in either the orphaned or canonical chain, roughly 1 in 230 transactions would have landed in a reorged block. More than nine in ten of those forked blocks date from before the Merge, and Ethereum reorgs are much rarer today.

Conclusion

Reorgs are a crucial consideration in blockchain indexing. Understanding their implications and designing with flexibility allows you to properly account for them in your indexer. Envio handles reorg detection and state rollback automatically and by default, so developers building on HyperIndex get correct data at the head without needing to implement rollback logic themselves. Read from HyperSync for guaranteed detection and keep side effects out of your handlers. For the failures that aren't reorgs, such as a data source going down or the indexer process stopping, see Production Indexer Reliability.

What Are Chain Reorgs?

In order to understand reorgs, let's break down the fundamental concepts and build up to a definition.

Fundamental concepts:

• Block
• Chain
• Miners
• Chain fork
• Orphaned chain
• Canonical chain
• Block finality

Block

A container that stores transactions.

Chain

A series of sequential blocks.

Miners

Actors that try to submit the next valid block.

Chain Fork

A chain fork occurs when more than one miner submits a valid block at the same time, causing a split where two valid chains exist simultaneously.

Orphaned Chain and Canonical Chain

When a chain forks, eventually one chain becomes accepted as the valid chain, known as the canonical chain. The forked chain that is not accepted becomes the orphaned chain. Orphaned blocks cease to exist, and transactions that occurred in those blocks cease to exist as well.

• Orphaned chain: The forked chain that is dropped
• Canonical chain: The chain adopted as the valid chain

Info: We do not know which fork will be orphaned and which will become canonical until after the fact.

Block Finality

The minimum number of blocks needed to confirm that blocks will not become part of an orphaned chain.

Info: Block finality is the reason bridges and centralized exchanges require a confirmation delay after a transaction is confirmed, to ensure blocks will not become orphaned.

Reorg

A reorg is a set of events that results in a chain rolling back to a previous point in time.

Frequently Asked Questions

How Do Blockchain Indexers Handle Reorgs, Backfills and Data Completeness?

Near the chain head, an indexer has to detect reorgs and roll back any data written from orphaned blocks. Envio HyperIndex does this automatically, by default, for reorgs up to max_reorg_depth blocks deep. Backfills cover finalized history, so reorgs rarely apply there. Data completeness is a separate and less common problem, where a node drops logs from a response, and Nodes Silently Miss Events covers how HyperSync checks for it.

How Do I Implement Automatic Reorg Handling in My Indexer?

With HyperIndex you don't implement it. Reorg handling is on by default through rollback_on_reorg: true in config.yaml, and HyperIndex rolls back every entity in your schema when it detects a reorg. You can tune how deep it looks with max_reorg_depth per chain (200 blocks on most chains by default). If you're building on raw HyperSync without HyperIndex, you handle it yourself with the rollback guard returned with query responses near the chain head.

What Causes Reorg Failures in a Multichain Indexing Setup?

Most failures come from one of four things. A reorg deeper than the configured max_reorg_depth. A chain whose default depth is 0, such as Arbitrum or OP Mainnet. Handler side effects outside the database, which a rollback can't undo. Or rollback_on_reorg turned off. In a multichain indexer, state shared across chains means a reorg on one chain has to roll back the others too, which HyperIndex does by default. If your chains don't share state, the per-chain data mode keeps rollbacks to the chain that reorged.

Does Envio Require Handler-Level Logic to Handle Reorgs?

No. Reorg detection and rollback are built into HyperIndex and enabled by default, so your event handlers need no reorg-specific code. The only thing left to you is side effects outside the database, such as calls to external APIs, which are not rolled back.

Is Reorg Detection Guaranteed With HyperSync?

Yes. HyperSync returns the logs and blocks for a range atomically, so block hashes and parent hashes always match the data returned, and HyperIndex can rely on them to detect a reorg. Use HyperSync wherever it's available for the chain you're indexing. RPC-based indexers, by comparison, fetch logs and block headers in separate requests, which leaves some edge cases.

Does Every Blockchain Indexer Need to Handle Reorgs?

Not necessarily. If your indexer only processes finalized blocks (past the finality threshold), reorgs are not a concern. Reorg handling is only important if you are indexing at the head or within the range between the head and the network's finalized block.

What Is the Difference Between Stateless and Stateful Indexing for Reorgs?

A stateless indexer only creates new entities. On a reorg, you delete orphaned entities and re-ingest from the canonical chain. A stateful indexer also updates and deletes entities based on previous state, which requires tracking the history of changes so that state can be accurately rolled back when a reorg occurs.

Which Networks Experience the Most Frequent or Deepest Reorgs?

Polygon is known for frequent and sometimes deep reorgs, and a 157-block reorg has been recorded. OP Mainnet rarely reorgs in practice, though exceptions exist, and Ethereum mainnet reorgs are much rarer than they were before the Merge. Block explorers such as Etherscan and Blockscout list the forked blocks their own nodes saw, which gives a rough guide for a specific network.

Build With Envio

Envio is the fastest independently benchmarked EVM blockchain indexer for querying real-time and historical data. If you are building onchain and need indexing that stays correct at the head, check out the docs and the reorg support guide, run the benchmarks yourself, and come talk to us about your data needs.

Stay tuned for more updates by subscribing to our newsletter, following us on X, or hopping into our Discord.

Subscribe to our newsletter 💌

Website | X | Discord | Telegram | GitHub | YouTube | Reddit