Skip to main content

Gear Library (Low-Level)

The Gear Protocol’s library gstd provides all the necessary and sufficient functions and methods for developing programs.

Importing familiar types via prelude​

The gstd default prelude lists things that Rust automatically imports into every program. It re-imports default std modules and traits. std can be safely replaced with gstd in the Vara programs on Rust.

See more details here.

Message handling​

The Gear Protocol allows users and programs to interact with other users and programs via messages. Messages can contain a payload that can be processed during message execution. Interaction with messages is possible thanks to the module msg:

use gstd::msg;

Message processing is possible only inside the defined functions init(), handle(), hadle_reply(), and state(). They also define the context for processing such messages.

  • Get a payload of the message currently being processed and decode it:
#![no_std]
use gstd::{msg, prelude::*};

#[no_mangle]
extern "C" fn handle() {
    let payload_string: String = msg::load().expect("Unable to decode `String`");
}
  • Reply to the message with payload:
#![no_std]
use gstd::msg;

#[no_mangle]
extern "C" fn handle() {
    msg::reply("PONG", 0).expect("Unable to reply");
}
  • Send message to user:
#![no_std]
use gstd::{msg, prelude::*};

#[no_mangle]
extern "C" fn handle() {
    // ...
    let id = msg::source();
    let message_string = "Hello there".to_string();
    msg::send(id, message_string, 0).expect("Unable to send message");
}

More cases of using the msg module can be found in the documentation.

Execution info​

A program can get some useful information about the current execution context by using the exec module:

use gstd::exec;
  • Send a reply after the block timestamp reaches the indicated date:
#![no_std]
use gstd::{exec, msg};

#[no_mangle]
extern "C" fn handle() {
    // Timestamp is in milliseconds since the Unix epoch
    if exec::block_timestamp() >= 1672531200000 {
        msg::reply(b"Current block has been generated after January 01, 2023", 0)
            .expect("Unable to reply");
    }
}
  • Get self value balance of a program:
#![no_std]
use gstd::exec;

#[no_mangle]
extern "C" fn handle() {
    // Get self value balance in program
    let my_balance = exec::value_available();
}

More info about program syscalls can be found here.

Logging inside the programs​

Macro gstd::debug provides an ability to debug program during program execution:

#![no_std]
use gstd::{debug, msg, prelude::*};

#[no_mangle]
extern "C" fn handle() {
    let payload_string: String = msg::load().expect("Unable to decode `String`");
    debug!("Received message: {payload_string:?}");
}
note

The debug! macro is available only when the "debug" feature is enabled for the gstd crate.

[dependencies]
gstd = { git = "https://github.com/gear-tech/gear.git", tag = "v1.1.1", features = ["debug"] }