wasm

package module
v10.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 10, 2025 License: MIT Imports: 24 Imported by: 9

README

08-wasm

Overview

Learn about the 08-wasm light client proxy module.

Context

Traditionally, light clients used by ibc-go have been implemented only in Go, and since ibc-go v7 (with the release of the 02-client refactor), they are first-class Cosmos SDK modules. This means that updating existing light client implementations or adding support for new light clients is a multi-step, time-consuming process involving on-chain governance: 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 have validators upgrade their nodes.

Motivation

To break the limitation of being able to write light client implementations only in Go, the 08-wasm adds support to run light clients written in a Wasm-compilable language. The light client byte code implements the entry points of a CosmWasm smart contract, and runs inside a Wasm VM. The 08-wasm module exposes a proxy light client interface that routes incoming messages to the appropriate handler function, inside the Wasm VM, for execution.

Adding a new light client to a chain is just as simple as submitting a governance proposal with the message that stores the byte code of the light client contract. No coordinated upgrade is needed. When the governance proposal passes and the message is executed, the contract is ready to be instantiated upon receiving a relayer-submitted MsgCreateClient. The process of creating a Wasm light client is the same as with a regular light client implemented in Go.

Use cases
  • Development of light clients for non-Cosmos ecosystem chains: state machines in other ecosystems are, in many cases, implemented in Rust, and thus there are probably libraries used in their light client implementations for which there is no equivalent in Go. This makes the development of a light client in Go very difficult, but relatively simple to do it in Rust. Therefore, writing a CosmWasm smart contract in Rust that implements the light client algorithm becomes a lower effort.

Version Matrix

08-wasm has no stable releases yet. To use it, you need to import the git commit that contains the module with the compatible versions of ibc-go and wasmvm. To do so, run the following command with the desired git commit in your project:

go get github.com/cosmos/ibc-go/modules/light-clients/08-wasm@7ee2a2452b79d0bc8316dc622a1243afa058e8cb

You can find the compatibility matrix between the 08-wasm module, ibc-go, and wasmvm in here.

Documentation

Overview

Package wasm implements a concrete LightClientModule, ClientState, ConsensusState, ClientMessage and types for the proxy light client module communicating with underlying Wasm light clients. This implementation is based off the ICS 08 specification (https://github.com/cosmos/ibc/blob/main/spec/client/ics-008-wasm-client)

By default the 08-wasm module requires cgo and libwasmvm dependencies available on the system. However, users of this module may want to depend only on types, without incurring the dependency on cgo or libwasmvm. In this case, it is possible to build the code with either cgo disabled or a custom build directive: nolink_libwasmvm. This allows disabling linking of libwasmvm and not forcing users to have specific libraries available on their systems.

Please refer to the 08-wasm module documentation for more information.

Note that client identifiers are expected to be in the form: 08-wasm-{N}. Client identifiers are generated and validated by core IBC, unexpected client identifiers will result in errors.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AppModule 

type AppModule struct {
	AppModuleBasic
	// contains filtered or unexported fields
}

AppModule represents the AppModule for this module

func NewAppModule 

func NewAppModule(k keeper.Keeper) AppModule

NewAppModule creates a new 08-wasm module

func (AppModule) ConsensusVersion 

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements AppModule/ConsensusVersion.

func (AppModule) ExportGenesis 

func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage

func (AppModule) InitGenesis 

func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, bz json.RawMessage)

func (AppModule) IsAppModule 

func (AppModule) IsAppModule()

IsAppModule implements the appmodule.AppModule interface.

func (AppModule) IsOnePerModuleType 

func (AppModule) IsOnePerModuleType()

IsOnePerModuleType implements the depinject.OnePerModuleType interface.

func (AppModule) ProposalMsgs 

func (AppModule) ProposalMsgs(simState module.SimulationState) []simtypes.WeightedProposalMsg

ProposalMsgs returns msgs used for governance proposals for simulations.

func (AppModule) RegisterServices 

func (am AppModule) RegisterServices(cfg module.Configurator)

RegisterServices registers module services.

type AppModuleBasic 

type AppModuleBasic struct{}

AppModuleBasic defines the basic application module used by the Wasm light client. Only the RegisterInterfaces function needs to be implemented. All other function perform a no-op.

func (AppModuleBasic) DefaultGenesis 

func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage

DefaultGenesis returns an empty state, i.e. no contracts

func (AppModuleBasic) GetQueryCmd 

func (AppModuleBasic) GetQueryCmd() *cobra.Command

GetQueryCmd implements AppModuleBasic interface

func (AppModuleBasic) GetTxCmd 

func (AppModuleBasic) GetTxCmd() *cobra.Command

GetTxCmd implements AppModuleBasic interface

func (AppModuleBasic) Name 

func (AppModuleBasic) Name() string

Name returns the tendermint module name.

func (AppModuleBasic) RegisterGRPCGatewayRoutes 

func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux)

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for Wasm client module.

func (AppModuleBasic) RegisterInterfaces 

func (AppModuleBasic) RegisterInterfaces(registry codectypes.InterfaceRegistry)

RegisterInterfaces registers module concrete types into protobuf Any. This allows core IBC to unmarshal Wasm light client types.

func (AppModuleBasic) RegisterLegacyAminoCodec 

func (AppModuleBasic) RegisterLegacyAminoCodec(*codec.LegacyAmino)

RegisterLegacyAminoCodec performs a no-op. The Wasm client does not support amino.

func (AppModuleBasic) ValidateGenesis 

func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, _ client.TxEncodingConfig, bz json.RawMessage) error

ValidateGenesis performs a no-op.

type LightClientModule 

type LightClientModule struct {
	// contains filtered or unexported fields
}

