reth_transaction_pool/
error.rs

1//! Transaction pool errors
2
3use std::any::Any;
4
5use alloy_eips::eip4844::BlobTransactionValidationError;
6use alloy_primitives::{Address, TxHash, U256};
7use reth_primitives_traits::transaction::error::InvalidTransactionError;
8
9/// Transaction pool result type.
10pub type PoolResult<T> = Result<T, PoolError>;
11
12/// A trait for additional errors that can be thrown by the transaction pool.
13///
14/// For example during validation
15/// [`TransactionValidator::validate_transaction`](crate::validate::TransactionValidator::validate_transaction)
16pub trait PoolTransactionError: core::error::Error + Send + Sync {
17    /// Returns `true` if the error was caused by a transaction that is considered bad in the
18    /// context of the transaction pool and warrants peer penalization.
19    ///
20    /// See [`PoolError::is_bad_transaction`].
21    fn is_bad_transaction(&self) -> bool;
22
23    /// Returns a reference to `self` as a `&dyn Any`, enabling downcasting.
24    fn as_any(&self) -> &dyn Any;
25}
26
27// Needed for `#[error(transparent)]`
28impl core::error::Error for Box<dyn PoolTransactionError> {
29    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
30        (**self).source()
31    }
32}
33
34/// Transaction pool error.
35#[derive(Debug, thiserror::Error)]
36#[error("[{hash}]: {kind}")]
37pub struct PoolError {
38    /// The transaction hash that caused the error.
39    pub hash: TxHash,
40    /// The error kind.
41    pub kind: PoolErrorKind,
42}
43
44/// Transaction pool error kind.
45#[derive(Debug, thiserror::Error)]
46pub enum PoolErrorKind {
47    /// Same transaction already imported
48    #[error("already imported")]
49    AlreadyImported,
50    /// Thrown if a replacement transaction's gas price is below the already imported transaction
51    #[error("insufficient gas price to replace existing transaction")]
52    ReplacementUnderpriced,
53    /// The fee cap of the transaction is below the minimum fee cap determined by the protocol
54    #[error("transaction feeCap {0} below chain minimum")]
55    FeeCapBelowMinimumProtocolFeeCap(u128),
56    /// Thrown when the number of unique transactions of a sender exceeded the slot capacity.
57    #[error("rejected due to {0} being identified as a spammer")]
58    SpammerExceededCapacity(Address),
59    /// Thrown when a new transaction is added to the pool, but then immediately discarded to
60    /// respect the size limits of the pool.
61    #[error("transaction discarded outright due to pool size constraints")]
62    DiscardedOnInsert,
63    /// Thrown when the transaction is considered invalid.
64    #[error(transparent)]
65    InvalidTransaction(#[from] InvalidPoolTransactionError),
66    /// Thrown if the mutual exclusivity constraint (blob vs normal transaction) is violated.
67    #[error("transaction type {1} conflicts with existing transaction for {0}")]
68    ExistingConflictingTransactionType(Address, u8),
69    /// Any other error that occurred while inserting/validating a transaction. e.g. IO database
70    /// error
71    #[error(transparent)]
72    Other(#[from] Box<dyn core::error::Error + Send + Sync>),
73}
74
75// === impl PoolError ===
76
77impl PoolError {
78    /// Creates a new pool error.
79    pub fn new(hash: TxHash, kind: impl Into<PoolErrorKind>) -> Self {
80        Self { hash, kind: kind.into() }
81    }
82
83    /// Creates a new pool error with the `Other` kind.
84    pub fn other(
85        hash: TxHash,
86        error: impl Into<Box<dyn core::error::Error + Send + Sync>>,
87    ) -> Self {
88        Self { hash, kind: PoolErrorKind::Other(error.into()) }
89    }
90
91    /// Returns `true` if the error was caused by a transaction that is considered bad in the
92    /// context of the transaction pool and warrants peer penalization.
93    ///
94    /// Not all error variants are caused by the incorrect composition of the transaction (See also
95    /// [`InvalidPoolTransactionError`]) and can be caused by the current state of the transaction
96    /// pool. For example the transaction pool is already full or the error was caused my an
97    /// internal error, such as database errors.
98    ///
99    /// This function returns true only if the transaction will never make it into the pool because
100    /// its composition is invalid and the original sender should have detected this as well. This
101    /// is used to determine whether the original sender should be penalized for sending an
102    /// erroneous transaction.
103    #[inline]
104    pub fn is_bad_transaction(&self) -> bool {
105        #[expect(clippy::match_same_arms)]
106        match &self.kind {
107            PoolErrorKind::AlreadyImported => {
108                // already imported but not bad
109                false
110            }
111            PoolErrorKind::ReplacementUnderpriced => {
112                // already imported but not bad
113                false
114            }
115            PoolErrorKind::FeeCapBelowMinimumProtocolFeeCap(_) => {
116                // fee cap of the tx below the technical minimum determined by the protocol, see
117                // [MINIMUM_PROTOCOL_FEE_CAP](alloy_primitives::constants::MIN_PROTOCOL_BASE_FEE)
118                // although this transaction will always be invalid, we do not want to penalize the
119                // sender because this check simply could not be implemented by the client
120                false
121            }
122            PoolErrorKind::SpammerExceededCapacity(_) => {
123                // the sender exceeded the slot capacity, we should not penalize the peer for
124                // sending the tx because we don't know if all the transactions are sent from the
125                // same peer, there's also a chance that old transactions haven't been cleared yet
126                // (pool lags behind) and old transaction still occupy a slot in the pool
127                false
128            }
129            PoolErrorKind::DiscardedOnInsert => {
130                // valid tx but dropped due to size constraints
131                false
132            }
133            PoolErrorKind::InvalidTransaction(err) => {
134                // transaction rejected because it violates constraints
135                err.is_bad_transaction()
136            }
137            PoolErrorKind::Other(_) => {
138                // internal error unrelated to the transaction
139                false
140            }
141            PoolErrorKind::ExistingConflictingTransactionType(_, _) => {
142                // this is not a protocol error but an implementation error since the pool enforces
143                // exclusivity (blob vs normal tx) for all senders
144                false
145            }
146        }
147    }
148}
149
150/// Represents all errors that can happen when validating transactions for the pool for EIP-4844
151/// transactions
152#[derive(Debug, thiserror::Error)]
153pub enum Eip4844PoolTransactionError {
154    /// Thrown if we're unable to find the blob for a transaction that was previously extracted
155    #[error("blob sidecar not found for EIP4844 transaction")]
156    MissingEip4844BlobSidecar,
157    /// Thrown if an EIP-4844 transaction without any blobs arrives
158    #[error("blobless blob transaction")]
159    NoEip4844Blobs,
160    /// Thrown if an EIP-4844 transaction without any blobs arrives
161    #[error("too many blobs in transaction: have {have}, permitted {permitted}")]
162    TooManyEip4844Blobs {
163        /// Number of blobs the transaction has
164        have: u64,
165        /// Number of maximum blobs the transaction can have
166        permitted: u64,
167    },
168    /// Thrown if validating the blob sidecar for the transaction failed.
169    #[error(transparent)]
170    InvalidEip4844Blob(BlobTransactionValidationError),
171    /// EIP-4844 transactions are only accepted if they're gapless, meaning the previous nonce of
172    /// the transaction (`tx.nonce -1`) must either be in the pool or match the on chain nonce of
173    /// the sender.
174    ///
175    /// This error is thrown on validation if a valid blob transaction arrives with a nonce that
176    /// would introduce gap in the nonce sequence.
177    #[error("nonce too high")]
178    Eip4844NonceGap,
179    /// Thrown if blob transaction has an EIP-7594 style sidecar before Osaka.
180    #[error("unexpected eip-7594 sidecar before osaka")]
181    UnexpectedEip7594SidecarBeforeOsaka,
182    /// Thrown if blob transaction has an EIP-4844 style sidecar after Osaka.
183    #[error("unexpected eip-4844 sidecar after osaka")]
184    UnexpectedEip4844SidecarAfterOsaka,
185}
186
187/// Represents all errors that can happen when validating transactions for the pool for EIP-7702
188/// transactions
189#[derive(Debug, thiserror::Error)]
190pub enum Eip7702PoolTransactionError {
191    /// Thrown if the transaction has no items in its authorization list
192    #[error("no items in authorization list for EIP7702 transaction")]
193    MissingEip7702AuthorizationList,
194    /// Returned when a transaction with a nonce
195    /// gap is received from accounts with a deployed delegation or pending delegation.
196    #[error("gapped-nonce tx from delegated accounts")]
197    OutOfOrderTxFromDelegated,
198    /// Returned when the maximum number of in-flight
199    /// transactions is reached for specific accounts.
200    #[error("in-flight transaction limit reached for delegated accounts")]
201    InflightTxLimitReached,
202    /// Returned if a transaction has an authorization
203    /// signed by an address which already has in-flight transactions known to the
204    /// pool.
205    #[error("authority already reserved")]
206    AuthorityReserved,
207}
208
209/// Represents errors that can happen when validating transactions for the pool
210///
211/// See [`TransactionValidator`](crate::TransactionValidator).
212#[derive(Debug, thiserror::Error)]
213pub enum InvalidPoolTransactionError {
214    /// Hard consensus errors
215    #[error(transparent)]
216    Consensus(#[from] InvalidTransactionError),
217    /// Thrown when a new transaction is added to the pool, but then immediately discarded to
218    /// respect the size limits of the pool.
219    #[error("transaction's gas limit {0} exceeds block's gas limit {1}")]
220    ExceedsGasLimit(u64, u64),
221    /// Thrown when a transaction's gas limit exceeds the configured maximum per-transaction limit.
222    #[error("transaction's gas limit {0} exceeds maximum per-transaction gas limit {1}")]
223    MaxTxGasLimitExceeded(u64, u64),
224    /// Thrown when a new transaction is added to the pool, but then immediately discarded to
225    /// respect the tx fee exceeds the configured cap
226    #[error("tx fee ({max_tx_fee_wei} wei) exceeds the configured cap ({tx_fee_cap_wei} wei)")]
227    ExceedsFeeCap {
228        /// max fee in wei of new tx submitted to the pull (e.g. 0.11534 ETH)
229        max_tx_fee_wei: u128,
230        /// configured tx fee cap in wei (e.g. 1.0 ETH)
231        tx_fee_cap_wei: u128,
232    },
233    /// Thrown when a new transaction is added to the pool, but then immediately discarded to
234    /// respect the `max_init_code_size`.
235    #[error("transaction's input size {0} exceeds max_init_code_size {1}")]
236    ExceedsMaxInitCodeSize(usize, usize),
237    /// Thrown if the input data of a transaction is greater
238    /// than some meaningful limit a user might use. This is not a consensus error
239    /// making the transaction invalid, rather a DOS protection.
240    #[error("input data too large")]
241    OversizedData(usize, usize),
242    /// Thrown if the transaction's fee is below the minimum fee
243    #[error("transaction underpriced")]
244    Underpriced,
245    /// Thrown if the transaction's would require an account to be overdrawn
246    #[error("transaction overdraws from account, balance: {balance}, cost: {cost}")]
247    Overdraft {
248        /// Cost transaction is allowed to consume. See `reth_transaction_pool::PoolTransaction`.
249        cost: U256,
250        /// Balance of account.
251        balance: U256,
252    },
253    /// EIP-2681 error thrown if the nonce is higher or equal than `U64::max`
254    /// `<https://eips.ethereum.org/EIPS/eip-2681>`
255    #[error("nonce exceeds u64 limit")]
256    Eip2681,
257    /// EIP-4844 related errors
258    #[error(transparent)]
259    Eip4844(#[from] Eip4844PoolTransactionError),
260    /// EIP-7702 related errors
261    #[error(transparent)]
262    Eip7702(#[from] Eip7702PoolTransactionError),
263    /// Any other error that occurred while inserting/validating that is transaction specific
264    #[error(transparent)]
265    Other(Box<dyn PoolTransactionError>),
266    /// The transaction is specified to use less gas than required to start the
267    /// invocation.
268    #[error("intrinsic gas too low")]
269    IntrinsicGasTooLow,
270    /// The transaction priority fee is below the minimum required priority fee.
271    #[error("transaction priority fee below minimum required priority fee {minimum_priority_fee}")]
272    PriorityFeeBelowMinimum {
273        /// Minimum required priority fee.
274        minimum_priority_fee: u128,
275    },
276}
277
278// === impl InvalidPoolTransactionError ===
279
280impl InvalidPoolTransactionError {
281    /// Returns a new [`InvalidPoolTransactionError::Other`] instance with the given
282    /// [`PoolTransactionError`].
283    pub fn other<E: PoolTransactionError + 'static>(err: E) -> Self {
284        Self::Other(Box::new(err))
285    }
286
287    /// Returns `true` if the error was caused by a transaction that is considered bad in the
288    /// context of the transaction pool and warrants peer penalization.
289    ///
290    /// See [`PoolError::is_bad_transaction`].
291    #[expect(clippy::match_same_arms)]
292    #[inline]
293    fn is_bad_transaction(&self) -> bool {
294        match self {
295            Self::Consensus(err) => {
296                // transaction considered invalid by the consensus rules
297                // We do not consider the following errors to be erroneous transactions, since they
298                // depend on dynamic environmental conditions and should not be assumed to have been
299                // intentionally caused by the sender
300                match err {
301                    InvalidTransactionError::InsufficientFunds { .. } |
302                    InvalidTransactionError::NonceNotConsistent { .. } => {
303                        // transaction could just have arrived late/early
304                        false
305                    }
306                    InvalidTransactionError::GasTooLow |
307                    InvalidTransactionError::GasTooHigh |
308                    InvalidTransactionError::TipAboveFeeCap => {
309                        // these are technically not invalid
310                        false
311                    }
312                    InvalidTransactionError::FeeCapTooLow => {
313                        // dynamic, but not used during validation
314                        false
315                    }
316                    InvalidTransactionError::Eip2930Disabled |
317                    InvalidTransactionError::Eip1559Disabled |
318                    InvalidTransactionError::Eip4844Disabled |
319                    InvalidTransactionError::Eip7702Disabled => {
320                        // settings
321                        false
322                    }
323                    InvalidTransactionError::OldLegacyChainId |
324                    InvalidTransactionError::ChainIdMismatch |
325                    InvalidTransactionError::GasUintOverflow |
326                    InvalidTransactionError::TxTypeNotSupported |
327                    InvalidTransactionError::SignerAccountHasBytecode |
328                    InvalidTransactionError::GasLimitTooHigh => true,
329                }
330            }
331            Self::ExceedsGasLimit(_, _) => true,
332            Self::MaxTxGasLimitExceeded(_, _) => {
333                // local setting
334                false
335            }
336            Self::ExceedsFeeCap { max_tx_fee_wei: _, tx_fee_cap_wei: _ } => true,
337            Self::ExceedsMaxInitCodeSize(_, _) => true,
338            Self::OversizedData(_, _) => true,
339            Self::Underpriced => {
340                // local setting
341                false
342            }
343            Self::IntrinsicGasTooLow => true,
344            Self::Overdraft { .. } => false,
345            Self::Other(err) => err.is_bad_transaction(),
346            Self::Eip2681 => true,
347            Self::Eip4844(eip4844_err) => {
348                match eip4844_err {
349                    Eip4844PoolTransactionError::MissingEip4844BlobSidecar => {
350                        // this is only reachable when blob transactions are reinjected and we're
351                        // unable to find the previously extracted blob
352                        false
353                    }
354                    Eip4844PoolTransactionError::InvalidEip4844Blob(_) => {
355                        // This is only reachable when the blob is invalid
356                        true
357                    }
358                    Eip4844PoolTransactionError::Eip4844NonceGap => {
359                        // it is possible that the pool sees `nonce n` before `nonce n-1` and this
360                        // is only thrown for valid(good) blob transactions
361                        false
362                    }
363                    Eip4844PoolTransactionError::NoEip4844Blobs => {
364                        // this is a malformed transaction and should not be sent over the network
365                        true
366                    }
367                    Eip4844PoolTransactionError::TooManyEip4844Blobs { .. } => {
368                        // this is a malformed transaction and should not be sent over the network
369                        true
370                    }
371                    Eip4844PoolTransactionError::UnexpectedEip4844SidecarAfterOsaka |
372                    Eip4844PoolTransactionError::UnexpectedEip7594SidecarBeforeOsaka => {
373                        // for now we do not want to penalize peers for broadcasting different
374                        // sidecars
375                        false
376                    }
377                }
378            }
379            Self::Eip7702(eip7702_err) => match eip7702_err {
380                Eip7702PoolTransactionError::MissingEip7702AuthorizationList => {
381                    // as EIP-7702 specifies, 7702 transactions must have an non-empty authorization
382                    // list so this is a malformed transaction and should not be
383                    // sent over the network
384                    true
385                }
386                Eip7702PoolTransactionError::OutOfOrderTxFromDelegated => false,
387                Eip7702PoolTransactionError::InflightTxLimitReached => false,
388                Eip7702PoolTransactionError::AuthorityReserved => false,
389            },
390            Self::PriorityFeeBelowMinimum { .. } => false,
391        }
392    }
393
394    /// Returns `true` if an import failed due to an oversized transaction
395    pub const fn is_oversized(&self) -> bool {
396        matches!(self, Self::OversizedData(_, _))
397    }
398
399    /// Returns `true` if an import failed due to nonce gap.
400    pub const fn is_nonce_gap(&self) -> bool {
401        matches!(self, Self::Consensus(InvalidTransactionError::NonceNotConsistent { .. })) ||
402            matches!(self, Self::Eip4844(Eip4844PoolTransactionError::Eip4844NonceGap))
403    }
404
405    /// Returns the arbitrary error if it is [`InvalidPoolTransactionError::Other`]
406    pub fn as_other(&self) -> Option<&dyn PoolTransactionError> {
407        match self {
408            Self::Other(err) => Some(&**err),
409            _ => None,
410        }
411    }
412
413    /// Returns a reference to the [`InvalidPoolTransactionError::Other`] value if this type is a
414    /// [`InvalidPoolTransactionError::Other`] of that type. Returns None otherwise.
415    pub fn downcast_other_ref<T: core::error::Error + 'static>(&self) -> Option<&T> {
416        let other = self.as_other()?;
417        other.as_any().downcast_ref()
418    }
419
420    /// Returns true if the this type is a [`InvalidPoolTransactionError::Other`] of that error
421    /// type. Returns false otherwise.
422    pub fn is_other<T: core::error::Error + 'static>(&self) -> bool {
423        self.as_other().map(|err| err.as_any().is::<T>()).unwrap_or(false)
424    }
425}
426
427#[cfg(test)]
428mod tests {
429    use super::*;
430
431    #[derive(thiserror::Error, Debug)]
432    #[error("err")]
433    struct E;
434
435    impl PoolTransactionError for E {
436        fn is_bad_transaction(&self) -> bool {
437            false
438        }
439
440        fn as_any(&self) -> &dyn Any {
441            self
442        }
443    }
444
445    #[test]
446    fn other_downcast() {
447        let err = InvalidPoolTransactionError::Other(Box::new(E));
448        assert!(err.is_other::<E>());
449
450        assert!(err.downcast_other_ref::<E>().is_some());
451    }
452}