fix: improve more docs and more refactoring

Thank you @vladimirfomene for these suggestions.

* Rename `LocalUpdate::keychain` to `LocalUpdate::last_active_indices`.
* Change docs for `CheckPoint` to be more descriptive.
* Fix incorrect logic in `update_local_chain` for `EsploraExt` and
  `EsploraAsyncExt`.

crates/bdk/src/wallet/mod.rs

@@ -1711,7 +1711,7 @@ impl<D> Wallet<D> {
         let (_, index_additions) = self
             .indexed_graph
             .index
-            .reveal_to_target_multi(&update.keychain);
+            .reveal_to_target_multi(&update.last_active_indices);
         changeset.append(ChangeSet::from(IndexedAdditions::from(index_additions)));
         changeset.append(ChangeSet::from(
             self.indexed_graph.apply_update(update.graph),

crates/chain/src/keychain.rs

@@ -91,8 +91,9 @@ impl<K> AsRef<BTreeMap<K, u32>> for DerivationAdditions<K> {
 /// [`LocalChain`]: local_chain::LocalChain
 #[derive(Debug, Clone)]
 pub struct LocalUpdate<K, A> {
-    /// Last active derivation index per keychain (`K`).
+    /// Contains the last active derivation indices per keychain (`K`), which is used to update the
-    pub keychain: BTreeMap<K, u32>,
+    /// [`KeychainTxOutIndex`].
+    pub last_active_indices: BTreeMap<K, u32>,
 
     /// Update for the [`TxGraph`].
     pub graph: TxGraph<A>,
@@ -104,12 +105,12 @@ pub struct LocalUpdate<K, A> {
 }
 
 impl<K, A> LocalUpdate<K, A> {
-    /// Construct a [`LocalUpdate`] with a given [`CheckPoint`] tip.
+    /// Construct a [`LocalUpdate`] with a given [`local_chain::Update`].
     ///
     /// [`CheckPoint`]: local_chain::CheckPoint
     pub fn new(chain_update: local_chain::Update) -> Self {
         Self {
-            keychain: BTreeMap::new(),
+            last_active_indices: BTreeMap::new(),
             graph: TxGraph::default(),
             chain: chain_update,
         }

crates/chain/src/local_chain.rs

@@ -10,9 +10,13 @@ use bitcoin::BlockHash;
 /// A structure that represents changes to [`LocalChain`].
 pub type ChangeSet = BTreeMap<u32, Option<BlockHash>>;
 
-/// A blockchain of [`LocalChain`].
+/// A [`LocalChain`] checkpoint is used to find the agreement point between two chains and as a
+/// transaction anchor.
 ///
-/// The in a linked-list with newer blocks pointing to older ones.
+/// Each checkpoint contains the height and hash of a block ([`BlockId`]).
+///
+/// Internaly, checkpoints are nodes of a linked-list. This allows the caller to view the entire
+/// chain without holding a lock to [`LocalChain`].
 #[derive(Debug, Clone)]
 pub struct CheckPoint(Arc<CPInner>);
 
@@ -382,7 +386,7 @@ impl LocalChain {
         }
     }
 
-    /// Get a reference to the internal index mapping the height to block hash
+    /// Get a reference to the internal index mapping the height to block hash.
     pub fn heights(&self) -> &BTreeMap<u32, BlockHash> {
         &self.index
     }

crates/chain/tests/test_local_chain.rs

@@ -123,7 +123,7 @@ fn update_local_chain() {
             },
         },
         // Introduce an older checkpoint (A) that is not directly behind PoA
-        //        | 1 | 2 | 3
+        //        | 2 | 3 | 4
         // chain  |     B   C
         // update | A       C
         TestLocalChain {

crates/electrum/src/electrum_ext.rs

@@ -69,7 +69,7 @@ impl<K, A: Anchor> ElectrumUpdate<K, A> {
             }
         }
         Ok(LocalUpdate {
-            keychain: self.keychain_update,
+            last_active_indices: self.keychain_update,
             graph: graph_update,
             chain: local_chain::Update {
                 tip: self.new_tip,
@@ -93,7 +93,6 @@ impl<K> ElectrumUpdate<K, ConfirmationHeightAnchor> {
         missing: Vec<Txid>,
     ) -> Result<LocalUpdate<K, ConfirmationTimeAnchor>, Error> {
         let update = self.finalize(client, seen_at, missing)?;
-        // client.batch_transaction_get(txid)
 
         let relevant_heights = {
             let mut visited_heights = HashSet::new();
@@ -141,7 +140,7 @@ impl<K> ElectrumUpdate<K, ConfirmationHeightAnchor> {
         };
 
         Ok(LocalUpdate {
-            keychain: update.keychain,
+            last_active_indices: update.last_active_indices,
             graph: {
                 let mut graph = TxGraph::default();
                 graph.apply_additions(graph_additions);

crates/esplora/src/async_ext.rs

@@ -282,7 +282,6 @@ impl EsploraAsyncExt for esplora_client::AsyncClient {
                     async move { client.get_tx_status(&txid).await.map(|s| (txid, s)) }
                 })
                 .collect::<FuturesOrdered<_>>();
-            // .collect::<Vec<JoinHandle<Result<(Txid, TxStatus), Error>>>>();
 
             if handles.is_empty() {
                 break;

example-crates/example_electrum/src/main.rs

@@ -278,7 +278,9 @@ fn main() -> anyhow::Result<()> {
 
         let indexed_additions = {
             let mut additions = IndexedAdditions::<ConfirmationHeightAnchor, _>::default();
-            let (_, index_additions) = graph.index.reveal_to_target_multi(&final_update.keychain);
+            let (_, index_additions) = graph
+                .index
+                .reveal_to_target_multi(&final_update.last_active_indices);
             additions.append(IndexedAdditions {
                 index_additions,
                 ..Default::default()

example-crates/wallet_esplora/src/main.rs

@@ -59,7 +59,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     let get_heights = wallet.tx_graph().missing_blocks(wallet.local_chain());
     let chain_update = client.update_local_chain(prev_tip, get_heights)?;
     let update = LocalUpdate {
-        keychain: last_active_indices,
+        last_active_indices,
         graph: update_graph,
         ..LocalUpdate::new(chain_update)
     };

example-crates/wallet_esplora_async/src/main.rs

@@ -60,7 +60,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let get_heights = wallet.tx_graph().missing_blocks(wallet.local_chain());
     let chain_update = client.update_local_chain(prev_tip, get_heights).await?;
     let update = LocalUpdate {
-        keychain: last_active_indices,
+        last_active_indices,
         graph: update_graph,
         ..LocalUpdate::new(chain_update)
     };