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

reth_ethereum_consensus/
lib.rs
