EVM Compatibility - Cosmos Documentation

The EVM module is still in active development: Some of what is detailed here may change or be removed entirely as development continues. This document represents the current state of the implementation.Implementation Variations: This document is specific to the current version of Cosmos-EVM and may not be applicable in part or in full to older versions or Ethermint variants.

Critical for Ethermint/Evmos Migrations: Cosmos EVM has significant architectural differences from Ethermint/Evmos. See Migration from Evmos/Ethermint for breaking changes.

Quick Summary

Cosmos EVM provides Ethereum compatibility on Cosmos chains with significant architectural improvements and differences from both standard Ethereum and Ethermint-based implementations Most Important Differences for Developers:

Instant finality - No block reorganizations, transactions are final after one block
1-2 second blocks - Much faster than Ethereum’s 12-15 seconds
Dual Chain IDs - ⚠️ Two completely independent IDs (Cosmos string + EVM integer), unlike Ethermint’s single combined format
Experimental pending state - Two-tiered mempool (local queue + public pool) handles nonce gaps
Configurable base fee - Can be dynamic (EIP-1559) or disabled, distributed to validators instead of burned
Native IBC - Built-in cross-chain communication without bridges
Cosmos precompiles - Direct access to staking, governance, and other Cosmos SDK modules
Token precision - Native tokens use 18 decimals via x/precisebank module
EIP compatibility - Most Core EIPs supported with some consensus-related exceptions (see full matrix)

Core Differences

Aspect	Cosmos EVM	Standard EVM	Impact
Transaction Ordering	Fee priority and nonce with mempool	Gas price and nonce	Similar ordering with two-tier system
Transactions per Block	Multiple per account	Multiple per account	Full Ethereum compatibility
Mempool	Two-tiered (local queue + public pool)	Traditional mempool	Nonce gaps queued locally, valid txs broadcast
Block Rewards	Native token inflation to validators	Block rewards + tips	Different economic model
Consensus	Tendermint/CometBFT	Proof of Work/Stake	Byzantine Fault Tolerant with 2/3+ validator agreement
Finality	Immediate (single block, irreversible)	Probabilistic (12+ confirmations)	No waiting period vs 12-15 minute finality
Chain Reorganizations	Not possible	Possible	Event handling simplified
Address Formats	Dual (0x… and cosmos1…)	Ethereum only (0x…)	Same account accessible via both formats
Gas Token	Native chain token (18 decimals via x/precisebank)	ETH/derivatives	Full precision compatibility
Base Fee	Configurable (can be 0 or dynamic)	Dynamic based on demand	Chain-specific configuration
Block Time	1-2 seconds (configurable via `timeout_commit`)	12-15 seconds (varies by L2)	Faster transaction confirmation
Cross-chain	Native IBC	Bridge protocols	Built-in interoperability

Gas Price Behavior

// May return 0 if NoBaseFee is true, or dynamic value if EIP-1559 is enabled
uint256 baseFee = block.basefee;

// BaseFee is distributed to validators (not burned)
// Lower-bounded by global min-gas-price
uint256 gasPrice = tx.gasprice;

// Priority calculation for EVM transactions
uint256 priority = min(tx.gasTipCap, tx.gasFeeCap - baseFee);

Cosmos EVM supports EIP-1559 with dynamic base fees, but with key differences:

Base fee is distributed to validators instead of burned (preserving token economics)
Can be disabled via NoBaseFee parameter (returns 0 for block.basefee)
Lower-bounded by global min-gas-price configuration
Calculated using x/feemarket module based on block utilization
Transaction priority: min(gas_tip_cap, gas_fee_cap - base_fee) for EVM txs
Unlike Ethereum where base fee is burned, Cosmos EVM maintains token supply

Precompiled Contracts

Cosmos Precompiles

Access staking, governance, IBC, and other Cosmos SDK modules via precompiled contracts at fixed addresses.

Standard Precompiles

All standard Ethereum cryptographic precompiles (ecrecover, sha256, etc.) are fully supported.

Precompile addresses may vary between implementations. Verify addresses with your specific chain.

JSON-RPC Method Support

Cosmos EVM implements most standard Ethereum JSON-RPC methods with modifications for Tendermint consensus:

JSON-RPC Implementation

View the complete JSON-RPC methods reference with detailed implementation status for all eth_*, web3_*, net_*, txpool_*, personal_*, debug_*, and admin_* namespaces.

