CheckTx Phase
- Transaction routing: The ante handler identifies transaction type via extension options (
ante/ante.go:18-71
) - EVM validation: MonoDecorator consolidates validation using go-ethereum’s
txpool.ValidateTransaction()
(ante/evm/mono_decorator.go:99+
) - Transaction filtering: Uses
PendingFilter
with configurableMinTip
, base fee, and transaction type filters (mempool/mempool.go:455-461
) - Nonce gap handling: Transactions with future nonces are queued locally via
InsertInvalidNonce()
(mempool/check_tx.go:21-23
) - Mempool addition: Valid transactions added to CometBFT mempool for P2P broadcast
DeliverTx Phase
- Message unwrapping:
msg.AsTransaction()
extracts Ethereum transaction fromMsgEthereumTx
(x/vm/keeper/msg_server.go:32
) - State transition:
ApplyTransaction()
executes EVM logic with gas isolation (x/vm/keeper/state_transition.go:165-199
) - Cache contexts: Isolated execution with rollback capability (
x/vm/keeper/state_transition.go:182
) - State commitment: Successful transactions committed to Cosmos SDK store
For detailed transaction flow and mempool behavior, see the Mempool documentation and Cosmos SDK lifecycle.
Transaction Types
Cosmos EVM supports two transaction types:- Cosmos transactions
- Ethereum transactions
MsgEthereumTx
(x/vm/types/tx.pb.go:36-43
), which contains:
From
: Ethereum signer address bytes for signature verificationRaw
: Complete Ethereum transaction data
sdk.Msg
and sdk.Tx
interfaces, bypassing standard SDK transaction bundling to use go-ethereum validation logic directly.
Find more information about these two types on the following sections.
Cosmos Transactions
On Cosmos chains, transactions are comprised of metadata held in contexts andsdk.Msg
s that trigger state changes within a module through the module’s Protobuf Msg service.
When users want to interact with an application and make state changes (e.g. sending coins), they create transactions. Cosmos transactions can have multiple sdk.Msg
s. Each of these must be signed using the private key associated with the appropriate account(s), before the transaction is broadcasted to the network.
A Cosmos transaction includes the following information:
Msgs
: an array of msgs (sdk.Msg
)GasLimit
: option chosen by the users for how to calculate how much gas they will need to payFeeAmount
: max amount user is willing to pay in feesTimeoutHeight
: block height until which the transaction is validSignatures
: array of signatures from all signers of the txMemo
: a note or comment to send with the transaction
Ethereum Transactions
Ethereum transactions refer to actions initiated by EOAs (externally-owned accounts, managed by humans), rather than internal smart contract calls. Ethereum transactions transform the state of the EVM and therefore must be broadcasted to the entire network. Ethereum transactions also require a fee, known asgas
. (EIP-1559) introduced the idea of a base fee, along with a priority fee which serves as an incentive for validators to include specific transactions in blocks.
There are several categories of Ethereum transactions:
- regular transactions: transactions from one account to another
- contract deployment transactions: transactions without a
to
address, where the contract code is sent in thedata
field - execution of a contract: transactions that interact with a deployed smart contract, where the
to
address is the smart contract address
recipient
: receiving addresssignature
: sender’s signaturenonce
: counter of tx number from accountvalue
: amount of ETH to transfer (in wei)data
: include arbitrary data. Used when deploying a smart contract or making a smart contract method callgasLimit
: max amount of gas to be consumedmaxPriorityFeePerGas
: mas gas to be included as tip to validatorsmaxFeePerGas
: max amount of gas to be paid for tx
AcceptedTxType
(ante/evm/mono_decorator.go:23-27
):
- Legacy Transactions (EIP-155): With chain ID protection
- Access List Transactions (EIP-2930): Pre-declared storage access
- Dynamic Fee Transactions (EIP-1559): Base fee + priority fee model
- Set Code Transactions (EIP-7702): Account code assignment with authorization list support (
x/vm/types/tx.go:28
)
Note: Unprotected legacy transactions are not supported by default.
sdk.Msg
. It achieves this by using the MsgEthereumTx
. This message encapsulates an Ethereum transaction as an SDK message and contains the necessary transaction data fields.
The MsgEthereumTx
implements both sdk.Msg
and sdk.Tx
interfaces to bypass standard Cosmos SDK transaction bundling. This design enables:
- Direct go-ethereum integration: Uses
txpool.ValidateTransaction()
instead of SDK ante handlers - Gas isolation: EVM execution uses infinite gas meter, bypassing SDK gas consumption (
x/vm/keeper/state_transition.go:153-164
) - Economic validation:
CheckSenderBalance()
compares account balance with transaction cost (x/vm/keeper/fees.go:24-39
) - Single message constraint: Only one EVM message per transaction (
ante/evm/mono_decorator.go:88-91
)
EVM Execution Integration
Cosmos EVM creates a sophisticated execution environment that bridges Ethereum and Cosmos SDK state management: Block Context Mapping (x/vm/keeper/state_transition.go:46-57
):
- CometBFT block proposer → EVM coinbase address
- Block height → EVM block number
- Block timestamp → EVM timestamp opcode
- Historical block access via EIP-2935 contract (
x/vm/keeper/state_transition.go:114-122
)
x/vm/keeper/state_transition.go:67-78
):
- Restrict contract creation and execution via EVM opcode interceptors
- Policy-based permissions for
CREATE
,CREATE2
, andCALL
operations
x/vm/keeper/state_transition.go:125
):
- Ethereum-compatible bloom filters for log filtering
- Dual transaction hash emission for cross-ecosystem compatibility (
x/vm/keeper/msg_server.go:77-80
) - Contract address generation via
crypto.CreateAddress()
(x/vm/keeper/state_transition.go:198
)
IBC Integration
Cosmos EVM enables cross-chain functionality through IBC integration accessible directly from EVM smart contracts: ICS20 Precompile: Provides direct interface for Ethereum contracts to initiate cross-chain token transfers, bridging EVM execution with the Cosmos ecosystem. Cosmos SDK Module Access: Smart contracts can interact with bank, staking, distribution, and governance modules through precompiled contracts, enabling DeFi applications that access staking rewards and cross-chain transfers from Solidity code.Transaction Ordering and Prioritization
In Cosmos EVM, both Ethereum and Cosmos transactions compete fairly for block inclusion:Transactions are ordered by their effective tips:
- Ethereum:
gas_tip_cap
ormin(gas_tip_cap, gas_fee_cap - base_fee)
- Cosmos:
(fee_amount / gas_limit) - base_fee
- Higher tips = higher priority, regardless of transaction type
For detailed mempool behavior and flow diagrams, see Mempool Architecture.
Transaction Receipts
Cosmos EVM generates Ethereum-compatible transaction receipts while integrating with Cosmos SDK event systems. Receipt processing (x/vm/keeper/state_transition.go:125-146
) includes:
Bloom Filter Computation: initializeBloomFromLogs()
creates transaction and block-level bloom filters for efficient log filtering.
Gas Reconciliation: calculateCumulativeGasFromEthResponse()
reconciles EVM gas usage with SDK gas meter state.
Dual Event Emission: Events contain both Ethereum transaction hash (for Ethereum tools) and CometBFT transaction hash (for Cosmos tools) (x/vm/keeper/msg_server.go:77-80
).
Receipt fields include:
transactionHash
: hash of the transactiontransactionIndex
: integer of the transactions index position in the blockblockHash
: hash of the block where this transaction was inblockNumber
: block number where this transaction was infrom
: address of the senderto
: address of the receiver. null when its a contract creation transactioncumulativeGasUsed
: The total amount of gas used when this transaction was executed in the blockeffectiveGasPrice
: The sum of the base fee and tip paid per unit of gasgasUsed
: The amount of gas used by this specific transaction alonecontractAddress
: The contract address created, if the transaction was a contract creation, otherwise nulllogs
: Array of log objects, which this transaction generatedlogsBloom
: Bloom filter for light clients to quickly retrieve related logstype
: integer of the transaction type, 0x00 for legacy transactions, 0x01 for access list types, 0x02 for dynamic fees, 0x04 for set code transactionsroot
: transaction stateroot (pre Byzantium)status
: either 1 (success) or 0 (failure)
Implementation Reference
Transaction Processing Core:- Message Definition:
x/vm/types/tx.pb.go:36-43
-MsgEthereumTx
protobuf structure with dual interface implementation - Transaction Types:
x/vm/types/tx.go:13-29
-EvmTxArgs
supporting all transaction types including EIP-7702 authorization lists - Validation Pipeline:
ante/evm/mono_decorator.go
- Consolidated EVM transaction validation with go-ethereum integration - Execution Entry:
x/vm/keeper/msg_server.go:29-47
- Message server processing and telemetry
- State Transition:
x/vm/keeper/state_transition.go:165-199
- Cache contexts, gas isolation, and EVM execution - EVM Integration:
x/vm/keeper/state_transition.go:38-78
- Block context mapping and access control hooks - Economic Validation:
x/vm/keeper/fees.go
- Balance verification, fee deduction, and SDK integration
- ExperimentalEVMMempool:
mempool/mempool.go:44-70
- Unified mempool managing both EVM and Cosmos transactions with fee-based prioritization - Transaction Filtering:
mempool/mempool.go:455-461
- Configurable filtering by minimum tip, base fee, and transaction types - Transaction Broadcasting:
mempool/mempool.go:473-497
- Automatic EVM transaction wrapping and broadcast viaMsgEthereumTx
- Transaction Routing:
mempool/check_tx.go:16-40
- Nonce gap detection and local queuing mechanism