Run an EVM Chain - Cosmos Docs

Cosmos EVM 仓库中的 evmd 目录包含一条示例链，用于演示 Cosmos EVM 模块的集成。该参考实现基于 Cosmos SDK 仓库中的 simapp 实现，提供了一个简化但完整的区块链基础。

前置条件

请确保你已具备以下前置条件：

Go 1.23.8+ - 安装指南
Git - 安装指南
Make - 安装指南
GCC/构建工具 - 安装指南

如果你刚开始进行 Go 开发，请确保你的系统 PATH 中包含 $GOPATH/bin。大多数包管理器（Homebrew、apt、pacman）都会自动处理这一点。详情请参阅 Go 环境设置指南。

构建 `evmd`

evmd 实现可作为构建你自己的自定义区块链的基础。要创建你的链：

Fork 仓库 — 克隆 Cosmos EVM 仓库：

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

运行链 — 运行本地节点脚本以启动链：

./local_node.sh -y

该脚本会在启动前运行 make install，因此完成后 evmd 二进制文件会出现在你的 $GOPATH/bin 中。JSON-RPC 服务器可通过 http://localhost:8545 访问。

evmd status
evmd keys list
evmd query bank balances <address>
evmd --help  # full list of commands

`local_node.sh` 参数

以下是本地节点脚本可用的参数：

./local_node.sh -y   # fresh start (overwrite previous database)
./local_node.sh -n   # resume from previous state
./local_node.sh --no-install # skip rebuild, use the existing binary

连接钱包

链启动后，你可以使用任何兼容 Ethereum 的钱包进行连接。下面的示例使用 MetaMask：

MetaMask 配置

1. 导入测试账户 — 在 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

这是一个广为人知的测试助记词。切勿在主网或真实资金场景中使用它。

2. 添加网络 — 前往 网络 → 添加自定义网络，并输入：

配置项	值
网络名称	`Cosmos EVM Local`
RPC URL	`http://localhost:8545`
Chain ID	`262144`
货币符号	`TEST`
区块浏览器 URL	（留空）

3. 验证 — 在 MetaMask 中切换到“Cosmos EVM Local”。你应该能看到账户余额，并且现在可以发送交易。 4. 发送测试交易 — 向 0x742d35cc6644c068532fddb11B4C36A58D6D3eAb 发送 1 TEST，以确认端到端交易流程工作正常。

使用 Forge 部署 Solidity 合约

链运行后，你可以使用 Forge 部署 Solidity 合约。如果尚未安装，可通过 curl -L https://foundry.paradigm.xyz | bash && foundryup 进行安装。

创建合约 — 将以下内容保存为 Counter.sol：

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract Counter {
    uint256 public count;
    function increment() public { count++; }
}

部署合约 — 使用 dev0 测试账户私钥进行部署：

forge create Counter.sol:Counter \
  --rpc-url http://localhost:8545 \
  --private-key 0x88cbead91aee890d27bf06e003ade3d4e952427e88f88d31d61d3ef5e5d54305 \
  --broadcast

这个私钥仅用于本地开发。切勿将其用于真实资金。

与合约交互 — 读取当前计数，发送一笔交易将其加一，然后再次读取以确认状态变化：

# Read current count (returns 0)
cast call <deployed-address> "count()(uint256)" --rpc-url http://localhost:8545

# Increment the counter
cast send <deployed-address> "increment()" \
  --rpc-url http://localhost:8545 \
  --private-key 0x88cbead91aee890d27bf06e003ade3d4e952427e88f88d31d61d3ef5e5d54305

# Read again (returns 1)
cast call <deployed-address> "count()(uint256)" --rpc-url http://localhost:8545

配置

基础链配置

以下是 evmd 链的一些基础配置项示例。

配置项	默认值	修改方式	参考
Cosmos Chain ID	`cosmos_262144-1`	在节点启动时传入 `--chain-id`	—
EVM Chain ID	`262144`	在节点启动时传入 `--evm-chain-id`	`x/vm/types/params.go`
Bech32 前缀	`cosmos`	修改 `Bech32Prefix` 常量	`evmd/config/bech32.go`
代币面额	`aatom`	更新 `ExampleAttoDenom`，其被 `NewMintGenesisState()` 使用	`testutil/constants/constants.go`
EVM 权限控制	无许可	在 `DefaultAccessControl` 中设置 `AccessType`	`x/vm/types/params.go`
预编译合约	全部（启用 9 个）	在 `NewEVMGenesisState()` 中替换 `AvailableStaticPrecompiles`	`evmd/genesis.go`
模块	标准 SDK 集合	注册模块，设置 pre-begin-、begin- 和 endblocker、创世模块顺序以及 keeper 初始化	`evmd/app.go`
二进制名称	`evmd`	重命名目录并运行 `find . -type f -name "*.go" -exec sed -i 's/evmd/yourchain/g' {} \;`，然后更新 `go.mod`	—

高级配置

evmd 开箱即用，并提供了合理的默认值。以下是针对需要进一步定制的链的可选配置。

配置项	说明	参考
内存池	自定义交易优先级、nonce 间隙处理、池大小限制	Mempool Configuration
费用市场	禁用基础费、设置最小 gas price、调整基础费调节速率	Fee Market Module
EVM 访问控制	将合约部署/调用限制为白名单地址	VM Module
JSON-RPC	启用/禁用命名空间、设置资源上限、配置 WebSocket 来源	Node Configuration
预部署合约	在创世时部署 Create2、Multicall3、Permit2、Safe	Predeployed Contracts
预编译合约	启用内置预编译合约或添加自定义预编译合约	Precompile Configuration

