Normative specification

Runes specification

Numbered rules for encoding, parsing, and validating runestones. Every rule below is grounded in the ord reference implementation, version 0.29.0 (ordinals crate 0.0.17): crates/ordinals/src/runestone.rs, varint.rs, runestone/tag.rs, runestone/flag.rs, runestone/message.rs, rune.rs, rune_id.rs, edict.rs, etching.rs, and src/index/updater/rune_updater.rs. Chain: Bitcoin. Network: mainnet unless stated.

Behavior that diverges from these rules will disagree with the ord index, and disagreement about balances means loss of funds. Follow the test vectors when implementing.

1 · Carrier and transaction anatomy

1. A runestone is carried in a transaction output whose script begins with OP_RETURN (0x6a) followed immediately by OP_13 (0x5d, also written OP_PUSHNUM_13), the Runes protocol identifier.
2. Outputs are examined in order. The first output matching R1 is the transaction's runestone. A transaction has at most one runestone; once one is found, no later output is examined.
3. Outputs that do not match R1 are skipped when searching, including outputs whose scripts do not parse and OP_RETURN outputs without the OP_13 identifier. They never make the transaction invalid.
4. The runestone payload is the concatenation, in order, of the contents of every data push after OP_13. All pushdata opcodes are legal: OP_0 (0x00, empty push), direct pushes 0x01 to 0x4b, OP_PUSHDATA1 (0x4c), OP_PUSHDATA2 (0x4d), and OP_PUSHDATA4 (0x4e). Zero pushes is legal and yields an empty runestone.
5. Any non-pushdata opcode (0x4f and above, including OP_PUSHNUM opcodes) after OP_13 makes the transaction a cenotaph with flaw Opcode.
6. A script that fails to parse after OP_13 (for example a push length running past the end of the script) makes the transaction a cenotaph with flaw InvalidScript.
7. The protocol does not constrain the runestone output's value in satoshis. It is conventionally zero, since OP_RETURN outputs are unspendable.

2 · Varint encoding

1. The payload decodes into a sequence of unsigned 128-bit integers encoded as LEB128 varints: each byte contributes its low 7 bits, least significant group first; a set high bit (0x80) means another byte follows.
2. A varint is at most 19 bytes long. Decoding fails as Overlong past 19 bytes, as Overflow when the 19th byte carries bits above the 128th (19th byte value with any of mask 0b0111_1100 set), and as Unterminated when the payload ends with the continuation bit set.
3. Any varint decoding failure anywhere in the payload makes the transaction a cenotaph with flaw Varint. The whole payload must decode.
4. Non-minimal encodings decode successfully: 0x80 0x00 decodes to the same integer as 0x00. Encoders should emit minimal encodings; decoders must accept both.

3 · Message structure

1. The integer sequence is parsed front to back as tag and value pairs: even positions are tags, the following integer is the value, until the Body tag (0) is reached.
2. A tag at the end of the sequence with no following value makes the transaction a cenotaph with flaw TruncatedField.
3. Repeated occurrences of the same tag accumulate their values in order into a queue for that tag. Interpretation consumes values from the front of the queue.
4. Everything after the Body tag is edict data, in groups of exactly four integers: block delta, transaction index (or delta), amount, output. A final group of fewer than four integers makes the transaction a cenotaph with flaw TrailingIntegers.

4 · Tag table

1. Odd tags are informational. Unrecognized odd tags, duplicate odd-tag values beyond those consumed, and odd-tag values that fail their range checks are silently ignored.
2. Even tags must be understood and fully consumed. If any even-tag value remains unconsumed after interpretation, the transaction is a cenotaph with flaw UnrecognizedEvenTag. This covers: unrecognized even tags (including reserved tag 126), even fields present without the flag that enables them, duplicate values beyond a field's arity, a Mint tag with only one value, and even-tag values that fail a range check (for example a Pointer not less than the output count, or a HeightStart above u64).

5 · Flags

