Skip to main content
Version: Next

Migrating from v7 to v8

This guide provides instructions for migrating to version v8.0.0 of ibc-go.

There are four sections based on the four potential user groups of this document:

Note: ibc-go supports golang semantic versioning and therefore all imports must be updated on major version releases.

Chains​

The type of the PortKeeper field of the IBC keeper have been changed to *portkeeper.Keeper:

// Keeper defines each ICS keeper for IBC
type Keeper struct {
  // implements gRPC QueryServer interface
  types.QueryServer

  cdc codec.BinaryCodec

  ClientKeeper     clientkeeper.Keeper
  ConnectionKeeper connectionkeeper.Keeper
  ChannelKeeper    channelkeeper.Keeper
- PortKeeper       portkeeper.Keeper
+ PortKeeper       *portkeeper.Keeper
  Router           *porttypes.Router

  authority string
}

See this PR for the changes required in app.go.

An extra parameter totalEscrowed of type sdk.Coins has been added to transfer module's NewGenesisState function. This parameter specifies the total amount of tokens that are in the module's escrow accounts.

Cosmos SDK v0.50 upgrade​

Version v8.0.0 of ibc-go upgrades to Cosmos SDK v0.50. Please follow the Cosmos SDK v0.50 upgrading guide to account for its API breaking changes.

Authority​

