chore(txpool): clarify ready terminology (#234)

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<dyn BestTransactions<Item = Arc<ValidPoolTransaction<Self::Transaction>>>> {
-        Box::new(self.pool.ready_transactions())
+        Box::new(self.pool.best_transactions())
     }
 
     fn remove_invalid(

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.

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)
     }
 

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<T> {
+    pub(crate) fn best_transactions(&self) -> BestTransactions<T> {
         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<TxHash>) {
         let pool = self.pool.read();
         hashes.retain(|tx| !pool.contains(tx))

crates/transaction-pool/src/pool/txpool.rs

@@ -188,7 +188,10 @@ impl<T: TransactionOrdering> TxPool<T> {
     ///
     /// 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