Repository files navigation

This repository hostsWasmd, the first implementation of a cosmos zone with wasm smart contracts enabled.

This code was forked from thecosmos/gaia repository as a basis and then we addedx/wasm and cleaned upmany gaia-specific files. However, thewasmd binary should function just likegaiad except for theaddition of thex/wasm module.

Note: RequiresGo 1.21+

For critical security issues & disclosure, seeSECURITY.md.

Since CosmWasm 1.0 the contract-host interface has not changed in a breaking way.Also CosmWasm 2.0 contracts remain compatible at the Wasm interface level.

To extend the feature set over time, contracts can specify requiredcapabilities through cargo features in cosmwasm-std.The following table shows which of thelatest capabilities are supported by certain wasmd versions.

Thewasmvm dependency works in most aspects like any other Go dependency. When embedding wasmd as a module into your chain, wasmvm becomes a transitive (or "indirect") dependency of the final binary project. You can specify which wasmvm version you want in your node by adding it explicitly to go.mod or using areplace directive.

Please note that all minor version bumps of wasmvm are expected to be consensus breaking.For patch releases this should not be the case but there are many exceptions and corner cases.

The following table shows

• Specified wasmvm version: the wasmvm dependency that wasmd specifies in its own go.mod
• Compatible wasmvm version: the versions you can use by setting it in your project's go.mod

Dependency resolution in Go is not obvious. In case of doubt, please usego list -m github.com/CosmWasm/wasmvm to get the dynamically calculated version of the wasmvm dependency. Also check

# Replace <node> with you binary name<node> query wasm libwasmvm-version

for getting the libwasmvm version loaded at runtime.

The supported systems are limited by the dlls created inwasmvm. In particular,we only support MacOS and Linux.However,M1 macs are not fully supported. (Experimental support was merged with wasmd 0.24)For linux, the default is to build for glibc, and we cross-compile with CentOS 7 to providebackwards compatibility forglibc 2.12+. This includes all known supported distributionsusing glibc (CentOS 7 uses 2.12, obsolete Debian Jessy uses 2.19).

As of0.9.0 we supportmuslc Linux systems, in particularAlpine linux,which is popular in docker distributions. Note that we donot store thestaticmuslc build in the repo, so you must compile this yourself, and pass-tags muslc.Please look at theDockerfile for an example of how we build a static Gobinary formuslc. (Or just use this Dockerfile for your production setup).

This is beta software It is run in some production systems, but we cannot yet provide a stability guaranteeand have not yet gone through and audit of this codebase. Note that theCosmWasm smart contract framework used bywasmd is in a 1.0 release candidateas of March 2022, with stability guarantee and addressing audit results.

As ofwasmd 0.22, we will work to provide upgrade pathsfor this module for projects running a non-forkedversion on their live networks. If there are Cosmos SDK upgrades, you will have to run their migration codefor their modules. If we change the internal storage ofx/wasm we will provide a function to migrate state thatcan be called by anx/upgrade handler.

The APIs are pretty stable, but we cannot guarantee their stability until we reach v1.0.However, we will provide a way for you to hard-fork your way to v1.0.

Thank you to all projects who have run this code in your mainnets and testnets andgiven feedback to improve stability.

The used cosmos-sdk version is in transition migrating from amino encoding to protobuf for state. So are we now.

We use standard cosmos-sdk encoding (amino) for all sdk Messages. However, the message body sent to all contracts,as well as the internal state is encoded using JSON. Cosmwasm allows arbitrary bytes with the contract itselfresponsible for decoding. For better UX, we often usejson.RawMessage to contain these bytes, which enforces that it isvalid json, but also give a much more readable interface. If you want to use another encoding in the contracts, that isa relatively minor change to wasmd but would currently require a fork. Please open an issue if this is important foryour use case.

make installmake test

if you are using a linux without X or headless linux, look atthis article or#31.

The protobuf files for this project are published automatically to thebuf repository to make integration easier:

Generate protobuf

make proto-gen

The generators are executed within a Dockercontainer, now.

We provide a docker image to help with test setups. There are two modes to use it

Build:docker build -t cosmwasm/wasmd:latest . or pull from dockerhub

Bring up a local node with a test account containing tokens

This is just designed for local testing/CI - do not use these scripts in production.Very likely you will assign tokens to accounts whose mnemonics are public on github.

