Support compiler-version aware exceptions

Support Compile-time Linking (#79 )
* Use wrappers for libraries in metadata. * Create a unified way to access deployed contracts * Support linking at compile time
2026-04-22 10:17:56 +00:00 · 2025-07-25 17:06:14 +03:00 · 2025-07-25 07:03:21 +00:00 · 2025-07-24 15:35:25 +00:00 · 2025-07-24 12:42:45 +00:00 · 2025-07-24 08:46:14 +00:00
55 changed files with 8456 additions and 1057 deletions
@@ -0,0 +1,147 @@
+name: Test workflow
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+    types: [opened, synchronize]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  cache-polkadot:
+    name: Build and cache Polkadot binaries on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-24.04, macos-14]
+
+    steps:
+      - name: Checkout repo and submodules
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install dependencies (Linux)
+        if: matrix.os == 'ubuntu-24.04'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y protobuf-compiler clang libclang-dev
+          rustup target add wasm32-unknown-unknown
+          rustup component add rust-src
+
+      - name: Install dependencies (macOS)
+        if: matrix.os == 'macos-14'
+        run: |
+          brew install protobuf
+          rustup target add wasm32-unknown-unknown
+          rustup component add rust-src
+
+      - name: Cache binaries
+        id: cache
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cargo/bin/substrate-node
+            ~/.cargo/bin/eth-rpc
+          key: polkadot-binaries-${{ matrix.os }}-${{ hashFiles('polkadot-sdk/.git') }}
+
+      - name: Build substrate-node
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: |
+          cd polkadot-sdk
+          cargo install --locked --force --profile=production --path substrate/bin/node/cli --bin substrate-node --features cli
+
+      - name: Build eth-rpc
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: |
+          cd polkadot-sdk
+          cargo install --path substrate/frame/revive/rpc --bin eth-rpc
+
+  ci:
+    name: CI on ${{ matrix.os }}
+    needs: cache-polkadot
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-24.04, macos-14]
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Restore binaries from cache
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cargo/bin/substrate-node
+            ~/.cargo/bin/eth-rpc
+          key: polkadot-binaries-${{ matrix.os }}-${{ hashFiles('polkadot-sdk/.git') }}
+
+      - name: Setup Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          rustflags: ""
+
+      - name: Add wasm32 target
+        run: |
+          rustup target add wasm32-unknown-unknown
+          rustup component add rust-src
+
+      - name: Install Geth on Ubuntu
+        if: matrix.os == 'ubuntu-24.04'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y protobuf-compiler
+
+          # We were facing some issues in CI with the 1.16.* versions of geth, and specifically on
+          # Ubuntu. Eventually, we found out that the last version of geth that worked in our CI was
+          # version 1.15.11. Thus, this is the version that we want to use in CI. The PPA sadly does
+          # not have historic versions of Geth and therefore we need to resort to downloading pre
+          # built binaries for Geth and the surrounding tools which is what the following parts of 
+          # the script do.
+
+          sudo apt-get install -y wget ca-certificates tar
+          ARCH=$(uname -m)
+          if [ "$ARCH" = "x86_64" ]; then
+            URL="https://gethstore.blob.core.windows.net/builds/geth-alltools-linux-amd64-1.15.11-36b2371c.tar.gz"
+          elif [ "$ARCH" = "aarch64" ]; then
+            URL="https://gethstore.blob.core.windows.net/builds/geth-alltools-linux-arm64-1.15.11-36b2371c.tar.gz"
+          else
+            echo "Unsupported architecture: $ARCH"
+            exit 1
+          fi
+          wget -qO- "$URL" | sudo tar xz -C /usr/local/bin --strip-components=1
+          geth --version
+
+      - name: Install Geth on macOS
+        if: matrix.os == 'macos-14'
+        run: |
+          brew tap ethereum/ethereum
+          brew install ethereum protobuf
+
+      - name: Machete
+        uses: bnjbvr/cargo-machete@v0.7.1
+
+      - name: Format
+        run: make format
+
+      - name: Clippy
+        run: make clippy
+
+      - name: Check substrate-node version
+        run: substrate-node --version
+
+      - name: Check eth-rpc version
+        run: eth-rpc --version
+
+      - name: Test cargo workspace
+        run: make test
@@ -3,3 +3,7 @@
 .DS_Store
 node_modules
 /*.json
+
+# We do not want to commit any log files that we produce from running the code locally so this is 
+# added to the .gitignore file.
+*.log
@@ -0,0 +1,3 @@
+[submodule "polkadot-sdk"]
+	path = polkadot-sdk
+	url = https://github.com/paritytech/polkadot-sdk.git
@@ -4,15 +4,14 @@ members = ["crates/*"]

 [workspace.package]
 version = "0.1.0"
-authors = [
-    "Parity Technologies <admin@parity.io>",
-]
+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-common = { version = "0.1.0", path = "crates/common" }
 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" }
@@ -20,30 +19,48 @@ 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-report = { version = "0.1.0", path = "crates/report" }
 revive-dt-solc-binaries = { version = "0.1.0", path = "crates/solc-binaries" }

+alloy-primitives = "1.2.1"
+alloy-sol-types = "1.2.1"
 anyhow = "1.0"
 clap = { version = "4", features = ["derive"] }
-env_logger = "0.11.7"
+futures = { version = "0.3.31" }
 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"] }
+serde_json = { version = "1.0", default-features = false, features = [
+    "arbitrary_precision",
+    "std",
+] }
+sha2 = { version = "0.10.9" }
+sp-core = "36.1.0"
+sp-runtime = "41.1.0"
+temp-dir = { version = "0.1.16" }
+tempfile = "3.3"
+tokio = { version = "1", default-features = false, features = [
+    "rt-multi-thread",
+] }
+uuid = { version = "1.8", features = ["v4"] }
+tracing = "0.1.41"
+tracing-subscriber = { version = "0.3.19", default-features = false, features = [
+    "fmt",
+    "json",
+    "env-filter",
+] }
+indexmap = { version = "2.10.0", default-features = false }

 # 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" }
+revive-solc-json-interface = { git = "https://github.com/paritytech/revive", rev = "3389865af7c3ff6f29a586d82157e8bc573c1a8e" }
+revive-common = { git = "https://github.com/paritytech/revive", rev = "3389865af7c3ff6f29a586d82157e8bc573c1a8e" }
+revive-differential = { git = "https://github.com/paritytech/revive", rev = "3389865af7c3ff6f29a586d82157e8bc573c1a8e" }

 [workspace.dependencies.alloy]
-version = "0.13.0"
+version = "1.0.22"
 default-features = false
 features = [
    "json-abi",
@@ -54,6 +71,10 @@ features = [
    "rpc-types",
    "signer-local",
    "std",
+    "network",
+    "serde",
+    "rpc-types-eth",
+    "genesis",
 ]

 [profile.bench]
@@ -0,0 +1,15 @@
+.PHONY: format clippy test machete
+
+format:
+	cargo fmt --all -- --check
+
+clippy:
+	cargo clippy --all-features --workspace -- --deny warnings
+
+machete:
+	cargo install cargo-machete
+	cargo machete crates
+
+test: format clippy machete
+	cargo test --workspace -- --nocapture
+
@@ -1,2 +1,34 @@
 # revive-differential-tests
-revive differential testing framework
+
+The revive differential testing framework allows to define smart contract tests in a declarative manner in order to compile and execute them against different Ethereum-compatible blockchain implmentations. This is useful to:
+- Analyze observable differences in contract compilation and execution across different blockchain implementations, including contract storage, account balances, transaction output and emitted events on a per-transaction base.
+- Collect and compare benchmark metrics such as code size, gas usage or transaction throughput per seconds (TPS) of different blockchain implementations.
+- Ensure reproducible contract builds across multiple compiler implementations or multiple host platforms.
+- Implement end-to-end regression tests for Ethereum-compatible smart contract stacks.
+
+# Declarative test format
+
+For now, the format used to write tests is the [matter-labs era compiler format](https://github.com/matter-labs/era-compiler-tests?tab=readme-ov-file#matter-labs-simplecomplex-format). This allows us to re-use many tests from their corpora.
+
+# The `retester` utility
+
+The `retester` helper utilty is used to run the tests. To get an idea of what `retester` can do, please consults its command line help: 
+
+```
+cargo run -p revive-dt-core -- --help
+```
+
+For example, to run the [complex Solidity tests](https://github.com/matter-labs/era-compiler-tests/tree/main/solidity/complex), define a corpus structure as follows:
+
+```json
+{
+    "name": "ML Solidity Complex",
+    "path": "/path/to/era-compiler-tests/solidity/complex"
+}
+```
+
+Assuming this to be saved in a `ml-solidity-complex.json` file, the following command will try to compile and execute the tests found inside the corpus:
+
+```bash
+RUST_LOG=debug cargo r --release -p revive-dt-core  -- --corpus ml-solidity-complex.json 
+```
@@ -0,0 +1,326 @@
+{
+    "modes": [
+        "Y >=0.8.9",
+        "E",
+        "I"
+    ],
+    "cases": [
+        {
+            "name": "first",
+            "inputs": [
+                {
+                    "instance": "WBTC_1",
+                    "method": "#deployer",
+                    "calldata": [
+                        "0x40",
+                        "0x80",
+                        "4",
+                        "0x5742544300000000000000000000000000000000000000000000000000000000",
+                        "14",
+                        "0x5772617070656420425443000000000000000000000000000000000000000000"
+                    ],
+                    "expected": [
+                        "WBTC_1.address"
+                    ]
+                },
+                {
+                    "instance": "WBTC_2",
+                    "method": "#deployer",
+                    "calldata": [
+                        "0x40",
+                        "0x80",
+                        "4",
+                        "0x5742544300000000000000000000000000000000000000000000000000000000",
+                        "14",
+                        "0x5772617070656420425443000000000000000000000000000000000000000000"
+                    ],
+                    "expected": [
+                        "WBTC_2.address"
+                    ]
+                },
+                {
+                    "instance": "Mooniswap",
+                    "method": "#deployer",
+                    "calldata": [
+                        "0x0000000000000000000000000000000000000000000000000000000000000060",
+                        "0x00000000000000000000000000000000000000000000000000000000000000c0",
+                        "0x0000000000000000000000000000000000000000000000000000000000000100",
+                        "0x0000000000000000000000000000000000000000000000000000000000000002",
+                        "WBTC_1.address",
+                        "WBTC_2.address",
+                        "4",
+                        "0x5742544300000000000000000000000000000000000000000000000000000000",
+                        "14",
+                        "0x5772617070656420425443000000000000000000000000000000000000000000"
+                    ],
+                    "expected": {
+                        "return_data": [
+                            "Mooniswap.address"
+                        ],
+                        "events": [
+                            {
+                                "topics": [
+                                    "0x8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0",
+                                    "0x0000000000000000000000000000000000000000000000000000000000000000",
+                                    "0xdeadbeef01000000000000000000000000000000"
+                                ],
+                                "values": []
+                            }
+                        ],
+                        "exception": false
+                    }
+                },
+                {
+                    "instance": "WBTC_1",
+                    "method": "_mint",
+                    "calldata": [
+                        "0xdeadbeef00000000000000000000000000000042",
+                        "1000000000"
+                    ],
+                    "expected": {
+                        "return_data": [],
+                        "events": [
+                            {
+                                "topics": [
+                                    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+                                    "0x0000000000000000000000000000000000000000000000000000000000000000",
+                                    "0xdeadbeef00000000000000000000000000000042"
+                                ],
+                                "values": [
+                                    "1000000000"
+                                ]
+                            }
+                        ],
+                        "exception": false
+                    }
+                },
+                {
+                    "instance": "WBTC_2",
+                    "method": "_mint",
+                    "calldata": [
+                        "0xdeadbeef00000000000000000000000000000042",
+                        "1000000000"
+                    ],
+                    "expected": {
+                        "return_data": [],
+                        "events": [
+                            {
+                                "topics": [
+                                    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+                                    "0x0000000000000000000000000000000000000000000000000000000000000000",
+                                    "0xdeadbeef00000000000000000000000000000042"
+                                ],
+                                "values": [
+                                    "1000000000"
+                                ]
+                            }
+                        ],
+                        "exception": false
+                    }
+                },
+                {
+                    "instance": "WBTC_1",
+                    "caller": "0xdeadbeef00000000000000000000000000000042",
+                    "method": "approve",
+                    "calldata": [
+                        "Mooniswap.address",
+                        "500000000"
+                    ],
+                    "expected": {
+                        "return_data": [
+                            "0x0000000000000000000000000000000000000000000000000000000000000001"
+                        ],
+                        "events": [
+                            {
+                                "topics": [
+                                    "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
+                                    "0xdeadbeef00000000000000000000000000000042",
+                                    "Mooniswap.address"
+                                ],
+                                "values": [
+                                    "500000000"
+                                ]
+                            }
+                        ],
+                        "exception": false
+                    }
+                },
+                {
+                    "instance": "WBTC_2",
+                    "caller": "0xdeadbeef00000000000000000000000000000042",
+                    "method": "approve",
+                    "calldata": [
+                        "Mooniswap.address",
+                        "500000000"
+                    ],
+                    "expected": {
+                        "return_data": [
+                            "0x0000000000000000000000000000000000000000000000000000000000000001"
+                        ],
+                        "events": [
+                            {
+                                "topics": [
+                                    "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
+                                    "0xdeadbeef00000000000000000000000000000042",
+                                    "Mooniswap.address"
+                                ],
+                                "values": [
+                                    "500000000"
+                                ]
+                            }
+                        ],
+                        "exception": false
+                    }
+                },
+                {
+                    "instance": "Mooniswap",
+                    "caller": "0xdeadbeef00000000000000000000000000000042",
+                    "method": "deposit",
+                    "calldata": [
+                        "0x0000000000000000000000000000000000000000000000000000000000000040",
+                        "0x00000000000000000000000000000000000000000000000000000000000000a0",
+                        "0x0000000000000000000000000000000000000000000000000000000000000002",
+                        "10000000",
+                        "10000000",
+                        "0x0000000000000000000000000000000000000000000000000000000000000002",
+                        "1000000",
+                        "1000000"
+                    ],
+                    "expected": {
+                        "return_data": [
+                            "10000000"
+                        ],
+                        "events": [
+                            {
+                                "topics": [
+                                    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+                                    "0x0000000000000000000000000000000000000000000000000000000000000000",
+                                    "Mooniswap.address"
+                                ],
+                                "values": [
+                                    "1000"
+                                ]
+                            },
+                            {
+                                "topics": [
+                                    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+                                    "0xdeadbeef00000000000000000000000000000042",
+                                    "Mooniswap.address"
+                                ],
+                                "values": [
+                                    "10000000"
+                                ]
+                            },
+                            {
+                                "topics": [
+                                    "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
+                                    "0xdeadbeef00000000000000000000000000000042",
+                                    "Mooniswap.address"
+                                ],
+                                "values": [
+                                    "490000000"
+                                ]
+                            },
+                            {
+                                "topics": [
+                                    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+                                    "0xdeadbeef00000000000000000000000000000042",
+                                    "Mooniswap.address"
+                                ],
+                                "values": [
+                                    "10000000"
+                                ]
+                            },
+                            {
+                                "topics": [
+                                    "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
+                                    "0xdeadbeef00000000000000000000000000000042",
+                                    "Mooniswap.address"
+                                ],
+                                "values": [
+                                    "490000000"
+                                ]
+                            },
+                            {
+                                "topics": [
+                                    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+                                    "0x0000000000000000000000000000000000000000000000000000000000000000",
+                                    "0xdeadbeef00000000000000000000000000000042"
+                                ],
+                                "values": [
+                                    "10000000"
+                                ]
+                            },
+                            {
+                                "topics": [
+                                    "0x2da466a7b24304f47e87fa2e1e5a81b9831ce54fec19055ce277ca2f39ba42c4",
+                                    "0xdeadbeef00000000000000000000000000000042"
+                                ],
+                                "values": [
+                                    "10000000"
+                                ]
+                            }
+                        ],
+                        "exception": false
+                    }
+                },
+                {
+                    "instance": "Mooniswap",
+                    "caller": "0xdeadbeef00000000000000000000000000000042",
+                    "method": "swap",
+                    "calldata": [
+                        "WBTC_1.address",
+                        "WBTC_2.address",
+                        "5000",
+                        "5000",
+                        "0"
+                    ]
+                }
+            ],
+            "expected": {
+                "return_data": [
+                    "5000"
+                ],
+                "events": [
+                    {
+                        "topics": [
+                            "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+                            "0xdeadbeef00000000000000000000000000000042",
+                            "Mooniswap.address"
+                        ],
+                        "values": [
+                            "5000"
+                        ]
+                    },
+                    {
+                        "topics": [
+                            "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
+                            "0xdeadbeef00000000000000000000000000000042",
+                            "Mooniswap.address"
+                        ],
+                        "values": [
+                            "489995000"
+                        ]
+                    }
+                ],
+                "exception": false
+            }
+        }
+    ],
+    "contracts": {
+        "Mooniswap": "Mooniswap.sol:Mooniswap",
+        "WBTC_1": "ERC20/ERC20.sol:ERC20",
+        "WBTC_2": "ERC20/ERC20.sol:ERC20",
+        "VirtualBalance": "Mooniswap.sol:VirtualBalance",
+        "Math": "math/Math.sol:Math"
+    },
+    "libraries": {
+        "Mooniswap.sol": {
+            "VirtualBalance": "VirtualBalance"
+        },
+        "math/Math.sol": {
+            "Math": "Math"
+        }
+    },
+    "group": "Real life"
+}
@@ -0,0 +1,16 @@
+[package]
+name = "revive-dt-common"
+description = "A library containing common concepts that other crates in the workspace can rely on"
+version.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+anyhow = { workspace = true }
+futures = { workspace = true }
+tracing = { workspace = true }
+once_cell = { workspace = true }
+tokio = { workspace = true }
@@ -0,0 +1,225 @@
+//! The alloy crate __requires__ a tokio runtime.
+//! We contain any async rust right here.
+
+use std::{any::Any, panic::AssertUnwindSafe, pin::Pin, thread};
+
+use futures::FutureExt;
+use once_cell::sync::Lazy;
+use tokio::{
+    runtime::Builder,
+    sync::{mpsc::UnboundedSender, oneshot},
+};
+use tracing::Instrument;
+
+/// A blocking async executor.
+///
+/// This struct exposes the abstraction of a blocking async executor. It is a global and static
+/// executor which means that it doesn't require for new instances of it to be created, it's a
+/// singleton and can be accessed by any thread that wants to perform some async computation on the
+/// blocking executor thread.
+///
+/// The API of the blocking executor is created in a way so that it's very natural, simple to use,
+/// and unbounded to specific tasks or return types. The following is an example of using this
+/// executor to drive an async computation:
+///
+/// ```rust
+/// use revive_dt_common::concepts::*;
+///
+/// fn blocking_function() {
+///     let result = BlockingExecutor::execute(async move {
+///         tokio::time::sleep(std::time::Duration::from_secs(1)).await;
+///         0xFFu8
+///     })
+///     .expect("Computation failed");
+///
+///     assert_eq!(result, 0xFF);
+/// }
+/// ```
+///
+/// Users get to pass in their async tasks without needing to worry about putting them in a [`Box`],
+/// [`Pin`], needing to perform down-casting, or the internal channel mechanism used by the runtime.
+/// To the user, it just looks like a function that converts some async code into sync code.
+///
+/// This struct also handled panics that occur in the passed futures and converts them into errors
+/// that can be handled by the user. This is done to allow the executor to be robust.
+///
+/// Internally, the executor communicates with the tokio runtime thread through channels which carry
+/// the [`TaskMessage`] and the results of the execution.
+pub struct BlockingExecutor;
+
+impl BlockingExecutor {
+    pub fn execute<R>(future: impl Future<Output = R> + Send + 'static) -> Result<R, anyhow::Error>
+    where
+        R: Send + 'static,
+    {
+        // Note: The blocking executor is a singleton and therefore we store its state in a static
+        // so that it's assigned only once. Additionally, when we set the state of the executor we
+        // spawn the thread where the async runtime runs.
+        static STATE: Lazy<ExecutorState> = Lazy::new(|| {
+            tracing::trace!("Initializing the BlockingExecutor state");
+
+            // All communication with the tokio runtime thread happens over mspc channels where the
+            // producers here are the threads that want to run async tasks and the consumer here is
+            // the tokio runtime thread.
+            let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel::<TaskMessage>();
+
+            thread::spawn(move || {
+                tracing::info!(
+                    thread_id = ?std::thread::current().id(),
+                    "Starting async runtime thread"
+                );
+
+                let runtime = Builder::new_current_thread()
+                    .enable_all()
+                    .build()
+                    .expect("Failed to create the async runtime");
+
+                runtime.block_on(async move {
+                    while let Some(TaskMessage {
+                        future: task,
+                        response_tx: response_channel,
+                    }) = rx.recv().await
+                    {
+                        tracing::trace!("Received a new future to execute");
+                        tokio::spawn(async move {
+                            // One of the things that the blocking executor does is that it allows
+                            // us to catch panics if they occur. By wrapping the given future in an
+                            // AssertUnwindSafe::catch_unwind we are able to catch all panic unwinds
+                            // in the given future and convert them into errors.
+                            let task = AssertUnwindSafe(task).catch_unwind();
+
+                            let result = task.await;
+                            let _ = response_channel.send(result);
+                        });
+                    }
+                })
+            });
+
+            ExecutorState { tx }
+        });
+
+        // We need to perform blocking synchronous communication between the current thread and the
+        // tokio runtime thread with the result of the async computation and the oneshot channels
+        // from tokio allows us to do that. The sender side of the channel will be given to the
+        // tokio runtime thread to send the result when the computation is completed and the receive
+        // side of the channel will be kept with this thread to await for the response of the async
+        // task to come back.
+        let (response_tx, response_rx) =
+            oneshot::channel::<Result<Box<dyn Any + Send>, Box<dyn Any + Send>>>();
+
+        // The tokio runtime thread expects a Future<Output = Box<dyn Any + Send>> + Send to be
+        // sent to it to execute. However, this function has a typed Future<Output = R> + Send and
+        // therefore we need to change the type of the future to fit what the runtime thread expects
+        // in the task message. In doing this conversion, we lose some of the type information since
+        // we're converting R => dyn Any. However, we will perform down-casting on the result to
+        // convert it back into R.
+        let future = Box::pin(
+            async move { Box::new(future.await) as Box<dyn Any + Send> }.in_current_span(),
+        );
+
+        let task = TaskMessage::new(future, response_tx);
+        if let Err(error) = STATE.tx.send(task) {
+            tracing::error!(?error, "Failed to send the task to the blocking executor");
+            anyhow::bail!("Failed to send the task to the blocking executor: {error:?}")
+        }
+
+        let result = match response_rx.blocking_recv() {
+            Ok(result) => result,
+            Err(error) => {
+                tracing::error!(
+                    ?error,
+                    "Failed to get the response from the blocking executor"
+                );
+                anyhow::bail!("Failed to get the response from the blocking executor: {error:?}")
+            }
+        };
+
+        let result = match result {
+            Ok(result) => result,
+            Err(error) => {
+                tracing::error!(?error, "An error occurred when running the async task");
+                anyhow::bail!("An error occurred when running the async task: {error:?}")
+            }
+        };
+
+        Ok(*result
+            .downcast::<R>()
+            .expect("An error occurred when downcasting into R. This is a bug"))
+    }
+}
+/// Represents the state of the async runtime. This runtime is designed to be a singleton runtime
+/// which means that in the current running program there's just a single thread that has an async
+/// runtime.
+struct ExecutorState {
+    /// The sending side of the task messages channel. This is used by all of the other threads to
+    /// communicate with the async runtime thread.
+    tx: UnboundedSender<TaskMessage>,
+}
+
+/// Represents a message that contains an asynchronous task that's to be executed by the runtime
+/// as well as a way for the runtime to report back on the result of the execution.
+struct TaskMessage {
+    /// The task that's being requested to run. This is a future that returns an object that does
+    /// implement [`Any`] and [`Send`] to allow it to be sent between the requesting thread and the
+    /// async thread.
+    future: Pin<Box<dyn Future<Output = Box<dyn Any + Send>> + Send>>,
+
+    /// A one shot sender channel where the sender of the task is expecting to hear back on the
+    /// result of the task.
+    response_tx: oneshot::Sender<Result<Box<dyn Any + Send>, Box<dyn Any + Send>>>,
+}
+
+impl TaskMessage {
+    pub fn new(
+        future: Pin<Box<dyn Future<Output = Box<dyn Any + Send>> + Send>>,
+        response_tx: oneshot::Sender<Result<Box<dyn Any + Send>, Box<dyn Any + Send>>>,
+    ) -> Self {
+        Self {
+            future,
+            response_tx,
+        }
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    #[test]
+    fn simple_future_works() {
+        // Act
+        let result = BlockingExecutor::execute(async move {
+            tokio::time::sleep(std::time::Duration::from_secs(1)).await;
+            0xFFu8
+        })
+        .unwrap();
+
+        // Assert
+        assert_eq!(result, 0xFFu8);
+    }
+
+    #[test]
+    #[allow(unreachable_code, clippy::unreachable)]
+    fn panics_in_futures_are_caught() {
+        // Act
+        let result = BlockingExecutor::execute(async move {
+            panic!(
+                "If this panic causes, well, a panic, then this is an issue. If it's caught then all good!"
+            );
+            0xFFu8
+        });
+
+        // Assert
+        assert!(result.is_err());
+
+        // Act
+        let result = BlockingExecutor::execute(async move {
+            tokio::time::sleep(std::time::Duration::from_secs(1)).await;
+            0xFFu8
+        })
+        .unwrap();
+
+        // Assert
+        assert_eq!(result, 0xFFu8)
+    }
+}
@@ -0,0 +1,3 @@
+mod blocking_executor;
+
+pub use blocking_executor::*;
@@ -0,0 +1,73 @@
+use std::{borrow::Cow, collections::HashSet, path::PathBuf};
+
+/// An iterator that finds files of a certain extension in the provided directory. You can think of
+/// this a glob pattern similar to: `${path}/**/*.md`
+pub struct FilesWithExtensionIterator {
+    /// The set of allowed extensions that that match the requirement and that should be returned
+    /// when found.
+    allowed_extensions: HashSet<Cow<'static, str>>,
+
+    /// The set of directories to visit next. This iterator does BFS and so these directories will
+    /// only be visited if we can't find any files in our state.
+    directories_to_search: Vec<PathBuf>,
+
+    /// The set of files matching the allowed extensions that were found. If there are entries in
+    /// this vector then they will be returned when the [`Iterator::next`] method is called. If not
+    /// then we visit one of the next directories to visit.
+    files_matching_allowed_extensions: Vec<PathBuf>,
+}
+
+impl FilesWithExtensionIterator {
+    pub fn new(root_directory: PathBuf) -> Self {
+        Self {
+            allowed_extensions: Default::default(),
+            directories_to_search: vec![root_directory],
+            files_matching_allowed_extensions: Default::default(),
+        }
+    }
+
+    pub fn with_allowed_extension(
+        mut self,
+        allowed_extension: impl Into<Cow<'static, str>>,
+    ) -> Self {
+        self.allowed_extensions.insert(allowed_extension.into());
+        self
+    }
+}
+
+impl Iterator for FilesWithExtensionIterator {
+    type Item = PathBuf;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        if let Some(file_path) = self.files_matching_allowed_extensions.pop() {
+            return Some(file_path);
+        };
+
+        let directory_to_search = self.directories_to_search.pop()?;
+
+        // Read all of the entries in the directory. If we failed to read this dir's entires then we
+        // elect to just ignore it and look in the next directory, we do that by calling the next
+        // method again on the iterator, which is an intentional decision that we made here instead
+        // of panicking.
+        let Ok(dir_entries) = std::fs::read_dir(directory_to_search) else {
+            return self.next();
+        };
+
+        for entry in dir_entries.flatten() {
+            let entry_path = entry.path();
+            if entry_path.is_dir() {
+                self.directories_to_search.push(entry_path)
+            } else if entry_path.is_file()
+                && entry_path.extension().is_some_and(|ext| {
+                    self.allowed_extensions
+                        .iter()
+                        .any(|allowed| ext.eq_ignore_ascii_case(allowed.as_ref()))
+                })
+            {
+                self.files_matching_allowed_extensions.push(entry_path)
+            }
+        }
+
+        self.next()
+    }
+}
@@ -0,0 +1,3 @@
+mod files_with_extension_iterator;
+
+pub use files_with_extension_iterator::*;
@@ -0,0 +1,6 @@
+//! This crate provides common concepts, functionality, types, macros, and more that other crates in
+//! the workspace can benefit from.
+
+pub mod concepts;
+pub mod iterators;
+pub mod macros;
@@ -0,0 +1,106 @@
+/// Defines wrappers around types.
+///
+/// For example, the macro invocation seen below:
+///
+/// ```rust,ignore
+/// define_wrapper_type!(CaseId => usize);
+/// ```
+///
+/// Would define a wrapper type that looks like the following:
+///
+/// ```rust,ignore
+/// pub struct CaseId(usize);
+/// ```
+///
+/// And would also implement a number of methods on this type making it easier to use.
+///
+/// These wrapper types become very useful as they make the code a lot easier to read.
+///
+/// Take the following as an example:
+///
+/// ```rust,ignore
+/// struct State {
+///     contracts: HashMap<usize, HashMap<String, Vec<u8>>>
+/// }
+/// ```
+///
+/// In the above code it's hard to understand what the various types refer to or what to expect them
+/// to contain.
+///
+/// With these wrapper types we're able to create code that's self-documenting in that the types
+/// tell us what the code is referring to. The above code is transformed into
+///
+/// ```rust,ignore
+/// struct State {
+///     contracts: HashMap<CaseId, HashMap<ContractName, ContractByteCode>>
+/// }
+/// ```
+///
+/// Note that we follow the same syntax for defining wrapper structs but we do not permit the use of
+/// generics.
+#[macro_export]
+macro_rules! define_wrapper_type {
+    (
+        $(#[$meta: meta])*
+        $vis:vis struct $ident: ident($ty: ty);
+    ) => {
+        $(#[$meta])*
+        $vis struct $ident($ty);
+
+        impl $ident {
+            pub fn new(value: impl Into<$ty>) -> Self {
+                Self(value.into())
+            }
+
+            pub fn into_inner(self) -> $ty {
+                self.0
+            }
+
+            pub fn as_inner(&self) -> &$ty {
+                &self.0
+            }
+        }
+
+        impl AsRef<$ty> for $ident {
+            fn as_ref(&self) -> &$ty {
+                &self.0
+            }
+        }
+
+        impl AsMut<$ty> for $ident {
+            fn as_mut(&mut self) -> &mut $ty {
+                &mut self.0
+            }
+        }
+
+        impl std::ops::Deref for $ident {
+            type Target = $ty;
+
+            fn deref(&self) -> &Self::Target {
+                &self.0
+            }
+        }
+
+        impl std::ops::DerefMut for $ident {
+            fn deref_mut(&mut self) -> &mut Self::Target {
+                &mut self.0
+            }
+        }
+
+        impl From<$ty> for $ident {
+            fn from(value: $ty) -> Self {
+                Self(value)
+            }
+        }
+
+        impl From<$ident> for $ty {
+            fn from(value: $ident) -> Self {
+                value.0
+            }
+        }
+    };
+}
+
+/// Technically not needed but this allows for the macro to be found in the `macros` module of the
+/// crate in addition to being found in the root of the crate.
+pub use define_wrapper_type;
@@ -0,0 +1,3 @@
+mod define_wrapper_type;
+
+pub use define_wrapper_type::*;
@@ -9,8 +9,13 @@ repository.workspace = true
 rust-version.workspace = true

 [dependencies]
-anyhow = { workspace = true }
 revive-solc-json-interface = { workspace = true }
+revive-dt-config = { workspace = true }
+revive-dt-solc-binaries = { workspace = true }
 revive-common = { workspace = true }
+
+alloy-primitives = { workspace = true }
+anyhow = { workspace = true }
 semver = { workspace = true }
 serde_json = { workspace = true }
+tracing = { workspace = true }
@@ -9,6 +9,9 @@ use std::{
    path::{Path, PathBuf},
 };

+use alloy_primitives::Address;
+use revive_dt_config::Arguments;
+
 use revive_common::EVMVersion;
 use revive_solc_json_interface::{
    SolcStandardJsonInput, SolcStandardJsonInputLanguage, SolcStandardJsonInputSettings,
@@ -33,6 +36,8 @@ pub trait SolidityCompiler {
    ) -> anyhow::Result<CompilerOutput<Self::Options>>;

    fn new(solc_executable: PathBuf) -> Self;
+
+    fn get_compiler_executable(config: &Arguments, version: Version) -> anyhow::Result<PathBuf>;
 }

 /// The generic compilation input configuration.
@@ -40,12 +45,19 @@ pub trait SolidityCompiler {
 pub struct CompilerInput<T: PartialEq + Eq + Hash> {
    pub extra_options: T,
    pub input: SolcStandardJsonInput,
+    pub allow_paths: Vec<PathBuf>,
+    pub base_path: Option<PathBuf>,
 }

 /// The generic compilation output configuration.
+#[derive(Debug)]
 pub struct CompilerOutput<T: PartialEq + Eq + Hash> {
+    /// The solc standard JSON input.
    pub input: CompilerInput<T>,
+    /// The produced solc standard JSON output.
    pub output: SolcStandardJsonOutput,
+    /// The error message in case the compiler returns abnormally.
+    pub error: Option<String>,
 }

 impl<T> PartialEq for CompilerInput<T>
@@ -75,8 +87,8 @@ where
 pub struct Compiler<T: SolidityCompiler> {
    input: SolcStandardJsonInput,
    extra_options: T::Options,
-    allow_paths: Vec<String>,
-    base_path: Option<String>,
+    allow_paths: Vec<PathBuf>,
+    base_path: Option<PathBuf>,
 }

 impl Default for Compiler<solc::Solc> {
@@ -106,6 +118,7 @@ where
                        false,
                    ),
                    None,
+                    None,
                ),
            },
            extra_options: Default::default(),
@@ -136,20 +149,47 @@ where
        self
    }

