CosmWasm

synopsis

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

• Transactions
• Messages
• Queries

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? Check out 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

You need to have installed Go 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 get started. 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 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 right:

Copy $ echo $CHAIN_ID pebblenet-1

And if you happen to open another terminal window, don't 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

Let's see what was created:

Copy $ wasmd keys show wallet --address wasm1jj7gzazxvgy56rj8kersuc44ehvep0uey85jdn

That's your address, query your token balance:

Copy wasmd query bank balances $(wasmd keys show wallet --address) --node $RPC pagination: {}

None. Time to ask the faucet (opens new window) to remedy that sorry state. 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" { "denom": "upebble", "address": "wasm1jj7gzazxvgy56rj8kersuc44ehvep0uey85jdn" }

upebble is the denomination of the test net token. With the content of the request ready, you can call the faucet:

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

Query your balance again:

Copy $ wasmd query bank balances $(wasmd keys show wallet --address) --node $RPC balances: - amount: "100000" denom: upebble pagination: {}

Repeat the same 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 ... 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 Rust compiled with default settings. Check the size of your build with:

Copy $ ls -lh target/wasm32-unknown-unknown/release/cw_nameservice.wasm -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 -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. Keep it at hand in order to instantiate a name service with this binary in the next steps.

Instantiate your smart contract

You only uploaded some code but do not yet have any smart contract instance. You can now 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, you will note, looks very similar to Cosmos SDK's Coin (opens new window). Of course 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"

You see again 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 it 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 back 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. It is 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 indeed what you want to use with your 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 at 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]https://docs.cosmwasm.com/docs/1.0/getting-started/setting-env#setup-go-cli) in case you wish to test on your local node. Also have a 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:

• Understood how Cosmos and the Cosmos SDK fit in the overall development of blockchain technology.
• A better sense of what comprises the Cosmos ecosystem.
• Set up a wallet, got some ATOM tokens, and staked them.
• Learned more about the elements of application architecture.
• Understood and applied main concepts of the Cosmos SDK.
• Ran a node, API, and CLI for a Cosmos chain.
• Used Starport to develop your chain.
• Explored CosmJS and the code generated by Starport.
• Discovered how CosmWasm assists with developing multi-chain smart contracts in Rust.

You might wonder: what's next? There are vast opportunities to continue your journey with Cosmos to:

• Reach out to the community.
• Contribute to the Cosmos SDK, IBC, and Tendermint BFT consensus development.
• Get support for enterprise solutions, which you are developing.

Head to the What's Next section to find useful information to launch your journey into the Cosmos universe.