1. The value of tag 2 is a bitfield. Bit 0 (Etching): this runestone etches a rune. Bit 1 (Terms): the etching has open mint terms. Bit 2 (Turbo): the etching opts in to future protocol changes. Bit 127 (Cenotaph): reserved, never valid.
2. The Terms and Turbo flags are consumed only when Etching is set. Any flag bit still set after consumption, including Terms without Etching or any unassigned bit, makes the transaction a cenotaph with flaw UnrecognizedFlag.

6 · Etching

1. An etching is present exactly when flag bit 0 is set. Its fields, all optional, are Rune (4), Divisibility (1), Spacers (3), Symbol (5), Premine (6), and, when the Terms flag is also set, Amount (10), Cap (8), HeightStart (12), HeightEnd (14), OffsetStart (16), OffsetEnd (18). Once etched, all properties are permanently immutable.
2. Names are sequences of the letters A through Z, encoded as an integer in modified base 26: for each letter after the first, add one, then multiply by 26 and add the letter's index (A is 0). A is 0, B is 1, Z is 25, AA is 26, AB is 27, and so on. Decoding reverses this: add one, then repeatedly take (n − 1) % 26 as the last letter and continue with (n − 1) / 26.
3. All name values at or above 6402364363415443603228541259936211926 (the value of 27 letters A) are reserved. Consequently, etchable names are 1 to 26 letters long.
4. Divisibility is the number of decimal places, at most 38. A larger value fails the range check and is ignored: the etching proceeds with default divisibility 0.
5. Spacers are a bitmap: bit i set places a dot • after letter i + 1. The maximum accepted value is 0x07FFFFFF; larger values are ignored. Spacers are display only: a name's identity and uniqueness ignore spacers, spacers may only fall between letters, and they do not count toward name length.
6. The symbol is a single Unicode scalar value. Values that are not valid scalars (above U+10FFFF or in the surrogate range) are ignored. A rune with no symbol is displayed with the generic currency sign ¤.
7. The premine is allocated to the etching transaction as unallocated runes, exactly as if it had been an input balance, and is assigned to outputs by the same edict and pointer rules.
8. Etching supply must fit: premine + cap × amount computed in u128 must not overflow. Overflow makes the transaction a cenotaph with flaw SupplyOverflow.
9. An etching with a name is honored by the indexer only if all of the following hold at indexing time; otherwise the etching is disregarded entirely (this is not a cenotaph):
   1. the name's value is at least the minimum unlocked at the etching block height (R30);
   2. the name is not reserved (R22);
   3. the name has not already been etched, ignoring spacers;
   4. the transaction commits to the name: some input spends a pay-to-taproot output, that input's witness contains a tapscript with a data push exactly equal to the name's value as little-endian bytes with trailing zero bytes trimmed, and the output being spent was confirmed at least 6 blocks before the etching block (COMMIT_CONFIRMATIONS = 6).
10. An etching without a name is assigned a reserved name by the indexer: 6402364363415443603228541259936211926 + (block << 32 | tx), where block and tx are the etching's rune ID components. Reserved-name etchings need no commitment.
11. Name unlock schedule, mainnet: runes activate at block 840,000 (first_rune_height = 4 × 210,000). At activation, names of 13 letters and longer are unlocked. The minimum steps down through the length thresholds every 17,500 blocks (one twelfth of a halving interval), interpolating linearly between thresholds, until every name, including single letters, is unlocked at block 1,050,000. Before activation no etching is honored.

7 · Minting

1. The Mint tag (20) is given twice: the first value is the block and the second the transaction index of the rune ID to mint. Values must fit u64 and u32 respectively, and block 0 with a nonzero tx is invalid. Values failing these checks are left unconsumed and make the transaction a cenotaph via R17. A single Mint value with no pair behaves the same way.
2. A mint succeeds when the target rune exists and its terms are satisfied at the mint transaction's block height: the height is not below the mint's start, is below the mint's end, and the recorded number of mints is below the cap (a missing cap is 0, so a rune without terms or cap is unmintable). Start is the later of HeightStart and etching block + OffsetStart; end is the earlier of HeightEnd and etching block + OffsetEnd; whichever of the pair is absent does not constrain.
3. A successful mint increments the rune's mint count and adds the fixed amount (Amount at etching, 0 if absent) to the transaction's unallocated runes. A mint whose terms are not satisfied is simply ignored: it is not a cenotaph and does not count toward the cap. A mint in a transaction that is a cenotaph for other reasons does count toward the cap, and its output is burned (R45).