-    pub fn allow_path(mut self, path: String) -> Self {
+    pub fn allow_path(mut self, path: PathBuf) -> Self {
        self.allow_paths.push(path);
        self
    }

-    pub fn base_path(mut self, base_path: String) -> Self {
+    pub fn base_path(mut self, base_path: PathBuf) -> Self {
        self.base_path = Some(base_path);
        self
    }

+    pub fn with_library(
+        mut self,
+        scope: impl AsRef<Path>,
+        library_ident: impl AsRef<str>,
+        library_address: Address,
+    ) -> Self {
+        self.input
+            .settings
+            .libraries
+            .get_or_insert_with(Default::default)
+            .entry(scope.as_ref().display().to_string())
+            .or_default()
+            .insert(
+                library_ident.as_ref().to_owned(),
+                library_address.to_string(),
+            );
+
+        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,
+            allow_paths: self.allow_paths,
+            base_path: self.base_path,
        })
    }
+
+    /// Returns the compiler JSON input.
+    pub fn input(&self) -> SolcStandardJsonInput {
+        self.input.clone()
+    }
 }
@@ -1,2 +1,158 @@
-//! Implements the [crate::SolidityCompiler] trait with resolc for
-//! compiling contracts to PVM bytecode.
+//! Implements the [SolidityCompiler] trait with `resolc` for
+//! compiling contracts to PolkaVM (PVM) bytecode.
+
+use std::{
+    path::PathBuf,
+    process::{Command, Stdio},
+};
+
+use crate::{CompilerInput, CompilerOutput, SolidityCompiler};
+use revive_dt_config::Arguments;
+use revive_solc_json_interface::SolcStandardJsonOutput;
+
+// TODO: I believe that we need to also pass the solc compiler to resolc so that resolc uses the
+// specified solc compiler. I believe that currently we completely ignore the specified solc binary
+// when invoking resolc which doesn't seem right if we're using solc as a compiler frontend.
+
+/// A wrapper around the `resolc` binary, emitting PVM-compatible bytecode.
+#[derive(Debug)]
+pub struct Resolc {
+    /// Path to the `resolc` executable
+    resolc_path: PathBuf,
+}
+
+impl SolidityCompiler for Resolc {
+    type Options = Vec<String>;
+
+    #[tracing::instrument(level = "debug", ret)]
+    fn build(
+        &self,
+        input: CompilerInput<Self::Options>,
+    ) -> anyhow::Result<CompilerOutput<Self::Options>> {
+        let mut command = Command::new(&self.resolc_path);
+        command
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped())
+            .arg("--standard-json");
+
+        if let Some(ref base_path) = input.base_path {
+            command.arg("--base-path").arg(base_path);
+        }
+        if !input.allow_paths.is_empty() {
+            command.arg("--allow-paths").arg(
+                input
+                    .allow_paths
+                    .iter()
+                    .map(|path| path.display().to_string())
+                    .collect::<Vec<_>>()
+                    .join(","),
+            );
+        }
+        let mut child = command.spawn()?;
+
+        let stdin_pipe = child.stdin.as_mut().expect("stdin must be piped");
+        serde_json::to_writer(stdin_pipe, &input.input)?;
+
+        let json_in = serde_json::to_string_pretty(&input.input)?;
+
+        let output = child.wait_with_output()?;
+        let stdout = output.stdout;
+        let stderr = output.stderr;
+
+        if !output.status.success() {
+            let message = String::from_utf8_lossy(&stderr);
+            tracing::error!(
+                "resolc failed exit={} stderr={} JSON-in={} ",
+                output.status,
+                &message,
+                json_in,
+            );
+            return Ok(CompilerOutput {
+                input,
+                output: Default::default(),
+                error: Some(message.into()),
+            });
+        }
+
+        let mut parsed =
+            serde_json::from_slice::<SolcStandardJsonOutput>(&stdout).map_err(|e| {
+                anyhow::anyhow!(
+                    "failed to parse resolc JSON output: {e}\nstderr: {}",
+                    String::from_utf8_lossy(&stderr)
+                )
+            })?;
+
+        // Detecting if the compiler output contained errors and reporting them through logs and
+        // errors instead of returning the compiler output that might contain errors.
+        for error in parsed.errors.iter().flatten() {
+            if error.severity == "error" {
+                tracing::error!(?error, ?input, "Encountered an error in the compilation");
+                anyhow::bail!("Encountered an error in the compilation: {error}")
+            }
+        }
+
+        // We need to do some post processing on the output to make it in the same format that solc
+        // outputs. More specifically, for each contract, the `.metadata` field should be replaced
+        // with the `.metadata.solc_metadata` field which contains the ABI and other information
+        // about the compiled contracts. We do this because we do not want any downstream logic to
+        // need to differentiate between which compiler is being used when extracting the ABI of the
+        // contracts.
+        if let Some(ref mut contracts) = parsed.contracts {
+            for (contract_path, contracts_map) in contracts.iter_mut() {
+                for (contract_name, contract_info) in contracts_map.iter_mut() {
+                    let Some(metadata) = contract_info.metadata.take() else {
+                        continue;
+                    };
+
+                    // Get the `solc_metadata` in the metadata of the contract.
+                    let Some(solc_metadata) = metadata
+                        .get("solc_metadata")
+                        .and_then(|metadata| metadata.as_str())
+                    else {
+                        tracing::error!(
+                            contract_path,
+                            contract_name,
+                            metadata = serde_json::to_string(&metadata).unwrap(),
+                            "Encountered a contract compiled with resolc that has no solc_metadata"
+                        );
+                        anyhow::bail!(
+                            "Contract {} compiled with resolc that has no solc_metadata",
+                            contract_name
+                        );
+                    };
+
+                    // Replace the original metadata with the new solc_metadata.
+                    contract_info.metadata =
+                        Some(serde_json::Value::String(solc_metadata.to_string()));
+                }
+            }
+        }
+
+        tracing::debug!(
+            output = %serde_json::to_string(&parsed).unwrap(),
+            "Compiled successfully"
+        );
+
+        Ok(CompilerOutput {
+            input,
+            output: parsed,
+            error: None,
+        })
+    }
+
+    fn new(resolc_path: PathBuf) -> Self {
+        Resolc { resolc_path }
+    }
+
+    fn get_compiler_executable(
+        config: &Arguments,
+        _version: semver::Version,
+    ) -> anyhow::Result<PathBuf> {
+        if !config.resolc.as_os_str().is_empty() {
+            return Ok(config.resolc.clone());
+        }
+
+        Ok(PathBuf::from("resolc"))
+    }
+}
@@ -7,7 +7,11 @@ use std::{
 };

 use crate::{CompilerInput, CompilerOutput, SolidityCompiler};
