feat(chain)!: make CheckPoint data field optional

Author: LagginTimes

crates/chain/src/local_chain.rs

@@ -27,7 +27,9 @@ where
 
         for cp in init_cp.iter() {
             if cp.height() >= start_height {
-                extension.insert(cp.height(), cp.data());
+                if let Some(data) = cp.data() {
+                    extension.insert(cp.height(), data);
+                }
             } else {
                 base = Some(cp);
                 break;
@@ -45,12 +47,19 @@ where
             };
         }
 
-        let new_tip = match base {
+        let mut new_tip = match base {
             Some(base) => base
                 .extend(extension)
                 .expect("extension is strictly greater than base"),
             None => LocalChain::from_blocks(extension)?.tip(),
         };
+
+        if new_tip.data_ref().is_none() {
+            new_tip = new_tip
+                .find_data(new_tip.height())
+                .expect("genesis checkpoint should have data");
+        }
+
         init_cp = new_tip;
     }
 
@@ -322,11 +331,7 @@ where
     /// recover the current chain.
     pub fn initial_changeset(&self) -> ChangeSet<D> {
         ChangeSet {
-            blocks: self
-                .tip
-                .iter()
-                .map(|cp| (cp.height(), Some(cp.data())))
-                .collect(),
+            blocks: self.tip.iter().map(|cp| (cp.height(), cp.data())).collect(),
         }
     }
 
@@ -349,6 +354,20 @@ where
                     update_hash: Some(data.to_blockhash()),
                 });
             }
+
+            // If this `CheckPoint` is an empty placeholder, append the `data` to it.
+            if original_cp.data_ref().is_none() {
+                let mut changeset = ChangeSet::<D>::default();
+                changeset.blocks.insert(height, Some(data));
+                self.apply_changeset(&changeset)
+                    .map_err(|_| AlterCheckPointError {
+                        height: 0,
+                        original_hash: self.genesis_hash(),
+                        update_hash: None,
+                    })?;
+                return Ok(changeset);
+            }
+
             return Ok(ChangeSet::default());
         }
 
