Adding EVM to an Existing Chain

概述

本指南介绍了从标准 Cosmos 链平滑迁移到兼容 EVM 的链所需的关键配置要求。

集成过程聚焦两个关键领域：账户派生和 Gas 代币配置。在添加 EVM 模块之前，必须先完成这些设置，以确保与 Ethereum 工具链兼容。如果你的链仍处于创世前阶段，且未来可能接入 Cosmos EVM，我们强烈建议现在就完成第 1 步和第 2a 步，以避免后续进行大规模迁移。

前置条件

在开始集成流程之前，请确保你已具备：

一个正在运行且已启用治理的 Cosmos SDK 链
修改链配置和代码库的权限
了解你的链当前的账户派生配置
了解你的 Gas 代币的小数位配置

这些变更需要通过治理协调完成链升级。

1) 地址派生设置

正确的地址派生对于确保与 Ethereum 钱包、CLI 工具和区块浏览器兼容至关重要。该设置由两个协同工作的组件组成，用于在你的 Cosmos 链上生成兼容 Ethereum 的地址。

将 Coin Type 设为 60

Coin Type 是 BIP44 公钥派生路径的一部分，必须设为 60（Ethereum 标准）才能兼容 EVM。这可确保使用标准 Ethereum 派生路径的钱包能够为你的链正确生成密钥。 在链初始化时进行配置：

// Set the coin type in your SDK config
config := sdk.GetConfig()
config.SetCoinType(60) // Ethereum's coin type
config.Seal()

参考实现： evmd/config/bech32.go

Coin Type 必须在链初始化期间、且在 SDK 配置被密封之前设置。

添加 EthSecp256k1 密钥类型

EthSecp256k1 密钥类型启用 Ethereum 风格的地址派生方式，即使用公钥的后 20 个字节，而不是先进行 RIPEMD-160 哈希再编码。这使得 0x 前缀地址与 Cosmos Bech32 地址编码之间可以互相转换，并且二者都可以还原回公钥字节。 参考实现：

Keyring 选项：cmd/evmd/cmd/root.go
app.go 中的编码配置：evmd/app.go
编码配置辅助函数：encoding/config.go

为什么这很重要

Coin Type 60 与 EthSecp256k1 密钥类型的组合可确保：

统一的账户访问：同一私钥或助记词在 Cosmos 侧和 EVM 侧派生出相同地址，因此用户会看到相同余额，并可通过 MetaMask 或 Cosmos 钱包访问同一笔资金
钱包兼容性：MetaMask、Ledger 及其他 Ethereum 钱包可无缝工作
地址转换：用户可以在同一底层账户的 0x 与 Bech32 地址格式之间轻松转换
工具链支持：Ethereum 开发工具（Hardhat、Foundry、Remix）能够正确运行

关键： 如果你在添加 EVM 模块之前没有完成此设置，那么私钥在 EVM 侧派生出的地址将与 Cosmos 侧完全不同。这会让用户现有的 Cosmos 侧余额和状态极难与其 EVM 账户关联起来，可能需要复杂的迁移工具，或者迫使用户在彼此割裂的账户之间手动转移资金。

2) Gas 代币小数位

Ethereum 的 Gas 代币使用 18 位小数（1 wei = 10^-18 ETH），为了兼容 EVM，强烈建议保持这一标准。小数位配置会影响所有 Ethereum 工具中 Gas 价格的计算与显示方式。

强烈建议：使用 18 位小数代币如果你的链仍处于创世前阶段，或计划在未来加入 EVM 支持，请从一开始就将 Gas 代币配置为 18 位小数。非 18 位小数代币需要额外的模块依赖（具体是 x/precisebank 模块），并会增加管理分数余额的复杂性。对于那些无法迁移代币小数位、但需要在创世后接入 EVM 的链，这种变通方案是可用的，但它会带来额外负担，应尽量避免。

方案 A：18 位小数 Gas 代币（推荐）

如果你的链已经使用 18 位小数代币作为 Gas 代币，则无需额外配置。EVM 模块可以原生兼容你现有的代币。 创世配置：

