doc, rpc: document enumerate model field and fingerprint deduplication
What changed, and why it matters
This commit only updates documentation and RPC help text. It explains how Bitcoin Core talks to external hardware wallets: the signer's 'model' field becomes the 'name' shown to users, duplicate fingerprints are skipped, and wallet operations require exactly one connected signer. No code behavior changed, so there is no security issue here.
No action needed; this is a non-functional documentation change.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The patch is purely documentation/help-text. It changes doc/external-signer.md and the help string in src/rpc/external_signer.cpp to describe existing behavior of the enumeratesigners RPC and external signer protocol. No logic, parsing, or access-control code was modified.
Changed components
doc/external-signer.mdsrc/rpc/external_signer.cpp (help text only)Inspect captured patch +8 / −4
diff --git a/doc/external-signer.md b/doc/external-signer.md
index ee1b68bb..d777871d 100644
--- a/doc/external-signer.md
+++ b/doc/external-signer.md
@@ -125,13 +125,15 @@ Usage:
[
{
"fingerprint": "00000000",
- "name": "trezor_t"
+ "model": "trezor_t"
}
]
```
The command MUST return an array, possibly empty, of entries that contain at least a `fingerprint` field.
+If present, the optional `model` field is used as the device name in the `enumeratesigners` RPC result.
+
A 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.
A future extension could add an optional return field `reachable`, in case `<cmd>` knows a signer exists but can't currently reach it.
@@ -204,7 +206,9 @@ The command MAY complain if `--chain` is set to a test-network, but the BIP32 co
## How Bitcoin Core uses the Signer API
-The `enumeratesigners` RPC simply calls `<cmd> enumerate`.
+The `enumeratesigners` RPC calls `<cmd> enumerate`, skips duplicate entries with the same `fingerprint`, and maps the optional `model` field to the RPC `name` field.
+
+Wallet 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.
The `createwallet` RPC calls:
diff --git a/src/rpc/external_signer.cpp b/src/rpc/external_signer.cpp
index 08226ffb..bc10a9c2 100644
--- a/src/rpc/external_signer.cpp
+++ b/src/rpc/external_signer.cpp
@@ -20,7 +20,7 @@
static RPCMethod enumeratesigners()
{
return RPCMethod{"enumeratesigners",
- "Returns a list of external signers from -signer.",
+ "Returns a list of external signers from -signer. Signers with duplicate master key fingerprints are skipped.",
{},
RPCResult{
RPCResult::Type::OBJ, "", "",
@@ -30,7 +30,7 @@ static RPCMethod enumeratesigners()
{RPCResult::Type::OBJ, "", "",
{
{RPCResult::Type::STR_HEX, "fingerprint", "Master key fingerprint"},
- {RPCResult::Type::STR, "name", "Device name"},
+ {RPCResult::Type::STR, "name", "Device name, the model returned by the signer"},
}},
},
}
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.