Indexer semantics

I.1 The pipeline

A DUST-20 reader needs two authoritative inputs and six stages. The inputs are an inscription index, for inscription identity, content and location, and a Bitcoin node, for complete blocks with input values, output values and output addresses. Neither is sufficient alone.

1. 01 / OBSERVE

   Ingest raw chain events

   Read complete blocks with input values, output values and output addresses, plus authoritative inscription identity. Record the transaction, output, inscription association and block position before declaring anything about balances.

2. 02 / NORMALIZE

   Parse strictly and keep failures visible

   Apply the flat-string-object reader, exact key sets and strict integer parsing. Keep parse failures as recorded invalid events rather than dropping them into an unexplained empty result.

3. 03 / RESOLVE

   Resolve deployment and history

   Fold the ticker to its identity, apply first-deploy-wins, and check the mint against the resolved unit size, the per-mint cap and remaining supply. Do not guess when two candidates conflict.

4. 04 / MATERIALIZE

   Create allocation records with position

   An allocation is an outpoint, a ticker identity, an amount, a unit size and a satoshi offset inside that output. The offset is not optional bookkeeping, it is what makes the next spend computable.

5. 05 / PROPAGATE

   Follow satoshis through each spend

   Concatenate input values into one range and output values into another, intersect each allocation span with each output, keep only whole units, and record the difference as burned. Emit transfer effects only where the owning address actually changes.

6. 06 / RECONCILE

   Roll forward and roll back

   Track block association so a reorganization can invalidate newest first, reverse mutations, restore spent allocations, remove orphaned ones and replay the replacement branch. Preserve enough history to explain every transition.

I.2 The allocation record

The single most common implementation mistake is storing an amount per outpoint and nothing else. Without the satoshi offset, the next spend cannot be computed, and the reader silently diverges from every reader that stored it.

I.3 Confirmation and pending

DUST-20 defines no finality threshold. What it does define is that confirmed and pending are distinct states which must never be blurred together.

Confirmed

Carries block height, block hash, transaction index and event index. All four, or the event is not confirmed. Partial placement is rejected rather than filled in.

Pending

Carries none of those, and a confirmation count of zero. An event that has a height and calls itself pending is a bug in the reader, not an edge case.

Depth

The protocol sets no threshold. Publish your own finality depth, show confirmation counts to users, and never present unconfirmed state as settled.

Coverage

Every answer carries a coverage label of complete, partial or unavailable, plus a checkpoint of network, height, hash, finalized height and observation time. A consumer that ignores coverage cannot tell a quiet ticker from a stalled reader.

I.4 Reorganizations

A DUST-20 balance is only as final as the depth it was confirmed at. When the chain moves, a reader does not patch its state; it unwinds and replays.

1. Emit invalidations newest first, so a consumer applying them in order never sees an inconsistent intermediate state.
2. Reverse every ledger mutation the orphaned branch made, in the reverse of the order it made them.
3. Restore allocations the orphaned branch had marked spent, at their original outpoint, amount and offset.
4. Remove allocations the orphaned branch created. They never existed on the chain that survived.
5. Replay the replacement branch from the fork point, as if it had always been the chain.

Replace-by-fee deserves separate attention. A replacement transaction can have a different output layout, which moves the boundaries in the output range, which changes which whole units survive. A replacement can burn units the original would have preserved. Derive state from the transaction that actually confirmed, never from the one you broadcast, and never rebroadcast blindly.

I.5 Event contract

What a reader publishes, so that a downstream consumer can check the arithmetic instead of trusting it. These constraints are enforced on every accepted batch by the Bitcoin Universe production reader.

Two further constraints apply to every event. Each wallet delta must equal its own received minus sent, so a consumer can verify the arithmetic per address rather than only in aggregate. And an address may appear at most once per event: repeating it would let two rows disagree about the same balance change.

Checklist

The complete implementation checklist, including the reader, identity, allocation, publication and application requirements, is on the reference page.