doc: clarify which commands receive --chain, --fingerprint and --stdin
What changed, and why it matters
This commit only updates documentation and code comments for Bitcoin Core's external signer interface. It clarifies which command-line flags are passed to which signer commands and fixes usage examples to match the actual implementation. No code behavior changes, no security bug fix, and no vulnerability is present.
No security action needed; this is a documentation-only clarification.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff modifies doc/external-signer.md and src/external_signer.h. It changes wording of flag descriptions from ‘(required)’ to ‘(required except for enumerate)’ for –chain and –fingerprint, documents –stdin as a global flag, adds testnet4 to chain name lists, updates getdescriptors and displayaddress usage examples and doxygen comments to include –fingerprint and –chain, and removes an implementation-detail mention of getaddressinfo. No executable code is changed.
Changed components
doc/external-signer.mdsrc/external_signer.hInspect captured patch +20 / −15
diff --git a/doc/external-signer.md b/doc/external-signer.md
index de5e5b5a..174ccb2f 100644
--- a/doc/external-signer.md
+++ b/doc/external-signer.md
@@ -84,13 +84,17 @@ Prerequisite knowledge:
* [Output Descriptors](descriptors.md)
* Partially Signed Bitcoin Transaction ([PSBT](psbt.md))
-### Flag `--chain <name>` (required)
+### Flag `--chain <name>` (required except for `enumerate`)
With `<name>` one of `main`, `test`, `signet`, `regtest`, `testnet4`.
+Bitcoin Core passes this flag to commands that operate on a chain-specific signer, for example `getdescriptors`, `displayaddress` and `signtx`.
+
### Flag `--stdin` (required)
-Indicate that (sub)command should be received over stdin and results returned in response to that. `--stdin` is a global flag, it is not used for all subcommands.
+Indicate 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.
+
+Bitcoin Core currently uses this flag for `signtx`.
All subcommands SHOULD support both
- being called as commandline arguments; or
@@ -107,11 +111,11 @@ Usage:
Note: remember that shell-expansion is not available on _stdin_. Consequently, commands such as `signtx`, may write their arguments in either quoted or unquoted form.
-### Flag `--fingerprint <fingerprint>` (required)
+### Flag `--fingerprint <fingerprint>` (required except for `enumerate`)
With `<fingerprint>` being the hexadecimal 8-symbol identifier for a wallet.
-Commands will specify a fingerprint as an identifier for external-signer wallet.
+Bitcoin Core passes this flag to commands that operate on a specific external-signer wallet, for example `getdescriptors`, `displayaddress` and `signtx`.
### `enumerate` (required)
@@ -155,14 +159,13 @@ The command MAY complain if `--chain` is set to a test-network, but any of the B
Usage:
```sh
-<cmd> --fingerprint=<fingerprint> getdescriptors <account>
-<xpub>
+<cmd> --fingerprint <fingerprint> --chain <name> getdescriptors --account <account>
```
Returns descriptors supported by the device. Example:
```sh
-<cmd> --fingerprint=00000000 getdescriptors
+<cmd> --fingerprint 00000000 --chain main getdescriptors --account 0
```
```
@@ -184,13 +187,13 @@ Returns descriptors supported by the device. Example:
Usage:
```sh
-<cmd> --fingerprint=<fingerprint> displayaddress --desc <descriptor>
+<cmd> --fingerprint <fingerprint> --chain <name> displayaddress --desc <descriptor>
```
Example, display the first native SegWit receive address on Testnet:
```sh
-<cmd> --chain test --fingerprint=00000000 displayaddress --desc "wpkh([00000000/84h/1h/0h]tpubDDUZ..../0/0)"
+<cmd> --fingerprint 00000000 --chain test displayaddress --desc "wpkh([00000000/84h/1h/0h]tpubDDUZ..../0/0)"
```
The command MUST be able to figure out the address type from the descriptor.
@@ -212,10 +215,10 @@ Wallet operations that need a signer (`createwallet`, `walletdisplayaddress` and
The `createwallet` RPC calls:
-* `<cmd> --chain <name> --fingerprint=00000000 getdescriptors --account 0`
+* `<cmd> --fingerprint 00000000 --chain <name> getdescriptors --account 0`
It then imports descriptors for all supported address types, in a BIP44/49/84/86 compatible manner.
-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>`.
+The `walletdisplayaddress` RPC obtains the inferred descriptor for the provided address. It then calls `<cmd> --fingerprint 00000000 --chain <name> displayaddress --desc <descriptor>`.
For 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.
diff --git a/src/external_signer.h b/src/external_signer.h
index a6f16e8e..5131a207 100644
--- a/src/external_signer.h
+++ b/src/external_signer.h
@@ -29,7 +29,7 @@ private:
public:
//! @param[in] command the command which handles interaction with the external signer
//! @param[in] fingerprint master key fingerprint of the signer
- //! @param[in] chain "main", "test", "regtest" or "signet"
+ //! @param[in] chain "main", "test", "signet", "regtest" or "testnet4"
//! @param[in] name device name
ExternalSigner(std::vector<std::string> command, std::string chain, std::string fingerprint, std::string name);
@@ -42,17 +42,19 @@ public:
//! Obtain a list of signers. Calls `<command> enumerate`.
//! @param[in] command the command which handles interaction with the external signer
//! @param[in,out] signers vector to which new signers (with a unique master key fingerprint) are added
- //! @param chain "main", "test", "regtest" or "signet"
+ //! @param chain "main", "test", "signet", "regtest" or "testnet4"
//! @returns success
static bool Enumerate(const std::string& command, std::vector<ExternalSigner>& signers, const std::string& chain);
- //! Display address on the device. Calls `<command> displayaddress --desc <descriptor>`.
+ //! Display address on the device. Calls `<command> --fingerprint <fingerprint> --chain <chain>
+ //! displayaddress --desc <descriptor>`.
//! @param[in] descriptor Descriptor specifying which address to display.
//! Must include a public key or xpub, as well as key origin.
UniValue DisplayAddress(const std::string& descriptor) const;
//! Get receive and change Descriptor(s) from device for a given account.
- //! Calls `<command> getdescriptors --account <account>`
+ //! Calls `<command> --fingerprint <fingerprint> --chain <chain> getdescriptors
+ //! --account <account>`.
//! @param[in] account which BIP32 account to use (e.g. `m/44'/0'/account'`)
//! @returns see doc/external-signer.md
UniValue GetDescriptors(int account);
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.