Adding descriptor generator #180

AmosOO7 · 2025-05-02T01:51:13Z

Pull Request: Add `descriptor` Subcommand (Generate & Info)

Description

This PR introduces a new descriptor subcommand to the BDK CLI that enables users to generate and inspect Bitcoin wallet descriptors for internal and external paths, supporting common BIP standards (44, 49, 84, 86). It includes support for both single-path and multipath descriptors from extended keys (xprv/xpub or tprv/tpub).

This resolves issue #175

Note: The --weak option for string-based key generation is intentionally excluded in this PR, pending further instruction.

Features Implemented

Adds new descriptor subcommand with:
- generate – generate new descriptors
- info – inspect and display descriptor metadata
Supports BIP44, BIP49, BIP84, and BIP86 script types
Generates internal and external descriptors
Supports --multipath for wildcard derivation paths
Rejects mismatched key-network pairs (e.g., xprv on testnet)
Reasonable defaults:
- --type defaults to 84 and a short t
- --network default testnet
- --multipath defaults to false and a short m

Usage Examples

1. Generate Descriptors from an Extended Private Key

cargo run -- --network testnet descriptor generate --type 84 <XPRV>

2. Generate Descriptors from a Mnemonic (no key provided)

cargo run -- --network testnet descriptor generate --type 86

3. Generate Multipath Descriptors from an Extended Public Key or Private Key

cargo run -- --network testnet descriptor generate --type 44 --multipath <XPUB/XPRIV>

4. Show Info about an Existing Descriptor

cargo run -- --network testnet descriptor info "wpkh([fingerprint/84h/1h/0h]xpub/0/*)"

I've signed all my commits
I followed the contribution guidelines
I ran cargo fmt and cargo clippy before committing

New Features:

I've added tests for the new feature
I've added docs for the new feature
I've updated CHANGELOG.md

src/commands.rs

Cargo.toml

src/commands.rs

src/descriptor_handler.rs

tvpeter

Good work Amos.

Most of the fns in utils should be in the handlers file, while most of those in handlers should be placed in the utils.

Cargo.lock

src/handlers.rs

tvpeter

Thank you for your work on this, @AmosOO7.

If possible, please revert the imports you removed, as this will help in tracking your imports. Also, kindly remove any unnecessary comments and squash your commits into logical groupings. I have also left comments on other specific areas for your review.

Thank you!

src/handlers.rs

src/commands.rs

src/handlers.rs

src/utils.rs

tvpeter

Thank you for continuing to work on this.

I have left a couple of comments.

src/handlers.rs

src/utils.rs

src/commands.rs

src/handlers.rs

coveralls · 2025-06-24T20:00:27Z

Pull Request Test Coverage Report for Build 17490529141

Details

0 of 328 (0.0%) changed or added relevant lines in 3 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage decreased (-0.5%) to 1.68%

Changes Missing Coverage	Changed/Added Lines	%
src/commands.rs	1	0.0%
src/handlers.rs	72	0.0%
src/utils.rs	255	0.0%

Totals
Change from base Build 17324807959:	-0.5%
Covered Lines:	25
Relevant Lines:	1488

💛 - Coveralls

tvpeter

Thanks @AmosOO7 for continuing to work on this.

The checks for path and how a user can use it is a little bit confusing. I think we might need to split it into subcommands, similar to how key has generate, derive and restore. If you have any suggestions for the best subcategories, please feel free to share them in the conversation before continuing with the implementation. Otherwise, I will propose the subcategories this coming week to make it clearer. I've also left some additional comments for you.

Additionally, it would be a good idea to include documentation comments for each command option and parameter to help users better understand their functionalities.

Thank you.

src/commands.rs

src/handlers.rs

AmosOO7 · 2025-07-16T22:45:45Z

After having a discussion with @tvpeter and following his suggestions.

Breaking the descriptor command into subcommands improves clarity, usability, and future extensibility of the BDK CLI.

Suggested Subcommands for `descriptor`

Subcommand	Description
from-key	Generate descriptors from a provided Xprv or Xpub
from-mnemonic	Generate descriptors from a newly generated or provided BIP39 mnemonic
multipath	Generate multipath (wildcard derivation) descriptors from a key
info (optional/future)	Inspect a descriptor and show parsed structure (e.g., key origin, type, script)

