Migrating from v8 to v9

This guide provides instructions for migrating to a new version of ibc-go.

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

• Chains
• IBC Apps
• Relayers
• IBC Light Clients

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

Chains

• No relevant changes were made in this release.

IBC Apps

API removals

The exported.ChannelI and exported.CounterpartyChannelI interfaces have been removed. Please use the concrete types. The exported.ConnectionI and exported.CounterpartyConnectionI interfaces have been removed. Please use the concrete types.

The functions GetState(), GetOrdering(), GetCounterparty(), GetConnectionHops(), GetVersion() of the Channel type have been removed. The functions GetPortID(), GetChannelID() of the CounterpartyChannel type have been removed. The functions GetClientID(), GetState(), GetCounterparty(), GetVersions(), and GetDelayPeriod of the Connection type have been removed. The functions GetClientID(), GetConnectionID(), and GetPrefix() of the CounterpartyConnection type have been removed.

The utility function QueryLatestConsensusState of 04-channel CLI has been removed.

API deprecation notice

The testing package functions coordinator.Setup, coordinator.SetupClients, coordinator.SetupConnections, coordinator.CreateConnections, and coordinator.CreateChannels have been deprecated and will be removed in v10. Please use the new functions path.Setup, path.SetupClients, path.SetupConnections, path.CreateConnections, path.CreateChannels.

IBC testing package

• The mock.PV type has been removed in favour of cmttypes.MockPV (#5709).
• Functions ConstructUpdateTMClientHeader and ConstructUpdateTMClientHeaderWithTrustedHeight of TestChain type have been replaced with IBCClientHeader. This function will construct a 07-tendermint header to update the light client on the counterparty chain. The trusted height must be passed in as a non-zero height.
• GetValsAtHeight has been renamed to GetTrustedValidators
• AssertEventsLegacy function of ibctesting package (alias for "github.com/cosmos/ibc-go/v9/testing") has been removed and AssertEvents function should be used instead (ref: #6070).

// testing/events.go
- func AssertEventsLegacy(
-   suite *testifysuite.Suite,
-   expected EventsMap,
-   actual []abci.Event,
- )

func AssertEvents(
  suite *testifysuite.Suite,
  expected []abci.Event,
  actual []abci.Event,
)

IBC core

• Router reference has been removed from IBC core keeper: #6138

ICS27 - Interchain Accounts

In #5785 the list of arguments of the NewKeeper constructor function of the host submodule was extended with an extra argument for the gRPC query router that the submodule uses when executing a MsgModuleQuerySafe to perform queries that are module safe:

func NewKeeper(
  cdc codec.Codec, key storetypes.StoreKey, legacySubspace icatypes.ParamSubspace,
  ics4Wrapper porttypes.ICS4Wrapper, channelKeeper icatypes.ChannelKeeper,
  portKeeper icatypes.PortKeeper,	accountKeeper icatypes.AccountKeeper, 
  scopedKeeper exported.ScopedKeeper, msgRouter icatypes.MessageRouter,
+ queryRouter icatypes.QueryRouter, 
  authority string,
) Keeper

Relayers

• Renaming of event attribute keys in #5603.
• Removal of duplicate non-hexlified event attributes in #6023.

IBC Light Clients

API removals

The ExportMetadata interface function has been removed from the ClientState interface. Core IBC will export all key/value's within the 02-client store.

The ZeroCustomFields interface function has been removed from the ClientState interface.

The following functions have also been removed from the ClientState interface: Initialize, Status, GetLatestHeight, GetTimestampAtHeight, VerifyClientMessage, VerifyMembership, VerifyNonMembership, CheckForMisbehaviour, UpdateState, UpdateStateOnMisbehaviour, CheckSubstituteAndUpdateState and VerifyUpgradeAndUpdateState. ibc-go v9 decouples routing at the 02-client layer from the light clients' encoding structure (i.e. every light client implementation of the ClientState interface is not used anymore to route the requests to the right light client at the 02-client layer, instead a light client module is registered for every light client type and 02-client routes the requests to the right light client module based on the client ID). Light client developers must implement the newly introduced LightClientModule interface and are encouraged to move the logic implemented in the functions of their light client's implementation of the ClientState interface to the equivalent function in the LightClientModule interface. The table below shows the equivalence between the ClientState interface functions that have been removed and the functions in the LightClientModule interface:

ClientState interface	LightClientModule interface
Initialize	Initialize
Status	Status
GetLatestHeight	LatestHeight
GetTimestampAtHeight	TimestampAtHeight
VerifyClientMessage	VerifyClientMessage
VerifyMembership	VerifyMembership
VerifyNonMembership	VerifyNonMembership
CheckForMisbehaviour	CheckForMisbehaviour
UpdateState	UpdateState
UpdateStateOnMisbehaviour	UpdateStateOnMisbehaviour
CheckSubstituteAndUpdateState	RecoverClient
VerifyUpgradeAndUpdateState	VerifyUpgradeAndUpdateState
ExportMetadata
ZeroCustomFields

Please check also the Light client developer guide for more information. The light client module implementation for 07-tendermint may also be useful as reference.

06-solomachine

The Initialize function in ClientState has been removed and all its logic has been moved to the implementation of the LightClientModule interface Initialize function.

07-tendermint

The IterateConsensusMetadata function has been removed.

08-wasm

The ExportMetadataMsg struct has been removed and is no longer required for contracts to implement. Core IBC will handle exporting all key/value's written to the store by a light client contract. The ZeroCustomFields interface function has been removed from the ClientState interface. Core IBC only used this function to set tendermint client states when scheduling an IBC software upgrade. The interface function has been replaced by a type assertion.