WEB3-293: feat: Add risc0-ethereum-trie (#391)

This PR introduces the new `risc0-ethereum-trie` crate consolidating all
functionality related to sparse Merkle-Patricia Tries (MPT).

Merge #390 first

---------

Co-authored-by: Victor Snyder-Graf <[email protected]>

Author: 2 people

Cargo.toml

@@ -15,8 +15,8 @@ risc0-aggregation = { version = "0.3.0", default-features = false, path = "crate
 risc0-build-ethereum = { version = "1.4.0", default-features = false, path = "build" }
 risc0-ethereum-contracts = { version = "1.4.0", default-features = false, path = "contracts" }
 risc0-forge-ffi = { version = "1.4.0", default-features = false, path = "crates/ffi" }
-risc0-steel = { version = "2.0.0", default-features = false, path = "crates/steel" }
 risc0-op-steel = { version = "0.2.0", default-features = false, path = "crates/op-steel" }
+risc0-steel = { version = "2.0.0", default-features = false, path = "crates/steel" }
 
 # risc0 monorepo dependencies.
 risc0-build = { git = "https://github.com/risc0/risc0", branch = "release-1.3", default-features = false }
@@ -28,9 +28,9 @@ risc0-binfmt = { git = "https://github.com/risc0/risc0", branch = "release-1.3",
 alloy-consensus = { version = "0.11" }
 alloy-eips = { version = "0.11" }
 alloy-rlp = { version = "0.3.8" }
-alloy-primitives = { version = "0.8.16" }
+alloy-primitives = { version = "0.8.18" }
 alloy-rpc-types = { version = "0.11" }
-alloy-sol-types = { version = "0.8.16" }
+alloy-sol-types = { version = "0.8.18" }
 
 # OP Steel
 op-alloy-network = { version = "0.10.0" }
@@ -42,23 +42,27 @@ alloy-trie = { version = "0.7.7" }
 # Beacon chain support
 ethereum-consensus = { git = "https://github.com/ralexstokes/ethereum-consensus.git", rev = "cf3c404043230559660810bc0c9d6d5a8498d819" }
 
-hex = "0.4"
 anyhow = { version = "1.0" }
+arrayvec = "0.7"
 bincode = { version = "1.3" }
+bytemuck = "1.21"
+cfg-if = "1.0"
 clap = { version = "4.5", features = ["derive", "env"] }
+criterion = "0.5"
+hex = "0.4"
+itertools = "0.14"
 log = "0.4"
-revm = { version = "19.2", default-features = false, features = ["std"] }
+rand = "0.9"
 reqwest = "0.12"
+revm = { version = "19.2", default-features = false, features = ["std"] }
+rkyv = "0.8"
 serde = "1.0"
 serde_json = "1.0"
 sha2 = { version = "0.10" }
 stability = "0.2"
 test-log = "0.2.15"
-thiserror = { version = "2.0", default-features = false }
+thiserror = { version = "2.0" }
 tokio = { version = "1.35" }
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 url = { version = "2.5" }
-rand = "0.9"
-cfg-if = "1.0"
-bytemuck = "1.21"

crates/trie/Cargo.toml

@@ -0,0 +1,62 @@
+[package]
+name = "risc0-ethereum-trie"
+version = "0.1.0"
+edition = { workspace = true }
+license = { workspace = true }
+homepage = { workspace = true }
+repository = { workspace = true }
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
+
+[lints.clippy]
+dbg-macro = "warn"
+manual-string-new = "warn"
+uninlined-format-args = "warn"
+redundant-clone = "warn"
+missing-const-for-fn = "warn"
+
+[lints.rust]
+missing-copy-implementations = "warn"
+missing-debug-implementations = "warn"
+missing-docs = "warn"
+rust-2018-idioms = "warn"
+unreachable-pub = "warn"
+unused-must-use = "warn"
+redundant-lifetimes = "warn"
+unnameable-types = "warn"
+
+[lints.rustdoc]
+all = "warn"
+
+[profile.bench]
+codegen-units = 1
+lto = "fat"
+
+[dependencies]
+alloy-primitives = { workspace = true, features = ["map"] }
+alloy-rlp = { workspace = true, features = ["arrayvec"] }
+alloy-trie = { workspace = true }
+arrayvec = { workspace = true }
+bincode = { workspace = true, optional = true }
+itertools = { workspace = true }
+rkyv = { workspace = true, optional = true }
+serde = { workspace = true, optional = true }
+thiserror = { workspace = true }
+
+[dev-dependencies]
+alloy-trie = { workspace = true, features = ["ethereum"] }
+criterion = { workspace = true }
+serde_json = { workspace = true }
+
+[[bench]]
+name = "mpt"
+harness = false
+
+[features]
+default = []
+rkyv = ["dep:rkyv"]
+serde = ["dep:serde", "dep:bincode", "alloy-primitives/serde", "alloy-trie/serde"]
+rlp_serialize = []
+orphan = []

crates/trie/README.md

@@ -0,0 +1,3 @@
+# risc0-ethereum-trie
+
+Fast Merkle-Patricia Trie (MPT) implementation.

crates/trie/benches/mpt.rs

@@ -0,0 +1,118 @@
+// Copyright 2025 RISC Zero, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#![allow(missing_docs)]
+
+use alloy_primitives::{bytes, keccak256, Bytes, B256};
+use alloy_trie::{HashBuilder, Nibbles};
+use criterion::{black_box, criterion_group, criterion_main, BenchmarkId, Criterion};
+use risc0_ethereum_trie::{CachedTrie, Trie};
+use std::collections::BTreeMap;
+
+const SIZE: usize = 1024;
+
+pub fn trie(c: &mut Criterion) {
+    let mut g = c.benchmark_group("trie");
+
+    g.bench_with_input(BenchmarkId::new("hash_slow", SIZE), &SIZE, |b, &s| {
+        let trie = create_trie(&create_leaves(s));
+        b.iter(|| {
+            _ = black_box(trie.hash_slow());
+        })
+    });
+    g.bench_with_input(BenchmarkId::new("get", SIZE), &SIZE, |b, &s| {
+        let leaves = create_leaves(s);
+        let keys: Vec<B256> = leaves.keys().step_by(2).cloned().collect();
+        let trie = create_trie(&leaves);
+        b.iter(|| {
+            keys.iter().for_each(|k| {
+                _ = black_box(trie.get(k));
+            })
+        })
+    });
+    g.bench_with_input(BenchmarkId::new("insert", SIZE), &SIZE, |b, &s| {
+        let leaves = create_leaves(s);
+        b.iter(|| {
+            let mut mpt = Trie::default();
+            leaves.iter().for_each(|(k, v)| mpt.insert(k, v.clone()));
+        })
+    });
+    g.bench_with_input(BenchmarkId::new("remove", SIZE), &SIZE, |b, &s| {
+        let leaves = create_leaves(s);
+        let keys: Vec<B256> = leaves.keys().cloned().collect();
+        let mpt = Trie::from_iter(leaves);
+        b.iter(|| {
+            let mut mpt = mpt.clone();
+            keys.iter().for_each(|k| {
+                _ = black_box(mpt.remove(k));
+            })
+        })
+    });
+}
+
+pub fn cached_trie(c: &mut Criterion) {
+    let mut g = c.benchmark_group("cached_trie");
+
+    g.bench_with_input(BenchmarkId::new("hash_slow", SIZE), &SIZE, |b, &s| {
+        let trie = create_trie(&create_leaves(s)).into_cached();
+        b.iter(|| {
+            _ = black_box(trie.hash_slow());
+        })
+    });
+    g.bench_with_input(BenchmarkId::new("get", SIZE), &SIZE, |b, &s| {
+        let leaves = create_leaves(s);
+        let keys: Vec<B256> = leaves.keys().step_by(2).cloned().collect();
+        let trie = create_trie(&leaves).into_cached();
+        b.iter(|| {
+            keys.iter().for_each(|k| {
+                _ = black_box(trie.get(k));
+            })
+        })
+    });
+    g.bench_with_input(BenchmarkId::new("insert", SIZE), &SIZE, |b, &s| {
+        let leaves = create_leaves(s);
+        b.iter(|| {
+            let mut mpt = CachedTrie::default();
+            leaves.iter().for_each(|(k, v)| mpt.insert(k, v.clone()));
+        })
+    });
+    g.bench_with_input(BenchmarkId::new("remove", SIZE), &SIZE, |b, &s| {
+        let leaves = create_leaves(s);
+        let keys: Vec<B256> = leaves.keys().cloned().collect();
+        let mpt = CachedTrie::from_iter(leaves);
+        b.iter(|| {
+            let mut mpt = mpt.clone();
+            keys.iter().for_each(|k| {
+                _ = black_box(mpt.remove(k));
+            })
+        })
+    });
+}
+
+fn create_leaves(size: usize) -> BTreeMap<B256, Bytes> {
+    (0..size).map(|i| (keccak256(i.to_be_bytes()), bytes!("deadbeaf"))).collect()
+}
+
+fn create_trie(leaves: &BTreeMap<B256, Bytes>) -> Trie {
+    let proof_keys = leaves.keys().step_by(2).map(Nibbles::unpack).collect();
+    let mut hb = HashBuilder::default().with_proof_retainer(proof_keys);
+    leaves.iter().for_each(|(k, v)| hb.add_leaf(Nibbles::unpack(k), v));
+    _ = hb.root();
+
+    let proofs = hb.take_proof_nodes().into_nodes_sorted().into_iter().map(|node| node.1);
+    Trie::from_rlp(proofs).unwrap()
+}
+
+criterion_group!(benches, trie, cached_trie);
+criterion_main!(benches);

crates/trie/rustfmt.toml

@@ -0,0 +1,3 @@
+reorder_imports = true
+use_field_init_shorthand = true
+use_small_heuristics = "Max"

crates/trie/src/lib.rs

@@ -0,0 +1,24 @@
+// Copyright 2025 RISC Zero, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#![doc = include_str!("../README.md")]
+#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
+
+mod mpt;
+
+#[cfg(feature = "orphan")]
+pub use mpt::orphan;
+pub use mpt::{CachedTrie, Trie, EMPTY_ROOT_HASH};
+
+pub use alloy_trie::Nibbles;