stateless

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.6 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-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.