From 0170c977a642d4e85b57517c35a64c93f84ca35d Mon Sep 17 00:00:00 2001
From: Casey Rodarmor <casey@rodarmor.com>
Date: Wed, 14 Dec 2022 13:14:01 -0800
Subject: [PATCH] Revise inscription guide after mainnet walkthrough (#968)

---
 docs/src/guides/inscriptions.md               | 81 +++++++++++++++----
 src/subcommand/server.rs                      | 12 +--
 .../server/templates/inscription.rs           | 20 ++---
 templates/inscription.html                    |  4 +-
 templates/transaction.html                    |  2 +
 tests/server.rs                               | 26 +++---
 tests/wallet.rs                               | 12 +--
 7 files changed, 109 insertions(+), 48 deletions(-)

diff --git a/docs/src/guides/inscriptions.md b/docs/src/guides/inscriptions.md
index 5a51ad7b22..98cef258aa 100644
--- a/docs/src/guides/inscriptions.md
+++ b/docs/src/guides/inscriptions.md
@@ -14,8 +14,8 @@ 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.
+utility. `ord` doesn't implement its own wallet, so `ord wallet` subcommands
+interact with an existing Bitcoin Core wallet.
 
 This guide covers:
 
@@ -73,10 +73,22 @@ 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).
+To sync the chain, run:
+
+```
+bitcoind -signet -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
 ------------------------------
@@ -90,7 +102,7 @@ unintentionally using the `ord` utility with non-ordinal Bitcoin wallets.
 To create a Bitcoin Core wallet named `ord` for use with `ord`, run:
 
 ```
-ord --chain signet wallet create
+ord --signet wallet create
 ```
 
 This is equivalent to running:
@@ -110,6 +122,32 @@ 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/<filename> uri-path).", data: None }
+```
+
+This means that `bitcoind` has more than one wallet loaded. List loaded wallets with:
+
+```
+bitcoin-cli -signet listwallets
+```
+
+And unload all wallets other than `ord`:
+
+```
+bitcoin-cli -signet unloadwallet foo
+```
+
 Installing `ord`
 ----------------
 
@@ -123,8 +161,13 @@ You can install the latest pre-built binary from the command line with:
 curl --proto '=https' --tlsv1.2 -fsLS https://ordinals.com/install.sh | bash -s
 ```
 
-Once `ord` is installed, you should be able to run `ord --version` on the
-command line.
+Once `ord` is installed, you should be able to run:
+
+```
+ord --version
+```
+
+Which prints out `ord`'s version number.
 
 Receiving Satoshis
 ------------------
@@ -132,14 +175,22 @@ 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 --signet wallet
-receive`
+Get a new address from your `ord` wallet by running:
+
+```
+ord --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/).
 
-You can see pending transactions with `ord --chain signet walet transactions`.
+You can see pending transactions with:
+
+```
+ord --signet wallet transactions
+```
+
 Once the faucet transaction confirms, you should be able to see the
 transactions outputs with `ord --signet wallet utxos`.
 
@@ -153,7 +204,7 @@ 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
+witnesses, so mainnet inscriptions will be limited only by the depths of your
 pockets and the 4,000,000 byte witness size limit.
 
 Creating Inscriptions
@@ -205,7 +256,7 @@ ord --signet wallet send INSCRIPTION_ID ADDRESS
 
 See the pending transaction with:
 ```
-ord --chain signet wallet transactions
+ord --signet wallet transactions
 ```
 
 Once the send transaction confirms, the recipient can confirm receipt by
@@ -232,7 +283,7 @@ ord --signet wallet send INSCRIPTION_ID ADDRESS
 
 See the pending transaction with:
 ```
