Merge #976: Reimplement Wallet, ElectrumExt and Esplora{Async}Ext with redesigned structures.

75f8b81 Update documentation (志宇)
cff9211 [wallet_redesign] Clean up and document address methods (志宇)
a7668a2 [wallet_redesign] Modified `insert_tx` to use lowest checkpoint (志宇)
ac80829 Rename fields of `tx_graph::Additions` (Shourya742)
1c3cbef [chain_redesign] Remove old structures (志宇)
5860704 Implement redesigned versions of `EsploraExt` and `EsploraAsyncExt` (志宇)
2952341 Update the `wallet_electrum` example (志宇)
78a7920 `bdk_electrum` API improvements and simplifications (志宇)
92709d0 Various tweaks to code arrangement and documentation (志宇)
50425e9 Introduce `keychain::LocalChangeSet` (志宇)
a78967e [example-cli] simplify new address logic (LLFourn)
6a1ac7f [examples_redesign] Implemented `example_electrum` (志宇)
f55974a [examples_redesign] Introduce `example_cli` package (志宇)
2e3cee4 [electrum_redesign] Introduce redesigned `ElectrumExt` (志宇)
7261669 Add `last_seen` to the the `ConfirmationTime::Unconfirmed` variant (志宇)
aba8813 [wallet_redesign] Move the majority of `Update` to `bdk_chain` (志宇)
e69fccb [wallet_redesign] Update `Wallet` with redesigned structures (志宇)

Pull request description:

  ### Description

  Closes #938

  * Update `Wallet` to use redesigned structures.
  * Update `bdk_electrum::ElectrumExt` to produce updates for redesigned structures.
  * Update `bdk_esplora::EsploraExt` and `bdk_esplora::EsploraAsyncExt` to produce updates for redesigned structures.
  * Added `example-crates/example_cli` library for implementing examples with redesigned structures.
  * Added `example-crate/example_electrum` which is an electrum CLI wallet using the redesigned structures.
  * Updated `example-crate/{wallet_electrum|wallet_esplora|wallet_esplora_async}` examples to use redesigned structures.
  * Remove all old structures.

  ### Notes to the reviewers

  ~These changes bump our `all-features` MSRV to `1.60.0` because of the introduction of `bdk_esplora`. As long as the `bdk_chain` and `bdk_wallet` crates hit a MSRV of `1.48.0`, it will be fine (this work is done in #987).~ No longer needed due to #993

  ~I had to comment out the examples that use `Wallet` with our chain sources. Once we update the helper-packages for those chain sources, we can also update the examples.~

  Possible future improvements for `ElectrumExt`:

  * Remove requirement to retry obtaining ALL data after reorg is detected. Transactions can be anchored to a lower block (not block tip), and an `assume_final_depth` value can be used.

  * The logic to finalize an update with confirmation time can be improved during reorgs to not require returning an error.

  * Use the subscription model of electrum, as intended by the API.

  ### Changelog notice

  ### Checklists

  #### All Submissions:

  * [x] I've signed all my commits
  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)
  * [x] I ran `cargo fmt` and `cargo clippy` before committing

  #### New Features:

  * [x] I've added tests for the new feature
  * [x] I've added docs for the new feature

ACKs for top commit:
  LLFourn:
    ACK 75f8b81
  danielabrozzoni:
    Partial ACK 75f8b81 - the Wallet code looks good to me, I don't have a good enough understanding of the esplora/electrum code to confidently ACK it.

Tree-SHA512: d1d2b79e3c28fbe826044a8b5ef9b122c2dcfc0d371f24cc4aac7f286500b587c2dc3b06ca6461c8721adbc29f56ca41e7566eace560b0a9c541604e6a225c61

Author: danielabrozzoni

Cargo.toml

