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

reth_ethereum_consensus/
lib.rs
