Merge #1040: Add cli esplora example

f41cc1c fix: s/index_tx_graph/indexed_tx_graph/g (LLFourn)
da8cfd3 feat: add cli example for `esplora` (志宇)

Pull request description:

  ### Description

  This PR builds on top of #1034 and adds a cli-example for our `esplora` chain-src crate.

  ### Notes to the reviewers

  Don't merge this until #1034 is merged. The only relevant commit is 5ff0412.

  ### Changelog notice

  * Add cli-example for `esplora`.

  ### 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:

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

ACKs for top commit:
  danielabrozzoni:
    ACK f41cc1c
  notmandatory:
    ACK f41cc1c

Tree-SHA512: a41fa456a9509f75feea0af013deaaad846cc6b60e5e6671672630a716e8c962361cbc9bb2d62c68e96d5fdb9e580912c19ff5fcab1acaf604b5b4a10eb40cee

Author: notmandatory

Cargo.toml

@@ -7,6 +7,7 @@ members = [
     "crates/esplora",
     "example-crates/example_cli",
     "example-crates/example_electrum",
+    "example-crates/example_esplora",
     "example-crates/wallet_electrum",
     "example-crates/wallet_esplora_blocking",
     "example-crates/wallet_esplora_async",

crates/bdk/src/wallet/mod.rs

@@ -248,7 +248,7 @@ impl<D> Wallet<D> {
 
         let changeset = db.load_from_persistence().map_err(NewError::Persist)?;
         chain.apply_changeset(&changeset.chain);
-        indexed_graph.apply_changeset(changeset.index_tx_graph);
+        indexed_graph.apply_changeset(changeset.indexed_tx_graph);
 
         let persist = Persist::new(db);
 

crates/chain/src/keychain.rs

@@ -133,26 +133,26 @@ pub struct WalletChangeSet<K, A> {
     /// ChangeSet to [`IndexedTxGraph`].
     ///
     /// [`IndexedTxGraph`]: crate::indexed_tx_graph::IndexedTxGraph
-    pub index_tx_graph: indexed_tx_graph::ChangeSet<A, ChangeSet<K>>,
+    pub indexed_tx_graph: indexed_tx_graph::ChangeSet<A, ChangeSet<K>>,
 }
 
 impl<K, A> Default for WalletChangeSet<K, A> {
     fn default() -> Self {
         Self {
             chain: Default::default(),
-            index_tx_graph: Default::default(),
+            indexed_tx_graph: Default::default(),
         }
     }
 }
 
 impl<K: Ord, A: Anchor> Append for WalletChangeSet<K, A> {
     fn append(&mut self, other: Self) {
         Append::append(&mut self.chain, other.chain);
-        Append::append(&mut self.index_tx_graph, other.index_tx_graph);
+        Append::append(&mut self.indexed_tx_graph, other.indexed_tx_graph);
     }
 
     fn is_empty(&self) -> bool {
-        self.chain.is_empty() && self.index_tx_graph.is_empty()
+        self.chain.is_empty() && self.indexed_tx_graph.is_empty()
     }
 }
 
@@ -166,9 +166,9 @@ impl<K, A> From<local_chain::ChangeSet> for WalletChangeSet<K, A> {
 }
 
 impl<K, A> From<indexed_tx_graph::ChangeSet<A, ChangeSet<K>>> for WalletChangeSet<K, A> {
-    fn from(index_tx_graph: indexed_tx_graph::ChangeSet<A, ChangeSet<K>>) -> Self {
+    fn from(indexed_tx_graph: indexed_tx_graph::ChangeSet<A, ChangeSet<K>>) -> Self {
         Self {
-            index_tx_graph,
+            indexed_tx_graph,
             ..Default::default()
         }
     }

crates/chain/src/tx_graph.rs

@@ -1066,6 +1066,45 @@ impl<A> ChangeSet<A> {
             })
             .chain(self.txouts.iter().map(|(op, txout)| (*op, txout)))
     }
+
+    /// Iterates over the heights of that the new transaction anchors in this changeset.
+    ///
+    /// This is useful if you want to find which heights you need to fetch data about in order to
+    /// confirm or exclude these anchors.
+    ///
+    /// See also: [`TxGraph::missing_heights`]
+    pub fn anchor_heights(&self) -> impl Iterator<Item = u32> + '_
+    where
+        A: Anchor,
+    {
+        let mut dedup = None;
+        self.anchors
+            .iter()
+            .map(|(a, _)| a.anchor_block().height)
+            .filter(move |height| {
+                let duplicate = dedup == Some(*height);
+                dedup = Some(*height);
+                !duplicate
+            })
+    }
+
+    /// Returns an iterator for the [`anchor_heights`] in this changeset that are not included in
+    /// `local_chain`. This tells you which heights you need to include in `local_chain` in order
+    /// for it to conclusively act as a [`ChainOracle`] for the transaction anchors this changeset
+    /// will add.
+    ///
+    /// [`ChainOracle`]: crate::ChainOracle
+    /// [`anchor_heights`]: Self::anchor_heights
+    pub fn missing_heights_from<'a>(
+        &'a self,
+        local_chain: &'a LocalChain,
+    ) -> impl Iterator<Item = u32> + 'a
+    where
+        A: Anchor,
+    {
+        self.anchor_heights()
+            .filter(move |height| !local_chain.blocks().contains_key(height))
+    }
 }
 
 impl<A: Ord> Append for ChangeSet<A> {

example-crates/example_electrum/src/main.rs

@@ -68,7 +68,7 @@ fn main() -> anyhow::Result<()> {
 
     let graph = Mutex::new({
         let mut graph = IndexedTxGraph::new(index);
-        graph.apply_changeset(init_changeset.index_tx_graph);
+        graph.apply_changeset(init_changeset.indexed_tx_graph);
         graph
     });
 
@@ -277,7 +277,7 @@ fn main() -> anyhow::Result<()> {
 
         let chain = chain.apply_update(final_update.chain)?;
 
-        let index_tx_graph = {
+        let indexed_tx_graph = {
             let mut changeset =
                 indexed_tx_graph::ChangeSet::<ConfirmationHeightAnchor, _>::default();
             let (_, indexer) = graph
@@ -292,7 +292,7 @@ fn main() -> anyhow::Result<()> {
         };
 
         ChangeSet {
-            index_tx_graph,
+            indexed_tx_graph,
             chain,
         }
     };

example-crates/example_esplora/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "example_esplora"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+bdk_chain = { path = "../../crates/chain", features = ["serde"] }
+bdk_esplora = { path = "../../crates/esplora", features = ["blocking"] }
+example_cli = { path = "../example_cli" }
+