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

# Mempool Configuration

> Customize the EVM mempool behavior on your Cosmos EVM chain.

The mempool holds submitted transactions before they are included in a block, handling ordering, nonce gap queuing, and fee-based prioritization across both EVM and Cosmos transactions. The EVM mempool is enabled by default in `evmd`. For conceptual information about mempool design and architecture, see the [Mempool Concepts](/evm/latest/documentation/concepts/mempool) page.

The mempool setup is split across two locations:

* [`evmd/mempool.go`](https://github.com/cosmos/evm/blob/main/evmd/mempool.go) — `configureEVMMempool` and `createMempoolConfig`, which must be called from your `app.go` after `setAnteHandler`
* [`mempool/`](https://github.com/cosmos/evm/tree/main/mempool) — the mempool implementation (`ExperimentalEVMMempool`, `CheckTxHandler`, `TxPool`)

The most common [Legacy pool](/evm/latest/documentation/concepts/mempool#core-components) parameters and `MinTip` are exposed [via `app.toml`](#app.toml-configuration) and require no code changes. The legacy pool (`legacypool.LegacyPool`) is a port of go-ethereum's transaction pool and handles all EVM transaction ordering and fee enforcement. Advanced legacy pool settings not covered by `app.toml`, along with `CosmosPoolConfig` and `BroadCastTxFn`, require modifying `createMempoolConfig` in `evmd/mempool.go`. `BlockGasLimit` is read from `consensus_params.block.max_gas` in `genesis.json`.

## Configuration Options

The `EVMMempoolConfig` struct controls mempool behavior:

```go title="mempool/mempool.go" theme={"system"}
type EVMMempoolConfig struct {
    LegacyPoolConfig *legacypool.Config                                // Optional: port of Geth's txpool — see Custom Legacy Pool below
    CosmosPoolConfig *sdkmempool.PriorityNonceMempoolConfig[math.Int] // Optional: Cosmos pool tuning — see Custom Cosmos Mempool below
    AnteHandler      sdk.AnteHandler                                   // Required: transaction validation
    BroadCastTxFn    func(txs []*ethtypes.Transaction) error           // Optional: custom promotion broadcast — see Custom Broadcast below
    BlockGasLimit    uint64                                            // Required: gas limit for block selection
    MinTip           *uint256.Int                                      // Optional: minimum tip for EVM txs
}
```

### Defaults and Fallbacks

* If `BlockGasLimit` is `0`, the mempool uses a fallback of `100_000_000` gas.
* If `LegacyPoolConfig` is not provided, defaults from `legacypool.DefaultConfig` are used.
* If `CosmosPoolConfig` is not provided, a default `PriorityNonceMempool` is created with:
  * Priority = `(fee_amount / gas_limit)` in the EVM coin denom
  * Comparator = big-int comparison (higher is selected first)
  * `MinValue = 0`
* If `BroadCastTxFn` is not provided, a default is created that uses the app `clientCtx`/`txConfig` to broadcast EVM transactions when they are promoted from queued → pending.
* `MinTip` is optional. If unset, selection uses the effective tip from each tx (`min(gas_tip_cap, gas_fee_cap - base_fee)`).

### Custom Legacy Pool Configuration

Customize EVM transaction pool parameters:

```go title="evmd/mempool.go" theme={"system"}
// EVM legacy txpool tuning
legacyCfg := legacypool.DefaultConfig
legacyCfg.PriceLimit = 2              // Minimum gas price (wei)
legacyCfg.PriceBump = 15              // 15% price bump to replace
legacyCfg.AccountSlots = 32           // Slots per account
legacyCfg.GlobalSlots = 10240         // Total executable slots
legacyCfg.AccountQueue = 128          // Non-executable per account
legacyCfg.GlobalQueue = 2048          // Total non-executable
legacyCfg.Lifetime = 6 * time.Hour    // Max queue time

mempoolConfig.LegacyPoolConfig = &legacyCfg
```

### Custom Cosmos Mempool Configuration

The mempool uses a `PriorityNonceMempool` for Cosmos transactions by default. You can customize the priority calculation:

```go title="evmd/mempool.go" theme={"system"}
// Define custom priority calculation for Cosmos transactions
cosmosCfg := sdkmempool.PriorityNonceMempoolConfig[math.Int]{}
cosmosCfg.TxPriority = sdkmempool.TxPriority[math.Int]{
    GetTxPriority: func(goCtx context.Context, tx sdk.Tx) math.Int {
        feeTx, ok := tx.(sdk.FeeTx)
        if !ok {
            return math.ZeroInt()
        }

        // Get fee in bond denomination
        bondDenom := "uatom" // or your chain's bond denom
        fee := feeTx.GetFee()
        found, coin := fee.Find(bondDenom)
        if !found {
            return math.ZeroInt()
        }

        // Calculate gas price: fee_amount / gas_limit
        gasPrice := coin.Amount.Quo(math.NewIntFromUint64(feeTx.GetGas()))
        return gasPrice
    },
    Compare: func(a, b math.Int) int {
        return a.BigInt().Cmp(b.BigInt()) // Higher values have priority
    },
    MinValue: math.ZeroInt(),
}

mempoolConfig.CosmosPoolConfig = &cosmosCfg
```

### Custom Broadcast Function

Override the default broadcast behavior for promoted EVM transactions:

```go title="evmd/mempool.go" theme={"system"}
// Custom EVM broadcast (optional)
mempoolConfig.BroadCastTxFn = func(txs []*ethtypes.Transaction) error {
    // Custom logic for broadcasting promoted transactions
    return nil
}
```

### Custom Block Gas Limit

`BlockGasLimit` is read automatically from `consensus_params.block.max_gas` in `genesis.json` — it is not an `app.toml` setting. To change it, update the genesis file before chain start. The value can also be overridden in code:

```go title="evmd/mempool.go" theme={"system"}
// Example: 50M gas limit for lower capacity chains
mempoolConfig := &evmmempool.EVMMempoolConfig{
    AnteHandler:   app.GetAnteHandler(),
    BlockGasLimit: 50_000_000,
}
```

### Event Bus Integration

For best results, connect the mempool to CometBFT's EventBus so it can react to finalized blocks:

```go title="evmd/app.go" theme={"system"}
// After starting the CometBFT node
if m, ok := app.GetMempool().(*evmmempool.ExperimentalEVMMempool); ok {
    m.SetEventBus(bftNode.EventBus())
}
```

This enables chain-head notifications so the mempool can promptly promote/evict transactions when blocks are committed.

## app.toml Configuration

The following settings can be configured in `app.toml` and take effect at node startup without code changes:

| Key                         | Default | Description                                                                                  |
| --------------------------- | ------- | -------------------------------------------------------------------------------------------- |
| `evm.min-tip`               | `0`     | Minimum tip (priority fee) in wei; transactions below this are excluded from block selection |
| `evm.mempool.price-limit`   | `1`     | Minimum gas price in wei to accept a transaction into the pool                               |
| `evm.mempool.price-bump`    | `10`    | Minimum % increase required to replace a pending transaction with the same nonce             |
| `evm.mempool.account-slots` | `16`    | Max executable transactions per account                                                      |
| `evm.mempool.global-slots`  | `5120`  | Max total executable transactions across all accounts                                        |
| `evm.mempool.account-queue` | `64`    | Max queued (non-executable) transactions per account                                         |
| `evm.mempool.global-queue`  | `1024`  | Max total queued transactions across all accounts                                            |
| `evm.mempool.lifetime`      | `3h`    | Max time a transaction can remain queued before eviction                                     |

`CosmosPoolConfig` and `BroadCastTxFn` have no `app.toml` equivalent and require code changes in `createMempoolConfig`.

## Monitoring and Debugging

Use the [txpool RPC methods](/evm/latest/api-reference/ethereum-json-rpc/methods#txpool-methods) to monitor mempool state:

* `txpool_status`: Get pending and queued transaction counts
* `txpool_content`: View all transactions in the pool
* `txpool_inspect`: Get human-readable transaction summaries
* `txpool_contentFrom`: View transactions from specific addresses

## Related Documentation

* [Mempool Concepts](/evm/latest/documentation/concepts/mempool) - Understanding mempool behavior and design
* [EVM Module Integration](/evm/latest/documentation/getting-started/build-a-chain/overview) - Prerequisites for mempool integration
* [JSON-RPC Methods](/evm/latest/api-reference/ethereum-json-rpc/methods#txpool-methods) - Mempool query methods