​
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

  1. Compile: 
    go build ./...
  2. 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