{
  "app_state": {
    "bank": {
      "denom_metadata": [
        {
          "base": "atoken",
          "display": "token",
          "name": "Token",
          "symbol": "TKN",
          "denom_units": [
            {
              "denom": "atoken",
              "exponent": 0
            },
            {
              "denom": "token",
              "exponent": 18
            }
          ]
        }
      ]
    }
  }
}

方案 B：使用 PreciseBank 的非 18 位小数代币

对于使用非 18 位小数 Gas 代币的链（例如 6 位小数的 uatom），请使用 x/precisebank 模块，在保持 Cosmos 交易原生面额不变的同时，于 EVM 层追踪分数余额。 precisebank 模块封装了标准 bank 模块，并将分数余额单独存储。例如，如果有人通过 EVM 交易转账 0.5 × 10^-6 个代币（小于 1 个 uatom），即使基础面额无法表示该数量，precisebank 仍会追踪这部分分数金额。

小数位配置总结

代币类型	配置	所需模块
18 位小数原生代币	标准设置	无
非 18 位小数代币	ExtendedDenomOptions + precisebank	`x/precisebank`

3) 升级处理器实现

完成地址派生和 Gas 代币小数位配置后，实现一个升级处理器，将 EVM 模块添加到正在运行的链中。

有关如何实现和测试升级处理器的更多细节，请参考升级处理器文档。

4) 测试与验证

在主网上发起升级提案之前，请先在测试网或本地网络上进行充分测试。

升级前检查清单

[] Coin Type 已设为 60
[] 已将 EthSecp256k1 添加到 keyring 和签名选项
[] 已确定 Gas 代币小数位配置（18 位小数原生代币或 x/precisebank）
[] 升级处理器已实现并测试

升级后验证

升级执行后：

验证地址派生：

# Create a new key with eth_secp256k1
<binary> keys add test-key --keyring-backend test --algo eth_secp256k1

# Verify the address format matches Ethereum expectations

测试 EVM 交易：

# Send a simple value transfer using Forge's cast
cast send <RECIPIENT_ADDRESS> \
  --value 1ether \
  --rpc-url http://localhost:8545 \
  --private-key <YOUR_PRIVATE_KEY>

# Verify transaction succeeded and check the receipt
cast receipt <TX_HASH> --rpc-url http://localhost:8545

# Check balance to confirm transfer (value shown in wei)
cast balance <RECIPIENT_ADDRESS> --rpc-url http://localhost:8545

这可以确认：

EVM 交易被正确处理
Gas 按 wei（18 位小数）计算
Ethereum 工具链（Forge）能够与你的链无缝协作

检查模块参数：

<binary> query vm params
<binary> query feemarket params

关键注意事项

链停机风险

不正确的配置可能导致共识失败。在提交治理升级提案之前，务必先在能够映射主网状态的测试网上完整测试整个升级流程。

账户迁移

在添加 EVM 模块后，你链上的现有账户仍可继续使用。不过：

使用 secp256k1 密钥的旧账户仍然可以与 Cosmos SDK 模块交互
新的 EVM 兼容账户应使用 eth_secp256k1 密钥创建

如果跳过了第 1 步（地址派生设置），用户将助记词导入 Ethereum 钱包后，看到的地址会与其 Cosmos 账户完全不同，且看不到任何余额或状态。这就是为什么在添加 EVM 模块之前必须正确配置地址派生。

现有余额

升级期间会保留代币余额：

对于 18 位小数代币：无需迁移，只需确保正确设置 bank metadata。
对于非 18 位小数代币：Cosmos SDK 中的现有余额保持不变，但 EVM 交互会通过 precisebank 封装层处理分数精度

其他资源

Overview

This guide covers the essential configuration requirements to ensure a smooth transition from a standard Cosmos chain to an EVM-compatible chain.

The integration process focuses on two key areas: account derivation and gas token configuration. These must be set before adding the EVM module to ensure compatibility with Ethereum tooling. If you’re pre-genesis and may add Cosmos EVM in the future, we strongly recommend completing steps 1 and 2a now to avoid major migrations later.

Prerequisites

Before beginning the integration process, ensure you have:

A running Cosmos SDK chain with governance enabled
Access to modify the chain’s configuration and codebase
Understanding of your chain’s current account derivation setup
Knowledge of your gas token’s decimal configuration

These changes require a coordinated chain upgrade via governance.

1) Address Derivation Setup

