fix(chain)!: In apply_changeset{_to checkpoint} propagate the error from extend

Now that `apply_changeset` can fail due to inconsistent data in
addition to `MissingGenesisError`, we need to propagate the error
rather than expect that the chain update can always succeed.

Added private struct `ApplyChangeSetError`. This error is returned
by `apply_changeset_to_checkpoint`.

BREAKING:

- Changed `LocalChain::from_blocks` to return
  `Result<Self, Option<CheckPoint<D>>`
- Changed `LocalChain::from_changeset` to return
  `Result<Option<Self>, CannotConnectError)`
- Changed `LocalChain::apply_changeset` to return
  `Result<(), CannotConnectError>`

Author: ValuedMammal

crates/chain/src/local_chain.rs

@@ -13,11 +13,22 @@ pub use bdk_core::{CheckPoint, CheckPointIter};
 use bitcoin::block::Header;
 use bitcoin::BlockHash;
 
+/// Error for `apply_changeset_to_checkpoint`.
+#[derive(Debug)]
+struct ApplyChangeSetError<D> {
+    cp: Option<CheckPoint<D>>,
+}
+
 /// Apply `changeset` to the checkpoint.
+///
+/// # Errors
+///
+/// - If constructing the new chain from the provided `changeset` fails, then a
+///   [`ApplyChangeSetError`] is returned.
 fn apply_changeset_to_checkpoint<D>(
     mut init_cp: CheckPoint<D>,
     changeset: &ChangeSet<D>,
-) -> Result<CheckPoint<D>, MissingGenesisError>
+) -> Result<CheckPoint<D>, ApplyChangeSetError<D>>
 where
     D: ToBlockHash + fmt::Debug + Clone,
 {
@@ -50,8 +61,11 @@ where
         let new_tip = match base {
             Some(base) => base
                 .extend(extension)
-                .expect("extension is strictly greater than base"),
-            None => LocalChain::from_blocks(extension)?.tip(),
+                .map_err(Option::Some)
+                .map_err(|cp| ApplyChangeSetError { cp })?,
+            None => LocalChain::from_blocks(extension)
+                .map_err(|cp| ApplyChangeSetError { cp })?
+                .tip(),
         };
         init_cp = new_tip;
     }
@@ -255,30 +269,36 @@ where
     ///
     /// The [`BTreeMap`] enforces the height order. However, the caller must ensure the blocks are
     /// all of the same chain.
-    pub fn from_blocks(blocks: BTreeMap<u32, D>) -> Result<Self, MissingGenesisError> {
-        let genesis_hash = blocks
-            .get(&0)
-            .map(ToBlockHash::to_blockhash)
-            .ok_or(MissingGenesisError)?;
+    ///
+    /// Returns `Err(None)` if `blocks` is empty or doesn't contain a value at height `0` a.k.a
+    /// the "genesis" block.
+    /// If `blocks` contains inconsistent or invalid data, then returns `Err(Some(..))`
+    /// containing the last valid checkpoint.
+    pub fn from_blocks(blocks: BTreeMap<u32, D>) -> Result<Self, Option<CheckPoint<D>>> {
+        let genesis_hash = blocks.get(&0).map(ToBlockHash::to_blockhash).ok_or(None)?;
+        let tip = CheckPoint::from_blocks(blocks)?;
 
-        Ok(Self {
-            genesis_hash,
-            tip: CheckPoint::from_blocks(blocks).expect("blocks must be in order"),
-        })
+        Ok(Self { genesis_hash, tip })
     }
 
     /// Construct a [`LocalChain`] from an initial `changeset`.
-    pub fn from_changeset(changeset: ChangeSet<D>) -> Result<Self, MissingGenesisError> {
+    ///
+    /// # Returns
+    ///
+    /// - `Ok(None)` if `changeset` doesn't contain a value at height 0, a.k.a "genesis".
+    /// - `CannotConnectError` if the `changeset` can't be applied.
+    /// - Otherwise returns a new [`LocalChain`] with the changeset applied
+    pub fn from_changeset(changeset: ChangeSet<D>) -> Result<Option<Self>, CannotConnectError> {
         let genesis_entry = changeset.blocks.get(&0).cloned().flatten();
         let genesis_data = match genesis_entry {
             Some(data) => data,
-            None => return Err(MissingGenesisError),
+            None => return Ok(None),
         };
 
         let (mut chain, _) = Self::from_genesis(genesis_data);
         chain.apply_changeset(&changeset)?;
         debug_assert!(chain._check_changeset_is_applied(&changeset));
-        Ok(chain)
+        Ok(Some(chain))
     }
 
     /// Construct a [`LocalChain`] from a given `checkpoint` tip.
@@ -317,9 +337,12 @@ where
     }
 
     /// Apply the given `changeset`.
-    pub fn apply_changeset(&mut self, changeset: &ChangeSet<D>) -> Result<(), MissingGenesisError> {
+    pub fn apply_changeset(&mut self, changeset: &ChangeSet<D>) -> Result<(), CannotConnectError> {
         let old_tip = self.tip.clone();
-        let new_tip = apply_changeset_to_checkpoint(old_tip, changeset)?;
+        let new_tip =
+            apply_changeset_to_checkpoint(old_tip, changeset).map_err(|e| CannotConnectError {
+                try_include_height: e.cp.as_ref().map_or(0, CheckPoint::height),
+            })?;
         self.tip = new_tip;
         debug_assert!(self._check_changeset_is_applied(changeset));
         Ok(())
@@ -702,9 +725,9 @@ where
         }
 
         // Apply changeset to tip.
-        let new_tip = apply_changeset_to_checkpoint(self.tip(), &changeset).map_err(|_| {
+        let new_tip = apply_changeset_to_checkpoint(self.tip(), &changeset).map_err(|e| {
             CannotConnectError {
-                try_include_height: 0,
+                try_include_height: e.cp.as_ref().map_or(0, CheckPoint::height),
             }
         })?;