diff --git a/docs/requirements/ics08-requirements.md b/docs/requirements/ics08-requirements.md new file mode 100644 index 00000000000..34c5a4d51c7 --- /dev/null +++ b/docs/requirements/ics08-requirements.md @@ -0,0 +1,124 @@ + +# 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 | + \ No newline at end of file diff --git a/e2e/go.mod b/e2e/go.mod index 73db4fdc02b..90a52fd4e82 100644 --- a/e2e/go.mod +++ b/e2e/go.mod @@ -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 diff --git a/e2e/go.sum b/e2e/go.sum index 7fe5e2c6abb..895591217ca 100644 --- a/e2e/go.sum +++ b/e2e/go.sum @@ -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= @@ -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= diff --git a/modules/light-clients/08-wasm/types/querier_test.go b/modules/light-clients/08-wasm/types/querier_test.go index 51d66afbc17..f912480864b 100644 --- a/modules/light-clients/08-wasm/types/querier_test.go +++ b/modules/light-clients/08-wasm/types/querier_test.go @@ -131,6 +131,7 @@ func (suite *TypesTestSuite) TestStargateQuery() { testCases := []struct { name string malleate func() + expError error }{ { "success: custom query", @@ -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) @@ -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. @@ -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, @@ -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, @@ -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) @@ -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)}, }, } @@ -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))