feat(supervisor/storage): derivation schema

crates/supervisor/storage/Cargo.toml

@@ -18,6 +18,7 @@ alloy-primitives = { workspace = true, features = ["map", "rlp", "serde", "rand"
 
 # Misc
 serde = { workspace = true, features = ["derive"] }
+derive_more.workspace = true
 bytes = { workspace = true }
 modular-bitfield = { workspace = true }
 

crates/supervisor/storage/src/models/common.rs

@@ -0,0 +1,87 @@
+//! Common model types used across various storage tables.
+
+use derive_more::{Deref, DerefMut};
+use reth_codecs::Compact;
+use serde::{Deserialize, Serialize};
+
+/// Wrapper for `Vec<u64>` to represent a list of numbers.
+// todo: add support for Vec<64> in table
+#[derive(
+    Deref, DerefMut, Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize, Compact,
+)]
+pub struct U64List(pub Vec<u64>);
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use reth_codecs::Compact;
+
+    #[test]
+    fn test_u64list_compact_empty() {
+        let original_list = U64List(Vec::new());
+
+        let mut buffer = Vec::new();
+        let bytes_written = original_list.to_compact(&mut buffer);
+
+        assert_eq!(
+            bytes_written,
+            buffer.len(),
+            "Bytes written should match buffer length for empty list"
+        );
+        let (deserialized_list, remaining_buf) = U64List::from_compact(&buffer, bytes_written);
+
+        assert_eq!(
+            original_list, deserialized_list,
+            "Original and deserialized empty lists should be equal"
+        );
+        assert!(
+            remaining_buf.is_empty(),
+            "Remaining buffer should be empty after deserialization of empty list"
+        );
+    }
+
+    #[test]
+    fn test_u64list_compact_with_data() {
+        let original_list = U64List(vec![10, 20, 30, 40, 50]);
+
+        let mut buffer = Vec::new();
+        let bytes_written = original_list.to_compact(&mut buffer);
+
+        assert_eq!(
+            bytes_written,
+            buffer.len(),
+            "Bytes written should match buffer length for list with data"
+        );
+        let (deserialized_list, remaining_buf) = U64List::from_compact(&buffer, bytes_written);
+
+        assert_eq!(
+            original_list, deserialized_list,
+            "Original and deserialized lists with data should be equal"
+        );
+        assert!(
+            remaining_buf.is_empty(),
+            "Remaining buffer should be empty after deserialization of list with data"
+        );
+    }
+
+    #[test]
+    fn test_u64list_deref() {
+        let list = U64List(vec![1, 2, 3]);
+        assert_eq!(list.len(), 3);
+        assert_eq!(list[0], 1);
+        assert!(!list.is_empty());
+    }
+
+    #[test]
+    fn test_u64list_deref_mut() {
+        let mut list = U64List(vec![1, 2, 3]);
+        list.push(4);
+        assert_eq!(list.0, vec![1, 2, 3, 4]);
+
+        list.sort();
+        assert_eq!(list.0, vec![1, 2, 3, 4]);
+
+        list.clear();
+        assert!(list.is_empty());
+    }
+}

crates/supervisor/storage/src/models/derivation.rs

@@ -0,0 +1,77 @@
+//! Models for storing blockchain derivation in the database.
+//!
+//! This module defines the data structure and schema used for tracking
+//! how blocks are derived from source. This is particularly relevant
+//! in rollup contexts, such as linking an L2 block to its originating L1 block.
+
+use super::BlockRef;
+use reth_codecs::Compact;
+use serde::{Deserialize, Serialize};
+
+/// Represents a pair of blocks where one block [`derived`](`Self::derived`) is derived
+/// from another [`source`](`Self::source`).
+///
+/// This structure is used to track the lineage of blocks where L2 blocks are derived from L1
+/// blocks. It stores the [`BlockRef`] information for both the source and the derived blocks.
+/// It is stored as value in the [`DerivedBlocks`](`crate::models::DerivedBlocks`) table.
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub struct DerivedBlockPair {
+    /// The block that was derived from the [`source`](`Self::source`) block.
+    pub derived: BlockRef,
+    /// The source block from which the [`derived`](`Self::derived`) block was created.
+    pub source: BlockRef,
+}
+
+impl Compact for DerivedBlockPair {
+    fn to_compact<B: bytes::BufMut + AsMut<[u8]>>(&self, buf: &mut B) -> usize {
+        let mut bytes_written = 0;
+        bytes_written += self.derived.to_compact(buf);
+        bytes_written += self.source.to_compact(buf);
+        bytes_written
+    }
+
+    fn from_compact(buf: &[u8], _len: usize) -> (Self, &[u8]) {
+        let (derived, remaining_buf) = BlockRef::from_compact(buf, buf.len());
+        let (source, final_remaining_buf) =
+            BlockRef::from_compact(remaining_buf, remaining_buf.len());
+        (Self { derived, source }, final_remaining_buf)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::BlockRef;
+    use alloy_primitives::B256;
+    use reth_codecs::Compact;
+
+    fn test_b256(val: u8) -> B256 {
+        let mut val_bytes = [0u8; 32];
+        val_bytes[0] = val;
+        let b256_from_val = B256::from(val_bytes);
+        B256::random() ^ b256_from_val
+    }
+
+    #[test]
+    fn test_derived_block_pair_compact_roundtrip() {
+        let source_ref =
+            BlockRef { number: 100, hash: test_b256(1), parent_hash: test_b256(2), time: 1000 };
+        let derived_ref =
+            BlockRef { number: 200, hash: test_b256(3), parent_hash: test_b256(4), time: 1010 };
+
+        let original_pair = DerivedBlockPair { source: source_ref, derived: derived_ref };
+
+        let mut buffer = Vec::new();
+        let bytes_written = original_pair.to_compact(&mut buffer);
+
+        assert_eq!(bytes_written, buffer.len(), "Bytes written should match buffer length");
+        let (deserialized_pair, remaining_buf) =
+            DerivedBlockPair::from_compact(&buffer, bytes_written);
+
+        assert_eq!(
+            original_pair, deserialized_pair,
+            "Original and deserialized pairs should be equal"
+        );
+        assert!(remaining_buf.is_empty(), "Remaining buffer should be empty after deserialization");
+    }
+}

crates/supervisor/storage/src/models/mod.rs

@@ -15,9 +15,16 @@
 
 mod log;
 pub use log::{ExecutingMessageEntry, LogEntry};
+
 mod block;
 pub use block::BlockRef;
 
+mod derivation;
+pub use derivation::DerivedBlockPair;
+
+mod common;
+pub use common::U64List;
+
 /// Implements [`reth_db_api::table::Compress`] and [`reth_db_api::table::Decompress`] traits for
 /// types that implement [`reth_codecs::Compact`].
 ///
@@ -50,7 +57,7 @@
 }
 
 // Implement compression logic for all value types stored in tables
