🪨RUNES SPEC
OFFICIAL RUNE SPEC BY CASEY RODARMOR
Runes
=====
Runes allow Bitcoin transactions to etch, mint, and transfer Bitcoin-native
digital commodities.
Whereas every inscription is unique, every unit of a rune is the same. They are
interchangeable tokens, fit for a variety of purposes.
Runestones
----------
Rune protocol messages, called runestones, are stored in Bitcoin transaction
outputs.
A runestone output's script pubkey begins with an `OP_RETURN`, followed by
`OP_13`, followed by zero or more data pushes. These data pushes are
concatenated and decoded into a sequence of 128-bit integers, and finally
parsed into a runestone.
A transaction may have at most one runestone.
A runestone may etch a new rune, mint an existing rune, and transfer runes from
a transaction's inputs to its outputs.
A transaction output may hold balances of any number of runes.
Runes are identified by IDs, which consist of the block in which a rune was
etched and the index of the etching transaction within that block.
Etching
-------
Runes come into existence by being etched. Etching creates a rune and sets its
properties. Once set, these properties are immutable, even to its etcher.
### Name
Names consist of the letters A through Z and are between one and twenty-eight
characters long. For example `UNCOMMONGOODS` is a rune name.
Names may contain spacers, represented as bullets, to aid readability.
`UNCOMMONGOODS` might be etched as `UNCOMMON•GOODS`.
The uniqueness of a name does not depend on spacers. Thus, a rune may not be
etched with the same sequence of letters as an existing rune, even if it has
different spacers.
### Divisibility
A rune's divisibility is how finely it may be divided into its atomic units.
Divisibility is expressed as the number of digits permissible after the decimal
point in an amount of runes. A rune with divisibility 0 may not be divided. A
unit of a rune with divisibility 1 may be divided into ten sub-units, a rune
with divisibility 2 may be divided into a hundred, and so on.
### Symbol
A rune's currency symbol is a single Unicode code point, for example `$`, `⧉`,
or `🧿`, displayed after quantities of that rune.
101 atomic units of a rune with divisibility 2 and symbol `🧿` would be
rendered as `1.01 🧿`.
If a rune does not have a symbol, the generic currency sign `¤`, also called a
scarab, should be used.
### Premine
The etcher of a rune may optionally allocate to themselves units of the rune
being etched. This allocation is called a premine.
### Terms
A rune may have an open mint, allowing anyone to create and allocate units of
that rune for themselves. An open mint is subject to terms, which are set upon
etching.
A mint is open while all terms of the mint are satisfied, and closed when any
of them are not. For example, a mint may be limited to a starting height, an
ending height, and a cap, and will be open between the starting height and
ending height, or until the cap is reached, whichever comes first.
#### Cap
The number of times a rune may be minted is its cap. A mint is closed once the
cap is reached.
#### Amount
Each mint transaction creates a fixed amount of new units of a rune.
#### Start Height
A mint is open starting in the block with the given start height.
#### End Height
A rune may not be minted in or after the block with the given end height.
#### Start Offset
A mint is open starting in the block whose height is equal to the start offset
plus the height of the block in which the rune was etched.
#### End Offset
A rune may not be minted in or after the block whose height is equal to the end
offset plus the height of the block in which the rune was etched.
Minting
-------
While a rune's mint is open, anyone may create a mint transaction that creates
a fixed amount of new units of that rune, subject to the terms of the mint.
Transferring
------------
When transaction inputs contain runes, or new runes are created by a premine or
mint, those runes are transferred to that transaction's outputs. A
transaction's runestone may change how input runes transfer to outputs.
### Edicts
A runestone may contain any number of edicts. Edicts consist of a rune ID, an
amount, and an output number. Edicts are processed in order, allocating
unallocated runes to outputs.
### Pointer
After all edicts are processed, remaining unallocated runes are transferred to
the transaction's first non-`OP_RETURN` output. A runestone may optionally
contain a pointer that specifies an alternative default output.
### Burning
Runes may be burned by transferring them to an `OP_RETURN` output with an edict
or pointer.
Cenotaphs
---------
Runestones may be malformed for a number of reasons, including non-pushdata
opcodes in the runestone `OP_RETURN`, invalid varints, or unrecognized
runestone fields.
Malformed runestones are termed
[cenotaphs](https://en.wikipedia.org/wiki/Cenotaph).
Runes input to a transaction with a cenotaph are burned. Runes etched in a
transaction with a cenotaph are set as unmintable. Mints in a transaction with
a cenotaph count towards the mint cap, but the minted runes are burned.
Cenotaphs are an upgrade mechanism, allowing runestones to be given new
semantics that change how runes are created and transferred, while not
misleading unupgraded clients as to the location of those runes, as unupgraded
clients will see those runes as having been burned.RUNES Specification
The Runes reference implementation, ord, is the normative specification of the Runes protocol.
Nothing you read here or elsewhere, aside from the code of ord, is a specification. This prose description of the runes protocol is provided as an guide to the behavior of ord, and the code of ord itself should always be consulted to confirm the correctness of any prose description.
If, due to a bug in ord, this document diverges from the actual behavior of ord and it is impractically disruptive to change ord's behavior, this document will be amended to agree with ord's actual behavior.
Users of alternative implementations do so at their own risk, and services wishing to integrate Runes are strongly encouraged to use ord itself to make Runes transactions, and to determine the state of runes, mints, and balances.
Runestones
Rune protocol messages are termed "runestones".
The Runes protocol activates on block 840,000. Runestones in earlier blocks are ignored.
Abstractly, runestones contain the following fields:
struct Runestone {
edicts: Vec<Edict>,
etching: Option<Etching>,
mint: Option<RuneId>,
pointer: Option<u32>,
}Runes are created by etchings:
struct Etching {
divisibility: Option<u8>,
premine: Option<u128>,
rune: Option<Rune>,
spacers: Option<u32>,
symbol: Option<char>,
terms: Option<Terms>,
}Which may contain mint terms:
struct Terms {
amount: Option<u128>,
cap: Option<u128>,
height: (Option<u64>, Option<u64>),
offset: (Option<u64>, Option<u64>),
}Runes are transferred by edict:
struct Edict {
id: RuneId,
amount: u128,
output: u32,
}Rune IDs are encoded as the block height and transaction index of the transaction in which the rune was etched:
struct RuneId {
block: u64,
tx: u32,
}Rune names are encoded as modified base-26 integers:
struct Rune(u128);Deciphering
Runestones are deciphered from transactions with the following steps:
Find the first transaction output whose script pubkey begins with
OP_RETURN OP_13.Concatenate all following data pushes into a payload buffer.
Decode a sequence 128-bit LEB128 integers from the payload buffer.
Parse the sequence of integers into an untyped message.
Parse the untyped message into a runestone.
Deciphering may produce a malformed runestone, termed a cenotaph.
Locating the Runestone Output
Outputs are searched for the first script pubkey that beings with OP_RETURN OP_13. If deciphering fails, later matching outputs are not considered.
Assembling the Payload Buffer
The payload buffer is assembled by concatenating data pushes. If a non-data push opcode is encountered, the deciphered runestone is a cenotaph with no etching, mint, or edicts.
Decoding the Integer Sequence
A sequence of 128-bit integers are decoded from the payload as LEB128 varints.
LEB128 varints are encoded as sequence of bytes, each of which has the most-significant bit set, except for the last.
If a LEB128 varint contains more than 18 bytes, would overflow a u128, or is truncated, meaning that the end of the payload buffer is reached before encountering a byte with the continuation bit not set, the decoded runestone is a cenotaph with no etching, mint, or edicts.
Parsing the Message
The integer sequence is parsed into an untyped message:
struct Message {
fields: Map<u128, Vec<u128>>,
edicts: Vec<Edict>,
}The integers are interpreted as a sequence of tag/value pairs, with duplicate tags appending their value to the field value.
If a tag with value zero is encountered, all following integers are interpreted as a series of four-integer edicts, each consisting of a rune ID block height, rune ID transaction index, amount, and output.
struct Edict {
id: RuneId,
amount: u128,
output: u32,
}If an edict output is greater than the number of outputs of the transaction, an edict rune ID is encountered with block zero and nonzero transaction index, or a field is truncated, meaning a tag is encountered without a value, the decoded runestone is a cenotaph.
Note that if a cenotaph is produced here, the cenotaph is not empty, meaning that it contains the fields and edicts, which may include an etching and mint.
Parsing the Runestone
The runestone:
struct Runestone {
edicts: Vec<Edict>,
etching: Option<Etching>,
mint: Option<RuneId>,
pointer: Option<u32>,
}Is parsed from the unsigned message using the following tags:
enum Tag {
Body = 0,
Flags = 2,
Rune = 4,
Premine = 6,
Cap = 8,
Amount = 10,
HeightStart = 12,
HeightEnd = 14,
OffsetStart = 16,
OffsetEnd = 18,
Mint = 20,
Pointer = 22,
Cenotaph = 126,
Divisibility = 1,
Spacers = 3,
Symbol = 5,
Nop = 127,
}Note that tags are grouped by parity, i.e., whether they are even or odd. Unrecognized odd tags are ignored. Unrecognized even tags produce a cenotaph.
All unused tags are reserved for use by the protocol, may be assigned at any time, and must not be used.
Body
The Body tag marks the end of the runestone's fields, causing all following integers to be interpreted as edicts.
Flags
The Flag field contains a bitmap of flags, whose position is 1 << FLAG_VALUE:
enum Flag {
Etching = 0,
Terms = 1,
Cenotaph = 127,
}The Etching flag marks this transaction as containing an etching.
The Terms flag marks this transaction's etching as having open mint terms.
The Cenotaph flag is unrecognized.
If the value of the flags field after removing recognized flags is nonzero, the runestone is a cenotaph.
Rune
The Rune field contains the name of the rune being etched. If the Eching flag is set, but the Rune field is omitted, a reserved rune name is allocated, starting with AAAAAAAAAAAAAAAAAAAAAAAAAAA and increasing by one with each such reserved rune allocated.
Premine
The Premine field contains the amount of premined runes.
Cap
The Cap field contains the allowed number of mints.
Amount
The Amount field contains the amount of runes each mint transaction receives.
HeightStart and HeightEnd
The HeightStart and HeightEnd fields contain the mint's starting and ending absolute block heights, respectively. The mint is open starting in the block with height HeightStart, and closes in the block with height HeightEnd.
OffsetStart and OffsetEnd
The OffsetStart and OffsetEnd fields contain the mint's starting and ending block heights, relative to the block in which the etching is mined. The mint is open starting in the block with height OffsetStart + ETCHING_HEIGHT, and closes in the block with height OffsetEnd + ETCHING_HEIGHT.
Mint
The Mint field contains the Rune ID of the rune to be minted in this transaction.
Pointer
The Pointer field contains the index of the output to which runes unallocated by edicts should be transferred. If the Pointer field is absent, unallocated runes are transferred to the first non-OP_RETURN output.
Cenotaph
The Cenotaph field is unrecognized.
Divisibility
The Divisibility field, raised to the power of ten, is the number of subunits in a super unit of runes.
For example, the amount 1234 of different runes with divisibility 0 through 3 is displayed as follows:
0
1234
1
123.4
2
12.34
3
1.234
Spacers
The Spacers field is a bitfield of • spacers that should be displayed between the letters of the rune's name.
The Nth field of the bitfield, starting from the least significant, determines whether or not a spacer should be displayed between the Nth and N+1th character, starting from the left of the rune's name.
For example, the rune name AAAA rendered with different spacers:
| Spacers | Display | | 0b1 | A•AAA | | 0b11 | A•A•AA | | 0b10 | AA•AA | | 0b111 | A•A•A•A |
Trailing spacers are ignored.
Symbol
The Symbol field is the Unicode codepoint of the Rune's currency symbol, which should be displayed after amounts of that rune. If a rune does not have a currency symbol, the generic currency character ¤ should be used.
For example, if the Symbol is # and the divisibility is 2, the amount of 1234 units should be displayed as 12.34 #.
Nop
The Nop field is unrecognized.
Cenotaphs
Cenotaphs have the following effects:
All runes input to a cenotaph are burned.
If the cenotaph is an etching, the etched rune has supply zero and is unmintable.
If the cenotaph is a mint, the mint counts against the mint cap and the minted runes are burned.
Cenotaphs may be created if a runestone contains an unrecognized even tag, an unrecognized flag, an edict with an output number greater than the number of inputs, a rune ID with block zero and nonzero transaction index, a malformed varint, a non-datapush instruction in the runestone output script pubkey, a tag without a following value, or trailing integers not part of an edict.
Executing the Runestone
Runestones are executed in the order their transactions are included in blocks.
Etchings
A runestone may contain an etching:
struct Etching {
divisibility: Option<u8>,
premine: Option<u128>,
rune: Option<Rune>,
spacers: Option<u32>,
symbol: Option<char>,
terms: Option<Terms>,
}rune is the name of the rune to be etched, encoded as modified base-26 integer.
Rune names consist of the letters A through Z, with the following encoding:
A
0
B
1
…
…
Y
24
Z
25
AA
26
AB
27
…
…
AY
50
AZ
51
BA
52
And so on and so on.
Rune names AAAAAAAAAAAAAAAAAAAAAAAAAAA and above are reserved.
rune may be omitted, in which case the first unallocated rune name, starting at AAAAAAAAAAAAAAAAAAAAAAAAAAA and increasing by one each time, is etched.
If rune is present, it must be unlocked as of the block in which the etching appears.
Initially, all rune names of length thirteen and longer, up until the first reserved rune name, are unlocked.
Runes begin unlocking in block 840,000, the block in which the runes protocol activates.
Thereafter, every 17,500 block period, the next shortest length of rune names is continously unlocked. So, between block 840,000 and block 857,500, the twelve-character rune names are unlocked, between block 857,500 and block 875,000 the eleven character rune names are unlocked, and so on and so on, until the one-character rune names are unlocked between block 1,032,500 and block 1,050,000. See the ord codebase for the precise unlocking schedule.
To prevent front running an etching that has been broadcast but not mined, if a non-reserved rune name is being etched, the etching transaction must contain a valid commitment to the name being etched.
A commitment consists of a data push of the rune name, encoded as a little-endian integer with trailing zero bytes elided, present in an input witness tapscript where the output being spent has at least six confirmations.
If a valid commitment is not present, the etching is ignored.
Last updated