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
83 changes: 64 additions & 19 deletions src/script/descriptor.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
#include <util/vector.h>

#include <algorithm>
#include <array>
#include <compare>
#include <map>
#include <memory>
Expand Down Expand Up @@ -233,6 +234,17 @@ static std::string MergeNormalizedOrigin(const std::string& origin_str, const st
return "[" + origin_str + "]" + key_str;
}

/** Find the extended private key among xprvs from which xpub derives via origin. */
static std::optional<CExtKey> FindOriginExtKey(const std::map<CExtPubKey, CExtKey>& xprvs, const KeyOriginInfo& origin, const CExtPubKey& xpub)
{
for (const auto& [root_xpub, root_xprv] : xprvs) {
if (root_xpub.id_key_fingerprint() != origin.fingerprint) continue;
const auto derived{DeriveExtKey(root_xprv, origin.path)};
if (derived && derived->first.Neuter() == xpub) return root_xprv;
}
return std::nullopt;
}

/** A source-text replacement used by Parse() to construct the public form of a
* multipath descriptor string. */
struct KeyReplacement {
Expand Down Expand Up @@ -2076,18 +2088,27 @@ static DeriveType ParseDeriveType(std::vector<std::span<const char>>& split, boo

/** Parsed providers and an optional replacement for ParsePubkey to collect
* after processing explicit key origin information. */
using ParsePubkeyInnerResult = std::pair<std::vector<std::unique_ptr<PubkeyProvider>>, std::optional<KeyReplacement>>;
struct ParsePubkeyInnerResult {
std::vector<std::unique_ptr<PubkeyProvider>> providers;
std::optional<KeyReplacement> key_replacement;
//! Whether a known extended private key replaced the explicit key origin
bool origin_absorbed{false};
};
using ParsePubkeyResult = std::vector<std::unique_ptr<PubkeyProvider>>;

/** Mutable state shared by recursive descriptor parser calls. */
struct ParseState {
uint32_t& key_exp_index;
FlatSigningProvider& out;
std::vector<KeyReplacement>* key_replacements{nullptr};
const std::map<CExtPubKey, CExtKey>* known_xprvs{nullptr};
};

/** Parse a public key that excludes origin information. */
util::Expected<ParsePubkeyInnerResult, std::string> ParsePubkeyInner(ParseState& state, const std::span<const char>& sp, ParseScriptContext ctx, bool& apostrophe)
/** Parse the key part of a key expression, after the caller split off any
* origin information and parsed it into origin. The origin is only used to
* match a known extended private key, which then replaces it by the full
* derivation path in the providers. */
util::Expected<ParsePubkeyInnerResult, std::string> ParsePubkeyInner(ParseState& state, const std::span<const char>& sp, ParseScriptContext ctx, bool& apostrophe, const KeyOriginInfo* origin)
{
std::vector<std::unique_ptr<PubkeyProvider>> ret;
// Return the replacement separately so ParsePubkey can incorporate an explicit
Expand Down Expand Up @@ -2159,18 +2180,39 @@ util::Expected<ParsePubkeyInnerResult, std::string> ParsePubkeyInner(ParseState&
std::string error;
if (!ParseKeyPath(split, paths, apostrophe, error, /*allow_multipath=*/true, has_hardened_path)) return util::Unexpected{std::move(error)};
const bool has_hardened_derivation{type == DeriveType::HARDENED_RANGED || has_hardened_path};
bool origin_absorbed{false};
if (extkey.key.IsValid()) {
extpubkey = extkey.Neuter();
state.out.keys.emplace(extpubkey.pubkey.GetID(), extkey.key);
if (state.key_replacements) key_replacement = NormalizedExtKeyReplacement(split, paths, type, extkey, extpubkey);
} else if (state.key_replacements && has_hardened_derivation) {
key_replacement = KeyReplacement{split[0], str, /*publicly_derivable=*/false};
} else {
if (state.key_replacements && has_hardened_derivation) {
key_replacement = KeyReplacement{split[0], str, /*publicly_derivable=*/false};
}
// Fill in a known private key. The multipath replacement above is
// left as is: known keys do not change the multipath descriptor.
if (state.known_xprvs) {
if (const auto it{state.known_xprvs->find(extpubkey)}; it != state.known_xprvs->end()) {
// The key expression names a known key directly. Keep the
// expression, and provide the private key as if the
// descriptor had contained it.
state.out.keys.emplace(extpubkey.pubkey.GetID(), it->second.key);
} else if (const auto root{origin ? FindOriginExtKey(*state.known_xprvs, *origin, extpubkey) : std::nullopt}) {
// The key expression names a child of a known key. Replace
// the origin and the child key by the known key and the full
// path, like a descriptor containing that key.
extpubkey = root->Neuter();
state.out.keys.emplace(extpubkey.pubkey.GetID(), root->key);
for (auto& path : paths) path.insert(path.begin(), origin->path.begin(), origin->path.end());
origin_absorbed = true;
}
}
}
for (auto& path : paths) {
ret.emplace_back(std::make_unique<BIP32PubkeyProvider>(state.key_exp_index, extpubkey, std::move(path), type, apostrophe));
}
++state.key_exp_index;
return ParsePubkeyInnerResult{std::move(ret), std::move(key_replacement)};
return ParsePubkeyInnerResult{std::move(ret), std::move(key_replacement), origin_absorbed};
}

/** Parse a public key including origin information (if enabled). */
Expand Down Expand Up @@ -2318,11 +2360,10 @@ util::Expected<ParsePubkeyResult, std::string> ParsePubkey(ParseState& state, co
if (origin_split.size() == 1) {
// With no closing ']', there is no complete origin to apply. Parse the
// entire expression as a key and collect its replacement unchanged.
auto result = ParsePubkeyInner(state, origin_split[0], ctx, apostrophe);
auto result = ParsePubkeyInner(state, origin_split[0], ctx, apostrophe, /*origin=*/nullptr);
if (!result) return util::Unexpected{std::move(result.error())};
auto [providers, key_replacement] = std::move(*result);
if (key_replacement) state.key_replacements->push_back(std::move(*key_replacement));
return std::move(providers);
if (result->key_replacement) state.key_replacements->push_back(std::move(*result->key_replacement));
return std::move(result->providers);
}
// The only remaining case has one closing ']', whose prefix must start with '['.
Assume(origin_split.size() == 2);
Expand All @@ -2348,9 +2389,9 @@ util::Expected<ParsePubkeyResult, std::string> ParsePubkey(ParseState& state, co
std::string error;
if (!ParseKeyPath(slash_split, path, apostrophe, error, /*allow_multipath=*/false)) return util::Unexpected{std::move(error)};
info.path = path.at(0);
auto result = ParsePubkeyInner(state, origin_split[1], ctx, apostrophe);
auto result = ParsePubkeyInner(state, origin_split[1], ctx, apostrophe, &info);
if (!result) return util::Unexpected{std::move(result.error())};
auto [providers, key_replacement] = std::move(*result);
auto [providers, key_replacement, origin_absorbed] = std::move(*result);
if (key_replacement) {
// Include the explicit origin in the replacement, merging it with any
// origin produced by normalization, like OriginPubkeyProvider does.
Expand All @@ -2364,6 +2405,8 @@ util::Expected<ParsePubkeyResult, std::string> ParsePubkey(ParseState& state, co
const std::span<const char> origin_text{sp.data(), origin_split[0].size() + 1};
state.key_replacements->push_back({origin_text, "[" + HexStr(info.fingerprint) + FormatHDKeypath(info.path) + "]"});
}
// A known key already accounts for the origin in the providers' paths.
if (origin_absorbed) return std::move(providers);
ret.reserve(providers.size());
for (auto& prov : providers) {
ret.emplace_back(std::make_unique<OriginPubkeyProvider>(prov->m_expr_index, info, std::move(prov), apostrophe));
Expand Down Expand Up @@ -2420,11 +2463,13 @@ struct KeyParser {
uint32_t& m_expr_index;
//! Source-text replacements collected while parsing Miniscript keys, if requested.
std::vector<KeyReplacement>* m_key_replacements;
//! Extended private keys known to the caller, if any.
const std::map<CExtPubKey, CExtKey>* m_known_xprvs;

KeyParser(FlatSigningProvider* out LIFETIMEBOUND, const SigningProvider* in LIFETIMEBOUND,
miniscript::MiniscriptContext ctx, uint32_t& key_exp_index LIFETIMEBOUND,
std::vector<KeyReplacement>* key_replacements = nullptr)
: m_out(out), m_in(in), m_script_ctx(ctx), m_expr_index(key_exp_index), m_key_replacements(key_replacements) {}
std::vector<KeyReplacement>* key_replacements = nullptr, const std::map<CExtPubKey, CExtKey>* known_xprvs = nullptr)
: m_out(out), m_in(in), m_script_ctx(ctx), m_expr_index(key_exp_index), m_key_replacements(key_replacements), m_known_xprvs(known_xprvs) {}

bool KeyCompare(const Key& a, const Key& b) const {
// Deriving a hardened step needs the private key, so use the provider that was filled
Expand Down Expand Up @@ -2454,7 +2499,7 @@ struct KeyParser {
{
assert(m_out);
Key key = m_keys.size();
ParseState state{m_expr_index, *m_out, m_key_replacements};
ParseState state{m_expr_index, *m_out, m_key_replacements, m_known_xprvs};
auto result = ParsePubkey(state, in, ParseContext());
if (!result) {
m_key_parsing_error = std::move(result.error());
Expand Down Expand Up @@ -2822,7 +2867,7 @@ util::Expected<ParseScriptResult, std::string> ParseScript(ParseState& state, st
// Process miniscript expressions.
{
const auto script_ctx{ctx == ParseScriptContext::P2WSH ? miniscript::MiniscriptContext::P2WSH : miniscript::MiniscriptContext::TAPSCRIPT};
KeyParser parser(/*out = */&state.out, /* in = */nullptr, /* ctx = */script_ctx, state.key_exp_index, state.key_replacements);
KeyParser parser(/*out = */&state.out, /* in = */nullptr, /* ctx = */script_ctx, state.key_exp_index, state.key_replacements, state.known_xprvs);
auto node = miniscript::FromString(std::string_view{expr.data(), expr.size()}, parser);
if (parser.m_key_parsing_error != "") {
return util::Unexpected{std::move(parser.m_key_parsing_error)};
Expand Down Expand Up @@ -3093,15 +3138,15 @@ bool CheckChecksum(std::span<const char>& sp, bool require_checksum, std::string
return true;
}

std::vector<std::unique_ptr<Descriptor>> Parse(std::string_view descriptor, FlatSigningProvider& out, std::string& error, bool require_checksum, std::optional<std::string>* multipath)
std::vector<std::unique_ptr<Descriptor>> Parse(std::string_view descriptor, FlatSigningProvider& out, std::string& error, bool require_checksum, std::optional<std::string>* multipath, const std::map<CExtPubKey, CExtKey>* known_xprvs)
{
if (multipath) multipath->reset();
std::span<const char> sp{descriptor};
if (!CheckChecksum(sp, require_checksum, error)) return {};
const std::string_view no_checksum{sp.data(), sp.size()};
uint32_t key_exp_index = 0;
std::vector<KeyReplacement> key_replacements;
ParseState state{key_exp_index, out, multipath ? &key_replacements : nullptr};
ParseState state{key_exp_index, out, multipath ? &key_replacements : nullptr, known_xprvs};
auto result = ParseScript(state, sp, ParseScriptContext::TOP);
if (!result) {
error = std::move(result.error());
Expand All @@ -3117,7 +3162,7 @@ std::vector<std::unique_ptr<Descriptor>> Parse(std::string_view descriptor, Flat
std::ranges::replace(canonical, '\'', 'h');
std::span<const char> sp_canonical{canonical};
key_exp_index = 0;
ParseState canonical_state{key_exp_index, out};
ParseState canonical_state{key_exp_index, out, /*key_replacements=*/nullptr, known_xprvs};
auto canonical_result = ParseScript(canonical_state, sp_canonical, ParseScriptContext::TOP);
// Only the marker stored in the pubkey providers differs, so this
// parse cannot fail.
Expand Down
10 changes: 9 additions & 1 deletion src/script/descriptor.h
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@

#include <cstddef>
#include <cstdint>
#include <map>
#include <memory>
#include <optional>
#include <set>
Expand All @@ -22,6 +23,7 @@

class CScript;
class SigningProvider;
struct CExtKey;
struct FlatSigningProvider;

using ExtPubKeyMap = std::unordered_map<uint32_t, CExtPubKey>;
Expand Down Expand Up @@ -234,9 +236,15 @@ util::Expected<void, std::string> CheckDescriptorRangeBounds(int64_t low, int64_
* public forms. Private extended keys followed by a fixed hardened prefix are
* normalized by replacing them with their key origin and the extended public
* key at the last hardened step.
* @param[in] known_xprvs If provided, extended private keys known to the
* caller, by their public form, to fill in for the extended public keys of
* `descriptor` as if it contained them. A key expression with an explicit key
* origin that leads from one of these keys to its extended public key is
* replaced by that key and the full derivation path. The keys are put in
* `out`, and do not affect `multipath`.
* @return Parsed descriptors, or an empty vector on error.
*/
std::vector<std::unique_ptr<Descriptor>> Parse(std::string_view descriptor, FlatSigningProvider& out, std::string& error, bool require_checksum = false, std::optional<std::string>* multipath = nullptr);
std::vector<std::unique_ptr<Descriptor>> Parse(std::string_view descriptor, FlatSigningProvider& out, std::string& error, bool require_checksum = false, std::optional<std::string>* multipath = nullptr, const std::map<CExtPubKey, CExtKey>* known_xprvs = nullptr);

/** Get the checksum for a `descriptor`.
*
Expand Down
59 changes: 59 additions & 0 deletions src/test/descriptor_tests.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -1591,4 +1591,63 @@ BOOST_AUTO_TEST_CASE(parse_multipath_string_test)
check("wsh(or_b(pk(" + wif + "),s:pk(" + xprv + "/<0;1>/*)))", "wsh(or_b(pk(" + HexStr(pubkey) + "),s:pk(" + xpub + "/<0;1>/*)))", 2);
}

BOOST_AUTO_TEST_CASE(descriptor_known_keys)
{
// BIP 32 test vector 1: master key with fingerprint 3442193e, and m/0h
const std::string xprv{"xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jPPqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHi"};
const std::string xpub{"xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8"};
const std::string xpub_0h{"xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw"};

std::map<CExtPubKey, CExtKey> known;
const CExtKey ext_key{DecodeExtKey(xprv)};
known.emplace(ext_key.Neuter(), ext_key);

const auto with_checksum = [](const std::string& desc) { return desc + "#" + GetDescriptorChecksum(desc); };
// Parse desc with the known keys and check its public form, and its
// private form if expected.
const auto check = [&](const std::string& desc, const std::string& expected_pub, const std::string& expected_priv, const std::map<CExtPubKey, CExtKey>* known_xprvs) {
FlatSigningProvider keys;
std::string error;
const auto parsed{Parse(desc, keys, error, /*require_checksum=*/false, /*multipath=*/nullptr, known_xprvs)};
BOOST_REQUIRE_MESSAGE(parsed.size() == 1, error);
BOOST_CHECK_EQUAL(parsed[0]->ToString(), with_checksum(expected_pub));
std::string priv;
if (expected_priv.empty()) {
BOOST_CHECK(!parsed[0]->ToPrivateString(keys, priv));
} else {
BOOST_REQUIRE(parsed[0]->ToPrivateString(keys, priv));
BOOST_CHECK_EQUAL(priv, with_checksum(expected_priv));
}
};

// The origin and the key derived from it are replaced by the known key and the full path
check("pkh([3442193e/0h]" + xpub_0h + "/1/*)", "pkh(" + xpub + "/0h/1/*)", "pkh(" + xprv + "/0h/1/*)", &known);
// The hardened marker of the origin is kept
check("pkh([3442193e/0']" + xpub_0h + "/1/*)", "pkh(" + xpub + "/0'/1/*)", "pkh(" + xprv + "/0'/1/*)", &known);
// A known extended key is filled in as is
check("pkh(" + xpub + "/0h/1/*)", "pkh(" + xpub + "/0h/1/*)", "pkh(" + xprv + "/0h/1/*)", &known);
// Inside miniscript and musig
check("wsh(pk([3442193e/0h]" + xpub_0h + "/1/*))", "wsh(pk(" + xpub + "/0h/1/*))", "wsh(pk(" + xprv + "/0h/1/*))", &known);
check("tr(musig([3442193e/0h]" + xpub_0h + "," + xpub + ")/1/*)", "tr(musig(" + xpub + "/0h," + xpub + ")/1/*)", "tr(musig(" + xprv + "/0h," + xprv + ")/1/*)", &known);
// A mismatched fingerprint or path leaves the descriptor unchanged
check("pkh([deadbeef/0h]" + xpub_0h + "/1/*)", "pkh([deadbeef/0h]" + xpub_0h + "/1/*)", "", &known);
check("pkh([3442193e/1h]" + xpub_0h + "/1/*)", "pkh([3442193e/1h]" + xpub_0h + "/1/*)", "", &known);
// Without known keys, nothing is filled in
check("pkh([3442193e/0h]" + xpub_0h + "/1/*)", "pkh([3442193e/0h]" + xpub_0h + "/1/*)", "", nullptr);

// A multipath descriptor expands with the known key, including when its
// apostrophe hardened markers make it parse a second time
{
FlatSigningProvider keys;
std::string error;
const auto parsed{Parse("pkh([3442193e/0']" + xpub_0h + "/<0;1>/*)", keys, error, /*require_checksum=*/false, /*multipath=*/nullptr, &known)};
BOOST_REQUIRE_MESSAGE(parsed.size() == 2, error);
for (size_t i{0}; i < parsed.size(); ++i) {
std::string priv;
BOOST_REQUIRE(parsed[i]->ToPrivateString(keys, priv));
BOOST_CHECK_EQUAL(priv, with_checksum("pkh(" + xprv + "/0h/" + util::ToString(i) + "/*)"));
}
}
}

BOOST_AUTO_TEST_SUITE_END()
8 changes: 6 additions & 2 deletions src/wallet/imports.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,15 @@ ImportResult ImportDescriptor(CWallet& wallet, const ImportDescriptorRequest& re

std::vector<std::string> warnings;

// Parse descriptor string
// Parse descriptor string, filling in the wallet's HD private keys
FlatSigningProvider keys;
std::string error;
std::optional<std::string> multipath_normalized;
auto parsed_descs = Parse(request.descriptor, keys, error, /*require_checksum=*/true, &multipath_normalized);
std::map<CExtPubKey, CExtKey> known_xprvs;
for (const auto& [xpub, spkms] : wallet.GetHDPubKeys(CWallet::HDKeyFilter::All)) {
if (std::optional<CExtKey> xprv{wallet.GetExtKey(xpub)}) known_xprvs.emplace(xpub, *xprv);
}
auto parsed_descs = Parse(request.descriptor, keys, error, /*require_checksum=*/true, &multipath_normalized, &known_xprvs);
if (parsed_descs.empty()) {
return ImportResult(WalletErrorCode::InvalidDescriptor, error, warnings);
}
Expand Down
2 changes: 1 addition & 1 deletion src/wallet/rpc/backup.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -186,7 +186,7 @@ RPCMethod importdescriptors()
{
{"", RPCArg::Type::OBJ, RPCArg::Optional::OMITTED, "",
{
{"desc", RPCArg::Type::STR, RPCArg::Optional::NO, "Descriptor to import."},
{"desc", RPCArg::Type::STR, RPCArg::Optional::NO, "Descriptor to import. HD keys of the wallet, given as their extended public key or an origin from it, are imported with their private key."},
{"active", RPCArg::Type::BOOL, RPCArg::Default{false}, "Set this descriptor to be the active descriptor for the corresponding output type/externality"},
{"range", RPCArg::Type::RANGE, RPCArg::Optional::OMITTED, "If a ranged descriptor is used, this specifies the end or the range (in the form [begin,end]) to import"},
{"next_index", RPCArg::Type::NUM, RPCArg::Optional::OMITTED, "If a ranged descriptor is set to active, this specifies the next index to generate addresses from"},
Expand Down
Loading
Loading