Migration: v0.3.0 to v0.4.0 - Cosmos Documentation

Process Overview

Create an upgrade branch and freeze schema-affecting changes
Export a pre-upgrade state and archive node configs
Bump cosmos/evm to v0.4.0 and align Cosmos SDK/IBC/CometBFT constraints
Rewire keepers and AppModule (imports, constructors, RegisterServices)
Add client context field and SetClientCtx method
Add pending transaction listener support
Migrate ERC20 precompiles if you have existing token pairs (see [this section]./(erc20-precompiles-migration))
Audit and migrate EVM & FeeMarket params (EIP-1559 knobs, denom/decimals)
Implement store/params migrations in your UpgradeHandler

Prep

Create a branch: git switch -c upgrade/evm-v0.4
Ensure a clean build + tests green pre-upgrade
Snapshot your current params/genesis for comparison later

git switch -c upgrade/evm-v0.4
go test ./...
evmd export > pre-upgrade-genesis.json

Dependency bumps

Pin EVM and tidy

Bump the cosmos/evm dependency in go.mod:

- github.com/cosmos/evm v0.3.1
+ github.com/cosmos/evm v0.4.0

Transitive bumps

Check for minor dependency bumps (e.g., google.golang.org/protobuf, github.com/gofrs/flock, github.com/consensys/gnark-crypto):

go mod tidy

Resolve any version conflicts here before moving on.

App constructor return type & CLI command wiring

Update your app’s newApp to return an evmserver.Application rather than servertypes.Application, and CLI commands that still expect an SDK app creator require a wrapper.

Change the return type

// cmd/myapp/cmd/root.go
import (
    evmserver "github.com/cosmos/evm/server"
)

func (a appCreator) newApp(
    l log.Logger,
    db dbm.DB,
    traceStore io.Writer,
    appOpts servertypes.AppOptions,
) evmserver.Application { // Changed from servertypes.Application
    // ...
}

Provide a wrapper for commands that expect the SDK type

Create a thin wrapper and use it for pruning.Cmd and snapshot.Cmd:

// cmd/myapp/cmd/root.go
sdkAppCreatorWrapper := func(l log.Logger, d dbm.DB, w io.Writer, ao servertypes.AppOptions) servertypes.Application {
    return ac.newApp(l, d, w, ao)
}

rootCmd.AddCommand(
    pruning.Cmd(sdkAppCreatorWrapper, myapp.DefaultNodeHome),
    snapshot.Cmd(sdkAppCreatorWrapper),
)

Add clientCtx and SetClientCtx

Add the clientCtx to your app object:

// app/app.go
import (
    "github.com/cosmos/cosmos-sdk/client"
)

type MyApp struct {
    // ... existing fields
    clientCtx client.Context
}

func (app *MyApp) SetClientCtx(clientCtx client.Context) {
    app.clientCtx = clientCtx
}

Pending-tx listener support

Imports

Import the EVM ante package and geth common:

// app/app.go
import (
    "github.com/cosmos/evm/ante"
    "github.com/ethereum/go-ethereum/common"
)

App state: listeners slice

Add a new field for listeners:

// app/app.go
type MyApp struct {
    // ... existing fields
    pendingTxListeners []ante.PendingTxListener
}

Registration method

Add a public method to register a listener by txHash:

// app/app.go
func (app *MyApp) RegisterPendingTxListener(listener func(common.Hash)) {
    app.pendingTxListeners = append(app.pendingTxListeners, listener)
}

Precompiles: optionals + codec injection

New imports

// app/keepers/precompiles.go
import (
    "cosmossdk.io/core/address"
    addresscodec "github.com/cosmos/cosmos-sdk/codec/address"
    sdk "github.com/cosmos/cosmos-sdk/types"
)

Define Optionals + defaults + functional options

Create a small options container with sane defaults pulled from the app’s bech32 config:

