Reorg Handling

This page explains how Citrea handles blockchain reorganizations at both layers: Bitcoin (L1) reorgs that could affect the data Citrea reads from Bitcoin, and potential L2 reorgs that a malicious sequencer might attempt. Understanding these mechanisms is essential for grasping Citrea's security model and how Bitcoin finality anchors the rollup state.

L1 - Bitcoin Reorg Handling

Citrea currently has 4 types of nodes, sequencer, batch prover, full node, and light client prover. All of these nodes scan every Bitcoin block starting from a pre-configured block number up to a block with at least n number of confirmations, which is called the finality depth.

Finality Depth

Finality depth (also called confirmation depth) is the number of blocks that must be built on top of a transaction's block before it's considered secure enough to be irreversible. In Bitcoin, finality is probabilistic rather than deterministic - the more confirmations a block has, the exponentially harder it becomes to reverse.

How Bitcoin Confirmations Work

When a transaction is included in a block, that block counts as confirmation 1. Each subsequent block adds another confirmation. The deeper a block is buried, the more computational work required to reorganize the chain.

Bitcoin Finality

A transaction in block 896 has 5 confirmations because the block containing the transaction counts as 1, plus 4 additional blocks have been built on top of it (897 through 900).

Why Finality Depth Matters for Citrea

A blockchain reorganization (reorg) occurs when a competing chain becomes longer than the current chain, causing nodes to switch to the new chain:

Bitcoin Fork

If Citrea had processed block 896 immediately, it would have seen TX A. But after the reorg, TX A might not exist in the canonical chain at that position, causing state inconsistencies.

Citrea only processes finalized blocks that have sufficient confirmations, making it robust against L1 reorgs:

This means that no Bitcoin block will be recorded in Bitcoin Light Client Contract unless it is finalized.

Safe Processing with Finality Depth = 6

Standard Confirmation Depths in Bitcoin

• 1 confirmation: Small transactions, low value

• 3 confirmations: Medium security (used by many exchanges for deposits)

• 6 confirmations: Standard high security

• 100 confirmations: Coinbase maturity requirement (newly mined Bitcoin)

Probability of 6-block reorg: ~0.000001%

Citrea Finality Depth Configuration

Citrea's finality depth is configurable and varies based on the underlying Bitcoin network:

• Mainnet: 6 confirmations

• Testnet4: 100 confirmations

Note on Testnet4 Configuration: Bitcoin's testnet4 exhibits significantly higher volatility in terms of blockchain reorganizations compared to mainnet. During early Citrea Testnet operation, the finality depth was initially set to 8 blocks. However, a 12-block reorganization occurred, prompting an increase to 30 blocks. Subsequently, a 30-block reorganization was observed, leading to the current configuration of 100 confirmations for testnet4. This behavior is related to Testnet4's 20-minute Exception Rule, which allows for reduced difficulty under specific conditions.

Handling Deep Reorganizations

While deep reorganizations beyond the finality depth are extremely rare, they can still occur and have occurred in the past on Testnet4.

Manual Process: Handling deep reorganizations is not automated. When a deep reorg is detected, the Citrea team coordinates the recovery process and provides specific instructions to node operators.

When a deep reorganization occurs, the recovery process works as follows:

1. Detection: The Citrea team detects that a reorganization has exceeded the configured finality depth

2. Communication: The team announces the incident and provides rollback instructions to all node operators via official channels

3. Manual Rollback: Node operators execute the provided rollback commands to restore their node's state to the last consistent checkpoint before the affected blocks

4. Reprocessing: After rollback, nodes reprocess blocks from the canonical Bitcoin chain

For example, if a 7-block reorganization occurred on Bitcoin mainnet (where Citrea uses 6-block finality depth), the Citrea team would detect the issue, publish rollback commands, and coordinate with independent full node operators to execute the recovery. This manual coordination ensures network-wide consistency and maintains the integrity of the rollup state relative to Bitcoin's canonical chain.

L2 - Native Reorg Handling

Centralized Sequencer Architecture

