• Stars
    star
    173
  • Rank 220,124 (Top 5 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created about 5 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Go bindings to the CosmWasm VM

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.

More Repositories

1

cosmwasm

Framework for building smart contracts in Wasm for the Cosmos SDK
Rust
1,060
star
2

cw-plus

Production Quality contracts under open source licenses
Rust
506
star
3

wasmd

Basic cosmos-sdk app with web assembly smart contracts
Go
367
star
4

cw-template

Quickstart template to get started writing your own cosmwasm contracts
Rust
283
star
5

awesome-cosmwasm

😎 Curated list of tools, contracts, and projects working with CosmWasm
242
star
6

optimizer

Dockerfile and script to deterministically produce the smallest possible Wasm for your Rust contract
Rust
123
star
7

ts-codegen

Convert your CosmWasm smart contracts into dev-friendly TypeScript classes so you can focus on shipping code.
TypeScript
116
star
8

sylvia

CosmWasm smart contract framework
Rust
93
star
9

mesh-security-hackathon

Implementation of Sunny's Mesh Security talk (Hackathon / Prototype status)
Rust
88
star
10

cw-tokens

Examples of cw20 usage, extracted from cw-plus, maintained by the community
Rust
85
star
11

dApps

A collection of sample dApps for CosmWasm contracts, using CosmJS frontend SDK
TypeScript
55
star
12

docs-deprecated

Updated documentation repo
JavaScript
52
star
13

CosmWasmJS

Source of the cosmwasm npm package
TypeScript
50
star
14

cw-multi-test

CosmWasm multi-contract testing framework
Rust
46
star
15

cw-storage-plus

Storage abstractions for CosmWasm smart contracts
Rust
35
star
16

testnets

Information on all public CosmWasm testnets
TypeScript
34
star
17

book

CosmWasm book
34
star
18

cosmwasm-go

Enabling CosmWasm smart contracts in Go using TinyGo
Go
29
star
19

token-factory

Pulling out Osmosis token factory module and the custom CosmWasm bindings into it's own repo for easier reuse
Go
24
star
20

resources

23
star
21

tinyjson

Fast JSON serializer for golang.
Go
22
star
22

code-explorer

A code explorer for CosmWasm
TypeScript
21
star
23

cw-minus

Contract helpers originally used for cw-plus contracts/specs
Rust
16
star
24

cosmwasm-verify

Verify CosmWasm build results
Shell
15
star
25

advisories

To publicly communicate advisories about serious bugs in CosmWasm, wasmvm, and wasmd
Shell
14
star
26

drand-verify

A drand verification library in Rust. This can be used by other crates or be compiled to a Wasm blob (< 500 kilobytes) with JavaScript bindings.
Rust
12
star
27

cosmwasm-simulate

Simulation tool for cosmwasm smart contract
Rust
10
star
28

cw-academy-course

CosmWasm academy smart contracts course projects
Rust
7
star
29

mesh-security-ui

Basic UI to try out mesh security
TypeScript
6
star
30

docs

MDX
6
star
31

token-bindings

Minimal Rust bindings for token factory
Rust
5
star
32

CWIPs

CosmWasm Improvement Proposals
Shell
5
star
33

storey

Experimental storage abstractions for blockchain key-value stores
Rust
5
star
34

academy-deploy

TypeScript
4
star
35

cw-cron

Basic job scheduler service implementation for CosmWasm
3
star
36

sylvia-book

3
star
37

name-app

Simple react app on top of cosmwasm, showing use of name server contract
TypeScript
3
star
38

terra-contracts

Custom bindings and sample contracts for Terra integration
Rust
2
star
39

cw-mcs-academy-course

Repository for multi contract systems academy course
Rust
2
star
40

docs-old

Documentation for cosmwasm
JavaScript
2
star
41

simple-option

Demo repo for hackatom video
Rust
2
star
42

cw-storage

CosmWasm library with useful helpers for Storage patterns
Rust
1
star
43

chat.cosmwasm.com

Redirect to our community chat
HTML
1
star
44

cw-tools

Rust
1
star
45

idl

The CosmWasm IDL docs
1
star
46

sylvia-template

Rust
1
star