> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction Pool

## Purpose and Scope

The transaction pool manages **pending transactions** that have been submitted to the node but are not yet included in a block. Its primary responsibilities are as follows:

1. **Acceptance**: Receive transactions from RPC clients and P2P peers
2. **Validation**: Verify signatures, nonce, balance, and gas-related rules
3. **Storage**: Store transactions in memory based on their executability state
4. **Provisioning**: Provide transactions to the miner/worker for block assembly
5. **Propagation**: Broadcast transactions over the P2P network
6. **Querying**: Expose pool status through RPC APIs

Related documents:

* Transaction execution: [State Transitions](/en/transaction-processing/6.2-state-transitions-and-gas)
* Transaction data structures: [Transaction Types and Encoding](/en/core-architecture/3.5-transaction-types-and-encoding)
* Transaction consumption during block production: [Block Production](/en/consensus-and-block-production/4.2-block-production-and-mining)

## Architecture Overview

`txpool.TxPool` acts as the central coordinator for transaction management.

```
RPC (eth_sendRawTransaction)  ──┐
                                 ├→ TxPool.Add() → validation → queued/pending classification
P2P (NewPooledTransactionHashes) ┘                         │
                                                           ├→ NewTxsEvent published
                                                           ├→ P2P propagation
                                                           └→ Worker.Pending() → block assembly
```

The transaction pool consists of two sub-pools:

* **legacypool**: Handles standard transactions (types 0x00–0x04, 0x16)
* **blobpool**: Handles blob transactions (EIP-4844)

## Transaction Submission Paths

Transactions enter the pool through one of the following paths.

### RPC Submission

Transactions submitted via `eth_sendRawTransaction` or `eth_sendTransaction` are classified as **local transactions**.\
Local transactions are prioritized and are relatively protected by the eviction policy when the pool is under pressure.

### P2P Submission

Transactions received from peers via the `eth` protocol are classified as **remote transactions**.\
Remote transactions are subject to more conservative validation policies and have a lower default priority.

## Transaction Validation

All transactions accepted via `TxPool.Add()` must pass the following validation steps.

| Validation Item      | Description                                                          |
| -------------------- | -------------------------------------------------------------------- |
| **Signature**        | ECDSA signature verification and sender address recovery             |
| **Nonce**            | Comparison against the sender’s current on-chain nonce               |
| **Balance**          | Sufficient balance to cover value + maximum gas cost                 |
| **Gas Limit**        | Must be below the block gas limit and above intrinsic gas            |
| **Gas Price / Tip**  | Must satisfy the pool’s minimum gas requirements                     |
| **Transaction Type** | Type-specific field and rule validation                              |
| **Fee Delegation**   | For fee-delegated transactions, validate payer signature and balance |

### Gas Price and Gas Tip Validation

For EIP-1559-based transactions (types 0x02, 0x04, 0x16), the effective gas tip is calculated as:

```
EffectiveGasTip = min(GasTipCap, GasFeeCap - BaseFee)
```

In the Anzeon network, gas tip rules differ by account type:

* **Authorized accounts**: May use the `GasTipCap` specified in the transaction
* **General accounts**: Must satisfy the governance-defined `GasTip` included in the block header

## Internal Pool Structure

### Pending Transactions

* Sender nonce exactly matches the current on-chain nonce
* Immediately executable
* Candidates for inclusion in the next block
* Provided to the worker via `Pending()`

### Queued Transactions

* Sender nonce is a future value
* Cannot be executed until preceding nonce transactions are processed
* Automatically promoted to pending once conditions are met

## Capacity Limits

The transaction pool uses **slot-based capacity limits** to control memory usage and mitigate denial-of-service (DoS) attacks.\
Each transaction occupies one or more slots depending on its size, and limits are enforced at both the account level and the global level.