// app/keepers/precompiles.go
type Optionals struct {
    AddressCodec       address.Codec // used by gov/staking
    ValidatorAddrCodec address.Codec // used by slashing
    ConsensusAddrCodec address.Codec // used by slashing
}

func defaultOptionals() Optionals {
    return Optionals{
        AddressCodec:       addresscodec.NewBech32Codec(sdk.GetConfig().GetBech32AccountAddrPrefix()),
        ValidatorAddrCodec: addresscodec.NewBech32Codec(sdk.GetConfig().GetBech32ValidatorAddrPrefix()),
        ConsensusAddrCodec: addresscodec.NewBech32Codec(sdk.GetConfig().GetBech32ConsensusAddrPrefix()),
    }
}

type Option func(*Optionals)

func WithAddressCodec(c address.Codec) Option {
    return func(o *Optionals) { o.AddressCodec = c }
}

func WithValidatorAddrCodec(c address.Codec) Option {
    return func(o *Optionals) { o.ValidatorAddrCodec = c }
}

func WithConsensusAddrCodec(c address.Codec) Option {
    return func(o *Optionals) { o.ConsensusAddrCodec = c }
}

4.3 Update the precompile factory to accept options

// app/keepers/precompiles.go
func NewAvailableStaticPrecompiles(
    ctx context.Context,
    // ... other params
    opts ...Option,
) map[common.Address]vm.PrecompiledContract {
    options := defaultOptionals()
    for _, opt := range opts {
        opt(&options)
    }
    // ... rest of implementation
}

4.4 Modify individual precompile constructors

ICS-20 precompile now needs bankKeeper first:

