remove commented out code

Signed-off-by: Cyrill Leutwiler <bigcyrill@hotmail.com>

.gitignore

@@ -0,0 +1,5 @@
+/target
+.vscode/
+.DS_Store
+node_modules
+/*.json

Cargo.toml

@@ -0,0 +1,62 @@
+[workspace]
+resolver = "2"
+members = ["crates/*"]
+
+[workspace.package]
+version = "0.1.0"
+authors = [
+    "Parity Technologies <admin@parity.io>",
+]
+license = "MIT/Apache-2.0"
+edition = "2024"
+repository = "https://github.com/paritytech/revive-differential-testing.git"
+rust-version = "1.85.0"
+
+[workspace.dependencies]
+revive-dt-compiler = { version = "0.1.0", path = "crates/compiler" }
+revive-dt-config = { version = "0.1.0", path = "crates/config" }
+revive-dt-core = { version = "0.1.0", path = "crates/core" }
+revive-dt-format = { version = "0.1.0", path = "crates/format" }
+revive-dt-node = { version = "0.1.0", path = "crates/node" }
+revive-dt-node-interaction = { version = "0.1.0", path = "crates/node-interaction" }
+revive-dt-node-pool = { version = "0.1.0", path = "crates/node-pool" }
+revive-dt-solc-binaries = { version = "0.1.0", path = "crates/solc-binaries" }
+
+anyhow = "1.0"
+clap = { version = "4", features = ["derive"] }
+env_logger = "0.11.7"
+hex = "0.4.3"
+reqwest = { version = "0.12.15", features = ["blocking", "json"] }
+log = "0.4.26"
+once_cell = "1.21"
+rayon = { version = "1.10" }
+semver = { version = "1.0", features = ["serde"] }
+serde = { version = "1.0", default-features = false, features = ["derive"] }
+serde_json = { version = "1.0", default-features = false, features = ["arbitrary_precision", "std"] }
+sha2 = { version = "0.10.8" }
+temp-dir = { version = "0.1.14" }
+tokio = { version = "1", default-features = false, features = ["rt-multi-thread"] }
+
+# revive compiler
+revive-solc-json-interface = { git = "https://github.com/paritytech/revive", rev = "497dae2494dabe12d1af32d6d687122903cb2ada" }
+revive-common = { git = "https://github.com/paritytech/revive", rev = "497dae2494dabe12d1af32d6d687122903cb2ada" }
+revive-differential = { git = "https://github.com/paritytech/revive", rev = "497dae2494dabe12d1af32d6d687122903cb2ada" }
+
+[workspace.dependencies.alloy]
+version = "0.13.0"
+default-features = false
+features = [
+    "json-abi",
+    "providers",
+    "provider-ipc",
+    "provider-debug-api",
+    "reqwest",
+    "rpc-types",
+    "signer-local",
+    "std",
+]
+
+[profile.bench]
+inherits = "release"
+lto = true
+codegen-units = 1

crates/compiler/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "revive-dt-compiler"
+description = "Library for compiling Solidity contracts to EVM and PVM"
+version.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+anyhow = { workspace = true }
+revive-solc-json-interface = { workspace = true }
+revive-common = { workspace = true }
+semver = { workspace = true }
+serde_json = { workspace = true }

crates/compiler/src/lib.rs

@@ -0,0 +1,155 @@
+//! This crate provides compiler helpers for all supported Solidity targets:
+//! - Ethereum solc compiler
+//! - Polkadot revive resolc compiler
+//! - Polkadot revive Wasm compiler
+
+use std::{
+    fs::read_to_string,
+    hash::Hash,
+    path::{Path, PathBuf},
+};
+
+use revive_common::EVMVersion;
+use revive_solc_json_interface::{
+    SolcStandardJsonInput, SolcStandardJsonInputLanguage, SolcStandardJsonInputSettings,
+    SolcStandardJsonInputSettingsOptimizer, SolcStandardJsonInputSettingsSelection,
+    SolcStandardJsonOutput,
+};
+use semver::Version;
+
+pub mod revive_js;
+pub mod revive_resolc;
+pub mod solc;
+
+/// A common interface for all supported Solidity compilers.
+pub trait SolidityCompiler {
+    /// Extra options specific to the compiler.
+    type Options: Default + PartialEq + Eq + Hash;
+
+    /// The low-level compiler interface.
+    fn build(
+        &self,
+        input: CompilerInput<Self::Options>,
+    ) -> anyhow::Result<CompilerOutput<Self::Options>>;
+
+    fn new(solc_executable: PathBuf) -> Self;
+}
+
+/// The generic compilation input configuration.
+#[derive(Debug)]
+pub struct CompilerInput<T: PartialEq + Eq + Hash> {
+    pub extra_options: T,
+    pub input: SolcStandardJsonInput,
+}
+
+/// The generic compilation output configuration.
+pub struct CompilerOutput<T: PartialEq + Eq + Hash> {
+    pub input: CompilerInput<T>,
+    pub output: SolcStandardJsonOutput,
+}
+
+impl<T> PartialEq for CompilerInput<T>
+where
+    T: PartialEq + Eq + Hash,
+{
+    fn eq(&self, other: &Self) -> bool {
+        let self_input = serde_json::to_vec(&self.input).unwrap_or_default();
+        let other_input = serde_json::to_vec(&self.input).unwrap_or_default();
+        self.extra_options.eq(&other.extra_options) && self_input == other_input
+    }
+}
+
+impl<T> Eq for CompilerInput<T> where T: PartialEq + Eq + Hash {}
+
+impl<T> Hash for CompilerInput<T>
+where
+    T: PartialEq + Eq + Hash,
+{
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        self.extra_options.hash(state);
+        state.write(&serde_json::to_vec(&self.input).unwrap_or_default());
+    }
+}
+
+/// A generic builder style interface for configuring all compiler options.
+pub struct Compiler<T: SolidityCompiler> {
+    input: SolcStandardJsonInput,
+    extra_options: T::Options,
+    allow_paths: Vec<String>,
+    base_path: Option<String>,
+}
+
+impl Default for Compiler<solc::Solc> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl<T> Compiler<T>
+where
+    T: SolidityCompiler,
+{
+    pub fn new() -> Self {
+        Self {
+            input: SolcStandardJsonInput {
+                language: SolcStandardJsonInputLanguage::Solidity,
+                sources: Default::default(),
+                settings: SolcStandardJsonInputSettings::new(
+                    None,
+                    Default::default(),
+                    None,
+                    SolcStandardJsonInputSettingsSelection::new_required(),
+                    SolcStandardJsonInputSettingsOptimizer::new(
+                        false,
+                        None,
+                        &Version::new(0, 0, 0),
+                        false,
+                    ),
+                    None,
+                ),
+            },
+            extra_options: Default::default(),
+            allow_paths: Default::default(),
+            base_path: None,
+        }
+    }
+
+    pub fn solc_optimizer(mut self, enabled: bool) -> Self {
+        self.input.settings.optimizer.enabled = enabled;
+        self
+    }
+
+    pub fn with_source(mut self, path: &Path) -> anyhow::Result<Self> {
+        self.input
+            .sources
+            .insert(path.display().to_string(), read_to_string(path)?.into());
+        Ok(self)
+    }
+
+    pub fn evm_version(mut self, evm_version: EVMVersion) -> Self {
+        self.input.settings.evm_version = Some(evm_version);
+        self
+    }
+
+    pub fn extra_options(mut self, extra_options: T::Options) -> Self {
+        self.extra_options = extra_options;
+        self
+    }
+
+    pub fn allow_path(mut self, path: String) -> Self {
+        self.allow_paths.push(path);
+        self
+    }
+
+    pub fn base_path(mut self, base_path: String) -> Self {
+        self.base_path = Some(base_path);
+        self
+    }
+
+    pub fn try_build(self, solc_path: PathBuf) -> anyhow::Result<CompilerOutput<T::Options>> {
+        T::new(solc_path).build(CompilerInput {
+            extra_options: self.extra_options,
+            input: self.input,
+        })
+    }
+}

crates/compiler/src/revive_js.rs

@@ -0,0 +1,2 @@
+//! Implements the [crate::SolidityCompiler] trait with revive Wasm for
+//! compiling contracts to PVM bytecode (via Wasm).

crates/compiler/src/revive_resolc.rs

@@ -0,0 +1,2 @@
+//! Implements the [crate::SolidityCompiler] trait with resolc for
+//! compiling contracts to PVM bytecode.

crates/compiler/src/solc.rs

@@ -0,0 +1,42 @@
+//! Implements the [SolidityCompiler] trait with solc for
+//! compiling contracts to EVM bytecode.
+
+use std::{
+    path::PathBuf,
+    process::{Command, Stdio},
+};
+
+use crate::{CompilerInput, CompilerOutput, SolidityCompiler};
+
+pub struct Solc {
+    solc_path: PathBuf,
+}
+
+impl SolidityCompiler for Solc {
+    type Options = ();
+
+    fn build(
+        &self,
+        input: CompilerInput<Self::Options>,
+    ) -> anyhow::Result<CompilerOutput<Self::Options>> {
+        let mut child = Command::new(&self.solc_path)
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped())
+            .arg("--standard-json")
+            .spawn()?;
+
+        let stdin = child.stdin.as_mut().expect("should be piped");
+        serde_json::to_writer(stdin, &input.input)?;
+
+        let output = child.wait_with_output()?.stdout;
+        Ok(CompilerOutput {
+            input,
+            output: serde_json::from_slice(&output)?,
+        })
+    }
+
+    fn new(solc_path: PathBuf) -> Self {
+        Self { solc_path }
+    }
+}

crates/config/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "revive-dt-config"
+description = "global configuration for the revive differential tester"
+version.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+alloy = { workspace = true }
+clap = { workspace = true }
+semver = { workspace = true }
+temp-dir = { workspace = true }

crates/config/src/lib.rs

@@ -0,0 +1,134 @@
+//! The global configuration used accross all revive differential testing crates.
+
+use std::path::{Path, PathBuf};
+
+use alloy::{network::EthereumWallet, signers::local::PrivateKeySigner};
+use clap::{Parser, ValueEnum};
+use semver::Version;
+use temp_dir::TempDir;
+
+#[derive(Debug, Parser, Clone)]
+#[command(name = "retester")]
+pub struct Arguments {
+    /// The `solc` version to use if the test didn't specify it explicitly.
+    #[arg(long = "solc", short, default_value = "0.8.29")]
+    pub solc: Version,
+
+    /// Use the Wasm compiler versions.
+    #[arg(long = "wasm")]
+    pub wasm: bool,
+
+    /// The path to the `resolc` executable to be tested.
+    ///
+    /// By default it uses the `resolc` binary found in `$PATH`.
+    ///
+    /// If `--wasm` is set, this should point to the resolc Wasm ile.
+    #[arg(long = "resolc", short, default_value = "resolc")]
+    pub resolc: PathBuf,
+
+    /// A list of test corpus JSON files to be tested.
+    #[arg(long = "corpus", short)]
+    pub corpus: Vec<PathBuf>,
+
+    /// A place to store temporary artifacts during test execution.
+    ///
+    /// Creates a temporary dir if not specified.
+    #[arg(long = "workdir", short)]
+    pub working_directory: Option<PathBuf>,
+
+    /// Add a tempdir manually if `working_directory` was not given.
+    ///
+    /// We attach it here because [TempDir] prunes itself on drop.
+    #[clap(skip)]
+    pub temp_dir: Option<&'static TempDir>,
+
+    /// The path to the `geth` executable.
+    ///
+    /// By default it uses `geth` binary found in `$PATH`.
+    #[arg(short, long = "geth", default_value = "geth")]
+    pub geth: PathBuf,
+
+    /// The maximum time in milliseconds to wait for geth to start.
+    #[arg(long = "geth-start-timeout", default_value = "2000")]
+    pub geth_start_timeout: u64,
+
+    /// The test network chain ID.
+    #[arg(short, long = "network-id", default_value = "420420420")]
+    pub network_id: u64,
+
+    /// Configure nodes according to this genesis.json file.
+    #[arg(long = "genesis", default_value = "genesis.json")]
+    pub genesis_file: PathBuf,
+
+    /// The signing account private key.
+    #[arg(
+        short,
+        long = "account",
+        default_value = "0x4f3edf983ac636a65a842ce7c78d9aa706d3b113bce9c46f30d7d21715b23b1d"
+    )]
+    pub account: String,
+
+    /// The differential testing leader node implementation.
+    #[arg(short, long = "leader", default_value = "geth")]
+    pub leader: TestingPlatform,
+
+    /// The differential testing follower node implementation.
+    #[arg(short, long = "follower", default_value = "kitchensink")]
+    pub follower: TestingPlatform,
+
+    /// Only compile against this testing platform (doesn't execute the tests).
+    #[arg(long = "compile-only")]
+    pub compile_only: Option<TestingPlatform>,
+
+    /// Determines the amount of tests that are executed in parallel.
+    #[arg(long = "workers", default_value = "12")]
+    pub workers: usize,
+}
+
+impl Arguments {
+    /// Return the configured working directory with the following precedence:
+    /// 1. `self.working_directory` if it was provided.
+    /// 2. `self.temp_dir` if it it was provided
+    /// 3. Panic.
+    pub fn directory(&self) -> &Path {
+        if let Some(path) = &self.working_directory {
+            return path.as_path();
+        }
+
+        if let Some(temp_dir) = &self.temp_dir {
+            return temp_dir.path();
+        }
+
+        panic!("should have a workdir configured")
+    }
+
+    /// Try to parse `self.account` into a [PrivateKeySigner],
+    /// panicing on error.
+    pub fn wallet(&self) -> EthereumWallet {
+        let signer = self
+            .account
+            .parse::<PrivateKeySigner>()
+            .unwrap_or_else(|error| {
+                panic!("private key '{}' parsing error: {error}", self.account);
+            });
+        EthereumWallet::new(signer)
+    }
+}
+
+impl Default for Arguments {
+    fn default() -> Self {
+        Arguments::parse_from(["retester"])
+    }
+}
+
+/// The Solidity compatible node implementation.
+///
+/// This describes the solutions to be tested against on a high level.
+#[derive(Clone, Debug, Eq, Hash, PartialEq, ValueEnum)]
+#[clap(rename_all = "lower")]
+pub enum TestingPlatform {
+    /// The go-ethereum reference full node EVM implementation.
+    Geth,
+    /// The kitchensink runtime provides the PolkaVM (PVM) based node implentation.
+    Kitchensink,
+}

crates/core/Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name = "revive-dt-core"
+description = "revive differential testing core utility"
+version.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[[bin]]
+name = "retester"
+path = "src/main.rs"
+
+[dependencies]
+revive-dt-compiler = { workspace = true }
+revive-dt-config = { workspace = true }
+revive-dt-format = { workspace = true }
+revive-dt-node = { workspace = true }
+revive-dt-node-interaction = { workspace = true }
+revive-dt-solc-binaries = { workspace = true }
+
+alloy = { workspace = true }
+anyhow = { workspace = true }
+clap = { workspace = true }
+log = { workspace = true }
+env_logger = { workspace = true }
+rayon = { workspace = true }
+revive-solc-json-interface = { workspace = true }
+semver = { workspace = true }
+serde = { workspace = true, features = [ "derive" ] }
+serde_json = { workspace = true }
+temp-dir = { workspace = true }

crates/core/src/driver/mod.rs

@@ -0,0 +1,122 @@
+//! The test driver handles the compilation and execution of the test cases.
+
+use alloy::{
+    primitives::{Address, map::HashMap},
+    rpc::types::trace::geth::GethTrace,
+};
+use revive_dt_compiler::{Compiler, CompilerInput, SolidityCompiler};
+use revive_dt_config::Arguments;
+use revive_dt_format::{input::Input, metadata::Metadata, mode::SolcMode};
+use revive_dt_node_interaction::EthereumNode;
+use revive_dt_solc_binaries::download_solc;
+use revive_solc_json_interface::SolcStandardJsonOutput;
+
+use crate::Platform;
+
+type Contracts<T> = HashMap<
+    CompilerInput<<<T as Platform>::Compiler as SolidityCompiler>::Options>,
+    SolcStandardJsonOutput,
+>;
+
+pub struct State<'a, T: Platform> {
+    config: &'a Arguments,
+    contracts: Contracts<T>,
+    deployed_contracts: HashMap<String, Address>,
+}
+
+impl<'a, T> State<'a, T>
+where
+    T: Platform,
+{
+    pub fn new(config: &'a Arguments) -> Self {
+        Self {
+            config,
+            contracts: Default::default(),
+            deployed_contracts: Default::default(),
+        }
+    }
+
+    pub fn build_contracts(&mut self, mode: &SolcMode, metadata: &Metadata) -> anyhow::Result<()> {
+        let Some(version) = mode.last_patch_version(&self.config.solc) else {
+            anyhow::bail!("unsupported solc version: {:?}", mode.solc_version);
+        };
+
+        let sources = metadata.contract_sources()?;
+        let base_path = metadata.directory()?.display().to_string();
+        let mut compiler = Compiler::<T::Compiler>::new().base_path(base_path.clone());
+        for (file, _contract) in sources.values() {
+            log::debug!("contract source {}", file.display());
+            compiler = compiler.with_source(file)?;
+        }
+
+        let solc_path = download_solc(self.config.directory(), version, self.config.wasm)?;
+        let output = compiler
+            .solc_optimizer(mode.solc_optimize())
+            .try_build(solc_path)?;
+
+        self.contracts.insert(output.input, output.output);
+
+        Ok(())
+    }
+
+    pub fn execute_input(
+        &mut self,
+        input: &Input,
+        node: &T::Blockchain,
+    ) -> anyhow::Result<GethTrace> {
+        let receipt = node.execute_transaction(input.legacy_transaction(
+            self.config.network_id,
+            0,
+            &self.deployed_contracts,
+        )?)?;
+        dbg!(&receipt);
+        //node.trace_transaction(receipt)
+        todo!()
+    }
+}
+
+pub struct Driver<'a, Leader: Platform, Follower: Platform> {
+    metadata: &'a Metadata,
+    config: &'a Arguments,
+    leader_node: &'a Leader::Blockchain,
+    follower_node: &'a Follower::Blockchain,
+}
+
+impl<'a, L, F> Driver<'a, L, F>
+where
+    L: Platform,
+    F: Platform,
+{
+    pub fn new(
+        metadata: &'a Metadata,
+        config: &'a Arguments,
+        leader_node: &'a L::Blockchain,
+        follower_node: &'a F::Blockchain,
+    ) -> Driver<'a, L, F> {
+        Self {
+            metadata,
+            config,
+            leader_node,
+            follower_node,
+        }
+    }
+
+    pub fn execute(&mut self) -> anyhow::Result<()> {
+        for mode in self.metadata.solc_modes() {
+            let mut leader_state = State::<L>::new(self.config);
+            leader_state.build_contracts(&mode, self.metadata)?;
+
+            let mut follower_state = State::<F>::new(self.config);
+            follower_state.build_contracts(&mode, self.metadata)?;
+
+            for case in &self.metadata.cases {
+                for input in &case.inputs {
+                    let _ = leader_state.execute_input(input, self.leader_node)?;
+                    let _ = follower_state.execute_input(input, self.follower_node)?;
+                }
+            }
+        }
+
+        Ok(())
+    }
+}

crates/core/src/lib.rs

@@ -0,0 +1,34 @@
+//! The revive differential testing core library.
+//!
+//! This crate defines the testing configuration and
+//! provides a helper utilty to execute tests.
+
+use revive_dt_compiler::{SolidityCompiler, solc};
+use revive_dt_node::geth;
+use revive_dt_node_interaction::EthereumNode;
+
+pub mod driver;
+
+/// One platform can be tested differentially against another.
+///
+/// For this we need a blockchain node implementation and a compiler.
+pub trait Platform {
+    type Blockchain: EthereumNode;
+    type Compiler: SolidityCompiler;
+}
+
+#[derive(Default)]
+pub struct Geth;
+
+impl Platform for Geth {
+    type Blockchain = geth::Instance;
+    type Compiler = solc::Solc;
+}
+
+#[derive(Default)]
+pub struct Kitchensink;
+
+impl Platform for Kitchensink {
+    type Blockchain = geth::Instance;
+    type Compiler = solc::Solc;
+}

crates/core/src/main.rs

@@ -0,0 +1,121 @@
+use std::{collections::HashMap, sync::LazyLock};
+
+use clap::Parser;
+use rayon::{ThreadPoolBuilder, prelude::*};
+
+use revive_dt_config::*;
+use revive_dt_core::{
+    Geth,
+    driver::{Driver, State},
+};
+use revive_dt_format::{corpus::Corpus, metadata::Metadata};
+use revive_dt_node::pool::NodePool;
+use temp_dir::TempDir;
+
+static TEMP_DIR: LazyLock<TempDir> = LazyLock::new(|| TempDir::new().unwrap());
+
+fn main() -> anyhow::Result<()> {
+    let args = init_cli()?;
+
+    let corpora = collect_corpora(&args)?;
+
+    if let Some(platform) = &args.compile_only {
+        for tests in corpora.values() {
+            main_compile_only(&args, tests, platform)?;
+        }
+
+        return Ok(());
+    }
+
+    for tests in corpora.values() {
+        main_execute_differential(&args, tests)?;
+    }
+
+    Ok(())
+}
+
+fn init_cli() -> anyhow::Result<Arguments> {
+    env_logger::init();
+
+    let mut args = Arguments::parse();
+    if args.corpus.is_empty() {
+        anyhow::bail!("no test corpus specified");
+    }
+    if args.working_directory.is_none() {
+        args.temp_dir = Some(&TEMP_DIR);
+    }
+
+    ThreadPoolBuilder::new()
+        .num_threads(args.workers)
+        .build_global()
+        .unwrap();
+
+    Ok(args)
+}
+
+fn collect_corpora(args: &Arguments) -> anyhow::Result<HashMap<Corpus, Vec<Metadata>>> {
+    let mut corpora = HashMap::new();
+
+    for path in &args.corpus {
+        let corpus = Corpus::try_from_path(path)?;
+        log::info!("found corpus: {}", path.display());
+        let tests = corpus.enumerate_tests();
+        log::info!("corpus '{}' contains {} tests", &corpus.name, tests.len());
+        corpora.insert(corpus, tests);
+    }
+
+    Ok(corpora)
+}
+
+fn main_execute_differential(args: &Arguments, tests: &[Metadata]) -> anyhow::Result<()> {
+    let leader_nodes = NodePool::new(args)?;
+    let follower_nodes = NodePool::new(args)?;
+
+    tests.par_iter().for_each(|metadata| {
+        let mut driver = match (&args.leader, &args.follower) {
+            (TestingPlatform::Geth, TestingPlatform::Kitchensink) => Driver::<Geth, Geth>::new(
+                metadata,
+                args,
+                leader_nodes.round_robbin(),
+                follower_nodes.round_robbin(),
+            ),
+            _ => unimplemented!(),
+        };
+
+        match driver.execute() {
+            Ok(build) => {
+                log::info!(
+                    "metadata {} success",
+                    metadata.directory().as_ref().unwrap().display()
+                );
+                build
+            }
+            Err(error) => {
+                log::warn!(
+                    "metadata {} failure: {error:?}",
+                    metadata.file_path.as_ref().unwrap().display()
+                );
+            }
+        }
+    });
+
+    Ok(())
+}
+
+fn main_compile_only(
+    config: &Arguments,
+    tests: &[Metadata],
+    platform: &TestingPlatform,
+) -> anyhow::Result<()> {
+    tests.par_iter().for_each(|metadata| {
+        for mode in &metadata.solc_modes() {
+            let mut state = match platform {
+                TestingPlatform::Geth => State::<Geth>::new(config),
+                _ => todo!(),
+            };
+            let _ = state.build_contracts(mode, metadata);
+        }
+    });
+
+    Ok(())
+}

crates/format/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "revive-dt-format"
+description = "declarative test definition format"
+version.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+alloy = { workspace = true }
+anyhow = { workspace = true }
+log = { workspace = true }
+semver = { workspace = true }
+serde = { workspace = true, features = [ "derive" ] }
+serde_json = { workspace = true }

crates/format/src/case.rs

@@ -0,0 +1,12 @@
+use serde::Deserialize;
+
+use crate::{input::Input, mode::Mode};
+
+#[derive(Debug, Default, Deserialize, Clone, Eq, PartialEq)]
+pub struct Case {
+    pub name: Option<String>,
+    pub comment: Option<String>,
+    pub modes: Option<Vec<Mode>>,
+    pub inputs: Vec<Input>,
+    pub group: Option<String>,
+}

crates/format/src/corpus.rs

@@ -0,0 +1,67 @@
+use std::{
+    fs::File,
+    path::{Path, PathBuf},
+};
+
+use serde::Deserialize;
+
+use crate::metadata::Metadata;
+
+#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Hash)]
+pub struct Corpus {
+    pub name: String,
+    pub path: PathBuf,
+}
+
+impl Corpus {
+    /// Try to read and parse the corpus definition file at given `path`.
+    pub fn try_from_path(path: &Path) -> anyhow::Result<Self> {
+        let file = File::open(path)?;
+        Ok(serde_json::from_reader(file)?)
+    }
+
+    /// Scan the corpus base directory and return all tests found.
+    pub fn enumerate_tests(&self) -> Vec<Metadata> {
+        let mut tests = Vec::new();
+        collect_metadata(&self.path, &mut tests);
+        tests
+    }
+}
+
+/// Recursively walks `path` and parses any JSON or Solidity file into a test
+/// definition [Metadata].
+///
+/// Found tests are inserted into `tests`.
+///
+/// `path` is expected to be a directory.
+pub fn collect_metadata(path: &Path, tests: &mut Vec<Metadata>) {
+    let dir_entry = match std::fs::read_dir(path) {
+        Ok(dir_entry) => dir_entry,
+        Err(error) => {
+            log::error!("failed to read dir '{}': {error}", path.display());
+            return;
+        }
+    };
+
+    for entry in dir_entry {
+        let entry = match entry {
+            Ok(entry) => entry,
+            Err(error) => {
+                log::error!("error reading dir entry: {error}");
+                continue;
+            }
+        };
+
+        let path = entry.path();
+        if path.is_dir() {
+            collect_metadata(&path, tests);
+            continue;
+        }
+
+        if path.is_file() {
+            if let Some(metadata) = Metadata::try_from_file(&path) {
+                tests.push(metadata)
+            }
+        }
+    }
+}

crates/format/src/input.rs

@@ -0,0 +1,132 @@
+use std::collections::HashMap;
+
+use alloy::{
+    json_abi::Function, network::TransactionBuilder, primitives::Address,
+    rpc::types::TransactionRequest,
+};
+use semver::VersionReq;
+use serde::{Deserialize, de::Deserializer};
+use serde_json::Value;
+
+#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq)]
+pub struct Input {
+    #[serde(default = "default_caller")]
+    pub caller: Address,
+    pub comment: Option<String>,
+    #[serde(default = "default_instance")]
+    pub instance: String,
+    #[serde(deserialize_with = "deserialize_method")]
+    pub method: Method,
+    pub calldata: Option<Calldata>,
+    pub expected: Option<Expected>,
+    pub value: Option<String>,
+    pub storage: Option<HashMap<String, Calldata>>,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq)]
+#[serde(untagged)]
+pub enum Expected {
+    Calldata(Calldata),
+    Expected(ExpectedOutput),
+    ExpectedMany(Vec<ExpectedOutput>),
+}
+
+#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq)]
+pub struct ExpectedOutput {
+    compiler_version: Option<VersionReq>,
+    return_data: Option<Calldata>,
+    events: Option<Value>,
+    exception: Option<bool>,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq)]
+#[serde(untagged)]
+pub enum Calldata {
+    Single(String),
+    Compound(Vec<String>),
+}
+
+/// Specify how the contract is called.
+#[derive(Debug, Default, Clone, Eq, PartialEq)]
+pub enum Method {
+    /// Initiate a deploy transaction, calling contracts constructor.
+    ///
+    /// Indicated by `#deployer`.
+    Deployer,
+    /// Does not calculate and insert a function selector.
+    ///
+    /// Indicated by `#fallback`.
+    #[default]
+    Fallback,
+    /// Call the public function with this selector.
+    ///
+    /// Calculates the selector if neither deployer or fallback matches.
+    Function([u8; 4]),
+}
+
+fn deserialize_method<'de, D>(deserializer: D) -> Result<Method, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    Ok(match String::deserialize(deserializer)?.as_str() {
+        "#deployer" => Method::Deployer,
+        "#fallback" => Method::Fallback,
+        signature => {
+            let signature = if signature.ends_with(')') {
+                signature.to_string()
+            } else {
+                format!("{signature}()")
+            };
+            match Function::parse(&signature) {
+                Ok(function) => Method::Function(function.selector().0),
+                Err(error) => {
+                    return Err(serde::de::Error::custom(format!(
+                        "parsing function signature '{signature}' error: {error}"
+                    )));
+                }
+            }
+        }
+    })
+}
+
+impl Input {
+    fn instance_to_address(
+        &self,
+        instance: &str,
+        deployed_contracts: &HashMap<String, Address>,
+    ) -> anyhow::Result<Address> {
+        deployed_contracts
+            .get(instance)
+            .copied()
+            .ok_or_else(|| anyhow::anyhow!("instance {instance} not deployed"))
+    }
+
+    /// Parse this input into a legacy transaction.
+    pub fn legacy_transaction(
+        &self,
+        chain_id: u64,
+        nonce: u64,
+        deployed_contracts: &HashMap<String, Address>,
+    ) -> anyhow::Result<TransactionRequest> {
+        let to = match self.method {
+            Method::Deployer => Address::ZERO,
+            _ => self.instance_to_address(&self.instance, deployed_contracts)?,
+        };
+
+        Ok(TransactionRequest::default()
+            .with_from(self.caller)
+            .with_to(to)
+            .with_nonce(nonce)
+            .with_chain_id(chain_id)
+            .with_gas_price(20_000_000_000)
+            .with_gas_limit(20_000_000_000))
+    }
+}
+
+fn default_instance() -> String {
+    "Test".to_string()
+}
+
+fn default_caller() -> Address {
+    "90F8bf6A479f320ead074411a4B0e7944Ea8c9C1".parse().unwrap()
+}

crates/format/src/lib.rs

@@ -0,0 +1,7 @@
+//! The revive differential tests case format.
+
+pub mod case;
+pub mod corpus;
+pub mod input;
+pub mod metadata;
+pub mod mode;

crates/format/src/metadata.rs

@@ -0,0 +1,168 @@
+use std::{
+    collections::BTreeMap,
+    fs::{File, read_to_string},
+    path::{Path, PathBuf},
+};
+
+use serde::Deserialize;
+
+use crate::{
+    case::Case,
+    mode::{Mode, SolcMode},
+};
+
+pub const METADATA_FILE_EXTENSION: &str = "json";
+pub const SOLIDITY_CASE_FILE_EXTENSION: &str = "sol";
+pub const SOLIDITY_CASE_COMMENT_MARKER: &str = "//!";
+
+#[derive(Debug, Default, Deserialize, Clone, Eq, PartialEq)]
+pub struct Metadata {
+    pub cases: Vec<Case>,
+    pub contracts: Option<BTreeMap<String, String>>,
+    pub libraries: Option<BTreeMap<String, BTreeMap<String, String>>>,
+    pub ignore: Option<bool>,
+    pub modes: Option<Vec<Mode>>,
+    pub file_path: Option<PathBuf>,
+}
+
+impl Metadata {
+    /// Returns the solc modes of this metadata, inserting a default mode if not present.
+    pub fn solc_modes(&self) -> Vec<SolcMode> {
+        self.modes
+            .to_owned()
+            .unwrap_or_else(|| vec![Mode::Solidity(Default::default())])
+            .iter()
+            .filter_map(|mode| match mode {
+                Mode::Solidity(solc_mode) => Some(solc_mode),
+                Mode::Unknown(mode) => {
+                    log::debug!("compiler: ignoring unknown mode '{mode}'");
+                    None
+                }
+            })
+            .cloned()
+            .collect()
+    }
+
+    /// Returns the base directory of this metadata.
+    pub fn directory(&self) -> anyhow::Result<PathBuf> {
+        Ok(self
+            .file_path
+            .as_ref()
+            .and_then(|path| path.parent())
+            .ok_or_else(|| anyhow::anyhow!("metadata invalid file path: {:?}", self.file_path))?
+            .to_path_buf())
+    }
+
+    /// Extract the contract sources.
+    ///
+    /// Returns a mapping of contract IDs to their source path and contract name.
+    pub fn contract_sources(&self) -> anyhow::Result<BTreeMap<String, (PathBuf, String)>> {
+        let directory = self.directory()?;
+        let mut sources = BTreeMap::new();
+        let Some(contracts) = &self.contracts else {
+            return Ok(sources);
+        };
+
+        for (id, contract) in contracts {
+            // TODO: broken if a colon is in the dir name..
+            let mut parts = contract.split(':');
+            let (Some(file_name), Some(contract_name)) = (parts.next(), parts.next()) else {
+                anyhow::bail!("metadata contains invalid contract: {contract}");
+            };
+            let file = directory.to_path_buf().join(file_name);
+            if !file.is_file() {
+                anyhow::bail!("contract {id} is not a file: {}", file.display());
+            }
+
+            sources.insert(id.clone(), (file, contract_name.to_string()));
+        }
+
+        Ok(sources)
+    }
+
+    /// Try to parse the test metadata struct from the given file at `path`.
+    ///
+    /// Returns `None` if `path` didn't contain a test metadata or case definition.
+    ///
+    /// # Panics
+    /// Expects the supplied `path` to be a file.
+    pub fn try_from_file(path: &Path) -> Option<Self> {
+        assert!(path.is_file(), "not a file: {}", path.display());
+
+        let Some(file_extension) = path.extension() else {
+            log::debug!("skipping corpus file: {}", path.display());
+            return None;
+        };
+
+        if file_extension == METADATA_FILE_EXTENSION {
+            return Self::try_from_json(path);
+        }
+
+        if file_extension == SOLIDITY_CASE_FILE_EXTENSION {
+            return Self::try_from_solidity(path);
+        }
+
+        log::debug!("ignoring invalid corpus file: {}", path.display());
+        None
+    }
+
+    fn try_from_json(path: &Path) -> Option<Self> {
+        let file = File::open(path)
+            .inspect_err(|error| {
+                log::error!(
+                    "opening JSON test metadata file '{}' error: {error}",
+                    path.display()
+                );
+            })
+            .ok()?;
+
+        match serde_json::from_reader::<_, Metadata>(file) {
+            Ok(mut metadata) => {
+                metadata.file_path = Some(path.to_path_buf());
+                Some(metadata)
+            }
+            Err(error) => {
+                log::error!(
+                    "parsing JSON test metadata file '{}' error: {error}",
+                    path.display()
+                );
+                None
+            }
+        }
+    }
+
+    fn try_from_solidity(path: &Path) -> Option<Self> {
+        let buf = read_to_string(path)
+            .inspect_err(|error| {
+                log::error!(
+                    "opening JSON test metadata file '{}' error: {error}",
+                    path.display()
+                );
+            })
+            .ok()?
+            .lines()
+            .filter_map(|line| line.strip_prefix(SOLIDITY_CASE_COMMENT_MARKER))
+            .fold(String::new(), |mut buf, string| {
+                buf.push_str(string);
+                buf
+            });
+
+        if buf.is_empty() {
+            return None;
+        }
+
+        match serde_json::from_str::<Self>(&buf) {
+            Ok(mut metadata) => {
+                metadata.file_path = Some(path.to_path_buf());
+                Some(metadata)
+            }
+            Err(error) => {
+                log::error!(
+                    "parsing Solidity test metadata file '{}' error: {error}",
+                    path.display()
+                );
+                None
+            }
+        }
+    }
+}

crates/format/src/mode.rs

@@ -0,0 +1,96 @@
+use semver::Version;
+use serde::Deserialize;
+use serde::de::Deserializer;
+
+/// Specifies the compilation mode of the test artifact.
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub enum Mode {
+    Solidity(SolcMode),
+    Unknown(String),
+}
+
+/// Specify Solidity specific compiler options.
+#[derive(Debug, Default, Clone, Eq, PartialEq)]
+pub struct SolcMode {
+    pub solc_version: Option<semver::VersionReq>,
+    solc_optimize: Option<bool>,
+    pub llvm_optimizer_settings: Vec<String>,
+}
+
+impl SolcMode {
+    /// Try to parse a mode string into a solc mode.
+    /// Returns `None` if the string wasn't a solc YUL mode string.
+    ///
+    /// The mode string is expected to start with the `Y` ID (YUL ID),
+    /// optionally followed by `+` or `-` for the solc optimizer settings.
+    ///
+    /// Options can be separated by a whitespace contain the following
+    /// - A solc `SemVer version requirement` string
+    /// - One or more `-OX` where X is a supposed to be an LLVM opt mode
+    pub fn parse_from_mode_string(mode_string: &str) -> Option<Self> {
+        let mut result = Self::default();
+
+        let mut parts = mode_string.trim().split(" ");
+
+        match parts.next()? {
+            "Y" => {}
+            "Y+" => result.solc_optimize = Some(true),
+            "Y-" => result.solc_optimize = Some(false),
+            _ => return None,
+        }
+
+        for part in parts {
+            if let Ok(solc_version) = semver::VersionReq::parse(part) {
+                result.solc_version = Some(solc_version);
+                continue;
+            }
+            if let Some(level) = part.strip_prefix("-O") {
+                result.llvm_optimizer_settings.push(level.to_string());
+                continue;
+            }
+            panic!("the YUL mode string {mode_string} failed to parse, invalid part: {part}")
+        }
+
+        Some(result)
+    }
+
+    /// Returns whether to enable the solc optimizer.
+    pub fn solc_optimize(&self) -> bool {
+        self.solc_optimize.unwrap_or(true)
+    }
+
+    /// Calculate the latest matching solc patch version. Returns:
+    /// - `latest_supported` if no version request was specified.
+    /// - A matching version with the same minor version as `latest_supported`, if any.
+    /// - `None` if no minor version of the `latest_supported` version matches.
+    pub fn last_patch_version(&self, latest_supported: &Version) -> Option<Version> {
+        let Some(version_req) = self.solc_version.as_ref() else {
+            return Some(latest_supported.to_owned());
+        };
+
+        // lgtm
+        for patch in (0..latest_supported.patch + 1).rev() {
+            let version = Version::new(0, latest_supported.minor, patch);
+            if version_req.matches(&version) {
+                return Some(version);
+            }
+        }
+
+        None
+    }
+}
+
+impl<'de> Deserialize<'de> for Mode {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let mode_string = String::deserialize(deserializer)?;
+
+        if let Some(solc_mode) = SolcMode::parse_from_mode_string(&mode_string) {
+            return Ok(Self::Solidity(solc_mode));
+        }
+
+        Ok(Self::Unknown(mode_string))
+    }
+}

crates/node-interaction/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "revive-dt-node-interaction"
+description = "send and trace transactions to nodes"
+version.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+alloy = { workspace = true }
+anyhow = { workspace = true }
+hex = { workspace = true }
+log = { workspace = true }
+once_cell = { workspace = true }
+serde_json = { workspace = true }
+tokio = { workspace = true }

crates/node-interaction/src/lib.rs

@@ -0,0 +1,21 @@
+//! This crate implements all node interactions.
+
+use alloy::rpc::types::trace::geth::GethTrace;
+use alloy::rpc::types::{TransactionReceipt, TransactionRequest};
+use tokio_runtime::TO_TOKIO;
+
+mod tokio_runtime;
+pub mod trace;
+pub mod transaction;
+
+/// An interface for all interactions with Ethereum compatible nodes.
+pub trait EthereumNode {
+    /// Execute the [TransactionRequest] and return a [TransactionReceipt].
+    fn execute_transaction(
+        &self,
+        transaction: TransactionRequest,
+    ) -> anyhow::Result<TransactionReceipt>;
+
+    /// Trace the transaction in the [TransactionReceipt] and return a [GethTrace].
+    fn trace_transaction(&self, transaction: TransactionReceipt) -> anyhow::Result<GethTrace>;
+}

crates/node-interaction/src/tokio_runtime.rs

@@ -0,0 +1,79 @@
+//! The alloy crate __requires__ a tokio runtime.
+//! We contain any async rust right here.
+
+use once_cell::sync::Lazy;
+use std::pin::Pin;
+use std::sync::Mutex;
+use std::thread;
+use tokio::runtime::Runtime;
+use tokio::spawn;
+use tokio::sync::{mpsc, oneshot};
+use tokio::task::JoinError;
+
+use crate::trace::Trace;
+use crate::transaction::Transaction;
+
+pub(crate) static TO_TOKIO: Lazy<Mutex<TokioRuntime>> =
+    Lazy::new(|| Mutex::new(TokioRuntime::spawn()));
+
+/// Common interface for executing async node interactions from a non-async context.
+#[allow(clippy::type_complexity)]
+pub(crate) trait AsyncNodeInteraction: Send + 'static {
+    type Output: Send;
+
+    //// Returns the task and the output sender.
+    fn split(
+        self,
+    ) -> (
+        Pin<Box<dyn Future<Output = Self::Output> + Send>>,
+        oneshot::Sender<Self::Output>,
+    );
+}
+
+pub(crate) struct TokioRuntime {
+    pub(crate) transaction_sender: mpsc::Sender<Transaction>,
+    pub(crate) trace_sender: mpsc::Sender<Trace>,
+}
+
+impl TokioRuntime {
+    fn spawn() -> Self {
+        let rt = Runtime::new().expect("should be able to create the tokio runtime");
+        let (transaction_sender, transaction_receiver) = mpsc::channel::<Transaction>(1024);
+        let (trace_sender, trace_receiver) = mpsc::channel::<Trace>(1024);
+
+        thread::spawn(move || {
+            rt.block_on(async move {
+                let transaction_task = spawn(interaction::<Transaction>(transaction_receiver));
+                let trace_task = spawn(interaction::<Trace>(trace_receiver));
+
+                if let Err(error) = transaction_task.await {
+                    log::error!("tokio transaction task failed: {error}");
+                }
+                if let Err(error) = trace_task.await {
+                    log::error!("tokio trace transaction task failed: {error}");
+                }
+            });
+        });
+
+        Self {
+            transaction_sender,
+            trace_sender,
+        }
+    }
+}
+
+async fn interaction<T>(mut receiver: mpsc::Receiver<T>) -> Result<(), JoinError>
+where
+    T: AsyncNodeInteraction,
+{
+    while let Some(task) = receiver.recv().await {
+        spawn(async move {
+            let (task, sender) = task.split();
+            sender
+                .send(task.await)
+                .unwrap_or_else(|_| panic!("failed to send task output"));
+        });
+    }
+
+    Ok(())
+}

crates/node-interaction/src/trace.rs

@@ -0,0 +1,43 @@
+//! Trace transactions in a sync context.
+
+use std::pin::Pin;
+
+use alloy::rpc::types::trace::geth::GethTrace;
+use tokio::sync::oneshot;
+
+use crate::TO_TOKIO;
+use crate::tokio_runtime::AsyncNodeInteraction;
+
+pub type Task = Pin<Box<dyn Future<Output = anyhow::Result<GethTrace>> + Send>>;
+
+pub(crate) struct Trace {
+    sender: oneshot::Sender<anyhow::Result<GethTrace>>,
+    task: Task,
+}
+
+impl AsyncNodeInteraction for Trace {
+    type Output = anyhow::Result<GethTrace>;
+
+    fn split(
+        self,
+    ) -> (
+        std::pin::Pin<Box<dyn Future<Output = Self::Output> + Send>>,
+        oneshot::Sender<Self::Output>,
+    ) {
+        (self.task, self.sender)
+    }
+}
+
+/// Execute some [Task] that return a [GethTrace] result.
+pub fn trace_transaction(task: Task) -> anyhow::Result<GethTrace> {
+    let task_sender = TO_TOKIO.lock().unwrap().trace_sender.clone();
+    let (sender, receiver) = oneshot::channel();
+
+    task_sender
+        .blocking_send(Trace { task, sender })
+        .expect("we are not calling this from an async context");
+
+    receiver
+        .blocking_recv()
+        .unwrap_or_else(|error| anyhow::bail!("no trace received: {error}"))
+}

crates/node-interaction/src/transaction.rs

@@ -0,0 +1,46 @@
+//! Execute transactions in a sync context.
+
+use std::pin::Pin;
+
+use alloy::rpc::types::TransactionReceipt;
+use tokio::sync::oneshot;
+
+use crate::TO_TOKIO;
+use crate::tokio_runtime::AsyncNodeInteraction;
+
+pub type Task = Pin<Box<dyn Future<Output = anyhow::Result<TransactionReceipt>> + Send>>;
+
+pub(crate) struct Transaction {
+    receipt_sender: oneshot::Sender<anyhow::Result<TransactionReceipt>>,
+    task: Task,
+}
+
+impl AsyncNodeInteraction for Transaction {
+    type Output = anyhow::Result<TransactionReceipt>;
+
+    fn split(
+        self,
+    ) -> (
+        Pin<Box<dyn Future<Output = Self::Output> + Send>>,
+        oneshot::Sender<Self::Output>,
+    ) {
+        (self.task, self.receipt_sender)
+    }
+}
+
+/// Execute some [Task] that returns a [TransactionReceipt].
+pub fn execute_transaction(task: Task) -> anyhow::Result<TransactionReceipt> {
+    let request_sender = TO_TOKIO.lock().unwrap().transaction_sender.clone();
+    let (receipt_sender, receipt_receiver) = oneshot::channel();
+
+    request_sender
+        .blocking_send(Transaction {
+            receipt_sender,
+            task,
+        })
+        .expect("we are not calling this from an async context");
+
+    receipt_receiver
+        .blocking_recv()
+        .unwrap_or_else(|error| anyhow::bail!("no receipt received: {error}"))
+}

crates/node/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "revive-dt-node"
+description = "abstraction over blockchain nodes"
+version.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+anyhow = { workspace = true }
+alloy = { workspace = true }
+log = { workspace = true }
+serde_json = { workspace = true }
+
+revive-dt-node-interaction = { workspace = true }
+revive-dt-config = { workspace = true }
+
+[dev-dependencies]
+temp-dir = { workspace = true }

crates/node/src/geth.rs

@@ -0,0 +1,298 @@
+//! The go-ethereum node implementation.
+
+use std::{
+    fs::{File, create_dir_all, remove_dir_all},
+    io::{BufRead, BufReader, Read, Write},
+    path::PathBuf,
+    process::{Child, Command, Stdio},
+    sync::atomic::{AtomicU32, Ordering},
+    thread,
+    time::{Duration, Instant},
+};
+
+use alloy::{
+    network::EthereumWallet,
+    providers::{Provider, ProviderBuilder, ext::DebugApi},
+    rpc::types::{
+        TransactionReceipt, TransactionRequest,
+        trace::geth::{DiffMode, GethDebugTracingOptions, PreStateConfig, PreStateFrame},
+    },
+};
+use revive_dt_config::Arguments;
+use revive_dt_node_interaction::{
+    EthereumNode, trace::trace_transaction, transaction::execute_transaction,
+};
+
+use crate::Node;
+
+static NODE_COUNT: AtomicU32 = AtomicU32::new(0);
+
+/// The go-ethereum node instance implementation.
+///
+/// Implements helpers to initialize, spawn and wait the node.
+///
+/// Assumes dev mode and IPC only (`P2P`, `http`` etc. are kept disabled).
+///
+/// Prunes the child process and the base directory on drop.
+#[derive(Debug)]
+pub struct Instance {
+    connection_string: String,
+    base_directory: PathBuf,
+    data_directory: PathBuf,
+    geth: PathBuf,
+    id: u32,
+    handle: Option<Child>,
+    network_id: u64,
+    start_timeout: u64,
+    wallet: EthereumWallet,
+}
+
+impl Instance {
+    const BASE_DIRECTORY: &str = "geth";
+    const DATA_DIRECTORY: &str = "data";
+
+    const IPC_FILE: &str = "geth.ipc";
+    const GENESIS_JSON_FILE: &str = "genesis.json";
+
+    const READY_MARKER: &str = "IPC endpoint opened";
+    const ERROR_MARKER: &str = "Fatal:";
+
+    /// Create the node directory and call `geth init` to configure the genesis.
+    fn init(&mut self, genesis: String) -> anyhow::Result<&mut Self> {
+        create_dir_all(&self.base_directory)?;
+
+        let genesis_path = self.base_directory.join(Self::GENESIS_JSON_FILE);
+        File::create(&genesis_path)?.write_all(genesis.as_bytes())?;
+
+        let mut child = Command::new(&self.geth)
+            .arg("init")
+            .arg("--datadir")
+            .arg(&self.data_directory)
+            .arg(genesis_path)
+            .stderr(Stdio::piped())
+            .stdout(Stdio::null())
+            .spawn()?;
+
+        let mut stderr = String::new();
+        child
+            .stderr
+            .take()
+            .expect("should be piped")
+            .read_to_string(&mut stderr)?;
+
+        if !child.wait()?.success() {
+            anyhow::bail!("failed to initialize geth node #{:?}: {stderr}", &self.id);
+        }
+
+        Ok(self)
+    }
+
+    /// Spawn the go-ethereum node child process.
+    ///
+    /// [Instance::init] must be called priorly.
+    fn spawn_process(&mut self) -> anyhow::Result<&mut Self> {
+        self.handle = Command::new(&self.geth)
+            .arg("--dev")
+            .arg("--datadir")
+            .arg(&self.data_directory)
+            .arg("--ipcpath")
+            .arg(&self.connection_string)
+            .arg("--networkid")
+            .arg(self.network_id.to_string())
+            .arg("--nodiscover")
+            .arg("--maxpeers")
+            .arg("0")
+            .stderr(Stdio::piped())
+            .stdout(Stdio::null())
+            .spawn()?
+            .into();
+        Ok(self)
+    }
+
+    /// Wait for the g-ethereum node child process getting ready.
+    ///
+    /// [Instance::spawn_process] must be called priorly.
+    fn wait_ready(&mut self) -> anyhow::Result<&mut Self> {
+        // Thanks clippy but geth is a server; we don't `wait` but eventually kill it.
+        #[allow(clippy::zombie_processes)]
+        let mut child = self.handle.take().expect("should be spawned");
+        let start_time = Instant::now();
+        let maximum_wait_time = Duration::from_millis(self.start_timeout);
+        let mut stderr = BufReader::new(child.stderr.take().expect("should be piped")).lines();
+        let error = loop {
+            let Some(Ok(line)) = stderr.next() else {
+                break "child process stderr reading error".to_string();
+            };
+            if line.contains(Self::ERROR_MARKER) {
+                break line;
+            }
+            if line.contains(Self::READY_MARKER) {
+                // Keep stderr alive
+                // https://github.com/alloy-rs/alloy/issues/2091#issuecomment-2676134147
+                thread::spawn(move || for _ in stderr.by_ref() {});
+
+                self.handle = child.into();
+                return Ok(self);
+            }
+            if Instant::now().duration_since(start_time) > maximum_wait_time {
+                break "spawn timeout".to_string();
+            }
+        };
+
+        let _ = child.kill();
+        anyhow::bail!("geth node #{} spawn error: {error}", self.id)
+    }
+}
+
+impl EthereumNode for Instance {
+    fn execute_transaction(
+        &self,
+        transaction: TransactionRequest,
+    ) -> anyhow::Result<alloy::rpc::types::TransactionReceipt> {
+        let connection_string = self.connection_string();
+        let wallet = self.wallet.clone();
+
+        execute_transaction(Box::pin(async move {
+            Ok(ProviderBuilder::new()
+                .wallet(wallet)
+                .connect(&connection_string)
+                .await?
+                .send_transaction(transaction)
+                .await?
+                .get_receipt()
+                .await?)
+        }))
+    }
+
+    fn trace_transaction(
+        &self,
+        transaction: TransactionReceipt,
+    ) -> anyhow::Result<alloy::rpc::types::trace::geth::GethTrace> {
+        let connection_string = self.connection_string();
+        let trace_options = GethDebugTracingOptions::prestate_tracer(PreStateConfig {
+            diff_mode: Some(true),
+            disable_code: None,
+            disable_storage: None,
+        });
+        let wallet = self.wallet.clone();
+
+        trace_transaction(Box::pin(async move {
+            Ok(ProviderBuilder::new()
+                .wallet(wallet)
+                .connect(&connection_string)
+                .await?
+                .debug_trace_transaction(transaction.transaction_hash, trace_options)
+                .await?)
+        }))
+    }
+}
+
+impl Node for Instance {
+    fn new(config: &Arguments) -> Self {
+        let geth_directory = config.directory().join(Self::BASE_DIRECTORY);
+        let id = NODE_COUNT.fetch_add(1, Ordering::SeqCst);
+        let base_directory = geth_directory.join(id.to_string());
+
+        Self {
+            connection_string: base_directory.join(Self::IPC_FILE).display().to_string(),
+            data_directory: base_directory.join(Self::DATA_DIRECTORY),
+            base_directory,
+            geth: config.geth.clone(),
+            id,
+            handle: None,
+            network_id: config.network_id,
+            start_timeout: config.geth_start_timeout,
+            wallet: config.wallet(),
+        }
+    }
+
+    fn connection_string(&self) -> String {
+        self.connection_string.clone()
+    }
+
+    fn shutdown(self) -> anyhow::Result<()> {
+        Ok(())
+    }
+
+    fn spawn(&mut self, genesis: String) -> anyhow::Result<()> {
+        self.init(genesis)?.spawn_process()?.wait_ready()?;
+        Ok(())
+    }
+
+    fn state_diff(
+        &self,
+        transaction: alloy::rpc::types::TransactionReceipt,
+    ) -> anyhow::Result<DiffMode> {
+        match self
+            .trace_transaction(transaction)?
+            .try_into_pre_state_frame()?
+        {
+            PreStateFrame::Diff(diff) => Ok(diff),
+            _ => anyhow::bail!("expected a diff mode trace"),
+        }
+    }
+
+    fn version(&self) -> anyhow::Result<String> {
+        let output = Command::new(&self.geth)
+            .arg("--version")
+            .stdin(Stdio::null())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::null())
+            .spawn()?
+            .wait_with_output()?
+            .stdout;
+        Ok(String::from_utf8_lossy(&output).into())
+    }
+}
+
+impl Drop for Instance {
+    fn drop(&mut self) {
+        if let Some(child) = self.handle.as_mut() {
+            let _ = child.kill();
+        }
+        if self.base_directory.exists() {
+            let _ = remove_dir_all(&self.base_directory);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use revive_dt_config::Arguments;
+    use temp_dir::TempDir;
+
+    use crate::{GENESIS_JSON, Node};
+
+    use super::Instance;
+
+    fn test_config() -> (Arguments, TempDir) {
+        let mut config = Arguments::default();
+        let temp_dir = TempDir::new().unwrap();
+        config.working_directory = temp_dir.path().to_path_buf().into();
+
+        (config, temp_dir)
+    }
+
+    #[test]
+    fn init_works() {
+        Instance::new(&test_config().0)
+            .init(GENESIS_JSON.to_string())
+            .unwrap();
+    }
+
+    #[test]
+    fn spawn_works() {
+        Instance::new(&test_config().0)
+            .spawn(GENESIS_JSON.to_string())
+            .unwrap();
+    }
+
+    #[test]
+    fn version_works() {
+        let version = Instance::new(&test_config().0).version().unwrap();
+        assert!(
+            version.starts_with("geth version"),
+            "expected version string, got: '{version}'"
+        );
+    }
+}

crates/node/src/lib.rs

@@ -0,0 +1,36 @@
+//! This crate implements the testing nodes.
+
+use alloy::rpc::types::{TransactionReceipt, trace::geth::DiffMode};
+use revive_dt_config::Arguments;
+use revive_dt_node_interaction::EthereumNode;
+
+pub mod geth;
+pub mod pool;
+
+/// The default genesis configuration.
+pub const GENESIS_JSON: &str = include_str!("../../../genesis.json");
+
+/// An abstract interface for testing nodes.
+pub trait Node: EthereumNode {
+    /// Create a new uninitialized instance.
+    fn new(config: &Arguments) -> Self;
+
+    /// Spawns a node configured according to the genesis json.
+    ///
+    /// Blocking until it's ready to accept transactions.
+    fn spawn(&mut self, genesis: String) -> anyhow::Result<()>;
+
+    /// Prune the node instance and related data.
+    ///
+    /// Blocking until it's completely stopped.
+    fn shutdown(self) -> anyhow::Result<()>;
+
+    /// Returns the nodes connection string.
+    fn connection_string(&self) -> String;
+
+    /// Returns the state diff of the transaction hash in the [TransactionReceipt].
+    fn state_diff(&self, transaction: TransactionReceipt) -> anyhow::Result<DiffMode>;
+
+    /// Returns the node version.
+    fn version(&self) -> anyhow::Result<String>;
+}

crates/node/src/pool.rs

@@ -0,0 +1,68 @@
+//! This crate implements concurrent handling of testing node.
+
+use std::{
+    fs::read_to_string,
+    sync::atomic::{AtomicUsize, Ordering},
+    thread,
+};
+
+use anyhow::Context;
+use revive_dt_config::Arguments;
+
+use crate::Node;
+
+/// The node pool starts one or more [Node] which then can be accessed
+/// in a round robbin fasion.
+pub struct NodePool<T> {
+    next: AtomicUsize,
+    nodes: Vec<T>,
+}
+
+impl<T> NodePool<T>
+where
+    T: Node + Send + 'static,
+{
+    /// Create a new Pool. This will start as many nodes as there are workers in `config`.
+    pub fn new(config: &Arguments) -> anyhow::Result<Self> {
+        let nodes = config.workers;
+        let genesis = read_to_string(&config.genesis_file).context(format!(
+            "can not read genesis file: {}",
+            config.genesis_file.display()
+        ))?;
+
+        let mut handles = Vec::with_capacity(nodes);
+        for _ in 0..nodes {
+            let config = config.clone();
+            let genesis = genesis.clone();
+            handles.push(thread::spawn(move || spawn_node::<T>(&config, genesis)));
+        }
+
+        let mut nodes = Vec::with_capacity(nodes);
+        for handle in handles {
+            nodes.push(
+                handle
+                    .join()
+                    .map_err(|error| anyhow::anyhow!("failed to spawn node: {:?}", error))?
+                    .map_err(|error| anyhow::anyhow!("node failed to spawn: {error}"))?,
+            );
+        }
+
+        Ok(Self {
+            nodes,
+            next: Default::default(),
+        })
+    }
+
+    /// Get a handle to the next node.
+    pub fn round_robbin(&self) -> &T {
+        let current = self.next.fetch_add(1, Ordering::SeqCst) % self.nodes.len();
+        self.nodes.get(current).unwrap()
+    }
+}
+
+fn spawn_node<T: Node + Send>(args: &Arguments, genesis: String) -> anyhow::Result<T> {
+    let mut node = T::new(args);
+    log::info!("starting node: {}", node.connection_string());
+    node.spawn(genesis)?;
+    Ok(node)
+}

crates/solc-binaries/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "revive-dt-solc-binaries"
+dependencies = "Download and cache solc binaries"
+version.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+anyhow = { workspace = true }
+hex = { workspace = true }
+log = { workspace = true }
+reqwest = { workspace = true }
+semver = { workspace = true }
+serde = { workspace = true }
+sha2 = { workspace = true }

crates/solc-binaries/src/cache.rs

@@ -0,0 +1,71 @@
+//! Helper for caching the solc binaries.
+
+use std::{
+    collections::HashSet,
+    fs::{File, create_dir_all},
+    io::{BufWriter, Write},
+    os::unix::fs::PermissionsExt,
+    path::{Path, PathBuf},
+    sync::{LazyLock, Mutex},
+};
+
+use crate::download::GHDownloader;
+
+pub const SOLC_CACHE_DIRECTORY: &str = "solc";
+pub(crate) static SOLC_CACHER: LazyLock<Mutex<HashSet<PathBuf>>> = LazyLock::new(Default::default);
+
+pub(crate) fn get_or_download(
+    working_directory: &Path,
+    downloader: &GHDownloader,
+) -> anyhow::Result<PathBuf> {
+    let target_directory = working_directory
+        .join(SOLC_CACHE_DIRECTORY)
+        .join(downloader.version.to_string());
+    let target_file = target_directory.join(downloader.target);
+
+    let mut cache = SOLC_CACHER.lock().unwrap();
+    if cache.contains(&target_file) {
+        log::debug!("using cached solc: {}", target_file.display());
+        return Ok(target_file);
+    }
+
+    create_dir_all(target_directory)?;
+    download_to_file(&target_file, downloader)?;
+    cache.insert(target_file.clone());
+
+    Ok(target_file)
+}
+
+fn download_to_file(path: &Path, downloader: &GHDownloader) -> anyhow::Result<()> {
+    log::info!("caching file: {}", path.display());
+
+    let Ok(file) = File::create_new(path) else {
+        log::debug!("cache file already exists: {}", path.display());
+        return Ok(());
+    };
+
+    #[cfg(unix)]
+    {
+        let mut permissions = file.metadata()?.permissions();
+        permissions.set_mode(permissions.mode() | 0o111);
+        file.set_permissions(permissions)?;
+    }
+
+    let mut file = BufWriter::new(file);
+    file.write_all(&downloader.download()?)?;
+    file.flush()?;
+    drop(file);
+
+    #[cfg(target_os = "macos")]
+    std::process::Command::new("xattr")
+        .arg("-d")
+        .arg("com.apple.quarantine")
+        .arg(&path)
+        .stderr(std::process::Stdio::null())
+        .stdout(std::process::Stdio::null())
+        .stdout(std::process::Stdio::null())
+        .spawn()?
+        .wait()?;
+
+    Ok(())
+}

crates/solc-binaries/src/download.rs

@@ -0,0 +1,146 @@
+//! This module downloads solc binaries.
+
+use std::{
+    collections::HashMap,
+    sync::{LazyLock, Mutex},
+};
+
+use semver::Version;
+use sha2::{Digest, Sha256};
+
+use crate::list::List;
+
+pub static LIST_CACHE: LazyLock<Mutex<HashMap<&'static str, List>>> =
+    LazyLock::new(Default::default);
+
+impl List {
+    pub const LINUX_URL: &str = "https://binaries.soliditylang.org/linux-amd64/list.json";
+    pub const WINDOWS_URL: &str = "https://binaries.soliditylang.org/windows-amd64/list.json";
+    pub const MACOSX_URL: &str = "https://binaries.soliditylang.org/macosx-amd64/list.json";
+    pub const WASM_URL: &str = "https://binaries.soliditylang.org/wasm/list.json";
+
+    /// Try to downloads the list from the given URL.
+    ///
+    /// Caches the list retrieved from the `url` into [LIST_CACHE],
+    /// subsequent calls with the same `url` will return the cached list.
+    pub fn download(url: &'static str) -> anyhow::Result<Self> {
+        if let Some(list) = LIST_CACHE.lock().unwrap().get(url) {
+            return Ok(list.clone());
+        }
+
+        let body: List = reqwest::blocking::get(url)?.json()?;
+
+        LIST_CACHE.lock().unwrap().insert(url, body.clone());
+
+        Ok(body)
+    }
+}
+
+/// Download solc binaries from GitHub releases (IPFS links aren't reliable).
+#[derive(Clone, Debug)]
+pub struct GHDownloader {
+    pub version: Version,
+    pub target: &'static str,
+    pub list: &'static str,
+}
+
+impl GHDownloader {
+    pub const BASE_URL: &str = "https://github.com/ethereum/solidity/releases/download";
+
+    pub const LINUX_NAME: &str = "solc-static-linux";
+    pub const MACOSX_NAME: &str = "solc-macos";
+    pub const WINDOWS_NAME: &str = "solc-windows.exe";
+    pub const WASM_NAME: &str = "soljson.js";
+
+    fn new(version: Version, target: &'static str, list: &'static str) -> Self {
+        Self {
+            version,
+            target,
+            list,
+        }
+    }
+
+    pub fn linux(version: Version) -> Self {
+        Self::new(version, Self::LINUX_NAME, List::LINUX_URL)
+    }
+
+    pub fn macosx(version: Version) -> Self {
+        Self::new(version, Self::MACOSX_NAME, List::MACOSX_URL)
+    }
+
+    pub fn windows(version: Version) -> Self {
+        Self::new(version, Self::WINDOWS_NAME, List::WINDOWS_URL)
+    }
+
+    pub fn wasm(version: Version) -> Self {
+        Self::new(version, Self::WASM_NAME, List::WASM_URL)
+    }
+
+    /// Returns the download link.
+    pub fn url(&self) -> String {
+        format!("{}/v{}/{}", Self::BASE_URL, &self.version, &self.target)
+    }
+
+    /// Download the solc binary.
+    ///
+    /// Errors out if the download fails or the digest of the downloaded file
+    /// mismatches the expected digest from the release [List].
+    pub fn download(&self) -> anyhow::Result<Vec<u8>> {
+        log::info!("downloading solc: {self:?}");
+        let expected_digest = List::download(self.list)?
+            .builds
+            .iter()
+            .find(|build| build.version == self.version)
+            .ok_or_else(|| anyhow::anyhow!("solc v{} not found builds", self.version))
+            .map(|b| b.sha256.strip_prefix("0x").unwrap_or(&b.sha256).to_string())?;
+
+        let file = reqwest::blocking::get(self.url())?.bytes()?.to_vec();
+
+        if hex::encode(Sha256::digest(&file)) != expected_digest {
+            anyhow::bail!("sha256 mismatch for solc version {}", self.version);
+        }
+
+        Ok(file)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::{download::GHDownloader, list::List};
+
+    #[test]
+    fn try_get_windows() {
+        let version = List::download(List::WINDOWS_URL)
+            .unwrap()
+            .latest_release
+            .into();
+        GHDownloader::windows(version).download().unwrap();
+    }
+
+    #[test]
+    fn try_get_macosx() {
+        let version = List::download(List::MACOSX_URL)
+            .unwrap()
+            .latest_release
+            .into();
+        GHDownloader::macosx(version).download().unwrap();
+    }
+
+    #[test]
+    fn try_get_linux() {
+        let version = List::download(List::LINUX_URL)
+            .unwrap()
+            .latest_release
+            .into();
+        GHDownloader::linux(version).download().unwrap();
+    }
+
+    #[test]
+    fn try_get_wasm() {
+        let version = List::download(List::WASM_URL)
+            .unwrap()
+            .latest_release
+            .into();
+        GHDownloader::wasm(version).download().unwrap();
+    }
+}

crates/solc-binaries/src/lib.rs

@@ -0,0 +1,39 @@
+//! This crates provides serializable Rust type definitions for the [solc binary lists][0]
+//! and download helpers.
+//!
+//! [0]: https://binaries.soliditylang.org
+
+use std::path::{Path, PathBuf};
+
+use cache::get_or_download;
+use download::GHDownloader;
+use semver::Version;
+
+pub mod cache;
+pub mod download;
+pub mod list;
+
+/// Downloads the solc binary for Wasm is `wasm` is set, otherwise for
+/// the target platform.
+///
+/// Subsequent calls for the same version will use a cached artifact
+/// and not download it again.
+pub fn download_solc(
+    cache_directory: &Path,
+    version: Version,
+    wasm: bool,
+) -> anyhow::Result<PathBuf> {
+    let downloader = if wasm {
+        GHDownloader::wasm(version)
+    } else if cfg!(target_os = "linux") {
+        GHDownloader::linux(version)
+    } else if cfg!(target_os = "macos") {
+        GHDownloader::macosx(version)
+    } else if cfg!(target_os = "windows") {
+        GHDownloader::windows(version)
+    } else {
+        unimplemented!()
+    };
+
+    get_or_download(cache_directory, &downloader)
+}

crates/solc-binaries/src/list.rs

@@ -0,0 +1,26 @@
+//! Rust type definitions for the solc binary lists.
+
+use std::{collections::HashMap, path::PathBuf};
+
+use semver::Version;
+use serde::Deserialize;
+
+#[derive(Debug, Deserialize, Clone, Eq, PartialEq)]
+pub struct List {
+    pub builds: Vec<Build>,
+    pub releases: HashMap<Version, String>,
+    #[serde(rename = "latestRelease")]
+    pub latest_release: Version,
+}
+
+#[derive(Debug, Deserialize, Clone, Eq, PartialEq)]
+pub struct Build {
+    pub path: PathBuf,
+    pub version: Version,
+    pub build: String,
+    #[serde(rename = "longVersion")]
+    pub long_version: String,
+    pub keccak256: String,
+    pub sha256: String,
+    pub urls: Vec<String>,
+}

genesis.json

@@ -0,0 +1,41 @@
+{
+    "config": {
+        "chainId": 420420420,
+        "homesteadBlock": 0,
+        "eip150Block": 0,
+        "eip155Block": 0,
+        "eip158Block": 0,
+        "byzantiumBlock": 0,
+        "constantinopleBlock": 0,
+        "petersburgBlock": 0,
+        "istanbulBlock": 0,
+        "berlinBlock": 0,
+        "londonBlock": 0,
+        "arrowGlacierBlock": 0,
+        "grayGlacierBlock": 0,
+        "shanghaiTime": 0,
+        "cancunTime": 0,
+        "terminalTotalDifficulty": 0,
+        "terminalTotalDifficultyPassed": true,
+        "blobSchedule": {
+            "cancun": {
+                "target": 3,
+                "max": 6,
+                "baseFeeUpdateFraction": 3338477
+            }
+        }
+    },
+    "coinbase": "0xffffffffffffffffffffffffffffffffffffffff",
+    "difficulty": "0x00",
+    "extraData": "",
+    "gasLimit": "0xffffffff",
+    "nonce": "0x0000000000000042",
+    "mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000",
+    "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
+    "timestamp": "0x00",
+    "alloc": {
+        "90F8bf6A479f320ead074411a4B0e7944Ea8c9C1": {
+            "balance": "1000000000000000000"
+        }
+    }
+}