Skip to main content

​
Example Cosmos EVM Chain

The evmd directory in the Cosmos EVM repository contains an example chain that demonstrates the integration of Cosmos EVM modules. This reference implementation is based on the simapp implementation from the Cosmos SDK repository, which provides a simplified yet complete blockchain foundation.
This chain implementation serves two primary purposes:
  1. Demonstration: Shows how to integrate Cosmos EVM modules into a blockchain
  2. Testing Foundation: Provides a working chain for development and testing
You can use evmd as the starting point for building your own custom chain.

​
Why Cosmos-EVM?

In addition to being a standalone module, the Cosmos/EVM project repository includes evmd, a complete working blockchain pre-wired with the EVM module and a few supporting modules. Because this example is actively developed and maintained alongside the module itself and serves as the canonical reference implementation, it is the perfect starting point to modify and customize into your own EVM-compatible chain. One of the largest benefits is the simplicity and time saved. Rather than researching and going through the trial and error process of assembling components individually and figuring out what works, simply fork evmd and customize it to your needs. This approach lets engineers focus on what makes your chain unique rather than debugging basic integration issues.

​
Prerequisites

You’ll need a standard Go development environment:
  • Go 1.23.8+ - Installation guide
  • Git - For repository management
  • Make - For build commands
  • GCC/Build Tools - Required for CGo compilation
If you’re new to Go development, ensure your $GOPATH/bin is in your system PATH. Most package managers (Homebrew, apt, pacman) handle this automatically.

​
Building Your Custom Chain

The evmd implementation serves as the foundation for building your own custom blockchain. To create your chain:
1

Fork the Repository

Start by forking the Cosmos EVM repository:
git clone https://github.com/cosmos/evm.git
cd evm
2

Rename and Rebrand

Rename the evmd directory and update all references:
# Rename directory
mv evmd yourchain

# Update imports and binary name
find . -type f -name "*.go" -exec sed -i 's/evmd/yourchain/g' {} \;
Update go.mod to reflect your repository path.
3

Customize Configuration

Modify the default configuration in your chain:
  • Chain IDs: Update Cosmos chain ID and EVM chain ID
  • Bech32 Prefix: Set your address prefix in evmd/config/config.go
  • Token Denomination: Configure in genesis
  • Precompiles: Enable only the precompiles you need
  • Modules: Add or remove modules based on requirements
4

Test Locally

Use the local node script to test your changes:
./local_node.sh -y
Verify that:
  • The chain starts successfully
  • JSON-RPC is accessible
  • Wallets can connect
  • Transactions work as expected
5

Deploy to Testnet

Once testing is complete, prepare for testnet deployment:
  • Set up validator infrastructure
  • Configure persistent peers
  • Coordinate genesis with validators
  • Launch the network

​
Default Configuration

The example chain (evmd) comes with the following default configuration:
OptionValueDescription
BinaryevmdThe compiled chain binary name
Chain IDcosmos_262144-1Default Cosmos chain ID (format: name_evmChainID-version)
EVM Chain ID262144EVM chain ID for transaction replay protection
Custom Opcodes-No custom opcodes by default
Token Pairs1 (native token)Default ERC20 token pair for the native denomination
DenominationatestNative token denomination (18 decimals, atto-prefix)
EVM PermissioningPermissionlessAnyone can deploy and call contracts
Enabled PrecompilesAllAll nine static precompiles are enabled by default
The default configuration uses an 18-decimal token (atest) which provides direct EVM compatibility without requiring the precisebank module. This is the recommended setup for new chains.

​
Running The Chain

To run the example chain locally, use the provided local node script from the repository root: 
./local_node.sh [FLAGS]

​
Available Flags

  • -y: Overwrite previous database (fresh start)
  • -n: Do not overwrite previous database (resume from previous state)
  • --no-install: Skip installation of the binary (use existing binary)
  • --remote-debugging: Build a binary suitable for remote debugging
The local_node.sh script handles all the setup including:
  • Building the evmd binary
  • Initializing the chain configuration
  • Setting up genesis parameters
  • Starting the chain with JSON-RPC enabled

​
Example Usage

# Start with a clean slate
./local_node.sh -y

​
Connect to Wallet

Once the chain is running, you can connect using any Ethereum-compatible wallet. The example below uses MetaMask:

​
MetaMask Setup

1

Import Test Account

Use the following seed phrase when adding a new wallet in MetaMask:
gesture inject test cycle original hollow east ridge hen combine
junk child bacon zero hope comfort vacuum milk pitch cage oppose
unhappy lunar seat
Notice: This is a well-known test seed phrase. Never use it for mainnet or with real funds. It’s provided solely for local development and testing purposes.
2

Add Custom Network

  1. Click the Network button on the top left of MetaMask
  2. Click Add custom network at the bottom of the modal
  3. Configure the network with these settings:
SettingValue
Network NameCosmos EVM Local
RPC URLhttp://localhost:8545
Chain ID262144
Currency SymbolTEST
Block Explorer URL(leave empty for local)
Make sure your local chain is running before adding the network. The RPC URL must be accessible from your browser.
3

Verify Connection

After adding the network:
  • Switch to the “Cosmos EVM Local” network in MetaMask
  • You should see your account balance (if the test account was funded in genesis)
  • You can now interact with the chain through MetaMask

​
Key Concepts

Before diving into configuration, familiarize yourself with: Precompiled Contracts - Precompiles bridge EVM smart contracts with Cosmos SDK modules, enabling Solidity contracts to access staking, governance, IBC, and other native functionality. Cosmos SDK Modules - Explore the core modules that provide blockchain functionality:
  • Bank - Token transfers and balances
  • Staking - Validator delegation and rewards
  • Governance - On-chain voting and proposals
  • Slashing - Validator penalty enforcement
  • Distribution - Fee and reward distribution

​
Understanding the Stack

Before diving into configuration, it’s helpful to understand what you’re building with:
  • Cosmos SDK Modules - Core blockchain functionality including staking, governance, and token management
  • Precompiles - Smart contract interfaces that bridge EVM and Cosmos SDK capabilities
  • Security & Audits - Third-party security assessments of the codebase
These guides are designed to be followed in order, taking you from an empty repository to a running blockchain network. For a comprehensive reference of all commands and configuration options, see the Configuration Reference.

​
Advanced Configuration

For specialized customization beyond the core configuration:

VM Module

EVM execution and parameter configuration

Precompiles Overview

Available precompiled contracts and integration
For additional support and community resources, visit the Cosmos EVM GitHub repository or join the Cosmos developer community.
⌘I