Published in


Don’t trust. CosmWasm Verify.

If we have confidence that smart contracts do what they promise, we can achieve amazing things. But how do we establish that confidence?

Photo by Austin Schmid on Unsplash

When uploading smart contract code to a blockchain, it is stored forever in the transaction history and usually in the blockchain’s current state as well. This gives us nice properties like immutability and replication but comes at a relatively high infrastructure cost.

For this reason we want the code to be as small as possible and upload code in a compact binary representation rather than as source code. In CosmWasm, smart contracts are represented as WebAssembly bytecode that can be optimized down to something like 100 kilobytes for the examples we built.

Once we compiled the code it is almost impossible for humans to reason about its behaviour. For this reason we developed a standardized way to link off-chain source code with on-chain bytecode: CosmWasm Verify.

CosmWasm Verify is a set of shell scripts to answer the question: is this bytecode really compiled from that source? Once you have certainty that this link is correct, you can audit the source code to get clarity on the code’s behaviour. It achieves that by taking the inputs

  1. source code
  2. builder (tooling to compile source code)
  3. expected checksum

and performing a reproducible build with the builder on the source code. Then it checks if the build result matches the expected checksum and returns either valid or invalid.

The ingredients

The three input values source, builder and expected checksum are all stored on-chain alongside of the code. Let’s have a look what they are.


The source code is represented as an URL to an optionally compressed .tar file. This especially covers the popular .tar.gz/.tgz archive format used by code registries like or

For our contracts written in Rust we use for publishing source code, which allows us to download packages via the URL:{crate_name}/{crate_version}/download.

“But isn’t that insecure?” — I’m glad you’re asking. With version pinning in registries we get somewhat stable source code downloads, but in general the content behind an URL is mutable. This is not a problem since the worst that can happen is failing contract verifications. And it is in the smart contract author’s best interest to choose a reliable storage location that keeps the contract verifyable. We are looking forward to work together with contract authors on exploring decentralized file storage options in the future.


The builder represents the toolchain for compiling and optimizing code in a reproducible manner. For this we use Docker images, which can be represented as a short string like e.g. confio/cosmwasm-opt:0.7.0.

Builders will exist for all supported programming languages and CosmWasm Verify prepares for a world with many competing builders optimized for specific goals like output size, gas cost or compilation speed. In order to support this variety, a few conventions are established that keeps the builder swappable, like:

  • Builder is a docker image available on Docker Hub
  • Source code is mounted into the folder /code
  • Builder produces a file called contract.wasm on the host in the current working directory

Expected checksum

Checksums are hex encoded SHA-256 hashes of the Wasm bytecode. This gives you a short and secure identifier for the code running on-chain. CosmWasm Verify compares the hash of the build result with this expected checksum.

Getting started

To install and use ComsmWasm Verify in your current session, run

git clone
export PATH="$PWD/cosmwasm-verify/bin:$PATH"
cosmwasm-verify --help

The verification command can be composed from on-chain data and a CosmWasm code explorer displays them.

Code explorer shows verification command

Copy/pasting the verification command starts the verification process

cosmwasm-verify \
https\:// \
confio/cosmwasm-opt\:0.7.0 \
CosmWasm Verify started a reproducible build for verification

If everything works well, CosmWasm Verify gives you a high five and returns the success code 0. Well done!

What’s next?

Now that you can verify the link between a source code and an on-chain bytecode, wouldn’t it be cool if you could share the result of that verification with other potential users of the contract? This would develop a collective confidence that the link is valid and preserve this confidence even if the verfication tooling cannot be run anymore for some reason. And once the link is established, shouldn’t the general public have the opportunity to collectively review and discuss the source code? The team behind CosmWasm is currently exploring this and similar options. If you are interested, reach out to us in the CosmWasm group on Telegram or send an email to



The premier smart contract platform for the Cosmos SDK ecosystem. Easy integration to your chains. Live on 3 mainnets and more coming soon!

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Simon Warta

Simon Warta

Building CosmWasm and CosmJS at Confio | Ex IOV | Co-Founder of Kullo | Board member prolina Foundation