doc: Add offline signing tutorial #28363

   0 | @@ -0,0 +1,256 @@
   1 | +# Offline Signing Tutorial
   2 | +
   3 | +Welcome to this tutorial on how to sign transactions offline using PSBT (Partially Signed Bitcoin Transactions). This tutorial will guide you through the process of securely signing Bitcoin transactions using an offline wallet and an online watch-only wallet.
   4 | +
   5 | +## Overview
   6 | +In this tutirial we have two hosts [offline] which is

rot13maxi commented at 1:03 PM on August 29, 2023:

In this tutorial we have two hosts: [offline] which is

   7 | +totally offline and without a copy of the blockchain
   8 | +and [online] which is a regular online node, both
   9 | +running bitcoin 25.0
  10 | +
  11 | +In this example, we are going to generate a key on the offline wallet, then
  12 | +send it 0.0009 BTC with an online wallet, then using the online

rot13maxi commented at 1:23 PM on August 29, 2023:

it might be more instructive to have a second wallet that does the initial send and then the second receive, so it's not just a self-send

BrandonOdiwuor commented at 11:05 AM on August 31, 2023:

Thanks for the suggestion, I've updated the doc to use separate online sending and receiving wallets

   0 | @@ -0,0 +1,259 @@
   1 | +# Offline Signing Tutorial
   2 | +
   3 | +Welcome to this tutorial on how to sign transactions offline using PSBT (Partially Signed Bitcoin Transactions). This tutorial will guide you through the process of securely signing Bitcoin transactions using an offline wallet and an online watch-only wallet.
   4 | +
   5 | +## Overview
   6 | +In this tutorial, we have two hosts: [offline] which is totally offline and without a copy of the blockchain and [online] which is a regular online node, both running Bitcoin 25.0
   7 | +
   8 | +In this example, we are going to generate a key on the offline wallet, and then send it 0.0009 BTC with an online(sending) wallet, then using the online wallet draft a transaction to send 0.0008 BTC to another online(receiving) wallet, then sign that with the offline wallet, and finally announce the signed transaction into the network using the online wallet.

pinheadmz commented at 11:03 AM on September 5, 2023:

nits, spacing

In this example, we are going to generate a key on the offline wallet, and then send it 0.0009 BTC with an online (sending) wallet, then using the online wallet draft a transaction to send 0.0008 BTC to another online (receiving) wallet, then sign that with the offline wallet, and finally announce the signed transaction into the network using the online wallet.

  11 | +> Tested using Signet with a connected host machine and an offline docker container (representing the offline wallet) both running Signet, should also work with Regtest and Mainnet
  12 | +
  13 | +
  14 | +## Step 1: Sending money to the offline wallet
  15 | +
  16 | +### Create and Load Funds into the Online Sending Wallet

pinheadmz commented at 11:06 AM on September 5, 2023:

I think the guide can be written without this online sending wallet. That would make it more practical too. I think starting this way is perhaps good for teaching a user about bitcoin but it I don't think it's necessary in a Bitcoin Core doc. The goal here in my opinion should be as close to real world usage as possible. So my suggestion would be: create the offline wallet, copy the descriptors to the online wallet, and then fund the wallet directly from the faucet.

willcl-ark commented at 12:52 PM on September 5, 2023:

I second this; I think we only need a single wallet in the guide, where the offline Bitcoin Core has the private keys available, and the hot wallet is watch-only.

  45 | +}
  46 | +```
  47 | +
  48 | +2. Export the offline wallet descriptors to a JSON file named `descriptors.json`. This file will be exported to the online machine to create a watch-only wallet.
  49 | +```sh
  50 | +[offline]$ ./src/bitcoin-cli -signet -rpcwallet="offline_wallet" listdescriptors | jq -r '.descriptors' >> ~/descriptors.json

pinheadmz commented at 11:07 AM on September 5, 2023:

users might not have jq installed so you could either mention that it is a requirement or explain what you are doing here (pulling out the "descriptors" object from the output)

  94 | +]
  95 | +```
  96 | +
  97 | +### Send Funds to the Offline Wallet
  98 | +
  99 | +1. Generate a new address in the `offline_wallet` to receive funds.

pinheadmz commented at 11:08 AM on September 5, 2023:

You should be able to generate receive address from the online wallet now! I feel like one of the best benefits of this setup is that once you create the private keys in the offline wallet, you shouldn't even need to turn that computer on until you are ready to sign something.

willcl-ark commented at 12:55 PM on September 5, 2023:

Yep, this is probably the second biggest benefit of such a setup, and the biggest convenience factor!

 136 | +
 137 | +## Step 2: Sending money from the offline wallet
 138 | +
 139 | +### Create an Online Receiving Wallet
 140 | +
 141 | +1. On the online machine, create an online wallet named `online_receiving_wallet`.

pinheadmz commented at 11:12 AM on September 5, 2023:

Again I think we can avoid creating yet another wallet here. You could either demonstrate a self-send or get an example destination address from some other source (some faucets have a return address)

 158 | +
 159 | +1. Create a PSBT transaction using the online `watch_only_wallet`, sending funds to the `online_receiving_wallet` address.
 160 | +- Export the psbt transaction to `funded_psbt.txt` for easy portability to the `offline_wallet`
 161 | +
 162 | +```sh
 163 | +[online]$ ./src/bitcoin-cli -signet -rpcwallet="watch_only_wallet" walletcreatefundedpsbt '[]' '[{"tb1q9k5w0nhnhyeh78snpxh0t5t7c3lxdeg3erez32": 0.0008}]' | jq -r '.psbt' >> ~/funded_psbt.txt

pinheadmz commented at 11:14 AM on September 5, 2023:

Might be nice to explain the arguments here (inputs[], outputs[]). And again explain what you're doing with jq