Proper address derivation is critical for ensuring compatibility with Ethereum wallets, CLI tools, and block explorers. This setup consists of two components that work together to generate Ethereum-compatible addresses on your Cosmos chain.

Set Coin Type to 60

The coin type is part of the BIP44 public key derivation path and must be set to 60 (Ethereum’s standard) for EVM compatibility. This ensures that wallets using standard Ethereum derivation paths can correctly generate keys for your chain. Configure in your chain’s initialization:

// Set the coin type in your SDK config
config := sdk.GetConfig()
config.SetCoinType(60) // Ethereum's coin type
config.Seal()

Reference implementation: evmd/config/bech32.go

The coin type must be set during chain initialization and before the SDK config is sealed.

Add EthSecp256k1 Key Type

The EthSecp256k1 key type enables Ethereum-style address derivation, which uses the last 20 bytes of the public key rather than RIPEMD-160 hashing it before encoding. This makes it possible to convert between 0x prefixed addresses and Cosmos Bech32 address encodings—both of which may be reverted back to the public key bytes. Reference implementations:

Keyring options: cmd/evmd/cmd/root.go
Encoding config in app.go: evmd/app.go
Encoding config helper: encoding/config.go

Why This Matters

The combination of coin type 60 and EthSecp256k1 key type ensures:

Unified Account Access: The same private key/mnemonic derives the same address on both Cosmos and EVM sides, so users see identical balances and can access the same funds through MetaMask or Cosmos wallets
Wallet Compatibility: MetaMask, Ledger, and other Ethereum wallets work seamlessly
Address Conversion: Users can easily convert between 0x and Bech32 address formats for the same underlying account
Tooling Support: Ethereum development tools (Hardhat, Foundry, Remix) function correctly

Critical: If you don’t set this up before adding the EVM module, private keys will derive completely different addresses on the EVM side than on the Cosmos side. This makes it extremely difficult to associate users’ existing Cosmos-side balances and state with their EVM accounts, potentially requiring complex migration tooling or forcing users to manually transfer funds between their disconnected accounts.

2) Gas Token Decimals

Ethereum uses 18 decimals for its gas token (1 wei = 10^-18 ETH), and maintaining this standard is strongly preferred for EVM compatibility. The decimal configuration affects how gas prices are calculated and displayed across all Ethereum tooling.

Strongly Recommended: Use 18-Decimal TokensIf you are pre-genesis or planning to add EVM support in the future, configure your gas token with 18 decimals from the start. Non-18-decimal tokens require additional module dependencies (specifically the x/precisebank module) and introduce complexity in managing fractional balances. This workaround is available for post-genesis chains that cannot migrate their token decimals, but it adds overhead and should be avoided when possible.

Option A: 18-Decimal Gas Token (Preferred)

If your chain already uses an 18-decimal token as the gas token, no additional configuration is needed. The EVM module will work natively with your existing token. Genesis configuration:

{
  "app_state": {
    "bank": {
      "denom_metadata": [
        {
          "base": "atoken",
          "display": "token",
          "name": "Token",
          "symbol": "TKN",
          "denom_units": [
            {
              "denom": "atoken",
              "exponent": 0
            },
            {
              "denom": "token",
              "exponent": 18
            }
          ]
        }
      ]
    }
  }
}

Option B: Non-18-Decimal Token with PreciseBank

For chains with non-18-decimal gas tokens (e.g., 6 decimals like uatom), use the x/precisebank module to track fractional balances at the EVM level while maintaining the native denomination for Cosmos transactions. The precisebank module wraps the standard bank module and stores fractional balances separately. For example, if someone transfers 0.5 × 10^-6 tokens (less than 1 uatom) via an EVM transaction, precisebank tracks this fractional amount even though the base denomination can’t represent it.

Decimal Configuration Summary

Token Type	Configuration	Module Required
18-decimal native token	Standard setup	None
Non-18-decimal token	ExtendedDenomOptions + precisebank	`x/precisebank`

3) Upgrade Handler Implementation

After configuring address derivation and gas token decimals, implement an upgrade handler to add the EVM module to your running chain.

Refer to the upgrade handlers documentation for more details on implementing and testing upgrade handlers.

4) Testing and Validation

Before proposing the upgrade on mainnet, thoroughly test on a testnet or local network.

