VM

​

Parameters

​

Parameter Details

{
  "history_serve_window": 8192   // Default: full EIP-2935 compatibility
}

{
  "history_serve_window": 1024   // Performance optimized: reduced storage
}

{
  "history_serve_window": 16384  // Extended history: maximum compatibility
}

contract HistoryExample {
    function getRecentBlockHash(uint256 blockNumber) public view returns (bytes32) {
        // Works for blocks within history_serve_window range
        return blockhash(blockNumber);
    }
}

type AccessControl struct {
    Create AccessControlType  // Contract deployment
    Call   AccessControlType  // Contract execution
}

​

Configuration Profiles

{
  "evm_denom": "atest",
  "extra_eips": [3855],
  "active_static_precompiles": [
    "0x0000000000000000000000000000000000000100",
    "0x0000000000000000000000000000000000000400"
  ],
  "evm_channels": [],
  "access_control": {
    "create": {"access_type": "PERMISSIONLESS", "access_control_list": []},
    "call": {"access_type": "PERMISSIONLESS", "access_control_list": []}
  },
  "history_serve_window": 8192
}

​

Chain Configuration

​

Static Precompiles

​

Activation

# Via genesis
{
  "active_static_precompiles": [
    "0x0000000000000000000000000000000000000804",
    "0x0000000000000000000000000000000000000800"
  ]
}

# Via governance proposal
evmd tx gov submit-proposal update-params-proposal.json

​

Messages

​

MsgEthereumTx

message MsgEthereumTx {
  google.protobuf.Any data = 1;  // Transaction data (Legacy/AccessList/DynamicFee)
  string hash = 3;                // Transaction hash
  string from = 4;                // Sender address (derived from signature)
}

• Valid signature matching from address
• Sufficient balance for gas + value
• Correct nonce (account sequence)
• Gas limit ≥ intrinsic gas

​

MsgUpdateParams

message MsgUpdateParams {
  string authority = 1;  // Must be governance module
  Params params = 2;     // New parameters
}

​

State

​

Persistent State

​

Transient State

​

Events

​

Transaction Events

​

Block Events

​

Queries

​

gRPC

service Query {
  // Account queries
  rpc Account(QueryAccountRequest) returns (QueryAccountResponse);
  rpc CosmosAccount(QueryCosmosAccountRequest) returns (QueryCosmosAccountResponse);
  rpc ValidatorAccount(QueryValidatorAccountRequest) returns (QueryValidatorAccountResponse);
  
  // State queries
  rpc Balance(QueryBalanceRequest) returns (QueryBalanceResponse);
  rpc Storage(QueryStorageRequest) returns (QueryStorageResponse);
  rpc Code(QueryCodeRequest) returns (QueryCodeResponse);
  
  // Module queries
  rpc Params(QueryParamsRequest) returns (QueryParamsResponse);
  rpc Config(QueryConfigRequest) returns (QueryConfigResponse);
  
  // EVM operations
  rpc EthCall(EthCallRequest) returns (MsgEthereumTxResponse);
  rpc EstimateGas(EthCallRequest) returns (EstimateGasResponse);
  
  // Debugging
  rpc TraceTx(QueryTraceTxRequest) returns (QueryTraceTxResponse);
  rpc TraceBlock(QueryTraceBlockRequest) returns (QueryTraceBlockResponse);
  
  // Fee queries
  rpc BaseFee(QueryBaseFeeRequest) returns (QueryBaseFeeResponse);
  rpc GlobalMinGasPrice(QueryGlobalMinGasPriceRequest) returns (QueryGlobalMinGasPriceResponse);
}

​

CLI

# Query EVM account
evmd query vm account 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0

# Query Cosmos address
evmd query vm cosmos-account 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0

​

JSON-RPC

​

Supported Methods

​

Hooks

type EvmHooks interface {
    PostTxProcessing(
        ctx sdk.Context,
        msg core.Message,
        receipt *ethtypes.Receipt,
    ) error
}

​

Registration

// In app.go
app.EvmKeeper = app.EvmKeeper.SetHooks(
    vmkeeper.NewMultiEvmHooks(
        app.Erc20Keeper.Hooks(),
        app.CustomKeeper.Hooks(),
    ),
)

​

Use Cases

• Process EVM events in Cosmos modules
• Bridge EVM logs to Cosmos events
• Trigger native module actions from contracts
• Custom indexing and monitoring

​

Gas Configuration

​

Gas Consumption Mapping

​

Gas Refunds

refund = min(gasUsed/2, gasRefund)
finalGasUsed = gasUsed - refund

​

Best Practices

​

Chain Integration

1. Precompile Selection
   • Only enable necessary precompiles
   • Test gas costs in development
   • Monitor usage patterns
2. Access Control
   • Start restrictive, open gradually
   • Use governance for changes
   • Monitor blacklist/whitelist events
3. Fork Planning
   Copy

   {
     "shanghai_time": "1681338455",  // Test first
     "cancun_time": "1710338455"     // Delay for safety
   }
   

​

Contract Development

1. Gas Optimization
   Copy

   // Cache storage reads
   uint256 cached = storageVar;
   // Use cached instead of storageVar
   
   // Pack structs
   struct Packed {
       uint128 a;
       uint128 b;  // Single slot
   }
   

2. Precompile Usage
   Copy

   IBank bank = IBank(0x0000000000000000000000000000000000000804);
   uint256 balance = bank.balances(msg.sender, "atest");
   

​

dApp Integration

1. Provider Setup
   Copy

   const provider = new ethers.JsonRpcProvider(
       "http://localhost:8545",
       { chainId: 9000, name: "evmos" }
   );
   

2. Error Handling
   Copy

   try {
       await contract.method();
   } catch (error) {
       if (error.code === 'CALL_EXCEPTION') {
           // Handle revert
       }
   }
   

​

Troubleshooting

​

Common Issues

​

Debug Commands

# Check EVM parameters
evmd query vm params

# Trace failed transaction
evmd query vm trace-tx 0xFailedTxHash

# Check account state
evmd query vm account 0xAddress

​

References

​

Source Code

• VM Module Implementation
• StateDB
• Precompiles
• AnteHandlers

​

Related Documentation

• EVM Architecture - Conceptual overview
• Fee Market Module - EIP-1559 implementation
• ERC20 Module - Token conversions