signtx (#31005)
#33765
Updates to documentation for External Signer.
signtransaction command is no longer primary mechanism.--stdin flag followed with stdin-content.signtx command followed by Base64-encoded PSBT.Best to squash commits when ready to merge.
The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.
For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/33765.
See the guideline for information on the review process. A summary of reviews will appear here.
Reviewers, this pull request conflicts with the following ones:
If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.
Possible typos and grammar issues:
signtx <base64-encoded psbt> from stdin” -> “This command reads a request signtx <base64-encoded psbt> from stdin” [missing article “a” before “request” makes the sentence ungrammatical]No other typographic or grammatical errors that impact comprehension were found.
2025-12-10
77@@ -78,6 +78,28 @@ Prerequisite knowledge:
78 * [Output Descriptors](descriptors.md)
79 * Partially Signed Bitcoin Transaction ([PSBT](psbt.md))
80
81+### Flag `--stdin` (required)
82+
83+Usage:
84+```
85+$ <cmd> --stdin
86+[…IPC interaction written to stdin…]
The term “IPC” could be confused with our multiprocess integration, maybe just use the wording from hwi --help:
--stdin Enter commands and arguments via stdin
90+
91+```
92+signtx "<Base64-encoded PSBT-content>"
93+```
94+
95+`signtx` indicates a PSBT signing request, followed by Base64-encoded PSBT-content. Quotes are optional, added in more recent versions. Semantically there is no difference, as Base64-encoded content is an uninterrupted sequence of characters regardless.
Afaik the use of quotes depends on the shell environment, I don’t think it’s worth documenting.
More important is to point out that Bitcoin Core will use --stdin here, in order to support large PSBTs.
119@@ -98,6 +120,8 @@ A future extension could add an optional return field `reachable`, in case `<cmd
120
121 ### `signtransaction` (required)
The original doc is wrong, there is only signtx, no signtransaction.
signtx and its arguments, like all other commands, can optionally be passed via --stdin
Is your comment that the doc is wrong, or that you moved away from that solution long ago? I only recently got involved with this side of Bitcoin, so I am really only familiar with v27+.
I can drop the signtransaction shell command for the sake obsolescence regardless, but it would be nice to know.
I don’t think there was ever a signtransaction, it was just a typo in the docs. The external signer feature was introduced in v22. The docs from that time mentions signtransaction and not signtx: https://github.com/bitcoin/bitcoin/blob/v22.0/doc/external-signer.md
Looking at the code from v22.0 however, the actual command was already signtx.
Good idea to update these docs.
Yes … I was inspired by a certain #31005 (comment)
84+```
85+$ <cmd> --stdin
86+[…command and arguments written to stdin…]
87+```
88+
89+#### stdin-command `signtx` (required)
signtx is not inherently stdin
All (required) commands should work with or without --stdin. Bitcoin Core currently only uses it for signtx, and that’s worth mentioning, but it can change.
Oookaaaaaay .. that changes things considerably. That was not at all clear to me.
Any chance you can drop a link to the place in source-code (assuming it is somewhat concentrated), such that I can have a quick peek. I could search myself, but I suspect you are familiar with the code-base.
Please use unique, descriptive commit message, or squash your commits according to https://github.com/bitcoin/bitcoin/blob/master/CONTRIBUTING.md#squashing-commits.
Also, there are a few LLM linter comments. Not sure if they all apply, but the missing a article makes sense.
42
43 Create a wallet, this automatically imports the public keys:
44
45 ```sh
46-$ bitcoin-cli createwallet "hww" true true "" true true true
47+$ bitcoin-cli -named createwallet wallet_name="hww" disable_private_keys=true external_signer=true
bitcoin rpc createwallet, which sets -named automatically.
46-$ bitcoin-cli createwallet "hww" true true "" true true true
47+$ bitcoin-cli -named createwallet wallet_name="hww" disable_private_keys=true external_signer=true
48 ```
49
50-`bitcoin rpc` can also be substituted for `bitcoin-cli`.
51+You can also enter equivalent RPCs in the `bitcoin-qt` Debug Console instead of using `bitcoin-cli`.
75 ```
76
77 ## Signer API
78
79-In 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.
80+More recent versions of Bitcoin, around v29 and later, have made significant improvements. It is recommended to use more recent versions.
Nope. I do not have sufficient knowledge of Bitcoin Core to state this. Do you have an idea? My goal is to emphasize that older versions behaved differently and less refined, such that there is benefit to start using external-signers with recent Bitcoin versions.
Maybe we should just leave it out?
87
88+### Flag `--chain <name>` (required)
89+
90+With `<name>` one of `main`, `test`, `signet`, `regtest`.
91+
92+Previously, flag `--testnet` would be used to indicate "_testnet_" specifically. Presently, all calls of external-signer include `--chain` argument with value.
127@@ -96,35 +128,39 @@ A future extension could add an optional return field with device capabilities.
128
129 A future extension could add an optional return field `reachable`, in case `<cmd>` knows a signer exists but can't currently reach it.
130
131-### `signtransaction` (required)
132+### `signtx` (required)
133+
134+`signtx` indicates a PSBT-signing-request, followed by Base64-encoded PSBT-content. Quotes are optional, added in more recent versions. Semantically, there is no difference as Base64-encoded content is an uninterrupted sequence of characters regardless.
140+$ <cmd> --fingerprint=<fingerprint> signtx <psbt>
141+<base64-encode (partially-)signed PSBT>
142 ```
143
144-The command returns a psbt with any signatures.
145+With `<psbt>` a Base64-encoded PSBT and updated `<psbt>` result returned.
<psbt>”?
143
144-The command returns a psbt with any signatures.
145+With `<psbt>` a Base64-encoded PSBT and updated `<psbt>` result returned.
146
147-The `psbt` SHOULD include bip32 derivations. The command SHOULD fail if none of the bip32 derivations match a key owned by the device.
148+The command reads the request from stdin and MUST return a JSON object. On success, it MUST contain `{"psbt": "<base64_psbt>"}` updated to include any new signatures. On failure, it SHOULD contain `{"error": "<message>"}`. A key `error` with value `null` is ignored, therefore interpreted as not an error.
The command reads the request from stdin
You already cover this in the general section about stdin.
and MUST return a JSON object
All commands do.
On success, it MUST contain … as not an err
This seems needlessly verbose.
A key
errorwith valuenullis ignored,
Is this a known HWI bug? Otherwise it doesn’t seem worth bringing up and client software shouldn’t do this.
signtx does interact via stdin. I removed another sections, but left on the “On success ..”. Based on what is it verbose, because I am not otherwise familiar with Bitcoin Core RPC and I find it useful to have these bits of behavior made explicit.
error in a successful result is not an issue if "error": null.
145+With `<psbt>` a Base64-encoded PSBT and updated `<psbt>` result returned.
146
147-The `psbt` SHOULD include bip32 derivations. The command SHOULD fail if none of the bip32 derivations match a key owned by the device.
148+The command reads the request from stdin and MUST return a JSON object. On success, it MUST contain `{"psbt": "<base64_psbt>"}` updated to include any new signatures. On failure, it SHOULD contain `{"error": "<message>"}`. A key `error` with value `null` is ignored, therefore interpreted as not an error.
149+
150+PSBT-content SHOULD include BIP32-derivations. The command SHOULD fail if none of the BIP32-derivations match a key owned by the device.
216-It then imports descriptors for all support address types, in a BIP44/49/84 compatible manner.
217+It then imports descriptors for all supported address types, in a BIP44/49/84/86 compatible manner.
218
219 The `walletdisplayaddress` RPC reuses some code from `getaddressinfo` on the provided address and obtains the inferred descriptor. It then calls `<cmd> --fingerprint=00000000 displayaddress --desc=<descriptor>`.
220
221+For external-signer wallets, spending uses `send` or `sendall`. Bitcoin Core builds a PSBT, calls the signer via stdin with `signtx`, and if signatures are sufficient, finalizes and broadcasts the transaction. If the signer is not connected or cancels, the call fails with an error. For fee-bumping on such wallets, use `psbtbumpfee` when interactive signing is required.
For external-signer wallets, sspending uses
sendorsendall
I think you mean: to spend from an external-signer wallet, use the send or sendall RPCs.
when interactive signing is required
?
Looks mostly good, but some text seems off or needlessly verbose.
I expected that someone would squash upon integrating the work.
Maintainers don’t touch the original commits, which is especially nice if you GPG sign them.
Whenever you push an update, just squash the changes right away, reviewers will figure out how to view the diff.
I expected that someone would squash upon integrating the work.
Maintainers don’t touch the original commits, which is especially nice if you GPG sign them.
That is a fair point. I could sign, but it feels like unnecessarily blowing up the size of a minor contribution.
update I did a second push that rebases PR to current master.