reth_payload_primitives/
error.rs

1//! Error types for payload operations.
2
3use alloc::{boxed::Box, string::ToString};
4use alloy_primitives::B256;
5use alloy_rpc_types_engine::{ForkchoiceUpdateError, PayloadError, PayloadStatusEnum};
6use core::error;
7use reth_errors::{BlockExecutionError, ProviderError, RethError};
8use tokio::sync::{mpsc, oneshot};
9
10/// Possible error variants during payload building.
11#[derive(Debug, thiserror::Error)]
12pub enum PayloadBuilderError {
13    /// Thrown when the parent header cannot be found
14    #[error("missing parent header: {0}")]
15    MissingParentHeader(B256),
16    /// Thrown when the parent block is missing.
17    #[error("missing parent block {0}")]
18    MissingParentBlock(B256),
19    /// An oneshot channels has been closed.
20    #[error("sender has been dropped")]
21    ChannelClosed,
22    /// If there's no payload to resolve.
23    #[error("missing payload")]
24    MissingPayload,
25    /// Other internal error
26    #[error(transparent)]
27    Internal(#[from] RethError),
28    /// Unrecoverable error during evm execution.
29    #[error("evm execution error: {0}")]
30    EvmExecutionError(Box<dyn core::error::Error + Send + Sync>),
31    /// Any other payload building errors.
32    #[error(transparent)]
33    Other(Box<dyn core::error::Error + Send + Sync>),
34    /// The payload attributes are invalid on top of the parent block, e.g. a transaction they
35    /// include is invalid.
36    ///
37    /// Returned from `PayloadJobGenerator::new_payload_job`, this is the only variant that rejects
38    /// the attributes; returned later from a running job, it is an internal error like any other.
39    /// Failures of this node, such as a failed state read during execution, must use another
40    /// variant.
41    #[error("invalid payload attributes: {0}")]
42    InvalidAttributes(Box<dyn core::error::Error + Send + Sync>),
43}
44
45impl PayloadBuilderError {
46    /// Create a new EVM error from a boxed error.
47    pub fn evm<E>(error: E) -> Self
48    where
49        E: core::error::Error + Send + Sync + 'static,
50    {
51        Self::EvmExecutionError(Box::new(error))
52    }
53
54    /// Create a new error from a boxed error.
55    pub fn other<E>(error: E) -> Self
56    where
57        E: core::error::Error + Send + Sync + 'static,
58    {
59        Self::Other(Box::new(error))
60    }
61
62    /// Create a new error that rejects the payload attributes.
63    pub fn invalid_attributes<E>(error: E) -> Self
64    where
65        E: core::error::Error + Send + Sync + 'static,
66    {
67        Self::InvalidAttributes(Box::new(error))
68    }
69}
70
71impl From<ProviderError> for PayloadBuilderError {
72    fn from(error: ProviderError) -> Self {
73        Self::Internal(RethError::Provider(error))
74    }
75}
76
77impl From<oneshot::error::RecvError> for PayloadBuilderError {
78    fn from(_: oneshot::error::RecvError) -> Self {
79        Self::ChannelClosed
80    }
81}
82
83impl From<BlockExecutionError> for PayloadBuilderError {
84    fn from(error: BlockExecutionError) -> Self {
85        Self::evm(error)
86    }
87}
88
89impl<T> From<mpsc::error::SendError<T>> for PayloadBuilderError {
90    fn from(_: mpsc::error::SendError<T>) -> Self {
91        Self::ChannelClosed
92    }
93}
94
95/// Thrown when the payload or attributes are known to be invalid __before__ processing.
96///
97/// This is used mainly for
98/// [`validate_version_specific_fields`](crate::validate_version_specific_fields), which validates
99/// both execution payloads and forkchoice update attributes with respect to a method version.
100#[derive(thiserror::Error, Debug)]
101pub enum EngineObjectValidationError {
102    /// Thrown when the underlying validation error occurred while validating an
103    /// `ExecutionPayload`.
104    #[error("Payload validation error: {0}")]
105    Payload(VersionSpecificValidationError),
106
107    /// Thrown when the underlying validation error occurred while validating a
108    /// `PayloadAttributes`.
109    #[error("Payload attributes validation error: {0}")]
110    PayloadAttributes(VersionSpecificValidationError),
111
112    /// Thrown if `PayloadAttributes` or `ExecutionPayload` were provided with a timestamp, but the
113    /// version of the engine method called is meant for a fork that occurs after the provided
114    /// timestamp.
115    #[error("Unsupported fork")]
116    UnsupportedFork,
117    /// Another type of error that is not covered by the above variants.
118    #[error("Invalid params: {0}")]
119    InvalidParams(#[from] Box<dyn core::error::Error + Send + Sync>),
120}
121
122/// Thrown when validating an execution payload OR payload attributes fails due to:
123/// * The existence of a new field that is not supported in the given engine method version, or
124/// * The absence of a field that is required in the given engine method version
125#[derive(thiserror::Error, Debug)]
126pub enum VersionSpecificValidationError {
127    /// Thrown if the pre-V3 `PayloadAttributes` or `ExecutionPayload` contains a parent beacon
128    /// block root
129    #[error("parent beacon block root not supported before V3")]
130    ParentBeaconBlockRootNotSupportedBeforeV3,
131    /// Thrown if `engine_forkchoiceUpdatedV1` or `engine_newPayloadV1` contains withdrawals
132    #[error("withdrawals not supported in V1")]
133    WithdrawalsNotSupportedInV1,
134    /// Thrown if an engine method requires withdrawals but none are provided.
135    #[error("no withdrawals post-Shanghai")]
136    NoWithdrawalsPostShanghai,
137    /// Thrown if V2 `PayloadAttributes` or `ExecutionPayload` contains withdrawals before
138    /// Shanghai.
139    #[error("withdrawals pre-Shanghai")]
140    HasWithdrawalsPreShanghai,
141    /// Thrown if the `PayloadAttributes` or `ExecutionPayload` contains no parent beacon block
142    /// root after Cancun
143    #[error("no parent beacon block root post-cancun")]
144    NoParentBeaconBlockRootPostCancun,
145    /// Thrown if the current engine method version does not support a block access list
146    #[error("block access list not supported in this engine API version")]
147    BlockAccessListNotSupported,
148    /// Thrown if an engine method that requires a block access list does not contain one.
149    #[error("no block access list post-Amsterdam")]
150    NoBlockAccessListPostAmsterdam,
151    /// Thrown if the current engine method version does not support a slot number
152    #[error("slot number not supported in this engine API version")]
153    SlotNumberNotSupported,
154    /// Thrown if an engine method that requires a slot number does not contain one.
155    #[error("no slot number post-Amsterdam")]
156    NoSlotNumberPostAmsterdam,
157}
158
159/// Error validating payload received over `newPayload` API.
160#[derive(thiserror::Error, Debug)]
161pub enum NewPayloadError {
162    /// Payload validation error.
163    #[error(transparent)]
164    Eth(#[from] PayloadError),
165    /// Custom payload validation error.
166    #[error(transparent)]
167    Other(Box<dyn error::Error + Send + Sync>),
168}
169
170impl NewPayloadError {
171    /// Creates instance of variant [`NewPayloadError::Other`].
172    #[inline]
173    pub fn other(err: impl error::Error + Send + Sync + 'static) -> Self {
174        Self::Other(Box::new(err))
175    }
176
177    /// Returns `true` if the error is caused by a block hash mismatch.
178    #[inline]
179    pub const fn is_block_hash_mismatch(&self) -> bool {
180        matches!(self, Self::Eth(PayloadError::BlockHash { .. }))
181    }
182
183    /// Returns `true` if the error is caused by invalid block hashes (Cancun).
184    #[inline]
185    pub const fn is_invalid_versioned_hashes(&self) -> bool {
186        matches!(self, Self::Eth(PayloadError::InvalidVersionedHashes))
187    }
188}
189
190impl From<NewPayloadError> for PayloadStatusEnum {
191    fn from(error: NewPayloadError) -> Self {
192        Self::Invalid { validation_error: error.to_string() }
193    }
194}
195
196impl EngineObjectValidationError {
197    /// Creates an instance of the `InvalidParams` variant with the given error.
198    pub fn invalid_params<E>(error: E) -> Self
199    where
200        E: core::error::Error + Send + Sync + 'static,
201    {
202        Self::InvalidParams(Box::new(error))
203    }
204}
205
206/// Thrown when validating the correctness of a payloadattributes object.
207#[derive(thiserror::Error, Debug)]
208pub enum InvalidPayloadAttributesError {
209    /// Thrown if the timestamp of the payload attributes is invalid according to the engine specs.
210    #[error("invalid timestamp")]
211    InvalidTimestamp,
212    /// Another type of error that is not covered by the above variants.
213    #[error("Invalid params: {0}")]
214    InvalidParams(#[from] Box<dyn core::error::Error + Send + Sync>),
215}
216
217impl From<InvalidPayloadAttributesError> for ForkchoiceUpdateError {
218    fn from(_: InvalidPayloadAttributesError) -> Self {
219        Self::UpdatedInvalidPayloadAttributes
220    }
221}
reth_payload_primitives/error.rs

reth_payload_primitives/
error.rs
