Skip to main content
Version: Next

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:

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

Chains​

Chains will need to remove the route for the legacy proposal handler for 02-client from their app/app.go:

// app.go
govRouter.AddRoute(govtypes.RouterKey, govv1beta1.ProposalHandler).
- AddRoute(paramproposal.RouterKey, params.NewParamChangeProposalHandler(app.ParamsKeeper)).
- AddRoute(ibcclienttypes.RouterKey, ibcclient.NewClientProposalHandler(app.IBCKeeper.ClientKeeper))
+ AddRoute(paramproposal.RouterKey, params.NewParamChangeProposalHandler(app.ParamsKeeper))

IBC core​

API removals​

02-client​

03-connection​

04-channel​

func (k *Keeper) ChanCloseConfirm(
	ctx sdk.Context,
	portID,
	channelID string,
	chanCap *capabilitytypes.Capability,
	initProof []byte,
	proofHeight exported.Height,
+	counterpartyUpgradeSequence uint64,
)

func (k *Keeper) TimeoutOnClose(
	ctx sdk.Context,
	chanCap *capabilitytypes.Capability,
	packet types.Packet,
	proof,
	closedProof []byte,
	proofHeight exported.Height,
	nextSequenceRecv uint64,
+	counterpartyUpgradeSequence uint64,
)

05-port​

  • The signature of the UnmarshalPacketData function of the PacketDataUnmarshaler interface takes now extra arguments for the context and the port and channel identifiers. These parameters have been added so that implementations of the interface function can retrieve the channel version, which allows the provided packet data to be unmarshaled based on the channel version:
type PacketDataUnmarshaler interface {
	UnmarshalPacketData(
+   ctx sdk.Context,
+   portID, 
+   channelID string,
    bz []byte,
  ) (interface{}, error)
}

23-commitment​

  • The exported.Proof interface has been removed. Please use the MerkleProof concrete type.
  • The MerklePath type has been deprecated and a new commitment.v2.MerklePath type has been introduced in #6644. The new commitment.v2.MerklePath contains repeated bytes in favour of repeated string. This allows users to prove values stored under keys which contain non-utf8 encoded symbols. As a result, changes have been made to the 02-client Query service and 08-wasm contract API messages for JSON blobs. See 02-client and 08-wasm, respectively.

IBC Apps​

ICS20 - Transfer​

ICS20 v2​

  • With support for multidenom transfer packets and path forwarding, the NewMsgTransfer constructor function to create a new MsgTransfer instance now accepts multiple coins instead of just one, and an argument with forwarding information:
func NewMsgTransfer(
  sourcePort, sourceChannel string,
- token sdk.Coin, 
+ tokens sdk.Coins,
  sender, receiver string,
  timeoutHeight clienttypes.Height, timeoutTimestamp uint64,
  memo string,
+ forwarding *Forwarding,
)
  • The ibc_transfer and fungible_token_packet events do not include the attributes denom and amount anymore; instead they include the attribute tokens with the list of coins transferred in the packet.
  • A new type for the packet payload has been introduced: FungibleTokenPacketDataV2. Transfer channels with version ics20-2 will use this new type for the payload and it will be encoded using Protobuf (instead of JSON). Middleware that wraps the transfer application and unmarshals the packet data MUST take this into account when upgrading: depending on the channel version, packet data should unmarshal either as JSON (v1) or Protobuf (v2). The helper function UnmarshalPacketData encapsulates this logic and can be used by middleware or other applications to correctly unmarshal the packet data:
packetData, err := transfertypes.UnmarshalPacketData(packet.Data, version)
if err != nil {
  return err
}

DenomTrace type refactoring​

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
  • The function RegisterInterchainAccountWithOrdering has been removed. The legacy function RegisterInterchainAccount now takes an extra parameter to specify the ordering of new ICA channels:
func (k Keeper) RegisterInterchainAccount(
  ctx sdk.Context,
  connectionID, owner,
  version string,
+ ordering channeltypes.Order
) error {
  • The requests repeated field of MsgModuleQuerySafe has been marked non-nullable, and therefore the signature of the constructor function NewMsgModuleQuerySafe has been updated:
func NewMsgModuleQuerySafe(
  signer string, 
- requests []*QueryRequest,
+ requests []QueryRequest,
) *MsgModuleQuerySafe {
  • The signature of the NewIBCMiddleware constructor function in the controller submodule now only takes the controller keeper as an argument. The base application is then set by default to nil and thus authentication is assumed to be done by a Cosmos SDK module, such as the x/gov, x/group or x/auth, that sends messages to the controller submodule's message server. An authentication module can be set using the newly added NewIBCMiddlewareWithAuth constructor function.
func NewIBCMiddleware(
- app porttypes.IBCModule, 
  k keeper.Keeper,
) IBCMiddleware {
  • The InitModule function has been removed. When adding the interchain accounts module to the chain, please set the desired params for controller and host submodules directly after calling RunMigrations in the upgrade handler.
  • The GetBytes() function of the CosmosTx type has been removed.

IBC testing package​

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

func AssertEvents(
  suite *testifysuite.Suite,
  expected []abci.Event,
  actual []abci.Event,
)
clientQueryServer := clientkeeper.NewQueryServer(app.IBCKeeper.ClientKeeper)

API deprecation notice​

  • The testing package functions Setup, SetupClients, SetupConnections, CreateConnections, and CreateChannels of the Coordinator type have been deprecated and will be removed in v10. Please use the new functions Setup, SetupClients, SetupConnections, CreateConnections, CreateChannels of the Path type.

Relayers​

Events​

02-client​

04-channel​

  • The constant AttributeVersion has been renamed to AttributeKeyVersion.
  • The packet_data and the packet_ack attributes of the send_packet, recv_packet and write_acknowledgement events have been removed in #6023. The attributes packet_data_hex and packet_ack_hex should be used instead. The constants AttributeKeyData and AttributeKeyAck have also been removed.
Channel upgrades​
  • The attributes version, ordering and connection_hops from the channel_upgrade_init, channel_upgrade_try, channel_upgrade_ack, channel_upgrade_open, channel_upgrade_timeout and channel_upgrade_cancelled events have been removed in #6063.

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 interfaceLightClientModule interface
InitializeInitialize
StatusStatus
GetLatestHeightLatestHeight
GetTimestampAtHeightTimestampAtHeight
VerifyClientMessageVerifyClientMessage
VerifyMembershipVerifyMembership
VerifyNonMembershipVerifyNonMembership
CheckForMisbehaviourCheckForMisbehaviour
UpdateStateUpdateState
UpdateStateOnMisbehaviourUpdateStateOnMisbehaviour
CheckSubstituteAndUpdateStateRecoverClient
VerifyUpgradeAndUpdateStateVerifyUpgradeAndUpdateState
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​

07-tendermint​

08-wasm​

Refer to the 08-wasm migration documentation for more information.

09-localhost​

The 09-localhost light client has been made stateless and will no longer update the client on every block. The ClientState is constructed on demand when required. The ClientState itself is therefore no longer provable directly with VerifyMembership or VerifyNonMembership.

An automatic migration handler is configured to prune all previously stored client state data on IBC module store migration from ConsensusVersion 6 to 7.