From fa208aa5ffe0225df2b58587dad9ed1a970d1f7b Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Tue, 25 Aug 2026 17:25:00 +0200 Subject: [PATCH 01/14] descriptor: add MultipathDescriptor ParseKeyPath already computes the position and values of a BIP 389 multipath specifier before expanding it into one key path per element, but discards them. Keep that information in each expanded BIP 32 and MuSig pubkey provider, so that any single sibling can reproduce the multipath string it came from, and add a flag to the descriptor string serialization that makes them emit it instead of their own path element. On top of that, add MultipathDescriptor, a wrapper around the expanded descriptors that Parse() produces for a BIP 389 multipath descriptor. It sets the flag to expose the combined multipath string forms, and a single DescriptorID computed over that string so all paths share one identifier. A multipath element at or before the last hardened derivation step ends up inside the origin of a normalized descriptor, where each sibling has a different last hardened xpub. There is no single normalized multipath string in that case, so ToNormalizedString fails. --- src/script/descriptor.cpp | 230 +++++++++++++++++++++++++--------- src/script/descriptor.h | 34 +++++ src/test/descriptor_tests.cpp | 70 +++++++++++ 3 files changed, 274 insertions(+), 60 deletions(-) diff --git a/src/script/descriptor.cpp b/src/script/descriptor.cpp index 5d9e62494726..ac848442e97d 100644 --- a/src/script/descriptor.cpp +++ b/src/script/descriptor.cpp @@ -176,6 +176,30 @@ std::string AddChecksum(const std::string& str) { return str + "#" + DescriptorC typedef std::vector KeyPath; +/** Retained multipath specifier info for a key expression that was expanded from + * a BIP 389 multipath descriptor. Each expanded sibling carries the same info, + * which allows any single sibling to reproduce the multipath string form. */ +struct MultipathInfo { + //! Index of the multipath element within the derivation path + size_t pos; + //! All values of the multipath specifier (hardened flag included), in the order they were listed + std::vector values; +}; + +/** Format a derivation path as a string, substituting the multipath specifier back in at its position. */ +static std::string FormatMultipathKeypath(const KeyPath& path, const MultipathInfo& multipath, bool apostrophe) +{ + const auto format_index{[&](uint32_t num) { + return strprintf("%u%s", num & ~BIP32_HARDENED_FLAG, (num & BIP32_HARDENED_FLAG) ? (apostrophe ? "'" : "h") : ""); + }}; + std::string ret{FormatHDKeypath({path.begin(), path.begin() + multipath.pos}, apostrophe) + "/<"}; + for (size_t i = 0; i < multipath.values.size(); ++i) { + if (i) ret += ";"; + ret += format_index(multipath.values[i]); + } + return ret + ">" + FormatHDKeypath({path.begin() + multipath.pos + 1, path.end()}, apostrophe); +} + /** Interface for public key objects in descriptors. */ struct PubkeyProvider { @@ -206,20 +230,23 @@ struct PubkeyProvider COMPAT // string calculation that mustn't change over time to stay compatible with previous software versions }; - /** Get the descriptor string form. */ - virtual std::string ToString(StringType type=StringType::PUBLIC) const = 0; + /** Get the descriptor string form. + * If multipath is set, providers expanded from a multipath descriptor emit + * the multipath specifier instead of their own path element. + */ + virtual std::string ToString(StringType type=StringType::PUBLIC, bool multipath=false) const = 0; /** Get the descriptor string form including private data (if available in arg). * If the private data is not available, the output string in the "out" parameter * will not contain any private key information, * and this function will return "false". */ - virtual bool ToPrivateString(const SigningProvider& arg, std::string& out) const = 0; + virtual bool ToPrivateString(const SigningProvider& arg, std::string& out, bool multipath=false) const = 0; /** Get the descriptor string form with the xpub at the last hardened derivation, * and always use h for hardened derivation. */ - virtual bool ToNormalizedString(const SigningProvider& arg, std::string& out, const DescriptorCache* cache = nullptr) const = 0; + virtual bool ToNormalizedString(const SigningProvider& arg, std::string& out, const DescriptorCache* cache = nullptr, bool multipath=false) const = 0; /** Derive a private key, if private data is available in arg and put it into out. */ virtual void GetPrivKey(int pos, const SigningProvider& arg, FlatSigningProvider& out) const = 0; @@ -287,18 +314,18 @@ class OriginPubkeyProvider final : public PubkeyProvider bool IsRange() const override { return m_provider->IsRange(); } size_t GetSize() const override { return m_provider->GetSize(); } bool IsBIP32() const override { return m_provider->IsBIP32(); } - std::string ToString(StringType type) const override { return "[" + OriginString(type) + "]" + m_provider->ToString(type); } - bool ToPrivateString(const SigningProvider& arg, std::string& ret) const override + std::string ToString(StringType type, bool multipath=false) const override { return "[" + OriginString(type) + "]" + m_provider->ToString(type, multipath); } + bool ToPrivateString(const SigningProvider& arg, std::string& ret, bool multipath=false) const override { std::string sub; - bool has_priv_key{m_provider->ToPrivateString(arg, sub)}; + bool has_priv_key{m_provider->ToPrivateString(arg, sub, multipath)}; ret = "[" + OriginString(StringType::PUBLIC) + "]" + std::move(sub); return has_priv_key; } - bool ToNormalizedString(const SigningProvider& arg, std::string& ret, const DescriptorCache* cache) const override + bool ToNormalizedString(const SigningProvider& arg, std::string& ret, const DescriptorCache* cache, bool multipath=false) const override { std::string sub; - if (!m_provider->ToNormalizedString(arg, sub, cache)) return false; + if (!m_provider->ToNormalizedString(arg, sub, cache, multipath)) return false; // If m_provider is a BIP32PubkeyProvider, we may get a string formatted like a OriginPubkeyProvider // In that case, we need to strip out the leading square bracket and fingerprint from the substring, // and append that to our own origin string. @@ -357,8 +384,8 @@ class ConstPubkeyProvider final : public PubkeyProvider bool IsRange() const override { return false; } size_t GetSize() const override { return m_pubkey.size(); } bool IsBIP32() const override { return false; } - std::string ToString(StringType type) const override { return m_xonly ? HexStr(m_pubkey).substr(2) : HexStr(m_pubkey); } - bool ToPrivateString(const SigningProvider& arg, std::string& ret) const override + std::string ToString(StringType type, bool multipath=false) const override { return m_xonly ? HexStr(m_pubkey).substr(2) : HexStr(m_pubkey); } + bool ToPrivateString(const SigningProvider& arg, std::string& ret, bool multipath=false) const override { std::optional key = GetPrivKey(arg); if (!key) { @@ -368,7 +395,7 @@ class ConstPubkeyProvider final : public PubkeyProvider ret = EncodeSecret(*key); return true; } - bool ToNormalizedString(const SigningProvider& arg, std::string& ret, const DescriptorCache* cache) const override + bool ToNormalizedString(const SigningProvider& arg, std::string& ret, const DescriptorCache* cache, bool multipath=false) const override { ret = ToString(StringType::PUBLIC); return true; @@ -409,6 +436,15 @@ class BIP32PubkeyProvider final : public PubkeyProvider DeriveType m_derive; // Whether ' or h is used in harded derivation bool m_apostrophe; + // Multipath specifier this provider was expanded from, if any + std::optional m_multipath; + + //! Format m_path, emitting the multipath specifier instead of its concrete element when requested + std::string PathToString(bool apostrophe, bool multipath) const + { + if (multipath && m_multipath) return FormatMultipathKeypath(m_path, *m_multipath, apostrophe); + return FormatHDKeypath(m_path, apostrophe); + } bool GetExtKey(const SigningProvider& arg, CExtKey& ret) const { @@ -442,7 +478,7 @@ class BIP32PubkeyProvider final : public PubkeyProvider } public: - BIP32PubkeyProvider(uint32_t exp_index, const CExtPubKey& extkey, KeyPath path, DeriveType derive, bool apostrophe) : PubkeyProvider(exp_index), m_root_extkey(extkey), m_path(std::move(path)), m_derive(derive), m_apostrophe(apostrophe) {} + BIP32PubkeyProvider(uint32_t exp_index, const CExtPubKey& extkey, KeyPath path, DeriveType derive, bool apostrophe, std::optional multipath = std::nullopt) : PubkeyProvider(exp_index), m_root_extkey(extkey), m_path(std::move(path)), m_derive(derive), m_apostrophe(apostrophe), m_multipath(std::move(multipath)) {} bool IsRange() const override { return m_derive != DeriveType::NON_RANGED; } size_t GetSize() const override { return 33; } bool IsBIP32() const override { return true; } @@ -506,39 +542,39 @@ class BIP32PubkeyProvider final : public PubkeyProvider return final_extkey.pubkey; } - std::string ToString(StringType type, bool normalized) const + std::string ToString(StringType type, bool normalized, bool multipath) const { // If StringType==COMPAT, always use the apostrophe to stay compatible with previous versions const bool use_apostrophe = (!normalized && m_apostrophe) || type == StringType::COMPAT; - std::string ret = EncodeExtPubKey(m_root_extkey) + FormatHDKeypath(m_path, /*apostrophe=*/use_apostrophe); + std::string ret = EncodeExtPubKey(m_root_extkey) + PathToString(/*apostrophe=*/use_apostrophe, multipath); if (IsRange()) { ret += "/*"; if (m_derive == DeriveType::HARDENED_RANGED) ret += use_apostrophe ? '\'' : 'h'; } return ret; } - std::string ToString(StringType type=StringType::PUBLIC) const override + std::string ToString(StringType type=StringType::PUBLIC, bool multipath=false) const override { - return ToString(type, /*normalized=*/false); + return ToString(type, /*normalized=*/false, multipath); } - bool ToPrivateString(const SigningProvider& arg, std::string& out) const override + bool ToPrivateString(const SigningProvider& arg, std::string& out, bool multipath=false) const override { CExtKey key; if (!GetExtKey(arg, key)) { - out = ToString(StringType::PUBLIC); + out = ToString(StringType::PUBLIC, multipath); return false; } - out = EncodeExtKey(key) + FormatHDKeypath(m_path, /*apostrophe=*/m_apostrophe); + out = EncodeExtKey(key) + PathToString(/*apostrophe=*/m_apostrophe, multipath); if (IsRange()) { out += "/*"; if (m_derive == DeriveType::HARDENED_RANGED) out += m_apostrophe ? '\'' : 'h'; } return true; } - bool ToNormalizedString(const SigningProvider& arg, std::string& out, const DescriptorCache* cache) const override + bool ToNormalizedString(const SigningProvider& arg, std::string& out, const DescriptorCache* cache, bool multipath=false) const override { if (m_derive == DeriveType::HARDENED_RANGED) { - out = ToString(StringType::PUBLIC, /*normalized=*/true); + out = ToString(StringType::PUBLIC, /*normalized=*/true, multipath); return true; } @@ -551,9 +587,13 @@ class BIP32PubkeyProvider final : public PubkeyProvider } // Either no derivation or all unhardened derivation if (i == -1) { - out = ToString(); + out = ToString(StringType::PUBLIC, multipath); return true; } + // A multipath element at or before the last hardened step would end up + // inside the normalized origin, where each sibling has a different + // last hardened xpub, so no single normalized multipath string exists. + if (multipath && m_multipath && m_multipath->pos <= (size_t)i) return false; // Get the path to the last hardened stup KeyOriginInfo origin; int k = 0; @@ -584,7 +624,15 @@ class BIP32PubkeyProvider final : public PubkeyProvider // Build the string std::string origin_str = HexStr(origin.fingerprint) + FormatHDKeypath(origin.path); - out = "[" + origin_str + "]" + EncodeExtPubKey(xpub) + FormatHDKeypath(end_path); + std::string end_path_str; + if (multipath && m_multipath) { + // The multipath element sits after the last hardened step; emit it + // at its position within the remaining path. + end_path_str = FormatMultipathKeypath(end_path, MultipathInfo{m_multipath->pos - (size_t)(i + 1), m_multipath->values}, /*apostrophe=*/false); + } else { + end_path_str = FormatHDKeypath(end_path); + } + out = "[" + origin_str + "]" + EncodeExtPubKey(xpub) + end_path_str; if (IsRange()) { out += "/*"; assert(m_derive == DeriveType::UNHARDENED_RANGED); @@ -610,7 +658,7 @@ class BIP32PubkeyProvider final : public PubkeyProvider } std::unique_ptr Clone() const override { - return std::make_unique(m_expr_index, m_root_extkey, m_path, m_derive, m_apostrophe); + return std::make_unique(m_expr_index, m_root_extkey, m_path, m_derive, m_apostrophe, m_multipath); } bool CanSelfExpand() const override { return !IsHardened(); } }; @@ -627,21 +675,32 @@ class MuSigPubkeyProvider final : public PubkeyProvider mutable std::unique_ptr m_aggregate_provider; mutable std::optional m_aggregate_pubkey; const DeriveType m_derive; + //! Multipath specifier the derivation path was expanded from, if any + const std::optional m_multipath; const bool m_ranged_participants; bool IsRangedDerivation() const { return m_derive != DeriveType::NON_RANGED; } + //! Format m_path, emitting the multipath specifier instead of its concrete element when requested + std::string PathToString(bool multipath) const + { + if (multipath && m_multipath) return FormatMultipathKeypath(m_path, *m_multipath, /*apostrophe=*/false); + return FormatHDKeypath(m_path); + } + public: MuSigPubkeyProvider( uint32_t exp_index, std::vector> providers, KeyPath path, - DeriveType derive + DeriveType derive, + std::optional multipath = std::nullopt ) : PubkeyProvider(exp_index), m_participants(std::move(providers)), m_path(std::move(path)), m_derive(derive), + m_multipath(std::move(multipath)), m_ranged_participants(std::any_of(m_participants.begin(), m_participants.end(), [](const auto& pubkey) { return pubkey->IsRange(); })) { if (!Assume(!(m_ranged_participants && IsRangedDerivation()))) { @@ -719,22 +778,22 @@ class MuSigPubkeyProvider final : public PubkeyProvider // musig() expressions can only be used in tr() contexts which have 32 byte xonly pubkeys size_t GetSize() const override { return 32; } - std::string ToString(StringType type=StringType::PUBLIC) const override + std::string ToString(StringType type=StringType::PUBLIC, bool multipath=false) const override { std::string out = "musig("; for (size_t i = 0; i < m_participants.size(); ++i) { const auto& pubkey = m_participants.at(i); if (i) out += ","; - out += pubkey->ToString(type); + out += pubkey->ToString(type, multipath); } out += ")"; - out += FormatHDKeypath(m_path); + out += PathToString(multipath); if (IsRangedDerivation()) { out += "/*"; } return out; } - bool ToPrivateString(const SigningProvider& arg, std::string& out) const override + bool ToPrivateString(const SigningProvider& arg, std::string& out, bool multipath=false) const override { bool any_privkeys = false; out = "musig("; @@ -742,32 +801,32 @@ class MuSigPubkeyProvider final : public PubkeyProvider const auto& pubkey = m_participants.at(i); if (i) out += ","; std::string tmp; - if (pubkey->ToPrivateString(arg, tmp)) { + if (pubkey->ToPrivateString(arg, tmp, multipath)) { any_privkeys = true; } out += tmp; } out += ")"; - out += FormatHDKeypath(m_path); + out += PathToString(multipath); if (IsRangedDerivation()) { out += "/*"; } return any_privkeys; } - bool ToNormalizedString(const SigningProvider& arg, std::string& out, const DescriptorCache* cache = nullptr) const override + bool ToNormalizedString(const SigningProvider& arg, std::string& out, const DescriptorCache* cache = nullptr, bool multipath=false) const override { out = "musig("; for (size_t i = 0; i < m_participants.size(); ++i) { const auto& pubkey = m_participants.at(i); if (i) out += ","; std::string tmp; - if (!pubkey->ToNormalizedString(arg, tmp, cache)) { + if (!pubkey->ToNormalizedString(arg, tmp, cache, multipath)) { return false; } out += tmp; } out += ")"; - out += FormatHDKeypath(m_path); + out += PathToString(multipath); if (IsRangedDerivation()) { out += "/*"; } @@ -810,7 +869,7 @@ class MuSigPubkeyProvider final : public PubkeyProvider for (const std::unique_ptr& p : m_participants) { providers.emplace_back(p->Clone()); } - return std::make_unique(m_expr_index, std::move(providers), m_path, m_derive); + return std::make_unique(m_expr_index, std::move(providers), m_path, m_derive, m_multipath); } bool IsBIP32() const override { @@ -915,7 +974,7 @@ class DescriptorImpl : public Descriptor } // NOLINTNEXTLINE(misc-no-recursion) - virtual bool ToStringSubScriptHelper(const SigningProvider* arg, std::string& ret, const StringType type, const DescriptorCache* cache = nullptr) const + virtual bool ToStringSubScriptHelper(const SigningProvider* arg, std::string& ret, const StringType type, const DescriptorCache* cache = nullptr, bool multipath = false) const { size_t pos = 0; bool is_private{type == StringType::PRIVATE}; @@ -925,7 +984,7 @@ class DescriptorImpl : public Descriptor for (const auto& scriptarg : m_subdescriptor_args) { if (pos++) ret += ","; std::string tmp; - bool subscript_res{scriptarg->ToStringHelper(arg, tmp, type, cache)}; + bool subscript_res{scriptarg->ToStringHelper(arg, tmp, type, cache, multipath)}; if (!is_private && !subscript_res) return false; any_success = any_success || subscript_res; ret += tmp; @@ -934,7 +993,7 @@ class DescriptorImpl : public Descriptor } // NOLINTNEXTLINE(misc-no-recursion) - virtual bool ToStringHelper(const SigningProvider* arg, std::string& out, const StringType type, const DescriptorCache* cache = nullptr) const + virtual bool ToStringHelper(const SigningProvider* arg, std::string& out, const StringType type, const DescriptorCache* cache = nullptr, bool multipath = false) const { std::string extra = ToStringExtra(); size_t pos = extra.size() > 0 ? 1 : 0; @@ -949,22 +1008,22 @@ class DescriptorImpl : public Descriptor std::string tmp; switch (type) { case StringType::NORMALIZED: - if (!pubkey->ToNormalizedString(*arg, tmp, cache)) return false; + if (!pubkey->ToNormalizedString(*arg, tmp, cache, multipath)) return false; break; case StringType::PRIVATE: - any_success = pubkey->ToPrivateString(*arg, tmp) || any_success; + any_success = pubkey->ToPrivateString(*arg, tmp, multipath) || any_success; break; case StringType::PUBLIC: - tmp = pubkey->ToString(); + tmp = pubkey->ToString(PubkeyProvider::StringType::PUBLIC, multipath); break; case StringType::COMPAT: - tmp = pubkey->ToString(PubkeyProvider::StringType::COMPAT); + tmp = pubkey->ToString(PubkeyProvider::StringType::COMPAT, multipath); break; } ret += tmp; } std::string subscript; - bool subscript_res{ToStringSubScriptHelper(arg, subscript, type, cache)}; + bool subscript_res{ToStringSubScriptHelper(arg, subscript, type, cache, multipath)}; if (!is_private && !subscript_res) return false; any_success = any_success || subscript_res; if (pos && subscript.size()) ret += ','; @@ -1520,7 +1579,7 @@ class TRDescriptor final : public DescriptorImpl out.tr_trees[output] = builder; return Vector(GetScriptForDestination(output)); } - bool ToStringSubScriptHelper(const SigningProvider* arg, std::string& ret, const StringType type, const DescriptorCache* cache = nullptr) const override + bool ToStringSubScriptHelper(const SigningProvider* arg, std::string& ret, const StringType type, const DescriptorCache* cache = nullptr, bool multipath = false) const override { if (m_depths.empty()) { // If there are no sub-descriptors and a PRIVATE string @@ -1543,7 +1602,7 @@ class TRDescriptor final : public DescriptorImpl path.push_back(false); } std::string tmp; - bool subscript_res{m_subdescriptor_args[pos]->ToStringHelper(arg, tmp, type, cache)}; + bool subscript_res{m_subdescriptor_args[pos]->ToStringHelper(arg, tmp, type, cache, multipath)}; if (!is_private && !subscript_res) return false; any_success = any_success || subscript_res; ret += tmp; @@ -1638,13 +1697,16 @@ class StringMaker { //! StringType to serialize keys const DescriptorImpl::StringType m_type; const DescriptorCache* m_cache; + //! Whether to emit multipath specifiers instead of the expanded path elements + const bool m_multipath; public: StringMaker(const SigningProvider* arg LIFETIMEBOUND, const std::vector>& pubkeys LIFETIMEBOUND, DescriptorImpl::StringType type, - const DescriptorCache* cache LIFETIMEBOUND) - : m_arg(arg), m_pubkeys(pubkeys), m_type(type), m_cache(cache) {} + const DescriptorCache* cache LIFETIMEBOUND, + bool multipath = false) + : m_arg(arg), m_pubkeys(pubkeys), m_type(type), m_cache(cache), m_multipath(multipath) {} std::optional ToString(uint32_t key, bool& has_priv_key) const { @@ -1652,16 +1714,16 @@ class StringMaker { has_priv_key = false; switch (m_type) { case DescriptorImpl::StringType::PUBLIC: - ret = m_pubkeys[key]->ToString(); + ret = m_pubkeys[key]->ToString(PubkeyProvider::StringType::PUBLIC, m_multipath); break; case DescriptorImpl::StringType::PRIVATE: - has_priv_key = m_pubkeys[key]->ToPrivateString(*m_arg, ret); + has_priv_key = m_pubkeys[key]->ToPrivateString(*m_arg, ret, m_multipath); break; case DescriptorImpl::StringType::NORMALIZED: - if (!m_pubkeys[key]->ToNormalizedString(*m_arg, ret, m_cache)) return {}; + if (!m_pubkeys[key]->ToNormalizedString(*m_arg, ret, m_cache, m_multipath)) return {}; break; case DescriptorImpl::StringType::COMPAT: - ret = m_pubkeys[key]->ToString(PubkeyProvider::StringType::COMPAT); + ret = m_pubkeys[key]->ToString(PubkeyProvider::StringType::COMPAT, m_multipath); break; } return ret; @@ -1710,10 +1772,10 @@ class MiniscriptDescriptor final : public DescriptorImpl } bool ToStringHelper(const SigningProvider* arg, std::string& out, const StringType type, - const DescriptorCache* cache = nullptr) const override + const DescriptorCache* cache = nullptr, bool multipath = false) const override { bool has_priv_key{false}; - auto res = m_node.ToString(StringMaker(arg, m_pubkey_args, type, cache), has_priv_key); + auto res = m_node.ToString(StringMaker(arg, m_pubkey_args, type, cache, multipath), has_priv_key); if (res) out = *res; if (type == StringType::PRIVATE) { Assume(res.has_value()); @@ -1824,9 +1886,10 @@ enum class ParseScriptContext { * @param[out] error parsing error message * @param[in] allow_multipath Allows the parsed path to use the multipath specifier * @param[out] has_hardened Records whether the path contains any hardened derivation + * @param[out] multipath_out If not null, set to the multipath specifier info when one was parsed * @returns false if parsing failed **/ -[[nodiscard]] bool ParseKeyPath(const std::vector>& split, std::vector& out, bool& apostrophe, std::string& error, bool allow_multipath, bool& has_hardened) +[[nodiscard]] bool ParseKeyPath(const std::vector>& split, std::vector& out, bool& apostrophe, std::string& error, bool allow_multipath, bool& has_hardened, std::optional* multipath_out = nullptr) { auto parse_elem = [&](std::span elem) -> std::optional { const auto parsed{ParseKeyPathElement(elem)}; @@ -1895,6 +1958,7 @@ enum class ParseScriptContext { if (!substitutes) { out.emplace_back(std::move(path)); } else { + if (multipath_out) *multipath_out = MultipathInfo{substitutes->placeholder_index, substitutes->values}; // Replace the multipath placeholder with each value while generating paths for (uint32_t substitute : substitutes->values) { KeyPath branch_path = path; @@ -1992,13 +2056,15 @@ std::vector> ParsePubkeyInner(uint32_t& key_exp_ } std::vector paths; DeriveType type = ParseDeriveType(split, apostrophe); - if (!ParseKeyPath(split, paths, apostrophe, error, /*allow_multipath=*/true)) return {}; + bool dummy_has_hardened{false}; + std::optional multipath; + if (!ParseKeyPath(split, paths, apostrophe, error, /*allow_multipath=*/true, dummy_has_hardened, &multipath)) return {}; if (extkey.key.IsValid()) { extpubkey = extkey.Neuter(); out.keys.emplace(extpubkey.pubkey.GetID(), extkey.key); } for (auto& path : paths) { - ret.emplace_back(std::make_unique(key_exp_index, extpubkey, std::move(path), type, apostrophe)); + ret.emplace_back(std::make_unique(key_exp_index, extpubkey, std::move(path), type, apostrophe, multipath)); } ++key_exp_index; return ret; @@ -2067,6 +2133,7 @@ std::vector> ParsePubkey(uint32_t& key_exp_index // Parse any derivation DeriveType deriv_type = DeriveType::NON_RANGED; std::vector derivation_multipaths; + std::optional derivation_multipath_info; if (split.size() == 2 && Const("/", split.at(1), /*skip=*/false)) { if (!all_bip32) { error = "musig(): derivation requires all participants to be xpubs or xprvs"; @@ -2084,7 +2151,7 @@ std::vector> ParsePubkey(uint32_t& key_exp_index return {}; } bool has_hardened = false; - if (!ParseKeyPath(deriv_split, derivation_multipaths, dummy, error, /*allow_multipath=*/true, has_hardened)) { + if (!ParseKeyPath(deriv_split, derivation_multipaths, dummy, error, /*allow_multipath=*/true, has_hardened, &derivation_multipath_info)) { error = "musig(): " + error; return {}; } @@ -2113,14 +2180,14 @@ std::vector> ParsePubkey(uint32_t& key_exp_index // Emplace the final MuSigPubkeyProvider into ret with the pubkey providers from the specified provider vectors index // and the path from the specified path index - const auto& emplace_final_provider = [&ret, &key_exp_index, &deriv_type, &derivation_multipaths, &providers](size_t vec_idx, size_t path_idx) -> void { + const auto& emplace_final_provider = [&ret, &key_exp_index, &deriv_type, &derivation_multipaths, &derivation_multipath_info, &providers](size_t vec_idx, size_t path_idx) -> void { KeyPath& path = derivation_multipaths.at(path_idx); std::vector> pubs; pubs.reserve(providers.size()); for (auto& vec : providers) { pubs.emplace_back(std::move(vec.at(vec_idx))); } - ret.emplace_back(std::make_unique(key_exp_index, std::move(pubs), path, deriv_type)); + ret.emplace_back(std::make_unique(key_exp_index, std::move(pubs), path, deriv_type, derivation_multipath_info)); }; if (max_multipath_len > 1 && derivation_multipaths.size() > 1) { @@ -2993,6 +3060,49 @@ uint256 DescriptorID(const Descriptor& desc) return id; } +MultipathDescriptor::MultipathDescriptor(std::vector> descs) +{ + assert(descs.size() >= 2); + m_descriptors.reserve(descs.size()); + for (auto& desc : descs) { + m_descriptors.emplace_back(std::move(desc)); + } +} + +std::string MultipathDescriptor::ToString(bool compat_format) const +{ + // All paths carry the same multipath annotations, so any single one can + // reproduce the multipath string; use the first. + const auto& desc = dynamic_cast(*m_descriptors.front()); + std::string ret; + desc.ToStringHelper(nullptr, ret, compat_format ? DescriptorImpl::StringType::COMPAT : DescriptorImpl::StringType::PUBLIC, nullptr, /*multipath=*/true); + return AddChecksum(ret); +} + +bool MultipathDescriptor::ToPrivateString(const SigningProvider& provider, std::string& out) const +{ + const auto& desc = dynamic_cast(*m_descriptors.front()); + bool has_priv_key{desc.ToStringHelper(&provider, out, DescriptorImpl::StringType::PRIVATE, nullptr, /*multipath=*/true)}; + out = AddChecksum(out); + return has_priv_key; +} + +bool MultipathDescriptor::ToNormalizedString(const SigningProvider& provider, std::string& out, const DescriptorCache* cache) const +{ + const auto& desc = dynamic_cast(*m_descriptors.front()); + if (!desc.ToStringHelper(&provider, out, DescriptorImpl::StringType::NORMALIZED, cache, /*multipath=*/true)) return false; + out = AddChecksum(out); + return true; +} + +uint256 DescriptorID(const MultipathDescriptor& desc) +{ + std::string desc_str = desc.ToString(/*compat_format=*/true); + uint256 id; + CSHA256().Write((unsigned char*)desc_str.data(), desc_str.size()).Finalize(id.begin()); + return id; +} + void DescriptorCache::CacheParentExtPubKey(uint32_t key_exp_pos, const CExtPubKey& xpub) { m_parent_xpubs[key_exp_pos] = xpub; diff --git a/src/script/descriptor.h b/src/script/descriptor.h index 26781629cbf3..fdb1e324f357 100644 --- a/src/script/descriptor.h +++ b/src/script/descriptor.h @@ -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> m_descriptors; + +public: + //! descs must be the (at least two) sibling descriptors produced by a single Parse() call. + explicit MultipathDescriptor(std::vector> 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& 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` @@ -244,4 +274,8 @@ std::unique_ptr 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 diff --git a/src/test/descriptor_tests.cpp b/src/test/descriptor_tests.cpp index ed410dfbb148..bf975491582d 100644 --- a/src/test/descriptor_tests.cpp +++ b/src/test/descriptor_tests.cpp @@ -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. @@ -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>> 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() From e1d8dce04a6fc925c3c483b19c0a43e3c79931cc Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Tue, 25 Aug 2026 11:09:30 +0200 Subject: [PATCH 02/14] wallet: refactor WalletDescriptor to per-path state Replace the single range_start/next_index/range_end/cache state of WalletDescriptor with a vector of per-path states, in preparation for storing multipath descriptors that track a separate address range and derivation cache per path. Accessors take a path index defaulting to 0 and the vector has size one for single path descriptors, so behavior and serialization are unchanged. --- src/wallet/export.cpp | 3 ++- src/wallet/rpc/util.cpp | 2 +- src/wallet/scriptpubkeyman.cpp | 20 ++++++++-------- src/wallet/wallet.cpp | 2 +- src/wallet/walletdb.cpp | 2 +- src/wallet/walletutil.h | 42 ++++++++++++++++++++++------------ 6 files changed, 42 insertions(+), 29 deletions(-) diff --git a/src/wallet/export.cpp b/src/wallet/export.cpp index 9f9a9486db88..7f213dd7139d 100644 --- a/src/wallet/export.cpp +++ b/src/wallet/export.cpp @@ -109,7 +109,8 @@ util::Result ExportWatchOnlyWallet(const CWallet& wallet, const fs: uint256 desc_id = w_desc.id; if (!w_desc.descriptor->CanSelfExpand()) { DescriptorScriptPubKeyMan* desc_spkm = dynamic_cast(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); + w_desc.CacheAt() = desc_spkm->GetWalletDescriptor().CacheAt(); } // Add to the watchonly wallet diff --git a/src/wallet/rpc/util.cpp b/src/wallet/rpc/util.cpp index 77a8745ced7e..0f355dc88f2c 100644 --- a/src/wallet/rpc/util.cpp +++ b/src/wallet/rpc/util.cpp @@ -115,7 +115,7 @@ void PushParentDescriptors(const CWallet& wallet, const CScript& script_pubkey, for (const auto& desc: wallet.GetWalletDescriptors(script_pubkey)) { std::string desc_str; FlatSigningProvider dummy_provider; - if (!CHECK_NONFATAL(desc.descriptor->ToNormalizedString(dummy_provider, desc_str, &desc.cache))) continue; + if (!CHECK_NONFATAL(desc.descriptor->ToNormalizedString(dummy_provider, desc_str, &desc.CacheAt()))) continue; parent_descs.push_back(desc_str); } entry.pushKV("parent_descs", std::move(parent_descs)); diff --git a/src/wallet/scriptpubkeyman.cpp b/src/wallet/scriptpubkeyman.cpp index 30742753602e..713be7aeb53b 100644 --- a/src/wallet/scriptpubkeyman.cpp +++ b/src/wallet/scriptpubkeyman.cpp @@ -900,7 +900,7 @@ void DescriptorScriptPubKeyMan::SetRangeEnd(int32_t end) AssertLockHeld(cs_desc_man); const auto old_can = CanGetAddresses(); - m_wallet_descriptor.SetEnd(end); + m_wallet_descriptor.SetEnd(/*path=*/0, end); const auto new_can = CanGetAddresses(); if (old_can != new_can) { NotifyCanGetAddressesChanged(); @@ -931,7 +931,7 @@ util::Result DescriptorScriptPubKeyMan::GetNewDestination(const // We can't generate anymore keys return util::Error{_("Error: Keypool ran out, please call keypoolrefill first")}; } - if (!m_wallet_descriptor.descriptor->ExpandFromCache(m_wallet_descriptor.GetNext(), m_wallet_descriptor.cache, scripts_temp, out_keys)) { + if (!m_wallet_descriptor.descriptor->ExpandFromCache(m_wallet_descriptor.GetNext(), m_wallet_descriptor.CacheAt(), scripts_temp, out_keys)) { // We can't generate anymore keys return util::Error{_("Error: Keypool ran out, please call keypoolrefill first")}; } @@ -1111,7 +1111,7 @@ bool DescriptorScriptPubKeyMan::TopUpWithDB(WalletBatch& batch, unsigned int siz std::vector scripts_temp; DescriptorCache temp_cache; // Maybe we have a cached xpub and we can expand from the cache first - if (!m_wallet_descriptor.descriptor->ExpandFromCache(i, m_wallet_descriptor.cache, scripts_temp, out_keys)) { + if (!m_wallet_descriptor.descriptor->ExpandFromCache(i, m_wallet_descriptor.CacheAt(), scripts_temp, out_keys)) { if (!m_wallet_descriptor.descriptor->Expand(i, provider, scripts_temp, out_keys, &temp_cache)) return false; } // Add all of the scriptPubKeys to the scriptPubKey set @@ -1129,7 +1129,7 @@ bool DescriptorScriptPubKeyMan::TopUpWithDB(WalletBatch& batch, unsigned int siz m_map_pubkeys[pubkey] = i; } // Merge and write the cache - DescriptorCache new_items = m_wallet_descriptor.cache.MergeAndDiff(temp_cache); + DescriptorCache new_items = m_wallet_descriptor.CacheAt().MergeAndDiff(temp_cache); if (!batch.WriteDescriptorCacheItems(id, new_items)) { throw std::runtime_error(std::string(__func__) + ": writing cache items failed"); } @@ -1156,7 +1156,7 @@ std::vector DescriptorScriptPubKeyMan::MarkUnusedAddresses(co auto out_keys = std::make_unique(); std::vector scripts_temp; while (index >= m_wallet_descriptor.GetNext()) { - if (!m_wallet_descriptor.descriptor->ExpandFromCache(m_wallet_descriptor.GetNext(), m_wallet_descriptor.cache, scripts_temp, *out_keys)) { + if (!m_wallet_descriptor.descriptor->ExpandFromCache(m_wallet_descriptor.GetNext(), m_wallet_descriptor.CacheAt(), scripts_temp, *out_keys)) { throw std::runtime_error(std::string(__func__) + ": Unable to expand descriptor from cache"); } CTxDestination dest; @@ -1327,7 +1327,7 @@ std::unique_ptr DescriptorScriptPubKeyMan::GetSigningProvid } else { // Get the scripts, keys, and key origins for this script std::vector scripts_temp; - if (!m_wallet_descriptor.descriptor->ExpandFromCache(index, m_wallet_descriptor.cache, scripts_temp, *out_keys)) return nullptr; + if (!m_wallet_descriptor.descriptor->ExpandFromCache(index, m_wallet_descriptor.CacheAt(), scripts_temp, *out_keys)) return nullptr; // Cache SigningProvider so we don't need to re-derive if we need this SigningProvider again m_map_signing_providers[index] = *out_keys; @@ -1514,7 +1514,7 @@ void DescriptorScriptPubKeyMan::Load() for (int32_t i = m_wallet_descriptor.GetStart(); i < m_wallet_descriptor.GetEnd(); ++i) { FlatSigningProvider out_keys; std::vector scripts_temp; - if (!m_wallet_descriptor.descriptor->ExpandFromCache(i, m_wallet_descriptor.cache, scripts_temp, out_keys)) { + if (!m_wallet_descriptor.descriptor->ExpandFromCache(i, m_wallet_descriptor.CacheAt(), scripts_temp, out_keys)) { throw std::runtime_error("Error: Unable to expand wallet descriptor from cache"); } // Add all of the scriptPubKeys to the scriptPubKey set @@ -1596,7 +1596,7 @@ bool DescriptorScriptPubKeyMan::GetDescriptorString(std::string& out, const bool return m_wallet_descriptor.descriptor->ToPrivateString(provider, out); } - return m_wallet_descriptor.descriptor->ToNormalizedString(provider, out, &m_wallet_descriptor.cache); + return m_wallet_descriptor.descriptor->ToNormalizedString(provider, out, &m_wallet_descriptor.CacheAt()); } void DescriptorScriptPubKeyMan::UpgradeDescriptorCache() @@ -1607,7 +1607,7 @@ void DescriptorScriptPubKeyMan::UpgradeDescriptorCache() } // Skip if we have the last hardened xpub cache - if (m_wallet_descriptor.cache.GetCachedLastHardenedExtPubKeys().size() > 0) { + if (m_wallet_descriptor.CacheAt().GetCachedLastHardenedExtPubKeys().size() > 0) { return; } @@ -1622,7 +1622,7 @@ void DescriptorScriptPubKeyMan::UpgradeDescriptorCache() } // Cache the last hardened xpubs - DescriptorCache diff = m_wallet_descriptor.cache.MergeAndDiff(temp_cache); + DescriptorCache diff = m_wallet_descriptor.CacheAt().MergeAndDiff(temp_cache); if (!WalletBatch(m_storage.GetDatabase()).WriteDescriptorCacheItems(GetID(), diff)) { throw std::runtime_error(std::string(__func__) + ": writing cache items failed"); } diff --git a/src/wallet/wallet.cpp b/src/wallet/wallet.cpp index 310e9ea07a1b..2c614572e1eb 100644 --- a/src/wallet/wallet.cpp +++ b/src/wallet/wallet.cpp @@ -3819,7 +3819,7 @@ util::Result> CWallet::AddWall // Write the existing cache to disk WalletBatch batch(GetDatabase()); - if (!batch.WriteDescriptorCacheItems(id, desc.cache)) { + if (!batch.WriteDescriptorCacheItems(id, desc.CacheAt())) { return util::Error{_("Unable to write descriptor cache")}; } } diff --git a/src/wallet/walletdb.cpp b/src/wallet/walletdb.cpp index 1a9ebaa3549e..cecade06a3ae 100644 --- a/src/wallet/walletdb.cpp +++ b/src/wallet/walletdb.cpp @@ -837,7 +837,7 @@ static DBErrors LoadDescriptorWalletRecords(CWallet* pwallet, DatabaseBatch& bat result = std::max(result, lh_cache_res.m_result); // Set the cache to the WalletDescriptor - desc.cache = cache; + desc.CacheAt() = cache; // Get unencrypted keys KeyMap keys; diff --git a/src/wallet/walletutil.h b/src/wallet/walletutil.h index a85a339a2da9..d4f445cbde9a 100644 --- a/src/wallet/walletutil.h +++ b/src/wallet/walletutil.h @@ -62,39 +62,50 @@ fs::path GetWalletDir(); /** Descriptor with some wallet metadata */ class WalletDescriptor { +public: + //! Address generation state, kept per derivation path of a multipath descriptor + struct PathState { + int32_t next_index = 0; // Position of the next item to generate + int32_t range_end = 0; // Item after the last; end of range, exclusive, i.e. [range_start, range_end). This will increment with each TopUp() + DescriptorCache cache; + }; + private: - int32_t range_start = 0; // First item in range; start of range, inclusive, i.e. [range_start, range_end). This never changes. - int32_t next_index = 0; // Position of the next item to generate - int32_t range_end = 0; // Item after the last; end of range, exclusive, i.e. [range_start, range_end). This will increment with each TopUp() + int32_t range_start = 0; // First item in range; start of range, inclusive, i.e. [range_start, range_end). Shared by all paths and never changes. + std::vector m_paths{PathState{}}; // One entry per derivation path; size 1 for single path descriptors public: std::shared_ptr descriptor; uint256 id; // Descriptor ID (calculated once at descriptor initialization/deserialization) uint64_t creation_time = 0; - DescriptorCache cache; + + size_t NumPaths() const { return m_paths.size(); } + + DescriptorCache& CacheAt(size_t path = 0) { return m_paths.at(path).cache; } + const DescriptorCache& CacheAt(size_t path = 0) const { return m_paths.at(path).cache; } int32_t GetStart() const { return range_start; } - int32_t GetNext() const { return next_index; } - int32_t GetEnd() const { return range_end; } + int32_t GetNext(size_t path = 0) const { return m_paths.at(path).next_index; } + int32_t GetEnd(size_t path = 0) const { return m_paths.at(path).range_end; } //! Increments the next_index of the descriptor. - void IncNext() + void IncNext(size_t path = 0) { - next_index++; + m_paths.at(path).next_index++; } //! Increments the next_index of the descriptor. - void DecNext() + void DecNext(size_t path = 0) { - next_index--; + m_paths.at(path).next_index--; } //! Sets the range_end of the descriptor. - void SetEnd(int32_t end) + void SetEnd(size_t path, int32_t end) { if (!descriptor->IsRange()) { CHECK_NONFATAL(end == 1); } - range_end = end; + m_paths.at(path).range_end = end; } void DeserializeDescriptor(const std::string& str) @@ -116,15 +127,16 @@ class WalletDescriptor { std::string descriptor_str; SER_WRITE(obj, descriptor_str = obj.descriptor->ToString()); - READWRITE(descriptor_str, obj.creation_time, obj.next_index, obj.range_start, obj.range_end); + READWRITE(descriptor_str, obj.creation_time, obj.m_paths.at(0).next_index, obj.range_start, obj.m_paths.at(0).range_end); SER_READ(obj, obj.DeserializeDescriptor(descriptor_str)); } WalletDescriptor() = default; WalletDescriptor(std::shared_ptr descriptor, uint64_t creation_time, int32_t range_start, int32_t range_end, int32_t next_index) : range_start(descriptor->IsRange() ? range_start : 0), - next_index(next_index), - range_end(descriptor->IsRange() ? range_end : 1), + m_paths{{next_index, + descriptor->IsRange() ? range_end : 1, + DescriptorCache{}}}, descriptor(descriptor), id(DescriptorID(*descriptor)), creation_time(creation_time) {} From 11ece83f4bf15e65bcea075159fbab0a26c3aa93 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Tue, 25 Aug 2026 14:02:34 +0200 Subject: [PATCH 03/14] wallet: add WALLET_FLAG_MULTIPATH_DESCRIPTORS Add a mandatory (backward incompatible) wallet flag indicating that the wallet stores its descriptors as BIP 389 multipath records covering both the receive and change chain. Nothing sets it yet. Because the flag is in the mandatory range, previous versions refuse to open such a wallet with a clear 'requires newer version' error instead of misinterpreting its descriptor records. --- src/wallet/wallet.h | 9 ++++++--- src/wallet/walletutil.h | 8 ++++++++ 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/src/wallet/wallet.h b/src/wallet/wallet.h index 61ba2dea2634..3bd44dc3a9c9 100644 --- a/src/wallet/wallet.h +++ b/src/wallet/wallet.h @@ -154,7 +154,8 @@ inline constexpr uint64_t KNOWN_WALLET_FLAGS = | WALLET_FLAG_LAST_HARDENED_XPUB_CACHED | WALLET_FLAG_DISABLE_PRIVATE_KEYS | WALLET_FLAG_DESCRIPTORS - | WALLET_FLAG_EXTERNAL_SIGNER; + | WALLET_FLAG_EXTERNAL_SIGNER + | WALLET_FLAG_MULTIPATH_DESCRIPTORS; inline constexpr uint64_t MUTABLE_WALLET_FLAGS = WALLET_FLAG_AVOID_REUSE; @@ -166,7 +167,8 @@ inline const std::map WALLET_FLAG_TO_STRING{ {WALLET_FLAG_LAST_HARDENED_XPUB_CACHED, "last_hardened_xpub_cached"}, {WALLET_FLAG_DISABLE_PRIVATE_KEYS, "disable_private_keys"}, {WALLET_FLAG_DESCRIPTORS, "descriptor_wallet"}, - {WALLET_FLAG_EXTERNAL_SIGNER, "external_signer"} + {WALLET_FLAG_EXTERNAL_SIGNER, "external_signer"}, + {WALLET_FLAG_MULTIPATH_DESCRIPTORS, "multipath_descriptors"} }; inline const std::map STRING_TO_WALLET_FLAG{ @@ -176,7 +178,8 @@ inline const std::map STRING_TO_WALLET_FLAG{ {WALLET_FLAG_TO_STRING.at(WALLET_FLAG_LAST_HARDENED_XPUB_CACHED), WALLET_FLAG_LAST_HARDENED_XPUB_CACHED}, {WALLET_FLAG_TO_STRING.at(WALLET_FLAG_DISABLE_PRIVATE_KEYS), WALLET_FLAG_DISABLE_PRIVATE_KEYS}, {WALLET_FLAG_TO_STRING.at(WALLET_FLAG_DESCRIPTORS), WALLET_FLAG_DESCRIPTORS}, - {WALLET_FLAG_TO_STRING.at(WALLET_FLAG_EXTERNAL_SIGNER), WALLET_FLAG_EXTERNAL_SIGNER} + {WALLET_FLAG_TO_STRING.at(WALLET_FLAG_EXTERNAL_SIGNER), WALLET_FLAG_EXTERNAL_SIGNER}, + {WALLET_FLAG_TO_STRING.at(WALLET_FLAG_MULTIPATH_DESCRIPTORS), WALLET_FLAG_MULTIPATH_DESCRIPTORS} }; /** A wrapper to reserve an address from a wallet diff --git a/src/wallet/walletutil.h b/src/wallet/walletutil.h index d4f445cbde9a..c2ea77d460fc 100644 --- a/src/wallet/walletutil.h +++ b/src/wallet/walletutil.h @@ -54,6 +54,14 @@ enum WalletFlags : uint64_t { //! Indicates that the wallet needs an external signer WALLET_FLAG_EXTERNAL_SIGNER = (1ULL << 35), + + //! Indicates that the wallet stores its descriptors in multipath form: + //! each descriptor record is a BIP 389 multipath descriptor with exactly + //! two derivation paths, covering both the receive and change chain, and + //! the wallet only supports such descriptors. Mandatory so that previous + //! versions, which can only load single path descriptor records, refuse + //! to open the wallet. + WALLET_FLAG_MULTIPATH_DESCRIPTORS = (1ULL << 36), }; //! Get the path of the wallet directory. From 60487cacd606d2fd2744666626ccf8a2d37b5de3 Mon Sep 17 00:00:00 2001 From: Sjors Provoost Date: Tue, 25 Aug 2026 14:03:37 +0200 Subject: [PATCH 04/14] wallet: store multipath descriptors in WalletDescriptor Let WalletDescriptor hold a MultipathDescriptor. The record serializes the multipath string followed by one (next_index, range_start, range_end) triplet per path, which leaves single path records byte-for-byte unchanged. Loading previously rejected every multipath record. It now cross-checks that multipath records only appear in wallets with the flag and vice versa, except for scriptless unused() HD key containers, which stay single path in either kind of wallet. While the record format supports any number of paths, loading is restricted to exactly two (a receive and change pair), so that wallets written by a hypothetical future version storing more paths are refused rather than misinterpreted. --- src/wallet/test/walletdb_tests.cpp | 31 ++++++++++++++++++++ src/wallet/test/walletload_tests.cpp | 42 ++++++++++++++++++++++++++++ src/wallet/walletdb.cpp | 18 ++++++++++++ src/wallet/walletutil.h | 42 ++++++++++++++++++++++++---- 4 files changed, 127 insertions(+), 6 deletions(-) diff --git a/src/wallet/test/walletdb_tests.cpp b/src/wallet/test/walletdb_tests.cpp index b3741f09895a..fe33f3a8366b 100644 --- a/src/wallet/test/walletdb_tests.cpp +++ b/src/wallet/test/walletdb_tests.cpp @@ -4,6 +4,8 @@ #include #include +#include