refactor: replace examples with focused rustdoc examples

Remove standalone examples in favor of focused, contextual rustdoc
examples that are easier to maintain and provide better documentation.
This makes the codebase more maintainable while improving the developer
experience with examples that are tested alongside the code they
document.

Author: kwsantiago

.github/workflows/cont_integration.yml

@@ -64,11 +64,11 @@ jobs:
           MATRIX_RUST_VERSION: ${{ matrix.rust.version }}
         run: |
           if [ $MATRIX_RUST_VERSION = '1.63.0' ]; then
-            cargo build --workspace --exclude 'example_*' --exclude 'bdk_electrum' ${{ matrix.features }}
-            cargo test --workspace --exclude 'example_*' --exclude 'bdk_electrum' ${{ matrix.features }}
+            cargo build --workspace --exclude 'bdk_electrum' ${{ matrix.features }}
+            cargo test --workspace --exclude 'bdk_electrum' ${{ matrix.features }}
           else
-            cargo build --workspace --exclude 'example_*' ${{ matrix.features }}
-            cargo test --workspace --exclude 'example_*' ${{ matrix.features }}
+            cargo build --workspace ${{ matrix.features }}
+            cargo test --workspace ${{ matrix.features }}
           fi
 
   check-no-std:
@@ -168,30 +168,3 @@ jobs:
           name: Clippy Results
           args: --all-features --all-targets -- -D warnings
 
-  build-examples:
-    needs: prepare
-    name: Build & Test Examples
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        example-dir:
-          - example_cli
-          - example_bitcoind_rpc_polling
-          - example_electrum
-          - example_esplora
-    steps:
-      - name: checkout
-        uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-      - name: Install Rust toolchain
-        uses: actions-rs/toolchain@v1
-        with:
-          toolchain: ${{ needs.prepare.outputs.rust_version }}
-          override: true
-          profile: minimal
-      - name: Rust Cache
-        uses: Swatinem/[email protected]
-      - name: Build
-        working-directory: examples/${{ matrix.example-dir }}
-        run: cargo build

Cargo.toml

@@ -8,10 +8,6 @@ members = [
     "crates/esplora",
     "crates/bitcoind_rpc",
     "crates/testenv",
-    "examples/example_cli",
-    "examples/example_electrum",
-    "examples/example_esplora",
-    "examples/example_bitcoind_rpc_polling",
 ]
 
 [workspace.package]

crates/chain/src/indexed_tx_graph.rs

