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

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.

<!--e57a25ab6845829454e8d69fc972939a-->

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

<!--006a51241073e994b41acfe9ec718e94-->

External sites

• Code coverage & benchmarks: https://corecheck.dev/bitcoin/bitcoin/pulls/36442
• Ralph review <img src=https://review.fish.foo/assets/bitcoin/bitcoin/36442.png alt="Ralph review status"> https://git.fish.foo/bitcoin/bitcoin/pulls/36442#author-ralph

<!--021abf342d371248e50ceaed478a90ca-->

Reviews

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

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:

• #36443 _{<img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36443.svg">} (descriptor: Reconstruct a multipath descriptor from its expansion by achow101)
• #36122 _{<img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36122.svg">} (BIP460: CISA for Taproot key path spends by fjahr)
• #36070 _{<img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36070.svg">} (wallet: Add deriveHDKey interface by PraneethGunas)
• #35377 _{<img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/35377.svg">} (wallet: Allow importing of descriptors without private keys when the wallet has the private keys by achow101)
• #35170 _{<img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/35170.svg">} (test: Better test coverage for ParseHDKeypath() by optout21)
• #34909 _{<img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/34909.svg">} (wallet, refactor: modularise wallet by extracting out legacy wallet migration by rkrux)

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: give → given [misspelling]

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/rpc/mining.cpp: Parse(descriptor, key_provider, error, false)
• src/rpc/output_script.cpp: Parse(desc_str, key_provider, error, true)
• 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: WalletDescriptor(std::move(desc), creation_time, 0, 0, 0)
• src/wallet/scriptpubkeyman.cpp: WalletDescriptor(std::move(desc), 0, 0, chain_counter, 0)
• src/wallet/test/wallet_tests.cpp: WalletDescriptor{std::move(desc), 0, 0, 0, 0}
• src/wallet/wallet.cpp: WalletDescriptor(std::move(desc), creation_time, 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/test/util.cpp: Parse(desc_str, keys, error, false)

^{2026-10-07 21:48:25}

<!--85328a0da195eb286784d51f73fa0af9-->

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

<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>

Concept ACK