feat: add wasm light client module to feat/wasm-clients branch

.gitignore

@@ -27,6 +27,7 @@ artifacts
 baseapp/data/*
 client/lcd/keys/*
 mytestnet
+modules/light-clients/08-wasm/types/ibc_08-wasm_client_data/
 
 # Testing
 coverage.txt
@@ -56,6 +57,8 @@ dependency-graph.png
 
 *.history
 
+tmp/
+*.wasm
 # Go
 go.work
 go.work.sum

docs/architecture/adr-027-ibc-wasm.md

@@ -3,147 +3,177 @@
 ## Changelog
 
 - 26/11/2020: Initial Draft
+- 26/05/2023: Update after 02-client refactor and re-implementation by Strangelove
 
 ## Status
 
 *Draft, needs updates*
 
 ## Abstract
 
-In the Cosmos SDK light clients are current hardcoded in Go. This makes upgrading existing IBC light clients or adding
-support for new light client a multi step process involving on-chain governance which is time-consuming.
+In the Cosmos SDK light clients are current hardcoded in Go. This makes upgrading existing IBC light clients or
+adding support for new light client a multi step process involving on-chain governance which is time-consuming.
 
-To remedy this, we are proposing a WASM VM to host light client bytecode, which allows easier upgrading of
-existing IBC light clients as well as adding support for new IBC light clients without requiring a code release and corresponding
-hard-fork event.
+To remedy this, we are proposing a Wasm VM to host light client bytecode, which allows easier upgrading of
+existing IBC light clients as well as adding support for new IBC light clients without requiring a code release and 
+corresponding hard-fork event.
 
 ## Context
 
-Currently in the SDK, light clients are defined as part of the codebase and are implemented as submodules under
-`ibc-go/core/modules/light-clients/`.
+Currently in ibc-go light clients are defined as part of the codebase and are implemented as modules under
+`modules/light-clients`. Adding support for new light clients or updating an existing light client in the event
+of a security issue or consensus update is a multi-step process which is both time consuming and error prone. 
+In order to enable new IBC light client implementations it is necessary to modify the codebase of ibc-go, 
+re-build chains' binaries, pass a governance proposal and validators upgrade their nodes.
 
-Adding support for new light client or update an existing light client in the event of security
-issue or consensus update is multi-step process which is both time consuming and error prone:
+Another problem stemming from the above process is that if a chain wants to upgrade its own consensus, it will 
+need to convince every chain or hub connected to it to upgrade its light client in order to stay connected. Due 
+to the time consuming process required to upgrade a light client, a chain with lots of connections needs to be 
+disconnected for quite some time after upgrading its consensus, which can be very expensive in terms of time and effort.
 
-1. To add support for new light client or update an existing light client in the
-   event of security issue or consensus update, we need to modify the codebase and integrate it in numerous places.
+We are proposing simplifying this workflow by integrating a Wasm light client module that makes adding support for
+new light clients a simple governance-gated transaction. The light client bytecode, written in Wasm-compilable Rust, 
+runs inside a Wasm VM. The Wasm light client submodule exposes a proxy light client interface that routes incoming 
+messages to the appropriate handler function, inside the Wasm VM for execution.
 
-2. Governance voting: Adding new light client implementations require governance support and is expensive: This is
-   not ideal as chain governance is gatekeeper for new light client implementations getting added. If a small community
-   want support for light client X, they may not be able to convince governance to support it.
-
-3. Validator upgrade: After governance voting succeeds, validators need to upgrade their nodes in order to enable new
-   IBC light client implementation.
-
-Another problem stemming from the above process is that if a chain wants to upgrade its own consensus, it will need to convince every chain
-or hub connected to it to upgrade its light client in order to stay connected. Due to time consuming process required
-to upgrade light client, a chain with lots of connections needs to be disconnected for quite some time after upgrading
-its consensus, which can be very expensive in terms of time and effort.
-
-We are proposing simplifying this workflow by integrating a WASM light client module which makes adding support for
-a new light client a simple transaction. The light client bytecode, written in Wasm-compilable Rust, runs inside a WASM
-VM. The Wasm light client submodule exposes a proxy light client interface that routes incoming messages to the
-appropriate handler function, inside the Wasm VM for execution.
-
-With WASM light client module, anybody can add new IBC light client in the form of WASM bytecode (provided they are able to pay the requisite gas fee for the transaction)
-as well as instantiate clients using any created client type. This allows any chain to update its own light client in other chains
-without going through steps outlined above.
+With the Wasm light client module, anybody can add new IBC light client in the form of Wasm bytecode (provided they are 
+able to submit the governance proposal transaction and that it passes) as well as instantiate clients using any created 
+client type. This allows any chain to update its own light client in other chains without going through the steps outlined above.
 
 ## Decision
 
-We decided to use WASM light client module as a light client proxy which will interface with the actual light client
-uploaded as WASM bytecode. This will require changing client selection method to allow any client if the client type
-has prefix of `wasm/`.
+We decided to implement the Wasm light client module as a light client proxy that will interface with the actual light client
+uploaded as Wasm bytecode. To enable usage of the Wasm light client module, users need to add it to the list of allowed clients
+by updating the `AllowedClients` parameter in the 02-client submodule of core IBC.
 
 ```go
-// IsAllowedClient checks if the given client type is registered on the allowlist.
-func (p Params) IsAllowedClient(clientType string) bool {
-  if p.AreWASMClientsAllowed && isWASMClient(clientType) {
-    return true
-  }
+params := clientKeeper.GetParams(ctx)
+params.AllowedClients = append(params.AllowedClients, exported.Wasm)
+clientKeeper.SetParams(ctx, params)
+```
 
-  for _, allowedClient := range p.AllowedClients {
-    if allowedClient == clientType {
-      return true
-    }
-  }
+Adding a new light client contract is governance-gated. To upload a new light client users need to submit 
+a [governance v1 proposal](https://docs.cosmos.network/main/modules/gov#proposals) that contains the `sdk.Msg` for storing 
+the Wasm contract's bytecode. The required message is `MsgStoreCode` and the bytecode is provided in the field `code`:
 
-  return false
+```proto
+// MsgStoreCode defines the request type for the StoreCode rpc.
+message MsgStoreCode {
+  string signer = 1;
+  bytes  code   = 2;
 }
 ```
 
-To upload new light client, user need to create a transaction with Wasm byte code which will be
-processed by IBC Wasm module.
+The RPC handler processing `MsgStoreCode` will make sure that the signer of the message matches the address of authority allowed to 
+submit this message (which is normally the address of the governance module).
 
 ```go
-func (k Keeper) UploadLightClient (wasmCode: []byte, description: String) {
-  wasmRegistry = getWASMRegistry()
-  id := hex.EncodeToString(sha256.Sum256(wasmCode))
-  assert(!wasmRegistry.Exists(id))
-  assert(wasmRegistry.ValidateAndStoreCode(id, description, wasmCode, false))
+// StoreCode defines a rpc handler method for MsgStoreCode
+func (k Keeper) StoreCode(goCtx context.Context, msg *types.MsgStoreCode) (*types.MsgStoreCodeResponse, error) {
+  ctx := sdk.UnwrapSDKContext(goCtx)
+
+  if k.authority != msg.Signer {
+    return nil, sdkerrors.Wrapf(govtypes.ErrInvalidSigner, "invalid authority: expected %s, got %s", k.authority, msg.Signer)
+  }
+
+  codeID, err := k.storeWasmCode(ctx, msg.Code)
+  if err != nil {
+    return nil, sdkerrors.Wrap(err, "storing wasm code failed")
+  }
+
+  ctx.EventManager().EmitEvents(sdk.Events{
+    sdk.NewEvent(
+      clienttypes.EventTypeStoreWasmCode,
+      sdk.NewAttribute(clienttypes.AttributeKeyWasmCodeID, hex.EncodeToString(codeID)),
+    ),
+    sdk.NewEvent(
+      sdk.EventTypeMessage,
+      sdk.NewAttribute(sdk.AttributeKeyModule, clienttypes.AttributeValueCategory),
+    ),
+  })
+
+  return &types.MsgStoreCodeResponse{
+    CodeId: codeID,
+  }, nil
 }
 ```
 
-As name implies, Wasm registry is a registry which stores set of Wasm client code indexed by its hash and allows
-client code to retrieve latest code uploaded.
-
-`ValidateAndStoreCode` checks if the wasm bytecode uploaded is valid and confirms to VM interface.
+The contract's bytecode is stored in state in an entry indexed by the code ID: `codeId/{code ID}`. The code ID is simply 
+the hash of the bytecode of the contract.
 
 ### How light client proxy works?
 
-The light client proxy behind the scenes will call a cosmwasm smart contract instance with incoming arguments in json
-serialized format with appropriate environment information. Data returned by the smart contract is deserialized and
+The light client proxy behind the scenes will call a CosmWasm smart contract instance with incoming arguments serialized 
+in JSON format with appropriate environment information. Data returned by the smart contract is deserialized and
 returned to the caller.
 
-Consider an example of `CheckProposedHeaderAndUpdateState` function of `ClientState` interface. Incoming arguments are
-packaged inside a payload which is json serialized and passed to `callContract` which calls `vm.Execute` and returns the
-array of bytes returned by the smart contract. This data is deserialized and passed as return argument.
+Consider the example of the `VerifyClientMessage` function of `ClientState` interface. Incoming arguments are
+packaged inside a payload object that is then JSON serialized and passed to `callContract`, which execute `WasmVm.Execute` 
+and returns the slice of bytes returned by the smart contract. This data is deserialized and passed as return argument.
 
 ```go
-func (c *ClientState) CheckProposedHeaderAndUpdateState(context sdk.Context, marshaler codec.BinaryMarshaler, store sdk.KVStore, header exported.ClientMessage) (exported.ClientState, exported.ConsensusState, error) {
-  // get consensus state corresponding to client state to check if the client is expired
-  consensusState, err := GetConsensusState(store, marshaler, c.LatestHeight)
-  if err != nil {
-    return nil, nil, sdkerrors.Wrapf(
-    err, "could not get consensus state from clientstore at height: %d", c.LatestHeight,
-    )
+type (
+  verifyClientMessageInnerPayload struct {
+    ClientMessage clientMessage `json:"client_message"`
   }
-
-  payload := make(map[string]map[string]interface{})
-  payload[CheckProposedHeaderAndUpdateState] = make(map[string]interface{})
-  inner := payload[CheckProposedHeaderAndUpdateState]
-  inner["me"] = c
-  inner["header"] = header
-  inner["consensus_state"] = consensusState
-
-  encodedData, err := json.Marshal(payload)
-  if err != nil {
-    return nil, nil, sdkerrors.Wrapf(ErrUnableToMarshalPayload, fmt.Sprintf("underlying error: %s", err.Error()))
+  clientMessage struct {
+    Header       *Header       `json:"header,omitempty"`
+    Misbehaviour *Misbehaviour `json:"misbehaviour,omitempty"`
   }
-  out, err := callContract(c.CodeId, context, store, encodedData)
-  if err != nil {
-    return nil, nil, sdkerrors.Wrapf(ErrUnableToCall, fmt.Sprintf("underlying error: %s", err.Error()))
+  verifyClientMessagePayload struct {
+    VerifyClientMessage verifyClientMessageInnerPayload `json:"verify_client_message"`
+  }
+)
+
+// VerifyClientMessage must verify a ClientMessage. A ClientMessage could be a Header, Misbehaviour, or batch update.
+// It must handle each type of ClientMessage appropriately. Calls to CheckForMisbehaviour, UpdateState, and UpdateStateOnMisbehaviour
+// will assume that the content of the ClientMessage has been verified and can be trusted. An error should be returned
+// if the ClientMessage fails to verify.
+func (cs ClientState) VerifyClientMessage(
+  ctx sdk.Context, 
+  _ codec.BinaryCodec, 
+  clientStore sdk.KVStore, 
+  clientMsg exported.ClientMessage
+) error {
+  clientMsgConcrete := clientMessage{
+    Header:       nil,
+    Misbehaviour: nil,
+  }
+  switch clientMsg := clientMsg.(type) {
+  case *Header:
+    clientMsgConcrete.Header = clientMsg
+  case *Misbehaviour:
+    clientMsgConcrete.Misbehaviour = clientMsg
   }
-  output := clientStateCallResponse{}
-  if err := json.Unmarshal(out.Data, &output); err != nil {
-    return nil, nil, sdkerrors.Wrapf(ErrUnableToUnmarshalPayload, fmt.Sprintf("underlying error: %s", err.Error()))
+  inner := verifyClientMessageInnerPayload{
+    ClientMessage: clientMsgConcrete,
   }
-  if !output.Result.IsValid {
-    return nil, nil, fmt.Errorf("%s error ocurred while updating client state", output.Result.ErrorMsg)
+  payload := verifyClientMessagePayload{
+    VerifyClientMessage: inner,
   }
-  output.resetImmutables(c)
-  return output.NewClientState, output.NewConsensusState, nil
+  _, err := call[contractResult](ctx, clientStore, &cs, payload)
+  return err
 }
 ```
 
+### Global Wasm VM variable
+
+The 08-wasm keeper structure keeps a reference to the Wasm VM instantiated in the keeper constructor function. The keeper uses 
+the Wasm VM to store the bytecode of light client contracts. However, the Wasm VM is also needed in the 08-wasm implementations of
+some of the `ClientState` interface functions to initialise a contract, execute calls on the contract and query the contract. Since
+the `ClientState` functions do not have access to the 08-wasm keeper, then it has been decided to keep a global pointer variable that
+points to the same instance as the one in the 08-wasm keeper. This global pointer variable is then used in the implementations of
+the `ClientState` functions. 
+
 ## Consequences
 
 ### Positive
 
-- Adding support for new light client or upgrading existing light client is way easier than before and only requires single transaction.
-- Improves maintainability of Cosmos SDK, since no change in codebase is required to support new client or upgrade it.
+- Adding support for new light client or upgrading existing light client is way easier than before and only requires single transaction instead of a hard-fork.
+- Improves maintainability of ibc-go, since no change in codebase is required to support new client or upgrade it.
+- The existence of support for Rust dependencies in light clients which may not exist in Go.
 
 ### Negative
 
-- Light clients need to be written in subset of rust which could compile in Wasm.
+- Light clients written in Rust need to be written in a subset of Rust which could compile in Wasm.
 - Introspecting light client code is difficult as only compiled bytecode exists in the blockchain.

docs/client/config.json

@@ -62,5 +62,13 @@
         }
       }
     },
+    {
+      "url": "./tmp-swagger-gen/ibc/lightclients/wasm/v1/query.swagger.json",
+      "operationIds": {
+        "rename": {
+          "Params": "WasmParams"
+        }
+      }
+    }
   ]
 }