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

reth_ethereum_consensus/
lib.rs
