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/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`).
-    pub keychain: BTreeMap<K, u32>,
+    /// Contains the last active derivation indices per keychain (`K`), which is used to update the
+    /// [`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
     }