Chain Reorganizations

A chain reorganization, or reorg, happens when the node you are reading from replaces a block it previously reported as the tip with a different block at the same height, so a transaction that appeared confirmed is rewound and may land in a different block — or not at all. On the Avalanche C-Chain this is uncommon and shallow: Snowman consensus finalizes blocks within roughly one to two seconds, so once a block is accepted it is effectively permanent, and reorgs are confined to the brief, unfinalized moment right at the tip. Even so, an application that reads the very latest block before finality can observe one, and if it credits a balance or ships a product off an orphaned block it ends up with state that no longer matches the canonical C-Chain. That is why even on a fast-finality chain you must detect reorgs and reconcile state rather than assume the tip never changes.

Understanding Reorgs

• Causes: a reorg arises when nodes briefly disagree about the tip — typically from propagation latency around a freshly produced block before Snowman consensus converges. The protocol resolves the disagreement by finalizing one block, and any competing block at that height becomes orphaned. Because finality is reached in ~1-2s, the window for disagreement is tiny.
• Shallow vs. deep: reorgs come in shallow (one or a few blocks at the tip) and deep (many blocks) varieties. On the C-Chain, fast finality means only shallow reorgs at the unfinalized tip are realistic; deep reorgs of finalized blocks essentially do not occur.
• Effect on transactions: a pending transaction is unaffected in identity — it simply waits to be re-included. A transaction in a block that gets orphaned is rewound to pending and usually re-mined into a later block, but its block number, position, and any dependent receipts change, so anything you computed from the old block must be recomputed.
• Detection signals: at the JSON-RPC level, watch for a new header whose parentHash does not match the hash you recorded for the previous height, or a block hash at a known height that differs from what you stored. A newBlockHeaders subscription or polling eth_getBlockByNumber both surface these mismatches.

Implementation Examples

1// Monitor for reorgs
2const monitorReorgs = async (callback, checkInterval = 5000) => {
3  let lastBlock = await web3.eth.getBlockNumber();
4  let lastBlockHash = (await web3.eth.getBlock(lastBlock)).hash;
5 
6  return setInterval(async () => {
7    const currentBlock = await web3.eth.getBlockNumber();
8    const currentBlockHash = (await web3.eth.getBlock(lastBlock)).hash;
9 
10    if (currentBlockHash !== lastBlockHash) {
11      // Reorg detected
12      callback({
13        oldBlock: lastBlock,
14        oldHash: lastBlockHash,
15        newBlock: currentBlock,
16        newHash: currentBlockHash,
17      });
18    }
19 
20    lastBlock = currentBlock;
21    lastBlockHash = currentBlockHash;
22  }, checkInterval);
23};
24 
25// Get common ancestor block
26const findCommonAncestor = async (hash1, hash2) => {
27  let block1 = await web3.eth.getBlock(hash1);
28  let block2 = await web3.eth.getBlock(hash2);
29 
30  while (block1.number > block2.number) {
31    block1 = await web3.eth.getBlock(block1.parentHash);
32  }
33  while (block2.number > block1.number) {
34    block2 = await web3.eth.getBlock(block2.parentHash);
35  }
36  while (block1.hash !== block2.hash) {
37    block1 = await web3.eth.getBlock(block1.parentHash);
38    block2 = await web3.eth.getBlock(block2.parentHash);
39  }
40  return block1;
41};

Mitigation Strategies

• Confirmations before final: thanks to Snowman finality you need only a small margin on the C-Chain. Wait until a transaction's block sits a few heights below the tip — comfortably past the unfinalized window — before treating it as final, and widen that margin for high-value settlement.
• Implementing detection: in a polling system, store the hash of each height you process and, on each tick, refetch and compare — a changed hash signals a reorg. In a subscription system, compare each incoming header's parentHash to your last recorded hash. Either way, keep a short ring buffer of recent height-to-hash mappings so you can locate where the chains diverged.
• Resubmission without double-spending: when a transaction is orphaned, it is usually re-included automatically, so do not blindly rebroadcast. Track transactions by hash and make all downstream effects idempotent and keyed by block hash, so re-inclusion at a new height never triggers a duplicate credit or shipment.
• Restoring consistency: on detecting a reorg, walk back to the common ancestor of the old and new branches, roll back every state change derived from the orphaned blocks, then replay forward along the new canonical C-Chain. Keying state by block hash makes this rollback clean.
• Listeners vs. polling: prefer newBlockHeaders subscriptions for low-latency detection that rides Avalanche's ~1-2s cadence; fall back to polling eth_getBlockByNumber when a subscription is unavailable or for a periodic reconciliation sweep that catches anything a dropped subscription missed.

See also

• eth_getBlockByHash - Retrieve block by hash
• Block Confirmations Guide - Understanding transaction finality
• Working with Blocks - General block handling