docs: cycles management guide

[marc0olo]

Summary

• ICP → cycles conversion via the CMC using icp cycles mint
• Checking balances with icp cycles balance and icp canister status
• Topping up canisters with icp canister top-up
• Accepting and sending cycles programmatically (Motoko mo:core/Cycles, Rust ic_cdk)
• Freezing threshold configuration (CLI and icp.yaml)
• Multi-environment deployment with staging/production icp.yaml
• Automated monitoring (CycleOps, canfund)
• Programmatic canister creation with cycles

Note: page uses .mdx for language-synced Motoko/Rust tabs.

Sync recommendation

informed by dfinity/portal, dfinity/icp-cli, dfinity/icskills — skills/cycles-management/SKILL.md

[marc0olo]

Review: Cycles Management

Must fix

• Internal links use .mdx extension instead of .md: Three links violate the project rule "Always use .md extension in internal links, even when linking to a .mdx file":

  • Line 223: [Canister settings](settings.mdx) → should be [Canister settings](settings.md)
  • Line 424: [Canister settings](settings.mdx) → should be [Canister settings](settings.md)
  • Line 425: [Canister lifecycle](lifecycle.mdx) → should be [Canister lifecycle](lifecycle.md)

  Astro resolves .md links to .mdx files automatically. Using .mdx in links may break on GitHub previews and violates the content authoring rules.

Suggestions

• XDR pricing caveat: The page states "roughly 1.3 USD as of 2025". Since XDR rates fluctuate, consider adding a note pointing readers to the NNS or current rate source, or softening the claim to "roughly 1–2 USD" without a year anchor. (Minor — the portal source uses the same phrasing, so this is consistent with the source material.)

• icp canister top-up argument order: In two places the page uses icp canister top-up ryjl3-tyaaa-aaaaa-aaaba-cai --amount 1T -n ic, placing the canister principal before --amount. The documented usage form is icp canister top-up [OPTIONS] --amount <AMOUNT> <CANISTER> (CANISTER last). clap parsers typically accept any order, so this is not a hard error, but aligning with the documented form would be more consistent: icp canister top-up --amount 1T ryjl3-tyaaa-aaaaa-aaaba-cai -n ic.

• Programmatic section title is slightly misleading: The section "Setting a freezing threshold programmatically" shows two functions: createWithThreshold (create a canister with a threshold) and topUp (top up another canister). The section title implies it only covers reading/setting the threshold. Consider renaming to "Creating and funding canisters programmatically" since both operations are shown and are valuable.

Verified

• All internal link targets exist: reverse-gas-model.md, cycles-costs.md, settings.mdx (resolves via .mdx), lifecycle.mdx (resolves via .mdx), reproducible-builds.md, canister-upgrades.md — all confirmed with ls.
• All icp CLI commands verified against .sources/icp-cli/docs/reference/cli.md:
  • icp identity new, icp identity default, icp identity principal, icp identity account-id ✓
  • icp token balance -n ic ✓
  • icp cycles mint --icp 5 -n ic and --cycles 5T -n ic ✓
  • icp cycles balance -n ic ✓
  • icp canister status backend -e ic, icp canister status ryjl3... -n ic, icp canister status -e ic (optional CANISTER arg) ✓
  • icp canister top-up backend --amount 1T -e ic ✓
  • icp canister settings update backend --freezing-threshold 7776000 -e ic ✓
  • icp canister settings update backend --add-controller BACKUP_PRINCIPAL -e ic ✓
  • icp deploy -e staging and icp deploy -e production ✓
• No dfx references found.
• Frontmatter complete (title, description, sidebar order) and consistent with body.
• File is .mdx with import { Tabs, TabItem } — justified by Motoko/Rust tab components throughout.
• Motoko code verified against .sources/motoko-core/src/Cycles.mo and Runtime.mo: Cycles.balance(), Cycles.available(), Cycles.accept<system>(available), Runtime.trap(...), Principal.fromActor(Self) all correct.
• Rust code verified against .sources/cdk-rs/ic-cdk/src/api.rs and management_canister.rs: canister_cycle_balance() returns u128 ✓, msg_cycles_available() returns u128 ✓, msg_cycles_accept(u128) returns u128 ✓. All imports from ic_cdk::management_canister (create_canister_with_extra_cycles, deposit_cycles, CreateCanisterArgs, DepositCyclesArgs, CanisterSettings) are publicly exported ✓. All CanisterSettings fields used in the snippet exist in the struct ✓.
• icp.yaml freezing_threshold: 30d and 90d duration syntax verified against .sources/icp-cli/docs/reference/canister-settings.md ✓.
• icp.yaml environment_variables map syntax verified ✓.
• XDR pricing claim ("1T ≈ 1 XDR ≈ 1.3 USD as of 2025") cross-checked against .sources/portal/docs/building-apps/getting-started/tokens-and-cycles.mdx ✓.
• Page structure follows orient → explain → instruct → next steps ✓.
• ## Next steps section present ✓.
• {/* Upstream: */} comment present at end of file in correct JSX format for .mdx ✓.
• No <\!-- TODO: verify output --> or <\!-- Needs human verification --> flags.
• No links to internetcomputer.org/docs/ or docs.internetcomputer.org ✓.
• External links (https://cli.internetcomputer.org/, third-party monitoring services, GitHub library links) appear correct ✓.

[marc0olo]

Feedback addressed:

• Fixed all 4 internal links using .mdx extension → .md (settings.mdx × 3, lifecycle.mdx × 1)
• Fixed icp canister top-up argument order to match documented form: --amount <AMOUNT> <CANISTER> (verified against icp-cli reference)
• Renamed section "Setting a freezing threshold programmatically" → "Creating and funding canisters programmatically" to accurately reflect both the canister creation and top-up examples it contains