gstd

The standard library for Gear programs provides all the necessary functions and methods required for your programs.

While gcore allows for a more low-level implementation of programs, gstd offers pre-built modules enabling program implementation in a secure and precise manner, which is recommended for most scenarios.

lib.rs:

Standard library for use in Gear programs.

This library should be used as a standard library when writing Gear programs. Compared to gcore crate, this library provides higher-level primitives that allow you to develop more complex dApps. Choose this library if you are ready to spend more gas but receive refined code.

gstd crate provides many advanced tools for a developer, such as asynchronous programming primitives, arbitrary types encoding/decoding, providing convenient instruments for creating programs from programs, etc.

Minimum supported Rust version

This crate requires Rust >= 1.81 due to the implementation of the panic handler in the stable version.

Crate features

Examples

Decode input payload using a custom type:

#![no_std]

use gstd::{msg, prelude::*};

#[derive(Decode, Encode, TypeInfo)]
#[codec(crate = gstd::codec)]
#[scale_info(crate = gstd::scale_info)]
struct Payload {
    question: String,
    answer: u8,
}

#[no_mangle]
extern "C" fn handle() {
    let payload: Payload = msg::load().expect("Unable to decode payload");
    if payload.question == "life-universe-everything" {
        msg::reply(payload.answer, 0).expect("Unable to reply");
    }
}

Asynchronous program example.

It sends empty messages to three addresses and waits for at least two replies ("approvals") during initialization. When invoked, it handles only PING messages and sends empty messages to the three addresses, and waits for just one approval. If approval is obtained, the program replies with PONG.

#![no_std]
use futures::future;
use gstd::{msg, prelude::*, ActorId};

static mut APPROVERS: [ActorId; 3] = [ActorId::zero(); 3];

#[derive(Debug, Decode, TypeInfo)]
#[codec(crate = gstd::codec)]
#[scale_info(crate = gstd::scale_info)]
pub struct Input {
    pub approvers: [ActorId; 3],
}

#[gstd::async_init]
async fn init() {
    let payload: Input = msg::load().expect("Failed to decode input");
    unsafe { APPROVERS = payload.approvers };

    let mut requests: Vec<_> = unsafe { APPROVERS }
        .iter()
        .map(|addr| msg::send_bytes_for_reply(*addr, b"", 0, 0))
        .collect::<Result<_, _>>()
        .unwrap();

    let mut threshold = 0;
    while !requests.is_empty() {
        let (.., remaining) = future::select_all(requests).await;
        threshold += 1;
        if threshold >= 2 {
            break;
        }
        requests = remaining;
    }
}

#[gstd::async_main]
async fn main() {
    let message = msg::load_bytes().expect("Failed to load payload bytes");
    if message != b"PING" {
        return;
    }

    let requests: Vec<_> = unsafe { APPROVERS }
        .iter()
        .map(|addr| msg::send_bytes_for_reply(*addr, b"", 0, 0))
        .collect::<Result<_, _>>()
        .unwrap();

    _ = future::select_all(requests).await;
    msg::reply(b"PONG", 0).expect("Unable to reply");
}