Quick Start: Build with evmd

Get started building with the Cosmos EVM reference implementation (evmd). Run a local chain, configure parameters, and connect your wallet.

Quick Start with evmd

The evmd directory in the Cosmos EVM repository contains a reference chain implementation that demonstrates how to integrate Cosmos EVM modules. Use evmd as a starting point for understanding chain configuration and local development.

This quick start guide covers:

1. Running evmd locally - Get a chain running quickly
2. Basic configuration - Understand key parameters
3. Wallet connection - Connect MetaMask for testing

For detailed configuration options, see the Chain Configuration Parameters guide.

Prerequisites

Before starting, ensure you have:

• Go 1.23.8+ - Installation guide
• Git - For cloning the repository
• Make - For build commands

Clone the Repository

Start by cloning the Cosmos EVM repository:

git clone https://github.com/cosmos/evm.git
cd evm

Run a Local Chain

The easiest way to start is using the provided local_node.sh script:

./local_node.sh -y

This script handles:

• Building the evmd binary
• Initializing chain configuration
• Setting up genesis parameters
• Starting the chain with JSON-RPC enabled

Script Flags:

• -y: Fresh start (overwrites previous database)
• -n: Resume from previous state
• --no-install: Skip binary rebuild
• --remote-debugging: Build with debugging symbols

Default Configuration

The evmd reference implementation comes with these defaults:

Parameter	Default Value	Configuration Method
Chain ID	cosmos_262144-1	Genesis (set at init)
EVM Chain ID	262144	CLI flag or app.toml
Base Denomination	aatom (18 decimals)	Genesis
Token Pairs	1 (WEVMOS contract)	Genesis
Precompiles	All 9 enabled	Genesis
EVM Permissions	Permissionless	Genesis

The default 18-decimal token (aatom) provides direct EVM compatibility without requiring additional modules.

Customize Configuration

To customize your chain configuration, you can modify several parameters:

1. Initialize with Custom Chain ID

   evmd init mynode --chain-id yourchain-1
   

2. Configure Genesis

   Edit ~/.evmd/config/genesis.json to set:

   • Token denomination
   • Token pairs
   • Precompiles
   • Access control permissions
3. Configure app.toml

   Edit ~/.evmd/config/app.toml to set:

   • EVM Chain ID
   • JSON-RPC settings
   • API endpoints
4. Start Your Chain

   evmd start
   

For detailed configuration instructions, see Chain Configuration Parameters.

Connect MetaMask

Once your chain is running, connect a wallet for testing:

1. Import Test Account

   Add a new wallet in MetaMask using this test seed phrase:

   gesture inject test cycle original hollow east ridge hen combine
   junk child bacon zero hope comfort vacuum milk pitch cage oppose
   unhappy lunar seat
   

   This is a well-known test seed phrase. Never use it with real funds. For local development and testing only.

2. Add Custom Network

   Configure MetaMask with these settings:

   Setting	Value
   Network Name	Cosmos EVM Local
   RPC URL	http://localhost:8545
   Chain ID	262144
   Currency Symbol	ATOM
   Block Explorer URL	(leave empty)

3. Verify Connection

   After adding the network:

   • Switch to “Cosmos EVM Local” in MetaMask
   • You should see your account balance
   • You can now send transactions and interact with contracts

Key Concepts

Precompiles

Precompiles are native Cosmos SDK functionality exposed as EVM contracts. The evmd reference implementation enables all 9 precompiles by default:

• P256 (0x0100) - Cryptographic operations
• Bech32 (0x0400) - Address conversion
• Staking (0x0800) - Validator operations
• Distribution (0x0801) - Reward distribution
• ICS20 (0x0802) - IBC transfers
• Vesting (0x0803) - Vesting accounts
• Bank (0x0804) - Token transfers
• Governance (0x0805) - On-chain voting
• Slashing (0x0806) - Validator slashing

Learn more in the Precompiles Overview.

Token Pairs

The evmd implementation includes a default token pair that maps the native denomination (aatom) to an ERC20 contract (WEVMOS). This allows the native token to be used in EVM contracts.

18-Decimal Tokens

The evmd uses 18-decimal precision for direct EVM compatibility:

• Base denom: aatom (atto-atom)
• Display denom: atom
• Exponent: 18 (1 atom = 10^18 aatom)

This provides 1:1 mapping with Ethereum’s wei system without requiring additional modules.

Next Steps

Configuration Parameters

Detailed guide to all configuration options

Precompiles

Learn about available precompiled contracts

VM Module

EVM module documentation and parameters

ERC20 Module

Token pair management and configuration

---

For additional support, visit the Cosmos EVM GitHub repository.