Skip to main content

Documentation Index

Fetch the complete documentation index at: https://cosmos-docs-evm-upgrade-7.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

A transaction refers to an action initiated by an account that changes blockchain state. Transactions are broadcasted to the network where validators validate, execute, and propagate the resulting state change. Transactions consume computational resources (gas) requiring associated fees. Additionally, transactions must be signed using the sender’s private key to prove authenticity.

​
Transaction Lifecycle

The transaction lifecycle involves a dual-phase process through CometBFT consensus:

​
CheckTx Phase

  • Transaction routing: Ante handler identifies transaction type (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 configurable MinTip, base fee, and transaction type filters (mempool/mempool.go:455-461)
  • Nonce gap handling: Transactions with future nonces 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 from MsgEthereumTx (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
  • State commitment: Successful transactions committed to Cosmos SDK store
For detailed transaction flow and mempool behavior, see Mempool documentation and Cosmos SDK lifecycle.

​
Transaction Types

Cosmos EVM supports two transaction types:

​
1. Cosmos Transactions

Transactions comprised of metadata held in contexts and sdk.Msgs that trigger state changes through Protobuf Msg services. Cosmos transactions can have multiple sdk.Msgs and include:
  • Msgs: Array of messages
  • GasLimit: Gas calculation option
  • FeeAmount: Maximum fee willing to pay
  • TimeoutHeight: Block height validity
  • Signatures: Array of signer signatures
  • Memo: Note or comment

​
2. Ethereum Transactions

Actions initiated by EOAs (externally-owned accounts) that transform EVM state. Must be broadcasted to the entire network. Ethereum transaction categories:
  • Regular transactions: Account to account
  • Contract deployment: No to address, contract code in data field
  • Contract execution: Interact with deployed smart contract
Ethereum transaction fields:
  • recipient, signature, nonce, value
  • data: Arbitrary data for contract deployment/calls
  • gasLimit, maxPriorityFeePerGas, maxFeePerGas
Reference: Ethereum transactions

​
Supported Ethereum Transaction Types

Cosmos EVM supports types defined in AcceptedTxType (ante/evm/mono_decorator.go:23-27):
  • Legacy Transactions (EIP-155): 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
Note: Unprotected legacy transactions are not supported by default.

​
MsgEthereumTx Wrapper

Cosmos EVM wraps Ethereum transactions in MsgEthereumTx (x/vm/types/tx.pb.go:36-43):
  • From: Ethereum signer address bytes for signature verification
  • Raw: Complete Ethereum transaction data
This wrapper implements both sdk.Msg and sdk.Tx interfaces, enabling:

​
EVM Execution Integration

Cosmos EVM creates an execution environment bridging 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
Access Control Hooks (x/vm/keeper/state_transition.go:67-78):
  • Restrict contract creation and execution via EVM opcode interceptors
  • Policy-based permissions for CREATE, CREATE2, and CALL operations
Receipt Generation (x/vm/keeper/state_transition.go:125):
  • Ethereum-compatible bloom filters for log filtering
  • Dual transaction hash emission for cross-ecosystem compatibility
  • Contract address generation via crypto.CreateAddress()

​
Transaction Ordering and Prioritization

Transactions are ordered by effective tips:
  • Ethereum: gas_tip_cap or min(gas_tip_cap, gas_fee_cap - base_fee)
  • Cosmos: (fee_amount / gas_limit) - base_fee
Higher tips = higher priority, regardless of transaction type. Nonce Handling:
  • Ethereum transactions: Support nonce gaps with local queuing and automatic promotion
  • Cosmos transactions: Require sequential nonces
For detailed mempool behavior, see Mempool Architecture.

​
Transaction Receipts

Cosmos EVM generates Ethereum-compatible receipts with Cosmos SDK event integration (x/vm/keeper/state_transition.go:125-146):
  • Bloom Filter Computation: Creates transaction and block-level bloom filters
  • Gas Reconciliation: Reconciles EVM gas usage with SDK gas meter state
  • Dual Event Emission: Contains both Ethereum transaction hash and CometBFT transaction hash (x/vm/keeper/msg_server.go:77-80)
Receipt fields include:
  • transactionHash, transactionIndex, blockHash, blockNumber
  • from, to, cumulativeGasUsed, effectiveGasPrice, gasUsed
  • contractAddress, logs, logsBloom
  • type, status

​
IBC Integration

Cosmos EVM enables cross-chain functionality through IBC accessible from EVM smart contracts:
  • ICS20 Precompile: Direct interface for cross-chain token transfers
  • Cosmos SDK Module Access: Smart contracts interact with bank, staking, distribution, and governance modules through precompiled contracts