Pre-Upgrade Checklist

[] Coin type set to 60
[] EthSecp256k1 added to keyring and signing options
[] Gas token decimal configuration determined (18-decimal native or x/precisebank)
[] Upgrade handler implemented and tested

Post-Upgrade Validation

After the upgrade executes:

Verify address derivation:

# Create a new key with eth_secp256k1
<binary> keys add test-key --keyring-backend test --algo eth_secp256k1

# Verify the address format matches Ethereum expectations

Test EVM transactions:

# Send a simple value transfer using Forge's cast
cast send <RECIPIENT_ADDRESS> \
  --value 1ether \
  --rpc-url http://localhost:8545 \
  --private-key <YOUR_PRIVATE_KEY>

# Verify transaction succeeded and check the receipt
cast receipt <TX_HASH> --rpc-url http://localhost:8545

# Check balance to confirm transfer (value shown in wei)
cast balance <RECIPIENT_ADDRESS> --rpc-url http://localhost:8545

This confirms:

EVM transactions are processed correctly
Gas is calculated in wei (18 decimals)
Ethereum tooling (Forge) works seamlessly with your chain

Check module parameters:

<binary> query vm params
<binary> query feemarket params

Key Considerations

Chain Halt Risk

Improper configuration can cause consensus failures. Always test the complete upgrade process on a testnet that mirrors your mainnet state before proposing the governance upgrade.

Account Migration

Existing accounts on your chain will continue to work after adding the EVM module. However:

Legacy accounts using secp256k1 keys can still interact with Cosmos SDK modules
New EVM-compatible accounts should be created with eth_secp256k1 keys

If Step 1 (address derivation setup) was skipped, users importing their mnemonic into an Ethereum wallet will see a completely different address than their Cosmos account, with no visible balances or state. This is why proper address derivation must be configured before adding the EVM module.

Existing Balances

Token balances are preserved during the upgrade:

For 18-decimal tokens: No migration needed, just ensure bank metadata is set properly.
For non-18-decimal tokens: Existing balances remain unchanged in the Cosmos SDK, but EVM interactions will use the precisebank wrapper for fractional precision

​概述

​前置条件

​1) 地址派生设置

​将 Coin Type 设为 60

​添加 EthSecp256k1 密钥类型

​为什么这很重要

​2) Gas 代币小数位

​方案 A：18 位小数 Gas 代币（推荐）

​方案 B：使用 PreciseBank 的非 18 位小数代币

​小数位配置总结

​3) 升级处理器实现

​4) 测试与验证

​升级前检查清单

​升级后验证

​关键注意事项

​链停机风险

​账户迁移

​现有余额

​其他资源

​Overview

​Prerequisites

​1) Address Derivation Setup

​Set Coin Type to 60

​Add EthSecp256k1 Key Type

​Why This Matters

​2) Gas Token Decimals

​Option A: 18-Decimal Gas Token (Preferred)

​Option B: Non-18-Decimal Token with PreciseBank

​Decimal Configuration Summary

​3) Upgrade Handler Implementation

​4) Testing and Validation

​Pre-Upgrade Checklist

​Post-Upgrade Validation

​Key Considerations

​Chain Halt Risk

​Account Migration

​Existing Balances

​Additional Resources

概述

前置条件

1) 地址派生设置

将 Coin Type 设为 60

添加 EthSecp256k1 密钥类型

为什么这很重要

2) Gas 代币小数位

方案 A：18 位小数 Gas 代币（推荐）

方案 B：使用 PreciseBank 的非 18 位小数代币

小数位配置总结

3) 升级处理器实现

4) 测试与验证

升级前检查清单

升级后验证

关键注意事项

链停机风险

账户迁移

现有余额

其他资源

Overview

Prerequisites

1) Address Derivation Setup

Set Coin Type to 60

Add EthSecp256k1 Key Type

Why This Matters

2) Gas Token Decimals

Option A: 18-Decimal Gas Token (Preferred)

Option B: Non-18-Decimal Token with PreciseBank

Decimal Configuration Summary

3) Upgrade Handler Implementation

4) Testing and Validation

Pre-Upgrade Checklist

Post-Upgrade Validation

Key Considerations

Chain Halt Risk

Account Migration

Existing Balances

Additional Resources