reth_stateless/
lib.rs

1//! Provides types and functions for stateless execution and validation of Ethereum blocks.
2//!
3//! This crate enables the verification of block execution without requiring access to a
4//! full node's persistent database. Instead, it relies on pre-generated "witness" data
5//! that proves the specific state accessed during the block's execution.
6//!
7//! # Key Components
8//!
9//! * `WitnessDatabase`: An implementation of [`reth_revm::Database`] that uses a
10//!   [`reth_trie_sparse::SparseStateTrie`] populated from witness data, along with provided
11//!   bytecode and ancestor block hashes, to serve state reads during execution.
12//! * `stateless_validation`: The core function that orchestrates the stateless validation process.
13//!   It takes a block, its execution witness, ancestor headers, and chain specification, then
14//!   performs:
15//!     1. Witness verification against the parent block's state root.
16//!     2. Block execution using the `WitnessDatabase`.
17//!     3. Post-execution consensus checks.
18//!     4. Post-state root calculation and comparison against the block header.
19//!
20//! # Usage
21//!
22//! The primary entry point is typically the `validation::stateless_validation` function. Callers
23//! need to provide the block to be validated along with accurately generated `ExecutionWitness`
24//! data corresponding to that block's execution trace and the necessary Headers of ancestor
25//! blocks.
26
27#![doc(
28    html_logo_url = "https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-docs.png",
29    html_favicon_url = "https://avatars0.githubusercontent.com/u/97369466?s=256",
30    issue_tracker_base_url = "https://github.com/paradigmxyz/reth/issues/"
31)]
32#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
33#![cfg_attr(not(test), warn(unused_crate_dependencies))]
34#![no_std]
35
36extern crate alloc;
37
38pub(crate) mod root;
39/// Implementation of stateless validation
40pub mod validation;
41pub(crate) mod witness_db;
42
43#[doc(inline)]
44pub use alloy_rpc_types_debug::ExecutionWitness;
45
46use reth_ethereum_primitives::Block;
47
48/// StatelessInput is a convenience structure for serializing the input needed
49/// for the stateless validation function.
50#[serde_with::serde_as]
51#[derive(Clone, Debug, Default, serde::Serialize, serde::Deserialize)]
52pub struct StatelessInput {
53    /// The block being executed in the stateless validation function
54    #[serde_as(
55        as = "reth_primitives_traits::serde_bincode_compat::Block<reth_ethereum_primitives::TransactionSigned, alloy_consensus::Header>"
56    )]
57    pub block: Block,
58    /// ExecutionWitness for the stateless validation function
59    pub witness: ExecutionWitness,
60}