Detailed Breakdown

1. `descriptor from-key`

Input: --type, <XPRV | XPUB>
Optional: --path m/84h/1h/0h (for custom derivation base)
Output: external/internal descriptor strings
Optionally support both single and multipath modes via --multipath

2. `descriptor from-mnemonic`

Input: --type,
Optional: --mnemonic <WORDS> (if not, generate randomly)
Output: same as from-key, plus return mnemonic used

3. `descriptor multipath`

Input: --type, <XPRV | XPUB>
Output: wildcard descriptors (e.g., /0/* and /1/*)

4. (Optional) `descriptor info`

Input: descriptor string
Output: parsed structure, origin, derivation, checksum, script type, etc.

Example CLI Usage


From key
bdk-cli descriptor from-key --type 84 <XPRV | <XPUB>;
From mnemonic
bdk-cli descriptor from-mnemonic --type 86 (optional)<WORDS>
From key with multipath
bdk-cli descriptor multipath --type 44 <XPUB | <XPUB>;
Descriptor info (optional)
bdk-cli descriptor info "wpkh([abcd1234/84'/1'/0']xpub.../0/*)"

What do you think about the suggestions @tvpeter and @notmandatory ?

tvpeter · 2025-07-17T04:26:24Z

I think the following is more descriptive:

From key

bdk-cli descriptor from-key --type 84 <XPRV | ;

bdk-cli --network [network] descriptor generate --type [type] --key <xprv | xpub>

From mnemonic

bdk-cli descriptor from-mnemonic --type 86 (optional)

bdk-cli --network [network] descriptor generate --type [type] --mnemonic [mnemonic]

From key with multipath

bdk-cli descriptor multipath --type 44 <XPUB | ;

bdk-cli --network [network] descriptor generate --type [type] --multipath <xprv|xpub>

Descriptor info (optional)

bdk-cli descriptor info "wpkh([abcd1234/84'/1'/0']xpub.../0/*)"

bdk-cli --network [network] descriptor --info <descriptor>

note:

<param> - required
[param] - optional as defaults are provided

Also, wait for confirmation from Notmandatory.

notmandatory · 2025-07-17T14:10:23Z

@tvpeter I agree that having two descriptor sub-commands generate and info makes sense. Also good for generate sub-command to have optional --type with default being 84. One other suggestion is that I think you can remove the --key and --mnemonic options and just require a key in either xprv OR mnemonic format, we should be able to parse either format into a key. But if that turns out to be too hard it's OK to be explicit and use --key and --mnemonic mutually exclusive but required options.

Having the descriptor info <descriptor> is nice to have but not sure it's that useful since you can see this info by just looking at the descriptor. But could still be useful as a training tool to show people what each part is for new people.

tvpeter · 2025-07-17T14:45:33Z

One other suggestion is that I think you can remove the --key and --mnemonic options and just require a key in either xprv OR mnemonic format, we should be able to parse either format into a key. But if that turns out to be too hard it's OK to be explicit and use --key and --mnemonic mutually exclusive but required options.

Having the descriptor info <descriptor> is nice to have but not sure it's that useful since you can see this info by just looking at the descriptor. But could still be useful as a training tool to show people what each part is for new people.

@AmosOO7, you should be able to update according to this. Thank you

tvpeter

Hi @AmosOO7,

Thanks for continuing to push this PR. I have left comments, when you address them, I will continue with testing.
Thank you

src/handlers.rs

src/error.rs

src/commands.rs

src/handlers.rs

tvpeter · 2025-08-19T17:21:58Z

src/error.rs

+    #[error("Invalid arguments: {0}")]
+    InvalidArguments(String),


This variant seems to be duplicating the Generic Variant. See output below:

tvpeter · 2025-09-04T11:14:08Z

@AmosOO7, can you please make time to update this PR? I was hoping it could make it into the next release. It would be great if you could push it forward.
Thank you.

tvpeter

Thank you for your efforts on this PR @AmosOO7

I have left comments but don't worry, I will push changes so that it is easier for us to close the PR.
Thank you.

tvpeter · 2025-09-22T12:36:59Z

src/utils.rs

+    let descriptor_type = match script_type {
+        44 => Bip44,
+        49 => Bip49,
+        84 => Bip84,
+        86 => Bip86,
+        _ => return Err(Error::UnsupportedScriptType(script_type)),
+    };


These were already validated in handle_descriptor_subcommand fn in handlers.rs

tvpeter · 2025-09-22T12:56:46Z

src/utils.rs

+
+            let desc_secret = DescriptorSecretKey::XPrv(desc_xprv.clone());
+            let (desc_key, keymap, _) = match descriptor_type {
+                DescriptorType::Bip84 | DescriptorType::Bip49 | DescriptorType::Bip44 => {


BIP44 is legacy and not Segwitv0

tvpeter · 2025-09-22T13:08:49Z

src/handlers.rs

+    let descriptor_type = match script_type {
+        44 => DescriptorType::Bip44,
+        49 => DescriptorType::Bip49,
+        84 => DescriptorType::Bip84,
+        86 => DescriptorType::Bip86,
+        _ => return Err(Error::UnsupportedScriptType(script_type)),
+    };


Redundant validation as this was already handled by the handle_descriptor_subcommand fn

tvpeter · 2025-09-22T13:12:11Z

src/handlers.rs

+pub fn generate_standard_descriptor(
+    network: &Network,
+    script_type: u8,
+    key: &str,
+) -> Result<Value, Error> {


There is no need for this fn as generate_descriptor_from_key_by_type fn can be called directly in handle_descriptor_subcommand passing the network, key, descriptor_type (descriptor_type having already been validated)

tvpeter · 2025-09-22T17:55:55Z

src/utils.rs

+        DescriptorType::Bip49 => format!(
+            "{}([{}{}]{}{}))",
+            external_fmt, origin, derivation_base, xprv_str, "/0"
+        ),
+        _ => format!(
+            "{}([{}{}]{}{})",
+            external_fmt, origin, derivation_base, xprv_str, "/0"
+        ),


These descriptors will not have wildcard.

tvpeter · 2025-09-23T03:34:30Z

src/utils.rs

+pub fn generate_descriptor_from_key_by_type(
+    network: &Network,
+    key: &str,
+    descriptor_type: DescriptorType,
+) -> Result<serde_json::Value, Error> {
+    let derivation_path = match descriptor_type {
+        DescriptorType::Bip44 => "m/44h/1h/0h",
+        DescriptorType::Bip49 => "m/49h/1h/0h",
+        DescriptorType::Bip84 => "m/84h/1h/0h",
+        DescriptorType::Bip86 => "m/86h/1h/0h",
+    };
+
+    generate_bip_descriptor_from_key(network, key, derivation_path, descriptor_type)
+}


this fn is redundant

This allow users to generate wallet descriptors from either extended private keys (xprv), or fresh BIP39 mnemonics. It supports standard script types (BIP44, BIP49, BIP84, BIP86) and outputs both public and private descriptors for external and internal branches. The design improves developer and user experience by enabling easier wallet creation and script descriptor introspection. Closes bitcoindevkit#175

- Ensure you can generate different type of descriptor with mnemonic - Changed the Json output format - Added path subcommand for generating descriptors from keys - Set multipath to accept different types for descriptors - Set multipath default value to false and gave it a short of m - Set type default to 84 and gave it a short to t

- Created Subcommnds for the descriptor command; generate and info - Created function to get descriptors from mnemonics - Ensured consistent fingerprint when generating descriptors from both mnemonic and key - Removed the previously inserted path variable

and commands, and also deleted redundant errors that were created. - Updated the comment on the descriptor command, also added comments to the inputs for the subcommands. - Added possiblevalues for the descriptor types in the subcommand - Made the descriptor type format consistent - Fixed duplicated on invalidArguments call

- Updated the comment on the descriptor command, a> - Added possiblevalues for the descriptor types in> - Made the descriptor type format consistent - Fixed duplicated on invalidArguments call

tvpeter reviewed May 6, 2025

View reviewed changes

src/commands.rs Outdated Show resolved Hide resolved

AmosOO7 marked this pull request as ready for review May 7, 2025 14:17

AmosOO7 force-pushed the adding_descriptor_generator branch from 09b4f4a to ebf6be3 Compare May 7, 2025 16:23

tvpeter requested changes May 12, 2025

View reviewed changes

AmosOO7 requested a review from tvpeter May 19, 2025 16:21

tvpeter requested changes May 21, 2025

View reviewed changes

Cargo.lock Outdated Show resolved Hide resolved

src/handlers.rs Outdated Show resolved Hide resolved

AmosOO7 requested a review from tvpeter May 22, 2025 12:31

notmandatory added this to BDK-CLI May 28, 2025

notmandatory moved this to In Progress in BDK-CLI May 28, 2025

notmandatory added the enhancement New feature or request label May 28, 2025

notmandatory assigned AmosOO7 May 28, 2025

notmandatory added this to the CLI 1.1.0 milestone May 28, 2025

tvpeter requested changes Jun 4, 2025

View reviewed changes

AmosOO7 force-pushed the adding_descriptor_generator branch 7 times, most recently from 6bff257 to 31f256a Compare June 12, 2025 11:45

tvpeter requested changes Jun 12, 2025

View reviewed changes

AmosOO7 force-pushed the adding_descriptor_generator branch from 15495c4 to 6c8e714 Compare June 21, 2025 16:55

AmosOO7 requested a review from tvpeter June 22, 2025 08:33

tvpeter requested changes Jul 5, 2025

View reviewed changes

src/commands.rs Outdated Show resolved Hide resolved

src/commands.rs Outdated Show resolved Hide resolved

src/handlers.rs Outdated Show resolved Hide resolved

src/handlers.rs Outdated Show resolved Hide resolved

AmosOO7 requested a review from tvpeter July 27, 2025 18:44

tvpeter requested changes Aug 19, 2025

View reviewed changes

AmosOO7 requested a review from tvpeter September 5, 2025 10:49

tvpeter requested changes Sep 23, 2025

View reviewed changes

AmosOO7 and others added 8 commits September 24, 2025 17:39

fix imports

00c0a4e

Arranged imports

2cf9397

- Updated error calls on functions in handlers and>

dd58621

- Updated the comment on the descriptor command, a> - Added possiblevalues for the descriptor types in> - Made the descriptor type format consistent - Fixed duplicated on invalidArguments call

fix descriptors generation

3ba1dc0

tvpeter force-pushed the adding_descriptor_generator branch from 37ce428 to 3ba1dc0 Compare September 24, 2025 17:44

Adding descriptor generator #180

Are you sure you want to change the base?

Adding descriptor generator #180

Uh oh!

Conversation

AmosOO7 commented May 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request: Add descriptor Subcommand (Generate & Info)

Description

Features Implemented

Usage Examples

1. Generate Descriptors from an Extended Private Key

2. Generate Descriptors from a Mnemonic (no key provided)

3. Generate Multipath Descriptors from an Extended Public Key or Private Key

4. Show Info about an Existing Descriptor

New Features:

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tvpeter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

tvpeter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tvpeter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coveralls commented Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 17490529141

Details

💛 - Coveralls

Uh oh!

tvpeter left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AmosOO7 commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Suggested Subcommands for descriptor

Detailed Breakdown

1. descriptor from-key

2. descriptor from-mnemonic

3. descriptor multipath

4. (Optional) descriptor info

Example CLI Usage

From key

From mnemonic

From key with multipath

Descriptor info (optional)

Uh oh!

tvpeter commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

From key

From mnemonic

AmosOO7 commented May 2, 2025 •

edited

Loading

Pull Request: Add `descriptor` Subcommand (Generate & Info)

coveralls commented Jun 24, 2025 •

edited

Loading

tvpeter left a comment •

edited

Loading

AmosOO7 commented Jul 16, 2025 •

edited

Loading

Suggested Subcommands for `descriptor`

1. `descriptor from-key`

2. `descriptor from-mnemonic`

3. `descriptor multipath`

4. (Optional) `descriptor info`

tvpeter commented Jul 17, 2025 •

edited

Loading

notmandatory commented Jul 17, 2025 •

edited

Loading