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}