Adding descriptor generator #180

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

Pull Request: Add `descriptor` Subcommand

Description

This PR introduces a new descriptor subcommand to the BDK CLI that enable users to generate and inspect Bitcoin wallet descriptors for internal and external paths, supporting common types (pkh, sh, wpkh, wsh, tr). It includes support for both single-path descriptors from extended keys (xprv/xpub or tprv/tpub).

This resolves issue #175

Features Implemented

Adds new descriptor subcommand with:
- generate – generate new descriptors
- Supports BIP44, BIP49, BIP84, and BIP86 script types
- Generates internal and external descriptors
- Reasonable defaults:
  - --type defaults to wsh and a short t
  - --network default testnet

Usage Examples

1. Generate Descriptors from an Extended Private Key

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

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

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

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 19111115390

Details

0 of 224 (0.0%) changed or added relevant lines in 2 files are covered.
1 unchanged line in 1 file lost coverage.
Overall coverage decreased (-2.3%) to 12.147%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/handlers.rs	0	22	0.0%
src/utils.rs	0	202	0.0%

Files with Coverage Reduction	New Missed Lines	%
src/handlers.rs	1	15.53%

Totals
Change from base Build 19028754066:	-2.3%
Covered Lines:	172
Relevant Lines:	1416

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

src/error.rs

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.

src/utils.rs

src/handlers.rs

src/utils.rs

notmandatory · 2025-09-27T01:16:15Z

Unfortunately this PR needs a lot of cleanup, I've briefly discussed with @tvpeter and he'll help rework it when he has time. Problems I initially ran into:

shouldn't use bip #s which don't represent descriptor types, they are derivation paths which are related but different, descriptor types are: https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md#features. Descriptor types we should focus on are P2PKH, P2WPKH, and P2TR (key spend).
shouldn't use value_parser = PossibleValuesParser should do similar to Compile.script_type or create an enum of descriptor types we support
when I tested the multipath flag it only works for public keys, but should work if an auto generated privkey, manual priv key, or manual public key is given, or could leave this out of this PR and do in a follow-up PR.
minor but still confusing, the command is bdk-cli descriptor generate <flags> <key> but no other sub-commands only generate. should be like the top level "compile" command

- Created Subcommnds for the descriptor command; generate - Created function to get descriptors from mnemonics

- add generating multipath descriptors - add pretty formatting for descriptors

- remove multipath descriptor generation - fix descriptor type

tvpeter · 2025-11-03T21:46:05Z

minor but still confusing, the command is bdk-cli descriptor generate <flags> <key> but no other sub-commands only generate. should be like the top level "compile" command

@notmandatory for this 4th item, should I yank off the generate part of the command so that we will just have descriptor [options] [key]?

- remove generate subcommand - add descriptor to the repl

notmandatory

tACK 7d3720e

I tested:

create each descriptor type
create from mnemonic, xpub, xprv
output with --pretty

Looks good, and should be helpful for new folks learning about descriptors.

tvpeter

ACK 7d3720e

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

tvpeter force-pushed the adding_descriptor_generator branch 3 times, most recently from 483a7f8 to 1452eaa Compare September 26, 2025 15:23

tvpeter requested a review from notmandatory September 26, 2025 15:28

AmosOO7 and others added 4 commits November 3, 2025 11:43

feat: add descriptor generation

6c9c3a1

- Created Subcommnds for the descriptor command; generate - Created function to get descriptors from mnemonics

fix descriptors generation

1f77842

feat(descriptors): add multipath descs and pretty

550e816

- add generating multipath descriptors - add pretty formatting for descriptors

feat(descriptors): fix descriptor generation

c8f23ba

- remove multipath descriptor generation - fix descriptor type

tvpeter force-pushed the adding_descriptor_generator branch from 1452eaa to c8f23ba Compare November 3, 2025 21:34

tvpeter force-pushed the adding_descriptor_generator branch from 0f535b7 to f6f77f8 Compare November 4, 2025 18:00

feat(desc):update descriptors gen to use templates

32a2c88

tvpeter force-pushed the adding_descriptor_generator branch from f6f77f8 to 32a2c88 Compare November 4, 2025 18:09

feat(desc): remove generate subcommand

7d3720e

- remove generate subcommand - add descriptor to the repl

notmandatory approved these changes Nov 10, 2025

View reviewed changes

tvpeter approved these changes Nov 11, 2025

View reviewed changes

tvpeter merged commit 7df419a into bitcoindevkit:master Nov 11, 2025
5 checks passed

github-project-automation bot moved this from In Progress to Done in BDK-CLI Nov 11, 2025

Adding descriptor generator #180

Adding descriptor generator #180

Uh oh!

Conversation

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

Uh oh!

Pull Request: Add descriptor Subcommand

Description

Features Implemented

Usage Examples

1. Generate Descriptors from an Extended Private Key

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

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 19111115390

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

From key with multipath

Descriptor info (optional)

Uh oh!

AmosOO7 commented May 2, 2025 •

edited by tvpeter

Loading

Pull Request: Add `descriptor` Subcommand

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

notmandatory commented Sep 27, 2025 •

edited

Loading