test(esplora): move esplora tests into src files

Since we want to keep these methods private.

crates/esplora/Cargo.toml

@@ -25,6 +25,7 @@ miniscript = { version = "11.0.0", optional = true, default-features = false }
 bdk_testenv = { path = "../testenv", default_features = false }
 electrsd = { version= "0.27.1", features = ["bitcoind_25_0", "esplora_a33e97e1", "legacy"] }
 tokio = { version = "1", features = ["rt", "rt-multi-thread", "macros"] }
+anyhow = "1"
 
 [features]
 default = ["std", "async-https", "blocking"]

crates/esplora/src/async_ext.rs

@@ -139,8 +139,7 @@ impl EsploraAsyncExt for esplora_client::AsyncClient {
 /// block-based chain-sources). Therefore it's better to be conservative when setting the tip (use
 /// an earlier tip rather than a later tip) otherwise the caller may accidentally skip blocks when
 /// alternating between chain-sources.
-#[doc(hidden)]
-pub async fn init_chain_update(
+async fn init_chain_update(
     client: &esplora_client::AsyncClient,
     local_tip: &CheckPoint,
 ) -> Result<BTreeMap<u32, BlockHash>, Error> {
@@ -183,8 +182,7 @@ pub async fn init_chain_update(
 ///
 /// A checkpoint is considered "missing" if an anchor (of `anchors`) points to a height without an
 /// existing checkpoint/block under `local_tip` or `update_blocks`.
-#[doc(hidden)]
-pub async fn finalize_chain_update<A: Anchor>(
+async fn finalize_chain_update<A: Anchor>(
     client: &esplora_client::AsyncClient,
     local_tip: &CheckPoint,
     anchors: &BTreeSet<(A, Txid)>,
@@ -243,8 +241,7 @@ pub async fn finalize_chain_update<A: Anchor>(
 
 /// This performs a full scan to get an update for the [`TxGraph`] and
 /// [`KeychainTxOutIndex`](bdk_chain::keychain::KeychainTxOutIndex).
-#[doc(hidden)]
-pub async fn full_scan_for_index_and_graph<K: Ord + Clone + Send>(
+async fn full_scan_for_index_and_graph<K: Ord + Clone + Send>(
     client: &esplora_client::AsyncClient,
     keychain_spks: BTreeMap<
         K,
@@ -339,8 +336,7 @@ pub async fn full_scan_for_index_and_graph<K: Ord + Clone + Send>(
     Ok((graph, last_active_indexes))
 }
 
-#[doc(hidden)]
-pub async fn sync_for_index_and_graph(
+async fn sync_for_index_and_graph(
     client: &esplora_client::AsyncClient,
     misc_spks: impl IntoIterator<IntoIter = impl Iterator<Item = ScriptBuf> + Send> + Send,
     txids: impl IntoIterator<IntoIter = impl Iterator<Item = Txid> + Send> + Send,
@@ -414,3 +410,184 @@ pub async fn sync_for_index_and_graph(
 
     Ok(graph)
 }
+
+#[cfg(test)]
+mod test {
+    use std::{collections::BTreeSet, time::Duration};
+
+    use bdk_chain::{
+        bitcoin::{hashes::Hash, Txid},
+        local_chain::LocalChain,
+        BlockId,
+    };
+    use bdk_testenv::TestEnv;
+    use electrsd::bitcoind::bitcoincore_rpc::RpcApi;
+    use esplora_client::Builder;
+
+    use crate::async_ext::{finalize_chain_update, init_chain_update};
+
+    macro_rules! h {
+        ($index:literal) => {{
+            bdk_chain::bitcoin::hashes::Hash::hash($index.as_bytes())
+        }};
+    }
+
+    /// Ensure that update does not remove heights (from original), and all anchor heights are included.
+    #[tokio::test]
+    pub async fn test_finalize_chain_update() -> anyhow::Result<()> {
+        struct TestCase<'a> {
+            name: &'a str,
+            /// Initial blockchain height to start the env with.
+            initial_env_height: u32,
+            /// Initial checkpoint heights to start with.
+            initial_cps: &'a [u32],
+            /// The final blockchain height of the env.
+            final_env_height: u32,
+            /// The anchors to test with: `(height, txid)`. Only the height is provided as we can fetch
+            /// the blockhash from the env.
+            anchors: &'a [(u32, Txid)],
+        }
+
+        let test_cases = [
+            TestCase {
+                name: "chain_extends",
+                initial_env_height: 60,
+                initial_cps: &[59, 60],
+                final_env_height: 90,
+                anchors: &[],
+            },
+            TestCase {
+                name: "introduce_older_heights",
+                initial_env_height: 50,
+                initial_cps: &[10, 15],
+                final_env_height: 50,
+                anchors: &[(11, h!("A")), (14, h!("B"))],
+            },
+            TestCase {
+                name: "introduce_older_heights_after_chain_extends",
+                initial_env_height: 50,
+                initial_cps: &[10, 15],
+                final_env_height: 100,
+                anchors: &[(11, h!("A")), (14, h!("B"))],
+            },
+        ];
+
+        for (i, t) in test_cases.into_iter().enumerate() {
+            println!("[{}] running test case: {}", i, t.name);
+
+            let env = TestEnv::new()?;
+            let base_url = format!("http://{}", &env.electrsd.esplora_url.clone().unwrap());
+            let client = Builder::new(base_url.as_str()).build_async()?;
+
+            // set env to `initial_env_height`
+            if let Some(to_mine) = t
+                .initial_env_height
+                .checked_sub(env.make_checkpoint_tip().height())
+            {
+                env.mine_blocks(to_mine as _, None)?;
+            }
+            while client.get_height().await? < t.initial_env_height {
+                std::thread::sleep(Duration::from_millis(10));
+            }
+
+            // craft initial `local_chain`
+            let local_chain = {
+                let (mut chain, _) = LocalChain::from_genesis_hash(env.genesis_hash()?);
+                let chain_tip = chain.tip();
+                let update_blocks = init_chain_update(&client, &chain_tip).await?;
+                let update_anchors = t
+                    .initial_cps
+                    .iter()
+                    .map(|&height| -> anyhow::Result<_> {
+                        Ok((
+                            BlockId {
+                                height,
+                                hash: env.bitcoind.client.get_block_hash(height as _)?,
+                            },
+                            Txid::all_zeros(),
+                        ))
+                    })
+                    .collect::<anyhow::Result<BTreeSet<_>>>()?;
+                let chain_update =
+                    finalize_chain_update(&client, &chain_tip, &update_anchors, update_blocks)
+                        .await?;
+                chain.apply_update(chain_update)?;
+                chain
+            };
+            println!("local chain height: {}", local_chain.tip().height());
+
+            // extend env chain
+            if let Some(to_mine) = t
+                .final_env_height
+                .checked_sub(env.make_checkpoint_tip().height())
+            {
+                env.mine_blocks(to_mine as _, None)?;
+            }
+            while client.get_height().await? < t.final_env_height {
+                std::thread::sleep(Duration::from_millis(10));
+            }
+
+            // craft update
+            let update = {
+                let local_tip = local_chain.tip();
+                let update_blocks = init_chain_update(&client, &local_tip).await?;
+                let update_anchors = t
+                    .anchors
+                    .iter()
+                    .map(|&(height, txid)| -> anyhow::Result<_> {
+                        Ok((
+                            BlockId {
+                                height,
+                                hash: env.bitcoind.client.get_block_hash(height as _)?,
+                            },
+                            txid,
+                        ))
+                    })
+                    .collect::<anyhow::Result<_>>()?;
+                finalize_chain_update(&client, &local_tip, &update_anchors, update_blocks).await?
+            };
+
+            // apply update
+            let mut updated_local_chain = local_chain.clone();
+            updated_local_chain.apply_update(update)?;
+            println!(
+                "updated local chain height: {}",
+                updated_local_chain.tip().height()
+            );
+
+            assert!(
+                {
+                    let initial_heights = local_chain
+                        .iter_checkpoints()
+                        .map(|cp| cp.height())
+                        .collect::<BTreeSet<_>>();
+                    let updated_heights = updated_local_chain
+                        .iter_checkpoints()
+                        .map(|cp| cp.height())
+                        .collect::<BTreeSet<_>>();
+                    updated_heights.is_superset(&initial_heights)
+                },
+                "heights from the initial chain must all be in the updated chain",
+            );
+
+            assert!(
+                {
+                    let exp_anchor_heights = t
+                        .anchors
+                        .iter()
+                        .map(|(h, _)| *h)
+                        .chain(t.initial_cps.iter().copied())
+                        .collect::<BTreeSet<_>>();
+                    let anchor_heights = updated_local_chain
+                        .iter_checkpoints()
+                        .map(|cp| cp.height())
+                        .collect::<BTreeSet<_>>();
+                    anchor_heights.is_superset(&exp_anchor_heights)
+                },
+                "anchor heights must all be in updated chain",
+            );
+        }
+
+        Ok(())
+    }
+}