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
- The
exported.ChannelI
andexported.CounterpartyChannelI
interfaces have been removed. Please use the concrete types. - The
exported.ConnectionI
andexported.CounterpartyConnectionI
interfaces have been removed. Please use the concrete types. - The
Router
reference has been removed from the IBC core keeper in #6138. Please usePortKeeper.Router
instead. - The composite interface
QueryServer
has been removed from packagecore/types
. Please use the granularQueryServer
interfaces for IBC submodules directly. - The
TypeClientMisbehaviour
constant has been removed.
02-client
- The
QueryVerifyMembershipRequest
protobuf message has been modified to includecommitment.v2.MerklePath
. The deprecatedcommitment.v1.MerklePath
field has beenreserved
. See 23-commitment. - The function
CreateLocalhostClient
has been removed. The localhost client is now stateless. - The function
NewClientProposalHandler
has been removed in #6777. - The deprecated
ClientUpdateProposal
andUpgradeProposal
messages have been removed in #6782. Please useMsgRecoverClient
andMsgIBCSoftwareUpgrade
respectively instead.
03-connection
- The functions
GetState()
,GetClientID()
,GetCounterparty()
,GetVersions()
, andGetDelayPeriod()
of theConnection
type have been removed. - The functions
GetClientID()
,GetConnectionID()
, andGetPrefix()
of theCounterparty
type have been removed.
04-channel
- The utility function
QueryLatestConsensusState
of the CLI has been removed. - The functions
GetState()
,GetOrdering()
,GetCounterparty()
,GetConnectionHops()
,GetVersion()
of theChannel
type have been removed. - The functions
IsOpen()
andIsClosed()
of theChannel
type have been removed. - The functions
GetPortID()
,GetChannelID()
of theCounterpartyChannel
type have been removed. - Functions
ChanCloseConfirmWithCounterpartyUpgradeSequence
andTimeoutOnCloseWithCounterpartyUpgradeSequence
have been removed. Please useChanCloseConfirm
andTimeoutOnClose
with the updated signature that takes the counterparty upgrade sequence as extra argument:
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 thePacketDataUnmarshaler
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 theMerkleProof
concrete type. - The
MerklePath
type has been deprecated and a newcommitment.v2.MerklePath
type has been introduced in #6644. The newcommitment.v2.MerklePath
containsrepeated bytes
in favour ofrepeated 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-clientQuery
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 newMsgTransfer
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
andfungible_token_packet
events do not include the attributesdenom
andamount
anymore; instead they include the attributetokens
with the list of coins transferred in the packet. - A new type for the packet payload has been introduced:
FungibleTokenPacketDataV2
. Transfer channels with versionics20-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 functionUnmarshalPacketData
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
- The
DenomTrace
type has been made private and will be completely removed in a later release. Please use theDenom
type instead. - The
DenomTrace
andDenomTraces
gRPCs have been removed as well (together with the andQueryDenomTraceResponse
andQueryDenomTracesResponse
types). Please use theDenom
andDenoms
gRPCs instead. - An automatic migration handler is also configured to migrate the storage from using
DenomTrace
toDenom
. - The
denomination_trace
event emitted in theOnRecvPacket
callback has been replaced with thedenom
event. - The functions
SenderChainIsSource
andReceiverChainIsSource
have been replaced with the functionHasPrefix
of the newly addedDenom
type. - The helper function
GetTransferCoin
has been removed. - The helper function
GetDenomPrefix
has been removed. - The helper function
GetPrefixedDenom
has been removed. Please construct the denom using the newDenom
type.
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 aMsgModuleQuerySafe
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 functionRegisterInterchainAccount
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 ofMsgModuleQuerySafe
has been marked non-nullable, and therefore the signature of the constructor functionNewMsgModuleQuerySafe
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 thex/gov
,x/group
orx/auth
, that sends messages to the controller submodule's message server. An authentication module can be set using the newly addedNewIBCMiddlewareWithAuth
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 callingRunMigrations
in the upgrade handler. - The
GetBytes()
function of theCosmosTx
type has been removed.
IBC testing package
- The
mock.PV
type has been removed in favour ofcmttypes.MockPV
in #5709. - Functions
ConstructUpdateTMClientHeader
andConstructUpdateTMClientHeaderWithTrustedHeight
ofTestChain
type have been replaced withIBCClientHeader
function. 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 toGetTrustedValidators
.AssertEventsLegacy
function ofibctesting
package (alias for"github.com/cosmos/ibc-go/v9/testing"
) has been removed in #6070, andAssertEvents
function should be used instead.
// testing/events.go
- func AssertEventsLegacy(
- suite *testifysuite.Suite,
- expected EventsMap,
- actual []abci.Event,
- )
func AssertEvents(
suite *testifysuite.Suite,
expected []abci.Event,
actual []abci.Event,
)
- The
QueryServer
interface has been removed from theTestChain
struct. Submodule query servers can be constructed directly by passing their associated keeper to the appropriate constructor function. For example:
clientQueryServer := clientkeeper.NewQueryServer(app.IBCKeeper.ClientKeeper)
API deprecation notice
- The testing package functions
Setup
,SetupClients
,SetupConnections
,CreateConnections
, andCreateChannels
of theCoordinator
type have been deprecated and will be removed in v10. Please use the new functionsSetup
,SetupClients
,SetupConnections
,CreateConnections
,CreateChannels
of thePath
type.
Relayers
Events
02-client
- The
header
attribute has been removed from theupdate_client
event in #5110.
04-channel
- The constant
AttributeVersion
has been renamed toAttributeKeyVersion
. - The
packet_data
and thepacket_ack
attributes of thesend_packet
,recv_packet
andwrite_acknowledgement
events have been removed in #6023. The attributespacket_data_hex
andpacket_ack_hex
should be used instead. The constantsAttributeKeyData
andAttributeKeyAck
have also been removed.
Channel upgrades
- The attributes
version
,ordering
andconnection_hops
from thechannel_upgrade_init
,channel_upgrade_try
,channel_upgrade_ack
,channel_upgrade_open
,channel_upgrade_timeout
andchannel_upgrade_cancelled
events have been removed in #6063.
IBC Light Clients
API removals
- The
ExportMetadata
interface function has been removed from theClientState
interface. Core IBC will export all key/value's within the 02-client store. - The
ZeroCustomFields
interface function has been removed from theClientState
interface. - The following functions have also been removed from the
ClientState
interface:Initialize
,Status
,GetLatestHeight
,GetTimestampAtHeight
,VerifyClientMessage
,VerifyMembership
,VerifyNonMembership
,CheckForMisbehaviour
,UpdateState
,UpdateStateOnMisbehaviour
,CheckSubstituteAndUpdateState
andVerifyUpgradeAndUpdateState
. ibc-go v9 decouples routing at the 02-client layer from the light clients' encoding structure (i.e. every light client implementation of theClientState
interface is not used anymore to route the requests to the right light client at the02-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 introducedLightClientModule
interface and are encouraged to move the logic implemented in the functions of their light client's implementation of theClientState
interface to the equivalent function in theLightClientModule
interface. The table below shows the equivalence between theClientState
interface functions that have been removed and the functions in theLightClientModule
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
,Status
,GetTimestampAtHeight
andUpdateStateOnMisbehaviour
functions inClientState
have been removed and all their logic has been moved to functions of theLightClientModule
. TheVerifyMembership
andVerifyNonMembership
functions have been made private. - The
Type
method onMisbehaviour
has been removed.
07-tendermint
- The
IterateConsensusMetadata
function has been removed. TheInitialize
,Status
,GetTimestampAtHeight
,VerifyMembership
,VerifyNonMembership
functions have been made private.
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.