reth_payload_primitives/
traits.rs

1//! Core traits for working with execution payloads.
2
3use crate::PayloadBuilderError;
4use alloc::{boxed::Box, sync::Arc, vec::Vec};
5use alloy_eips::{eip4895::Withdrawal, eip7685::Requests};
6use alloy_primitives::{Bytes, B256, U256};
7use alloy_rpc_types_engine::{PayloadAttributes as EthPayloadAttributes, PayloadId};
8use core::fmt;
9use either::Either;
10use reth_execution_types::BlockExecutionOutput;
11use reth_primitives_traits::{NodePrimitives, RecoveredBlock, SealedBlock, SealedHeader};
12use reth_trie_common::{updates::TrieUpdates, HashedPostState};
13use sha2::Digest;
14
15/// Represents an executed block for payload building purposes.
16///
17/// This type captures the complete execution state of a built block,
18/// including the recovered block, execution outcome, hashed state, and trie updates.
19#[derive(Clone, Debug, PartialEq, Eq)]
20pub struct BuiltPayloadExecutedBlock<N: NodePrimitives> {
21    /// Recovered Block
22    pub recovered_block: Arc<RecoveredBlock<N::Block>>,
23    /// Block's execution outcome.
24    pub execution_output: Arc<BlockExecutionOutput<N::Receipt>>,
25    /// Block's hashed state (unsorted).
26    pub hashed_state: Arc<HashedPostState>,
27    /// Trie updates that result from calculating the state root for the block (unsorted).
28    pub trie_updates: Arc<TrieUpdates>,
29}
30
31/// Represents a successfully built execution payload (block).
32///
33/// Provides access to the underlying block data, execution results, and associated metadata
34/// for payloads ready for execution or propagation.
35#[auto_impl::auto_impl(&, Arc)]
36pub trait BuiltPayload: Send + Sync + fmt::Debug {
37    /// The node's primitive types
38    type Primitives: NodePrimitives;
39
40    /// Returns the built block in its sealed (hash-verified) form.
41    fn block(&self) -> &SealedBlock<<Self::Primitives as NodePrimitives>::Block>;
42
43    /// Returns the total fees collected from all transactions in this block.
44    fn fees(&self) -> U256;
45
46    /// Returns the EIP-7928 block access list included in this payload.
47    ///
48    /// Returns `None` for payloads that do not carry a block access list.
49    fn block_access_list(&self) -> Option<&Bytes> {
50        None
51    }
52
53    /// Returns the complete execution result including state updates.
54    ///
55    /// Returns `None` if execution data is not available or not tracked.
56    fn executed_block(&self) -> Option<BuiltPayloadExecutedBlock<Self::Primitives>> {
57        None
58    }
59
60    /// Returns the EIP-7685 execution layer requests included in this block.
61    ///
62    /// These are requests generated by the execution layer that need to be
63    /// processed by the consensus layer (e.g., validator deposits, withdrawals).
64    fn requests(&self) -> Option<Requests>;
65}
66
67/// Basic attributes required to initiate payload construction.
68///
69/// Defines minimal parameters needed to build a new execution payload.
70/// Implementations must be serializable for transmission.
71pub trait PayloadAttributes:
72    serde::de::DeserializeOwned + serde::Serialize + fmt::Debug + Clone + Send + Sync + 'static
73{
74    /// Computes the unique identifier for this payload build job.
75    fn payload_id(&self, parent_hash: &B256) -> PayloadId;
76
77    /// Returns the timestamp for the new payload.
78    fn timestamp(&self) -> u64;
79
80    /// Returns the withdrawals to be included in the payload.
81    ///
82    /// `Some` for post-Shanghai blocks, `None` for earlier blocks.
83    fn withdrawals(&self) -> Option<&Vec<Withdrawal>>;
84
85    /// Returns the parent beacon block root.
86    ///
87    /// `Some` for post-merge blocks, `None` for pre-merge blocks.
88    fn parent_beacon_block_root(&self) -> Option<B256>;
89
90    /// Returns the slot number for the new payload.
91    ///
92    /// `Some` for post-Amsterdam blocks, `None` for earlier blocks.
93    fn slot_number(&self) -> Option<u64>;
94
95    /// Returns the target gas limit for the new payload.
96    ///
97    /// `Some` for payload attributes that specify the desired gas limit, `None` if the builder
98    /// should use its configured target.
99    fn target_gas_limit(&self) -> Option<u64> {
100        None
101    }
102
103    /// Returns the EIP-7805 inclusion-list transactions supplied by the consensus layer.
104    fn inclusion_list_transactions(&self) -> Option<&[Bytes]> {
105        None
106    }
107}
108
109impl PayloadAttributes for EthPayloadAttributes {
110    fn payload_id(&self, parent_hash: &B256) -> PayloadId {
111        payload_id(parent_hash, self)
112    }
113
114    fn timestamp(&self) -> u64 {
115        self.timestamp
116    }
117
118    fn withdrawals(&self) -> Option<&Vec<Withdrawal>> {
119        self.withdrawals.as_ref()
120    }
121
122    fn parent_beacon_block_root(&self) -> Option<B256> {
123        self.parent_beacon_block_root
124    }
125
126    fn slot_number(&self) -> Option<u64> {
127        self.slot_number
128    }
129
130    fn target_gas_limit(&self) -> Option<u64> {
131        self.target_gas_limit
132    }
133}
134
135/// Factory trait for creating payload attributes.
136///
137/// Enables different strategies for generating payload attributes based on
138/// contextual information. Useful for testing and specialized building.
139pub trait PayloadAttributesBuilder<Attributes, Header = alloy_consensus::Header>:
140    Send + Sync + 'static
141{
142    /// Constructs new payload attributes for the given timestamp.
143    fn build(&self, parent: &SealedHeader<Header>) -> Attributes;
144}
145
146impl<Attributes, Header, F> PayloadAttributesBuilder<Attributes, Header> for F
147where
148    Header: Clone,
149    F: Fn(SealedHeader<Header>) -> Attributes + Send + Sync + 'static,
150{
151    fn build(&self, parent: &SealedHeader<Header>) -> Attributes {
152        self(parent.clone())
153    }
154}
155
156impl<Attributes, Header, L, R> PayloadAttributesBuilder<Attributes, Header> for Either<L, R>
157where
158    L: PayloadAttributesBuilder<Attributes, Header>,
159    R: PayloadAttributesBuilder<Attributes, Header>,
160{
161    fn build(&self, parent: &SealedHeader<Header>) -> Attributes {
162        match self {
163            Self::Left(l) => l.build(parent),
164            Self::Right(r) => r.build(parent),
165        }
166    }
167}
168
169impl<Attributes, Header> PayloadAttributesBuilder<Attributes, Header>
170    for Box<dyn PayloadAttributesBuilder<Attributes, Header>>
171where
172    Header: 'static,
173    Attributes: 'static,
174{
175    fn build(&self, parent: &SealedHeader<Header>) -> Attributes {
176        self.as_ref().build(parent)
177    }
178}
179
180/// Trait to build the EVM environment for the next block from the given payload attributes.
181///
182/// Accepts payload attributes from CL, parent header and additional payload builder context.
183pub trait BuildNextEnv<Attributes, Header, Ctx>: Sized {
184    /// Builds the EVM environment for the next block from the given payload attributes.
185    fn build_next_env(
186        attributes: &Attributes,
187        parent: &SealedHeader<Header>,
188        ctx: &Ctx,
189    ) -> Result<Self, PayloadBuilderError>;
190}
191
192/// Generates the payload id for the configured payload from the [`PayloadAttributes`].
193///
194/// Returns an 8-byte identifier by hashing the payload components with sha256 hash.
195pub fn payload_id(
196    parent: &B256,
197    attributes: &alloy_rpc_types_engine::PayloadAttributes,
198) -> PayloadId {
199    let mut hasher = sha2::Sha256::new();
200    hasher.update(parent.as_slice());
201    hasher.update(&attributes.timestamp.to_be_bytes()[..]);
202    hasher.update(attributes.prev_randao.as_slice());
203    hasher.update(attributes.suggested_fee_recipient.as_slice());
204    if let Some(withdrawals) = &attributes.withdrawals {
205        hasher.update(alloy_rlp::encode(withdrawals));
206    }
207
208    if let Some(parent_beacon_block) = attributes.parent_beacon_block_root {
209        hasher.update(parent_beacon_block);
210    }
211
212    if let Some(slot_number) = attributes.slot_number {
213        hasher.update(slot_number.to_be_bytes());
214    }
215
216    if let Some(target_gas_limit) = attributes.target_gas_limit {
217        hasher.update(target_gas_limit.to_be_bytes());
218    }
219
220    let out = hasher.finalize();
221
222    #[allow(deprecated)] // generic-array 0.14 deprecated
223    PayloadId::new(out.as_slice()[..8].try_into().expect("sufficient length"))
224}
225
226#[cfg(test)]
227mod tests {
228    use super::*;
229    use alloy_eips::eip4895::Withdrawal;
230    use alloy_primitives::{address, b256, b64, Address};
231
232    #[test]
233    fn attributes_serde() {
234        let attributes = r#"{"timestamp":"0x1235","prevRandao":"0xf343b00e02dc34ec0124241f74f32191be28fb370bb48060f5fa4df99bda774c","suggestedFeeRecipient":"0x0000000000000000000000000000000000000000","withdrawals":null,"parentBeaconBlockRoot":null}"#;
235        let _attributes: EthPayloadAttributes = serde_json::from_str(attributes).unwrap();
236    }
237
238    #[test]
239    fn test_payload_id_basic() {
240        // Create a parent block and payload attributes
241        let parent = b256!("0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a");
242        let attributes = EthPayloadAttributes {
243            timestamp: 0x5,
244            prev_randao: B256::ZERO,
245            suggested_fee_recipient: address!("0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b"),
246            withdrawals: None,
247            parent_beacon_block_root: None,
248            slot_number: None,
249            ..Default::default()
250        };
251
252        // Verify that the generated payload ID matches the expected value
253        assert_eq!(payload_id(&parent, &attributes), PayloadId(b64!("0xa247243752eb10b4")));
254    }
255
256    #[test]
257    fn test_payload_id_with_withdrawals() {
258        // Set up the parent and attributes with withdrawals
259        let parent = b256!("0x9876543210abcdef9876543210abcdef9876543210abcdef9876543210abcdef");
260        let attributes = EthPayloadAttributes {
261            timestamp: 1622553200,
262            prev_randao: B256::from_slice(&[1; 32]),
263            suggested_fee_recipient: address!("0xb94f5374fce5edbc8e2a8697c15331677e6ebf0b"),
264            withdrawals: Some(vec![
265                Withdrawal {
266                    index: 1,
267                    validator_index: 123,
268                    address: Address::repeat_byte(0xAA),
269                    amount: 10,
270                },
271                Withdrawal {
272                    index: 2,
273                    validator_index: 456,
274                    address: Address::repeat_byte(0xBB),
275                    amount: 20,
276                },
277            ]),
278            parent_beacon_block_root: None,
279            slot_number: None,
280            ..Default::default()
281        };
282
283        // Verify that the generated payload ID matches the expected value
284        assert_eq!(payload_id(&parent, &attributes), PayloadId(b64!("0xedddc2f84ba59865")));
285    }
286
287    #[test]
288    fn test_payload_id_with_parent_beacon_block_root() {
289        // Set up the parent and attributes with a parent beacon block root
290        let parent = b256!("0x9876543210abcdef9876543210abcdef9876543210abcdef9876543210abcdef");
291        let attributes = EthPayloadAttributes {
292            timestamp: 1622553200,
293            prev_randao: b256!(
294                "0x123456789abcdef123456789abcdef123456789abcdef123456789abcdef1234"
295            ),
296            suggested_fee_recipient: address!("0xc94f5374fce5edbc8e2a8697c15331677e6ebf0b"),
297            withdrawals: None,
298            parent_beacon_block_root: Some(B256::repeat_byte(0x22)),
299            slot_number: None,
300            ..Default::default()
301        };
302
303        // Verify that the generated payload ID matches the expected value
304        assert_eq!(payload_id(&parent, &attributes), PayloadId(b64!("0x0fc49cd532094cce")));
305    }
306
307    #[test]
308    fn test_payload_id_with_slot_number() {
309        let parent = b256!("0x9876543210abcdef9876543210abcdef9876543210abcdef9876543210abcdef");
310        let mut attributes = EthPayloadAttributes {
311            timestamp: 1622553200,
312            prev_randao: B256::from_slice(&[1; 32]),
313            suggested_fee_recipient: address!("0xb94f5374fce5edbc8e2a8697c15331677e6ebf0b"),
314            withdrawals: Some(vec![]),
315            parent_beacon_block_root: Some(B256::from_slice(&[2; 32])),
316            slot_number: Some(1),
317            ..Default::default()
318        };
319
320        let first = payload_id(&parent, &attributes);
321        attributes.slot_number = Some(2);
322
323        assert_ne!(first, payload_id(&parent, &attributes));
324    }
325
326    #[test]
327    fn test_payload_id_with_target_gas_limit() {
328        let parent = b256!("0x9876543210abcdef9876543210abcdef9876543210abcdef9876543210abcdef");
329        #[allow(clippy::needless_update)]
330        let mut attributes = EthPayloadAttributes {
331            timestamp: 1622553200,
332            prev_randao: B256::from_slice(&[1; 32]),
333            suggested_fee_recipient: address!("0xb94f5374fce5edbc8e2a8697c15331677e6ebf0b"),
334            withdrawals: Some(vec![]),
335            parent_beacon_block_root: Some(B256::from_slice(&[2; 32])),
336            slot_number: Some(1),
337            target_gas_limit: Some(30_000_000),
338            ..Default::default()
339        };
340
341        let first = payload_id(&parent, &attributes);
342        attributes.target_gas_limit = Some(60_000_000);
343
344        assert_ne!(first, payload_id(&parent, &attributes));
345    }
346}
reth_payload_primitives/traits.rs

reth_payload_primitives/
traits.rs
