Skip to main content

​
Overview

A blockchain reorganization (re-org) occurs when a previously accepted block is replaced by another block at the same height. Re-orgs are a normal part of blockchain operation, especially on:
  • High-throughput chains
  • L2s
  • Testnets
Moralis Streams is designed to handle re-orgs safely and transparently.

​
How Streams Handles Re-orgs

When a re-org occurs:
  1. Streams detects the replaced block
  2. Events from the dropped block are invalidated
  3. Replacement block events are processed
  4. Confirmation logic is recalculated
You do not need to manually detect or resolve re-orgs.

​
Impact on Webhooks

Re-org handling is reflected through:
  • confirmed: false events that may not be finalized
  • confirmed: true events only sent after finality
If a transaction is removed due to a re-org:
  • It will not receive a confirmed webhook
  • Replacement transactions will be delivered instead
See also:

​
Why This Matters

Without re-org handling, applications risk:
  • Double-counting transactions
  • Incorrect balances
  • Invalid ownership state
Streams ensures:
  • Only finalized state is confirmed
  • Re-orgs do not corrupt downstream systems

​
Replays & Recovery

If your system was offline during a re-org:
  • You can replay affected blocks
  • You can replay failed webhooks
See also:

​
Best Practices

  • Treat confirmed: false as provisional
  • Persist only confirmed state
  • Make handlers idempotent
  • Use replays for recovery, not polling