willcl-ark commented at 12:57 PM on September 5, 2023:

It can (sometimes) be nice to pipe things through tee so people can see what's going on, but it also introduces another "magical" tool, which may end up being more confusing...

  60 | +{
  61 | +  "name": "watch_only_wallet"
  62 | +}
  63 | +```
  64 | +
  65 | +2. Import the `offline_wallet` descriptors to the online `watch_only_wallet` using the `descriptors.json` file created on the offline wallet

pinheadmz commented at 11:16 AM on September 5, 2023:

Might be nice to explain here that multiple descriptors are being imported and the wallets can create a variety of address types. Later when you call getnewaddress you can also explain the default address type and how to select another type if desired.

 198 | +### Process and Sign the PSBT Transaction
 199 | +
 200 | +1. Process and sign the PSBT transaction on the `offline_wallet`.
 201 | +
 202 | +```sh
 203 | +[offline]$ processed_psbt=$(./src/bitcoin-cli -signet -rpcwallet="offline_wallet" walletprocesspsbt $(cat ~/funded_psbt.txt) | jq -r .psbt)

pinheadmz commented at 11:20 AM on September 5, 2023:

Hm I haven't noticed this before but walletprocesspsbt can finalize (default is to finalize if possible) and so if this command returned hex in addition to base64, we could omit the finalizepsbt step... right? Might be another good follow-up PR ;-)

pinheadmz commented at 1:04 PM on September 5, 2023:

I wrote the PR: #28414

If this gets merged, we can update your doc ;-)

  50 | +[offline]$ ./src/bitcoin-cli -signet -rpcwallet="offline_wallet" listdescriptors | jq -r '.descriptors' >> ~/descriptors.json
  51 | +```
  52 | +
  53 | +### Create the online "watch_only_wallet"
  54 | +
  55 | +1. On the online machine, create an online watch-only wallet named `watch_only_wallet` without private keys.

willcl-ark commented at 12:54 PM on September 5, 2023:

You could mention what the blank=True is doing that you've used below.

 155 | +```
 156 | +
 157 | +### Create and Export a PSBT Transaction
 158 | +
 159 | +1. Create a PSBT transaction using the online `watch_only_wallet`, sending funds to the `online_receiving_wallet` address.
 160 | +- Export the psbt transaction to `funded_psbt.txt` for easy portability to the `offline_wallet`

willcl-ark commented at 12:59 PM on September 5, 2023:

it may seem imple, but is it worth mentioning that the transaction at this stage is a file which needs to be physically moved from one machine to another with e.g. a USB drive?

 214 | +[offline]$ cat ~/final_psbt.txt
 215 | +0200000000010165e8a271a85542f2eda9f867e4dc40002e4f46b1b46640712fd0a77010d908040100000000fdffffff0280380100000000001600142da8e7cef3b9337f1e1309aef5d17ec47e66e5118326000000000000160014c9a498552f6fd359acfbbe57179a30b8b075b1c7024730440220659e544f37d1b48923df89dff71c63d996c0b233183c58f84a773d8e6306e5a00220765cb5a31403320ce49ab66d6fa097a70b00a131abfa832524bcc840af251f67012102b66303a69d660e98c49320afc28dd9abd8f34c9d59c4ca2148a243fa811ea6c800000000
 216 | +```
 217 | +
 218 | +### Broadcast the Finalized PSBT Transaction
 219 | +1. Broadcast the signed and finalized PSBT transaction (on the `final_psbt.txt` file) using the online wallet

willcl-ark commented at 12:59 PM on September 5, 2023:

If you do choose to include a comment about moving the transaction (file) between hosts, perhaps mention here that you need to move it back...

Your path below might also want to be something like /path/to/final_psbt.txt so that it's super clear that users have to know where they've put it, then reference it themselves.

 223 | +e79497b11e3561cfd6349213ed71578d68411821d079855d56d419ba1db71170
 224 | +```
 225 | +
 226 | +### Confirm Wallet Balances
 227 | +
 228 | +1. Confirm the updated balance of the `online_receiving_wallet`.

willcl-ark commented at 1:01 PM on September 5, 2023:

Would be able to drop this whole step if you eliminated the online_recieving_wallet.

 161 | +[offline]$ processed_psbt=$(./src/bitcoin-cli -signet -rpcwallet="offline_wallet" walletprocesspsbt $(cat /path/to/funded_psbt.txt) | jq -r .psbt)
 162 | +[offline]$ echo $processed_psbt
 163 | +cHNidP8BAHECAAAAAWLHKR9/xAjetzL/FCmZU5lbfINRMWPRPHWO68PfUzkPAQAAAAD9////AoxPAQAAAAAAFgAU3aD0J/Z7/sqfDnJS5FjuObgsfgaguw0AAAAAABYAFC2o587zuTN/HhMJrvXRfsR+ZuURAAAAAAABAHECAAAAAY+dRPEBrGopkw4ugSzS9npzJDEIrE/bq1XXI0KbYnYrAQAAAAD+////ArKaXgAAAAAAFgAUwEc4LdoxSjbWo/2Ue+HS+QjwfiBAQg8AAAAAABYAFF8oBGNNbfYN0ICTLoPECLKXXLuyYW8CAAEBH0BCDwAAAAAAFgAUXygEY01t9g3QgJMug8QIspdcu7IBCGsCRzBEAiANJF7pLfi+AYPJj7Jry8R0MHzNt2SHcnNkS0xOs1kTggIgbEz3h/EggoqBK0cEOQJoPiTVCmAhbjsv4PEEvigG5U8BIQJZMszudZAVj34IuzYpDRNdMKCwRRY9qJbhzXZF7EIjqQAiAgIAr8a1DCryJj031qO8iImwTASQGphBh6t/G3xoxfHVQRgwbHNPVAAAgAEAAIAAAACAAQAAAAIAAAAAAA==
 164 | +```
 165 | +
 166 | +### Finalize the PSBT Transaction

pinheadmz commented at 4:45 PM on September 12, 2023:

#28414 merged! This can be rebased ;-) calling finalizepsbt could be optional

  77 | +]
  78 | +```
  79 | +> [!NOTE]
  80 | +> Importing the multiple descriptors from the `offline_wallet` provides the ability to generate a variety of address types by the [online] `watch_only_wallets`
  81 | +
  82 | +### Load Funds to the `offline_wallet`

