psychedelic / ic-kit Goto Github PK

Rust library for developing safe canisters.

Rust 100.00%

ic internet-computer testing cdk api-bindings

ic-kit's Introduction

IC Kit

This library provides an alternative to ic-cdk that can help developers write canisters and unit test them in their Rust code.

Blog post: IC Kit: Rust Canister Testing Kit we Used to Improve Code Coverage at Fleek

THIS IS ALPHA SOFTWARE

IC-Kit v0.5 is still alpha and a developer preview. we're working towards making sure it's feature complete, and advise you to not use it in any sensitive canister before it comes out of the alpha.

Install

Add this to your Cargo.toml

[dependencies]
ic-kit = "0.5.0-alpha.6"
candid = "0.8"

Example Usage

See the examples directory.

What's different?

IC-Kit 0.5 is breaking drop-in replacement guarantee of the CDK, which allows us to go one step further in improving canister development experience.

Note: The kit includes a breaking change to the Principal type. The kit is upgraded to candid 0.8 and ic_types 0.6, where Principal lives directly in the candid crate.

Fully Simulated Replica

Now we have a #[kit_test] macro which gives you access to a replica simulator that you can use for testing your canister.

use ic_kit::prelude::*;

#[kit_test]
async fn test(replica: Replica) {
    // let handle = replica.add_canister(Canister::anonymous());
}

Inspect Message

It makes it easier to use the inspect_message feature of the Interest Computer, your function only needs to return a bool and we take care of the rest.

use ic_kit::prelude::*;

#[inspect_message]
fn inspect_message() -> bool {
    // Only accept ingress message calls which have a payload
    // smaller than 1000 bytes.
    ic_kit::arg_data_size::arg_data_size() <= 1000
}

Secure Memory Helpers

No need to use thread_local! to get rid of the get_mut anymore, we have deprecated get[/_mut method and now have with variation.

let count = with(|counter: &Counter| {
    *counter.get()
});

let count = with_mut(|counter: &mut Counter| {
    *counter.get()
});

Dependency Injection

Now your sync (non-async) methods can be simplified, we wrap them in the appropriate with and with_mut methods for you so you don't have to think about it.

use ic_kit::prelude::*;
use std::collections::HashMap;

#[derive(Default)]
struct Registry {
    names: HashMap<Principal, String>,
}

#[update]
fn register(registry: &mut Registry, name: String) {
    registry.names.insert(caller(), name);
}

#[query]
fn get_name(registry: &Registry, user: Principal) -> Option<&String> {
    registry.names.get(&user)
}

Native Macros

Now we no longer rely on the ic-cdk-macros allowing us to host our version of macros and innovate even more.

Importable Canisters

The KitCanister derive macro allows you to export a canister to be imported from other canisters.

Easy Auto Candid Generation

#[derive(KitCanister)]
#[candid_path("candid.did")]
pub struct NamingSystemCanister;

ic-kit's People

Contributors

Stargazers

Watchers

Forkers

deland-labs myse1f awkure bitfinity-network ozwaldorf qti3e saikatdas0790 sshyran cryptchef giiiiiiiib sonicdex

ic-kit's Issues

What is the motivation for this library?

I see that there is something interesting with cycles going on, but I can't quite put my finger on it. Could you elaborate on it, please?

How to mock canister with existing method?

Hi. Amazing library! Can you please provide some insight on how to mock a canister with existing methods.

Say, I have a method

#[update]
async fn do_nothing(my_arg: u64) -> Result<(), String> {
    Ok(())
}

How would I create a Canister mock with the method above? I've tried to use RawHandler, but cannot figure out how to transfer arguments correctly.

The way I want to use it later is like so:

let canister = Canister::new(mock_principals::alice())
    .method("do_nothing", ...);

let ctx = canister.context().inject();
ic::call_with_payment(mock_principals::alice(), "do_nothing", (1000), 100);

Is it even possible with the current implementation?

Compitable with ic_cdk 0.4.0

I found that ic_cdk 0.4.0 deprecate block_on function and use its own spawn.

ic_kit use ic_cdk::block_on to do the job of ic::spwan.

Besides, ic_cdk::spawn doesn't need Send trait bound to the future F while ic_kit does.

#[inline(always)]
pub fn spawn<F: 'static + std::future::Future<Output = ()> + std::marker::Send>(future: F) {
    get_context().spawn(future)
}

When I have a job which call another canister, the future returned does not have Send trait. Thus ic::spawn can not execute the job.

    |
498 |     let xtc_balance: (Nat, ) = ic::call(Principal::from_text(XTC).unwrap(), "balanceOf", (ic::id(),))
    |                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ await occurs here on type `Pin<Box<dyn Future<Output = Result<(ic_kit::candid::Nat,), (RejectionCode, std::string::String)>>>>`, which is not `Send`
note: required by a bound in `ic_kit::ic::spawn`


    |
555 |     ic::spawn(schedule_job());
    |     ^^^^^^^^^ future returned by `schedule_job` is not `Send`
    |

Requesting clarification on the following: Dynamic canister creation, automatic Candid generation, inter canister calls

It would be really helpful if you could document how to do the following with ic-kit:

dynamic canister creation
automatic Candid generation
inter canister calls

as comments in the examples provided and provide any guidance on how to set it up from scratch on a new project.

I was using ic-kit 0.4.8 before. It included calls to the management canister as documented here for the dynamic creations of canisters but that seems to have been removed in v0.5 onwards.

And I had been using the cargo test mechanism of automatic Candid generation as used in some other Psychedelic projects like this

For inter canister calls, I tried the mechanism outlined here but it's not type safe so it breaks compilation with Cargo. I created a post for it here

I feel ic-kit 0.5 would probably solve all of the above but I'm unable to make it work atm.

I see some of the examples have pending todos and I imagine you'll be fleshing them out in more details.

In case you already plan to cover the above, please ignore this issue :)