Skip to content

Commit

Permalink
Merge pull request CosmWasm#1805 from CosmWasm/rewrite-compatibility
Browse files Browse the repository at this point in the history 
Rewrite compatibility section in README
  • Loading branch information
@webmaster128
webmaster128 authored Feb 15, 2024
2 parents 5f444cd + 9511185 commit 9e44af1
Show file tree
Hide file tree
Showing 2 changed files with 111 additions and 89 deletions.
16 changes: 16 additions & 0 deletions .editorconfig
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# EditorConfig is awesome: https://EditorConfig.org

# top-most EditorConfig file
root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[{Makefile,*.go}]
indent_style = tab
indent_size = 4
184 changes: 95 additions & 89 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,98 +1,97 @@

# Wasm Zone

[![CircleCI](https://circleci.com/gh/CosmWasm/wasmd/tree/main.svg?style=shield)](https://circleci.com/gh/CosmWasm/wasmd/tree/main)
[![codecov](https://codecov.io/gh/cosmwasm/wasmd/branch/main/graph/badge.svg)](https://codecov.io/gh/cosmwasm/wasmd)
[![Go Report Card](https://goreportcard.com/badge/github.com/CosmWasm/wasmd)](https://goreportcard.com/report/github.com/CosmWasm/wasmd)
[![license](https://img.shields.io/github/license/CosmWasm/wasmd.svg)](https://github.com/CosmWasm/wasmd/blob/main/LICENSE)
[![LoC](https://tokei.rs/b1/github/CosmWasm/wasmd)](https://github.com/CosmWasm/wasmd)

<!-- [![GolangCI](https://golangci.com/badges/github.com/CosmWasm/wasmd.svg)](https://golangci.com/r/github.com/CosmWasm/wasmd) -->

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

This code was forked from the `cosmos/gaia` repository as a basis and then we added `x/wasm` and cleaned up
This code was forked from the `cosmos/gaia` repository as a basis and then we added `x/wasm` and cleaned up
many gaia-specific files. However, the `wasmd` binary should function just like `gaiad` except for the
addition of the `x/wasm` module.

**Note**: Requires [Go 1.21+](https://golang.org/dl/)

For critical security issues & disclosure, see [SECURITY.md](SECURITY.md).
## Compatibility with CosmWasm contracts

## Compatibility

A VM can support one or more contract-VM interface versions. The interface
version is communicated by the contract via a Wasm export. This is the current
compatibility list:

| wasmd | wasmvm | cosmwasm-vm | cosmwasm-std |
|-------|--------------|-------------|--------------|
| 0.51 | v1.5.2 | | 1.0-1.5 |
| 0.50 | v1.5.0 | | 1.0-1.5 |
| 0.45 | v1.5.0 | | 1.0-1.5 |
| 0.44 | v1.5.0 | | 1.0-1.5 |
| 0.43 | v1.4.1 | | 1.0-1.4 |
| 0.42 | v1.4.0 | | 1.0-1.4 |
| 0.41 | v1.3.0 | | 1.0-1.3 |
| 0.40 | v1.2.3 | | 1.0-1.2 |
| 0.31 | v1.2.0 | | 1.0-1.2 |
| 0.30 | v1.1.0 | | 1.0-1.1 |
| 0.29 | v1.1.0 | | 1.0-1.1 |
| 0.28 | v1.0.0 | | 1.0-1.1 |
| 0.27 | v1.0.0 | | 1.0 |
| 0.26 | 1.0.0-beta10 | | 1.0 |
| 0.25 | 1.0.0-beta10 | | 1.0 |
| 0.24 | 1.0.0-beta7 | 1.0.0-beta6 | 1.0 |
| 0.23 | | 1.0.0-beta5 | 1.0 |
| 0.22 | | 1.0.0-beta5 | 1.0 |
| 0.21 | | 1.0.0-beta2 | 1.0 |
| 0.20 | | 1.0.0-beta | 1.0 |
| 0.19 | | 0.16 | 0.16 |
| 0.18 | | 0.16 | 0.16 |
| 0.17 | | 0.14 | 0.14 |
| 0.16 | | 0.14 | 0.14 |
| 0.15 | | 0.13 | 0.11-0.13 |
| 0.14 | | 0.13 | 0.11-0.13 |
| 0.13 | | 0.12 | 0.11-0.13 |
| 0.12 | | 0.12 | 0.11-0.13 |
| 0.11 | | 0.11 | 0.11-0.13 |
| 0.10 | | 0.10 | 0.10 |
| 0.9 | | 0.9 | 0.9 |
| 0.8 | | 0.8 | 0.8 |

Note: `cosmwasm_std v1.0` means it supports contracts compiled by any `v1.0.0-betaX` or `1.0.x`.
It will also run contracts compiled with 1.x assuming they don't opt into any newer features.
The 1.x cosmwasm_vm will support all contracts with 1.0 <= version <= 1.x.

Note that `cosmwasm-std` version defines which contracts are compatible with this system. The wasm code uploaded must
have been compiled with one of the supported `cosmwasm-std` versions, or will be rejected upon upload (with some error
message about "contract too old?" or "contract too new?"). `cosmwasm-vm` version defines the runtime used. It is a
breaking change to switch runtimes (you will need to organize a chain upgrade). As of `cosmwasm-vm 0.13` we are
using [wasmer](https://github.com/wasmerio/wasmer/) 1.0, which is significantly more performant than the older versions.
### For contract developers

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 required [capabilities](https://github.com/CosmWasm/cosmwasm/blob/main/docs/CAPABILITIES.md) through cargo features in cosmwasm-std.
The following table shows which of the [latest capabilities](https://github.com/CosmWasm/cosmwasm/blob/main/docs/CAPABILITIES-BUILT-IN.md) are supported by certain wasmd versions.

| capability | >= 0.42 | >= 0.41 | >= 0.31 | >= 0.29 | 0.28 |
| ------------ | ------- | ------- | ------- | ------- | ---- |
| iterator | x | x | x | x | x |
| stargate | x | x | x | x | x |
| staking | x | x | x | x | x |
| cosmwasm_1_1 | x | x | x | x | |
| cosmwasm_1_2 | x | x | x | | |
| cosmwasm_1_3 | x | x | | | |
| cosmwasm_1_4 | x | | | | |

### For node developers

The [wasmvm](https://github.com/CosmWasm/wasmvm) 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 a [`replace` directive](https://go.dev/ref/mod#go-mod-file-replace).

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

| wasmd | compatible | specified |
| ------ | ---------- | ----------------------------------------------------------------- |
| 0.51.0 | 1.5.x | 1.5.2 |
| 0.50.0 | 1.5.x | [1.5.0](https://github.com/CosmWasm/wasmd/blob/v0.50.0/go.mod#L6) |
| 0.45.0 | 1.5.x | [1.5.0](https://github.com/CosmWasm/wasmd/blob/v0.45.0/go.mod#L6) |
| 0.44.0 | 1.5.x | [1.5.0](https://github.com/CosmWasm/wasmd/blob/v0.44.0/go.mod#L6) |
| 0.43.0 | 1.4.x | [1.4.1](https://github.com/CosmWasm/wasmd/blob/v0.43.0/go.mod#L6) |
| 0.42.0 | 1.4.x | [1.4.1](https://github.com/CosmWasm/wasmd/blob/v0.42.0/go.mod#L6) |
| 0.41.0 | 1.3.x | [1.3.0](https://github.com/CosmWasm/wasmd/blob/v0.41.0/go.mod#L6) |

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

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

for getting the libwasmvm version loaded at runtime.

## Supported Systems

The supported systems are limited by the dlls created in [`wasmvm`](https://github.com/CosmWasm/wasmvm). 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 provide
backwards compatibility for `glibc 2.12+`. This includes all known supported distributions
using glibc (CentOS 7 uses 2.12, obsolete Debian Jessy uses 2.19).
using glibc (CentOS 7 uses 2.12, obsolete Debian Jessy uses 2.19).

As of `0.9.0` we support `muslc` Linux systems, in particular **Alpine linux**,
which is popular in docker distributions. Note that we do **not** store the
static `muslc` build in the repo, so you must compile this yourself, and pass `-tags muslc`.
Please look at the [`Dockerfile`](./Dockerfile) for an example of how we build a static Go
binary for `muslc`. (Or just use this Dockerfile for your production setup).


## Stability

**This is beta software** It is run in some production systems, but we cannot yet provide a stability guarantee
and have not yet gone through and audit of this codebase. Note that the
[CosmWasm smart contract framework](https://github.com/CosmWasm/cosmwasm) used by `wasmd` is in a 1.0 release candidate
as of March 2022, with stability guarantee and addressing audit results.

As of `wasmd` 0.22, we will work to provide upgrade paths *for this module* for projects running a non-forked
As of `wasmd` 0.22, we will work to provide upgrade paths _for this module_ for projects running a non-forked
version on their live networks. If there are Cosmos SDK upgrades, you will have to run their migration code
for their modules. If we change the internal storage of `x/wasm` we will provide a function to migrate state that
can be called by an `x/upgrade` handler.
Expand All @@ -104,13 +103,14 @@ Thank you to all projects who have run this code in your mainnets and testnets a
given feedback to improve stability.

## Encoding

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 itself
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 itself
responsible for decoding. For better UX, we often use `json.RawMessage` to contain these bytes, which enforces that it is
valid json, but also give a much more readable interface. If you want to use another encoding in the contracts, that is
a relatively minor change to wasmd but would currently require a fork. Please open an issue if this is important for
valid json, but also give a much more readable interface. If you want to use another encoding in the contracts, that is
a relatively minor change to wasmd but would currently require a fork. Please open an issue if this is important for
your use case.

## Quick Start
Expand All @@ -119,28 +119,32 @@ your use case.
make install
make test
```

if you are using a linux without X or headless linux, look at [this article](https://ahelpme.com/linux/dbusexception-could-not-get-owner-of-name-org-freedesktop-secrets-no-such-name) or [#31](https://github.com/CosmWasm/wasmd/issues/31#issuecomment-577058321).

## Protobuf

The protobuf files for this project are published automatically to the [buf repository](https://buf.build/) to make integration easier:

| wasmd version | buf tag |
|---------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| 0.31.x | [e0e5a6fa433449e695af692478c86fb5](https://buf.build/cosmwasm/wasmd/tree/e0e5a6fa433449e695af692478c86fb5:cosmwasm/wasm/v1) |
| 0.30.x | [6508ee062011440c907de6f5c40398ea](https://buf.build/cosmwasm/wasmd/tree/6508ee062011440c907de6f5c40398ea:cosmwasm/wasm/v1) |
| 0.29.x | [51931206dbe09529c1819a8a2863d291035a2549](https://buf.build/cosmwasm/wasmd/tree/51931206dbe09529c1819a8a2863d291035a2549:cosmwasm/wasm/v1) |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| 0.31.x | [e0e5a6fa433449e695af692478c86fb5](https://buf.build/cosmwasm/wasmd/tree/e0e5a6fa433449e695af692478c86fb5:cosmwasm/wasm/v1) |
| 0.30.x | [6508ee062011440c907de6f5c40398ea](https://buf.build/cosmwasm/wasmd/tree/6508ee062011440c907de6f5c40398ea:cosmwasm/wasm/v1) |
| 0.29.x | [51931206dbe09529c1819a8a2863d291035a2549](https://buf.build/cosmwasm/wasmd/tree/51931206dbe09529c1819a8a2863d291035a2549:cosmwasm/wasm/v1) |

Generate protobuf

```shell script
make proto-gen
```

The generators are executed within a Docker [container](./contrib/prototools-docker), now.

## Dockerized

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
Build: `docker build -t cosmwasm/wasmd:latest .` or pull from dockerhub

### Dev server

Expand Down Expand Up @@ -198,16 +202,16 @@ docker run --rm -it -p 26657:26657 -p 26656:26656 -p 1317:1317 \

We provide a number of variables in `app/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 change
to the configuration.
to 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 (default `wasm`)

- `-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 (default `wasm`)

Examples:

* [`wasmd`](./Makefile#L50-L55) is a generic, permissionless version using the `cosmos` bech32 prefix
- [`wasmd`](./Makefile#L50-L55) is a generic, permissionless version using the `cosmos` bech32 prefix

## Compile Time Parameters

Expand All @@ -217,16 +221,18 @@ you can adjust a few items via module parameters, but a few others did not fit i
used by stateless `ValidateBasic()`. Thus, we made them public `var` and these can be overridden in the `app.go`
file 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)
- `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)

## Genesis Configuration

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

```json
"consensus_params": {
"block": {
"max_gas": "SET_YOUR_MAX_VALUE",
"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 file
Expand All @@ -239,22 +245,22 @@ to only allow permissioned use of code upload or instantiating:
Much thanks to all who have contributed to this project, from this app, to the `cosmwasm` 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 Frey [ethanfrey](https://github.com/ethanfrey)
* Simon Warta [webmaster128](https://github.com/webmaster128)
* Alex Peters [alpe](https://github.com/alpe)
* Aaron Craelius [aaronc](https://github.com/aaronc)
* Sunny Aggarwal [sunnya97](https://github.com/sunnya97)
* Cory Levinson [clevinson](https://github.com/clevinson)
* Sahith Narahari [sahith-narahari](https://github.com/sahith-narahari)
* Jehan Tremback [jtremback](https://github.com/jtremback)
* Shane Vitarana [shanev](https://github.com/shanev)
* Billy Rennekamp [okwme](https://github.com/okwme)
* Westaking [westaking](https://github.com/westaking)
* Marko [marbar3778](https://github.com/marbar3778)
* JayB [kogisin](https://github.com/kogisin)
* Rick Dudley [AFDudley](https://github.com/AFDudley)
* KamiD [KamiD](https://github.com/KamiD)
* Valery Litvin [litvintech](https://github.com/litvintech)
* Leonardo Bragagnolo [bragaz](https://github.com/bragaz)
- Ethan Frey [ethanfrey](https://github.com/ethanfrey)
- Simon Warta [webmaster128](https://github.com/webmaster128)
- Alex Peters [alpe](https://github.com/alpe)
- Aaron Craelius [aaronc](https://github.com/aaronc)
- Sunny Aggarwal [sunnya97](https://github.com/sunnya97)
- Cory Levinson [clevinson](https://github.com/clevinson)
- Sahith Narahari [sahith-narahari](https://github.com/sahith-narahari)
- Jehan Tremback [jtremback](https://github.com/jtremback)
- Shane Vitarana [shanev](https://github.com/shanev)
- Billy Rennekamp [okwme](https://github.com/okwme)
- Westaking [westaking](https://github.com/westaking)
- Marko [marbar3778](https://github.com/marbar3778)
- JayB [kogisin](https://github.com/kogisin)
- Rick Dudley [AFDudley](https://github.com/AFDudley)
- KamiD [KamiD](https://github.com/KamiD)
- Valery Litvin [litvintech](https://github.com/litvintech)
- Leonardo Bragagnolo [bragaz](https://github.com/bragaz)

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

0 comments on commit 9e44af1

Please sign in to comment.