fix: docs and some minor refactoring

Shout out to @LLFourn for these suggestions.

* Improve/fix `LocalChain` documentation
* Refactor `TxGraph::missing_blocks` to make it more explicit that
  `last_block` has state.
* `update_local_chain` method of `EsploraExt` and `EsploraAsyncExt` now
  returns a `local_chain::Update` instead of just a `CheckPoint`.

Author: evanlinjin

crates/chain/src/local_chain.rs

@@ -113,17 +113,25 @@ impl IntoIterator for CheckPoint {
     }
 }
 
-/// Represents an update to [`LocalChain`].
+/// A struct to update [`LocalChain`].
+///
+/// This is used as input for [`LocalChain::apply_update`]. It contains the update's chain `tip` and
+/// a `bool` which signals whether this update can introduce blocks below the original chain's tip
+/// without invalidating blocks residing on the original chain. Block-by-block syncing mechanisms
+/// would typically create updates that builds upon the previous tip. In this case, this paramater
+/// would be `false`. Script-pubkey based syncing mechanisms may not introduce transactions in a
+/// chronological order so some updates require introducing older blocks (to anchor older
+/// transactions). For script-pubkey based syncing, this parameter would typically be `true`.
 #[derive(Debug, Clone)]
 pub struct Update {
-    /// The update's new [`CheckPoint`] tip.
+    /// The update chain's new tip.
     pub tip: CheckPoint,
 
     /// Whether the update allows for introducing older blocks.
     ///
-    /// Refer to [`LocalChain::apply_update`] for more.
+    /// Refer to [struct-level documentation] for more.
     ///
-    /// [`LocalChain::apply_update`]: crate::local_chain::LocalChain::apply_update
+    /// [struct-level documentation]: Update
     pub introduce_older_blocks: bool,
 }
 
@@ -146,12 +154,6 @@ impl From<LocalChain> for BTreeMap<u32, BlockHash> {
     }
 }
 
-impl From<ChangeSet> for LocalChain {
-    fn from(value: ChangeSet) -> Self {
-        Self::from_changeset(value)
-    }
-}
-
 impl From<BTreeMap<u32, BlockHash>> for LocalChain {
     fn from(value: BTreeMap<u32, BlockHash>) -> Self {
         Self::from_blocks(value)
@@ -244,18 +246,9 @@ impl LocalChain {
         self.tip.is_none()
     }
 
-    /// Updates [`Self`] with the given `update_tip`.
-    ///
-    /// `introduce_older_blocks` specifies whether the `update_tip`'s history can introduce blocks
-    /// below the original chain's tip without invalidating blocks. Block-by-block syncing
-    /// mechanisms would typically create updates that builds upon the previous tip. In this case,
-    /// this paramater would be false. Script-pubkey based syncing mechanisms may not introduce
-    /// transactions in a chronological order so some updates require introducing older blocks (to
-    /// anchor older transactions). For script-pubkey based syncing, this parameter would typically
-    /// be true.
+    /// Applies the given `update` to the chain.
     ///
-    /// The method returns [`ChangeSet`] on success. This represents the applied changes to
-    /// [`Self`].
+    /// The method returns [`ChangeSet`] on success. This represents the applied changes to `self`.
     ///
     /// To update, the `update_tip` must *connect* with `self`. If `self` and `update_tip` has a
     /// mutual checkpoint (same height and hash), it can connect if:
@@ -275,7 +268,7 @@ impl LocalChain {
     ///
     /// An error will occur if the update does not correctly connect with `self`.
     ///
-    /// Refer to [module-level documentation] for more.
+    /// Refer to [`Update`] for more about the update struct.
     ///
     /// [module-level documentation]: crate::local_chain
     pub fn apply_update(&mut self, update: Update) -> Result<ChangeSet, CannotConnectError> {

crates/chain/src/tx_graph.rs

@@ -603,18 +603,16 @@ impl<A: Anchor> TxGraph<A> {
     /// This works by scanning through anchors, and seeing whether the anchor block of the anchor
     /// exists in the [`LocalChain`].
     pub fn missing_blocks<'a>(&'a self, chain: &'a LocalChain) -> impl Iterator<Item = u32> + 'a {
+        let mut last_block = Option::<BlockId>::None;
         self.anchors
             .iter()
             .map(|(a, _)| a.anchor_block())
-            .filter({
-                let mut last_block = Option::<BlockId>::None;
-                move |block| {
-                    if last_block.as_ref() == Some(block) {
-                        false
-                    } else {
-                        last_block = Some(*block);
-                        true
-                    }
+            .filter(move |block| {
+                if last_block.as_ref() == Some(block) {
+                    false
+                } else {
+                    last_block = Some(*block);
+                    true
                 }
             })
             .filter_map(|block| match chain.heights().get(&block.height) {

crates/chain/tests/test_indexed_tx_graph.rs

@@ -107,11 +107,11 @@ fn insert_relevant_txs() {
 
 fn test_list_owned_txouts() {
     // Create Local chains
-
-    let local_chain = (0..150)
-        .map(|i| (i as u32, Some(h!("random"))))
-        .collect::<BTreeMap<u32, Option<BlockHash>>>();
-    let local_chain = LocalChain::from(local_chain);
+    let local_chain = LocalChain::from(
+        (0..150)
+            .map(|i| (i as u32, h!("random")))
+            .collect::<BTreeMap<u32, BlockHash>>(),
+    );
 
     // Initiate IndexedTxGraph
 

crates/esplora/src/blocking_ext.rs

@@ -6,8 +6,8 @@ use bdk_chain::collections::{BTreeMap, BTreeSet};
 use bdk_chain::{
     bitcoin::{BlockHash, Script},
     local_chain::{self, CheckPoint},
+    BlockId, ConfirmationTimeAnchor, TxGraph,
 };
-use bdk_chain::{BlockId, ConfirmationTimeAnchor, TxGraph};
 use esplora_client::{Error, TxStatus};
 
 use crate::{anchor_from_status, ASSUME_FINAL_DEPTH};