From 4fd1225dd6e42ed8d7553756e7f5877b534b1773 Mon Sep 17 00:00:00 2001 From: Matthias Seitz Date: Tue, 22 Nov 2022 19:04:19 +0100 Subject: [PATCH] chore(txpool): clarify ready terminology (#234) --- crates/transaction-pool/src/lib.rs | 4 ++-- crates/transaction-pool/src/pool/events.rs | 2 -- crates/transaction-pool/src/pool/listener.rs | 10 +++++----- crates/transaction-pool/src/pool/mod.rs | 18 ++++++++++-------- crates/transaction-pool/src/pool/txpool.rs | 5 ++++- 5 files changed, 21 insertions(+), 18 deletions(-) diff --git a/crates/transaction-pool/src/lib.rs b/crates/transaction-pool/src/lib.rs index a29554212f..01dc45dfb5 100644 --- a/crates/transaction-pool/src/lib.rs +++ b/crates/transaction-pool/src/lib.rs @@ -59,7 +59,7 @@ //! //! The `TransactionPool` trait exposes all externally used functionality of the pool, such as //! inserting, querying specific transactions by hash or retrieving the best transactions. -//! Additionally, it allows to register event listeners for new ready transactions or state changes. +//! In addition, it enables the registration of event listeners that are notified of state changes. //! Events are communicated via channels. //! //! ### Architecture @@ -217,7 +217,7 @@ where fn best_transactions( &self, ) -> Box>>> { - Box::new(self.pool.ready_transactions()) + Box::new(self.pool.best_transactions()) } fn remove_invalid( diff --git a/crates/transaction-pool/src/pool/events.rs b/crates/transaction-pool/src/pool/events.rs index f36b360784..7853c95b37 100644 --- a/crates/transaction-pool/src/pool/events.rs +++ b/crates/transaction-pool/src/pool/events.rs @@ -4,8 +4,6 @@ use serde::{Deserialize, Serialize}; /// Various events that describe status changes of a transaction. #[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)] pub enum TransactionEvent { - /// Transaction has been added to the ready queue. - Ready, /// Transaction has been added to the pending pool. Pending, /// Transaction has been added to the queued pool. diff --git a/crates/transaction-pool/src/pool/listener.rs b/crates/transaction-pool/src/pool/listener.rs index 220feeccc3..7c423da0e3 100644 --- a/crates/transaction-pool/src/pool/listener.rs +++ b/crates/transaction-pool/src/pool/listener.rs @@ -32,9 +32,9 @@ impl PoolEventListener { } } - /// Notify listeners about a transaction that was added to the ready queue. - pub(crate) fn ready(&mut self, tx: &TxHash, replaced: Option<&TxHash>) { - self.notify_with(tx, |notifier| notifier.ready()); + /// Notify listeners about a transaction that was added to the pending queue. + pub(crate) fn pending(&mut self, tx: &TxHash, replaced: Option<&TxHash>) { + self.notify_with(tx, |notifier| notifier.pending()); if let Some(replaced) = replaced { // notify listeners that this transaction was replaced @@ -77,8 +77,8 @@ impl PoolEventNotifier { self.senders.is_empty() || self.is_done } - /// Transaction became ready. - fn ready(&mut self) { + /// Transaction was moved to the pending queue. + fn pending(&mut self) { self.notify(TransactionEvent::Pending) } diff --git a/crates/transaction-pool/src/pool/mod.rs b/crates/transaction-pool/src/pool/mod.rs index 1393ca8465..6d1bb206b0 100644 --- a/crates/transaction-pool/src/pool/mod.rs +++ b/crates/transaction-pool/src/pool/mod.rs @@ -35,7 +35,9 @@ //! 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 +//! (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. @@ -57,8 +59,8 @@ //! //! ## Terminology //! -//! - _Pending_: pending transactions are transactions that fall under (2.). Those transactions are -//! _currently_ ready to be executed and are stored in the pending sub-pool +//! - _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. @@ -304,7 +306,7 @@ where let mut listener = self.event_listener.write(); mined.iter().for_each(|tx| listener.mined(tx, block_hash)); - promoted.iter().for_each(|tx| listener.ready(tx, None)); + promoted.iter().for_each(|tx| listener.pending(tx, None)); discarded.iter().for_each(|tx| listener.discarded(tx)); } @@ -316,8 +318,8 @@ where AddedTransaction::Pending(tx) => { let AddedPendingTransaction { transaction, promoted, discarded, .. } = tx; - listener.ready(transaction.hash(), None); - promoted.iter().for_each(|tx| listener.ready(tx, None)); + listener.pending(transaction.hash(), None); + promoted.iter().for_each(|tx| listener.pending(tx, None)); discarded.iter().for_each(|tx| listener.discarded(tx)); } AddedTransaction::Parked { transaction, .. } => { @@ -327,11 +329,11 @@ where } /// Returns an iterator that yields transactions that are ready to be included in the block. - pub(crate) fn ready_transactions(&self) -> BestTransactions { + pub(crate) fn best_transactions(&self) -> BestTransactions { self.pool.read().best_transactions() } - /// Removes all transactions transactions that are missing in the pool. + /// Removes all transactions that are missing in the pool. pub(crate) fn retain_unknown(&self, hashes: &mut Vec) { let pool = self.pool.read(); hashes.retain(|tx| !pool.contains(tx)) diff --git a/crates/transaction-pool/src/pool/txpool.rs b/crates/transaction-pool/src/pool/txpool.rs index 0cbc6ed121..b55de1f7a6 100644 --- a/crates/transaction-pool/src/pool/txpool.rs +++ b/crates/transaction-pool/src/pool/txpool.rs @@ -188,7 +188,10 @@ impl TxPool { /// /// The `Pending` pool contains all transactions that have no nonce gaps, and can be afforded by /// the sender. It only contains transactions that are ready to be included in the pending - /// block. + /// block. In the pending pool are all transactions that could be listed currently, but not + /// necessarily independently. However, this pool never contains transactions with nonce gaps. A + /// transaction is considered `ready` when it has the lowest nonce of all transactions from the + /// same sender. Which is equals to the chain nonce of the sender in the pending pool. /// /// The `BaseFee` pool contains transaction that currently can't satisfy the dynamic fee /// requirement. With EIP-1559, transactions can become executable or not without any changes to