diff --git a/CHANGELOG.md b/CHANGELOG.md index ee56fa3031e..90e91dd3039 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -45,9 +45,16 @@ Ref: https://keepachangelog.com/en/1.0.0/ ### API Breaking +* (apps/27-interchain-accounts) [\#4977](https://github.com/cosmos/ibc-go/pull/4977) The `InitModule` function has been removed. +* (core/02-client) [\#5110](https://github.com/cosmos/ibc-go/pull/5110) The `header` attribute has been removed from the `update_client` event. +* (apps/27-interchain-accounts) [\#5396](https://github.com/cosmos/ibc-go/pull/5396) Remove `GetBytes` function of `CosmosTx` type. +* (core/04-channel) [\#5691](https://github.com/cosmos/ibc-go/pull/5691) Remove functions `IsOpen` and `IsClosed` of `Channel` type. +* (core/04-channel) [\#5705](https://github.com/cosmos/ibc-go/pull/5705) Remove functions `GetState`, `GetOrdering`, `GetCounterparty`, `GetConnectionHops`, `GetVersion` of the `Channel` type. +* (core/04-channel) [\#5603](https://github.com/cosmos/ibc-go/pull/5603) Rename attribute names and constants for channel upgrades events. * (core/02-client, light-clients) [\#5806](https://github.com/cosmos/ibc-go/pull/5806) Decouple light client routing from their encoding structure. * (core/04-channel) [\#5991](https://github.com/cosmos/ibc-go/pull/5991) The client CLI `QueryLatestConsensusState` has been removed. * (light-clients/06-solomachine) [\#6037](https://github.com/cosmos/ibc-go/pull/6037) Remove `Initialize` function from `ClientState` and move logic to `Initialize` function of `LightClientModule`. +- (core/04-channel) [\#6063](https://github.com/cosmos/ibc-go/pull/6063) Remove 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. * (light-clients/06-solomachine) [\#6230](https://github.com/cosmos/ibc-go/pull/6230) Remove `GetTimestampAtHeight`, `Status` and `UpdateStateOnMisbehaviour` functions from `ClientState` and move logic to functions of `LightClientModule`. * (core/02-client) [\#6084](https://github.com/cosmos/ibc-go/pull/6084) Removed `stakingKeeper` as an argument to `NewKeeper` and replaced with a `ConsensusHost` implementation. * (testing) [\#6070](https://github.com/cosmos/ibc-go/pull/6070) Remove `AssertEventsLegacy` function. diff --git a/docs/docs/05-migrations/13-v8-to-v9.md b/docs/docs/05-migrations/13-v8-to-v9.md index ff42acaf175..73013c092bf 100644 --- a/docs/docs/05-migrations/13-v8-to-v9.md +++ b/docs/docs/05-migrations/13-v8-to-v9.md @@ -11,29 +11,127 @@ 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](#chains) -- [IBC Apps](#ibc-apps) -- [Relayers](#relayers) -- [IBC Light Clients](#ibc-light-clients) +- [Migrating from v8 to v9](#migrating-from-v8-to-v9) + - [Chains](#chains) + - [IBC core](#ibc-core) + - [API removals](#api-removals) + - [02-client](#02-client) + - [03-connection](#03-connection) + - [04-channel](#04-channel) + - [05-port](#05-port) + - [23-commitment](#23-commitment) + - [IBC Apps](#ibc-apps) + - [ICS20 - Transfer](#ics20---transfer) + - [ICS20 v2](#ics20-v2) + - [`DenomTrace` type refactoring](#denomtrace-type-refactoring) + - [ICS27 - Interchain Accounts](#ics27---interchain-accounts) + - [IBC testing package](#ibc-testing-package) + - [API deprecation notice](#api-deprecation-notice) + - [Relayers](#relayers) + - [Events](#events) + - [02-client](#02-client-1) + - [04-channel](#04-channel-1) + - [Channel upgrades](#channel-upgrades) + - [IBC Light Clients](#ibc-light-clients) + - [API removals](#api-removals-1) + - [06-solomachine](#06-solomachine) + - [07-tendermint](#07-tendermint) + - [08-wasm](#08-wasm) + - [09-localhost](#09-localhost) **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`: +Chains will need to remove the route for the legacy proposal handler for 02-client from their `app/app.go`: ```diff // 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)) +- 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`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/exported/channel.go#L3-L11) and [`exported.CounterpartyChannelI`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/exported/channel.go#L13-L19) interfaces have been removed. Please use the concrete types. +- The [`exported.ConnectionI`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/exported/connection.go#L6-L13) and [`exported.CounterpartyConnectionI`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/exported/connection.go#L15-L21) interfaces have been removed. Please use the concrete types. +- The [`Router` reference](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/keeper/keeper.go#L35) has been removed from the IBC core keeper in [#6138](https://github.com/cosmos/ibc-go/pull/6138). Please use `PortKeeper.Router` instead. +- The [composite interface `QueryServer`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/types/query.go#L14-L19) has been removed from package `core/types`. Please use the granular `QueryServer` interfaces for IBC submodules directly. +- The [`TypeClientMisbehaviour` constant](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/exported/client.go#L17) has been removed. + +### 02-client + +- The `QueryVerifyMembershipRequest` protobuf message has been modified to include `commitment.v2.MerklePath`. The deprecated `commitment.v1.MerklePath` field has been `reserved`. [See 23-commitment](#23-commitment). +- The function [`CreateLocalhostClient`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/02-client/keeper/keeper.go#L56) has been removed. The localhost client is now stateless. +- The function [`NewClientProposalHandler`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/02-client/proposal_handler.go#L18) has been removed in [#6777](https://github.com/cosmos/ibc-go/pull/6777). +- The deprecated [`ClientUpdateProposal` and `UpgradeProposal` messages](https://github.com/cosmos/ibc-go/blob/v8.0.0/proto/ibc/core/client/v1/client.proto#L67-L113) have been removed in [\#6782](https://github.com/cosmos/ibc-go/pull/6782). Please use [`MsgRecoverClient`](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/proto/ibc/core/client/v1/tx.proto#L125-L138) and [`MsgIBCSoftwareUpgrade`](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/proto/ibc/core/client/v1/tx.proto#L143-L158) respectively instead. + +### 03-connection + +- The [functions `GetState()`, `GetClientID()`, `GetCounterparty()`, `GetVersions()`, and `GetDelayPeriod()`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/03-connection/types/connection.go#L25-L48) of the `Connection` type have been removed. +- The [functions `GetClientID()`, `GetConnectionID()`, and `GetPrefix()`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/03-connection/types/connection.go#L79-L92) of the `Counterparty` type have been removed. + +### 04-channel + +- The utility function [`QueryLatestConsensusState`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/04-channel/client/utils/utils.go#L130) of the CLI has been removed. +- The [functions `GetState()`, `GetOrdering()`, `GetCounterparty()`, `GetConnectionHops()`, `GetVersion()`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/04-channel/types/channel.go#L29-L52) of the `Channel` type have been removed. +- The [functions `IsOpen()` and `IsClosed()`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/04-channel/types/channel.go#L54-L62) of the `Channel` type have been removed. +- The [functions `GetPortID()`, `GetChannelID()`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/04-channel/types/channel.go#L92-L100) of the `CounterpartyChannel` type have been removed. +- Functions [`ChanCloseConfirmWithCounterpartyUpgradeSequence`](https://github.com/cosmos/ibc-go/blob/v8.1.0/modules/core/04-channel/keeper/handshake.go#L446) and [`TimeoutOnCloseWithCounterpartyUpgradeSequence`](https://github.com/cosmos/ibc-go/blob/v8.1.0/modules/core/04-channel/keeper/timeout.go#L226) have been removed. Please use `ChanCloseConfirm` and `TimeoutOnClose` with the updated signature that takes the counterparty upgrade sequence as extra argument: + +```diff +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: + +```diff +type PacketDataUnmarshaler interface { + UnmarshalPacketData( ++ ctx sdk.Context, ++ portID, ++ channelID string, + bz []byte, + ) (interface{}, error) +} +``` + +### 23-commitment + +- The [`exported.Proof`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/exported/commitment.go#L34-L44) interface has been removed. Please use the [`MerkleProof`](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/modules/core/23-commitment/types/commitment.pb.go#L161-L168) concrete type. +- The [`MerklePath` type](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/modules/core/23-commitment/types/commitment.pb.go#L113-L119) has been deprecated and a new [`commitment.v2.MerklePath` type](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/modules/core/23-commitment/types/v2/commitment.pb.go#L25-L30) has been introduced in [#6644](https://github.com/cosmos/ibc-go/pull/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](#02-client) and [08-wasm](#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: ```diff @@ -48,22 +146,30 @@ func NewMsgTransfer( ) ``` -- 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. -- The helper function [`GetTransferCoin`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/types/coin.go#L46) has been removed. -- The helper function [`GetDenomPrefix`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/types/coin.go#L35) has been removed. -- The helper function [`GetPrefixedDenom`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/types/coin.go#L40) has been removed. Please construct the denom using the new [`Denom` type](https://github.com/cosmos/ibc-go/blob/7068760f7277cab75b760a0d6ca95ccbfe2f78ae/modules/apps/transfer/types/token.pb.go#L82). +- 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`](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/proto/ibc/applications/transfer/v2/packet.proto#L27-L41). 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`](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/modules/apps/transfer/types/packet.go#L212) encapsulates this logic and can be used by middleware or other applications to correctly unmarshal the packet data: -#### `DenomTrace` type +```go +packetData, err := transfertypes.UnmarshalPacketData(packet.Data, version) +if err != nil { + return err +} +``` + +#### `DenomTrace` type refactoring -- The [`DenomTrace`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/types/transfer.pb.go#L25-L33) type has been made private and will be completely removed in a later release. -- The [`DenomTrace` and `DenomTraces` gRPCs](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/keeper/grpc_query.go#L22-L75) have therefore been removed as well. Please use the [`Denom` type](https://github.com/cosmos/ibc-go/blob/14fedae884e541779eefd01fc4aab5fe194856bc/modules/apps/transfer/types/token.pb.go#L81-L87) instead, and the [`Denom` and `Denoms` gRPCs](https://github.com/cosmos/ibc-go/blob/14fedae884e541779eefd01fc4aab5fe194856bc/modules/apps/transfer/keeper/grpc_query.go#L27-L80). -- An [automatic migration handler](https://github.com/cosmos/ibc-go/blob/14fedae884e541779eefd01fc4aab5fe194856bc/modules/apps/transfer/keeper/migrations.go#L75-L113) is also configured to migrate the storage from using `DenomTrace` to `Denom`. -- The [`denomination_trace` event emitted in the `OnRecvPacket` callback](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/keeper/relay.go#L268-L274) has been replaced with the [`denom` event](https://github.com/cosmos/ibc-go/blob/18121380dec5cff5ec803f1088fd409e069c2c9e/modules/apps/transfer/keeper/relay.go#L247). +- The [`DenomTrace`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/types/transfer.pb.go#L25-L33) type has been made private and will be completely removed in a later release. Please use the [`Denom` type](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/modules/apps/transfer/types/token.pb.go#L81-L87) instead. +- The [`DenomTrace` and `DenomTraces` gRPCs](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/keeper/grpc_query.go#L22-L75) have been removed as well (together with the and `QueryDenomTraceResponse` and `QueryDenomTracesResponse` types). Please use the [`Denom` and `Denoms` gRPCs](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/modules/apps/transfer/keeper/grpc_query.go#L27-L80) instead. +- An [automatic migration handler](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/modules/apps/transfer/keeper/migrations.go#L75-L113) is also configured to migrate the storage from using `DenomTrace` to `Denom`. +- The [`denomination_trace` event emitted in the `OnRecvPacket` callback](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/keeper/relay.go#L268-L274) has been replaced with the [`denom` event](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/modules/apps/transfer/keeper/relay.go#L230). - The functions [`SenderChainIsSource` and `ReceiverChainIsSource`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/types/coin.go#L12-L32) have been replaced with the function `HasPrefix` of the newly added `Denom` type. +- The helper function [`GetTransferCoin`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/types/coin.go#L46) has been removed. +- The helper function [`GetDenomPrefix`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/types/coin.go#L35) has been removed. +- The helper function [`GetPrefixedDenom`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/types/coin.go#L40) has been removed. Please construct the denom using the new [`Denom` type](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/modules/apps/transfer/types/token.pb.go#L82). ### ICS27 - Interchain Accounts -In [#5785](https://github.com/cosmos/ibc-go/pull/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`](https://github.com/cosmos/ibc-go/blob/eecfa5c09a4c38a5c9f2cc2a322d2286f45911da/proto/ibc/applications/interchain_accounts/host/v1/tx.proto#L41-L51) to perform queries that are module safe: +- In [#5785](https://github.com/cosmos/ibc-go/pull/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`](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/proto/ibc/applications/interchain_accounts/host/v1/tx.proto#L40-L51) to perform queries that are module safe: ```diff func NewKeeper( @@ -76,7 +182,7 @@ func NewKeeper( ) Keeper ``` -The legacy function `RegisterInterchainAccount` now takes an extra parameter to specify the ordering of new ICA channels: +- The function [`RegisterInterchainAccountWithOrdering`](https://github.com/cosmos/ibc-go/blob/v8.3.0/modules/apps/27-interchain-accounts/controller/keeper/account.go#L68) has been removed. The legacy function `RegisterInterchainAccount` now takes an extra parameter to specify the ordering of new ICA channels: ```diff func (k Keeper) RegisterInterchainAccount( @@ -87,7 +193,7 @@ func (k Keeper) RegisterInterchainAccount( ) error { ``` -The `requests` repeated field of `MsgModuleQuerySafe` has been marked non-nullable, and therefore the signature of the constructor function `NewMsgModuleQuerySafe` has been updated: +- The `requests` repeated field of `MsgModuleQuerySafe` has been marked non-nullable, and therefore the signature of the constructor function `NewMsgModuleQuerySafe` has been updated: ```diff func NewMsgModuleQuerySafe( @@ -97,7 +203,7 @@ func NewMsgModuleQuerySafe( ) *MsgModuleQuerySafe { ``` -The signature of the [`NewIBCMiddleware` constructor function](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/27-interchain-accounts/controller/ibc_middleware.go#L35) in the controller submodule now only takes the controller keeper as an argument: +- The signature of the [`NewIBCMiddleware` constructor function](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/27-interchain-accounts/controller/ibc_middleware.go#L35) 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](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/modules/apps/27-interchain-accounts/controller/ibc_middleware.go#L46). ```diff func NewIBCMiddleware( @@ -106,41 +212,15 @@ func NewIBCMiddleware( ) IBCMiddleware { ``` -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](https://github.com/cosmos/ibc-go/blob/82b5fb668b6f1c918023fb7be72a8606d2329d81/modules/apps/27-interchain-accounts/controller/ibc_middleware.go#L46). - -### IBC core - -### 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 `exported.Proof` interface has been removed. Please use the `MerkleProof` concrete type. -- 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. -- `UnmarshalPacketData` now takes in the context, portID, and channelID. This allows the packet data to be unmarshaled based on the channel version. -- `Router` reference has been removed from IBC core keeper: [#6138](https://github.com/cosmos/ibc-go/pull/6138). Please use `PortKeeper.Router` instead. -- The function `CreateLocalhostClient` has been removed. The localhost client is now stateless. -- The function `NewClientProposalHandler` has been removed. [#6777](https://github.com/cosmos/ibc-go/pull/6777). -- The composite interface `QueryServer` has been removed from package `core/types`. Please use the granular `QueryServer` interfaces for ibc submodules directly. -- The `TypeClientMisbehaviour` constant has been removed. - -### 02-client - -- The `QueryVerifyMembershipRequest` protobuf message has been modified to include `commitment.v2.MerklePath`. The deprecated `commitment.v1.MerklePath` field has been `reserved`. [See 23-commitment](#23-commitment) - -### 23-commitment - -- The `MerklePath` type has been deprecated and a new `commitment.v2.MerklePath` type has been introduced (ref: [#6644](https://github.com/cosmos/ibc-go/pull/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](#02-client) and [08-wasm](#08-wasm), respectively. +- The [`InitModule` function](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/27-interchain-accounts/module.go#L124-L143) 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](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/27-interchain-accounts/types/packet.go#L65-L68) of the `CosmosTx` type has been removed. ### IBC testing package -- The `mock.PV` type has been removed in favour of [`cmttypes.MockPV`](https://github.com/cometbft/cometbft/blob/v0.38.5/types/priv_validator.go#L50) ([#5709](https://github.com/cosmos/ibc-go/pull/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](https://github.com/cosmos/ibc-go/pull/6070)). +- The `mock.PV` type has been removed in favour of [`cmttypes.MockPV`](https://github.com/cometbft/cometbft/blob/v0.38.5/types/priv_validator.go#L50) in [#5709](https://github.com/cosmos/ibc-go/pull/5709). +- [Functions `ConstructUpdateTMClientHeader` and `ConstructUpdateTMClientHeaderWithTrustedHeight`](https://github.com/cosmos/ibc-go/blob/v8.0.0/testing/chain.go#L446-L481) of `TestChain` type have been replaced with `IBCClientHeader` 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`](https://github.com/cosmos/ibc-go/blob/v8.0.0/testing/chain.go#L401) has been renamed to [`GetTrustedValidators`](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/testing/chain.go#L403). +- [`AssertEventsLegacy` function](https://github.com/cosmos/ibc-go/blob/v8.0.0/testing/events.go#L140) of `ibctesting` package (alias for `"github.com/cosmos/ibc-go/v9/testing"`) has been removed in [#6070](https://github.com/cosmos/ibc-go/pull/6070), and [`AssertEvents` function](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/testing/events.go#L187) should be used instead. ```diff // testing/events.go @@ -157,31 +237,40 @@ func AssertEvents( ) ``` -- The `QueryServer` interface has been removed from the `TestChain` struct. Submodule query servers can be constructed directly by passing their associated keeper to the appropriate constructor function. For example: +- The [`QueryServer` interface has been removed from the `TestChain` struct](https://github.com/cosmos/ibc-go/blob/v8.0.0/testing/chain.go#L61). Submodule query servers can be constructed directly by passing their associated keeper to the appropriate constructor function. For example: ```golang clientQueryServer := clientkeeper.NewQueryServer(app.IBCKeeper.ClientKeeper) ``` -#### API deprecation notice +### 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`. +- 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 -- Renaming of event attribute keys in [#5603](https://github.com/cosmos/ibc-go/pull/5603). -- Removal of duplicate non-hexlified event attributes in [#6023](https://github.com/cosmos/ibc-go/pull/6023). +### Events -## IBC Light Clients +#### 02-client -### API removals +- The [`header` attribute](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/02-client/keeper/events.go#L60) has been removed from the `update_client` event in [\#5110](https://github.com/cosmos/ibc-go/pull/5110). + +#### 04-channel + +- The constant [`AttributeVersion`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/04-channel/types/events.go#L14) 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](https://github.com/cosmos/ibc-go/pull/6023). The attributes `packet_data_hex` and `packet_ack_hex` should be used instead. The [constants `AttributeKeyData` and `AttributeKeyAck`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/04-channel/types/events.go#L24-L27) have also been removed. -The `ExportMetadata` interface function has been removed from the `ClientState` interface. Core IBC will export all key/value's within the 02-client store. +##### 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](https://github.com/cosmos/ibc-go/pull/6063). -The `ZeroCustomFields` interface function has been removed from the `ClientState` interface. +## IBC Light Clients + +### API removals -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: +- The [`ExportMetadata` interface function](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/exported/client.go#L59) has been removed from the `ClientState` interface. Core IBC will export all key/value's within the 02-client store. +- The [`ZeroCustomFields` interface function](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/exported/client.go#L64) 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| |-----------------------|-----------------------------| @@ -200,24 +289,23 @@ The following functions have also been removed from the `ClientState` interface: |`ExportMetadata` | | |`ZeroCustomFields` | | -Please check also the [Light client developer guide](../03-light-clients/01-developer-guide/01-overview.md) for more information. The light client module implementation for `07-tendermint` may also be useful as reference. +Please check also the [Light client developer guide](../03-light-clients/01-developer-guide/01-overview.md) for more information. The light client module implementation for 07-tendermint may also be useful as reference. ### 06-solomachine -- The `Initialize`, `Status`, `GetTimestampAtHeight` and `UpdateStateOnMisbehaviour` functions in `ClientState` have been removed and all their logic has been moved to functions of the `LightClientModule`. The `VerifyMembership` and `VerifyNonMembership` functions have been made private. -- The `Type` method on `Misbehaviour` has been removed. +- The [`Initialize`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/light-clients/06-solomachine/client_state.go#L85), [`Status`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/light-clients/06-solomachine/client_state.go#L59), [`GetTimestampAtHeight`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/light-clients/06-solomachine/client_state.go#L46) and [`UpdateStateOnMisbehaviour`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/light-clients/06-solomachine/update.go#L105) functions in `ClientState` have been removed and all their logic has been moved to functions of the `LightClientModule`. The [`VerifyMembership`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/light-clients/06-solomachine/client_state.go#L111) and [`VerifyNonMembership`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/light-clients/06-solomachine/client_state.go#L168) functions have been made private. +- The [`Type` method](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/light-clients/06-solomachine/misbehaviour.go#L20) on `Misbehaviour` has been removed. ### 07-tendermint -The `IterateConsensusMetadata` function has been removed. The `VerifyMembership`, `VerifyNonMembership`, `GetTimestampAtHeight`, `Status` and `Initialize` functions have been made private. +- The [`IterateConsensusMetadata` function](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/light-clients/07-tendermint/store.go#L81) has been removed. The [`Initialize`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/light-clients/07-tendermint/client_state.go#L192), [`Status`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/light-clients/07-tendermint/client_state.go#L84), [`GetTimestampAtHeight`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/light-clients/07-tendermint/client_state.go#L62), [`VerifyMembership`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/light-clients/07-tendermint/client_state.go#L209), [`VerifyNonMembership`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/light-clients/07-tendermint/client_state.go#L252) functions have been made private. ### 08-wasm -Refer to the [08-wasm migrations](../03-light-clients/04-wasm/09-migrations.md) for more information. +Refer to the [08-wasm migration documentation](../03-light-clients/04-wasm/09-migrations.md) 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`. +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`. -Previously stored client state data is pruned automatically on IBC module store migration from `ConsensusVersion` 6 to 7. +An [automatic migration handler](https://github.com/cosmos/ibc-go/blob/release/v9.0.x/modules/core/02-client/keeper/migrations.go#L49) is configured to prune all previously stored client state data on IBC module store migration from `ConsensusVersion` 6 to 7.