ic-cdk

Canister Developer Kit for the Internet Computer.

Background

On the Internet Computer, smart contracts come in the form of canisters which are WebAssembly modules.

Canisters expose entry points which can be called both by other canisters and by parties external to the IC.

This library aims to provide a Rust-ergonomic abstraction to implement Canister entry points.

Getting Started

In Cargo.toml:

[lib]
crate-type = ["cdylib"]

[dependencies]
ic-cdk = "0.18"
candid = "0.10" # required if you want to define Candid data types

Then in Rust source code:

#[ic_cdk::query]
fn hello() -> String {
    "world".to_string()
}

This will register a query entry point named hello.

Compilation

Stable Target: wasm32-unknown-unknown

cargo build --target wasm32-unknown-unknown

Experimental Target: wasm64-unknown-unknown

No changes to the source code are required. However, setting up the Rust toolchain for Wasm64 support requires some additional steps.

1. Install nightly toolchain:

rustup toolchain install nightly

2. Add rust-src component:

rustup component add rust-src --toolchain nightly

3. Build with necessary flags:

cargo +nightly build -Z build-std=std,panic_abort --target wasm64-unknown-unknown

Macros

This library re-exports macros defined in ic-cdk-macros crate.

The macros fall into two categories:

• To register functions as canister entry points
• To export Candid definitions

Register functions as canister entry points

These macros are directly related to the Internet Computer Specification.

• init
• pre_upgrade
• post_upgrade
• inspect_message
• heartbeat
• on_low_wasm_memory
• update
• query

Canister entry points can be async. The CDK embeds an asynchronous executor. Unfortunately anything tokio-specific cannot be used. Use the spawn function to run more asynchronous functions in the background. Panics can cause async tasks to cancel partway through; read the documentation for the futures module for more information.

Export Candid definitions

• export_candid

Check Generating Candid files for Rust canisters for more details.

More examples

The examples repository offers numerous Rust examples demonstrating how to build functional Rust canisters.

Manage Data Structures in Stable Memory

For managing larger datasets and multiple data structures in stable memory, consider using the ic-stable-structures crate. While the ic_cdk::storage::{stable_save, stable_restore} API is straightforward, it may not be efficient for larger datasets. The ic-stable-structures crate provides more scalable solutions for such scenarios.