Perf/core bench

.dockerignore

@@ -0,0 +1,22 @@
+# Build artifacts
+target/
+
+# Git
+.git/
+.gitignore
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Documentation
+*.md
+!crates/*/Cargo.toml
+
+# CI/CD
+.github/
+
+# Miscellaneous
+.DS_Store

.github/workflows/sanity.yaml

@@ -19,7 +19,7 @@ jobs:
             ~/.cargo/registry
             ~/.cargo/git
             target
-          key: ${{ runner.os }}-rust-nightly-${{ hashFiles('**/Cargo.lock') }}
+          key: ${{ runner.os }}-rust-nightly-fmt-${{ hashFiles('**/Cargo.lock') }}
       - name: Set up Rust Nightly
         uses: actions-rs/toolchain@v1
         with:
@@ -41,15 +41,15 @@ jobs:
             ~/.cargo/registry
             ~/.cargo/git
             target
-          key: ${{ runner.os }}-rust-stable-${{ hashFiles('**/Cargo.lock') }}
+          key: ${{ runner.os }}-rust-stable-clippy-all-${{ hashFiles('**/Cargo.lock') }}
       - name: Set up Rust Stable
         uses: actions-rs/toolchain@v1
         with:
           toolchain: stable
           override: true
           components: clippy
       - name: Run Clippy with stable
-        run: cargo clippy --all-targets --all-features -- -D warnings
+        run: cargo clippy --workspace --all-targets --all-features -- -D warnings
 
   clippy-no-default:
     name: Clippy (no default features)
@@ -63,15 +63,15 @@ jobs:
             ~/.cargo/registry
             ~/.cargo/git
             target
-          key: ${{ runner.os }}-rust-stable-${{ hashFiles('**/Cargo.lock') }}
+          key: ${{ runner.os }}-rust-stable-clippy-nodefault-${{ hashFiles('**/Cargo.lock') }}
       - name: Set up Rust Stable
         uses: actions-rs/toolchain@v1
         with:
           toolchain: stable
           override: true
           components: clippy
       - name: Run Clippy with stable
-        run: cargo clippy --all-targets --no-default-features -- -D warnings
+        run: cargo clippy --workspace --all-targets --no-default-features -- -D warnings
 
   typos:
     name: Typos
@@ -96,14 +96,14 @@ jobs:
             ~/.cargo/registry
             ~/.cargo/git
             target
-          key: ${{ runner.os }}-rust-stable-${{ hashFiles('**/Cargo.lock') }}
+          key: ${{ runner.os }}-rust-stable-test-${{ hashFiles('**/Cargo.lock') }}
       - name: Set up Rust Stable
         uses: actions-rs/toolchain@v1
         with:
           toolchain: stable
           override: true
       - name: Run tests with stable
-        run: cargo test --all-targets --all-features
+        run: cargo test --workspace --lib --bins --tests --examples --all-features
 
   doc:
     name: Docs
@@ -117,7 +117,7 @@ jobs:
             ~/.cargo/registry
             ~/.cargo/git
             target
-          key: ${{ runner.os }}-rust-stable-${{ hashFiles('**/Cargo.lock') }}
+          key: ${{ runner.os }}-rust-stable-doc-${{ hashFiles('**/Cargo.lock') }}
       - name: Set up Rust Stable
         uses: actions-rs/toolchain@v1
         with:
@@ -126,4 +126,4 @@ jobs:
       - name: Build documentation
         env:
           RUSTDOCFLAGS: -D warnings
-        run: cargo doc --no-deps --document-private-items --all-features --examples
+        run: cargo doc --workspace --no-deps --document-private-items --all-features --examples

Cargo.toml