-ord --chain signet wallet transactions
+ord --signet wallet transactions
 ```
 
 Once the send transaction confirms, you can can confirm receipt by running:
diff --git a/src/subcommand/server.rs b/src/subcommand/server.rs
index 2ae3147328..196994ac3a 100644
--- a/src/subcommand/server.rs
+++ b/src/subcommand/server.rs
@@ -635,20 +635,22 @@ impl Server {
   async fn inscription(
     Extension(chain): Extension<Chain>,
     Extension(index): Extension<Arc<Index>>,
-    Path(txid): Path<Txid>,
+    Path(inscription_id): Path<InscriptionId>,
   ) -> ServerResult<PageHtml> {
     let (inscription, satpoint) = index
-      .get_inscription_by_inscription_id(txid)
+      .get_inscription_by_inscription_id(inscription_id)
       .map_err(|err| {
         ServerError::Internal(anyhow!(
-          "failed to retrieve inscription from txid {txid} from index: {err}"
+          "failed to retrieve inscription with inscription id {inscription_id} from index: {err}"
         ))
       })?
-      .ok_or_else(|| ServerError::NotFound(format!("transaction {txid} has no inscription")))?;
+      .ok_or_else(|| {
+        ServerError::NotFound(format!("transaction {inscription_id} has no inscription"))
+      })?;
 
     Ok(
       InscriptionHtml {
-        txid,
+        inscription_id,
         inscription,
         satpoint,
       }
diff --git a/src/subcommand/server/templates/inscription.rs b/src/subcommand/server/templates/inscription.rs
index de64a7a325..efd68d83cd 100644
--- a/src/subcommand/server/templates/inscription.rs
+++ b/src/subcommand/server/templates/inscription.rs
@@ -2,14 +2,14 @@ use super::*;
 
 #[derive(Boilerplate)]
 pub(crate) struct InscriptionHtml {
-  pub(crate) txid: Txid,
+  pub(crate) inscription_id: InscriptionId,
   pub(crate) inscription: Inscription,
   pub(crate) satpoint: SatPoint,
 }
 
 impl PageContent for InscriptionHtml {
   fn title(&self) -> String {
-    format!("Inscription {}", self.txid)
+    format!("Inscription {}", self.inscription_id)
   }
 }
 
@@ -21,16 +21,18 @@ mod tests {
   fn txt_inscription() {
     pretty_assert_eq!(
       InscriptionHtml {
-        txid: Txid::from_str("ec90757eb3b164aa43fc548faa2fa0c52025494f2c15d5ddf11260b4034ac6dc")
-          .unwrap(),
+        inscription_id: InscriptionId::from_str(
+          "ec90757eb3b164aa43fc548faa2fa0c52025494f2c15d5ddf11260b4034ac6dc"
+        )
+        .unwrap(),
         inscription: inscription("text/plain;charset=utf-8", "HELLOWORLD"),
         satpoint: satpoint(1, 0),
       }
       .to_string(),
       "
-        <h1>Inscription</h1>
+        <h1>Inscription ec90757eb3b164aa43fc548faa2fa0c52025494f2c15d5ddf11260b4034ac6dc</h1>
         <dl>
-          <dt>satpoint</dt>
+          <dt>location</dt>
           <dd>1111111111111111111111111111111111111111111111111111111111111111:1:0</dd>
         </dl>
         HELLOWORLD
@@ -43,15 +45,15 @@ mod tests {
   fn png_inscription() {
     pretty_assert_eq!(
       InscriptionHtml {
-        txid: Txid::from_str("ec90757eb3b164aa43fc548faa2fa0c52025494f2c15d5ddf11260b4034ac6dc").unwrap(),
+        inscription_id: InscriptionId::from_str("ec90757eb3b164aa43fc548faa2fa0c52025494f2c15d5ddf11260b4034ac6dc").unwrap(),
         inscription: inscription("image/png", [1; 100]),
         satpoint: satpoint(1, 0),
       }
       .to_string(),
       "
-        <h1>Inscription</h1>
+        <h1>Inscription ec90757eb3b164aa43fc548faa2fa0c52025494f2c15d5ddf11260b4034ac6dc</h1>
         <dl>
-          <dt>satpoint</dt>
+          <dt>location</dt>
           <dd>1111111111111111111111111111111111111111111111111111111111111111:1:0</dd>
         </dl>
         <img src='data:image/png;base64,AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQ=='>
diff --git a/templates/inscription.html b/templates/inscription.html
index 9ea2ac4dc8..58ab4f9221 100644
--- a/templates/inscription.html
+++ b/templates/inscription.html
@@ -1,6 +1,6 @@
-<h1>Inscription</h1>
+<h1>Inscription {{ self.inscription_id }}</h1>
 <dl>
-  <dt>satpoint</dt>
+  <dt>location</dt>
   <dd>{{ self.satpoint }}</dd>
 </dl>
 {{ self.inscription.content_html() }}
diff --git a/templates/transaction.html b/templates/transaction.html
index 1586c9092c..e98b4b550a 100644
--- a/templates/transaction.html
+++ b/templates/transaction.html
@@ -1,7 +1,9 @@
 <h1>Transaction <span class=monospace>{{self.txid}}</span></h1>
 %% if let Some(inscription) = &self.inscription {
 <h2>Inscription</h2>
+<a href=/inscription/{{self.txid}}>
 {{ inscription.content_html() }}
+</a>
 %% }
 <h2>{{"Output".tally(self.transaction.output.len())}}</h2>
 <ul class=monospace>
diff --git a/tests/server.rs b/tests/server.rs
index ef48b1ba90..4ad3569135 100644
--- a/tests/server.rs
+++ b/tests/server.rs
@@ -52,11 +52,11 @@ fn inscription_page() {
   rpc_server.mine_blocks(1);
 
   TestServer::spawn_with_args(&rpc_server, &[]).assert_response_regex(
-    &format!("/inscription/{}", reveal_tx),
+    &format!("/inscription/{reveal_tx}"),
     &format!(
-      ".*<h1>Inscription</h1>
+      ".*<h1>Inscription {reveal_tx}</h1>
 <dl>
-  <dt>satpoint</dt>
+  <dt>location</dt>
   <dd>{reveal_tx}:0:0</dd>
 </dl>
 HELLOWORLD.*",
@@ -83,9 +83,13 @@ fn inscription_appears_on_reveal_transaction_page() {
 
   TestServer::spawn_with_args(&rpc_server, &[]).assert_response_regex(
     &format!("/tx/{}", reveal_tx),
-    ".*<h1>Transaction .*</h1>.*
+    &format!(
+      ".*<h1>Transaction .*</h1>.*
 <h2>Inscription</h2>
-HELLOWORLD.*",
+<a href=/inscription/{reveal_tx}>
+HELLOWORLD
+</a>.*",
+    ),
   );
 }
 
@@ -108,11 +112,11 @@ fn inscription_page_after_send() {
 
   let ord_server = TestServer::spawn_with_args(&rpc_server, &[]);
   ord_server.assert_response_regex(
-    &format!("/inscription/{}", reveal_txid),
+    &format!("/inscription/{reveal_txid}"),
     &format!(
-      ".*<h1>Inscription</h1>
+      ".*<h1>Inscription {reveal_txid}</h1>
 <dl>
-  <dt>satpoint</dt>
+  <dt>location</dt>
   <dd>{reveal_txid}:0:0</dd>
 </dl>
 HELLOWORLD.*",
@@ -131,11 +135,11 @@ HELLOWORLD.*",
 
   let ord_server = TestServer::spawn_with_args(&rpc_server, &[]);
   ord_server.assert_response_regex(
-    &format!("/inscription/{}", reveal_txid),
+    &format!("/inscription/{reveal_txid}"),
     &format!(
-      ".*<h1>Inscription</h1>
+      ".*<h1>Inscription {reveal_txid}</h1>
 <dl>
-  <dt>satpoint</dt>
+  <dt>location</dt>
   <dd>{}:0:0</dd>
 </dl>
 HELLOWORLD.*",
diff --git a/tests/wallet.rs b/tests/wallet.rs
index b611aa2e9e..d63456890c 100644
--- a/tests/wallet.rs
+++ b/tests/wallet.rs
@@ -87,11 +87,11 @@ fn send_works_on_signet() {
 
   let ord_server = TestServer::spawn_with_args(&rpc_server, &[]);
   ord_server.assert_response_regex(
-    &format!("/inscription/{}", reveal_txid),
+    &format!("/inscription/{reveal_txid}"),
     &format!(
-      ".*<h1>Inscription</h1>
+      ".*<h1>Inscription {reveal_txid}</h1>
 <dl>
-  <dt>satpoint</dt>
+  <dt>location</dt>
   <dd>{send_txid}:0:0</dd>
 </dl>
 .*",
@@ -144,11 +144,11 @@ fn send_inscribed_sat() {
 
   let ord_server = TestServer::spawn_with_args(&rpc_server, &[]);
   ord_server.assert_response_regex(
-    &format!("/inscription/{}", reveal_txid),
+    &format!("/inscription/{reveal_txid}"),
     &format!(
-      ".*<h1>Inscription</h1>
+      ".*<h1>Inscription {reveal_txid}</h1>
 <dl>
-  <dt>satpoint</dt>
+  <dt>location</dt>
   <dd>{send_txid}:0:0</dd>
 </dl>
 .*",