This PR adds offline signing tutorial. Fixes #9492
Although there currently exists tutorials on external-signer and on multisig implemented on #24519 . The external-signer tutorial assumes a connected device and the multisig tutorial is only for multisig transactions and does not include using an offline wallet
The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.
For detailed information about the code coverage, see the test coverage report.
See the guideline for information on the review process.
| Type | Reviewers |
|---|---|
| ACK | achow101, pinheadmz, willcl-ark, Zero-1729 |
| Concept ACK | RandyMcMillan |
If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.
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
0In 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
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.
nits, spacing
0In 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
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
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.
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`.
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
jq
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
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)
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 ;-)
concept ACK de9a0f7b6cd2b3076ce7a7dac61e3847e0570813
Left a few comments - I think the complexity can be reduced to make it more practical for actual mainnet users as opposed to a purely educational exercise.
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.
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`
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
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`.
Nice work @BrandonOdiwuor
Gave it a first pass too, and agree with many of @pinheadmz comments. I think removing the online wallet would remove a load of steps and make things easier to follow.
Later today I will try and manually test the steps myself using a docker instance, as you described.
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
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`
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.
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.
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]`)
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.
0This 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.
1Maintaining an air-gap between private keys and any network connections drastically reduces the opportunity for those keys to be exfiltrated from the user.
2
3This 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
0In this tutorial, we have two hosts, both running Bitcoin Core v25.0:
1
2* [offline] which is disconnected from all networks (internet, Tor, wifi, bluetooth etc.) and does not have, or need, a copy of the blockchain.
3* [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
0We 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
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"
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)
0> 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).
01. 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`.
1
2Note: `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`.
0At 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`.
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.
01. 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.
02. 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:
03. 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.
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`
00. 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]`)
01. 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.
0- 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.
01. 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
0### Decode and Analyze the Unsigned PSBT
156+ "fee": 0.00014100,
157+ "next": "signer"
158+}
159+```
160+
161+### Process and Sign the PSBT Transaction
0### Process and Sign the PSBT
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`.
01. 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
0### 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
01. 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
0### 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`.
02. 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.
0- 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`
0> Importing the multiple descriptors from the `offline_wallet` provides the ability to generate a variety of address types from the [online] `watch_only_wallet`
Hey @BrandonOdiwuor looking pretty good now, nice work!
I left some (ok, quite a few!) nits, but not related to the process. Feel free to take whichever you feel improve the readability the most.
@willcl-ark Thanks a lot for the suggestions above, which really improved the readability of the doc
I have updated the doc to include the suggestions
Hey @BrandonOdiwuor, thanks for addressing the feedback so quickly.
I’ve given this another run through, this time on my own editor, and made some more suggestions which I formatted into two seperate patches here.
https://github.com/BrandonOdiwuor/bitcoin/commit/beef4b210c5f2f2c4eb44e8a4f82e25c65c340cd contains more readability nits which I think improve the readbility further.
https://github.com/BrandonOdiwuor/bitcoin/commit/beef353513fc2a72a9f692530077977a4d288110 I am less sure about, but I noticed that some of the longer shell commands are rendered off the edge of the screen with no wrapping by deafult, so experimented with using \ linebreaks in some of them to try and have them shown in the narrow default GitHub render.
Both of them are, like my previous reviews’ suggestions, optional. So feel free to take what you like from both of them if you agree that the suggestions are useful.
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:
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:
super-extra clarity nit:
0Broadcast 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.
0Process, 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.
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?
Ok I think this is looking pretty good now!
I left two nits which you can choose to take or ignore as you please, but I think L201 where the instruction doesn’t match the text should be corrected before I can ACK it.
Ping @pinheadmz to take another look soon too
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.
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"
-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`.
nit
0Process, 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:
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.
0Broadcast the funded, signed and finalized PSBT `final_psbt.txt` using `sendrawtransaction` with an online node:
ACK 4f12e2ba986406aa623d2fa3adc75c239dfea409
Read through everything and I think it looks great. Definitely good enough for publishing in the repo. I left a few comments if you like, I’m happy to re-ACK
0-----BEGIN PGP SIGNED MESSAGE-----
1Hash: SHA256
2
3ACK 4f12e2ba986406aa623d2fa3adc75c239dfea409
4-----BEGIN PGP SIGNATURE-----
5
6iQIzBAEBCAAdFiEE5hdzzW4BBA4vG9eM5+KYS2KJyToFAmUtaUMACgkQ5+KYS2KJ
7yTpsZA/+NaoPpYrLQfM5qw/H+NT3BHvOUZJkVkmHSNWvgqnEwX8TDVJTvbz8zZOt
8xAOTzjCfmH7OSIqHkUY41eKzm1SFJdemsl8AqOt2IWhk0vdEV8K7WZxRNzncPeGZ
9E1DP2iUhx1bkLbq9ybkcZ4JHm2Lz5xJw0Nu8x6I1Q0byNiDrvbyrZZ4G7oZ2HHHd
10dGoIatM4P92Nc8YuF+QTvRg1E/qOGOnQ2a+YUUKecc3nDvrcQAFX3JSyd4NYb22O
11Mgl46boPvmxgN24kn+1I8I+vPxekILuhgPGYBFi5yWSrAI1A2REtju3Uk0VLImAV
12nZgrcbiBU8sv3H+bfLKcYbikp/qjZExGPHuMlLpmOHqsKbtrysZEfcZohHCusfDS
13BrSpCf8pPJF88oylEi/zd0IUEiYOIeV2IfwGi6Gy/1IAIEiYR/bGUZP3aCw1Zbrz
14C7ic5up5nUZuhwWB8OHh3vzEeIduezAt9ng2D7/4W8k6ygKUH5Z2R2YCCrZf4zrm
15+C0pdoFauMRuH9vVMfL7XEFXY2rPvRpUsFlUYPG2/K4mQGyLPBtreHj8OmC6c3Nf
164k3vtR7Ed9G0QLz5O1G7MnrDxvE8PR6U3f7vzkZACcMrYyiFtv08aV2U6wa1d4Qw
17aXZNf/3jq0W3JMWmAUuY65962fq0apNJvxnyp4ZPiiqMUJhYwu8=
18=wsgh
19-----END PGP SIGNATURE-----
pinheadmz’s public key is on keybase
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.
nit: I’d use created like everywhere else
0At 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.
nit, if you retouch:
0The `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.
misplaced backtick?
0We 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`.
0> While this tutorial demonstrates the process using `signet` network, you should omit the `-signet` flag in the provided commands when working with `mainnet`.
ACK 1f8ac46bea019f984f2a050e121a51eb79bf9580
0-----BEGIN PGP SIGNED MESSAGE-----
1Hash: SHA256
2
3ACK 1f8ac46bea019f984f2a050e121a51eb79bf9580
4-----BEGIN PGP SIGNATURE-----
5
6iQIzBAEBCAAdFiEE5hdzzW4BBA4vG9eM5+KYS2KJyToFAmUupCEACgkQ5+KYS2KJ
7yTp25xAAq2Tg7xArPpDHxPDWpvDzsUShovFxpMQdnrixQ+OHSvOGPEPB94iRElfi
8BP8WoxmulpBaiYB3y7fXjUIXePHULChPvjM3fOJTCS5HnqrDAZ3yACTlfyXf453u
9cTI3tRMdF6vy5xzUCw69bG1EwMtoaulj2S3I7iqfc6OKxQ7eyA/jl92N8ax9Ciwb
105ylUtWMKcfP78Lz/ssx7Jbrtwx/zyLYK/j44LkpbAz6AAxbUhOYxqrHaYOvXTTJ3
11LHkZ76iYKrBmkH9Mdy4+blxeD/Por5e4qdQFcsk3zl0N6c3iX0658zwG0s7XR8pH
128nJQDiLYuoMmLb8cWbHuUifFbQihM6op+BGe4kTMWJH02rymjXp6p6DPEuoYqFXJ
13QUq22obSrjeST1uEOnpDrNO9VuQAdLjQ8lPfUT809vucxoMvkhJxVIcskXPF5D2i
149pxQpqA2vP0ZZXsAzTI7k8Sx9T1hjcQEn3aKStpobjvqa2L9Cl7jrys23R3IpjDW
15/mpEOAdSV88ezaC8ox4MoWlCjV96a4zh0nMOpSBZXynQRKFr1RjWAcPxkFrJi/yO
16arGV1CPkBSrNSc9HIj+LX9dhuQZCKQDlD1L7kTBmAqvBKODo81qXISIATJjLfaQ4
1781v97jEy0Tf2THkv2xh2sHRnQoWQ5vylz7R+gtOW7zz/MO9bScg=
18=lJzK
19-----END PGP SIGNATURE-----
pinheadmz’s public key is on keybase
could you please review the latest version of the doc
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
blank is not necessary.
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:
send RPC is slightly easier to use and will also make a PSBT.
ACK 3c208cc05ea9efb145c956e70f80efd8b027ff33
Confirmed only updates since last review addressed achow101’s nits re: send and blank
0-----BEGIN PGP SIGNED MESSAGE-----
1Hash: SHA256
2
3ACK 3c208cc05ea9efb145c956e70f80efd8b027ff33
4-----BEGIN PGP SIGNATURE-----
5
6iQIzBAEBCAAdFiEE5hdzzW4BBA4vG9eM5+KYS2KJyToFAmVH8gIACgkQ5+KYS2KJ
7yToV3Q//TyBSa0j3/cGSVnT7dNZREnfh2ecKV5IueWBK1OnS3Bae1eLFS9hikmuG
8gjxgRJFcrQYnwrqst72fkXlhXWnldam9NRsMV7LB8e5Caq6Vu0Bw+Kn0A1iSGnAc
9VpZ5BVTz/bfB5UaLsoxGmsSU7S36YiuleXmuf/y/V59O6bxKBR0AAyxSSPLCW0yZ
10KScURimiX0Y7VIfZxQdnj/Jm4a0K9CfaFEjaAJeS622hdQTJDWx/Diwog4PWMdDe
11jmjnBQ+zAUT4O90ACJoe+Dipgv4Hl2e4TuvhVU/+2bmycnzxIgD5R2ZUyX7tplbD
12b9y4OpEdKuJDu6LMlIJtFvvhESRxGwWaliGS5afXxO4O4slqmMnyizm93jcJdhaQ
13SpSCaywOTdbcRQ0/IHn0Lz+hECsAeJgdFgOXJXfH5y5Q1AZkSkXYyrKaNBR+EHpg
14vBEPiJyoRu57xzH360JW0PFmUdF4P60mmHQaTl5uH2CdHw0YofTAcjs/KfijqjVu
15gEPHHWflq6G9HcUinWZRcZ9asaJG2hzmoyrDTRnrL70ztRVyMtIU/99jN9lsix7s
169Hfv9MPBddFmLbBTKmulmzMZ9r+VOT4eexcq+J9zOwDEZZ/LHC2ClkzvrX7gJDlo
17h/dQ9ud7qN5oGOSbbjQ7CTHaquTEw6ijbgHkaEw5E7j95JlSmaQ=
18=9+H8
19-----END PGP SIGNATURE-----
pinheadmz’s public key is on keybase
ACK 3c208cc05ea9efb145c956e70f80efd8b027ff33
Looks good to me!
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:
Minor capitalization nit.
01. 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.
Minor capitalization nit.
0* `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.
Minor hyphenation nit.
0Maintaining an air gap between private keys and any network connections drastically reduces the opportunity for those keys to be exfiltrated from the user.
ACK 3c208cc05ea9efb145c956e70f80efd8b027ff33
Great work!