pinheadmz commented at 6:52 PM on September 15, 2023:

At this point it might be helpful to explain that both offline and online wallets have the exact same public keys and therefore they have the same addresses AND the same "funds" although spending the funds requires cooperation between both wallets...

  78 | +```
  79 | +> [!NOTE]
  80 | +> Importing the multiple descriptors from the `offline_wallet` provides the ability to generate a variety of address types by the [online] `watch_only_wallets`
  81 | +
  82 | +### Load Funds to the `offline_wallet`
  83 | +1. Generate an address for the `offline_wallet` using the `watch_only_wallet` to load funds.

pinheadmz commented at 6:55 PM on September 15, 2023:

...then here instead of "generating an address from one wallet using the other wallet" (confusing!) you might mention that either wallet can provide an address (they will be the same address) but we will use online wallet for this guide since presumably we will be giving that address to someone else online.

  87 | +tb1qtu5qgc6ddhmqm5yqjvhg83qgk2t4ewajg0h6yh
  88 | +```
  89 | +
  90 | +2. Visit a faucet like https://signet.bc-2.jp to load funds into the generated address.
  91 | +
  92 | +3. Confirm the received funds (to the offline_wallet) using the online watch_only_wallet.

pinheadmz commented at 6:59 PM on September 15, 2023:

again lets try to emphasize that they are the same wallet. we can use the online wallet to confirm the transaction was broadcast / confirmed

 112 | +]
 113 | +```
 114 | +
 115 | +### Create and Export a PSBT Transaction
 116 | +
 117 | +1. Create a PSBT transaction using the online `watch_only_wallet`, sending funds to the `online_receiving_wallet` address. (`walletcreatefundedpsbt inputs[], outputs[address: amount]`)

pinheadmz commented at 7:00 PM on September 15, 2023:

I'd maybe add a step 0 just getting another receive address from the online wallet and do a self-send.

   0 | @@ -0,0 +1,198 @@
   1 | +# Offline Signing Tutorial
   2 | +
   3 | +Welcome to this tutorial on how to sign transactions offline using PSBT (Partially Signed Bitcoin Transactions). This tutorial will guide you through the process of securely signing Bitcoin transactions using an offline wallet and an online watch-only wallet.

willcl-ark commented at 9:44 AM on September 26, 2023:

This tutorial will describe how to use two instances of Bitcoin Core, one online and one offline, to greatly increase security by not having private keys reside on a networked device.
Maintaining an air-gap between private keys and any network connections drastically reduces the opportunity for those keys to be exfiltrated from the user.

This workflow uses [Partially Signed Bitcoin Transactions](https://github.com/bitcoin/bitcoin/blob/master/doc/psbt.md) (PSBTs) to transfer the transaction to and from the offline wallet for signing using the private keys.

   0 | @@ -0,0 +1,198 @@
   1 | +# Offline Signing Tutorial
   2 | +
   3 | +Welcome to this tutorial on how to sign transactions offline using PSBT (Partially Signed Bitcoin Transactions). This tutorial will guide you through the process of securely signing Bitcoin transactions using an offline wallet and an online watch-only wallet.
   4 | +
   5 | +## Overview
   6 | +In this tutorial, we have two hosts: [offline] which is totally offline and without a copy of the blockchain and [online] which is a regular online node, both running Bitcoin 25.0

willcl-ark commented at 9:47 AM on September 26, 2023:

In this tutorial, we have two hosts, both running Bitcoin Core v25.0:

* [offline] which is disconnected from all networks (internet, Tor, wifi, bluetooth etc.) and does not have, or need, a copy of the blockchain.
* [online] which is a regular online node with a synced blockchain.

   0 | @@ -0,0 +1,198 @@
   1 | +# Offline Signing Tutorial
   2 | +
   3 | +Welcome to this tutorial on how to sign transactions offline using PSBT (Partially Signed Bitcoin Transactions). This tutorial will guide you through the process of securely signing Bitcoin transactions using an offline wallet and an online watch-only wallet.
   4 | +
   5 | +## Overview
   6 | +In this tutorial, we have two hosts: [offline] which is totally offline and without a copy of the blockchain and [online] which is a regular online node, both running Bitcoin 25.0
   7 | +
   8 | +In this example, we are going to create an `offline_wallet` on the [offline] host. We will then create a `watch_only_wallet` on the [online] host using descriptors imported from the `offline_wallet` and load funds to the wallet. we'll create a PSBT transaction using the  `watch_only_wallet`, sign it with the `offline_wallet` then broadcast the transaction using the [online] host

willcl-ark commented at 9:49 AM on September 26, 2023:

We are going to first create an `offline_wallet` on the [offline] host. We will then create a `watch_only_wallet` on the [online] host using public key descriptors exported from the `offline_wallet` and receive some coins into the wallet. In order to spend these coins we'll create an unsigned PSBT using the  `watch_only_wallet`, sign it with the `offline_wallet`  and finally broadcast the signed PSBT using the [online] host.

   9 | +
  10 | +### Requirements
  11 | +- [jq](https://jqlang.github.io/jq/) installation - This tutorial uses jq to process JSON.
  12 | +
  13 | +> [!NOTE]
  14 | +> Tested using Signet with a connected host machine and an offline docker container (representing the offline wallet) both running Signet, should also work with Regtest and Mainnet

willcl-ark commented at 10:14 AM on September 26, 2023:

I don't think that it's really necessary to say that docker was used here, nor the comment about it "should also work with Regtest and Mainnet" (it will :P )

  16 | +### Create and Prepare the `offline_wallet`
  17 | +
  18 | +1. On the offline machine, create an offline wallet named `offline_wallet`.
  19 | +
  20 | +```sh
  21 | +[offline]$ ./src/bitcoin-cli -signet -named createwallet wallet_name="offline_wallet"

