Crate for providing metadata for Gear programs.

Metadata is used to describe the interface of a Gear program. For example, it can be used when uploading a program using https://idea.gear-tech.io. The metadata informs the user about the program's interface and allows them to interact with it using custom types on web applications UI.

Another use case is to parse metadata in JavaScript using the gear-js library and get the metadata details for some custom UI.

Note that metadata is not required for a Gear program to work. It is only used to provide additional information about the program. Also, metadata can be used for various purposes but we will focus on the use cases related to the https://idea.gear-tech.io.

To generate a metadata output file for a program, you need:

• Add gmeta crate to your Cargo.toml file.
• Define an empty struct that will identify the program metadata.
• Implement the [Metadata] trait for this struct by defining the associated types of the trait.
• Option 1: Call gear_wasm_builder::build_with_metadata function in build.rs file.
• Option 2: Convert metadata to hex string using [MetadataRepr::hex] function and write it to the text file.

Examples

In this example we will create a simple ping-pong program. Let's define message types and metadata in a separate ping-io crate to be able to use it in both program and build.rs files.

We will define message types for handle() and state() functions.

• ping-io crate:

#[no_std]
use gmeta::{InOut, Metadata, Out};
use gstd::prelude::*;

// Message type for `handle()` function.
#[derive(Encode, Decode, TypeInfo)]
pub enum PingPong {
Ping,
Pong,
}

// Metadata struct.
pub struct ProgramMetadata;

impl Metadata for ProgramMetadata {
// The unit tuple is used as neither incoming nor outgoing messages are
// expected in the `init()` function.
type Init = ();
// We use the same `PingPong` type for both incoming and outgoing
// messages.
type Handle = InOut<PingPong, PingPong>;
// The unit tuple is used as we don't use asynchronous interaction in this
// program.
type Others = ();
// The unit tuple is used as we don't process any replies in this program.
type Reply = ();
// The unit tuple is used as we don't process any signals in this program.
type Signal = ();
// We return a counter value (`i32`) in the `state()` function in this program.
type State = Out<i32>;
}

• ping program crate:

#[no_std]
use gmeta::{InOut, Metadata};
use gstd::{msg, prelude::*};
# const IGNORE: &'static str = stringify! {
use ping_io::PingPong;
# };

// Counter that will be incremented on each `Ping` message.
static mut COUNTER: i32 = 0;

# #[derive(Encode, Decode, TypeInfo)]
# pub enum PingPong {
#     Ping,
#     Pong,
# }
#
#[no_mangle]
extern "C" fn handle() {
// Load incoming message of `PingPong` type.
let payload: PingPong = msg::load().expect("Unable to load");

if let PingPong::Ping = payload {
unsafe { COUNTER += 1 };
// Send a reply message of `PingPong` type back to the sender.
msg::reply(PingPong::Pong, 0).expect("Unable to reply");
}
}

#[no_mangle]
extern "C" fn state() {
msg::reply(unsafe { COUNTER }, 0).expect("Unable to reply");
}

• build.rs file:

# const IGNORE: &'static str = stringify! {
use ping_io::ProgramMetadata;
# };
#
# pub struct ProgramMetadata;
# impl gmeta::Metadata for ProgramMetadata {
#     type Init = ();
#     type Handle = ();
#     type Others = ();
#     type Reply = ();
#     type Signal = ();
#     type State = ();
# }

fn main() {
gear_wasm_builder::build_with_metadata::<ProgramMetadata>();
}

You can also generate metadata manually and write it to the file without using build.rs:

use gmeta::{Metadata, Out};
# const IGNORE: &'static str = stringify! {
use ping_io::ProgramMetadata;
# };
use std::fs;

# #[derive(gstd::Encode, gstd::Decode, gstd::TypeInfo)]
# pub enum PingPong {
#     Ping,
#     Pong,
# }
#
# pub struct ProgramMetadata;
# impl gmeta::Metadata for ProgramMetadata {
#     type Init = ();
#     type Handle = (PingPong, PingPong);
#     type Others = ();
#     type Reply = ();
#     type Signal = ();
#     type State = Out<i32>;
# }
#
let metadata_hex = ProgramMetadata::repr().hex();
assert_eq!(metadata_hex.len(), 146);
fs::write("ping.meta.txt", metadata_hex).expect("Unable to write");

You can parse generated metadata file using gear-js API in JavaScript:

import { getProgramMetadata } from '@gear-js/api';
import { readFileSync } from 'fs';

const metadataHex = readFileSync('ping.meta.txt', 'utf-8');
const metadata = getProgramMetadata('0x' + metadataHex);

console.log('Registry:', metadata.regTypes);
console.log('Types:', metadata.types);

This will print the following:

Registry: Map(2) {
0 => { name: 'RustOutPingPong', def: '{"_enum":["Ping","Pong"]}' },
1 => { name: 'i32', def: null }
}
Types: {
init: { input: null, output: null },
handle: { input: 0, output: 0 },
reply: { input: null, output: null },
others: { input: null, output: null },
signal: null,
state: 1
}