> For the complete documentation index, see [llms.txt](https://docs.citrea.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.citrea.xyz/advanced/citrea-mempool.md).

# Citrea Mempool

As a Type-2 zkEVM rollup, Citrea inherits its transaction pool architecture from [Reth](https://github.com/paradigmxyz/reth/), the high-performance Ethereum execution client. This page explains how the Citrea mempool works, its architecture, and key differences from the standard Reth implementation.

## Architecture Overview

Citrea uses a **dual-mempool architecture**:

1. **Main Transaction Mempool**: Handles regular EVM transactions using Reth's transaction pool
2. **Deposit Data Mempool**: A separate FIFO queue specifically for Bitcoin deposit transactions

### Reth Transaction Pool Foundation

The main mempool is built on Reth's `Pool` type with the following components:

| Component      | Implementation            | Purpose                                           |
| -------------- | ------------------------- | ------------------------------------------------- |
| **Validator**  | `EthTransactionValidator` | Validates transactions against current state      |
| **Ordering**   | `CoinbaseTipOrdering`     | Orders transactions by effective tip/priority fee |
| **Blob Store** | `NoopBlobStore`           | EIP-4844 blob storage (disabled)                  |

## Sub-Pool Structure

[Reth's transaction pool](https://reth.rs/docs/reth_transaction_pool/index.html) uses a three-layer sub-pool model that Citrea inherits:

### Pending Sub-Pool

Contains transactions that are ready for immediate block inclusion:

* Nonce matches the account's next expected nonce
* Balance covers gas costs and value
* Gas price meets the current base fee

### Base-Fee Sub-Pool

Holds transactions that are valid but currently below the base fee:

* Transactions move here when base fee increases
* Automatically promoted to pending when base fee drops

### Queued Sub-Pool

Stores transactions that cannot yet be executed:

* Nonce gaps exist (waiting for earlier transactions)
* Insufficient balance (waiting for deposits)

Transactions automatically move between sub-pools as conditions change. When a nonce gap is filled, queued transactions are promoted. When base fee changes, transactions shift between pending and base-fee pools.

<figure><img src="/files/MkSco6TmbI3yHNpOiTJC" alt=""><figcaption><p>Simplified Reth Transaction Pool Architecture</p></figcaption></figure>

## Transaction Validation

### Stateless Validation

Before entering the pool, transactions undergo stateless checks:

* Transaction type is supported for the current fork
* Input data does not exceed limits
* Gas limits and fee requirements are met
* Chain ID matches
* Intrinsic gas calculations are valid

### Stateful Validation

Additional checks against the current blockchain state:

* Sender account has no bytecode (unless EIP-7702 delegated)
* Nonce is greater than or equal to account nonce
* Balance covers value plus gas costs

### Citrea-Specific Validation

Citrea adds additional validation rules:

**System Transaction Filtering**: Transactions signed by the system signer are rejected from user submissions. System transactions are reserved for internal operations like Bitcoin light client updates and bridge deposits.

**EIP-4844 Blob Transactions**: Explicitly disabled on Citrea. Blob transactions are rejected at submission time.

**L1 Fee Validation**: Transactions must have sufficient balance to cover [L1 data availability fees](/advanced/fee-model.md#l1-data-availability-fee). Transactions failing L1 fee validation during block production are evicted from the mempool.

## Transaction Ordering

Citrea uses `CoinbaseTipOrdering`, which orders transactions by their effective tip:

```
effective_tip = priority_fee + max_fee_per_gas - base_fee
```

This creates MEV-resistant ordering similar to Ethereum's approach. Only the pending pool uses priority-based ordering for block production; other pools use different sorting criteria (base-fee pool by fee, queued pool by nonce distance).

## Configuration

Citrea's mempool is configured with **significantly larger limits** than standard Reth defaults to handle high throughput from the 2-second block time:

| Parameter         | Citrea Default | Standard Reth |
| ----------------- | -------------- | ------------- |
| Pending TX Limit  | 100,000        | \~10,000      |
| Pending TX Size   | 200 MB         | \~20 MB       |
| Queued TX Limit   | 100,000        | \~10,000      |
| Queued TX Size    | 200 MB         | \~20 MB       |
| Base-Fee TX Limit | 100,000        | \~10,000      |
| Base-Fee TX Size  | 200 MB         | \~20 MB       |
| Max Account Slots | 64             | 64            |
| Max TX Lifetime   | 3 hours        | 3 hours       |

### Environment Variables

| Variable            | Description                               |
| ------------------- | ----------------------------------------- |
| `PENDING_TX_LIMIT`  | Maximum transactions in pending sub-pool  |
| `PENDING_TX_SIZE`   | Maximum MB in pending sub-pool            |
| `QUEUE_TX_LIMIT`    | Maximum transactions in queued sub-pool   |
| `QUEUE_TX_SIZE`     | Maximum MB in queued sub-pool             |
| `BASE_FEE_TX_LIMIT` | Maximum transactions in base-fee sub-pool |
| `BASE_FEE_TX_SIZE`  | Maximum MB in base-fee sub-pool           |
| `MAX_ACCOUNT_SLOTS` | Guaranteed slots per account              |

## Eviction Policies

Transactions are evicted from the mempool when:

1. **Size limits exceeded**: When a sub-pool exceeds its transaction count or size limit, the lowest-priority transactions are removed
2. **Lifetime exceeded**: Non-executable transactions older than 3 hours are removed
3. **Account slot limit**: If an account exceeds its guaranteed slots, lowest-priority transactions from that account are evicted
4. **L1 fee failure**: Transactions that fail L1 fee validation during dry-run are removed

## Deposit Data Mempool

Citrea maintains a separate mempool for Bitcoin deposit transactions with different characteristics:

| Aspect     | Main Mempool      | Deposit Mempool                      |
| ---------- | ----------------- | ------------------------------------ |
| Ordering   | Priority (by fee) | FIFO (first-in-first-out)            |
| Validation | EVM rules         | ABI decoding + Bitcoin TX validation |
| Duplicates | By hash           | By Bitcoin TX ID (SHA256)            |

Deposit transactions are processed in order of arrival, not by fee, ensuring fair treatment of bridge deposits.

## Block Production Flow

During block production, the sequencer:

1. **Fetches best transactions** from the mempool based on current base fee
2. **Dry-runs each transaction** against the block state
3. **Validates L1 fees** and removes failing transactions
4. **Builds the block** with successful transactions
5. **Notifies the mempool** of included transactions for removal
6. **Triggers maintenance** to update account states and promote/demote transactions

<figure><img src="/files/kPsatbT0gL42YKvwEWFe" alt=""><figcaption><p>Sequencer Block Production Flow</p></figcaption></figure>

## Mempool Maintenance

A background maintenance task runs continuously to keep the mempool consistent:

* **Account state updates**: Reloads nonces and balances after new blocks
* **Transaction promotion**: Moves newly-executable transactions to pending
* **Transaction demotion**: Moves no-longer-executable transactions to queued
* **Expiration cleanup**: Removes transactions exceeding the lifetime limit

## RPC Methods

### Standard Ethereum Methods

| Method                     | Description                              |
| -------------------------- | ---------------------------------------- |
| `eth_sendRawTransaction`   | Submit a transaction to the mempool      |
| `eth_getTransactionByHash` | Get transaction from mempool or chain    |
| `txpool_content`           | View all pending and queued transactions |

### Citrea-Specific Deposit Data Mempool RPC Method

| Method                             | Description                                                                                                      |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `citrea_sendRawDepositTransaction` | Submit a [deposit transaction](/developer-documentation/system-contracts/bridge.md#deposit-flow) with validation |

## Key Differences from Standard Reth

| Aspect              | Standard Reth  | Citrea                                |
| ------------------- | -------------- | ------------------------------------- |
| Pool Size           | Default limits | 10x larger capacity                   |
| Blob Transactions   | Supported      | Disabled                              |
| System Transactions | Not filtered   | Rejected from RPC                     |
| Deposit Handling    | N/A            | Separate FIFO mempool                 |
| L1 Fee Validation   | N/A            | Custom validation and eviction        |
| Persistence         | In-memory      | Stored in LedgerDB for crash recovery |