docs(rpc): add Emitter examples and remove example_bitcoind_rpc_polling

Author: kwsantiago

.github/workflows/cont_integration.yml

@@ -149,7 +149,6 @@ jobs:
       matrix:
         example-dir:
           - example_cli
-          - example_bitcoind_rpc_polling
           - example_electrum
           - example_esplora
     steps:

Cargo.toml

@@ -11,7 +11,6 @@ members = [
     "examples/example_cli",
     "examples/example_electrum",
     "examples/example_esplora",
-    "examples/example_bitcoind_rpc_polling",
 ]
 
 [workspace.package]

README.md

@@ -46,7 +46,6 @@ Fully working examples of how to use these components are in `/examples`:
 - [`example_cli`](examples/example_cli): Library used by the `example_*` crates. Provides utilities for syncing, showing the balance, generating addresses and creating transactions without using the bdk_wallet `Wallet`.
 - [`example_electrum`](examples/example_electrum): A command line Bitcoin wallet application built on top of `example_cli` and the `electrum` crate. It shows the power of the bdk tools (`chain` + `file_store` + `electrum`), without depending on the main `bdk_wallet` library.
 - [`example_esplora`](examples/example_esplora): A command line Bitcoin wallet application built on top of `example_cli` and the `esplora` crate. It shows the power of the bdk tools (`chain` + `file_store` + `esplora`), without depending on the main `bdk_wallet` library.
-- [`example_bitcoind_rpc_polling`](examples/example_bitcoind_rpc_polling): A command line Bitcoin wallet application built on top of `example_cli` and the `bitcoind_rpc` crate. It shows the power of the bdk tools (`chain` + `file_store` + `bitcoind_rpc`), without depending on the main `bdk_wallet` library.
 
 [`rust-miniscript`]: https://github.com/rust-bitcoin/rust-miniscript
 [`rust-bitcoin`]: https://github.com/rust-bitcoin/rust-bitcoin

crates/bitcoind_rpc/src/lib.rs

@@ -107,6 +107,38 @@ where
     /// are only reported once the emitter’s checkpoint matches the RPC’s best block in both height
     /// and hash. Until `next_block()` advances the checkpoint to tip, `mempool()` will always
     /// return an empty `evicted` set.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use bdk_bitcoind_rpc::{
+    ///     bitcoincore_rpc::{Auth, Client},
+    ///     Emitter, NO_EXPECTED_MEMPOOL_TXS,
+    /// };
+    /// use bdk_core::CheckPoint;
+    /// use bitcoin::{constants::genesis_block, Network};
+    ///
+    /// let client = Client::new("127.0.0.1:8332", Auth::None)?;
+    /// let genesis_hash = genesis_block(Network::Bitcoin).block_hash();
+    /// let mut emitter = Emitter::new(
+    ///     &client,
+    ///     CheckPoint::new(0, genesis_hash),
+    ///     0,
+    ///     NO_EXPECTED_MEMPOOL_TXS,
+    /// );
+    ///
+    /// // Drain blocks first so evictions can be reported once the checkpoint reaches tip.
+    /// while emitter.next_block()?.is_some() {}
+    ///
+    /// let event = emitter.mempool()?;
+    /// for (tx, seen_at) in event.update {
+    ///     // index unconfirmed `tx` (first seen at `seen_at`)
+    /// }
+    /// for (txid, evicted_at) in event.evicted {
+    ///     // mark `txid` as evicted from the mempool at `evicted_at`
+    /// }
+    /// # Ok::<_, bdk_bitcoind_rpc::bitcoincore_rpc::Error>(())
+    /// ```
     #[cfg(feature = "std")]
     pub fn mempool(&mut self) -> Result<MempoolEvent, bitcoincore_rpc::Error> {
         let sync_time = std::time::UNIX_EPOCH
@@ -199,6 +231,38 @@ where
     }
 
     /// Emit the next block height and block (if any).
+    ///
+    /// Call this repeatedly until it returns `Ok(None)`, which means the chain tip has been
+    /// reached. Each [`BlockEvent`] carries the block alongside the [`CheckPoint`] it connects to,
+    /// so it can be applied to BDK structures that require block connectivity.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use bdk_bitcoind_rpc::{
+    ///     bitcoincore_rpc::{Auth, Client},
+    ///     Emitter, NO_EXPECTED_MEMPOOL_TXS,
+    /// };
+    /// use bdk_core::CheckPoint;
+    /// use bitcoin::{constants::genesis_block, Network};
+    ///
+    /// let client = Client::new("127.0.0.1:8332", Auth::None)?;
+    /// let genesis_hash = genesis_block(Network::Bitcoin).block_hash();
+    /// let start_height = 0;
+    /// let mut emitter = Emitter::new(
+    ///     &client,
+    ///     CheckPoint::new(0, genesis_hash),
+    ///     start_height,
+    ///     NO_EXPECTED_MEMPOOL_TXS,
+    /// );
+    ///
+    /// while let Some(event) = emitter.next_block()? {
+    ///     let height = event.block_height();
+    ///     let connected_to = event.connected_to();
+    ///     // apply `event.block` to your chain and tx graph here
+    /// }
+    /// # Ok::<_, bdk_bitcoind_rpc::bitcoincore_rpc::Error>(())
+    /// ```
     pub fn next_block(&mut self) -> Result<Option<BlockEvent<Block>>, bitcoincore_rpc::Error> {
         if let Some((checkpoint, block)) = poll(self, move |hash, client| client.get_block(hash))? {
             // Stop tracking unconfirmed transactions that have been confirmed in this block.