# CosmWasm

Discover how multi-chain smart contracts become possible with CosmWasm. The following sections are recommended as a preparation:

CosmWasm (opens new window) offers multi-chain solutions for smart contracts through an actor-model design focused on providing a library.

The actor model is a design pattern for reliable, distributed systems. It is the pattern underlying CosmWasm smart contracts.

Each actor has access to its own internal state and can only message other actors through a so-called dispatcher, which maintains the state and maps addresses to code and storage.

Want to read more on the actor model? See the CosmWasm documentation on the Actor Model for Contract Calls (opens new window).

CosmWasm's design makes the code agnostic to the details of underlying chains. It only requires a Cosmos SDK application to embed the Wasm module.

CosmWasm is adaptable to different development environments by design and makes it possible to connect chains. It is a solid platform to develop on because:

  • If you want to change chains, you can easily transfer smart contracts and decentralized applications (dApps).
  • If your application grows, you can launch your chain for the next version of your smart contract. You do not need to compile and deploy the binaries again.

# Install

Go must be installed to use the Cosmos SDK. You also need Rust to write smart contracts.

Go to rustup.rs (opens new window) to install Rust, or update your version with rustup update. Then, have it download and install the wasm32 compilation target:

Copy $ rustup target list --installed # if wasm32 is not listed above, run this $ rustup target add wasm32-unknown-unknown

wasmd is the easiest way to begin. It is forked from gaiad (the Gaia Daemon) (opens new window), which is a binary build with the Cosmos Hub, and includes the Wasm (opens new window) module.

Create a folder and clone the wasmd (opens new window) repository into it:

Copy $ git clone https://github.com/CosmWasm/wasmd.git $ cd wasmd $ git checkout v0.18.0 $ make install

Verify your installation:

Copy $ wasmd version

This returns:

Copy 0.18.0

If you cannot call wasmd, make sure your $GOPATH and $PATH are set correctly.

# Connect to a testnet

First test the wasmd client with the Pebblenet (opens new window) testnet. wasmd is configured via environment variables. Export the most recent environment from here (opens new window):

Copy $ curl https://raw.githubusercontent.com/CosmWasm/testnets/master/pebblenet-1/defaults.env -o pebblenet-1-defaults.env $ source pebblenet-1-defaults.env

Confirm you got it correctly:

Copy $ echo $CHAIN_ID

This returns:

Copy pebblenet-1

If you open another terminal window, do not forget to repeat this source command, as this is local to the session.

# Your accounts

Now add some keys:

Copy $ wasmd keys add wallet $ wasmd keys add wallet2

What was created?

Copy $ wasmd keys show wallet --address

This returns:

Copy wasm1jj7gzazxvgy56rj8kersuc44ehvep0uey85jdn

That is your address. Query your token balance:

Copy $ wasmd query bank balances $(wasmd keys show wallet --address) --node $RPC

This returns:

Copy pagination: {}

You have none. Time to ask the faucet (opens new window) to remedy this. To facilitate command-line actions, install jq (opens new window), which is a lightweight and flexible command-line JSON processor. Then prepare the request for your wallet:

Copy $ JSON=$(jq --null-input --arg addr $(wasmd keys show wallet --address) '{"denom":"upebble","address":$addr}') $ echo "$JSON"

This returns:

Copy { "denom": "upebble", "address": "wasm1jj7gzazxvgy56rj8kersuc44ehvep0uey85jdn" }

upebble is the denomination of the testnet token. With the content of the request ready, call the faucet:

Copy $ curl -X POST --header "Content-Type: application/json" --data "$JSON" https://faucet.pebblenet.cosmwasm.com/credit

This returns:

Copy ok

Query your balance again:

Copy $ wasmd query bank balances $(wasmd keys show wallet --address) --node $RPC

This returns:

Copy balances: - amount: "100000" denom: upebble pagination: {}

Repeat this process for wallet2.

# Compile a smart contract

Now that you have enough tokens to deploy a smart contract on Pebblenet, clone the contract samples away from your wasmd folder:

Copy $ git clone https://github.com/InterWasm/cw-contracts $ cd cw-contracts/contracts/nameservice $ cargo wasm

This returns:

Copy ... Compiling cw-nameservice v0.11.0 (/Users/me/cw-contracts/contracts/nameservice) Finished release [optimized] target(s) in 1m 20s

In this last command, wasm is an alias (opens new window) for wasm build --release --target wasm32-unknown-unknown.

You now have a compiled smart contract on file. You want to maintain your smart contract binary as small as possible, and have Rust compiled with default settings. Check the size of your build with:

Copy $ ls -lh target/wasm32-unknown-unknown/release/cw_nameservice.wasm

This returns:

Copy -rwxr-xr-x 2 me staff 1.7M target/wasm32-unknown-unknown/release/cw_nameservice.wasm

You can optimize the code with a Docker (opens new window) container based on an image provided by CosmWasm (opens new window) for production purposes:

Copy $ docker run --rm -v "$(pwd)":/code \ --mount type=volume,source="$(basename "$(pwd)")_cache",target=/code/target \ --mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \ cosmwasm/rust-optimizer:0.12.3

Compare the result:

Copy $ ls -alh artifacts/cw_nameservice.wasm

This returns:

Copy -rw-r--r-- 1 me staff 139K artifacts/cw_nameservice.wasm

# Upload a smart contract binary