-impl_compression_for_compact!(BlockRef, LogEntry);
+impl_compression_for_compact!(BlockRef, LogEntry, DerivedBlockPair, U64List);
 
 tables! {
     /// A dup-sorted table that stores all logs emitted in a given block, sorted by their index.
@@ -69,6 +76,22 @@
         type Key = u64;
         type Value = BlockRef;
     }
+
+    /// A table mapping a derived block number to its corresponding source and derived block reference.
+    /// - Key: `u64` — derived block number
+    /// - Value: [`DerivedBlockPair`] — pair of source and derived block reference
+    table DerivedBlocks {
+        type Key = u64;
+        type Value = DerivedBlockPair;
+    }
+
+    /// A table mapping a source block number to a list of its derived block numbers.
+    /// - Key: `u64` — source block number
+    /// - Value: [`U64List`] — list of derived block numbers
+     table SourceToDerivedBlockNumbers {
+        type Key = u64;
+        type Value = U64List;
+    }
 }
 
 #[cfg(test)]
@@ -129,4 +152,64 @@
         let decompressed = LogEntry::decompress(&compressed_buf).unwrap();
         assert_eq!(original, decompressed);
     }
+
+    #[test]
+    fn test_derived_block_pair_compression_decompression() {
+        let source_ref =
+            BlockRef { number: 100, hash: test_b256(6), parent_hash: test_b256(7), time: 1000 };
+        let derived_ref = BlockRef {
+            number: 200,
+            hash: test_b256(8),
+            parent_hash: test_b256(8), // Link to source
+            time: 1010,
+        };
+
+        let original_pair = DerivedBlockPair { source: source_ref, derived: derived_ref };
+
+        let mut compressed_buf = Vec::new();
+        original_pair.compress_to_buf(&mut compressed_buf);
+
+        assert!(!compressed_buf.is_empty(), "Buffer should not be empty after compression");
+
+        let decompressed_pair = DerivedBlockPair::decompress(&compressed_buf).unwrap();
+        assert_eq!(
+            original_pair, decompressed_pair,
+            "Original and deserialized pairs should be equal"
+        );
+    }
+
+    #[test]
+    fn test_u64list_compression_decompression_empty() {
+        let original_list = U64List(Vec::new());
+
+        let mut compressed_buf = Vec::new();
+        original_list.compress_to_buf(&mut compressed_buf);
+
+        // For an empty list, the compact representation might also be empty or very small.
+        // The primary check is that deserialization works and results in an empty list.
+        let decompressed_list = U64List::decompress(&compressed_buf).unwrap();
+        assert_eq!(
+            original_list, decompressed_list,
+            "Original and deserialized empty U64List should be equal"
+        );
+    }
+
+    #[test]
+    fn test_u64list_compression_decompression_with_data() {
+        let original_list = U64List(vec![10, 20, 30, 40, 50]);
+
+        let mut compressed_buf = Vec::new();
+        original_list.compress_to_buf(&mut compressed_buf);
+
+        assert!(
+            !compressed_buf.is_empty(),
+            "Buffer should not be empty after compression of U64List with data"
+        );
+
+        let decompressed_list = U64List::decompress(&compressed_buf).unwrap();
+        assert_eq!(
+            original_list, decompressed_list,
+            "Original and deserialized U64List with data should be equal"
+        );
+    }
 }