Key RPC Differences

Mining methods: Return stub values (e.g., eth_mining always false, eth_hashrate always 0)
Uncle methods: Always return 0/null since no uncle blocks exist
Pending state: Full support via experimental mempool with txpool_* methods
Trace methods: Not implemented (use debug_* methods instead)
Light client protocols: Not supported (les_* namespace unavailable)

Address Formats

Dual Address System

Same account accessible via both Ethereum (0x) and Cosmos (bech32) formats. Use Bech32 precompile for conversion.

Ethereum: 0x742d35cc6644c068532fddb11B4C36A58D6D3eAb
Cosmos:   cosmos1wskntvnryr5qxpe4tv5k64rhc6kx6ma4dxjmav

EIP Compatibility

EIP Support Matrix

View the comprehensive matrix of all 339+ Core EIPs with detailed implementation status, searchable by EIP number or feature.

Key EIP Differences

EIP-1559: Base Fee Distribution

EIP-155: Chain-Level Enforcement

Consensus EIPs: Not Applicable

Additional Key Differences

Transaction Execution

Two-tiered mempool: Local queue for nonce-gapped transactions (not broadcast), public pool for executable transactions (broadcast to network)
Fee-priority ordering: Fair competition between EVM and Cosmos txs based on effective tips
Nonce gap handling: Transactions with future nonces queued locally until gaps fill (unique to Cosmos EVM)
Multiple transactions per block per EOA: Full support for batched transactions
Transaction replacement: Same-nonce transactions with higher fees replace lower-fee ones (configurable threshold)
Automatic promotion: Queued transactions promoted to public pool when gaps are filled
Deterministic execution: Same transaction order for all validators due to BFT consensus

State and Storage

No state rent: No storage rent or state expiry mechanisms
Pruning: Historical state can be pruned based on node configuration
Archive nodes: Full historical state requires archive node configuration

Network Architecture

Validator set: Fixed validator set with stake-based voting power (2/3+ required for consensus)
Validator selection: Deterministic round-robin proposer selection based on voting power
No light clients: Full or archive nodes only, no light client protocol
P2P differences: Uses Tendermint/CometBFT P2P networking instead of devp2p
Block propagation: Gossip protocol with immediate finality, no uncle blocks

Developer Considerations

Pending state: Full pending state support via experimental mempool with nonce gap handling
Transaction batching: Send multiple transactions at once, out-of-order delivery handled automatically
Gas refunds: 50% of unused gas is refunded by default (configurable via params)
Revert reasons: Full revert reason strings always available
Event reliability: Events are immediately final, no need to wait for confirmations
Block timestamps: More reliable due to BFT consensus requirements
Account abstraction: EIP-7702 support coming in v0.5.0 for EOA code delegation
Opcode differences: DIFFICULTY/PREVRANDAO returns 0, COINBASE returns validator operator address
Chain ID: Two completely separate independent values (unlike Ethermint’s single ID) - Cosmos string ID for consensus/IBC and EVM integer ID for transactions/wallets
Token precision: x/precisebank module provides 18 decimal precision for native tokens
Storage costs: No state rent mechanisms, pruning configurable per node

Migration from Evmos/Ethermint

Breaking Changes: Migrating from Evmos/Ethermint requires careful planning due to fundamental architectural differences.

Critical Architectural Differences

Chain ID System (Most Important)

Two Completely Independent Chain IDs:

Cosmos Chain ID: String format ("cosmosevm-1")
- Used by: CometBFT, IBC, native SDK transactions
- Can change during upgrades
EVM Chain ID: Integer format (9000)
- Used by: MetaMask, EIP-155, smart contracts
- Must remain constant across upgrades

// genesis.json
"chain_id": "cosmosevm-1",  // Cosmos ID

// EVM params
"evm_chain_id": "9000"      // EVM ID (separate)

State-Breaking Parameter Changes

Module Reorganization

x/evm → x/vm: EVM module renamed to VM module
Organization change: evmos/os → cosmos/evm
Protobuf changes: Package names updated from evmos to cosmos
x/precisebank: New module for 18-decimal precision

Feemarket Updates

MinGasPrice Type Change

Breaking change from Evmos/OS:

- MinGasPrice string  // Old: string type
+ MinGasPrice sdk.Dec // New: decimal type

