Add automatic descriptor generator and beginner-focused documentation for examples and server setup

[AmosOO7]

Describe the enhancement

Add a feature to automatically generate valid Bitcoin descriptors (e.g., from a mnemonic or xpub) via a CLI command or helper function. This would assist users, especially beginners in quickly bootstrapping and running BDK examples without needing to manually write descriptors.

Additionally, include beginner-friendly documentation (possibly in the examples/ directory or main docs site) that walks users through:

• Setting up the server environment (Electrum, Esplora, etc.)
• Running specific examples step-by-step
• Generating and using descriptors
• Handling common setup issues or errors

Use case

This enhancement would significantly improve the onboarding experience for developers new to BDK or Bitcoin in general. It lowers the barrier to entry by abstracting away descriptor generation and provides clarity on how to get the local environment up and running. This would benefit:

• New contributors testing example scripts
• Developers evaluating BDK for integration
• Educators or workshop organizers introducing BDK to learners

Question

Would it be better to break this into two separate issues; one for the descriptor generation tool, and one for the documentation improvements?

[sdmg15]

For the descriptor generation tool I think you already have it but it's inside the example_electrum or example_esplora
after compiled you can run cargo run -- --help.
Both of those examples depends on example_cli which seems to have the necessary utilities functions.

For the documentation parts, it's true some of the example crates lack README on how to run, but those that have it have detailed steps I think.

[AmosOO7]

Thanks for the clarification, @sdmg15

You're right, the example crates do provide detailed steps once you start running them. However, there's no clear README to guide new users on how to get started with them. What do you think about me updating the docs and adding README files to help new users settle in more quickly?

[notmandatory]

I think this belongs in the bitcoindevkit/bdk-cli repo, since that project could add a command to create a new descriptor and/or act as a detailed example.

[AmosOO7]

I would love to work on the project, may i know if it can be assigned to me?

[notmandatory]

Have you seen this project: https://github.com/bitcoindevkit/elephant

I think it's a better approach to create private keys from regular words that can then be used in test descriptors. I'm not sure what the API would look like, but it should be feature flagged and have lots of warnings not to use it to create mainnet keys.

Or this could be combined with your idea by adding commands to create different template descriptors from a given key or keys.

[tvpeter]

Have you seen this project: https://github.com/bitcoindevkit/elephant

I think it's a better approach to create private keys from regular words that can then be used in test descriptors. I'm not sure what the API would look like, but it should be feature flagged and have lots of warnings not to use it to create mainnet keys.

While I have not thoroughly reviewed the elephant project, I think it is a good idea to add a command in the key subcommands that will generate descriptors (and output them) for testing purposes (with a WARNING not to use in production). The descriptors example does a similar thing with little additions of parameters from the cli.

[AmosOO7]

@notmandatory and @tvpeter thank you for the insights. I have not thoroughly gone through the https://github.com/bitcoindevkit/elephant project also, I will do that, although I have worked on something for this issue but I am yet to create the Pr, I can fine tune it and create a Pr so it can be reviewed there.

I was also thinking we can modify the generate option for key, cargo run key generate --entropy 12 command so it can also provide a descriptor along side the private key generated.

[tvpeter]

I was also thinking we can modify the generate option for key, cargo run key generate --entropy 12 command so it can also provide a descriptor along side the private key generated.

I considered adding a new command: cargo run key descriptors --network {signet} --key-type {44/49/84/86} instead of modifying the existing generate command.

[AmosOO7]

@tvpeter that sounds better. I will work on the changes of what I have already.

[tvpeter]

@tvpeter that sounds better. I will work on the changes of what I have already.

Please wait a moment for confirmation from @notmandatory before proceeding.

[notmandatory]

I'd prefer a new top level subcommand for descriptor operations, and in that subcommand we can try to incorporate the elephant "weak" key idea. Does this make sense:

1. Create two single key descriptors (internal/external) for different script types:
   cargo run -- --network {signet/testnet/etc.} descriptor --type {44/49/84/86} {one valid tpub/tprv or xpub/xprv}

2. Create one multipath single key descriptor for different script types:
   cargo run -- --network {signet/testnet/etc.} descriptor --type {44/49/84/86} --multipath {one valid tpub/tprv or xpub/xprv}

3. Create two single key descriptors (internal/external) for different script types with "weak" string based key:
   cargo run -- --network {signet/testnet/etc.} descriptor --type {44/49/84/86} --weak {any simple string, ie. "Peter"}

4. Have reasonable defaults for "type" use 84 and "multipath" use false (for now), and weak should be false. Then to create internal/external WPKH descriptors with weak testnet key would look like:
   cargo run -- descriptor --weak Peter

5. If the user give an "xprv" or "xpub" with a test network give an error.

6. If the user uses the --weak option with network "bitcoin" give an error.

[tvpeter]

Yes, I completely agree. Thanks for providing the details for implementation.

[notmandatory]

One other thing to note is that these "weak" keys generated from simple strings are more useful for testing or demoing wallets using multikey descriptors. But first we should add a bdk_wallet template for BIP383 descriptors.

Once that's done then can add a new "type" 383 that requires -k # and -n # followed by a list of exactly n keys.

The usage with weak keys would look something like:
cargo run -- descriptor --type 383 -k 2 -n 3 --weak Peter Steve Amos

[notmandatory]

I just thought of one problem with all of this, if the --weak option only create tprv keys then it will be hard to demo a "multi signer" or "watch wallet" vs "spending wallet" scenarios. I'll have to think about that, maybe better to just add the --weak option to the existing key command, but that will make it almost as hard to use as real keys. But for now the "descriptor" command above without the --weak option I think would be a good improvement.