canic-core

Core orchestration logic for Canic canisters: config handling, ops layer, registries, and IC interface helpers.

Most canister projects should depend on canic (the facade crate) and use:

• canic::build! / canic::build_root! from build.rs to validate/embed canic.toml
• canic::start! / canic::start_root! from lib.rs to wire init/upgrade and export endpoints

canic-core is still published because it holds the underlying building blocks: typed config, auth/policy helpers, storage/view layers, and the workflow and ops internals that power the facade crate.

See ../../README.md for the workspace overview and ../../CONFIG.md for the canic.toml schema.

Architecture

Canic is intentionally layered to keep the boundary surface small and ownership explicit:

• access/ – authorization and guard helpers used by endpoint macros.
• config/ – parse + validate canic.toml into a typed schema.
• storage/ – persisted schemas and stable-memory-backed state.
• view/ – internal read-only projections over storage state.
• ops/ – deterministic services over storage plus approved single-step platform effects.
• domain/ – pure domain and policy logic.
• workflow/ – orchestration, retries, and multi-step behavior over time.

The default flow is: endpoints → workflow → domain/policy → ops → storage.

Module Map

• canic_core::access – common auth and routing checks used by the facade macros.
• canic_core::api – runtime APIs surfaced through canic::api::*.
• canic_core::dto – candid-friendly DTOs for paging, auth, topology, metrics, and RPC.
• canic_core::ids – typed identifiers (CanisterRole, SubnetRole, etc.).
• canic_core::log / canic_core::perf – logging and perf instrumentation helpers.
• canic_core::protocol – protocol constants and runtime service identifiers.

Quick Start (Typical Canister)

Make sure canic is available in both [dependencies] and [build-dependencies], because the build! macros run inside build.rs.

In build.rs:

fn main() {
    canic::build!("../canic.toml");
}

In src/lib.rs:

use canic::prelude::*;
use canic::ids::CanisterRole;

const APP: CanisterRole = CanisterRole::new("app");

canic::start!(APP);

async fn canic_setup() {}
async fn canic_install(_: Option<Vec<u8>>) {}
async fn canic_upgrade() {}