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_rlp::Encodable;
8use alloy_rpc_types_engine::{PayloadAttributes as EthPayloadAttributes, PayloadId};
9use core::fmt;
10use either::Either;
11use reth_execution_types::BlockExecutionOutput;
12use reth_primitives_traits::{NodePrimitives, RecoveredBlock, SealedBlock, SealedHeader};
13use reth_trie_common::{updates::TrieUpdates, HashedPostState};
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
104impl PayloadAttributes for EthPayloadAttributes {
105    fn payload_id(&self, parent_hash: &B256) -> PayloadId {
106        payload_id(parent_hash, self)
107    }
108
109    fn timestamp(&self) -> u64 {
110        self.timestamp
111    }
112
113    fn withdrawals(&self) -> Option<&Vec<Withdrawal>> {
114        self.withdrawals.as_ref()
115    }
116
117    fn parent_beacon_block_root(&self) -> Option<B256> {
118        self.parent_beacon_block_root
119    }
120
121    fn slot_number(&self) -> Option<u64> {
122        self.slot_number
123    }
124
125    fn target_gas_limit(&self) -> Option<u64> {
126        self.target_gas_limit
127    }
128}
129
130/// Factory trait for creating payload attributes.
131///
132/// Enables different strategies for generating payload attributes based on
133/// contextual information. Useful for testing and specialized building.
134pub trait PayloadAttributesBuilder<Attributes, Header = alloy_consensus::Header>:
135    Send + Sync + 'static
136{
137    /// Constructs new payload attributes for the given timestamp.
138    fn build(&self, parent: &SealedHeader<Header>) -> Attributes;
139}
140
141impl<Attributes, Header, F> PayloadAttributesBuilder<Attributes, Header> for F
142where
143    Header: Clone,
144    F: Fn(SealedHeader<Header>) -> Attributes + Send + Sync + 'static,
145{
146    fn build(&self, parent: &SealedHeader<Header>) -> Attributes {
147        self(parent.clone())
148    }
149}
150
151impl<Attributes, Header, L, R> PayloadAttributesBuilder<Attributes, Header> for Either<L, R>
152where
153    L: PayloadAttributesBuilder<Attributes, Header>,
154    R: PayloadAttributesBuilder<Attributes, Header>,
155{
156    fn build(&self, parent: &SealedHeader<Header>) -> Attributes {
157        match self {
158            Self::Left(l) => l.build(parent),
159            Self::Right(r) => r.build(parent),
160        }
161    }
162}
163
164impl<Attributes, Header> PayloadAttributesBuilder<Attributes, Header>
165    for Box<dyn PayloadAttributesBuilder<Attributes, Header>>
166where
167    Header: 'static,
168    Attributes: 'static,
169{
170    fn build(&self, parent: &SealedHeader<Header>) -> Attributes {
171        self.as_ref().build(parent)
172    }
173}
174
175/// Trait to build the EVM environment for the next block from the given payload attributes.
176///
177/// Accepts payload attributes from CL, parent header and additional payload builder context.
178pub trait BuildNextEnv<Attributes, Header, Ctx>: Sized {
179    /// Builds the EVM environment for the next block from the given payload attributes.
180    fn build_next_env(
181        attributes: &Attributes,
182        parent: &SealedHeader<Header>,
183        ctx: &Ctx,
184    ) -> Result<Self, PayloadBuilderError>;
185}
186
187/// Generates the payload id for the configured payload from the [`PayloadAttributes`].
188///
189/// Returns an 8-byte identifier by hashing the payload components with sha256 hash.
190pub fn payload_id(
191    parent: &B256,
192    attributes: &alloy_rpc_types_engine::PayloadAttributes,
193) -> PayloadId {
194    use sha2::Digest;
195    let mut hasher = sha2::Sha256::new();
196    hasher.update(parent.as_slice());
197    hasher.update(&attributes.timestamp.to_be_bytes()[..]);
198    hasher.update(attributes.prev_randao.as_slice());
199    hasher.update(attributes.suggested_fee_recipient.as_slice());
200    if let Some(withdrawals) = &attributes.withdrawals {
201        let mut buf = Vec::new();
202        withdrawals.encode(&mut buf);
203        hasher.update(buf);
204    }
205
206    if let Some(parent_beacon_block) = attributes.parent_beacon_block_root {
207        hasher.update(parent_beacon_block);
208    }
209
210    let out = hasher.finalize();
211
212    #[allow(deprecated)] // generic-array 0.14 deprecated
213    PayloadId::new(out.as_slice()[..8].try_into().expect("sufficient length"))
214}
215
216#[cfg(test)]
217mod tests {
218    use super::*;
219    use alloy_eips::eip4895::Withdrawal;
220    use alloy_primitives::{Address, B64};
221    use core::str::FromStr;
222
223    #[test]
224    fn attributes_serde() {
225        let attributes = r#"{"timestamp":"0x1235","prevRandao":"0xf343b00e02dc34ec0124241f74f32191be28fb370bb48060f5fa4df99bda774c","suggestedFeeRecipient":"0x0000000000000000000000000000000000000000","withdrawals":null,"parentBeaconBlockRoot":null}"#;
226        let _attributes: EthPayloadAttributes = serde_json::from_str(attributes).unwrap();
227    }
228
229    #[test]
230    fn test_payload_id_basic() {
231        // Create a parent block and payload attributes
232        let parent =
233            B256::from_str("0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a")
234                .unwrap();
235        let attributes = EthPayloadAttributes {
236            timestamp: 0x5,
237            prev_randao: B256::from_str(
238                "0x0000000000000000000000000000000000000000000000000000000000000000",
239            )
240            .unwrap(),
241            suggested_fee_recipient: Address::from_str(
242                "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
243            )
244            .unwrap(),
245            withdrawals: None,
246            parent_beacon_block_root: None,
247            slot_number: None,
248            target_gas_limit: None,
249        };
250
251        // Verify that the generated payload ID matches the expected value
252        assert_eq!(
253            payload_id(&parent, &attributes),
254            PayloadId(B64::from_str("0xa247243752eb10b4").unwrap())
255        );
256    }
257
258    #[test]
259    fn test_payload_id_with_withdrawals() {
260        // Set up the parent and attributes with withdrawals
261        let parent =
262            B256::from_str("0x9876543210abcdef9876543210abcdef9876543210abcdef9876543210abcdef")
263                .unwrap();
264        let attributes = EthPayloadAttributes {
265            timestamp: 1622553200,
266            prev_randao: B256::from_slice(&[1; 32]),
267            suggested_fee_recipient: Address::from_str(
268                "0xb94f5374fce5edbc8e2a8697c15331677e6ebf0b",
269            )
270            .unwrap(),
271            withdrawals: Some(vec![
272                Withdrawal {
273                    index: 1,
274                    validator_index: 123,
275                    address: Address::from([0xAA; 20]),
276                    amount: 10,
277                },
278                Withdrawal {
279                    index: 2,
280                    validator_index: 456,
281                    address: Address::from([0xBB; 20]),
282                    amount: 20,
283                },
284            ]),
285            parent_beacon_block_root: None,
286            slot_number: None,
287            target_gas_limit: None,
288        };
289
290        // Verify that the generated payload ID matches the expected value
291        assert_eq!(
292            payload_id(&parent, &attributes),
293            PayloadId(B64::from_str("0xedddc2f84ba59865").unwrap())
294        );
295    }
296
297    #[test]
298    fn test_payload_id_with_parent_beacon_block_root() {
299        // Set up the parent and attributes with a parent beacon block root
300        let parent =
301            B256::from_str("0x9876543210abcdef9876543210abcdef9876543210abcdef9876543210abcdef")
302                .unwrap();
303        let attributes = EthPayloadAttributes {
304            timestamp: 1622553200,
305            prev_randao: B256::from_str(
306                "0x123456789abcdef123456789abcdef123456789abcdef123456789abcdef1234",
307            )
308            .unwrap(),
309            suggested_fee_recipient: Address::from_str(
310                "0xc94f5374fce5edbc8e2a8697c15331677e6ebf0b",
311            )
312            .unwrap(),
313            withdrawals: None,
314            parent_beacon_block_root: Some(
315                B256::from_str(
316                    "0x2222222222222222222222222222222222222222222222222222222222222222",
317                )
318                .unwrap(),
319            ),
320            slot_number: None,
321            target_gas_limit: None,
322        };
323
324        // Verify that the generated payload ID matches the expected value
325        assert_eq!(
326            payload_id(&parent, &attributes),
327            PayloadId(B64::from_str("0x0fc49cd532094cce").unwrap())
328        );
329    }
330}
reth_payload_primitives/traits.rs

reth_payload_primitives/
traits.rs
