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.12"
# Only necessary if you want to define Candid data types
candid = "0.10" 

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
• update
• query

Export Candid definitions

• export_candid

Check Generating Candid files for Rust canisters for more details.

More examples

• Basic examples: Demonstrate usage of ic-cdk API.
• Comprehensive examples: Illustrate how to build useful Rust canisters.

Manage Data Structure in Stable Memory

Using the ic_cdk::storage::{stable_save, stable_restore} API is easy but it doesn’t scale well.

ic-stable-structures is recommended when you are dealing with multiple data structures with larger datasets.

Modules

api

System API and low level functions for it.

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

block_onDeprecated

See documentation for spawn.

call

Performs an asynchronous call to another canister.

caller

Returns the caller of the current call.

id

Returns the canister id as a blob.

notify

Like notify_with_payment128, but sets the payment to zero.

print

Prints the given message.

setup

Setup the stdlib hooks.

spawn

Spawn an asynchronous task that drives the provided future to completion.

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.

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.