Merge #1601: fix(core): calling CheckPoint::insert with existing block must succeed

3ae9ecb test: fix off-by-one in `checkpoint_insert_existing` (valued mammal)
e6aeaea doc(core): document panic for `CheckPoint::insert` (valued mammal)
2970b83 fix(core): calling `CheckPoint::insert` with existing block must succeed (志宇)

Pull request description:

  ### Description

  Previously, we were panicking when the caller tried to insert a block at height 0. However, this should succeed if the block hash does not change.

  ### Notes to the reviewers

  For context:

  * lightningdevkit/ldk-node#358
  * https://discord.com/channels/753336465005608961/978744259693916230/1283050849429356629

  ### Changelog notice

  * Fix `CheckPoint::insert` to not panic when inserting existing genesis block (same block height and hash).

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

  #### Bugfixes:

  ~~* [ ] This pull request breaks the existing API~~
  * [x] I've added tests to reproduce the issue which are now passing

ACKs for top commit:
  ValuedMammal:
    Self ACK 3ae9ecb
  notmandatory:
    ACK 3ae9ecb

Tree-SHA512: 638d8aacac59ad18b5ee369d08f39bb12cc37fa9b3f936404b60dbf44938ef850ca341d00566840b5a77909d31c9291ab56299d986d832005ca96cd91a0b0e55

Author: notmandatory

crates/core/src/checkpoint.rs

@@ -171,17 +171,20 @@ impl CheckPoint {
     /// it. If the height already existed and has a conflicting block hash then it will be purged
     /// along with all block following it. The returned chain will have a tip of the `block_id`
     /// passed in. Of course, if the `block_id` was already present then this just returns `self`.
+    ///
+    /// # Panics
+    ///
+    /// This panics if called with a genesis block that differs from that of `self`.
     #[must_use]
     pub fn insert(self, block_id: BlockId) -> Self {
-        assert_ne!(block_id.height, 0, "cannot insert the genesis block");
-
         let mut cp = self.clone();
         let mut tail = vec![];
         let base = loop {
             if cp.height() == block_id.height {
                 if cp.hash() == block_id.hash {
                     return self;
                 }
+                assert_ne!(cp.height(), 0, "cannot replace genesis block");
                 // if we have a conflict we just return the inserted block because the tail is by
                 // implication invalid.
                 tail = vec![];

crates/core/tests/common.rs

@@ -0,0 +1,9 @@
+#[allow(unused_macros)]
+macro_rules! block_id {
+    ($height:expr, $hash:literal) => {{
+        bdk_chain::BlockId {
+            height: $height,
+            hash: bitcoin::hashes::Hash::hash($hash.as_bytes()),
+        }
+    }};
+}

crates/core/tests/test_checkpoint.rs

@@ -0,0 +1,36 @@
+#[macro_use]
+mod common;
+
+use bdk_core::CheckPoint;
+
+/// Inserting a block that already exists in the checkpoint chain must always succeed.
+#[test]
+fn checkpoint_insert_existing() {
+    let blocks = &[
+        block_id!(0, "genesis"),
+        block_id!(1, "A"),
+        block_id!(2, "B"),
+        block_id!(3, "C"),
+    ];
+
+    // Index `i` allows us to test with chains of different length.
+    // Index `j` allows us to test inserting different block heights.
+    for i in 0..blocks.len() {
+        let cp_chain = CheckPoint::from_block_ids(blocks[..=i].iter().copied())
+            .expect("must construct valid chain");
+
+        for j in 0..=i {
+            let block_to_insert = cp_chain
+                .get(j as u32)
+                .expect("cp of height must exist")
+                .block_id();
+            let new_cp_chain = cp_chain.clone().insert(block_to_insert);
+
+            assert_eq!(
+                new_cp_chain, cp_chain,
+                "must not divert from original chain"
+            );
+            assert!(new_cp_chain.eq_ptr(&cp_chain), "pointers must still match");
+        }
+    }
+}