diff --git a/docs/book.toml b/docs/book.toml index 1970cc7aac..ae8685741a 100644 --- a/docs/book.toml +++ b/docs/book.toml @@ -1,5 +1,5 @@ [book] -title = "Ordinal Hunter's Manual" +title = "Ordinal Theory Handbook" language = "en" src = "src" diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 3ad3e91d83..75400b77b4 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -2,12 +2,15 @@ [Introduction](introduction.md) -- [Theory](theory.md) -- [Block Explorer](block-explorer.md) -- [Hunting](hunting.md) +- [Overview](overview.md) - [FAQ](faq.md) -- [Bounties](bounty.md) +- [Guides](guides.md) + - [Explorer](guides/explorer.md) + - [Inscriptions](guides/inscriptions.md) + - [Ordinal Hunting](guides/ordinal-hunting.md) + +- [Bounties](bounties.md) - [Bounty 0: 100,000 sats Claimed!](bounty/0.md) - [Bounty 1: 200,000 sats Claimed!](bounty/1.md) - [Bounty 2: 300,000 sats Claimed!](bounty/2.md) diff --git a/docs/src/bounty.md b/docs/src/bounties.md similarity index 83% rename from docs/src/bounty.md rename to docs/src/bounties.md index cbe914e200..2dbc2093e3 100644 --- a/docs/src/bounty.md +++ b/docs/src/bounties.md @@ -1,9 +1,9 @@ Ordinal Bounty Hunting Hints ============================ -- There are no ordinal wallets or transaction construction libraries. However, +- The `ord` wallet can send and receive specific satoshis. Additionally, ordinal theory is extremely simple. A clever hacker should be able to write - code to manipulate ordinals in no time. + code from scratch to manipulate satoshis using ordinal theory in no time. - For more information about ordinals, check out the [FAQ](./faq.md) for an overview, the [BIP](https://github.com/casey/ord/blob/master/bip.mediawiki) diff --git a/docs/src/guides.md b/docs/src/guides.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/src/block-explorer.md b/docs/src/guides/explorer.md similarity index 97% rename from docs/src/block-explorer.md rename to docs/src/guides/explorer.md index 0279c86a36..8899cdf001 100644 --- a/docs/src/block-explorer.md +++ b/docs/src/guides/explorer.md @@ -1,5 +1,5 @@ -Ordinal Block Explorer -====================== +Ordinal Explorer +================ The `ord` binary includes a block explorer. We host a instance of the block explorer on mainnet at [ordinals.com](https://ordinals.com), and on signet at diff --git a/docs/src/guides/inscriptions.md b/docs/src/guides/inscriptions.md new file mode 100644 index 0000000000..67a3caf883 --- /dev/null +++ b/docs/src/guides/inscriptions.md @@ -0,0 +1,218 @@ +Ordinal Inscription Guide +========================= + +Individual satoshis can be inscribed with arbitrary content, creating +Bitcoin-native digital artifacts that can be held in a Bitcoin wallet and +transferred using Bitcoin transactions. Inscriptions are as durable, immutable, +secure, and decentralized as the Bitcoin blockchain itself. + +Working with inscriptions requires a Bitcoin full node, to give you a view of +the current state of the Bitcoin blockchain, and a wallet that can make +ordinal-aware transactions that inscribe satoshis with content and transfer +individual satoshis using ordinal theory. + +Bitcoin Core provides both a Bitcoin full node and wallet. However, the Bitcoin +Core wallet cannot make ordinal-aware transactions. Making ordinal-aware +transactions requires [`ord`](https://github.com/casey/ord), the ordinal theory +utility. `ord wallet` subcommands interact with an existing Bitcoin Core +wallet. + +This guide covers: + +1. Installing Bitcoin Core +2. Syncing the Bitcoin blockchain +3. Creating a Bitcoin Core wallet +4. Using `ord wallet receive` to receive satoshis +5. Creating inscriptions with `ord wallet inscribe` +6. Sending inscriptions with `ord wallet send` +7. Receiving inscriptions with `ord wallet receive` + +Getting Help +------------ + +If you get stuck, try asking for help on the [Ordinal Theory Discord +Server](https://discord.com/invite/87cjuz4FYg), or checking GitHub for relevant +[issues](https://github.com/casey/ord/issues) and +[discussions](https://github.com/casey/ord/discussions). + +Installing Bitcoin Core +----------------------- + +Bitcoin Core is available from [bitcoincore.org](https://bitcoincore.org/) on +the [download page](https://bitcoincore.org/en/download/). + +This guide does not cover installing Bitcoin Core in detail. Once Bitcoin Core +is installed, you should be able to run `bitcoind -version` successfully from +the command line. + +Configuring Bitcoin Core +------------------------ + +`ord wallet` subcommands cannot yet be used on mainnet, so your Bitcoin Core +node must be configured to use another chain. This guide uses signet, but +testnet or regtest mode may also be used. Additionally, `ord` requires Bitcoin +Core's transaction index. + +To configure your Bitcoin Core node to use signet and maintain a transaction +index, add the following to your `bitcoin.conf`: + +``` +signet=1 +txindex=1 +``` + +Or, run `bitcoind` with `-signet` and `-txindex`: + +``` +bitcoind -signet -txindex +``` + +Syncing the Bitcoin Blockchain +------------------------------ + +Once Bitcoin Core has been configured to use signet, you'll need to sync the +blockchain. Signet is a low-volume test network, so this shouldn't take long. + +To sync the chain, run `bitcoind -signet -txindex` and leave it running until +`bitcoin-cli -signet getblockcount` agrees with the block count on a block +explorer like [the mempool.space signet block +explorer](https://mempool.space/signet). + +Creating a Bitcoin Core Wallet +------------------------------ + +`ord` uses Bitcoin Core to manage private keys, sign transactions, and +broadcast transactions to the Bitcoin network. + +`ord` wallets must be named `ord`, or start with `ord-`, to avoid +unintentionally using the `ord` utility with non-ordinal Bitcoin wallets. + +To create a wallet for use with `ord`, run: + +``` +bitcoin-cli -signet createwallet ord +``` + +Loading the Bitcoin Core Wallet +------------------------------- + +Bitcoin Core wallets must be loaded before the can be used with `ord`. To load +your wallet, run: + +``` +bitcoin-cli -signet loadwallet ord +``` + +Installing `ord` +---------------- + +The `ord` utility is written in Rust and can be built from +[source](https://github.com/casey/ord). Pre-built binaries are available on the +[releases page](https://github.com/casey/ord/releases). + +Once `ord` is installed, you should be able to run `ord --version` on the +command line. + +Receiving Satoshis +------------------ + +Inscriptions are made on individual satoshis, using normal Bitcoin transactions +that pay fees in satoshis, so your wallet will need some sats. + +Get a new address from your `ord` wallet by running `ord --chain signet wallet +receive` + +Use a signet faucet to send satoshis to the address you generated. Two faucets +you might try are [signet.bc-2.jp](https://signet.bc-2.jp/) and +[alt.signetfaucet.com](https://alt.signetfaucet.com/). + +Once the faucet transaction confirms, you should be able to see the +transactions outputs with `ord --chain signet wallet utxos`. + +Creating Inscription Content +---------------------------- + +Create a `.png` or `.txt` file smaller than 1024 bytes to inscribe. + +Satoshis can be inscribed with any kind of content, but the `ord` wallet and +explorer are currently limited to `.png` and `.txt` files. + +Additionally, inscriptions made on signet must be 1024 bytes or less, to avoid +congesting signet for other users. Inscriptions are stored in Taproot input +witnesses, so mainnet inscriptions will only be limited by the depths of your +pockets and the 4,000,000 byte witness size limit. + +Creating Inscriptions +--------------------- + +To create an inscription with the contents of `FILE`, run: + +``` +ord --chain signet wallet inscribe --file FILE +``` + +Ord will output two transactions IDs, one for the commit transaction, and one +for the reveal transaction. + +The commit transaction commits to a tapscript containing the contents of the +inscription, and the reveal transaction spends from that tapscript, revealing +the contents on chain and inscribing them on the first satoshi of the first +output of the reveal transaction. + +Wait for the reveal transaction to be mined. You can check the status of the +commit and reveal transactions using [the mempool.space signet block +explorer](https://mempool.space/signet). + +Once the reveal transaction has been mined, the inscription ID should be +printed when you run: + +``` +ord --chain signet wallet inscriptions +``` + +And when you visit [the signet ordinals explorer](https://signet.ordinals.com/) +at `signet.ordinals.com/inscription/INSCRIPTION_ID`. + + +Sending Inscriptions +-------------------- + +Ask the recipient to generate a new address by running: + +``` +ord --chain signet wallet receive +``` + +Send the inscription by running: + +``` +ord --chain signet wallet send INSCRIPTION_ID ADDRESS +``` + +Once the send transaction confirms, the recipient can confirm receipt by +running: + +``` +ord --chain signet wallet inscriptions +``` + +Receiving Inscriptions +---------------------- + +Generate a new receive address using: + +``` +ord --chain signet wallet receive +``` + +The sender can transfer the inscription to your address using: + +``` +ord --chain signet wallet send INSCRIPTION_ID ADDRESS +``` + +Once the send transaction confirms, you can can confirm receipt by running: + +``` +ord --chain signet wallet inscriptions +``` diff --git a/docs/src/hunting.md b/docs/src/guides/ordinal-hunting.md similarity index 91% rename from docs/src/hunting.md rename to docs/src/guides/ordinal-hunting.md index eb275c150c..f3a12b1e86 100644 --- a/docs/src/hunting.md +++ b/docs/src/guides/ordinal-hunting.md @@ -1,9 +1,13 @@ Ordinal Hunting =============== +*This guide is out of date. Since it was written, the `ord` binary was changed +to only build the full ordinal index when the `--ordinal-index` flag is +supplied. Additionally, `ord` now has a built-in wallet that wraps a Bitcoin +Core wallet. See `ord wallet --help`.* + Ordinal hunting is difficult but rewarding. The feeling of owning a wallet full -of UTXOs, redolent with the scent of rare and exotic ordinals, is beyond -compare. +of UTXOs, redolent with the scent of rare and exotic sats, is beyond compare. Ordinals are numbers for satoshis. Every satoshi has an ordinal number and every ordinal number has a satoshi. @@ -234,11 +238,12 @@ those multiple descriptors into Bitcoin Core. #### Sparrow Wallet -Navigate to the `Settings` tab, then to `Script Policy`, and press the edit button to display the descriptor. +Navigate to the `Settings` tab, then to `Script Policy`, and press the edit +button to display the descriptor. ### Transferring Ordinals -`ord` does not yet support transferring specific ordinals. Currently, your best -bet is to use the `bitcoin-cli` commands `createrawtransaction`, -`signrawtransactionwithwallet`, and `sendrawtransaction`, however, how to do so -is complex and outside the scope of this guide. +The `ord` wallet supports transferring specific satoshis. You can also use +`bitcoin-cli` commands `createrawtransaction`, `signrawtransactionwithwallet`, +and `sendrawtransaction`, how to do so is complex and outside the scope of this +guide. diff --git a/docs/src/introduction.md b/docs/src/introduction.md index 62b7f1c0a9..0ede3bea8d 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -1,4 +1,34 @@ -Ordinals are a namespace for Bitcoin. For an overview, check out the [theory](theory.md) page. +Introduction +============ + +This handbook is a guide to ordinal theory. Ordinal theory concerns itself with +satoshis, giving them individual identities and allowing them to be tracked, +transferred, and imbued with meaning. + +Satoshis, not bitcoin, are the atomic, native currency of the Bitcoin network. +One bitcoin can be sub-divided into 100,000,000 satoshis, but no further. + +Ordinal theory does not require a sidechain or token aside from Bitcoin, and +can be used without any changes to the Bitcoin network. It works right now. + +Ordinal theory imbues satoshis with numismatic value, allowing them to +collected and traded as curios. + +Individual satoshis can be inscribed with arbitrary content, creating +Bitcoin-native digital artifacts that can be held in Bitcoin wallets and +transferred using Bitcoin transactions. Inscriptions are as durable, immutable, +secure, and decentralized as the Bitcoin blockchain itself. + +Other, more unusual use-cases are possible: off-chain colored-coins, public key +infrastructure with key rotation, a decentralized replacement for the DNS. For +now though, such use-cases are theoretical, and exist only in the minds of +fringe ordinal theorists. + +For more details on ordinal theory, see the [overview](overview.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. Links ----- @@ -7,7 +37,7 @@ Links - [BIP](https://github.com/casey/ord/blob/master/bip.mediawiki) - [Discord](https://discord.gg/87cjuz4FYg) - [Mainnet Block Explorer](https://ordinals.com) -- [Signet Block Explorer](https://ordinals.com) +- [Signet Block Explorer](https://signet.ordinals.com) Videos ------ diff --git a/docs/src/theory.md b/docs/src/overview.md similarity index 72% rename from docs/src/theory.md rename to docs/src/overview.md index 22420b6234..cc169cc1a9 100644 --- a/docs/src/theory.md +++ b/docs/src/overview.md @@ -1,27 +1,32 @@ -Ordinal Theory -============== +Ordinal Theory Overview +======================= -Ordinals are numbering scheme for satoshis that allows tracking and -transferring individual sats. These numbers are called -[ordinals](https://ordinals.com). Satoshis are numbered in the order in which +Ordinals are a numbering scheme for satoshis that allows tracking and +transferring individual sats. These numbers are called [ordinal +numbers](https://ordinals.com). Satoshis are numbered in the order in which they're mined, and transferred from transaction inputs to transaction outputs -in first-in-first-out order. More details are available in [the +first-in-first-out. Both the numbering scheme and the transfer scheme rely on +*order*, the numbering scheme on the *order* in which satoshis are mined, and +the transfer scheme on the *order* of transaction inputs and outputs. Thus the +name, *ordinals*. + +Technical details are available in [the BIP](https://github.com/casey/ord/blob/master/bip.mediawiki). -Ordinals don't require a separate token, another blockchain, or any changes to +Ordinals do not require a separate token, another blockchain, or any changes to Bitcoin. They work right now. -Ordinals have a few different representations: +Ordinal numbers have a few different representations: - *Integer notation*: - [`2099994106992659`](https://ordinals.com/ordinal/2099994106992659). The - number is the ordinal number, and the "°" is the Romance language ordinal - symbol. + [`2099994106992659`](https://ordinals.com/ordinal/2099994106992659) The + ordinal number, assigned according to the order in which the satoshi was + mined. - *Decimal notation*: - [`3891094.16797`](https://ordinals.com/ordinal/3891094.16797)The first number - is the block height in which the ordinal was created, the second the offset - of the ordinal within the block. + [`3891094.16797`](https://ordinals.com/ordinal/3891094.16797) The first + number is the block height in which the satoshi was mined, the second the + offset of the satoshi within the block. - *Degree notation*: [`3°111094′214″16797‴`](https://ordinals.com/ordinal/3%C2%B0111094%E2%80%B2214%E2%80%B316797%E2%80%B4). @@ -29,27 +34,27 @@ Ordinals have a few different representations: - *Percentile notation*: [`99.99971949060254%`](https://ordinals.com/ordinal/99.99971949060254%25) . - The ordinals position in Bitcoin's supply, expressed as a percentage. + The satoshi's position in Bitcoin's supply, expressed as a percentage. - *Name*: [`satoshi`](https://ordinals.com/ordinal/satoshi). An encoding of the ordinal number using the characters `a` through `z`. Arbitrary assets, such as NFTs, security tokens, accounts, or stablecoins can -be attached to Ordinals. +be attached to satoshis using ordinal numbers as stable identifiers. Ordinals is an open-source project, developed [on GitHub](https://github.com/casey/ord). The project consists of a BIP describing the ordinal scheme, an index that communicates with a Bitcoin Core node to -track the location of all ordinals, a wallet that allows making ordinal-aware +track the location of all satoshis, a wallet that allows making ordinal-aware transactions, a block explorer for interactive exploration of the blockchain, -functionality for minting ordinal NFTs, and this manual. +functionality for inscribing satoshis with digital artifacts, and this manual. Rarity ------ -Humans are collectors, and since ordinals can be tracked and transferred, +Humans are collectors, and since satoshis can now be tracked and transferred, people will naturally want to collect them. Ordinal theorists can decide for -themselves which sats are rare and desirable, but there are some hints. +themselves which sats are rare and desirable, but there are some hints… Bitcoin has periodic events, some frequent, some more uncommon, and these naturally lend themselves to a system of rarity. These periodic events are: @@ -79,7 +84,7 @@ This gives us the following rarity levels: - `mythic`: The first sat of the genesis block Which brings us to degree notation, which unambiguously represents an ordinal -in a way that makes rarity easy to see at a glance: +number in a way that makes the rarity of a satoshi easy to see at a glance: ``` A°B′C″D‴ @@ -92,7 +97,7 @@ A°B′C″D‴ Ordinal theorists often use the terms "hour", "minute", "second", and "third" for *A*, *B*, *C*, and *D*, respectively. -Now for some examples. This ordinal is common: +Now for some examples. This satoshi is common: ``` 1°1′1″1‴ @@ -103,7 +108,7 @@ Now for some examples. This ordinal is common: ``` -This ordinal is uncommon: +This satoshi is uncommon: ``` 1°1′1″0‴ @@ -113,7 +118,7 @@ This ordinal is uncommon: ╰─────── Second cycle ``` -This ordinal is rare: +This satoshi is rare: ``` 1°1′0″0‴ @@ -123,7 +128,7 @@ This ordinal is rare: ╰─────── Second cycle ``` -This ordinal is epic: +This satoshi is epic: ``` 1°0′1″0‴ @@ -133,7 +138,7 @@ This ordinal is epic: ╰─────── Second cycle ``` -This ordinal is legendary: +This satoshi is legendary: ``` 1°0′0″0‴ @@ -143,7 +148,7 @@ This ordinal is legendary: ╰─────── Second cycle ``` -And this ordinal is mythic: +And this satoshi is mythic: ``` 0°0′0″0‴ @@ -153,7 +158,7 @@ And this ordinal is mythic: ╰─────── First cycle ``` -If the block offset is zero, it may be omitted. This is the uncommon ordinal +If the block offset is zero, it may be omitted. This is the uncommon satoshi from above: ``` @@ -163,8 +168,8 @@ from above: ╰───── Second cycle ``` -Ordinal Supply --------------- +Rare Satoshi Supply +------------------- ### Total Supply @@ -184,35 +189,45 @@ Ordinal Supply - `legendary`: 0 - `mythic`: 1 -At the moment, even uncommon ordinals are quite rare. As of this writing, -745,855 uncommon ordinals have been mined - one per 25.6 bitcoin in +At the moment, even uncommon satoshis are quite rare. As of this writing, +745,855 uncommon satoshis have been mined - one per 25.6 bitcoin in circulation. Names ----- -Each ordinal has a name, consisting of the letters *A* through *Z*, that get -shorter the larger the ordinal is. They could start short and get longer, but -then all the good, short names would be trapped in the unspendable genesis -block. +Each satoshi has a name, consisting of the letters *A* through *Z*, that get +shorter the further into the future the satoshi was mined. They could start +short and get longer, but then all the good, short names would be trapped in +the unspendable genesis block. As an example, 1905530482684727°'s name is "iaiufjszmoba". The name of the last -ordinal to be mined is "a". Every combination of 10 characters or less is out +satoshi to be mined is "a". Every combination of 10 characters or less is out there, or will be out there, some day. Exotics ------- -Ordinals may be prized for reasons other than their name or rarity. This might +Satoshis may be prized for reasons other than their name or rarity. This might be due to a quality of the number itself, like having an integer square or cube root. Or it might be due to a connection to a historical event, such as -ordinals from block 477,120, the block in which SegWit activated, or ordinal -2099999997689999°, the last ordinal that will ever be mined. +satoshis from block 477,120, the block in which SegWit activated, +2099999997689999°, the last satoshi that will ever be mined. -Such ordinals are termed "exotic". Which ordinals are exotic and what makes +Such satoshis are termed "exotic". Which satoshis are exotic and what makes them so is subjective. Ordinal theorists are are encouraged to seek out exotics based on criteria of their own devising. +Inscriptions +------------ + +Satoshis can be inscribed with arbitrary content, creating Bitcoin-native +digital artifacts. Inscribing is done by sending the satoshi to be inscribed in +a transaction that reveals the inscription content on-chain. This content is +then inextricably linked to that satoshi, turning it into an immutable digital +artifact that can be tracked, transferred, hoarded, bought, sold, lost, and +rediscovered. + Archaeology ----------- diff --git a/src/subcommand/server/templates/home.rs b/src/subcommand/server/templates/home.rs index 6b387e6ec8..124956611c 100644 --- a/src/subcommand/server/templates/home.rs +++ b/src/subcommand/server/templates/home.rs @@ -51,7 +51,7 @@ mod tests { ) ],) .to_string(), - "

Status

+ "

Explore digital artifacts on Bitcoin

.*

Status

cycle
1
epoch
6
diff --git a/templates/home.html b/templates/home.html index bb83e3cb4e..5a269b5e15 100644 --- a/templates/home.html +++ b/templates/home.html @@ -1,3 +1,13 @@ +

Explore digital artifacts on Bitcoin

+ +

Ordinal theory unlocks Bitcoin-native digital artifacts.

+ +

Rare and exotic sats, and NFTs that are as durable, immutable, secure, +scarce, and decentralized as the Bitcoin blockchain itself. Natively. No +sidechain or token required.

+ +

Learn more.

+ %% if let Some(starting_ordinal) = self.starting_ordinal {

Status