Working knowledge

Guide

Everything on this page is the same protocol described normatively on the specification page, told in the order you actually meet it: what an Atomical is, how one is created, how ARC-20 balances move, and where the sharp edges are.

1. The mental model

Most token protocols keep a ledger: an account has a balance, and a message moves it. Atomicals does not. An ARC-20 balance is a set of satoshis. Holding 10000 QUARK means holding a UTXO of 10000 satoshis that the indexer has recorded as colored QUARK. Send those satoshis and the balance goes with them; let them fall into a miner fee and the balance is gone.

Three consequences follow, and they explain almost every surprise people hit:

• A token amount can never exceed the satoshi amount of the output holding it. 10000 units need at least 10000 satoshis.
• Coin selection is dangerous. A wallet that treats a colored UTXO as ordinary change will spend your tokens as fees.
• The rules that decide which output inherits which units are purely mechanical: input order, then output order. No intent is recorded anywhere.

2. How a mint happens

Every Atomical is created by two transactions.

1. Commit. You build a taproot script containing an atom envelope: the operation you want (ft, dft, dmt, nft) plus a CBOR payload with your parameters. You pay to the address that script commits to. Nothing is visible yet; the script is only a hash.
2. Reveal. You spend that output, which forces the script into the witness where indexers can read it. The Atomical is born, its identity fixed to the commit outpoint, its home fixed to output 0 of this reveal.

Two clocks run between them. A general mint must reveal within 100 blocks of its commit; anything requesting a name (a ticker, realm, container, or dmitem) must reveal within 3 blocks. Miss the window and the mint is simply void: the bitcoin moved, the Atomical never existed.

Commit/reveal exists to make name races fair. Because the commit hides your intent, nobody can see that you are claiming +alpha and front-run you; because claims resolve by earliest commit, the person who committed first wins even if someone else reveals sooner.

3. Launching an ARC-20 token

Direct mint (ft)

One transaction pair creates the whole supply at once. The supply equals the satoshi value of the reveal's first output, so a 100000-unit token means paying 100000 satoshis into output 0 and holding them. Simple, immediate, and entirely pre-allocated to you.

Decentralized mint (dft then many dmt)

The deploy declares the shape of the mint and creates no supply at all:

Then anyone mints. A claim is valid when it names the ticker, arrives at or after mint_height, pays exactly mint_amount satoshis to its first output, comes before the cap is reached, and satisfies whatever bitwork the deploy demanded. Nothing is reserved, nothing is whitelisted, and claims are processed in block order: it is a public race.

What bitwork actually is

Bitwork is proof-of-work over your own transaction id. A requirement of 1a2b means you must grind your transaction (changing a nonce field in the payload, re-signing, re-hashing) until its txid starts with 1a2b. Four hex characters is roughly 65 thousand attempts on average; each extra character multiplies by 16. The fractional form 1a2b.8 asks for the next digit to be at least 8, giving a half-step of difficulty.

Bitwork is a fairness device, not security: it slows down mass minting so a launch is not instantly drained by one script. In perpetual mode the required difficulty rises automatically after every max_mints claims, so a token can mint forever with steadily increasing cost.

4. How a transfer colors outputs

This is the part worth internalizing. When you spend colored UTXOs, no part of the transaction says where the tokens should go. The indexer decides, by walking a fixed procedure:

1. Collect. Sum every token's value across all inputs. Two inputs of 500 QUARK are one 1000-unit pool.
2. Order the tokens. First-in-first-out, by the earliest input index each token appears at.
3. Fill outputs left to right. The first token fills output 0, then output 1, and so on until its value is exhausted. The next token starts at the output after the last one the previous token touched. OP_RETURN outputs are skipped.
4. Anything left over burns. Value that no output can hold leaves the supply permanently.

So a transfer is "engineered" by choosing output values. To send 3000 units to a friend and keep 7000, you build output 0 with 3000 satoshis to their address and output 1 with 7000 satoshis to yourself. The order matters more than the addresses.

Since block 848484 the last output a token touches can be partially colored (a 5000-satoshi output carrying 3000 units, the other 2000 satoshis being plain bitcoin). Before that, an output had to be filled exactly or the assignment failed. Use the simulator to see either era behave.