Global minimum gas price parameter enforcement
More precise fee calculations
Requires genesis state migration

Base Fee v1 Removal

Fee Priority System

VM/App Configuration Changes

EIP Support: Different set of activated EIPs
Config Structure: New configuration format
Precompile Changes: Removed x/authz dependency
IBC Denoms: Changed from erc20/ to erc20 prefix

Migration Checklist

Export State

Export existing chain state before any migration attempts

Update Chain IDs

Configure separate Cosmos and EVM chain IDs (cannot use Ethermint format)

Update Module Names

Rename all references from x/evm to x/vm in code and configs

Update Parameters

Migrate feemarket parameters including min_gas_price type

Test Thoroughly

Verify all precompiles, transactions, and IBC functionality

For detailed migration steps, see Migration Guide v0.3 to v0.4

Common Migration Issues

These issues frequently cause migration failures:

Chain ID Format Errors
- Cannot use Ethermint format evmos_9001-2
- Must configure two separate IDs
- EVM chain ID must remain constant post-migration
Genesis Migration Failures
- Module name changes (x/evm → x/vm)
- Parameter type updates in feemarket
- Protobuf package name changes
Precompile Address Changes
- Different addresses than Evmos/Ethermint
- Some precompiles removed or added
- Verify all addresses before migration
Transaction Pool Behavior
- Different mempool architecture
- Changed priority calculations
- New nonce gap handling

Known Limitations and Considerations

Implementation-Specific Variations

Precompile addresses: May vary between chains - verify with your specific implementation
Transaction replacement thresholds: Configurable per chain, not standardized at 10%
Validator rewards: Distribution mechanics may vary based on chain parameters
Mempool configuration: Two-tiered system is experimental and optional

Missing Ethereum Features

State sync protocols: No snap sync or fast sync equivalents
Light client protocol: Only full nodes supported
MEV infrastructure: No native flashbots or MEV-boost equivalents
Archive node pruning: Different pruning strategies than Ethereum

Areas Under Development

EIP-155 enforcement: Moving from chain-level to per-transaction validation
EIP-7702 (Account Abstraction): Planned for v0.5.0
EIP-2681 (Nonce Limit): Stricter overflow checking needed
Parameter migrations: Ongoing work to simplify upgrades from Evmos/Ethermint (Issue #424)

Mempool Architecture

Two-tiered system with nonce gap handling

Gas & Fees

EIP-1559 implementation details

Chain ID System

Dual chain ID architecture

Pending State

Ethereum-compatible pending transactions

Integration Guide

Add EVM to your Cosmos chain

Migration Guide

Upgrade to latest version

Cosmos EVM

​Quick Summary

​Core Differences

​Gas Price Behavior

​Precompiled Contracts

Cosmos Precompiles

Standard Precompiles

​JSON-RPC Method Support

JSON-RPC Implementation

​Key RPC Differences

​Address Formats

Dual Address System

​EIP Compatibility

EIP Support Matrix

​Key EIP Differences

​Additional Key Differences

​Transaction Execution

​State and Storage

​Network Architecture

​Developer Considerations

​Migration from Evmos/Ethermint

​Critical Architectural Differences

​Chain ID System (Most Important)

​State-Breaking Parameter Changes

​Module Reorganization

​Feemarket Updates

​VM/App Configuration Changes

​Migration Checklist

​Common Migration Issues

​Known Limitations and Considerations

​Implementation-Specific Variations

​Missing Ethereum Features

​Areas Under Development

​Related Documentation

Mempool Architecture

Gas & Fees

Chain ID System

Pending State

Integration Guide

Migration Guide

​Additional Resources

Quick Summary

Core Differences

Gas Price Behavior

Precompiled Contracts

JSON-RPC Method Support

Key RPC Differences

Address Formats

EIP Compatibility

Key EIP Differences

Additional Key Differences

Transaction Execution

State and Storage

Network Architecture

Developer Considerations

Migration from Evmos/Ethermint

Critical Architectural Differences

Chain ID System (Most Important)

State-Breaking Parameter Changes

Module Reorganization

Feemarket Updates

VM/App Configuration Changes

Migration Checklist

Common Migration Issues

Known Limitations and Considerations

Implementation-Specific Variations

Missing Ethereum Features

Areas Under Development

Related Documentation

Additional Resources