02-tutorial-Rust-SDK.md

Trinci rust SDK

How to write a method callable from a transaction

A method to be executed through a transaction:

• must have this signature:

  fn my_method(context: AppContext, args: SerializableStruct) -> WasmResult<Value>;

  • where SerializableStruct is a struct that derives the Serializable/Deserializable traits from the serde_derive crate.

  #[derive(Serialize, Deserialize, Debug)]
  #[cfg_attr(test, derive(PartialEq, Clone, Default))]
  struct SerializableStruct {
      pub field1: u32,
      pub field2: u8,
      ...
  }

• must be exported by the app_export! sdk macro, like this:

  sdk::app_export!(..., my_method, ...);

Host Functions Wrapper

log

pub fn log(msg: &str);

• send the message msg to the host to be logged.

load_data

pub fn load_data(key: &str) -> Vec<u8>;

• load the serialized data stored at the given key from the current account.

store_data

pub fn store_data(key: &str, buf: &[u8]);

• store the data passed as bytes array in the current account at the given key.

remove_data

pub fn remove_data(key: &str);

• remove the data stored at the given key from the current account.

load_asset

pub fn load_asset(id: &str) -> Vec<u8>;

• load asset from the account id specified.
• the asset id is the current account id

store_asset

pub fn store_asset(id: &str, value: &[u8]);

• store asset to the account id specified as byte array.
• the asset id is the current account id

verify

pub fn verify(pk: &PublicKey, data: &[u8], sign: &[u8]) -> bool;

• verify the signature of the given data by the given pk and algorithm

call

pub fn call(account: &str, method: &str, data: &[u8]) -> WasmResult<Vec<u8>>;

• calls a method of an arbitrary smart contract passing the data as argument
• if succeed returns the data from the method called

asset_balance

pub fn asset_balance(asset: &str) -> WasmResult<u64>;

• get account balance for a given asset id.
• this is an helper function over the lower level call(asset_id, "balance", args).

asset_transfer

pub fn asset_transfer(from: &str, to: &str, asset: &str, units: u64) -> WasmResult<()>;

• transfer an amount of asset units to a destination account.
• this is an helper function over the lower level call(asset_id, "transfer", args).

asset_lock

pub fn asset_lock(asset: &str, to: &str, value: LockType) -> WasmResult<()>;

• Lock/Unlock the asset.
• this is an helper function over the lower level call(asset_id, "lock", true/false).

load_asset_typed

pub fn load_asset_typed<T: DeserializeOwned + Default>(id: &str) -> T;

• load asset with from the given account id and tries to convert it into a type.

store_asset_typed

pub fn store_asset_typed<T: Serialize>(id: &str, value: T);

• store the typed asset to the given account id.

RAW Host Functions

The functions above are wrapper to the raw host_function that can be also called directly.

• These functions require data structures to be written to memory and passed their address and size.
• WasmSlice that is a i64 where is coded address and size of a memory location that stores the result.

hf_log

• Allows to log strings

fn hf_log(address: i32, size: i32);

Example of usage:

...
let msg = String::from("Hello");
let buf = msg.as_bytes();

hf_log(buf.as_ref() as i32, buf.len() as i32);

...

hf_load_data

• Load data from the account

fn hf_load_data(key_addr: i32, key_size: i32) -> WasmSlice;

hf_store_data

• Store data to the account

fn hf_store_data(key_addr: i32, key_size: i32, data_addr: i32, data_size: i32);

hf_remove_data

• Remove data from the account

fn hf_remove_data(key_addr: i32, key_size: i32);

hf_load_asset

• load asset from the given account id

fn hf_load_asset(id_addr: i32, id_size: i32) -> WasmSlice;

hf_store_asset

• store asset to the given account id

fn hf_store_asset(id_addr: i32, id_size: i32, value_addr: i32, value_size: i32);

hf_verify

• verify the data signature

    fn hf_verify(
        pk_addr: i32,
        pk_size: i32,
        data_addr: i32,
        data_size: i32,
        sign_addr: i32,
        sign_size: i32,
    ) -> i32;

hf_call

• call the method of another account

    fn hf_call(
        account_addr: i32,
        account_size: i32,
        method_addr: i32,
        method_size: i32,
        data_addr: i32,
        data_size: i32,
    ) -> WasmSlice;

Utility Functions

rmp_serialize_named

• Serialize a type implementing Serialize trait using MessagePack format with named keys.

pub fn rmp_serialize_named<T>(val: &T) -> WasmResult<Vec<u8>>

rmp_serialize

• Serialize a type implementing Serialize trait using MessagePack format.

pub fn rmp_serialize<T>(val: &T) -> WasmResult<Vec<u8>>

rmp_deserialize

• Serialize a type implementing Deserialize trait using MessagePack format.

pub fn rmp_deserialize<'a, T>(buf: &'a [u8]) -> WasmResult<T>

PackedValue

• Value that has been already packed, thus it doesn't require further processing and shall be taken "as-is".

pub struct PackedValue(pub Vec<u8>);