Skip to content

Commit

Permalink
Merge branch 'main' into jim/enable-wasm-tests
Browse files Browse the repository at this point in the history
  • Loading branch information
DimitrisJim authored Feb 21, 2024
2 parents db2d064 + 87ee739 commit d2a4d3f
Show file tree
Hide file tree
Showing 4 changed files with 157 additions and 11 deletions.
124 changes: 124 additions & 0 deletions docs/requirements/ics08-requirements.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
<!-- markdown-link-check-disable -->
# Business requirements

Using IBC as a mean of communicating between chains and ecosystems has proven to be useful within Cosmos. There is then value in extending
this feature into other ecosystems, bringing a battle-tested protocol of trust-minimized communication as an option to send assets and data.

This is especially useful to protocols and companies whose business model is to improve cross-chain user interface, or to enable it when
it's not. The main use case for this is bridging assets between chains. There are multiple protocols and companies currently performing such
a service but none has yet been able to do it using IBC outside of the Cosmos ecosystem.

A core piece for this to happen is to have a light client implementation of each ecosystem that has to be integrated, and uses a **new** consensus
algorithm. This module broadens the horizon of light client development to not be limited to using Golang only for chains wanting to use IBC and ibc-go,
but instead expands the choice to any programming language and toolchain that is able to compile to Wasm instead.