willcl-ark commented at 10:16 AM on September 26, 2023:

Could be worth mentioning that Bitcoin Core v23.0 upwards is needed for this command to create a descriptor wallet by default?

  29 | +```sh
  30 | +[offline]$ ./src/bitcoin-cli -signet -rpcwallet="offline_wallet" listdescriptors | jq -r '.descriptors' >> /path/to/descriptors.json
  31 | +```
  32 | +
  33 | +> [!NOTE]
  34 | +> The `descriptors.json` file will be exported to the online machine (e.g. using a USB) to create a watch-only wallet. (This is an easier way to export the descriptors compared to manual export)

willcl-ark commented at 10:16 AM on September 26, 2023:

> The `descriptors.json` file will be transferred to the online machine (e.g. using a USB) and imported to create a related watch-only wallet.

  33 | +> [!NOTE]
  34 | +> The `descriptors.json` file will be exported to the online machine (e.g. using a USB) to create a watch-only wallet. (This is an easier way to export the descriptors compared to manual export)
  35 | +
  36 | +### Create the online `watch_only_wallet`
  37 | +
  38 | +1. On the online machine, create an online watch-only wallet named `watch_only_wallet` without private keys (disable_private_keys=true) and should be blank with no keys or HD seed (blank=true).

willcl-ark commented at 10:18 AM on September 26, 2023:

1. On the online machine, create a blank watch-only wallet which has private keys disabled and is named `watch_only_wallet` by using the `createwallet` options: `disable_private_keys=true, blank=true`.

Note: `blank` indicates that the wallet should not generate any new keys of its own. `disable_private_keys` indicates that the wallet should refuse to import private keys, i.e. will be a dedicated watch-only wallet.

  79 | +> [!NOTE]
  80 | +> Importing the multiple descriptors from the `offline_wallet` provides the ability to generate a variety of address types by the [online] `watch_only_wallets`
  81 | +
  82 | +### Load Funds to the `offline_wallet`
  83 | +
  84 | +At this point, it's important to understand that both the `offline_wallet` and [online] `watch_only_wallets` share the same public keys. As a result, they generate the same addresses and have access to the same "funds." However, to spend these funds, cooperation between both wallets is required since you need the private keys to sign the transactions which are only available on the `offline_wallet`.

willcl-ark commented at 10:22 AM on September 26, 2023:

At this point, it's important to understand that both the `offline_wallet` and [online] `watch_only_wallet` share the same public keys. As a result, they generate the same addresses. To spend these coins cooperation between both wallets is required since the private keys needed to sign a transaction are only available on the `offline_wallet`.

willcl-ark commented at 10:22 AM on September 26, 2023:

Sorry to nit this (here, and elsewhere), I just don't really like the term "funds" in Bitcoin myself, but it's just a personal preference... I am going to leave suggestions in future occurrences too, but if folks are happy with "funds" then you can ignore them all?

  81 | +
  82 | +### Load Funds to the `offline_wallet`
  83 | +
  84 | +At this point, it's important to understand that both the `offline_wallet` and [online] `watch_only_wallets` share the same public keys. As a result, they generate the same addresses and have access to the same "funds." However, to spend these funds, cooperation between both wallets is required since you need the private keys to sign the transactions which are only available on the `offline_wallet`.
  85 | +
  86 | +1. Generate an address for the `offline_wallet` to load funds. You can use either the `offline_wallet` or the [online] `watch_only_wallet` to generate this address, as they will produce the same address. For the sake of this guide, we'll use the [online] `watch_only_wallet` to generate the address, which can then be shared with others online.

willcl-ark commented at 10:25 AM on September 26, 2023:

1. Generate an address for the `offline_wallet` to receive coins to. Note that here you can use _either_ the `offline_wallet` or the [online] `watch_only_wallet` to generate this address, as they will produce the same addresses. For the sake of this guide, we'll use the [online] `watch_only_wallet` to generate the address.

  88 | +```sh
  89 | +[online]$ ./src/bitcoin-cli -signet -rpcwallet="watch_only_wallet" getnewaddress
  90 | +tb1qtu5qgc6ddhmqm5yqjvhg83qgk2t4ewajg0h6yh
  91 | +```
  92 | +
  93 | +2. Visit a faucet like https://signet.bc-2.jp to load funds into the generated address.

willcl-ark commented at 10:26 AM on September 26, 2023:

2. Visit a faucet like https://signet.bc-2.jp and enter your address from the previous command to receive a small amount of signet coins to this address.

  90 | +tb1qtu5qgc6ddhmqm5yqjvhg83qgk2t4ewajg0h6yh
  91 | +```
  92 | +
  93 | +2. Visit a faucet like https://signet.bc-2.jp to load funds into the generated address.
  94 | +
  95 | +3. Confirm the received funds (to the `offline_wallet`) using the online `watch_only_wallet`. Since both wallets are essentially the same, you can use the [online] `watch_only_wallet` to monitor and confirm that the transaction was broadcast and confirmed:

willcl-ark commented at 10:27 AM on September 26, 2023:

3. Confirm that coins were recieved using the online `watch_only_wallet`. Note that the transaction may take a few moments before being received on your local node, depending on its connectivity. Just re-run the command periodically until the transaction is recieved.

willcl-ark commented at 10:27 AM on September 26, 2023:

We already said that both wallets share pubkeys and addresses, so I don't think the duplication is necessary here?

 115 | +]
 116 | +```
 117 | +
 118 | +### Create and Export a PSBT Transaction
 119 | +
 120 | +0. Get a receiving address to send the funds to. In this tutorial, we'll be sending funds to the address `tb1q9k5w0nhnhyeh78snpxh0t5t7c3lxdeg3erez32`

