From 074d341e59346e3d1fa906aa57e590cfb52949ca Mon Sep 17 00:00:00 2001 From: srdtrk <59252793+srdtrk@users.noreply.github.com> Date: Tue, 21 May 2024 21:37:22 +0800 Subject: [PATCH] docs: added a version matrix to callbacks and 08-wasm (#6339) * docs: 08-wasm README.md * docs: added readme for callbacks * docs: added callbacks middleware version matrix to the docs * docs: added 08-wasm versin matrix to docs * imp: added to readme --- .../04-wasm/03-integration.md | 16 ++++++++++ .../02-callbacks/02-integration.md | 15 ++++++++++ .../04-wasm/03-integration.md | 10 +++++++ .../02-callbacks/02-integration.md | 10 +++++++ .../04-wasm/03-integration.md | 10 +++++++ .../02-callbacks/02-integration.md | 10 +++++++ modules/apps/callbacks/README.md | 19 ++++++++++++ modules/light-clients/08-wasm/README.md | 29 +++++++++++++++++++ 8 files changed, 119 insertions(+) create mode 100644 modules/apps/callbacks/README.md create mode 100644 modules/light-clients/08-wasm/README.md diff --git a/docs/docs/03-light-clients/04-wasm/03-integration.md b/docs/docs/03-light-clients/04-wasm/03-integration.md index 33fd75fad9d..7d6d4541430 100644 --- a/docs/docs/03-light-clients/04-wasm/03-integration.md +++ b/docs/docs/03-light-clients/04-wasm/03-integration.md @@ -9,6 +9,22 @@ slug: /ibc/light-clients/wasm/integration Learn how to integrate the `08-wasm` module in a chain binary and about the recommended approaches depending on whether the [`x/wasm` module](https://github.com/CosmWasm/wasmd/tree/main/x/wasm) is already used in the chain. The following document only applies for Cosmos SDK chains. +## Importing the `08-wasm` module + +`08-wasm` has no stable releases yet. To use it, you need to import the git commit that contains the module with the compatible versions of `ibc-go` and `wasmvm`. To do so, run the following command with the desired git commit in your project: + +```sh +go get github.com/cosmos/ibc-go/modules/light-clients/08-wasm@7ee2a2452b79d0bc8316dc622a1243afa058e8cb +``` + +The following table shows the compatibility matrix between the `08-wasm` module, `ibc-go`, and `wasmvm`. + +| **Version** | **Git commit to import** | +|:--------------------------------:|:----------------------------------------:| +| `v0.1.1+ibc-go-v7.3-wasmvm-v1.5` | 7ee2a2452b79d0bc8316dc622a1243afa058e8cb | +| `v0.1.0+ibc-go-v8.0-wasmvm-v1.5` | 57fcdb9a9a9db9b206f7df2f955866dc4e10fef4 | +| `v0.1.0+ibc-go-v7.3-wasmvm-v1.5` | b306e7a706e1f84a5e11af0540987bd68de9bae5 | + ## `app.go` setup The sample code below shows the relevant integration points in `app.go` required to setup the `08-wasm` module in a chain binary. Since `08-wasm` is a light client module itself, please check out as well the section [Integrating light clients](../../01-ibc/02-integration.md#integrating-light-clients) for more information: diff --git a/docs/docs/04-middleware/02-callbacks/02-integration.md b/docs/docs/04-middleware/02-callbacks/02-integration.md index 404a4f22d38..d0ec7e03e1a 100644 --- a/docs/docs/04-middleware/02-callbacks/02-integration.md +++ b/docs/docs/04-middleware/02-callbacks/02-integration.md @@ -19,6 +19,21 @@ The callbacks middleware is a minimal and stateless implementation of the IBC mi The callbacks middleware, as the name suggests, plays the role of an IBC middleware and as such must be configured by chain developers to route and handle IBC messages correctly. For Cosmos SDK chains this setup is done via the `app/app.go` file, where modules are constructed and configured in order to bootstrap the blockchain application. +## Importing the callbacks middleware + +The callbacks middleware has no stable releases yet. To use it, you need to import the git commit that contains the module with the compatible version of `ibc-go`. To do so, run the following command with the desired git commit in your project: + +```sh +go get github.com/cosmos/ibc-go/modules/apps/callbacks@342c00b0f8bd7feeebf0780f208a820b0faf90d1 +``` + +The following table shows the compatibility matrix between the callbacks middleware, `ibc-go`. + +| **Version** | **Git commit to import** | +|:--------------------:|:----------------------------------------:| +| `v0.2.0+ibc-go-v8.0` | 342c00b0f8bd7feeebf0780f208a820b0faf90d1 | +| `v0.1.0+ibc-go-v7.3` | 17cf1260a9cdc5292512acc9bcf6336ef0d917f4 | + ## Configuring an application stack with the callbacks middleware As mentioned in [IBC middleware development](../../01-ibc/04-middleware/02-develop.md) an application stack may be composed of many or no middlewares that nest a base application. diff --git a/docs/versioned_docs/version-v7.5.x/03-light-clients/04-wasm/03-integration.md b/docs/versioned_docs/version-v7.5.x/03-light-clients/04-wasm/03-integration.md index 5e1246a4594..f3388627904 100644 --- a/docs/versioned_docs/version-v7.5.x/03-light-clients/04-wasm/03-integration.md +++ b/docs/versioned_docs/version-v7.5.x/03-light-clients/04-wasm/03-integration.md @@ -9,6 +9,16 @@ slug: /ibc/light-clients/wasm/integration Learn how to integrate the `08-wasm` module in a chain binary and about the recommended approaches depending on whether the [`x/wasm` module](https://github.com/CosmWasm/wasmd/tree/main/x/wasm) is already used in the chain. The following document only applies for Cosmos SDK chains. +## Importing the `08-wasm` module + +`08-wasm` has no stable releases yet. To use it, you need to import the git commit that contains the module with the compatible versions of `ibc-go` and `wasmvm`. To do so, run the following command with the desired git commit in your project: + +```sh +go get github.com/cosmos/ibc-go/modules/light-clients/08-wasm@7ee2a2452b79d0bc8316dc622a1243afa058e8cb +``` + +You can find the version matrix in [here](../../../../docs/03-light-clients/04-wasm/03-integration.md#importing-the-08-wasm-module). + ## `app.go` setup The sample code below shows the relevant integration points in `app.go` required to setup the `08-wasm` module in a chain binary. Since `08-wasm` is a light client module itself, please check out as well the section [Integrating light clients](../../01-ibc/02-integration.md#integrating-light-clients) for more information: diff --git a/docs/versioned_docs/version-v7.5.x/04-middleware/02-callbacks/02-integration.md b/docs/versioned_docs/version-v7.5.x/04-middleware/02-callbacks/02-integration.md index 57f484841d0..85b2a3b5889 100644 --- a/docs/versioned_docs/version-v7.5.x/04-middleware/02-callbacks/02-integration.md +++ b/docs/versioned_docs/version-v7.5.x/04-middleware/02-callbacks/02-integration.md @@ -19,6 +19,16 @@ The callbacks middleware is a minimal and stateless implementation of the IBC mi The callbacks middleware, as the name suggests, plays the role of an IBC middleware and as such must be configured by chain developers to route and handle IBC messages correctly. For Cosmos SDK chains this setup is done via the `app/app.go` file, where modules are constructed and configured in order to bootstrap the blockchain application. +## Importing the callbacks middleware + +The callbacks middleware has no stable releases yet. To use it, you need to import the git commit that contains the module with the compatible version of `ibc-go`. To do so, run the following command with the desired git commit in your project: + +```sh +go get github.com/cosmos/ibc-go/modules/apps/callbacks@17cf1260a9cdc5292512acc9bcf6336ef0d917f4 +``` + +You can find the version matrix in [here](../../../../docs/04-middleware/02-callbacks/02-integration.md#importing-the-callbacks-middleware). + ## Configuring an application stack with the callbacks middleware As mentioned in [IBC middleware development](../../01-ibc/04-middleware/01-develop.md) an application stack may be composed of many or no middlewares that nest a base application. diff --git a/docs/versioned_docs/version-v8.3.x/03-light-clients/04-wasm/03-integration.md b/docs/versioned_docs/version-v8.3.x/03-light-clients/04-wasm/03-integration.md index b1c333660c8..74bc33452de 100644 --- a/docs/versioned_docs/version-v8.3.x/03-light-clients/04-wasm/03-integration.md +++ b/docs/versioned_docs/version-v8.3.x/03-light-clients/04-wasm/03-integration.md @@ -9,6 +9,16 @@ slug: /ibc/light-clients/wasm/integration Learn how to integrate the `08-wasm` module in a chain binary and about the recommended approaches depending on whether the [`x/wasm` module](https://github.com/CosmWasm/wasmd/tree/main/x/wasm) is already used in the chain. The following document only applies for Cosmos SDK chains. +## Importing the `08-wasm` module + +`08-wasm` has no stable releases yet. To use it, you need to import the git commit that contains the module with the compatible versions of `ibc-go` and `wasmvm`. To do so, run the following command with the desired git commit in your project: + +```sh +go get github.com/cosmos/ibc-go/modules/light-clients/08-wasm@57fcdb9a9a9db9b206f7df2f955866dc4e10fef4 +``` + +You can find the version matrix in [here](../../../../docs/03-light-clients/04-wasm/03-integration.md#importing-the-08-wasm-module). + ## `app.go` setup The sample code below shows the relevant integration points in `app.go` required to setup the `08-wasm` module in a chain binary. Since `08-wasm` is a light client module itself, please check out as well the section [Integrating light clients](../../01-ibc/02-integration.md#integrating-light-clients) for more information: diff --git a/docs/versioned_docs/version-v8.3.x/04-middleware/02-callbacks/02-integration.md b/docs/versioned_docs/version-v8.3.x/04-middleware/02-callbacks/02-integration.md index 404a4f22d38..bcc2a2502eb 100644 --- a/docs/versioned_docs/version-v8.3.x/04-middleware/02-callbacks/02-integration.md +++ b/docs/versioned_docs/version-v8.3.x/04-middleware/02-callbacks/02-integration.md @@ -19,6 +19,16 @@ The callbacks middleware is a minimal and stateless implementation of the IBC mi The callbacks middleware, as the name suggests, plays the role of an IBC middleware and as such must be configured by chain developers to route and handle IBC messages correctly. For Cosmos SDK chains this setup is done via the `app/app.go` file, where modules are constructed and configured in order to bootstrap the blockchain application. +## Importing the callbacks middleware + +The callbacks middleware has no stable releases yet. To use it, you need to import the git commit that contains the module with the compatible version of `ibc-go`. To do so, run the following command with the desired git commit in your project: + +```sh +go get github.com/cosmos/ibc-go/modules/apps/callbacks@342c00b0f8bd7feeebf0780f208a820b0faf90d1 +``` + +You can find the version matrix in [here](../../../../docs/04-middleware/02-callbacks/02-integration.md#importing-the-callbacks-middleware). + ## Configuring an application stack with the callbacks middleware As mentioned in [IBC middleware development](../../01-ibc/04-middleware/02-develop.md) an application stack may be composed of many or no middlewares that nest a base application. diff --git a/modules/apps/callbacks/README.md b/modules/apps/callbacks/README.md new file mode 100644 index 00000000000..002fb414e8c --- /dev/null +++ b/modules/apps/callbacks/README.md @@ -0,0 +1,19 @@ +# Callbacks Middleware + +IBC was designed with callbacks between core IBC and IBC applications. IBC apps would send a packet to core IBC, and receive a callback on every step of that packet's lifecycle. This allows IBC applications to be built on top of core IBC, and to be able to execute custom logic on packet lifecycle events (e.g. unescrow tokens for ICS-20). + +This setup worked well for off-chain users interacting with IBC applications. However, we are now seeing the desire for secondary applications (e.g. smart contracts, modules) to call into IBC apps as part of their state machine logic and then do some actions on packet lifecycle events. + +The Callbacks Middleware allows for this functionality by allowing the packets of the underlying IBC applications to register callbacks to secondary applications for lifecycle events. These callbacks are then executed by the Callbacks Middleware when the corresponding packet lifecycle event occurs. + +After much discussion, the design was expanded to [an ADR](/architecture/adr-008-app-caller-cbs), and the Callbacks Middleware is an implementation of that ADR. + +## Version Matrix + +The callbacks middleware has no stable releases yet. To use it, you need to import the git commit that contains the module with the compatible version of `ibc-go`. To do so, run the following command with the desired git commit in your project: + +```sh +go get github.com/cosmos/ibc-go/modules/apps/callbacks@342c00b0f8bd7feeebf0780f208a820b0faf90d1 +``` + +You can find the version matrix for the callbacks middleware [here](https://github.com/cosmos/ibc-go/blob/main/docs/docs/04-middleware/02-callbacks/02-integration.md#importing-the-callbacks-middleware) diff --git a/modules/light-clients/08-wasm/README.md b/modules/light-clients/08-wasm/README.md new file mode 100644 index 00000000000..b9cdf984b2e --- /dev/null +++ b/modules/light-clients/08-wasm/README.md @@ -0,0 +1,29 @@ +# `08-wasm` + +## Overview + +Learn about the `08-wasm` light client proxy module. + +### Context + +Traditionally, light clients used by ibc-go have been implemented only in Go, and since ibc-go v7 (with the release of the 02-client refactor), they are [first-class Cosmos SDK modules](/architecture/adr-010-light-clients-as-sdk-modules). This means that updating existing light client implementations or adding support for new light clients is a multi-step, time-consuming process involving on-chain governance: it is necessary to modify the codebase of ibc-go (if the light client is part of its codebase), re-build chains' binaries, pass a governance proposal and have validators upgrade their nodes. + +### Motivation + +To break the limitation of being able to write light client implementations only in Go, the `08-wasm` adds support to run light clients written in a Wasm-compilable language. The light client byte code implements the entry points of a [CosmWasm](https://docs.cosmwasm.com/docs/) smart contract, and runs inside a Wasm VM. The `08-wasm` module exposes a proxy light client interface that routes incoming messages to the appropriate handler function, inside the Wasm VM, for execution. + +Adding a new light client to a chain is just as simple as submitting a governance proposal with the message that stores the byte code of the light client contract. No coordinated upgrade is needed. When the governance proposal passes and the message is executed, the contract is ready to be instantiated upon receiving a relayer-submitted `MsgCreateClient`. The process of creating a Wasm light client is the same as with a regular light client implemented in Go. + +### Use cases + +- Development of light clients for non-Cosmos ecosystem chains: state machines in other ecosystems are, in many cases, implemented in Rust, and thus there are probably libraries used in their light client implementations for which there is no equivalent in Go. This makes the development of a light client in Go very difficult, but relatively simple to do it in Rust. Therefore, writing a CosmWasm smart contract in Rust that implements the light client algorithm becomes a lower effort. + +## Version Matrix + +`08-wasm` has no stable releases yet. To use it, you need to import the git commit that contains the module with the compatible versions of `ibc-go` and `wasmvm`. To do so, run the following command with the desired git commit in your project: + +```sh +go get github.com/cosmos/ibc-go/modules/light-clients/08-wasm@7ee2a2452b79d0bc8316dc622a1243afa058e8cb +``` + +You can find the compatibility matrix between the `08-wasm` module, `ibc-go`, and `wasmvm` in [here](https://github.com/cosmos/ibc-go/blob/main/docs/docs/03-light-clients/04-wasm/03-integration.md#importing-the-08-wasm-module).