docs: add docs folder for v8.0.x (cosmos#5078)

* docs: add docs folder for v8.0.x * fix links * docs: fixed with absolute url links * docs: fix more links --------- Co-authored-by: srdtrk <[email protected]> Co-authored-by: srdtrk <[email protected]>
hoangdv2429 · Dec 9, 2023 · 876e2c8 · 876e2c8
1 parent 9b1d502
commit 876e2c8
Show file tree

Hide file tree

Showing 117 changed files with 9,329 additions and 4 deletions.
diff --git a/docs/docs/01-ibc/06-proposals.md b/docs/docs/01-ibc/06-proposals.md
@@ -79,7 +79,7 @@ The client is attached to the expected Akash `chain_id`. Note that although the
 ### Step 2
 
 Anyone can submit the governance proposal to recover the client by executing the following via CLI.
-If the chain is on an ibc-go version older than v8, please see the [relevant documentation](https://ibc.cosmos.network/v7.3.x/ibc/proposals.html).
+If the chain is on an ibc-go version older than v8, please see the [relevant documentation](https://ibc.cosmos.network/v7/ibc/proposals.html).
 
 - From ibc-go v8 onwards
 

diff --git a/docs/docs/05-migrations/11-v7-to-v8.md b/docs/docs/05-migrations/11-v7-to-v8.md
@@ -175,8 +175,8 @@ Support for in-flight legacy recover client proposals (i.e. `ClientUpdateProposa
 
 Please note that ibc-go offers facilities to test an ibc-go upgrade:
 
-- All e2e tests of the repository can be [run with custom Docker chain images](../../../e2e/README.md#running-tests-with-custom-images).
-- An [importable workflow](../../../e2e/README.md#importable-workflow) that can be used from any other repository to test chain upgrades.
+- All e2e tests of the repository can be [run with custom Docker chain images](https://github.com/cosmos/ibc-go/blob/c5bac5e03a0eae449b9efe0d312258115c1a1e85/e2e/README.md#running-tests-with-custom-images).
+- An [importable workflow](https://github.com/cosmos/ibc-go/blob/c5bac5e03a0eae449b9efe0d312258115c1a1e85/e2e/README.md#importable-workflow) that can be used from any other repository to test chain upgrades.
 
 ### Transfer migration
 

diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
@@ -54,6 +54,10 @@ const config = {
               path: "main",
               banner: "unreleased",
             },
+            "v8.0.x": {
+              path: "v8",
+              banner: "none",
+            },
             "v7.3.x": {
               path: "v7",
               banner: "none",

diff --git a/docs/tutorials/01-fee/06-wire-fee-react.md b/docs/tutorials/01-fee/06-wire-fee-react.md
@@ -99,7 +99,7 @@ At this point, you should be able to see the ICS-29 fee UI in the app. See the d
 
 ## 3. Add the ICS-29 Fee to the transaction
 
-Since we will perform a `MultiMsgTx` and follow the [immediate incentivization flow](https://ibc.cosmos.network/v7.3.x/middleware/ics29-fee/msgs#escrowing-fees), we must import the required msg constructors from the `ts-client`.
+Since we will perform a `MultiMsgTx` and follow the [immediate incentivization flow](https://ibc.cosmos.network/v7/middleware/ics29-fee/msgs#escrowing-fees), we must import the required msg constructors from the `ts-client`.
 
 ```ts title="src/components/IgntSend.tsx"
 export default function IgntSend(props: IgntSendProps) {

diff --git a/docs/versioned_docs/version-v8.0.x/00-intro.md b/docs/versioned_docs/version-v8.0.x/00-intro.md
@@ -0,0 +1,16 @@
+---
+slug: /
+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).
+
+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 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.
diff --git a/docs/versioned_docs/version-v8.0.x/01-ibc/01-overview.md b/docs/versioned_docs/version-v8.0.x/01-ibc/01-overview.md
diff --git a/docs/versioned_docs/version-v8.0.x/01-ibc/02-integration.md b/docs/versioned_docs/version-v8.0.x/01-ibc/02-integration.md
@@ -0,0 +1,230 @@
+---
+title: Integration
+sidebar_label: Integration
+sidebar_position: 2
+slug: /ibc/integration
+---
+
+# Integration
+
+:::note Synopsis
+Learn how to integrate IBC to your application and send data packets to other chains.
+:::
+
+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.
+
+## 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:
+
+- Add required modules to the `module.BasicManager`
+- Define additional `Keeper` fields for the new modules on the `App` type
+- Add the module's `StoreKey`s and initialize their `Keeper`s
+- Set up corresponding routers and routes for the `ibc` module
+- Add the modules to the module `Manager`
+- Add modules to `Begin/EndBlockers` and `InitGenesis`
+- Update the module `SimulationManager` to enable simulations
+
+### Module `BasicManager` and `ModuleAccount` permissions
+
+The first step is to add the following modules to the `BasicManager`: `x/capability`, `x/ibc`,
+and `x/ibc-transfer`. After that, we need to grant `Minter` and `Burner` permissions to
+the `ibc-transfer` `ModuleAccount` to mint and burn relayed tokens.
+
+### Integrating light clients
+
+> Note that from v7 onwards, all light clients have to be explicitly registered in a chain's app.go and follow the steps listed below.
+> This is in contrast to earlier versions of ibc-go when `07-tendermint` and `06-solomachine` were added out of the box.
+
+All light clients must be registered with `module.BasicManager` in a chain's app.go file.
+
+The following code example shows how to register the existing `ibctm.AppModuleBasic{}` light client implementation.
+
+```go
+import (
+  ...
+  // highlight-next-line
++ ibctm "github.com/cosmos/ibc-go/v6/modules/light-clients/07-tendermint"
+  ...
+)
+
+// app.go
+var (
+  ModuleBasics = module.NewBasicManager(
+    // ...
+    capability.AppModuleBasic{},
+    ibc.AppModuleBasic{},
+    transfer.AppModuleBasic{}, // i.e ibc-transfer module
+
+    // register light clients on IBC
+    // highlight-next-line
++   ibctm.AppModuleBasic{},
+  )
+
+  // module account permissions
+  maccPerms = map[string][]string{
+    // other module accounts permissions
+    // ...
+    ibctransfertypes.ModuleName:    {authtypes.Minter, authtypes.Burner},
+  }
+)
+```
+
+### Application fields
+
+Then, we need to register the `Keepers` as follows:
+
+```go title="app.go"
+type App struct {
+  // baseapp, keys and subspaces definitions
+
+  // other keepers
+  // ...
+  IBCKeeper        *ibckeeper.Keeper // IBC Keeper must be a pointer in the app, so we can SetRouter on it correctly
+  TransferKeeper   ibctransferkeeper.Keeper // for cross-chain fungible token transfers
+
+  // make scoped keepers public for test purposes
+  ScopedIBCKeeper      capabilitykeeper.ScopedKeeper
+  ScopedTransferKeeper capabilitykeeper.ScopedKeeper
+
+  /// ...
+  /// module and simulation manager definitions
+}
+```
+
+### Configure the `Keepers`
+
+During initialization, besides initializing the IBC `Keepers` (for the `x/ibc`, and
+`x/ibc-transfer` modules), we need to grant specific capabilities through the capability module
+`ScopedKeepers` so that we can authenticate the object-capability permissions for each of the IBC
+channels.
+
+```go
+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 ibc-transfer modules
+  scopedIBCKeeper := app.CapabilityKeeper.ScopeToModule(ibcexported.ModuleName)
+  scopedTransferKeeper := app.CapabilityKeeper.ScopeToModule(ibctransfertypes.ModuleName)
+
+  // ... other modules keepers
+
+  // Create IBC Keeper
+  app.IBCKeeper = ibckeeper.NewKeeper(
+    appCodec, keys[ibcexported.StoreKey], app.GetSubspace(ibcexported.ModuleName), app.StakingKeeper, app.UpgradeKeeper, scopedIBCKeeper,
+  )
+
+  // Create Transfer Keepers
+  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,
+  )
+  transferModule := transfer.NewAppModule(app.TransferKeeper)
+
+  // .. continues
+}
+```
+
+### Register `Routers`
+
+IBC needs to know which module is bound to which port so that it can route packets to the
+appropriate module and call the appropriate callbacks. The port to module name mapping is handled by
+IBC's port `Keeper`. However, the mapping from module name to the relevant callbacks is accomplished
+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.
+
+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.
+
+```go title="app.go"
+func NewApp(...args) *App {
+  // .. continuation from above
+
+  // Create static IBC router, add ibc-transfer module route, then set and seal it
+  ibcRouter := port.NewRouter()
+  ibcRouter.AddRoute(ibctransfertypes.ModuleName, transferModule)
+  // Setting Router will finalize all routes by sealing router
+  // No more routes can be added
+  app.IBCKeeper.SetRouter(ibcRouter)
+
+  // .. continues
+```
+
+### Module Managers
+
+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).
+
+```go title="app.go"
+func NewApp(...args) *App {
+  // .. continuation from above
+
+  app.mm = module.NewManager(
+    // other modules
+    // ...
+    capability.NewAppModule(appCodec, *app.CapabilityKeeper),
+    ibc.NewAppModule(app.IBCKeeper),
+    transferModule,
+  )
+
+  // ...
+
+  app.sm = module.NewSimulationManager(
+    // other modules
+    // ...
+    capability.NewAppModule(appCodec, *app.CapabilityKeeper),
+    ibc.NewAppModule(app.IBCKeeper),
+    transferModule,
+  )
+
+  // .. continues
+```
+
+### Application ABCI Ordering
+
+One addition from IBC is the concept of `HistoricalEntries` which are stored on the staking module.
+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 historical info is required to introspect the
+past historical info at any given height in order to verify the light client `ConsensusState` during the
+connection handshake.
+
+```go title="app.go"
+func NewApp(...args) *App {
+  // .. continuation from above
+
+  // add staking and ibc modules to BeginBlockers
+  app.mm.SetOrderBeginBlockers(
+    // other modules ...
+    stakingtypes.ModuleName, ibcexported.ModuleName,
+  )
+
+  // ...
+
+  // NOTE: Capability module must occur first so that it can initialize any capabilities
+  // so that other modules that want to create or claim capabilities afterwards in InitChain
+  // can do so safely.
+  app.mm.SetOrderInitGenesis(
+    capabilitytypes.ModuleName,
+    // other modules ...
+    ibcexported.ModuleName, ibctransfertypes.ModuleName,
+  )
+
+  // .. continues
+```
+
+:::warning
+**IMPORTANT**: The capability module **must** be declared first in `SetOrderInitGenesis`
+:::
+
+That's it! You have now wired up the IBC module and are now able to send fungible tokens across
+different chains. If you want to have a broader view of the changes take a look into the SDK's
+[`SimApp`](https://github.com/cosmos/ibc-go/blob/main/testing/simapp/app.go).