descriptor: Reconstruct a multipath descriptor from its expansion #36443

pull achow101 wants to merge 12 commits into bitcoin:master from achow101:multipath-reconstruction changing 39 files +1200 −672
  1. achow101 commented at 10:16 PM on October 5, 2026: member

    #36442 allows multipath descriptors to be represented in a single Descriptor object. GetMultipathExpansion returns the multiple descriptors represented by a multipath descriptor. This expansion is reversible - given the expansion in the order of the multipath elements, it is possible to determine what the original multipath descriptor was. This PR adds ReconstructMultipath to produce a new Descriptor representing the multipath descriptor that produced the expansion.

    Depends on #36442

  2. DrahtBot added the label Descriptors on Oct 5, 2026
  3. DrahtBot commented at 10:16 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

    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 [misspelling]
    • src/test/descriptor_tests.cpp: Failed reconstrcted to private string → Failed to reconstruct private string [misspelling and unclear phrasing]
    • src/test/descriptor_tests.cpp: Failed reconstructed to private string → Failed to reconstruct private string [broken phrasing]

    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 w_desc(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/test/fuzz/scriptpubkeyman.cpp: Parse(desc_str.value(), keys, error, false)
    • src/wallet/scriptpubkeyman.cpp: WalletDescriptor w_desc(std::move(desc), creation_time, 0, 0, 0)
    • src/wallet/scriptpubkeyman.cpp: Parse(desc_str, provider, error, false)
    • src/wallet/scriptpubkeyman.cpp: Parse(desc_str, parsed_keys, parse_error, false)
    • src/wallet/scriptpubkeyman.cpp: WalletDescriptor w_desc(std::move(desc), 0, 0, chain_counter, 0)
    • src/wallet/test/psbt_wallet_tests.cpp: WalletDescriptor w_desc(std::move(desc), 0, 0, 10, 0)
    • src/wallet/test/util.cpp: Parse(desc_str, keys, error, false)
    • src/wallet/test/wallet_tests.cpp: WalletDescriptor w_desc{std::move(desc), 0, 0, 0, 0}
    • src/wallet/wallet.cpp: Parse(desc_str, keys, desc_error, false)
    • src/wallet/walletutil.cpp: Parse(desc_str, keys, error, false)

    <sup>2026-11-07 03:08:11</sup>

  4. achow101 marked this as a draft on Oct 5, 2026
  5. achow101 force-pushed on Oct 5, 2026
  6. DrahtBot added the label CI failed on Oct 5, 2026
  7. DrahtBot commented at 10:36 PM on October 5, 2026: contributor

    <!--85328a0da195eb286784d51f73fa0af9-->

    🚧 At least one of the CI tasks failed. <sub>Task macOS-cross to arm64: https://github.com/bitcoin/bitcoin/actions/runs/37381386585/job/112003972868</sub> <sub>LLM reason (✨ experimental): CI failed to compile walletload_tests.cpp: Parse() returns a std::unique_ptr<Descriptor>, but the code assigns it to a vector of those 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>

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

    Concept ACK

  12. Sjors referenced this in commit de20c94b37 on Oct 20, 2026
  13. Sjors referenced this in commit de8d85c4c6 on Oct 20, 2026
  14. Sjors referenced this in commit 59eb880b15 on Oct 20, 2026
  15. Sjors referenced this in commit 334e6a6388 on Oct 20, 2026
  16. Sjors referenced this in commit 80a95f5644 on Oct 20, 2026
  17. Sjors referenced this in commit 2635883c46 on Oct 21, 2026
  18. Sjors referenced this in commit 4ac892de26 on Oct 21, 2026
  19. DrahtBot added the label Needs rebase on Oct 21, 2026
  20. fametrano commented at 6:18 AM on October 23, 2026: none

    ReconstructMultipath accepts relatives that repeat a path value, and then returns a descriptor that is not their multipath form.

    I tested it with a small harness against btclib-wallet, a BIP389 implementation I maintain. Its expansions of 24 multipath descriptors each came back as the original. Thirteen mismatched sets (different keys, function, threshold, timelock, key order, tree shape, origin, wildcard or range, two changed steps in one key, musig steps at both levels) return null, as they should.

    Repeated values are not caught. wpkh(X/0/*), wpkh(X/1/*), wpkh(X/0/*) gives wpkh(X/<0;1;0>/*), which Parse refuses as a duplicate. wpkh(X/0/*) twice and then wpkh(X/1/*) gives wpkh(X/<0;1>/*): two elements for three inputs. Two identical inputs give the single-path descriptor back. In BIP32PubkeyProvider::ReconstructMultipath, each relative is compared with p after AddMultipathIndex has already extended it. So a repeat is skipped while p still holds one index, and appended once it holds more. Nothing checks the indexes already in p, or that the step ends with one index per input. The inline suggestions add both checks, with a test for the repeated cases, musig included. I can share the harness and its outputs.

  21. in src/script/descriptor.cpp:699 in 62e70eb6f0 outdated
     695 | +                if (p != rp) {
     696 | +                    if (multipath_pos.has_value() && *multipath_pos != i) {
     697 | +                        return false;
     698 | +                    }
     699 | +                    multipath_pos = i;
     700 | +                    p.AddMultipathIndex(rp.Index(0));
    


    fametrano commented at 6:18 AM on October 23, 2026:

    A relative whose index is already in the step is a repeat, so reject it.

                        if (std::ranges::find(p.Indexes(), rp.Index(0)) != p.Indexes().end()) return false;
                        p.AddMultipathIndex(rp.Index(0));
    
  22. in src/script/descriptor.cpp:959 in 62e70eb6f0 outdated
     954 | +                if (p != rp) {
     955 | +                    if (multipath_pos.has_value() && *multipath_pos != i) {
     956 | +                        return false;
     957 | +                    }
     958 | +                    multipath_pos = i;
     959 | +                    p.AddMultipathIndex(rp.Index(0));
    


    fametrano commented at 6:18 AM on October 23, 2026:

    Same check for the musig path.

                        if (std::ranges::find(p.Indexes(), rp.Index(0)) != p.Indexes().end()) return false;
                        p.AddMultipathIndex(rp.Index(0));
    
  23. in src/script/descriptor.cpp:1389 in 62e70eb6f0 outdated
    1384 | +                    todo.back().second.push_back(rel->m_subdescriptor_args.at(i).get());
    1385 | +                }
    1386 | +            }
    1387 | +        }
    1388 | +
    1389 | +        return out;
    


    fametrano commented at 6:18 AM on October 23, 2026:

    Fail unless the step ends with one index per input. This also rejects identical inputs.

            // Each relative must add one multipath index
            if (!relatives.empty() && multipath_len != relatives.size() + 1) return nullptr;
    
            return out;
    
  24. in src/test/descriptor_tests.cpp:1157 in 62e70eb6f0 outdated
    1152 | +        "tr(musig(xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/1,xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y)/1)",
    1153 | +    });
    1154 | +    CheckFailedMultipathReconstruction({
    1155 | +        "tr(musig(xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/0/*,xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y/1))",
    1156 | +        "tr(musig(xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/9/*h,xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y/1))",
    1157 | +    });
    


    fametrano commented at 6:18 AM on October 23, 2026:

    Add the repeated-value cases, with and without musig.

        });
        CheckFailedMultipathReconstruction({
            "wpkh(xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y/0)",
            "wpkh(xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y/1)",
            "wpkh(xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y/0)",
        });
        CheckFailedMultipathReconstruction({
            "wpkh(xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y/0)",
            "wpkh(xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y/0)",
            "wpkh(xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y/1)",
        });
        CheckFailedMultipathReconstruction({
            "wpkh(xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y/0)",
            "wpkh(xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y/0)",
        });
        CheckFailedMultipathReconstruction({
            "tr(musig(xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/0,xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y)/1)",
            "tr(musig(xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/0,xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y)/2)",
            "tr(musig(xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/0,xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y)/1)",
        });
        CheckFailedMultipathReconstruction({
            "tr(musig(xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/0,xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y)/1)",
            "tr(musig(xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/0,xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y)/1)",
            "tr(musig(xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/0,xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y)/2)",
        });
    
  25. achow101 force-pushed on Nov 5, 2026
  26. DrahtBot removed the label Needs rebase on Nov 5, 2026
  27. DrahtBot added the label Needs rebase on Nov 5, 2026
  28. util: Make KeyPathElement class with private members 2f727b3552
  29. util: Change all key path operations to operate with std::vector<KeyPathElement> 7fac1374f3
  30. 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
  31. util: Store hardened character in KeyPathElement b2205211a6
  32. util: Make KeyPathElement handle multipaths
    Moves all of the multipath parsing into ParseHDKeypath, and let
    KeyPathElement be a multipath element.
    13d56f38eb
  33. descriptor: Get the multipath expansion from a multipath descriptor 68fda857b8
  34. 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
  35. 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
  36. descriptor: Implement multipath reconstruction 91ac9aaa5f
  37. test: Add multipath reconstruction round trip checks a7910c75d5
  38. fuzz: Check multipath descriptor reconstruction d8005a19d2
  39. test: Invalid multipath reconstruction tests 09d019a4c8
  40. achow101 force-pushed on Nov 7, 2026
  41. DrahtBot removed the label Needs rebase on Nov 7, 2026

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 16:51 UTC

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