Chain Reorganizations

A chain reorganization (reorg) is when the canonical history of OP Mainnet changes: blocks your application already saw are replaced by a different sequence, so a transaction once at the head can move to a new block or disappear entirely. On OP Mainnet (chain ID 10), the single sequencer produces blocks in a steady ~2s order, so day-to-day reorgs of confirmed blocks are uncommon compared to PoW chains — but the chain is an optimistic rollup that only becomes truly final once its batch is settled on Ethereum L1, so unfinalized blocks near the head are not guaranteed permanent and can be reorganized during sequencer or derivation hiccups. If your application commits state from those unfinalized blocks and a reorg follows, you end up with balances, indexes, or order books that reflect a history that no longer exists — which is exactly why every serious OP Mainnet integration must detect and handle reorgs rather than assume the head is immutable.

Understanding Reorgs

• Causes: on OP Mainnet, reorgs stem from the L2 head being revised before L1 settlement — sequencer restarts, unsafe-head changes during derivation from L1, or propagation lag between nodes — rather than from competing miners. Once a block's batch is finalized on Ethereum L1, that part of chain ID 10 history is settled.
• Shallow vs. deep: shallow reorgs (one or a few unfinalized blocks near the head) are the realistic case to plan for on OP Mainnet; deep reorgs of L1-finalized history do not occur under normal operation, which is why finalized depth is the safe boundary.
• Effect on transactions: a reorg can return a pending transaction to the mempool, move a recently included transaction to a different block (changing its block number and confirmation count), or drop it. Anything you computed from the orphaned block must be reconsidered.
• JSON-RPC detection signals: the core signal is a broken parent link — a new block whose parentHash does not match the hash you stored for the previous height, or the same block number suddenly reporting a different hash. Polling eth_getBlockByNumber/eth_getBlockByHash and comparing hashes, as the examples do, surfaces these breaks.

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

• Confirmation depth for finality: for routine actions wait several OP Mainnet blocks of depth; for high-value or irreversible state, wait until the block's batch is finalized on Ethereum L1 — L1 finality, not L2 block count, is the point past which a reorg cannot undo your transaction on chain ID 10.
• Detecting reorgs: in a polling system, store each height's hash and compare on every poll (as monitorReorgs does); in a subscription system, check that each new header's parentHash matches the last header you processed. Either way, a mismatch triggers the recovery path.
• Transaction resubmission: when a reorg drops a transaction, resubmit it with the same nonce so it cannot execute twice — if the original is later re-mined, the duplicate is rejected as a nonce conflict. Track transactions by hash and nonce so you never broadcast a true duplicate or double-spend.
• Restoring state consistency: on detection, find the common ancestor (the findCommonAncestor helper), roll back every state change derived from the orphaned blocks, then replay forward along the new canonical chain. Keying your storage by block hash makes this a clean replace.
• Listeners vs. polling: prefer a newBlockHeaders subscription for low-latency parent-hash checks on a ~2s-block chain; keep polling as a fallback for gap recovery after a dropped connection, since a subscription that silently stops would otherwise miss reorgs entirely.

See also

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