An authority identifier (e.g. an address) needs to be passed in the NewKeeper functions of the following keepers:

  • You must pass the authority to the ica/host keeper (implemented in #3520). See diff:
// app.go

// ICA Host keeper
app.ICAHostKeeper = icahostkeeper.NewKeeper(
  appCodec, keys[icahosttypes.StoreKey], app.GetSubspace(icahosttypes.SubModuleName),
  app.IBCFeeKeeper, // use ics29 fee as ics4Wrapper in middleware stack
  app.IBCKeeper.ChannelKeeper, &app.IBCKeeper.PortKeeper,
  app.AccountKeeper, scopedICAHostKeeper, app.MsgServiceRouter(),
+ authtypes.NewModuleAddress(govtypes.ModuleName).String(),
)
  • You must pass the authority to the ica/controller keeper (implemented in #3590). See diff:
// app.go

// ICA Controller keeper
app.ICAControllerKeeper = icacontrollerkeeper.NewKeeper(
  appCodec, keys[icacontrollertypes.StoreKey], app.GetSubspace(icacontrollertypes.SubModuleName),
  app.IBCFeeKeeper, // use ics29 fee as ics4Wrapper in middleware stack
  app.IBCKeeper.ChannelKeeper, &app.IBCKeeper.PortKeeper,
  scopedICAControllerKeeper, app.MsgServiceRouter(),
+ authtypes.NewModuleAddress(govtypes.ModuleName).String(),
)
  • You must pass the authority to the ibctransfer keeper (implemented in #3553). See diff:
// app.go

// Create Transfer Keeper and pass IBCFeeKeeper as expected Channel and PortKeeper
// since fee middleware will wrap the IBCKeeper for underlying application.
app.TransferKeeper = ibctransferkeeper.NewKeeper(
  appCodec, keys[ibctransfertypes.StoreKey], app.GetSubspace(ibctransfertypes.ModuleName),
  app.IBCFeeKeeper, // ISC4 Wrapper: fee IBC middleware
  app.IBCKeeper.ChannelKeeper, &app.IBCKeeper.PortKeeper,
  app.AccountKeeper, app.BankKeeper, scopedTransferKeeper,
+ authtypes.NewModuleAddress(govtypes.ModuleName).String(),
)
  • You should pass the authority to the IBC keeper (implemented in #3640 and #3650). See diff:
// app.go

// IBC Keepers
app.IBCKeeper = ibckeeper.NewKeeper(
  appCodec, 
  keys[ibcexported.StoreKey],
  app.GetSubspace(ibcexported.ModuleName),
  app.StakingKeeper,
  app.UpgradeKeeper,
  scopedIBCKeeper,
+ authtypes.NewModuleAddress(govtypes.ModuleName).String(),
)

The authority determines the transaction signer allowed to execute certain messages (e.g. MsgUpdateParams).

Testing package​

  • The function SetupWithGenesisAccounts has been removed.
  • The function RelayPacketWithResults has been added. This function returns the result of the packet receive transaction, the acknowledgement written on the receiving chain, an error if a relay step fails or the packet commitment does not exist on either chain.

Params migration​

Params are now self managed in the following submodules:

Each module has a corresponding MsgUpdateParams message with a Params which can be specified in full to update the modules' Params.

Legacy params subspaces must still be initialised in app.go in order to successfully migrate from `x/params`` to the new self-contained approach. See reference this for reference.

For new chains which do not rely on migration of parameters from x/params, an expected interface has been added for each module. This allows chain developers to provide nil as the legacySubspace argument to NewKeeper functions.

Governance V1 migration​

Proposals have been migrated to gov v1 messages (see #4620). The proposal ClientUpdateProposal has been deprecated and MsgRecoverClient should be used instead. Likewise, the proposal UpgradeProposal has been deprecated and MsgIBCSoftwareUpgrade should be used instead. Both proposals will be removed in the next major release.

MsgRecoverClient and MsgIBCSoftwareUpgrade will only be allowed to be executed if the signer is the authority designated at the time of instantiating the IBC keeper. So please make sure that the correct authority is provided to the IBC keeper.

Remove the UpgradeProposalHandler and UpdateClientProposalHandler from the BasicModuleManager:

app.BasicModuleManager = module.NewBasicManagerFromManager(
  app.ModuleManager,
  map[string]module.AppModuleBasic{
    genutiltypes.ModuleName: genutil.NewAppModuleBasic(genutiltypes.DefaultMessageValidator),
    govtypes.ModuleName: gov.NewAppModuleBasic(
      []govclient.ProposalHandler{
      paramsclient.ProposalHandler,
-     ibcclientclient.UpdateClientProposalHandler,
-     ibcclientclient.UpgradeProposalHandler,
    },
  ),
})

Support for in-flight legacy recover client proposals (i.e. ClientUpdateProposal) will be made for v8, but chains should use MsgRecoverClient only afterwards to avoid in-flight client recovery failing when upgrading to v9. See this issue for more information.

Please note that ibc-go offers facilities to test an ibc-go upgrade:

Transfer migration​

An automatic migration handler is configured in the transfer module to set the denomination metadata for the IBC denominations of all vouchers minted by the transfer module.

IBC Apps​

ICS20 - Transfer​

  • The function IsBound has been renamed to hasCapability and made unexported.

ICS27 - Interchain Accounts​

Relayers​

  • Getter functions in MsgChannelOpenInitResponse, MsgChannelOpenTryResponse, MsgTransferResponse, MsgRegisterInterchainAccountResponse and MsgSendTxResponse have been removed. The fields can be accessed directly.
  • channeltypes.EventTypeTimeoutPacketOnClose (where channeltypes is an import alias for "github.com/cosmos/ibc-go/v8/modules/core/04-channel") has been removed, since core IBC does not emit any event with this key.
  • Attribute with key counterparty_connection_id has been removed from event with key connectiontypes.EventTypeConnectionOpenInit (where connectiontypes is an import alias for "github.com/cosmos/ibc-go/v8/modules/core/03-connection/types") and attribute with key counterparty_channel_id has been removed from event with key channeltypes.EventTypeChannelOpenInit (where channeltypes is an import alias for "github.com/cosmos/ibc-go/v8/modules/core/04-channel") since both (counterparty connection ID and counterparty channel ID) are empty on ConnectionOpenInit and ChannelOpenInit respectively.
  • As part of the migration to governance V1 messages the following changes in events have been made:
// IBC client events vars
var (
  EventTypeCreateClient          = "create_client"
  EventTypeUpdateClient          = "update_client"
  EventTypeUpgradeClient         = "upgrade_client"
  EventTypeSubmitMisbehaviour    = "client_misbehaviour"
- EventTypeUpdateClientProposal  = "update_client_proposal"
- EventTypeUpgradeClientProposal = "upgrade_client_proposal"
+ EventTypeRecoverClient              = "recover_client"
+ EventTypeScheduleIBCSoftwareUpgrade = "schedule_ibc_software_upgrade"
  EventTypeUpgradeChain               = "upgrade_chain"
)

IBC Light Clients​

  • Functions Pretty and String of type MerklePath have been removed.