Merge branch 'main' into carlos/ica-channel-timeout-after-upgrade

RELEASES.md

@@ -58,26 +58,36 @@ A release should not be finalized until the development team and the external co
 
 The beginning of a new major release series is marked by the release of a new major version. A major release series is comprised of all minor and patch releases made under the same major version number. The series continues to receive bug fixes (released as minor or patch releases) until it reaches end of life. The date when a major release series reaches end of life is determined by one of the two following methods:
 
-- If the next major release is made within the first 6 months, then the end of life date of the major release series is 1 year after its initial release.
-- If the next major release is made 6 months after the initial release, then the end of life date of the major release series is 6 months after the release date of the next major release.
+- If the next major release is made within the first 6 months, then the end of life date of the major release series is 18 months after its initial release.
+- If the next major release is made 6 months after the initial release, then the end of life date of the major release series is 12 months after the release date of the next major release.
 
 For example, if the current major release series is v1 and was released on January 1st, 2022, then v1 will be supported at least until January 1st, 2023. If v2 is published on August 1st 2022, then v1's end of life will be March 1st, 2023.
 
 Only the following major release series have a stable release status. All missing minor release versions have been discontinued.
 
+We reserve the right to drop support for releases if they are deemed unused (for example, because the Cosmos SDK version they depend on is not used or has been deprecated). Likewise, we also reserve the right to drop support for pre v1.0 versions of modules if we deem them unnecessary to maintain (we are only looking to give support for stable major releases).
+
 ### ibc-go 
 
 |Release|End of Life Date|
 |-------|----------------|
-|`v7.2.x`|March 17, 2024|
-|`v7.3.x`|March 17, 2024|
-|`v8.0.x`|November 10, 2024|
+|`v7.2.x`|September 17, 2024|
+|`v7.3.x`|September 17, 2024|
+|`v8.0.x`|May 10, 2025|
 
 ### Callbacks middleware
 
 |Release|End of Life Date|
 |-------|----------------|
-|`v0.1.x-ibc-go-v7.3.x`|March 17, 2024|
+|`v0.1.x+ibc-go-v7.3.x`|September 17, 2024|
+|`v0.1.x+ibc-go-v8.0.x`|May 10, 2025|
+
+### `08-wasm` light client proxy module
+
+|Release|End of Life Date|
+|-------|----------------|
+|`v0.1.0+ibc-go-v7.3.x-wasmvm-v1.5.x`|September 17, 2024|
+|`v0.2.x+ibc-go-v8.0.x-wasmvm-v1.5.x`|May 10, 2025|
 
 ### What pull requests will be included in stable patch-releases?
 
@@ -121,7 +131,17 @@ Versions of Golang, ibc-go, Cosmos SDK and CometBFT used by callbacks middleware
 
 | Go | callbacks | ibc-go | Cosmos SDK | Tendermint/CometBFT |
 |----|-----------|--------|------------|---------------------|
-| 1.19 | v0.1.0-ibc-go-v7.3 | v7.3.0 | v0.47.4 | v0.37.2 |
+| 1.19 | v0.1.0+ibc-go-v7.3 | v7.3.0 | v0.47.4 | v0.37.2 |
+| 1.21 | v0.2.0+ibc-go-v8.0 | v8.0.0 | v0.50.1 | v0.38.0 |
+
+### `08-wasm` light client proxy module
+
+Versions of Golang, ibc-go, Cosmos SDK and CometBFT used by `08-wasm` module in the currently active releases:
+
+| Go | callbacks | ibc-go | Cosmos SDK | Tendermint/CometBFT |
+|----|-----------|--------|------------|---------------------|
+| 1.19 | v0.1.0+ibc-go-v7.3-wasmvm-v1.5 | v7.3.0 | v0.47.6 | v0.37.2 |
+| 1.21 | v0.1.0+ibc-go-v8.0-wasmvm-v1.5 | v8.0.0 | v0.50.1 | v0.38.0 |
 
 ## Graphics
 

docs/docs/01-ibc/04-middleware/02-develop.md

@@ -32,7 +32,7 @@ type IBCMiddleware struct {
   keeper keeper.Keeper
 }
 
