Implementer's reference

Reference

Terminology, the semantics an indexer must reproduce, and the practical limits that shape real integrations.

1. Terminology

Atomical

Any digital object minted under this protocol: an NFT, a fungible token deploy, a realm, a container. Identified by its commit outpoint.

ARC-20

The fungible token model where one token unit occupies exactly one satoshi.

Envelope

The tapscript structure carrying the protocol marker atom, an operation code, and a CBOR payload.

Commit / reveal

The two-transaction mint pattern. The commit creates the outpoint that fixes identity; the reveal exposes the envelope in witness data.

Atomical id

36 bytes: commit txid plus commit output index. Compact form <txid>i<index>.

Location id

Where an Atomical currently sits: the outpoint (txid plus index) of the UTXO holding it. Changes with every transfer; the atomical id never does.

Coloring

The assignment of token value from a transaction's inputs to its outputs, decided entirely by the rules in specification section 8.

Sat value / atomical value

Two numbers recorded per token-bearing UTXO. Classically equal; since the custom coloring activation the atomical value may be lower (partial color), never higher.

Cleanly assigned

A flag meaning every colored output's satoshi value was exactly matched by token value. Unclean assignment is legal but is a signal that a transaction shape deserves scrutiny.

Burn

Token value that landed on no spendable output. Permanently removed from supply; the indexer reports it per token.

Bitwork

Proof-of-work over a transaction id, expressed as a hex prefix with an optional fractional extension (1a2b.8).

dft / dmt

The decentralized mint deploy and the individual mint claims against it.

Splat / split

The x operation separates co-located NFTs into distinct outputs; the y operation lets each fungible token skip output value before its coloring begins.

Realm, subrealm, container, dmitem

The naming and collection families: a top-level name, a name under a parent, a collection, and a proven item of a collection.

Sealed

An NFT locked forever by the sl operation: it can no longer move or change state.

2. Indexer semantics

2.1 Deterministic ordering

Everything is decided by position, never by timestamp or intent. Blocks are processed in height order, transactions in block order, inputs in index order, outputs in index order. Two independent indexers processing the same chain must produce identical state; any divergence is a bug in one of them.

Races (a ticker, a realm, a mint claim near the cap) resolve on the transaction number of the commit, which is a monotonically increasing counter assigned in block-then-position order. This is why a name claim can be lost by someone who revealed earlier but committed later.

2.2 Confirmation

Indexing happens at block connection: a transaction has no protocol effect until it is in a block. Two additional depths matter:

• 3 blocks for name and ticker claims to move from pending to verified. Before that depth the winner is not settled and an application must not treat a claim as final.
• Application confirmation depth. Bitcoin Universe marketplace settlement requires at least one confirmation by default and is operator-configurable from 1 to 100. Mempool observation alone never marks a trade settled.

2.3 Mempool

The indexer parses unconfirmed transactions so wallets can see pending mints and transfers, but mempool state is strictly provisional and separate from indexed state. Unconfirmed operations are held in a per-transaction map and dropped the moment the transaction leaves the mempool. Consequences for integrators:

• Do not treat a mempool mint as owning a ticker or a name; races are decided by confirmed commit order.
• Replace-by-fee changes the transaction id, which changes the reveal txid. Any operation whose validity depends on a bitwork requirement over that txid is invalidated by RBF, and a name mint that is replaced loses its place.
• Broadcast-time validation is available separately: the indexer exposes a validation call that runs the coloring blueprint over a raw transaction and refuses it when the result would burn or misassign value unexpectedly. Wallets should use a check of this kind before signing rather than after broadcasting.

2.4 Reorgs

Rollback is exact, not approximate. Every block write records undo information for both the base UTXO set and the Atomicals state, so disconnecting a block restores the precise prior state: mint records, coloring assignments, name candidacies, and mint counters all revert. On reconnection the affected blocks are reprocessed in order, and a name race whose winner was reorged out is genuinely re-run.

Undo data is retained for a bounded window (the reorg limit of the coin configuration; the ElectrumX default is 200 blocks for Bitcoin). A reorg deeper than the retained window cannot be unwound incrementally and requires a resync from an earlier snapshot. Applications built on top should therefore treat any assertion of ownership as valid only up to the reorg depth they are willing to tolerate, and should reconcile rather than assume.

3. Universe indexing decisions

