Remove pending transactions from the layered transactions pool

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,29 @@ 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
+
+A transient invalid pending transaction is a transaction that cannot be included in the current block
+but might be included in a future block due to transient issues, such as an 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`, which decreases with each penalization down to `-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 not be
+removed and will stay in the pool with the lowest score, and selected after all other pending transactions.
+
+
 ## Sequenced transaction pool
 
 In the sequenced transaction pool, transactions are processed strictly in the order they are received.
@@ -118,6 +142,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.           |

docs/public-networks/reference/cli/options.md

@@ -5608,6 +5608,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>