From 78a17294a458577a10bb48fec9fe6d01397cc030 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kyle=20=F0=9F=90=86?= <kyle@privkey.io>
Date: Sat, 23 May 2026 14:59:47 -0400
Subject: [PATCH] docs(rpc): add Emitter::next_block and Emitter::mempool
 examples

---
 crates/bitcoind_rpc/src/lib.rs | 64 ++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/crates/bitcoind_rpc/src/lib.rs b/crates/bitcoind_rpc/src/lib.rs
index 35e6e2427..065ddccbf 100644
--- a/crates/bitcoind_rpc/src/lib.rs
+++ b/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.