Trait PoolTransaction

pub trait PoolTransaction:
    Transaction
    + InMemorySize
    + Debug
    + Send
    + Sync
    + Clone {
    type TryFromConsensusError: Display;
    type Consensus: SignedTransaction + From<Self::Pooled>;
    type Pooled: TryFrom<Self::Consensus, Error = Self::TryFromConsensusError> + SignedTransaction;

    // Required methods
    fn into_consensus(self) -> Recovered<Self::Consensus>;
    fn from_pooled(pooled: Recovered<Self::Pooled>) -> Self;
    fn hash(&self) -> &FixedBytes<32>;
    fn sender(&self) -> Address;
    fn sender_ref(&self) -> &Address;
    fn cost(&self) -> &Uint<256, 4>;
    fn encoded_length(&self) -> usize;

    // Provided methods
    fn try_from_consensus(
        tx: Recovered<Self::Consensus>,
    ) -> Result<Self, Self::TryFromConsensusError> { ... }
    fn clone_into_consensus(&self) -> Recovered<Self::Consensus> { ... }
    fn into_consensus_with2718(self) -> WithEncoded<Recovered<Self::Consensus>> { ... }
    fn try_into_pooled(
        self,
    ) -> Result<Recovered<Self::Pooled>, Self::TryFromConsensusError> { ... }
    fn pooled_into_consensus(tx: Self::Pooled) -> Self::Consensus { ... }
    fn ensure_max_init_code_size(
        &self,
        max_init_code_size: usize,
    ) -> Result<(), InvalidPoolTransactionError> { ... }
}

Trait for transaction types stored in the transaction pool.

This trait represents the actual transaction object stored in the mempool, which includes not only the transaction data itself but also additional metadata needed for efficient pool operations. Implementations typically cache values that are frequently accessed during transaction ordering, validation, and eviction.

Key Responsibilities

1. Metadata Caching: Store computed values like address, cost and encoded size
2. Representation Conversion: Handle conversions between consensus and pooled representations
3. Validation Support: Provide methods for pool-specific validation rules

Cached Metadata

Implementations should cache frequently accessed values to avoid recomputation:

• Address: Recovered sender address of the transaction
• Cost: Max amount spendable (gas × price + value + blob costs)
• Size: RLP encoded length for mempool size limits

See EthPooledTransaction for a reference implementation.

Transaction Representations

This trait abstracts over the different representations a transaction can have:

1. Consensus representation (Consensus associated type): The canonical form included in blocks

   • Compact representation without networking metadata
   • For EIP-4844: includes only blob hashes, not the actual blobs
   • Used for block execution and state transitions

2. Pooled representation (Pooled associated type): The form used for network propagation

   • May include additional data for validation
   • For EIP-4844: includes full blob sidecars (blobs, commitments, proofs)
   • Used for mempool validation and p2p gossiping

Why Two Representations?

This distinction is necessary because:

• EIP-4844 blob transactions: Require large blob sidecars for validation that would bloat blocks if included. Only blob hashes are stored on-chain.

• Network efficiency: Blob transactions are not broadcast to all peers automatically but must be explicitly requested to reduce bandwidth usage.

• Special transactions: Some transactions (like OP deposit transactions) exist only in consensus format and are never in the mempool.

Conversion Rules

• Consensus → Pooled: May fail for transactions that cannot be pooled (e.g., OP deposit transactions, blob transactions without sidecars)
• Pooled → Consensus: Always succeeds (pooled is a superset)

Required Associated Types

type TryFromConsensusError: Display

Associated error type for the try_from_consensus method.

type Consensus: SignedTransaction + From<Self::Pooled>

Associated type representing the raw consensus variant of the transaction.

type Pooled: TryFrom<Self::Consensus, Error = Self::TryFromConsensusError> + SignedTransaction

Associated type representing the recovered pooled variant of the transaction.

Required Methods

fn into_consensus(self) -> Recovered<Self::Consensus>

Define a method to convert from the Self type to Consensus

fn from_pooled(pooled: Recovered<Self::Pooled>) -> Self

Define a method to convert from the Pooled type to Self

fn hash(&self) -> &FixedBytes<32>

Hash of the transaction.

fn sender(&self) -> Address

The Sender of the transaction.

fn sender_ref(&self) -> &Address

Reference to the Sender of the transaction.

fn cost(&self) -> &Uint<256, 4>

Returns the cost that this transaction is allowed to consume:

For EIP-1559 transactions: max_fee_per_gas * gas_limit + tx_value. For legacy transactions: gas_price * gas_limit + tx_value. For EIP-4844 blob transactions: max_fee_per_gas * gas_limit + tx_value + max_blob_fee_per_gas * blob_gas_used.

fn encoded_length(&self) -> usize

Returns the length of the rlp encoded transaction object

Note: Implementations should cache this value.

Provided Methods

fn try_from_consensus( tx: Recovered<Self::Consensus>, ) -> Result<Self, Self::TryFromConsensusError>

Define a method to convert from the Consensus type to Self

This conversion may fail for transactions that are valid for inclusion in blocks but cannot exist in the transaction pool. Examples include:

• OP Deposit transactions: These are special system transactions that are directly included in blocks by the sequencer/validator and never enter the mempool
• Blob transactions without sidecars: After being included in a block, the sidecar data is pruned, making the consensus transaction unpoolable

fn clone_into_consensus(&self) -> Recovered<Self::Consensus>

Clone the transaction into a consensus variant.

This method is preferred when the PoolTransaction already wraps the consensus variant.

fn into_consensus_with2718(self) -> WithEncoded<Recovered<Self::Consensus>>

Converts the transaction into consensus format while preserving the EIP-2718 encoded bytes. This is used to optimize transaction execution by reusing cached encoded bytes instead of re-encoding the transaction. The cached bytes are particularly useful in payload building where the same transaction may be executed multiple times.

fn try_into_pooled( self, ) -> Result<Recovered<Self::Pooled>, Self::TryFromConsensusError>

Tries to convert the Consensus type into the Pooled type.

fn pooled_into_consensus(tx: Self::Pooled) -> Self::Consensus

Converts the Pooled type into the Consensus type.

fn ensure_max_init_code_size( &self, max_init_code_size: usize, ) -> Result<(), InvalidPoolTransactionError>

Ensures that the transaction’s code size does not exceed the provided max_init_code_size.

This is specifically relevant for contract creation transactions (TxKind::Create), where the input data contains the initialization code. If the input code size exceeds the configured limit, an InvalidPoolTransactionError::ExceedsMaxInitCodeSize error is returned.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl PoolTransaction for MockTransaction

type TryFromConsensusError = ValueError<EthereumTxEnvelope<TxEip4844>>

type Consensus = EthereumTxEnvelope<TxEip4844>

type Pooled = EthereumTxEnvelope<TxEip4844WithSidecar<BlobTransactionSidecarVariant>>

impl PoolTransaction for EthPooledTransaction

type TryFromConsensusError = ValueError<EthereumTxEnvelope<TxEip4844>>

type Consensus = EthereumTxEnvelope<TxEip4844>

type Pooled = EthereumTxEnvelope<TxEip4844WithSidecar<BlobTransactionSidecarVariant>>