Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion doc/external-signer.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@ The command MAY complain if `--chain` is set to a test-network, but any of the B
Usage:

```sh
<cmd> --fingerprint <fingerprint> --chain <name> getdescriptors --account <account>
<cmd> --fingerprint <fingerprint> --chain <name> getdescriptors --account <account> [--multipath]
```

Returns descriptors supported by the device. Example:
Expand All @@ -185,6 +185,29 @@ Returns descriptors supported by the device. Example:
}
```

#### Flag `--multipath` (optional)

With `--multipath` the command MUST instead return a flat array of [BIP 389](https://github.com/bitcoin/bips/blob/master/bip-0389.mediawiki)
multipath descriptors, each combining the receive and change chain in a single
descriptor with a `<0;1>` element:

```sh
<cmd> --fingerprint 00000000 --chain main getdescriptors --account 0 --multipath
```

```
[
"pkh([00000000/44h/0h/0h]xpub6C.../<0;1>/*)#tw6cmp0h",
"sh(wpkh([00000000/49h/0h/0h]xpub6B..../<0;1>/*))#tetlyt9c",
"wpkh([00000000/84h/0h/0h]xpub6C.../<0;1>/*)#3ryl7uz3",
"tr([00000000/86h/0h/0h]xpub6C.../<0;1>/*)#kpq6q00r"
]
```

Bitcoin Core passes this flag when creating a wallet with the `multipath`
option. A command that does not support the flag MUST fail rather than ignore
it, so that the wallet is not silently created from single path descriptors.

### `displayaddress` (optional)

Usage:
Expand Down
9 changes: 7 additions & 2 deletions src/external_signer.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -72,9 +72,14 @@ UniValue ExternalSigner::DisplayAddress(const std::string& descriptor) const
return RunCommandParseJSON(Cat(m_command, Cat(Cat({"--fingerprint", m_fingerprint}, NetworkArg()), {"displayaddress", "--desc", descriptor})), "");
}

UniValue ExternalSigner::GetDescriptors(const int account)
UniValue ExternalSigner::GetDescriptors(const int account, const bool multipath)
{
return RunCommandParseJSON(Cat(m_command, Cat(Cat({"--fingerprint", m_fingerprint}, NetworkArg()), {"getdescriptors", "--account", strprintf("%d", account)})), "");
std::vector<std::string> args{"getdescriptors", "--account", strprintf("%d", account)};
// Signers that predate this argument exit with an error, which is what we
// want: silently falling back to single path descriptors would create a
// wallet that does not match what was asked for.
if (multipath) args.emplace_back("--multipath");
return RunCommandParseJSON(Cat(m_command, Cat(Cat({"--fingerprint", m_fingerprint}, NetworkArg()), args)), "");
}

bool ExternalSigner::SignTransaction(PartiallySignedTransaction& psbtx, std::string& error)
Expand Down
9 changes: 6 additions & 3 deletions src/external_signer.h
Original file line number Diff line number Diff line change
Expand Up @@ -54,10 +54,13 @@ class ExternalSigner

//! Get receive and change Descriptor(s) from device for a given account.
//! Calls `<command> --fingerprint <fingerprint> --chain <chain> getdescriptors
//! --account <account>`.
//! @param[in] account which BIP32 account to use (e.g. `m/44'/0'/account'`)
//! --account <account> [--multipath]`.
//! @param[in] account which BIP32 account to use (e.g. `m/44'/0'/account'`)
//! @param[in] multipath ask for BIP 389 multipath descriptors, which combine the
//! receive and change chain. Signers that do not support this
//! are expected to fail rather than ignore the argument.
//! @returns see doc/external-signer.md
UniValue GetDescriptors(int account);
UniValue GetDescriptors(int account, bool multipath = false);

//! Sign PartiallySignedTransaction on the device.
//! Calls `<command> --stdin --fingerprint <fingerprint> --chain <chain>` and passes the
Expand Down
1 change: 1 addition & 0 deletions src/rpc/client.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -365,6 +365,7 @@ static const CRPCConvertParam vRPCConvertParams[] =
{ "createwallet", 5, "descriptors"},
{ "createwallet", 6, "load_on_startup"},
{ "createwallet", 7, "external_signer"},
{ "createwallet", 8, "multipath"},
{ "restorewallet", 0, "wallet_name", ParamFormat::STRING },
{ "restorewallet", 1, "backup_file", ParamFormat::STRING },
{ "restorewallet", 2, "load_on_startup"},
Expand Down
230 changes: 170 additions & 60 deletions src/script/descriptor.cpp