LightClientModule implements the core IBC api.LightClientModule interface.

func NewLightClientModule 

func NewLightClientModule(keeper wasmkeeper.Keeper, storeProvider clienttypes.StoreProvider) LightClientModule

NewLightClientModule creates and returns a new 08-wasm LightClientModule.

func (LightClientModule) CheckForMisbehaviour 

func (l LightClientModule) CheckForMisbehaviour(ctx sdk.Context, clientID string, clientMsg exported.ClientMessage) bool

CheckForMisbehaviour obtains the client state associated with the client identifier, it detects misbehaviour in a submitted Header message and verifies the correctness of a submitted Misbehaviour ClientMessage.

func (LightClientModule) Initialize 

func (l LightClientModule) Initialize(ctx sdk.Context, clientID string, clientStateBz, consensusStateBz []byte) error

Initialize unmarshals the provided client and consensus states and performs basic validation. It sets the client state and consensus state in the client store. It also initializes the wasm contract for the client.

func (LightClientModule) LatestHeight 

func (l LightClientModule) LatestHeight(ctx sdk.Context, clientID string) exported.Height

LatestHeight returns the latest height for the client state for the given client identifier. If no client is present for the provided client identifier a zero value height is returned.

func (LightClientModule) RecoverClient 

func (l LightClientModule) RecoverClient(ctx sdk.Context, clientID, substituteClientID string) error

RecoverClient asserts that the substitute client is a wasm client. It obtains the client state associated with the subject client and calls into the appropriate contract endpoint. It will verify that a substitute client state is valid and update the subject client state. Note that this method is used only for recovery and will not allow changes to the checksum.

func (LightClientModule) Status 

func (l LightClientModule) Status(ctx sdk.Context, clientID string) exported.Status

Status obtains the client state associated with the client identifier and calls into the appropriate contract endpoint. It returns the status of the wasm client. The client may be: - Active: frozen height is zero and client is not expired - Frozen: frozen height is not zero - Expired: the latest consensus state timestamp + trusting period <= current time - Unauthorized: the client type is not registered as an allowed client type

A frozen client will become expired, so the Frozen status has higher precedence.

func (LightClientModule) TimestampAtHeight 

func (l LightClientModule) TimestampAtHeight(ctx sdk.Context, clientID string, height exported.Height) (uint64, error)

TimestampAtHeight obtains the client state associated with the client identifier and calls into the appropriate contract endpoint. It returns the timestamp in nanoseconds of the consensus state at the given height.

func (LightClientModule) UpdateState 

func (l LightClientModule) UpdateState(ctx sdk.Context, clientID string, clientMsg exported.ClientMessage) []exported.Height

UpdateState obtains the client state associated with the client identifier and calls into the appropriate contract endpoint. Client state and new consensus states are updated in the store by the contract.

func (LightClientModule) UpdateStateOnMisbehaviour 

func (l LightClientModule) UpdateStateOnMisbehaviour(ctx sdk.Context, clientID string, clientMsg exported.ClientMessage)

UpdateStateOnMisbehaviour obtains the client state associated with the client identifier performs appropriate state changes on a client state given that misbehaviour has been detected and verified. Client state is updated in the store by the contract.

func (LightClientModule) VerifyClientMessage 

func (l LightClientModule) VerifyClientMessage(ctx sdk.Context, clientID string, clientMsg exported.ClientMessage) error

VerifyClientMessage obtains the client state associated with the client identifier, it then must verify the 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 (LightClientModule) VerifyMembership 

func (l LightClientModule) VerifyMembership(
	ctx sdk.Context,
	clientID string,
	height exported.Height,
	delayTimePeriod uint64,
	delayBlockPeriod uint64,
	proof []byte,
	path exported.Path,
	value []byte,
) error

VerifyMembership obtains the client state associated with the client identifier and calls into the appropriate contract endpoint. VerifyMembership is a generic proof verification method which verifies a proof of the existence of a value at a given CommitmentPath at the specified height. The caller is expected to construct the full CommitmentPath from a CommitmentPrefix and a standardized path (as defined in ICS 24). If a zero proof height is passed in, it will fail to retrieve the associated consensus state.

func (LightClientModule) VerifyNonMembership 

func (l LightClientModule) VerifyNonMembership(
	ctx sdk.Context,
	clientID string,
	height exported.Height,
	delayTimePeriod uint64,
	delayBlockPeriod uint64,
	proof []byte,
	path exported.Path,
) error

VerifyNonMembership obtains the client state associated with the client identifier and calls into the appropriate contract endpoint. VerifyNonMembership is a generic proof verification method which verifies the absence of a given CommitmentPath at a specified height. The caller is expected to construct the full CommitmentPath from a CommitmentPrefix and a standardized path (as defined in ICS 24). If a zero proof height is passed in, it will fail to retrieve the associated consensus state.

func (LightClientModule) VerifyUpgradeAndUpdateState 

func (l LightClientModule) VerifyUpgradeAndUpdateState(
	ctx sdk.Context,
	clientID string,
	newClient []byte,
	newConsState []byte,
	upgradeClientProof,
	upgradeConsensusStateProof []byte,
) error

VerifyUpgradeAndUpdateState obtains the client state associated with the client identifier and calls into the appropriate contract endpoint. The new client and consensus states will be unmarshaled and an error is returned if the new client state is not at a height greater than the existing client. On a successful verification, it expects the contract to update the new client state, consensus state, and any other client metadata.

Source Files

View all Source files

Directories

Path Synopsis
client
cli
internal
types
simapp
simapp/params
Package params defines the simulation parameters in the simapp.
 Package params defines the simulation parameters in the simapp.
simapp/simd command
simapp/simd/cmd
Package types is a reverse proxy.
 Package types is a reverse proxy.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.