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
38/// Sparse trie implementation for stateless validation
39pub mod trie;
40
41#[doc(inline)]
42pub use trie::StatelessTrie;
43#[doc(inline)]
44pub use validation::stateless_validation_with_trie;
45
46/// Implementation of stateless validation
47pub mod validation;
48pub(crate) mod witness_db;
49
50#[doc(inline)]
51pub use alloy_rpc_types_debug::ExecutionWitness;
52
53use reth_ethereum_primitives::Block;
54
55/// `StatelessInput` is a convenience structure for serializing the input needed
56/// for the stateless validation function.
57#[serde_with::serde_as]
58#[derive(Clone, Debug, Default, serde::Serialize, serde::Deserialize)]
59pub struct StatelessInput {
60    /// The block being executed in the stateless validation function
61    #[serde_as(
62        as = "reth_primitives_traits::serde_bincode_compat::Block<reth_ethereum_primitives::TransactionSigned, alloy_consensus::Header>"
63    )]
64    pub block: Block,
65    /// `ExecutionWitness` for the stateless validation function
66    pub witness: ExecutionWitness,
67}