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 library (shared .dll/.dylib/.so or static .a) 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.

Rust code

The Rust code lives in a sub-folder ./libwasmvm. This folder compiles to a library that can be used via FFI. It is compiled like this:

# Run unit tests
(cd libwasmvm && cargo test)

# Create release build for your current system. Uses whatever default Rust
# version you have installed.
make build-rust

# Create reproducible release builds for other systems (slow, don't use for development)
make release-build-alpine
make release-build-linux
make release-build-macos
make release-build-windows

Go code

The Go code consistes of three packages:

1. The types (the github.com/CosmWasm/wasmvm/types import), using package types
2. The internal package internal/api, using package api
3. This repo (the github.com/CosmWasm/wasmvm import), using package cosmwasm

The dependencies between them are as follows:

graph TD;
    api-->types;
    cosmwasm-->types;
    cosmwasm-->api;

The Go code is built like this:

make build-go
make test

Package github.com/CosmWasm/wasmvm/types

This packages contains types used by the two other packages. It can be compiled without cgo.

# Build
go build ./types
# Build without CGO
CGO_ENABLED=0 go build ./types

Package internal/api

This package contains the code binding the libwasmvm build to the Go code. All low level FFI handling code belongs there. This package can only be built using cgo. Uing the internal/ convention makes this package fully private.

Package github.com/CosmWasm/wasmvm

This is the package users import. It can be compiled without cgo, but when you do so, a lot of functionality is removed.

# Build
go build .
# Build without CGO
CGO_ENABLED=0 go build .

Supported Platforms

See COMPILER_VERSIONS.md for information on Go and Rust compiler support.

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	Shared library linking not working on Windows (#389)
Windows (mingw)	x86_64	static	🚫​	Unclear if this can work using a cross compiler; needs research on .lib (MSVC toolchain) vs. .a (GNU toolchain). (#389)
Windows (mingw)	aarch64	shared	🚫​	Shared library linking not working on Windows (#389)
Windows (mingw)	aarch64	static	🚫​	Unclear if this can work using a cross compiler; needs research on .lib (MSVC toolchain) vs. .a (GNU toolchain). (#389)

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.

Documentation

Index

• func LibwasmvmVersion() (string, error)
• type Checksum
• type GasMeter
• type GoAPI
• type KVStore
• type Querier
• type VM
  • func NewVM(dataDir string, supportedCapabilities string, memoryLimit uint32, ...) (*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) RemoveCode(checksum Checksum) error
  • func (vm *VM) Reply(checksum Checksum, env types.Env, reply types.Reply, store KVStore, ...) (*types.Response, uint64, error)
  • func (vm *VM) StoreCode(code WasmCode) (Checksum, 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.

When cgo is disabled at build time, this returns an error at runtime.

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 = types.GasMeter

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

type GoAPI

type GoAPI = types.GoAPI

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

type KVStore

type KVStore = types.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
}

func NewVM

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

`dataDir` is a base directory for Wasm blobs and various caches. `supportedCapabilities` is a comma separated list of capabilities 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)

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)

Deprecated: Renamed to StoreCode

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)

func (*VM) GetCode

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

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)

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)

func (*VM) Pin

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

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)

func (*VM) RemoveCode

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

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

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

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)

func (*VM) Unpin

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

type WasmCode

type WasmCode []byte

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