Chain Reorganizations

A chain reorganization is when Polygon discards a block (or a short run of blocks) it had at the tip and replaces it with a different one, so a block your application already saw is no longer part of the canonical chain. On Polygon PoS this happens because Bor validators occasionally produce competing blocks at the same height and, with ~2-second blocks propagating across a global validator set, nodes can briefly disagree on the head before converging. Reorgs here are shallow — usually a block or two deep — and routine rather than alarming, but they are real until a Heimdall checkpoint anchors the chain to Ethereum L1. If your code treats the latest block as permanent, a reorg silently corrupts state: a credited deposit gets undone, an event you reacted to never happened, balances disagree with PolygonScan. That is why any service reading chain 137 from https://polygon.therpc.io/YOUR_API_KEY must detect reorgs and recover from them.

Understanding Reorgs

• Causes on Polygon: Reorgs arise when two Bor validators propose blocks at the same height and the network temporarily forks. Propagation latency across a globally distributed validator set, plus the fast ~2s block interval, means nodes can briefly follow different tips before consensus selects one canonical chain and orphans the other.
• Shallow vs. deep: A shallow reorg replaces just the last block or two and is the normal case on Polygon. Deep reorgs (many blocks) are extremely rare and, once a height is sealed by a Heimdall checkpoint to Ethereum L1, it is effectively final and not reorganizable — so the practical risk window on chain 137 is the small handful of unconfirmed blocks at the tip.
• Effect on transactions: Pending transactions are unaffected in identity — they simply wait to be re-included on the new canonical chain. The danger is a recently confirmed transaction in an orphaned block: it may be re-mined into a different block (new block number, same hash) or, if it conflicts, dropped entirely. Anything you did in response to its first confirmation must be reconsidered.
• JSON-RPC detection signals: At the RPC level you detect a reorg by tracking block hashes, not just numbers. If the block now at a height you already saw has a different hash, or if a new header's parentHash does not match the hash of the block you recorded as its parent, the chain reorganized — exactly what the monitorReorgs example watches for.

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: Wait past the shallow reorg window before treating a transaction as settled — a handful of confirmations for low-value MATIC actions, tens of blocks for larger amounts, and a Heimdall checkpoint to Ethereum L1 for high-value settlement, after which the block is no longer reorganizable.
• Detection in either model: In a polling system, record each block's hash and compare on every tick (the monitorReorgs example) so a changed hash at a known height flags a reorg. In a subscription system, verify each newBlockHeaders event's parentHash against your last recorded hash and trigger recovery on a mismatch. Either way, key your bookkeeping on hash, not number.
• Safe resubmission: When a confirmed transaction is orphaned, first re-check its receipt — it is often simply re-mined on the new chain. Only resubmit if it is genuinely absent, and reuse the same nonce so the network treats it as one transaction; never broadcast a fresh nonce, which can land both and double-spend. Dedupe every downstream effect by transaction hash so a re-mine does not double-apply.
• Restore consistency: On detecting a reorg, use findCommonAncestor to locate where the chains diverge, roll back all state derived from the orphaned blocks above that ancestor, then re-process the canonical blocks forward. Because Polygon reorgs are shallow, this rollback typically spans only a block or two.
• Listeners vs. polling: Prefer WebSocket header subscriptions for low-latency reorg detection — you see a bad parentHash the instant the new head arrives within Polygon's ~2s window. Fall back to polling when you need a simpler, connection-resilient setup or when a subscription is unavailable; combine both for defense in depth on chain 137.

See also

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