cosmwasm

README

Go-CosmWasm

This provides go bindings to the CosmWasm smart contract framework. In particular, it allows you to easily compile, initialize, and execute these contracts from Go.

As of the 0.7.0 release, we support CosmWasm 0.7.0 and any compatible smart contracts.

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

Since this package includes a rust prebuilt dll, you cannot just import the go code, but need to be on a system that works with an existing dll. Currently this is Linux (tested on Ubuntu, Debian, and CentOS7) and MacOS. We have a build system for Windows, but it is not supported by the wasmer singlepass backend which we rely upon for gas metering.

Note: CentOS support is currently disabled due to work on CD tooling. We require Linux with glibc 2.18+

Note: Windows is not supported currently

Note: We only currently support i686/amd64 architectures, although AMD support is an open issue

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/libgo_cosmwasm.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.39+. Generally, you can just use rustup to install all this with no problems.

Toolchain

The Rust toolchain is pinned in the file rust-toolchain. It must be in sync with Dockerfile.cross and Dockerfile.centos7. When choosing a version, please use version with clippy, rustfmt and rls available to make Simon happy.

• Mac: https://rust-lang.github.io/rustup-components-history/x86_64-apple-darwin.html
• Linux: https://rust-lang.github.io/rustup-components-history/x86_64-unknown-linux-gnu.html

Documentation

Index

• func AppendReplyInternalDataToData(data []byte, internaReplyEnclaveSig []byte, internalMsgId []byte) ([]byte, error)
• type CodeID
• type ContractExecResponse
• type GasMeter
• type GoAPI
• type KVStore
• type Querier
• type V010ContractExecResponse
• type V010ContractInitResponse
• type V010orV1ContractInitResponse
• type V1ContractExecResponse
• type V1ContractInitResponse
• type WasmCode
• type Wasmer
  • func NewWasmer(dataDir string, supportedFeatures string, cacheSize uint64, ...) (*Wasmer, error)
  • func (w *Wasmer) AnalyzeCode(codeHash []byte) (*v1types.AnalysisReport, error)
  • func (w *Wasmer) Cleanup()
  • func (w *Wasmer) Create(code WasmCode) (CodeID, error)
  • func (w *Wasmer) Execute(code CodeID, env types.Env, executeMsg []byte, store KVStore, goapi GoAPI, ...) (interface{}, uint64, error)
  • func (w *Wasmer) GetCode(code CodeID) (WasmCode, error)
  • func (w *Wasmer) Instantiate(codeId CodeID, env types.Env, initMsg []byte, store KVStore, goapi GoAPI, ...) (interface{}, []byte, uint64, error)
  • func (w *Wasmer) Query(code CodeID, env types.Env, queryMsg []byte, store KVStore, goapi GoAPI, ...) ([]byte, uint64, error)

Functions

func AppendReplyInternalDataToData

func AppendReplyInternalDataToData(data []byte, internaReplyEnclaveSig []byte, internalMsgId []byte) ([]byte, error)

Types

type CodeID

type CodeID []byte

CodeID represents an ID for a given wasm code blob, must be generated from this library

type ContractExecResponse

type ContractExecResponse struct {
	V1                     *V1ContractExecResponse       `json:"v1,omitempty"`
	V010                   *V010ContractExecResponse     `json:"v010,omitempty"`
	InternaReplyEnclaveSig []byte                        `json:"internal_reply_enclave_sig"`
	InternalMsgId          []byte                        `json:"internal_msg_id"`
	IBCBasic               *v1types.IBCBasicResult       `json:"ibc_basic,omitempty"`
	IBCPacketReceive       *v1types.IBCReceiveResult     `json:"ibc_packet_receive,omitempty"`
	IBCChannelOpen         *v1types.IBCOpenChannelResult `json:"ibc_open_channel,omitempty"`
}

This struct helps us to distinguish between v0.10 contract response and v1 contract response

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 V010ContractExecResponse

type V010ContractExecResponse struct {
	Ok  *v010types.HandleResponse `json:"Ok,omitempty"`
	Err *types.StdError           `json:"Err,omitempty"`
}

type V010ContractInitResponse

type V010ContractInitResponse struct {
	Ok  *v010types.InitResponse `json:"Ok,omitempty"`
	Err *types.StdError         `json:"Err,omitempty"`
}

type V010orV1ContractInitResponse

type V010orV1ContractInitResponse struct {
	V1                     *V1ContractInitResponse   `json:"v1,omitempty"`
	V010                   *V010ContractInitResponse `json:"v010,omitempty"`
	InternaReplyEnclaveSig []byte                    `json:"internal_reply_enclave_sig"`
	InternalMsgId          []byte                    `json:"internal_msg_id"`
}

type V1ContractExecResponse

type V1ContractExecResponse struct {
	Ok  *v1types.Response `json:"Ok,omitempty"`
	Err *types.StdError   `json:"Err,omitempty"`
}

type V1ContractInitResponse

type V1ContractInitResponse struct {
	Ok  *v1types.Response `json:"Ok,omitempty"`
	Err *types.StdError   `json:"Err,omitempty"`
}

type WasmCode

type WasmCode []byte

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

type Wasmer

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

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

func NewWasmer

func NewWasmer(dataDir string, supportedFeatures string, cacheSize uint64, moduleCacheSize uint8) (*Wasmer, error)

NewWasmer creates an new binding, with the given dataDir where it can store raw wasm and the pre-compile cache. cacheSize sets the size of an optional in-memory LRU cache for prepared VMs. They allow popular contracts to be executed very rapidly (no loading overhead), but require ~32-64MB each in memory usage.

func (*Wasmer) AnalyzeCode

func (w *Wasmer) AnalyzeCode(
	codeHash []byte,
) (*v1types.AnalysisReport, error)

AnalyzeCode 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 (*Wasmer) Cleanup

func (w *Wasmer) Cleanup()

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

func (*Wasmer) Create

func (w *Wasmer) Create(code WasmCode) (CodeID, 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 CodeID 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 (*Wasmer) Execute

func (w *Wasmer) Execute(
	code CodeID,
	env types.Env,
	executeMsg []byte,
	store KVStore,
	goapi GoAPI,
	querier Querier,
	gasMeter GasMeter,
	gasLimit uint64,
	sigInfo types.VerificationInfo,
	handleType types.HandleType,
) (interface{}, uint64, error)

Execute calls a given contract. Since the only difference between contracts with the same CodeID 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 relevant info on this instance (address, balance, etc)

func (*Wasmer) GetCode

func (w *Wasmer) GetCode(code CodeID) (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 (*Wasmer) Instantiate

func (w *Wasmer) Instantiate(
	codeId CodeID,
	env types.Env,
	initMsg []byte,
	store KVStore,
	goapi GoAPI,
	querier Querier,
	gasMeter GasMeter,
	gasLimit uint64,
	sigInfo types.VerificationInfo,
	contractAddress sdk.AccAddress,
) (interface{}, []byte, uint64, error)

Instantiate will create a new contract based on the given codeID. 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 (*Wasmer) Query

func (w *Wasmer) Query(
	code CodeID,
	env types.Env,
	queryMsg []byte,
	store KVStore,
	goapi GoAPI,
	querier Querier,
	gasMeter GasMeter,
	gasLimit uint64,
) ([]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