8 · Edicts and delta encoding

1. Each edict is four integers: block delta, transaction index or delta, amount, output. A running rune ID starts at 0:0. The block delta is added to the running block. If the block delta is 0, the transaction value is added to the running transaction index; if the block delta is nonzero, the transaction value is the absolute transaction index. Encoders must sort edicts by rune ID for this encoding to be compact; decoders reconstruct absolute IDs by accumulation.
2. The resulting ID 0:0 refers to the rune etched by this very transaction. If the transaction etches no rune (or the etching was disregarded under R28), such an edict is skipped without effect.
3. If ID accumulation overflows (block above u64, transaction index above u32) or produces block 0 with a nonzero transaction index, the transaction is a cenotaph with flaw EdictRuneId. Edict parsing stops at the first failure.
4. The edict output must fit u32 and must be at most the transaction's output count. An output greater than the output count makes the transaction a cenotaph with flaw EdictOutput.
5. Edicts are processed in order against the unallocated pool. An amount of 0 means the edict's entire remaining balance of that rune. A nonzero amount is clamped to the remaining balance. An edict output exactly equal to the output count is a split: with amount 0, the remaining balance is divided evenly over all non-OP_RETURN outputs, earlier outputs receiving the remainder one unit at a time; with a nonzero amount, that amount is allocated to each non-OP_RETURN output in order until the balance runs out.

9 · Pointer

1. The Pointer (tag 22) must fit u32 and be strictly less than the output count; otherwise its value is unconsumed and the transaction is a cenotaph via R17. After all edicts are processed, remaining unallocated runes go to the pointer output. Without a pointer they go to the first non-OP_RETURN output. If no non-OP_RETURN output exists, they are burned.

10 · State transitions

1. A transaction's unallocated pool is the sum of: rune balances on every spent input outpoint, plus the minted amount when the runestone mints successfully, plus the premine when it etches.
2. Allocations assigned to an OP_RETURN output are burned, whether they got there by edict or by pointer. This is the deliberate burn mechanism.
3. A transaction with rune inputs and no runestone at all transfers every input rune balance to its first non-OP_RETURN output. Runes never disappear silently: every unit is either allocated to an output or recorded as burned.
4. A rune's ID is assigned at etching: the etching block height and the transaction's index within that block, written BLOCK:TX. IDs are permanent and never reassigned.
5. Balances are per rune, per outpoint, in atomic units (u128). An outpoint may carry balances of any number of runes. Spending the outpoint releases all of them into the spending transaction's unallocated pool.

11 · Cenotaphs

1. A cenotaph is a runestone that violates any rule marked above as producing one. In a cenotaph transaction: every input rune balance and every minted or premined amount is burned; a mint still increments the target rune's mint count; and an etching (if its name is valid and committed under R28) still creates the rune, but with no recorded divisibility, symbol, spacers, premine, or terms, and permanently unmintable.
2. Cenotaphs are the protocol's forward-compatibility mechanism. Future upgrades may assign meaning to currently unrecognized even tags and flags. Unupgraded clients, applying these rules, will treat upgraded runestones as cenotaphs and report the affected runes as burned rather than misreporting who owns them.
3. Only the first flaw encountered is reported by the reference implementation, but any single flaw is sufficient: cenotaph status is not a matter of degree.

12 · Hardcoded genesis rune

The mainnet index is initialized with one hardcoded rune: UNCOMMON•GOODS, rune ID 1:0, name value 2055900680524219742, spacers 128, symbol ⧉ (U+29C9), divisibility 0, no premine, turbo set, and open mint terms of amount 1 per mint, cap u128::MAX, height window 840,000 to 1,050,000. It is the only rune whose ID block precedes activation.