Getting started in 5 minutes
This guide provides a general overview of running smart contracts on the networks powered by Gear Protocol (such as the Vara Network). It guides you through how to write a smart contract, compile it to Wasm and deploy it to the Gear network.
Attention developers! Want to take your blockchain development skills to the next level? Join Gear Academy's free course, "Gear Smart Contract Developer." In this comprehensive course, you'll learn the ins and outs of developing on the Gear Protocol, from deploying programs onto the blockchain and interacting with them, to testing your programs on the Gear Network. You'll also gain hands-on experience navigating the @gear-js
library for interacting with contracts on the client side and developing real-world applications, including contracts and frontends. Don't miss this opportunity to become a pro Gear blockchain developer. Enroll now in Gear Academy's "Gear Smart Contract Developer" course!
Prerequisitesโ
-
Linux users should generally install
GCC
andClang
, according to their distributionโs documentation.For example, on Ubuntu use:
sudo apt install -y build-essential clang cmake
On macOS, you can get a compiler toolset by running:
xcode-select --install
-
Make sure you have installed all the tools required to build a smart-contract in Rust. Rustup will be used to get Rust compiler ready:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-
Now, let's install a
nightly
version of the toolchain withrustup
, since Gear uses the most up-to-date featuresrustup
provides. We usenightly-2023-09-18
as it is the latest version that is compatible with Gear.rustup toolchain add nightly-2023-09-18
-
As we will be compiling our Rust smart contract to Wasm, we will need a Wasm compiler. Let's add it to the toolchain.
rustup target add wasm32-unknown-unknown --toolchain nightly-2023-09-18
-
Also, you need to install the
wasm-proc
utility that optimizes compiled Wasm to be more compact.cargo install --locked --git https://github.com/gear-tech/gear.git wasm-proc
Note: If you use Windows, download and install Build Tools for Visual Studio.
Creating your first Gear smart contractโ
-
For your convenience, it is recommended that you create a dedicated directory for everything Gear-related. The rest of the article will assume that you are using the paths suggested. Type to create a folder in your home directory:
mkdir -p ~/gear
-
Let's create a
contracts
directory insidegear
andcd
to it.mkdir -p ~/gear/contracts
cd ~/gear/contracts -
The next step would be to build a Rust library for our contract:
cargo new counter --lib
Now, your
gear/contracts
directory tree should look like this:counter
โโโ Cargo.toml
โโโ src
โโโ lib.rs -
It's time to write some code. Open
counter
with your favorite editor. ForVS Code
editor type:code ~/gear/contracts/counter
-
In the
counter
folder, configureCargo.toml
for our contract to be properly built:[package]
name = "counter"
version = "0.1.0"
edition = "2021"
[lib]
crate-type = ["cdylib"]
[dependencies]
gstd = { git = "https://github.com/gear-tech/gear.git", tag = "v1.0.2" } -
Replace the default contents of
lib.rs
in thecounter
folder with the code for our first smart-contract.This simple smart-contract accepts
inc
,dec
, andget
commands. Opensrc/lib.rs
in your editor and paste the following code:#![no_std]
use gstd::{msg, prelude::*};
static mut COUNTER: i32 = 0;
#[no_mangle]
extern "C" fn handle() {
let command = msg::load_bytes().expect("Invalid message");
let mut counter = unsafe { COUNTER };
match command.as_slice() {
b"inc" => counter += 1,
b"dec" => counter -= 1,
b"get" => {
msg::reply_bytes(format!("{counter}"), 0).expect("Unable to reply");
}
_ => (),
}
unsafe { COUNTER = counter };
} -
Now compile the smart-contract to Wasm using
cargo
:RUSTFLAGS="-C link-args=--import-memory -C linker-plugin-lto" \
cargo +nightly-2023-09-18 build --release --target=wasm32-unknown-unknownThis command is quite verbose, so we can create cargo config and Rust toolchain override files to make it shorter. Create a
.cargo/config.toml
file in thecounter
directory with the following contents:[build]
target = "wasm32-unknown-unknown"
rustflags = [
"-C", "link-args=--import-memory",
"-C", "linker-plugin-lto",
]And create a
rust-toolchain.toml
file in thecounter
directory with the following contents:[toolchain]
channel = "nightly-2023-09-18"
targets = ["wasm32-unknown-unknown"]
profile = "default"Now you can build your smart-contract with a single command:
cargo build --release
If everything goes well, your working directory should now have a
target
directory that looks like this:target
โโโ ...
โโโ wasm32-unknown-unknown
โโโ release
โโโ ...
โโโ counter.wasm <---- this is our built .wasm file -
The last preparation step is to optimize the Wasm binary using
wasm-proc
:wasm-proc target/wasm32-unknown-unknown/release/counter.wasm
A new Wasm file will be created:
target
โโโ ...
โโโ wasm32-unknown-unknown
โโโ release
โโโ ...
โโโ counter.wasm <---- this is our built .wasm file
โโโ counter.opt.wasm <---- this is optimized .wasm fileNow the
target/wasm32-unknown-unknown/release
directory contains two required Wasm binaries:counter.wasm
is the output Wasm binary built from source filescounter.opt.wasm
is the optimized Wasm aimed to be uploaded to the blockchain
Deploy your Smart Contract to the Testnetโ
Gear provides a demo application that implements all of the possibilities of interaction with smart-contracts in Gear networks, available at idea.gear-tech.io.
Create accountโ
-
Download the Polkadot extension for your browser via https://polkadot.js.org/extension/. This extension manages accounts and allows the signing of transactions with those accounts. It is a secure tool that allows injecting your accounts into any Substrate-based dapp. It does not perform wallet functions, e.g send funds.
-
Once downloaded, click + button to create a new account:
-
Make sure you save your 12-word mnemonic seed securely.
-
Select the network that will be used for this account - choose "Allow to use on any chain". Provide any name to this account and password and click "Add the account with the generated seed" to complete account registration.
-
Go to idea.gear-tech.io. You will be prompted to grant access to your account for Gear Tech application, click "Yes, allow this application access".
-
Make sure you are connected to the
Vara Network Testnet
. The network name is on the bottom left corner of the page. -
You may switch the network by clicking on the network name.
-
Click the
Connect
button on the top-right to select an account that will be connected to Gear Tech.
-
In accordance with the Actor model, smart contracts are uploaded to a network via messages. Gear node charges a gas fee during message processing. Your account balance needs to have enough funds to upload a smart-contract to the
TestNet
. Click the following button to get the test balance:A notification about successful balance replenishment will appear after passing captcha at the bottom of the window. You can also see the current account balance next to the account name in the upper right corner.
Upload programโ
-
When your account balance is sufficient, click the Upload program and navigate to the
.opt.wasm
file we have pointed to above. -
Specify the program Name and click Calculate Gas button. The Gas limit will be set automatically. Now click the Upload program button.
-
Sign the program uploading the transaction to the Gear network. Also, sign the program and metadata upload to the Gear demo environment so you could work with the program. It is recommended to set the checkbox
Remember my password for the next 15 minutes
for your convenience.
The red dot status for a program indicates init failure. Try to upload the program again with an increased Gas limit.
-
Once your program is uploaded, head to the
Programs
section and find your program.
Send message to a programโ
-
Now, try sending your newly uploaded program a message to see how it responds! Click the Send message button.
-
In the
Payload
field of the opened dialog type0x696E63
(this isinc
encoded in hex). Click Calculate Gas button, the Gas limit will be set automatically. Now click the Send Message button. -
Sign the message sending transaction as it is shown in step 3 of the section Upload Program.
-
After your message has been successfully processed, you are to see correspondent log messages:
Now you have sent an increment command to the program. After processing the counter will be incremented to
1
. -
Repeat step 2 with
0x676574
payload (this isget
command). This will send a get command to the program. -
Press the Mailbox button to enter the mailbox and find the reply.
noteThe reply is in the mailbox for a limited time depending on the gas limit. If you don't see the reply, try resending the
0x676574
(get
) message with the gas limit increasing and go to the mailbox immediately after sending the message.
Further readingโ
For more info about writing smart contracts for Gear and the specifics behind the smart contract implementation, refer to this article on Smart Contracts.