Introduction to CosmWasm for 2023 Hackathon.
In this repo you will find the content to match the CosmWasm 101 presentation for the Injective Global Hackathon 2023.
The introduction is split into 7 sections, numbered from 0-6, in order to navigate to a specific section checkout the git tags.
- Unix
- Terminal
- Git 2.37.1 or above
First clone the repo:
$ git clone https://github.com/InjectiveLabs/cosmwasm101.git
$ cd cosmwasm101
$ git checkout section-0
Here you find an empty repo, with nothing but this README.md
to see. If you got this far you probably have got the relevant pre-requisites installed.
Navigate to sections 1 in order to find the instructions to get the environment setup:
$ git checkout section-1
Now setup the development environment. You will need to install:
- Rust
- CosmWasm
- Cargo Generate
- PlantUML
First download rust:
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
$ rustup default stable
Check rust has successfully been installed:
$ cargo version
$ cargo 1.67.1 (8ecd4f20a 2023-01-10)
Note: If version is lower than 1.55 we need to update run command $ rustup update stable
Next add the CosmWasm targets:
$ rustup target add wasm32-unknown-unknown
Finally install cargo generate
this will help us quickly launch a new CosmWasm project.
$ cargo install cargo-generate --features vendored-openssl
$ cargo install cargo-run-script
You may wish you install helpful plugins for your IDE:
Once rust, CosmWasm and cargo generate have successfully been installed it is possible to create a contract skeleton.
In the terminal
$ cargo generate --git https://github.com/CosmWasm/cw-template.git --name CosmWasm -d minimal=true
Now you should have a directory similar to the following:
.
├── README.md
└── cosmwasm
├── Cargo.toml
├── LICENSE
├── NOTICE
└── src
Now let's use PlantUML to make some component and sequence diagrams. After following installation of PlantUML create a new directory and files as below:
$ mkdir diagrams
$ touch diagrams/component-diagram.puml && touch diagrams/instantiate-sequence.puml && touch diagrams/escrow-sequence.puml && touch diagrams/query-sequence.puml
Following the template shown in Plantuml documentation create a component diagram and sequence diagrams for the following scenario:
- instantiation
- escrow and redemption
- queries
Having created diagrams describing the basic functionality of the Escrow contract implement the following:
- Instantiate
- Execute
- Escrow
- Redemption
- Query
- Config
- Escrow State
First define the storage of the contract which should be config and then a storage containing information about a user's specific storage. To do this use Rust crate CosmWasm Storage Plus.
The config should store:
- CW20 token address
- Contract owner address
The escrow state should store:
- User address
- Amount escrowed
- Time of escrow
Once the storage has been correctly implemented and additional query functions we are able to start to develop unit tests. Unit tests are of course the first step towards building good software.
Create a file unit_tests.rs
and using the cosmwasm-std testing module we can build a unit test for the contract instantiation and query functions created in the previous section. In addition we will import the instantiate
and query
from the escrow contract itself.
Place this skeleton in unit_tests.rs
:
use crate::contract::{execute, instantiate, query};
use cosmwasm_std::testing::{mock_dependencies, mock_env, mock_info};
#[test]
fn test_instantiation() {
// FILL THIS IN
}
Having successfully created some unit tests we wish to start developing the execute functions for escrow and redemption. However, as they involve a CW20 token it will not be possible to create these tests as unit tests. Rather we will need to create a mock blockchain environment and create integration tests.
To do this we will leverage the cw-multi-test package.
In order to complete this section we will:
- Add
cw-multi-test
as a dev dependency in ourCargo.toml
- Create the functions:
- Escrow: should allow a user to send CW20 token to the escrow contract which receives and locks the tokens a period of time
- Redeem: should allow a user to redeem their locked tokens once the period has expired
- Use
cw-multi-test
to create integration tests