Skip to main content
ibc-go supports golang semantic versioning and therefore all imports must be updated on major version releases. This guide is for chains upgrading directly from ibc-go v10 to ibc-go v11.1. It includes the changes from the ibc-go v11.0 migration and the Packet Forward Middleware changes introduced in ibc-go v11.1. The following changes from v10 to v11 are relevant to this upgrade:
  • Chains will need to remove the ParamSubspace arg from all calls to Keeper constructors
  app.IBCKeeper = ibckeeper.NewKeeper(
    appCodec,
    runtime.NewKVStoreService(keys[ibcexported.StoreKey]),
-   app.GetSubspace(ibcexported.ModuleName),
    app.UpgradeKeeper,
    authtypes.NewModuleAddress(govtypes.ModuleName).String(),
  )
The transfer module, the packet forward middleware, and the rate limiting middleware support custom address codecs. This feature is primarily added to support Cosmos EVM for IBC transfers. In a standard Cosmos SDK app, they are wired as follows: 
  app.TransferKeeper = ibctransferkeeper.NewKeeper(
    appCodec,
+    app.AccountKeeper.AddressCodec(),
    runtime.NewKVStoreService(keys[ibctransfertypes.StoreKey]),
    app.IBCKeeper.ChannelKeeper,
    app.MsgServiceRouter(),
    app.AccountKeeper, app.BankKeeper,
    authtypes.NewModuleAddress(govtypes.ModuleName).String(),
  )

  app.RateLimitKeeper = ratelimitkeeper.NewKeeper(
    appCodec,
+    app.AccountKeeper.AddressCodec(),
    runtime.NewKVStoreService(keys[ratelimittypes.StoreKey]),
    app.IBCKeeper.ChannelKeeper,
    app.IBCKeeper.ClientKeeper,
    app.BankKeeper,
    authtypes.NewModuleAddress(govtypes.ModuleName).String()
  )

  app.PFMKeeper = packetforwardkeeper.NewKeeper(
    appCodec,
+    app.AccountKeeper.AddressCodec(),
    runtime.NewKVStoreService(keys[packetforwardtypes.StoreKey]),
    app.TransferKeeper,
    app.IBCKeeper.ChannelKeeper,
    app.BankKeeper,
    authtypes.NewModuleAddress(govtypes.ModuleName).String()
  )

​
ICS27-GMP

ICS27 General Message Passing (GMP) has been added as a supported IBC application of ibc-go. It has no parameters.

​
Add StoreUpgrades for ICS27-GMP module

If ICS27-GMP is being added to an existing chain, you must manually add store upgrades for the new GMP module and configure the store loader to apply those upgrades in app.go: 
if upgradeInfo.Name == "v11_1" && !app.UpgradeKeeper.IsSkipHeight(upgradeInfo.Height) {
  storeUpgrades := store.StoreUpgrades{
    Added: []string{gmptypes.StoreKey},
  }

  app.SetStoreLoader(upgradetypes.UpgradeStoreLoader(upgradeInfo.Height, &storeUpgrades))
}
This ensures that the new module’s stores are added to the multistore before the migrations begin. If a chain does not integrate ICS27-GMP, it does not need to add the GMP key to the Added field.

​
Packet Forward Middleware (New in v11.1)

Packet Forward Middleware (PFM) has been moved from cosmos/ibc-apps to ibc-go in this release. PFM is now available under modules/apps/packet-forward-middleware. Your migration path depends on whether your chain already uses PFM from ibc-apps.

​
If your chain already uses PFM from ibc-apps

Replace all ibc-apps PFM imports with the new ibc-go imports and review the integration instructions. If your chain already has a PFM store from a previous upgrade, do not add packetforwardtypes.StoreKey as a new store in this upgrade. The ibc-go PFM module intentionally preserves the original module name and store key, including the packetfowardmiddleware spelling, for compatibility with the legacy implementation. The PFM module includes in-place migrations for existing PFM state. Before upgrading, ensure there are no non-refundable in-flight packets. The v3-to-v4 PFM migration removes the deprecated nonrefundable field from in-flight packet state and aborts if any stored in-flight packet has nonrefundable=true.

​
If your chain is adding PFM for the first time

First follow the integration instructions. If PFM is being added to an existing chain, you must manually add store upgrades for the new PFM module and configure the store loader to apply those upgrades in app.go. If your upgrade also introduces ICS27-GMP, include both store keys: 
if upgradeInfo.Name == "v11_1" && !app.UpgradeKeeper.IsSkipHeight(upgradeInfo.Height) {
  storeUpgrades := store.StoreUpgrades{
    Added: []string{gmptypes.StoreKey, packetforwardtypes.StoreKey},
  }

  app.SetStoreLoader(upgradetypes.UpgradeStoreLoader(upgradeInfo.Height, &storeUpgrades))
}
This ensures that the new module’s stores are added to the multistore before the migrations begin. If your chain already added the ICS27-GMP store key in a previous upgrade, do not add gmptypes.StoreKey again. If your chain does not integrate PFM, it does not need to add the PFM key to the Added field.