willcl-ark commented at 10:33 AM on September 26, 2023:

0. Get a destination address for the transaction. In this tutorial, we'll be sending funds to the address `tb1q9k5w0nhnhyeh78snpxh0t5t7c3lxdeg3erez32`, but it if you don't need the coins for further testing you could send the coins back to the faucet.

 117 | +
 118 | +### Create and Export a PSBT Transaction
 119 | +
 120 | +0. Get a receiving address to send the funds to. In this tutorial, we'll be sending funds to the address `tb1q9k5w0nhnhyeh78snpxh0t5t7c3lxdeg3erez32`
 121 | +
 122 | +1. Create a PSBT transaction using the online `watch_only_wallet`, sending funds to the receiving address. (using `walletcreatefundedpsbt inputs[], outputs[address: amount]`)

willcl-ark commented at 10:37 AM on September 26, 2023:

1. Create an funded but unsigned PSBT to the destination address with the online `watch_only_wallet` by using `walletcreatefundedpsbt inputs[], outputs[address: amount]`

 118 | +### Create and Export a PSBT Transaction
 119 | +
 120 | +0. Get a receiving address to send the funds to. In this tutorial, we'll be sending funds to the address `tb1q9k5w0nhnhyeh78snpxh0t5t7c3lxdeg3erez32`
 121 | +
 122 | +1. Create a PSBT transaction using the online `watch_only_wallet`, sending funds to the receiving address. (using `walletcreatefundedpsbt inputs[], outputs[address: amount]`)
 123 | +- Export the psbt transaction to `funded_psbt.txt` for easy portability to the `offline_wallet` which will be signing the transaction.

willcl-ark commented at 10:38 AM on September 26, 2023:

- Export the unsigned PSBT to a file `funded_psbt.txt` for easy portability to the `offline_wallet` for signing.

 128 | +cHNidP8BAHECAAAAAWLHKR9/xAjetzL/FCmZU5lbfINRMWPRPHWO68PfUzkPAQAAAAD9////AoA4AQAAAAAAFgAULajnzvO5M38eEwmu9dF+xH5m5RGs0g0AAAAAABYAFMaT0f/Wp2DCZzL6dkJ3GhWj4Y9vAAAAAAABAHECAAAAAY+dRPEBrGopkw4ugSzS9npzJDEIrE/bq1XXI0KbYnYrAQAAAAD+////ArKaXgAAAAAAFgAUwEc4LdoxSjbWo/2Ue+HS+QjwfiBAQg8AAAAAABYAFF8oBGNNbfYN0ICTLoPECLKXXLuyYW8CAAEBH0BCDwAAAAAAFgAUXygEY01t9g3QgJMug8QIspdcu7IiBgJZMszudZAVj34IuzYpDRNdMKCwRRY9qJbhzXZF7EIjqRgwbHNPVAAAgAEAAIAAAACAAAAAAAAAAAAAACICA7BlBnyAR4F2UkKuSX9MFhYCsn6j//z9i7lHDm1O0CU0GDBsc09UAACAAQAAgAAAAIABAAAAAAAAAAA=
 129 | +```
 130 | +
 131 | +### Decode and Analyze the PSBT Transaction
 132 | +
 133 | +1. Decode and analyze the PSBT transaction on the `offline_wallet` using the `funded_psbt.txt` file.

willcl-ark commented at 10:39 AM on September 26, 2023:

1. Decode and analyze the unsigned PSBT on the `offline_wallet` using the `funded_psbt.txt` file.

 126 | +[online]$ ./src/bitcoin-cli -signet -rpcwallet="watch_only_wallet" walletcreatefundedpsbt '[]' '[{"tb1q9k5w0nhnhyeh78snpxh0t5t7c3lxdeg3erez32": 0.009}]' | jq -r '.psbt' >> /path/to/funded_psbt.txt
 127 | +[online]$ cat /path/to/funded_psbt.txt
 128 | +cHNidP8BAHECAAAAAWLHKR9/xAjetzL/FCmZU5lbfINRMWPRPHWO68PfUzkPAQAAAAD9////AoA4AQAAAAAAFgAULajnzvO5M38eEwmu9dF+xH5m5RGs0g0AAAAAABYAFMaT0f/Wp2DCZzL6dkJ3GhWj4Y9vAAAAAAABAHECAAAAAY+dRPEBrGopkw4ugSzS9npzJDEIrE/bq1XXI0KbYnYrAQAAAAD+////ArKaXgAAAAAAFgAUwEc4LdoxSjbWo/2Ue+HS+QjwfiBAQg8AAAAAABYAFF8oBGNNbfYN0ICTLoPECLKXXLuyYW8CAAEBH0BCDwAAAAAAFgAUXygEY01t9g3QgJMug8QIspdcu7IiBgJZMszudZAVj34IuzYpDRNdMKCwRRY9qJbhzXZF7EIjqRgwbHNPVAAAgAEAAIAAAACAAAAAAAAAAAAAACICA7BlBnyAR4F2UkKuSX9MFhYCsn6j//z9i7lHDm1O0CU0GDBsc09UAACAAQAAgAAAAIABAAAAAAAAAAA=
 129 | +```
 130 | +
 131 | +### Decode and Analyze the PSBT Transaction

