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

reth_ethereum_consensus/
lib.rs
