canic

Facade crate that re-exports the main Canic stack for canister projects:

• endpoint and lifecycle macros
• core runtime/types
• stable-memory helpers under canic::memory

Most downstream canister projects should start here instead of reaching for lower-level crates directly.

Use the explicit module paths for the larger bundled surfaces:

• canic::api::* for runtime APIs
• canic::dto::* for public wire and value types
• canic::memory::* for stable-memory helpers and macros

Crate Boundary

Use canic only from configured canister role packages. Each role package must declare its own direct, normal runtime dependency on canic.

Shared runtime libraries must not depend on canic. Keep their domain logic framework-independent; role packages and IC adapters depend directly on upstream crates such as candid, ic-cdk, or ic-stable-structures for generic IC types and APIs. This keeps every role package's runtime graph to one direct path to Canic.

Feature Contract

The default feature set contains only metrics. Disable default features when you need a narrower facade dependency, then select every runtime capability required by the role.

The control-plane feature is the normal root-role selection. The narrower wasm-store-canister feature exists for the canonical store canister package; it is not an alternate root control-plane configuration.

Config-Driven Auth Features

Some canic.toml auth settings require matching runtime canic features in the role crate's [dependencies]. Add these to the runtime dependency, not only [build-dependencies].

Run canic medic project --ci for concise fail-only diagnostics, or canic medic project --json for automation-friendly check rows such as role_required_canic_feature_missing.

Typical Use

Use canic in both [dependencies] and [build-dependencies] so the build macros and runtime macros come from the same facade crate.

Each canister crate declares its role in package metadata:

[package.metadata.canic]
app = "demo"
role = "app"

Use canic::build!("../canic.toml") from build.rs and canic::start!() from lib.rs. The app value must match [app].name in the selected canic.toml. role = "root" selects the root lifecycle and root endpoint bundle; ordinary roles select the non-root lifecycle and endpoint bundle.

Inter-Canister Calls

Use the Canic call builder when application code benefits from concise Candid encoding, typed public errors, and Canic's inter-canister call metrics:

use candid::Principal;
use canic::prelude::Call;

async fn read_count(target: Principal) -> Result<u64, canic::Error> {
    Call::bounded_wait(target, "read_count")
        .execute_candid()
        .await
}

Call::unbounded_wait is also available, as are with_arg, with_args, with_raw_args, with_cycles, and execute_candid_tuple. Use execute directly when the response must be retained or decoded later. This is an ordinary IC call builder; it does not replace Canic's protected capability RPC used for framework-owned creation, upgrade, placement, recycling, or cycle operations.

Application Timers

timer! schedules one asynchronous invocation. timer_interval! schedules the next invocation only after the current future completes, so interval work cannot overlap itself. Both return an opaque, single-owner handle:

use canic::prelude::*;
use std::time::Duration;

let handle = timer_interval!(Duration::from_secs(30), refresh_cache);
assert!(canic::api::timer::cancel(handle));

Cancellation consumes the handle. A pending invocation is cleared; a running invocation is allowed to finish but cannot rearm. Guarded timer macros and raw CDK timer access are not part of the maintained facade.

This crate lives in the Canic workspace. See the workspace guide at ../../README.md for full setup, topology, and example canisters.