-// NewIBCMiddleware creates a new IBCMiddlware given the keeper and underlying application
+// NewIBCMiddleware creates a new IBCMiddleware given the keeper and underlying application
 func NewIBCMiddleware(app porttypes.IBCModule, k keeper.Keeper) IBCMiddleware {
   return IBCMiddleware{
     app:    app,

docs/docs/01-ibc/05-upgrades/00-intro.md

@@ -9,7 +9,7 @@ slug: /ibc/upgrades/intro
 
 This directory contains information on how to upgrade an IBC chain without breaking counterparty clients and connections.
 
-IBC-connnected chains must be able to upgrade without breaking connections to other chains. Otherwise there would be a massive disincentive towards upgrading and disrupting high-value IBC connections, thus preventing chains in the IBC ecosystem from evolving and improving. Many chain upgrades may be irrelevant to IBC, however some upgrades could potentially break counterparty clients if not handled correctly. Thus, any IBC chain that wishes to perform a IBC-client-breaking upgrade must perform an IBC upgrade in order to allow counterparty clients to securely upgrade to the new light client.
+IBC-connected chains must be able to upgrade without breaking connections to other chains. Otherwise there would be a massive disincentive towards upgrading and disrupting high-value IBC connections, thus preventing chains in the IBC ecosystem from evolving and improving. Many chain upgrades may be irrelevant to IBC, however some upgrades could potentially break counterparty clients if not handled correctly. Thus, any IBC chain that wishes to perform a IBC-client-breaking upgrade must perform an IBC upgrade in order to allow counterparty clients to securely upgrade to the new light client.
 
 1. The [quick-guide](./01-quick-guide.md) describes how IBC-connected chains can perform client-breaking upgrades and how relayers can securely upgrade counterparty clients using the SDK.
 2. The [developer-guide](./02-developer-guide.md) is a guide for developers intending to develop IBC client implementations with upgrade functionality.

docs/docs/01-ibc/06-channel-upgrades.md

@@ -55,17 +55,26 @@ 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. It is possible to upgrade the channel ordering, the channel connection hops, and the channel version, which can be found in the `UpgradeFields`. 
 
-As part of the handling of the `ChanUpgradeInit` message, the application's callbacks `OnChanUpgradeInit` will be triggered as well.
+```go
+type MsgChannelUpgradeInit struct {
+  PortId    string
+  ChannelId string
+  Fields    UpgradeFields
+  Signer    string
+}
+```
+
+As part of the handling of the `MsgChannelUpgradeInit` message, the application's `OnChanUpgradeInit` callback will be triggered as well.
 
 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`. The `upgrade-channels` CLI command can be used to submit a proposal that initiates the upgrade of multiple channels; see section [Upgrading channels with the CLI](#upgrading-channels-with-the-cli) below for more information.
 
 ## Channel State and Packet Flushing
 
@@ -147,6 +156,89 @@ 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. If upgrades cannot be performed in a timely manner (due to unforeseen flushing issues), upgrade timeouts allow the channel to avoid blocking packet sends indefinitely. If flushing exceeds the time limit set in the `UpgradeTimeout` channel `Params`, the upgrade process will need to be timed out to abort the upgrade attempt and resume normal channel processing.
+
+Channel upgrades require setting a valid timeout value in the channel `Params` before submitting a `MsgChannelUpgradeTry` or `MsgChannelUpgradeAck` message (by default, 10 minutes): 
+
+```go
+type Params struct {
+  UpgradeTimeout Timeout 
+}
+```
+
+A valid Timeout contains either one or both of a timestamp and block height (sequence).
+
+```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:
+
+```go
+type MsgChannelUpgradeTimeout struct {
+  PortId              string    
+  ChannelId           string
+  CounterpartyChannel Channel 
+  ProofChannel        []byte
+  ProofHeight         types.Height
+  Signer              string 
+}
+```
+
+An `ErrorReceipt` will be written with the channel's current upgrade sequence, and the channel will move back to `OPEN` state keeping its original parameters.
+
+The application's `OnChanUpgradeRestore` callback method will also be invoked.
+
+Note that timing out a channel upgrade will end the upgrade process, and a new `MsgChannelUpgradeInit` will have to be submitted via governance in order to restart the upgrade process.
+
+## Pruning Acknowledgements
+
+Acknowledgements can be pruned by broadcasting the `MsgPruneAcknowledgements` message.
+
+> Note: It is only possible to prune acknowledgements after a channel has been upgraded, so pruning will fail
+> if the channel has not yet been upgraded.
+
+```protobuf
+// MsgPruneAcknowledgements defines the request type for the PruneAcknowledgements rpc.
+message MsgPruneAcknowledgements {
+  option (cosmos.msg.v1.signer)      = "signer";
+  option (gogoproto.goproto_getters) = false;
+
+  string port_id    = 1;
+  string channel_id = 2;
+  uint64 limit      = 3;
+  string signer     = 4;
+}
+```
+
+The `port_id` and `channel_id` specify the port and channel to act on, and the `limit` specifies the upper bound for the number
+of acknowledgements and packet receipts to prune.
+
+### CLI Usage
+
+Acknowledgements can be pruned via the cli with the `prune-acknowledgements` command.
+
+```bash
+simd tx ibc channel prune-acknowledgements [port] [channel] [limit]
+```
+
 ## IBC App Recommendations
 
 IBC application callbacks should be primarily used to validate data fields and do compatibility checks.
@@ -164,3 +256,135 @@ IBC application callbacks should be primarily used to validate data fields and d
 > IBC applications should not attempt to process any packet data under the new conditions until after `OnChanUpgradeOpen`
 > has been executed, as up until this point it is still possible for the upgrade handshake to fail and for the channel
 > to remain in the pre-upgraded state. 
+
+## Upgrade an existing transfer application stack to use 29-fee middleware
+
+### Wire up the transfer stack and middleware in app.go
+
+In app.go, the existing transfer stack must be wrapped with the fee middleware.
+
+```golang
+
+import (
+  // ... 
+  ibcfee "github.com/cosmos/ibc-go/v8/modules/apps/29-fee"
+  ibctransferkeeper "github.com/cosmos/ibc-go/v8/modules/apps/transfer/keeper"
+  transfer "github.com/cosmos/ibc-go/v8/modules/apps/transfer"
+  porttypes "github.com/cosmos/ibc-go/v8/modules/core/05-port/types"
+  // ...
+)
+
+type App struct {
+  // ...
+  TransferKeeper        ibctransferkeeper.Keeper
+  IBCFeeKeeper          ibcfeekeeper.Keeper
+  // ..
+}
+
+// ...
+
+app.IBCFeeKeeper = ibcfeekeeper.NewKeeper(
+  appCodec, keys[ibcfeetypes.StoreKey],
+  app.IBCKeeper.ChannelKeeper, // may be replaced with IBC middleware
+  app.IBCKeeper.ChannelKeeper,
+  app.IBCKeeper.PortKeeper, app.AccountKeeper, app.BankKeeper,
+)
+
+// Create Transfer Keeper and pass IBCFeeKeeper as expected Channel and PortKeeper
+// since fee middleware will wrap the IBCKeeper for underlying application.
+app.TransferKeeper = ibctransferkeeper.NewKeeper(
+  appCodec, keys[ibctransfertypes.StoreKey], app.GetSubspace(ibctransfertypes.ModuleName),
+  app.IBCFeeKeeper, // ISC4 Wrapper: fee IBC middleware
+  app.IBCKeeper.ChannelKeeper, app.IBCKeeper.PortKeeper,
+  app.AccountKeeper, app.BankKeeper, scopedTransferKeeper,
+  authtypes.NewModuleAddress(govtypes.ModuleName).String(),
+)
+
+
+ibcRouter := porttypes.NewRouter()
+
+// create IBC module from bottom to top of stack
+var transferStack porttypes.IBCModule
+transferStack = transfer.NewIBCModule(app.TransferKeeper)
+transferStack = ibcfee.NewIBCMiddleware(transferStack, app.IBCFeeKeeper)
+
+// Add transfer stack to IBC Router
+ibcRouter.AddRoute(ibctransfertypes.ModuleName, transferStack)
+```
+
+### Submit a governance proposal to execute a MsgChannelUpgradeInit message
+
+> This process can be performed with the new CLI that has been added
+> outlined [here](#upgrading-channels-with-the-cli).
+
+Only the configured authority for the ibc module is able to initiate a channel upgrade by submitting a `MsgChannelUpgradeInit` message.
+
+Execute a governance proposal specifying the relevant fields to perform a channel upgrade.
+
+Update the following json sample, and copy the contents into `proposal.json`.
+
+```json
+{
+  "title": "Channel upgrade init",
+  "summary": "Channel upgrade init",
+  "messages": [
+    {
+      "@type": "/ibc.core.channel.v1.MsgChannelUpgradeInit",
+      "signer": "<gov-address>",
+      "port_id": "transfer",
+      "channel_id": "channel-...",
+      "fields": {
+        "ordering": "ORDER_UNORDERED",
+        "connection_hops": ["connection-0"],
+        "version": "{\"fee_version\":\"ics29-1\",\"app_version\":\"ics20-1\"}"
+      }
+    }
+  ],
+  "metadata": "<metadata>",
+  "deposit": "10stake"
+}
+```
+
+> Note: ensure the correct fields.version is specified. This is the new version that the channels will be upgraded to.
+
+### Submit the proposal
+
+```shell
+simd tx submit-proposal proposal.json --from <key_or_address>
+```
+
+## Upgrading channels with the CLI
+
+A new cli has been added which enables either
+    - submitting a governance proposal which contains a `MsgChannelUpgradeInit` for every channel to be upgraded.
+    - generating a `proposal.json` file which contains the proposal contents to be edited/submitted at a later date.
+
+The following example, would submit a governance proposal with the specified deposit, title and summary which would
+contain a `MsgChannelUpgradeInit` for all `OPEN` channels whose port matches the regular expression `transfer`.
+
+> Note: by adding the `--json` flag, the command would instead output the contents of the proposal which could be 
+> stored in a `proposal.json` file to be edited and submitted at a later date.
+
+```bash
+simd tx ibc channel upgrade-channels "{\"fee_version\":\"ics29-1\",\"app_version\":\"ics20-1\"}" \
+  --deposit "10stake" \
+  --title "Channel Upgrades Governance Proposal" \
+  --summary "Upgrade all transfer channels to be fee enabled" \
+  --port-pattern "transfer"
+```
+
+It is also possible to explicitly list a comma separated string of channel IDs. It is important to note that the 
+regular expression matching specified by `--port-pattern` (which defaults to `transfer`) still applies.
+
+For example the following command would generate the contents of a `proposal.json` file which would attempt to upgrade
+channels with a port ID of `transfer` and a channelID of `channel-0`, `channel-1` or `channel-2`.
+
+```bash
+simd tx ibc channel upgrade-channels "{\"fee_version\":\"ics29-1\",\"app_version\":\"ics20-1\"}" \
+  --deposit "10stake" \
+  --title "Channel Upgrades Governance Proposal" \
+  --summary "Upgrade all transfer channels to be fee enabled" \
+  --port-pattern "transfer" \
+  --channel-ids "channel-0,channel-1,channel-2" \
+  --json
+```

docs/docs/01-ibc/10-roadmap.md

@@ -7,7 +7,7 @@ slug: /ibc/roadmap
 
 # Roadmap ibc-go
 
-*Lastest update: December 4th, 2023*
+*Latest update: December 4th, 2023*
 
 This document endeavours to inform the wider IBC community about plans and priorities for work on ibc-go by the team at Interchain GmbH. It is intended to broadly inform all users of ibc-go, including developers and operators of IBC, relayer, chain and wallet applications.
 

docs/docs/01-ibc/11-troubleshooting.md

@@ -12,4 +12,4 @@ slug: /ibc/troubleshooting
 If it is being reported that a client state is unauthorized, this is due to the client type not being present
 in the [`AllowedClients`](https://github.com/cosmos/ibc-go/blob/v6.0.0/modules/core/02-client/types/client.pb.go#L345) array.
 
-Unless the client type is present in this array, all usage of clients of this type will be prevented.
+Unless the client type is present in this array or the `AllowAllClients` wildcard (`"*"`) is used, all usage of clients of this type will be prevented.

docs/docs/03-light-clients/01-developer-guide/09-setup.md

@@ -131,3 +131,5 @@ where `proposal.json` contains:
   "deposit": "100stake"
 }
 ```
+
+If the `AllowedClients` list contains a single element that is equal to the wildcard `"*"`, then all client types are allowed and it is thus not necessary to submit a governance proposal to update the parameter.

docs/docs/03-light-clients/02-localhost/02-integration.md

@@ -10,11 +10,10 @@ slug: /ibc/light-clients/localhost/integration
 
 The 09-localhost light client module registers codec types within the core IBC module. This differs from other light client module implementations which are expected to register codec types using the `AppModuleBasic` interface.
 
-The localhost client is added to the 02-client submodule param [`allowed_clients`](https://github.com/cosmos/ibc-go/blob/v7.0.0/proto/ibc/core/client/v1/client.proto#L102) by default in ibc-go.
+The localhost client is implicitly enabled by using the `AllowAllClients` wildcard (`"*"`) in the 02-client submodule default value for param  [`allowed_clients`](https://github.com/cosmos/ibc-go/blob/v7.0.0/proto/ibc/core/client/v1/client.proto#L102).
 
 ```go
-var (
-  // DefaultAllowedClients are the default clients for the AllowedClients parameter.
-  DefaultAllowedClients = []string{exported.Solomachine, exported.Tendermint, exported.Localhost}
-)
+// DefaultAllowedClients are the default clients for the AllowedClients parameter.
+// By default it allows all client types.
+var DefaultAllowedClients = []string{AllowAllClients}
 ```