Various tweaks to code arrangement and documentation

As per reviews by @danielabrozzoni and @LLFourn

crates/bdk/src/wallet/mod.rs

@@ -501,20 +501,7 @@ impl<D> Wallet<D> {
         Ok(changed)
     }
 
-    #[deprecated(note = "use Wallet::transactions instead")]
-    /// Deprecated. use `Wallet::transactions` instead.
-    pub fn list_transactions(
-        &self,
-        include_raw: bool,
-    ) -> impl Iterator<Item = TransactionDetails> + '_ {
-        self.indexed_graph
-            .graph()
-            .list_chain_txs(&self.chain, self.chain.tip().unwrap_or_default())
-            .map(move |canonical_tx| new_tx_details(&self.indexed_graph, canonical_tx, include_raw))
-    }
-
-    /// Iterate over the transactions in the wallet in order of ascending confirmation time with
-    /// unconfirmed transactions last.
+    /// Iterate over the transactions in the wallet.
     pub fn transactions(
         &self,
     ) -> impl Iterator<Item = CanonicalTx<'_, Transaction, ConfirmationTimeAnchor>> + '_ {
@@ -1685,6 +1672,8 @@ impl<D> Wallet<D> {
 
     /// Applies an update to the wallet and stages the changes (but does not [`commit`] them).
     ///
+    /// This returns whether the `update` resulted in any changes.
+    ///
     /// Usually you create an `update` by interacting with some blockchain data source and inserting
     /// transactions related to your wallet into it.
     ///
@@ -1706,7 +1695,10 @@ impl<D> Wallet<D> {
         Ok(changed)
     }
 
-    /// Commits all curently [`staged`] changed to the persistence backend returning and error when this fails.
+    /// Commits all curently [`staged`] changed to the persistence backend returning and error when
+    /// this fails.
+    ///
+    /// This returns whether the `update` resulted in any changes.
     ///
     /// [`staged`]: Self::staged
     pub fn commit(&mut self) -> Result<bool, D::WriteError>

crates/electrum/src/v2.rs

@@ -53,7 +53,6 @@ impl<'a, K, A: Anchor> ElectrumUpdate<K, A> {
                 let _ = graph_update.insert_anchor(txid, anchor);
             }
         }
-        dbg!(graph_update.full_txs().count());
         LocalUpdate {
             keychain: self.keychain_update,
             graph: graph_update,
@@ -63,6 +62,12 @@ impl<'a, K, A: Anchor> ElectrumUpdate<K, A> {
 }
 
 impl<K> ElectrumUpdate<K, ConfirmationHeightAnchor> {
+    /// Finalizes the [`ElectrumUpdate`] with `new_txs` and anchors of type
+    /// [`ConfirmationTimeAnchor`].
+    ///
+    /// **Note:** The confirmation time might not be precisely correct if there has been a reorg.
+    /// Electrum's API intends that we use the merkle proof API, we should change `bdk_electrum` to
+    /// use it.
     pub fn finalize_as_confirmation_time<T>(
         self,
         client: &Client,
@@ -73,7 +78,6 @@ impl<K> ElectrumUpdate<K, ConfirmationHeightAnchor> {
         T: IntoIterator<Item = Transaction>,
     {
         let update = self.finalize(seen_at, new_txs);
-        let update_tip = update.chain.tip().expect("must have tip");
 
         let relevant_heights = {
             let mut visited_heights = HashSet::new();
@@ -97,16 +101,6 @@ impl<K> ElectrumUpdate<K, ConfirmationHeightAnchor> {
             )
             .collect::<HashMap<u32, u64>>();
 
-        if update_tip.hash != client.block_header(update_tip.height as _)?.block_hash() {
-            // [TODO] We should alter the logic so we won't have to return an error. This is to
-            // [TODO] ensure obtained block times are "anchored" to our tip. If we exclude this, it
-            // [TODO] should be "safe" as well. Tx confirmation times would just slightly vary.
-            return Err(Error::Message(format!(
-                "tip changed during update: update_tip={:?}",
-                update_tip
-            )));
-        }
-
         let graph_additions = {
             let old_additions = TxGraph::default().determine_additions(&update.graph);
             tx_graph::Additions {
@@ -336,6 +330,10 @@ fn determine_tx_anchor(
     raw_height: i32,
     txid: Txid,
 ) -> Option<ConfirmationHeightAnchor> {
+    // The electrum API has a weird quirk where an unconfirmed transaction is presented with a
+    // height of 0. To avoid invalid representation in our data structures, we manually set
+    // transactions residing in the genesis block to have height 0, then interpret a height of 0 as
+    // unconfirmed for all other transactions.
     if txid
         == Txid::from_hex("4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b")
             .expect("must deserialize genesis coinbase txid")