Data flow
Where every number comes from, which hop can be stale, and what a consumer should record with each answer.
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/data-flow - 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
此内容尚不支持你的语言。
Where every Atomicals answer comes from
Universe-operated Bitcoin Core produces blocks. Atomicals ElectrumX reads them and applies the protocol rules, which is where protocol interpretation happens. A Universe index scans that provider and publishes an immutable generation as a materialised read model. Products read the index through a public API. Each hop can be behind the one before it, so every answer carries the generation identifier and indexed height it was computed at. No third-party blockchain data provider sits in any production path.
The hops
Section titled “The hops”- Bitcoin Core produces blocks. Universe operates the node.
- Atomicals ElectrumX reads blocks and applies the protocol rules. This is where protocol interpretation happens.
- A Universe index scans the provider, builds a materialised read model, and publishes it as an immutable generation.
- A product reads the index through a public API.
Each hop can be behind the one before it. A consumer must know which position each answer came from.
What can be stale, per hop
Section titled “What can be stale, per hop”| Hop | Can be stale because |
|---|---|
| Bitcoin Core | Normal block propagation |
| ElectrumX | Still processing a block, or a reorg |
| Index | Scan in progress, or generation build in progress |
| Product cache | Cached an answer without its generation |
The last row is the one under your control, and the one most often responsible for a wrong screen.
What the ARC-20 side guarantees
Section titled “What the ARC-20 side guarantees”The scan is all or nothing. Holder rows are aggregated by address and must sum exactly to circulating supply. A mismatch, a null address, a truncated page sequence, a changing declared total, or a changing chain tip aborts the entire poll. No partial authoritative snapshot is ever committed.
That is why an answer is either complete or absent, rather than plausible and wrong.
What the NFT and Realm side guarantees
Section titled “What the NFT and Realm side guarantees”NFT, Realm, and Subrealm rows share one provider scan, one generation, one checkpoint, and one active pointer. Publication requires exact final declared source-row coverage and rejects a count shrink or an incomplete page.
A generation that spans more than one provider tip is published explicitly as mixed and stale, without a single indexed height, rather than pretending to be consistent.
What to record with every answer
Section titled “What to record with every answer”| Field | Why |
|---|---|
| Generation identifier | So you can detect a rebuild |
| Indexed height | So you know the chain position |
| Source revision | So a behavior difference is explainable |
| Request identifier | So a support question is traceable |
| Stale and mixed-tip flags | So you know whether to act on it |
Storing an Atomicals result without those five makes any later disagreement unexplainable.