ADR 27: Add support for Wasm based light client

Changelog

26/11/2020: Initial Draft
26/05/2023: Update after 02-client refactor and re-implementation by Strangelove
13/12/2023: Update after upstreaming of module to ibc-go

Status

Accepted and applied in v0.1.0 of 08-wasm

Abstract

In the Cosmos SDK light clients are currently 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.

Context

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 (if the light client is part of its codebase), re-build chains' binaries, pass a governance proposal and validators upgrade their nodes.

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.

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.

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 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.

params := clientKeeper.GetParams(ctx)
params.AllowedClients = append(params.AllowedClients, exported.Wasm)
clientKeeper.SetParams(ctx, params)

Adding a new light client contract is governance-gated. To upload a new light client users need to submit a governance v1 proposal 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 wasm_byte_code:

// MsgStoreCode defines the request type for the StoreCode rpc.
message MsgStoreCode {
  // signer address
  string signer = 1;
  // wasm byte code of light client contract. It can be raw or gzip compressed
  bytes wasm_byte_code = 2;
}

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).

// StoreCode defines a rpc handler method for MsgStoreCode
func (k Keeper) StoreCode(goCtx context.Context, msg *types.MsgStoreCode) (*types.MsgStoreCodeResponse, error) {
  if k.GetAuthority() != msg.Signer {
    return nil, errorsmod.Wrapf(ibcerrors.ErrUnauthorized, "expected %s, got %s", k.GetAuthority(), msg.Signer)
  }

  ctx := sdk.UnwrapSDKContext(goCtx)
  checksum, err := k.storeWasmCode(ctx, msg.WasmByteCode, ibcwasm.GetVM().StoreCode)
  if err != nil {
    return nil, errorsmod.Wrap(err, "failed to store wasm bytecode")
  }

  emitStoreWasmCodeEvent(ctx, checksum)

  return &types.MsgStoreCodeResponse{
    Checksum: checksum,
  }, nil
}

The contract's bytecode is not stored in state (it is actually unnecessary and wasteful to store it, since the Wasm VM already stores it and can be queried back, if needed). The checksum is simply the hash of the bytecode of the contract and it is stored in state in an entry with key checksums that contains the checksums for the bytecodes that have been stored.

How light client proxy works?

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 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 queryContract, which executes WasmVm.Query and returns the slice of bytes returned by the smart contract. This data is deserialized and passed as return argument.

type QueryMsg struct {
  Status               *StatusMsg               `json:"status,omitempty"`
  ExportMetadata       *ExportMetadataMsg       `json:"export_metadata,omitempty"`
  TimestampAtHeight    *TimestampAtHeightMsg    `json:"timestamp_at_height,omitempty"`
  VerifyClientMessage  *VerifyClientMessageMsg  `json:"verify_client_message,omitempty"`
  CheckForMisbehaviour *CheckForMisbehaviourMsg `json:"check_for_misbehaviour,omitempty"`
}

type verifyClientMessageMsg struct {
  ClientMessage *ClientMessage `json:"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, UpdateStaåte, 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 storetypes.KVStore,
  clientMsg exported.ClientMessage
) error {
  clientMessage, ok := clientMsg.(*ClientMessage)
  if !ok {
    return errorsmod.Wrapf(ibcerrors.ErrInvalidType, "expected type: %T, got: %T", &ClientMessage{}, clientMsg)
  }

  payload := QueryMsg{
    VerifyClientMessage: &VerifyClientMessageMsg{ClientMessage: clientMessage.Data},
  }
  _, err := wasmQuery[EmptyResult](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 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 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.

ADR 27: Add support for Wasm based light client

Changelog​

Status​

Abstract​

Context​

Decision​

How light client proxy works?​

Global Wasm VM variable​

Consequences​

Positive​

Negative​