+use revive_dt_config::Arguments;
+use revive_dt_solc_binaries::download_solc;
+use revive_solc_json_interface::SolcStandardJsonOutput;

+#[derive(Debug)]
 pub struct Solc {
    solc_path: PathBuf,
 }
@@ -15,28 +19,85 @@ pub struct Solc {
 impl SolidityCompiler for Solc {
    type Options = ();

+    #[tracing::instrument(level = "debug", ret)]
    fn build(
        &self,
        input: CompilerInput<Self::Options>,
    ) -> anyhow::Result<CompilerOutput<Self::Options>> {
-        let mut child = Command::new(&self.solc_path)
+        let mut command = Command::new(&self.solc_path);
+        command
            .stdin(Stdio::piped())
            .stdout(Stdio::piped())
            .stderr(Stdio::piped())
-            .arg("--standard-json")
-            .spawn()?;
+            .arg("--standard-json");
+
+        if let Some(ref base_path) = input.base_path {
+            command.arg("--base-path").arg(base_path);
+        }
+        if !input.allow_paths.is_empty() {
+            command.arg("--allow-paths").arg(
+                input
+                    .allow_paths
+                    .iter()
+                    .map(|path| path.display().to_string())
+                    .collect::<Vec<_>>()
+                    .join(","),
+            );
+        }
+        let mut child = command.spawn()?;

        let stdin = child.stdin.as_mut().expect("should be piped");
        serde_json::to_writer(stdin, &input.input)?;
+        let output = child.wait_with_output()?;
+
+        if !output.status.success() {
+            let message = String::from_utf8_lossy(&output.stderr);
+            tracing::error!("solc failed exit={} stderr={}", output.status, &message);
+            return Ok(CompilerOutput {
+                input,
+                output: Default::default(),
+                error: Some(message.into()),
+            });
+        }
+
+        let parsed =
+            serde_json::from_slice::<SolcStandardJsonOutput>(&output.stdout).map_err(|e| {
+                anyhow::anyhow!(
+                    "failed to parse resolc JSON output: {e}\nstderr: {}",
+                    String::from_utf8_lossy(&output.stdout)
+                )
+            })?;
+
+        // Detecting if the compiler output contained errors and reporting them through logs and
+        // errors instead of returning the compiler output that might contain errors.
+        for error in parsed.errors.iter().flatten() {
+            if error.severity == "error" {
+                tracing::error!(?error, ?input, "Encountered an error in the compilation");
+                anyhow::bail!("Encountered an error in the compilation: {error}")
+            }
+        }
+
+        tracing::debug!(
+            output = %String::from_utf8_lossy(&output.stdout).to_string(),
+            "Compiled successfully"
+        );

-        let output = child.wait_with_output()?.stdout;
        Ok(CompilerOutput {
            input,
-            output: serde_json::from_slice(&output)?,
+            output: parsed,
+            error: None,
        })
    }

    fn new(solc_path: PathBuf) -> Self {
        Self { solc_path }
    }
+
+    fn get_compiler_executable(
+        config: &Arguments,
+        version: semver::Version,
+    ) -> anyhow::Result<PathBuf> {
+        let path = download_solc(config.directory(), version, config.wasm)?;
+        Ok(path)
+    }
 }
@@ -13,3 +13,5 @@ alloy = { workspace = true }
 clap = { workspace = true }
 semver = { workspace = true }
 temp-dir = { workspace = true }
+serde = { workspace = true }
+
@@ -1,13 +1,17 @@
-//! The global configuration used accross all revive differential testing crates.
+//! The global configuration used across all revive differential testing crates.

-use std::path::{Path, PathBuf};
+use std::{
+    fmt::Display,
+    path::{Path, PathBuf},
+};

 use alloy::{network::EthereumWallet, signers::local::PrivateKeySigner};
 use clap::{Parser, ValueEnum};
 use semver::Version;
+use serde::{Deserialize, Serialize};
 use temp_dir::TempDir;

-#[derive(Debug, Parser, Clone)]
+#[derive(Debug, Parser, Clone, Serialize, Deserialize)]
 #[command(name = "retester")]
 pub struct Arguments {
    /// The `solc` version to use if the test didn't specify it explicitly.
@@ -40,6 +44,7 @@ pub struct Arguments {
    ///
    /// We attach it here because [TempDir] prunes itself on drop.
    #[clap(skip)]
+    #[serde(skip)]
    pub temp_dir: Option<&'static TempDir>,

    /// The path to the `geth` executable.
@@ -68,6 +73,12 @@ pub struct Arguments {
    )]
    pub account: String,

+    /// This argument controls which private keys the nodes should have access to and be added to
+    /// its wallet signers. With a value of N, private keys (0, N] will be added to the signer set
+    /// of the node.
+    #[arg(long = "private-keys-count", default_value_t = 30)]
+    pub private_keys_to_add: usize,
+
    /// The differential testing leader node implementation.
    #[arg(short, long = "leader", default_value = "geth")]
    pub leader: TestingPlatform,
@@ -83,6 +94,22 @@ pub struct Arguments {
    /// Determines the amount of tests that are executed in parallel.
    #[arg(long = "workers", default_value = "12")]
    pub workers: usize,
+
+    /// Extract problems back to the test corpus.
+    #[arg(short, long = "extract-problems")]
+    pub extract_problems: bool,
+
+    /// The path to the `kitchensink` executable.
+    ///
+    /// By default it uses `substrate-node` binary found in `$PATH`.
+    #[arg(short, long = "kitchensink", default_value = "substrate-node")]
+    pub kitchensink: PathBuf,
+
+    /// The path to the `eth_proxy` executable.
+    ///
+    /// By default it uses `eth-rpc` binary found in `$PATH`.
+    #[arg(short = 'p', long = "eth_proxy", default_value = "eth-rpc")]
+    pub eth_proxy: PathBuf,
 }

 impl Arguments {
@@ -124,7 +151,7 @@ impl Default for Arguments {
 /// The Solidity compatible node implementation.
 ///
 /// This describes the solutions to be tested against on a high level.
-#[derive(Clone, Debug, Eq, Hash, PartialEq, ValueEnum)]
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, ValueEnum, Serialize, Deserialize)]
 #[clap(rename_all = "lower")]
 pub enum TestingPlatform {
    /// The go-ethereum reference full node EVM implementation.
@@ -132,3 +159,12 @@ pub enum TestingPlatform {
    /// The kitchensink runtime provides the PolkaVM (PVM) based node implentation.
    Kitchensink,
 }
+
+impl Display for TestingPlatform {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Geth => f.write_str("geth"),
+            Self::Kitchensink => f.write_str("revive"),
+        }
+    }
+}
@@ -13,21 +13,21 @@ name = "retester"
 path = "src/main.rs"

 [dependencies]
+revive-dt-common = { workspace = true }
 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 }
+revive-dt-report = { workspace = true }

 alloy = { workspace = true }
 anyhow = { workspace = true }
 clap = { workspace = true }
-log = { workspace = true }
-env_logger = { workspace = true }
+indexmap = { workspace = true }
+tracing = { workspace = true }
+tracing-subscriber = { 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 }
@@ -1,10 +1,12 @@
 //! The revive differential testing core library.
 //!
 //! This crate defines the testing configuration and
-//! provides a helper utilty to execute tests.
+//! provides a helper utility to execute tests.

