Implementer reference

Reference

Terminology, indexer semantics, and the operational details that decide whether two implementations agree. Everything here concerns replay behavior rather than payload syntax; for payload rules see the specification.

1. Terminology

Inscription

Content committed in a Bitcoin taproot witness and bound to one satoshi under the Ordinals numbering rules. The carrier for every BRC-20 operation.

Reveal transaction

The second transaction of an inscription pair, which exposes the witness content. Its output holding the inscribed satoshi determines first ownership.

Operation

One BRC-20 JSON payload: deploy, mint, or transfer.

Ticker

The 4-byte (or 5-byte self-mint) asset identifier, compared case-insensitively.

Available balance

Units an address can commit to a new transfer inscription.

Transferable balance

Units already reserved by unspent transfer inscriptions the address holds.

Overall balance

Available plus transferable. What the address economically owns.

Transfer inscription

A confirmed, valid transfer operation that has not yet been spent. A one-use bearer instrument for its amt.

transfer-inscribe / transfer-transfer

The two events a transfer produces. Indexers that hash their event streams must commit them separately; collapsing them into a single event breaks state comparison against other implementations.

Atomic amount

An amount as an unscaled base-10 integer at the ticker's dec. The safe internal representation; see arithmetic.

Checkpoint

The (height, block hash) pair a set of indexed results was computed at, together with the height below which results are treated as final.

Cursed inscription

An inscription assigned a negative number by the Ordinals rules because of a malformed or unusual envelope. Not a valid BRC-20 carrier (R24).

2. Confirmation semantics

Every BRC-20 validity decision is made at confirmation, against the confirmed ledger as of that point (R23). Two operations in the same block apply in transaction order, so a mint can validly reference a deploy from earlier in its own block.

The decision is permanent in one direction only. A transfer inscription that exceeded the available balance when it confirmed is void forever, and topping up the address later does not revive it (R16). Conversely a valid reservation stays valid until its inscription is spent, however the price or the balance moves afterwards.

The Bitcoin Universe read model makes this explicit: an ingested batch carries a checkpoint with height, hash, and finalizedHeight, and every response reports the checkpoint it was computed at.

3. Mempool semantics

Unconfirmed BRC-20 operations are not protocol state. An indexer may surface them as pending information, but it must not let them influence validity, because:

• Mempool contents differ between nodes, so pending-derived state is not reproducible.
• A pending transaction can be replaced (RBF), evicted, or simply never mined.
• Two conflicting pending mints for the last of a supply cannot both be honored, and the block, not the mempool, decides which one is.

Implementations that expose pending data should keep it in a separate lane from confirmed state, never let a pending operation satisfy a precondition for another operation, and drop pending entries when they disappear from the mempool.

4. Reorg semantics

A reorg removes blocks whose operations were already applied. Because BRC-20 state is a pure replay of block-ordered operations, correctness under reorg reduces to one requirement: the state after a reorg must equal a clean replay of the new chain.

Three details separate implementations that agree from ones that drift:

1. Reversal must be complete. Reverting a transfer must restore both the sender's and the recipient's columns, and reverting a transfer-inscribe must return the reservation to available. Leaving a dangling reservation is the classic bug.
2. Dependencies must unwind together. If a deploy is reverted, every mint and transfer that depended on it must be reverted too. A mint surviving without its deploy is a corrupt ledger.
3. Order is restored, not patched. After reversal, the new blocks apply in their own order. Re-applying a subset of old events in place produces state no clean replay would reach.

5. The cursed inscriptions caveat

Ordinals assigns negative inscription numbers to envelopes that were malformed or unusual under earlier rules, and later ord releases changed which envelopes are cursed and how they are numbered. BRC-20 does not treat cursed inscriptions as valid operations (R24), but the caveat for implementers is subtler than the rule:

• Whether a given inscription is cursed depends on the ord version and the height at which the rules changed. An indexer that upgrades its Ordinals layer can silently change its BRC-20 answers for historical blocks.
• Two indexers using different ord versions can therefore disagree about historical balances while both correctly implementing the BRC-20 rules.
• Pin the Ordinals implementation and version alongside the BRC-20 rules revision, and treat an Ordinals upgrade as requiring a full reindex and a state comparison, not a rolling restart.

6. Amounts and arithmetic

