reth_payload_primitives/
traits.rs

1//! Core traits for working with execution payloads.
2
3use alloc::vec::Vec;
4use alloy_eips::{
5    eip4895::{Withdrawal, Withdrawals},
6    eip7685::Requests,
7};
8use alloy_primitives::{Address, B256, U256};
9use alloy_rpc_types_engine::{PayloadAttributes as EthPayloadAttributes, PayloadId};
10use core::fmt;
11use reth_chain_state::ExecutedBlockWithTrieUpdates;
12use reth_primitives_traits::{NodePrimitives, SealedBlock, SealedHeader};
13
14use crate::PayloadBuilderError;
15
16/// Represents a successfully built execution payload (block).
17///
18/// Provides access to the underlying block data, execution results, and associated metadata
19/// for payloads ready for execution or propagation.
20#[auto_impl::auto_impl(&, Arc)]
21pub trait BuiltPayload: Send + Sync + fmt::Debug {
22    /// The node's primitive types
23    type Primitives: NodePrimitives;
24
25    /// Returns the built block in its sealed (hash-verified) form.
26    fn block(&self) -> &SealedBlock<<Self::Primitives as NodePrimitives>::Block>;
27
28    /// Returns the total fees collected from all transactions in this block.
29    fn fees(&self) -> U256;
30
31    /// Returns the complete execution result including state updates.
32    ///
33    /// Returns `None` if execution data is not available or not tracked.
34    fn executed_block(&self) -> Option<ExecutedBlockWithTrieUpdates<Self::Primitives>> {
35        None
36    }
37
38    /// Returns the EIP-7685 execution layer requests included in this block.
39    ///
40    /// These are requests generated by the execution layer that need to be
41    /// processed by the consensus layer (e.g., validator deposits, withdrawals).
42    fn requests(&self) -> Option<Requests>;
43}
44
45/// Attributes used to guide the construction of a new execution payload.
46///
47/// Extends basic payload attributes with additional context needed during the
48/// building process, tracking in-progress payload jobs and their parameters.
49pub trait PayloadBuilderAttributes: Send + Sync + Unpin + fmt::Debug + 'static {
50    /// The external payload attributes format this type can be constructed from.
51    type RpcPayloadAttributes: Send + Sync + 'static;
52    /// The error type used in [`PayloadBuilderAttributes::try_new`].
53    type Error: core::error::Error + Send + Sync + 'static;
54
55    /// Constructs new builder attributes from external payload attributes.
56    ///
57    /// Validates attributes and generates a unique [`PayloadId`] based on the
58    /// parent block, attributes, and version.
59    fn try_new(
60        parent: B256,
61        rpc_payload_attributes: Self::RpcPayloadAttributes,
62        version: u8,
63    ) -> Result<Self, Self::Error>
64    where
65        Self: Sized;
66
67    /// Returns the unique identifier for this payload build job.
68    fn payload_id(&self) -> PayloadId;
69
70    /// Returns the hash of the parent block this payload builds on.
71    fn parent(&self) -> B256;
72
73    /// Returns the timestamp to be used in the payload's header.
74    fn timestamp(&self) -> u64;
75
76    /// Returns the beacon chain block root from the parent block.
77    ///
78    /// Returns `None` for pre-merge blocks or non-beacon contexts.
79    fn parent_beacon_block_root(&self) -> Option<B256>;
80
81    /// Returns the address that should receive transaction fees.
82    fn suggested_fee_recipient(&self) -> Address;
83
84    /// Returns the randomness value for this block.
85    fn prev_randao(&self) -> B256;
86
87    /// Returns the list of withdrawals to be processed in this block.
88    fn withdrawals(&self) -> &Withdrawals;
89}
90
91/// Basic attributes required to initiate payload construction.
92///
93/// Defines minimal parameters needed to build a new execution payload.
94/// Implementations must be serializable for transmission.
95pub trait PayloadAttributes:
96    serde::de::DeserializeOwned + serde::Serialize + fmt::Debug + Clone + Send + Sync + 'static
97{
98    /// Returns the timestamp for the new payload.
99    fn timestamp(&self) -> u64;
100
101    /// Returns the withdrawals to be included in the payload.
102    ///
103    /// `Some` for post-Shanghai blocks, `None` for earlier blocks.
104    fn withdrawals(&self) -> Option<&Vec<Withdrawal>>;
105
106    /// Returns the parent beacon block root.
107    ///
108    /// `Some` for post-merge blocks, `None` for pre-merge blocks.
109    fn parent_beacon_block_root(&self) -> Option<B256>;
110}
111
112impl PayloadAttributes for EthPayloadAttributes {
113    fn timestamp(&self) -> u64 {
114        self.timestamp
115    }
116
117    fn withdrawals(&self) -> Option<&Vec<Withdrawal>> {
118        self.withdrawals.as_ref()
119    }
120
121    fn parent_beacon_block_root(&self) -> Option<B256> {
122        self.parent_beacon_block_root
123    }
124}
125
126#[cfg(feature = "op")]
127impl PayloadAttributes for op_alloy_rpc_types_engine::OpPayloadAttributes {
128    fn timestamp(&self) -> u64 {
129        self.payload_attributes.timestamp
130    }
131
132    fn withdrawals(&self) -> Option<&Vec<Withdrawal>> {
133        self.payload_attributes.withdrawals.as_ref()
134    }
135
136    fn parent_beacon_block_root(&self) -> Option<B256> {
137        self.payload_attributes.parent_beacon_block_root
138    }
139}
140
141/// Factory trait for creating payload attributes.
142///
143/// Enables different strategies for generating payload attributes based on
144/// contextual information. Useful for testing and specialized building.
145pub trait PayloadAttributesBuilder<Attributes>: Send + Sync + 'static {
146    /// Constructs new payload attributes for the given timestamp.
147    fn build(&self, timestamp: u64) -> Attributes;
148}
149
150/// Trait to build the EVM environment for the next block from the given payload attributes.
151///
152/// Accepts payload attributes from CL, parent header and additional payload builder context.
153pub trait BuildNextEnv<Attributes, Header, Ctx>: Sized {
154    /// Builds the EVM environment for the next block from the given payload attributes.
155    fn build_next_env(
156        attributes: &Attributes,
157        parent: &SealedHeader<Header>,
158        ctx: &Ctx,
159    ) -> Result<Self, PayloadBuilderError>;
160}
reth_payload_primitives/traits.rs

reth_payload_primitives/
traits.rs
