dfinity/icskills

cycles-management

Manage cycles and canister lifecycle.

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/dfinity/icskills --skill cycles-management

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

Cycles & Canister Management

What This Is

Cycles are the computation fuel for canisters on Internet Computer. Every canister operation (execution, storage, messaging) burns cycles. When a canister runs out of cycles, it freezes and is eventually uninstalled -- its code and data are deleted, but its metadata (canister ID, controllers, settings) survives. 1 trillion cycles (1T) costs approximately 1 USD equivalent in ICP (the exact rate is set by the NNS and fluctuates with ICP price via the CMC).

Note: icp-cli uses the cycles ledger (um5iw-rqaaa-aaaaq-qaaba-cai) by default. The cycles ledger is a single canister that tracks cycle balances for all principals, similar to a token ledger. Commands like icp cycles balance, icp cycles mint, and icp canister top-up go through the cycles ledger. There is no legacy wallet concept in icp-cli. The programmatic patterns below (accepting cycles, creating canisters via management canister) remain the same regardless of which funding mechanism is used.

Prerequisites

  • For Motoko: mops package manager, core = "2.0.0" in mops.toml
  • For Rust: ic-cdk >= 0.19

Canister IDs

ServiceCanister IDPurpose
Cycles Minting Canister (CMC)rkp4c-7iaaa-aaaaa-aaaca-caiConverts ICP to cycles, creates canisters
Cycles Ledgerum5iw-rqaaa-aaaaq-qaaba-caiTracks cycle balances for all principals
Management Canisteraaaaa-aaCanister lifecycle (create, install, stop, delete, status)

The Management Canister (aaaaa-aa) is a virtual canister -- it does not exist on a specific subnet but is handled by every subnet's execution layer.

Mistakes That Break Your Build

  1. Running out of cycles silently freezes the canister -- There is no warning. A frozen canister stops executing messages but keeps paying rent for its memory and allocations, so the balance continues to drain. When it reaches zero the canister is uninstalled: code and data are gone permanently, and only the metadata (canister ID, controllers, settings) remains. Set a freezing threshold and monitor balances.
  1. Not setting freezing_threshold -- Default is 30 days. If your canister burns cycles fast (high traffic, large stable memory), 30 days may not be enough warning. Set it higher for production canisters. The freezing threshold defines how many seconds worth of idle cycles the canister must retain before it freezes.
  1. Confusing local vs mainnet cycles -- Local replicas give canisters virtually unlimited cycles. Code that works locally may fail on mainnet because the canister has insufficient cycles. Always test with realistic cycle amounts before mainnet deployment.
  1. Sending cycles to the wrong canister -- Cycles sent to a canister cannot be retrieved. There is no refund mechanism for cycles transferred to the wrong principal. Double-check the canister ID before topping up.
  1. Forgetting to set the canister controller -- If you lose the controller identity, you permanently lose the ability to upgrade, top up, or manage the canister. Always add a backup controller. Use icp canister settings update --add-controller PRINCIPAL to add one.
  1. Using ExperimentalCycles in mo:core -- In mo:core 2.0, the module is renamed to Cycles. import ExperimentalCycles "mo:base/ExperimentalCycles" will fail. Use import Cycles "mo:core/Cycles".
  1. Using `icp cycles transfer` to fund a canister -- icp cycles transfer <amount> <principal> moves cycles between cycles-ledger balances, the same as a token transfer between accounts. Passing a canister's principal as the recipient credits that principal's cycles-ledger balance, not the canister's actual execution/compute cycle balance -- icp canister status will not show the cycles as received, and the canister keeps burning down its real balance toward freezing with no indication anything went wrong. Use icp canister top-up <canister> --amount <N> -e ic instead, which deposits cycles directly onto the canister via the management canister. See "Top Up a Canister" below for both commands side by side.
  1. Using `-n ic` on a command that names a canister -- -n/--network and -e/--environment are different selectors and conflict with each other; passing both is an error. A canister name can only be resolved through an environment, so -n fails on it:
bash
   icp canister status backend -n ic
   # Error: Specifying a network is not supported if you are targeting a canister
   # by name, specify an environment instead

So -e ic for anything naming a canister (top-up, status, settings update, create), and -n ic for commands that take a principal or no canister at all (cycles mint, cycles balance, cycles transfer). This is why the mainnet examples below mix the two flags. Load icp-cli for the full flag rules.

Implementation

Motoko

Checking and Accepting Cycles

motoko
import Cycles "mo:core/Cycles";
import Principal "mo:core/Principal";
import Runtime "mo:core/Runtime";