-use revive_dt_compiler::{SolidityCompiler, solc};
-use revive_dt_node::geth;
+use revive_dt_compiler::{SolidityCompiler, revive_resolc, solc};
+use revive_dt_config::TestingPlatform;
+use revive_dt_format::traits::ResolverApi;
+use revive_dt_node::{Node, geth, kitchensink::KitchensinkNode};
 use revive_dt_node_interaction::EthereumNode;

 pub mod driver;
@@ -13,8 +15,11 @@ pub mod driver;
 ///
 /// For this we need a blockchain node implementation and a compiler.
 pub trait Platform {
-    type Blockchain: EthereumNode;
+    type Blockchain: EthereumNode + Node + ResolverApi;
    type Compiler: SolidityCompiler;
+
+    /// Returns the matching [TestingPlatform] of the [revive_dt_config::Arguments].
+    fn config_id() -> TestingPlatform;
 }

 #[derive(Default)]
@@ -23,12 +28,20 @@ pub struct Geth;
 impl Platform for Geth {
    type Blockchain = geth::Instance;
    type Compiler = solc::Solc;
+
+    fn config_id() -> TestingPlatform {
+        TestingPlatform::Geth
+    }
 }

 #[derive(Default)]
 pub struct Kitchensink;

 impl Platform for Kitchensink {
-    type Blockchain = geth::Instance;
-    type Compiler = solc::Solc;
+    type Blockchain = KitchensinkNode;
+    type Compiler = revive_resolc::Resolc;
+
+    fn config_id() -> TestingPlatform {
+        TestingPlatform::Kitchensink
+    }
 }
@@ -5,117 +5,174 @@ use rayon::{ThreadPoolBuilder, prelude::*};

 use revive_dt_config::*;
 use revive_dt_core::{
-    Geth,
+    Geth, Kitchensink, Platform,
    driver::{Driver, State},
 };
-use revive_dt_format::{corpus::Corpus, metadata::Metadata};
+use revive_dt_format::{corpus::Corpus, metadata::MetadataFile};
 use revive_dt_node::pool::NodePool;
+use revive_dt_report::reporter::{Report, Span};
 use temp_dir::TempDir;
