Introduce Scroll Binary Patricia Merkle Trie Components

Cargo.toml

@@ -98,7 +98,10 @@ members = [
     "crates/rpc/rpc-server-types/",
     "crates/rpc/rpc-testing-util/",
     "crates/rpc/rpc-types-compat/",
-    "crates/rpc/rpc/",
+    "crates/rpc/rpc/", 
+    "crates/scroll/primitives", 
+    "crates/scroll/state-commitment",
+    "crates/scroll/trie",
     "crates/stages/api/",
     "crates/stages/stages/",
     "crates/stages/types/",
@@ -409,6 +412,11 @@ reth-trie-common = { path = "crates/trie/common" }
 reth-trie-db = { path = "crates/trie/db" }
 reth-trie-parallel = { path = "crates/trie/parallel" }
 
+# scroll
+scroll-state-commitment = { path = "crates/scroll/state-commitment" }
+scroll-trie = { path = "crates/scroll/trie" }
+scroll-primitives = { path = "crates/scroll/primitives" }
+
 # revm
 revm = { version = "14.0.3", features = [
     "std",

crates/scroll/primitives/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "scroll-primitives"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+exclude.workspace = true
+
+[dependencies]
+alloy-primitives.workspace = true
+reth-trie.workspace = true
+poseidon-bn254 = { git = "https://github.com/scroll-tech/poseidon-bn254", branch = "master" }
+
+[lints]
+workspace = true

crates/scroll/primitives/src/lib.rs

@@ -0,0 +1,42 @@
+//! Standalone crate for Scroll-specific Reth primitive types.
+
+use alloy_primitives::{B256, U256};
+use reth_trie::TrieAccount;
+
+/// Poseidon hashing primitives.
+pub mod poseidon;
+
+/// A Scroll account as represented in the trie.
+#[derive(Debug)]
+pub struct ScrollTrieAccount {
+    /// nonce
+    pub nonce: u64,
+    /// code size
+    pub code_size: u64,
+    /// balance
+    pub balance: U256,
+    /// storage root
+    pub storage_root: B256,
+    /// keccak code hash
+    pub code_hash: B256,
+    /// poseidon code hash
+    pub poseidon_code_hash: B256,
+}
+
+// TODO: Temporary method to convert from standard ethereum `TrieAccount` to `ScrollTrieAccount`
+// TODO: Fix cast
+impl From<TrieAccount> for ScrollTrieAccount {
+    fn from(value: TrieAccount) -> Self {
+        ScrollTrieAccount {
+            // TODO(frisitano): introduce code size and poseidon code hash following integration
+            // with Account changes
+            poseidon_code_hash: Default::default(),
+            code_size: Default::default(),
+            nonce: value.nonce,
+            balance: value.balance,
+            // TODO(frisitano): introduce storage root
+            storage_root: Default::default(),
+            code_hash: value.code_hash,
+        }
+    }
+}

crates/scroll/primitives/src/poseidon.rs

@@ -0,0 +1,74 @@
+pub use poseidon_bn254::{hash_with_domain, Fr, PrimeField};
+
+/// Type that is used to represent a field element in binary representation.
+pub type FieldElementBytes = <Fr as PrimeField>::Repr;
+
+/// The number of bytes in the binary representation of a field element.
+pub const FIELD_ELEMENT_REPR_BYTES: usize = core::mem::size_of::<FieldElementBytes>();
+
+// Half the number of bytes in the binary representation of a field element.
+const HALF_FIELD_ELEMENT_REPR_BYTES: usize = FIELD_ELEMENT_REPR_BYTES / 2;
+
+/// The domain multiplier per field element.
+pub const DOMAIN_MULTIPLIER_PER_FIELD_ELEMENT: u64 = 256;
+
+/// The domain for hashing two field elements.
+pub const DOMAIN_TWO_FIELD_ELEMENTS: Fr =
+    Fr::from_raw([DOMAIN_MULTIPLIER_PER_FIELD_ELEMENT * 2, 0, 0, 0]);
+
+/// Hash two field elements using poseidon.
+pub fn hash(element_1: Fr, element_2: Fr) -> Fr {
+    hash_with_domain(&[element_1, element_2], DOMAIN_TWO_FIELD_ELEMENTS)
+}
+
+/// Split and transform input be bytes into two field elements and hash using poseidon.
+///
+/// # Panics
+///
+/// This function will panic if more than 32 bytes are provided as input.
+pub fn split_and_hash_be_bytes<T: AsRef<[u8]>>(bytes: T) -> Fr {
+    debug_assert!(
+        bytes.as_ref().len() <= FIELD_ELEMENT_REPR_BYTES,
+        "bytes length should be less than or equal to field element bytes"
+    );
+    let (bytes_lo, bytes_hi) = split_and_parse_field_elements(bytes.as_ref());
+    hash(bytes_lo, bytes_hi)
+}
+
+/// Parse input bytes into two field elements which represent the lower bytes and the upper bytes.
+///
+/// # Panics
+///
+/// This function will panic if more than 32 bytes are provided as input.
+fn split_and_parse_field_elements(bytes: &[u8]) -> (Fr, Fr) {
+    debug_assert!(
+        bytes.len() <= FIELD_ELEMENT_REPR_BYTES,
+        "bytes length should be less than or equal to field element bytes"
+    );
+    let mut bytes_lo = FieldElementBytes::default();
+    let mut bytes_hi = FieldElementBytes::default();
+
+    if bytes.len() > (HALF_FIELD_ELEMENT_REPR_BYTES) {
+        bytes_lo[HALF_FIELD_ELEMENT_REPR_BYTES..]
+            .copy_from_slice(&bytes[..HALF_FIELD_ELEMENT_REPR_BYTES]);
+        bytes_hi[HALF_FIELD_ELEMENT_REPR_BYTES..bytes.len()]
+            .copy_from_slice(&bytes[HALF_FIELD_ELEMENT_REPR_BYTES..]);
+    } else {
+        bytes_lo[HALF_FIELD_ELEMENT_REPR_BYTES..(HALF_FIELD_ELEMENT_REPR_BYTES + bytes.len())]
+            .copy_from_slice(bytes)
+    }
+
+    let bytes_lo = field_element_from_be_bytes(bytes_lo);
+    let bytes_hi = field_element_from_be_bytes(bytes_hi);
+    (bytes_lo, bytes_hi)
+}
+
+/// Parses a field element from big endian bytes.
+///
+/// # Panics
+///
+/// This function will panic if the bytes are not a valid field element.
+pub fn field_element_from_be_bytes(mut bytes: FieldElementBytes) -> Fr {
+    bytes.reverse();
+    Fr::from_repr_vartime(bytes).expect("valid field element")
+}

crates/scroll/state-commitment/Cargo.toml

@@ -0,0 +1,46 @@
+[package]
+name = "scroll-state-commitment"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+exclude.workspace = true
+
+[dependencies]
+alloy-primitives.workspace = true
+alloy-rlp.workspace = true
+reth-execution-errors.workspace = true
+reth-trie.workspace = true
+reth-primitives.workspace = true
+tracing.workspace = true
+scroll-trie.workspace = true
+scroll-primitives.workspace = true
+poseidon-bn254 = { git = "https://github.com/scroll-tech/poseidon-bn254", branch = "master" }
+reth-trie-db.workspace = true
+reth-db = { workspace = true, features = ["test-utils"] }
+
+# `metrics` feature
+reth-metrics = { workspace = true, optional = true }
+metrics = { workspace = true, optional = true }
+
+[dev-dependencies]
+alloy-consensus.workspace = true
+reth-primitives = { workspace = true, features = ["test-utils", "arbitrary"] }
+reth-trie = { workspace = true, features = ["test-utils"] }
+reth-trie-common = { workspace = true, features = ["test-utils", "arbitrary"] }
+reth-provider = { workspace = true, features = ["test-utils"] }
+proptest.workspace = true
+proptest-arbitrary-interop.workspace = true
+zktrie_rust = { path = "/Users/f/dev/scroll/zktrie/rs_zktrie" }
+zktrie = { path = "/Users/f/dev/scroll/zktrie", features = ["rs_zktrie"] }
+tracing-subscriber = { version = "0.3", default-features = false, features = ["env-filter", "fmt", "json"] }
+
+[lints]
+workspace = true
+
+[features]
+metrics = ["reth-metrics", "dep:metrics"]
+
+

crates/scroll/state-commitment/src/key.rs

@@ -0,0 +1,26 @@
+use alloy_primitives::B256;
+use scroll_primitives::poseidon::{split_and_hash_be_bytes, PrimeField, FIELD_ELEMENT_REPR_BYTES};
+
+// TODO(frisitano): Implement `KeyHasher` trait from upstream. Also consider introducing a
+// `HashingScheme` trait that combines both `KeyHasher` and `ValueHasher` traits via GATs.
+
+/// An implementation of a key hasher that uses Poseidon.
+#[derive(Debug)]
+pub struct PoseidonKeyHasher;
+
+impl PoseidonKeyHasher {
+    /// Hashes the key using the Poseidon hash function.
+    ///
+    /// The bytes are expected to be provided in big endian format.
+    ///
+    /// Panics if the number of bytes provided is greater than the number of bytes in the
+    /// binary representation of a field element (32).
+    ///
+    /// Returns the hash digest in little endian representation with bits reversed.
+    pub fn hash_key<T: AsRef<[u8]>>(bytes: T) -> B256 {
+        debug_assert!(bytes.as_ref().len() <= FIELD_ELEMENT_REPR_BYTES);
+        let mut bytes = split_and_hash_be_bytes(bytes.as_ref()).to_repr();
+        bytes.iter_mut().for_each(|byte| *byte = byte.reverse_bits());
+        bytes.into()
+    }
+}

crates/scroll/state-commitment/src/lib.rs

@@ -0,0 +1,11 @@
+//! The implementation of scrolls binary Merkle Patricia Trie used a cryptographic state commitment.
+
+mod root;
+pub use root::{StateRoot, StorageRoot};
+
+mod key;
+mod value;
+
+// RE-EXPORTS
+pub use key::PoseidonKeyHasher;
+pub use value::PosiedonValueHasher;