Large diffs are not rendered by default.

34 changes: 34 additions & 0 deletions src/script/descriptor.h
Original file line number Diff line number Diff line change
Expand Up @@ -205,6 +205,36 @@ struct Descriptor {
virtual size_t GetKeyCount() const = 0;
};

/** A parsed BIP 389 multipath descriptor.
*
* Holds the expanded single-path descriptors that Parse() produced for each
* element of the multipath specifier, while retaining the ability to emit the
* combined multipath string forms and a single descriptor identifier.
*/
class MultipathDescriptor
{
//! The expanded per-path descriptors, in the order the multipath specifier lists them.
std::vector<std::shared_ptr<Descriptor>> m_descriptors;

public:
//! descs must be the (at least two) sibling descriptors produced by a single Parse() call.
explicit MultipathDescriptor(std::vector<std::unique_ptr<Descriptor>> descs);

//! Number of paths in the multipath specifier.
size_t PathCount() const { return m_descriptors.size(); }
//! The expanded descriptor for the given path index.
const std::shared_ptr<Descriptor>& PathAt(size_t path) const { return m_descriptors.at(path); }

/** Convert back to the multipath descriptor string, with checksum. */
std::string ToString(bool compat_format = false) const;
/** Convert to the multipath private string, see Descriptor::ToPrivateString. */
bool ToPrivateString(const SigningProvider& provider, std::string& out) const;
/** Convert to the multipath normalized string, see Descriptor::ToNormalizedString.
* Also fails when no single normalized multipath form exists, which is the
* case for hardened multipath specifiers. */
bool ToNormalizedString(const SigningProvider& provider, std::string& out, const DescriptorCache* cache = nullptr) const;
};

/** Parse a `descriptor` string. Included private keys are put in `out`.
*
* If the descriptor has a checksum, it must be valid. If `require_checksum`
Expand Down Expand Up @@ -244,4 +274,8 @@ std::unique_ptr<Descriptor> InferDescriptor(const CScript& script, const Signing
*/
uint256 DescriptorID(const Descriptor& desc);

/** DescriptorID of a multipath descriptor, computed over its combined multipath string,
* so that all paths share a single identifier. */
uint256 DescriptorID(const MultipathDescriptor& desc);

#endif // BITCOIN_SCRIPT_DESCRIPTOR_H
70 changes: 70 additions & 0 deletions src/test/descriptor_tests.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -533,6 +533,38 @@ void CheckMultipath(const std::string& prv,
expanded_prvs.at(i), expanded_pubs.at(i), i);
}

// Any single path can reproduce the multipath string forms, and all paths share one identifier.
const auto parse_multipath{[&](const std::string& desc_str, FlatSigningProvider& keys) {
std::string parse_error;
auto parsed{Parse(desc_str, keys, parse_error)};
BOOST_REQUIRE_MESSAGE(parsed.size() == expanded_pubs.size(), desc_str + ": " + parse_error);
return MultipathDescriptor{std::move(parsed)};
}};
FlatSigningProvider keys_prv, keys_pub;
const MultipathDescriptor multipath_prv{parse_multipath(prv, keys_prv)};
const MultipathDescriptor multipath_pub{parse_multipath(pub, keys_pub)};

BOOST_CHECK_MESSAGE(EqualDescriptor(multipath_prv.ToString(), pub), "Private ser: " + multipath_prv.ToString() + " Public desc: " + pub);
BOOST_CHECK_MESSAGE(EqualDescriptor(multipath_pub.ToString(), pub), "Public ser: " + multipath_pub.ToString() + " Public desc: " + pub);

std::string prv_ser;
BOOST_CHECK(multipath_prv.ToPrivateString(keys_prv, prv_ser));
BOOST_CHECK_MESSAGE(EqualDescriptor(prv_ser, prv), "Private ser: " + prv_ser + " Private desc: " + prv);
BOOST_CHECK(multipath_pub.ToPrivateString(keys_prv, prv_ser));
BOOST_CHECK_MESSAGE(EqualDescriptor(prv_ser, prv), "Private ser: " + prv_ser + " Private desc: " + prv);
BOOST_CHECK(!multipath_pub.ToPrivateString(keys_pub, prv_ser));

