From e11d35da8d2cf074f8cabc26d9b363cdf4f08c26 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Fri, 16 Dec 2022 12:58:32 -0800 Subject: [PATCH] Add inscription docs --- docs/src/SUMMARY.md | 1 + docs/src/inscriptions.md | 64 ++++++++++++++++++++++++++++++++++++++++ docs/src/introduction.md | 2 ++ 3 files changed, 67 insertions(+) create mode 100644 docs/src/inscriptions.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index cf04456e14..f6249d0508 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -1,6 +1,7 @@ # Summary [Introduction](introduction.md) - [Overview](overview.md) +- [Inscriptions](inscriptions.md) - [FAQ](faq.md) - [Contributing](contributing.md) - [Guides](guides.md) diff --git a/docs/src/inscriptions.md b/docs/src/inscriptions.md new file mode 100644 index 0000000000..7d3f4af010 --- /dev/null +++ b/docs/src/inscriptions.md @@ -0,0 +1,64 @@ +Inscriptions +============ + +Inscriptions inscribe sats with arbitrary content, creating bitcoin-native +digital artifacts, more commonly known as NFTs. Inscriptions do not require a +sidechain or separate token. + +These inscribed sats can then be transferred using bitcoin transactions, sent +to bitcoin addresses, and held in bitcoin UTXOs. These transactions, addresses, +and UTXOs are normal bitcoin transactions, addresses, and UTXOS in all +respects, with the exception that in order to send individual sats, +transactions must control the order and value of inputs and outputs according +to ordinal theory. + +The inscription content model is that of the web. An inscription consists of a +content type, also known as a MIME type, and the content itself, which is a +byte string. This allows inscription content to be returned from a web server, +and for creating HTML inscriptions that use and remix the content of other +inscriptions. + +Inscription content is entirely on-chain, stored in taproot script-path spend +scripts. Taproot scripts have very few restrictions on their content, and +additionally receive the witness discount, making inscription content storage +relatively economical. + +Since taproot script spends can only be made from existing taproot outputs, +inscriptions are made using a two-phase commit/reveal procedure. First, in the +commit transaction, a taproot output committing to a script containing the +inscription content is created. Second, in the reveal transaction, the output +created by the commit transaction is spent, revealing the inscription content +on-chain. + +Inscription content is serialized using data pushes within unexecuted +conditionals, called an "envelopes". Envelopes consist of an `OP_FALSE OP_IF … +OP_ENDIF` wrapping any number of data pushes. Because envelopes are effectively +no-ops, they do not change the semantics of the script in which they are +included, and can be combined with any other locking script. + +A text inscription containing the string "Hello, world!" is serialized as +follows: + +``` +OP_FALSE +OP_IF + OP_PUSH "ord" + OP_1 + OP_PUSH "text/plain;charset=utf-8" + OP_0 + OP_PUSH "Hello, world!" +OP_ENDIF +``` + +First the string `ord` is pushed, to disambiguate inscriptions from other uses +of envelopes. + +`OP_1` indicates that the next push contains the content type, and `OP_0` +indicates that subsequent data pushes contain the content itself. Multiple data +pushes must be used for large inscriptions, as one of taproot's few +restrictions is that individual data pushes may not be larger than 520 bytes. + +The inscription content is contained within the input of a reveal transaction, +and the inscription is made on the first sat of its first output. This sat can +then be tracked using the familiar rules of ordinal theory, allowing it to be +transferred, bought, sold, lost to fees, and recovered. diff --git a/docs/src/introduction.md b/docs/src/introduction.md index 0318473098..d765f5cef5 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -26,6 +26,8 @@ fringe ordinal theorists. For more details on ordinal theory, see the [overview](overview.md). +For more details on inscriptions, see [inscriptions](inscriptions.md). + When you're ready to get your hands dirty, a good place to start is with [inscriptions](guides/inscriptions.md), a curious species of digital artifact enabled by ordinal theory.