Chain Reorg Handling

On-Chain Reorganizations as a Settlement Risk

On-chain settlement depends on the assumption that confirmed transactions represent final state. In distributed ledger networks, this assumption can be temporarily violated by chain reorganizations, where blocks previously considered canonical are replaced by an alternative chain. This page defines how settlement logic treats reorgs as a first-class risk rather than an exceptional failure.

Separation Between Chain State and Settlement State

The settlement system does not equate immediate on-chain inclusion with economic finality. Chain state is observed as an input signal, while settlement state is derived through deterministic rules that require stability criteria to be met. This separation prevents transient chain events from directly mutating internal settlement records.

Confirmation Depth and Stability Thresholds

Each supported network defines a confirmation depth threshold that must be satisfied before an on-chain event is considered stable. Settlement logic only advances from pending to settled once this threshold is reached. Reorgs occurring before threshold satisfaction result in no settlement mutation.

Handling Reorgs After Initial Observation

If a reorganization invalidates a transaction that was previously observed but not yet finalized, the corresponding settlement entry remains in a pending or provisional state. No irreversible ledger writes occur until stability criteria are satisfied, ensuring that reorgs do not require retroactive correction of settled records.

Reorgs After Settlement Finalization

In the rare case that a reorg invalidates a transaction after it has crossed the stability threshold, the system treats this as an exception event. The original settlement record is preserved, and a compensating adjustment entry is introduced to restore invariant consistency. Historical records are never deleted or overwritten.

Deterministic Exception Modeling

All reorg-related corrections follow deterministic exception handling rules. The system records the cause, affected transaction identifiers, and reconciliation impact as explicit ledger entries. This ensures that reorg handling is auditable, replayable, and distinguishable from normal settlement flow.

Implications for Replay and Verification

Because reorg handling is encoded as explicit state transitions rather than implicit rewrites, independent systems can replay the full settlement history and arrive at the same final balances. Chain reorganizations become observable inputs, not hidden mutations, preserving reproducibility.

Defined Non-Goals

This model does not attempt to prevent or predict chain reorganizations. It does not assert guarantees about network behavior. Its sole purpose is to ensure that settlement correctness and auditability are preserved regardless of underlying chain instability.

Scope and Dependencies

This page is a derivative specification within GMG Engine. It does not define or redefine core primitives such as settlement, determinism, finality, proof, or exception handling. All authoritative definitions are inherited from the locked GMG Engine core primitives.

Related Core Primitives

This page depends on the authoritative definitions established in: Deterministic Outcomes, Settlement Ledger Format, Settlement Finality, Transaction Proof.