Multi Canister

If you're building on the Internet Computer and need to split your app across multiple canisters, this covers the architecture patterns and gotchas that matter. It walks through inter-canister calls, the 2MB payload limit, why update methods aren't atomic across awaits, and how to avoid reentrancy bugs. The guidance on bounded versus unbounded waits and cross-subnet latency is solid. This is written for engineers who already understand single-canister apps and need to scale up or separate concerns. The pitfall list is thorough, especially around idempotent APIs and defensive caller binding in Rust. Skip this if your app fits in one canister.

skills.sh installs: 300
GitHub stars: 39
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add dfinity/icskills --skill multi-canister --agent claude-code

Installs into .claude/skills of the current project.

Files

Multi-Canister Architecture

What This Is

Splitting an IC application across multiple canisters for scaling, separation of concerns, or independent upgrade cycles. Each canister has its own state, cycle balance, and upgrade path. Canisters communicate via async inter-canister calls.

Prerequisites

For Motoko: mops package manager, core = "2.1.0" in mops.toml — Runtime.envVar, used below to discover a sibling canister's ID, was added in motoko-core 2.1.0
For Rust: ic-cdk >= 0.19, candid, serde, ic-stable-structures

How It Works

A caller canister makes a call to a callee canister: the method name, arguments (payload) and attached cycles are packed into a canister request message, which is delivered to the callee after the caller blocks on await; the callee executes the request and produces a response; this is packed into a canister response message and delivered to the caller; the caller awakes fron the await and continues execution (executes the canister response message). The system may produce a reject response message if e.g. the callee is not found or some resource limit was reached.

SKILL.md on GitHub