refactor: replace examples with focused rustdoc examples

[kwsantiago]

Closes #1973

Changes

• Removed /examples folder containing CLI-heavy examples
• Added focused rustdoc examples to key functions:
  • IndexedTxGraph::new() - graph initialization
  • BdkElectrumClient::new() - client creation
  • BdkElectrumClient::sync() - blockchain sync
  • BdkElectrumClient::full_scan() - wallet restoration
  • TxGraph::insert_tx() - transaction insertion
  • TxGraph::balance() - balance calculation
  • TxGraph::filter_chain_unspents() - UTXO retrieval
  • KeychainTxOutIndex::reveal_next_spk() - address generation
  • KeychainTxOutIndex::insert_descriptor() - descriptor setup
  • IndexedTxGraph::apply_block_relevant() - block processing
  • EsploraExt::full_scan() - Esplora wallet scanning
• Updated Cargo.toml workspace members

Rationale

The previous examples contained 300+ lines of CLI boilerplate that obscured the core BDK functionality. The new rustdoc examples are 10-15 lines each and focus purely on API usage, making them much easier for developers to understand and follow.

The maintained bdk-cli tool serves as the comprehensive CLI example.

[oleonardolima]

Thanks for working on this one.
It's failing on CI. Make sure to use the 'just' commands and try building the docs locally if that helps with debugging the failures.

[kwsantiago]

@oleonardolima thank you. CI "should" be fixed now, at least it is locally. Can we try again?

[oleonardolima]

Thanks, there are some unrelated already merged commits, you probably need to do a rebase on top of master. Also, please note that we follow the conventional commits for commit messages, which would also need an update.

[kwsantiago]

@oleonardolima ok should be ready to test CI now. Thanks!

[oleonardolima]

You'll need to perform another rebase to incorporate the CI updates/fixes, and remove the unrelated merge commit.

[kwsantiago]

@oleonardolima should be good now, let me know if there is anything else here.

[oleonardolima]

You should also remove the example exclusion in build and test CI step.

I'm also wondering if the cfgs are strictly required, but haven't tested anything different yet.

[notmandatory]

cACK, but haven't done a close review yet. Thanks for hanging in on this one, but looks like it needs another rebase.

[luisschwab]

@kwsantiago you should run just pre-push to catch and correct any errors before pushing.

[kwsantiago]

@luisschwab got it, thanks!

[kwsantiago]

Code Coverage failure is unrelated to this PR: test_chain_update_wrong_network_error fails with ConnectionRefused on the local esplora server. Same failure on master: https://github.com/bitcoindevkit/bdk/actions/runs/22196832097

[notmandatory]

This will need a rebase also since I merged #2123.

[kwsantiago]

@notmandatory I rebased onto master in f9ec921

[ValuedMammal]

• Can you change ignore to no_run in bdk_electrum_client.rs, that way we know the example compiles.
• You can remove the #[allow(deprecated)] from fetch_latest_blocks. Thanks @kwsantiago

[ValuedMammal]

You may need to enable the crate default features for dev-dependencies in electrum/Cargo.toml in order for the doctests to compile.

[ValuedMammal]

In cont_integration.yml we no longer need to --exclude 'example_*' for the build-test job.

[kwsantiago]

@ValuedMammal your comments have been addressed in 35d6980

[nymius]

I think this is in a very good state, but It's hard to extract from the original issue the requirements to consider this done.

The value of the examples/ was mainly due to the integration of the multiple components bdk implements, and that's hard to replicate by just adding doc examples to the interesting methods.
That's why I think there is no much escape to having to look at bdk-cli for it.

However, there are components missing examples in the docs that will benefit from these changes.

@kwsantiago has already implemented some. The following list is an attempt to extract the provided functionality by the examples/ and identify the missing doc examples:

• Esplora new: Blocking/AsyncClient::from_builder()

Missing example.

• Esplora sync: EsploraAsync/EsploraExt::sync()

Missing example.

• Esplora full scan: EsploraAsync/EsploraExt::full_scan()
• Electrum new: BdkElectrumClient::new()
• Electrum sync: BdkElectrumClient::sync()
• Electrum full scan: BdkElectrumClient::full_scan()
• Electrum parameter: batch_size.
• bitcoind_rpc sync/live: Emitter::next_block() and Emitter::mempool

Missing example.

• TxOut listing: TxGraph::try_canonical_view + filter_outpoints (filter_outpointsalready contains examples)

Missing example.

• Balance TxGraph::balance()
• Index setup: KeychainTxOutIndex::insert_descriptor()
• Address listing: KeychainTxOutIndex::revealed_keychain_spks()
• Address reveal next: KeychainTxOutIndex::reveal_next_spk()
• Address reveal unused: KeychainTxOutIndex::next_unused_spk()

Once we have these in place, the added examples together with the bdk-cli project are going to be a better guide than the old examples/.

I left outside of the above list the functionality that cannot be replicated without recreating end to end examples like before.

• Wallet setup: generate keys, initialize indexes and local chain, set network and database. Trying to replicate this in some way will fall back again to the old examples/ way. It's better to point users to bdk-cli instead.
• PSBT operations: new, sign and extract: PSBT creation is mainly managed through TxBuilder in bdk_wallet, sign is on its way to be removed and extraction is also done by bdk_wallet. For more fine grained control is better to look at bdk_tx.
• Coin selection and transaction building: Same than above, most of this is implemented with TxBuilder in bdk_wallet, and for the new interface is better to work on bdk-tx.

[nymius]

I would like to hear other's opinions, but wouldn't it be better to replace all these uses of raw integers as parameters by the name of the parameter itself, as we are talking of documentation?

[notmandatory]

I agree, having the variable named after the parameter would be more readable than an unexplained value.

[oleonardolima]

I think this is in a very good state, but It's hard to extract from the original issue the requirements to consider this done.

The value of the examples/ was mainly due to the integration of the multiple components bdk implements, and that's hard to replicate by just adding doc examples to the interesting methods. That's why I think there is no much escape to having to look at bdk-cli for it.

[...]

@nymius Thanks for the detailed comment and review! If I may add to it, I would suggest to break this into different PRs if possible, e.g one for bdk_esplora; one for bdk_electrum, and so on.

I left outside of the above list the functionality that cannot be replicated without recreating end to end examples like before.

• Wallet setup: generate keys, initialize indexes and local chain, set network and database. Trying to replicate this in some way will fall back again to the old examples/ way. It's better to point users to bdk-cli instead.
• PSBT operations: new, sign and extract: PSBT creation is mainly managed through TxBuilder in bdk_wallet, sign is on its way to be removed and extraction is also done by bdk_wallet. For more fine grained control is better to look at bdk_tx.
• Coin selection and transaction building: Same than above, most of this is implemented with TxBuilder in bdk_wallet, and for the new interface is better to work on bdk-tx.

Yes, it's fine to left this on the side for now, they're bdk_wallet concerns. And I even feel that some of the examples here and there are some sort of duplicates (needs double-checking).