From 8fa253c9cb4ca55218e646af6432c550980b5f55 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Mon, 23 Jan 2023 12:44:09 -0800 Subject: [PATCH] Update inscriptions guide for mainnet (#1342) --- docs/src/guides/inscriptions.md | 195 ++++++++++++-------------------- 1 file changed, 74 insertions(+), 121 deletions(-) diff --git a/docs/src/guides/inscriptions.md b/docs/src/guides/inscriptions.md index 9f488e2184..624351577e 100644 --- a/docs/src/guides/inscriptions.md +++ b/docs/src/guides/inscriptions.md @@ -1,28 +1,29 @@ Ordinal Inscription Guide ========================= -Individual satoshis can be inscribed with arbitrary content, creating +Individual sats 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 Bitcoin 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. +the current state of the Bitcoin blockchain, and a wallet that can create +inscriptions and perform sat control when constructing transactions to send +inscriptions to another wallet. 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` doesn't implement its own wallet, so `ord wallet` subcommands -interact with an existing Bitcoin Core wallet. +Core wallet cannot create inscriptions and does not perform sat control. + +This requires [`ord`](https://github.com/casey/ord), the ordinal utility. `ord` +doesn't implement its own wallet, so `ord wallet` subcommands interact with +Bitcoin Core wallets. 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 +4. Using `ord wallet receive` to receive sats 5. Creating inscriptions with `ord wallet inscribe` 6. Sending inscriptions with `ord wallet send` 7. Receiving inscriptions with `ord wallet receive` @@ -30,7 +31,7 @@ This guide covers: Getting Help ------------ -If you get stuck, try asking for help on the [Ordinal Theory Discord +If you get stuck, try asking for help on the [Ordinals 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). @@ -50,105 +51,39 @@ 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. +`ord` requires Bitcoin Core's transaction index. -To configure your Bitcoin Core node to use signet and maintain a transaction +To configure your Bitcoin Core node to use maintain a transaction index, add the following to your `bitcoin.conf`: ``` -signet=1 txindex=1 ``` -Or, run `bitcoind` with `-signet` and `-txindex`: +Or, run `bitcoind` with `-txindex`: ``` -bitcoind -signet -txindex +bitcoind -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 +bitcoind -txindex ``` …and leave it running until `getblockchount`: ``` -bitcoin-cli -signet getblockcount -``` - -agrees with the block count on a block explorer like [the mempool.space signet -block explorer](https://mempool.space/signet). `ord` interacts with `bitcoind`, -so you should leave `bitcoind` running in the background when you're using -`ord`. - -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 Bitcoin Core wallet named `ord` for use with `ord`, run: - -``` -ord --signet wallet create -``` - -This is equivalent to running: - -``` -bitcoin-cli -signet createwallet ord -``` - -Loading the Bitcoin Core Wallet -------------------------------- - -Bitcoin Core wallets must be loaded before they can be used with `ord`. Wallets -are loaded automatically after being created, so you do not need to load your -wallet if you just created it. Otherwise, run: - -``` -bitcoin-cli -signet loadwallet ord -``` - -Once your wallet is loaded, you should be able to run: - -``` -ord --signet wallet receive -``` - -…and get a fresh receive address. - -If you get an error message like: - -``` -error: JSON-RPC error: RPC error response: RpcError { code: -19, message: "Wallet file not specified (must request wallet RPC through /wallet/ uri-path).", data: None } -``` - -This means that `bitcoind` has more than one wallet loaded. List loaded wallets with: - -``` -bitcoin-cli -signet listwallets +bitcoin-cli getblockcount ``` -And unload all wallets other than `ord`: - -``` -bitcoin-cli -signet unloadwallet foo -``` +agrees with the block count on a block explorer like [the mempool.space block +explorer](https://mempool.space/). `ord` interacts with `bitcoind`, so you +should leave `bitcoind` running in the background when you're using `ord`. Installing `ord` ---------------- @@ -171,43 +106,59 @@ ord --version Which prints out `ord`'s version number. -Receiving Satoshis ------------------- +Creating a Bitcoin Core Wallet +------------------------------ -Inscriptions are made on individual satoshis, using normal Bitcoin transactions -that pay fees in satoshis, so your wallet will need some sats. +`ord` uses Bitcoin Core to manage private keys, sign transactions, and +broadcast transactions to the Bitcoin network. + +To create a Bitcoin Core wallet named `ord` for use with `ord`, run: + +``` +ord wallet create +``` + +Receiving Sats +-------------- + +Inscriptions are made on individual sats, using normal Bitcoin transactions +that pay fees in sats, so your wallet will need some sats. Get a new address from your `ord` wallet by running: ``` -ord --signet wallet receive +ord 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/). +And send it some funds. You can see pending transactions with: ``` -ord --signet wallet transactions +ord wallet transactions ``` -Once the faucet transaction confirms, you should be able to see the -transactions outputs with `ord --signet wallet utxos`. +Once the transaction confirms, you should be able to see the transactions +outputs with `ord wallet utxos`. Creating Inscription Content ---------------------------- -Create a `.png` or `.txt` file smaller than 1024 bytes to inscribe. +Sats can be inscribed with any kind of content, but the `ord` wallet only +supports content types that can be displayed by the `ord` block explorer. -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 are included in transactions, so the larger the +content, the higher the fee that the inscription transaction must pay. -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 be limited only by the depths of your -pockets and the 4,000,000 byte witness size limit. +Inscription content is included in transaction witnesses, which receive the +witness discount. To calculate the approximate fee that in inscribe transaction +will pay, divide the content size by four and muliply by the fee rate. + +Inscription transactions must be less than 400,000 weight units, or they will +not be relayed by Bitcoin Core. One byte of inscription content costs one +weight unit. Since an inscription transaction includes not just the inscription +content, limit inscription content to less than 400,000 weight units. 390,000 +weight units should be safe. Creating Inscriptions --------------------- @@ -215,31 +166,32 @@ Creating Inscriptions To create an inscription with the contents of `FILE`, run: ``` -ord --signet wallet inscribe FILE +ord wallet inscribe FILE ``` Ord will output two transactions IDs, one for the commit transaction, and one -for the reveal transaction. +for the reveal transaction, and the inscription ID. Inscription IDs are of the +form `TXIDiN`, where `TXID` is the transaction ID of the reveal transaction, +and `N` is the index of the inscription in 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. +the contents on chain and inscribing them on the first sat 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). +commit and reveal transactions using [the mempool.space block +explorer](https://mempool.space/). Once the reveal transaction has been mined, the inscription ID should be printed when you run: ``` -ord --signet wallet inscriptions +ord wallet inscriptions ``` -And when you visit [the signet ordinals explorer](https://signet.ordinals.com/) -at `signet.ordinals.com/inscription/INSCRIPTION_ID`. - +And when you visit [the ordinals explorer](https://ordinals.com/) at +`ordinals.com/inscription/INSCRIPTION_ID`. Sending Inscriptions -------------------- @@ -247,25 +199,26 @@ Sending Inscriptions Ask the recipient to generate a new address by running: ``` -ord --signet wallet receive +ord wallet receive ``` Send the inscription by running: ``` -ord --signet wallet send INSCRIPTION_ID ADDRESS +ord wallet send ADDRESS INSCRIPTION_ID ``` See the pending transaction with: + ``` -ord --signet wallet transactions +ord wallet transactions ``` Once the send transaction confirms, the recipient can confirm receipt by running: ``` -ord --signet wallet inscriptions +ord wallet inscriptions ``` Receiving Inscriptions @@ -274,22 +227,22 @@ Receiving Inscriptions Generate a new receive address using: ``` -ord --signet wallet receive +ord wallet receive ``` The sender can transfer the inscription to your address using: ``` -ord --signet wallet send INSCRIPTION_ID ADDRESS +ord wallet send ADDRESS INSCRIPTION_ID ``` See the pending transaction with: ``` -ord --signet wallet transactions +ord wallet transactions ``` Once the send transaction confirms, you can can confirm receipt by running: ``` -ord --signet wallet inscriptions +ord wallet inscriptions ```