Handling Chain Reorganizations in Apps

Blockchains are often described as permanent records, and for older blocks that description holds. The newest blocks are different. Occasionally a network replaces one or more recent blocks with an alternative version. This is called a chain reorganization, or reorg. Apps that act instantly on the latest block can end up recording events that no longer exist.

Why reorgs happen

Reorgs happen when the network briefly disagrees about the latest block. Two valid blocks may be produced at similar times, and different nodes see different ones first. The network soon converges on one version, and transactions in the discarded block return to the pool or appear in a later block.

How often and how deep reorgs occur depends on the network's consensus design. Some networks rarely see reorgs beyond a block or two. Others have seen deeper reorganizations in the past. Layer 2 networks have their own ordering and finality characteristics, which also differ.

What goes wrong in apps

Without reorg handling, apps can:

• Mark a payment as received when the transaction later disappears
• Credit a deposit twice if a transaction appears in two different blocks
• Show NFT ownership that reverts
• Trigger emails, webhooks or fulfilment for events that never finalised

For small digital goods, the risk is modest. For exchanges, bridges and high-value payments, it is serious.

Confirmations

The simplest defence is waiting for confirmations. A transaction with N confirmations has N blocks built on top of it. Each additional block makes replacement less likely.

Use case	Typical approach
Low-value digital goods on a layer 2	A few blocks
Moderate-value payments	More blocks, or wait for the network's finality signal
High-value deposits	Wait for finality, often tens of blocks or more
Bridge withdrawals	Follow the bridge's own finality rules

Many networks expose "safe" or "finalized" block tags through JSON-RPC. Using those tags can be clearer than counting blocks yourself.

Idempotent processing

Design processing so that handling the same event twice has no extra effect:

1. Identify events by transaction hash and log index
2. Store that identifier with a unique constraint
3. Check the identifier before acting
4. Make fulfilment steps safe to repeat

If a transaction moves to a different block after a reorg, its hash usually stays the same, so a hash-based identifier prevents double crediting.

Handling removed logs

Log subscriptions and some queries mark logs as removed when a reorg discards them. Treat removed logs as a signal to undo pending work. When scanning with confirmations, you rarely see removed logs, which is another reason to scan up to a safe block rather than the latest one.

Rolling back

For apps that must react quickly, such as games or trading interfaces, show recent events as pending and confirm them later. If a reorg removes an event, roll back the pending state and tell the user. Keep a clear separation between provisional and final data in your database.

Monitoring

Track reorg occurrences on the networks you support. Log when a previously seen block hash changes at a given height. Occasional short reorgs are normal. Frequent or deep ones are a reason to increase confirmations.

Choosing sensible defaults

For most web apps and small payment systems, a modest confirmation count per network, idempotent processing and a unique payment reference provide strong protection with little complexity. Proud Globe uses per-network confirmation counts and unique payment references for every tile payment, so a pin only goes live once the payment is safely buried under new blocks.