Gear Examples

Gear provides a set of examples that can be used for your familiarization with writing programs on Gear or become the basis for your own dApp: https://github.com/gear-dapps.

You can write your own smart contract or try to build from examples. Let's Rock!

Stable environment

All smart contract examples and JS applications have been tested on a stable environment that consists of specific development tool versions necessary for implementing, building and running smart contracts and JS applications.

You may configure a local development environment according to the information provided below or use a pre-configured Docker image as described in the Using Docker section.

Current stable release: v1.1

Compiler Tools	Version	How to install / access
Linux users should generally install GCC and Clang, according to their distribution’s documentation.	Latest	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
Rust	2023-04-25	curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh Add Wasm target to your toolchain: rustup toolchain add nightly rustup target add wasm32-unknown-unknown --toolchain nightly
Gear Rust libraries: gstd, gtest, gmeta, gclient, gear-wasm-builder	commit hash: 78dfa07	Make sure the correct commit hash version is specified in the Cargo.toml file of the smart contract you're working on. For example: https://github.com/gear-dapps/app/blob/master/Cargo.toml#L10

Gear JS Tools	Version	How to install / access
Gear JS API	0.31.2	Make sure this version is specified in the package.json file of your smart contract repository
Gear JS React Hooks	0.5.18	Make sure this version is specified in the package.json file of your smart contract repository
Gear JS UI Kit	0.5.18	Make sure this version is specified in the package.json file of your smart contract repository

Note

Windows users may encounter some problems related to the installation of Rust components and dependencies. It is highly recommended to use Linux or macOS for compiling Gear node and smart-contracts.

First steps

To create our app project use the command cargo:

cargo new gear-app --lib

The project structure is following:

  └── gear-app // Your contract dir
      │
      ├── src // Source files of your program
      │    ├── maybe_some_file.rs // Additional module if needed
      │    └── lib.rs // Main file of your program
      │
      └── Cargo.toml // Manifest of your program

Create file build.rs with the following code:

fn main() {
    gear_wasm_builder::build();
}

Cargo.toml is a project manifest in Rust, it contains all metadata necessary for compiling the project. Configure the Cargo.toml similarly to how it is configured ping/Cargo.toml. You can refer to Getting Started for additional details.

Building Rust Contract

We should compile our smart contract in the app folder:

cargo build --release

Our application should compile successfully and the final file target/wasm32-unknown-unknown/release/gear-app.wasm should appear.

Using Docker

You can use a pre-configured Docker image to build and test your smart contract. The image contains all the necessary tools and dependencies for building and running smart contracts and JS applications.

The source code of the image is available on GitHub.

To use the image, you need to install Docker on your machine. You can find the installation instructions for your OS on the Docker website.

After installing Docker, you can pull the image from the Docker Hub:

docker pull ghcr.io/gear-dapps/gear-env:stable

To run the image, use the following command:

Linux / macOS x86_64

docker run --rm --name gear-env -itd ghcr.io/gear-dapps/gear-env:stable bash

macOS ARM

docker run --rm --name gear-env --platform linux/amd64 -itd ghcr.io/gear-dapps/gear-env:stable bash

The command will run the image in the background and give you access to the container's shell. You can use the following command to access the container's shell:

docker exec -it gear-env bash

Copy a smart contract to be built to the container (here we use the gear-app created above):

docker cp ./gear-app gear-env:/root

After that, you can build the smart contract:

docker exec -itw /root/gear-app gear-env cargo build --release

The compiled smart contract will be available in the target/wasm32-unknown-unknown/release folder inside the container. Copy it to your local machine:

docker cp gear-env:/root/gear-app/target/wasm32-unknown-unknown/release/. ./

Stop the Docker container after using:

docker stop gear-env