@@ -634,7 +653,9 @@ where
         match (curr_orig.as_ref(), curr_update.as_ref()) {
             // Update block that doesn't exist in the original chain
             (o, Some(u)) if Some(u.height()) > o.map(|o| o.height()) => {
-                changeset.blocks.insert(u.height(), Some(u.data()));
+                if let Some(data) = u.data() {
+                    changeset.blocks.insert(u.height(), Some(data));
+                }
                 prev_update = curr_update.take();
             }
             // Original block that isn't in the update
@@ -685,7 +706,7 @@ where
                 } else {
                     // We have an invalidation height so we set the height to the updated hash and
                     // also purge all the original chain block hashes above this block.
-                    changeset.blocks.insert(u.height(), Some(u.data()));
+                    changeset.blocks.insert(u.height(), u.data());
                     for invalidated_height in potentially_invalidated_heights.drain(..) {
                         changeset.blocks.insert(invalidated_height, None);
                     }

crates/core/src/checkpoint.rs

@@ -24,8 +24,8 @@ impl<D> Clone for CheckPoint<D> {
 struct CPInner<D> {
     /// Block id
     block_id: BlockId,
-    /// Data.
-    data: D,
+    /// Data (if any).
+    data: Option<D>,
     /// Previous checkpoint (if any).
     prev: Option<Arc<CPInner<D>>>,
 }
@@ -68,6 +68,11 @@ impl<D> Drop for CPInner<D> {
 pub trait ToBlockHash {
     /// Returns the [`BlockHash`] for the associated [`CheckPoint`] `data` type.
     fn to_blockhash(&self) -> BlockHash;
+
+    /// Returns `None` if the type has no knowledge of the previous [`BlockHash`].
+    fn prev_blockhash(&self) -> Option<BlockHash> {
+        None
+    }
 }
 
 impl ToBlockHash for BlockHash {
@@ -80,6 +85,10 @@ impl ToBlockHash for Header {
     fn to_blockhash(&self) -> BlockHash {
         self.block_hash()
     }
+
+    fn prev_blockhash(&self) -> Option<BlockHash> {
+        Some(self.prev_blockhash)
+    }
 }
 
 impl<D> PartialEq for CheckPoint<D> {
@@ -92,13 +101,13 @@ impl<D> PartialEq for CheckPoint<D> {
 
 // Methods for any `D`
 impl<D> CheckPoint<D> {
-    /// Get a reference of the `data` of the checkpoint.
-    pub fn data_ref(&self) -> &D {
-        &self.0.data
+    /// Get a reference of the `data` of the checkpoint if it exists.
+    pub fn data_ref(&self) -> Option<&D> {
+        self.0.data.as_ref()
     }
 
-    /// Get the `data` of a the checkpoint.
-    pub fn data(&self) -> D
+    /// Get the `data` of the checkpoint if it exists.
+    pub fn data(&self) -> Option<D>
     where
         D: Clone,
     {
@@ -170,6 +179,17 @@ impl<D> CheckPoint<D> {
         self.range(..=height).next()
     }
 
+    /// Finds the checkpoint with `data` at `height` if one exists, otherwise the neareast
+    /// checkpoint with `data` at a lower height.
+    ///
+    /// This is equivalent to taking the “floor” of "height" over this checkpoint chain, filtering
+    /// out any placeholder entries that do not contain any `data`.
+    ///
+    /// Returns `None` if no checkpoint with `data` exists at or below the given height.
+    pub fn find_data(&self, height: u32) -> Option<Self> {
+        self.range(..=height).find(|cp| cp.data_ref().is_some())
+    }
+
     /// Returns the checkpoint located a number of heights below this one.
     ///
     /// This is a convenience wrapper for [`CheckPoint::floor_at`], subtracting `to_subtract` from
@@ -198,13 +218,30 @@ where
     /// Construct a new base [`CheckPoint`] from given `height` and `data` at the front of a linked
     /// list.
     pub fn new(height: u32, data: D) -> Self {
+        // If `data` has a `prev_blockhash`, create a placeholder checkpoint one height below.
+        let prev = if height > 0 {
+            match data.prev_blockhash() {
+                Some(prev_blockhash) => Some(Arc::new(CPInner {
+                    block_id: BlockId {
+                        height: height - 1,
+                        hash: prev_blockhash,
+                    },
+                    data: None,
+                    prev: None,
+                })),
+                None => None,
+            }
+        } else {
+            None
+        };
+
         Self(Arc::new(CPInner {
             block_id: BlockId {
                 height,
                 hash: data.to_blockhash(),
             },
-            data,
-            prev: None,
+            data: Some(data),
+            prev,
         }))
     }
 
@@ -251,21 +288,30 @@ where
         let mut tail = vec![];
         let base = loop {
             if cp.height() == height {
-                if cp.hash() == data.to_blockhash() {
-                    return self;
+                let same_hash = cp.hash() == data.to_blockhash();
+                if same_hash {
+                    if cp.data().is_some() {
+                        return self;
+                    } else {
+                        // If `CheckPoint` is a placeholder, return previous `CheckPoint`.
+                        break cp.prev().expect("can't be called on genesis block");
+                    }
+                } else {
+                    assert_ne!(cp.height(), 0, "cannot replace genesis block");
+                    // If we have a conflict we just return the inserted data because the tail is by
+                    // implication invalid.
+                    tail = vec![];
+                    break cp.prev().expect("can't be called on genesis block");
                 }
-                assert_ne!(cp.height(), 0, "cannot replace genesis block");
-                // If we have a conflict we just return the inserted data because the tail is by
-                // implication invalid.
-                tail = vec![];
-                break cp.prev().expect("can't be called on genesis block");
             }
 
             if cp.height() < height {
                 break cp;
             }
 
-            tail.push((cp.height(), cp.data()));
+            if let Some(d) = cp.data() {
+                tail.push((cp.height(), d));
+            }
             cp = cp.prev().expect("will break before genesis block");
         };
 
@@ -277,15 +323,35 @@ where
     ///
     /// Returns an `Err(self)` if the block you are pushing on is not at a greater height that the
     /// one you are pushing on to.
+    ///
+    /// If `height` is non-contiguous and `data.prev_blockhash()` is available, a placeholder is
+    /// created at height - 1.
     pub fn push(self, height: u32, data: D) -> Result<Self, Self> {
         if self.height() < height {
+            let mut current_cp = self.0.clone();
+
+            // If non-contiguous and `prev_blockhash` exists, insert a placeholder at height - 1.
+            if height > self.height() + 1 {
+                if let Some(prev_hash) = data.prev_blockhash() {
+                    let empty = Arc::new(CPInner {
+                        block_id: BlockId {
+                            height: height - 1,
+                            hash: prev_hash,
+                        },
+                        data: None,
+                        prev: Some(current_cp),
+                    });
+                    current_cp = empty;
+                }
+            }
+
             Ok(Self(Arc::new(CPInner {
                 block_id: BlockId {
                     height,
                     hash: data.to_blockhash(),
                 },
-                data,
-                prev: Some(self.0),
+                data: Some(data),
+                prev: Some(current_cp),
             })))
         } else {
             Err(self)