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.