Skip to main content

Rust SDK Getting started

IC Mainnet demo

Import ICES Library

Cargo.toml

ices-sdk = { git = "https://github.com/icpfans-xyz/ices-contract.git", branch = "ices-sdk" }

Code Reference

use ices_sdk::{
    Transaction, 
    EventValue, 
    Indexed, 
    EventBuilder, 
    ICESBuilder
};

Register the current Canister to ICES Main (Router) Canister. Only need to register once successfully

let ices_builder = ICESBuilder::new()
    .build()
    .unwrap();

let _call_result = ices_sdk::register(ices_builder).await;

match _call_result {
    Ok(r) => {
        ic_cdk::println!("{:?}",r);
        true
    },
    Err(msg) => {
        ic_cdk::println!("msg:{}", msg);
        false
    } 
}

Emit event logs to ICES

  • Emit Common Event logs to ICES 
let event = EventBuilder::new()
    .caller(api::caller())
    .key(event_key)
    .values(vec![
        (String::from("sub_key"), EventValue::Text("hello ices!".to_owned()), Indexed::Indexed)
    ])
    .build()
    .unwrap();

let ices_builder = ICESBuilder::new()
    .event(event)
    .build()
    .unwrap();

let _call_result = ices_sdk::emit(ices_builder).await;

match _call_result {
    Ok(r) => {
        ic_cdk::println!("{:?}",r);
        true
    },
    Err(msg) => {
        ic_cdk::println!("msg:{}", msg);
        false
    }
}
  • Emit Transations Event logs to ICES 
let transaction  = Transaction {
    from: from.to_string(),
    to: to.to_string(),
    amount,
};
let event = EventBuilder::new()
    .caller(ic_cdk::caller())
    .key(String::from("Transaction"))
    .values(vec![
        (String::from("sub_key"),EventValue::Transaction(transaction), Indexed::Indexed)
    ])
    .build()
    .unwrap();

let ices_builder = ICESBuilder::new()
    .event(event)
    .build()
    .unwrap();

let _call_result = ices_sdk::emit(ices_builder).await;

match _call_result {
    Ok(r) => {
        ic_cdk::println!("{:?}",r);
        true
    },
    Err(msg) => {
        ic_cdk::println!("msg:{}", msg);
        false
    }
}

Aboout ICES Event values

  • Event values is a tuple array, the first element of the Tuple is a custom subKey type Text, the second element is subValue type enum EventValue, and the third element is an enum Indexed, which is stored in the canister as a search index
  • You can find the type definitions at ICES SDK
#[derive(CandidType,Deserialize, Clone, Debug)]
pub struct Transaction  {
    pub from: String,
    pub to: String,
    pub amount: Nat,
}

#[derive(CandidType, Deserialize, Clone, Debug)]
pub struct Event {
    /// The timestamp 
    pub time: Int,
    /// The caller that initiated the call on the token contract.
    pub caller: Principal,
    /// The key that took place.
    pub key: String,
    /// Details of the event.
    pub values: Vec<(String, EventValue, Indexed)>,
}


#[derive(Default, CandidType, Deserialize, Clone, Debug)]
pub struct EventBuilder {
    /// The caller that initiated the call on the token contract.
    pub caller: Option<Principal>,
    /// The key that took place.
    pub key: Option<String>,
    /// Details of the event.
    pub values: Vec<(String, EventValue, Indexed)>,
}


#[derive(CandidType, Serialize, Deserialize, Clone, Debug)]
pub enum Indexed {
    Indexed,
    Not,
}

#[derive(CandidType, Deserialize, Clone, Debug)]
pub enum EventValue {
    I64(i64),
    U64(u64),
    Vec(Vec<EventValue>),
    #[serde(with = "serde_bytes")]
    Slice(Vec<u8>),
    Text(String),
    True,
    False,  
    Float(f64),
    Principal(Principal),
    Transaction(Transaction),
}

tip

This is the example repository