// The expanded descriptors keep emitting their own concrete path
BOOST_CHECK_EQUAL(multipath_pub.PathCount(), expanded_pubs.size());
for (size_t i = 0; i < expanded_pubs.size(); ++i) {
const std::string path_ser{multipath_pub.PathAt(i)->ToString()};
BOOST_CHECK_MESSAGE(EqualDescriptor(path_ser, expanded_pubs.at(i)), "Path ser: " + path_ser + " Path desc: " + expanded_pubs.at(i));
}

// All paths share one identifier, which is not the identifier of any single path
BOOST_CHECK(DescriptorID(multipath_prv) == DescriptorID(multipath_pub));
BOOST_CHECK(DescriptorID(multipath_pub) != DescriptorID(*multipath_pub.PathAt(0)));

// The descriptor for each path must be standalone. They should not share common references. Test this
// by parsing a multipath descriptor expression, deallocating all but one of the descriptors and making
// sure we can perform operations on it.
Expand Down Expand Up @@ -1418,4 +1450,42 @@ BOOST_AUTO_TEST_CASE(unused_descriptor_test)
CheckUnused("unused(xprvA1RpRA33e1JQ7ifknakTFpgNXPmW2YvmhqLQYMmrj4xJXXWYpDPS3xz7iAxn8L39njGVyuoseXzU6rcxFLJ8HFsTjSyQbLYnMpCqE2VbFWc/0h/0h/1)", "unused(xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/0h/0h/1)");
}

BOOST_AUTO_TEST_CASE(multipath_descriptor_normalized_string)
{
const std::string master_xprv{"xprv9s21ZrQH143K31xYSDQpPDxsXRTUcvj2iNHm5NUtrGiGG5e2DtALGdso3pGz6ssrdK4PFmM8NSpSBHNqPqm55Qn3LqFtT2emdEXVYsCzC2U"};
const std::string master_xpub{"xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB"};
// The above, derived at 2147483647h
const std::string hardened_xpub{"xpub69H7F5dQzmVd3vPuLKtcXJziMEQByuDidnX3YdwgtNsecY5HRGtAAQC5mXTt4dsv9RzyjgDjAQs9VGVV6ydYCHnprc9vvaA5YtqWyL6hyds"};

// Normalized form of each multipath descriptor, or std::nullopt if it has none.
const std::vector<std::pair<std::string, std::optional<std::string>>> cases{
// Without hardened derivation the normalized form is the public form
{"pkh(" + master_xprv + "/<0;1>/0)", "pkh(" + master_xpub + "/<0;1>/0)"},
// A hardened step before the multipath element moves into the origin
{"pkh(" + master_xprv + "/2147483647h/<0;1>)", "pkh([bd16bee5/2147483647h]" + hardened_xpub + "/<0;1>)"},
// Each path of a hardened multipath specifier normalizes to a different last
// hardened xpub, so there is no single normalized multipath string
{"pkh(" + master_xprv + "/<2147483647h;0>/0)", std::nullopt},
};

for (const auto& [desc_str, norm] : cases) {
FlatSigningProvider keys;
std::string error;
auto parsed{Parse(desc_str, keys, error)};
BOOST_REQUIRE_MESSAGE(parsed.size() == 2, desc_str + ": " + error);
const MultipathDescriptor desc{std::move(parsed)};
std::string norm_ser;
BOOST_CHECK_EQUAL(desc.ToNormalizedString(keys, norm_ser), norm.has_value());
if (norm) BOOST_CHECK_MESSAGE(EqualDescriptor(norm_ser, *norm), "Normalized ser: " + norm_ser + " Norm. desc: " + *norm);
}

// The identifier is computed over the compat format, which always uses the
// apostrophe, so the hardened marker of the input does not affect it.
FlatSigningProvider keys_h, keys_apostrophe;
std::string error;
const MultipathDescriptor desc_h{Parse("pkh(" + master_xprv + "/<2147483647h;0>/0)", keys_h, error)};
const MultipathDescriptor desc_apostrophe{Parse("pkh(" + master_xprv + "/<2147483647\';0>/0)", keys_apostrophe, error)};
BOOST_CHECK(DescriptorID(desc_h) == DescriptorID(desc_apostrophe));
}

