Guides
SupportStatusSign UpLogin

Handling Blockchain Re-Orgs with Notifications

Suggest Edits

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.

Reorg Detection and Notification Process

The Tatum Notification system closely aligns with the blockchain tip, providing near real-time transaction and block updates. In the event of a reorg affecting already processed blocks, Tatum employs a secondary mechanism triggered at a set interval, a few blocks behind the current tip - to identify altered transactions. These transactions are reprocessed, and updated notifications are sent with a specific reorg: true flag indicating the reorganization.

Example - Updated Notification delivered after a Reorg:

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

How Tatum Handles Reorgs

Tatum provides notifications to help developers stay informed about blockchain reorgs and how they affect transactions. These notifications depend on the type of transaction:

  • Incoming Transactions to a Subscribed Address:
    • If an incoming transaction fails, no notification is sent—neither before nor after the reorg.
  • Outgoing Transactions from a Subscribed Address:
    • A fee notification is sent in both cases: before the reorg (without the reorg: true flag) and after the reorg (with the reorg: true flag).
    • A transfer notification is not sent if the transfer fails due to the reorg, as the transaction never took place.

Common Scenarios and Expected Behaviour

Scenario_1: Native Transaction Fails due to Insufficient Gas after Reorg

  • If the first outgoing transaction (from x to z) fails due to insufficient gas after the reorg, no reorg notification is sent since the transaction never succeeded post-reorg.
  • Subsequent outgoing token transaction (from z to y) also fails (no gas); similarly, no reorg notification is sent.

Scenario_2: Native Transaction Succeeds, but Token Transaction Fails after Reorg

  • Successful native transaction (from x to z) will trigger a reorg notification (reorg: true).
  • Failed token transaction (from z to y) due to gas price changes will not trigger a reorg notification, as the transaction never completed successfully.

Scenario_3: Token Transaction Block Experiences Reorg Independently

  • If only the second (token) transaction block (from z to y) experiences a reorg and the transaction fails due to gas price changes, no reorg notification is sent, as the transaction ultimately fails.

Recommended Action

If a transaction fails without a reorg notification, manually verify transaction status through blockchain explorers or transaction status queries. Maintaining sufficient balances on sender addresses for gas can mitigate the risk of transaction failures due to reorgs.

Common Scenarios and Expected Behavior

  1. Native token transfers failing due to insufficient gas:
    • No incoming transaction notifications sent.
  2. Token transaction failing post-reorg due to gas price fluctuations:
    • Fee notification is sent, but no transfer notification.
  3. Receipt of transaction details with reorg: true:
    • Transaction details such as transaction hash and new block number are provided.
  4. Separate failure notifications alongside reorg notifications:
    • Incoming transactions: No notifications if failed.
    • Outgoing transactions: Only fee notifications sent, no transfer notifications.
  5. Manual transaction status verification post-reorg:
    • Recommended to manually confirm status after reorg notification if uncertainty remains.
  6. Consistency across supported blockchains:
    • Behavior is consistent across all supported EVM and non-EVM chains (Ethereum, BSC, Polygon, Tron, XRP, etc.).

Important Information

Notifications impacted by reorgs may have slight delays (up to several minutes) depending on the blockchain, due to waiting for confirmation of stable blockchain state (typically 10-20 blocks).

Additional Resources

Updated 7 days ago