Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: channel upgrade timeout #5546

Merged
54 changes: 50 additions & 4 deletions docs/docs/01-ibc/06-channel-upgrades.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,17 +55,17 @@ Each handshake step will be documented below in greater detail.

## Initializing a Channel Upgrade

A channel upgrade is initialised by submitting the `ChanUpgradeInit` message, which can be submitted only by the chain itself upon governance authorization. This message should specify an appropriate timeout window for the upgrade. It is possible to upgrade the channel ordering, the channel connection hops, and the channel version.
A channel upgrade is initialised by submitting the `MsgChannelUpgradeInit` message, which can be submitted only by the chain itself upon governance authorization. This message should specify an appropriate timeout window for the upgrade. It is possible to upgrade the channel ordering, the channel connection hops, and the channel version.

As part of the handling of the `ChanUpgradeInit` message, the application's callbacks `OnChanUpgradeInit` will be triggered as well.
As part of the handling of the `MsgChannelUpgradeInit` message, the application's callbacks `OnChanUpgradeInit` will be triggered as well.
crodriguezvega marked this conversation as resolved.
Show resolved Hide resolved

After this message is handled successfully, the channel's upgrade sequence will be incremented. This upgrade sequence will serve as a nonce for the upgrade process to provide replay protection.

### Governance gating on `ChanUpgradeInit`

The message signer for `MsgChanUpgradeInit` must be the address which has been designated as the `authority` of the `IBCKeeper`. If this proposal passes, the counterparty's channel will upgrade by default.
The message signer for `MsgChannelUpgradeInit` must be the address which has been designated as the `authority` of the `IBCKeeper`. If this proposal passes, the counterparty's channel will upgrade by default.

If chains want to initiate the upgrade of many channels, they will need to submit a governance proposal with multiple `MsgChanUpgradeInit` messages, one for each channel they would like to upgrade, again with message signer as the designated `authority` of the `IBCKeeper`
If chains want to initiate the upgrade of many channels, they will need to submit a governance proposal with multiple `MsgChannelUpgradeInit` messages, one for each channel they would like to upgrade, again with message signer as the designated `authority` of the `IBCKeeper`
crodriguezvega marked this conversation as resolved.
Show resolved Hide resolved

## Channel State and Packet Flushing

Expand Down Expand Up @@ -147,6 +147,52 @@ The application's `OnChanUpgradeRestore` callback method will be invoked.

It will then be possible to re-initiate an upgrade by sending a `MsgChannelOpenInit` message.

## Timing Out a Channel Upgrade

Timing out an outstanding channel upgrade may be necessary during the flushing packet stage of the channel upgrade process. As stated above, with `ChanUpgradeTry` or `ChanUpgradeAck`, the channel state has been changed from `OPEN` to `FLUSHING`, so no new packets will be allowed to be sent over this channel while flushing. However, if flushing exceeds the time limit set in the `UpgradeTimeout` channel `Params`, the upgrade process will need to be timed out.
colin-axner marked this conversation as resolved.
Show resolved Hide resolved

Timing out an outstanding upgrade is performed by first setting a timeout in the channel `Params` before submitting a `MsgChannelUpgradeTry` or `MsgChannelUpgradeAck` message (by default, 10 minutes):
charleenfei marked this conversation as resolved.
Show resolved Hide resolved

```go
type Params struct {
UpgradeTimeout Timeout
}
```

A valid Timeout contains either one or both of a timestamp and block height (sequence).
charleenfei marked this conversation as resolved.
Show resolved Hide resolved

```go
type Timeout struct {
// block height after which the packet or upgrade times out
Height types.Height
// block timestamp (in nanoseconds) after which the packet or upgrade times out
Timestamp uint64
}
```

This timeout will then be set as a field on the `Upgrade` struct itself when flushing is started.

```go
type Upgrade struct {
Fields UpgradeFields
Timeout Timeout
NextSequenceSend uint64
}
```

If the timeout has been exceeded during flushing, a chain can then submit the `MsgChannelUpgradeTimeout` to timeout the channel upgrade process and restore the previous channel state:
charleenfei marked this conversation as resolved.
Show resolved Hide resolved

```go
type MsgChannelUpgradeTimeout struct {
PortId string
ChannelId string
CounterpartyChannel Channel
ProofChannel []byte
ProofHeight types.Height
Signer string
}
```

## IBC App Recommendations

IBC application callbacks should be primarily used to validate data fields and do compatibility checks.
Expand Down
Loading