Add Inscription guide

docs/book.toml

@@ -1,5 +1,5 @@
 [book]
-title = "Ordinal Hunter's Manual"
+title = "Ordinal Theory Handbook"
 language = "en"
 src = "src"
 

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)

docs/src/bounty.md → 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)

docs/src/block-explorer.md → 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

docs/src/guides/inscriptions.md

@@ -0,0 +1,209 @@
+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 Bitcoin 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 wrap an existing Bitcoin Core
+wallet.
+
+This guide contains everything you need to know about creating, sending, and
+receiving inscriptions:
+
+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
+------------
+
+A guide can only do so much! 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 to use Signet
+--------------------------------------
+
+`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.
+
+To configure your Bitcoin Core node to use signet, add `signet=1` to your
+`bitcoin.conf` configuration file, or pass `-signet` to `bitcoind` and
+`bitcoin-cli`, e.g. `bitcoind -signet` and `bitcoin-cli -signet`.
+
+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 shoudln't take long.
+
+To sync the chain, run `bitcoind -signet` 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-wallet -signet -wallet=ord create
+```
+
+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 shoud 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 4,000,000 byte
+witness size limit.
+
+Creating Inscriptions
+---------------------
+
+To create an inscription with the contents of `CONTENTS`, run:
+
+```
+ord --chain=signet wallet inscribe --file CONTENTS
+```
+
+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, reaveling
+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
+```

docs/src/hunting.md → 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 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.

docs/src/introduction.md

@@ -1,4 +1,35 @@
-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
+distinguishing satoshis, giving them an identity and allowing them to be
+tracked and transferred individually.
+
+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 is not a side chain, does not require any 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 a Bitcoin wallet 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 +38,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
 ------