BOOST_AUTO_TEST_SUITE_END()
54 changes: 40 additions & 14 deletions src/wallet/export.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -31,13 +31,21 @@ util::Expected<std::vector<WalletDescInfo>, std::string> ExportDescriptors(const
return util::Unexpected{"Can't get descriptor string."};
}
const bool is_range = wallet_descriptor.descriptor->IsRange();
const bool is_multipath = wallet_descriptor.IsMultipath();
// For a multipath descriptor, report the range up to the furthest path
// end and the next index of each chain.
int64_t range_end = wallet_descriptor.GetEnd();
for (size_t path = 1; path < wallet_descriptor.NumPaths(); ++path) {
range_end = std::max<int64_t>(range_end, wallet_descriptor.GetEnd(path));
}
wallet_descriptors.emplace_back(
descriptor,
wallet_descriptor.creation_time,
wallet.IsActiveScriptPubKeyMan(*desc_spk_man),
wallet.IsInternalScriptPubKeyMan(desc_spk_man),
is_range ? std::optional(std::make_pair(wallet_descriptor.GetStart(), wallet_descriptor.GetEnd())) : std::nullopt,
wallet_descriptor.GetNext()
is_range ? std::optional(std::pair<int64_t, int64_t>(wallet_descriptor.GetStart(), range_end)) : std::nullopt,
wallet_descriptor.GetNext(),
is_multipath ? std::optional<int64_t>(wallet_descriptor.GetNext(1)) : std::nullopt
);
}
return wallet_descriptors;
Expand Down Expand Up @@ -92,7 +100,9 @@ util::Result<std::string> ExportWatchOnlyWallet(const CWallet& wallet, const fs:
FlatSigningProvider dummy_keys;
std::string dummy_err;
std::vector<std::unique_ptr<Descriptor>> descs = Parse(desc_info.descriptor, dummy_keys, dummy_err, /*require_checksum=*/true);
CHECK_NONFATAL(descs.size() == 1); // All of our descriptors should be valid, and not multipath
CHECK_NONFATAL(!descs.empty()); // All of our descriptors should be valid
// Only multipath wallets export multipath descriptors, and vice versa
CHECK_NONFATAL((descs.size() > 1) == wallet.IsWalletFlagSet(WALLET_FLAG_MULTIPATH_DESCRIPTORS));
CHECK_NONFATAL(dummy_keys.keys.size() == 0); // No private keys should be present in our exported descriptors

// Get the range if there is one
Expand All @@ -103,29 +113,45 @@ util::Result<std::string> ExportWatchOnlyWallet(const CWallet& wallet, const fs:
range_end = desc_info.range->second;
}

WalletDescriptor w_desc(std::move(descs.at(0)), desc_info.creation_time, range_start, range_end, desc_info.next_index);
std::optional<WalletDescriptor> w_desc;
if (descs.size() > 1) {
w_desc.emplace(std::make_shared<MultipathDescriptor>(std::move(descs)), desc_info.creation_time, range_start, range_end, desc_info.next_index);
if (desc_info.next_index_internal) w_desc->SetNext(/*path=*/1, *desc_info.next_index_internal);
} else {
w_desc.emplace(std::move(descs.at(0)), desc_info.creation_time, range_start, range_end, desc_info.next_index);
}

// For descriptors that cannot self expand (i.e. needs private keys or cache), retrieve the cache
uint256 desc_id = w_desc.id;
if (!w_desc.descriptor->CanSelfExpand()) {
uint256 desc_id = w_desc->id;
if (!w_desc->descriptor->CanSelfExpand()) {
DescriptorScriptPubKeyMan* desc_spkm = dynamic_cast<DescriptorScriptPubKeyMan*>(wallet.GetScriptPubKeyMan(desc_id));
w_desc.cache = WITH_LOCK(desc_spkm->cs_desc_man, return desc_spkm->GetWalletDescriptor().cache);
LOCK(desc_spkm->cs_desc_man);
for (size_t path = 0; path < w_desc->NumPaths(); ++path) {
w_desc->CacheAt(path) = desc_spkm->GetWalletDescriptor().CacheAt(path);
}
}

// Add to the watchonly wallet
if (auto spkm_res = watchonly_wallet->AddWalletDescriptor(w_desc, dummy_keys, /*label=*/"", /*internal=*/false); !spkm_res) {
if (auto spkm_res = watchonly_wallet->AddWalletDescriptor(*w_desc, dummy_keys, /*label=*/"", /*internal=*/false); !spkm_res) {
return util::Error{util::ErrorString(spkm_res)};
}

// Set active spkms as active
if (desc_info.active) {
// Determine whether this descriptor is internal
// This is only set for active spkms
bool internal = false;
if (desc_info.internal) {
internal = *desc_info.internal;
const OutputType output_type = *Assert(w_desc->descriptor->GetOutputType());
if (w_desc->IsMultipath()) {
// A multipath descriptor covers both chains
watchonly_wallet->AddActiveScriptPubKeyMan(desc_id, output_type, /*internal=*/false);
watchonly_wallet->AddActiveScriptPubKeyMan(desc_id, output_type, /*internal=*/true);
} else {
// Determine whether this descriptor is internal
// This is only set for active spkms
bool internal = false;
if (desc_info.internal) {
internal = *desc_info.internal;
}
watchonly_wallet->AddActiveScriptPubKeyMan(desc_id, output_type, internal);
}
watchonly_wallet->AddActiveScriptPubKeyMan(desc_id, *Assert(w_desc.descriptor->GetOutputType()), internal);
}
}

Expand Down
3 changes: 3 additions & 0 deletions src/wallet/export.h
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,9 @@ struct WalletDescInfo {
std::optional<bool> internal;
std::optional<std::pair<int64_t,int64_t>> range;
int64_t next_index;
//! The next index of the change chain; only set for multipath descriptors,
//! whose next_index refers to the receive chain
std::optional<int64_t> next_index_internal;
};

//! Export the descriptors from a wallet so that they can be imported elsewhere
Expand Down
18 changes: 12 additions & 6 deletions src/wallet/external_signer_scriptpubkeyman.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -26,19 +26,15 @@ std::unique_ptr<ExternalSignerScriptPubKeyMan> ExternalSignerScriptPubKeyMan::Lo
return std::unique_ptr<ExternalSignerScriptPubKeyMan>(new ExternalSignerScriptPubKeyMan(storage, descriptor, keypool_size, keys, ckeys));
}

std::unique_ptr<ExternalSignerScriptPubKeyMan> ExternalSignerScriptPubKeyMan::CreateNew(WalletStorage& storage, WalletBatch& batch, int64_t keypool_size, std::unique_ptr<Descriptor> desc)
std::unique_ptr<ExternalSignerScriptPubKeyMan> ExternalSignerScriptPubKeyMan::CreateNew(WalletStorage& storage, WalletBatch& batch, int64_t keypool_size, WalletDescriptor&& w_desc)
{
auto spkm = std::unique_ptr<ExternalSignerScriptPubKeyMan>(new ExternalSignerScriptPubKeyMan(storage, keypool_size));

LOCK(spkm->cs_desc_man);
assert(storage.IsWalletFlagSet(WALLET_FLAG_DESCRIPTORS));
assert(storage.IsWalletFlagSet(WALLET_FLAG_EXTERNAL_SIGNER));

int64_t creation_time = GetTime();

// Make the descriptor
WalletDescriptor w_desc(std::move(desc), creation_time, 0, 0, 0);
spkm->m_wallet_descriptor = w_desc;
spkm->m_wallet_descriptor = std::move(w_desc);

// Store the descriptor
if (!batch.WriteDescriptor(spkm->GetID(), spkm->m_wallet_descriptor)) {
Expand All @@ -52,6 +48,16 @@ std::unique_ptr<ExternalSignerScriptPubKeyMan> ExternalSignerScriptPubKeyMan::Cr
return spkm;
}

std::unique_ptr<ExternalSignerScriptPubKeyMan> ExternalSignerScriptPubKeyMan::CreateNew(WalletStorage& storage, WalletBatch& batch, int64_t keypool_size, std::unique_ptr<Descriptor> desc)
{
return CreateNew(storage, batch, keypool_size, WalletDescriptor(std::move(desc), /*creation_time=*/GetTime(), 0, 0, 0));
}

std::unique_ptr<ExternalSignerScriptPubKeyMan> ExternalSignerScriptPubKeyMan::CreateNew(WalletStorage& storage, WalletBatch& batch, int64_t keypool_size, std::shared_ptr<MultipathDescriptor> desc)
{
return CreateNew(storage, batch, keypool_size, WalletDescriptor(std::move(desc), /*creation_time=*/GetTime(), 0, 0, 0));
}

util::Result<ExternalSigner> ExternalSignerScriptPubKeyMan::GetExternalSigner() {
const std::string command = gArgs.GetArg("-signer", "");
if (command == "") return util::Error{Untranslated("restart bitcoind with -signer=<cmd>")};
Expand Down
Loading
Loading