Merge #1582: refactor!: Implement generics for CheckPoint, LocalChain, and spk_client types

8bc2391 docs(chain): update docs for `CheckPoint` and `SyncRequest` (Wei Chen)
7cf4e5b test(chain): Add test for inserting `Header` into `LocalChain` (Wei Chen)
93a382d refactor!: make `CheckPoint`, `LocalChain`, and `SpkClient` take a generic (Wei Chen)

Pull request description:

  Implements #1937.

  ### Description

  This PR is a step towards header checkpointing for `bdk_electrum`. The goal is to be able to store whole headers in `CheckPoint` so they do not have to be re-downloaded. Storing headers this way would be a prerequisite for caching of merkle proofs and for median time passed.

  ### Notes to the reviewers

  ### Changelog notice

  * `CheckPoint` takes in a generic.
  * `LocalChain` and `ChangeSet` take in generics.
  * `spk_client` types can take in generics.

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

ACKs for top commit:
  evanlinjin:
    ACK 8bc2391

Tree-SHA512: 3c11b559a8d8f7cdf0418dbece7821e3304acd6b6e96b3e1827cdfc30b4a268c9d3511a9bc3d11408198ac93a96a84e449b879f562f368dc44a945671ef98e39

Author: evanlinjin

crates/bitcoind_rpc/examples/filter_iter.rs

