cosmwasm

README

wasmvm

This is a wrapper around the CosmWasm VM. It allows you to compile, initialize and execute CosmWasm smart contracts from Go applications, in particular from x/wasm.

Structure

This repo contains both Rust and Go code. The rust code is compiled into a dll/so to be linked via cgo and wrapped with a pleasant Go API. The full build step involves compiling rust -> C library, and linking that library to the Go code. For ergonomics of the user, we will include pre-compiled libraries to easily link with, and Go developers should just be able to import this directly.

Supported Platforms

Requires Rust 1.55+ and Go 1.17+.

The Rust implementation of the VM is compiled to a library called libwasmvm. This is then linked to the Go code when the final binary is built. For that reason not all systems supported by Go are supported by this project.

Linux (tested on Ubuntu, Debian, and CentOS7, Alpine) and macOS is supported. We are working on Windows (#288).

Builds of libwasmvm

Our system currently supports the following builds. In general we can only support targets that are supported by Wasmer's singlepass backend, which for example excludes all 32 bit systems.

OS family	Arch	Linking	Supported	Note
Linux (glibc)	x86_64	shared	✅​libwasmvm.x86_64.so
Linux (glibc)	x86_64	static	🚫​	Would link libwasmvm statically but glibc dynamically as static glibc linking is not recommended. Potentially interesting for Osmosis.
Linux (glibc)	aarch64	shared	✅​libwasmvm.aarch64.so
Linux (glibc)	aarch64	static	🚫​
Linux (musl)	x86_64	shared	🚫​	Possible but not needed
Linux (musl)	x86_64	static	✅​libwasmvm_muslc.x86_64.a
Linux (musl)	aarch64	shared	🚫​	Possible but not needed
Linux (musl)	aarch64	static	✅​libwasmvm_muslc.aarch64.a
macOS	x86_64	shared	✅​libwasmvm.dylib	Fat/universal library with multiple archs (#294)
macOS	x86_64	static	🚫​
macOS	aarch64	shared	✅​libwasmvm.dylib	Fat/universal library with multiple archs (#294)
macOS	aarch64	static	🚫​
Windows (mingw)	x86_64	shared	🏗​wasmvm.dll	See #288
Windows (mingw)	x86_64	static	🚫​
Windows (mingw)	aarch64	shared	🚫​
Windows (mingw)	aarch64	static	🚫​

Docs

Run (cd libwasmvm && cargo doc --no-deps --open).

Design

Please read the Documentation to understand both the general Architecture, as well as the more detailed Specification of the parameters and entry points.

Development

There are two halfs to this code - go and rust. The first step is to ensure that there is a proper dll built for your platform. This should be api/libwasmvm.X, where X is:

• so for Linux systems
• dylib for MacOS
• dll for Windows - Not currently supported due to upstream dependency

If this is present, then make test will run the Go test suite and you can import this code freely. If it is not present you will have to build it for your system, and ideally add it to this repo with a PR (on your fork). We will set up a proper CI system for building these binaries, but we are not there yet.

To build the rust side, try make build-rust and wait for it to compile. This depends on cargo being installed with rustc version 1.47+. Generally, you can just use rustup to install all this with no problems.

Toolchain

We fix the Rust version in the CI and build containers, so the following should be in sync:

• .circleci/config.yml
• builders/Dockerfile.*

For development you should be able to use any reasonably up-to-date Rust stable.

Documentation

Index

• func LibwasmvmVersion() (string, error)
• type Checksum
• type GasMeter
• type GoAPI
• type KVStore
• type Querier
• type VM
  • func NewVM(dataDir string, supportedFeatures string, memoryLimit uint32, printDebug bool, ...) (*VM, error)
  • func (vm *VM) AnalyzeCode(checksum Checksum) (*types.AnalysisReport, error)
  • func (vm *VM) Cleanup()
  • func (vm *VM) Create(code WasmCode) (Checksum, error)
  • func (vm *VM) Execute(checksum Checksum, env types.Env, info types.MessageInfo, executeMsg []byte, ...) (*types.Response, uint64, error)
  • func (vm *VM) GetCode(checksum Checksum) (WasmCode, error)
  • func (vm *VM) GetMetrics() (*types.Metrics, error)
  • func (vm *VM) IBCChannelClose(checksum Checksum, env types.Env, msg types.IBCChannelCloseMsg, store KVStore, ...) (*types.IBCBasicResponse, uint64, error)
  • func (vm *VM) IBCChannelConnect(checksum Checksum, env types.Env, msg types.IBCChannelConnectMsg, ...) (*types.IBCBasicResponse, uint64, error)
  • func (vm *VM) IBCChannelOpen(checksum Checksum, env types.Env, msg types.IBCChannelOpenMsg, store KVStore, ...) (*types.IBC3ChannelOpenResponse, uint64, error)
  • func (vm *VM) IBCPacketAck(checksum Checksum, env types.Env, msg types.IBCPacketAckMsg, store KVStore, ...) (*types.IBCBasicResponse, uint64, error)
  • func (vm *VM) IBCPacketReceive(checksum Checksum, env types.Env, msg types.IBCPacketReceiveMsg, store KVStore, ...) (*types.IBCReceiveResult, uint64, error)
  • func (vm *VM) IBCPacketTimeout(checksum Checksum, env types.Env, msg types.IBCPacketTimeoutMsg, store KVStore, ...) (*types.IBCBasicResponse, uint64, error)
  • func (vm *VM) Instantiate(checksum Checksum, env types.Env, info types.MessageInfo, initMsg []byte, ...) (*types.Response, uint64, error)
  • func (vm *VM) Migrate(checksum Checksum, env types.Env, migrateMsg []byte, store KVStore, ...) (*types.Response, uint64, error)
  • func (vm *VM) Pin(checksum Checksum) error
  • func (vm *VM) Query(checksum Checksum, env types.Env, queryMsg []byte, store KVStore, goapi GoAPI, ...) ([]byte, uint64, error)
  • func (vm *VM) Reply(checksum Checksum, env types.Env, reply types.Reply, store KVStore, ...) (*types.Response, uint64, error)
  • func (vm *VM) Sudo(checksum Checksum, env types.Env, sudoMsg []byte, store KVStore, goapi GoAPI, ...) (*types.Response, uint64, error)
  • func (vm *VM) Unpin(checksum Checksum) error
• type WasmCode

Functions

func LibwasmvmVersion

func LibwasmvmVersion() (string, error)

LibwasmvmVersion returns the version of the loaded library at runtime. This can be used for debugging to verify the loaded version matches the expected version.

Types

type Checksum

type Checksum []byte

Checksum represents a hash of the Wasm bytecode that serves as an ID. Must be generated from this library.

type GasMeter

type GasMeter = api.GasMeter

GasMeter is a read-only version of the sdk gas meter

type GoAPI

type GoAPI = api.GoAPI

GoAPI is a reference to some "precompiles", go callbacks

type KVStore

type KVStore = api.KVStore

KVStore is a reference to some sub-kvstore that is valid for one instance of a code

type Querier

type Querier = types.Querier

Querier lets us make read-only queries on other modules

type VM

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

VM is the main entry point to this library. You should create an instance with its own subdirectory to manage state inside, and call it for all cosmwasm code related actions.

func NewVM

func NewVM(dataDir string, supportedFeatures string, memoryLimit uint32, printDebug bool, cacheSize uint32) (*VM, error)

NewVM creates a new VM.

`dataDir` is a base directory for Wasm blobs and various caches. `supportedFeatures` is a comma separated list of features suppored by the chain. `memoryLimit` is the memory limit of each contract execution (in MiB) `printDebug` is a flag to enable/disable printing debug logs from the contract to STDOUT. This should be false in production environments. `cacheSize` sets the size in MiB of an in-memory cache for e.g. module caching. Set to 0 to disable. `deserCost` sets the gas cost of deserializing one byte of data.

func (*VM) AnalyzeCode

func (vm *VM) AnalyzeCode(checksum Checksum) (*types.AnalysisReport, error)

Returns a report of static analysis of the wasm contract (uncompiled). This contract must have been stored in the cache previously (via Create). Only info currently returned is if it exposes all ibc entry points, but this may grow later

func (*VM) Cleanup

func (vm *VM) Cleanup()

Cleanup should be called when no longer using this to free resources on the rust-side

func (*VM) Create

func (vm *VM) Create(code WasmCode) (Checksum, error)

Create will compile the wasm code, and store the resulting pre-compile as well as the original code. Both can be referenced later via Checksum This must be done one time for given code, after which it can be instatitated many times, and each instance called many times.

For example, the code for all ERC-20 contracts should be the same. This function stores the code for that contract only once, but it can be instantiated with custom inputs in the future.

TODO: return gas cost? Add gas limit??? there is no metering here...

func (*VM) Execute

func (vm *VM) Execute(
	checksum Checksum,
	env types.Env,
	info types.MessageInfo,
	executeMsg []byte,
	store KVStore,
	goapi GoAPI,
	querier Querier,
	gasMeter GasMeter,
	gasLimit uint64,
	deserCost types.UFraction,
) (*types.Response, uint64, error)

Execute calls a given contract. Since the only difference between contracts with the same Checksum is the data in their local storage, and their address in the outside world, we need no ContractID here. (That is a detail for the external, sdk-facing, side).

The caller is responsible for passing the correct `store` (which must have been initialized exactly once), and setting the env with relevent info on this instance (address, balance, etc)

func (*VM) GetCode

func (vm *VM) GetCode(checksum Checksum) (WasmCode, error)

GetCode will load the original wasm code for the given code id. This will only succeed if that code id was previously returned from a call to Create.

This can be used so that the (short) code id (hash) is stored in the iavl tree and the larger binary blobs (wasm and pre-compiles) are all managed by the rust library

func (*VM) GetMetrics

func (vm *VM) GetMetrics() (*types.Metrics, error)

GetMetrics some internal metrics for monitoring purposes.

func (*VM) IBCChannelClose

func (vm *VM) IBCChannelClose(
	checksum Checksum,
	env types.Env,
	msg types.IBCChannelCloseMsg,
	store KVStore,
	goapi GoAPI,
	querier Querier,
	gasMeter GasMeter,
	gasLimit uint64,
	deserCost types.UFraction,
) (*types.IBCBasicResponse, uint64, error)

IBCChannelClose is available on IBC-enabled contracts and is a hook to call into at the end of the channel lifetime

func (*VM) IBCChannelConnect

func (vm *VM) IBCChannelConnect(
	checksum Checksum,
	env types.Env,
	msg types.IBCChannelConnectMsg,
	store KVStore,
	goapi GoAPI,
	querier Querier,
	gasMeter GasMeter,
	gasLimit uint64,
	deserCost types.UFraction,
) (*types.IBCBasicResponse, uint64, error)

IBCChannelConnect is available on IBC-enabled contracts and is a hook to call into during the handshake pahse

func (*VM) IBCChannelOpen

func (vm *VM) IBCChannelOpen(
	checksum Checksum,
	env types.Env,
	msg types.IBCChannelOpenMsg,
	store KVStore,
	goapi GoAPI,
	querier Querier,
	gasMeter GasMeter,
	gasLimit uint64,
	deserCost types.UFraction,
) (*types.IBC3ChannelOpenResponse, uint64, error)

IBCChannelOpen is available on IBC-enabled contracts and is a hook to call into during the handshake pahse

func (*VM) IBCPacketAck

func (vm *VM) IBCPacketAck(
	checksum Checksum,
	env types.Env,
	msg types.IBCPacketAckMsg,
	store KVStore,
	goapi GoAPI,
	querier Querier,
	gasMeter GasMeter,
	gasLimit uint64,
	deserCost types.UFraction,
) (*types.IBCBasicResponse, uint64, error)

IBCPacketAck is available on IBC-enabled contracts and is called when an the response for an outgoing packet (previously sent by this contract) is received

func (*VM) IBCPacketReceive

func (vm *VM) IBCPacketReceive(
	checksum Checksum,
	env types.Env,
	msg types.IBCPacketReceiveMsg,
	store KVStore,
	goapi GoAPI,
	querier Querier,
	gasMeter GasMeter,
	gasLimit uint64,
	deserCost types.UFraction,
) (*types.IBCReceiveResult, uint64, error)

IBCPacketReceive is available on IBC-enabled contracts and is called when an incoming packet is received on a channel belonging to this contract

func (*VM) IBCPacketTimeout

func (vm *VM) IBCPacketTimeout(
	checksum Checksum,
	env types.Env,
	msg types.IBCPacketTimeoutMsg,
	store KVStore,
	goapi GoAPI,
	querier Querier,
	gasMeter GasMeter,
	gasLimit uint64,
	deserCost types.UFraction,
) (*types.IBCBasicResponse, uint64, error)

IBCPacketTimeout is available on IBC-enabled contracts and is called when an outgoing packet (previously sent by this contract) will provably never be executed. Usually handled like ack returning an error

func (*VM) Instantiate

func (vm *VM) Instantiate(
	checksum Checksum,
	env types.Env,
	info types.MessageInfo,
	initMsg []byte,
	store KVStore,
	goapi GoAPI,
	querier Querier,
	gasMeter GasMeter,
	gasLimit uint64,
	deserCost types.UFraction,
) (*types.Response, uint64, error)

Instantiate will create a new contract based on the given Checksum. We can set the initMsg (contract "genesis") here, and it then receives an account and address and can be invoked (Execute) many times.

Storage should be set with a PrefixedKVStore that this code can safely access.

Under the hood, we may recompile the wasm, use a cached native compile, or even use a cached instance for performance.

func (*VM) Migrate

func (vm *VM) Migrate(
	checksum Checksum,
	env types.Env,
	migrateMsg []byte,
	store KVStore,
	goapi GoAPI,
	querier Querier,
	gasMeter GasMeter,
	gasLimit uint64,
	deserCost types.UFraction,
) (*types.Response, uint64, error)

Migrate will migrate an existing contract to a new code binary. This takes storage of the data from the original contract and the Checksum of the new contract that should replace it. This allows it to run a migration step if needed, or return an error if unable to migrate the given data.

MigrateMsg has some data on how to perform the migration.

func (*VM) Pin

func (vm *VM) Pin(checksum Checksum) error

Pin pins a code to an in-memory cache, such that is always loaded quickly when executed. Pin is idempotent.

func (*VM) Query

func (vm *VM) Query(
	checksum Checksum,
	env types.Env,
	queryMsg []byte,
	store KVStore,
	goapi GoAPI,
	querier Querier,
	gasMeter GasMeter,
	gasLimit uint64,
	deserCost types.UFraction,
) ([]byte, uint64, error)

Query allows a client to execute a contract-specific query. If the result is not empty, it should be valid json-encoded data to return to the client. The meaning of path and data can be determined by the code. Path is the suffix of the abci.QueryRequest.Path

func (*VM) Reply

func (vm *VM) Reply(
	checksum Checksum,
	env types.Env,
	reply types.Reply,
	store KVStore,
	goapi GoAPI,
	querier Querier,
	gasMeter GasMeter,
	gasLimit uint64,
	deserCost types.UFraction,
) (*types.Response, uint64, error)

Reply allows the native Go wasm modules to make a priviledged call to return the result of executing a SubMsg.

These work much like Sudo (same scenario) but focuses on one specific case (and one message type)

func (*VM) Sudo

func (vm *VM) Sudo(
	checksum Checksum,
	env types.Env,
	sudoMsg []byte,
	store KVStore,
	goapi GoAPI,
	querier Querier,
	gasMeter GasMeter,
	gasLimit uint64,
	deserCost types.UFraction,
) (*types.Response, uint64, error)

Sudo allows native Go modules to make priviledged (sudo) calls on the contract. The contract can expose entry points that cannot be triggered by any transaction, but only via native Go modules, and delegate the access control to the system.

These work much like Migrate (same scenario) but allows custom apps to extend the priviledged entry points without forking cosmwasm-vm.

func (*VM) Unpin

func (vm *VM) Unpin(checksum Checksum) error

Unpin removes the guarantee of a contract to be pinned (see Pin). After calling this, the code may or may not remain in memory depending on the implementor's choice. Unpin is idempotent.

type WasmCode

type WasmCode []byte

WasmCode is an alias for raw bytes of the wasm compiled code