Multipath descriptor support (BIP 389)

[schjonhaug]

Description

Key Features:

• New API: Wallet::create_multipath(descriptor) following the same pattern as create() and create_single()
• BIP 389 compliance with exactly 2-path validation (receive and change)
• Robust validation with clear error messages
• Pattern consistency with existing wallet creation methods

Usage Example:

let multipath_desc = "wpkh([9a6a2580/84'/1'/0']tpub.../‹0;1›/*)";
let wallet = Wallet::create_multipath(multipath_desc)
      .network(Network::Testnet)
      .create_wallet_no_persist()?;

// Automatically creates separate receive and change descriptors
let receive_addr = wallet.peek_address(KeychainKind::External, 0);  // Uses path /0/*
let change_addr = wallet.peek_address(KeychainKind::Internal, 0);   // Uses path /1/*

Notes to the reviewers

Design Decisions:

1. Pattern Consistency: Uses make_multipath_descriptor_to_extract() helper following the same pattern as existing make_descriptor_to_extract() function
2. Lazy Evaluation: Descriptor parsing only happens when needed during wallet creation, not during parameter setup - this maintains performance and follows Rust's lazy evaluation patterns
3. Strict Validation: Only allows exactly 2-path multipath descriptors to ensure proper receive/change separation
4. API Consistency: The create_multipath() method returns CreateParams just like create() and create_single(), maintaining the fluent builder pattern

Implementation Notes:

• The function calls make_multipath_descriptor_to_extract() twice (once for receive, once for change) which is intentional and follows the established pattern of lazy evaluation
• Validation occurs in the descriptor extraction closures, providing clear error messages when descriptors are actually processed
• All existing functionality remains unchanged - this is a purely additive feature

Changelog notice

Added:

• Wallet::create_multipath() method for creating wallets from BIP 389 multipath descriptors
• CreateParams::new_multipath() for multipath descriptor parameter creation
• Support for 2-path multipath descriptors with automatic receive/change separation
• Enhanced validation for multipath descriptors with descriptive error messages

Checklists

All Submissions:

• I've signed all my commits
• I followed the contribution guidelines
• I ran just p before pushing

New Features:

• I've added tests for the new feature
• I've added docs for the new feature

Bugfixes:

• This pull request breaks the existing API
• I've added tests to reproduce the issue which are now passing
• I'm linking the issue being fixed by this PR

Closes #11

[coveralls]

Pull Request Test Coverage Report for Build 16654062685

Details

• 80 of 82 (97.56%) changed or added relevant lines in 4 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+0.1%) to 84.874%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
wallet/src/descriptor/error.rs	0	1	0.0%
wallet/src/descriptor/mod.rs	6	7	85.71%

Totals
Change from base Build 16389875164:	0.1%
Covered Lines:	6655
Relevant Lines:	7841

---

💛 - Coveralls

[ValuedMammal]

Thanks for working on this @schjonhaug.

[schjonhaug]

Glad to contribute, @ValuedMammal. Let me know if there’s anything I can improve!

[notmandatory]

Thanks for taking this one on, overall your PR looks great. I especially like the detailed docs and new validation to ensure only two indexes are used.

I have two small suggestions and you should do a rebase and then I think it's ready to merge.

[rustaceanrob]

I like the direction here and think this would be a great edition. In working with common hardware signer export files, these are very common descriptor representations. My one nit is to be careful naming the APIs with the more general multipath convention, as the code and documentation only supports two possible paths. I can see this becoming an issue if Wallet supports N arbitrary keychains in the future, and the functionality of this API changes subtly. My suggestion would be to use something like create_from_two_path_descriptor or similar to distinguish between N possible keychains and two.

[notmandatory]

... My suggestion would be to use something like create_from_two_path_descriptor or similar to distinguish between N possible keychains and two.

@rustaceanrob what do you think about a little shorter name like Wallet::create_two_path(two_path_descriptor)?

[notmandatory]

@schjonhaug do you think you'll have time this week to make the small changes ValuedMammal and Rob suggested above? You also need to do a cargo fmt to pass that CI test. If so then I think we can get this merged for our 2.1 release next week.

Or if you are OK with the changes but won't have time to work on it let me know and I can push a commit to your PR to wrap it up. Thanks!

[notmandatory]

I created a commit you can copy or I can push here if it looks OK. Then all the commits should be squashed to one with a conventional commits style message.

notmandatory@1423e46

I think the name @rustaceanrob suggested is better even though it's long. Then later when we're able to support any n descriptors in a wallet we can use the create_multipath function name.

[schjonhaug]

Thanks for the commit @notmandatory. I included it and renamed some functions and parameters to drive home the point that we are talking about two-path descriptors.

[ValuedMammal]

Approach ACK

[ValuedMammal]

ACK 9e3adf2

[notmandatory]

ACK da0b577

Thanks for getting this one wrapped up for the next release. I know there are downstream projects looking forward to having it.

[thunderbiscuit]

After playing with this today to expose it in the bindings I realized that this constructor cannot be used with private keys. This is a fairly important aspect/limitation of using the method, and I think it should be made more explicit in the API docs. I will open a PR for this tomorrow.

FYI if my investigation is correct, the issue is that miniscript cannot parse an xprv (I saw a comment from Sanket somewhere but now I can't find it anymore!) if the multipath contains hardened derivation paths, and therefore miniscipt cannot ensure the xprv will be parsable into public keys in all cases? Something like that. But our arguments for bdk wallet constructors require the IntoWalletDescriptor trait:

pub trait IntoWalletDescriptor {
    /// Convert to wallet descriptor
    fn into_wallet_descriptor(
        self,
        secp: &SecpCtx,
        network: Network,
    ) -> Result<(ExtendedDescriptor, KeyMap), DescriptorError>;
}

pub type ExtendedDescriptor = Descriptor<DescriptorPublicKey>;

In other words, upon creation, the wallet will always try to parse the descriptor string into its public form, and here since it cannot be done by miniscript we fail to build.

This limitation should also be reflected in the tests; I'll add that to my PR as well.