canic
Facade crate that re-exports the main Canic stack for canister projects:
- endpoint and lifecycle macros
- core runtime/types
- curated IC CDK helpers
- 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 APIscanic::cdk::*for curated IC CDK helperscanic::memory::*for stable-memory helpers and macros
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.
| Feature | Default | Enables |
|---|---|---|
metrics |
Yes | The standard canic_metrics endpoint bundle. |
control-plane |
No | Root control-plane bootstrap and Wasm publication APIs; also enables wasm-store-canister. |
wasm-store-canister |
No | The canonical wasm_store canister API used by generated/bootstrap store packages. Ordinary application roles should not enable it. |
icp-refill |
No | ICP-to-cycles refill runtime APIs and generated endpoint support. |
blob-storage |
No | Non-billing blob-storage status and gateway-administration runtime APIs/endpoints. |
blob-storage-billing |
No | Cashier-backed blob-storage billing, funding, and readiness support; also enables blob-storage. |
sharding |
No | Sharding placement, storage, metrics, and lifecycle support from canic-core. |
auth-chain-key-ecdsa |
No | Chain-key ECDSA validation and cryptographic support used by delegated-auth proof flows. |
auth-chain-key-root-sign |
No | Root-managed chain-key delegation-batch signing; also enables auth-chain-key-ecdsa. |
auth-root-canister-sig-create |
No | Root canister-signature proof creation for role attestation. |
auth-root-canister-sig-verify |
No | Root canister-signature proof verification for role attestation. |
auth-issuer-canister-sig-create |
No | Issuer canister-signature token-proof creation. |
auth-issuer-canister-sig-verify |
No | Issuer canister-signature token-proof verification. |
auth-delegated-token-verify |
No | Delegated-token verification, including required chain-key and issuer-signature verification support. |
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].
| Config setting | Role crate that needs the feature | Required runtime canic feature |
|---|---|---|
auth.role_attestation_cache = true on a non-root canister |
that non-root role | auth-root-canister-sig-verify |
any non-root role uses auth.role_attestation_cache = true |
root role | auth-root-canister-sig-create |
auth.delegated_token_issuer = true |
that issuer role | auth-issuer-canister-sig-create, auth-delegated-token-verify |
auth.delegated_token_verifier = true |
that verifier role | auth-delegated-token-verify |
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:
[]
= "demo"
= "app"
Use canic::build!("../canic.toml") from build.rs and canic::start!() from
lib.rs. The fleet value must match [fleet] 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.
This crate lives in the Canic workspace. See the workspace guide at
../../README.md for full setup, topology, and example canisters.