• Parse the decimal string form exactly (R11), then scale to an integer at the ticker's dec and never leave integer arithmetic afterwards. Floating point loses precision at 18 decimals and produces balances that do not reconcile.
• Reject values above the uint64 maximum, 18446744073709551615 (R9). Accumulated supply totals need more headroom than uint64, so use arbitrary-precision or 128-bit integers for aggregates.
• Trim trailing fractional zeros before counting decimal places: "1.500" has one significant decimal place and is valid at dec of 1.
• Compare amounts after scaling, never as strings.

7. Fee and size considerations

• A BRC-20 payload is 60 to 80 bytes of witness data. Witness bytes are discounted, so the dominant costs are the two transactions themselves and the fee rate at the time.
• Every operation costs a commit and a reveal transaction. A transfer therefore takes three transactions end to end: commit, reveal, and the spend that settles it.
• The inscribed satoshi normally travels in a small output, commonly 546 satoshis, which must not be treated as dust to be swept.
• An invalid operation costs exactly as much as a valid one. Validate before signing; the validator on this site checks everything that can be checked from the payload alone.
• Mint-out races bid the fee market up and then produce worthless inscriptions for everyone who lands after the supply is exhausted (R14).

8. Limitations

• No consensus enforcement. Bitcoin validates none of this. Agreement comes from indexers following the same rules, not from the chain.
• Indexer divergence is possible. Different rule revisions, ord versions, or extension support produce different balances from the same blocks.
• Two-phase transfers are not atomic. There is no protocol-level swap. Any trade needs a construction outside the protocol and outside its guarantees.
• No protocol-level offers or allowances. A transfer inscription is concrete collateral; there is no standing bid or delegated spending authority.
• Ticker squatting and lookalikes. First is valid rewards speed, and the 4-byte space is small and full of visually similar Unicode.
• Irreversible economics. No upgrade path exists for a deployed ticker.
• Fungibility with a footnote. Balances are fungible, but the transfer inscriptions carrying them are individual UTXOs subject to ordinary UTXO handling risks.

9. Security considerations

Accidental spends of transfer inscriptions

The largest practical risk. Any wallet unaware of inscriptions can spend a transfer inscription as change or fee, settling it against whoever receives it (R21). Keep inscriptions in inscription-aware wallets and never consolidate UTXOs blindly.

Ticker impersonation

Compare ticker bytes, not rendered glyphs. Confirm the deploy inscription ID of the asset you intend to trade.

Indexer trust

A balance is one indexer's opinion until you can reproduce it. For anything valuable, check the reading's height and compare independent indexers.

Marketplace and custody flows

Protocol state alone does not prove a listing is safe. Sound listing evidence joins the protocol position with an independent inscription inventory and an unspent-output check from a separate authority, all pinned to the same checkpoint, because the seller keeps control of the inscription UTXO after listing and can spend it.

Reorg exposure on irreversible actions

Bitcoin confirmation is necessary but not sufficient. An irreversible action should also require that the protocol event is still applied at a checkpoint deep enough for the operator's risk tolerance, and should re-verify after a reorg.

Replayed or malformed payloads

Parse defensively: bound input size, reject duplicate keys, and treat unknown keys as ignorable rather than as a reason to guess at intent.

10. Implementation checklist

1. Track inscriptions with a pinned Ordinals implementation and version; record both alongside your BRC-20 rules revision.
2. Filter carriers: accepted content types (R2), not cursed (R24).
3. Parse strictly: one JSON object, all values strings, exact p and op (R1 to R5).
4. Measure tickers in UTF-8 bytes; lowercase for identity and keep display casing (R7, R8).
5. Apply first-is-valid for deploys and treat deploy economics as immutable (R10).
6. Scale amounts to integers at dec; keep every operation in integer arithmetic.
7. Enforce lim, then the supply remainder rule on the last mint (R14).
8. Attribute mints to the first owner of the mint inscription (R15).
9. Model available and transferable balances separately per address and ticker.
10. Emit transfer-inscribe and transfer-transfer as two ordered events; make transfer inscriptions one-use (R18).
11. Classify the first spend as recipient, self, or fee and post the matching entries (R19 to R21).
12. Key balances by output script and apply operations in strict block and transaction order (R22).
13. Keep pending state in a separate lane from confirmed state; never let it satisfy a precondition.
14. Implement reorg reversal that fully unwinds dependent events, and refuse reorgs that cross your finality depth.
15. Report a checkpoint (height, hash, finalized height) with every answer so callers can judge freshness.
16. Verify against the test vectors, then against an independent indexer over a real block range before trusting the output.