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`.

diff --git a/crates/bdk/src/wallet/mod.rs b/crates/bdk/src/wallet/mod.rs
index 634c5c66c0f8d6ba9fe32c665e4adc86c9519eb2..73e8839d2f5e8531f49b511485c762e2183f4771 100644 (file)
--- a/crates/bdk/src/wallet/mod.rs
+++ b/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),

diff --git a/crates/chain/src/keychain.rs b/crates/chain/src/keychain.rs
index cc85df4cf91cb00b8629cc5b4265497c813f0316..317d5f2b4184bc93f5cd6bb19df5d1ad818088fb 100644 (file)
--- a/crates/chain/src/keychain.rs
+++ b/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,
         }

diff --git a/crates/chain/src/local_chain.rs b/crates/chain/src/local_chain.rs
index 48e298350d62627a3d3de17c48d8bf4ed98f3e90..1caf20b7aa18973a56fe143421988af93392f79e 100644 (file)
--- a/crates/chain/src/local_chain.rs
+++ b/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
     }

diff --git a/crates/chain/tests/test_local_chain.rs b/crates/chain/tests/test_local_chain.rs
index aaa2c371df0edeac1f989abe736e0eab69641ecf..9ea8b7f3a6ace355e939e25520aa02f9b23a489f 100644 (file)
--- a/crates/chain/tests/test_local_chain.rs
+++ b/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 {

diff --git a/crates/electrum/src/electrum_ext.rs b/crates/electrum/src/electrum_ext.rs
index 62f7aa7e33e2b3f1532c86c78bff883bb31fc248..666e06776369955305c8ac233b2d40c4afb30b1f 100644 (file)
--- a/crates/electrum/src/electrum_ext.rs
+++ b/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);

diff --git a/crates/esplora/src/async_ext.rs b/crates/esplora/src/async_ext.rs
index 5de02ffd0dc2d64827cc9c5889756797b5565991..6a72dac240718931ce903db97dd351c92d89aa39 100644 (file)
--- a/crates/esplora/src/async_ext.rs
+++ b/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;

diff --git a/example-crates/example_electrum/src/main.rs b/example-crates/example_electrum/src/main.rs
index 537412f076ca4ae41e2efd4b994b555262a21307..6b8d13526a9a71a9b7b7a85048e16721a9ecece3 100644 (file)
--- a/example-crates/example_electrum/src/main.rs
+++ b/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()

diff --git a/example-crates/wallet_esplora/src/main.rs b/example-crates/wallet_esplora/src/main.rs
index 530aee5bac35a198a486801f4a410e33b00b7a01..9cd4663e441bf8580d2dca3855ad8900917be105 100644 (file)
--- a/example-crates/wallet_esplora/src/main.rs
+++ b/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)
     };

diff --git a/example-crates/wallet_esplora_async/src/main.rs b/example-crates/wallet_esplora_async/src/main.rs
index fe1c85a227f540560bb0b21f751b9b975c36cb6f..a82b410b031a0eade88d2cb8675a1e1f228ae136 100644 (file)
--- a/example-crates/wallet_esplora_async/src/main.rs
+++ b/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)
     };