doc: update interface, --stdin flag, `signtx` (#31005) #33765

cobratbq · 2025-11-02T23:24:59Z

Updates to documentation for External Signer.

Added mention that signtransaction command is no longer primary mechanism.
Document inter-process communication via --stdin flag followed with stdin-content.
Document signtx command followed by Base64-encoded PSBT.

Best to squash commits when ready to merge.

DrahtBot · 2025-11-02T23:25:05Z

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/33765.

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	Sjors

If your review is incorrectly listed, please copy-paste  into the comment that the bot should ignore.

Conflicts

Reviewers, this pull request conflicts with the following ones:

#33112 (wallet: relax external_signer flag constraints by Sjors)
#30354 (doc: external-signer, example 'createwallet' RPC call requires eight argument by cobratbq)

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.

LLM Linter (✨ experimental)

Possible typos and grammar issues:

"being written to external-signer process directly through stdin" -> "being written to the external-signer process directly through stdin" [missing definite article "the" makes the phrase slightly ungrammatical]
"This command reads request 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

Sjors

Good idea to update these docs.

doc/external-signer.md

cobratbq · 2025-11-11T22:06:31Z

Good idea to update these docs.

Yes ... I was inspired by a certain #31005 (comment)

doc/external-signer.md

maflcko · 2025-11-26T14:29:01Z

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.

cobratbq · 2025-11-26T19:14:40Z

@maflcko I expected that someone would squash upon integrating the work. Now squashed.
I included some of the changes from #33947, though not verbatim. It may be worth checking the changes again, as a whole.

Sjors

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.

doc/external-signer.md

Sjors · 2025-12-10T12:07:46Z

doc/external-signer.md

 ```

 ## Signer API

-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.
+More recent versions of Bitcoin, around v29 and later, have made significant improvements. It is recommended to use more recent versions.


I guess the goal here is to specify the minimum Bitcoin Core version that's compatible with the API described here. If so, let's say that specifically.

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?

Yes, let's leave it out.

doc/external-signer.md

Sjors · 2025-12-10T12:20:38Z

doc/external-signer.md


-The `psbt` SHOULD include bip32 derivations. The command SHOULD fail if none of the bip32 derivations match a key owned by the device.
+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 error with value null is ignored,

Is this a known HWI bug? Otherwise it doesn't seem worth bringing up and client software shouldn't do this.

Not so. Not all commands are expected to interact via stdin. 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.

My involvement is not through HWI. I want to emphasize that presence of error in a successful result is not an issue if "error": null.

Sjors · 2025-12-10T12:21:31Z

doc/external-signer.md

-The `psbt` SHOULD include bip32 derivations. The command SHOULD fail if none of the bip32 derivations match a key owned by the device.
+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.
+
+PSBT-content SHOULD include BIP32-derivations. The command SHOULD fail if none of the BIP32-derivations match a key owned by the device.


Is there any hardware wallet that can sign without BIP32 derivations?

Not all of the text is by my own judgement. However, you might leave out BIP-32 derivations for keys not under own management. Technically, those would never be expected to be signed with this call to external-signer.

doc/external-signer.md

…ntx, contains updates from bitcoin#33947

cobratbq · 2025-12-10T18:28:35Z

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.

Sjors · 2025-12-12T17:54:51Z

@cobratbq there's certainly no need to sign commits, but when people do sign, it's nice that we don't break the signature.

Sjors

ACK 15da876

Sjors · 2025-12-29T05:01:13Z

doc/external-signer.md


 Bitcoin 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.

+Interaction with external signer is built upon a specialized construct [Partially Signed Bitcoin Transaction (PSBT)](psbt.md).


"is built upon a specialized construct" -> "uses"?

Sjors · 2025-12-29T05:04:14Z

doc/external-signer.md

 ```

 ## Signer API

-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.
+More recent versions of Bitcoin, around v29 and later, have made significant improvements. It is recommended to use more recent versions.


Yes, let's leave it out.

Sjors · 2025-12-29T05:05:16Z

doc/external-signer.md


+### Flag `--chain <name>` (required)
+
+With `<name>` one of `main`, `test`, `signet`, `regtest`.


Let's add testnet4

DrahtBot added the Docs label Nov 2, 2025

cobratbq mentioned this pull request Nov 2, 2025

Docs: "External signer" documentation is outdated. (plz close if unwanted request) #31005

Closed

1 task

Sjors reviewed Nov 11, 2025

View reviewed changes

doc/external-signer.md Outdated Show resolved Hide resolved

doc/external-signer.md Outdated Show resolved Hide resolved

doc/external-signer.md Outdated Show resolved Hide resolved

cobratbq force-pushed the external-signer-docs branch from 2b7c47c to e1d431c Compare November 11, 2025 22:19

Sjors reviewed Nov 12, 2025

View reviewed changes

doc/external-signer.md Outdated Show resolved Hide resolved

cobratbq changed the title ~~doc: update interface, --stdin flag, IPC-command signtx (#31005)~~ doc: update interface, --stdin flag, signtx (#31005) Nov 17, 2025

fanquake mentioned this pull request Nov 26, 2025

docs: sync external-signer.md with current external signer flow #33947

Closed

DrahtBot added the CI failed label Nov 26, 2025

cobratbq force-pushed the external-signer-docs branch from 58dc933 to 94a26e8 Compare November 26, 2025 19:12

cobratbq force-pushed the external-signer-docs branch from 94a26e8 to 8f6f147 Compare November 27, 2025 18:33

DrahtBot removed the CI failed label Nov 28, 2025

This was referenced Dec 1, 2025

wallet: relax external_signer flag constraints #33112

Open

doc: external-signer, example 'createwallet' RPC call requires eight argument #30354

Open

Sjors reviewed Dec 10, 2025

View reviewed changes

cobratbq force-pushed the external-signer-docs branch from 8f6f147 to 9ca7a84 Compare December 10, 2025 17:35

doc: external signer: update interface, --stdin flag, IPC-command sig…

15da876

…ntx, contains updates from bitcoin#33947

cobratbq force-pushed the external-signer-docs branch from 9ca7a84 to 15da876 Compare December 10, 2025 18:22

DrahtBot added CI failed and removed CI failed labels Dec 15, 2025

Sjors approved these changes Dec 29, 2025

View reviewed changes


		The `psbt` SHOULD include bip32 derivations. The command SHOULD fail if none of the bip32 derivations match a key owned by the device.
		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.


		Bitcoin 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.

		Interaction with external signer is built upon a specialized construct [Partially Signed Bitcoin Transaction (PSBT)](psbt.md).


		### Flag `--chain <name>` (required)

		With `<name>` one of `main`, `test`, `signet`, `regtest`.

doc: update interface, --stdin flag, signtx (#31005) #33765

Are you sure you want to change the base?

doc: update interface, --stdin flag, signtx (#31005) #33765

Conversation

cobratbq commented Nov 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DrahtBot commented Nov 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage & Benchmarks

Reviews

Conflicts

LLM Linter (✨ experimental)

Uh oh!

Sjors left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cobratbq commented Nov 11, 2025

Uh oh!

Uh oh!

maflcko commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cobratbq commented Nov 26, 2025

Uh oh!

Sjors left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cobratbq Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cobratbq commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Sjors commented Dec 12, 2025

Uh oh!

Sjors left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

doc: update interface, --stdin flag, `signtx` (#31005) #33765

doc: update interface, --stdin flag, `signtx` (#31005) #33765

cobratbq commented Nov 2, 2025 •

edited

Loading

DrahtBot commented Nov 2, 2025 •

edited

Loading

maflcko commented Nov 26, 2025 •

edited

Loading

Sjors left a comment •

edited

Loading

cobratbq Dec 10, 2025 •

edited

Loading

cobratbq commented Dec 10, 2025 •

edited

Loading