Handling Re-Orgs with Notifications

Blockchain re-organizations (reorgs) are rare but possible events that occur when the network’s consensus shifts, resulting in a reordering or replacement of previously confirmed blocks. To manage reorgs effectively, our notification system employs a multi-layered approach that ensures the accuracy and timeliness of the data provided to our users.

📘

Find more about Reogs and Block Finality in this article.

Reorg Detection and Notification Process

The Tatum Notification system is designed to stay closely aligned with the tip of the blockchain. This allows us to provide near real-time updates on the latest transactions and blocks.

However, on occasions when a reorg happens on blocks that have already been processed, a secondary mechanism is triggered. This mechanism operates at a predefined interval—X blocks behind the chain tip, depending on the specific blockchain. It identifies and handles any transactions that may have been altered due to the reorg. Once detected, these transactions are processed again, and updated notifications are sent out with a special reorg flag to indicate that a reorganization has happened.

Example - Updated Notification delivered after Re Org

{
  "address": "0xfAF0F447715dEeDF6Dd79c2fd1F7966F0CC647A1",
  "amount": "0.001",
  "asset": "ETH",
  "blockNumber": 3553692,
  "counterAddress": "0xF64E82131BE01618487Da5142fc9d289cbb60E9d",
  "txId": "0xde48b2572176eb3e1c4a2a9abe62c5552f778afcbba1ded8491a2ceb675a6390",
  "type": "native",
  "chain": "ethereum-mainnet",
  "subscriptionType": "ADDRESS_EVENT",
  "reorg": true,
}

Good to Know

Notifications affected by a reorg may arrive with a slight delay, which can be up to several minutes depending on the blockchain in question. This delay occurs because the system waits for a sufficient number of mined blocks (10-20 blocks) to ensure that the reorg is resolved before sending out updated notifications.