willcl-ark commented at 10:39 AM on September 26, 2023:

### Decode and Analyze the Unsigned PSBT

 156 | +  "fee": 0.00014100,
 157 | +  "next": "signer"
 158 | +}
 159 | +```
 160 | +
 161 | +### Process and Sign the PSBT Transaction

willcl-ark commented at 10:40 AM on September 26, 2023:

### Process and Sign the PSBT

willcl-ark commented at 10:42 AM on September 26, 2023:

I've been changing these as the T is for Transaction :P

 158 | +}
 159 | +```
 160 | +
 161 | +### Process and Sign the PSBT Transaction
 162 | +
 163 | +1. Process, Sign and Finalize the PSBT transaction on the `offline_wallet`.

willcl-ark commented at 10:42 AM on September 26, 2023:

1. Process, Sign and Finalize the PSBT on the `offline_wallet`.

 168 | +
 169 | +[offline]$ cat ~/final_psbt.txt
 170 | +0200000000010162c7291f7fc408deb732ff14299953995b7c83513163d13c758eebc3df53390f0100000000fdffffff028c4f010000000000160014dda0f427f67bfeca9f0e7252e458ee39b82c7e06a0bb0d00000000001600142da8e7cef3b9337f1e1309aef5d17ec47e66e5110247304402200d245ee92df8be0183c98fb26bcbc474307ccdb764877273644b4c4eb359138202206c4cf787f120828a812b47043902683e24d50a60216e3b2fe0f104be2806e54f0121025932ccee7590158f7e08bb36290d135d30a0b045163da896e1cd7645ec4223a900000000
 171 | +```
 172 | +
 173 | +### Broadcast the Finalized PSBT Transaction

willcl-ark commented at 10:43 AM on September 26, 2023:

### Broadcast the Signed and Finalized PSBT

 169 | +[offline]$ cat ~/final_psbt.txt
 170 | +0200000000010162c7291f7fc408deb732ff14299953995b7c83513163d13c758eebc3df53390f0100000000fdffffff028c4f010000000000160014dda0f427f67bfeca9f0e7252e458ee39b82c7e06a0bb0d00000000001600142da8e7cef3b9337f1e1309aef5d17ec47e66e5110247304402200d245ee92df8be0183c98fb26bcbc474307ccdb764877273644b4c4eb359138202206c4cf787f120828a812b47043902683e24d50a60216e3b2fe0f104be2806e54f0121025932ccee7590158f7e08bb36290d135d30a0b045163da896e1cd7645ec4223a900000000
 171 | +```
 172 | +
 173 | +### Broadcast the Finalized PSBT Transaction
 174 | +1. Broadcast the signed and finalized PSBT transaction (on the `final_psbt.txt` file) using the online wallet

willcl-ark commented at 10:44 AM on September 26, 2023:

1. Broadcast the funded, signed and finalized PSBT `final_psbt.txt` using the online wallet

 113 | +    "safe": true
 114 | +  }
 115 | +]
 116 | +```
 117 | +
 118 | +### Create and Export a PSBT Transaction

willcl-ark commented at 10:47 AM on September 26, 2023:

### Create and Export an Unsigned PSBT

  22 | +{
  23 | +  "name": "offline_wallet"
  24 | +}
  25 | +```
  26 | +
  27 | +2. Export the offline wallet descriptors to a JSON file named `descriptors.json`.

willcl-ark commented at 11:02 AM on September 26, 2023:

2. Export public key-only descriptors from [offline] to a JSON file named `descriptors.json`.

  34 | +> The `descriptors.json` file will be exported to the online machine (e.g. using a USB) to create a watch-only wallet. (This is an easier way to export the descriptors compared to manual export)
  35 | +
  36 | +### Create the online `watch_only_wallet`
  37 | +
  38 | +1. On the online machine, create an online watch-only wallet named `watch_only_wallet` without private keys (disable_private_keys=true) and should be blank with no keys or HD seed (blank=true).
  39 | +- The `watch_only_wallet` wallet will be used to track transactions received to the `offline_wallet` and for creating PSBT transactions.

willcl-ark commented at 11:44 AM on September 26, 2023:

- The `watch_only_wallet` wallet will be used to track and validate incoming transactions, for creating unsigned PSBTs when spending coins, and for broadcasting signed and finalised PSBTs.

  75 | +    "success": true
  76 | +  }
  77 | +]
  78 | +```
  79 | +> [!NOTE]
  80 | +> Importing the multiple descriptors from the `offline_wallet` provides the ability to generate a variety of address types by the [online] `watch_only_wallets`

willcl-ark commented at 11:48 AM on September 26, 2023:

> Importing the multiple descriptors from the `offline_wallet` provides the ability to generate a variety of address types from the [online] `watch_only_wallet`

 153 | +> [!NOTE]
 154 | +> Leaving the `input` array empty in the above `walletcreatefundedpsbt` command is permitted and will cause the wallet to automatically select appropriate inputs for the transaction.
 155 | +
 156 | +### Decode and Analyze the Unsigned PSBT
 157 | +
 158 | +Decode and analyze the unsigned PSBT on the `offline_wallet` using the `funded_psbt.txt` file:

willcl-ark commented at 11:28 AM on October 10, 2023:

nit: Could mention here that decodepsbt can be used with the offline host to check that the outputs are paying to the expected address(es), as analyzepsbt doesn't deal with outputs?

 205 | +
 206 | +0200000000010162c7291f7fc408deb732ff14299953995b7c83513163d13c758eebc3df53390f0100000000fdffffff028c4f010000000000160014dda0f427f67bfeca9f0e7252e458ee39b82c7e06a0bb0d00000000001600142da8e7cef3b9337f1e1309aef5d17ec47e66e5110247304402200d245ee92df8be0183c98fb26bcbc474307ccdb764877273644b4c4eb359138202206c4cf787f120828a812b47043902683e24d50a60216e3b2fe0f104be2806e54f0121025932ccee7590158f7e08bb36290d135d30a0b045163da896e1cd7645ec4223a900000000
 207 | +```
 208 | +
 209 | +### Broadcast the Signed and Finalized PSBT
 210 | +Broadcast the funded, signed and finalized PSBT `final_psbt.txt` using the online wallet:

