Skip to content

README.md

Latest commit

 

History

History
76 lines (51 loc) · 2.79 KB

README.md

File metadata and controls

76 lines (51 loc) · 2.79 KB
Raw

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,
    public_keys,
    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"

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.