Citrea's centralized sequencer is the sole authority for transaction ordering and block production, which means L2 reorganizations are impossible under normal operation—though this relies on the sequencer operating honestly.

While this centralization provides strong ordering guarantees, Citrea implements multiple security mechanisms to protect users even if this trust assumption fails.

Security Against Malicious Sequencer

Citrea's architecture ensures that even a compromised sequencer cannot force full nodes to accept invalid state transitions through two complementary verification mechanisms.

Invalid L2 State Transitions

Full nodes execute every transaction in every L2 block, protecting themselves from invalid state transitions.

Sequencer Commitment Verification

Full nodes independently verify sequencer commitments published to Bitcoin. Each commitment contains:

• Merkle root of all L2 block hashes in the batch

• Sequential index (no gaps allowed)

• L2 end block number

Full nodes verify commitments by:

1. Ensuring indices are strictly sequential (detects hidden blocks)

2. Calculating the Merkle root from received blocks and comparing it with the published commitment (detects block tampering or history rewriting)

3. Verifying deterministic block ranges where each commitment's start block = previous commitment's end block + 1 (prevents skipped blocks)

This prevents the sequencer from building a different chain than what it broadcasts to full nodes, rewriting history, or publishing different block histories to different parties.

Batch Proof Validation

Batch proofs are Groth16 zero-knowledge proofs that cryptographically verify state transition correctness. The batch proof circuit validates:

• Block signatures using the sequencer's public key

• Chain continuity via prev_hash verification between consecutive blocks

• State transitions by applying all L2 blocks through the State Transition Function (STF) and verifying state roots match

• Storage integrity using Jellyfish Merkle Tree (JMT) proofs for all storage accesses

• Commitment consistency by recalculating Merkle roots and verifying they match published commitments

• L1 anchoring by committing to the last Bitcoin hash in the Bitcoin Light Client contract, preventing the L2 from claiming validity on a forked Bitcoin chain

Key constraint: The circuit's mathematical constraints make it impossible to generate a valid proof for invalid state transitions (e.g., unauthorized token mints, invalid transfers). If a malicious sequencer publishes invalid blocks, batch proof generation will also fail.

Full nodes extract batch proofs from Bitcoin, verify their cryptographic validity, and confirm outputs match their local state. Mismatches result in proof rejection.

Security Against Malicious Batch Prover

The batch prover generates ZK proofs but has limited ability to cause harm due to the circuit's deterministic constraints.

Cannot attack state validity:

• Cannot prove invalid state transitions (mathematically impossible due to circuit constraints)

• Cannot modify block data (Merkle root verification will fail)

• Cannot skip commitments (sequential processing enforced)

Connecting The Dots

The security model ties back to L1 finalization: just as Citrea waits for Bitcoin blocks to reach finality depth before processing them, full nodes only treat sequencer commitments and batch proofs as canonical after they're finalized on Bitcoin (6 confirmations on mainnet).

This creates an immutable reference point. Once a commitment is finalized on Bitcoin, it cannot be reversed—meaning a malicious sequencer cannot "undo" what it published or convince full nodes to switch to a different chain. If the sequencer builds a private chain and tries to reorg full nodes later, the attack fails because the original commitment is already permanently recorded on Bitcoin, and full nodes will reject any blocks that don't match it.

The same principle applies to the light client prover: it only transitions the L2 state based on sequencer commitments and batch proofs that are finalized on Bitcoin. Each proof verifies against the previous light client proof's outputs, creating an unbroken chain of verified state from genesis.

Clementine enforces the same finality requirements. Even if someone generates a light client proof based on a 1-confirmation Bitcoin block, they cannot use it in Clementine's challenge-response game. The bridge verifies that the Bitcoin chain referenced in the proof has sufficient confirmations, a proof anchored to non-finalized Bitcoin data will be rejected. This prevents attackers from exploiting shallow forks to manipulate bridge operations.

In short: Bitcoin finality anchors Citrea's state. The sequencer, batch prover, and bridge participants can misbehave in real-time, but they cannot rewrite history that's already finalized on Bitcoin.