Overview
The EVM mempool is responsible for managing both EVM and Cosmos transactions in a unified pool, enabling Ethereum-compatible transaction flows including out-of-order transactions and nonce gap handling. It serves as a replacement for the default CometBFT FIFO mempool to support Ethereum tooling expectations while maintaining Cosmos SDK compatibility.Purpose and Design
The EVM mempool serves as a bridge between Ethereum’s transaction management model and Cosmos SDK’s consensus layer, enabling Ethereum-compatible transaction flows while maintaining the security and finality guarantees of CometBFT consensus.Design Goals
Ethereum Compatibility: Enable Ethereum tooling to work without modification by supporting:- Out-of-order transaction submission
- Nonce gap handling and automatic promotion
- Transaction replacement with higher fees
- Standard txpool RPC methods
- Unified mempool for both EVM and Cosmos transactions
- Fee-based transaction prioritization
- Integration with existing ante handlers
- Preservation of consensus finality
Use Cases
Complex Contract Deployments: DeFi protocols like Uniswap deploy multiple interdependent contracts rapidly. The mempool handles these deployment scripts without modification by queuing transactions with nonce gaps until they can be executed in order. Batch Transaction Workflows: Development tools and scripts often submit multiple transactions simultaneously, expecting the network to handle ordering and dependencies automatically. Transaction Replacement: Users can speed up pending transactions by submitting replacement transactions with the same nonce but higher fees, following standard Ethereum patterns.Transaction Flow
1. Transaction Submission
Users or other nodes submit transactions to the chain via JSON-RPC or P2P.2. CometBFT Reception
CometBFT receives the transactions and validates them in the app using CheckTx.3. CheckTx Routing
The CheckTx handler processes transactions with special handling for nonce gaps (source): Success Path - Valid transactions with correct nonces pass through to the Comet mempool for broadcast. Nonce Gap Detection - Transactions with future nonces are intercepted and queued locally:CheckTx Nonce Gap Handling
- Insufficient fees: Transactions with
GasFeeCap < BaseFee
fail withErrInsufficientFee
- Insufficient balance: Transactions exceeding account balance
- Invalid signature: Malformed or invalid transaction signatures
4. Comet Mempool Addition
Successfully validated transactions are added to the Comet mempool (FIFO).5. P2P Broadcast
Transactions in the Comet mempool are broadcast to other peers across the network.6. Block Building
When a validator is selected to propose a block, ProcessProposal uses the mempool to build blocks:- Sorts transactions by account (fee priority) and nonce
- Pulls from both local queue and public pool
- Replaces lower-fee duplicates with higher-fee versions
7. Automatic Promotion
The node periodically scans the local queue and promotes transactions when:- Nonce gaps are filled (either in mempool or from on-chain state)
- Promoted transactions are re-broadcast to the network
Transaction Lifecycle
Architecture

Problem Statement
CometBFT rejects transactions with:- Nonce gaps (non-sequential nonces)
- Out-of-order batches (common in deployment scripts)
Solution Architecture
To improve DevEx, a tiered approach was implemented: a local transaction pool handles queuing nonce-gapped transactions, upgrading transactions to CometBFT mempool which allows them to be gossipped to network peers and be included in blocks. This helps reduce network spam/DOS exposure while also enabling proper EVM transaction semantics. The two-tiered approach:- Local queue: Stores gapped transactions without network propagation, preventing invalid transaction gossip
- Public mempool: Contains only valid transactions, maintaining consensus integrity
- Automatic promotion: Moves transactions from local to public when gaps fill, ensuring inclusion once conditions are met

