Crate ic_cdk

source ·
Expand description

Documentation Crates.io License Downloads CI

§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.

§Export Candid definitions

Check Generating Candid files for Rust canisters for more details.

§More examples

§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§

  • System API and low level functions for it.
  • Tools for managing stable storage of data in a canister.

Macros§

  • Format and then print the formatted message
  • Create a get_candid_pointer method so that dfx can execute it to extract candid definition.
  • Format and then print the formatted message

Functions§

  • block_onDeprecated
    See documentation for spawn.
  • Performs an asynchronous call to another canister.
  • Returns the caller of the current call.
  • Returns the canister id as a blob.
  • Like notify_with_payment128, but sets the payment to zero.
  • Prints the given message.
  • Setup the stdlib hooks.
  • Spawn an asynchronous task that drives the provided future to completion.
  • Traps with the given message.

Attribute Macros§

  • Register the canister_heartbeat entry point of a canister.
  • Register the canister_init entry point of a canister.
  • Register the canister_inspect_message entry point of a canister.
  • Register the canister_post_upgrade entry point of a canister.
  • Register the canister_pre_upgrade entry point of a canister.
  • Register a query call entry point.
  • Register an update call entry point.