Stateless Ethereum block validation
  • Rust 97.3%
  • Shell 2.7%
Find a file
History 2026-11-16 09:04:32 +00:00
.github fix(ci): publish guest tags as pre-releases (#51) 2026-10-06 11:22:37 +01:00
bin/stateless-validator-reth chore: update ere to v0.20.0 (#60) 2026-11-10 14:28:37 +00:00
crates perf(zisk): drop the software G1 subgroup pre-check before BLS12-381 MSM and pairing (#62) 2026-11-16 09:04:32 +00:00
docs chore: update ere to v0.20.0 (#60) 2026-11-10 14:28:37 +00:00
scripts chore: update ere to v0.20.0 (#60) 2026-11-10 14:28:37 +00:00
targets build: support rv64im zkVM target via lower-atomic pass (#27) 2026-06-01 14:30:00 +01:00
testing chore: update to tests-zkevm@v21.0.7 and reject malformed witness trie nodes (#61) 2026-11-11 18:17:24 +00:00
.gitignore Update to tests-zkevm@v0.8.4 (#42) 2026-09-08 21:51:07 +01:00
AGENTS.md chore: update to tests-zkevm@v21.0.7 and reject malformed witness trie nodes (#61) 2026-11-11 18:17:24 +00:00
Cargo.lock chore: update ere to v0.20.0 (#60) 2026-11-10 14:28:37 +00:00
Cargo.toml chore: update ere to v0.20.0 (#60) 2026-11-10 14:28:37 +00:00
CLAUDE.md docs: add agent guidance (#56) 2026-10-22 18:50:40 +01:00
clippy.toml feat: disallow non-deterministic iteration order (#3) 2026-03-30 16:29:57 +01:00
LICENSE-APACHE commit 2026-02-14 17:13:02 +00:00
LICENSE-MIT commit 2026-02-14 17:13:02 +00:00
README.md chore: update to tests-zkevm@v21.0.7 and reject malformed witness trie nodes (#61) 2026-11-11 18:17:24 +00:00
rustfmt.toml feat: initial stateless validation crate with EF test support 2026-02-12 11:28:02 +00:00

stateless

CI status Telegram Chat

Stateless Ethereum block validation using execution witnesses.

What is stateless?

stateless provides types and functions for validating Ethereum blocks without access to a full node's persistent database. Instead, it relies on pre-generated witness data that proves the specific state accessed during block execution.

It is built on top of reth and revm, and is designed to be no_std compatible for use in constrained environments such as zkVMs.

How it works

  1. Witness verification — The execution witness is verified against the parent block's state root using a sparse Merkle Patricia trie.
  2. Block execution — The block is executed in-memory using a witness-backed database (WitnessDatabase).
  3. Consensus validation — Post-execution consensus checks are performed.
  4. State root computation — The post-state root is calculated and compared against the block header.

Usage

The primary entry point is stateless_validation:

use stateless::{stateless_validation, ExecutionWitness};

let validation = stateless_validation(
    block,
    witness,
    chain_spec,
    evm_config,
)?;

let block_hash = validation.block_hash;
let output = validation.execution_output;
let block_access_list = validation.block_access_list;

no_std

The stateless crate is #![no_std] compatible and builds for the 64-bit RISC-V target (riscv64im-unknown-none-elf), making it suitable for use in zkVM environments. Because upstream dependencies currently require atomics, it must be built using the custom target specification provided in targets/riscv64im-unknown-none-elf.json.

Note: The build temporarily relies on the LLVM lower-atomic pass to lower atomic instructions into non-atomic equivalents.

Running EF tests

To run the Ethereum Foundation blockchain tests with stateless validation:

# From the repository root:
./scripts/run_ef_tests.sh default
./scripts/run_ef_tests.sh zeth

Or manually:

# From the repository root:
./scripts/setup_ef_tests.sh
EF_TEST_TRIE=default cargo test -p ef-tests --release --features "asm-keccak ef-tests"

Running stateless validator tests

The Reth validator tests use the tests-zkevm@v21.0.7 execution-spec fixtures, in both the blockchain_test and blockchain_test_engine formats. The first run downloads the archive and checks its SHA-256 checksum. Later runs reuse the versioned fixture cache.

cargo test -p stateless-validator-tests --test host_execution --locked

The suite requires every fixture to pass, except the tests listed in KNOWN_FAILURES in testing/stateless-validator/tests/host_execution.rs. The EIP-7685 and EIP-7928 tests there fail on upstream alloy-evm and revm bugs. The EIP-8025 tests omit code from the witness after the block wrote the same code, and the guest reads code only from the witness. The suite fails once any of them pass.

Contributing

Contributions are welcome! Join the conversation in the Telegram group.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.