From 84c9ad8af1b016d3b48fe62cc967c4cbfee6434e Mon Sep 17 00:00:00 2001
From: Carlos Rodriguez <carlos@interchain.io>
Date: Mon, 29 Jul 2024 11:29:52 +0200
Subject: [PATCH] docs: changelog and migration docs for #6960 (#6973)

* changelog and migration docs for #6960

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

---------

Co-authored-by: DimitrisJim <d.f.hilliard@gmail.com>
---
 CHANGELOG.md                           |  1 +
 docs/docs/05-migrations/13-v8-to-v9.md | 68 ++++++++++++++++++++++++++
 2 files changed, 69 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a6fda2ae855..f79930b0594 100644
--- a/CHANGELOG.md
+++ b/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
 
diff --git a/docs/docs/05-migrations/13-v8-to-v9.md b/docs/docs/05-migrations/13-v8-to-v9.md
index 73013c092bf..0e77dda94bb 100644
--- a/docs/docs/05-migrations/13-v8-to-v9.md
+++ b/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` now return 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: