descriptor: Represent multipath descriptors in a single Descriptor object #36442

pull achow101 wants to merge 8 commits into bitcoin:master from achow101:multipath-first-class changing 39 files +771 −672
  1. achow101 commented at 10:14 PM on October 5, 2026: member

    Currently, multipath descriptor strings treat the multipath specifiers as syntactic sugar. Once we finish parsing such a string, the multipath elements are lost as the result is the multiple distinct descriptors that the multipath is a shorthand for. This means that we are unable to return the multipath string for such descriptors.

    This PR allows descriptors to actually be multipath where the multipath specifiers are represented inside of the paths of BIP32PubkeyProviders. This allows for the multipath string to be produced.

    In order to achieve this, a lot of derivation path parsing is refactored. KeyPath is promoted to being its own class (which subclasses std::vector), while the individual derivation indexes become a KeyPathElement object so that the multipath elements can be represented. Furthermore, hardened derivation characters are now being stored within KeyPathElements so each element knows what the original hardened character was. This also cleans up a little bit of the descriptor implementation as we no longer have to carry around bool apostrophe in a bunch of places.

    Lastly, Parse now returns a single Descriptor object, rather than a vector of them. If the descriptor is a multipath descriptor, the expansion can be retrieved using GetMultipathExpansion(). The wallet uses this and still must not store multipath descriptors.

  2. DrahtBot added the label Descriptors on Oct 5, 2026
  3. DrahtBot commented at 10:15 PM on October 5, 2026: contributor

    <!--e57a25ab6845829454e8d69fc972939a-->

    The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

    <!--006a51241073e994b41acfe9ec718e94-->

    External sites

    <!--021abf342d371248e50ceaed478a90ca-->

    Reviews

    See the guideline and AI policy for information on the review process.

    Type Reviewers
    Concept ACK w0xlt, Sjors, pythcoiner

    If your review is incorrectly listed, please copy-paste <code>&lt;!--meta-tag:bot-skip--&gt;</code> into the comment that the bot should ignore.

    <!--174a7506f384e20aa4161008e828411d-->

    Conflicts

    Reviewers, this pull request conflicts with the following ones:

    • #36897 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36897.svg"></sub> (wallet, migration: Contain all legacy wallet and migration related things in its own subdirectory, namespace, and classes by achow101)
    • #36885 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36885.svg"></sub> (wallet, rpc: Add analyzedescriptor for multisig setups by pablomartin4btc)
    • #36820 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36820.svg"></sub> (refactor: remove more dead code by fanquake)
    • #36808 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36808.svg"></sub> (iwyu: Fix warnings in src/test/fuzz and treat them as errors by hebasto)
    • #36648 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36648.svg"></sub> (descriptor, rpc, wallet: do not echo key material in error messages by fametrano)
    • #36122 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36122.svg"></sub> (BIP460: CISA for Taproot key path spends by fjahr)
    • #36070 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36070.svg"></sub> (wallet: Add deriveHDKey interface by PraneethGunas)
    • #36005 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36005.svg"></sub> (rpc, descriptor: warn when multipath expansion clones single-path key expressions by pythcoiner)
    • #35918 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/35918.svg"></sub> (descriptor: Expose key expression parsing by pseudoramdom)
    • #35377 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/35377.svg"></sub> (wallet: Allow importing of descriptors without private keys when the wallet has the private keys by achow101)
    • #34909 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/34909.svg"></sub> (wallet, refactor: modularise wallet by extracting out legacy wallet migration by rkrux)
    • #34193 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/34193.svg"></sub> (wallet: make migration more robust against failures by furszy)

    If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

    <!--5faf32d7da4f0f540f40219e4f7537a3-->

    LLM Linter (✨ experimental)

    Possible typos and grammar issues:

    • src/util/bip32.h: for a give multipath position → for a given multipath position [wording error]

    Possible places where named args for integral literals may be used (e.g. func(x, /*named_arg=*/0) in C++, and func(x, named_arg=0) in Python):

    • src/qt/test/wallettests.cpp: WalletDescriptor(std::move(desc), 0, 0, 1, 1)
    • src/script/descriptor.cpp: std::make_unique<ConstPubkeyProvider>(key_exp_index, pubkey, false)
    • src/script/descriptor.cpp: std::make_unique<ConstPubkeyProvider>(key_exp_index, pubkey, true)
    • src/script/descriptor.cpp: std::make_unique<ConstPubkeyProvider>(0, pubkey, false)
    • src/script/descriptor.cpp: std::make_unique<ConstPubkeyProvider>(0, pubkey, true)
    • src/wallet/scriptpubkeyman.cpp: Parse(desc_str, provider, error, false)
    • src/wallet/scriptpubkeyman.cpp: WalletDescriptor(std::move(desc), creation_time, 0, 0, 0)
    • src/wallet/scriptpubkeyman.cpp: Parse(desc_str, provider, error, false)
    • src/wallet/scriptpubkeyman.cpp: WalletDescriptor(std::move(desc), 0, 0, chain_counter, 0)
    • src/wallet/test/psbt_wallet_tests.cpp: WalletDescriptor(std::move(desc), 0, 0, 10, 0)
    • src/wallet/test/wallet_tests.cpp: WalletDescriptor{std::move(desc), 0, 0, 0, 0}
    • src/wallet/wallet.cpp: Parse(desc_str, keys, desc_error, false)
    • src/wallet/walletutil.cpp: WalletDescriptor(std::move(desc), creation_time, 0, 0, 0)
    • src/wallet/walletutil.h: Parse(descriptor_str, keys, error, true)

    <sup>2026-11-07 02:43:22</sup>

  4. achow101 force-pushed on Oct 5, 2026
  5. DrahtBot added the label CI failed on Oct 5, 2026
  6. DrahtBot commented at 10:35 PM on October 5, 2026: contributor

    <!--85328a0da195eb286784d51f73fa0af9-->

    🚧 At least one of the CI tasks failed. <sub>Task ASan + LSan + UBSan + integer: https://github.com/bitcoin/bitcoin/actions/runs/37381217840/job/112003412636</sub> <sub>LLM reason (✨ experimental): The build failed because walletload_tests.cpp assigns Parse()’s std::unique_ptr<Descriptor> result to a vector of unique pointers.</sub>

    <details><summary>Hints</summary>

    Try to run the tests locally, according to the documentation. However, a CI failure may still happen due to a number of reasons, for example:

    • Possibly due to a silent merge conflict (the changes in this pull request being incompatible with the current code in the target branch). If so, make sure to rebase on the latest commit of the target branch.

    • A sanitizer issue, which can only be found by compiling with the sanitizer and running the affected test.

    • An intermittent issue.

    Leave a comment here, if you need help tracking down a confusing failure.

    </details>

  7. DrahtBot added the label Needs rebase on Oct 7, 2026
  8. achow101 force-pushed on Oct 7, 2026
  9. DrahtBot removed the label Needs rebase on Oct 7, 2026
  10. achow101 force-pushed on Oct 7, 2026
  11. w0xlt commented at 6:05 PM on October 8, 2026: contributor

    Concept ACK

  12. Sjors referenced this in commit 95ad9d4ad5 on Oct 20, 2026
  13. Sjors referenced this in commit de20c94b37 on Oct 20, 2026
  14. Sjors referenced this in commit de8d85c4c6 on Oct 20, 2026
  15. Sjors referenced this in commit 59eb880b15 on Oct 20, 2026
  16. Sjors referenced this in commit 5c8268050b on Oct 20, 2026
  17. Sjors referenced this in commit 334e6a6388 on Oct 20, 2026
  18. Sjors referenced this in commit 80a95f5644 on Oct 20, 2026
  19. Sjors referenced this in commit 53a458ed82 on Oct 21, 2026
  20. Sjors referenced this in commit 2635883c46 on Oct 21, 2026
  21. Sjors referenced this in commit 4ac892de26 on Oct 21, 2026
  22. Sjors commented at 4:17 AM on October 21, 2026: member

    Concept ACK.

    Sorry for the pingback noise. I've now adjusted my merge skill to stop pinging the main repo from fork PRs.

  23. DrahtBot added the label Needs rebase on Oct 21, 2026
  24. fametrano commented at 4:50 AM on October 23, 2026: none

    On this head, migratewallet turns every step of an imported key's origin path into a hardened step.

    SingleKeyPathElement::Unserialize assigns a bool to std::optional<char> m_hardened. The optional is then always engaged, so ChildNumber() sets the hardened bit on every step read from disk. It came with "util: Store hardened character in KeyPathElement". A v29.4 legacy watch-only wallet holding wpkh([d34db33f/84h/0h/0h/0/5]<pubkey>) migrates to 84h/0h/0h/0/5 on v31.1 and to 84h/0h/0h/0h/5h on this head. With the change suggested inline, the migrated descriptors match v31.1.

    The multipath round trip agrees with btclib-wallet, a BIP389 implementation I maintain. On 25 descriptors (wpkh, sh-wsh multisig, tr trees, miniscript, musig, steps of three and five elements), getdescriptorinfo keeps each input's paths and markers, and its multipath_expansion and deriveaddresses match btclib-wallet. Both refuse the same 8 malformed ones. As the description says, markers are now kept as written; v31.1 printed one per key. A descriptor mixing h and ' thus prints, with its checksum, differently from v31.1, which may deserve a release note. I can share the scripts and outputs.

  25. in src/util/bip32.h:58 in 74915efa6e
      57 | +    inline void Unserialize(Stream& s)
      58 | +    {
      59 | +        uint32_t num;
      60 | +        s >> num;
      61 | +        m_index = num & ~BIP32_HARDENED_FLAG;
      62 | +        m_hardened = bool(num & BIP32_HARDENED_FLAG);
    


    fametrano commented at 4:50 AM on October 23, 2026:

    Engaged only for a hardened step, so an unhardened step read from disk stays unhardened:

            m_hardened = (num & BIP32_HARDENED_FLAG) ? std::optional<char>{'h'} : std::nullopt;
    

    achow101 commented at 12:33 AM on November 5, 2026:

    Fixed

  26. achow101 force-pushed on Nov 5, 2026
  27. DrahtBot removed the label Needs rebase on Nov 5, 2026
  28. DrahtBot removed the label CI failed on Nov 5, 2026
  29. DrahtBot added the label CI failed on Nov 5, 2026
  30. DrahtBot added the label Needs rebase on Nov 5, 2026
  31. achow101 force-pushed on Nov 6, 2026
  32. DrahtBot removed the label Needs rebase on Nov 6, 2026
  33. DrahtBot added the label Needs rebase on Nov 6, 2026
  34. util: Make KeyPathElement class with private members 2f727b3552
  35. util: Change all key path operations to operate with std::vector<KeyPathElement> 7fac1374f3
  36. util: Make KeyPath a subclass of std::vector and not only a typedef
    We will want to have member functions on KeyPath later, so make it a
    class now.
    e3a747ca94
  37. util: Store hardened character in KeyPathElement b2205211a6
  38. achow101 force-pushed on Nov 7, 2026
  39. DrahtBot removed the label Needs rebase on Nov 7, 2026
  40. util: Make KeyPathElement handle multipaths
    Moves all of the multipath parsing into ParseHDKeypath, and let
    KeyPathElement be a multipath element.
    13d56f38eb
  41. descriptor: Get the multipath expansion from a multipath descriptor 68fda857b8
  42. descriptor: Produce multipath descriptor in ParseScript
    Internally, descriptor parsing will produce multipath descriptor objects
    rather than std::vector<DescriptorImpl>. This single multipath
    descriptor becomes std::vector<Descriptor> within Parse. Future commits
    will return the single multipath descriptor object for all descriptor parsing.
    6c4ff42e1c
  43. descriptor: Return multipath descriptor from Parse
    Instead of a std::vector<std::unique_ptr<Descriptor>>, Parse can return
    a single std::unique_ptr<Descriptor> that contains the multipath
    information if the descriptor was multipath. Callers that
    require the multipath expansion use GetMultipathExpansion() to get the
    expanded descriptors.
    0f2dc37a8b
  44. achow101 force-pushed on Nov 7, 2026
  45. DrahtBot removed the label CI failed on Nov 7, 2026
  46. in src/util/bip32.h:79 in 0f2dc37a8b
      79 | +    KeyPathElement(std::vector<SingleKeyPathElement> indexes) : m_indexes(indexes) {}
      80 | +
      81 | +    const std::vector<SingleKeyPathElement>& Indexes() const { return m_indexes; }
      82 | +    size_t MultipathLen() const { return m_indexes.size(); }
      83 | +    bool IsMultipath() const { return m_indexes.size() > 1; }
      84 | +    const SingleKeyPathElement& Index(size_t multipath_pos) const { return m_indexes.at(multipath_pos); }
    


    pythcoiner commented at 8:19 AM on November 10, 2026:

    2 remarks here:

    • shouldn't multipath_pos default to 0 in order to mirror ChildNumber() and IsHardened()?
    • it seems weird that Index return a SinglePathElement because its < & == operate on the child number rather the underlying m_index
  47. in src/test/bip32_tests.cpp:474 in 7fac1374f3
     482 | -                BOOST_CHECK_EQUAL(keypath_num2[i], keypath_num[i]);
     483 | +            const std::optional<KeyPath> res2{ParseHDKeypath(keypath_str2_adjusted)};
     484 | +            BOOST_CHECK(res2.has_value());
     485 | +            BOOST_REQUIRE_EQUAL(res2->size(), res1->size());
     486 | +            for (size_t i{0}; i < res2->size(); ++i) {
     487 | +                BOOST_CHECK_EQUAL(res2->at(i).ChildNumber(), res2->at(i).ChildNumber());
    


    Sjors commented at 9:05 AM on November 10, 2026:

    In 7fac1374f38ddb69ee815e9151158153939e2783 util: Change all key path operations to operate with std::vector<KeyPathElement>

    diff --git a/src/test/bip32_tests.cpp b/src/test/bip32_tests.cpp
    index 3bfc2a6535..7958456e3e 100644
    --- a/src/test/bip32_tests.cpp
    +++ b/src/test/bip32_tests.cpp
    @@ -473,5 +473,5 @@ BOOST_AUTO_TEST_CASE(parse_hd_keypath)
                 BOOST_REQUIRE_EQUAL(res2->size(), res1->size());
                 for (size_t i{0}; i < res2->size(); ++i) {
    -                BOOST_CHECK_EQUAL(res2->at(i).ChildNumber(), res2->at(i).ChildNumber());
    +                BOOST_CHECK_EQUAL(res2->at(i).ChildNumber(), res1->at(i).ChildNumber());
                 }
                 const std::string keypath_str3{FormatHDKeypath(*res2, /*hardened_char=*/'\'')};
    

    It still passes after this fix.

  48. in src/script/sign.cpp:327 in 7fac1374f3
     323 | @@ -323,11 +324,11 @@ static bool SignMuSig2(const BaseSignatureCreator& creator, SignatureData& sigda
     324 |              }
     325 |              // Get the BIP32 derivation tweaks
     326 |              CExtPubKey extpub = CreateMuSig2SyntheticXpub(agg_pub);
     327 | -            for (const uint32_t i : agg_info.path) {
     328 | -                if (i >> 31) return false; // Hardened derivation is not possible from a public key
     329 | +            for (const auto& i : agg_info.path) {
    


    Sjors commented at 9:18 AM on November 10, 2026:

    In 7fac1374f38ddb69ee815e9151158153939e2783 util: Change all key path operations to operate with std::vector<KeyPathElement> nit: KeyPathElement& is more clear.

  49. in src/test/descriptor_tests.cpp:174 in 7fac1374f3
     170 | @@ -171,13 +171,22 @@ std::set<std::pair<CPubKey, KeyOriginInfo>> GetKeyOriginData(const FlatSigningPr
     171 |  
     172 |  void DoCheck(std::string prv, std::string pub, const std::string& norm_pub, int flags,
     173 |               const std::vector<std::vector<std::string>>& scripts, const std::optional<OutputType>& type, std::optional<uint256> op_compat_desc_hash = std::nullopt,
     174 | -             const std::set<std::vector<uint32_t>>& paths = ONLY_EMPTY, bool replace_apostrophe_with_h_in_prv=false,
     175 | +             const std::set<std::vector<uint32_t>>& paths_in = ONLY_EMPTY, bool replace_apostrophe_with_h_in_prv=false,
    


    Sjors commented at 9:27 AM on November 10, 2026:

    In 7fac1374f38ddb69ee815e9151158153939e2783 util: Change all key path operations to operate with std::vector<KeyPathElement>: if you make ONLY_EMPTY a const std::set<KeyPath>, the compiler makes life easier (thanks Claude...):

    diff --git a/src/test/descriptor_tests.cpp b/src/test/descriptor_tests.cpp
    index db090e2eb0..2866cdccc3 100644
    --- a/src/test/descriptor_tests.cpp
    +++ b/src/test/descriptor_tests.cpp
    @@ -122,5 +122,5 @@ static size_t CountUniqueXpubs(const std::string& desc)
     }
    
    -const std::set<std::vector<uint32_t>> ONLY_EMPTY{{}};
    +const std::set<KeyPath> ONLY_EMPTY{{}};
    
     std::set<CPubKey> GetKeyData(const FlatSigningProvider& provider, int flags) {
    @@ -172,17 +172,9 @@ std::set<std::pair<CPubKey, KeyOriginInfo>> GetKeyOriginData(const FlatSigningPr
     void DoCheck(std::string prv, std::string pub, const std::string& norm_pub, int flags,
                  const std::vector<std::vector<std::string>>& scripts, const std::optional<OutputType>& type, std::optional<uint256> op_compat_desc_hash = std::nullopt,
    -             const std::set<std::vector<uint32_t>>& paths_in = ONLY_EMPTY, bool replace_apostrophe_with_h_in_prv=false,
    +             const std::set<KeyPath>& paths = ONLY_EMPTY, bool replace_apostrophe_with_h_in_prv=false,
                  bool replace_apostrophe_with_h_in_pub=false, uint32_t spender_nlocktime=0, uint32_t spender_nsequence=CTxIn::SEQUENCE_FINAL,
                  std::map<std::vector<uint8_t>, std::vector<uint8_t>> preimages={},
                  std::optional<std::string> expected_prv = std::nullopt, std::optional<std::string> expected_pub = std::nullopt, int desc_index = 0)
     {
    -    std::set<KeyPath> paths;
    -    for (const std::vector<uint32_t>& path : paths_in) {
    -        KeyPath keypath;
    -        for (uint32_t elem : path) {
    -            keypath.emplace_back(elem);
    -        }
    -        paths.emplace(std::move(keypath));
    -    }
         std::set<KeyPath> left_paths = paths;
    
    @@ -516,5 +508,5 @@ void DoCheck(std::string prv, std::string pub, const std::string& norm_pub, int
     void Check(const std::string& prv, const std::string& pub, const std::string& norm_pub, int flags,
                const std::vector<std::vector<std::string>>& scripts, const std::optional<OutputType>& type, std::optional<uint256> op_compat_desc_hash = std::nullopt,
    -           const std::set<std::vector<uint32_t>>& paths = ONLY_EMPTY, uint32_t spender_nlocktime=0,
    +           const std::set<KeyPath>& paths = ONLY_EMPTY, uint32_t spender_nlocktime=0,
                uint32_t spender_nsequence=CTxIn::SEQUENCE_FINAL, std::map<std::vector<uint8_t>, std::vector<uint8_t>> preimages={},
                std::optional<std::string> expected_prv = std::nullopt, std::optional<std::string> expected_pub = std::nullopt, int desc_index = 0)
    @@ -543,5 +535,5 @@ void CheckMultipath(const std::string& prv,
             const std::vector<std::vector<std::vector<std::string>>>& scripts,
             const std::optional<OutputType>& type,
    -        const std::vector<std::set<std::vector<uint32_t>>>& paths)
    +        const std::vector<std::set<KeyPath>>& paths)
     {
         assert(expanded_prvs.size() == expanded_pubs.size());
    
  50. in src/util/bip32.h:28 in 7fac1374f3
      23 | @@ -23,26 +24,50 @@ class KeyPathElement {
      24 |      bool m_hardened;
      25 |  
      26 |  public:
      27 | +    KeyPathElement() = default;
      28 |      KeyPathElement(uint32_t index, bool hardened) : m_index(index), m_hardened(hardened) {}
    


    Sjors commented at 9:55 AM on November 10, 2026:

    In 7fac1374f38ddb69ee815e9151158153939e2783 util: Change all key path operations to operate with std::vector<KeyPathElement>: let's Assume or Assert that index < BIP32_HARDENED_FLAG.

  51. in src/util/bip32.h:33 in 0f2dc37a8b
      32 | +    std::optional<char> m_hardened;
      33 | +
      34 | +public:
      35 | +    SingleKeyPathElement() = default;
      36 | +    SingleKeyPathElement(uint32_t index, std::optional<char> hardened) : m_index(index), m_hardened(hardened) {}
      37 | +    SingleKeyPathElement(uint32_t num) : m_index(num & ~BIP32_HARDENED_FLAG), m_hardened(bool(num & BIP32_HARDENED_FLAG) ? std::optional{'h'} : std::nullopt) {}
    


    pythcoiner commented at 10:18 AM on November 10, 2026:

    I think it worth have constant for the default hardened marker:

    (see https://github.com/bitcoin/bitcoin/commit/159c260fb6f98007dfc2f766e3247f1e165b52b9)

  52. in src/util/bip32.h:39 in 0f2dc37a8b
      39 |      /** Derivation index with the hardened flag applied */
      40 | -    uint32_t ChildNumber() const { return index | (is_hardened ? BIP32_HARDENED_FLAG : BIP32_UNHARDENED_FLAG); }
      41 | +    uint32_t ChildNumber() const { return m_index | (m_hardened.has_value() ? BIP32_HARDENED_FLAG : BIP32_UNHARDENED_FLAG); }
      42 | +
      43 | +    bool IsHardened() const { return m_hardened.has_value(); }
      44 | +    void SetHardenedChar(char hardened)
    


    pythcoiner commented at 10:31 AM on November 10, 2026:

    SetHardenedChar can read like if it set the hardened property, while it only overwrite the hardened char. Since all callers uses the hardcoded default char maybe the method can be renamed to smth like NormalizedHardenedMarker, it would also prevent a future caller to pass an arbitrary char?

  53. in src/util/bip32.h:24 in b2205211a6
      20 | @@ -21,19 +21,23 @@ class KeyPathElement {
      21 |  private:
      22 |      /** Derivation index, without the hardened flag */
      23 |      uint32_t m_index;
      24 | -    bool m_hardened;
      25 | +    std::optional<char> m_hardened;
    


    Sjors commented at 10:38 AM on November 10, 2026:

    In b2205211a62f0b65b71941e2e12fe8fb3919de89 util: Store hardened character in KeyPathElement: worth elaborating in the commit message why you're doing this. E.g.:

    It's important for descriptor ID stability that we track whether hardened derivation used an h or apostrophe. Unify this tracking in KeyPathElement.

    Note that this breaks downgrading a mixed usage miniscript:

    diff --git a/test/functional/wallet_backwards_compatibility.py b/test/functional/wallet_backwards_compatibility.py
    index 0d94d9107a..1e6ecc418c 100755
    --- a/test/functional/wallet_backwards_compatibility.py
    +++ b/test/functional/wallet_backwards_compatibility.py
    @@ -340,4 +340,14 @@ class BackwardsCompatibilityTest(BitcoinTestFramework):
                 assert_equal(res[0]["success"], True)
    
    +        # A key expression that mixes both hardened markers. Older releases recompute
    +        # the descriptor ID when loading, and print such an expression with a single
    +        # marker.
    +        node_master.createwallet(wallet_name="miniscript_mixed")
    +        wallet = node_master.get_wallet_rpc("miniscript_mixed")
    +        miniscript_mixed = miniscript_desc.replace("[beefdead/4h/5h]", "[beefdead/4'/5h]")
    +        assert miniscript_mixed != miniscript_desc
    +        res = wallet.importdescriptors([{"desc": descsum_create(miniscript_mixed), "timestamp":"now"}])
    +        assert_equal(res[0]["success"], True)
    +
             # Unload wallets and copy to older nodes:
             node_master_wallets_dir = node_master.wallets_path
    @@ -346,4 +356,5 @@ class BackwardsCompatibilityTest(BitcoinTestFramework):
             node_master.unloadwallet("w3")
             node_master.unloadwallet("miniscript")
    +        node_master.unloadwallet("miniscript_mixed")
    
             for node in previous_nodes:
    @@ -359,9 +370,10 @@ class BackwardsCompatibilityTest(BitcoinTestFramework):
             for node in descriptors_nodes:
                 self.log.info(f"- {node.version}")
    -            for wallet_name in ["w1", "w2", "w3", "miniscript"]:
    +            for wallet_name in ["w1", "w2", "w3", "miniscript", "miniscript_mixed"]:
    +                is_miniscript = wallet_name in ("miniscript", "miniscript_mixed")
                     if self.major_version_less_than(node, 22) and wallet_name == "w1":
                         # Descriptor wallets created after 0.21 have taproot descriptors which 0.21 does not support, tested below
                         continue
    -                if self.major_version_less_than(node, 24) and wallet_name == "miniscript":
    +                if self.major_version_less_than(node, 24) and is_miniscript:
                         # Miniscript was introduced in 24.0
                         continue
    @@ -372,5 +384,5 @@ class BackwardsCompatibilityTest(BitcoinTestFramework):
                         # result in wallets that cannot be loaded into 31.0 and 31.1.
                         # These wallets will emit a "Wallet corrupted" error.
    -                    if wallet_name == "miniscript" and n.version in (310000, 310100):
    +                    if is_miniscript and n.version in (310000, 310100):
                             assert_raises_rpc_error(-4, "Wallet corrupted", n.loadwallet, wallet_name)
                             continue
    @@ -400,5 +412,5 @@ class BackwardsCompatibilityTest(BitcoinTestFramework):
                             assert_equal(info['private_keys_enabled'], True)
                             assert_equal(info['keypoolsize'], 0)
    -                    elif wallet_name == "miniscript":
    +                    elif is_miniscript:
                             descs = wallet.listdescriptors()["descriptors"]
                             assert any(desc["desc"].startswith("wsh(or_b(pk") for desc in descs), "Miniscript descriptor missing"
    

    We could refuse to import those, but BIP380 permits it.

    Or restore the previous behavior:

    diff --git a/src/script/descriptor.cpp b/src/script/descriptor.cpp
    index 1cc3cf7c2d..6e98a22189 100644
    --- a/src/script/descriptor.cpp
    +++ b/src/script/descriptor.cpp
    @@ -1887,4 +1887,5 @@ enum class ParseScriptContext {
      * [@param](/bitcoin-bitcoin/contributor/param/)[in] split BIP32 path string, using either ' or h for hardened derivation
      * [@param](/bitcoin-bitcoin/contributor/param/)[out] out Vector of parsed key paths
    + * [@param](/bitcoin-bitcoin/contributor/param/)[out] hardened only updated if hardened derivation is found
      * [@param](/bitcoin-bitcoin/contributor/param/)[out] error parsing error message
      * [@param](/bitcoin-bitcoin/contributor/param/)[in] allow_multipath Allows the parsed path to use the multipath specifier
    @@ -1892,5 +1893,5 @@ enum class ParseScriptContext {
      * [@returns](/bitcoin-bitcoin/contributor/returns/) false if parsing failed
      **/
    -[[nodiscard]] bool ParseKeyPath(const std::vector<std::span<const char>>& split, std::vector<KeyPath>& out, std::string& error, bool allow_multipath, bool& has_hardened)
    +[[nodiscard]] bool ParseKeyPath(const std::vector<std::span<const char>>& split, std::vector<KeyPath>& out, char& hardened, std::string& error, bool allow_multipath, bool& has_hardened)
     {
         auto parse_elem = [&](std::span<const char> elem) -> std::optional<KeyPathElement> {
    @@ -1902,4 +1903,5 @@ enum class ParseScriptContext {
             if (parsed->IsHardened()) {
                 has_hardened = true;
    +            hardened = elem.back();
             }
             return *parsed;
    @@ -1970,8 +1972,8 @@ enum class ParseScriptContext {
     }
    
    -[[nodiscard]] bool ParseKeyPath(const std::vector<std::span<const char>>& split, std::vector<KeyPath>& out, std::string& error, bool allow_multipath)
    +[[nodiscard]] bool ParseKeyPath(const std::vector<std::span<const char>>& split, std::vector<KeyPath>& out, char& hardened, std::string& error, bool allow_multipath)
     {
         bool dummy;
    -    return ParseKeyPath(split, out, error, allow_multipath, /*has_hardened=*/dummy);
    +    return ParseKeyPath(split, out, hardened, error, allow_multipath, /*has_hardened=*/dummy);
     }
    
    @@ -1995,5 +1997,5 @@ static DeriveType ParseDeriveType(std::vector<std::span<const char>>& split, cha
    
     /** Parse a public key that excludes origin information. */
    -std::vector<std::unique_ptr<PubkeyProvider>> ParsePubkeyInner(uint32_t& key_exp_index, const std::span<const char>& sp, ParseScriptContext ctx, FlatSigningProvider& out, std::string& error)
    +std::vector<std::unique_ptr<PubkeyProvider>> ParsePubkeyInner(uint32_t& key_exp_index, const std::span<const char>& sp, ParseScriptContext ctx, FlatSigningProvider& out, char& hardened, std::string& error)
     {
         std::vector<std::unique_ptr<PubkeyProvider>> ret;
    @@ -2059,7 +2061,6 @@ std::vector<std::unique_ptr<PubkeyProvider>> ParsePubkeyInner(uint32_t& key_exp_
         }
         std::vector<KeyPath> paths;
    -    char hardened{'h'};
         DeriveType type = ParseDeriveType(split, hardened);
    -    if (!ParseKeyPath(split, paths, error, /*allow_multipath=*/true)) return {};
    +    if (!ParseKeyPath(split, paths, hardened, error, /*allow_multipath=*/true)) return {};
         if (extkey.key.IsValid()) {
             extpubkey = extkey.Neuter();
    @@ -2067,4 +2068,5 @@ std::vector<std::unique_ptr<PubkeyProvider>> ParsePubkeyInner(uint32_t& key_exp_
         }
         for (auto& path : paths) {
    +        path.SetHardenedChar(hardened);
             ret.emplace_back(std::make_unique<BIP32PubkeyProvider>(key_exp_index, extpubkey, std::move(path), type, hardened));
         }
    @@ -2153,5 +2155,5 @@ std::vector<std::unique_ptr<PubkeyProvider>> ParsePubkey(uint32_t& key_exp_index
                 }
                 bool has_hardened = false;
    -            if (!ParseKeyPath(deriv_split, derivation_multipaths, error, /*allow_multipath=*/true, has_hardened)) {
    +            if (!ParseKeyPath(deriv_split, derivation_multipaths, dummy, error, /*allow_multipath=*/true, has_hardened)) {
                     error = "musig(): " + error;
                     return {};
    @@ -2227,7 +2229,9 @@ std::vector<std::unique_ptr<PubkeyProvider>> ParsePubkey(uint32_t& key_exp_index
             return {};
         }
    -    // This is set if either the origin or path suffix contains a hardened derivation.
    +    // A key expression is always written with a single hardened marker: that of the last
    +    // hardened step parsed. Descriptor IDs of wallets with Miniscript descriptors depend on this.
    +    char hardened{'h'};
         if (origin_split.size() == 1) {
    -        return ParsePubkeyInner(key_exp_index, origin_split[0], ctx, out, error);
    +        return ParsePubkeyInner(key_exp_index, origin_split[0], ctx, out, hardened, error);
         }
         if (origin_split[0].empty() || origin_split[0][0] != '[') {
    @@ -2252,8 +2256,9 @@ std::vector<std::unique_ptr<PubkeyProvider>> ParsePubkey(uint32_t& key_exp_index
         std::copy_n(fpr_bytes.begin(), info.fingerprint.size(), info.fingerprint.begin());
         std::vector<KeyPath> path;
    -    if (!ParseKeyPath(slash_split, path, error, /*allow_multipath=*/false)) return {};
    +    if (!ParseKeyPath(slash_split, path, hardened, error, /*allow_multipath=*/false)) return {};
         info.path = path.at(0);
    -    auto providers = ParsePubkeyInner(key_exp_index, origin_split[1], ctx, out, error);
    +    auto providers = ParsePubkeyInner(key_exp_index, origin_split[1], ctx, out, hardened, error);
         if (providers.empty()) return {};
    +    info.path.SetHardenedChar(hardened);
         ret.reserve(providers.size());
         for (auto& prov : providers) {
    
  54. in src/util/bip32.h:36 in b2205211a6
      36 | +    uint32_t ChildNumber() const { return m_index | (m_hardened.has_value() ? BIP32_HARDENED_FLAG : BIP32_UNHARDENED_FLAG); }
      37 |  
      38 | -    bool IsHardened() const { return m_hardened; }
      39 | +    bool IsHardened() const { return m_hardened.has_value(); }
      40 | +    void SetHardenedChar(char hardened)
      41 | +    {
    


    Sjors commented at 10:54 AM on November 10, 2026:

    In b2205211a62f0b65b71941e2e12fe8fb3919de89 util: Store hardened character in KeyPathElement:

    Assume(hardened == 'h' || hardened == '\'');
    
  55. in src/util/bip32.h:28 in b2205211a6
      26 |  
      27 |  public:
      28 |      KeyPathElement() = default;
      29 | -    KeyPathElement(uint32_t index, bool hardened) : m_index(index), m_hardened(hardened) {}
      30 | -    KeyPathElement(uint32_t num) : m_index(num & ~BIP32_HARDENED_FLAG), m_hardened(num & BIP32_HARDENED_FLAG) {}
      31 | +    KeyPathElement(uint32_t index, std::optional<char> hardened) : m_index(index), m_hardened(hardened) {}
    


    Sjors commented at 10:55 AM on November 10, 2026:

    In b2205211a62f0b65b71941e2e12fe8fb3919de89 util: Store hardened character in KeyPathElement:

    Assume(index < BIP32_HARDENED_FLAG);
    Assume(!hardened || *hardened == 'h' || *hardened == '\'');
    
  56. in src/util/bip32.cpp:92 in b2205211a6
      88 | +        elem.SetHardenedChar(hardened);
      89 | +    }
      90 | +}
      91 | +
      92 | +std::string KeyPathElement::ToString(const std::optional<char>& hardened_char) const
      93 |  {
    


    Sjors commented at 10:57 AM on November 10, 2026:

    In b2205211a62f0b65b71941e2e12fe8fb3919de89 util: Store hardened character in KeyPathElement:

    Assume(!hardened_char || *hardened_char == 'h' || *hardened_char == '\'');
    

    (all three assumes that I suggested for this commit pass the tests)

  57. in src/util/bip32.cpp:24 in b2205211a6
      20 | @@ -21,11 +21,11 @@ util::Expected<KeyPathElement, std::string> ParseKeyPathElement(std::span<const
      21 |          return util::Unexpected{strprintf("Key path value '%s' is not valid", raw)};
      22 |      }
      23 |  
      24 | -    bool is_hardened = false;
      25 | -    const char last = elem.back();
      26 | +    char last = elem.back();
    


    Sjors commented at 10:59 AM on November 10, 2026:

    In b2205211a62f0b65b71941e2e12fe8fb3919de89 util: Store hardened character in KeyPathElement nit: char can stay const

  58. in src/script/descriptor.cpp:579 in b2205211a6
     575 | @@ -573,10 +576,10 @@ class BIP32PubkeyProvider final : public PubkeyProvider
     576 |              out = ToString(StringType::PUBLIC);
     577 |              return false;
     578 |          }
     579 | -        out = EncodeExtKey(key) + FormatHDKeypath(m_path, /*apostrophe=*/m_apostrophe);
     580 | +        out = EncodeExtKey(key) + FormatHDKeypath(m_path, /*hardened_char*/std::nullopt);
    


    Sjors commented at 11:12 AM on November 10, 2026:

    In b2205211a62f0b65b71941e2e12fe8fb3919de89 util: Store hardened character in KeyPathElement nit: lost = in the comment.

  59. in src/util/bip32.h:80 in b2205211a6
      76 | @@ -71,7 +77,7 @@ util::Expected<KeyPathElement, std::string> ParseKeyPathElement(std::span<const
      77 |  std::optional<KeyPath> ParseHDKeypath(const std::string& keypath_str);
      78 |  
      79 |  /** Write HD keypaths as strings */
      80 | -std::string WriteHDKeypath(const KeyPath& keypath, bool apostrophe = false);
      81 | -std::string FormatHDKeypath(const KeyPath& path, bool apostrophe = false);
      82 | +std::string WriteHDKeypath(const KeyPath& keypath, const std::optional<char>& hardened_char = 'h');
    


    Sjors commented at 11:18 AM on November 10, 2026:

    In b2205211a62f0b65b71941e2e12fe8fb3919de89 util: Store hardened character in KeyPathElement: light preference for dropping these defaults. In e.g. scriptpubkeyman.cpp‎ you're setting h anyway.

  60. in src/util/bip32.cpp:26 in 0f2dc37a8b
      25 |          return util::Unexpected{strprintf("Key path value '%s' is not valid", raw)};
      26 |      }
      27 |  
      28 | -    bool is_hardened = false;
      29 | -    const char last = elem.back();
      30 | +    char last = elem.back();
    


    pythcoiner commented at 11:20 AM on November 10, 2026:

    const seems have inadvertly dropped

  61. Sjors commented at 11:26 AM on November 10, 2026: member

    Code review up to b2205211a62f0b65b71941e2e12fe8fb3919de89 util: Store hardened character in KeyPathElement

    • 7fac1374f38ddb69ee815e9151158153939e2783 util: Change all key path operations to operate with std::vector<KeyPathElement>: in the tests not "all" are changed. That seems better for readability, but worth pointing out in the commit message.
  62. in src/script/descriptor.cpp:499 in 0f2dc37a8b
     496 |      }
     497 |  
     498 |  public:
     499 | -    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) {}
     500 | +    BIP32PubkeyProvider(uint32_t exp_index, const CExtPubKey& extkey, KeyPath path, DeriveType derive) : PubkeyProvider(exp_index), m_root_extkey(extkey), m_path(std::move(path)), m_derive(derive) {}
     501 | +    BIP32PubkeyProvider(uint32_t exp_index, const CExtPubKey& extkey, KeyPath path, DeriveType derive, char hardened) : PubkeyProvider(exp_index), m_root_extkey(extkey), m_path(std::move(path)), m_derive(derive), m_hardened(hardened) {}
    


    pythcoiner commented at 12:51 PM on November 10, 2026:

    it seems a single constructor works?

        BIP32PubkeyProvider(uint32_t exp_index, const CExtPubKey& extkey, KeyPath path, DeriveType derive, char hardened = 'h') : PubkeyProvider(exp_index), m_root_extkey(extkey), m_path(std::move(path)), m_derive(derive), m_hardened(hardened) {}
    
  63. in src/util/bip32.h:67 in 0f2dc37a8b
      67 | +    }
      68 | +};
      69 | +
      70 | +class KeyPathElement {
      71 | +private:
      72 | +    std::vector<SingleKeyPathElement> m_indexes;
    


    pythcoiner commented at 1:32 PM on November 10, 2026:

    I'd rename the field as the "index" semantic seems not fit there, SingleKeyPathElement carry not only the index but also the hardened marker

        std::vector<SingleKeyPathElement> m_child_numbers;
    
  64. in src/test/bip32_tests.cpp:475 in 0f2dc37a8b
     483 | -                BOOST_CHECK_EQUAL(keypath_num2[i], keypath_num[i]);
     484 | +            const std::optional<KeyPath> res2{ParseHDKeypath(keypath_str2_adjusted)};
     485 | +            BOOST_CHECK(res2.has_value());
     486 | +            BOOST_REQUIRE_EQUAL(res2->size(), res1->size());
     487 | +            for (size_t i{0}; i < res2->size(); ++i) {
     488 | +                BOOST_CHECK_EQUAL(res2->at(i).ChildNumber(), res2->at(i).ChildNumber());
    


    pythcoiner commented at 1:49 PM on November 10, 2026:

    this test currently cant fail

                    BOOST_CHECK_EQUAL(res2->at(i).ChildNumber(), res1->at(i).ChildNumber());
    
  65. in src/util/bip32.h:94 in 0f2dc37a8b
      94 | +    }
      95 | +
      96 | +    std::string ToString(const std::optional<char>& hardened_char = std::nullopt) const;
      97 | +
      98 | +    bool operator<(const KeyPathElement& other) const { return m_indexes < other.m_indexes; }
      99 | +    bool operator==(const KeyPathElement& other) const { return m_indexes == other.m_indexes; }
    


    pythcoiner commented at 2:12 PM on November 10, 2026:

    maybe here it should be documented that operators apply on the child number but not on the marker char

  66. in src/util/bip32.h:139 in 0f2dc37a8b
     140 | +util::Expected<SingleKeyPathElement, std::string> ParseSingleKeyPathElement(std::span<const char> elem);
     141 |  util::Expected<KeyPathElement, std::string> ParseKeyPathElement(std::span<const char> elem);
     142 |  
     143 |  /** Parse an HD keypaths like "m/7/0'/2000". */
     144 | -[[nodiscard]] bool ParseHDKeypath(const std::string& keypath_str, std::vector<uint32_t>& keypath);
     145 | +std::optional<KeyPath> ParseHDKeypath(const std::string& keypath_str, bool allow_multipath = false);
    


    pythcoiner commented at 2:19 PM on November 10, 2026:

    shouldnt we return an Expected here?

  67. pythcoiner commented at 4:21 PM on November 10, 2026: contributor

    concept ACK

    i've reviewed 2f727b3552 to 13d56f38eb and added few remarks inline

  68. fametrano commented at 2:43 AM on November 11, 2026: none

    The migratewallet fix holds on 0f2dc37a8bb5a5c668ebc8ab8f2d43d3f07c810d, but the PR adds no test for it.

    achow101 fixed SingleKeyPathElement::Unserialize after my inline note on 74915efa. When I migrate a v29.4 legacy watch-only wallet that holds wpkh([d34db33f/84h/0h/0h/0/5]<pubkey>), 0f2dc37a keeps the origin path 84h/0h/0h/0/5, as v31.1 does; 74915efa gave 84h/0h/0h/0h/5h. On 74915efa bip32_tests and descriptor_tests still pass. The test below reads a KeyOriginInfo back from its serialization: it fails on 74915efa (2147483648 != 0) and passes on 0f2dc37a.

    --- a/src/test/bip32_tests.cpp
    +++ b/src/test/bip32_tests.cpp
    @@ -7,6 +7,7 @@
     #include <clientversion.h>
     #include <key.h>
     #include <key_io.h>
    +#include <script/keyorigin.h>
     #include <streams.h>
     #include <test/util/common.h>
     #include <test/util/setup_common.h>
    @@ -480,4 +481,21 @@ BOOST_AUTO_TEST_CASE(parse_hd_keypath)
         }
     }
     
    +BOOST_AUTO_TEST_CASE(key_origin_serialization_roundtrip)
    +{
    +    // A key origin as the wallet stores it: unhardened steps stay unhardened when read back.
    +    const auto path{ParseHDKeypath("m/84h/0h/0h/0/5")};
    +    BOOST_REQUIRE(path);
    +    KeyOriginInfo info{};
    +    info.path = *path;
    +    DataStream ss{};
    +    ss << info;
    +    KeyOriginInfo read;
    +    ss >> read;
    +    BOOST_REQUIRE_EQUAL(read.path.size(), path->size());
    +    for (size_t i{0}; i < read.path.size(); ++i) {
    +        BOOST_CHECK_EQUAL(read.path[i].ChildNumber(), path->at(i).ChildNumber());
    +    }
    +}
    +
     BOOST_AUTO_TEST_SUITE_END()
    

    The script that builds the wallet, the commands and their output are in https://gist.github.com/fametrano/fc7fd1b054657138a96a73befa81da66/5dabccf7307d47f9f2063df62fb7ce93e54ca0ab.


github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-11-20 15:51 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me