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