Crate ic_cdk

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.

Using ic-cdk

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.

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.

Modules

api

System API bindings.

bitcoin_canister

This module provides functionality for making inter-canister calls to the Bitcoin canisters.

call

Inter-canister Call API

futures

Functions relating to the async executor.

management_canister

Functions and types for interacting with the IC management canister.

stable

APIs to manage stable memory.

storage

Tools for managing stable storage of data in a canister.

Macros

eprintln

Format and then print the formatted message

export_candid

Create a get_candid_pointer method so that dfx can execute it to extract candid definition.

println

Format and then print the formatted message

Functions

callDeprecated

Performs an asynchronous call to another canister.

callerDeprecated

Returns the caller of the current call.

idDeprecated

Returns the canister id as a blob.

notifyDeprecated

Like notify_with_payment128, but sets the payment to zero.

printDeprecated

Prints the given message.

trap

Traps with the given message.

Attribute Macros

heartbeat

Register the canister_heartbeat entry point of a canister.

init

Register the canister_init entry point of a canister.

inspect_message

Register the canister_inspect_message entry point of a canister.

on_low_wasm_memory

Register the canister_on_low_wasm_memory entry point of a canister.

post_upgrade

Register the canister_post_upgrade entry point of a canister.

pre_upgrade

Register the canister_pre_upgrade entry point of a canister.

query

Register a query call entry point.

update

Register an update call entry point.