@@ -7,7 +7,7 @@ use bdk_chain::bitcoin::{constants::genesis_block, secp256k1::Secp256k1, Network
 use bdk_chain::indexer::keychain_txout::KeychainTxOutIndex;
 use bdk_chain::local_chain::LocalChain;
 use bdk_chain::miniscript::Descriptor;
-use bdk_chain::{BlockId, ConfirmationBlockTime, IndexedTxGraph, SpkIterator};
+use bdk_chain::{ConfirmationBlockTime, IndexedTxGraph, SpkIterator};
 use bdk_testenv::anyhow;
 
 // This example shows how BDK chain and tx-graph structures are updated using compact
@@ -29,7 +29,7 @@ fn main() -> anyhow::Result<()> {
     let secp = Secp256k1::new();
     let (descriptor, _) = Descriptor::parse_descriptor(&secp, EXTERNAL)?;
     let (change_descriptor, _) = Descriptor::parse_descriptor(&secp, INTERNAL)?;
-    let (mut chain, _) = LocalChain::from_genesis_hash(genesis_block(NETWORK).block_hash());
+    let (mut chain, _) = LocalChain::from_genesis(genesis_block(NETWORK).block_hash());
 
     let mut graph = IndexedTxGraph::<ConfirmationBlockTime, KeychainTxOutIndex<&str>>::new({
         let mut index = KeychainTxOutIndex::default();
@@ -39,11 +39,7 @@ fn main() -> anyhow::Result<()> {
     });
 
     // Assume a minimum birthday height
-    let block = BlockId {
-        height: START_HEIGHT,
-        hash: START_HASH.parse()?,
-    };
-    let _ = chain.insert_block(block)?;
+    let _ = chain.insert_block(START_HEIGHT, START_HASH.parse()?)?;
 
     // Configure RPC client
     let url = std::env::var("RPC_URL").context("must set RPC_URL")?;

crates/bitcoind_rpc/src/bip158.rs

@@ -7,7 +7,8 @@
 //! [1]: https://github.com/bitcoin/bips/blob/master/bip-0158.mediawiki
 
 use bdk_core::bitcoin;
-use bdk_core::{BlockId, CheckPoint};
+use bdk_core::CheckPoint;
+use bitcoin::BlockHash;
 use bitcoin::{bip158::BlockFilter, Block, ScriptBuf};
 use bitcoincore_rpc;
 use bitcoincore_rpc::{json::GetBlockHeaderResult, RpcApi};
@@ -34,7 +35,7 @@ pub struct FilterIter<'a> {
     /// SPK inventory
     spks: Vec<ScriptBuf>,
     /// checkpoint
-    cp: CheckPoint,
+    cp: CheckPoint<BlockHash>,
     /// Header info, contains the prev and next hashes for each header.
     header: Option<GetBlockHeaderResult>,
 }
@@ -125,10 +126,7 @@ impl Iterator for FilterIter<'_> {
             next_hash = next_header.hash;
             let next_height: u32 = next_header.height.try_into()?;
 
-            cp = cp.insert(BlockId {
-                height: next_height,
-                hash: next_hash,
-            });
+            cp = cp.insert(next_height, next_hash);
 
             let mut block = None;
             let filter =

crates/bitcoind_rpc/src/lib.rs

@@ -36,7 +36,7 @@ pub struct Emitter<C> {
 
     /// The checkpoint of the last-emitted block that is in the best chain. If it is later found
     /// that the block is no longer in the best chain, it will be popped off from here.
-    last_cp: CheckPoint,
+    last_cp: CheckPoint<BlockHash>,
 
     /// The block result returned from rpc of the last-emitted block. As this result contains the
     /// next block's block hash (which we use to fetch the next block), we set this to `None`
@@ -80,7 +80,7 @@ where
     /// If it is known that the wallet is empty, [`NO_EXPECTED_MEMPOOL_TXS`] can be used.
     pub fn new(
         client: C,
-        last_cp: CheckPoint,
+        last_cp: CheckPoint<BlockHash>,
         start_height: u32,
         expected_mempool_txs: impl IntoIterator<Item = impl Into<Arc<Transaction>>>,
     ) -> Self {
@@ -235,7 +235,7 @@ pub struct BlockEvent<B> {
     ///
     /// This is important as BDK structures require block-to-apply to be connected with another
     /// block in the original chain.
-    pub checkpoint: CheckPoint,
+    pub checkpoint: CheckPoint<BlockHash>,
 }
 
 impl<B> BlockEvent<B> {
@@ -269,7 +269,7 @@ enum PollResponse {
     NoMoreBlocks,
     /// Fetched block is not in the best chain.
     BlockNotInBestChain,
-    AgreementFound(bitcoincore_rpc_json::GetBlockResult, CheckPoint),
+    AgreementFound(bitcoincore_rpc_json::GetBlockResult, CheckPoint<BlockHash>),
     /// Force the genesis checkpoint down the receiver's throat.
     AgreementPointNotFound(BlockHash),
 }
@@ -331,7 +331,7 @@ where
 fn poll<C, V, F>(
     emitter: &mut Emitter<C>,
     get_item: F,
-) -> Result<Option<(CheckPoint, V)>, bitcoincore_rpc::Error>
+) -> Result<Option<(CheckPoint<BlockHash>, V)>, bitcoincore_rpc::Error>
 where
     C: Deref,
     C::Target: RpcApi,
@@ -347,7 +347,7 @@ where
                 let new_cp = emitter
                     .last_cp
                     .clone()
-                    .push(BlockId { height, hash })
+                    .push(height, hash)
                     .expect("must push");
                 emitter.last_cp = new_cp.clone();
                 emitter.last_block = Some(res);
@@ -368,10 +368,7 @@ where
                 continue;
             }
             PollResponse::AgreementPointNotFound(genesis_hash) => {
-                emitter.last_cp = CheckPoint::new(BlockId {
-                    height: 0,
-                    hash: genesis_hash,
-                });
+                emitter.last_cp = CheckPoint::new(0, genesis_hash);
                 emitter.last_block = None;
                 continue;
             }
@@ -411,7 +408,7 @@ mod test {
     #[test]
     fn test_expected_mempool_txids_accumulate_and_remove() -> anyhow::Result<()> {
         let env = TestEnv::new()?;
-        let chain = LocalChain::from_genesis_hash(env.rpc_client().get_block_hash(0)?).0;
+        let chain = LocalChain::from_genesis(env.rpc_client().get_block_hash(0)?).0;
         let chain_tip = chain.tip();
         let mut emitter = Emitter::new(
             env.rpc_client(),

crates/bitcoind_rpc/tests/test_emitter.rs

@@ -21,7 +21,7 @@ use bitcoincore_rpc::RpcApi;
 pub fn test_sync_local_chain() -> anyhow::Result<()> {
     let env = TestEnv::new()?;
     let network_tip = env.rpc_client().get_block_count()?;
-    let (mut local_chain, _) = LocalChain::from_genesis_hash(env.rpc_client().get_block_hash(0)?);
+    let (mut local_chain, _) = LocalChain::from_genesis(env.rpc_client().get_block_hash(0)?);
     let mut emitter = Emitter::new(
         env.rpc_client(),
         local_chain.tip(),
@@ -152,7 +152,7 @@ fn test_into_tx_graph() -> anyhow::Result<()> {
 
     env.mine_blocks(101, None)?;
 
-    let (mut chain, _) = LocalChain::from_genesis_hash(env.rpc_client().get_block_hash(0)?);
+    let (mut chain, _) = LocalChain::from_genesis(env.rpc_client().get_block_hash(0)?);
     let mut indexed_tx_graph = IndexedTxGraph::<BlockId, _>::new({
         let mut index = SpkTxOutIndex::<usize>::default();
         index.insert_spk(0, addr_0.script_pubkey());
@@ -252,10 +252,7 @@ fn ensure_block_emitted_after_reorg_is_at_reorg_height() -> anyhow::Result<()> {
     let env = TestEnv::new()?;
     let mut emitter = Emitter::new(
         env.rpc_client(),
-        CheckPoint::new(BlockId {
-            height: 0,
-            hash: env.rpc_client().get_block_hash(0)?,
-        }),
+        CheckPoint::new(0, env.rpc_client().get_block_hash(0)?),
         EMITTER_START_HEIGHT as _,
         NO_EXPECTED_MEMPOOL_TXS,
     );
@@ -286,7 +283,7 @@ fn process_block(
     block: Block,
     block_height: u32,
 ) -> anyhow::Result<()> {
-    recv_chain.apply_update(CheckPoint::from_header(&block.header, block_height))?;
+    recv_chain.apply_header(&block.header, block_height)?;
     let _ = recv_graph.apply_block(block, block_height);
     Ok(())
 }
@@ -334,10 +331,7 @@ fn tx_can_become_unconfirmed_after_reorg() -> anyhow::Result<()> {
     let env = TestEnv::new()?;
     let mut emitter = Emitter::new(
         env.rpc_client(),
-        CheckPoint::new(BlockId {
-            height: 0,
-            hash: env.rpc_client().get_block_hash(0)?,
-        }),
+        CheckPoint::new(0, env.rpc_client().get_block_hash(0)?),
         0,
         NO_EXPECTED_MEMPOOL_TXS,
     );
@@ -351,7 +345,7 @@ fn tx_can_become_unconfirmed_after_reorg() -> anyhow::Result<()> {
     let addr_to_track = Address::from_script(&spk_to_track, Network::Regtest)?;
 
     // setup receiver
-    let (mut recv_chain, _) = LocalChain::from_genesis_hash(env.rpc_client().get_block_hash(0)?);
+    let (mut recv_chain, _) = LocalChain::from_genesis(env.rpc_client().get_block_hash(0)?);
     let mut recv_graph = IndexedTxGraph::<BlockId, _>::new({
         let mut recv_index = SpkTxOutIndex::default();
         recv_index.insert_spk((), spk_to_track.clone());
@@ -425,10 +419,7 @@ fn mempool_avoids_re_emission() -> anyhow::Result<()> {
     let env = TestEnv::new()?;
     let mut emitter = Emitter::new(
         env.rpc_client(),
-        CheckPoint::new(BlockId {
-            height: 0,
-            hash: env.rpc_client().get_block_hash(0)?,
-        }),
+        CheckPoint::new(0, env.rpc_client().get_block_hash(0)?),
         0,
         NO_EXPECTED_MEMPOOL_TXS,
     );
@@ -498,10 +489,7 @@ fn no_agreement_point() -> anyhow::Result<()> {
     // start height is 99
     let mut emitter = Emitter::new(
         env.rpc_client(),
-        CheckPoint::new(BlockId {
-            height: 0,
-            hash: env.rpc_client().get_block_hash(0)?,
-        }),
+        CheckPoint::new(0, env.rpc_client().get_block_hash(0)?),
         (PREMINE_COUNT - 2) as u32,
         NO_EXPECTED_MEMPOOL_TXS,
     );
@@ -573,7 +561,7 @@ fn test_expect_tx_evicted() -> anyhow::Result<()> {
         .0;
     let spk = desc.at_derivation_index(0)?.script_pubkey();
 
-    let mut chain = LocalChain::from_genesis_hash(genesis_block(Network::Regtest).block_hash()).0;
+    let mut chain = LocalChain::from_genesis(genesis_block(Network::Regtest).block_hash()).0;
     let chain_tip = chain.tip().block_id();
 
     let mut index = SpkTxOutIndex::default();
@@ -594,7 +582,7 @@ fn test_expect_tx_evicted() -> anyhow::Result<()> {
     let mut emitter = Emitter::new(env.rpc_client(), chain.tip(), 1, core::iter::once(tx_1));
     while let Some(emission) = emitter.next_block()? {
         let height = emission.block_height();
-        chain.apply_update(CheckPoint::from_header(&emission.block.header, height))?;
+        chain.apply_header(&emission.block.header, height)?;
     }
 
     let changeset = graph.batch_insert_unconfirmed(emitter.mempool()?.update);
@@ -670,10 +658,7 @@ fn detect_new_mempool_txs() -> anyhow::Result<()> {
 
     let mut emitter = Emitter::new(
         env.rpc_client(),
-        CheckPoint::new(BlockId {
-            height: 0,
-            hash: env.rpc_client().get_block_hash(0)?,
-        }),
+        CheckPoint::new(0, env.rpc_client().get_block_hash(0)?),
         0,
         NO_EXPECTED_MEMPOOL_TXS,
     );

crates/bitcoind_rpc/tests/test_filter_iter.rs

@@ -1,5 +1,5 @@
 use bdk_bitcoind_rpc::bip158::{Error, FilterIter};
-use bdk_core::{BlockId, CheckPoint};
+use bdk_core::CheckPoint;
 use bdk_testenv::{anyhow, bitcoind, TestEnv};
 use bitcoin::{Address, Amount, Network, ScriptBuf};
 use bitcoincore_rpc::RpcApi;
@@ -36,10 +36,7 @@ fn filter_iter_matches_blocks() -> anyhow::Result<()> {
     let _ = env.mine_blocks(1, None);
 
     let genesis_hash = env.genesis_hash()?;
-    let cp = CheckPoint::new(BlockId {
-        height: 0,
-        hash: genesis_hash,
-    });
+    let cp = CheckPoint::new(0, genesis_hash);
 
     let iter = FilterIter::new(&env.bitcoind.client, cp, [addr.script_pubkey()]);
 
@@ -62,11 +59,7 @@ fn filter_iter_error_wrong_network() -> anyhow::Result<()> {
     let _ = env.mine_blocks(10, None)?;
 
     // Try to initialize FilterIter with a CP on the wrong network
-    let block_id = BlockId {
-        height: 0,
-        hash: bitcoin::hashes::Hash::hash(b"wrong-hash"),
-    };
-    let cp = CheckPoint::new(block_id);
+    let cp = CheckPoint::new(0, bitcoin::hashes::Hash::hash(b"wrong-hash"));
     let mut iter = FilterIter::new(&env.bitcoind.client, cp, [ScriptBuf::new()]);
     assert!(matches!(iter.next(), Some(Err(Error::ReorgDepthExceeded))));
 
@@ -85,10 +78,7 @@ fn filter_iter_detects_reorgs() -> anyhow::Result<()> {
     }
 
     let genesis_hash = env.genesis_hash()?;
-    let cp = CheckPoint::new(BlockId {
-        height: 0,
-        hash: genesis_hash,
-    });
+    let cp = CheckPoint::new(0, genesis_hash);
 
     let spk = ScriptBuf::from_hex("0014446906a6560d8ad760db3156706e72e171f3a2aa")?;
     let mut iter = FilterIter::new(&env.bitcoind.client, cp, [spk]);

crates/chain/benches/canonicalization.rs

@@ -76,8 +76,12 @@ fn add_ancestor_tx(graph: &mut KeychainTxGraph, block_id: BlockId, locktime: u32
 
 fn setup<F: Fn(&mut KeychainTxGraph, &LocalChain)>(f: F) -> (KeychainTxGraph, LocalChain) {
     const DESC: &str = "tr([ab28dc00/86h/1h/0h]tpubDCdDtzAMZZrkwKBxwNcGCqe4FRydeD9rfMisoi7qLdraG79YohRfPW4YgdKQhpgASdvh612xXNY5xYzoqnyCgPbkpK4LSVcH5Xv4cK7johH/0/*)";
-    let cp = CheckPoint::from_block_ids([genesis_block_id(), tip_block_id()])
-        .expect("blocks must be chronological");
+    let cp = CheckPoint::from_blocks(
+        [genesis_block_id(), tip_block_id()]
+            .into_iter()
+            .map(|block_id| (block_id.height, block_id.hash)),
+    )
+    .expect("blocks must be chronological");
     let chain = LocalChain::from_tip(cp).unwrap();
 
     let (desc, _) =

crates/chain/benches/indexer.rs

@@ -50,7 +50,12 @@ fn setup<F: Fn(&mut KeychainTxGraph, &LocalChain)>(f: F) -> (KeychainTxGraph, Lo
         .unwrap()
         .0;
 
-    let cp = CheckPoint::from_block_ids([genesis_block_id(), tip_block_id()]).unwrap();
+    let cp = CheckPoint::from_blocks(
+        [genesis_block_id(), tip_block_id()]
+            .into_iter()
+            .map(|block_id| (block_id.height, block_id.hash)),
+    )
+    .unwrap();
     let chain = LocalChain::from_tip(cp).unwrap();
 
     let mut index = KeychainTxOutIndex::new(LOOKAHEAD, USE_SPK_CACHE);