Remove pending transactions from the layered transactions pool (hyper…

…ledger#1718) * Add tx pool CLI option. Signed-off-by: bgravenorst <[email protected]> * Add extra clarification. Signed-off-by: bgravenorst <[email protected]> * Address reviewer feedback. Signed-off-by: bgravenorst <[email protected]> * Typo. Signed-off-by: bgravenorst <[email protected]> * Fix additional typos. Signed-off-by: bgravenorst <[email protected]> * Minor edits. Signed-off-by: bgravenorst <[email protected]> * Update syncing docs (hyperledger#1717) * Update syncing docs Signed-off-by: Alexandra Tran <[email protected]> * Update options.md Co-authored-by: Joan E <[email protected]> Signed-off-by: Alexandra Carrillo <[email protected]> * address reviewer feedback + edits Signed-off-by: Alexandra Tran <[email protected]> --------- Signed-off-by: Alexandra Tran <[email protected]> Signed-off-by: Alexandra Carrillo <[email protected]> Co-authored-by: Alexandra Tran <[email protected]> Co-authored-by: Joan E <[email protected]> * Update to match other Besu headings Signed-off-by: bgravenorst <[email protected]> --------- Signed-off-by: bgravenorst <[email protected]> Signed-off-by: Alexandra Tran <[email protected]> Signed-off-by: Alexandra Carrillo <[email protected]> Co-authored-by: Joan E <[email protected]> Co-authored-by: Alexandra Carrillo <[email protected]> Co-authored-by: Alexandra Tran <[email protected]>
ahamlat · Oct 22, 2024 · df17fe9 · df17fe9
1 parent 181133b
commit df17fe9
Show file tree

Hide file tree

Showing 2 changed files with 73 additions and 3 deletions.
diff --git a/docs/public-networks/concepts/transactions/pool.md b/docs/public-networks/concepts/transactions/pool.md
@@ -32,7 +32,8 @@ The implementation separates the pool into layers according to value and executa
 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.
+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.
@@ -53,6 +54,28 @@ 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`.
 
+### Penalize transient invalid pending transactions
+
+Transient invalid pending transactions cannot be included in the current block but might be included in a future one. 
+This can happen due to issues like insufficient balance in the sender's wallet or a gas price below the minimum. 
+These conditions could resolve in the future.
+
+:::note
+Invalid pending transactions where conditions can't be resolved in the future (for example, invalid nonce)
+are immediately dropped from the transaction pool.
+:::
+
+The layered transaction pool uses a scoring system to avoid repeatedly evaluating transient invalid pending
+transactions, which can block the evaluation of valid ones. Each pending transaction starts with a score of
+`127` and is penalized over time, with the score decreasing to a minimum of -128. 
+This score determines the transaction's rank in the pool, pushing invalid transactions lower so they are 
+evaluated only after non-penalized or less penalized ones.
+
+The [`--tx-pool-min-score`](../../reference/cli/options.md#tx-pool-min-score) option, which accepts a value
+between `-128` and `127`, instructs the transaction pool to remove pending transactions when their score falls
+below the specified value. By default, the value is `-128`, meaning the pending transaction will remain in the
+pool with the lowest score and will only be selected after all other pending transactions have been processed.
+
 ## Sequenced transaction pool
 
 In the sequenced transaction pool, transactions are processed strictly in the order they are received.
@@ -66,13 +89,13 @@ If you set the enterprise configuration profile using [`--profile=enterprise`](.
 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
+## Drop 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
+## Replace transactions with the same sender and nonce
 
 ### In networks with a base fee and priced gas
 
@@ -118,6 +141,7 @@ You can configure and monitor the transaction pool using the following methods,
 | 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-min-score`](../../reference/cli/options.md#tx-pool-min-score)                | Option to remove a pending transaction from the layered transaction pool when its score is below a specified value.               |
 | 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.           |

diff --git a/docs/public-networks/reference/cli/options.md b/docs/public-networks/reference/cli/options.md
@@ -5613,6 +5613,52 @@ tx-pool-min-gas-price="2000"
 The minimum gas price, in wei, required for a transaction to be accepted into the [transaction pool](../../concepts/transactions/pool.md).
 
 
+### `tx-pool-min-score`
+
+<Tabs>
+
+<TabItem value="Syntax" label="Syntax" default>
+
+```bash
+--tx-pool-min-score=<INTEGER>
+```
+
+</TabItem>
+
+<TabItem value="Example" label="Example">
+
+```bash
+--tx-pool-min-score=-100
+```
+
+</TabItem>
+
+<TabItem value="Environment variable" label="Environment variable">
+
+```bash
+BESU_TX_POOL_MIN_SCORE=-100
+```
+
+</TabItem>
+
+<TabItem value="Configuration file" label="Configuration file">
+
+```bash
+tx-pool-min-score="-100"
+```
+
+</TabItem>
+
+</Tabs>
+
+Remove a pending transaction from the [layered transaction pool](../../concepts/transactions/pool.md#penalize-invalid-pending-transactions)
+if its score is lower than this value. Accepts a value between `-128` and `127`.
+The default is `-128`.
+
+The lowest score a pending transaction can have is `-128`. The default value of `-128` means that pending
+transactions will not be removed and will remain in the pool with the lowest score, being selected after
+all other pending transactions.
+
 ### `tx-pool-no-local-priority`
 
 <Tabs>