@@ -87,6 +87,15 @@ where
     ///
     /// The underlying `TxGraph` is initialized with `TxGraph::default()`, and the provided
     /// `index`er is used as‐is (since there are no existing transactions to process).
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use bdk_chain::{keychain_txout::KeychainTxOutIndex, BlockId, IndexedTxGraph};
+    ///
+    /// let index = KeychainTxOutIndex::<&str>::new(10, true);
+    /// let graph = IndexedTxGraph::<BlockId, _>::new(index);
+    /// ```
     pub fn new(index: I) -> Self {
         Self {
             index,
@@ -367,6 +376,18 @@ where
     /// Relevancy is determined by the internal [`Indexer::is_tx_relevant`] implementation of `I`.
     /// A transaction that conflicts with a relevant transaction is also considered relevant.
     /// Irrelevant transactions in `block` will be ignored.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use bdk_chain::{IndexedTxGraph, keychain_txout::KeychainTxOutIndex, BlockId};
+    /// use bitcoin::Block;
+    ///
+    /// let mut graph = IndexedTxGraph::<BlockId, _>::new(KeychainTxOutIndex::<&str>::new(10, true));
+    /// # let block = Block { header: bitcoin::block::Header::from(bitcoin::constants::genesis_block(bitcoin::Network::Bitcoin).header), txdata: vec![] };
+    ///
+    /// let changeset = graph.apply_block_relevant(&block, 100);
+    /// ```
     pub fn apply_block_relevant(
         &mut self,
         block: &Block,

crates/chain/src/indexer/keychain_txout.rs

@@ -453,6 +453,22 @@ impl<K: Clone + Ord + Debug> KeychainTxOutIndex<K> {
     /// (one keychain just becomes the defacto owner of that spk arbitrarily) but this may have
     /// subtle implications up the application stack like one UTXO being missing from one keychain
     /// because it has been assigned to another which produces the same script pubkey.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use bdk_chain::keychain_txout::KeychainTxOutIndex;
+    /// use bdk_chain::miniscript::{Descriptor, DescriptorPublicKey};
+    /// # use std::str::FromStr;
+    ///
+    /// let mut index = KeychainTxOutIndex::<&str>::new(10, true);
+    /// let desc = Descriptor::<DescriptorPublicKey>::from_str(
+    ///     "wpkh([d34db33f/84h/0h/0h]xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/0/*)"
+    /// )?;
+    ///
+    /// index.insert_descriptor("external", desc)?;
+    /// # Ok::<_, Box<dyn std::error::Error>>(())
+    /// ```
     pub fn insert_descriptor(
         &mut self,
         keychain: K,
@@ -834,6 +850,22 @@ impl<K: Clone + Ord + Debug> KeychainTxOutIndex<K> {
     ///  1. The descriptor has no wildcard and already has one script revealed.
     ///  2. The descriptor has already revealed scripts up to the numeric bound.
     ///  3. There is no descriptor associated with the given keychain.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use bdk_chain::keychain_txout::KeychainTxOutIndex;
+    /// use bdk_chain::miniscript::{Descriptor, DescriptorPublicKey};
+    /// # use std::str::FromStr;
+    ///
+    /// let mut index = KeychainTxOutIndex::<&str>::new(10, true);
+    /// let desc = Descriptor::<DescriptorPublicKey>::from_str(
+    ///     "wpkh([d34db33f/84h/0h/0h]xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/0/*)"
+    /// ).unwrap();
+    /// index.insert_descriptor("external", desc).unwrap();
+    /// let (spk, changeset) = index.reveal_next_spk("external").unwrap();
+    /// assert_eq!(spk.0, 0);
+    /// ```
     pub fn reveal_next_spk(&mut self, keychain: K) -> Option<(Indexed<ScriptBuf>, ChangeSet)> {
         let mut changeset = ChangeSet::default();
         let indexed_spk = self._reveal_next_spk(&mut changeset, keychain)?;

crates/chain/src/tx_graph.rs

@@ -655,6 +655,24 @@ impl<A: Anchor> TxGraph<A> {
     /// * A smaller witness has precedence over a larger witness.
     /// * If the witness sizes are the same, we prioritize the two witnesses with lexicographical
     ///   order.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use bdk_chain::{tx_graph::TxGraph, BlockId};
+    /// use bitcoin::Transaction;
+    ///
+    /// let mut graph = TxGraph::<BlockId>::default();
+    /// let tx = Transaction {
+    ///     version: bitcoin::transaction::Version::ONE,
+    ///     lock_time: bitcoin::locktime::absolute::LockTime::ZERO,
+    ///     input: vec![],
+    ///     output: vec![],
+    /// };
+    ///
+    /// let changeset = graph.insert_tx(tx.clone());
+    /// assert_eq!(changeset.txs.len(), 1);
+    /// ```
     pub fn insert_tx<T: Into<Arc<Transaction>>>(&mut self, tx: T) -> ChangeSet<A> {
         // This returns `Some` only if the merged tx is different to the `original_tx`.
         fn _merge_tx_witnesses(
@@ -1247,6 +1265,37 @@ impl<A: Anchor> TxGraph<A> {
     ///
     /// This is the infallible version of [`try_filter_chain_unspents`].
     ///
+    /// # Example
+    ///
+    /// ```
+    /// use bdk_chain::local_chain::LocalChain;
+    /// use bdk_chain::{tx_graph::TxGraph, BlockId, CanonicalizationParams};
+    /// use bitcoin::{Amount, OutPoint, TxOut};
+    /// use std::sync::Arc;
+    ///
+    /// let mut graph = TxGraph::<BlockId>::default();
+    /// let chain = LocalChain::from_blocks(
+    ///     [(
+    ///         0,
+    ///         bitcoin::constants::genesis_block(bitcoin::Network::Bitcoin).block_hash(),
+    ///     )]
+    ///     .into_iter()
+    ///     .collect(),
+    /// )
+    /// .unwrap();
+    ///
+    /// // Get unspent outputs
+    /// let outpoints = vec![(0, OutPoint::default())];
+    /// let utxos: Vec<_> = graph
+    ///     .filter_chain_unspents(
+    ///         &chain,
+    ///         chain.tip().block_id(),
+    ///         CanonicalizationParams::default(),
+    ///         outpoints,
+    ///     )
+    ///     .collect();
+    /// ```
+    ///
     /// [`try_filter_chain_unspents`]: Self::try_filter_chain_unspents
     pub fn filter_chain_unspents<'a, C: ChainOracle<Error = Infallible> + 'a, OI: Clone + 'a>(
         &'a self,
@@ -1315,6 +1364,34 @@ impl<A: Anchor> TxGraph<A> {
     ///
     /// This is the infallible version of [`try_balance`].
     ///
+    /// # Example
+    ///
+    /// ```
+    /// use bdk_chain::local_chain::LocalChain;
+    /// use bdk_chain::{tx_graph::TxGraph, Balance, BlockId, CanonicalizationParams};
+    /// use bitcoin::OutPoint;
+    ///
+    /// let graph = TxGraph::<BlockId>::default();
+    /// let chain = LocalChain::from_blocks(
+    ///     [(
+    ///         0,
+    ///         bitcoin::constants::genesis_block(bitcoin::Network::Bitcoin).block_hash(),
+    ///     )]
+    ///     .into_iter()
+    ///     .collect(),
+    /// )
+    /// .unwrap();
+    ///
+    /// let outpoints = vec![(0, OutPoint::default())];
+    /// let balance = graph.balance(
+    ///     &chain,
+    ///     chain.tip().block_id(),
+    ///     CanonicalizationParams::default(),
+    ///     outpoints,
+    ///     |_, _| true,
+    /// );
+    /// ```
+    ///
     /// [`try_balance`]: Self::try_balance
     pub fn balance<C: ChainOracle<Error = Infallible>, OI: Clone>(
         &self,

crates/electrum/src/bdk_electrum_client.rs

@@ -29,6 +29,15 @@ pub struct BdkElectrumClient<E> {
 
 impl<E: ElectrumApi> BdkElectrumClient<E> {
     /// Creates a new bdk client from a [`electrum_client::ElectrumApi`]
+    ///
+    /// # Example
+    /// ```no_run
+    /// use bdk_electrum::{electrum_client, BdkElectrumClient};
+    ///
+    /// let client = electrum_client::Client::new("ssl://electrum.blockstream.info:50002")?;
+    /// let bdk_client = BdkElectrumClient::new(client);
+    /// # Ok::<_, electrum_client::Error>(())
+    /// ```
     pub fn new(client: E) -> Self {
         Self {
             inner: client,
@@ -107,6 +116,26 @@ impl<E: ElectrumApi> BdkElectrumClient<E> {
     ///   [`CalculateFeeError::MissingTxOut`] error if those `TxOut`s are not present in the
     ///   transaction graph.
     ///
+    /// # Example
+    /// ```no_run
+    /// use bdk_core::{spk_client::FullScanRequest, BlockId, CheckPoint};
+    /// use bdk_electrum::BdkElectrumClient;
+    /// # use bdk_electrum::electrum_client;
+    /// # use electrum_client::bitcoin::{constants, Network};
+    ///
+    /// # let client = electrum_client::Client::new("ssl://electrum.blockstream.info:50002")?;
+    /// # let bdk_client = BdkElectrumClient::new(client);
+    /// let request = FullScanRequest::<&str>::builder()
+    ///     .chain_tip(CheckPoint::new(BlockId {
+    ///         height: 0,
+    ///         hash: constants::genesis_block(Network::Bitcoin).block_hash(),
+    ///     }))
+    ///     .build();
+    ///
+    /// let response = bdk_client.full_scan(request, 10, 50, false)?;
+    /// # Ok::<_, electrum_client::Error>(())
+    /// ```
+    ///
     /// [`bdk_chain`]: ../bdk_chain/index.html
     /// [`CalculateFeeError::MissingTxOut`]: ../bdk_chain/tx_graph/enum.CalculateFeeError.html#variant.MissingTxOut
     /// [`Wallet.calculate_fee`]: ../bdk_wallet/struct.Wallet.html#method.calculate_fee
@@ -190,6 +219,23 @@ impl<E: ElectrumApi> BdkElectrumClient<E> {
     /// If the scripts to sync are unknown, such as when restoring or importing a keychain that
     /// may include scripts that have been used, use [`full_scan`] with the keychain.
     ///
+    /// # Example
+    /// ```no_run
+    /// use bdk_core::bitcoin::ScriptBuf;
+    /// use bdk_core::spk_client::SyncRequest;
+    /// use bdk_electrum::BdkElectrumClient;
+    /// # use bdk_electrum::electrum_client;
+    ///
+    /// # let client = electrum_client::Client::new("ssl://electrum.blockstream.info:50002")?;
+    /// # let bdk_client = BdkElectrumClient::new(client);
+    /// let request = SyncRequest::builder()
+    ///     .spks([ScriptBuf::new_op_return(&[0x00; 20])])
+    ///     .build();
+    ///
+    /// let response = bdk_client.sync(request, 50, false)?;
+    /// # Ok::<_, electrum_client::Error>(())
+    /// ```
+    ///
     /// [`full_scan`]: Self::full_scan
     /// [`bdk_chain`]: ../bdk_chain/index.html
     /// [`CalculateFeeError::MissingTxOut`]: ../bdk_chain/tx_graph/enum.CalculateFeeError.html#variant.MissingTxOut

crates/esplora/src/blocking_ext.rs

@@ -26,6 +26,27 @@ pub trait EsploraExt {
     /// `stop_gap` script pubkeys with no associated transactions. `parallel_requests` specifies
     /// the maximum number of HTTP requests to make in parallel.
     ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use bdk_core::bitcoin::{constants, Network};
+    /// use bdk_core::spk_client::FullScanRequest;
+    /// use bdk_core::{BlockId, CheckPoint};
+    /// use bdk_esplora::{esplora_client, EsploraExt};
+    ///
+    /// let client = esplora_client::Builder::new("https://blockstream.info/api").build_blocking();
+    ///
+    /// let request = FullScanRequest::<&str>::builder()
+    ///     .chain_tip(CheckPoint::new(BlockId {
+    ///         height: 0,
+    ///         hash: constants::genesis_block(Network::Bitcoin).block_hash(),
+    ///     }))
+    ///     .build();
+    ///
+    /// let response = client.full_scan(request, 10, 5)?;
+    /// # Ok::<_, Box<dyn std::error::Error>>(())
+    /// ```
+    ///
     /// Refer to [crate-level docs](crate) for more.
     fn full_scan<K: Ord + Clone, R: Into<FullScanRequest<K>>>(
         &self,