@@ -4,9 +4,9 @@ members = [
     "crates/chain",
     "crates/file_store",
     "crates/electrum",
-    "example-crates/keychain_tracker_electrum",
-    "example-crates/keychain_tracker_esplora",
-    "example-crates/keychain_tracker_example_cli",
+    "crates/esplora",
+    "example-crates/example_cli",
+    "example-crates/example_electrum",
     "example-crates/wallet_electrum",
     "example-crates/wallet_esplora",
     "example-crates/wallet_esplora_async",

crates/bdk/src/lib.rs

@@ -1,5 +1,7 @@
 #![doc = include_str!("../README.md")]
 #![no_std]
+#![warn(missing_docs)]
+
 #[cfg(feature = "std")]
 #[macro_use]
 extern crate std;

crates/bdk/src/types.rs

@@ -22,9 +22,9 @@ use serde::{Deserialize, Serialize};
 /// Types of keychains
 #[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Hash, Ord, PartialOrd)]
 pub enum KeychainKind {
-    /// External
+    /// External keychain, used for deriving recipient addresses.
     External = 0,
-    /// Internal, usually used for change outputs
+    /// Internal keychain, used for deriving change addresses.
     Internal = 1,
 }
 

crates/bdk/src/wallet/coin_selection.rs

@@ -722,9 +722,13 @@ mod test {
 
     fn get_test_utxos() -> Vec<WeightedUtxo> {
         vec![
-            utxo(100_000, 0, ConfirmationTime::Unconfirmed),
-            utxo(FEE_AMOUNT - 40, 1, ConfirmationTime::Unconfirmed),
-            utxo(200_000, 2, ConfirmationTime::Unconfirmed),
+            utxo(100_000, 0, ConfirmationTime::Unconfirmed { last_seen: 0 }),
+            utxo(
+                FEE_AMOUNT - 40,
+                1,
+                ConfirmationTime::Unconfirmed { last_seen: 0 },
+            ),
+            utxo(200_000, 2, ConfirmationTime::Unconfirmed { last_seen: 0 }),
         ]
     }
 
@@ -780,7 +784,7 @@ mod test {
                             time: rng.next_u64(),
                         }
                     } else {
-                        ConfirmationTime::Unconfirmed
+                        ConfirmationTime::Unconfirmed { last_seen: 0 }
                     },
                 }),
             });
@@ -803,7 +807,7 @@ mod test {
                 keychain: KeychainKind::External,
                 is_spent: false,
                 derivation_index: 42,
-                confirmation_time: ConfirmationTime::Unconfirmed,
+                confirmation_time: ConfirmationTime::Unconfirmed { last_seen: 0 },
             }),
         };
         vec![utxo; utxos_number]
@@ -1091,7 +1095,11 @@ mod test {
 
         let required = vec![utxos[0].clone()];
         let mut optional = utxos[1..].to_vec();
-        optional.push(utxo(500_000, 3, ConfirmationTime::Unconfirmed));
+        optional.push(utxo(
+            500_000,
+            3,
+            ConfirmationTime::Unconfirmed { last_seen: 0 },
+        ));
 
         // Defensive assertions, for sanity and in case someone changes the test utxos vector.
         let amount: u64 = required.iter().map(|u| u.utxo.txout().value).sum();

crates/bdk/src/wallet/export.rs

@@ -56,7 +56,6 @@
 use core::str::FromStr;
 
 use alloc::string::{String, ToString};
-use bdk_chain::sparse_chain::ChainPosition;
 use serde::{Deserialize, Serialize};
 
 use miniscript::descriptor::{ShInner, WshInner};
@@ -130,8 +129,10 @@ impl FullyNodedExport {
             wallet
                 .transactions()
                 .next()
-                .and_then(|(pos, _)| pos.height().into())
-                .unwrap_or(0)
+                .map_or(0, |canonical_tx| match canonical_tx.observed_as {
+                    bdk_chain::ChainPosition::Confirmed(a) => a.confirmation_height,
+                    bdk_chain::ChainPosition::Unconfirmed(_) => 0,
+                })
         } else {
             0
         };