Handling Blockchain Reorganisations in Data Apps
Detect changed block ancestry, invalidate displaced evidence and rebuild affected derived records without silently retaining non-canonical wallet activity.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
A reorganisation changes which blocks belong to the accepted chain. Applications that store only block numbers can miss the change and retain records from displaced history.
Track ancestry as well as height
Record block hash and parent hash for the monitored range. A new head that does not connect to the expected ancestor requires reconciliation with a common accepted ancestor. Choose a retained overlap appropriate to the network and workflow. A depth policy reduces operational risk but does not replace explicit identity checks.
Worked example: replacing the last two blocks
The application has blocks A, B and C. A new accepted branch continues from A through D and E. Mark evidence from B and C displaced, then process D and E. Derived balances, candles or payment states linked to displaced events must be recalculated or invalidated consistently.
Make reversal part of the design
Use durable links from raw events to derived outputs. Test a repeated rollback notification and a restart during repair. Do not delete the audit trail of the displaced observation if reproducibility matters. Separate provisional user-facing activity from irreversible fulfilment, and pause dependent actions when the required accepted-chain evidence cannot be established.
A practical acceptance test
Persist branch A–B–C, then supply A–D–E as accepted history. Verify invalidation of B and C and repair of every dependent summary. Crash during repair and resume using the recorded state. Repeating the rollback should be safe and should not subtract the same movements twice or destroy the displaced observation trail.
Questions about the topic
Frequently asked questions
Can block height alone detect a replacement?
No. Compare block identities and ancestry.
Should derived records survive a displaced source event unchanged?
No. Their validity depends on the evidence they used.
Standards & technical documentation