> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmos.network/llms.txt
> Use this file to discover all available pages before exploring further.

# VM

> Ethereum Virtual Machine execution environment for Cosmos SDK

The `x/vm` module from [cosmos/evm](https://github.com/cosmos/evm) provides a fully compatible Ethereum Virtual Machine execution environment as a Cosmos SDK module.

<Note>
  For conceptual understanding of EVM architecture and design, see [EVM Architecture](/evm/v0.4.x/documentation/concepts/overview).
</Note>

## Parameters

The module parameters control EVM behavior and access policies ([source](https://github.com/cosmos/evm/blob/v0.4.1/proto/cosmos/evm/vm/v1/evm.proto)):

| Parameter | Type | Default | Description |
| - | - | - | - |
| `evm_denom` | string | `"atest"` | Token denomination for EVM transactions (18 decimals) |
| `extra_eips` | \[]int64 | `[]` | Additional EIPs to activate beyond hard fork defaults |
| `allow_unprotected_txs` | bool | `false` | Allow non-EIP155 replay-protected transactions |
| `active_static_precompiles` | \[]string | `[]` | Activated static precompile addresses |
| `evm_channels` | \[]string | `[]` | IBC channel IDs for EVM-compatible chains |
| `access_control` | AccessControl | Permissionless | Permission policy for EVM operations |

### Parameter Details

<Expandable title="evm_denom">
  Defines the token used for gas and value transfers in EVM:

  * Must be registered in bank module
  * Should have 18 decimal precision
  * Used for all EVM operations (gas, transfers, contracts)
  * Example: `"atest"`, `"aevmos"`, `"wei"`
</Expandable>

<Expandable title="extra_eips">
  Activates additional EIPs beyond fork defaults:

  | EIP | Description | Gas Impact |
  | - | - | - |
  | 1344 | ChainID opcode | Minimal |
  | 1884 | Repricing for trie-size-dependent opcodes | Increases SLOAD |
  | 2200 | Structured definitions for net gas metering | Variable |
  | 2929 | Gas cost for state access opcodes | Increases cold access |
  | 3198 | BASEFEE opcode | Minimal |
  | 3529 | Reduction in refunds | Reduces max refund |
  | 3855 | PUSH0 instruction | New opcode |
</Expandable>

<Expandable title="access_control">
  Granular control over contract operations:

  ```go theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
  type AccessControl struct {
      Create AccessControlType  // Contract deployment
      Call   AccessControlType  // Contract execution
  }
  ```

  **Access Types:**

  * `PERMISSIONLESS`: Open access, list = blacklist
  * `RESTRICTED`: No access, list ignored
  * `PERMISSIONED`: Limited access, list = whitelist
</Expandable>

## Configuration Profiles

<Tabs>
  <Tab title="Ethereum Compatible">
    ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
    {
      "evm_denom": "atest",
      "extra_eips": [3855],
      "allow_unprotected_txs": false,
      "active_static_precompiles": [
        "0x0000000000000000000000000000000000000100",
        "0x0000000000000000000000000000000000000400"
      ],
      "access_control": {
        "create": {"access_type": "PERMISSIONLESS", "list": []},
        "call": {"access_type": "PERMISSIONLESS", "list": []}
      }
    }
    ```
  </Tab>

  <Tab title="Permissioned">
    ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
    {
      "evm_denom": "atoken",
      "extra_eips": [],
      "allow_unprotected_txs": false,
      "active_static_precompiles": [
        "0x0000000000000000000000000000000000000804"
      ],
      "access_control": {
        "create": {
          "access_type": "PERMISSIONED",
          "list": ["0x1234...", "0xABCD..."]
        },
        "call": {"access_type": "PERMISSIONLESS", "list": []}
      }
    }
    ```
  </Tab>

  <Tab title="High Security">
    ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
    {
      "evm_denom": "asecure",
      "extra_eips": [],
      "allow_unprotected_txs": false,
      "active_static_precompiles": [],
      "access_control": {
        "create": {"access_type": "RESTRICTED", "list": []},
        "call": {
          "access_type": "PERMISSIONED",
          "list": ["0xTrustedContract"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Chain Configuration

Hard fork activation schedule ([source](https://github.com/cosmos/evm/blob/v0.4.1/proto/cosmos/evm/vm/v1/evm.proto#L86-L218)):

| Fork | Default | Type | Opcodes/Features Added |
| - | - | - | - |
| `homestead_block` | 0 | Block | DELEGATECALL |
| `byzantium_block` | 0 | Block | REVERT, RETURNDATASIZE, STATICCALL |
| `constantinople_block` | 0 | Block | CREATE2, EXTCODEHASH, SHL/SHR/SAR |
| `istanbul_block` | 0 | Block | CHAINID, SELFBALANCE |
| `berlin_block` | 0 | Block | Access lists (EIP-2929, 2930) |
| `london_block` | 0 | Block | BASEFEE, EIP-1559 |
| `shanghai_time` | 0 | Timestamp | PUSH0 |
| `cancun_time` | 0 | Timestamp | Transient storage, blob transactions |
| `prague_time` | nil | Timestamp | TBD |
| `verkle_time` | nil | Timestamp | Verkle trees |

## Static Precompiles

Precompiled contracts at fixed addresses ([source](https://github.com/cosmos/evm/blob/v0.4.1/x/vm/types/precompiles.go)):

| Address | Contract | Gas Cost | Description |
| - | - | - | - |
| `0x0000...0100` | **P256** | 3000 | P256 curve verification |
| `0x0000...0400` | **Bech32** | 5000 | Bech32 address encoding |
| `0x0000...0800` | **Staking** | Variable | Delegation operations |
| `0x0000...0801` | **Distribution** | Variable | Reward claims |
| `0x0000...0802` | **ICS20** | Variable | IBC transfers |
| `0x0000...0803` | **Vesting** | Variable | Vesting account ops |
| `0x0000...0804` | **Bank** | Variable | Token transfers |
| `0x0000...0805` | **Gov** | Variable | Governance voting |
| `0x0000...0806` | **Slashing** | Variable | Validator slashing info |

### Activation

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# Via genesis
{
  "active_static_precompiles": [
    "0x0000000000000000000000000000000000000804",
    "0x0000000000000000000000000000000000000800"
  ]
}

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

## Messages

### MsgEthereumTx

Primary message for EVM transactions ([source](https://github.com/cosmos/evm/blob/v0.4.1/proto/cosmos/evm/vm/v1/tx.proto)):

```protobuf theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
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)
}
```

**Validation Requirements:**

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

### MsgUpdateParams

Governance message for parameter updates:

```protobuf theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
message MsgUpdateParams {
  string authority = 1;  // Must be governance module
  Params params = 2;     // New parameters
}
```

## State

### Persistent State

| Key Prefix | Description | Value Type |
| - | - | - |
| `0x01` | Parameters | `Params` |
| `0x02` | Contract code | `[]byte` |
| `0x03` | Contract storage | `[32]byte` |

### Transient State

| Key Prefix | Description | Value Type | Lifetime |
| - | - | - | - |
| `0x01` | Transaction logs | `[]Log` | Per block |
| `0x02` | Block bloom | `[256]byte` | Per block |
| `0x03` | Tx index | `uint64` | Per block |
| `0x04` | Log size | `uint64` | Per block |
| `0x05` | Gas used | `uint64` | Per tx |

## Events

### Transaction Events

| Event | Attributes | When Emitted |
| - | - | - |
| `ethereum_tx` | `amount`, `recipient`, `contract`, `txHash`, `txIndex`, `txGasUsed` | Every EVM transaction |
| `tx_log` | `txLog` (JSON) | When contracts emit events |
| `message` | `sender`, `action="ethereum"`, `module="evm"` | Every message |

### Block Events

| Event | Attributes | When Emitted |
| - | - | - |
| `block_bloom` | `bloom` (hex) | End of each block with EVM txs |

## Queries

### gRPC

```protobuf theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
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

<CodeGroup>
  ```bash Query-Account theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
  # Query EVM account
  evmd query vm account 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0

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

  ```bash Query-State theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
  # Query balance
  evmd query vm balance 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0

  # Query storage slot
  evmd query vm storage 0xContractAddress 0xStorageKey

  # Query contract code
  evmd query vm code 0xContractAddress
  ```

  ```bash Query-Config theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
  # Query module parameters
  evmd query vm params

  # Query EVM config
  evmd query vm config
  ```

  ```bash Debug theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
  # Trace transaction
  evmd query vm trace-tx 0xTxHash

  # Trace block
  evmd query vm trace-block 12345
  ```
</CodeGroup>

## JSON-RPC

### Supported Methods

<Tabs>
  <Tab title="eth namespace">
    | Method | Description |
    | - | - |
    | `eth_accounts` | List accounts |
    | `eth_blockNumber` | Current block number |
    | `eth_call` | Execute call without tx |
    | `eth_chainId` | Get chain ID |
    | `eth_estimateGas` | Estimate gas usage |
    | `eth_gasPrice` | Current gas price |
    | `eth_getBalance` | Get account balance |
    | `eth_getBlockByHash` | Get block by hash |
    | `eth_getBlockByNumber` | Get block by number |
    | `eth_getCode` | Get contract code |
    | `eth_getLogs` | Get filtered logs |
    | `eth_getStorageAt` | Get storage value |
    | `eth_getTransactionByHash` | Get tx by hash |
    | `eth_getTransactionCount` | Get account nonce |
    | `eth_getTransactionReceipt` | Get tx receipt |
    | `eth_sendRawTransaction` | Submit signed tx |
    | `eth_syncing` | Sync status |
  </Tab>

  <Tab title="web3 namespace">
    | Method | Description |
    | - | - |
    | `web3_clientVersion` | Client version |
    | `web3_sha3` | Keccak-256 hash |
  </Tab>

  <Tab title="net namespace">
    | Method | Description |
    | - | - |
    | `net_version` | Network ID |
    | `net_listening` | Node accepting connections |
    | `net_peerCount` | Number of peers |
  </Tab>

  <Tab title="debug namespace">
    | Method | Description |
    | - | - |
    | `debug_traceTransaction` | Detailed tx trace |
    | `debug_traceBlockByNumber` | Trace all txs in block |
    | `debug_traceBlockByHash` | Trace all txs by hash |
    | `debug_getBadBlocks` | Get invalid blocks |
    | `debug_storageRangeAt` | Get storage range |
    | `debug_intermediateRoots` | Get intermediate state roots |
  </Tab>
</Tabs>

## Hooks

Post-transaction processing interface ([source](https://github.com/cosmos/evm/blob/v0.4.1/x/vm/types/interfaces.go)):

```go theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
type EvmHooks interface {
    PostTxProcessing(
        ctx sdk.Context,
        msg core.Message,
        receipt *ethtypes.Receipt,
    ) error
}
```

### Registration

```go theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// 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

| Operation | EVM Gas | Cosmos Gas | Notes |
| - | - | - | - |
| Basic ops | 3-5 | 3-5 | 1:1 mapping |
| SLOAD | 2100 | 2100 | Cold access |
| SSTORE | 20000 | 20000 | New value |
| CREATE | 32000 | 32000 | Contract deploy |
| Precompile | Variable | Variable | Set per precompile |

### Gas Refunds

Maximum refund: 50% of gas used (after London)

```go theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
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**
   ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
   {
     "shanghai_time": "1681338455",  // Test first
     "cancun_time": "1710338455"     // Delay for safety
   }
   ```

### Contract Development

1. **Gas Optimization**
   ```solidity theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
   // Cache storage reads
   uint256 cached = storageVar;
   // Use cached instead of storageVar

   // Pack structs
   struct Packed {
       uint128 a;
       uint128 b;  // Single slot
   }
   ```

2. **Precompile Usage**
   ```solidity theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
   IBank bank = IBank(0x0000000000000000000000000000000000000804);
   uint256 balance = bank.balances(msg.sender, "atest");
   ```

### dApp Integration

1. **Provider Setup**
   ```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
   const provider = new ethers.JsonRpcProvider(
       "http://localhost:8545",
       { chainId: 9000, name: "evmos" }
   );
   ```

2. **Error Handling**
   ```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
   try {
       await contract.method();
   } catch (error) {
       if (error.code === 'CALL_EXCEPTION') {
           // Handle revert
       }
   }
   ```

## Troubleshooting

### Common Issues

| Issue | Cause | Solution |
| - | - | - |
| "out of gas" | Insufficient gas limit | Increase gas limit or optimize contract |
| "nonce too low" | Stale nonce | Query current nonce, retry |
| "insufficient funds" | Low balance | Ensure balance > value + (gasLimit × gasPrice) |
| "contract creation failed" | CREATE disabled or restricted | Check access\_control settings |
| "precompile not active" | Precompile not in active list | Enable via governance |

### Debug Commands

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# 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](https://github.com/cosmos/evm/tree/v0.4.1/x/vm)
* [StateDB](https://github.com/cosmos/evm/tree/v0.4.1/x/vm/statedb)
* [Precompiles](https://github.com/cosmos/evm/tree/v0.4.1/precompiles)
* [AnteHandlers](https://github.com/cosmos/evm/tree/v0.4.1/ante)

### Related Documentation

* [EVM Architecture](/evm/v0.4.x/documentation/concepts/overview) - Conceptual overview
* [Fee Market Module](/evm/v0.4.x/documentation/cosmos-sdk/modules/feemarket) - EIP-1559 implementation
* [ERC20 Module](/evm/v0.4.x/documentation/cosmos-sdk/modules/erc20) - Token conversions