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

reth_ethereum_consensus/
lib.rs