+use tracing::Level;
+use tracing_subscriber::{EnvFilter, FmtSubscriber};

 static TEMP_DIR: LazyLock<TempDir> = LazyLock::new(|| TempDir::new().unwrap());

 fn main() -> anyhow::Result<()> {
    let args = init_cli()?;

-    let corpora = collect_corpora(&args)?;
+    for (corpus, tests) in collect_corpora(&args)? {
+        let span = Span::new(corpus, args.clone())?;

-    if let Some(platform) = &args.compile_only {
-        for tests in corpora.values() {
-            main_compile_only(&args, tests, platform)?;
+        match &args.compile_only {
+            Some(platform) => compile_corpus(&args, &tests, platform, span),
+            None => execute_corpus(&args, &tests, span)?,
        }

-        return Ok(());
-    }
-
-    for tests in corpora.values() {
-        main_execute_differential(&args, tests)?;
+        Report::save()?;
    }

    Ok(())
 }

 fn init_cli() -> anyhow::Result<Arguments> {
-    env_logger::init();
+    let subscriber = FmtSubscriber::builder()
+        .with_thread_ids(true)
+        .with_thread_names(true)
+        .with_env_filter(EnvFilter::from_default_env())
+        .with_ansi(false)
+        .pretty()
+        .finish();
+    tracing::subscriber::set_global_default(subscriber)?;

    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);
+
+    match args.working_directory.as_ref() {
+        Some(dir) => {
+            if !dir.exists() {
+                anyhow::bail!("workdir {} does not exist", dir.display());
+            }
+        }
+        None => {
+            args.temp_dir = Some(&TEMP_DIR);
+        }
    }
+    tracing::info!("workdir: {}", args.directory().display());

    ThreadPoolBuilder::new()
        .num_threads(args.workers)
-        .build_global()
-        .unwrap();
+        .build_global()?;

    Ok(args)
 }

-fn collect_corpora(args: &Arguments) -> anyhow::Result<HashMap<Corpus, Vec<Metadata>>> {
+fn collect_corpora(args: &Arguments) -> anyhow::Result<HashMap<Corpus, Vec<MetadataFile>>> {
    let mut corpora = HashMap::new();

    for path in &args.corpus {
        let corpus = Corpus::try_from_path(path)?;
-        log::info!("found corpus: {}", path.display());
+        tracing::info!("found corpus: {}", path.display());
        let tests = corpus.enumerate_tests();
-        log::info!("corpus '{}' contains {} tests", &corpus.name, tests.len());
+        tracing::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)?;
+fn run_driver<L, F>(args: &Arguments, tests: &[MetadataFile], span: Span) -> anyhow::Result<()>
+where
+    L: Platform,
+    F: Platform,
+    L::Blockchain: revive_dt_node::Node + Send + Sync + 'static,
+    F::Blockchain: revive_dt_node::Node + Send + Sync + 'static,
+{
+    let leader_nodes = NodePool::<L::Blockchain>::new(args)?;
+    let follower_nodes = NodePool::<F::Blockchain>::new(args)?;

-    tests.par_iter().for_each(|metadata| {
-        let mut driver = match (&args.leader, &args.follower) {
-            (TestingPlatform::Geth, TestingPlatform::Kitchensink) => Driver::<Geth, Geth>::new(
+    tests.par_iter().for_each(
+        |MetadataFile {
+             content: metadata,
+             path: metadata_file_path,
+         }| {
+            // Starting a new tracing span for this metadata file. This allows our logs to be clear
+            // about which metadata file the logs belong to. We can add other information into this
+            // as well to be able to associate the logs with the correct metadata file and case
+            // that's being executed.
+            let tracing_span = tracing::span!(
+                Level::INFO,
+                "Running driver",
+                metadata_file_path = metadata_file_path.display().to_string(),
+            );
+            let _guard = tracing_span.enter();
+
+            let mut driver = Driver::<L, F>::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
+            let execution_result = driver.execute(span);
+            tracing::info!(
+                case_success_count = execution_result.successful_cases_count,
+                case_failure_count = execution_result.failed_cases_count,
+                "Execution completed"
+            );
+
+            let mut error_count = 0;
+            for result in execution_result.results.iter() {
+                if !result.is_success() {
+                    tracing::error!(execution_error = ?result, "Encountered an error");
+                    error_count += 1;
+                }
            }
-            Err(error) => {
-                log::warn!(
-                    "metadata {} failure: {error:?}",
-                    metadata.file_path.as_ref().unwrap().display()
-                );
+            if error_count == 0 {
+                tracing::info!("Execution succeeded");
+            } else {
+                tracing::info!("Execution failed");
            }
-        }
-    });
+        },
+    );

    Ok(())
 }

-fn main_compile_only(
+fn execute_corpus(args: &Arguments, tests: &[MetadataFile], span: Span) -> anyhow::Result<()> {
+    match (&args.leader, &args.follower) {
+        (TestingPlatform::Geth, TestingPlatform::Kitchensink) => {
+            run_driver::<Geth, Kitchensink>(args, tests, span)?
+        }
+        (TestingPlatform::Geth, TestingPlatform::Geth) => {
+            run_driver::<Geth, Geth>(args, tests, span)?
+        }
+        _ => unimplemented!(),
+    }
+
+    Ok(())
+}
+
+fn compile_corpus(
    config: &Arguments,
-    tests: &[Metadata],
+    tests: &[MetadataFile],
    platform: &TestingPlatform,
-) -> anyhow::Result<()> {
+    span: Span,
+) {
    tests.par_iter().for_each(|metadata| {
        for mode in &metadata.solc_modes() {
-            let mut state = match platform {
-                TestingPlatform::Geth => State::<Geth>::new(config),
-                _ => todo!(),
+            match platform {
+                TestingPlatform::Geth => {
+                    let mut state = State::<Geth>::new(config, span);
+                    let _ = state.build_contracts(mode, metadata);
+                }
+                TestingPlatform::Kitchensink => {
+                    let mut state = State::<Kitchensink>::new(config, span);
+                    let _ = state.build_contracts(mode, metadata);
+                }
            };
-            let _ = state.build_contracts(mode, metadata);
        }
    });
-
-    Ok(())
 }
@@ -9,9 +9,13 @@ repository.workspace = true
 rust-version.workspace = true

 [dependencies]
+revive-dt-common = { workspace = true }
+
 alloy = { workspace = true }
+alloy-primitives = { workspace = true }
+alloy-sol-types = { workspace = true }
 anyhow = { workspace = true }
-log = { workspace = true }
+tracing = { workspace = true }
 semver = { workspace = true }
-serde = { workspace = true, features = [ "derive" ] }
+serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
@@ -1,6 +1,11 @@
 use serde::Deserialize;

-use crate::{input::Input, mode::Mode};
+use revive_dt_common::macros::define_wrapper_type;
+
+use crate::{
+    input::{Expected, Input},
+    mode::Mode,
+};

 #[derive(Debug, Default, Deserialize, Clone, Eq, PartialEq)]
 pub struct Case {
@@ -9,4 +14,37 @@ pub struct Case {
    pub modes: Option<Vec<Mode>>,
    pub inputs: Vec<Input>,
    pub group: Option<String>,
+    pub expected: Option<Expected>,
 }
+
+impl Case {
+    pub fn inputs_iterator(&self) -> impl Iterator<Item = Input> {
+        let inputs_len = self.inputs.len();
+        self.inputs
+            .clone()
+            .into_iter()
+            .enumerate()
+            .map(move |(idx, mut input)| {
+                if idx + 1 == inputs_len {
+                    if input.expected.is_none() {
+                        input.expected = self.expected.clone();
+                    }
+
+                    // TODO: What does it mean for us to have an `expected` field on the case itself
+                    // but the final input also has an expected field that doesn't match the one on
+                    // the case? What are we supposed to do with that final expected field on the
+                    // case?
+
+                    input
+                } else {
+                    input
+                }
+            })
+    }
+}
+
+define_wrapper_type!(
+    /// A wrapper type for the index of test cases found in metadata file.
+    #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+    pub struct CaseIdx(usize);
+);
@@ -3,11 +3,11 @@ use std::{
    path::{Path, PathBuf},
 };

-use serde::Deserialize;
+use serde::{Deserialize, Serialize};

-use crate::metadata::Metadata;
+use crate::metadata::MetadataFile;

-#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Hash)]
+#[derive(Clone, Debug, Default, Serialize, Deserialize, Eq, PartialEq, Hash)]
 pub struct Corpus {
    pub name: String,
    pub path: PathBuf,
@@ -21,7 +21,7 @@ impl Corpus {
    }

    /// Scan the corpus base directory and return all tests found.
-    pub fn enumerate_tests(&self) -> Vec<Metadata> {
+    pub fn enumerate_tests(&self) -> Vec<MetadataFile> {
        let mut tests = Vec::new();
        collect_metadata(&self.path, &mut tests);
        tests
@@ -34,11 +34,11 @@ impl Corpus {
 /// Found tests are inserted into `tests`.
 ///
 /// `path` is expected to be a directory.
-pub fn collect_metadata(path: &Path, tests: &mut Vec<Metadata>) {
+pub fn collect_metadata(path: &Path, tests: &mut Vec<MetadataFile>) {
    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());
+            tracing::error!("failed to read dir '{}': {error}", path.display());
            return;
        }
    };
@@ -47,7 +47,7 @@ pub fn collect_metadata(path: &Path, tests: &mut Vec<Metadata>) {
        let entry = match entry {
            Ok(entry) => entry,
            Err(error) => {
-                log::error!("error reading dir entry: {error}");
+                tracing::error!("error reading dir entry: {error}");
                continue;
            }
        };
@@ -59,7 +59,7 @@ pub fn collect_metadata(path: &Path, tests: &mut Vec<Metadata>) {
        }

        if path.is_file() {
-            if let Some(metadata) = Metadata::try_from_file(&path) {
+            if let Some(metadata) = MetadataFile::try_from_file(&path) {
                tests.push(metadata)
            }
        }
@@ -5,3 +5,4 @@ pub mod corpus;
 pub mod input;
 pub mod metadata;
 pub mod mode;
+pub mod traits;
@@ -1,10 +1,15 @@
 use std::{
    collections::BTreeMap,
+    fmt::Display,
    fs::{File, read_to_string},
+    ops::Deref,
    path::{Path, PathBuf},
+    str::FromStr,
 };

-use serde::Deserialize;
+use serde::{Deserialize, Serialize};
+
+use revive_dt_common::macros::define_wrapper_type;

 use crate::{
    case::Case,
@@ -15,11 +20,36 @@ 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 MetadataFile {
+    pub path: PathBuf,
+    pub content: Metadata,
+}
+
+impl MetadataFile {
+    pub fn try_from_file(path: &Path) -> Option<Self> {
+        Metadata::try_from_file(path).map(|metadata| Self {
+            path: path.to_owned(),
+            content: metadata,
+        })
+    }
+}
+
+impl Deref for MetadataFile {
+    type Target = Metadata;
+
+    fn deref(&self) -> &Self::Target {
+        &self.content
+    }
+}
+
 #[derive(Debug, Default, Deserialize, Clone, Eq, PartialEq)]
 pub struct Metadata {
+    pub targets: Option<Vec<String>>,
    pub cases: Vec<Case>,
-    pub contracts: Option<BTreeMap<String, String>>,
-    pub libraries: Option<BTreeMap<String, BTreeMap<String, String>>>,
+    pub contracts: Option<BTreeMap<ContractInstance, ContractPathAndIdent>>,
+    // TODO: Convert into wrapper types for clarity.
+    pub libraries: Option<BTreeMap<PathBuf, BTreeMap<ContractIdent, ContractInstance>>>,
    pub ignore: Option<bool>,
    pub modes: Option<Vec<Mode>>,
    pub file_path: Option<PathBuf>,
@@ -35,7 +65,7 @@ impl Metadata {
            .filter_map(|mode| match mode {
                Mode::Solidity(solc_mode) => Some(solc_mode),
                Mode::Unknown(mode) => {
-                    log::debug!("compiler: ignoring unknown mode '{mode}'");
+                    tracing::debug!("compiler: ignoring unknown mode '{mode}'");
                    None
                }
            })
@@ -53,28 +83,35 @@ impl Metadata {
            .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)>> {
+    /// Returns the contract sources with canonicalized paths for the files
+    pub fn contract_sources(
+        &self,
+    ) -> anyhow::Result<BTreeMap<ContractInstance, ContractPathAndIdent>> {
        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());
-            }
+        for (
+            alias,
+            ContractPathAndIdent {
+                contract_source_path,
+                contract_ident,
+            },
+        ) in contracts
+        {
+            let alias = alias.clone();
+            let absolute_path = directory.join(contract_source_path).canonicalize()?;
+            let contract_ident = contract_ident.clone();

-            sources.insert(id.clone(), (file, contract_name.to_string()));
+            sources.insert(
+                alias,
+                ContractPathAndIdent {
+                    contract_source_path: absolute_path,
+                    contract_ident,
+                },
+            );
        }

        Ok(sources)
@@ -90,7 +127,7 @@ impl Metadata {
        assert!(path.is_file(), "not a file: {}", path.display());

        let Some(file_extension) = path.extension() else {
-            log::debug!("skipping corpus file: {}", path.display());
+            tracing::debug!("skipping corpus file: {}", path.display());
            return None;
        };

@@ -102,14 +139,14 @@ impl Metadata {
            return Self::try_from_solidity(path);
        }

-        log::debug!("ignoring invalid corpus file: {}", path.display());
+        tracing::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!(
+                tracing::error!(
                    "opening JSON test metadata file '{}' error: {error}",
                    path.display()
                );
@@ -122,7 +159,7 @@ impl Metadata {
                Some(metadata)
            }
            Err(error) => {
-                log::error!(
+                tracing::error!(
                    "parsing JSON test metadata file '{}' error: {error}",
                    path.display()
                );
@@ -132,9 +169,9 @@ impl Metadata {
    }

    fn try_from_solidity(path: &Path) -> Option<Self> {
-        let buf = read_to_string(path)
+        let spec = read_to_string(path)
            .inspect_err(|error| {
-                log::error!(
+                tracing::error!(
                    "opening JSON test metadata file '{}' error: {error}",
                    path.display()
                );
@@ -147,18 +184,28 @@ impl Metadata {
                buf
            });

-        if buf.is_empty() {
+        if spec.is_empty() {
            return None;
        }

-        match serde_json::from_str::<Self>(&buf) {
+        match serde_json::from_str::<Self>(&spec) {
            Ok(mut metadata) => {
                metadata.file_path = Some(path.to_path_buf());
+                metadata.contracts = Some(
+                    [(
+                        ContractInstance::new("test"),
+                        ContractPathAndIdent {
+                            contract_source_path: path.to_path_buf(),
+                            contract_ident: ContractIdent::new("Test"),
+                        },
+                    )]
+                    .into(),
+                );
                Some(metadata)
            }
            Err(error) => {
-                log::error!(
-                    "parsing Solidity test metadata file '{}' error: {error}",
+                tracing::error!(
+                    "parsing Solidity test metadata file '{}' error: '{error}' from data: {spec}",
                    path.display()
                );
                None
@@ -166,3 +213,143 @@ impl Metadata {
        }
    }
 }
+
+define_wrapper_type!(
+    /// Represents a contract instance found a metadata file.
+    ///
+    /// Typically, this is used as the key to the "contracts" field of metadata files.
+    #[derive(
+        Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize,
+    )]
+    #[serde(transparent)]
+    pub struct ContractInstance(String);
+);
+
+define_wrapper_type!(
+    /// Represents a contract identifier found a metadata file.
+    ///
+    /// A contract identifier is the name of the contract in the source code.
+    #[derive(
+        Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize,
+    )]
+    #[serde(transparent)]
+    pub struct ContractIdent(String);
+);
+
+/// Represents an identifier used for contracts.
+///
+/// The type supports serialization from and into the following string format:
+///
+/// ```text
+/// ${path}:${contract_ident}
+/// ```
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(try_from = "String", into = "String")]
+pub struct ContractPathAndIdent {
+    /// The path of the contract source code relative to the directory containing the metadata file.
+    pub contract_source_path: PathBuf,
+
+    /// The identifier of the contract.
+    pub contract_ident: ContractIdent,
+}
+
+impl Display for ContractPathAndIdent {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "{}:{}",
+            self.contract_source_path.display(),
+            self.contract_ident.as_ref()
+        )
+    }
+}
+
+impl FromStr for ContractPathAndIdent {
+    type Err = anyhow::Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let mut splitted_string = s.split(":").peekable();
+        let mut path = None::<String>;
+        let mut identifier = None::<String>;
+        loop {
+            let Some(next_item) = splitted_string.next() else {
+                break;
+            };
+            if splitted_string.peek().is_some() {
+                match path {
+                    Some(ref mut path) => {
+                        path.push(':');
+                        path.push_str(next_item);
+                    }
+                    None => path = Some(next_item.to_owned()),
+                }
+            } else {
+                identifier = Some(next_item.to_owned())
+            }
+        }
+        let Some(path) = path else {
+            anyhow::bail!("Path is not defined");
+        };
+        let Some(identifier) = identifier else {
+            anyhow::bail!("Contract identifier is not defined")
+        };
+        Ok(Self {
+            contract_source_path: PathBuf::from(path),
+            contract_ident: ContractIdent::new(identifier),
+        })
+    }
+}
+
+impl TryFrom<String> for ContractPathAndIdent {
+    type Error = anyhow::Error;
+
+    fn try_from(value: String) -> Result<Self, Self::Error> {
+        Self::from_str(&value)
+    }
+}
+
+impl From<ContractPathAndIdent> for String {
+    fn from(value: ContractPathAndIdent) -> Self {
+        value.to_string()
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    #[test]
+    fn contract_identifier_respects_roundtrip_property() {
+        // Arrange
+        let string = "ERC20/ERC20.sol:ERC20";
+
+        // Act
+        let identifier = ContractPathAndIdent::from_str(string);
+
+        // Assert
+        let identifier = identifier.expect("Failed to parse");
+        assert_eq!(
+            identifier.contract_source_path.display().to_string(),
+            "ERC20/ERC20.sol"
+        );
+        assert_eq!(identifier.contract_ident, "ERC20".to_owned().into());
+
+        // Act
+        let reserialized = identifier.to_string();
+
+        // Assert
+        assert_eq!(string, reserialized);
+    }
+
+    #[test]
+    fn complex_metadata_file_can_be_deserialized() {
+        // Arrange
+        const JSON: &str = include_str!("../../../assets/test_metadata.json");
+
+        // Act
+        let metadata = serde_json::from_str::<Metadata>(JSON);
+
+        // Assert
+        metadata.expect("Failed to deserialize metadata");
+    }
+}
@@ -1,16 +1,16 @@
 use semver::Version;
-use serde::Deserialize;
 use serde::de::Deserializer;
+use serde::{Deserialize, Serialize};

 /// Specifies the compilation mode of the test artifact.
-#[derive(Debug, Clone, Eq, PartialEq)]
+#[derive(Hash, Debug, Clone, Eq, PartialEq)]
 pub enum Mode {
    Solidity(SolcMode),
    Unknown(String),
 }

 /// Specify Solidity specific compiler options.
-#[derive(Debug, Default, Clone, Eq, PartialEq)]
+#[derive(Hash, Debug, Default, Clone, Eq, PartialEq, Serialize, Deserialize)]
 pub struct SolcMode {
    pub solc_version: Option<semver::VersionReq>,
    solc_optimize: Option<bool>,
@@ -0,0 +1,30 @@
+use alloy::eips::BlockNumberOrTag;
+use alloy::primitives::{Address, BlockHash, BlockNumber, BlockTimestamp, ChainId, U256};
+use anyhow::Result;
+
+/// A trait of the interface are required to implement to be used by the resolution logic that this
+/// crate implements to go from string calldata and into the bytes calldata.
+pub trait ResolverApi {
+    /// Returns the ID of the chain that the node is on.
+    fn chain_id(&self) -> Result<ChainId>;
+
+    // TODO: This is currently a u128 due to Kitchensink needing more than 64 bits for its gas limit
+    // when we implement the changes to the gas we need to adjust this to be a u64.
+    /// Returns the gas limit of the specified block.
+    fn block_gas_limit(&self, number: BlockNumberOrTag) -> Result<u128>;
+
+    /// Returns the coinbase of the specified block.
+    fn block_coinbase(&self, number: BlockNumberOrTag) -> Result<Address>;
+
+    /// Returns the difficulty of the specified block.
+    fn block_difficulty(&self, number: BlockNumberOrTag) -> Result<U256>;
+
+    /// Returns the hash of the specified block.
+    fn block_hash(&self, number: BlockNumberOrTag) -> Result<BlockHash>;
+
+    /// Returns the timestamp of the specified block,
+    fn block_timestamp(&self, number: BlockNumberOrTag) -> Result<BlockTimestamp>;
+
+    /// Returns the number of the last block.
+    fn last_block_number(&self) -> Result<BlockNumber>;
+}
@@ -11,8 +11,3 @@ 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 }
@@ -1,21 +1,21 @@
 //! This crate implements all node interactions.

-use alloy::rpc::types::trace::geth::GethTrace;
+use alloy::rpc::types::trace::geth::{DiffMode, GethDebugTracingOptions, GethTrace};
 use alloy::rpc::types::{TransactionReceipt, TransactionRequest};
-use tokio_runtime::TO_TOKIO;
-
-mod tokio_runtime;
-pub mod trace;
-pub mod transaction;
+use anyhow::Result;

 /// 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>;
+    fn execute_transaction(&self, transaction: TransactionRequest) -> Result<TransactionReceipt>;

    /// Trace the transaction in the [TransactionReceipt] and return a [GethTrace].
-    fn trace_transaction(&self, transaction: TransactionReceipt) -> anyhow::Result<GethTrace>;
+    fn trace_transaction(
+        &self,
+        receipt: &TransactionReceipt,
+        trace_options: GethDebugTracingOptions,
+    ) -> Result<GethTrace>;
+
+    /// Returns the state diff of the transaction hash in the [TransactionReceipt].
+    fn state_diff(&self, receipt: &TransactionReceipt) -> Result<DiffMode>;
 }
@@ -1,79 +0,0 @@
-//! 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(())
-}
@@ -1,43 +0,0 @@
-//! 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}"))
-}
@@ -1,46 +0,0 @@
-//! 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}"))
-}
@@ -11,11 +11,20 @@ rust-version.workspace = true
 [dependencies]
 anyhow = { workspace = true }
 alloy = { workspace = true }
-log = { workspace = true }
+tracing = { workspace = true }
+tokio = { workspace = true }
+
+revive-dt-common = { workspace = true }
+revive-dt-config = { workspace = true }
+revive-dt-format = { workspace = true }
+revive-dt-node-interaction = { workspace = true }
+
+serde = { workspace = true }
 serde_json = { workspace = true }

-revive-dt-node-interaction = { workspace = true }
-revive-dt-config = { workspace = true }
+sp-core = { workspace = true }
+sp-runtime = { workspace = true }

 [dev-dependencies]
 temp-dir = { workspace = true }
+tokio = { workspace = true }
@@ -0,0 +1,78 @@
+use alloy::{
+    network::{Network, TransactionBuilder},
+    providers::{
+        Provider, SendableTx,
+        fillers::{GasFiller, TxFiller},
+    },
+    transports::TransportResult,
+};
+
+#[derive(Clone, Debug)]
+pub struct FallbackGasFiller {
+    inner: GasFiller,
+    default_gas_limit: u64,
+    default_max_fee_per_gas: u128,
+    default_priority_fee: u128,
+}
+
+impl FallbackGasFiller {
+    pub fn new(
+        default_gas_limit: u64,
+        default_max_fee_per_gas: u128,
+        default_priority_fee: u128,
+    ) -> Self {
+        Self {
+            inner: GasFiller,
+            default_gas_limit,
+            default_max_fee_per_gas,
+            default_priority_fee,
+        }
+    }
+}
+
+impl<N> TxFiller<N> for FallbackGasFiller
+where
+    N: Network,
+{
+    type Fillable = Option<<GasFiller as TxFiller<N>>::Fillable>;
+
+    fn status(
+        &self,
+        tx: &<N as Network>::TransactionRequest,
+    ) -> alloy::providers::fillers::FillerControlFlow {
+        <GasFiller as TxFiller<N>>::status(&self.inner, tx)
+    }
+
+    fn fill_sync(&self, _: &mut alloy::providers::SendableTx<N>) {}
+
+    async fn prepare<P: Provider<N>>(
+        &self,
+        provider: &P,
+        tx: &<N as Network>::TransactionRequest,
+    ) -> TransportResult<Self::Fillable> {
+        // Try to fetch GasFiller’s “fillable” (gas_price, base_fee, estimate_gas, …)
+        // If it errors (i.e. tx would revert under eth_estimateGas), swallow it.
+        match self.inner.prepare(provider, tx).await {
+            Ok(fill) => Ok(Some(fill)),
+            Err(_) => Ok(None),
+        }
+    }
+
+    async fn fill(
+        &self,
+        fillable: Self::Fillable,
+        mut tx: alloy::providers::SendableTx<N>,
+    ) -> TransportResult<SendableTx<N>> {
+        if let Some(fill) = fillable {
+            // our inner GasFiller succeeded — use it
+            self.inner.fill(fill, tx).await
+        } else {
+            if let Some(builder) = tx.as_mut_builder() {
+                builder.set_gas_limit(self.default_gas_limit);
+                builder.set_max_fee_per_gas(self.default_max_fee_per_gas);
+                builder.set_max_priority_fee_per_gas(self.default_priority_fee);
+            }
+            Ok(tx)
+        }
+    }
+}
@@ -0,0 +1,5 @@
+/// This constant defines how much Wei accounts are pre-seeded with in genesis.
+///
+/// Note: After changing this number, check that the tests for kitchensink work as we encountered
+/// some issues with different values of the initial balance on Kitchensink.
+pub const INITIAL_BALANCE: u128 = 10u128.pow(37);
@@ -1,29 +1,37 @@
 //! The go-ethereum node implementation.

 use std::{
-    fs::{File, create_dir_all, remove_dir_all},
+    fs::{File, OpenOptions, 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},
+    eips::BlockNumberOrTag,
+    genesis::{Genesis, GenesisAccount},
+    network::{Ethereum, EthereumWallet, NetworkWallet},
+    primitives::{Address, BlockHash, BlockNumber, BlockTimestamp, FixedBytes, U256},
+    providers::{
+        Provider, ProviderBuilder,
+        ext::DebugApi,
+        fillers::{CachedNonceManager, ChainIdFiller, FillProvider, NonceFiller, TxFiller},
+    },
    rpc::types::{
        TransactionReceipt, TransactionRequest,
        trace::geth::{DiffMode, GethDebugTracingOptions, PreStateConfig, PreStateFrame},
    },
+    signers::local::PrivateKeySigner,
 };
+use revive_dt_common::concepts::BlockingExecutor;
 use revive_dt_config::Arguments;
-use revive_dt_node_interaction::{
-    EthereumNode, trace::trace_transaction, transaction::execute_transaction,
-};
+use revive_dt_format::traits::ResolverApi;
+use revive_dt_node_interaction::EthereumNode;
+use tracing::Level;

-use crate::Node;
+use crate::{Node, common::FallbackGasFiller, constants::INITIAL_BALANCE};

 static NODE_COUNT: AtomicU32 = AtomicU32::new(0);

@@ -39,17 +47,25 @@ pub struct Instance {
    connection_string: String,
    base_directory: PathBuf,
    data_directory: PathBuf,
+    logs_directory: PathBuf,
    geth: PathBuf,
    id: u32,
    handle: Option<Child>,
    network_id: u64,
    start_timeout: u64,
    wallet: EthereumWallet,
+    nonce_manager: CachedNonceManager,
+    /// This vector stores [`File`] objects that we use for logging which we want to flush when the
+    /// node object is dropped. We do not store them in a structured fashion at the moment (in
+    /// separate fields) as the logic that we need to apply to them is all the same regardless of
+    /// what it belongs to, we just want to flush them on [`Drop`] of the node.
+    logs_file_to_flush: Vec<File>,
 }

 impl Instance {
    const BASE_DIRECTORY: &str = "geth";
    const DATA_DIRECTORY: &str = "data";
+    const LOGS_DIRECTORY: &str = "logs";

    const IPC_FILE: &str = "geth.ipc";
    const GENESIS_JSON_FILE: &str = "genesis.json";
@@ -57,12 +73,30 @@ impl Instance {
    const READY_MARKER: &str = "IPC endpoint opened";
    const ERROR_MARKER: &str = "Fatal:";

+    const GETH_STDOUT_LOG_FILE_NAME: &str = "node_stdout.log";
+    const GETH_STDERR_LOG_FILE_NAME: &str = "node_stderr.log";
+
+    const TRANSACTION_INDEXING_ERROR: &str = "transaction indexing is in progress";
+
    /// Create the node directory and call `geth init` to configure the genesis.
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
    fn init(&mut self, genesis: String) -> anyhow::Result<&mut Self> {
        create_dir_all(&self.base_directory)?;
+        create_dir_all(&self.logs_directory)?;

+        let mut genesis = serde_json::from_str::<Genesis>(&genesis)?;
+        for signer_address in
+            <EthereumWallet as NetworkWallet<Ethereum>>::signer_addresses(&self.wallet)
+        {
+            // Note, the use of the entry API here means that we only modify the entries for any
+            // account that is not in the `alloc` field of the genesis state.
+            genesis
+                .alloc
+                .entry(signer_address)
+                .or_insert(GenesisAccount::default().with_balance(U256::from(INITIAL_BALANCE)));
+        }
        let genesis_path = self.base_directory.join(Self::GENESIS_JSON_FILE);
-        File::create(&genesis_path)?.write_all(genesis.as_bytes())?;
+        serde_json::to_writer(File::create(&genesis_path)?, &genesis)?;

        let mut child = Command::new(&self.geth)
            .arg("init")
@@ -89,8 +123,24 @@ impl Instance {

    /// Spawn the go-ethereum node child process.
    ///
-    /// [Instance::init] must be called priorly.
+    /// [Instance::init] must be called prior.
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
    fn spawn_process(&mut self) -> anyhow::Result<&mut Self> {
+        // This is the `OpenOptions` that we wish to use for all of the log files that we will be
+        // opening in this method. We need to construct it in this way to:
+        // 1. Be consistent
+        // 2. Less verbose and more dry
+        // 3. Because the builder pattern uses mutable references so we need to get around that.
+        let open_options = {
+            let mut options = OpenOptions::new();
+            options.create(true).truncate(true).write(true);
+            options
+        };
+
+        let stdout_logs_file = open_options
+            .clone()
+            .open(self.geth_stdout_log_file_path())?;
+        let stderr_logs_file = open_options.open(self.geth_stderr_log_file_path())?;
        self.handle = Command::new(&self.geth)
            .arg("--dev")
            .arg("--datadir")
@@ -102,88 +152,281 @@ impl Instance {
            .arg("--nodiscover")
            .arg("--maxpeers")
            .arg("0")
-            .stderr(Stdio::piped())
-            .stdout(Stdio::null())
+            .stderr(stderr_logs_file.try_clone()?)
+            .stdout(stdout_logs_file.try_clone()?)
            .spawn()?
            .into();
+
+        if let Err(error) = self.wait_ready() {
+            tracing::error!(?error, "Failed to start geth, shutting down gracefully");
+            self.shutdown()?;
+            return Err(error);
+        }
+
+        self.logs_file_to_flush
+            .extend([stderr_logs_file, stdout_logs_file]);
+
        Ok(self)
    }

    /// Wait for the g-ethereum node child process getting ready.
    ///
    /// [Instance::spawn_process] must be called priorly.
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
    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);
+        let logs_file = OpenOptions::new()
+            .read(true)
+            .write(false)
+            .append(false)
+            .truncate(false)
+            .open(self.geth_stderr_log_file_path())?;
+
+        let maximum_wait_time = Duration::from_millis(self.start_timeout);
+        let mut stderr = BufReader::new(logs_file).lines();
+        loop {
+            if let Some(Ok(line)) = stderr.next() {
+                if line.contains(Self::ERROR_MARKER) {
+                    anyhow::bail!("Failed to start geth {line}");
+                }
+                if line.contains(Self::READY_MARKER) {
+                    return Ok(self);
+                }
            }
            if Instant::now().duration_since(start_time) > maximum_wait_time {
-                break "spawn timeout".to_string();
+                anyhow::bail!("Timeout in starting geth");
            }
-        };
+        }
+    }

-        let _ = child.kill();
-        anyhow::bail!("geth node #{} spawn error: {error}", self.id)
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id), level = Level::TRACE)]
+    fn geth_stdout_log_file_path(&self) -> PathBuf {
+        self.logs_directory.join(Self::GETH_STDOUT_LOG_FILE_NAME)
+    }
+
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id), level = Level::TRACE)]
+    fn geth_stderr_log_file_path(&self) -> PathBuf {
+        self.logs_directory.join(Self::GETH_STDERR_LOG_FILE_NAME)
+    }
+
+    fn provider(
+        &self,
+    ) -> impl Future<
+        Output = anyhow::Result<
+            FillProvider<impl TxFiller<Ethereum>, impl Provider<Ethereum>, Ethereum>,
+        >,
+    > + 'static {
+        let connection_string = self.connection_string();
+        let wallet = self.wallet.clone();
+
+        // Note: We would like all providers to make use of the same nonce manager so that we have
+        // monotonically increasing nonces that are cached. The cached nonce manager uses Arc's in
+        // its implementation and therefore it means that when we clone it then it still references
+        // the same state.
+        let nonce_manager = self.nonce_manager.clone();
+
+        Box::pin(async move {
+            ProviderBuilder::new()
+                .disable_recommended_fillers()
+                .filler(FallbackGasFiller::new(500_000_000, 500_000_000, 1))
+                .filler(ChainIdFiller::default())
+                .filler(NonceFiller::new(nonce_manager))
+                .wallet(wallet)
+                .connect(&connection_string)
+                .await
+                .map_err(Into::into)
+        })
    }
 }

 impl EthereumNode for Instance {
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
    fn execute_transaction(
        &self,
        transaction: TransactionRequest,
    ) -> anyhow::Result<alloy::rpc::types::TransactionReceipt> {
-        let connection_string = self.connection_string();
-        let wallet = self.wallet.clone();
+        let provider = self.provider();
+        BlockingExecutor::execute(async move {
+            let outer_span = tracing::debug_span!("Submitting transaction", ?transaction);
+            let _outer_guard = outer_span.enter();

-        execute_transaction(Box::pin(async move {
-            Ok(ProviderBuilder::new()
-                .wallet(wallet)
-                .connect(&connection_string)
-                .await?
-                .send_transaction(transaction)
-                .await?
-                .get_receipt()
-                .await?)
-        }))
+            let provider = provider.await?;
+
+            let pending_transaction = provider.send_transaction(transaction).await?;
+            let transaction_hash = pending_transaction.tx_hash();
+
+            let span = tracing::info_span!("Awaiting transaction receipt", ?transaction_hash);
+            let _guard = span.enter();
+
+            // The following is a fix for the "transaction indexing is in progress" error that we
+            // used to get. You can find more information on this in the following GH issue in geth
+            // https://github.com/ethereum/go-ethereum/issues/28877. To summarize what's going on,
+            // before we can get the receipt of the transaction it needs to have been indexed by the
+            // node's indexer. Just because the transaction has been confirmed it doesn't mean that
+            // it has been indexed. When we call alloy's `get_receipt` it checks if the transaction
+            // was confirmed. If it has been, then it will call `eth_getTransactionReceipt` method
+            // which _might_ return the above error if the tx has not yet been indexed yet. So, we
+            // need to implement a retry mechanism for the receipt to keep retrying to get it until
+            // it eventually works, but we only do that if the error we get back is the "transaction
+            // indexing is in progress" error or if the receipt is None.
+            //
+            // Getting the transaction indexed and taking a receipt can take a long time especially
+            // when a lot of transactions are being submitted to the node. Thus, while initially we
+            // only allowed for 60 seconds of waiting with a 1 second delay in polling, we need to
+            // allow for a larger wait time. Therefore, in here we allow for 5 minutes of waiting
+            // with exponential backoff each time we attempt to get the receipt and find that it's
+            // not available.
+            let mut retries = 0;
+            let mut total_wait_duration = Duration::from_secs(0);
+            let max_allowed_wait_duration = Duration::from_secs(5 * 60);
+            loop {
+                if total_wait_duration >= max_allowed_wait_duration {
+                    tracing::error!(
+                        ?total_wait_duration,
+                        ?max_allowed_wait_duration,
+                        retry_count = retries,
+                        "Failed to get receipt after polling for it"
+                    );
+                    anyhow::bail!(
+                        "Polled for receipt for {total_wait_duration:?} but failed to get it"
+                    );
+                }
+
+                match provider.get_transaction_receipt(*transaction_hash).await {
+                    Ok(Some(receipt)) => break Ok(receipt),
+                    Ok(None) => {}
+                    Err(error) => {
+                        let error_string = error.to_string();
+                        if !error_string.contains(Self::TRANSACTION_INDEXING_ERROR) {
+                            break Err(error.into());
+                        }
+                    }
+                };
+
+                let next_wait_duration = Duration::from_secs(2u64.pow(retries))
+                    .min(max_allowed_wait_duration - total_wait_duration);
+                total_wait_duration += next_wait_duration;
+                retries += 1;
+
+                tokio::time::sleep(next_wait_duration).await;
+            }
+        })?
    }

+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
    fn trace_transaction(
        &self,
-        transaction: TransactionReceipt,
+        transaction: &TransactionReceipt,
+        trace_options: GethDebugTracingOptions,
    ) -> anyhow::Result<alloy::rpc::types::trace::geth::GethTrace> {
-        let connection_string = self.connection_string();
+        let tx_hash = transaction.transaction_hash;
+        let provider = self.provider();
+        BlockingExecutor::execute(async move {
+            Ok(provider
+                .await?
+                .debug_trace_transaction(tx_hash, trace_options)
+                .await?)
+        })?
+    }
+
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
+    fn state_diff(&self, transaction: &TransactionReceipt) -> anyhow::Result<DiffMode> {
        let trace_options = GethDebugTracingOptions::prestate_tracer(PreStateConfig {
            diff_mode: Some(true),
            disable_code: None,
            disable_storage: None,
        });
-        let wallet = self.wallet.clone();
+        match self
+            .trace_transaction(transaction, trace_options)?
+            .try_into_pre_state_frame()?
+        {
+            PreStateFrame::Diff(diff) => Ok(diff),
+            _ => anyhow::bail!("expected a diff mode trace"),
+        }
+    }
+}

-        trace_transaction(Box::pin(async move {
-            Ok(ProviderBuilder::new()
-                .wallet(wallet)
-                .connect(&connection_string)
+impl ResolverApi for Instance {
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
+    fn chain_id(&self) -> anyhow::Result<alloy::primitives::ChainId> {
+        let provider = self.provider();
+        BlockingExecutor::execute(async move {
+            provider.await?.get_chain_id().await.map_err(Into::into)
+        })?
+    }
+
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
+    fn block_gas_limit(&self, number: BlockNumberOrTag) -> anyhow::Result<u128> {
+        let provider = self.provider();
+        BlockingExecutor::execute(async move {
+            provider
                .await?
-                .debug_trace_transaction(transaction.transaction_hash, trace_options)
-                .await?)
-        }))
+                .get_block_by_number(number)
+                .await?
+                .ok_or(anyhow::Error::msg("Blockchain has no blocks"))
+                .map(|block| block.header.gas_limit as _)
+        })?
+    }
+
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
+    fn block_coinbase(&self, number: BlockNumberOrTag) -> anyhow::Result<Address> {
+        let provider = self.provider();
+        BlockingExecutor::execute(async move {
+            provider
+                .await?
+                .get_block_by_number(number)
+                .await?
+                .ok_or(anyhow::Error::msg("Blockchain has no blocks"))
+                .map(|block| block.header.beneficiary)
+        })?
+    }
+
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
+    fn block_difficulty(&self, number: BlockNumberOrTag) -> anyhow::Result<U256> {
+        let provider = self.provider();
+        BlockingExecutor::execute(async move {
+            provider
+                .await?
+                .get_block_by_number(number)
+                .await?
+                .ok_or(anyhow::Error::msg("Blockchain has no blocks"))
+                .map(|block| block.header.difficulty)
+        })?
+    }
+
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
+    fn block_hash(&self, number: BlockNumberOrTag) -> anyhow::Result<BlockHash> {
+        let provider = self.provider();
+        BlockingExecutor::execute(async move {
+            provider
+                .await?
+                .get_block_by_number(number)
+                .await?
+                .ok_or(anyhow::Error::msg("Blockchain has no blocks"))
+                .map(|block| block.header.hash)
+        })?
+    }
+
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
+    fn block_timestamp(&self, number: BlockNumberOrTag) -> anyhow::Result<BlockTimestamp> {
+        let provider = self.provider();
+        BlockingExecutor::execute(async move {
+            provider
+                .await?
+                .get_block_by_number(number)
+                .await?
+                .ok_or(anyhow::Error::msg("Blockchain has no blocks"))
+                .map(|block| block.header.timestamp)
+        })?
+    }
+
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
+    fn last_block_number(&self) -> anyhow::Result<BlockNumber> {
+        let provider = self.provider();
+        BlockingExecutor::execute(async move {
+            provider.await?.get_block_number().await.map_err(Into::into)
+        })?
    }
 }

@@ -193,45 +436,67 @@ impl Node for Instance {
        let id = NODE_COUNT.fetch_add(1, Ordering::SeqCst);
        let base_directory = geth_directory.join(id.to_string());

+        let mut wallet = config.wallet();
+        for signer in (1..=config.private_keys_to_add)
+            .map(|id| U256::from(id))
+            .map(|id| id.to_be_bytes::<32>())
+            .map(|id| PrivateKeySigner::from_bytes(&FixedBytes(id)).unwrap())
+        {
+            wallet.register_signer(signer);
+        }
+
        Self {
            connection_string: base_directory.join(Self::IPC_FILE).display().to_string(),
            data_directory: base_directory.join(Self::DATA_DIRECTORY),
+            logs_directory: base_directory.join(Self::LOGS_DIRECTORY),
            base_directory,
            geth: config.geth.clone(),
            id,
            handle: None,
            network_id: config.network_id,
            start_timeout: config.geth_start_timeout,
-            wallet: config.wallet(),
+            wallet,
+            // We know that we only need to be storing 2 files so we can specify that when creating
+            // the vector. It's the stdout and stderr of the geth node.
+            logs_file_to_flush: Vec::with_capacity(2),
+            nonce_manager: Default::default(),
        }
    }

+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
    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"),
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
+    fn shutdown(&mut self) -> anyhow::Result<()> {
+        // Terminate the processes in a graceful manner to allow for the output to be flushed.
+        if let Some(mut child) = self.handle.take() {
+            child
+                .kill()
+                .map_err(|error| anyhow::anyhow!("Failed to kill the geth process: {error:?}"))?;
        }
+
+        // Flushing the files that we're using for keeping the logs before shutdown.
+        for file in self.logs_file_to_flush.iter_mut() {
+            file.flush()?
+        }
+
+        // Remove the node's database so that subsequent runs do not run on the same database. We
+        // ignore the error just in case the directory didn't exist in the first place and therefore
+        // there's nothing to be deleted.
+        let _ = remove_dir_all(self.base_directory.join(Self::DATA_DIRECTORY));
+
+        Ok(())
    }

+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
+    fn spawn(&mut self, genesis: String) -> anyhow::Result<()> {
+        self.init(genesis)?.spawn_process()?;
+        Ok(())
+    }
+
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
    fn version(&self) -> anyhow::Result<String> {
        let output = Command::new(&self.geth)
            .arg("--version")
@@ -243,27 +508,32 @@ impl Node for Instance {
            .stdout;
        Ok(String::from_utf8_lossy(&output).into())
    }
+
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
+    fn matches_target(&self, targets: Option<&[String]>) -> bool {
+        match targets {
+            None => true,
+            Some(targets) => targets.iter().any(|str| str.as_str() == "evm"),
+        }
+    }
 }

 impl Drop for Instance {
+    #[tracing::instrument(skip_all, fields(geth_node_id = self.id))]
    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);
-        }
+        self.shutdown().expect("Failed to shutdown")
    }
 }

 #[cfg(test)]
 mod tests {
    use revive_dt_config::Arguments;
+
    use temp_dir::TempDir;

    use crate::{GENESIS_JSON, Node};

-    use super::Instance;
+    use super::*;

    fn test_config() -> (Arguments, TempDir) {
        let mut config = Arguments::default();
@@ -273,6 +543,16 @@ mod tests {
        (config, temp_dir)
    }

+    fn new_node() -> (Instance, TempDir) {
+        let (args, temp_dir) = test_config();
+        let mut node = Instance::new(&args);
+        node.init(GENESIS_JSON.to_owned())
+            .expect("Failed to initialize the node")
+            .spawn_process()
+            .expect("Failed to spawn the node process");
+        (node, temp_dir)
+    }
+
    #[test]
    fn init_works() {
        Instance::new(&test_config().0)
@@ -295,4 +575,93 @@ mod tests {
            "expected version string, got: '{version}'"
        );
    }
+
+    #[test]
+    fn can_get_chain_id_from_node() {
+        // Arrange
+        let (node, _temp_dir) = new_node();
+
+        // Act
+        let chain_id = node.chain_id();
+
+        // Assert
+        let chain_id = chain_id.expect("Failed to get the chain id");
+        assert_eq!(chain_id, 420_420_420);
+    }
+
+    #[test]
+    fn can_get_gas_limit_from_node() {
+        // Arrange
+        let (node, _temp_dir) = new_node();
+
+        // Act
+        let gas_limit = node.block_gas_limit(BlockNumberOrTag::Latest);
+
+        // Assert
+        let gas_limit = gas_limit.expect("Failed to get the gas limit");
+        assert_eq!(gas_limit, u32::MAX as u128)
+    }
+
+    #[test]
+    fn can_get_coinbase_from_node() {
+        // Arrange
+        let (node, _temp_dir) = new_node();
+
+        // Act
+        let coinbase = node.block_coinbase(BlockNumberOrTag::Latest);
+
+        // Assert
+        let coinbase = coinbase.expect("Failed to get the coinbase");
+        assert_eq!(coinbase, Address::new([0xFF; 20]))
+    }
+
+    #[test]
+    fn can_get_block_difficulty_from_node() {
+        // Arrange
+        let (node, _temp_dir) = new_node();
+
+        // Act
+        let block_difficulty = node.block_difficulty(BlockNumberOrTag::Latest);
+
+        // Assert
+        let block_difficulty = block_difficulty.expect("Failed to get the block difficulty");
+        assert_eq!(block_difficulty, U256::ZERO)
+    }
+
+    #[test]
+    fn can_get_block_hash_from_node() {
+        // Arrange
+        let (node, _temp_dir) = new_node();
+
+        // Act
+        let block_hash = node.block_hash(BlockNumberOrTag::Latest);
+
+        // Assert
+        let _ = block_hash.expect("Failed to get the block hash");
+    }
+
+    #[test]
+    fn can_get_block_timestamp_from_node() {
+        // Arrange
+        let (node, _temp_dir) = new_node();
+
+        // Act
+        let block_timestamp = node.block_timestamp(BlockNumberOrTag::Latest);
+
+        // Assert
+        let _ = block_timestamp.expect("Failed to get the block timestamp");
+    }
+
+    #[test]
+    fn can_get_block_number_from_node() {
+        // Arrange
+        let (node, _temp_dir) = new_node();
+
+        // Act
+        let block_number = node.last_block_number();
+
+        // Assert
+        let block_number = block_number.expect("Failed to get the block number");
+        assert_eq!(block_number, 0)
+    }
 }
@@ -1,10 +1,12 @@
 //! 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 common;
+pub mod constants;
 pub mod geth;
+pub mod kitchensink;
 pub mod pool;

 /// The default genesis configuration.
@@ -23,14 +25,15 @@ pub trait Node: EthereumNode {
    /// Prune the node instance and related data.
    ///
    /// Blocking until it's completely stopped.
-    fn shutdown(self) -> anyhow::Result<()>;
+    fn shutdown(&mut 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>;
+
+    /// Given a list of targets from the metadata file, this function determines if the metadata
+    /// file can be ran on this node or not.
+    fn matches_target(&self, targets: Option<&[String]>) -> bool;
 }
@@ -62,7 +62,7 @@ where

 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());
+    tracing::info!("starting node: {}", node.connection_string());
    node.spawn(genesis)?;
    Ok(node)
 }
@@ -0,0 +1,18 @@
+[package]
+name = "revive-dt-report"
+version.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+revive-dt-config = { workspace = true }
+revive-dt-format = { workspace = true }
+
+anyhow = { workspace = true }
+tracing = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+revive-solc-json-interface = { workspace = true }
@@ -0,0 +1,94 @@
+//! The report analyzer enriches the raw report data.
+
+use serde::{Deserialize, Serialize};
+
+use crate::reporter::CompilationTask;
+
+/// Provides insights into how well the compilers perform.
+#[derive(Clone, Default, Debug, Serialize, Deserialize, PartialEq, PartialOrd)]
+pub struct CompilerStatistics {
+    /// The sum of contracts observed.
+    pub n_contracts: usize,
+    /// The mean size of compiled contracts.
+    pub mean_code_size: usize,
+    /// The mean size of the optimized YUL IR.
+    pub mean_yul_size: usize,
+    /// Is a proxy because the YUL also containes a lot of comments.
+    pub yul_to_bytecode_size_ratio: f32,
+}
+
+impl CompilerStatistics {
+    /// Cumulatively update the statistics with the next compiler task.
+    pub fn sample(&mut self, compilation_task: &CompilationTask) {
+        let Some(output) = &compilation_task.json_output else {
+            return;
+        };
+
+        let Some(contracts) = &output.contracts else {
+            return;
+        };
+
+        for (_solidity, contracts) in contracts.iter() {
+            for (_name, contract) in contracts.iter() {
+                let Some(evm) = &contract.evm else {
+                    continue;
+                };
+                let Some(deploy_code) = &evm.deployed_bytecode else {
+                    continue;
+                };
+
+                // The EVM bytecode can be unlinked and thus is not necessarily a decodable hex
+                // string; for our statistics this is a good enough approximation.
+                let bytecode_size = deploy_code.object.len() / 2;
+
+                let yul_size = contract
+                    .ir_optimized
+                    .as_ref()
+                    .expect("if the contract has a deploy code it should also have the opimized IR")
+                    .len();
+
+                self.update_sizes(bytecode_size, yul_size);
+            }
+        }
+    }
+
+    /// Updates the size statistics cumulatively.
+    fn update_sizes(&mut self, bytecode_size: usize, yul_size: usize) {
+        let n_previous = self.n_contracts;
+        let n_current = self.n_contracts + 1;
+
+        self.n_contracts = n_current;
+
+        self.mean_code_size = (n_previous * self.mean_code_size + bytecode_size) / n_current;
+        self.mean_yul_size = (n_previous * self.mean_yul_size + yul_size) / n_current;
+
+        if self.mean_code_size > 0 {
+            self.yul_to_bytecode_size_ratio =
+                self.mean_yul_size as f32 / self.mean_code_size as f32;
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::CompilerStatistics;
+
+    #[test]
+    fn compiler_statistics() {
+        let mut received = CompilerStatistics::default();
+        received.update_sizes(0, 0);
+        received.update_sizes(3, 37);
+        received.update_sizes(123, 456);
+
+        let mean_code_size = 41; // rounding error from integer truncation
+        let mean_yul_size = 164;
+        let expected = CompilerStatistics {
+            n_contracts: 3,
+            mean_code_size,
+            mean_yul_size,
+            yul_to_bytecode_size_ratio: mean_yul_size as f32 / mean_code_size as f32,
+        };
+
+        assert_eq!(received, expected);
+    }
+}
@@ -0,0 +1,4 @@
+//! The revive differential tests reporting facility.
+
+pub mod analyzer;
+pub mod reporter;
@@ -0,0 +1,243 @@
+//! The reporter is the central place observing test execution by collecting data.
+//!
+//! The data collected gives useful insights into the outcome of the test run
+//! and helps identifying and reproducing failing cases.
+
+use std::{
+    collections::HashMap,
+    fs::{self, File, create_dir_all},
+    path::PathBuf,
+    sync::{Mutex, OnceLock},
+    time::{SystemTime, UNIX_EPOCH},
+};
+
+use anyhow::Context;
+use serde::{Deserialize, Serialize};
+
+use revive_dt_config::{Arguments, TestingPlatform};
+use revive_dt_format::{corpus::Corpus, mode::SolcMode};
+use revive_solc_json_interface::{SolcStandardJsonInput, SolcStandardJsonOutput};
+
+use crate::analyzer::CompilerStatistics;
+
+pub(crate) static REPORTER: OnceLock<Mutex<Report>> = OnceLock::new();
+
+/// The `Report` datastructure stores all relevant inforamtion required for generating reports.
+#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+pub struct Report {
+    /// The configuration used during the test.
+    pub config: Arguments,
+    /// The observed test corpora.
+    pub corpora: Vec<Corpus>,
+    /// The observed test definitions.
+    pub metadata_files: Vec<PathBuf>,
+    /// The observed compilation results.
+    pub compiler_results: HashMap<TestingPlatform, Vec<CompilationResult>>,
+    /// The observed compilation statistics.
+    pub compiler_statistics: HashMap<TestingPlatform, CompilerStatistics>,
+    /// The file name this is serialized to.
+    #[serde(skip)]
+    directory: PathBuf,
+}
+
+/// Contains a compiled contract.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct CompilationTask {
+    /// The observed compiler input.
+    pub json_input: SolcStandardJsonInput,
+    /// The observed compiler output.
+    pub json_output: Option<SolcStandardJsonOutput>,
+    /// The observed compiler mode.
+    pub mode: SolcMode,
+    /// The observed compiler version.
+    pub compiler_version: String,
+    /// The observed error, if any.
+    pub error: Option<String>,
+}
+
+/// Represents a report about a compilation task.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct CompilationResult {
+    /// The observed compilation task.
+    pub compilation_task: CompilationTask,
+    /// The linked span.
+    pub span: Span,
+}
+
+/// The [Span] struct indicates the context of what is being reported.
+#[derive(Clone, Copy, Debug, Serialize, Deserialize)]
+pub struct Span {
+    /// The corpus index this belongs to.
+    corpus: usize,
+    /// The metadata file this belongs to.
+    metadata_file: usize,
+    /// The index of the case definition this belongs to.
+    case: usize,
+    /// The index of the case input this belongs to.
+    input: usize,
+}
+
+impl Report {
+    /// The file name where this report will be written to.
+    pub const FILE_NAME: &str = "report.json";
+
+    /// The [Span] is expected to initialize the reporter by providing the config.
+    const INITIALIZED_VIA_SPAN: &str = "requires a Span which initializes the reporter";
+
+    /// Create a new [Report].
+    fn new(config: Arguments) -> anyhow::Result<Self> {
+        let now = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_millis();
+
+        let directory = config.directory().join("report").join(format!("{now}"));
+        if !directory.exists() {
+            create_dir_all(&directory)?;
+        }
+
+        Ok(Self {
+            config,
+            directory,
+            ..Default::default()
+        })
+    }
+
+    /// Add a compilation task to the report.
+    pub fn compilation(span: Span, platform: TestingPlatform, compilation_task: CompilationTask) {
+        let mut report = REPORTER
+            .get()
+            .expect(Report::INITIALIZED_VIA_SPAN)
+            .lock()
+            .unwrap();
+
+        report
+            .compiler_statistics
+            .entry(platform)
+            .or_default()
+            .sample(&compilation_task);
+
+        report
+            .compiler_results
+            .entry(platform)
+            .or_default()
+            .push(CompilationResult {
+                compilation_task,
+                span,
+            });
+    }
+
+    /// Write the report to disk.
+    pub fn save() -> anyhow::Result<()> {
+        let Some(reporter) = REPORTER.get() else {
+            return Ok(());
+        };
+        let report = reporter.lock().unwrap();
+
+        if let Err(error) = report.write_to_file() {
+            anyhow::bail!("can not write report: {error}");
+        }
+
+        if report.config.extract_problems {
+            if let Err(error) = report.save_compiler_problems() {
+                anyhow::bail!("can not write compiler problems: {error}");
+            }
+        }
+
+        Ok(())
+    }
+
+    /// Write compiler problems to disk for later debugging.
+    pub fn save_compiler_problems(&self) -> anyhow::Result<()> {
+        for (platform, results) in self.compiler_results.iter() {
+            for result in results {
+                // ignore if there were no errors
+                if result.compilation_task.error.is_none()
+                    && result
+                        .compilation_task
+                        .json_output
+                        .as_ref()
+                        .and_then(|output| output.errors.as_ref())
+                        .map(|errors| errors.is_empty())
+                        .unwrap_or(true)
+                {
+                    continue;
+                }
+
+                let path = &self.metadata_files[result.span.metadata_file]
+                    .parent()
+                    .unwrap()
+                    .join(format!("{platform}_errors"));
+                if !path.exists() {
+                    create_dir_all(path)?;
+                }
+
+                if let Some(error) = result.compilation_task.error.as_ref() {
+                    fs::write(path.join("compiler_error.txt"), error)?;
+                }
+
+                if let Some(errors) = result.compilation_task.json_output.as_ref() {
+                    let file = File::create(path.join("compiler_output.txt"))?;
+                    serde_json::to_writer_pretty(file, &errors)?;
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    fn write_to_file(&self) -> anyhow::Result<()> {
+        let path = self.directory.join(Self::FILE_NAME);
+
+        let file = File::create(&path).context(path.display().to_string())?;
+        serde_json::to_writer_pretty(file, &self)?;
+
+        tracing::info!("report written to: {}", path.display());
+
+        Ok(())
+    }
+}
+
+impl Span {
+    /// Create a new [Span] with case and input index at 0.
+    ///
+    /// Initializes the reporting facility on the first call.
+    pub fn new(corpus: Corpus, config: Arguments) -> anyhow::Result<Self> {
+        let report = Mutex::new(Report::new(config)?);
+        let mut reporter = REPORTER.get_or_init(|| report).lock().unwrap();
+        reporter.corpora.push(corpus);
+
+        Ok(Self {
+            corpus: reporter.corpora.len() - 1,
+            metadata_file: 0,
+            case: 0,
+            input: 0,
+        })
+    }
+
+    /// Advance to the next metadata file: Resets the case input index to 0.
+    pub fn next_metadata(&mut self, metadata_file: PathBuf) {
+        let mut reporter = REPORTER
+            .get()
+            .expect(Report::INITIALIZED_VIA_SPAN)
+            .lock()
+            .unwrap();
+
+        reporter.metadata_files.push(metadata_file);
+
+        self.metadata_file = reporter.metadata_files.len() - 1;
+        self.case = 0;
+        self.input = 0;
+    }
+
+    /// Advance to the next case: Increas the case index by one and resets the input index to 0.
+    pub fn next_case(&mut self) {
+        self.case += 1;
+        self.input = 0;
+    }
+
+    /// Advance to the next input.
+    pub fn next_input(&mut self) {
+        self.input += 1;
+    }
+}
@@ -1,6 +1,6 @@
 [package]
 name = "revive-dt-solc-binaries"
-dependencies = "Download and cache solc binaries"
+description = "Download and cache solc binaries"
 version.workspace = true
 authors.workspace = true
 license.workspace = true
@@ -11,7 +11,7 @@ rust-version.workspace = true
 [dependencies]
 anyhow = { workspace = true }
 hex = { workspace = true }
-log = { workspace = true }
+tracing = { workspace = true }
 reqwest = { workspace = true }
 semver = { workspace = true }
 serde = { workspace = true }
@@ -25,7 +25,7 @@ pub(crate) fn get_or_download(

    let mut cache = SOLC_CACHER.lock().unwrap();
    if cache.contains(&target_file) {
-        log::debug!("using cached solc: {}", target_file.display());
+        tracing::debug!("using cached solc: {}", target_file.display());
        return Ok(target_file);
    }

@@ -37,10 +37,10 @@ pub(crate) fn get_or_download(
 }

 fn download_to_file(path: &Path, downloader: &GHDownloader) -> anyhow::Result<()> {
-    log::info!("caching file: {}", path.display());
+    tracing::info!("caching file: {}", path.display());

    let Ok(file) = File::create_new(path) else {
-        log::debug!("cache file already exists: {}", path.display());
+        tracing::debug!("cache file already exists: {}", path.display());
        return Ok(());
    };

@@ -60,7 +60,7 @@ fn download_to_file(path: &Path, downloader: &GHDownloader) -> anyhow::Result<()
    std::process::Command::new("xattr")
        .arg("-d")
        .arg("com.apple.quarantine")
-        .arg(&path)
+        .arg(path)
        .stderr(std::process::Stdio::null())
        .stdout(std::process::Stdio::null())
        .stdout(std::process::Stdio::null())
@@ -86,7 +86,7 @@ impl GHDownloader {
    /// 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:?}");
+        tracing::info!("downloading solc: {self:?}");
        let expected_digest = List::download(self.list)?
            .builds
            .iter()
@@ -110,37 +110,25 @@ mod tests {

    #[test]
    fn try_get_windows() {
-        let version = List::download(List::WINDOWS_URL)
-            .unwrap()
-            .latest_release
-            .into();
+        let version = List::download(List::WINDOWS_URL).unwrap().latest_release;
        GHDownloader::windows(version).download().unwrap();
    }

    #[test]
    fn try_get_macosx() {
-        let version = List::download(List::MACOSX_URL)
-            .unwrap()
-            .latest_release
-            .into();
+        let version = List::download(List::MACOSX_URL).unwrap().latest_release;
        GHDownloader::macosx(version).download().unwrap();
    }

    #[test]
    fn try_get_linux() {
-        let version = List::download(List::LINUX_URL)
-            .unwrap()
-            .latest_release
-            .into();
+        let version = List::download(List::LINUX_URL).unwrap().latest_release;
        GHDownloader::linux(version).download().unwrap();
    }

    #[test]
    fn try_get_wasm() {
-        let version = List::download(List::WASM_URL)
-            .unwrap()
-            .latest_release
-            .into();
+        let version = List::download(List::WASM_URL).unwrap().latest_release;
        GHDownloader::wasm(version).download().unwrap();
    }
 }
@@ -33,9 +33,5 @@
    "mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "timestamp": "0x00",
-    "alloc": {
-        "90F8bf6A479f320ead074411a4B0e7944Ea8c9C1": {
-            "balance": "1000000000000000000"
-        }
-    }
+    "alloc": {}
 }
Author	SHA1	Message	Date
Omar Abdulla	9676fca3fe	Support compiler-version aware exceptions	2025-07-25 17:06:14 +03:00
Omar	2923d675cd	Support Compile-time Linking (#79 ) * Use wrappers for libraries in metadata. * Create a unified way to access deployed contracts * Support linking at compile time	2025-07-25 07:03:21 +00:00
Omar	8f5bcf08ad	Support `Calldata` arithmetic (#77 ) * Re-order the input file. This commit reorders the input file such that we have a definitions section and an implementations section and such that the the order of the items in both sections is the same. * Implement a reverse polish calculator for calldata arithmetic	2025-07-24 15:35:25 +00:00
Omar	90fb89adc0	Add a `common` crate (#75 ) * Add a barebones common crate * Refactor some code into the common crate * Add a `ResolverApi` interface. This commit adds a `ResolverApi` trait to the `format` crate that can be implemented by any type that can act as a resolver. A resolver is able to provide information on the chain state. This chain state could be fresh or it could be cached (which is something that we will do in a future PR). This cleans up our crate graph so that `format` is not depending on the node interactions crate for the `EthereumNode` trait. * Cleanup the blocking executor	2025-07-24 12:42:45 +00:00
Omar	b03ad3027e	Pre-seed accounts with more ETH. (#73 ) * Pre-seed accounts with more ETH. This commit fixes and solves some issues around how much ETH we seed an account with in genesis. Currently, any account that the node has keys to sign for will be seeded with u128::MAX WEI in genesis. This also includes the default signer account. * Bump commit hash of polkadot SDK * Change how the cache key is computed * Revert "Change how the cache key is computed" This reverts commit `75afdd9cfd`. * Revert "Bump commit hash of polkadot SDK" This reverts commit `8aaa69780e`. * Add extra comments * Revert "Add extra comments" This reverts commit `bd4de2c83d`. * Update the initial balance	2025-07-24 08:46:14 +00:00
Omar	972f3b6d5b	Wait longer for geth receipts (#74 )	2025-07-24 04:40:19 +00:00
Omar	6f4aa731ab	Handle exceptions (#54 ) * Add support for wrapper types * Move `FilesWithExtensionIterator` to `core::common` * Remove unneeded use of two `HashMap`s * Make metadata structs more typed * Impl new_from for wrapper types * Implement the new input handling logic * Fix edge-case in input handling * Ignore macro doc comment tests * Correct comment * Fix edge-case in deployment order * Handle calldata better * Allow for the use of function signatures * Add support for exceptions * Cached nonce allocator * Fix tests * Add support for address replacement * Cleanup implementation * Cleanup mutability * Wire up address replacement with rest of code * Implement caller replacement * Switch to callframe trace for exceptions * Add a way to skip tests if they don't match the target * Handle values from the metadata files * Remove address replacement * Correct the arguments * Remove empty impl * Remove address replacement * Correct the arguments * Remove empty impl * Fix size_requirement underflow * Add support for wildcards in exceptions * Fix calldata construction of single calldata * Better handling for length in equivalency checks * Make initial balance a constant * Fix size_requirement underflow * Add support for wildcards in exceptions * Fix calldata construction of single calldata * Better handling for length in equivalency checks * Fix tests	2025-07-24 03:45:53 +00:00
Omar	589a5dc988	Handle calldata better (#49 ) * Add support for wrapper types * Move `FilesWithExtensionIterator` to `core::common` * Remove unneeded use of two `HashMap`s * Make metadata structs more typed * Impl new_from for wrapper types * Implement the new input handling logic * Fix edge-case in input handling * Ignore macro doc comment tests * Correct comment * Fix edge-case in deployment order * Handle calldata better * Remove todo	2025-07-22 03:39:35 +00:00
Omar	c6d55515be	Allow for the use of function signatures (#50 ) * Allow for the use of function signatures * Add test	2025-07-21 10:43:17 +00:00
Omar	a9970eb2bb	Refactor the input handling logic (#48 ) * Add support for wrapper types * Move `FilesWithExtensionIterator` to `core::common` * Remove unneeded use of two `HashMap`s * Make metadata structs more typed * Impl new_from for wrapper types * Implement the new input handling logic * Fix edge-case in input handling * Ignore macro doc comment tests * Correct comment * Fix edge-case in deployment order	2025-07-21 09:01:52 +00:00
Omar	2259942363	Cleanup execution logic (#45 ) * Introduce a custom kitchensink network * fix formatting * Added `--dev` to `substrate-node` arguments. This commit adds the `--dev` argument to the `substrate-node` to allow the chain to keep advancing as time goes own. We have found that if this option is not added then the chain won't advance forward. * fix clippy warning * fix clippy warning * Fix the ABI finding logic * Fix function selector and argument encoding * Avoid extra buffer allocation * Remove reliance on the web3 crate * Implement ABI fix in the compiler trait impl * Update the async runtime with syntactic sugar. * Fix tests * Fix doc test * Give nodes a standard way to get their alloy provider * Add ability to get the chain_id from node * Get kitchensink provider to use kitchensink network * Use provider method in tests * Add support for getting the gas limit from the node * Add a way to get the coinbase address * Add a way to get the block difficulty from the node * Add a way to get block info from the node * Expose APIs for getting the info of a specific block * Add resolution logic for other matterlabs variables * Fix tests * Add comment on alternative solutions * Change kitchensink gas limit assertion * Cleanup execution logic	2025-07-18 12:08:13 +00:00
Omar	0b97d7dc29	Support other matterlabs variables (#43 ) * Introduce a custom kitchensink network * fix formatting * Added `--dev` to `substrate-node` arguments. This commit adds the `--dev` argument to the `substrate-node` to allow the chain to keep advancing as time goes own. We have found that if this option is not added then the chain won't advance forward. * fix clippy warning * fix clippy warning * Fix function selector and argument encoding * Avoid extra buffer allocation * Remove reliance on the web3 crate * Update the async runtime with syntactic sugar. * Fix tests * Fix doc test * Give nodes a standard way to get their alloy provider * Add ability to get the chain_id from node * Get kitchensink provider to use kitchensink network * Use provider method in tests * Add support for getting the gas limit from the node * Add a way to get the coinbase address * Add a way to get the block difficulty from the node * Add a way to get block info from the node * Expose APIs for getting the info of a specific block * Add resolution logic for other matterlabs variables * Fix tests * Add comment on alternative solutions * Change kitchensink gas limit assertion * Remove un-needed profile config	2025-07-18 12:06:40 +00:00
Omar	2bee2d5c8b	Fix the ABI finding logic (#38 ) * Fix the ABI finding logic * Implement ABI fix in the compiler trait impl	2025-07-18 11:22:51 +00:00
Omar	854e8d9690	Fix `deserialization error: invalid value: string "0x2d79dd80ff729c000"` (#34 ) * Introduce a custom kitchensink network * fix formatting * Added `--dev` to `substrate-node` arguments. This commit adds the `--dev` argument to the `substrate-node` to allow the chain to keep advancing as time goes own. We have found that if this option is not added then the chain won't advance forward. * fix clippy warning * fix clippy warning	2025-07-18 11:22:13 +00:00
Omar	2d517784dd	Better logging for contract deployment (#46 ) * Log certain errors better * Remove unneeded code	2025-07-16 18:16:12 +00:00
Omar	baa11ad28f	Correctly identify which contracts to compile (#44 ) * Compile all contracts for a test file * Fix compilation errors related to paths * Set the base path if specified	2025-07-16 11:52:40 +00:00
Omar	c2e65f9e33	Fix function selector & argument encoding (#39 ) * Fix function selector and argument encoding * Avoid extra buffer allocation * Remove reliance on the web3 crate * Fix tests	2025-07-15 20:00:10 +00:00
Omar	14888f9767	Update the async runtime (#42 ) * Update the async runtime with syntactic sugar. * Fix doc test * Update crates/node-interaction/src/blocking_executor.rs Co-authored-by: xermicus <cyrill@parity.io> * Update crates/node-interaction/src/blocking_executor.rs Co-authored-by: xermicus <cyrill@parity.io> * Update crates/node-interaction/src/blocking_executor.rs Co-authored-by: xermicus <cyrill@parity.io> * Update crates/node-interaction/src/blocking_executor.rs Co-authored-by: xermicus <cyrill@parity.io> * Update crates/node-interaction/src/blocking_executor.rs Co-authored-by: xermicus <cyrill@parity.io> * Update crates/node-interaction/src/blocking_executor.rs Co-authored-by: xermicus <cyrill@parity.io> * Update crates/node-interaction/src/blocking_executor.rs Co-authored-by: xermicus <cyrill@parity.io> * Update crates/node-interaction/src/blocking_executor.rs Co-authored-by: xermicus <cyrill@parity.io> * Update crates/node-interaction/src/blocking_executor.rs Co-authored-by: xermicus <cyrill@parity.io> * Update crates/node-interaction/src/blocking_executor.rs Co-authored-by: xermicus <cyrill@parity.io> * Improve the comments * Update the release profile --------- Co-authored-by: xermicus <cyrill@parity.io>	2025-07-15 11:19:17 +00:00
Omar	3e99d1c2a5	Allow alloy to estimate tx gas (#37 )	2025-07-14 17:34:44 +00:00
Omar	4e234aa1bd	Remove code that was accidentally committed. (#41 ) * Remove code that was accidentally committed. * Remove unneeded dependency	2025-07-14 16:24:39 +00:00
Omar	b204de5484	Persist node logs (#36 ) * Persist node logs * Fix clippy lints * Delete the node's db on shutdown but persist logs * Fix tests * Separate stdout and stderr and use more consts. * More consistent handling of open options * Revert the use of subprocess * Remove outdated comment * Flush the log files on drop * Rename `log_files` -> `logs_file_to_flush`	2025-07-14 16:08:47 +00:00
Omar	5eb3a0e1b5	Fix for "transaction indexing is in progress" (#32 ) * Retry getting transaction receipt * Small fix to logging consistency * Introduce a custom kitchensink network * Fix formtting and clippy	2025-07-14 09:32:57 +00:00
Omar	772bd217c3	Fixing the CI on Ubuntu (#31 ) * pin the version of geth used in CI * pin the version of geth used in CI * temp: run on each push * pin the version of geth used in CI * Make geth installation arch dependent * Remove temp run on push to branch * Add a comment on the need for pre-built binaries	2025-07-14 09:17:13 +00:00
Omar	0513a4befb	Use `tracing` for logging. (#29 ) This commit updates how logging is done in the differential testing harness to use `tracing` instead of using the `log` crate. This allows us to be able to better associate logs with the cases being executed which makes it easier to debug and understand what the harness is doing.	2025-07-10 07:28:16 +00:00
activecoder10	de7c7d6703	Compute transaction input for executing transactions (#28 ) * Parsed ABI field in order to get method parameter * Added logic for ABI * Refactored dependencies * Small refactoring * Added unit tests for ABI parameter extraction logic * Fixed format issues * Fixed format * Added new changes to format * Added bail to stop execution when we have an error during deployment	2025-07-09 11:03:38 +00:00
activecoder10	3a537c2812	Added extra logging for critical part of the flow. (#27 ) * Fix legacy_transaction to address for execution part * updated polkadot-sdk to latest * Update polkadot-sdk to latest main with fixes * Added extra logging * Applied some clippy improvements	2025-06-27 15:24:57 +00:00
activecoder10	4ab79ed97e	Fixed the contract deployment logic. Added new tracing logging for differential for leader and follower receipt structure (#26 )	2025-06-20 13:02:54 +00:00
activecoder10	ee97b62e70	Added fetch_add_nonce method for NodeInteraction trait. Added extra logging. (#25 ) * added logging * added fetch_add_nonce method * Added nonce for legacy transaction also * Addressed PR comments	2025-06-18 19:43:16 +00:00
xermicus	e9b5a06aec	fix the simple test case definition (#24 ) Signed-off-by: xermicus <cyrill@parity.io>	2025-06-17 10:23:09 +00:00
xermicus	534170db6f	dont fail machete on polkadot-sdk submodule (#23 ) Signed-off-by: xermicus <cyrill@parity.io>	2025-06-14 10:12:30 +00:00
activecoder10	090b56c46a	deploy contracts (#22 )	2025-06-12 11:09:01 +00:00
activecoder10	547563e718	Extended execute_input method (#21 ) * Extended execute_input method * Improve tracing part	2025-06-10 08:23:37 +00:00
xermicus	c8eb8cf7b0	the state diff method belongs to node interactions (#20 ) Signed-off-by: Cyrill Leutwiler <bigcyrill@hotmail.com>	2025-06-05 07:50:54 +00:00
activecoder10	3b26e1e1d6	Implement the Node trait for kitchensink (#16 ) * feat: implement Node trait for Kitchensink node * removed self from eth_to_substrate_address method	2025-06-05 06:12:54 +00:00
xermicus	1bc20d088f	update dependencies (#19 ) Signed-off-by: Cyrill Leutwiler <bigcyrill@hotmail.com>	2025-05-26 07:02:27 +00:00
xermicus	10bfaed461	Implement basic reporting facility (#18 ) * wip Signed-off-by: Cyrill Leutwiler <bigcyrill@hotmail.com> * save to file after all tasks done Signed-off-by: Cyrill Leutwiler <bigcyrill@hotmail.com> * error out early if the workdir does not exist Signed-off-by: Cyrill Leutwiler <bigcyrill@hotmail.com> * the compiler statistics Signed-off-by: Cyrill Leutwiler <bigcyrill@hotmail.com> * allow compiler statistics per implementation Signed-off-by: Cyrill Leutwiler <bigcyrill@hotmail.com> * save compiler problems Signed-off-by: Cyrill Leutwiler <bigcyrill@hotmail.com> * add flag whether to extract compiler errors Signed-off-by: Cyrill Leutwiler <bigcyrill@hotmail.com> * whitespace Signed-off-by: Cyrill Leutwiler <bigcyrill@hotmail.com> --------- Signed-off-by: Cyrill Leutwiler <bigcyrill@hotmail.com>	2025-05-23 17:15:04 +00:00
xermicus	399f7820cd	add all cargo tasks to the test target (#14 ) Signed-off-by: Cyrill Leutwiler <bigcyrill@hotmail.com>	2025-05-15 11:15:50 +00:00
activecoder10	ae1174febe	Added basic CI workflow (#13 )	2025-05-12 13:00:13 +03:00
activecoder10	38b42560ec	Added implementation for resolc trait (#12 ) Implement the Solidity Compiler trait for resolc	2025-05-08 11:09:02 +02:00
Cyrill Leutwiler	8009f5880c	update README.md Signed-off-by: Cyrill Leutwiler <bigcyrill@hotmail.com>	2025-03-31 16:44:16 +02:00
xermicus	c590fa7bfd	Scaffold utility and library (#3 ) Signed-off-by: Cyrill Leutwiler <bigcyrill@hotmail.com> Signed-off-by: xermicus <bigcyrill@hotmail.com>	2025-03-31 11:40:05 +02:00