Crate reth_transaction_pool

Help

Source

Expand description

Reth’s transaction pool implementation.

This crate provides a generic transaction pool implementation.

§Functionality

The transaction pool is responsible for

recording incoming transactions
providing existing transactions
ordering and providing the best transactions for block production
monitoring memory footprint and enforce pool size limits
storing blob data for transactions in a separate blobstore on insertion

§Assumptions

§Transaction type

The pool expects certain ethereum related information from the generic transaction type of the pool (PoolTransaction), this includes gas price, base fee (EIP-1559 transactions), nonce etc. It makes no assumptions about the encoding format, but the transaction type must report its size so pool size limits (memory) can be enforced.

§Transaction ordering

The pending pool contains transactions that can be mined on the current state. The order in which they’re returned are determined by a Priority value returned by the TransactionOrdering type this pool is configured with.

This is only used in the pending pool to yield the best transactions for block production. The base pool is ordered by base fee, and the queued pool by current distance.

§Validation

The pool itself does not validate incoming transactions, instead this should be provided by implementing TransactionsValidator. Only transactions that the validator returns as valid are included in the pool. It is assumed that transaction that are in the pool are either valid on the current state or could become valid after certain state changes. Transactions that can never become valid (e.g. nonce lower than current on chain nonce) will never be added to the pool and instead are discarded right away.

§State Changes

Once a new block is mined, the pool needs to be updated with a changeset in order to:

remove mined transactions
update using account changes: balance changes
base fee updates

§Implementation details

The TransactionPool trait exposes all externally used functionality of the pool, such as inserting, querying specific transactions by hash or retrieving the best transactions. In addition, it enables the registration of event listeners that are notified of state changes. Events are communicated via channels.

§Architecture

The final TransactionPool is made up of two layers:

The lowest layer is the actual pool implementations that manages (validated) transactions: TxPool. This is contained in a higher level pool type that guards the low level pool and handles additional listeners or metrics: PoolInner.

The transaction pool will be used by separate consumers (RPC, P2P), to make sharing easier, the Pool type is just an Arc wrapper around PoolInner. This is the usable type that provides the TransactionPool interface.

§Blob Transactions

Blob transaction can be quite large hence they are stored in a separate blobstore. The pool is responsible for inserting blob data for new transactions into the blobstore. See also ValidTransaction

§Examples

Listen for new transactions and print them:

use reth_chainspec::MAINNET;
use reth_storage_api::StateProviderFactory;
use reth_tasks::TokioTaskExecutor;
use reth_chainspec::ChainSpecProvider;
use reth_transaction_pool::{TransactionValidationTaskExecutor, Pool, TransactionPool};
use reth_transaction_pool::blobstore::InMemoryBlobStore;
use reth_chainspec::EthereumHardforks;
async fn t<C>(client: C)  where C: ChainSpecProvider<ChainSpec: EthereumHardforks> + StateProviderFactory + Clone + 'static{
    let blob_store = InMemoryBlobStore::default();
    let pool = Pool::eth_pool(
        TransactionValidationTaskExecutor::eth(client, blob_store.clone(), TokioTaskExecutor::default()),
        blob_store,
        Default::default(),
    );
  let mut transactions = pool.pending_transactions_listener();
  tokio::task::spawn( async move {
     while let Some(tx) = transactions.recv().await {
         println!("New transaction: {:?}", tx);
     }
  });

  // do something useful with the pool, like RPC integration

Spawn maintenance task to keep the pool updated

