From 56b04c46e72bf300c25219f0bb41526917f81bac Mon Sep 17 00:00:00 2001 From: Charly Date: Fri, 8 Dec 2023 14:54:59 +0100 Subject: [PATCH 01/10] reasoning and use cases --- docs/docs/01-ibc/06-channel-upgrades.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/docs/01-ibc/06-channel-upgrades.md b/docs/docs/01-ibc/06-channel-upgrades.md index 6bbbc6ff515..38ea08635cc 100644 --- a/docs/docs/01-ibc/06-channel-upgrades.md +++ b/docs/docs/01-ibc/06-channel-upgrades.md @@ -11,6 +11,12 @@ slug: /ibc/channel-upgrades Learn how to upgrade existing IBC channels. ::: +Channel upgradeability is an IBC-level protocol that allows chains to leverage new channel features without having to create new channels or perform a network-wide upgrade. Prior to this feature, developers who wanted to update an application module or add a middleware to their application flow would need to negotiate a new channel in order to use the updated application feature/middleware, resulting in a loss of the accumulated state/liquidity, token fungibility (as the channel would have been encoded in the IBC denom), and any other larger network effects of losing usage of the existing channel from relayers monitoring, etc. + +With channel upgradeability, applications will be able to implement features such as but not limited to: [including a memo field in the packet data for fungible tokens](https://github.com/cosmos/ibc/pull/842), adding [denom metadata to tokens](https://github.com/cosmos/ibc/discussions/719), or utilizing the [fee middleware](https://github.com/cosmos/ibc/tree/main/spec/app/ics-029-fee-payment), all while maintaining the channels on which they currently operate. + +This document outlines the channel upgrade feature, and the multiple steps used in the upgrade process. + ## Cancelling a Channel Upgrade Channel upgrade cancellation is performed by submitting a `MsgChannelUpgradeCancel` message. From 9c1c3e80bdc49a8c675c9a28708445c4eb14be9b Mon Sep 17 00:00:00 2001 From: Charly Date: Fri, 8 Dec 2023 14:57:27 +0100 Subject: [PATCH 02/10] overview channel handshake --- docs/docs/01-ibc/06-channel-upgrades.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/docs/01-ibc/06-channel-upgrades.md b/docs/docs/01-ibc/06-channel-upgrades.md index 38ea08635cc..8dca6d45d29 100644 --- a/docs/docs/01-ibc/06-channel-upgrades.md +++ b/docs/docs/01-ibc/06-channel-upgrades.md @@ -17,6 +17,19 @@ With channel upgradeability, applications will be able to implement features suc This document outlines the channel upgrade feature, and the multiple steps used in the upgrade process. +## Channel Upgrade Handshake + +Channel upgrades will be initialized using a handshake process that is designed to be similar to the standard connection/channel opening handshake. + +On a high level, successful handshake process for channel upgrades works as follows: + +1. The chain initiating the upgrade process (chain A) sets its channel state from `OPEN` to `INITUPGRADE` via the `ChanUpgradeInit` function. +2. Subsequently, the counterparty (chain B) changes its channel end from `OPEN` to `TRYUPGRADE` with `ChanUpgradeTry`. +3. Upon successful completion of the previous step, chain A sets its channel state to `OPEN` with `ChanUpgradeAck`. +4. Finally, chain B sets its channel state to `OPEN` with `ChanUpgradeConfirm`. + +Each handshake step will be documented below in greater detail. + ## Cancelling a Channel Upgrade Channel upgrade cancellation is performed by submitting a `MsgChannelUpgradeCancel` message. From d5741cd9f5edf7d6a0787c34895db5d5512e40d5 Mon Sep 17 00:00:00 2001 From: Charly Date: Fri, 8 Dec 2023 17:48:43 +0100 Subject: [PATCH 03/10] add spec upgrade field info --- docs/docs/01-ibc/06-channel-upgrades.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/docs/01-ibc/06-channel-upgrades.md b/docs/docs/01-ibc/06-channel-upgrades.md index 8dca6d45d29..309532dbddf 100644 --- a/docs/docs/01-ibc/06-channel-upgrades.md +++ b/docs/docs/01-ibc/06-channel-upgrades.md @@ -11,7 +11,9 @@ slug: /ibc/channel-upgrades Learn how to upgrade existing IBC channels. ::: -Channel upgradeability is an IBC-level protocol that allows chains to leverage new channel features without having to create new channels or perform a network-wide upgrade. Prior to this feature, developers who wanted to update an application module or add a middleware to their application flow would need to negotiate a new channel in order to use the updated application feature/middleware, resulting in a loss of the accumulated state/liquidity, token fungibility (as the channel would have been encoded in the IBC denom), and any other larger network effects of losing usage of the existing channel from relayers monitoring, etc. +Channel upgradeability is an IBC-level protocol that allows chains to leverage new channel features without having to create new channels or perform a network-wide upgrade. + +Prior to this feature, developers who wanted to update an application module or add a middleware to their application flow would need to negotiate a new channel in order to use the updated application feature/middleware, resulting in a loss of the accumulated state/liquidity, token fungibility (as the channel would have been encoded in the IBC denom), and any other larger network effects of losing usage of the existing channel from relayers monitoring, etc. With channel upgradeability, applications will be able to implement features such as but not limited to: [including a memo field in the packet data for fungible tokens](https://github.com/cosmos/ibc/pull/842), adding [denom metadata to tokens](https://github.com/cosmos/ibc/discussions/719), or utilizing the [fee middleware](https://github.com/cosmos/ibc/tree/main/spec/app/ics-029-fee-payment), all while maintaining the channels on which they currently operate. @@ -21,6 +23,25 @@ This document outlines the channel upgrade feature, and the multiple steps used Channel upgrades will be initialized using a handshake process that is designed to be similar to the standard connection/channel opening handshake. +```go +interface ChannelEnd { + state: ChannelState + ordering: ChannelOrder + counterpartyPortIdentifier: Identifier + counterpartyChannelIdentifier: Identifier + connectionHops: [Identifier] + version: string + upgradeSequence: uint64 +} +``` + +Anything within this channel end interface except the identifiers (counterparty port ID and channel ID) can be changed — such as the version, connection hops, and channel ordering. For example, the fee middleware can be added to an application module by updating the version string [shown here](https://github.com/cosmos/ibc-go/blob/995b647381b909e9d6065d6c21004f18fab37f55/modules/apps/29-fee/types/metadata.pb.go#L28). + +There a few caveats for the changes in the channel end fields: + +1. Connection hops can change in a channel upgrade, however both sides must still be each other's counterparty. +2. The channel ordering can only be upgraded if the new ordering is a subset of its previous one. This means that a channel can be upgraded from an ordered to an unordered channel but not the other way around. + On a high level, successful handshake process for channel upgrades works as follows: 1. The chain initiating the upgrade process (chain A) sets its channel state from `OPEN` to `INITUPGRADE` via the `ChanUpgradeInit` function. From 2c0df5cc8e19f1e35dfa6bf15f3598d8c28dd9f4 Mon Sep 17 00:00:00 2001 From: Charly Date: Mon, 11 Dec 2023 10:17:07 +0100 Subject: [PATCH 04/10] fix docs --- docs/docs/01-ibc/06-channel-upgrades.md | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/docs/docs/01-ibc/06-channel-upgrades.md b/docs/docs/01-ibc/06-channel-upgrades.md index 309532dbddf..7d91625af15 100644 --- a/docs/docs/01-ibc/06-channel-upgrades.md +++ b/docs/docs/01-ibc/06-channel-upgrades.md @@ -15,7 +15,7 @@ Channel upgradeability is an IBC-level protocol that allows chains to leverage n Prior to this feature, developers who wanted to update an application module or add a middleware to their application flow would need to negotiate a new channel in order to use the updated application feature/middleware, resulting in a loss of the accumulated state/liquidity, token fungibility (as the channel would have been encoded in the IBC denom), and any other larger network effects of losing usage of the existing channel from relayers monitoring, etc. -With channel upgradeability, applications will be able to implement features such as but not limited to: [including a memo field in the packet data for fungible tokens](https://github.com/cosmos/ibc/pull/842), adding [denom metadata to tokens](https://github.com/cosmos/ibc/discussions/719), or utilizing the [fee middleware](https://github.com/cosmos/ibc/tree/main/spec/app/ics-029-fee-payment), all while maintaining the channels on which they currently operate. +With channel upgradeability, applications will be able to implement features such as but not limited to: potentially adding [denom metadata to tokens](https://github.com/cosmos/ibc/discussions/719), or utilizing the [fee middleware](https://github.com/cosmos/ibc/tree/main/spec/app/ics-029-fee-payment), all while maintaining the channels on which they currently operate. This document outlines the channel upgrade feature, and the multiple steps used in the upgrade process. @@ -35,19 +35,14 @@ interface ChannelEnd { } ``` -Anything within this channel end interface except the identifiers (counterparty port ID and channel ID) can be changed — such as the version, connection hops, and channel ordering. For example, the fee middleware can be added to an application module by updating the version string [shown here](https://github.com/cosmos/ibc-go/blob/995b647381b909e9d6065d6c21004f18fab37f55/modules/apps/29-fee/types/metadata.pb.go#L28). - -There a few caveats for the changes in the channel end fields: - -1. Connection hops can change in a channel upgrade, however both sides must still be each other's counterparty. -2. The channel ordering can only be upgraded if the new ordering is a subset of its previous one. This means that a channel can be upgraded from an ordered to an unordered channel but not the other way around. +Anything within this channel end interface except the identifiers (counterparty port ID and channel ID) can be changed — such as the version, connection hops, and channel ordering. For example, the fee middleware can be added to an application module by updating the version string [shown here](https://github.com/cosmos/ibc-go/blob/995b647381b909e9d6065d6c21004f18fab37f55/modules/apps/29-fee/types/metadata.pb.go#L28). However, although connection hops can change in a channel upgrade, both sides must still be each other's counterparty. On a high level, successful handshake process for channel upgrades works as follows: -1. The chain initiating the upgrade process (chain A) sets its channel state from `OPEN` to `INITUPGRADE` via the `ChanUpgradeInit` function. -2. Subsequently, the counterparty (chain B) changes its channel end from `OPEN` to `TRYUPGRADE` with `ChanUpgradeTry`. -3. Upon successful completion of the previous step, chain A sets its channel state to `OPEN` with `ChanUpgradeAck`. -4. Finally, chain B sets its channel state to `OPEN` with `ChanUpgradeConfirm`. +1. The chain initiating the upgrade process (chain A) submits the `ChanUpgradeInit` function. +2. Subsequently, the counterparty (chain B) changes its channel end from `OPEN` to `FLUSHING` with `ChanUpgradeTry`. +3. Upon successful completion of the previous step, chain A sets its channel state from `OPEN` to `FLUSHING` or `FLUSHCOMPLETE` with `ChanUpgradeAck` depending on the packet flushing status +4. Finally, chain B sets its channel state to `FLUSHCOMPLETE` when its packet flush is finished, and then `OPEN` with `ChanUpgradeConfirm`. Each handshake step will be documented below in greater detail. @@ -62,7 +57,7 @@ It is possible for the authority to cancel an in-progress channel upgrade if the - If the channel state has reached FLUSHCOMPLETE, an existence proof of an `ErrorReceipt` on the counterparty chain is provided at our upgrade sequence or greater It is possible for a relayer to cancel an in-progress channel upgrade if the following are true: -- An existence proof of an `ErrorReceipt` on the counterparty chain is provided at our upgrade sequence or greater +- An existence proof of an `ErrorReceipt` on the counterparty chain is provided at our upgrade sequence or gr eater > Note: if the signer is the authority, e.g. the `gov` address, no `ErrorReceipt` or proof is required if the current channel state is not in FLUSHCOMPLETE. > These can be left empty in the `MsgChannelUpgradeCancel` message in that case. From 75ef037ae40455759cdbcd29b735186f696deb5a Mon Sep 17 00:00:00 2001 From: Charly Date: Mon, 11 Dec 2023 10:17:53 +0100 Subject: [PATCH 05/10] spelling --- docs/docs/01-ibc/06-channel-upgrades.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/01-ibc/06-channel-upgrades.md b/docs/docs/01-ibc/06-channel-upgrades.md index 7d91625af15..5c73032e845 100644 --- a/docs/docs/01-ibc/06-channel-upgrades.md +++ b/docs/docs/01-ibc/06-channel-upgrades.md @@ -11,11 +11,11 @@ slug: /ibc/channel-upgrades Learn how to upgrade existing IBC channels. ::: -Channel upgradeability is an IBC-level protocol that allows chains to leverage new channel features without having to create new channels or perform a network-wide upgrade. +Channel upgradability is an IBC-level protocol that allows chains to leverage new channel features without having to create new channels or perform a network-wide upgrade. Prior to this feature, developers who wanted to update an application module or add a middleware to their application flow would need to negotiate a new channel in order to use the updated application feature/middleware, resulting in a loss of the accumulated state/liquidity, token fungibility (as the channel would have been encoded in the IBC denom), and any other larger network effects of losing usage of the existing channel from relayers monitoring, etc. -With channel upgradeability, applications will be able to implement features such as but not limited to: potentially adding [denom metadata to tokens](https://github.com/cosmos/ibc/discussions/719), or utilizing the [fee middleware](https://github.com/cosmos/ibc/tree/main/spec/app/ics-029-fee-payment), all while maintaining the channels on which they currently operate. +With channel upgradability, applications will be able to implement features such as but not limited to: potentially adding [denom metadata to tokens](https://github.com/cosmos/ibc/discussions/719), or utilizing the [fee middleware](https://github.com/cosmos/ibc/tree/main/spec/app/ics-029-fee-payment), all while maintaining the channels on which they currently operate. This document outlines the channel upgrade feature, and the multiple steps used in the upgrade process. From f1284f408d2d13a93e75bfb13aee8162428f658a Mon Sep 17 00:00:00 2001 From: Charly Date: Mon, 11 Dec 2023 10:25:07 +0100 Subject: [PATCH 06/10] update with channel struct --- docs/docs/01-ibc/06-channel-upgrades.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/docs/docs/01-ibc/06-channel-upgrades.md b/docs/docs/01-ibc/06-channel-upgrades.md index 5c73032e845..0bd87b40f0b 100644 --- a/docs/docs/01-ibc/06-channel-upgrades.md +++ b/docs/docs/01-ibc/06-channel-upgrades.md @@ -24,18 +24,25 @@ This document outlines the channel upgrade feature, and the multiple steps used Channel upgrades will be initialized using a handshake process that is designed to be similar to the standard connection/channel opening handshake. ```go -interface ChannelEnd { - state: ChannelState - ordering: ChannelOrder - counterpartyPortIdentifier: Identifier - counterpartyChannelIdentifier: Identifier - connectionHops: [Identifier] - version: string - upgradeSequence: uint64 +type Channel struct { + // current state of the channel end + State State `protobuf:"varint,1,opt,name=state,proto3,enum=ibc.core.channel.v1.State" json:"state,omitempty"` + // whether the channel is ordered or unordered + Ordering Order `protobuf:"varint,2,opt,name=ordering,proto3,enum=ibc.core.channel.v1.Order" json:"ordering,omitempty"` + // counterparty channel end + Counterparty Counterparty `protobuf:"bytes,3,opt,name=counterparty,proto3" json:"counterparty"` + // list of connection identifiers, in order, along which packets sent on + // this channel will travel + ConnectionHops []string `protobuf:"bytes,4,rep,name=connection_hops,json=connectionHops,proto3" json:"connection_hops,omitempty"` + // opaque channel version, which is agreed upon during the handshake + Version string `protobuf:"bytes,5,opt,name=version,proto3" json:"version,omitempty"` + // upgrade sequence indicates the latest upgrade attempt performed by this channel + // the value of 0 indicates the channel has never been upgraded + UpgradeSequence uint64 `protobuf:"varint,6,opt,name=upgrade_sequence,json=upgradeSequence,proto3" json:"upgrade_sequence,omitempty"` } ``` -Anything within this channel end interface except the identifiers (counterparty port ID and channel ID) can be changed — such as the version, connection hops, and channel ordering. For example, the fee middleware can be added to an application module by updating the version string [shown here](https://github.com/cosmos/ibc-go/blob/995b647381b909e9d6065d6c21004f18fab37f55/modules/apps/29-fee/types/metadata.pb.go#L28). However, although connection hops can change in a channel upgrade, both sides must still be each other's counterparty. +The version, connection hops, and channel ordering are fields in this channel struct which can be changed. For example, the fee middleware can be added to an application module by updating the version string [shown here](https://github.com/cosmos/ibc-go/blob/995b647381b909e9d6065d6c21004f18fab37f55/modules/apps/29-fee/types/metadata.pb.go#L28). However, although connection hops can change in a channel upgrade, both sides must still be each other's counterparty. On a high level, successful handshake process for channel upgrades works as follows: From f6eff04b009933e4a5bfebb1d6a929715ba84fb0 Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Wed, 13 Dec 2023 11:40:51 +0100 Subject: [PATCH 07/10] reduce code indentation --- docs/docs/01-ibc/06-channel-upgrades.md | 28 ++++++++++++------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/docs/01-ibc/06-channel-upgrades.md b/docs/docs/01-ibc/06-channel-upgrades.md index 31d13dee9cb..9c8a2dcce63 100644 --- a/docs/docs/01-ibc/06-channel-upgrades.md +++ b/docs/docs/01-ibc/06-channel-upgrades.md @@ -25,20 +25,20 @@ Channel upgrades will be initialized using a handshake process that is designed ```go type Channel struct { - // current state of the channel end - State State `protobuf:"varint,1,opt,name=state,proto3,enum=ibc.core.channel.v1.State" json:"state,omitempty"` - // whether the channel is ordered or unordered - Ordering Order `protobuf:"varint,2,opt,name=ordering,proto3,enum=ibc.core.channel.v1.Order" json:"ordering,omitempty"` - // counterparty channel end - Counterparty Counterparty `protobuf:"bytes,3,opt,name=counterparty,proto3" json:"counterparty"` - // list of connection identifiers, in order, along which packets sent on - // this channel will travel - ConnectionHops []string `protobuf:"bytes,4,rep,name=connection_hops,json=connectionHops,proto3" json:"connection_hops,omitempty"` - // opaque channel version, which is agreed upon during the handshake - Version string `protobuf:"bytes,5,opt,name=version,proto3" json:"version,omitempty"` - // upgrade sequence indicates the latest upgrade attempt performed by this channel - // the value of 0 indicates the channel has never been upgraded - UpgradeSequence uint64 `protobuf:"varint,6,opt,name=upgrade_sequence,json=upgradeSequence,proto3" json:"upgrade_sequence,omitempty"` + // current state of the channel end + State State `protobuf:"varint,1,opt,name=state,proto3,enum=ibc.core.channel.v1.State" json:"state,omitempty"` + // whether the channel is ordered or unordered + Ordering Order `protobuf:"varint,2,opt,name=ordering,proto3,enum=ibc.core.channel.v1.Order" json:"ordering,omitempty"` + // counterparty channel end + Counterparty Counterparty `protobuf:"bytes,3,opt,name=counterparty,proto3" json:"counterparty"` + // list of connection identifiers, in order, along which packets sent on + // this channel will travel + ConnectionHops []string `protobuf:"bytes,4,rep,name=connection_hops,json=connectionHops,proto3" json:"connection_hops,omitempty"` + // opaque channel version, which is agreed upon during the handshake + Version string `protobuf:"bytes,5,opt,name=version,proto3" json:"version,omitempty"` + // upgrade sequence indicates the latest upgrade attempt performed by this channel + // the value of 0 indicates the channel has never been upgraded + UpgradeSequence uint64 `protobuf:"varint,6,opt,name=upgrade_sequence,json=upgradeSequence,proto3" json:"upgrade_sequence,omitempty"` } ``` From 744509db60d014249a0f1797029df03d5560ff7c Mon Sep 17 00:00:00 2001 From: Charly Date: Thu, 14 Dec 2023 14:43:13 +0100 Subject: [PATCH 08/10] pr review --- docs/docs/01-ibc/06-channel-upgrades.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/01-ibc/06-channel-upgrades.md b/docs/docs/01-ibc/06-channel-upgrades.md index 9c8a2dcce63..35687e76877 100644 --- a/docs/docs/01-ibc/06-channel-upgrades.md +++ b/docs/docs/01-ibc/06-channel-upgrades.md @@ -13,7 +13,7 @@ Learn how to upgrade existing IBC channels. Channel upgradability is an IBC-level protocol that allows chains to leverage new channel features without having to create new channels or perform a network-wide upgrade. -Prior to this feature, developers who wanted to update an application module or add a middleware to their application flow would need to negotiate a new channel in order to use the updated application feature/middleware, resulting in a loss of the accumulated state/liquidity, token fungibility (as the channel would have been encoded in the IBC denom), and any other larger network effects of losing usage of the existing channel from relayers monitoring, etc. +Prior to this feature, developers who wanted to update an application module or add a middleware to their application flow would need to create a new channel in order to use the updated application feature/middleware, resulting in a loss of the accumulated state/liquidity, token fungibility (as the channel ID is encoded in the IBC denom), and any other larger network effects of losing usage of the existing channel from relayers monitoring, etc. With channel upgradability, applications will be able to implement features such as but not limited to: potentially adding [denom metadata to tokens](https://github.com/cosmos/ibc/discussions/719), or utilizing the [fee middleware](https://github.com/cosmos/ibc/tree/main/spec/app/ics-029-fee-payment), all while maintaining the channels on which they currently operate. @@ -46,10 +46,10 @@ The version, connection hops, and channel ordering are fields in this channel st On a high level, successful handshake process for channel upgrades works as follows: -1. The chain initiating the upgrade process (chain A) submits the `ChanUpgradeInit` function. -2. Subsequently, the counterparty (chain B) changes its channel end from `OPEN` to `FLUSHING` with `ChanUpgradeTry`. -3. Upon successful completion of the previous step, chain A sets its channel state from `OPEN` to `FLUSHING` or `FLUSHCOMPLETE` with `ChanUpgradeAck` depending on the packet flushing status -4. Finally, chain B sets its channel state to `FLUSHCOMPLETE` when its packet flush is finished, and then `OPEN` with `ChanUpgradeConfirm`. +1. The chain initiating the upgrade process will propose a potential upgrade. +2. If the counterparty agrees with the proposal, it will block sends and begin flushing its channel end. +3. Upon successful completion of the previous step, the initiating chain will also block packet sends and begin flushing its channel end. +4. Once both channel ends have completely flushed before either upgrade timeout has elapsed, both channel ends can be opened and upgraded to the new channel fields. Each handshake step will be documented below in greater detail. From cc59fb77ee62f6bbe023a15c08f55bb270d5bc75 Mon Sep 17 00:00:00 2001 From: Charly Date: Mon, 18 Dec 2023 17:28:36 +0100 Subject: [PATCH 09/10] pr reviews --- docs/docs/01-ibc/06-channel-upgrades.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/01-ibc/06-channel-upgrades.md b/docs/docs/01-ibc/06-channel-upgrades.md index 210b8b5c17b..2c56d3b113b 100644 --- a/docs/docs/01-ibc/06-channel-upgrades.md +++ b/docs/docs/01-ibc/06-channel-upgrades.md @@ -11,7 +11,7 @@ slug: /ibc/channel-upgrades Learn how to upgrade existing IBC channels. ::: -Channel upgradability is an IBC-level protocol that allows chains to leverage new channel features without having to create new channels or perform a network-wide upgrade. +Channel upgradability is an IBC-level protocol that allows chains to leverage new application and channel features without having to create new channels or perform a network-wide upgrade. Prior to this feature, developers who wanted to update an application module or add a middleware to their application flow would need to create a new channel in order to use the updated application feature/middleware, resulting in a loss of the accumulated state/liquidity, token fungibility (as the channel ID is encoded in the IBC denom), and any other larger network effects of losing usage of the existing channel from relayers monitoring, etc. @@ -42,14 +42,14 @@ type Channel struct { } ``` -The version, connection hops, and channel ordering are fields in this channel struct which can be changed. For example, the fee middleware can be added to an application module by updating the version string [shown here](https://github.com/cosmos/ibc-go/blob/995b647381b909e9d6065d6c21004f18fab37f55/modules/apps/29-fee/types/metadata.pb.go#L28). However, although connection hops can change in a channel upgrade, both sides must still be each other's counterparty. +The version, connection hops, and channel ordering are fields in this channel struct which can be changed. For example, the fee middleware can be added to an application module by updating the version string [shown here](https://github.com/cosmos/ibc-go/blob/995b647381b909e9d6065d6c21004f18fab37f55/modules/apps/29-fee/types/metadata.pb.go#L28). However, although connection hops can change in a channel upgrade, both sides must still be each other's counterparty. This is enforced by the upgrade protocol and upgrade attempts which try to alter an expected counterparty will fail. On a high level, successful handshake process for channel upgrades works as follows: 1. The chain initiating the upgrade process will propose a potential upgrade. -2. If the counterparty agrees with the proposal, it will block sends and begin flushing its channel end. -3. Upon successful completion of the previous step, the initiating chain will also block packet sends and begin flushing its channel end. -4. Once both channel ends have completely flushed before either upgrade timeout has elapsed, both channel ends can be opened and upgraded to the new channel fields. +2. If the counterparty agrees with the proposal, it will block sends and begin flushing any in-flight packets on its channel end. This flushing process will be covered in more detail below. +3. Upon successful completion of the previous step, the initiating chain will also block packet sends and begin flushing any in-flight packets on its channel end. +4. Once both channel ends have completed flushing packets within the upgrade timeout window, both channel ends can be opened and upgraded to the new channel fields. Each handshake step will be documented below in greater detail. From 703d569ecaa9a34c8c1f32a8f58c96b4d5e51127 Mon Sep 17 00:00:00 2001 From: Charly Date: Mon, 18 Dec 2023 17:29:58 +0100 Subject: [PATCH 10/10] nits --- docs/docs/01-ibc/06-channel-upgrades.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/01-ibc/06-channel-upgrades.md b/docs/docs/01-ibc/06-channel-upgrades.md index 2c56d3b113b..6bc445b2bc7 100644 --- a/docs/docs/01-ibc/06-channel-upgrades.md +++ b/docs/docs/01-ibc/06-channel-upgrades.md @@ -21,7 +21,7 @@ This document outlines the channel upgrade feature, and the multiple steps used ## Channel Upgrade Handshake -Channel upgrades will be initialized using a handshake process that is designed to be similar to the standard connection/channel opening handshake. +Channel upgrades will be achieved using a handshake process that is designed to be similar to the standard connection/channel opening handshake. ```go type Channel struct { @@ -46,7 +46,7 @@ The version, connection hops, and channel ordering are fields in this channel st On a high level, successful handshake process for channel upgrades works as follows: -1. The chain initiating the upgrade process will propose a potential upgrade. +1. The chain initiating the upgrade process will propose an upgrade. 2. If the counterparty agrees with the proposal, it will block sends and begin flushing any in-flight packets on its channel end. This flushing process will be covered in more detail below. 3. Upon successful completion of the previous step, the initiating chain will also block packet sends and begin flushing any in-flight packets on its channel end. 4. Once both channel ends have completed flushing packets within the upgrade timeout window, both channel ends can be opened and upgraded to the new channel fields.