Migration: v0.6.0 to v0.7.0

Documentation Index

Fetch the complete documentation index at: https://docs.cosmos.network/llms.txt

Use this file to discover all available pages before exploring further.

• Krakatoa mempool (#1030, #1053, #1112) — moves the EVM mempool out of CometBFT and into the application layer. The chain gets full control over CheckTx / RecheckTx, sudo-rechecking on promote/demote, reapable-list filtering, and pool-level lifecycle hooks. Krakatoa is the only app-side EVM mempool in v0.7; the v0.6 ExperimentalEVMMempool type is gone. If your v0.6 fork wired ExperimentalEVMMempool, migrating to Krakatoa is required — see Step 5a. If your v0.6 fork ran on CometBFT’s stock mempool, Krakatoa is optional and you can stay on stock CometBFT.
• BlockSTM parallel execution (#589, #1082, #1132) — parallel state-transition function under a software-transactional-memory scheduler, with per-tx object stores for bloom / log indexing / gas accounting and an incarnation cache for signature/auth verification. Includes virtual fee collection (EndBlock fee settlement via per-tx bank object store, 18-decimal chains only) — virtual fees are bundled with BlockSTM, not a standalone feature. Chains that don’t wire the STM runner keep sequential execution.

• ICS-02 client-router precompile (#768) — Solidity contracts can now manage IBC light clients.
• Authority params (#1130) — x/vm, x/erc20, x/feemarket MsgServer handlers consult AuthorityParams from the consensus module before falling back to per-module gov authority.
• OpenTelemetry tracing (#871, #863) — spans across x/vm and the JSON-RPC layer.
• JSON-RPC filter lifecycle overhaul (#1008) — idle-timeout reclamation replacing the old global filter cap.

• Krakatoa overview
• Krakatoa configuration
• BlockSTM and parallel execution

​

Table of contents

• Step 1: Bump dependencies
• Step 1.5: Migrate import paths
• Step 2: Update store keys in app.go
• Step 3: Update EVMD struct fields
• Step 4: Update NewExampleApp and keeper constructors in app.go
• Step 6: Drop x/precisebank (18-decimal chains)
• Step 7: Update custom code
• Step 8: Coordinate the upgrade
• Step 9: Verify

• Step 5a: Krakatoa application-layer mempool

• Step 5b: BlockSTM parallel execution and virtual fee collection

• Step 5c: Optimistic execution

​

Step 1: Bump dependencies

go get github.com/cosmos/evm@v0.7.0
go mod tidy

Audit every go.mod in your tree. Forks with nested submodules (e.g., a separate tests/systemtests/go.mod) need the dependency bumps applied independently and go mod tidy run separately in each — root-only bumps leave the nested modules with stale cosmossdk.io/log, cosmossdk.io/store resolutions that fail to compile.

replace github.com/ethereum/go-ethereum => github.com/cosmos/go-ethereum v1.17.2-cosmos-0

​

Step 1.5: Migrate import paths

​

Step 2: Update store keys in app.go

  keys := storetypes.NewKVStoreKeys(/* ... */)
- tkeys := storetypes.NewTransientStoreKeys(evmtypes.TransientKey, feemarkettypes.TransientKey)
+ oKeys := storetypes.NewObjectStoreKeys(evmtypes.ObjectKey)
+
+ var nonTransientKeys []storetypes.StoreKey
+ for _, k := range keys {
+     nonTransientKeys = append(nonTransientKeys, k)
+ }
+ for _, k := range oKeys {
+     nonTransientKeys = append(nonTransientKeys, k)
+ }

- app.MountTransientStores(tkeys)
+ app.MountObjectStores(oKeys)

Step 5 (parallel path) extends oKeys with banktypes.ObjectStoreKey and wires it into the bank keeper. Skip if you’re not adopting virtual fee collection.

​

Step 3: Update EVMD struct fields

  type EVMD struct {
      // ...
-     keys    map[string]*storetypes.KVStoreKey
-     tkeys   map[string]*storetypes.TransientStoreKey
-     memKeys map[string]*storetypes.MemoryStoreKey
+     keys  map[string]*storetypes.KVStoreKey
+     oKeys map[string]*storetypes.ObjectStoreKey

-     clientCtx client.Context
-
      // ...
-     TransferKeeper    transferkeeper.Keeper
+     TransferKeeper    *transferkeeper.Keeper

-     EVMMempool        *evmmempool.ExperimentalEVMMempool
+     EVMMempool        sdkmempool.ExtMempool
-
-     PreciseBankKeeper precisebankkeeper.Keeper
  }

  func (app *EVMD) Close() error {
      var err error
-     if m, ok := app.GetMempool().(*evmmempool.ExperimentalEVMMempool); ok {
+     if m, ok := app.EVMMempool.(*evmmempool.Mempool); ok && m != nil {
          app.Logger().Info("Shutting down mempool")
          err = m.Close()
      }
      // ...
  }

​

Step 4: Update NewExampleApp and keeper constructors in app.go

​

NewExampleApp signature — drop traceStore

  func NewExampleApp(
      logger log.Logger,
      db dbm.DB,
-     traceStore io.Writer,
      loadLatest bool,
      appOpts servertypes.AppOptions,
      baseAppOptions ...func(*baseapp.BaseApp),
  ) *EVMD {

- bApp.SetCommitMultiStoreTracer(traceStore)

​

feemarketkeeper.NewKeeper — drop transient key

  app.FeeMarketKeeper = feemarketkeeper.NewKeeper(
      appCodec, authtypes.NewModuleAddress(govtypes.ModuleName),
      keys[feemarkettypes.StoreKey],
-     tkeys[feemarkettypes.TransientKey],
  )

​

ibckeeper.NewKeeper — drop capability keeper

  app.IBCKeeper = ibckeeper.NewKeeper(
      appCodec,
      runtime.NewKVStoreService(keys[ibcexported.StoreKey]),
-     nil,
      app.UpgradeKeeper,
      authAddr,
  )

​

govkeeper.NewKeeper — reordered args, new vote-results function

  govKeeper := govkeeper.NewKeeper(
      appCodec,
      runtime.NewKVStoreService(keys[govtypes.StoreKey]),
      app.AccountKeeper,
      app.BankKeeper,
-     app.StakingKeeper,
      app.DistrKeeper,
      app.MsgServiceRouter(),
      govConfig,
      authAddr,
+     govkeeper.NewDefaultCalculateVoteResultsAndVotingPower(app.StakingKeeper),
  )

​

transferkeeper.NewKeeper — pointer return, inline address codec, drop ICS4Wrapper / duplicate ChannelKeeper

  app.TransferKeeper = transferkeeper.NewKeeper(
      appCodec,
+     evmaddress.NewEvmCodec(sdk.GetConfig().GetBech32AccountAddrPrefix()),
      runtime.NewKVStoreService(keys[ibctransfertypes.StoreKey]),
-     nil, // ICS4Wrapper param
-     app.IBCKeeper.ChannelKeeper,
      app.IBCKeeper.ChannelKeeper,
      app.MsgServiceRouter(),
      app.AccountKeeper,
      app.BankKeeper,
      authAddr,
  )
- app.TransferKeeper.SetAddressCodec(evmaddress.NewEvmCodec(sdk.GetConfig().GetBech32AccountAddrPrefix()))

⚠️ The reference evmd instantiates TransferKeeper before EVMKeeper so static precompiles receive a non-nil reference. v0.6 constructs them in the opposite order (EVMKeeper, then Erc20Keeper consuming &app.TransferKeeper, then TransferKeeper). To swap, you’ll also need to move Erc20Keeper so it’s constructed after TransferKeeper — and Erc20Keeper itself now takes the pointer-typed app.TransferKeeper directly, no &. Walk the three keeper constructions as a unit, not individually.

​

IBC callbacks middleware — wrap with setter calls

- transferStack = ibccallbacks.NewIBCMiddleware(transferStack, app.IBCKeeper.ChannelKeeper, app.CallbackKeeper, maxCallbackGas)
+ callbacksMiddleware := ibccallbacks.NewIBCMiddleware(app.CallbackKeeper, maxCallbackGas)
+ callbacksMiddleware.SetICS4Wrapper(app.IBCKeeper.ChannelKeeper)
+ callbacksMiddleware.SetUnderlyingApplication(transferStack)
+ transferStack = callbacksMiddleware

​

evmkeeper.NewKeeper — object store key, store-key slice, BankKeeper replaces PreciseBankKeeper

  app.EVMKeeper = evmkeeper.NewKeeper(
-     appCodec, keys[evmtypes.StoreKey], tkeys[evmtypes.TransientKey], keys,
+     appCodec, keys[evmtypes.StoreKey], oKeys[evmtypes.ObjectKey], nonTransientKeys,
      authtypes.NewModuleAddress(govtypes.ModuleName),
      app.AccountKeeper,
-     app.PreciseBankKeeper,
+     app.BankKeeper,
      app.StakingKeeper,
      app.FeeMarketKeeper,
      &app.ConsensusParamsKeeper,
      &app.Erc20Keeper,
      evmChainID,
      tracer,
  )

​

DefaultStaticPrecompiles — Bank, dereferenced TransferKeeper, ClientKeeper

  precompiletypes.DefaultStaticPrecompiles(
      *app.StakingKeeper,
      app.DistrKeeper,
-     app.PreciseBankKeeper,
+     app.BankKeeper,
      &app.Erc20Keeper,
-     &app.TransferKeeper,
+     app.TransferKeeper,
      app.IBCKeeper.ChannelKeeper,
+     app.IBCKeeper.ClientKeeper,
      app.GovKeeper,
      app.SlashingKeeper,
      appCodec,
  )

​

erc20keeper.NewKeeper — Bank, dereferenced TransferKeeper

  app.Erc20Keeper = erc20keeper.NewKeeper(
      keys[erc20types.StoreKey],
      appCodec,
      authtypes.NewModuleAddress(govtypes.ModuleName),
      app.AccountKeeper,
-     app.PreciseBankKeeper,
+     app.BankKeeper,
      app.EVMKeeper,
      app.StakingKeeper,
-     &app.TransferKeeper,
+     app.TransferKeeper,
  )

​

node.RegisterNodeService — earliest-version callback

  func (app *EVMD) RegisterNodeService(clientCtx client.Context, cfg config.Config) {
-     node.RegisterNodeService(clientCtx, app.GRPCQueryRouter(), cfg)
+     node.RegisterNodeService(clientCtx, app.GRPCQueryRouter(), cfg, func() int64 {
+         return app.CommitMultiStore().EarliestVersion()
+     })
  }

​

Hydrate EVM globals on restart (#1126)

+ ctx := app.NewContextLegacy(true, cmtproto.Header{
+     Height:  app.LastBlockHeight(),
+     ChainID: app.ChainID(),
+ })
+ vmModule.HydrateGlobals(ctx)

- app.ModuleManager = module.NewManager(
-     // ... other modules
-     vm.NewAppModule(app.EVMKeeper, app.AccountKeeper, app.BankKeeper, app.AccountKeeper.AddressCodec()),
-     // ...
- )
+ vmModule := vm.NewAppModule(app.EVMKeeper, app.AccountKeeper, app.BankKeeper, app.AccountKeeper.AddressCodec())
+
+ app.ModuleManager = module.NewManager(
+     // ... other modules
+     vmModule,
+     // ...
+ )

​

Wire the EVM tx runner (#1132)

• Sequential (default) — pass txnrunner.NewDefaultRunner(txDecoder).
• Parallel — pass txnrunner.NewSTMRunner(...) (see Step 5b).

  txConfig := encodingConfig.TxConfig
+ txDecoder := encodingConfig.TxConfig.TxDecoder()

+ vmrunner.SetRunner(bApp, txnrunner.NewDefaultRunner(txDecoder))

​

Removed EVMD methods

• GetTKey, GetMemKey — transient/mem stores no longer exist as separate maps.
• GetAuthzKeeper — the helper was redundant; expose app.AuthzKeeper directly if you need it.
• GetPreciseBankKeeper — module is removed (Step 6).
• SetClientCtx and the clientCtx field — unused.

​

Step 5: Enable Krakatoa and/or BlockSTM

• Krakatoa (5a) is required for forks that already used the v0.6 ExperimentalEVMMempool (the type was removed); optional for forks on CometBFT’s stock mempool.
• BlockSTM with virtual fee collection (5b) is always opt-in. Skip 5b to keep sequential execution.

State-breaking features. Each ships as part of the binary; adopting or dropping any of them requires a coordinated MsgSoftwareUpgrade and a binary swap, the same as any other consensus change.

​

5a. Krakatoa application-layer mempool

• If you wired ExperimentalEVMMempool in v0.6: this step is required. The construction signature changed and the handler set was redesigned; you must migrate or your fork won’t compile.
• If you ran on CometBFT’s stock mempool in v0.6 (no app-side EVM mempool): this step is optional. Adopt Krakatoa to gain app-level CheckTx / RecheckTx control, or skip it and stay on stock CometBFT.

// Setup block (in evmd/mempool.go's configureEVMMempool, all required):
mpConfig        := server.ResolveMempoolConfig(app.GetAnteHandler(), appOpts, logger)
txEncoder       := evmmempool.NewTxEncoder(app.txConfig)
evmRechecker    := evmmempool.NewTxRechecker(mpConfig.AnteHandler, txEncoder)
cosmosRechecker := evmmempool.NewTxRechecker(mpConfig.AnteHandler, txEncoder)
cosmosPoolMaxTx := server.GetCosmosPoolMaxTx(appOpts, logger)
checkTxTimeout  := server.GetMempoolCheckTxTimeout(appOpts, logger)

Ordering: app.SetAnteHandler(...) must run before configureEVMMempool. ResolveMempoolConfig calls app.GetAnteHandler() and stashes the result on mpConfig.AnteHandler, which the recheckers then close over. If the ante handler hasn’t been set yet, GetAnteHandler returns nil and the chain panics on first RecheckTx. There’s no compile-time signal — get the ordering right. evmRechecker and cosmosRechecker must be distinct instances, even though they wrap identical config. They feed different subpools (the EVM eth-tx pool vs. the Cosmos pool) and need independent state for promotion/demotion bookkeeping. Sharing one instance compiles fine but produces silent cross-pool state interference at promote/demote time.

- evmMempool := evmmempool.NewExperimentalEVMMempool(
-     app.CreateQueryContext, logger,
-     app.EVMKeeper, app.FeeMarketKeeper, app.txConfig, app.clientCtx,
-     mempoolConfig, cosmosPoolMaxTx,
- )
- app.EVMMempool = evmMempool
- app.SetMempool(evmMempool)
- checkTxHandler := evmmempool.NewCheckTxHandler(evmMempool)
- app.SetCheckTxHandler(checkTxHandler)
- abciProposalHandler := baseapp.NewDefaultProposalHandler(evmMempool, app)
- abciProposalHandler.SetSignerExtractionAdapter(/* ... */)
- app.SetPrepareProposal(abciProposalHandler.PrepareProposalHandler())
+ mempool := evmmempool.NewMempool(
+     app.CreateQueryContext, logger,
+     app.EVMKeeper, app.FeeMarketKeeper, app.txConfig,
+     evmRechecker, cosmosRechecker, mpConfig, cosmosPoolMaxTx,
+ )
+ app.EVMMempool = mempool
+ app.SetPrepareProposal(baseapp.NewDefaultProposalHandler(mempool, NewNoCheckProposalTxVerifier(app.BaseApp)).PrepareProposalHandler())
+ app.SetInsertTxHandler(mempool.NewInsertTxHandler(app.TxDecode))
+ app.SetReapTxsHandler(mempool.NewReapTxsHandler())
+ app.SetCheckTxHandler(mempool.NewCheckTxHandler(app.TxDecode, checkTxTimeout))
+ app.SetMempool(mempool)

The reference application uses a NewNoCheckProposalTxVerifier at proposal time when verifying the txs in a given proposal. This is a performance optimization since with the Krakatoa mempool, it is a requirement that every tx within the proposal has already been validated, thus this check is redundant. If you choose to adopt this pattern as well copy the reference NewNoCheckProposalTxVerifier and pass this to your PrepareProposalHandler.

⚠️ Set mempool.type = "app" in config.toml. CometBFT v0.39 requires the app-side mempool type whenever the application supplies an EVM mempool. The default is "flood"; Krakatoa errors out at startup if it’s left as the default. This is a one-line patch to each validator’s config.toml (or your fork’s equivalent), applied at the same time as the binary swap. Forks that opt out of Krakatoa (the previous paragraph) don’t need this. Note that by setting mempool.type = "app" in config.toml, there are additional configuration parameters you may want to configure that will affect Krakatoa mempool operations. Please see the CometBFT application mempool documentation for more info.

​

5b. (Optional) BlockSTM parallel execution and virtual fee collection

​

Swap the inner tx runner to BlockSTM

- vmrunner.SetRunner(bApp, txnrunner.NewDefaultRunner(txDecoder))
+ vmrunner.SetRunner(bApp, txnrunner.NewSTMRunner(
+     txDecoder,
+     nonTransientKeys,
+     min(goruntime.GOMAXPROCS(0), goruntime.NumCPU()),
+     true,
+     func(ms storetypes.MultiStore) string {
+         return app.EVMKeeper.GetParams(sdk.NewContext(ms, cmtproto.Header{}, false, log.NewNopLogger())).EvmDenom
+     },
+ ))

​

Virtual fee collection (18-decimal chains only)

- oKeys := storetypes.NewObjectStoreKeys(evmtypes.ObjectKey)
+ oKeys := storetypes.NewObjectStoreKeys(banktypes.ObjectStoreKey, evmtypes.ObjectKey)

+ app.BankKeeper = app.BankKeeper.WithObjStoreKey(oKeys[banktypes.ObjectStoreKey])

  app.EVMKeeper = evmkeeper.NewKeeper(/* ... */).WithStaticPrecompiles(/* ... */)
+ app.EVMKeeper.EnableVirtualFeeCollection()

⚠️ Do not call EnableVirtualFeeCollection() if your gas token is not 18-decimal. x/vm/keeper.DeductFees reads the EVM denom’s bank metadata and panics if the display-denom unit’s exponent is not 18 (x/vm/keeper/fees.go:156). See Step 6. A non-18-decimal chain that still wants BlockSTM has to skip this final piece — but the parallel path’s main throughput win comes from virtual fees, so the practical recommendation is to migrate to 18 decimals first.

​

5c. (Optional) Optimistic execution

  func NewExampleApp(
      logger log.Logger,
      db dbm.DB,
      loadLatest bool,
      appOpts servertypes.AppOptions,
      baseAppOptions ...func(*baseapp.BaseApp),
  ) *EVMD {
      // ... encoding/txDecoder setup ...

+     // enable optimistic execution
+     baseAppOptions = append(
+         baseAppOptions,
+         baseapp.SetOptimisticExecution(),
+     )

      bApp := baseapp.NewBaseApp(
          appName, logger, db, txDecoder,
          baseAppOptions...,
      )

• Determinism is preserved. Speculative execution uses a sandboxed cache; on a mismatch the state is dropped, not committed. The user-visible behavior is identical to non-optimistic execution — only the latency of FinalizeBlock shifts.
• Composes with BlockSTM (5b) and Krakatoa (5a). Optimistic execution runs the speculative block through whichever runner is wired (vmrunner.SetRunner), so you get parallel-on-speculative + parallel-on-final when 5b is also enabled.
• State-breaking. Like 5a and 5b, this is baked into the binary. Adopting or dropping it requires a coordinated MsgSoftwareUpgrade, not a runtime toggle. See Step 8.
• Resource cost. The speculative path uses an extra goroutine and an extra working state cache per height. On memory-tight nodes you may prefer to disable it; the SDK doc linked at the top of this guide covers the trade-offs.

​

Step 6: Drop x/precisebank

Non-18-decimal chains are not fully supported going forward. v0.7.0 still ships precisebank under contrib/x/precisebank, but future EVM releases will not test or maintain it. Either stay on v0.6.x until you can migrate to 18 decimals, or pin cosmos/evm/contrib/x/precisebank and do not enable virtual fee collection (5b).

  type EVMD struct {
      // ... other keepers
-     PreciseBankKeeper precisebankkeeper.Keeper
  }

- // Set up PreciseBank keeper
- app.PreciseBankKeeper = precisebankkeeper.NewKeeper(/* ... */)

  app.ModuleManager = module.NewManager(
      // ... other modules
-     precisebank.NewAppModule(app.PreciseBankKeeper, app.BankKeeper, app.AccountKeeper),
  )

- func (app *EVMD) GetPreciseBankKeeper() *precisebankkeeper.Keeper { /* ... */ }

​

Step 7: Update custom code

​

Custom ante handlers / mempool plugins

​

Custom BankKeeper / BankWrapper implementations

SendCoinsFromModuleToAccountVirtual(
    ctx context.Context, senderModule string,
    recipientAddr sdk.AccAddress, amt sdk.Coins,
) error
SendCoinsFromAccountToModuleVirtual(
    ctx context.Context, senderAddr sdk.AccAddress,
    recipientModule string, amt sdk.Coins,
) error
UncheckedSetBalance(ctx context.Context, addr sdk.AccAddress, amt sdk.Coin) error
LockedCoins(ctx context.Context, addr sdk.AccAddress) sdk.Coins
BlockedAddr(addr sdk.AccAddress) bool

​

Custom indexers / receipt consumers

• Read log.Index and log.TxIndex only after post-execution patching (#1132). Recomputing from raw event order will diverge from canonical receipts.
• Drop any workaround that special-cased the MaxUint64 overflow on transactionIndex — fixed in #1047.
• Don’t assume tx counts in receipt arrays match raw block tx counts. StateDB-error txs are now skipped during receipt conversion (#1107).

​

Forks of precompile abi.json

​

Removed helpers

• Params.GetActiveStaticPrecompilesAddrs() is gone — derive []common.Address yourself if you used it.

​

Mocks of EVMKeeper

​

Step 8: Coordinate the upgrade

• All validators must run the same v0.7 binary post-upgrade. Mixing v0.6 and v0.7 binaries will fork.
• Step 5 (Krakatoa, BlockSTM + virtual fees, optimistic execution) is state-breaking. Each is baked into the binary — adopting or dropping any of them later is another coordinated MsgSoftwareUpgrade, not a runtime toggle.
• There is no on-chain governance flag for these toggles. Switching paths later requires a new binary release and another MsgSoftwareUpgrade.

  // evmd/upgrades.go (or wherever your fork keeps its upgrade name)
- // NOTE: This upgrade defines a reference implementation of what an upgrade
- // could look like when an application is migrating from EVMD version
- // v0.4.0 to v0.5.x
- const UpgradeName = "v0.5.0-to-v0.6.0"
+ // NOTE: This upgrade defines a reference implementation of what an upgrade
+ // could look like when an application is migrating from EVMD version
+ // v0.6.x to v0.7.0
+ const UpgradeName = "v0.6.0-to-v0.7.0"

​

Step 9: Verify

go build ./...
go test ./...

​

Sanity check the upgrade path

make test-system

• Output goes to tests/systemtests/binaries/v0.6/evmd (or wherever your chainupgrade/v6_v7.go reads from).
• Your test-system Make target (or equivalent) depends on it and on the current binary, in that order.
• If your previous release had a build-v05 target chained from test-system, retarget that dependency to the new build-v06 (or whatever you name it).