willcl-ark commented at 11:29 AM on October 10, 2023:

super-extra clarity nit:

Broadcast the funded, signed and finalized PSBT `final_psbt.txt` using `sendrawtransaction` on the online wallet:

 188 | +
 189 | +Notice that the analysis of the PSBT shows that "signatures" are missing and should be provided by the private key corresponding to the public key hash (hash160) "5f2804634d6df60dd080932e83c408b2975cbbb2"
 190 | +
 191 | +### Process and Sign the PSBT
 192 | +
 193 | +Process, Sign and Finalize the PSBT on the `offline_wallet` using the `walletprocesspsbt` command.

willcl-ark commented at 11:32 AM on October 10, 2023:

Process, Sign and Finalize the PSBT on the `offline_wallet` using the `walletprocesspsbt` command, saving the output to a file `final_psbt.txt`.

 196 | +[offline]$ ./src/bitcoin-cli -signet -rpcwallet="offline_wallet" walletprocesspsbt $(cat /path/to/funded_psbt.txt) \
 197 | +               | jq -r .hex \
 198 | +               >> /path/to/final_psbt.txt
 199 | +```
 200 | +
 201 | +Next save the final PSBT hex to a file `final_psbt.txt` so that it can be transferred back to the online wallet for broadcasting.

willcl-ark commented at 11:34 AM on October 10, 2023:

We already saved this in the previous command.

Also not sure of the value of cat-ing the psbt file here? Just to check something saved correctly? Perhaps if there is little value we can remove L201-L207 altogether?

  10 | +In this tutorial we have two hosts, both running Bitcoin v25.0
  11 | +
  12 | +* [offline] which is disconnected from all networks (internet, Tor, wifi, bluetooth etc.) and does not have, or need, a copy of the blockchain.
  13 | +* [online] which is a regular online node with a synced blockchain.
  14 | +
  15 | +We are going to first create an `offline_wallet` on the [offline] host. We will then create a `watch_only_wallet` on the [online] host using public key descriptors exported from the `offline_wallet`. Next we will receive some coins into the wallet. In order to spend these coins we'll create an unsigned PSBT using the `watch_only_wallet`, sign the PSBT using the private keys in the `offline_wallet`, and finally broadcast the signed PSBT using the [online] host.

pinheadmz commented at 4:37 PM on October 16, 2023:

nit, if you retouch: I'd say remove the brackets around online and offline - they are English words and don't really need to look like code

  20 | +### Create and Prepare the `offline_wallet`
  21 | +
  22 | +1. On the offline machine create a wallet named `offline_wallet`. This wallet will contain private keys and must remain unconnected to any networks at all times.
  23 | +
  24 | +```sh
  25 | +[offline]$ ./src/bitcoin-cli -signet -named createwallet wallet_name="offline_wallet"

pinheadmz commented at 4:39 PM on October 16, 2023:

1. First time signet is mentioned. I suggest either explaining it quickly at the top and inform users to leave it out for mainnet, or just leave it out for the guide
2. I think -passphrase should be set here too to encrypt the wallet. This is a security tutorial after all!

 188 | +
 189 | +Notice that the analysis of the PSBT shows that "signatures" are missing and should be provided by the private key corresponding to the public key hash (hash160) "5f2804634d6df60dd080932e83c408b2975cbbb2"
 190 | +
 191 | +### Process and Sign the PSBT
 192 | +
 193 | +Process, Sign and Finalize the PSBT on the `offline_wallet` using the `walletprocesspsbt` command, saving the output to a file `final_psbt.txt`.

pinheadmz commented at 4:45 PM on October 16, 2023:

nit

Process, sign and finalize the PSBT on the `offline_wallet` using the `walletprocesspsbt` command, saving the output to a file `final_psbt.txt`.

 197 | +               | jq -r .hex \
 198 | +               >> /path/to/final_psbt.txt
 199 | +```
 200 | +
 201 | +### Broadcast the Signed and Finalized PSBT
 202 | +Broadcast the funded, signed and finalized PSBT `final_psbt.txt` using `sendrawtransaction` on the online wallet:

pinheadmz commented at 4:47 PM on October 16, 2023:

nit, could explain that the wallet's job is all done now and any bitcoin full node, light client, or even some block explorer APIs can be used just to broadcast.

Broadcast the funded, signed and finalized PSBT `final_psbt.txt` using `sendrawtransaction` with an online node:

  95 | +> [!NOTE]
  96 | +> Multiple success values show indicates that multiple descriptors, for different address types, have been successfully imported. This allows generating different address types on the `watch_only_wallet`.
  97 | +
  98 | +### Fund the `offline_wallet`
  99 | +
 100 | +At this point it's important to understand that both the `offline_wallet` and [online] `watch_only_wallet` share the same public keys. As a result they generate the same addresses. Transactions can be constructed using either wallet, but valid signatures can only be added by the `offline_wallet` as only it has the private keys.

MarnixCroes commented at 6:18 PM on October 16, 2023:

nit: I'd use created like everywhere else

At this point it's important to understand that both the `offline_wallet` and [online] `watch_only_wallet` share the same public keys. As a result they generate the same addresses. Transactions can be created using either wallet, but valid signatures can only be added by the `offline_wallet` as only it has the private keys.

  42 | +
  43 | +### Create the online `watch_only_wallet`
  44 | +
  45 | +1. On the online machine create a blank watch-only wallet which has private keys disabled and is named `watch_only_wallet`. This is achieved by using the `createwallet` options: `disable_private_keys=true, blank=true`.
  46 | +
  47 | +The `watch_only_wallet` wallet will be used to track and validate incoming transactions, for creating unsigned PSBTs when spending coins, and for broadcasting signed and finalised PSBTs.

MarnixCroes commented at 6:44 PM on October 16, 2023:

nit, if you retouch:

The `watch_only_wallet` wallet will be used to track and validate incoming transactions, for creating unsigned PSBTs when spending coins, and for broadcasting signed and finalized PSBTs.

  13 | +In this tutorial we have two hosts, both running Bitcoin v25.0
  14 | +
  15 | +* `offline` host which is disconnected from all networks (internet, Tor, wifi, bluetooth etc.) and does not have, or need, a copy of the blockchain.
  16 | +* `online` host which is a regular online node with a synced blockchain.
  17 | +
  18 | +We are going to first create an `offline_wallet` on the offline host. We will then create a `watch_only_wallet` on the online host using public key descriptors exported from the `offline_wallet`. N`ext we will receive some coins into the wallet. In order to spend these coins we'll create an unsigned PSBT using the `watch_only_wallet`, sign the PSBT using the private keys in the `offline_wallet`, and finally broadcast the signed PSBT using the online host.