Bridging assets is likely the simplest form of interchain communication. Its value is confirmed on a daily basis, when considering the volumes that protocols
like [Axelar](https://dappradar.com/multichain/defi/axelar-network), Gravity, [Wormhole](https://dappradar.com/multichain/defi/wormhole/) and
Layer0 process.

## Problem

In order to export IBC outside of Tendermint-based ecosystems, there is a need to introduce new light clients. This is a core need for
companies and protocols trying to bridge ecosystems such as Ethereum, NEAR, Polkadot, etc. as none of these uses Tendermint as their
consensus mechanism. Introducing a new light client implementation is not straightforward: sometimes cryptographic primitives are not
available, or support for operating with certain data structures (like specific tries/trees, etc) are not available in Go. The implementor needs to follow
the light client's specification, and will try to make use of all available tools to keep the development cost reasonable.

Normally, most of available tools to implement a light client stem from the blockchain ecosystem this client belongs to. Say for example, if a developer
wants to implement the Polkadot finality gadget called GRANDPA, she will find that most of the tools are available on Substrate. Hence, being able to have a way
to let developers implement these light clients using the best and most accessible tools for the job is very beneficial, as it avoids having to re-implement
features that are otherwise available and likely heavily audited already. And since Wasm is a well supported target that most programming languages support,
it becomes a proper solution to port the code for ibc-go to interpret without requiring the entire light client being written using Go.

## Objectives

The objective of this module is to have allow two chains with heterogenous consensus algorithms being connected through light clients that are not necesarily written in Go, but compiled to Wasm instead.

## Scope

The scope of this feature is to allow any implemention written in Wasm to be compliant with the interface
expressed in [02-client `ClientState` interface](https://github.com/cosmos/ibc-go/blob/main/modules/core/exported/client.go#L44-L139).

| Features | Release |
| ---------------------- | ------- |
| Store light client contract bytecode by means of a governance proposal. | v1 |
| Dispatch messages to a light client written in Wasm following the `ClientState` interface. | v1 |
| Migrate the contract instance of a light client to a newer contract bytecode. | v1 |
| Remove checksums from the list of allowed checksums to dissalow contract instantiation. | v1 |
| Support GRANDPA light client. | v1 |

# User requirements

## Use cases

The first use case that this module will enable is the connection between GRANDPA light client chains and Tendermint light client chains. Further implementation of other light clients, such as NEAR, Ethereum, etc. will likely consider building on top of this module.

# Functional requirements

## Assumptions

1. This feature expects the [02-client refactor completed](https://github.com/cosmos/ibc-go/milestone/16), which is enabled in ibc-go v7.

## Features

### 1 - Configuration

| ID | Description | Verification | Status | Release |
| -- | ----------- | ------------ | ------ | ------- |
| 1.01 | To enable the usage of the Wasm client module, chains must update the `AllowedClients` parameter in the 02-client submodule. | The `AllowedClients` needs to be updated to add the `08-wasm` client type. | `Verified` | v0.1.0 |
| 1.02 | The genesis state of the Wasm client module consists of the list of contracts' bytecode for each light client Wasm contract. | See [here](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/proto/ibc/lightclients/wasm/v1/genesis.proto#L12). | `Verified` | v0.1.0 |
| 1.03 | A chain shall have the ability to initialize the Wasm client module genesis state. | See [here](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/modules/light-clients/08-wasm/keeper/genesis.go#L12). | `Verified` | v0.1.0 |
| 1.04 | A chain shall have the ability to export the Wasm client module genesis state. | See [here](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/modules/light-clients/08-wasm/keeper/genesis.go#L24). | `Verified` | v0.1.0 |
| 1.05 | Chains that integrate the wasmd module may have the option to use the same wasm VM instance for both wasmd and the 08-wasm module. | A [keeper constructor function](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/modules/light-clients/08-wasm/keeper/keeper.go#L39) is provided that accepts a wasm VM pointer. | `Verified` | v0.1.0 |
| 1.06 | Chains that do not integrate the wasmd module may have the option to delegate to the 08-wasm module the instantiation of the necessary wasm VM. | A [keeper constructor function](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/modules/light-clients/08-wasm/keeper/keeper.go#L88) is provided that accepts parameters to configure the wasm VM that would instantiated by the module. | `Verified` | v0.1.0 |
| 1.07 | It may be possible to register custom query plugins for the 08-wasm module. | See [parameter in keeper constructor function](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/modules/light-clients/08-wasm/keeper/keeper.go#L45). | `Verified` | v0.1.0 |

### 2 - Initiation

| ID | Description | Verification | Status | Release |
| -- | ----------- | ------------ | ------ | ------- |
| 2.01 | Users must submit a governance proposal to store a light client implementation compiled in Wasm bytecode. | [`MsgStoreCode` is authority-gated](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/modules/light-clients/08-wasm/keeper/msg_server.go#L20). | `Verified` | v0.1.0 |
| 2.02 | Once a light client Wasm contract has been stored, every light client will be created with a new instance of the contract. | The [`Instantiate` endpoint](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/modules/light-clients/08-wasm/types/client_state.go#L129) of the contract is called when creating a new light client. | `Verified` | v0.1.0 |
| 2.03 | It must not be possible to initialize a light client with a bytecode checksum that has not been previously stored via `MsgStoreCode`. | Se check [here](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/modules/light-clients/08-wasm/types/client_state.go#L119). | `Verified` | v0.1.0 |

### 3 - Contract migration

| ID | Description | Verification | Status | Release |
| -- | ----------- | ------------ | ------ | ------- |
| 3.01 | Users may submit a governance proposal to remove a particular bytecode checksum from the list of allowed checksums. | [`MsgRemoveChecksum`](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/proto/ibc/lightclients/wasm/v1/tx.proto#L39) is available. | `Verified` | v0.1.0 |
| 3.02 | Users may submit a governance proposal to migrate a light client to a new contract instance specified by its contract checksum. | [`MsgMigrateContract`](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/proto/ibc/lightclients/wasm/v1/tx.proto#L52) is available. | `Verified` | v0.1.0 |

# Non-functional requirements

## 4 - Storage

| ID | Description | Verification | Status | Release |
| -- | ----------- | ------------ | ------ | ------- |
| 4.01 | The bytecode for each light client Wasm contract does not need to be stored in a client-prefixed store. | The [bytecode is stored only in the wasm VM](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/modules/light-clients/08-wasm/keeper/keeper.go#L137). | `Verified` | v0.1.0 |
| 4.02 | When a contract bytecode is stored it should also be pinned the wasm VM in-memory cache. | See [here](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/modules/light-clients/08-wasm/keeper/keeper.go#L148). | `Verified` | v0.1.0 |
| 4.03 | The size in bytes of bytecode of the light client Wasm contract must be > 0 and <= 3 MiB. | See validation [here](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/modules/light-clients/08-wasm/types/validation.go#L20). | `Verified` | v0.1.0 |

## 5 - Memory

| ID | Description | Verification | Status | Release |
| -- | ----------- | ------------ | ------ | ------- |
| 5.01 | Each contract execution memory limit is 32 MiB. | See [here](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/modules/light-clients/08-wasm/types/config.go#L8). | `Verified` | v0.1.0 |

## 6 - Security

| ID | Description | Verification | Status | Release |
| -- | ----------- | ------------ | ------ | ------- |
| 6.01 | The 08-wasm module must ensure that the contracts do not remove or corrupt the the stored client state state. | See [here](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/modules/light-clients/08-wasm/types/vm.go#L227). | `Verified` | v0.1.0 |
| 6.02 | The 08-wasm module must ensure that the contracts do not include in the response to sudo, instantiate or migrate calls messages, events or attributes. | See [here](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/modules/light-clients/08-wasm/types/vm.go#L300). | `Verified` | v0.1.0 |

# External interface requirements

## 7 - CLI

### Query

| ID | Description | Verification | Status | Release |
| -- | ----------- | ------------ | ------ | ------- |
| 6.01 | There shall be a CLI command available to query the bytecode of a light client Wasm contract by checksum. | See [here](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/modules/light-clients/08-wasm/keeper/grpc_query.go#L23). | `Verified` | v0.1.0 |
| 7.02 | There shall be a CLI command available to query the checksums for all deployed light client Wasm contracts. | See [here](https://github.com/cosmos/ibc-go/blob/modules/light-clients/08-wasm/v0.1.0%2Bibc-go-v8.0-wasmvm-v1.5/modules/light-clients/08-wasm/keeper/grpc_query.go#L49). | `Verified` | v0.1.0 |
<!-- markdown-link-check-enable-->
2 changes: 1 addition & 1 deletion e2e/go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ require (
github.com/docker/docker v24.0.7+incompatible
github.com/strangelove-ventures/interchaintest/v8 v8.1.0
github.com/stretchr/testify v1.8.4
go.uber.org/zap v1.26.0
go.uber.org/zap v1.27.0
golang.org/x/mod v0.15.0
google.golang.org/grpc v1.61.1
gopkg.in/yaml.v2 v2.4.0
Expand Down
8 changes: 4 additions & 4 deletions e2e/go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -1150,8 +1150,8 @@ go.uber.org/atomic v1.4.0/go.mod h1:gD2HeocX3+yG+ygLZcrzQJaqmWj9AIm7n08wl/qW/PE=
go.uber.org/atomic v1.5.0/go.mod h1:sABNBOSYdrvTF6hTgEIbc7YasKWGhgEQZyfxyTvoXHQ=
go.uber.org/atomic v1.7.0/go.mod h1:fEN4uk6kAWBTFdckzkM89CLk9XfWZrxpCo0nPH17wJc=
go.uber.org/goleak v1.1.10/go.mod h1:8a7PlsEVH3e/a/GLqe5IIrQx6GzcnRmZEufDUTk4A7A=
go.uber.org/goleak v1.2.0 h1:xqgm/S+aQvhWFTtR0XK3Jvg7z8kGV8P4X14IzwN3Eqk=
go.uber.org/goleak v1.2.0/go.mod h1:XJYK+MuIchqpmGmUSAzotztawfKvYLUIgg7guXrwVUo=
go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
go.uber.org/multierr v1.1.0/go.mod h1:wR5kodmAFQ0UK8QlbwjlSNy0Z68gJhDJUG5sjR94q/0=
go.uber.org/multierr v1.3.0/go.mod h1:VgVr7evmIr6uPjLBxg28wmKNXyqE9akIJ5XnfpiKl+4=
go.uber.org/multierr v1.6.0/go.mod h1:cdWPpRnG4AhwMwsgIHip0KRBQjJy5kYEpYjJxpXp9iU=
Expand All @@ -1161,8 +1161,8 @@ go.uber.org/tools v0.0.0-20190618225709-2cfd321de3ee/go.mod h1:vJERXedbb3MVM5f9E
go.uber.org/zap v1.10.0/go.mod h1:vwi/ZaCAaUcBkycHslxD9B2zi4UTXhF60s6SWpuDF0Q=
go.uber.org/zap v1.13.0/go.mod h1:zwrFLgMcdUuIBviXEYEH1YKNaOBnKXsx2IPda5bBwHM=
go.uber.org/zap v1.18.1/go.mod h1:xg/QME4nWcxGxrpdeYfq7UvYrLh66cuVKdrbD1XF/NI=
go.uber.org/zap v1.26.0 h1:sI7k6L95XOKS281NhVKOFCUNIvv9e0w4BF8N3u+tCRo=
go.uber.org/zap v1.26.0/go.mod h1:dtElttAiwGvoJ/vj4IwHBS/gXsEu/pZ50mUIRWuG0so=
go.uber.org/zap v1.27.0 h1:aJMhYGrd5QSmlpLMr2MftRKl7t8J8PTZPA732ud/XR8=
go.uber.org/zap v1.27.0/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
golang.org/x/crypto v0.0.0-20170613210332-850760c427c5/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=
golang.org/x/crypto v0.0.0-20180904163835-0709b304e793/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=
golang.org/x/crypto v0.0.0-20181029021203-45a5f77698d3/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=
Expand Down
34 changes: 28 additions & 6 deletions modules/light-clients/08-wasm/types/querier_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,7 @@ func (suite *TypesTestSuite) TestStargateQuery() {
testCases := []struct {
name string
malleate func()
expError error
}{
{
"success: custom query",
Expand All @@ -141,7 +142,7 @@ func (suite *TypesTestSuite) TestStargateQuery() {

ibcwasm.SetQueryPlugins(&querierPlugin)

suite.mockVM.RegisterQueryCallback(types.StatusMsg{}, func(_ wasmvm.Checksum, _ wasmvmtypes.Env, _ []byte, store wasmvm.KVStore, _ wasmvm.GoAPI, querier wasmvm.Querier, _ wasmvm.GasMeter, _ uint64, _ wasmvmtypes.UFraction) ([]byte, uint64, error) {
suite.mockVM.RegisterQueryCallback(types.TimestampAtHeightMsg{}, func(_ wasmvm.Checksum, _ wasmvmtypes.Env, _ []byte, store wasmvm.KVStore, _ wasmvm.GoAPI, querier wasmvm.Querier, _ wasmvm.GasMeter, _ uint64, _ wasmvmtypes.UFraction) ([]byte, uint64, error) {
queryRequest := types.QueryChecksumsRequest{}
bz, err := queryRequest.Marshal()
suite.Require().NoError(err)
Expand All @@ -165,9 +166,13 @@ func (suite *TypesTestSuite) TestStargateQuery() {

store.Set(testKey, value)

return resp, wasmtesting.DefaultGasUsed, nil
result, err := json.Marshal(types.TimestampAtHeightResult{})
suite.Require().NoError(err)

return result, wasmtesting.DefaultGasUsed, nil
})
},
nil,
},
{
// The following test sets a mock proof key and value in the ibc store and registers a query callback on the Status msg.
Expand All @@ -194,7 +199,7 @@ func (suite *TypesTestSuite) TestStargateQuery() {
merklePath, err := commitmenttypes.ApplyPrefix(suite.chainA.GetPrefix(), merklePath)
suite.Require().NoError(err)

suite.mockVM.RegisterQueryCallback(types.StatusMsg{}, func(_ wasmvm.Checksum, _ wasmvmtypes.Env, _ []byte, _ wasmvm.KVStore, _ wasmvm.GoAPI, querier wasmvm.Querier, _ wasmvm.GasMeter, _ uint64, _ wasmvmtypes.UFraction) ([]byte, uint64, error) {
suite.mockVM.RegisterQueryCallback(types.TimestampAtHeightMsg{}, func(_ wasmvm.Checksum, _ wasmvmtypes.Env, _ []byte, _ wasmvm.KVStore, _ wasmvm.GoAPI, querier wasmvm.Querier, _ wasmvm.GasMeter, _ uint64, _ wasmvmtypes.UFraction) ([]byte, uint64, error) {
queryRequest := clienttypes.QueryVerifyMembershipRequest{
ClientId: endpoint.ClientID,
Proof: proof,
Expand All @@ -220,7 +225,10 @@ func (suite *TypesTestSuite) TestStargateQuery() {

suite.Require().True(respData.Success)

return resp, wasmtesting.DefaultGasUsed, nil
result, err := json.Marshal(types.TimestampAtHeightResult{})
suite.Require().NoError(err)

return result, wasmtesting.DefaultGasUsed, nil
})

suite.mockVM.RegisterSudoCallback(types.VerifyMembershipMsg{}, func(_ wasmvm.Checksum, _ wasmvmtypes.Env, sudoMsg []byte, store wasmvm.KVStore,
Expand All @@ -247,11 +255,12 @@ func (suite *TypesTestSuite) TestStargateQuery() {
return &wasmvmtypes.Response{Data: bz}, wasmtesting.DefaultGasUsed, nil
})
},
nil,
},
{
"failure: default querier",
func() {
suite.mockVM.RegisterQueryCallback(types.StatusMsg{}, func(_ wasmvm.Checksum, _ wasmvmtypes.Env, _ []byte, store wasmvm.KVStore, _ wasmvm.GoAPI, querier wasmvm.Querier, _ wasmvm.GasMeter, _ uint64, _ wasmvmtypes.UFraction) ([]byte, uint64, error) {
suite.mockVM.RegisterQueryCallback(types.TimestampAtHeightMsg{}, func(_ wasmvm.Checksum, _ wasmvmtypes.Env, _ []byte, store wasmvm.KVStore, _ wasmvm.GoAPI, querier wasmvm.Querier, _ wasmvm.GasMeter, _ uint64, _ wasmvmtypes.UFraction) ([]byte, uint64, error) {
queryRequest := types.QueryChecksumsRequest{}
bz, err := queryRequest.Marshal()
suite.Require().NoError(err)
Expand All @@ -270,6 +279,7 @@ func (suite *TypesTestSuite) TestStargateQuery() {
return nil, wasmtesting.DefaultGasUsed, err
})
},
wasmvmtypes.UnsupportedRequest{Kind: fmt.Sprintf("'%s' path is not allowed from the contract", typeURL)},
},
}

Expand All @@ -286,7 +296,19 @@ func (suite *TypesTestSuite) TestStargateQuery() {

clientStore := suite.chainA.App.GetIBCKeeper().ClientKeeper.ClientStore(suite.chainA.GetContext(), endpoint.ClientID)
clientState := endpoint.GetClientState()
clientState.Status(suite.chainA.GetContext(), clientStore, suite.chainA.App.AppCodec())

// NOTE: we register query callbacks against: types.TimestampAtHeightMsg{}
// in practise, this can against any client state msg, however registering against types.StatusMsg{} introduces recursive loops
// due to test case: "success: verify membership query"
_, err = clientState.GetTimestampAtHeight(suite.chainA.GetContext(), clientStore, suite.chainA.App.AppCodec(), clienttypes.NewHeight(1, 100))

expPass := tc.expError == nil
if expPass {
suite.Require().NoError(err)
} else {
// use error contains as wasmvm errors do not implement errors.Is method
suite.Require().ErrorContains(err, tc.expError.Error())
}

if expDiscardedState {
suite.Require().False(clientStore.Has(testKey))
Expand Down

0 comments on commit d2a4d3f

Please sign in to comment.