Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document sequenced transaction pool behavior #1600

Merged
merged 30 commits into from
Jun 12, 2024
Merged
Show file tree
Hide file tree
Changes from 20 commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
f3cb9d4
Document sequenced transaction pool behavior
joaniefromtheblock May 22, 2024
1b1c74a
Merge branch 'main' into 1561-sequenced-transaction
joaniefromtheblock May 31, 2024
2b6d594
Merge branch 'main' into 1561-sequenced-transaction
joaniefromtheblock Jun 4, 2024
addb70a
Add sequenced text
joaniefromtheblock Jun 4, 2024
04d8b34
update language
joaniefromtheblock Jun 4, 2024
c111556
Update wording
joaniefromtheblock Jun 5, 2024
6c6f94c
Merge branch 'main' into 1561-sequenced-transaction
joaniefromtheblock Jun 6, 2024
ac84e77
Updatedescription
joaniefromtheblock Jun 6, 2024
e48ffde
slight reword
joaniefromtheblock Jun 6, 2024
eeeb67e
edit
joaniefromtheblock Jun 6, 2024
cf0f37e
Merge branch 'main' into 1561-sequenced-transaction
joaniefromtheblock Jun 6, 2024
a413641
Update pool.md
joaniefromtheblock Jun 10, 2024
6a7fe0d
Update table
joaniefromtheblock Jun 10, 2024
0bac155
add default for enterprise profile
joaniefromtheblock Jun 10, 2024
e345767
Update language
joaniefromtheblock Jun 10, 2024
f71e3d2
Merge branch 'main' into 1561-sequenced-transaction
joaniefromtheblock Jun 10, 2024
d1a8da2
Merge branch 'main' into 1561-sequenced-transaction
joaniefromtheblock Jun 11, 2024
da1fec8
Move table
joaniefromtheblock Jun 11, 2024
9c81f60
add clearer language
joaniefromtheblock Jun 11, 2024
0d46e8b
add links
joaniefromtheblock Jun 11, 2024
30abd8a
Update docs/public-networks/concepts/transactions/pool.md
joaniefromtheblock Jun 12, 2024
a4624dd
add additional api methods
joaniefromtheblock Jun 12, 2024
c121fd5
add missing link
joaniefromtheblock Jun 12, 2024
68e55c9
Merge branch 'main' into 1561-sequenced-transaction
joaniefromtheblock Jun 12, 2024
116f1c1
Update docs/public-networks/concepts/transactions/pool.md
joaniefromtheblock Jun 12, 2024
7e1ee09
Update docs/public-networks/concepts/transactions/pool.md
joaniefromtheblock Jun 12, 2024
cbfa35b
Update docs/public-networks/concepts/transactions/pool.md
alexandratran Jun 12, 2024
0d91981
reformat table
joaniefromtheblock Jun 12, 2024
39b51d6
remove space
joaniefromtheblock Jun 12, 2024
074754d
Update link
joaniefromtheblock Jun 12, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 52 additions & 23 deletions docs/public-networks/concepts/transactions/pool.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-options-and-methods).

:::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)
Expand All @@ -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.
Expand All @@ -62,9 +53,23 @@ 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`](../../reference/cli/options.md#enterpriseprivate-profile) or [`--profile=private`](../../reference/cli/options.md#enterpriseprivate-profile), the `sequenced` transaction pool is set by default.
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.
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

Expand All @@ -90,4 +95,28 @@ 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 options and methods

Options and methods for configuring and monitoring the transaction pool include the following:

| | Description | Transaction pool type|
|----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|----------------------|
joaniefromtheblock marked this conversation as resolved.
Show resolved Hide resolved
| [`txpool_besuTransactions`](../../reference/api/index.md#txpool_besutransactions) | API method to list transactions in the transaction pool. | Both |
| [`--tx-pool`](../../reference/cli/options.md#tx-pool) | Option to specify the type of transaction pool to use. | Both |
| [`--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. | Both |
| [`--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. | Layered only |
| [`--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. | Both |
| [`--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. | Both |
| [`--tx-pool-max-prioritized`](../../reference/cli/options.md#tx-pool-max-prioritized) | Option to specify the maximum number of prioritized transactions. | Both |
| [`--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.| Both |
| [`--tx-pool-max-size`](../../reference/cli/options.md#tx-pool-max-size) | Option to specify the maximum size of the transaction pool. | Both |
| [`--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. | Both |
| [`--tx-pool-no-local-priority`](../../reference/cli/options.md#tx-pool-no-local-priority) | Option to disable local priority for transactions. | Both |
| [`--tx-pool-price-bump`](../../reference/cli/options.md#tx-pool-price-bump) | Option to specify the price bump percentage to replace an existing transaction. | Both |
| [`--tx-pool-priority-senders`](../../reference/cli/options.md#tx-pool-priority-senders) | Option to specify sender addresses to prioritize in the transaction pool. | Both |
| [`--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. | Both |
joaniefromtheblock marked this conversation as resolved.
Show resolved Hide resolved
| [`tx-pool-save-file`](../../reference/cli/options.md#tx-pool-save-file) | Option to specify the file for saving the transaction pool state. | Both |
| [`newPendingTransactions`](../../how-to/use-besu-api/rpc-pubsub.md#pending-transactions) | RPC subscription to notify you of transactions added to the transaction pool. | Both |
| [`droppedPendingTransactions`](../../how-to/use-besu-api/rpc-pubsub.md#dropped-transactions) | RPC subscription to notify you of transactions dropped from the transaction pool.| Both |
6 changes: 4 additions & 2 deletions docs/public-networks/reference/cli/options.md
Original file line number Diff line number Diff line change
Expand Up @@ -4951,10 +4951,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`.
joaniefromtheblock marked this conversation as resolved.
Show resolved Hide resolved

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>
Expand Down
Loading