Consistency and reorgs
Generations, checkpoints, invalidation, and rollback, and what a consumer must do about each.
Universe implementation Verified 2026-08-31
Describes what a Bitcoin Universe service actually does today. It is not a statement about the protocol in general.
- Page ID
-
develop/consistency-and-reorgs - Normative authority
- Universe implementation documentation
- Networks
- mainnet
- Documentation version
- 2026.08
- Audience
- developer, operator
- Owner
- bitcoin-universe-docs
- Sources
-
- Universe Atomicals NFT, Realm, and Subrealm index
at
1d9109c68d95private repository - Universe ARC-20 index and Marketplace v1 authority
at
670030e50071private repository
- Universe Atomicals NFT, Realm, and Subrealm index
at
Este conteúdo não está disponível em sua língua ainda.
Generations
Section titled “Generations”A generation is an immutable snapshot of an index at one consistent chain position. Answers are served from the active generation, and the identifier is returned with every response.
Why immutability matters: a consumer that recorded a generation identifier can tell the difference between “the data changed” and “I am looking at a different snapshot”.
Checkpoints
Section titled “Checkpoints”A checkpoint records the chain position a generation was built from, including block hashes. When the chain moves under the index, the checkpoint is what makes a correct rebuild possible.
Reorg handling
Section titled “Reorg handling”The ARC-20 side rescans each changed tip under identical before and after Bitcoin and Atomicals tips. Missing unfinalised events produce explicit invalidations. Changes to finalised blocks, events, or ticker identity fail closed rather than being silently accepted. Historical headers outside the configured reorg window are reused from a durable journal.
The NFT and Realm side publishes a complete generation only when the declared source-row coverage is exact, and rejects a count shrink or an incomplete page. A generation spanning more than one provider tip is published explicitly as mixed and stale.
Rollback
Section titled “Rollback”An operator can roll the active pointer back to an earlier generation. That is an operational action, not a consumer action, and it changes which snapshot readers see.
A consumer detects it by the generation identifier changing to one it has seen before.
What a consumer must do
Section titled “What a consumer must do”- Read the generation identifier and indexed height with every answer.
- Store both alongside any cached result.
- Treat a generation change as a signal to re-read, not as noise.
- Never merge results from two different generations into one view.
- Do not act on a result computed inside the reorg window for a significant amount.
- Handle
staleandmixedTipexplicitly rather than rendering the numbers anyway.
Pagination across a reorg
Section titled “Pagination across a reorg”A cursor refers to a position inside a generation. When the generation changes, the cursor is no longer valid for the new one. Restart the listing rather than continuing with a stale cursor. See pagination and cursors.