ChannelUpgradeInit refactor

.github/dependabot.yml

@@ -38,4 +38,12 @@ updates:
     labels:
       - dependencies
 
+  - package-ecosystem: gomod
+    directory: "/modules/capability"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 10
+    labels:
+      - dependencies
+
 

.github/workflows/deploy-docs.yml

@@ -27,7 +27,7 @@ jobs:
         run: make build-docs
 
       - name: Deploy 🚀
-        uses: JamesIves/github-pages-deploy-action@v4.4.3
+        uses: JamesIves/github-pages-deploy-action@v4.5.0
         with:
           branch: gh-pages
           folder: docs/build

.github/workflows/markdown-lint.yml

@@ -18,7 +18,7 @@ jobs:
       with:
         files: '**/*.md'
         separator: ","
-    - uses: DavidAnson/markdownlint-cli2-action@v13
+    - uses: DavidAnson/markdownlint-cli2-action@v14
       if: steps.changed-files.outputs.any_changed == 'true'
       with:
         globs: ${{ steps.changed-files.outputs.all_changed_files }}

.github/workflows/test.yml

@@ -16,22 +16,6 @@ jobs:
           GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
     if: "!startsWith(github.ref, 'refs/tags/') && github.ref != 'refs/heads/main'"
 
-  install-tparse:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/setup-go@v4
-        with:
-          go-version: '1.21'
-      - name: Display go version
-        run: go version
-      - name: install tparse
-        run: |
-          go install github.com/mfridman/[email protected]
-      - uses: actions/cache@v3
-        with:
-          path: ~/go/bin
-          key: ${{ runner.os }}-go-tparse-binary
-
   build:
     runs-on: ubuntu-latest
     strategy:

README.md

@@ -35,7 +35,7 @@
     <img alt="E2E Status" src="https://github.com/cosmos/ibc-go/workflows/Tests%20/%20E2E/badge.svg" />
 </div>
 
