reth_ethereum_consensus/
lib.rs

1//! Beacon consensus implementation.
2
3#![doc(
4    html_logo_url = "https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-docs.png",
5    html_favicon_url = "https://avatars0.githubusercontent.com/u/97369466?s=256",
6    issue_tracker_base_url = "https://github.com/paradigmxyz/reth/issues/"
7)]
8#![cfg_attr(not(test), warn(unused_crate_dependencies))]
9#![cfg_attr(docsrs, feature(doc_cfg))]
10#![cfg_attr(not(feature = "std"), no_std)]
11
12extern crate alloc;
13
14use alloc::{fmt::Debug, sync::Arc};
15use alloy_consensus::{constants::MAXIMUM_EXTRA_DATA_SIZE, EMPTY_OMMER_ROOT_HASH};
16use alloy_eips::eip7840::BlobParams;
17use alloy_primitives::B256;
18use reth_chainspec::{EthChainSpec, EthereumHardforks};
19use reth_consensus::{
20    Consensus, ConsensusError, FullConsensus, HeaderValidator, ReceiptRootBloom, TransactionRoot,
21};
22use reth_consensus_common::validation::{
23    validate_4844_header_standalone, validate_against_parent_4844,
24    validate_against_parent_eip1559_base_fee, validate_against_parent_gas_limit,
25    validate_against_parent_hash_number, validate_against_parent_timestamp,
26    validate_block_pre_execution, validate_block_pre_execution_with_tx_root,
27    validate_body_against_header, validate_header_base_fee, validate_header_extra_data,
28    validate_header_gas,
29};
30use reth_execution_types::BlockExecutionResult;
31use reth_primitives_traits::{
32    Block, BlockHeader, NodePrimitives, RecoveredBlock, SealedBlock, SealedHeader,
33};
34
35mod validation;
36pub use validation::validate_block_post_execution;
37
38/// Ethereum beacon consensus
39///
40/// This consensus engine does basic checks as outlined in the execution specs.
41#[derive(Debug, Clone)]
42pub struct EthBeaconConsensus<ChainSpec> {
43    /// Configuration
44    chain_spec: Arc<ChainSpec>,
45    /// Maximum allowed extra data size in bytes
46    max_extra_data_size: usize,
47    /// When true, skips the gas limit change validation between parent and child blocks.
48    skip_gas_limit_ramp_check: bool,
49    /// When true, skips the blob gas used check in header validation.
50    skip_blob_gas_used_check: bool,
51    /// When true, skips the requests hash check in post-execution validation.
52    skip_requests_hash_check: bool,
53}
54
55impl<ChainSpec: EthChainSpec + EthereumHardforks> EthBeaconConsensus<ChainSpec> {
56    /// Create a new instance of [`EthBeaconConsensus`]
57    pub const fn new(chain_spec: Arc<ChainSpec>) -> Self {
58        Self {
59            chain_spec,
60            max_extra_data_size: MAXIMUM_EXTRA_DATA_SIZE,
61            skip_gas_limit_ramp_check: false,
62            skip_blob_gas_used_check: false,
63            skip_requests_hash_check: false,
64        }
65    }
66
67    /// Returns the maximum allowed extra data size.
68    pub const fn max_extra_data_size(&self) -> usize {
69        self.max_extra_data_size
70    }
71
72    /// Sets the maximum allowed extra data size and returns the updated instance.
73    pub const fn with_max_extra_data_size(mut self, size: usize) -> Self {
74        self.max_extra_data_size = size;
75        self
76    }
77
78    /// Disables the gas limit change validation between parent and child blocks.
79    pub const fn with_skip_gas_limit_ramp_check(mut self, skip: bool) -> Self {
80        self.skip_gas_limit_ramp_check = skip;
81        self
82    }
83
84    /// Disables the blob gas used check in header validation.
85    pub const fn with_skip_blob_gas_used_check(mut self, skip: bool) -> Self {
86        self.skip_blob_gas_used_check = skip;
87        self
88    }
89
90    /// Disables the requests hash check in post-execution validation.
91    pub const fn with_skip_requests_hash_check(mut self, skip: bool) -> Self {
92        self.skip_requests_hash_check = skip;
93        self
94    }
95
96    /// Returns the chain spec associated with this consensus engine.
97    pub const fn chain_spec(&self) -> &Arc<ChainSpec> {
98        &self.chain_spec
99    }
100}
101
102impl<ChainSpec, N> FullConsensus<N> for EthBeaconConsensus<ChainSpec>
103where
104    ChainSpec: Send + Sync + EthChainSpec<Header = N::BlockHeader> + EthereumHardforks + Debug,
105    N: NodePrimitives,
106{
107    fn validate_block_post_execution(
108        &self,
109        block: &RecoveredBlock<N::Block>,
110        result: &BlockExecutionResult<N::Receipt>,
111        receipt_root_bloom: Option<ReceiptRootBloom>,
112        block_access_list_hash: Option<B256>,
113    ) -> Result<(), ConsensusError> {
114        let res = validate_block_post_execution(
115            block,
116            &self.chain_spec,
117            result,
118            receipt_root_bloom,
119            block_access_list_hash,
120        );
121
122        if self.skip_requests_hash_check &&
123            let Err(ConsensusError::BodyRequestsHashDiff(_)) = &res
124        {
125            return Ok(());
126        }
127
128        res
129    }
130}
131
132impl<B, ChainSpec> Consensus<B> for EthBeaconConsensus<ChainSpec>
133where
134    B: Block,
135    ChainSpec: EthChainSpec<Header = B::Header> + EthereumHardforks + Debug + Send + Sync,
136{
137    fn validate_body_against_header(
138        &self,
139        body: &B::Body,
140        header: &SealedHeader<B::Header>,
141    ) -> Result<(), ConsensusError> {
142        validate_body_against_header(body, header.header())
143    }
144
145    fn validate_block_pre_execution(&self, block: &SealedBlock<B>) -> Result<(), ConsensusError> {
146        validate_block_pre_execution(block, &self.chain_spec)
147    }
148
149    fn validate_block_pre_execution_with_tx_root(
150        &self,
151        block: &SealedBlock<B>,
152        transaction_root: Option<TransactionRoot>,
153    ) -> Result<(), ConsensusError> {
154        validate_block_pre_execution_with_tx_root(block, &self.chain_spec, transaction_root)
155    }
156}
157
158impl<H, ChainSpec> HeaderValidator<H> for EthBeaconConsensus<ChainSpec>
159where
160    H: BlockHeader,
161    ChainSpec: EthChainSpec<Header = H> + EthereumHardforks + Debug + Send + Sync,
162{
163    fn validate_header(&self, header: &SealedHeader<H>) -> Result<(), ConsensusError> {
164        let header = header.header();
165        let is_post_merge = self.chain_spec.is_paris_active_at_block(header.number());
166
167        if is_post_merge {
168            if !header.difficulty().is_zero() {
169                return Err(ConsensusError::TheMergeDifficultyIsNotZero);
170            }
171
172            if !header.nonce().is_some_and(|nonce| nonce.is_zero()) {
173                return Err(ConsensusError::TheMergeNonceIsNotZero);
174            }
175
176            if header.ommers_hash() != EMPTY_OMMER_ROOT_HASH {
177                return Err(ConsensusError::TheMergeOmmerRootIsNotEmpty);
178            }
179        } else {
180            #[cfg(feature = "std")]
181            {
182                let present_timestamp = std::time::SystemTime::now()
183                    .duration_since(std::time::SystemTime::UNIX_EPOCH)
184                    .unwrap()
185                    .as_secs();
186
187                if header.timestamp() >
188                    present_timestamp + alloy_eips::merge::ALLOWED_FUTURE_BLOCK_TIME_SECONDS
189                {
190                    return Err(ConsensusError::TimestampIsInFuture {
191                        timestamp: header.timestamp(),
192                        present_timestamp,
193                    });
194                }
195            }
196        }
197        validate_header_extra_data(header, self.max_extra_data_size)?;
198        validate_header_gas(header)?;
199        validate_header_base_fee(header, &self.chain_spec)?;
200
201        // EIP-4895: Beacon chain push withdrawals as operations
202        if self.chain_spec.is_shanghai_active_at_timestamp(header.timestamp()) &&
203            header.withdrawals_root().is_none()
204        {
205            return Err(ConsensusError::WithdrawalsRootMissing)
206        } else if !self.chain_spec.is_shanghai_active_at_timestamp(header.timestamp()) &&
207            header.withdrawals_root().is_some()
208        {
209            return Err(ConsensusError::WithdrawalsRootUnexpected)
210        }
211
212        // Ensures that EIP-4844 fields are valid once cancun is active.
213        if self.chain_spec.is_cancun_active_at_timestamp(header.timestamp()) {
214            if !self.skip_blob_gas_used_check {
215                validate_4844_header_standalone(
216                    header,
217                    self.chain_spec
218                        .blob_params_at_timestamp(header.timestamp())
219                        .unwrap_or_else(BlobParams::cancun),
220                )?;
221            }
222        } else if header.blob_gas_used().is_some() {
223            return Err(ConsensusError::BlobGasUsedUnexpected)
224        } else if header.excess_blob_gas().is_some() {
225            return Err(ConsensusError::ExcessBlobGasUnexpected)
226        } else if header.parent_beacon_block_root().is_some() {
227            return Err(ConsensusError::ParentBeaconBlockRootUnexpected)
228        }
229
230        if self.chain_spec.is_prague_active_at_timestamp(header.timestamp()) {
231            if header.requests_hash().is_none() {
232                return Err(ConsensusError::RequestsHashMissing)
233            }
234        } else if header.requests_hash().is_some() {
235            return Err(ConsensusError::RequestsHashUnexpected)
236        }
237
238        Ok(())
239    }
240
241    fn validate_header_against_parent(
242        &self,
243        header: &SealedHeader<H>,
244        parent: &SealedHeader<H>,
245    ) -> Result<(), ConsensusError> {
246        validate_against_parent_hash_number(header.header(), parent)?;
247
248        validate_against_parent_timestamp(header.header(), parent.header())?;
249
250        if !self.skip_gas_limit_ramp_check {
251            validate_against_parent_gas_limit(header, parent, &self.chain_spec)?;
252        }
253
254        validate_against_parent_eip1559_base_fee(
255            header.header(),
256            parent.header(),
257            &self.chain_spec,
258        )?;
259
260        // ensure that the blob gas fields for this block
261        if let Some(blob_params) = self.chain_spec.blob_params_at_timestamp(header.timestamp()) {
262            validate_against_parent_4844(header.header(), parent.header(), blob_params)?;
263        }
264
265        Ok(())
266    }
267}
268
269#[cfg(test)]
270mod tests {
271    use super::*;
272    use alloy_consensus::Header;
273    use alloy_primitives::B256;
274    use reth_chainspec::{ChainSpec, ChainSpecBuilder};
275    use reth_consensus_common::validation::validate_against_parent_gas_limit;
276    use reth_primitives_traits::{
277        constants::{GAS_LIMIT_BOUND_DIVISOR, MINIMUM_GAS_LIMIT},
278        proofs,
279    };
280
281    fn header_with_gas_limit(gas_limit: u64) -> SealedHeader {
282        let header = reth_primitives_traits::Header { gas_limit, ..Default::default() };
283        SealedHeader::new(header, B256::ZERO)
284    }
285
286    #[test]
287    fn test_valid_gas_limit_increase() {
288        let parent = header_with_gas_limit(GAS_LIMIT_BOUND_DIVISOR * 10);
289        let child = header_with_gas_limit(parent.gas_limit + 5);
290
291        assert!(validate_against_parent_gas_limit(
292            &child,
293            &parent,
294            &ChainSpec::<Header>::default()
295        )
296        .is_ok());
297    }
298
299    #[test]
300    fn test_gas_limit_below_minimum() {
301        let parent = header_with_gas_limit(MINIMUM_GAS_LIMIT);
302        let child = header_with_gas_limit(MINIMUM_GAS_LIMIT - 1);
303
304        assert!(matches!(
305            validate_against_parent_gas_limit(&child, &parent, &ChainSpec::<Header>::default()).unwrap_err(),
306            ConsensusError::GasLimitInvalidMinimum { child_gas_limit }
307                if child_gas_limit == child.gas_limit
308        ));
309    }
310
311    #[test]
312    fn test_invalid_gas_limit_increase_exceeding_limit() {
313        let parent = header_with_gas_limit(GAS_LIMIT_BOUND_DIVISOR * 10);
314        let child = header_with_gas_limit(
315            parent.gas_limit + parent.gas_limit / GAS_LIMIT_BOUND_DIVISOR + 1,
316        );
317
318        assert!(matches!(
319            validate_against_parent_gas_limit(&child, &parent, &ChainSpec::<Header>::default()).unwrap_err(),
320            ConsensusError::GasLimitInvalidIncrease { parent_gas_limit, child_gas_limit }
321                if parent_gas_limit == parent.gas_limit && child_gas_limit == child.gas_limit
322        ));
323    }
324
325    #[test]
326    fn test_valid_gas_limit_decrease_within_limit() {
327        let parent = header_with_gas_limit(GAS_LIMIT_BOUND_DIVISOR * 10);
328        let child = header_with_gas_limit(parent.gas_limit - 5);
329
330        assert!(validate_against_parent_gas_limit(
331            &child,
332            &parent,
333            &ChainSpec::<Header>::default()
334        )
335        .is_ok());
336    }
337
338    #[test]
339    fn test_invalid_gas_limit_decrease_exceeding_limit() {
340        let parent = header_with_gas_limit(GAS_LIMIT_BOUND_DIVISOR * 10);
341        let child = header_with_gas_limit(
342            parent.gas_limit - parent.gas_limit / GAS_LIMIT_BOUND_DIVISOR - 1,
343        );
344
345        assert!(matches!(
346            validate_against_parent_gas_limit(&child, &parent, &ChainSpec::<Header>::default()).unwrap_err(),
347            ConsensusError::GasLimitInvalidDecrease { parent_gas_limit, child_gas_limit }
348                if parent_gas_limit == parent.gas_limit && child_gas_limit == child.gas_limit
349        ));
350    }
351
352    #[test]
353    fn shanghai_block_zero_withdrawals() {
354        // ensures that if shanghai is activated, and we include a block with a withdrawals root,
355        // that the header is valid
356        let chain_spec = Arc::new(ChainSpecBuilder::mainnet().shanghai_activated().build());
357
358        let header = reth_primitives_traits::Header {
359            base_fee_per_gas: Some(1337),
360            withdrawals_root: Some(proofs::calculate_withdrawals_root(&[])),
361            ..Default::default()
362        };
363
364        assert!(EthBeaconConsensus::new(chain_spec)
365            .validate_header(&SealedHeader::seal_slow(header,))
366            .is_ok());
367    }
368}
reth_ethereum_consensus/lib.rs

reth_ethereum_consensus/
lib.rs
