Reorgs

Reorgs detects events invalidated by a chain reorganization (reorg) and helps you reverse what was recorded in your ledger. With the Webhook correction option (reorgCorrectionEnabled), you receive correction messages for invalidated messages. If you query directly, you can detect a reorg by comparing stored block hashes against the canonical chain.

When a reorg occurs, blocks you have already seen and the deposits and withdrawals in them become invalid. If you reflect only the state at query time, invalidated deposits remain in your ledger. Reorgs gives you a correction signal so you can keep the ledger accurate.

Use Cases

• Finance & AccountingReverse invalidated deposits

  If the block hash of a credited deposit differs from the canonical chain, deduct the deposit amount from the customer balance and check whether the deposit is re-included. This prevents an invalidated deposit from remaining in the balance and being withdrawn.

• Withdrawal OpsRecheck withdrawal results

  If a withdrawal marked as completed was in a block that became invalid, return it to pending and check whether it is re-included. This keeps withdrawal status consistent with the on-chain result.

• EngineeringHandle duplicate and correction messages

  Record a unique key (`subscriptionId` and `sequenceNumber`) and the `reorgRemoved` flag for each message. Apply a message you receive again only once, and treat a message with `reorgRemoved` set to true as a reversal. A correction message is sent with the same `sequenceNumber` as the original, so handling it with duplicate detection alone drops the correction.

Available APIs