Where this documentation follows the Bitcoin Universe indexers rather than upstream Atomicals documentation, the difference is listed here. Nothing else on this site is a Universe-specific rule.

4. Fee and size considerations

• Two transactions per mint. Budget for a commit and a reveal, plus the dust each carries.
• Payload lives in the witness and is discounted, but a large NFT payload still dominates reveal cost. Payload bytes are split across pushes; there is no single-push size ceiling on the payload as a whole.
• Token value is satoshi value. A 1000000-unit ARC-20 position locks up 0.01 BTC. Dust rules apply: an output below the dust threshold is not relayable, so very small balances cannot be split arbitrarily. The minimum mint_amount for a decentralized mint is 546 satoshis for exactly this reason.
• Bitwork costs time, not fees, but each grinding attempt re-signs the transaction; the cost is CPU and latency, and a high-difficulty launch can mean minutes per claim.
• Fee funding. Paying a fee out of colored inputs burns tokens. Always add an uncolored funding input for transfers where the balance must be preserved exactly.

5. Limitations

• No divisibility. One unit is one satoshi; there is no decimals field at the protocol layer. Applications that display decimals are applying their own convention.
• Supply is bounded by bitcoin. A token's maximum supply is limited by how many satoshis its holders are willing to immobilize.
• No protocol-level rejection. Malformed intent produces burns, not errors. There is no recovery mechanism, no admin, no reversal.
• Ordering couples unrelated assets. Combining two tokens in one transaction makes each one's outcome depend on the other's input position.
• Names are ASCII. Only a-z0-9- at the protocol layer; unicode presentation is an application convention.
• Upstream development has slowed. The protocol is stable as specified, but new upstream rule changes should not be assumed; verify activation heights against the implementation you index with.
• Indexer diversity is low. Most of the ecosystem runs one implementation lineage, so "what the indexer does" and "what the protocol is" are closer together here than in protocols with several independent implementations.

6. Security considerations

• Coin selection is the primary risk. Any wallet component that can spend UTXOs must know which are colored. Treat an unknown indexer response as "colored" and refuse, never as "clean".
• Validate before signing. Run the coloring blueprint over the draft transaction and show the user the resulting per-output balances and any burn. Post-broadcast checks are too late.
• Verify ownership at the exact outpoint. Ownership claims must bind txid, output index, ticker, and amount together. An address-level or amount-only check can be satisfied by an unrelated UTXO.
• Fail closed on indexer outage. Falling back to raw prevout data for asset decisions turns an availability problem into a loss of funds.
• Respect the 3-block name depth. Acting on a pending claim risks acting on a name someone else will win.
• Reconcile after reorgs. Any state derived from confirmed observation must be re-derived when blocks are disconnected, including settlement records.
• Do not trust payload content. CBOR payloads are attacker-controlled. Enforce the type restrictions on meta, args, ctx, and treat rendered payload data as untrusted input (content type sniffing, script injection, decompression bombs).
• Merkle proofs bound collections. A dmitem's membership proof is what makes a collection finite. Verify it rather than trusting a container's advertised item list.

7. Implementation checklist

Minimum work to index or integrate correctly:

• Parse witness elements for the atom marker under the structural conditions of rules E1 to E4; reject non-map CBOR and disallowed nested types.
• Enforce input-index 0 for mint operations, and both commit windows (100 blocks general, 3 blocks named).
• Derive atomical ids from the commit outpoint and imprint mints at reveal output 0.
• Implement coloring exactly: FIFO input ordering, left-to-right output filling, OP_RETURN skipping, era-dependent partial coloring, the non-clean fallback to output 0, and burn accounting.
• Implement the y split skip semantics and, from height 848484, the z custom color clamping (never inflate).
• Track NFT movement by input index with the fallback to output 0, plus x splat and sl sealing.
• Validate deploy parameter bounds and enforce mint caps by recounting from durable state at block boundaries, not from an in-memory counter.
• Implement bitwork validation including the fractional extension, and the perpetual difficulty schedule with the rollover allowance.
• Resolve name and ticker races by earliest commit transaction number, with the 3-block verification depth.
• Record undo information per block and support exact rollback to the reorg limit.
• Expose burns explicitly. An integration that silently hides burned value will eventually mislead someone into losing funds.
• Check your implementation against the test vectors; several are drawn from the indexer's own suite.