changelog and migration docs for #6960

CHANGELOG.md

@@ -74,6 +74,7 @@ Ref: https://keepachangelog.com/en/1.0.0/
 * (core/types) [\#6794](https://github.com/cosmos/ibc-go/pull/6794) The composite interface `QueryServer` has been removed from package `core/types`. Please use the granular `QueryServer` interfaces provided by each core submodule.
 * (light-clients/06-solomachine) [\#6888](https://github.com/cosmos/ibc-go/pull/6888) Remove `TypeClientMisbehaviour` constant and the `Type` method on `Misbehaviour`.
 * (light-clients/06-solomachine, light-clients/07-tendermint) [\#6891](https://github.com/cosmos/ibc-go/pull/6891) The `VerifyMembership` and `VerifyNonMembership` functions of solomachine's `ClientState` have been made private. The `VerifyMembership`, `VerifyNonMembership`, `GetTimestampAtHeight`, `Status` and `Initialize` functions of tendermint's `ClientState` have been made private.
+* (core/04-channel) [\#6902](https://github.com/cosmos/ibc-go/pull/6902) Add channel version to core application callbacks.
 
 ### State Machine Breaking
 

docs/docs/05-migrations/13-v8-to-v9.md

@@ -106,6 +106,74 @@ func (k *Keeper) TimeoutOnClose(
 ) 
 ```
 
+- The keeper handlers `RecvPacket`, `AcknowledgePacket`, `TimeoutPacket` and `TimeoutOnClose` return now the channel version, which the message server passes to the packet lifecycle application callbacks (`OnRecvPacket`, `OnAcknowledgementPacket` and `OnTimeoutPacket`). The channel version is useful when adding backwards compatible features to an existing application implementation (for example: in the context of ICS20 v2, middleware and the transfer application may use the channel version to unmarshal the packet differently depending on the channel version).
+
+```diff
+func (k *Keeper) RecvPacket(
+  ctx sdk.Context,
+  chanCap *capabilitytypes.Capability,
+  packet types.Packet,
+  proof []byte,
+  proofHeight exported.Height,
+- ) error { 
++ ) (string, error) {
+
+func (k *Keeper) AcknowledgePacket(
+  ctx sdk.Context,
+  chanCap *capabilitytypes.Capability,
+  packet types.Packet,
+  acknowledgement []byte,
+  proof []byte,
+  proofHeight exported.Height,
+- ) error {
++ ) (string, error) {
+
+func (k *Keeper) TimeoutPacket(
+  ctx sdk.Context,
+  packet types.Packet,
+  proof []byte,
+  proofHeight exported.Height,
+  nextSequenceRecv uint64,
+- ) error {
++ ) (string, error) {
+
+func (k *Keeper) TimeoutOnClose(
+  ctx sdk.Context,
+  chanCap *capabilitytypes.Capability,
+  packet types.Packet,
+  proof,
+  closedProof []byte,
+  proofHeight exported.Height,
+  nextSequenceRecv uint64,
+  counterpartyUpgradeSequence uint64,
+- ) error {
++ ) (string, error) {
+```
+
+```diff
+OnRecvPacket func(
+  ctx sdk.Context,
++ channelVersion string,
+  packet channeltypes.Packet,
+  relayer sdk.AccAddress,
+) exported.Acknowledgement
+
+OnAcknowledgementPacket func(
+  ctx sdk.Context,
++ channelVersion string,
+  packet channeltypes.Packet,
+  acknowledgement []byte,
+  relayer sdk.AccAddress,
+) error
+
+OnTimeoutPacket func(
+  ctx sdk.Context,
++ channelVersion string,
+  packet channeltypes.Packet,
+  relayer sdk.AccAddress,
+) error
+```
+
 ### 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: