diff --git a/docs/docs/01-ibc/01-overview.md b/docs/docs/01-ibc/01-overview.md index 73c755d18a8..fa2abcaaf21 100644 --- a/docs/docs/01-ibc/01-overview.md +++ b/docs/docs/01-ibc/01-overview.md @@ -217,15 +217,27 @@ handshake; either `OnChanOpenInit` on the initializing chain or `OnChanOpenTry` #### Closing channels Closing a channel occurs in 2 handshake steps as defined in [ICS 04](https://github.com/cosmos/ibc/tree/master/spec/core/ics-004-channel-and-packet-semantics). +Once a channel is closed, it cannot be reopened. The channel handshake steps are: -`ChanCloseInit` closes a channel on the executing chain if the channel exists, it is not -already closed and the connection it exists upon is OPEN. Channels can only be closed by a -calling module or in the case of a packet timeout on an ORDERED channel. +**`ChanCloseInit`** closes a channel on the executing chain if -`ChanCloseConfirm` is a response to a counterparty channel executing `ChanCloseInit`. The channel -on the executing chain closes if the channel exists, the channel is not already closed, -the connection the channel exists upon is OPEN and the executing chain successfully verifies -that the counterparty channel has been closed. +- the channel exists and it is not already closed, +- the connection it exists upon is OPEN, +- the [IBC module callback `OnChanCloseInit`](./03-apps/02-ibcmodule.md#channel-closing-callbacks) returns `nil`. + +`ChanCloseInit` can be initiated by any user by submitting a `MsgChannelCloseInit` transaction. +Note that channels are automatically closed when a packet times out on an `ORDERED` channel. +A timeout on an `ORDERED` channel skips the `ChanCloseInit` step and immediately closes the channel. + +**`ChanCloseConfirm`** is a response to a counterparty channel executing `ChanCloseInit`. The channel +on the executing chain closes if + +- the channel exists and is not already closed, +- the connection the channel exists upon is OPEN, +- the executing chain successfully verifies that the counterparty channel has been closed +- the [IBC module callback `OnChanCloseConfirm`](./03-apps/02-ibcmodule.md#channel-closing-callbacks) returns `nil`. + +Currently, none of the IBC applications provided in ibc-go support `ChanCloseInit`. ### [Packets](https://github.com/cosmos/ibc-go/blob/main/modules/core/04-channel) diff --git a/docs/docs/01-ibc/03-apps/02-ibcmodule.md b/docs/docs/01-ibc/03-apps/02-ibcmodule.md index d128612fab2..0a632590a6a 100644 --- a/docs/docs/01-ibc/03-apps/02-ibcmodule.md +++ b/docs/docs/01-ibc/03-apps/02-ibcmodule.md @@ -141,8 +141,12 @@ func (im IBCModule) OnChanOpenConfirm( } ``` +### Channel closing callbacks + The channel closing handshake will also invoke module callbacks that can return errors to abort the closing handshake. Closing a channel is a 2-step handshake, the initiating chain calls `ChanCloseInit` and the finalizing chain calls `ChanCloseConfirm`. +Currently, all IBC modules in this repository return an error for `OnChanCloseInit` to prevent the channels from closing. This is because any user can call `ChanCloseInit` by submitting a `MsgChannelCloseInit` transaction. + ```go // Called by IBC Handler on MsgCloseInit func (im IBCModule) OnChanCloseInit( diff --git a/docs/docs/02-apps/01-transfer/01-overview.md b/docs/docs/02-apps/01-transfer/01-overview.md index 7e257d1e805..da8595c7e88 100644 --- a/docs/docs/02-apps/01-transfer/01-overview.md +++ b/docs/docs/02-apps/01-transfer/01-overview.md @@ -126,3 +126,7 @@ form. For safety, no other module must be capable of minting tokens with the `ibc/` prefix. The IBC transfer module needs a subset of the denomination space that only it can create tokens in. + +## Channel Closure + +The IBC transfer module does not support channel closure. diff --git a/docs/docs/02-apps/02-interchain-accounts/01-overview.md b/docs/docs/02-apps/02-interchain-accounts/01-overview.md index e8edada979f..42e5c6345fd 100644 --- a/docs/docs/02-apps/02-interchain-accounts/01-overview.md +++ b/docs/docs/02-apps/02-interchain-accounts/01-overview.md @@ -37,3 +37,8 @@ SDK modules on a chain are assumed to be trustworthy. For example, there are no The implementation of ICS-27 in ibc-go uses this assumption in its security considerations. The implementation assumes other IBC application modules will not bind to ports within the ICS-27 namespace. + +## Channel Closure + +The provided interchain account host and controller implementations do not support `ChanCloseInit`. However, they do support `ChanCloseConfirm`. +This means that the host and controller modules cannot close channels, but they will confirm channel closures initiated by other implementations of ICS-27.