Core Components
CheckTx Handler Intercepts nonce gap errors during validation, routes gapped transactions to the local queue, and returns success to maintain compatibility with Ethereum tooling that expects queuing behavior. Only nonce gaps are intercepted - other validation failures (insufficient fees, balance, etc.) are rejected immediately. TxPool Direct port of Ethereum’s transaction pool that manages both pending (executable) and queued (future) transactions. Handles promotion, eviction, and replacement according to Ethereum rules. LegacyPool Stores non-executable transactions with nonce gaps, tracks dependencies between transactions, and automatically promotes them when gaps are filled. The queue contains only transactions waiting for earlier nonces - not transactions with insufficient fees. ExperimentalEVMMempool Unified structure that manages both EVM and Cosmos transaction pools while providing a single interface for transaction insertion, selection, and removal.Transaction States
Queued (Local Storage):- Nonce gaps: Transactions with nonce > expected nonce
- These are stored locally and promoted when gaps fill
- Insufficient fees:
GasFeeCap < BaseFee
- Insufficient balance: Transaction cost exceeds account balance
- Invalid signature: Malformed or improperly signed transactions
- Gas limit exceeded: Transactions exceeding block gas limit
API Reference
The mempool exposes Ethereum-compatible RPC methods for querying transaction pool state. See the JSON-RPC Methods documentation for detailed API reference:txpool_status
: Get pending and queued transaction countstxpool_content
: View all transactions in the pooltxpool_contentFrom
: View transactions from specific addressestxpool_inspect
: Get human-readable transaction summaries
Integration
For chain developers looking to integrate the mempool into their Cosmos SDK chain, see the EVM Mempool Integration Guide for complete setup instructions.
Configuration
v0.5.0 Configuration Changes
Breaking Change: v0.5.0 replaces pre-built pool objects with configuration-based instantiation for better flexibility.What Changed
Before v0.5.0 (Pre-built Objects):Before v0.5.0 Configuration
After v0.5.0 Configuration
Where to Configure
Application Code (app/app.go
):
- Mempool instantiation during app construction
- Custom pool configurations for chain-specific requirements
- Broadcast function customization (optional)
- Mempool settings are code-level configuration only
- No
app.toml
orconfig.toml
changes required - Configuration happens during application startup
Mempool Configuration Options
v0.5.0 introduces comprehensive configuration options for customizing mempool behavior, replacing previously hard-coded parameters with flexible configuration objects.Basic Configuration
Basic Mempool Configuration
Advanced Configuration
Advanced Mempool Configuration
Custom Priority Functions
Custom Priority Function Example
Custom Broadcast Functions
Custom Broadcast Function Example
Configuration Parameter Details
LegacyPoolConfig Parameters
Source:mempool/txpool/legacypool/legacypool.go:168-178
LegacyPoolConfig Structure
CosmosPoolConfig Parameters
Source: Cosmos SDK mempool typesCosmosPoolConfig Structure
Migration from v0.4.x
Step 1: Remove Pre-built Pools
Remove this code:Remove Pre-built Pools
Step 2: Add Configuration Objects
Add this code:Add Configuration Objects
Step 3: Update Imports
Add required imports:Step 4: Handle New Required Parameters
New Required Parameter:- If
BlockGasLimit
is set to0
, defaults to100_000_000
- If
LegacyPoolConfig
isnil
, useslegacypool.DefaultConfig
- If
CosmosPoolConfig
isnil
, uses default priority mempool - If
MinTip
isnil
, no minimum tip enforcement BroadcastTxFn
is optional (uses default broadcast if nil)
Step 5: Initialization Location
Where to Add Configuration:Initialization Location
Configuration Use Cases
High-Throughput Chains
Resource-Constrained Nodes
DeFi-Optimized Configuration
State Management
The mempool maintains transaction state through the unifiedExperimentalEVMMempool
structure, which manages separate pools for EVM and Cosmos transactions while providing a single interface. This experimental implementation handles fee-based prioritization, nonce sequencing, and transaction verification through an integrated ante handler.
Testing
The mempool behavior can be verified using the test scripts provided in the cosmos/evm repository. Thetests/systemtests/Counter/script/SimpleSends.s.sol
script demonstrates typical Ethereum tooling behavior - it sends 10 sequential transactions in a batch, which naturally arrive out of order and create nonce gaps.