feat: Add stateless-executor guest program and SP1 cluster infrastructure

[WiseMrMusa]

This PR introduces the stateless-executor guest program, a new benchmarking workload that executes Ethereum blocks without pre/post execution validation overhead. It also adds initial SP1 cluster Docker infrastructure for local proving.

Detailed Changes

1. New Stateless Executor Guest Program

Added a complete stateless-executor crate under ere-guests/ that provides execution-only benchmarking capabilities:

Core Library (ere-guests/stateless-executor/src/)

File	Description
lib.rs	Module exports and common types
execution.rs	Core execution logic - executes block transactions without validation
guest.rs	Guest program entry point and cycle tracking
witness_db.rs	Database implementation using witness data

zkVM Entry Points

Each supported zkVM has its own entry point:

zkVM	Path	Description
RISC0	risc0/src/main.rs	RISC0 zkVM guest entry
SP1	sp1/src/main.rs	SP1 zkVM guest entry
OpenVM	openvm/src/main.rs	OpenVM guest entry
Pico	pico/src/main.rs	Pico zkVM guest entry
Zisk	zisk/src/main.rs	Zisk zkVM guest entry
Airbender	airbender/src/main.rs	Airbender entry

2. Benchmark Runner Integration

Updated crates/benchmark-runner/ to support the stateless-executor:

Change	Description
stateless_executor.rs	New module for executor-specific runner logic
stateless_executor/reth.rs	Reth execution client integration
runner.rs	Added executor mode alongside validator mode
Cargo.toml	Added memory tracking features

3. CLI Enhancements

Updated crates/ere-hosts/src/cli.rs:

Feature	Description
Guest type selection	Added --guest flag for stateless-executor vs stateless-validator
Input handling	Support for both --input-file and --input-folder
Network resource	Added network as valid resource type for SP1 zkVM

4. Memory Tracking (crates/metrics/)

Added memory tracking capabilities:

// New memory tracking feature
pub struct MemoryStats {
    pub peak_memory_bytes: u64,
    pub average_memory_bytes: u64,
}

5. SP1 Cluster Infrastructure

Added Docker-based SP1 cluster setup under scripts/sp1-cluster/:

File	Description
docker-compose.yml	Docker Compose configuration for SP1 cluster services
start-sp1-cluster.sh	Startup script with GPU worker configuration (0-8 GPUs)
stop-sp1-cluster.sh	Graceful shutdown script

Services included:

• Redis (artifact storage)
• PostgreSQL (job metadata)
• API service (gRPC endpoint)
• Coordinator (job distribution)
• CPU/GPU worker nodes

6. Dependency Updates

Updated Cargo.toml and Cargo.lock:

• Point ere packages to NethermindEth/ere repository
• Version update to 4bac87e
• Updated ethrex dependencies for stateless-validator

7. Cluster Resource Support

Added cluster resource type for SP1 proving:

pub enum ProverResourceType {
    Cpu,
    Gpu,
    Network,  // Uses SP1 network
    Cluster,  // Uses local SP1 cluster
}

---

Why These Changes?

Stateless Executor Benefits

1. Pure EVM Benchmarking: Measures only execution cycles without validation overhead
2. Opcode Cost Analysis: More accurate per-opcode cost measurement
3. Research Focused: Isolates EVM execution for performance research
4. Comparison Baseline: Provides baseline for comparing against full validation

SP1 Cluster Benefits

1. Self-Hosted Proving: Run provers locally without network dependency
2. Multi-GPU Support: Leverage multiple GPUs for parallel proving
3. Consistent Environment: Reproducible benchmarking environment
4. Cost Control: No network proving costs for development/testing

---

Testing

# Build the stateless-executor
cargo build --release -p benchmark-runner

# Run executor benchmark
./target/release/ere-hosts prove \
  --guest stateless-executor \
  --zkvm risc0 \
  --input-folder ./zkevm-fixtures-input-1M

# Start SP1 cluster
cd scripts/sp1-cluster
./start-sp1-cluster.sh --gpu-nodes 4 -d

---

Breaking Changes

None. This PR adds new functionality without modifying existing APIs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
zkgas-profiling	Ignored		Jan 8, 2026 5:02pm