| Limit Type          | Parameter      | Default | Description                                                  |
| ------------------- | -------------- | ------- | ------------------------------------------------------------ |
| Per-account Pending | `AccountSlots` | 16      | Maximum slots a single account may hold in pending state     |
| Per-account Queued  | `AccountQueue` | 64      | Maximum slots a single account may hold in queued state      |
| Global Pending      | `GlobalSlots`  | 5120    | Total pending slots shared by all accounts                   |
| Global Queued       | `GlobalQueue`  | 1024    | Total queued slots shared by all accounts                    |
| Minimum Gas Price   | `PriceLimit`   | 1 Gwei  | Minimum effective gas price accepted by the pool             |
| Replacement Bump    | `PriceBump`    | 10%     | Minimum gas price increase required to replace a transaction |

Although the default `PriceLimit` is 1 Gwei, StableNet applies the network-wide `GasTip` value determined by GovValidator governance as the effective baseline.

## Transaction Eviction Rules

When the transaction pool reaches its capacity limit, it evicts transactions with the lowest priority to make room for new ones.\
Eviction decisions consider both **slot-based capacity constraints** and **fee-based priority ordering**.

The core principles are:

* **Priority-based eviction**\
  Transactions are ordered by fee priority, and the lowest-priority transactions are removed first.

* **Account-level limits first**\
  If a specific account exceeds its per-account slot limits (`AccountSlots`, `AccountQueue`), that account’s transactions are evicted first.

* **Global eviction on overflow**\
  If global pending or queued slot limits (`GlobalSlots`, `GlobalQueue`) are exceeded, the lowest-priority transactions across all accounts are evicted.

* **Local transaction protection**\
  Locally submitted transactions have lower eviction priority than remote transactions and are preserved whenever possible.

This policy ensures stable memory usage while preferentially retaining transactions with higher fees and better execution prospects.

## Transaction Replacement Rules

A new transaction with the same sender and nonce may replace an existing transaction only if it offers an effective gas price at least `PriceBump` higher than the existing one.

`PriceBump` is applied as a **percentage-based relative increase**.\
For example, with `PriceBump = 10%`, the new transaction’s effective gas price must be at least 10% higher than the existing transaction.

This mechanism allows users to increase gas conditions to mitigate processing delays.

## Transaction Query APIs

### txpool RPC Namespace

* `txpool_content`: Retrieve all pending and queued transactions
* `txpool_contentFrom(address)`: Retrieve transactions for a specific address
* `txpool_status`: Retrieve counts of pending and queued transactions
* `txpool_inspect`: Human-readable summary view

### Backend Access Methods

Through `EthAPIBackend`, the following internal methods are available:

* `SendTx(tx)`
* `GetPoolTransaction(hash)`
* `GetPoolTransactions()`
* `GetPoolNonce(addr)`
* `Stats()`

## Event System

When a transaction is accepted into the pool, a `NewTxsEvent` is published.

Primary subscribers:

* **Worker**: Incorporates transactions into the current block candidate
* **P2P Handler**: Propagates transactions to other peers
* **RPC Subscribers**: Provides pending transaction notifications

Events can be subscribed to via `SubscribeNewTxsEvent()`.

## Integration with Block Production

During block assembly, the worker calls `TxPool.Pending()` to retrieve executable transactions.\
The returned structure is organized as `address → nonce-ordered transaction list`.

### Ordering Priority

1. Effective gas tip
2. Nonce order within each account
3. Executability
4. Anzeon authorized account status

## P2P Network Integration

### Propagation Flow

Transactions added to the local pool are propagated to peers by hash, with full transactions requested as needed.

### Reception Flow

1. Peer announces transaction hashes
2. Missing hashes are identified
3. Full transactions are requested
4. Transactions are validated and added to the pool
5. Accepted transactions are re-propagated

## Pool Updates on Block Reception

When a new block is inserted into the chain, the transaction pool performs the following steps:

1. Remove transactions included in the block
2. Update sender nonces
3. Promote queued transactions
4. Revalidate based on updated balances
5. Remove transactions that are no longer valid

In the Anzeon network, this process also queries the GovValidator contract to synchronize the latest gas tip policy with both the pool and the worker.