如需更多支持和社区资源，请访问 Cosmos EVM GitHub 仓库或加入 Cosmos 开发者社区。

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.

Prerequisites

Make sure you have the following prerequisites:

Go 1.23.8+ - Installation guide
Git - Installation guide
Make - Installation guide
GCC/Build Tools - Installation guide

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. See the Go environment setup guide for details.

Building `evmd`

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

Fork the repository — Clone the Cosmos EVM repository:

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

Run the chain — Run the local node script to start the chain:

./local_node.sh -y

The script runs make install before starting, so the evmd binary will be available in your $GOPATH/bin once it completes. The JSON-RPC server will be available at http://localhost:8545.

evmd status
evmd keys list
evmd query bank balances <address>
evmd --help  # full list of commands

`local_node.sh` Flags

The following are the available flags for the local node script:

./local_node.sh -y   # fresh start (overwrite previous database)
./local_node.sh -n   # resume from previous state
./local_node.sh --no-install # skip rebuild, use the existing binary

Connect a Wallet

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

MetaMask Setup

1. Import the test account — Add a new wallet in MetaMask using this 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 for mainnet or with real funds.

2. Add the network — Go to Networks → Add custom network and enter:

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

3. Verify — Switch to “Cosmos EVM Local” in MetaMask. You should see your account balance and can now send transactions. 4. Send a test transaction — Send 1 TEST to 0x742d35cc6644c068532fddb11B4C36A58D6D3eAb to confirm end-to-end transaction flow is working.

Deploy a Solidity Contract with Forge

With the chain running, you can deploy Solidity contracts using Forge. Install it with curl -L https://foundry.paradigm.xyz | bash && foundryup if you haven’t already.

Create a contract — Save the following as Counter.sol:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract Counter {
    uint256 public count;
    function increment() public { count++; }
}

Deploy it — Use the dev0 test account private key to deploy:

forge create Counter.sol:Counter \
  --rpc-url http://localhost:8545 \
  --private-key 0x88cbead91aee890d27bf06e003ade3d4e952427e88f88d31d61d3ef5e5d54305 \
  --broadcast

This private key is for local development only. Never use it with real funds.

Interact with the contract — Read the current count, send a transaction to increment it, then read again to confirm the state change:

# Read current count (returns 0)
cast call <deployed-address> "count()(uint256)" --rpc-url http://localhost:8545

# Increment the counter
cast send <deployed-address> "increment()" \
  --rpc-url http://localhost:8545 \
  --private-key 0x88cbead91aee890d27bf06e003ade3d4e952427e88f88d31d61d3ef5e5d54305

# Read again (returns 1)
cast call <deployed-address> "count()(uint256)" --rpc-url http://localhost:8545

Configuration

Basic Chain Configuration

The following are some examples of basic configuration options for the evmd chain.

Setting	Default	How to change	Reference
Cosmos Chain ID	`cosmos_262144-1`	Pass `--chain-id` at node start	—
EVM Chain ID	`262144`	Pass `--evm-chain-id` at node start	`x/vm/types/params.go`
Bech32 Prefix	`cosmos`	Change `Bech32Prefix` constant	`evmd/config/bech32.go`
Token Denomination	`aatom`	Update `ExampleAttoDenom`, used by `NewMintGenesisState()`	`testutil/constants/constants.go`
EVM Permissioning	Permissionless	Set `AccessType` in `DefaultAccessControl`	`x/vm/types/params.go`
Precompiles	All (9 enabled)	Replace `AvailableStaticPrecompiles` in `NewEVMGenesisState()`	`evmd/genesis.go`
Modules	Standard SDK set	Register, set the pre-begin-, begin-, and endblockers, genesis module order, and keeper initialization	`evmd/app.go`
Binary name	`evmd`	Rename directory and run `find . -type f -name "*.go" -exec sed -i 's/evmd/yourchain/g' {} \;`, then update `go.mod`	—

Advanced Configuration

evmd works out of the box with sensible defaults. The following are optional configurations for chains that need to go further.

Configuration	Description	Reference
Mempool	Custom transaction prioritization, nonce gap handling, pool size limits	Mempool Configuration
Fee Market	Disable base fee, set min gas price, tune base fee adjustment rate	Fee Market Module
EVM Access Control	Restrict contract deployment/calls to whitelisted addresses	VM Module
JSON-RPC	Enable/disable namespaces, set resource caps, configure WebSocket origins	Node Configuration
Predeployed Contracts	Deploy Create2, Multicall3, Permit2, Safe at genesis	Predeployed Contracts
Precompiles	Enable built-in precompiles or add custom ones	Precompile Configuration

For additional support and community resources, visit the Cosmos EVM GitHub repository or join the Cosmos developer community.

​前置条件

​构建 evmd

​local_node.sh 参数

​连接钱包

​MetaMask 配置

​使用 Forge 部署 Solidity 合约

​配置

​基础链配置

​高级配置

​Prerequisites

​Building evmd

​local_node.sh Flags

​Connect a Wallet

​MetaMask Setup

​Deploy a Solidity Contract with Forge

​Configuration

​Basic Chain Configuration

​Advanced Configuration

前置条件

构建 `evmd`

`local_node.sh` 参数

连接钱包

MetaMask 配置

使用 Forge 部署 Solidity 合约

配置

基础链配置

高级配置

Prerequisites

Building `evmd`

`local_node.sh` Flags

Connect a Wallet

MetaMask Setup

Deploy a Solidity Contract with Forge

Configuration

Basic Chain Configuration

Advanced Configuration