> ## Documentation Index > Fetch the complete documentation index at: https://docs.cosmos.network/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` must be called from your `app.go` after `setAnteHandler` * [`mempool/`](https://github.com/cosmos/evm/tree/main/mempool) — the mempool implementation (`EVMMempool`,`TxPool`, `Rechecker`, `ReapList`, `RecheckPool`, etc) The most common EVM Mempool, Legacy pool parameters, `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. Some advanced settings are not covered by `app.toml`, and require modifying `createMempoolConfig` in `evmd/mempool.go`. `BlockGasLimit` is read from `consensus_params.block.max_gas` in `genesis.json`. ## Configuration Options The `Config` struct controls mempool behavior: ```go title="mempool/mempool.go" theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} type Config 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 BlockGasLimit uint64 // Required: gas limit for block selection MinTip *uint256.Int // Optional: minimum tip for EVM txs PendingTxProposalTimeout time.Duration // Optional but recommended: max amount of time to allocate to fetching pending execution txs InsertQueueSize int // Optional: how many txs can be pending insertion at once EnableTxTracker bool // Optional: if tracking transaction inclusion metrics is enabled } ``` ### 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` * `MinTip` is optional. If unset, selection uses the effective tip from each tx (`min(gas_tip_cap, gas_fee_cap - base_fee)`). * If `PendingTxProposalTimeout` is not provided, 0 is used. This means unlimited timeout and always wait for all tx rechecking to finish before creating a proposal. * If `InsertQueueSize` is 0, the mempool uses a fallback of 5000. * If `EnableTxTracker` is not provided, it is kept false. ### Custom Legacy Pool Configuration Customize EVM transaction pool parameters: ```go title="evmd/mempool.go" theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} // 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 legacyCfg.IncludedNonceCacheSize = 5000 // Max cache size for tracking account nonces 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={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} // 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 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={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} // Example: 50M gas limit for lower capacity chains mempoolConfig := &evmmempool.Config{ BlockGasLimit: 50_000_000, } ``` ### Event Bus Integration Users must connect the mempool to CometBFT's EventBus so it can react to finalized blocks: ```go title="evmd/app.go" theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} // After starting the CometBFT node if m, ok := app.GetMempool().(*evmmempool.EVMMempool); 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 | | `evm.mempool.included-nonce-cache-size` | `4096` | Max amount of nonces to track for eviction. Should be set to the maximum number of accounts you expect to see in a single block, given your chains block gas limit. | | `evm.mempool.pending-tx-proposal-timeout` | `0ms` | Max time to wait for fetching pending execution transaction when creating a proposal. 0 means wait for all transactions to be validated before creating a proposal. Note that this may take a significant amount of time under high load and can degrade performance. We've found setting this to \~250ms strikes the right balance between performance and rechecking a sufficient amount of transactions per block. | | `evm.mempool.check-tx-timeout` | `5s` | Timeout to wait for `CheckTx` on Cosmos txs insertion. | | `evm.mempool.insert-queue-size` | `5000` | Max amount of transactions that can be pending insertion before returning an error. Note that EVM & Cosmos transaction use separate queues. So you may have `insert-queue-size` EVM transactions pending insertion, and `insert-queue-size` Cosmos transactions pending insertion. | | `evm.mempool.enable-tx-tracker` | `false` | If metrics for tracking EVM transaction inclusion latencies should be enabled. | ## 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