docker volume rm -f wasmd_data# pass password (one time) as env variable for setup, so we don't need to keep typing it# add some addresses that you have private keys for (locally) to give them genesis fundsdocker run --rm -it \    -e PASSWORD=xxxxxxxxx \    --mount type=volume,source=wasmd_data,target=/root \    cosmwasm/wasmd:latest /opt/setup_wasmd.sh cosmos1pkptre7fdkl6gfrzlesjjvhxhlc3r4gmmk8rs6# This will start both wasmd and rest-server, both are loggeddocker run --rm -it -p 26657:26657 -p 26656:26656 -p 1317:1317 \    --mount type=volume,source=wasmd_data,target=/root \    cosmwasm/wasmd:latest /opt/run_wasmd.sh

For CI, we want to generate a template one time and save to disk/repo. Then we can start a chain copying the initial state, but not modifying it. This lets us get the same, fresh start every time.

# Init chain and pass addresses so they are non-empty accountsrm -rf ./template&& mkdir ./templatedocker run --rm -it \    -e PASSWORD=xxxxxxxxx \    --mount type=bind,source=$(pwd)/template,target=/root \    cosmwasm/wasmd:latest /opt/setup_wasmd.sh cosmos1pkptre7fdkl6gfrzlesjjvhxhlc3r4gmmk8rs6sudo chown -R$(id -u):$(id -g) ./template# FIRST TIME# bind to non-/root and pass an argument to run.sh to copy the template into /root# we need wasmd_data volume mount not just for restart, but also to view logsdocker volume rm -f wasmd_datadocker run --rm -it -p 26657:26657 -p 26656:26656 -p 9090:9090 \    --mount type=bind,source=$(pwd)/template,target=/template \    --mount type=volume,source=wasmd_data,target=/root \    cosmwasm/wasmd:latest /opt/run_wasmd.sh /template# RESTART CHAIN with existing statedocker run --rm -it -p 26657:26657 -p 26656:26656 -p 1317:1317 \    --mount type=volume,source=wasmd_data,target=/root \    cosmwasm/wasmd:latest /opt/run_wasmd.sh

We provide a number of variables inapp/app.go that are intended to be set via-ldflags -X ...compile-time flags. This enables us to avoid copying a new binary directory over for each small changeto the configuration.

Available flags:

• -X github.com/CosmWasm/wasmd/app.NodeDir=.corald - set the config/data directory for the node (default~/.wasmd)
• -X github.com/CosmWasm/wasmd/app.Bech32Prefix=coral - set the bech32 prefix for all accounts (defaultwasm)

Examples:

• wasmd is a generic, permissionless version using thecosmos bech32 prefix

Besides those above variables (meant for custom wasmd compilation), there are a few more variables whichwe allow blockchains to customize, but at compile time. If you build your own chain and importx/wasm,you can adjust a few items via module parameters, but a few others did not fit in that, as they need to beused by statelessValidateBasic(). Thus, we made them publicvar and these can be overridden in theapp.gofile of your custom chain.

• wasmtypes.MaxLabelSize = 64 to set the maximum label size on instantiation (default 128)
• wasmtypes.MaxWasmSize=777000 to set the max size of compiled wasm to be accepted (default 819200)
• wasmtypes.MaxProposalWasmSize=888000 to set the max size of gov proposal compiled wasm to be accepted (default 3145728)

We strongly suggestto limit the max block gas in the genesis and not use the default value (-1 for infinite).

"consensus_params": {"block": {"max_gas":"SET_YOUR_MAX_VALUE",

Tip: if you want to lock this down to a permisisoned network, the following script can edit the genesis fileto only allow permissioned use of code upload or instantiating:

sed -i 's/permission": "Everybody"/permission": "Nobody"/' .../config/genesis.json

Much thanks to all who have contributed to this project, from this app, to thecosmwasm framework, to example contracts and documentation.Or even testing the app and bringing up critical issues. The following have helped bring this project to life:

• Ethan Freyethanfrey
• Simon Wartawebmaster128
• Alex Petersalpe
• Aaron Craeliusaaronc
• Sunny Aggarwalsunnya97
• Cory Levinsonclevinson
• Sahith Naraharisahith-narahari
• Jehan Trembackjtremback
• Shane Vitaranashanev
• Billy Rennekampokwme
• Westakingwestaking
• Markomarbar3778
• JayBkogisin
• Rick DudleyAFDudley
• KamiDKamiD
• Valery Litvinlitvintech
• Leonardo Bragagnolobragaz

Sorry if I forgot you from this list, just contact me or add yourself in a PR :)