docs: add versioned docs for v10 (#8279)

* delete v9 docs

* add v10.1.x versioned docs

* fix broken links

* more link fixes

---------

Co-authored-by: Susannah Evans <65018876+womensrights@users.noreply.github.com>

Author: 2 people

.github/PULL_REQUEST_TEMPLATE.md

@@ -36,7 +36,7 @@ write a little note why.
 
 - [ ] Targeted PR against the correct branch (see [CONTRIBUTING.md](https://github.com/cosmos/ibc-go/blob/main/docs/dev/pull-requests.md#pull-request-targeting)).
 - [ ] Linked to GitHub issue with discussion and accepted design, OR link to spec that describes this work.
-- [ ] Code follows the [module structure standards](https://github.com/cosmos/cosmos-sdk/blob/main/docs/build/building-modules/11-structure.md) and [Go style guide](../docs/dev/go-style-guide.md).
+- [ ] Code follows the [module structure standards](https://docs.cosmos.network/main/build/building-modules/intro) and [Go style guide](../docs/dev/go-style-guide.md).
 - [ ] Wrote unit and integration [tests](https://github.com/cosmos/ibc-go/blob/main/testing/README.md#ibc-testing-package).
 - [ ] Updated relevant documentation (`docs/`).
 - [ ] Added relevant `godoc` [comments](https://blog.golang.org/godoc-documenting-go-code).

docs/dev/project-structure.md

@@ -1,6 +1,6 @@
 # Project structure
 
-If you're not familiar with the overall module structure from the SDK modules, please check this [document](https://github.com/cosmos/cosmos-sdk/blob/main/docs/build/building-modules/11-structure.md) as prerequisite reading.
+If you're not familiar with the overall module structure from the SDK modules, please check this [document](https://docs.cosmos.network/main/build/building-modules/intro) as prerequisite reading.
 
 Every Interchain Standard (ICS) has been developed in its own package. The development team separated the IBC TAO (Transport, Authentication, Ordering) ICS specifications from the IBC application level specification. The following sections describe the architecture of the most relevant directories that comprise this repository.
 

docs/docs/01-ibc/02-integration.md

@@ -197,7 +197,7 @@ With IBC v2, there is a new [router](https://github.com/cosmos/ibc-go/blob/main/
 
 ### Module `Manager` and `SimulationManager`
 
-In order to use IBC, we need to add the new modules to the module `Manager` and to the `SimulationManager`, in case your application supports [simulations](https://github.com/cosmos/cosmos-sdk/blob/main/docs/build/building-modules/14-simulator.md).
+In order to use IBC, we need to add the new modules to the module `Manager` and to the `SimulationManager`, in case your application supports [simulations](https://docs.cosmos.network/main/learn/advanced/simulation).
 
 ```go title="app.go"
 import (

docs/docs/01-ibc/07-relayer.md

@@ -12,7 +12,7 @@ slug: /ibc/relayer
 ## Pre-requisite readings
 
 - [IBC Overview](01-overview.md)
-- [Events](https://github.com/cosmos/cosmos-sdk/blob/main/docs/learn/advanced/08-events.md)
+- [Events](https://docs.cosmos.network/v0.47/learn/advanced/events)
 
 :::
 

docs/docs/02-apps/01-transfer/06-metrics.md

@@ -7,7 +7,7 @@ slug: /apps/transfer/ics20-v1/metrics
 
 # Metrics
 
-The IBC transfer application module exposes the following set of [metrics](https://github.com/cosmos/cosmos-sdk/blob/main/docs/learn/advanced/09-telemetry.md).
+The IBC transfer application module exposes the following set of [metrics](https://docs.cosmos.network/main/learn/advanced/telemetry).
 
 | Metric                          | Description                                                                               | Unit            | Type    |
 |:--------------------------------|:------------------------------------------------------------------------------------------|:----------------|:--------|

docs/docusaurus.config.js

@@ -49,7 +49,7 @@ const config = {
           // Exclude template markdown files from the docs
           exclude: ["**/*.template.md"],
           // Select the latest version
-          lastVersion: "v8.5.x",
+          lastVersion: "v10.1.x",
           // Assign banners to specific versions
           versions: {
             current: {

docs/versioned_docs/version-v9.0.x/00-intro.md renamed to docs/versioned_docs/version-v10.1.x/00-intro.md

@@ -5,17 +5,23 @@ sidebar_position: 0
 
 # IBC-Go Documentation
 
-Welcome to the documentation for IBC-Go, the Golang implementation of the Inter-Blockchain Communication Protocol! Looking for information on ibc-rs? [Click here to go to the ibc-rs github repo](https://github.com/cosmos/ibc-rs).
+Welcome to the documentation for IBC-Go, the Golang implementation of the Inter-Blockchain Communication Protocol! 
 
-The Inter-Blockchain Communication Protocol (IBC) is an end-to-end, connection-oriented, stateful protocol for reliable, ordered, and authenticated communication between heterogeneous blockchains arranged in an unknown and dynamic topology.
-
-IBC is a protocol that allows blockchains to talk to each other. Chains that speak IBC can share any type of data as long as it's encoded in bytes, enabling the industry’s most feature-rich cross-chain interactions. IBC is secure and permissionless.
+The Inter-Blockchain Communication Protocol (IBC) is a protocol that allows blockchains to talk to each other. Chains that speak IBC can share any type of data as long as it's encoded in bytes, enabling the industry’s most feature-rich cross-chain interactions. 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), and cross-chain account control. IBC is secure and permissionless. 
 
 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.
+:::note Notice
+Since ibc-go v10, there are two versions of the protocol in the same release: IBC classic and IBC v2. The protocols are seperate - a connection uses either IBC classic or IBC v2
+:::
+
+## High-level overview of IBC v2
+
+For a high level overview of IBC v2, please refer to [this blog post.](https://ibcprotocol.dev/blog/ibc-v2-announcement) For a more detailed understanding of the IBC v2 protocol, please refer to the [IBC v2 protocol specification.](https://github.com/cosmos/ibc/tree/main/spec/IBC_V2)
+
+If you are interested in using the cannonical deployment of IBC v2, connecting Cosmos chains and Ethereum, take a look at the [IBC Eureka](https://docs.skip.build/go/eureka/eureka-overview) documentation to get started.
 
-## High-level overview of IBC
+## High-level overview of IBC Classic
 
 The following diagram shows how IBC works at a high level:
 

docs/versioned_docs/version-v9.0.x/01-ibc/01-overview.md renamed to docs/versioned_docs/version-v10.1.x/01-ibc/01-overview.md

@@ -8,19 +8,19 @@ slug: /ibc/integration
 # Integration
 
 :::note Synopsis
-Learn how to integrate IBC to your application and send data packets to other chains.
+Learn how to integrate IBC to your application
 :::
 
 This document outlines the required steps to integrate and configure the [IBC
-module](https://github.com/cosmos/ibc-go/tree/main/modules/core) to your Cosmos SDK application and
-send fungible token transfers to other chains.
+module](https://github.com/cosmos/ibc-go/tree/main/modules/core) to your Cosmos SDK application and enable sending fungible token transfers to other chains. An [example app using ibc-go v10 is linked](https://github.com/gjermundgaraba/probe/tree/ibc/v10).
 
 ## Integrating the IBC module
 
 Integrating the IBC module to your SDK-based application is straightforward. The general changes can be summarized in the following steps:
 
 - [Define additional `Keeper` fields for the new modules on the `App` type](#add-application-fields-to-app).
 - [Add the module's `StoreKey`s and initialize their `Keeper`s](#configure-the-keepers).
+- [Create Application Stacks with Middleware](#create-application-stacks-with-middleware)
 - [Set up IBC router and add route for the `transfer` module](#register-module-routes-in-the-ibc-router).
 - [Grant permissions to `transfer`'s `ModuleAccount`](#module-account-permissions).
 - [Add the modules to the module `Manager`](#module-manager-and-simulationmanager).
@@ -30,14 +30,17 @@ Integrating the IBC module to your SDK-based application is straightforward. The
 
 ### Add application fields to `App`
 
-We need to register the core `ibc` and `transfer` `Keeper`s as follows:
+We need to register the core `ibc` and `transfer` `Keeper`s. To support the use of IBC v2, `transferv2` and `callbacksv2` must also be registered as follows:
 
 ```go title="app.go"
 import (
   // other imports
   // ...
   ibckeeper "github.com/cosmos/ibc-go/v10/modules/core/keeper"
   ibctransferkeeper "github.com/cosmos/ibc-go/v10/modules/apps/transfer/keeper"
+  // ibc v2 imports
+  transferv2 "github.com/cosmos/ibc-go/v10/modules/apps/transfer/v2"
+  ibccallbacksv2 "github.com/cosmos/ibc-go/v10/modules/apps/callbacks/v2"
 )
 
 type App struct {
@@ -55,16 +58,18 @@ type App struct {
 
 ### Configure the `Keeper`s
 
-During initialization, besides initializing the IBC `Keeper`s (for core `ibc` and `transfer` modules), we need to grant specific capabilities through the capability module `ScopedKeeper`s so that we can authenticate the object-capability permissions for each of the IBC channels.
+Initialize the IBC `Keeper`s (for core `ibc` and `transfer` modules), and any additional modules you want to include. 
+
+:::note Notice
+The capability module has been removed in ibc-go v10, therefore the `ScopedKeeper` has also been removed
+:::
 
 ```go
 import (
   // other imports
   // ...
   authtypes "github.com/cosmos/cosmos-sdk/x/auth/types"
 
-  capabilitykeeper "github.com/cosmos/ibc-go/modules/capability/keeper"
-  capabilitytypes "github.com/cosmos/ibc-go/modules/capability/types"
   ibcexported "github.com/cosmos/ibc-go/v10/modules/core/exported"
   ibckeeper "github.com/cosmos/ibc-go/v10/modules/core/keeper"
   "github.com/cosmos/ibc-go/v10/modules/apps/transfer"
@@ -75,48 +80,73 @@ import (
 func NewApp(...args) *App {
   // define codecs and baseapp
 
-  // add capability keeper and ScopeToModule for ibc module
-  app.CapabilityKeeper = capabilitykeeper.NewKeeper(
-    appCodec,
-    keys[capabilitytypes.StoreKey],
-    memKeys[capabilitytypes.MemStoreKey],
-  )
-
-  // grant capabilities for the ibc and transfer modules
-  scopedIBCKeeper := app.CapabilityKeeper.ScopeToModule(ibcexported.ModuleName)
-  scopedTransferKeeper := app.CapabilityKeeper.ScopeToModule(ibctransfertypes.ModuleName)
-
   // ... other module keepers
 
   // Create IBC Keeper
   app.IBCKeeper = ibckeeper.NewKeeper(
-    appCodec,
-    keys[ibcexported.StoreKey],
-    app.GetSubspace(ibcexported.ModuleName),
-    app.UpgradeKeeper,
-    scopedIBCKeeper,
-    authtypes.NewModuleAddress(govtypes.ModuleName).String(),
-  )
+		appCodec,
+		runtime.NewKVStoreService(keys[ibcexported.StoreKey]),
+		app.GetSubspace(ibcexported.ModuleName),
+		app.UpgradeKeeper,
+		authtypes.NewModuleAddress(govtypes.ModuleName).String(),
+	)
 
   // Create Transfer Keeper
   app.TransferKeeper = ibctransferkeeper.NewKeeper(
-    appCodec,
-    keys[ibctransfertypes.StoreKey],
-    app.GetSubspace(ibctransfertypes.ModuleName),
-    app.IBCKeeper.ChannelKeeper,
-    app.IBCKeeper.ChannelKeeper,
-    app.IBCKeeper.PortKeeper,
-    app.AccountKeeper,
-    app.BankKeeper,
-    scopedTransferKeeper,
-    authtypes.NewModuleAddress(govtypes.ModuleName).String(),
-  )
-  transferModule := transfer.NewIBCModule(app.TransferKeeper)
+		appCodec,
+		runtime.NewKVStoreService(keys[ibctransfertypes.StoreKey]),
+		app.GetSubspace(ibctransfertypes.ModuleName),
+		app.IBCKeeper.ChannelKeeper,
+		app.IBCKeeper.ChannelKeeper,
+		app.MsgServiceRouter(),
+		app.AccountKeeper,
+		app.BankKeeper,
+		authtypes.NewModuleAddress(govtypes.ModuleName).String(),
+	)
 
   // ... continues
 }
 ```
 
+### Create Application Stacks with Middleware
+
+Middleware stacks in IBC allow you to wrap an `IBCModule` with additional logic for packets and acknowledgements. This is a chain of handlers that execute in order. The transfer stack below shows how to wire up transfer to use packet forward middleware, and the callbacks middleware. Note that the order is important. 
+
+```go
+// Create Transfer Stack for IBC Classic
+maxCallbackGas := uint64(10_000_000)
+wasmStackIBCHandler := wasm.NewIBCHandler(app.WasmKeeper, app.IBCKeeper.ChannelKeeper, app.IBCKeeper.ChannelKeeper)
+
+var transferStack porttypes.IBCModule
+transferStack = transfer.NewIBCModule(app.TransferKeeper)
+// callbacks wraps the transfer stack as its base app, and uses PacketForwardKeeper as the ICS4Wrapper
+// i.e. packet-forward-middleware is higher on the stack and sits between callbacks and the ibc channel keeper
+// Since this is the lowest level middleware of the transfer stack, it should be the first entrypoint for transfer keeper's
+// WriteAcknowledgement.
+cbStack := ibccallbacks.NewIBCMiddleware(transferStack, app.PacketForwardKeeper, wasmStackIBCHandler, maxCallbackGas)
+transferStack = packetforward.NewIBCMiddleware(
+  cbStack,
+  app.PacketForwardKeeper,
+  0, // retries on timeout
+  packetforwardkeeper.DefaultForwardTransferPacketTimeoutTimestamp,
+)
+```
+
+#### IBC v2 Application Stack
+
+For IBC v2, an example transfer stack is shown below. In this case the transfer stack is using the callbacks middleware.
+
+```go
+// Create IBC v2 transfer middleware stack
+// the callbacks gas limit is recommended to be 10M for use with wasm contracts
+maxCallbackGas := uint64(10_000_000)
+wasmStackIBCHandler := wasm.NewIBCHandler(app.WasmKeeper, app.IBCKeeper.ChannelKeeper, app.IBCKeeper.ChannelKeeper)
+
+var ibcv2TransferStack ibcapi.IBCModule
+	ibcv2TransferStack = transferv2.NewIBCModule(app.TransferKeeper)
+	ibcv2TransferStack = ibccallbacksv2.NewIBCMiddleware(transferv2.NewIBCModule(app.TransferKeeper), app.IBCKeeper.ChannelKeeperV2, wasmStackIBCHandler, app.IBCKeeper.ChannelKeeperV2, maxCallbackGas)
+```
+
 ### Register module routes in the IBC `Router`
 
 IBC needs to know which module is bound to which port so that it can route packets to the
@@ -126,8 +156,7 @@ by the port
 [`Router`](https://github.com/cosmos/ibc-go/blob/main/modules/core/05-port/types/router.go) on the
 `ibc` module.
 
-Adding the module routes allows the IBC handler to call the appropriate callback when processing a
-channel handshake or a packet.
+Adding the module routes allows the IBC handler to call the appropriate callback when processing a channel handshake or a packet.
 
 Currently, a `Router` is static so it must be initialized and set correctly on app initialization.
 Once the `Router` has been set, no new routes can be added.
@@ -145,17 +174,30 @@ func NewApp(...args) *App {
 
   // Create static IBC router, add transfer module route, then set and seal it
   ibcRouter := porttypes.NewRouter()
-  ibcRouter.AddRoute(ibctransfertypes.ModuleName, transferModule)
+	ibcRouter.AddRoute(ibctransfertypes.ModuleName, transferStack)
   // Setting Router will finalize all routes by sealing router
   // No more routes can be added
   app.IBCKeeper.SetRouter(ibcRouter)
 
   // ... continues
 ```
 
+#### IBC v2 Router
+
+With IBC v2, there is a new [router](https://github.com/cosmos/ibc-go/blob/main/modules/core/api/router.go) that needs to register the routes for a portID to a given IBCModule. 
+
+```go
+// IBC v2 router creation
+	ibcRouterV2 := ibcapi.NewRouter()
+	ibcRouterV2.AddRoute(ibctransfertypes.PortID, ibcv2TransferStack)
+  // Setting Router will finalize all routes by sealing router
+  // No more routes can be added
+	app.IBCKeeper.SetRouterV2(ibcRouterV2)
+```
+
 ### Module `Manager` and `SimulationManager`
 
-In order to use IBC, we need to add the new modules to the module `Manager` and to the `SimulationManager`, in case your application supports [simulations](https://github.com/cosmos/cosmos-sdk/blob/main/docs/build/building-modules/14-simulator.md).
+In order to use IBC, we need to add the new modules to the module `Manager` and to the `SimulationManager`, in case your application supports [simulations](https://docs.cosmos.network/main/learn/advanced/simulation).
 
 ```go title="app.go"
 import (
@@ -218,13 +260,11 @@ var (
 )
 ```
 
-#### Integrating light clients
-
-> Note that from v9 onwards, all light clients are expected to implement the [`LightClientInterface` interface](../03-light-clients/01-developer-guide/02-light-client-module.md#implementing-the-lightclientmodule-interface) defined by core IBC, and have to be explicitly registered in a chain's app.go. This is in contrast to earlier versions of ibc-go when `07-tendermint` and `06-solomachine` were added out of the box. Follow the steps below to integrate the `07-tendermint` light client.
+### Integrating light clients
 
-All light clients must be registered with `module.Manager` in a chain's app.go file.
+> Note that from v10 onwards, all light clients are expected to implement the [`LightClientInterface` interface](../03-light-clients/01-developer-guide/02-light-client-module.md#implementing-the-lightclientmodule-interface) defined by core IBC, and have to be explicitly registered in a chain's app.go. This is in contrast to earlier versions of ibc-go when `07-tendermint` and `06-solomachine` were added out of the box. Follow the steps below to integrate the `07-tendermint` light client. 
 
-The following code example shows how to instantiate `07-tendermint` light client module and register its `ibctm.AppModule`.
+All light clients must be registered with `module.Manager` in a chain's app.go file. The following code example shows how to instantiate `07-tendermint` light client module and register its `ibctm.AppModule`. 
 
 ```go title="app.go"
 import (
@@ -237,11 +277,12 @@ import (
 
 // app.go
 // after sealing the IBC router
-
+clientKeeper := app.IBCKeeper.ClientKeeper
 storeProvider := app.IBCKeeper.ClientKeeper.GetStoreProvider()
 
 tmLightClientModule := ibctm.NewLightClientModule(appCodec, storeProvider)
-app.IBCKeeper.ClientKeeper.AddRoute(ibctm.ModuleName, &tmLightClientModule)
+clientKeeper.AddRoute(ibctm.ModuleName, &tmLightClientModule)
+// ...
 app.ModuleManager = module.NewManager(
   // ...
   ibc.NewAppModule(app.IBCKeeper),
@@ -253,9 +294,19 @@ app.ModuleManager = module.NewManager(
 )
 ```
 
+#### Allowed Clients Params
+
+The allowed clients parameter defines an allow list of client types supported by the chain. The 
+default value is a single-element list containing the [`AllowedClients`](https://github.com/cosmos/ibc-go/blob/main/modules/core/02-client/types/client.pb.go#L248-L253) wildcard (`"*"`). Alternatively, the parameter
+may be set with a list of client types (e.g. `"06-solomachine","07-tendermint","09-localhost"`).
+A client type that is not registered on this list will fail upon creation or on genesis validation.
+Note that, since the client type is an arbitrary string, chains must not register two light clients
+which return the same value for the `ClientType()` function, otherwise the allow list check can be
+bypassed.
+
 ### Application ABCI ordering
 
-One addition from IBC is the concept of `HistoricalInfo` which is stored in the Cosmos SDK `x/staking` module. The number of records stored by `x/staking` is controlled by the `HistoricalEntries` parameter which stores `HistoricalInfo` on a per height basis.
+One addition from IBC is the concept of `HistoricalInfo` which is stored in the Cosmos SDK `x/staking` module. The number of records stored by `x/staking` is controlled by the `HistoricalEntries` parameter which stores `HistoricalInfo` on a per-height basis.
 Each entry contains the historical information for the `Header` and `ValidatorSet` of this chain which is stored
 at each height during the `BeginBlock` call. The `HistoricalInfo` is required to introspect a blockchain's prior state at a given height in order to verify the light client `ConsensusState` during the
 connection handshake.