Blockchain Reorgs and Data Consistency: Why Your API Can Return Data That Later Disappears
Blockchain reorgs can invalidate transactions after they're indexed. Learn how subgraphs, indexers, and data APIs handle rollbacks, finality, and data consistency.
A blockchain API returns a transaction, the application processes it, and the user's wallet updates. The payment is now marked as received, and the balance in your account is reflected on the interface
All is good, until a few minutes later, the transaction disappears from the blockchain's canonical history.
So...what happened?
This is called a blockchain reorganization, commonly called a reorg. It's a normal part of how blockchains reach consensus, but it creates a problem for applications that depend on real-time on-chain data.
The problem isn't simply that a transaction was removed. It's that an application may have already consumed the data and acted on it.
For blockchain indexers, subgraphs, and data APIs, handling reorgs means more than fetching the latest blocks. They must recognize when previously indexed data is no longer valid, correct the affected records, and ensure downstream applications receive a consistent view of the chain.
An API can return an accurate result at the time of a request and still return information that subsequently becomes invalid. Understanding this nuance is essential for building reliable Web3 applications.
What happens to indexed data during a blockchain reorg?
Blockchains maintain a canonical chain: the sequence of blocks accepted as the authoritative history of the network.
However, the latest blocks are not necessarily permanent. Under certain conditions, the network can replace one or more recently accepted blocks with an alternative sequence.
Consider a simplified example:
- Block 100 contains a transfer of 500 USDC from Alice to Bob.
- An indexer processes the block, records the transfer, and updates Bob's indexed balance.
- A data API returns the transfer in Bob's transaction history.
- The blockchain reorganizes. Block 100 is replaced by a different block that does not contain the transfer.
- The indexer must remove the effects of the original block and process the replacement.
The transfer was part of the chain when the API first reported it. After the reorg, it is no longer part of the canonical chain.
The transaction might eventually be included in a later block, or it might not. If it is included again, its execution context, block number, and event positions may differ.
This is why a block number alone cannot uniquely identify a block. Two competing blocks can exist at the same height with different block hashes and transaction contents.
Ethereum's execution client, Geth, explicitly accounts for this behavior. When a subscribed event log is removed due to a reorg, the client can emit it again with removed: true. A transaction included on the replacement chain can subsequently produce another log notification.
See Geth's event subscription documentation.
For applications querying a database rather than subscribing directly to blockchain events, this correction process is usually hidden behind the indexing infrastructure.
That makes reorg handling a fundamental requirement of reliable blockchain data services.
Why reorgs are a data consistency problem
The bulk of web3 applications don't rely on raw blockchain data.
They rely on indexing infrastructure to transform blockchain activity into structured, queryable data.
A typical architecture looks like this:
Blockchain RPC → Indexer → Database → Data API → Application
The indexer processes transactions, event logs, and sometimes contract calls to create useful records such as token transfers, wallet activity, liquidity positions, trades, and protocol statistics.
These records are exposed through APIs or subgraphs, allowing applications to retrieve the information without scanning the blockchain themselves.
But this introduces several layers where data can become inconsistent.
#1: An indexer can retain transactions that no longer exist on the canonical chain
An indexer that only appends new events without detecting reorgs will eventually retain records from blocks that have been replaced.
These orphaned records can appear as legitimate transactions even though they are no longer part of the canonical history.
For example, a wallet could display a token transfer that was never settled on the canonical chain.
This isn't necessarily an issue with the smart contract or the blockchain as much as it's a failure to reconcile indexed data with the current chain.
#2: Removing an invalid transaction isn't enough
Indexed data often contains more than raw transaction records.
Consider a DeFi protocol where a single transaction triggers several updates:
- A user deposits tokens into a liquidity pool.
- The pool's total liquidity increases.
- The user's position is updated.
- The protocol's total value locked (TVL) changes.
- A dashboard updates its historical deposit volume.
If the block containing that deposit is reorganized out of the chain, removing the transaction record alone does not restore consistency.
The liquidity position, pool totals, TVL, and historical aggregates may all need to be corrected.
This is especially important for subgraphs, which use mapping logic to transform events into persistent entities.
Reorg recovery must reverse the effects of invalidated blocks, not merely delete the original events.
Otherwise, inconsistencies can accumulate silently. A protocol's analytics may report liquidity that doesn't exist, balances may fail to reconcile, or users may see positions that were never established on the canonical chain.
#3: APIs and applications can continue using data after the indexer has corrected it
Even when an indexer handles a reorg correctly, the correction doesn't automatically propagate to every system consuming its data.
An API may cache an earlier result. A frontend may continue displaying a transaction from its local state. A backend may have already triggered a notification or updated an internal ledger.
Consider a payment application that marks an invoice as paid as soon as a token transfer appears in its indexed transaction history.
If that transaction is subsequently removed by a reorg, the indexing database can be corrected, but the invoice may still be marked as paid.
The application has created an off-chain state change based on a provisional on-chain event.
This is where reorg handling becomes an application architecture problem.
A correct indexer can repair its own database. It cannot automatically reverse every business decision made by downstream systems.
How reorgs affect different types of Web3 applications
The consequences depend on what an application does with indexed blockchain data.
| Application | Potential impact of a reorg |
|---|---|
| Wallets and block explorers | Transactions appear and then disappear, balances change unexpectedly, or activity histories become inconsistent. |
| DeFi trading and lending | Indexed positions, collateral amounts, pool liquidity, or risk indicators may reflect state that has been reversed. |
| Stablecoin and payment applications | A payment may be credited before the underlying transfer has sufficient finality. |
| Analytics dashboards | Trading volume, TVL, token supply, and other aggregated metrics may contain orphaned events unless recomputed. |
| Trading bots and AI agents | Automated decisions may be triggered by events or market conditions that do not survive a reorg. |
These applications have different tolerance levels for provisional data.
A wallet may reasonably show an incoming payment immediately, provided the interface communicates that it is awaiting confirmation.
A payment processor releasing goods or credit based on the same event might require stronger finality guarantees.
Likewise, a trading dashboard may prioritize access to the latest information, while a financial reconciliation system may require data from finalized blocks.
The correct approach isn't necessarily to delay all blockchain data until finality. It's to understand what level of consistency each application needs.
Real-time data and finalized data are not the same
One of the most important distinctions in blockchain data infrastructure is the difference between freshness and finality.
Freshness describes how close an indexer is to the latest blockchain state.
Finality describes how strongly the network guarantees that a particular block will remain part of the canonical chain.
An indexer operating at the chain tip can offer extremely fresh data, but the latest blocks may still be reversible.
An indexer serving only finalized data provides stronger assurances about permanence, but at the cost of additional delay.
Neither approach is universally better.
For real-time trading, risk monitoring, and live dashboards, waiting for finality may be too slow.
For deposits, withdrawals, and accounting, acting on the latest block may be too risky.
Ethereum exposes several block references through its JSON-RPC API:
| Block reference | Meaning | Application consideration |
|---|---|---|
latest | Latest block at the chain head | Freshest available state, but subject to reorganization |
safe | Block at the safe head | Stronger confidence that the block will remain canonical |
finalized | Block finalized by Ethereum's consensus mechanism | Strongest standard finality guarantee, with additional delay |
On Ethereum, finalized blocks have strong economic finality: reverting them would require a severe consensus failure with substantial validator penalties.
However, finality models differ between networks. On some Layer 2 networks, the latest sequencer-confirmed block is not equivalent to a block whose data has reached finality on the underlying settlement chain.
For example, Arbitrum's finality documentation distinguishes between sequencer confirmation, parent-chain safety, and finality.
Applications operating across multiple chains therefore cannot assume that the same number of block confirmations—or even the same labels—provides identical guarantees everywhere.
For more on the relationship between the chain head and indexing latency, see What Is the Tip of the Chain?.
What reliable blockchain indexing infrastructure needs to handle
Because applications depend on indexed data rather than raw blocks, the indexing layer plays a critical role in preserving data consistency.
A production indexing system should be designed around several capabilities.
Detecting when the canonical chain changes
An indexer needs to track block identities and ancestry, not just block heights.
When the block hash at a previously processed height differs from the canonical chain, the system must identify the last common ancestor and determine which indexed blocks are no longer valid.
Without this detection, the indexer may simply continue processing new blocks on top of incorrect historical state.
Reverting affected indexed state
Once a reorg is detected, the indexer needs to reverse changes associated with the orphaned blocks.
For a subgraph, those changes can include entity creation, deletion, and updates to existing entities.
For an indexer maintaining aggregate data, they can also include balances, running totals, historical statistics, and other derived records.
Reverting the state consistently is particularly important when multiple entities depend on the same event.
Reprocessing the canonical chain
After reverting invalidated blocks, the indexer must process the replacement blocks and rebuild the correct state.
The result should reflect the canonical blockchain history, without duplicate transactions, missing events, or lingering updates from the discarded chain.
This requires deterministic processing and safe recovery behavior.
Maintaining consistency while corrections occur
A reorg may affect many records. Applications should not receive a partially corrected view in which some entities reflect the old chain while others reflect the replacement chain.
Reliable indexing systems need appropriate transaction boundaries, versioning, or other consistency mechanisms to ensure queries observe coherent state.
This is especially important for DeFi applications where balances, positions, and protocol-level metrics are related.
Recovering from deeper reorganizations and infrastructure failures
A robust indexing pipeline also needs to account for unusual conditions, such as deeper-than-expected reorgs, RPC inconsistencies, interruptions during replay, and failures while updating stored data.
Reorg handling should be testable and observable, with clear behavior when recovery exceeds the system's configured assumptions.
The critical question is not simply whether an indexer supports reorg handling. It's whether its recovery mechanisms can restore data correctness without introducing new inconsistencies.
Why the API layer matters just as much as the indexer
Even a reorg-safe indexer does not guarantee that every API response will reflect the same blockchain state.
Consider a DeFi dashboard retrieving information through several requests:
One API request returns the user's token balance. Another returns recent transfers. A third retrieves the user's liquidity positions.
If these requests are evaluated against different indexed block heights—or one response comes from an outdated cache—the application may display values that don't reconcile.
This can happen even without a reorg. Reorganizations make the problem harder because the meaning of a recent block height can change.
For applications that need consistent snapshots, the API should ideally make it possible to identify the blockchain state associated with a response.
Useful metadata can include the indexed block number, block hash, chain identity, indexing progress, and the finality status of the underlying data when available.
Graph-compatible subgraphs, for example, expose indexing metadata through the _meta field, including the latest indexed block number and hash. Supported GraphQL implementations also allow historical queries at specified blocks.
See The Graph's GraphQL API documentation.
Applications can use these capabilities to coordinate reads against a consistent block snapshot, subject to the provider's support and the possibility that a non-finalized block becomes non-canonical.
This distinction also matters for caching.
A conventional API cache might invalidate data after a fixed time interval. Blockchain applications may need additional invalidation based on reorgs, indexed block changes, or finality transitions.
A cached response that was correct when generated can remain incorrect long after the underlying indexer has repaired its state.
Data consistency must extend beyond the indexing database to the interfaces through which applications consume that data.
How applications should handle data that can change
Applications need to distinguish between observing an event and treating that event as final.
For example, a payment application could maintain three stages for an incoming transfer:
Observed → Safe → Finalized
When the transfer first appears, the application can display it as detected or pending.
Once it reaches the required safety threshold, the application can update its status.
Only after the application's settlement policy is satisfied should it perform actions that depend on the payment being sufficiently irreversible.
If the event is removed before reaching the required threshold, the application must be able to retract the provisional state.
The exact stages and thresholds depend on the blockchain and the application's risk tolerance.
For event-driven systems, this also means treating retractions as first-class events. A webhook or stream that only announces new transactions is insufficient when downstream consumers need to correct previously processed state.
Applications should also support idempotent event processing and reconciliation after service interruptions. Replayed events must not accidentally trigger the same credit or notification multiple times, and missed reorg notifications must not leave records permanently incorrect.
For high-stakes workflows, querying authoritative on-chain state at an appropriate block can provide an additional check before executing irreversible off-chain actions.
These protections are particularly relevant for automated systems, where decisions can happen faster than a human operator could detect a discrepancy.
What to look for in a blockchain data API or indexing provider
When evaluating blockchain data infrastructure, query latency and indexing speed are only part of the picture.
A provider may deliver extremely fast responses while still exposing applications to inconsistent or unreconciled data.
Developers should also understand how the system handles chain reorganizations.
Does it track canonical block hashes and detect when previously processed blocks are replaced? Can it revert all affected entities and aggregates before rebuilding state? Does the API expose indexing progress or block metadata so applications know what they're querying?
For event streams, can consumers receive removal notifications and recover missed events? And if an unusual reorg exceeds the supported recovery depth, will the system alert operators rather than silently serve incorrect data?
These considerations become more important as applications scale across networks with different block times, throughput characteristics, and finality models.
A well-designed indexing layer should make these complexities manageable without forcing each application team to implement its own blockchain reconciliation infrastructure.
But application developers still need to decide how provisional data is presented and when it is safe to act on it.
Conclusion: Reliable blockchain data must remain correct as the chain changes
Blockchain indexing is often discussed in terms of speed: how quickly events are processed, how close data stays to the chain head, and how fast APIs return results.
Those metrics matter, but they don't tell the whole story.
Unlike conventional application databases, recent blockchain history can change. A transaction that was valid when indexed may disappear, be re-included in a different block, or produce different downstream state.
A reliable blockchain data layer must not only process new information. It must also recognize when previously processed information is no longer valid and correct the resulting state.
For applications, the responsibility extends further. They must understand the finality of the data they consume, maintain consistent reads, and avoid treating provisional events as irreversible facts.
As Web3 applications become more real-time, automated, and financially consequential, the ability to correct data is as important as the ability to deliver it quickly.
The goal isn't simply an API that returns the latest blockchain data.
It's an API that applications can continue to trust when the blockchain changes.
About Ormi
Ormi is the next-generation data layer for Web3, purpose-built for real-time, high-throughput applications like DeFi, gaming, wallets, and on-chain infrastructure. Its hybrid architecture ensures sub-30ms latency and up to 4,000 RPS for live subgraph indexing.
With 99.9% uptime and deployments across ecosystems representing $50B+ in TVL and $100B+ in annual transaction volume, Ormi is trusted to power the most demanding production environments without throttling or delay.