Module pool

Transaction Pool internals.

Incoming transactions are validated before they enter the pool first. The validation outcome can have 3 states:

1. Transaction can never be valid
2. Transaction is currently valid
3. Transaction is currently invalid, but could potentially become valid in the future

However, (2.) and (3.) of a transaction can only be determined on the basis of the current state, whereas (1.) holds indefinitely. This means once the state changes (2.) and (3.) the state of a transaction needs to be reevaluated again.

The transaction pool is responsible for storing new, valid transactions and providing the next best transactions sorted by their priority. Where priority is determined by the transaction’s score (TransactionOrdering).

Furthermore, the following characteristics fall under (3.):

a) Nonce of a transaction is higher than the expected nonce for the next transaction of its sender. A distinction is made here whether multiple transactions from the same sender have gapless nonce increments.

a)(1) If no transaction is missing in a chain of multiple transactions from the same sender (all nonce in row), all of them can in principle be executed on the current state one after the other.

a)(2) If there’s a nonce gap, then all transactions after the missing transaction are blocked until the missing transaction arrives.

b) Transaction does not meet the dynamic fee cap requirement introduced by EIP-1559: The fee cap of the transaction needs to be no less than the base fee of block.

In essence the transaction pool is made of three separate sub-pools:

• Pending Pool: Contains all transactions that are valid on the current state and satisfy (3. a)(1): No nonce gaps. A pending transaction is considered ready when it has the lowest nonce of all transactions from the same sender. Once a ready transaction with nonce n has been executed, the next highest transaction from the same sender n + 1 becomes ready.

• Queued Pool: Contains all transactions that are currently blocked by missing transactions: (3. a)(2): With nonce gaps or due to lack of funds.

• Basefee Pool: To account for the dynamic base fee requirement (3. b) which could render an EIP-1559 and all subsequent transactions of the sender currently invalid.

The classification of transactions is always dependent on the current state that is changed as soon as a new block is mined. Once a new block is mined, the account changeset must be applied to the transaction pool.

Depending on the use case, consumers of the TransactionPool are interested in (2.) and/or (3.). A generic TransactionPool that only handles transactions.

This Pool maintains two separate sub-pools for (2.) and (3.)

Terminology

• Pending: pending transactions are transactions that fall under (2.). These transactions can currently be executed and are stored in the pending sub-pool
• Queued: queued transactions are transactions that fall under category (3.). Those transactions are currently waiting for state changes that eventually move them into category (2.) and become pending.

Modules

• txpool
  The internal transaction pool implementation.

Structs

• AddedPendingTransaction
  Tracks an added transaction and all graph changes caused by adding it.
• AllTransactionsEvents
  A Stream that receives FullTransactionEvent for all transaction.
• BasefeeOrd
  A new type wrapper for ValidPoolTransaction
• BestPayloadTransactions
  Wrapper struct that allows to convert BestTransactions (used in tx pool) to PayloadTransactions (used in block composition).
• BestTransactionFilter
  A BestTransactions implementation that filters the transactions of iter with predicate.
• BestTransactionsWithPrioritizedSenders
  Wrapper over crate::traits::BestTransactions that prioritizes transactions of certain senders capping total gas used by such transactions.
• ParkedPool
  A pool of transactions that are currently parked and are waiting for external changes (e.g. basefee, ancestor transactions, balance) that eventually move the transaction into the pending pool.
• PayloadTransactionsChain
  Wrapper over crate::traits::PayloadTransactions that combines transactions from multiple PayloadTransactions iterators and keeps track of the gas for both of iterators.
• PayloadTransactionsFixed
  An implementation of crate::traits::PayloadTransactions that yields a pre-defined set of transactions.
• PendingPool
  A pool of validated and gapless transactions that are ready to be executed on the current state and are waiting to be included in a block.
• PoolInner
  Transaction pool internals.
• QueuedOrd
  A new type wrapper for ValidPoolTransaction
• TransactionEvents
  A Stream that receives TransactionEvent only for the transaction with the given hash.

Enums

• AddedTransaction
  Represents a transaction that was added into the pool and its state
• FullTransactionEvent
  An event that happened to a transaction and contains its full body where possible.
• TransactionEvent
  Various events that describe status changes of a transaction.

Constants

• NEW_TX_LISTENER_BUFFER_SIZE
  Bound on number of new transactions from reth_network::TransactionsManager to buffer.
• PENDING_TX_LISTENER_BUFFER_SIZE
  Bound on number of pending transactions from reth_network::TransactionsManager to buffer.

Traits

• ParkedOrd
  Helper trait used for custom Ord wrappers around a transaction.

Functions

• blob_tx_priority
  Returns the priority for the transaction, based on the “delta” blob fee and priority fee.
• fee_delta
  The blob step function, attempting to compute the delta given the max_tx_fee, and current_fee.