src/lib.rs(opens new window) file contains wasm bindings. Wraps smart contract (handle, init, query) functions around rust functions. If you are not doing advanced wasm tweaking, don't touch it.
We will begin with InitMsg(opens new window). This struct has the initial values that initializes smart contract from the code and feeds in the data required for logic setup.
Copy
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]pubstructInitMsg{// owner and creator come from env// collateral comes from envpub counter_offer:Vec<Coin>,pub expires:u64,}
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)] implements specified traits for this structure using macros. More read Rust docs / Derive(opens new window)
Owner, creator and collateral comes from message transaction context, meaning owner and creator is the address signed the tx and collateral is funds sent along the message.
Contract execution is branched using HandleMsg enum. Each field defines a message and content of that message.
Copy
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]#[serde(rename_all = "snake_case")]pubenumHandleMsg{/// Owner can transfer to a new ownerTransfer{ recipient:HumanAddr},/// Owner can post counter_offer on unexpired option to execute and get the collateralExecute{},/// Burn will release collateral if expiredBurn{},}
Canonical and Human Addresses
Canonical Addresses represent binary format of crypto addresses.
Human Addresses on the other hand are great for the UI. They are always a subset of ascii text, and often contain security checks - such as chain-prefix in Bech32, e.g. cosmos1h57760w793q6vh06jsppnqdkc4ejcuyrrjxnke
State(opens new window) handles state of the database where smart contract data is stored and accessed.
You have two options when modeling state:
Singleton: contract saves only one instance of the structure using unique db key. We will use this in this tutorial.
Structured store: models can be structured and stored dynamically. You can form one-to-one, one-to-many and many-to-many relations with indexing and lookup functionality.
Copy
// configuration instance key. config object will be saved under this key.pubstaticCONFIG_KEY:&[u8]=b"config";// contract state structure, this will be saved.#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]pubstructState{pub creator:HumanAddr,pub owner:HumanAddr,pub collateral:Vec<Coin>,pub counter_offer:Vec<Coin>,pub expires:u64,}pubfnconfig(storage:&mutdynStorage)->Singleton<State>{singleton(storage,CONFIG_KEY)}pubfnconfig_read(storage:&dynStorage)->ReadonlySingleton<State>{singleton_read(storage,CONFIG_KEY)}
The init function will be called exactly once, before the contract is executed. It is a "privileged" function in that it can set configuration that can never be modified by any other method call.
the first line parses the input from raw bytes into our contract-defined message. We then check if option is expired, then create the initial state. If expired, we return a generic contract error, otherwise, we store the state and return a success code:
You will see this signature all over CosmWasm handler functions. Execution context passed in to handler using Deps, which contains Storage, API and Querier functions; Env, which contains block, message and contract info; and msg, well, no explanation needed.
Result<T, ContractError> is a type that represents either success ([Ok]) or failure ([Err]). If the execution is successful returns T type otherwise returns ContractError. Useful.
Copy
pubfnhandle_transfer(
deps:DepsMut,
_env:Env,
info:MessageInfo,
recipient:HumanAddr,)->Result<HandleResponse,ContractError>{// ensure msg sender is the ownerletmut state =config(deps.storage).load()?;if info.sender != state.owner {returnErr(ContractError::Unauthorized{});}// set new owner on state
state.owner = recipient.clone();config(deps.storage).save(&state)?;letmut res =Context::new();
res.add_attribute("action","transfer");
res.add_attribute("owner", recipient);Ok(res.into())}
You will see handle_execute in plus and example smart contracts, but actually it is just a naming, nothing special.
Most of the function is same with transfer. Just two new things: message fund check and sdk messages in return context.
Copy
pubfnhandle_execute(
deps:DepsMut,
env:Env,
info:MessageInfo,)->Result<HandleResponse,ContractError>{// ensure msg sender is the ownerlet state =config(deps.storage).load()?;if info.sender != state.owner {returnErr(ContractError::Unauthorized{});}// ensure not expiredif env.block.height >= state.expires {returnErr(ContractError::OptionExpired{
expired: state.expires,});}// ensure sending proper counter_offerif info.sent_funds != state.counter_offer {returnErr(ContractError::CounterOfferMismatch{
offer: info.sent_funds,
counter_offer: state.counter_offer,});}// release counter_offer to creatorletmut res =Context::new();
res.add_message(BankMsg::Send{
from_address: env.contract.address.clone(),
to_address: state.creator,
amount: state.counter_offer,});// release collateral to sender
res.add_message(BankMsg::Send{
from_address: env.contract.address,
to_address: state.owner,
amount: state.collateral,});// delete the optionconfig(deps.storage).remove();
res.add_attribute("action","execute");Ok(res.into())}
This contracts query method is very simple, only configuration query.
For more complex queries check cosmwasm-plus(opens new window) contracts.
If you are starting to learn from zero, now you have 20 minutes of cosmwasm experience. Go ahead skim plus contracts to see the simplicity.
Copy
pubfnquery(deps:Deps, _env:Env, msg:QueryMsg)->StdResult<Binary>{match msg {QueryMsg::Config{}=>to_binary(&query_config(deps)?),}}fnquery_config(deps:Deps)->StdResult<ConfigResponse>{let state =config_read(deps.storage).load()?;Ok(state)}
Normally Rust compiler does its job great, leads you to the solution for the errors, shows warnings etc.
But it is always good to run linter on the code.
We can also generate JSON Schemas that serve as a guide for anyone trying to use the contract. This is mainly for documentation purposes, but if you click on "Open TypeScript definitions" in the code explorer, you can see how we use those to generate TypeScript bindings.