@@ -109,6 +109,8 @@ reth-optimism-cli = { git = "https://github.com/paradigmxyz/reth", tag = "v1.9.3
 reth-optimism-primitives = { git = "https://github.com/paradigmxyz/reth", tag = "v1.9.3" }
 
 # test-utils
+criterion = { version = "0.8", features = ["html_reports"] }
+gungraun = "0.17.0"
 jsonrpsee-core = { version = "0.26.0", features = ["client"] }
 nanoid = "0.4"
 alloy-genesis = { version = "1.0", default-features = false }

crates/core/Cargo.toml

@@ -112,4 +112,41 @@ op-alloy-flz = { workspace = true, optional = true }
 alloy-genesis = { workspace = true, optional = true }
 
 [dev-dependencies]
-rblib-core = { path = ".", features = ["test-utils"] }
+rblib-core = { path = ".", features = ["test-utils"] }
+criterion = { workspace = true }
+gungraun = { workspace = true }
+
+[[bench]]
+name = "apply_criterion"
+path = "benches/revm_regression/apply_criterion.rs"
+harness = false
+
+[[bench]]
+name = "apply_valgrind"
+path = "benches/revm_regression/apply_valgrind.rs"
+harness = false
+
+[[bench]]
+name = "revert_criterion"
+path = "benches/revm_regression/revert_criterion.rs"
+harness = false
+
+[[bench]]
+name = "revert_valgrind"
+path = "benches/revm_regression/revert_valgrind.rs"
+harness = false
+
+[[bench]]
+name = "traversal_criterion"
+path = "benches/revm_regression/traversal_criterion.rs"
+harness = false
+
+[[bench]]
+name = "traversal_valgrind"
+path = "benches/revm_regression/traversal_valgrind.rs"
+harness = false
+
+[[bench]]
+name = "forking"
+path = "benches/revm_regression/forking.rs"
+harness = false

crates/core/bench/Dockerfile

@@ -0,0 +1,40 @@
+# Dockerfile for running rblib-core benchmarks
+
+FROM rust:1.92-bookworm
+
+RUN apt-get update && apt-get install -y \
+    valgrind \
+    pkg-config \
+    libssl-dev \
+    clang \
+    libclang-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN cargo install gungraun-runner --version 0.17.0
+
+WORKDIR /workspace
+
+# Copy workspace manifests
+COPY Cargo.toml Cargo.lock ./
+COPY crates/rblib/Cargo.toml crates/rblib/
+COPY crates/core/Cargo.toml crates/core/
+COPY crates/pipeline/Cargo.toml crates/pipeline/
+COPY crates/pipeline-macros/Cargo.toml crates/pipeline-macros/
+COPY crates/test-utils-macros/Cargo.toml crates/test-utils-macros/
+
+# Minimal stubs for workspace members
+RUN mkdir -p crates/rblib/src crates/core/src crates/pipeline/src \
+    crates/pipeline-macros/src crates/test-utils-macros/src && \
+    touch crates/rblib/src/lib.rs crates/core/src/lib.rs crates/pipeline/src/lib.rs \
+    crates/pipeline-macros/src/lib.rs crates/test-utils-macros/src/lib.rs
+
+# Cache dependencies
+RUN cargo fetch
+
+# Copy rblib-core source
+COPY crates/core crates/core
+
+# Build benchmarks
+RUN cargo build --release -p rblib-core --features test-utils --benches
+
+CMD ["cargo", "bench", "-p", "rblib-core"]

crates/core/bench/README.md

@@ -0,0 +1,74 @@
+# Benchmarking rblib-core
+
+## Overview
+
+The `revm_regression` benchmarks compare checkpoint operations against equivalent direct REVM/BundleState operations to
+quantify abstraction overhead.
+
+### Scenarios
+
+| Benchmark     | What it measures                                                   |
+|---------------|--------------------------------------------------------------------|
+| `apply_*`     | Transaction execution: checkpoint chain vs single mutable State    |
+| `revert_*`    | Revert capability: checkpoint fork vs BundleState::revert_latest() |
+| `traversal_*` | State lookup cost at varying checkpoint chain depths               |
+| `forking`     | Cost of creating parallel branches from shared checkpoint          |
+
+See [`benches/revm_regression/scenarios.rs`](../benches/revm_regression/scenarios.rs) for detailed
+scenario definitions including workloads, approaches compared, and what each benchmark measures.
+
+### Harnesses
+
+- **Criterion** (`*_criterion`): Wall-clock timing (cross-platform)
+- **Valgrind** (`*_valgrind`): CPU instructions, cache behavior, heap profiling (Linux only)
+
+## Running Benchmarks
+
+### macOS (via Docker)
+
+```bash
+# Run all benchmarks in Docker, results copied to target/
+./crates/core/bench/macos.sh
+```
+
+Docker build:
+
+```bash
+docker build -f crates/core/bench/Dockerfile -t rblib-core-bench .
+```
+
+### Linux (native)
+
+```bash
+# Criterion only
+cargo bench -p rblib-core
+
+# All including Valgrind (requires valgrind + gungraun-runner)
+cargo bench -p rblib-core --bench apply_valgrind --bench revert_valgrind --bench traversal_valgrind
+```
+
+or a specific benchmark:
+
+```bash
+cargo bench -p rblib-core --bench apply_criterion
+```
+
+## Results
+
+### Criterion
+
+Results in `target/criterion/` with HTML reports.
+
+### Valgrind (via Gungraun)
+
+Results in `target/gungraun/`.
+
+```
+apply_valgrind::tx_execution::single_state tx_10:setup_10()
+Instructions:  413062  |  506572           (-18.45%) [-1.23x]
+               ^ current  ^ checkpoint     ^ single_state is 18% faster
+```
+
+- Negative percentage = baseline (revm) uses fewer instructions
+- `[-1.23x]` = checkpoint uses 1.23x more instructions
+

crates/core/bench/macos.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORKSPACE_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+CORE_DIR="$WORKSPACE_ROOT/crates/core"
+
+cd "$WORKSPACE_ROOT"
+
+echo "=== Building Docker image ==="
+docker build -f crates/core/bench/Dockerfile -t rblib-core-bench .
+
+echo ""
+echo "=== Running Criterion benchmarks ==="
+docker run --rm \
+    -v "$CORE_DIR/target/criterion:/workspace/crates/core/target/criterion" \
+    rblib-core-bench \
+    cargo bench -p rblib-core \
+        --bench apply_criterion \
+        --bench revert_criterion \
+        --bench traversal_criterion \
+        --bench forking
+
+echo ""
+echo "=== Running Valgrind benchmarks ==="
+docker run --rm \
+    -v "$CORE_DIR/target/gungraun:/workspace/target/gungraun" \
+    rblib-core-bench \
+    cargo bench -p rblib-core \
+        --bench apply_valgrind \
+        --bench revert_valgrind \
+        --bench traversal_valgrind
+
+echo ""
+echo "=== Done ==="
+echo "Criterion results: crates/core/target/criterion/"
+echo "Valgrind results:  crates/core/target/gungraun/"