- ibcTransferPrecompile, err := ics20precompile.NewPrecompile(
-     stakingKeeper,
+ ibcTransferPrecompile, err := ics20precompile.NewPrecompile(
+     bankKeeper,
+     stakingKeeper,
      transferKeeper,
      &channelKeeper,
      // ...

Gov precompile now requires an AddressCodec:

- govPrecompile, err := govprecompile.NewPrecompile(govKeeper, cdc)
+ govPrecompile, err := govprecompile.NewPrecompile(govKeeper, cdc, options.AddressCodec)

ERC20 Precompiles Migration

This migration is required for chains with existing ERC20 token pairsThe storage mechanism for ERC20 precompiles has fundamentally changed in v0.4.0. Without proper migration, your ERC20 tokens will become inaccessible via EVM.

Include this migration with your upgrade if your chain has:

IBC tokens converted to ERC20
Token factory tokens with ERC20 representations
Any existing DynamicPrecompiles or NativePrecompiles in storage

Implementation

For complete migration instructions, see: ERC20 Precompiles Migration Guide Add this to your upgrade handler:

// In your upgrade handler
store := ctx.KVStore(storeKeys[erc20types.StoreKey])
const addressLength = 42

// Migrate dynamic precompiles
if oldData := store.Get([]byte("DynamicPrecompiles")); len(oldData) > 0 {
    for i := 0; i < len(oldData); i += addressLength {
        address := common.HexToAddress(string(oldData[i : i+addressLength]))
        erc20Keeper.SetDynamicPrecompile(ctx, address)
    }
    store.Delete([]byte("DynamicPrecompiles"))
}

// Migrate native precompiles
if oldData := store.Get([]byte("NativePrecompiles")); len(oldData) > 0 {
    for i := 0; i < len(oldData); i += addressLength {
        address := common.HexToAddress(string(oldData[i : i+addressLength]))
        erc20Keeper.SetNativePrecompile(ctx, address)
    }
    store.Delete([]byte("NativePrecompiles"))
}

Verification

Post-upgrade, verify your migration succeeded:

# Check ERC20 balance (should NOT be 0 if tokens existed before)
cast call $TOKEN_ADDRESS "balanceOf(address)" $USER_ADDRESS --rpc-url http://localhost:8545

# Verify precompiles in state
mantrachaind export | jq '.app_state.erc20.dynamic_precompiles'

Build & quick tests

Compile:
go build ./...
Smoke tests (local single-node):
- Start your node; ensure RPC starts cleanly
- Deploy a trivial contract; verify events and logs
- Send a couple 1559 txs and confirm base-fee behavior looks sane
- (Optional) register a pending-tx listener and log hashes as they enter the mempool

Rollout checklist

Package the new binary (and Cosmovisor upgrade folder if you use it)
Confirm all validators build the same commit (no replace lines)
Share an app.toml diff only if you changed defaults; otherwise regenerate the file from the new binary and re-apply customizations
Post-upgrade: monitor mempool/pending tx logs, base-fee progression, and contract events for the first 20-50 blocks

Pitfalls & remedies

Forgot wrapper for CLI commands → pruning/snapshot panic or wrong type:
- Ensure you pass sdkAppCreatorWrapper (not ac.newApp) into those commands
ICS-20 precompile build error:
- You likely didn’t pass bankKeeper first; update the call site
Governance precompile address parsing fails:
- Provide the correct AddressCodec via defaults or WithAddressCodec(...)
Listeners never fire:
- Register with RegisterPendingTxListener during app construction or module init

Minimal code snippets

App listeners

// app/app.go
import (
    "github.com/cosmos/evm/ante"
    "github.com/ethereum/go-ethereum/common"
)

type MyApp struct {
    // ...
    pendingTxListeners []ante.PendingTxListener
}

func (app *MyApp) RegisterPendingTxListener(l func(common.Hash)) {
    app.pendingTxListeners = append(app.pendingTxListeners, l)
}

CLI wrapper

// cmd/myapp/cmd/root.go
sdkAppCreatorWrapper := func(l log.Logger, d dbm.DB, w io.Writer, ao servertypes.AppOptions) servertypes.Application {
    return ac.newApp(l, d, w, ao)
}

rootCmd.AddCommand(
    pruning.Cmd(sdkAppCreatorWrapper, myapp.DefaultNodeHome),
    snapshot.Cmd(sdkAppCreatorWrapper),
)

Precompile options & usage

// app/keepers/precompiles.go
opts := []Option{
    // override defaults only if you use non-standard prefixes/codecs
    WithAddressCodec(myAcctCodec),
    WithValidatorAddrCodec(myValCodec),
    WithConsensusAddrCodec(myConsCodec),
}

pcs := NewAvailableStaticPrecompiles(ctx, /* ... keepers ... */, opts...)

Verify before tagging

go.mod has no replace lines for github.com/cosmos/evm
Node boots with expected RPC namespaces
Contracts deploy/call; events stream; fee market behaves
(If applicable) ICS-20 transfers work and precompiles execute

​Process Overview

​Prep

​Dependency bumps

​Pin EVM and tidy

​Transitive bumps

​App constructor return type & CLI command wiring

​Change the return type

​Provide a wrapper for commands that expect the SDK type

​Add clientCtx and SetClientCtx

​Pending-tx listener support

​Imports

​App state: listeners slice

​Registration method

​Precompiles: optionals + codec injection

​New imports

​Define Optionals + defaults + functional options

​4.3 Update the precompile factory to accept options

​4.4 Modify individual precompile constructors

​ERC20 Precompiles Migration

​Implementation

​Verification

​Build & quick tests

​Rollout checklist

​Pitfalls & remedies

​Minimal code snippets

​Verify before tagging

Process Overview

Prep

Dependency bumps

Pin EVM and tidy

Transitive bumps

App constructor return type & CLI command wiring

Change the return type

Provide a wrapper for commands that expect the SDK type

Add clientCtx and SetClientCtx

Pending-tx listener support

Imports

App state: listeners slice

Registration method

Precompiles: optionals + codec injection

New imports

Define Optionals + defaults + functional options

4.3 Update the precompile factory to accept options

4.4 Modify individual precompile constructors

ERC20 Precompiles Migration

Implementation

Verification

Build & quick tests

Rollout checklist

Pitfalls & remedies

Minimal code snippets

Verify before tagging