Your First Smart Contract
Within this section, we'll explain how to setup your environment for CosmWasm Smart Contracts Development.
Prerequisites
Before starting, make sure you have rustup
along with recent versions of rustc
and cargo
installed. Currently, we are testing on Rust v1.58.1+.
You also need to have the wasm32-unknown-unknown
target installed as well as the cargo-generate
Rust crate.
You can check versions via the following commands:
Objectives
Create and interact with a smart contract that increases and resets a counter to a given value
Understand the basics of a CosmWasm smart contract, learn how to deploy it on Injective, and interact with it using Injective tools
CosmWasm Contract Basics
A smart contract can be considered an instance of a singleton object whose internal state is persisted on the blockchain. Users can trigger state changes by sending the smart contract JSON messages, and users can also query its state by sending a request formatted as a JSON message. These JSON messages are different than Injective blockchain messages such as MsgSend
and MsgExecuteContract
.
As a smart contract writer, your job is to define 3 functions that compose your smart contract's interface:
instantiate()
: a constructor which is called during contract instantiation to provide initial stateexecute()
: gets called when a user wants to invoke a method on the smart contractquery()
: gets called when a user wants to get data out of a smart contract
In our sample counter contract, we will implement one instantiate
, one query
, and two execute
methods.
Start with a Template
In your working directory, quickly launch your smart contract with the recommended folder structure and build options by running the following commands:
This helps get you started by providing the basic boilerplate and structure for a smart contract. In the src/contract.rs
file you will find that the standard CosmWasm entrypoints instantiate()
, execute()
, and query()
are properly exposed and hooked up.
State
You can learn more about CosmWasm State on their documentation.
State
handles the state of the database where smart contract data is stored and accessed.
The starting template has the following basic state, a singleton struct State
containing:
count
, a 32-bit integer with whichexecute()
messages will interact by increasing or resetting it.owner
, the senderaddress
of theMsgInstantiateContract
, which will determine if certain execution messages are permitted.
Injective smart contracts have the ability to keep persistent state through Injective's native LevelDB, a bytes-based key-value store. As such, any data you wish to persist should be assigned a unique key, which may be used to index and retrieve the data.
Data can only be persisted as raw bytes, so any notion of structure or data type must be expressed as a pair of serializing and deserializing functions. For instance, objects must be stored as bytes, so you must supply both the function that encodes the object into bytes to save it on the blockchain, as well as the function that decodes the bytes back into data types that your contract logic can understand. The choice of byte representation is up to you, so long as it provides a clean, bi-directional mapping.
Fortunately, CosmWasm provides utility crates, such as cosmwasm_storage
, which provides convenient high-level abstractions for data containers such as a "singleton" and "bucket", which automatically provide serialization and deserialization for commonly-used types, such as structs and Rust numbers. Additionally, thecw-storage-plus
crate can be used for a more efficient storage mechanism.
Notice how the State
struct holds both count
and owner
. In addition, the derive
attribute is applied to auto-implement some useful traits:
Serialize
: provides serializationDeserialize
: provides deserializationClone
: makes the struct copyableDebug
: enables the struct to be printed to stringPartialEq
: provides equality comparisonJsonSchema
: auto-generates a JSON schema
Addr
refers to a human-readable Injective address prefixed with inj
, e.g. inj1clw20s2uxeyxtam6f7m84vgae92s9eh7vygagt
.
InstantiateMsg
You can learn more about CosmWasm InstantiateMsg on their documentation
The InstantiateMsg
is provided to the contract when a user instantiates a contract on the blockchain through a MsgInstantiateContract
. This provides the contract with its configuration as well as its initial state.
On the Injective blockchain, the uploading of a contract's code and the instantiation of a contract are regarded as separate events, unlike on Ethereum. This is to allow a small set of vetted contract archetypes to exist as multiple instances sharing the same base code, but be configured with different parameters (imagine one canonical ERC20, and multiple tokens that use its code).
Example
For your contract, the contract creator is expected to supply the initial state in a JSON message. We can see in the message definition below that the message holds one parameter count
, which represents the initial count.
Message Definition
Contract Logic
In contract.rs
, you will define your first entry-point, instantiate()
, or where the contract is instantiated and passed its InstantiateMsg
. Extract the count from the message and set up your initial state where:
count
is assigned the count from the messageowner
is assigned to the sender of theMsgInstantiateContract
ExecuteMsg
You can learn more about CosmWasm ExecuteMsg in their documentation.
The ExecuteMsg
is a JSON message passed to the execute()
function through a MsgExecuteContract
. Unlike the InstantiateMsg
, the ExecuteMsg
can exist as several different types of messages to account for the different types of functions that a smart contract can expose to a user. The execute()
function demultiplexes these different types of messages to its appropriate message handler logic.
We have two ExecuteMsg: Increment
and Reset
.
Increment
has no input parameter and increases the value of count by 1.Reset
takes a 32-bit integer as a parameter and resets the value ofcount
to the input parameter.
Example
Increment
Any user can increment the current count by 1.
Reset
Only the owner can reset the count to a specific number. See Logic below for the implementation details.
Message Definition
For ExecuteMsg
, an enum
can be used to multiplex over the different types of messages that your contract can understand. The serde
attribute rewrites your attribute keys in snake case and lower case, so you'll have increment
and reset
instead of Increment
and Reset
when serializing and deserializing across JSON.
Logic
This is your execute()
method, which uses Rust's pattern matching to route the received ExecuteMsg
to the appropriate handling logic, either dispatching a try_increment()
or a try_reset()
call depending on the message received.
First, it acquires a mutable reference to the storage to update the item located at key state
. It then updates the state's count by returning an Ok
result with the new state. Finally, it terminates the contract's execution with an acknowledgement of success by returning an Ok
result with the Response
.
The logic for reset is very similar to increment—except this time, it first checks that the message sender is permitted to invoke the reset function (in this case, it must be the contract owner).
QueryMsg
You can learn more about CosmWasm QueryMsg in their documentation
The GetCount
query message has no parameters and returns the count
value.
See the implementation details in Logic below.
Example
The template contract only supports one type of QueryMsg
:
GetCount
The request:
Which should return:
Message Definition
To support data queries in the contract, you'll have to define both a QueryMsg
format (which represents requests), as well as provide the structure of the query's output—CountResponse
in this case. You must do this because query()
will send information back to the user through structured JSON, so you must make the shape of your response known. See Generating JSON Schema for more info.
Add the following to your src/msg.rs
:
Logic
The logic for query()
is similar to that of execute()
; however, since query()
is called without the end-user making a transaction, the env
argument is omitted as no information is necessary.
Unit test
Unit tests should be run as the first line of assurance before deploying the code on chain. They are quick to execute and can provide helpful backtraces on failures with the RUST_BACKTRACE=1
flag:
You can find the unit test implementation at src/contract.rs
Building the Contract
Now that we understand and have tested the contract, we can run the following command to build the contract. This will check for any preliminary errors before we optimize the contract in the next step.
Next, we must optimize the contract in order to ready the code for upload to the chain.
Read more details on preparing the Wasm bytecode for production
CosmWasm has rust-optimizer, an optimizing compiler that can produce a small and consistent build output. The easiest method to use the tool is to use a published Docker image—check here for the latest x86 version, or here for the latest ARM version. With Docker running, run the following command to mount the contract code to /code
and optimize the output (you can use an absolute path instead of $(pwd)
if you don't want to cd
to the directory first):
If you're on an ARM64 machine, you should use a docker image built for ARM64:
CosmWasm does not recommend using the ARM64 version of the compiler because it produces different Wasm artifacts from the Intel/AMD version. For release/production, only contracts built with Intel/AMD optimizers are recommended for use. See here for the note from CosmWasm.
You may receive an Unable to update registry `crates-io`
error while running the command. Try adding the following lines to the Cargo.toml
file located within the contract directory and running the command again:
See The Cargo Book for more information.
This produces an artifacts
directory with a PROJECT_NAME.wasm
, as well as checksums.txt
, containing the Sha256 hash of the Wasm file. The Wasm file is compiled deterministically (anyone else running the same docker on the same git commit should get the identical file with the same Sha256 hash).
Install injectived
injectived
injectived
is the command-line interface and daemon that connects to Injective and enables you to interact with the Injective blockchain.
If you want to interact with your Smart Contract locally using CLI, you have to have injectived
installed. To do so, you can follow the installation guidelines here Install injectived.
Alternatively, a Docker image has been prepared to make this tutorial easier.
If you install injectived
from the binary, ignore the docker commands. On the public endpoints section you can find the right --node info to interact with Mainnet and Testnet.
Executing this command will make the docker container execute indefinitely.
Note: directory_to_which_you_cloned_cw-template
must be an absolute path. The absolute path can easily be found by running the pwd
command from inside the CosmWasm/cw-counter directory.
Open a new terminal and go into the Docker container to initialize the chain:
Let’s start by adding jq
dependency, which will be needed later on:
Now we can proceed to local chain initialization and add a test user called testuser
(when prompted use 12345678 as password). We will only use the test user to generate a new private key that will later on be used to sign messages on the testnet:
OUTPUT
Take a moment to write down the address or export it as an env variable, as you will need it to proceed:
You can request testnet funds for your recently generated test address using the Injective test faucet.
Now you have successfully created testuser
an Injective Testnet. It should also hold some funds after requesting testnet
funds from the faucet.
To confirm, search for your address on the Injective Testnet Explorer to check your balance.
Alternatively, you can verify it by querying the bank balance or with curl:
Upload the Wasm Contract
Now it's time to upload the .wasm
file that you compiled in the previous steps to the Injective Testnet. Please note that the procedure for mainnet is different and requires a governance proposal.
Output:
Check your address on the Injective Testnet Explorer, and look for a transaction with the txhash
returned from storing the code on chain. The transaction type should be MsgStoreCode
.
You can see all stored codes on Injective Testnet under Code.
There are different ways to find the code that you just stored:
Look for the TxHash on the Injective Explorer codes list; it is most likely the most recent.
Use
injectived
to query transaction info.
To query the transaction use the txhash
and verify the contract was deployed.
Inspecting the output more closely, we can see the code_id
of 290
for the uploaded contract:
Let's export your code_id
as an ENV variable—we'll need it to instantiate the contract. You can skip this step and manually add it later, but keep note of the ID.
Generating JSON Schema
While the Wasm calls instantiate
, execute
, and query
accept JSON, this is not enough information to use them. We need to expose the schema for the expected messages to the clients.
In order to make use of JSON-schema auto-generation, you should register each of the data structures that you need schemas for.
The schemas can then be generated with
which will output 5 files in ./schema
, corresponding to the 3 message types the contract accepts, the query response message, and the internal State
.
These files are in standard JSON Schema format, which should be usable by various client side tools, either to auto-generate codecs, or just to validate incoming JSON with respect to the defined schema.
Take a minute to generate the schema (take a look at it here) and get familiar with it, as you will need to it for the next steps.
Instantiate the Contract
Now that we have the code on Injective, it is time to instantiate the contract to interact with it.
Reminder On CosmWasm, the upload of a contract's code and the instantiation of a contract are regarded as separate events
To instantiate the contract, run the following CLI command with the code_id you got in the previous step, along with the JSON encoded initialization arguments and a label (a human-readable name for this contract in lists).
Output:
You can find the contract address and metadata by:
Looking on the Testnet Explorer
Querying the ContractsByCode and ContractInfo APIs
Querying through the CLI
Querying the Contract
As we know from earlier, the only QueryMsg we have is get_count
.
Output:
We see that count
is 99, as set when we instantiated the contract.
If you query the same contract, you may receive a different response as others may have interacted with the contract and incremented or reset the count.
Execute the Contract
Let's now interact with the contract by incrementing the counter.
If we query the contract for the count, we see:
yes 12345678 | automatically pipes (passes) the passphrase to the input of injectived tx wasm execute so you do not need to enter it manually.
To reset the counter:
Now, if we query the contract again, we see the count has been reset to the provided value:
Cosmos Messages
In addition to defining custom smart contract logic, CosmWasm also allows contracts to interact with the underlying Cosmos SDK functionalities. One common use case is to send tokens from the contract to a specified address using the Cosmos SDK's bank module.
Example: Bank Send
The BankMsg::Send
message allows the contract to transfer tokens to another address. This can be useful in various scenarios, such as distributing rewards or returning funds to users.
Note: If you want to send funds and execute a function on another contract at the same time, don't use BankMsg::Send. Instead, use WasmMsg::Execute and set the respective funds field.
Constructing the Message
You can construct a BankMsg::Send
message within your contract's execute
function. This message requires specifying the recipient address and the amount to send. Here's an example of how to construct this message:
Usage in a Smart Contract
In your contract, you can add a new variant to your ExecuteMsg enum to handle this bank send functionality. For example:
Then, in the execute
function, you can add a case to handle this message:
Testing
As with other smart contract functions, you should add unit tests to ensure your bank send functionality works as expected. This includes testing different scenarios, such as sending various token amounts and handling errors correctly.
You may use test-tube for running integration tests that include a local Injective chain.
Congratulations! You've created and interacted with your first Injective smart contract and now know how to get started with CosmWasm development on Injective. Continue to Creating a Frontend for Your Contract for a guide on creating a web UI.
Last updated