Inside Bitcoin

1# Support for signing transactions outside of Bitcoin Core
2
3Bitcoin Core can be launched with `-signer=<cmd>` where `<cmd>` is an external tool which can sign transactions and perform other functions. For example, it can be used to communicate with a hardware wallet.
4
5Interaction with external signer uses [Partially Signed Bitcoin Transaction (PSBT)](psbt.md).
6
7## Example usage
8
9The following example is based on the [HWI](https://github.com/bitcoin-core/HWI) tool. Version 2.0 or newer is required. Although this tool is hosted under the Bitcoin Core GitHub organization and maintained by Bitcoin Core developers, it should be used with caution. It is considered experimental and has far less review than Bitcoin Core itself. Be particularly careful when running tools such as these on a computer with private keys on it.
10
11When using a hardware wallet, consult the manufacturer website for (alternative) software they recommend. As long as their software conforms to the standard below, it should be able to work with Bitcoin Core.
12
13Start Bitcoin Core:
14
15```sh
16bitcoind -signer=../HWI/hwi.py
17```
18
19`bitcoin node` can also be substituted for `bitcoind`.
20
21### Device setup
22
23Follow the hardware manufacturers instructions for the initial device setup, as well as their instructions for creating a backup. Alternatively, for some devices, you can use the `setup`, `restore` and `backup` commands provided by [HWI](https://github.com/bitcoin-core/HWI).
24
25### Create wallet and import keys
26
27Get a list of signing devices / services:
28
29```sh
30bitcoin-cli enumeratesigners
31```
32
33```
34{
35  "signers": [
36    {
37      "fingerprint": "c8df832a",
38      "name": "trezor_t"
39    }
40  ]
41}
42```
43
44The master key fingerprint is used to identify a device.
45
46Create a wallet, this automatically imports the public keys:
47
48```sh
49bitcoin rpc createwallet wallet_name="hww2" disable_private_keys=true descriptors=true external_signer=true
50```
51
52Creation of the external wallet can be confirmed with `getwalletinfo`, which will report `"external_signer": true`. These commands can also be executed using `bitcoin-qt` Debug Console instead of using `bitcoin rpc` or `bitcoin-cli`.
53
54### Verify an address
55
56Display an address on the device:
57
58```sh
59bitcoin-cli -rpcwallet=<walletname> getnewaddress
60bitcoin-cli -rpcwallet=<walletname> walletdisplayaddress <address>
61```
62
63Replace `<address>` with the result of `getnewaddress`.
64
65### Spending
66
67Under the hood this uses a [PSBT (Partially Signed Bitcoin Transaction)](psbt.md).
68
69```sh
70bitcoin rpc -rpcwallet=<walletname> send outputs='{"<address>": <amount>}'
71```
72
73This constructs a PSBT and prompts your external signer to sign (will fail if it's not connected). If successful, Bitcoin Core finalizes and broadcasts the transaction.
74
75```
76{"complete": true, "txid": "<txid>"}
77```
78
79## Signer API
80
81In order to be compatible with Bitcoin Core, any signer command should conform to the specification below. This specification is subject to change. Ideally a BIP should propose a standard so that other wallets can also make use of it.
82
83Prerequisite knowledge:
84* [Output Descriptors](descriptors.md)
85* Partially Signed Bitcoin Transaction ([PSBT](psbt.md))
86
87### Flag `--chain <name>` (required except for `enumerate`)
88
89With `<name>` one of `main`, `test`, `signet`, `regtest`, `testnet4`.
90
91Bitcoin Core passes this flag to commands that operate on a chain-specific signer, for example `getdescriptors`, `displayaddress` and `signtx`.
92
93### Flag `--stdin` (required)
94
95Indicate that (sub)command should be received over stdin and results returned in response to that. `--stdin` is a global flag, it is not specific to any subcommand.
96
97Bitcoin Core currently uses this flag for `signtx`.
98
99All subcommands SHOULD support both
100- being called as commandline arguments; or
101- being written to _external-signer_ process directly through stdin (with `--stdin`).
102
103Usage:
104```sh
105<cmd> --stdin …
106```
107
108```
109[…command and arguments written to stdin…]
110```
111
112Note: remember that shell-expansion is not available on _stdin_. Consequently, commands such as `signtx`, may write their arguments in either quoted or unquoted form.
113
114### Flag `--fingerprint <fingerprint>` (required except for `enumerate`)
115
116With `<fingerprint>` being the hexadecimal 8-symbol identifier for a wallet.
117
118Bitcoin Core passes this flag to commands that operate on a specific external-signer wallet, for example `getdescriptors`, `displayaddress` and `signtx`.
119
120### `enumerate` (required)
121
122Usage:
123
124```sh
125<cmd> enumerate
126```
127
128```
129[
130    {
131        "fingerprint": "00000000",
132        "model": "trezor_t"
133    }
134]
135```
136
137The command MUST return an array, possibly empty, of entries that contain at least a `fingerprint` field.
138
139If present, the optional `model` field is used as the device name in the `enumeratesigners` RPC result.
140
141A future extension could add an optional return field with device capabilities. Perhaps a descriptor with wildcards. For example: `["pkh("44'/0'/$'/{0,1}/*"), sh(wpkh("49'/0'/$'/{0,1}/*")), wpkh("84'/0'/$'/{0,1}/*")]`. This would indicate the device supports legacy, wrapped SegWit and native SegWit. In addition it restricts the derivation paths that can used for those, to maintain compatibility with other wallet software. It also indicates the device, or the driver, doesn't support multisig.
142
143A future extension could add an optional return field `reachable`, in case `<cmd>` knows a signer exists but can't currently reach it.
144
145### `signtx` (required)
146
147`signtx` indicates a PSBT signing-request, followed by Base64-encoded PSBT. Quotes are optional.
148
149This command reads request `<base64-encoded psbt>` and MUST return a JSON object. On success, it MUST contain `{"psbt": "<base64-encoded psbt>"}` updated to include any new signatures. On failure, it SHOULD contain `{"error": "<message>"}`. Presence of a key `error` with value `null` is not considered an error.
150
151PSBT SHOULD include BIP32 derivations. The command SHOULD fail if none of the BIP32 derivations match a key owned by the device.
152
153The command SHOULD fail if the user cancels.
154
155The command MAY complain if `--chain` is set to a test-network, but any of the BIP32 derivation paths contain a coin type other than `1h` (and vice versa).
156
157### `getdescriptors` (optional)
158
159Usage:
160
161```sh
162<cmd> --fingerprint <fingerprint> --chain <name> getdescriptors --account <account>
163```
164
165Returns descriptors supported by the device. Example:
166
167```sh
168<cmd> --fingerprint 00000000 --chain main getdescriptors --account 0
169```
170
171```
172{
173  "receive": [
174    "pkh([00000000/44h/0h/0h]xpub6C.../0/*)#fn95jwmg",
175    "sh(wpkh([00000000/49h/0h/0h]xpub6B..../0/*))#j4r9hntt",
176    "wpkh([00000000/84h/0h/0h]xpub6C.../0/*)#qw72dxa9",
177    "tr([00000000/86h/0h/0h]xpub6C.../0/*)#4d8tq2ns"
178  ],
179  "internal": [
180    "pkh([00000000/44h/0h/0h]xpub6C.../1/*)#c8q40mts",
181    "sh(wpkh([00000000/49h/0h/0h]xpub6B..../1/*))#85dn0v75",
182    "wpkh([00000000/84h/0h/0h]xpub6C..../1/*)#36mtsnda",
183    "tr([00000000/86h/0h/0h]xpub6C.../1/*)#d63h6jpt"
184  ]
185}
186```
187
188### `displayaddress` (optional)
189
190Usage:
191```sh
192<cmd> --fingerprint <fingerprint> --chain <name> displayaddress --desc <descriptor>
193```
194
195Example, display the first native SegWit receive address on Testnet:
196
197```sh
198<cmd> --fingerprint 00000000 --chain test displayaddress --desc "wpkh([00000000/84h/1h/0h]tpubDDUZ..../0/0)"
199```
200
201The command MUST be able to figure out the address type from the descriptor.
202
203The command MUST return an object containing `{"address": "[the address]"}`.
204As a sanity check, for devices that support this, it SHOULD ask the device to derive the address.
205
206If `<descriptor>` contains a master key fingerprint, the command MUST fail if it does not match the fingerprint known by the device.
207
208If `<descriptor>` contains an xpub, the command MUST fail if it does not match the xpub known by the device.
209
210The command MAY complain if `--chain` is set to a test-network, but the BIP32 coin-type is not `1h` (and vice versa).
211
212## How Bitcoin Core uses the Signer API
213
214The `enumeratesigners` RPC calls `<cmd> enumerate`, skips duplicate entries with the same `fingerprint`, and maps the optional `model` field to the RPC `name` field.
215
216Wallet operations that need a signer (`createwallet`, `walletdisplayaddress` and spending) also call `<cmd> enumerate` and fail unless exactly one signer is found, so only one device should be connected at a time.
217
218The `createwallet` RPC calls:
219
220* `<cmd> --fingerprint 00000000 --chain <name> getdescriptors --account 0`
221
222It then imports descriptors for all supported address types, in a BIP44/49/84/86 compatible manner.
223
224The `walletdisplayaddress` RPC obtains the inferred descriptor for the provided address. It then calls `<cmd> --fingerprint 00000000 --chain <name> displayaddress --desc <descriptor>`.
225
226For external-signer wallets, spending uses `send` or `sendall`, and fee-bumping uses `bumpfee`. Bitcoin Core builds a PSBT, adds key origin information, checks whether any input key origin fingerprint matches the signer, calls `<cmd> --stdin --fingerprint 00000000 --chain <name>`, and sends `signtx <psbt>` over stdin. If signatures are sufficient, it finalizes the transaction and, for broadcasting RPCs, broadcasts it. If signing cannot complete, the call fails with an error. For manual fee-bumping, use `psbtbumpfee` to obtain a PSBT for signing.
227