5. Worked transactions

Example A: a clean split

inputs
  0: 10000 sats, colored 10000 QUARK
outputs
  0: 3000 sats -> recipient
  1: 6800 sats -> your change address
fee: 200 sats

result
  output 0 carries 3000 QUARK
  output 1 carries 6800 QUARK
  200 QUARK burn (they went to the miner)

The fee is paid in colored satoshis, so the fee is also paid in tokens. This is unavoidable when the fee comes out of a colored input: to avoid it, add a separate uncolored input to pay the fee, and give the outputs the full 10000 satoshis between them.

Example B: paying the fee from plain bitcoin

inputs
  0: 10000 sats, colored 10000 QUARK
  1: 50000 sats, plain bitcoin
outputs
  0: 3000 sats  -> recipient
  1: 7000 sats  -> your change address
  2: 49800 sats -> your change address
fee: 200 sats

result
  output 0 carries 3000 QUARK
  output 1 carries 7000 QUARK
  output 2 carries no token color
  nothing burns

The token pool is 10000 and outputs 0 and 1 absorb exactly that, in order, so coloring stops before output 2. Output 2 is ordinary change.

Example C: two tokens on one UTXO, separated with split

If a single UTXO carries both QUARK and ATOM (because a previous transaction merged them), a plain spend colors them consecutively in FIFO order, which may not be what you want. The y (split) operation lets each token skip a declared amount of output satoshis before its coloring starts, so you can steer each one onto its own output. NFTs in a split transaction are always forced to output 0, which is a deliberate safety rule.

6. Pitfalls that destroy value

• Fee-funded from a colored input. Every satoshi of fee taken from colored value is burned token supply (example A).
• An output too small for the remaining balance. In the exact-cover era this burned the whole remainder; today it burns only the excess, but the excess is still gone.
• Sending colored sats to an exchange or a service that does not index Atomicals. They will see ordinary bitcoin, and it will be swept into a hot wallet and mixed away.
• Consolidating UTXOs "to tidy up". Merging colored UTXOs is legal but changes which outputs carry what, and a consolidation to one small output burns the difference.
• Ordinary wallet coin selection. Any wallet without Atomicals awareness may pick a colored UTXO to pay for coffee.
• Directing value at an OP_RETURN output under the z operation. Regular assignment skips unspendable outputs; custom coloring does not protect you.

Before signing anything that touches an ARC-20 balance: identify which input is colored, confirm the total units, confirm output 0's value, confirm your change output's value, and confirm the two add up to the token total. Run it through the simulator if in any doubt.

7. Names, collections, NFTs

• NFTs are single Atomicals carrying arbitrary payload data. They move by input order (the n-th NFT-bearing input lands on output n) and fall back to output 0 rather than burning, which makes them much harder to lose than fungible value. Minting with the immutable flag, or later sealing with sl, locks them permanently.
• Realms are top-level names, written +alpha. Claiming one needs commit bitwork of at least four hex characters, and the earliest valid commit wins the race.
• Subrealms (+alpha.child) are minted under a parent, either directly (the parent owner spends the parent in the same transaction) or by rule: the parent publishes a rule set of regular expressions with prices, and anyone matching a pattern may claim by paying, within a window that opens 3 blocks after commit and closes at 15.
• Containers and dmitems are collections. The container publishes a merkle root of its full item list; each item mint proves membership with a merkle path, so the collection's contents are fixed at publication and cannot be quietly extended.

8. Product support matrix

Claims below are limited to what is wired in Bitcoin Universe's own code, verified in the shared protocol capability registry and the corresponding service implementations. Anything not listed is not currently supported in Bitcoin Universe products.

Marketplace ARC-20 execution runs through an authoritative prepare, sign, finalize flow: listings bind the exact indexed seller outpoint, ticker, and amount, and both listing and buyer-funding checks fail closed if the Atomicals indexer is unavailable rather than falling back to ordinary UTXO data. Settlement is recorded only after the configured confirmation depth (at least one confirmation by default, operator-configurable between 1 and 100).

Live ARC-20 token data and prepared deploy/mint/transfer actions are available in Bitcoin Inscribe; every action is handed to a compatible Bitcoin wallet for review and signing.