reth_primitives_traits/
lib.rs

1//! Commonly used types and traits in Reth.
2//!
3//! ## Overview
4//!
5//! This crate defines various traits and types that form the foundation of the reth stack.
6//! The top-level trait is [`Block`] which represents a block in the blockchain. A [`Block`] is
7//! composed of a [`Header`] and a [`BlockBody`]. A [`BlockBody`] contains the transactions in the
8//! block and additional data that is part of the block. In ethereum, this includes uncle headers
9//! and withdrawals. For optimism, uncle headers and withdrawals are always empty lists.
10//!
11//! The most common types you'll use are:
12//! - [`Block`] - A basic block with header and body
13//! - [`SealedBlock`] - A block with its hash cached
14//! - [`SealedHeader`] - A header with its hash cached
15//! - [`RecoveredBlock`] - A sealed block with sender addresses recovered
16//!
17//! ## Feature Flags
18//!
19//! - `arbitrary`: Adds `proptest` and `arbitrary` support for primitive types.
20//! - `op`: Implements the traits for various [op-alloy](https://github.com/alloy-rs/op-alloy)
21//!   types.
22//! - `reth-codec`: Enables db codec support for reth types including zstd compression for certain
23//!   types.
24//! - `rpc-compat`: Adds RPC compatibility functions for the types in this crate, e.g. rpc type
25//!   conversions.
26//! - `serde`: Adds serde support for all types.
27//! - `secp256k1`: Adds secp256k1 support for transaction signing/recovery. (By default the no-std
28//!   friendly `k256` is used)
29//! - `rayon`: Uses `rayon` for parallel transaction sender recovery in [`BlockBody`] by default.
30//! - `serde-bincode-compat` provides helpers for dealing with the `bincode` crate.
31//!
32//! ### Sealing (Hashing)
33//!
34//! The block hash is derived from the [`Header`] and is used to uniquely identify the block. This
35//! operation is referred to as sealing in the context of this crate. Sealing is an expensive
36//! operation. This crate provides various wrapper types that cache the hash of the block to avoid
37//! recomputing it: [`SealedHeader`] and [`SealedBlock`]. All sealed types can be downgraded to
38//! their unsealed counterparts.
39//!
40//! ### Recovery
41//!
42//! The raw consensus transactions that make up a block don't include the sender's address. This
43//! information is recovered from the transaction signature. This operation is referred to as
44//! recovery in the context of this crate and is an expensive operation. The [`RecoveredBlock`]
45//! represents a [`SealedBlock`] with the sender addresses recovered. A [`SealedBlock`] can be
46//! upgraded to a [`RecoveredBlock`] by recovering the sender addresses:
47//! [`SealedBlock::try_recover`]. A [`RecoveredBlock`] can be downgraded to a [`SealedBlock`] by
48//! removing the sender addresses: [`RecoveredBlock::into_sealed_block`].
49//!
50//! #### Naming
51//!
52//! The types in this crate support multiple recovery functions, e.g.
53//! [`SealedBlock::try_recover`] and [`SealedBlock::try_recover_unchecked`]. The `_unchecked` suffix indicates that this function recovers the signer _without ensuring that the signature has a low `s` value_, in other words this rule introduced in [EIP-2](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2.md) is ignored.
54//! Hence this function is necessary when dealing with pre EIP-2 transactions on the ethereum
55//! mainnet. Newer transactions must always be recovered with the regular `recover` functions, see
56//! also [`recover_signer`](crypto::secp256k1::recover_signer).
57//!
58//! ## Error Handling
59//!
60//! Most operations that can fail return `Result` types:
61//! - [`RecoveryError`](transaction::signed::RecoveryError) - Transaction signature recovery failed
62//! - [`BlockRecoveryError`](block::error::BlockRecoveryError) - Block-level recovery failed
63//! - [`GotExpected`] / [`GotExpectedBoxed`] - Generic error for mismatched values
64//!
65//! Recovery errors typically indicate invalid signatures or corrupted data. The block recovery
66//! error preserves the original block for further inspection.
67//!
68//! ### Example
69//!
70//! ```rust
71//! # use reth_primitives_traits::{SealedBlock, RecoveredBlock};
72//! # use reth_primitives_traits::block::error::BlockRecoveryError;
73//! # fn example<B: reth_primitives_traits::Block>(sealed_block: SealedBlock<B>) -> Result<(), BlockRecoveryError<SealedBlock<B>>>
74//! # where B::Body: reth_primitives_traits::BlockBody<Transaction: reth_primitives_traits::SignedTransaction> {
75//! // Attempt to recover senders from a sealed block
76//! match sealed_block.try_recover() {
77//!     Ok(recovered) => {
78//!         // Successfully recovered all senders
79//!         println!("Recovered {} senders", recovered.senders().len());
80//!         Ok(())
81//!     }
82//!     Err(err) => {
83//!         // Recovery failed - the block is returned in the error
84//!         println!("Failed to recover senders for block");
85//!         // You can still access the original block
86//!         let block = err.into_inner();
87//!         let hash = block.hash();
88//!         Err(BlockRecoveryError::new(block))
89//!     }
90//! }
91//! # }
92//! ```
93//!
94//! ## Performance Considerations
95//!
96//! - **Hashing**: Block hashing is expensive. Use [`SealedBlock`] to cache hashes.
97//! - **Recovery**: Sender recovery is CPU-intensive. Use [`RecoveredBlock`] to cache results.
98//! - **Parallel Recovery**: Enable the `rayon` feature for parallel transaction recovery.
99
100#![doc(
101    html_logo_url = "https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-docs.png",
102    html_favicon_url = "https://avatars0.githubusercontent.com/u/97369466?s=256",
103    issue_tracker_base_url = "https://github.com/paradigmxyz/reth/issues/"
104)]
105#![cfg_attr(not(test), warn(unused_crate_dependencies))]
106#![cfg_attr(docsrs, feature(doc_cfg))]
107#![cfg_attr(not(feature = "std"), no_std)]
108
109#[macro_use]
110extern crate alloc;
111
112/// Re-export of [`quanta::Instant`] for high-resolution timing with minimal overhead.
113#[cfg(feature = "std")]
114pub use quanta::Instant as FastInstant;
115
116/// Common constants.
117pub mod constants;
118pub use constants::gas_units::{format_gas, format_gas_throughput};
119
120/// Minimal account
121pub mod account;
122pub use account::{Account, Bytecode};
123
124pub mod receipt;
125pub use receipt::{FullReceipt, Receipt};
126
127pub mod transaction;
128pub use alloy_consensus::{
129    transaction::{Recovered, TransactionMeta},
130    ReceiptWithBloom,
131};
132
133pub use transaction::{
134    execute::FillTxEnv,
135    signed::{FullSignedTx, SignedTransaction},
136    FullTransaction, SignerRecoverable, Transaction,
137};
138
139pub mod block;
140pub use block::{
141    body::{BlockBody, FullBlockBody},
142    header::{AlloyBlockHeader, BlockHeader, FullBlockHeader},
143    recovered::IndexedTx,
144    Block, FullBlock, RecoveredBlock, SealedBlock,
145};
146
147#[cfg(all(test, feature = "std", feature = "reth-codec"))]
148mod withdrawal;
149pub use alloy_eips::eip2718::WithEncoded;
150
151pub mod crypto;
152
153mod error;
154pub use error::{GotExpected, GotExpectedBoxed};
155
156#[cfg(all(test, feature = "std", feature = "reth-codec"))]
157mod log;
158pub use alloy_primitives::{logs_bloom, Log, LogData};
159
160pub mod proofs;
161
162mod storage;
163pub use storage::{StorageEntry, ValueWithSubKey};
164
165pub mod sync;
166
167/// Common header types
168pub mod header;
169pub use header::{Header, SealedHeader, SealedHeaderFor};
170
171/// Heuristic size trait
172pub use alloy_consensus::InMemorySize;
173
174/// Rayon utilities
175#[cfg(feature = "rayon")]
176pub mod rayon;
177#[cfg(feature = "rayon")]
178pub use rayon::ParallelBridgeBuffered;
179
180/// Node traits
181pub mod node;
182pub use node::{BlockTy, BodyTy, HeaderTy, NodePrimitives, ReceiptTy, TxTy};
183
184/// Helper trait that requires de-/serialize implementation since `serde` feature is enabled.
185#[cfg(feature = "serde")]
186pub trait MaybeSerde: serde::Serialize + for<'de> serde::Deserialize<'de> {}
187/// Noop. Helper trait that would require de-/serialize implementation if `serde` feature were
188/// enabled.
189#[cfg(not(feature = "serde"))]
190pub trait MaybeSerde {}
191
192#[cfg(feature = "serde")]
193impl<T> MaybeSerde for T where T: serde::Serialize + for<'de> serde::Deserialize<'de> {}
194#[cfg(not(feature = "serde"))]
195impl<T> MaybeSerde for T {}
196
197/// Helper trait that requires database encoding implementation since `reth-codec` feature is
198/// enabled.
199#[cfg(feature = "reth-codec")]
200pub trait MaybeCompact: reth_codecs::Compact {}
201/// Noop. Helper trait that would require database encoding implementation if `reth-codec` feature
202/// were enabled.
203#[cfg(not(feature = "reth-codec"))]
204pub trait MaybeCompact {}
205
206#[cfg(feature = "reth-codec")]
207impl<T> MaybeCompact for T where T: reth_codecs::Compact {}
208#[cfg(not(feature = "reth-codec"))]
209impl<T> MaybeCompact for T {}
210
211/// Utilities for testing.
212#[cfg(any(test, feature = "arbitrary", feature = "test-utils"))]
213pub mod test_utils {
214    pub use crate::header::test_utils::{generate_valid_header, valid_header_strategy};
215    #[cfg(any(test, feature = "test-utils"))]
216    pub use crate::{block::TestBlock, header::test_utils::TestHeader};
217}
218
219/// Re-exports of `dashmap` types with [`alloy_primitives::map::DefaultHashBuilder`] as the hasher.
220#[cfg(feature = "dashmap")]
221pub mod dashmap {
222    pub use ::dashmap::{mapref, DashSet, Entry};
223    /// Re-export of `DashMap` with [`alloy_primitives::map::DefaultHashBuilder`] as the hasher.
224    pub type DashMap<K, V, S = alloy_primitives::map::DefaultHashBuilder> =
225        ::dashmap::DashMap<K, V, S>;
226}
reth_primitives_traits/lib.rs

reth_primitives_traits/
lib.rs
