---
title: IBC-Go v7 to v8
sidebar_label: IBC-Go v7 to v8
sidebar_position: 11
slug: /migrations/v7-to-v8
---

# 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:

- [Migrating from v7 to v8](#migrating-from-v7-to-v8)
    - [Chains](#chains)
        - [Cosmos SDK v0.50 upgrade](#cosmos-sdk-v050-upgrade)
        - [Authority](#authority)
        - [Testing package](#testing-package)
        - [Params migration](#params-migration)
        - [Governance V1 migration](#governance-v1-migration)
        - [Transfer migration](#transfer-migration)
    - [IBC Apps](#ibc-apps)
        - [ICS20 - Transfer](#ics20---transfer)
        - [ICS27 - Interchain Accounts](#ics27---interchain-accounts)
    - [Relayers](#relayers)
    - [IBC Light Clients](#ibc-light-clients)

**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`:

```diff
// 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](https://github.com/cosmos/ibc-go/pull/4703/files#diff-d18972debee5e64f16e40807b2ae112ddbe609504a93ea5e1c80a5d489c3a08a) for the changes required in `app.go`.

An extra parameter `totalEscrowed` of type `sdk.Coins` has been added to transfer module's [`NewGenesisState` function](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/types/genesis.go#L10). 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](https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/UPGRADING.md) 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](https://github.com/cosmos/ibc-go/pull/3520)). See [diff](https://github.com/cosmos/ibc-go/pull/3520/files#diff-d18972debee5e64f16e40807b2ae112ddbe609504a93ea5e1c80a5d489c3a08a):

```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](https://github.com/cosmos/ibc-go/pull/3590)). See [diff](https://github.com/cosmos/ibc-go/pull/3590/files#diff-d18972debee5e64f16e40807b2ae112ddbe609504a93ea5e1c80a5d489c3a08a):

```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](https://github.com/cosmos/ibc-go/pull/3553)). See [diff](https://github.com/cosmos/ibc-go/pull/3553/files#diff-d18972debee5e64f16e40807b2ae112ddbe609504a93ea5e1c80a5d489c3a08a):

```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](https://github.com/cosmos/ibc-go/pull/3640) and [#3650](https://github.com/cosmos/ibc-go/pull/3650)). See [diff](https://github.com/cosmos/ibc-go/pull/3640/files#diff-d18972debee5e64f16e40807b2ae112ddbe609504a93ea5e1c80a5d489c3a08a):

```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`](https://github.com/cosmos/ibc-go/blob/v8.0.0/testing/path.go#L66) 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:

- ica/controller [#3590](https://github.com/cosmos/ibc-go/pull/3590)
- ica/host [#3520](https://github.com/cosmos/ibc-go/pull/3520)
- ibc/connection [#3650](https://github.com/cosmos/ibc-go/pull/3650)
- ibc/client [#3640](https://github.com/cosmos/ibc-go/pull/3640)
- ibc/transfer [#3553](https://github.com/cosmos/ibc-go/pull/3553)

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](https://github.com/cosmos/ibc-go/blob/v8.0.0/testing/simapp/app.go#L1007-L1012) 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](https://docs.cosmos.network/v0.50/modules/gov#messages) (see [#4620](https://github.com/cosmos/ibc-go/pull/4620)). The proposal `ClientUpdateProposal` has been deprecated and [`MsgRecoverClient`](https://github.com/cosmos/ibc-go/blob/v8.0.0/proto/ibc/core/client/v1/tx.proto#L121-L134) should be used instead. Likewise, the proposal `UpgradeProposal` has been deprecated and [`MsgIBCSoftwareUpgrade`](https://github.com/cosmos/ibc-go/blob/v8.0.0/proto/ibc/core/client/v1/tx.proto#L139-L154) 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`:

```diff
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](https://github.com/cosmos/ibc-go/issues/4721) for more information.

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

- All e2e tests of the repository can be [run with custom Docker chain images](https://github.com/cosmos/ibc-go/blob/c5bac5e03a0eae449b9efe0d312258115c1a1e85/e2e/README.md#running-tests-with-custom-images).
- An [importable workflow](https://github.com/cosmos/ibc-go/blob/c5bac5e03a0eae449b9efe0d312258115c1a1e85/e2e/README.md#importable-workflow) that can be used from any other repository to test chain upgrades.

### Transfer migration

An [automatic migration handler](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/module.go#L136) is configured in the transfer module to set the [denomination metadata](https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/proto/cosmos/bank/v1beta1/bank.proto#L96-L125) for the IBC denominations of all vouchers minted by the transfer module.

## IBC Apps

### ICS20 - Transfer

- The function `IsBound` has been renamed to [`hasCapability`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/keeper/keeper.go#L98) and made unexported.

### ICS27 - Interchain Accounts

- Functions [`SerializeCosmosTx`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/27-interchain-accounts/types/codec.go#L32) and [`DeserializeCosmosTx`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/27-interchain-accounts/types/codec.go#L76) now accept an extra parameter `encoding` of type `string` that specifies the format in which the transaction messages are marshaled. Both [protobuf and proto3 JSON formats](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/27-interchain-accounts/types/metadata.go#L14-L17) are supported.
- The function `IsBound` of controller submodule has been renamed to [`hasCapability`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/27-interchain-accounts/controller/keeper/keeper.go#L111) and made unexported.
- The function `IsBound` of host submodule has been renamed to [`hasCapability`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/27-interchain-accounts/host/keeper/keeper.go#L94) and made unexported.

## 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](#governance-v1-migration) the following changes in events have been made:

```diff
// 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](https://github.com/cosmos/ibc-go/pull/4459/files#diff-dd94ec1dde9b047c0cdfba204e30dad74a81de202e3b09ac5b42f493153811af).