Time to store the smart contract binaries on the blockchain:

Copy $ RES=$(wasmd tx wasm store artifacts/cw_nameservice.wasm --from wallet --node $RPC --chain-id pebblenet-1 --gas-prices 0.001upebble --gas auto --gas-adjustment 1.3) $ CODE_ID=$(echo $RES | jq -r '.logs[0].events[-1].attributes[0].value')

The response returns a code_id value, which uniquely identifies your newly uploaded binary in the blockchain. Record this in order to instantiate a name service with this binary in the next steps.

# Instantiate your smart contract

You have uploaded some code, but do not yet have any smart contract instance. Now to instantiate a new smart contract that uses this code. Look at the aptly-named instantiate function in the name server contract:

Copy #[cfg_attr(not(feature = "library"), entry_point)] pub fn instantiate( deps: DepsMut, _env: Env, _info: MessageInfo, msg: InstantiateMsg, ) -> Result<Response, StdError> { let config_state = Config { purchase_price: msg.purchase_price, transfer_price: msg.transfer_price, }; config(deps.storage).save(&config_state)?; Ok(Response::default()) } contracts nameservice src contract.rs View source

Among the parameters the function expects are msg.purchase_price and msg.transfer_price (opens new window). Both have the type cosmwasm_std::Coin (opens new window), which looks very similar to Cosmos SDK's Coin (opens new window). This is no coincidence. With this knowledge, instantiate a new name service with a purchase_price and transfer_price:

Copy $ wasmd tx wasm instantiate $CODE_ID '{"purchase_price":{"amount":"100","denom":"upebble"},"transfer_price":{"amount":"999","denom":"upebble"}}' --from wallet --node $RPC --chain-id pebblenet-1 --gas-prices 0.001upebble --gas auto --gas-adjustment 1.3 --label "CosmWasm tutorial name service"

Note the CODE_ID that refers to which binary to use for the instantiation. Check that the name service instance was successfully created with:

Copy $ wasmd query wasm list-contract-by-code $CODE_ID --node $RPC --output json

You can find the contract address in the response. Make it a variable too:

Copy $ CONTRACT = the_address_in_the_response

Use this to fetch more information with the following command:

Copy $ wasmd query wasm contract $CONTRACT --node $RPC

# Call your smart contract

With your instance now running, you can call other functions on it.

# Register a name

Looking into the contract code, you can find the execute function:

Copy #[cfg_attr(not(feature = "library"), entry_point)] pub fn execute( deps: DepsMut, env: Env, info: MessageInfo, msg: ExecuteMsg, ) -> Result<Response, ContractError> { match msg { ExecuteMsg::Register { name } => execute_register(deps, env, info, name), ExecuteMsg::Transfer { name, to } => execute_transfer(deps, env, info, name, to), } } contracts nameservice src contract.rs View source

There are two execute message types. These are used to register or transfer a name within the name service. Start by registering (opens new window) a new name with your instance:

Copy $ wasmd tx wasm execute $CONTRACT '{"register":{"name":"fred"}}' --amount 100upebble --from wallet --node $RPC --chain-id pebblenet-1 --gas-prices 0.001upebble --gas auto --gas-adjustment 1.3

# Verify the name registration

With the transaction posted, it is time to verify that the name was registered. In the contract you can find the query function:

Copy #[cfg_attr(not(feature = "library"), entry_point)] pub fn query(deps: Deps, env: Env, msg: QueryMsg) -> StdResult<Binary> { match msg { QueryMsg::ResolveRecord { name } => query_resolver(deps, env, name), QueryMsg::Config {} => to_binary(&config_read(deps.storage).load()?), } } contracts nameservice src contract.rs View source

There are two query message types. Note that you now have deps: Deps instead of deps: DepsMut. This indicates that the execution of the function does not mutate the state. This is what to use with functions that implement a query type of service.

Verify the registration with ResolveRecord (opens new window):

Copy $ wasmd query wasm contract-state smart $CONTRACT '{"resolve_record": {"name": "fred"}}' --node $RPC --output json

The response gives you the wallet address owning the registered name, which should be wallet.

# Transfer a name

Now create another transaction to transfer the name to the second wallet wallet2. First prepare the query with the address of your other wallet:

Copy $ JSON=$(jq --null-input --arg addr $(wasmd keys show wallet2 --address) '{"transfer":{"name":"fred","to":$addr}}')

Then send the transaction:

Copy $ wasmd tx wasm execute $CONTRACT "$JSON" --amount 999upebble --from wallet --node $RPC --chain-id pebblenet-1 --gas-prices 0.001upebble --gas auto --gas-adjustment 1.3

Under the hood, the execution used transfer_price, which you set at the instantiation.

Check again with a resolve_record query to confirm that the transfer was successful. Experiment with another transfer from wallet2 to wallet, and pay attention to which wallet can perform which transaction.

CosmWasm offers good documentation (opens new window). This section is a summary of the Getting Started section (opens new window). Store the env script from here (opens new window) in case you wish to test it on your local node. Also look at the contract semantics (opens new window).

You can find more information in the CosmWasm Developer Academy (opens new window) and modular tutorials in the Wasm tutorials (opens new window). You can also find various hands-on videos on the workshops (opens new window) page.

# Next up

At this point, you have:

Head to the next chapter to discover the Inter-Blockchain Communication Protocol.