feat(l1): add statetest subcommand to ef_tests-statev2 for goevmlab fuzzing

tooling/ef_tests/state_v2/src/main.rs

@@ -1,14 +1,57 @@
 #![allow(clippy::all)]
 
-use clap::Parser;
+use std::process::ExitCode;
+
+use clap::{Parser, Subcommand};
 use ef_tests_statev2::modules::{
     error::RunnerError,
     parser::{RunnerOptions, parse_tests},
+    statetest::{self, StatetestOptions},
 };
 
+#[derive(Parser, Debug)]
+#[command(name = "ef-tests-state-v2")]
+struct Cli {
+    #[command(subcommand)]
+    command: Option<Command>,
+
+    /// Default (no subcommand): bulk-run the EF state-test suite.
+    #[command(flatten)]
+    runner: RunnerOptions,
+}
+
+#[derive(Subcommand, Debug)]
+enum Command {
+    /// Run a single EF state-test fixture and emit EIP-3155 trace + stateRoot to
+    /// stderr. Designed for goevmlab differential fuzzing.
+    Statetest(StatetestOptions),
+}
+
 #[tokio::main]
-pub async fn main() -> Result<(), RunnerError> {
-    let mut runner_options = RunnerOptions::parse();
+pub async fn main() -> ExitCode {
+    let cli = Cli::parse();
+
+    // Errors from a subcommand map to exit code 2 so that goevmlab can distinguish
+    // a state-root mismatch (deliberate exit 1) from an actual internal failure.
+    match cli.command {
+        Some(Command::Statetest(opts)) => match statetest::run(opts).await {
+            Ok(code) => code,
+            Err(e) => {
+                eprintln!("statetest error: {e:?}");
+                ExitCode::from(2)
+            }
+        },
+        None => match run_bulk(cli.runner).await {
+            Ok(()) => ExitCode::SUCCESS,
+            Err(e) => {
+                eprintln!("error: {e:?}");
+                ExitCode::from(2)
+            }
+        },
+    }
+}
+
+async fn run_bulk(mut runner_options: RunnerOptions) -> Result<(), RunnerError> {
     println!("Runner options: {:#?}", runner_options);
 
     println!("\nParsing test files...");

tooling/ef_tests/state_v2/src/modules/deserialize.rs

@@ -138,9 +138,16 @@ where
     let post_deserialized = HashMap::<String, Vec<RawPostValue>>::deserialize(deserializer)?;
     let mut post_parsed = HashMap::new();
     for (fork_str, values) in post_deserialized {
+        // Keep names in sync with the `Fork` enum in `crates/common/types/genesis.rs`.
+        // An unknown fork name is a hard error so that newly-emitted fixture forks
+        // surface as a build break (forcing a deserializer/Fork update), rather than
+        // silently dropping test coverage.
         let fork = match fork_str.as_str() {
             "Frontier" => Fork::Frontier,
             "Homestead" => Fork::Homestead,
+            "EIP150" => Fork::Tangerine,
+            "EIP158" => Fork::SpuriousDragon,
+            "Byzantium" => Fork::Byzantium,
             "Constantinople" => Fork::Constantinople,
             "ConstantinopleFix" | "Petersburg" => Fork::Petersburg,
             "Istanbul" => Fork::Istanbul,
@@ -150,9 +157,13 @@ where
             "Shanghai" => Fork::Shanghai,
             "Cancun" => Fork::Cancun,
             "Prague" => Fork::Prague,
-            "Byzantium" => Fork::Byzantium,
-            "EIP158" => Fork::SpuriousDragon,
-            "EIP150" => Fork::Tangerine,
+            "Osaka" => Fork::Osaka,
+            "BPO1" => Fork::BPO1,
+            "BPO2" => Fork::BPO2,
+            "BPO3" => Fork::BPO3,
+            "BPO4" => Fork::BPO4,
+            "BPO5" => Fork::BPO5,
+            "Amsterdam" => Fork::Amsterdam,
             other => {
                 return Err(serde::de::Error::custom(format!(
                     "Unknown fork name: {other}",

tooling/ef_tests/state_v2/src/modules/error.rs

@@ -1,3 +1,5 @@
+use std::path::PathBuf;
+
 use ethrex_levm::errors::VMError;
 
 #[derive(Debug)]
@@ -6,5 +8,11 @@ pub enum RunnerError {
     VMError(VMError),
     EIP7702ShouldNotBeCreateType,
     FailedToGetIndexValue(String),
+    /// Wraps an I/O or serde error encountered while parsing a fixture.
+    /// Holds the offending path and the underlying error message.
+    ParseFixture {
+        path: PathBuf,
+        source: String,
+    },
     Custom(String),
 }

tooling/ef_tests/state_v2/src/modules/mod.rs

@@ -5,5 +5,6 @@ pub mod parser;
 pub mod report;
 pub mod result_check;
 pub mod runner;
+pub mod statetest;
 pub mod types;
 pub mod utils;

tooling/ef_tests/state_v2/src/modules/parser.rs

@@ -52,8 +52,15 @@ pub fn parse_file(path: &PathBuf, log_parse_file: bool) -> Result<Vec<Test>, Run
     if log_parse_file {
         println!("Parsing file: {:?}", path);
     }
-    let test_file = std::fs::File::open(path.clone()).unwrap();
-    let mut tests: Tests = serde_json::from_reader(test_file).unwrap();
+    let test_file = std::fs::File::open(path).map_err(|e| RunnerError::ParseFixture {
+        path: path.clone(),
+        source: format!("open: {e}"),
+    })?;
+    let mut tests: Tests =
+        serde_json::from_reader(test_file).map_err(|e| RunnerError::ParseFixture {
+            path: path.clone(),
+            source: format!("deserialize: {e}"),
+        })?;
     for test in tests.0.iter_mut() {
         test.path = path.clone();
     }
@@ -71,14 +78,23 @@ pub fn parse_dir(
     if log_parse_dir {
         println!("Parsing test directory: {:?}", path);
     }
-    let dir_entries: Vec<_> = std::fs::read_dir(path.clone()).unwrap().flatten().collect();
+    let dir_entries: Vec<_> = std::fs::read_dir(path)
+        .map_err(|e| RunnerError::ParseFixture {
+            path: path.clone(),
+            source: format!("read_dir: {e}"),
+        })?
+        .flatten()
+        .collect();
 
     // Process directory entries in parallel
     let directory_tests_results: Vec<_> = dir_entries
         .into_par_iter()
         .map(|entry| -> Result<Option<Vec<Test>>, RunnerError> {
             // Check entry type
-            let entry_type = entry.file_type().unwrap();
+            let entry_type = entry.file_type().map_err(|e| RunnerError::ParseFixture {
+                path: entry.path(),
+                source: format!("file_type: {e}"),
+            })?;
             if entry_type.is_dir() {
                 let dir_tests = parse_dir(
                     &entry.path(),