diff --git a/doc/external-signer.md b/doc/external-signer.md index de5e5b5aba8..174ccb2f6e5 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 ` (required) +### Flag `--chain ` (required except for `enumerate`) With `` 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 ` (required) +### Flag `--fingerprint ` (required except for `enumerate`) With `` 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 - --fingerprint= getdescriptors - + --fingerprint --chain getdescriptors --account ``` Returns descriptors supported by the device. Example: ```sh - --fingerprint=00000000 getdescriptors + --fingerprint 00000000 --chain main getdescriptors --account 0 ``` ``` @@ -184,13 +187,13 @@ Returns descriptors supported by the device. Example: Usage: ```sh - --fingerprint= displayaddress --desc + --fingerprint --chain displayaddress --desc ``` Example, display the first native SegWit receive address on Testnet: ```sh - --chain test --fingerprint=00000000 displayaddress --desc "wpkh([00000000/84h/1h/0h]tpubDDUZ..../0/0)" + --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: -* ` --chain --fingerprint=00000000 getdescriptors --account 0` +* ` --fingerprint 00000000 --chain 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 ` --fingerprint=00000000 displayaddress --desc=`. +The `walletdisplayaddress` RPC obtains the inferred descriptor for the provided address. It then calls ` --fingerprint 00000000 --chain displayaddress --desc `. 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 ` --stdin --fingerprint 00000000 --chain `, and sends `signtx ` 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 a6f16e8e8ac..5131a2078f3 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 command, std::string chain, std::string fingerprint, std::string name); @@ -42,17 +42,19 @@ public: //! Obtain a list of signers. Calls ` 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& signers, const std::string& chain); - //! Display address on the device. Calls ` displayaddress --desc `. + //! Display address on the device. Calls ` --fingerprint --chain + //! displayaddress --desc `. //! @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 ` getdescriptors --account ` + //! Calls ` --fingerprint --chain getdescriptors + //! --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);