# 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 APIs
- `canic::cdk::*` for curated IC CDK helpers
- `canic::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.
| `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]`.
| `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:
```toml
[package.metadata.canic]
fleet = "demo"
role = "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.