Bitcoin Core’s external hardware signer interface

1// Copyright (c) 2018-present The Bitcoin Core developers
2// Distributed under the MIT software license, see the accompanying
3// file COPYING or http://www.opensource.org/licenses/mit-license.php.
4
5#ifndef BITCOIN_EXTERNAL_SIGNER_H
6#define BITCOIN_EXTERNAL_SIGNER_H
7
8#include <common/system.h>
9#include <univalue.h>
10
11#include <string>
12#include <vector>
13
14class PartiallySignedTransaction;
15
16//! Enables interaction with an external signing device or service, such as
17//! a hardware wallet. See doc/external-signer.md
18class ExternalSigner
19{
20private:
21    //! The command which handles interaction with the external signer.
22    std::vector<std::string> m_command;
23
24    //! Bitcoin mainnet, testnet, etc
25    std::string m_chain;
26
27    std::vector<std::string> NetworkArg() const;
28
29public:
30    //! @param[in] command      the command which handles interaction with the external signer
31    //! @param[in] fingerprint  master key fingerprint of the signer
32    //! @param[in] chain        "main", "test", "signet", "regtest" or "testnet4"
33    //! @param[in] name         device name
34    ExternalSigner(std::vector<std::string> command, std::string chain, std::string fingerprint, std::string name);
35
36    //! Master key fingerprint of the signer
37    std::string m_fingerprint;
38
39    //! Name of signer
40    std::string m_name;
41
42    //! Obtain a list of signers. Calls `<command> enumerate`.
43    //! @param[in]              command the command which handles interaction with the external signer
44    //! @param[in,out] signers  vector to which new signers (with a unique master key fingerprint) are added
45    //! @param chain            "main", "test", "signet", "regtest" or "testnet4"
46    //! @returns success
47    static bool Enumerate(const std::string& command, std::vector<ExternalSigner>& signers, const std::string& chain);
48
49    //! Display address on the device. Calls `<command> --fingerprint <fingerprint> --chain <chain>
50    //! displayaddress --desc <descriptor>`.
51    //! @param[in] descriptor Descriptor specifying which address to display.
52    //!            Must include a public key or xpub, as well as key origin.
53    UniValue DisplayAddress(const std::string& descriptor) const;
54
55    //! Get receive and change Descriptor(s) from device for a given account.
56    //! Calls `<command> --fingerprint <fingerprint> --chain <chain> getdescriptors
57    //! --account <account>`.
58    //! @param[in] account  which BIP32 account to use (e.g. `m/44'/0'/account'`)
59    //! @returns see doc/external-signer.md
60    UniValue GetDescriptors(int account);
61
62    //! Sign PartiallySignedTransaction on the device.
63    //! Calls `<command> --stdin --fingerprint <fingerprint> --chain <chain>` and passes the
64    //! `signtx` command and PSBT via stdin.
65    //! @param[in,out] psbt  PartiallySignedTransaction to be signed
66    bool SignTransaction(PartiallySignedTransaction& psbt, std::string& error);
67};
68
69#endif // BITCOIN_EXTERNAL_SIGNER_H
70