persistent actor {

  // Check this canister's cycle balance
  public query func getBalance() : async Nat {
    Cycles.balance()
  };

  // Accept cycles sent with a call (for "tip jar" or payment patterns)
  public func deposit() : async Nat {
    let available = Cycles.available();
    if (available == 0) {
      Runtime.trap("No cycles sent with this call")
    };
    let accepted = Cycles.accept<system>(available);
    accepted
  };

  // Send cycles to another canister via inter-canister call
  public func topUpCanister(target : Principal) : async () {
    let targetActor = actor (Principal.toText(target)) : actor {
      deposit_cycles : shared () -> async ();
    };
    // Attach 1T cycles to the call
    await (with cycles = 1_000_000_000_000) targetActor.deposit_cycles();
  };
}

Creating a Canister Programmatically

motoko
import Principal "mo:core/Principal";

persistent actor Self {

  type CanisterId = { canister_id : Principal };

  type CreateCanisterSettings = {
    controllers : ?[Principal];
    compute_allocation : ?Nat;
    memory_allocation : ?Nat;
    freezing_threshold : ?Nat;
  };

  // Management canister interface
  let ic = actor ("aaaaa-aa") : actor {
    create_canister : shared { settings : ?CreateCanisterSettings } ->
      async CanisterId;
    canister_status : shared { canister_id : Principal } ->
      async {
        status : { #running; #stopping; #stopped };
        memory_size : Nat;
        cycles : Nat;
        settings : CreateCanisterSettings;
        module_hash : ?Blob;
      };
    deposit_cycles : shared { canister_id : Principal } -> async ();
    stop_canister : shared { canister_id : Principal } -> async ();
    delete_canister : shared { canister_id : Principal } -> async ();
  };

  // Create a new canister with 1T cycles
  public func createNewCanister() : async Principal {
    let result = await (with cycles = 1_000_000_000_000) ic.create_canister({
      settings = ?{
        controllers = ?[Principal.fromActor(Self)];
        compute_allocation = null;
        memory_allocation = null;
        freezing_threshold = ?2_592_000; // 30 days in seconds
      };
    });
    result.canister_id
  };

  // Check a canister's status and cycle balance
  public func checkStatus(canisterId : Principal) : async Nat {
    let status = await ic.canister_status({ canister_id = canisterId });
    status.cycles
  };

  // Top up another canister
  public func topUp(canisterId : Principal, amount : Nat) : async () {
    await (with cycles = amount) ic.deposit_cycles({ canister_id = canisterId });
  };
}

Rust

Checking Balance and Accepting Cycles

rust
use ic_cdk::{query, update};
use candid::Nat;

#[query]
fn get_balance() -> Nat {
    Nat::from(ic_cdk::api::canister_cycle_balance())
}

#[update]
fn deposit() -> Nat {
    let available = ic_cdk::api::msg_cycles_available();
    if available == 0 {
        ic_cdk::trap("No cycles sent with this call");
    }
    let accepted = ic_cdk::api::msg_cycles_accept(available);
    Nat::from(accepted)
}

Creating and Managing Canisters

rust
use candid::{Nat, Principal};
use ic_cdk::update;
use ic_cdk::management_canister::{
    create_canister_with_extra_cycles, canister_status, deposit_cycles, stop_canister, delete_canister,
    CreateCanisterArgs, CanisterStatusArgs, DepositCyclesArgs, StopCanisterArgs, DeleteCanisterArgs,
    CanisterSettings, CanisterStatusResult,
};

#[update]
async fn create_new_canister() -> Principal {
    let caller = ic_cdk::api::canister_self(); // capture canister's own principal
    let user = ic_cdk::api::msg_caller(); // capture caller before await

    let settings = CanisterSettings {
        controllers: Some(vec![caller, user]),
        compute_allocation: None,
        memory_allocation: None,
        freezing_threshold: Some(Nat::from(2_592_000u64)), // 30 days
        reserved_cycles_limit: None,
        log_visibility: None,
        wasm_memory_limit: None,
        wasm_memory_threshold: None,
        environment_variables: None,
    };

    let arg = CreateCanisterArgs {
        settings: Some(settings),
    };

    // Send 1T cycles with the create call
    let result = create_canister_with_extra_cycles(&arg, 1_000_000_000_000u128)
        .await
        .expect("Failed to create canister");

    result.canister_id
}

#[update]
async fn check_status(canister_id: Principal) -> CanisterStatusResult {
    canister_status(&CanisterStatusArgs { canister_id })
        .await
        .expect("Failed to get canister status")
}

#[update]
async fn top_up(canister_id: Principal, amount: u128) {
    deposit_cycles(&DepositCyclesArgs { canister_id }, amount)
        .await
        .expect("Failed to deposit cycles");
}

#[update]
async fn stop_and_delete(canister_id: Principal) {
    stop_canister(&StopCanisterArgs { canister_id })
        .await
        .expect("Failed to stop canister");

    delete_canister(&DeleteCanisterArgs { canister_id })
        .await
        .expect("Failed to delete canister");
}

Deploy & Test

Check Cycle Balance

bash
# Check your canister's cycle balance
icp canister status backend
# Look for "Balance:" line in output

# Check balance on mainnet
icp canister status backend -e ic

# Check any canister by ID
icp canister status ryjl3-tyaaa-aaaaa-aaaba-cai -e ic

Top Up a Canister

bash
# Top up with cycles from the cycles ledger (local)
icp canister top-up backend --amount 1000000000000
# Adds 1T cycles to the backend canister

# Top up on mainnet
icp canister top-up backend --amount 1000000000000 -e ic

# Convert ICP to cycles and top up in one step (mainnet)
icp cycles mint --icp 1.0 -n ic   # no canister argument, so -n is fine (see Pitfall 8)

# No ICP to convert? Buy cycles with a card for the identity instead (load the `buy-cycles` skill)
icp cycles buy --amount 10 -n ic
icp canister top-up backend --amount 1000000000000 -e ic
bash
# CORRECT -- funds the canister's execution balance:
icp canister top-up backend --amount 600b -e ic

# WRONG -- sends to the recipient's cycles-ledger balance, canister cannot use it:
icp cycles transfer 600000000000 <canister-principal> -n ic

--amount on icp canister top-up accepts k/m/b/t suffixes (thousand/million/billion/trillion).

Create a Canister via icp

bash
# Create an empty canister (local)
icp canister create my_canister

# Create on mainnet with specific cycles
icp canister create my_canister -e ic --cycles 2000000000000

# Add a backup controller
icp canister settings update my_canister --add-controller BACKUP_PRINCIPAL_HERE

Each creation takes --cycles (default 2T) plus the cycles ledger's 100M fee out of the identity's balance. Before icp deploy -e ic creates several canisters at once, estimate N × (2T + 100M), compare with icp cycles balance -n ic, and close any gap before deploying -- icp cycles mint --cycles <gap> -n ic with ICP, icp cycles buy --cycles <gap> -n ic with a card. The icp-cli skill's "Funding an identity for mainnet" section has the steps.

Set Freezing Threshold

bash
# Set freezing threshold to 90 days (in seconds: 90 * 24 * 60 * 60 = 7776000)
icp canister settings update backend --freezing-threshold 7776000

# Mainnet
icp canister settings update backend --freezing-threshold 7776000 -e ic

Verify It Works

bash
# Deploy and check status
icp network start -d
icp deploy backend
icp canister status backend
# Expected output includes:
#   Status: Running
#   Balance: 3_100_000_000_000 Cycles (local default, varies)
#   Freezing threshold: 2_592_000

# Check balance programmatically (if you added getBalance)
icp canister call backend getBalance '()'
# Expected: a large nat value, e.g. (3_100_000_000_000 : nat)

# On mainnet: verify cycles balance is not zero
icp canister status backend -e ic
# If Balance shows 0, the canister will freeze. Top up immediately.
du même dépôt

Autres Skills

Tous les Skills
dfinity
Communauté

autoupgrade-icp-cli

One-time installer that keeps a project's Internet Computer CLI toolchain current. Sets up a SessionStart hook plus a script that compares the installed icp and ic-wasm against the latest release and either reports the upgrade or applies it, using whichever channel each tool was installed from (npm, Homebrew, or the shell installer). Use when a user wants to install, bootstrap, or enable automatic icp-cli / ic-wasm updates, asks to stop running an outdated icp, asks how to upgrade or check the v

Installations / 1h
1
GitHub Stars
39
Mis à jour
11 nov.
dfinity
Communauté

buy-cycles

Buy cycles with a credit card for the CLI's own identity with icp cycles buy, through CyclePay's on-chain gateway, then continue deploying. Use when a mainnet deploy or canister creation fails for lack of cycles, the user has no ICP, no wallet or no exchange account, or asks to pay for cycles by card, Stripe, fiat or USD. Do NOT use for converting ICP you already hold (cycles-management: icp cycles mint), for topping up a canister from an existing balance, or for Internet Identity sign-in (agent

Installations / 1h
1
GitHub Stars
39
Mis à jour
11 nov.
dfinity
Communauté

canhelp

Display a human-readable summary of a canister's interface given its mainnet canister ID or a human-readable name. Like --help but for canisters. Only for mainnet canisters — for local canisters, read the generated .did file in your project directly.

Installations / 1h
1
GitHub Stars
39
Mis à jour
11 nov.
dfinity
Communauté

canister-security

IC-specific security patterns for canister development in Motoko and Rust. Covers access control, anonymous principal rejection, reentrancy prevention (CallerGuard pattern), async safety (saga pattern), callback trap handling, cycle drain protection, and safe upgrade patterns. Use when writing or modifying any canister that modifies state, handles tokens, makes inter-canister calls, or implements access control.

Installations / 1h
1
GitHub Stars
39
Mis à jour
11 nov.