use futures_util::Stream;
use reth_chain_state::CanonStateNotification;
use reth_chainspec::{MAINNET, ChainSpecProvider, ChainSpec};
use reth_storage_api::{BlockReaderIdExt, StateProviderFactory};
use reth_tasks::TokioTaskExecutor;
use reth_tasks::TaskSpawner;
use reth_tasks::TaskManager;
use reth_transaction_pool::{TransactionValidationTaskExecutor, Pool};
use reth_transaction_pool::blobstore::InMemoryBlobStore;
use reth_transaction_pool::maintain::{maintain_transaction_pool_future};

 async fn t<C, St>(client: C, stream: St)
   where C: StateProviderFactory + BlockReaderIdExt + ChainSpecProvider<ChainSpec = ChainSpec> + Clone + 'static,
    St: Stream<Item = CanonStateNotification> + Send + Unpin + 'static,
    {
    let blob_store = InMemoryBlobStore::default();
    let rt = tokio::runtime::Runtime::new().unwrap();
    let manager = TaskManager::new(rt.handle().clone());
    let executor = manager.executor();
    let pool = Pool::eth_pool(
        TransactionValidationTaskExecutor::eth(client.clone(), blob_store.clone(), executor.clone()),
        blob_store,
        Default::default(),
    );

  // spawn a task that listens for new blocks and updates the pool's transactions, mined transactions etc..
  tokio::task::spawn(maintain_transaction_pool_future(client, pool, stream, executor.clone(), Default::default()));

§Feature Flags

serde (default): Enable serde support
test-utils: Export utilities for testing

Re-exports§

pub use crate::blobstore::BlobStore;
pub use crate::blobstore::BlobStoreError;
pub use crate::error::PoolResult;
pub use crate::pool::blob_tx_priority;
pub use crate::pool::fee_delta;
pub use crate::pool::AllTransactionsEvents;
pub use crate::pool::FullTransactionEvent;
pub use crate::pool::NewTransactionEvent;
pub use crate::pool::TransactionEvent;
pub use crate::pool::TransactionEvents;
pub use crate::pool::TransactionListenerKind;
pub use crate::validate::EthTransactionValidator;
pub use crate::validate::TransactionValidationOutcome;
pub use crate::validate::TransactionValidationTaskExecutor;
pub use crate::validate::TransactionValidator;
pub use crate::validate::ValidPoolTransaction;

Modules§

blobstore: Storage for blob data of EIP4844 transactions.
error: Transaction pool errors
identifier: Identifier types for transactions and senders.
maintain: Support for maintaining the state of the transaction pool
metrics: Transaction pool metrics.
noop: A transaction pool implementation that does nothing.
pool: Transaction Pool internals.
test_utilstest-utils: Common test helpers for mocking a pool Internal helpers for testing.
validate: Transaction validation abstractions.

Structs§

AllPoolTransactions: A Helper type that bundles all transactions in the pool.
BestTransactionsAttributes: A Helper type that bundles the best transactions attributes together.
BlockInfo: Represents the current status of the pool.
CanonicalStateUpdate: Represents changes after a new canonical block or range of canonical blocks was added to the chain.
CoinbaseTipOrdering: Default ordering for the pool.
EthPooledTransaction: The default PoolTransaction for the Pool for Ethereum.
LocalTransactionConfig: Configuration options for the locally received transactions: TransactionOrigin::Local
NewBlobSidecar: This type represents a new blob sidecar that has been stored in the transaction pool’s blobstore; it includes the TransactionHash of the blob transaction along with the assoc. sidecar (blobs, commitments, proofs)
NewSubpoolTransactionStream: A Stream that yields full transactions the subpool
NoopTransactionFilter: A no-op implementation of TransactionFilter which marks all transactions as valid.
Pool: A shareable, generic, customizable TransactionPool implementation.
PoolConfig: Configuration options for the Transaction pool.
PoolSize: Represents the current status of the pool.
PriceBumpConfig: Price bump config (in %) for the transaction pool underpriced check.
PropagatedTransactions: Represents transactions that were propagated over the network.
SubPoolLimit: Size limits for a sub-pool.

Enums§

EthBlobTransactionSidecar: Represents the blob sidecar of the EthPooledTransaction.
GetPooledTransactionLimit: The limit to enforce for TransactionPool::get_pooled_transaction_elements.
PoolUpdateKind: Represents the kind of update to the canonical state.
Priority: Priority of the transaction that can be missing.
PropagateKind: Represents how a transaction was propagated over the network.
SubPool: Identifier for the transaction Sub-pool
TransactionOrigin: Where the transaction originates from.

Constants§

DEFAULT_PRICE_BUMP: Default price bump (in %) for the transaction pool underpriced check.
DEFAULT_TXPOOL_ADDITIONAL_VALIDATION_TASKS: The default additional validation tasks size.
MAX_NEW_PENDING_TXS_NOTIFICATIONS: Default maximum new transactions for broadcasting.
REPLACE_BLOB_PRICE_BUMP: Replace blob price bump (in %) for the transaction pool underpriced check.
TXPOOL_MAX_ACCOUNT_SLOTS_PER_SENDER: Guarantees max transactions for one sender, compatible with geth/erigon
TXPOOL_SUBPOOL_MAX_SIZE_MB_DEFAULT: The default maximum allowed size of the given subpool.
TXPOOL_SUBPOOL_MAX_TXS_DEFAULT: The default maximum allowed number of transactions in the given subpool.

Traits§

BestTransactions: An Iterator that only returns transactions that are ready to be executed.
EthPoolTransaction: Super trait for transactions that can be converted to and from Eth transactions intended for the ethereum style pool.
PoolTransaction: Trait for transaction types used inside the pool.
TransactionFilter: A filter that allows to check if a transaction satisfies a set of conditions
TransactionOrdering: Transaction ordering trait to determine the order of transactions.
TransactionPool: General purpose abstraction of a transaction-pool.
TransactionPoolExt: Extension for TransactionPool trait that allows to set the current block info.

Type Aliases§

BestTransactionsFor: Alias to restrict the BestTransactions items to the pool’s transaction type.
EthTransactionPool: Type alias for default ethereum transaction pool
PeerId: The PeerId type.
PoolConsensusTx: Helper type alias to access PoolTransaction::Consensus for a given TransactionPool.
PoolPooledTx: Helper type alias to access PoolTransaction::Pooled for a given TransactionPool.
PoolTx: Helper type alias to access PoolTransaction for a given TransactionPool.

Crate reth_transaction_poolCopy item path