Document sequenced transaction pool behavior (#1600)

* Document sequenced transaction pool behavior Signed-off-by: Joan E <[email protected]> * Add sequenced text Signed-off-by: Joan E <[email protected]> * update language Signed-off-by: Joan E <[email protected]> * Update wording Signed-off-by: Joan E <[email protected]> * Updatedescription Signed-off-by: Joan E <[email protected]> * slight reword Signed-off-by: Joan E <[email protected]> * edit Signed-off-by: Joan E <[email protected]> * Update pool.md Signed-off-by: Joan E <[email protected]> * Update table Signed-off-by: Joan E <[email protected]> * add default for enterprise profile Signed-off-by: Joan E <[email protected]> * Update language Signed-off-by: Joan E <[email protected]> * Move table Signed-off-by: Joan E <[email protected]> * add clearer language Signed-off-by: Joan E <[email protected]> * add links Signed-off-by: Joan E <[email protected]> * Update docs/public-networks/concepts/transactions/pool.md Co-authored-by: Alexandra Tran Carrillo <[email protected]> Signed-off-by: Joan E <[email protected]> * add additional api methods Signed-off-by: Joan E <[email protected]> * add missing link Signed-off-by: Joan E <[email protected]> * Update docs/public-networks/concepts/transactions/pool.md Co-authored-by: Alexandra Tran Carrillo <[email protected]> Signed-off-by: Joan E <[email protected]> * Update docs/public-networks/concepts/transactions/pool.md Co-authored-by: Alexandra Tran Carrillo <[email protected]> Signed-off-by: Joan E <[email protected]> * Update docs/public-networks/concepts/transactions/pool.md Signed-off-by: Alexandra Tran Carrillo <[email protected]> * reformat table Signed-off-by: Joan E <[email protected]> * remove space Signed-off-by: Joan E <[email protected]> * Update link Signed-off-by: Joan E <[email protected]> --------- Signed-off-by: Joan E <[email protected]> Signed-off-by: Alexandra Tran Carrillo <[email protected]> Co-authored-by: Alexandra Tran Carrillo <[email protected]>
hyperledger · Jun 12, 2024 · 858a159 · 858a159
1 parent fd76777
commit 858a159
Show file tree

Hide file tree

Showing 2 changed files with 63 additions and 25 deletions.
diff --git a/docs/public-networks/concepts/transactions/pool.md b/docs/public-networks/concepts/transactions/pool.md
@@ -11,22 +11,13 @@ tags:
 
 All nodes maintain a transaction pool to store pending transactions before processing.
 
-Options and methods for configuring and monitoring the transaction pool include:
-
-- [`txpool_besuTransactions`](../../reference/api/index.md#txpool_besutransactions) API method to
-  list transactions in the transaction pool.
-- [`--tx-pool`](../../reference/cli/options.md#tx-pool) option to specify the type of transaction
-  pool to use.
-- [`--tx-pool-layer-max-capacity`](../../reference/cli/options.md#tx-pool-layer-max-capacity) option
-  to specify the maximum memory capacity of the transaction pool.
-- [`--tx-pool-price-bump`](../../reference/cli/options.md#tx-pool-price-bump) option to specify the
-  price bump percentage to replace an existing transaction.
-- [`--tx-pool-priority-senders`](../../reference/cli/options.md#tx-pool-priority-senders)
-  option to specify sender addresses to prioritize in the transaction pool.
-- [`newPendingTransactions`](../../how-to/use-besu-api/rpc-pubsub.md#pending-transactions) and
-  [`droppedPendingTransactions`](../../how-to/use-besu-api/rpc-pubsub.md#dropped-transactions) RPC
-  subscriptions to notify you of transactions added to and dropped from the transaction pool.
+Transaction pools are categorized into the following two types: 
 
+* [Layered](#layered-transaction-pool) - Recommended for public blockchain networks.
+* [Sequenced](#sequenced-transaction-pool) - Recommended for private blockchain networks.
+
+You can use specific options and methods to [configure and monitor the transaction pool](#transaction-pool-methods-and-options).
+
 :::note
 When submitting [private transactions](../../../private-networks/concepts/privacy/private-transactions/index.md#nonce-validation),
 the [privacy marker transaction](../../../private-networks/concepts/privacy/private-transactions/processing.md)
@@ -37,11 +28,11 @@ is submitted to the transaction pool, not the private transaction itself.
 
 The [layered transaction pool](https://github.com/hyperledger/besu/pull/5290) is the default
 transaction pool implementation.
-This implementation separates the pool into layers according to value and executability of the transactions.
-That is, the first layer keeps only transactions with the highest value and that could feasibly go
-into the next produced block.
-The two other layers ensure that Besu always has a backlog of transactions to fill blocks, gaining
-the maximum amount of fees.
+The implementation separates the pool into layers according to value and executability of the transactions.
+The first layer keeps only the highest-value transactions that can feasibly go into the next block. 
+The other two layers ensure Besu always has a backlog of transactions to fill blocks, maximizing the amount of fees.
+
+Layered pools have additional parameters that allow you to limit and configure the number of transactions in different layers, enabling them to handle high volumes and sort transactions at a faster speed.
 
 With the layered transaction pool, Besu produces more profitable blocks more quickly, with more
 denial-of-service protection, and using less CPU than with the legacy transaction pool.
@@ -62,9 +53,24 @@ If you previously configured transaction pool behavior, upgrade to the layered t
 You can opt out of the layered transaction pool implementation by setting the
 [`--tx-pool`](../../reference/cli/options.md#tx-pool) option to `sequenced`.
 
-## Dropping transactions when the transaction pool is full
+## Sequenced transaction pool
+
+In the sequenced transaction pool, transactions are processed strictly in the order they are received.
+Although sequenced transaction pools lack the flexibility of layered pools, they help maintain a 
+consistent and transparent transaction order, which is often useful in private blockchains. 
+
+You can select the sequenced transaction pool by setting [`--tx-pool=sequenced`](../../reference/cli/options.md#tx-pool).
+
+If you set the enterprise configuration profile using [`--profile=enterprise`](../../how-to/use-configuration-file/profile.md#enterpriseprivate-profile) or [`--profile=private`](../../how-to/use-configuration-file/profile.md#enterpriseprivate-profile), the `sequenced` transaction pool is set by default.
 
-When the transaction pool is full, it accepts and retains local transactions in preference to remote transactions. If the transaction pool is full of local transactions, Besu drops the oldest local transactions first. That is, a full transaction pool continues to accept new local transactions by first dropping remote transactions and then by dropping the oldest local transactions.
+The sequenced transaction pool suits enterprise environments because it functions like a first-in-first-out (FIFO) queue and processes transactions in the order of submission, regardless of the sender. 
+When the pool reaches capacity, the newer transactions are evicted first, reducing the likelihood of a nonce gap and avoiding the need to resubmit older transactions.
+
+## Dropping transactions when the layered transaction pool is full
+
+When the transaction pool is full, it accepts and retains local transactions in preference to remote transactions. 
+If the transaction pool is full of local transactions, Besu drops the oldest local transactions first. 
+That is, a full transaction pool continues to accept new local transactions by first dropping remote transactions and then by dropping the oldest local transactions.
 
 ## Replacing transactions with the same sender and nonce
 
@@ -90,4 +96,34 @@ or free gas networks:
 * If you set [`zeroBaseFee`](../../reference/genesis-items.md) to `true` in the genesis file,
   the transaction pool price bump is set to `0`. Specifying a value for transaction pool price bump using [`--tx-pool-price-bump`](../../reference/cli/options.md#tx-pool-price-bump)
   will cause an error.
-* If the [minimum gas price is zero](../../../private-networks/how-to/configure/free-gas.md), the transaction pool price bump is set to `0`, unless you specify a different value using [`--tx-pool-price-bump`](../../reference/cli/options.md#tx-pool-price-bump). 
+* If the [minimum gas price is zero](../../../private-networks/how-to/configure/free-gas.md), the transaction pool price bump is set to `0`, unless you specify a different value using [`--tx-pool-price-bump`](../../reference/cli/options.md#tx-pool-price-bump).
+
+## Transaction pool methods and options
+
+You can configure and monitor the transaction pool using the following methods, subscriptions, and options:
+
+|                | Name                                                                                             | Description                                                                         |
+|----------------|--------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
+| Method         | [`txpool_besuTransactions`](../../reference/api/index.md#txpool_besutransactions)                | API method to list transactions in the transaction pool.                            |
+| Method         | [`txpool_besuStatistics`](../../reference/api/index.md#txpool_besustatistics)                    | API method to list statistics of the transaction pool.                              |
+| Method         | [`txpool_besuPendingTransactions`](../../reference/api/index.md#txpool_besupendingtransactions)  | API method to list pending transactions in the transaction pool.                    |
+| Subscription   | [`newPendingTransactions`](../../how-to/use-besu-api/rpc-pubsub.md#pending-transactions)         | RPC subscription to notify of transactions added to the transaction pool.           |
+| Subscription   | [`droppedPendingTransactions`](../../how-to/use-besu-api/rpc-pubsub.md#dropped-transactions)     | RPC subscription to notify of transactions dropped from the transaction pool.       |
+| Option         | [`--tx-pool`](../../reference/cli/options.md#tx-pool)                                            | Option to specify the type of transaction pool to use.                              |
+| Option         | [`--tx-pool-enable-save-restore`](../../reference/cli/options.md#tx-pool-enable-save-restore)    | Option to enable save and restore functionality for the transaction pool.           |
+| Option         | [`--tx-pool-layer-max-capacity`](../../reference/cli/options.md#tx-pool-layer-max-capacity)      | Option to specify the maximum memory capacity of the layered transaction pool.      |
+| Option         | [`--tx-pool-limit-by-account-percentage`](../../reference/cli/options.md#tx-pool-limit-by-account-percentage) | Option to limit the transaction pool by account percentage.            |
+| Option         | [`--tx-pool-max-future-by-sender`](../../reference/cli/options.md#tx-pool-max-future-by-sender)  | Option to specify the maximum number of future transactions by sender.              |
+| Option         | [`--tx-pool-max-prioritized`](../../reference/cli/options.md#tx-pool-max-prioritized)            | Option to specify the maximum number of prioritized transactions.                   |
+| Option         | [`--tx-pool-max-prioritized-by-type`](../../reference/cli/options.md#tx-pool-max-prioritized-by-type) | Option to specify the maximum number of prioritized transactions by type.      |
+| Option         | [`--tx-pool-max-size`](../../reference/cli/options.md#tx-pool-max-size)                          | Option to specify the maximum size of the transaction pool.                         |
+| Option         | [`--tx-pool-min-gas-price`](../../reference/cli/options.md#tx-pool-min-gas-price)                | Option to specify the minimum gas price for transactions in the pool.               |
+| Option         | [`--tx-pool-no-local-priority`](../../reference/cli/options.md#tx-pool-no-local-priority)        | Option to disable local priority for transactions.                                  |
+| Option         | [`--tx-pool-price-bump`](../../reference/cli/options.md#tx-pool-price-bump)                      | Option to specify the price bump percentage to replace an existing transaction.     |
+| Option         | [`--tx-pool-priority-senders`](../../reference/cli/options.md#tx-pool-priority-senders)          | Option to specify sender addresses to prioritize in the transaction pool.           |
+| Option         | [`--tx-pool-retention-hours`](../../reference/cli/options.md#tx-pool-retention-hours)            | Option to specify the number of hours to retain transactions in the pool.           |
+| Option         | [`--tx-pool-save-file`](../../reference/cli/options.md#tx-pool-save-file)                        | Option to specify the file for saving the transaction pool state.                   |
+
+:::note
+The option [`--tx-pool-layer-max-capacity`](../../reference/cli/options.md#tx-pool-layer-max-capacity) is applicable only for [layered transaction pools](#layered-transaction-pool).
+:::
diff --git a/docs/public-networks/reference/cli/options.md b/docs/public-networks/reference/cli/options.md
@@ -4993,10 +4993,12 @@ tx-pool="sequenced"
 </Tabs>
 
 Type of [transaction pool](../../concepts/transactions/pool.md) to use.
-Set to `layered` to use the layered transaction pool implementation.
-Set to `sequenced` (previously known as `legacy`) to opt out of the layered transaction pool.
+Set to `layered` to use the [layered transaction pool](../../concepts/transactions/pool#layered-transaction-pool) implementation.
 The default is `layered`.
 
+Set to `sequenced` to use the [sequenced transaction pool](../../concepts/transactions/pool#sequenced-transaction-pool).
+The default is `sequenced` for the [enterprise/private profile](../../how-to/use-configuration-file/profile#enterpriseprivate-profile).
+
 ### `tx-pool-enable-save-restore`
 
 <Tabs>