pinheadmz commented at 2:03 PM on October 17, 2023:

misplaced backtick?

We are going to first create an `offline_wallet` on the offline host. We will then create a `watch_only_wallet` on the online host using public key descriptors exported from the `offline_wallet`. Next we will receive some coins into the wallet. In order to spend these coins we'll create an unsigned PSBT using the `watch_only_wallet`, sign the PSBT using the private keys in the `offline_wallet`, and finally broadcast the signed PSBT using the online host.

   5 | +Maintaining an air-gap between private keys and any network connections drastically reduces the opportunity for those keys to be exfiltrated from the user.
   6 | +
   7 | +This workflow uses [Partially Signed Bitcoin Transactions](https://github.com/bitcoin/bitcoin/blob/master/doc/psbt.md) (PSBTs) to transfer the transaction to and from the offline wallet for signing using the private keys.
   8 | +
   9 | +> [!NOTE]
  10 | +> While this tutorial demonstrates the process using `Signet` network, you should omit the `-signet` flag in the provided commands when working with the `Mainnet`.

pinheadmz commented at 2:03 PM on October 17, 2023:

> While this tutorial demonstrates the process using `signet` network, you should omit the `-signet` flag in the provided commands when working with `mainnet`.

  59 | +
  60 | +```sh
  61 | +[online]$ ./src/bitcoin-cli -signet -named createwallet \
  62 | +              wallet_name="watch_only_wallet" \
  63 | +              disable_private_keys=true \
  64 | +              blank=true

achow101 commented at 6:44 PM on October 26, 2023:

blank is not necessary.

BrandonOdiwuor commented at 9:04 AM on October 27, 2023:

fixed

 144 | +
 145 | +### Create and Export an Unsigned PSBT
 146 | +
 147 | +1. Get a destination address for the transaction. In this tutorial we'll be sending funds to the address `tb1q9k5w0nhnhyeh78snpxh0t5t7c3lxdeg3erez32`, but if you don't need the coins for further testing you could send the coins back to the faucet.
 148 | +
 149 | +2. Create a funded but unsigned PSBT to the destination address with the online `watch_only_wallet` by using `walletcreatefundedpsbt inputs[], outputs[address: amount]` and export the unsigned PSBT to a file `funded_psbt.txt` for easy portability to the `offline_wallet` for signing:

achow101 commented at 6:46 PM on October 26, 2023:

The send RPC is slightly easier to use and will also make a PSBT.

BrandonOdiwuor commented at 9:05 AM on October 27, 2023:

fixed

 195 | +
 196 | +Notice that the analysis of the PSBT shows that "signatures" are missing and should be provided by the private key corresponding to the public key hash (hash160) "5f2804634d6df60dd080932e83c408b2975cbbb2"
 197 | +
 198 | +### Process and Sign the PSBT
 199 | +
 200 | +1. Unlock the `offline_wallet` with the Passphrase:

Zero-1729 commented at 2:41 PM on November 6, 2023:

Minor capitalization nit.

1. Unlock the `offline_wallet` with the passphrase:

  10 | +> While this tutorial demonstrates the process using `signet` network, you should omit the `-signet` flag in the provided commands when working with `mainnet`.
  11 | +
  12 | +## Overview
  13 | +In this tutorial we have two hosts, both running Bitcoin v25.0
  14 | +
  15 | +* `offline` host which is disconnected from all networks (internet, Tor, wifi, bluetooth etc.) and does not have, or need, a copy of the blockchain.

Zero-1729 commented at 2:41 PM on November 6, 2023:

Minor capitalization nit.

* `offline` host which is disconnected from all networks (Internet, Tor, WiFi, Bluetooth, etc.) and does not have, or need, a copy of the blockchain.

   0 | @@ -0,0 +1,255 @@
   1 | +# Offline Signing Tutorial
   2 | +
   3 | +This tutorial will describe how to use two instances of Bitcoin Core, one online and one offline, to greatly increase security by not having private keys reside on a networked device.
   4 | +
   5 | +Maintaining an air-gap between private keys and any network connections drastically reduces the opportunity for those keys to be exfiltrated from the user.

Zero-1729 commented at 2:42 PM on November 6, 2023:

Minor hyphenation nit.

Maintaining an air gap between private keys and any network connections drastically reduces the opportunity for those keys to be exfiltrated from the user.