Skip to content

Commit

Permalink
docs: update links in wasm docs + create versioned docs (cosmos#5445)
Browse files Browse the repository at this point in the history 
* docs: update links in wasm docs + create versioned docs

* add appCodec to initializedPinnedCodes

* fix argument passed

* another fix

* unfortunately it seems like markdown link checker does not like encoded characters in the URL

* fix broken links

* Apply suggestions from code review

Co-authored-by: DimitrisJim <[email protected]>

* fix import name

* review comment

* wasm -> ibcwasm as per Damians suggestion

Co-authored-by: Damian Nolan <[email protected]>

---------

Co-authored-by: DimitrisJim <[email protected]>
Co-authored-by: Damian Nolan <[email protected]>
  • Loading branch information
@crodriguezvega @DimitrisJim @damiannolan
3 people authored Dec 20, 2023
1 parent 443398f commit 2d0d94a
Show file tree
Hide file tree
Showing 24 changed files with 1,975 additions and 51 deletions.
78 changes: 39 additions & 39 deletions docs/docs/03-light-clients/04-wasm/03-integration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,9 @@ import (

cmtos "github.com/cometbft/cometbft/libs/os"

wasm "github.com/cosmos/ibc-go/modules/light-clients/08-wasm"
wasmkeeper "github.com/cosmos/ibc-go/modules/light-clients/08-wasm/keeper"
wasmtypes "github.com/cosmos/ibc-go/modules/light-clients/08-wasm/types"
ibcwasm "github.com/cosmos/ibc-go/modules/light-clients/08-wasm"
ibcwasmkeeper "github.com/cosmos/ibc-go/modules/light-clients/08-wasm/keeper"
ibcwasmtypes "github.com/cosmos/ibc-go/modules/light-clients/08-wasm/types"
...
)

Expand All @@ -32,14 +32,14 @@ import (
// Register the AppModule for the 08-wasm module
ModuleBasics = module.NewBasicManager(
...
wasm.AppModuleBasic{},
ibcwasm.AppModuleBasic{},
...
)

// Add 08-wasm Keeper
type SimApp struct {
...
WasmClientKeeper wasmkeeper.Keeper
WasmClientKeeper ibcwasmkeeper.Keeper
...
}

Expand All @@ -54,7 +54,7 @@ func NewSimApp(
...
keys := sdk.NewKVStoreKeys(
...
wasmtypes.StoreKey,
ibcwasmtypes.StoreKey,
)

// Instantiate 08-wasm's keeper
Expand All @@ -63,9 +63,9 @@ func NewSimApp(
// This is the recommended approach when the chain
// also uses `x/wasm`, and then the Wasm VM instance
// can be shared.
app.WasmClientKeeper = wasmkeeper.NewKeeperWithVM(
app.WasmClientKeeper = ibcwasmkeeper.NewKeeperWithVM(
appCodec,
runtime.NewKVStoreService(keys[wasmtypes.StoreKey]),
runtime.NewKVStoreService(keys[ibcwasmtypes.StoreKey]),
app.IBCKeeper.ClientKeeper,
authtypes.NewModuleAddress(govtypes.ModuleName).String(),
wasmVM,
Expand All @@ -74,21 +74,21 @@ func NewSimApp(
app.ModuleManager = module.NewManager(
// SDK app modules
...
wasm.NewAppModule(app.WasmClientKeeper),
ibcwasm.NewAppModule(app.WasmClientKeeper),
)
app.ModuleManager.SetOrderBeginBlockers(
...
wasmtypes.ModuleName,
ibcwasmtypes.ModuleName,
...
)
app.ModuleManager.SetOrderEndBlockers(
...
wasmtypes.ModuleName,
ibcwasmtypes.ModuleName,
...
)
genesisModuleOrder := []string{
...
wasmtypes.ModuleName,
ibcwasmtypes.ModuleName,
...
}
app.ModuleManager.SetOrderInitGenesis(genesisModuleOrder...)
Expand All @@ -102,7 +102,7 @@ func NewSimApp(
// must be before Loading version
if manager := app.SnapshotManager(); manager != nil {
err := manager.RegisterExtensions(
wasmkeeper.NewWasmSnapshotter(app.CommitMultiStore(), &app.WasmClientKeeper),
ibcwasmkeeper.NewWasmSnapshotter(app.CommitMultiStore(), &app.WasmClientKeeper),
)
if err != nil {
panic(fmt.Errorf("failed to register snapshot extension: %s", err))
Expand All @@ -116,7 +116,7 @@ func NewSimApp(
ctx := app.BaseApp.NewUncachedContext(true, cmtproto.Header{})

// Initialize pinned codes in wasmvm as they are not persisted there
if err := wasmkeeper.InitializePinnedCodes(ctx); err != nil {
if err := ibcwasmkeeper.InitializePinnedCodes(ctx); err != nil {
cmtos.Exit(fmt.Sprintf("failed initialize pinned codes %s", err))
}
}
Expand All @@ -136,7 +136,7 @@ In order to share the Wasm VM instance please follow the guideline below. Please
- Instantiate the Wasm VM in `app.go` with the parameters of your choice.
- [Create an `Option` with this Wasm VM instance](https://github.com/CosmWasm/wasmd/blob/db93d7b6c7bb6f4a340d74b96a02cec885729b59/x/wasm/keeper/options.go#L21-L25).
- Add the option created in the previous step to a slice and [pass it to the `x/wasm NewKeeper` constructor function](https://github.com/CosmWasm/wasmd/blob/db93d7b6c7bb6f4a340d74b96a02cec885729b59/x/wasm/keeper/keeper_cgo.go#L36).
- Pass the pointer to the Wasm VM instance to `08-wasm` [NewKeeperWithVM constructor function](https://github.com/cosmos/ibc-go/blob/c95c22f45cb217d27aca2665af9ac60b0d2f3a0c/modules/light-clients/08-wasm/keeper/keeper.go#L33-L38).
- Pass the pointer to the Wasm VM instance to `08-wasm` [NewKeeperWithVM constructor function](https://github.com/cosmos/ibc-go/blob/57fcdb9a9a9db9b206f7df2f955866dc4e10fef4/modules/light-clients/08-wasm/keeper/keeper.go#L39-L47).

The code to set this up would look something like this:

Expand All @@ -147,7 +147,7 @@ import (
"github.com/cosmos/cosmos-sdk/runtime"

wasmvm "github.com/CosmWasm/wasmvm"
wasmkeeper "github.com/CosmWasm/wasmd/x/wasm/keeper"
ibcwasmkeeper "github.com/CosmWasm/wasmd/x/wasm/keeper"
...
)

Expand All @@ -167,15 +167,15 @@ if err != nil {

// create an Option slice (or append to an existing one)
// with the option to use a custom Wasm VM instance
wasmOpts = []wasmkeeper.Option{
wasmkeeper.WithWasmEngine(wasmer),
wasmOpts = []ibcwasmkeeper.Option{
ibcwasmkeeper.WithWasmEngine(wasmer),
}

// the keeper will use the provided Wasm VM instance,
// instead of instantiating a new one
app.WasmKeeper = wasmkeeper.NewKeeper(
app.WasmKeeper = ibcwasmkeeper.NewKeeper(
appCodec,
keys[wasmtypes.StoreKey],
keys[ibcwasmtypes.StoreKey],
app.AccountKeeper,
app.BankKeeper,
app.StakingKeeper,
Expand All @@ -194,9 +194,9 @@ app.WasmKeeper = wasmkeeper.NewKeeper(
wasmOpts...,
)

app.WasmClientKeeper = wasmkeeper.NewKeeperWithVM(
app.WasmClientKeeper = ibcwasmkeeper.NewKeeperWithVM(
appCodec,
runtime.NewKVStoreService(keys[wasmtypes.StoreKey]),
runtime.NewKVStoreService(keys[ibcwasmtypes.StoreKey]),
app.IBCKeeper.ClientKeeper,
authtypes.NewModuleAddress(govtypes.ModuleName).String(),
wasmer, // pass the Wasm VM instance to `08-wasm` keeper constructor
Expand All @@ -208,14 +208,14 @@ app.WasmClientKeeper = wasmkeeper.NewKeeperWithVM(
### If `x/wasm` is not present

If the chain does not use [`x/wasm`](https://github.com/CosmWasm/wasmd/tree/main/x/wasm), even though it is still possible to use the method above from the previous section
(e.g. instantiating a Wasm VM in app.go an pass it to 08-wasm's [`NewKeeperWithVM` constructor function](https://github.com/cosmos/ibc-go/blob/c95c22f45cb217d27aca2665af9ac60b0d2f3a0c/modules/light-clients/08-wasm/keeper/keeper.go#L33-L38), since there would be no need in this case to share the Wasm VM instance with another module, you can use the [`NewKeeperWithConfig`` constructor function](https://github.com/cosmos/ibc-go/blob/c95c22f45cb217d27aca2665af9ac60b0d2f3a0c/modules/light-clients/08-wasm/keeper/keeper.go#L52-L57) and provide the Wasm VM configuration parameters of your choice instead. A Wasm VM instance will be created in`NewKeeperWithConfig`. The parameters that can set are:
(e.g. instantiating a Wasm VM in app.go an pass it to 08-wasm's [`NewKeeperWithVM` constructor function](https://github.com/cosmos/ibc-go/blob/57fcdb9a9a9db9b206f7df2f955866dc4e10fef4/modules/light-clients/08-wasm/keeper/keeper.go#L39-L47), since there would be no need in this case to share the Wasm VM instance with another module, you can use the [`NewKeeperWithConfig`` constructor function](https://github.com/cosmos/ibc-go/blob/57fcdb9a9a9db9b206f7df2f955866dc4e10fef4/modules/light-clients/08-wasm/keeper/keeper.go#L88-L96) and provide the Wasm VM configuration parameters of your choice instead. A Wasm VM instance will be created in`NewKeeperWithConfig`. The parameters that can set are:

- `DataDir` is the [directory for Wasm blobs and various caches](https://github.com/CosmWasm/wasmvm/blob/1638725b25d799f078d053391945399cb35664b1/lib.go#L25). In `wasmd` this is set to the [`wasm` folder under the home directory](https://github.com/CosmWasm/wasmd/blob/36416def20effe47fb77f29f5ba35a003970fdba/app/app.go#L578).
- `SupportedCapabilities` is a comma separated [list of capabilities supported by the chain](https://github.com/CosmWasm/wasmvm/blob/1638725b25d799f078d053391945399cb35664b1/lib.go#L26). [`wasmd` sets this to all the available capabilities](https://github.com/CosmWasm/wasmd/blob/36416def20effe47fb77f29f5ba35a003970fdba/app/app.go#L586), but 08-wasm only requires `iterator`.
- `MemoryCacheSize` sets [the size in MiB of an in-memory cache for e.g. module caching](https://github.com/CosmWasm/wasmvm/blob/1638725b25d799f078d053391945399cb35664b1/lib.go#L29C16-L29C104). It is not consensus-critical and should be defined on a per-node basis, often in the range 100 to 1000 MB. [`wasmd` reads this value of](https://github.com/CosmWasm/wasmd/blob/36416def20effe47fb77f29f5ba35a003970fdba/app/app.go#L579). Default value is 256.
- `ContractDebugMode` is a [flag to enable/disable printing debug logs from the contract to STDOUT](https://github.com/CosmWasm/wasmvm/blob/1638725b25d799f078d053391945399cb35664b1/lib.go#L28). This should be false in production environments. Default value is false.

Another configuration parameter of the Wasm VM is the contract memory limit (in MiB), which is [set to 32](https://github.com/cosmos/ibc-go/blob/c95c22f45cb217d27aca2665af9ac60b0d2f3a0c/modules/light-clients/08-wasm/types/config.go#L5), [following the example of `wasmd`](https://github.com/CosmWasm/wasmd/blob/36416def20effe47fb77f29f5ba35a003970fdba/x/wasm/keeper/keeper.go#L32-L34). This parameter is not configurable by users of `08-wasm`.
Another configuration parameter of the Wasm VM is the contract memory limit (in MiB), which is [set to 32](https://github.com/cosmos/ibc-go/blob/57fcdb9a9a9db9b206f7df2f955866dc4e10fef4/modules/light-clients/08-wasm/types/config.go#L8), [following the example of `wasmd`](https://github.com/CosmWasm/wasmd/blob/36416def20effe47fb77f29f5ba35a003970fdba/x/wasm/keeper/keeper.go#L32-L34). This parameter is not configurable by users of `08-wasm`.

The following sample code shows how the keeper would be constructed using this method:

Expand All @@ -225,27 +225,27 @@ import (
...
"github.com/cosmos/cosmos-sdk/runtime"

wasmkeeper "github.com/CosmWasm/wasmd/x/wasm/keeper"
wasmtypes "github.com/cosmos/ibc-go/modules/light-clients/08-wasm/types"
ibcwasmkeeper "github.com/CosmWasm/wasmd/x/wasm/keeper"
ibcwasmtypes "github.com/cosmos/ibc-go/modules/light-clients/08-wasm/types"
...
)
...
wasmConfig := wasmtypes.WasmConfig{
wasmConfig := ibcwasmtypes.WasmConfig{
DataDir: "ibc_08-wasm_client_data",
SupportedCapabilities: "iterator",
ContractDebugMode: false,
}
app.WasmClientKeeper = wasmkeeper.NewKeeperWithConfig(
app.WasmClientKeeper = ibcwasmkeeper.NewKeeperWithConfig(
appCodec,
runtime.NewKVStoreService(keys[wasmtypes.StoreKey]),
runtime.NewKVStoreService(keys[ibcwasmtypes.StoreKey]),
app.IBCKeeper.ClientKeeper,
authtypes.NewModuleAddress(govtypes.ModuleName).String(),
wasmConfig,
app.GRPCQueryRouter(),
)
```

Check out also the [`WasmConfig` type definition](https://github.com/cosmos/ibc-go/blob/c95c22f45cb217d27aca2665af9ac60b0d2f3a0c/modules/light-clients/08-wasm/types/config.go#L7-L20) for more information on each of the configurable parameters. Some parameters allow node-level configurations. There is additionally the function [`DefaultWasmConfig`](https://github.com/cosmos/ibc-go/blob/6d8cee53a72524b7cf396d65f6c19fed45803321/modules/light-clients/08-wasm/types/config.go#L30) available that returns a configuration with the default values.
Check out also the [`WasmConfig` type definition](https://github.com/cosmos/ibc-go/blob/57fcdb9a9a9db9b206f7df2f955866dc4e10fef4/modules/light-clients/08-wasm/types/config.go#L21-L31) for more information on each of the configurable parameters. Some parameters allow node-level configurations. There is additionally the function [`DefaultWasmConfig`](https://github.com/cosmos/ibc-go/blob/57fcdb9a9a9db9b206f7df2f955866dc4e10fef4/modules/light-clients/08-wasm/types/config.go#L36-L42) available that returns a configuration with the default values.

### Options

Expand Down Expand Up @@ -282,9 +282,9 @@ querierOption := ibcwasmkeeper.WithQueryPlugins(&queryPlugins)
Finally, we pass the option to the `NewKeeperWithConfig` or `NewKeeperWithVM` constructor function during [Keeper instantiation](#keeper-instantiation):

```diff
app.WasmClientKeeper = wasmkeeper.NewKeeperWithConfig(
app.WasmClientKeeper = ibcwasmkeeper.NewKeeperWithConfig(
appCodec,
runtime.NewKVStoreService(keys[wasmtypes.StoreKey]),
runtime.NewKVStoreService(keys[ibcwasmtypes.StoreKey]),
app.IBCKeeper.ClientKeeper,
authtypes.NewModuleAddress(govtypes.ModuleName).String(),
wasmConfig,
Expand All @@ -294,9 +294,9 @@ app.WasmClientKeeper = wasmkeeper.NewKeeperWithConfig(
```

```diff
app.WasmClientKeeper = wasmkeeper.NewKeeperWithVM(
app.WasmClientKeeper = ibcwasmkeeper.NewKeeperWithVM(
appCodec,
runtime.NewKVStoreService(keys[wasmtypes.StoreKey]),
runtime.NewKVStoreService(keys[ibcwasmtypes.StoreKey]),
app.IBCKeeper.ClientKeeper,
authtypes.NewModuleAddress(govtypes.ModuleName).String(),
wasmer, // pass the Wasm VM instance to `08-wasm` keeper constructor
Expand All @@ -307,12 +307,12 @@ app.WasmClientKeeper = wasmkeeper.NewKeeperWithVM(

## Updating `AllowedClients`

In order to use the `08-wasm` module chains must update the [`AllowedClients` parameter in the 02-client submodule](https://github.com/cosmos/ibc-go/blob/main/proto/ibc/core/client/v1/client.proto#L103) of core IBC. This can be configured directly in the application upgrade handler with the sample code below:
In order to use the `08-wasm` module chains must update the [`AllowedClients` parameter in the 02-client submodule](https://github.com/cosmos/ibc-go/blob/v8.0.0/proto/ibc/core/client/v1/client.proto#L64) of core IBC. This can be configured directly in the application upgrade handler with the sample code below:

```go
import (
...
wasmtypes "github.com/cosmos/ibc-go/modules/light-clients/08-wasm/types"
ibcwasmtypes "github.com/cosmos/ibc-go/modules/light-clients/08-wasm/types"
...
)

Expand All @@ -327,7 +327,7 @@ func CreateWasmUpgradeHandler(
sdkCtx := sdk.UnwrapSDKContext(ctx)
// explicitly update the IBC 02-client params, adding the wasm client type
params := clientKeeper.GetParams(ctx)
params.AllowedClients = append(params.AllowedClients, wasmtypes.Wasm)
params.AllowedClients = append(params.AllowedClients, ibcwasmtypes.Wasm)
clientKeeper.SetParams(ctx, params)

return mm.RunMigrations(ctx, configurator, vm)
Expand Down Expand Up @@ -361,8 +361,8 @@ func (app SimApp) RegisterUpgradeHandlers() {

## Adding snapshot support

In order to use the `08-wasm` module chains are required to register the `WasmSnapshotter` extension in the snapshot manager. This snapshotter takes care of persisting the external state, in the form of contract code, of the Wasm VM instance to disk when the chain is snapshotted. [This code](https://github.com/cosmos/ibc-go/blob/2bd29c08fd1fe50b461fc33a25735aa792dc896e/modules/light-clients/08-wasm/testing/simapp/app.go#L768-L776) should be placed in `NewSimApp` function in `app.go`.
In order to use the `08-wasm` module chains are required to register the `WasmSnapshotter` extension in the snapshot manager. This snapshotter takes care of persisting the external state, in the form of contract code, of the Wasm VM instance to disk when the chain is snapshotted. [This code](https://github.com/cosmos/ibc-go/blob/57fcdb9a9a9db9b206f7df2f955866dc4e10fef4/modules/light-clients/08-wasm/testing/simapp/app.go#L775-L782) should be placed in `NewSimApp` function in `app.go`.

## Pin byte codes at start

Wasm byte codes should be pinned to the WasmVM cache on every application start, therefore [this code](https://github.com/cosmos/ibc-go/blob/0ed221f687ffce75984bc57402fd678e07aa6cc5/modules/light-clients/08-wasm/testing/simapp/app.go#L821-L826) should be placed in `NewSimApp` function in `app.go`.
Wasm byte codes should be pinned to the WasmVM cache on every application start, therefore [this code](https://github.com/cosmos/ibc-go/blob/57fcdb9a9a9db9b206f7df2f955866dc4e10fef4/modules/light-clients/08-wasm/testing/simapp/app.go#L825-L830) should be placed in `NewSimApp` function in `app.go`.
4 changes: 2 additions & 2 deletions docs/docs/03-light-clients/04-wasm/04-messages.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ This message is expected to fail if:

Only light client contracts stored using `MsgStoreCode` are allowed to be instantiated. An attempt to create a light client from contracts uploaded via other means (e.g. through `x/wasm` if the module shares the same Wasm VM instance with 08-wasm) will fail. Due to the idempotent nature of the Wasm VM's `StoreCode` function, it is possible to store the same byte code multiple times.

When execution of `MsgStoreCode` succeeds, the checksum of the contract (i.e. the sha256 hash of the contract's byte code) is stored in an allow list. When a relayer submits [`MsgCreateClient`](https://github.com/cosmos/ibc-go/blob/v7.2.0/proto/ibc/core/client/v1/tx.proto#L25-L37) with 08-wasm's `ClientState`, the client state includes the checksum of the Wasm byte code that should be called. Then 02-client calls [08-wasm's implementation of `Initialize` function](https://github.com/cosmos/ibc-go/blob/v7.2.0/modules/core/02-client/keeper/client.go#L34) (which is an interface function part of `ClientState`), and it will check that the checksum in the client state matches one of the checksums in the allow list. If a match is found, the light client is initialized; otherwise, the transaction is aborted.
When execution of `MsgStoreCode` succeeds, the checksum of the contract (i.e. the sha256 hash of the contract's byte code) is stored in an allow list. When a relayer submits [`MsgCreateClient`](https://github.com/cosmos/ibc-go/blob/v8.0.0/proto/ibc/core/client/v1/tx.proto#L25-L37) with 08-wasm's `ClientState`, the client state includes the checksum of the Wasm byte code that should be called. Then 02-client calls [08-wasm's implementation of `Initialize` function](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/02-client/keeper/client.go#L36) (which is an interface function part of `ClientState`), and it will check that the checksum in the client state matches one of the checksums in the allow list. If a match is found, the light client is initialized; otherwise, the transaction is aborted.

## `MsgMigrateContract`

Expand Down Expand Up @@ -72,4 +72,4 @@ This message is expected to fail if:
- `Signer` is an invalid Bech32 address, or it does not match the designated authority address.
- `Checksum` is not exactly 32 bytes long or it is not found in the list of allowed checksums (a new checksum is added to the list when executing `MsgStoreCode`).

When a checksum is removed from the list of allowed checksums, then the corresponding Wasm byte code will not be available for instantiation in [08-wasm's implementation of `Initialize` function](https://github.com/cosmos/ibc-go/blob/v7.2.0/modules/core/02-client/keeper/client.go#L34).
When a checksum is removed from the list of allowed checksums, then the corresponding Wasm byte code will not be available for instantiation in [08-wasm's implementation of `Initialize` function](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/core/02-client/keeper/client.go#L36).
Loading

0 comments on commit 2d0d94a

Please sign in to comment.