Skip to main content

Gear Library

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"] }