-The [Inter-Blockchain Communication protocol (IBC)](https://ibcprotocol.dev/) allows blockchains to talk to each other. This end-to-end, connection-oriented, stateful protocol provides reliable, ordered, and authenticated communication between heterogeneous blockchains.
+The [Inter-Blockchain Communication protocol (IBC)](https://ibcprotocol.dev/) allows blockchains to talk to each other. This end-to-end, connection-oriented, stateful protocol provides reliable, ordered, and authenticated communication between heterogeneous blockchains. For a high-level explanation of what IBC is and how it works, please read [this blog post](https://medium.com/the-interchain-foundation/eli5-what-is-ibc-def44d7b5b4c).
 
 This IBC implementation in Golang is built as a Cosmos SDK module. To understand more about how to use the `ibc-go` module as well as about the IBC protocol, please check out the Interchain Developer Academy [section on IBC](https://tutorials.cosmos.network/academy/3-ibc/), or [our docs](https://ibc.cosmos.network/main/ibc/overview.html).
 
@@ -47,8 +47,6 @@ This roadmap is also available as a [project board](https://github.com/orgs/cosm
 
 For the latest expected release timelines, please check [here](https://github.com/cosmos/ibc-go/wiki/Release-timeline).
 
-For the latest information on the progress of the work or the decisions made that might influence the roadmap, please follow our [engineering updates](https://github.com/cosmos/ibc-go/wiki/Engineering-updates).
-
 ## Releases
 
 The release lines currently supported are v6, v7 and v8.
@@ -61,14 +59,16 @@ Please refer to our [versioning guide](https://github.com/cosmos/ibc-go/blob/mai
 
 Discover more applications and middleware in the [cosmos/ibc-apps repository](https://github.com/cosmos/ibc-apps#-bonus-content).
 
-## Support
+## Community
 
 We have active, helpful communities on Discord and Telegram.
 
-For questions and support please use the `developers` channel in the [Cosmos Network Discord server](https://discord.com/channels/669268347736686612/1019978171367559208) or join the [IBC Gang Discord server](https://discord.gg/RdpdkaXKpZ). The issue list of this repo is exclusively for bug reports and feature requests.
+For questions and support please use the `developers` channel in the [Cosmos Network Discord server](https://discord.com/channels/669268347736686612/1019978171367559208) or join the [IBC Gang Discord server](https://discord.gg/Wtmk6ZNa8G). The issue list of this repo is exclusively for bug reports and feature requests.
 
 To receive announcements of new releases or other technical updates, please join the [Telegram group that we administer](https://t.me/ibc_is_expansive).
 
+We run biweekly community calls to update the community with our current direction and gather feedback on what to work on next. The community calls are also a platform for you to update everyone else with what you're working on, ask questions and find opportunities to collaborate. Please join [this Google group](https://groups.google.com/g/ibc-community) to receive a calendar invitation for the meeting.
+
 ## Contributing
 
 If you're interested in contributing to ibc-go, please take a look at the [contributing guidelines](./CONTRIBUTING.md). We welcome and appreciate community contributions!
@@ -92,7 +92,7 @@ To report a security vulnerability, see our [Coordinated Vulnerability Disclosur
 
 The following audits have been performed on the `ibc-go` source code:
 
-- [ICS27 Interchain Accounts](https://github.com/cosmos/ibc-go/blob/main/docs/audits/Trail%20of%20Bits%20audit%20-%20Final%20Report.pdf) by Trail of Bits
+- [ICS27 Interchain Accounts](https://github.com/cosmos/ibc-go/blob/main/docs/audits/Trail%20of%20Bits%20audit%20-%20Final%20Report.pdf) by Trail of Bits.
 
 ## Quick Navigation
 
@@ -138,3 +138,7 @@ The following audits have been performed on the `ibc-go` source code:
 - [IBC Protocol Specification](https://github.com/cosmos/ibc)
 - [Documentation](https://ibc.cosmos.network/main/ibc/overview.html)
 - [Interchain Developer Academy](https://tutorials.cosmos.network/academy/3-ibc/)
+
+---
+
+The development of ibc-go is led primarily by Interchain GmbH. Funding for this development comes primarily from the [Interchain Foundation](https://interchain.io), a Swiss non-profit.

docs/client/swagger-ui/swagger.yaml

@@ -13610,17 +13610,25 @@ paths:
           type: string
       tags:
         - Query
-  /ibc/core/channel/v1/channels/{channel_id}/ports/{port_id}/upgrade_error:
+  /ibc/lightclients/wasm/v1/checksums:
     get:
-      summary: UpgradeError returns the error receipt if the upgrade handshake failed.
-      operationId: UpgradeError
+      summary: Get all Wasm checksums
+      operationId: Checksums
       responses:
         '200':
           description: A successful response.
           schema:
             type: object
             properties:
-              error_receipt:
+              checksums:
+                type: array
+                items:
+                  type: string
+                description: >-
+                  checksums is a list of the hex encoded checksums of all wasm
+                  codes stored.
+              pagination:
+                description: pagination defines the pagination in the response.
                 type: object
                 properties:
                   sequence:
@@ -13634,11 +13642,21 @@ paths:
                   ErrorReceipt defines a type which encapsulates the upgrade
                   sequence and error associated with the
 
-                  upgrade handshake failure. When a channel upgrade handshake is
-                  aborted both chains are expected to increment to the
-
-                  next sequence.
-              proof:
+                      was set, its value is undefined otherwise
+            description: >-
+              QueryChecksumsResponse is the response type for the
+              Query/Checksums RPC method.
+        default:
+          description: An unexpected error response.
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+              code:
+                type: integer
+                format: int32
+              message:
                 type: string
                 format: byte
                 title: merkle proof of existence
@@ -20372,157 +20390,6 @@ definitions:
       ready to send and receive packets.
        - STATE_CLOSED: A channel has been closed and can no longer be used to send or receive
       packets.
-       - STATE_FLUSHING: A channel has just accepted the upgrade handshake attempt and is flushing in-flight packets.
-       - STATE_FLUSHCOMPLETE: A channel has just completed flushing any in-flight packets.
-  ibc.core.channel.v1.Timeout:
-    type: object
-    properties:
-      height:
-        title: block height after which the packet or upgrade times out
-        type: object
-        properties:
-          revision_number:
-            type: string
-            format: uint64
-            title: the revision that the client is currently on
-          revision_height:
-            type: string
-            format: uint64
-            title: the height within the given revision
-        description: >-
-          Normally the RevisionHeight is incremented at each height while
-          keeping
-
-          RevisionNumber the same. However some consensus algorithms may choose
-          to
-
-          reset the height in certain conditions e.g. hard forks, state-machine
-
-          breaking changes In these cases, the RevisionNumber is incremented so
-          that
-
-          height continues to be monitonically increasing even as the
-          RevisionHeight
-
-          gets reset
-      timestamp:
-        type: string
-        format: uint64
-        title: >-
-          block timestamp (in nanoseconds) after which the packet or upgrade
-          times out
-    description: >-
-      Timeout defines an execution deadline structure for 04-channel handlers.
-
-      This includes packet lifecycle handlers as well as the upgrade handshake
-      handlers.
-
-      A valid Timeout contains either one or both of a timestamp and block
-      height (sequence).
-  ibc.core.channel.v1.Upgrade:
-    type: object
-    properties:
-      fields:
-        type: object
-        properties:
-          ordering:
-            type: string
-            enum:
-              - ORDER_NONE_UNSPECIFIED
-              - ORDER_UNORDERED
-              - ORDER_ORDERED
-            default: ORDER_NONE_UNSPECIFIED
-            description: |-
-              - ORDER_NONE_UNSPECIFIED: zero-value for channel ordering
-               - ORDER_UNORDERED: packets can be delivered in any order, which may differ from the order in
-              which they were sent.
-               - ORDER_ORDERED: packets are delivered exactly in the order which they were sent
-            title: Order defines if a channel is ORDERED or UNORDERED
-          connection_hops:
-            type: array
-            items:
-              type: string
-          version:
-            type: string
-        description: |-
-          UpgradeFields are the fields in a channel end which may be changed
-          during a channel upgrade.
-      timeout:
-        type: object
-        properties:
-          height:
-            title: block height after which the packet or upgrade times out
-            type: object
-            properties:
-              revision_number:
-                type: string
-                format: uint64
-                title: the revision that the client is currently on
-              revision_height:
-                type: string
-                format: uint64
-                title: the height within the given revision
-            description: >-
-              Normally the RevisionHeight is incremented at each height while
-              keeping
-
-              RevisionNumber the same. However some consensus algorithms may
-              choose to
-
-              reset the height in certain conditions e.g. hard forks,
-              state-machine
-
-              breaking changes In these cases, the RevisionNumber is incremented
-              so that
-
-              height continues to be monitonically increasing even as the
-              RevisionHeight
-
-              gets reset
-          timestamp:
-            type: string
-            format: uint64
-            title: >-
-              block timestamp (in nanoseconds) after which the packet or upgrade
-              times out
-        description: >-
-          Timeout defines an execution deadline structure for 04-channel
-          handlers.
-
-          This includes packet lifecycle handlers as well as the upgrade
-          handshake handlers.
-
-          A valid Timeout contains either one or both of a timestamp and block
-          height (sequence).
-    description: |-
-      Upgrade is a verifiable type which contains the relevant information
-      for an attempted upgrade. It provides the proposed changes to the channel
-      end and the timeout for this upgrade attempt.
-  ibc.core.channel.v1.UpgradeFields:
-    type: object
-    properties:
-      ordering:
-        type: string
-        enum:
-          - ORDER_NONE_UNSPECIFIED
-          - ORDER_UNORDERED
-          - ORDER_ORDERED
-        default: ORDER_NONE_UNSPECIFIED
-        description: |-
-          - ORDER_NONE_UNSPECIFIED: zero-value for channel ordering
-           - ORDER_UNORDERED: packets can be delivered in any order, which may differ from the order in
-          which they were sent.
-           - ORDER_ORDERED: packets are delivered exactly in the order which they were sent
-        title: Order defines if a channel is ORDERED or UNORDERED
-      connection_hops:
-        type: array
-        items:
-          type: string
-      version:
-        type: string
-    description: |-
-      UpgradeFields are the fields in a channel end which may be changed
-      during a channel upgrade.
   ibc.lightclients.wasm.v1.QueryChecksumsResponse:
     type: object
     properties:

docs/docs/00-intro.md

@@ -14,3 +14,23 @@ IBC is a protocol that allows blockchains to talk to each other. Chains that spe
 The protocol realizes this interoperability by specifying a set of data structures, abstractions, and semantics that can be implemented by any distributed ledger that satisfies a small set of requirements.
 
 IBC can be used to build a wide range of cross-chain applications that include token transfers, atomic swaps, multi-chain smart contracts (with or without mutually comprehensible VMs), cross-chain account control, and data and code sharding of various kinds.
+
+## High-level overview of IBC
+
+The following diagram shows how IBC works at a high level:
+
+![IBC overview - two connected chains](./images/ibcoverview.png)
+
+The transport layer (TAO) provides the necessary infrastructure to establish secure connections and authenticate data packets between chains. The application layer builds on top of the transport layer and defines exactly how data packets should be packaged and interpreted by the sending and receiving chains.
+
+IBC provides a reliable, permissionless, and generic base layer (allowing for the secure relaying of data packets), while allowing for composability and modularity with separation of concerns by moving application designs (interpreting and acting upon the packet data) to a higher-level layer. This separation is reflected in the categories:
+
+- **IBC/TAO** comprises the Transport, Authentication, and Ordering of packets, i.e. the infrastructure layer.
+- **IBC/APP** consists of the application handlers for the data packets being passed over the transport layer. These include but are not limited to fungible token transfers (ICS-20), NFT transfers (ICS-721), and interchain accounts (ICS-27).
+- **Application module:** groups any application, middleware or smart contract that may wrap downsteam application handlers to provide enhanced functionality.
+
+Note three crucial elements in the diagram:
+
+- The chains depend on relayers to communicate. Relayers are the "physical" connection layer of IBC: off-chain processes responsible for relaying data between two chains running the IBC protocol by scanning the state of each chain, constructing appropriate datagrams, and executing them on the opposite chain as is allowed by the protocol.
+- Many relayers can serve one or more channels to send messages between the chains.
+- Each side of the connection uses the light client of the other chain to quickly verify incoming messages.

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)
 

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(