From cbe018a05c9d3a82d2fb29193b9782659dda5738 Mon Sep 17 00:00:00 2001
From: Marco Walz <marco.walz@dfinity.org>
Date: Thu, 19 Mar 2026 12:50:11 +0100
Subject: [PATCH 1/3] docs: management canister API reference

---
 docs/reference/management-canister.md | 520 +++++++++++++++++++++++++-
 1 file changed, 509 insertions(+), 11 deletions(-)

diff --git a/docs/reference/management-canister.md b/docs/reference/management-canister.md
index 56a09016..19ecc77f 100644
--- a/docs/reference/management-canister.md
+++ b/docs/reference/management-canister.md
@@ -6,17 +6,515 @@ sidebar:
 icskills: []
 ---
 
-TODO: Write content for this page.
+The management canister provides access to system features on the Internet Computer: creating and managing canisters, chain-key signing, HTTPS outcalls, randomness, and Bitcoin integration. It is not a real canister with its own state or Wasm module. It is a virtual canister implemented as part of the IC protocol itself.
 
-<!-- Content Brief -->
-API reference for the IC management canister (aaaaa-aa). Document all methods: create_canister, install_code, update_settings, canister_status, stop_canister, delete_canister, raw_rand, ecdsa_public_key, sign_with_ecdsa, schnorr_public_key, sign_with_schnorr, http_request, provisional_create_canister_with_cycles, etc. Include method signatures, parameters, cycle costs, and usage notes.
+The management canister address is `aaaaa-aa` (the empty blob). It is present on every subnet. When you call `aaaaa-aa`, the IC routes the request to the appropriate subnet transparently.
 
-<!-- Source Material -->
-- Portal: references/ic-interface-spec (management canister section)
-- IC interface specification
+Most methods require the caller to be a **controller** of the target canister. Some methods (such as `raw_rand` and `deposit_cycles`) can only be called by canisters, not by external users. When an external user calls the management canister, the cost is charged to the managed canister.
 
-<!-- Cross-Links -->
-- concepts/canisters -- canister lifecycle
-- guides/canister-management/lifecycle -- practical lifecycle management
-- guides/backends/randomness -- raw_rand usage
-- guides/chain-fusion/bitcoin -- ecdsa/schnorr signing
+For the full formal specification, see the [IC interface specification](ic-interface-spec.md).
+
+## Canister settings
+
+Several methods accept or return a `canister_settings` record. The fields are:
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `controllers` | `vec principal` | Caller only | Up to 10 principals that control the canister |
+| `compute_allocation` | `nat` | `0` | Guaranteed compute power (0-100%) |
+| `memory_allocation` | `nat` | `0` | Guaranteed memory in bytes (0 = best-effort) |
+| `freezing_threshold` | `nat` | `2_592_000` | Seconds before depletion at which the canister freezes (~30 days) |
+| `reserved_cycles_limit` | `nat` | `5_000_000_000_000` | Upper limit on reserved cycles (5T) |
+| `wasm_memory_limit` | `nat` | `0` | Upper limit on Wasm heap memory in bytes (0 = no limit) |
+| `wasm_memory_threshold` | `nat` | `0` | Remaining Wasm memory threshold that triggers the low-memory hook |
+| `log_visibility` | `log_visibility` | `controllers` | Who can read canister logs: `controllers`, `public`, or `allowed_viewers(vec principal)` |
+| `environment_variables` | `opt record` | `null` | Key-value pairs accessible during canister execution |
+
+For practical guidance on configuring these, see the [canister settings guide](../guides/canister-management/settings.md).
+
+## Canister lifecycle methods
+
+### `create_canister`
+
+Registers a new canister on the IC and returns its canister ID. The canister starts empty (no installed code).
+
+- **Caller:** Canisters only (not available via ingress messages)
+- **Parameters:**
+  - `settings` (`opt canister_settings`) — initial canister settings
+  - `sender_canister_version` (`opt nat64`) — caller's canister version (must match `ic0.canister_version` if provided)
+- **Returns:** `record { canister_id : principal }`
+- **Cycles:** Must be explicitly attached to the call (not deducted automatically)
+
+The caller is **not** automatically a controller unless included in the `controllers` list.
+
+For the lifecycle workflow, see the [canister lifecycle guide](../guides/canister-management/lifecycle.md).
+
+### `update_settings`
+
+Updates the settings of an existing canister. Only controllers can call this method. Omitting a field from the `settings` record leaves that setting unchanged.
+
+- **Caller:** Controllers (canisters or external users)
+- **Parameters:**
+  - `canister_id` (`principal`) — target canister
+  - `settings` (`canister_settings`) — settings to update
+  - `sender_canister_version` (`opt nat64`)
+- **Returns:** Nothing
+
+### `install_code`
+
+Installs or upgrades code on a canister. Only controllers can call this method.
+
+- **Caller:** Controllers (canisters or external users)
+- **Parameters:**
+  - `mode` — one of `install`, `reinstall`, or `upgrade`
+  - `canister_id` (`principal`) — target canister
+  - `wasm_module` (`blob`) — Wasm binary (raw or gzip-compressed)
+  - `arg` (`blob`) — initialization argument
+  - `sender_canister_version` (`opt nat64`)
+- **Returns:** Nothing
+
+Mode behavior:
+
+| Mode | Precondition | Effect |
+|---|---|---|
+| `install` | Canister must be empty | Instantiates module, calls `canister_init` |
+| `reinstall` | Any state | Wipes existing code and state (including stable memory), then installs |
+| `upgrade` | Canister must have code | Runs upgrade flow (`canister_pre_upgrade` then `canister_post_upgrade`) |
+
+The `upgrade` mode accepts optional sub-fields: `skip_pre_upgrade` (skip `canister_pre_upgrade`) and `wasm_memory_persistence` (set to `keep` to preserve Wasm heap memory).
+
+This operation is atomic: if it fails, the canister is unchanged.
+
+### `install_chunked_code`
+
+Installs code that was previously uploaded in chunks. Useful for Wasm modules that exceed the single-message size limit.
+
+- **Caller:** Controllers (canisters or external users)
+- **Parameters:**
+  - `mode` — same as `install_code`
+  - `target_canister` (`principal`) — where to install
+  - `store_canister` (`opt principal`) — where chunks are stored (defaults to `target_canister`)
+  - `chunk_hashes_list` (`vec record { hash : blob }`) — ordered list of chunk hashes
+  - `wasm_module_hash` (`blob`) — SHA-256 of the concatenated chunks
+  - `arg` (`blob`)
+  - `sender_canister_version` (`opt nat64`)
+- **Returns:** Nothing
+
+The caller must be a controller of `store_canister` (or the `store_canister` itself). Both canisters must be on the same subnet.
+
+For uploading large Wasm modules, see the [large Wasm guide](../guides/canister-management/large-wasm.md).
+
+### `uninstall_code`
+
+Removes a canister's code and state, making it empty. Outstanding calls are rejected. The canister retains its cycle balance, controllers, history, and settings.
+
+- **Caller:** Controllers (canisters or external users)
+- **Parameters:**
+  - `canister_id` (`principal`)
+  - `sender_canister_version` (`opt nat64`)
+- **Returns:** Nothing
+
+### `canister_status`
+
+Returns detailed information about a canister: status, settings, module hash, cycle balance, memory usage, and query statistics.
+
+- **Caller:** Controllers or the canister itself (canisters or external users; also available as a query call)
+- **Parameters:**
+  - `canister_id` (`principal`)
+- **Returns:** A record containing:
+  - `status` — `running`, `stopping`, or `stopped`
+  - `settings` — the definite canister settings currently in effect
+  - `module_hash` (`opt blob`) — SHA-256 of installed module (`null` if empty)
+  - `memory_size` (`nat`) — total memory consumed
+  - `memory_metrics` — breakdown by component (Wasm memory, stable memory, globals, binary, custom sections, history, chunk store, snapshots)
+  - `cycles` (`nat`) — current cycle balance
+  - `reserved_cycles` (`nat`) — reserved cycle balance
+  - `idle_cycles_burned_per_day` (`nat`) — daily idle burn rate
+  - `query_stats` — query call statistics (total calls, instructions, request/response bytes)
+
+### `canister_info`
+
+Returns the history, current module hash, and controllers of any canister. Unlike `canister_status`, any canister can call this on any other canister.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `canister_id` (`principal`)
+  - `num_requested_changes` (`opt nat64`) — how many history entries to return (default `0`)
+- **Returns:**
+  - `total_num_changes` (`nat64`)
+  - `recent_changes` — list of canister changes (creation, deployment, controller changes, etc.)
+  - `module_hash` (`opt blob`)
+  - `controllers` (`vec principal`)
+
+The system keeps at least the 20 most recent changes.
+
+### `start_canister`
+
+Sets a stopped or stopping canister to `running`.
+
+- **Caller:** Controllers (canisters or external users)
+- **Parameters:** `canister_id` (`principal`)
+- **Returns:** Nothing
+
+### `stop_canister`
+
+Transitions a canister to `stopping`, then `stopped` once all outstanding responses are processed. While stopping, all incoming calls are rejected.
+
+- **Caller:** Controllers (canisters or external users)
+- **Parameters:** `canister_id` (`principal`)
+- **Returns:** Nothing (returns when the canister reaches `stopped` status, or an error if it times out)
+
+### `delete_canister`
+
+Permanently deletes a canister. The canister must be stopped first. All state and cycles are discarded. The canister ID cannot be reused.
+
+- **Caller:** Controllers (canisters or external users)
+- **Parameters:** `canister_id` (`principal`)
+- **Returns:** Nothing
+
+### `deposit_cycles`
+
+Deposits the cycles attached to this call into the specified canister.
+
+- **Caller:** Canisters only
+- **Parameters:** `canister_id` (`principal`)
+- **Returns:** Nothing
+
+## Code management (chunked uploads)
+
+These methods support uploading large Wasm modules in chunks before installation via `install_chunked_code`.
+
+### `upload_chunk`
+
+Uploads a chunk (up to 1 MiB) to a canister's chunk store. Returns the SHA-256 hash of the stored chunk.
+
+- **Caller:** Controllers or the canister itself (canisters or external users)
+- **Parameters:**
+  - `canister_id` (`principal`)
+  - `chunk` (`blob`)
+- **Returns:** `record { hash : blob }`
+
+### `clear_chunk_store`
+
+Removes all chunks from a canister's chunk store.
+
+- **Caller:** Controllers or the canister itself (canisters or external users)
+- **Parameters:** `canister_id` (`principal`)
+- **Returns:** Nothing
+
+### `stored_chunks`
+
+Lists the hashes of all chunks in a canister's chunk store.
+
+- **Caller:** Controllers or the canister itself (canisters or external users)
+- **Parameters:** `canister_id` (`principal`)
+- **Returns:** `vec record { hash : blob }`
+
+## Canister snapshots
+
+Snapshots capture a canister's Wasm memory, stable memory, certified variables, chunk store, and Wasm binary. They can be loaded later to restore canister state.
+
+### `take_canister_snapshot`
+
+Creates a snapshot of the specified canister. Stop the canister first to ensure all outstanding callbacks are completed.
+
+- **Caller:** Controllers (canisters or external users)
+- **Parameters:**
+  - `canister_id` (`principal`)
+  - `replace_snapshot` (`opt snapshot_id`) — delete this snapshot after creating the new one
+  - `uninstall_code` (`opt bool`) — uninstall code after snapshot creation
+  - `sender_canister_version` (`opt nat64`)
+- **Returns:** Snapshot metadata including `snapshot_id`
+
+### `load_canister_snapshot`
+
+Restores a canister from a previously taken snapshot. Stop the canister first.
+
+- **Caller:** Controllers (canisters or external users)
+- **Parameters:**
+  - `canister_id` (`principal`)
+  - `snapshot_id` (`snapshot_id`)
+  - `sender_canister_version` (`opt nat64`)
+- **Returns:** Nothing
+
+### `list_canister_snapshots`
+
+Lists all snapshots belonging to a canister.
+
+- **Caller:** Controllers (canisters or external users)
+- **Parameters:** `canister_id` (`principal`)
+- **Returns:** List of snapshot metadata
+
+### `delete_canister_snapshot`
+
+Deletes a specific snapshot.
+
+- **Caller:** Controllers (canisters or external users)
+- **Parameters:**
+  - `canister_id` (`principal`)
+  - `snapshot_id` (`snapshot_id`)
+- **Returns:** Nothing
+
+For practical usage, see the [canister snapshots guide](../guides/canister-management/snapshots.md).
+
+## Randomness
+
+### `raw_rand`
+
+Returns 32 bytes of cryptographic randomness. The return value is unknown to any part of the IC at the time the call is submitted — it is resolved in the next execution round using the IC's random tape.
+
+- **Caller:** Canisters only
+- **Parameters:** None
+- **Returns:** `blob` (32 bytes)
+
+For practical usage patterns, see the [randomness guide](../guides/backends/randomness.md).
+
+## Chain-key signing
+
+Chain-key cryptography enables canisters to sign messages using threshold signatures without any single party holding the full private key. The management canister exposes ECDSA and Schnorr signing through the following methods.
+
+### `ecdsa_public_key`
+
+Returns a SEC1-encoded ECDSA public key derived for the given canister and derivation path.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `canister_id` (`opt principal`) — defaults to caller
+  - `derivation_path` (`vec blob`) — up to 255 byte strings of arbitrary length
+  - `key_id` (`record { curve : ecdsa_curve; name : text }`) — currently supports `secp256k1`
+- **Returns:**
+  - `public_key` (`blob`) — SEC1 compressed public key
+  - `chain_code` (`blob`) — for deterministic child key derivation
+
+For `secp256k1`, key derivation uses a generalization of BIP-32. To derive BIP-32-compatible public keys, each entry in `derivation_path` must be a 4-byte big-endian unsigned integer less than 2^31.
+
+### `sign_with_ecdsa`
+
+Signs a message hash using threshold ECDSA. The corresponding public key can be obtained via `ecdsa_public_key` with the same `derivation_path` and `key_id`.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `message_hash` (`blob`) — must be exactly 32 bytes
+  - `derivation_path` (`vec blob`)
+  - `key_id` (`record { curve : ecdsa_curve; name : text }`)
+- **Returns:**
+  - `signature` (`blob`) — concatenation of SEC1-encoded `r` and `s` values (64 bytes for `secp256k1`)
+- **Cycles:** Must be explicitly attached to the call
+
+> If the call returns a reject with code `SYS_UNKNOWN` or `CANISTER_ERROR`, the signature may still exist in the system. Do not assume the signature was not produced.
+
+### `schnorr_public_key`
+
+Returns a Schnorr public key derived for the given canister and derivation path.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `canister_id` (`opt principal`) — defaults to caller
+  - `derivation_path` (`vec blob`) — up to 255 byte strings
+  - `key_id` (`record { algorithm : schnorr_algorithm; name : text }`) — supports `bip340secp256k1` and `ed25519`
+- **Returns:**
+  - `public_key` (`blob`) — SEC1 compressed (for `bip340secp256k1`) or 32-byte Ed25519 format
+  - `chain_code` (`blob`)
+
+### `sign_with_schnorr`
+
+Signs a message using threshold Schnorr. The corresponding public key can be obtained via `schnorr_public_key` with the same `derivation_path` and `key_id`.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `message` (`blob`) — the message to sign (not a hash)
+  - `derivation_path` (`vec blob`)
+  - `key_id` (`record { algorithm : schnorr_algorithm; name : text }`)
+  - `aux` (`opt schnorr_aux`) — optional; the `bip341` variant accepts a `merkle_root_hash` for Taproot signatures (only with `bip340secp256k1`)
+- **Returns:**
+  - `signature` (`blob`) — 64 bytes (BIP-340 for `bip340secp256k1`, RFC 8032 for `ed25519`)
+- **Cycles:** Must be explicitly attached to the call
+
+> If the call returns a reject with code `SYS_UNKNOWN` or `CANISTER_ERROR`, the signature may still exist in the system.
+
+For practical usage of chain-key signing in Bitcoin and Ethereum workflows, see the [Bitcoin guide](../guides/chain-fusion/bitcoin.md) and [Ethereum guide](../guides/chain-fusion/ethereum.md).
+
+## vetKD (Verifiable Encrypted Threshold Key Derivation)
+
+### `vetkd_public_key`
+
+Returns a vetKD public (verification) key derived for the given canister and context.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `canister_id` (`opt principal`) — defaults to caller
+  - `context` (`blob`) — variable-length byte string
+  - `key_id` (`record { curve : vetkd_curve; name : text }`) — supports `bls12_381_g2`
+- **Returns:**
+  - `public_key` (`blob`) — G2 element in BLS12-381 compressed form
+
+### `vetkd_derive_key`
+
+Returns an encrypted vetKD key that can be decrypted with the caller's transport secret key.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `input` (`blob`) — primary key material differentiator
+  - `context` (`blob`) — domain separator
+  - `key_id` (`record { curve : vetkd_curve; name : text }`)
+  - `transport_public_key` (`blob`) — G1 element for encrypting the derived key
+- **Returns:**
+  - `encrypted_key` (`blob`) — the encrypted vetKD key
+- **Cycles:** Must be explicitly attached to the call
+
+## HTTPS outcalls
+
+### `http_request`
+
+Makes an HTTP request to an external URL and returns the response. This enables canisters to fetch offchain data, call external APIs, and interact with other blockchain RPCs.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `url` (`text`) — must start with `https://`; max 8192 characters
+  - `max_response_bytes` (`opt nat64`) — max response size (up to 2 MB; defaults to 2 MB if not set)
+  - `method` — `GET`, `HEAD`, or `POST` (also `PUT` and `DELETE` in non-replicated mode)
+  - `headers` (`vec record { name : text; value : text }`) — request headers (max 64 headers, 8 KiB per name/value, 48 KiB total)
+  - `body` (`opt blob`) — request body
+  - `transform` (`opt record { function : func; context : blob }`) — response transformation function exported by the calling canister
+  - `is_replicated` (`opt bool`) — select replicated (default) or non-replicated mode
+- **Returns:**
+  - `status` (`nat`) — HTTP status code
+  - `headers` (`vec record { name : text; value : text }`)
+  - `body` (`blob`)
+- **Cycles:** Must be explicitly attached to the call. Charged based on `max_response_bytes` — always set this to a reasonable value to avoid overpaying.
+
+In replicated mode, multiple replicas make the same request. Use the `transform` function to sanitize non-deterministic parts of the response (timestamps, unique IDs) so replicas can reach consensus.
+
+For concept details, see [HTTPS outcalls](../concepts/https-outcalls.md).
+
+## Bitcoin API (deprecated)
+
+> The management canister Bitcoin API is **deprecated**. Call the Bitcoin canisters directly instead: `ghsi2-tqaaa-aaaan-aaaca-cai` (mainnet) or `g4xu7-jiaaa-aaaan-aaaaq-cai` (testnet).
+
+The following methods are documented for reference. New code should use the Bitcoin canisters directly.
+
+### `bitcoin_get_utxos`
+
+Returns unspent transaction outputs (UTXOs) for a Bitcoin address.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `address` (`text`) — Bitcoin address (P2PKH, P2SH, P2WPKH, P2WSH, or P2TR)
+  - `network` — `mainnet` or `testnet`
+  - `filter` (`opt variant`) — either `min_confirmations : nat32` (max 144) or `page : blob` for pagination
+- **Returns:**
+  - `utxos` (`vec utxo`) — up to 10,000 UTXOs per request, sorted by block height descending
+  - `tip_block_hash` (`blob`)
+  - `tip_height` (`nat32`)
+  - `next_page` (`opt blob`) — pagination token if more UTXOs exist
+
+### `bitcoin_get_balance`
+
+Returns the balance of a Bitcoin address in satoshi.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `address` (`text`)
+  - `network` — `mainnet` or `testnet`
+  - `min_confirmations` (`opt nat32`)
+- **Returns:** `nat64` (balance in satoshi)
+
+### `bitcoin_send_transaction`
+
+Submits a Bitcoin transaction to the network. The transaction must be well-formed, consume only unspent outputs, and have a positive fee.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `transaction` (`blob`) — serialized Bitcoin transaction
+  - `network` — `mainnet` or `testnet`
+- **Returns:** Nothing
+
+No guarantee is provided that the transaction will enter the mempool or appear in a block.
+
+### `bitcoin_get_current_fee_percentiles`
+
+Returns fee percentiles (in millisatoshi/vbyte) over the last ~10,000 transactions.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `network` — `mainnet` or `testnet`
+- **Returns:** `vec nat64` — 101 percentiles (0th through 100th)
+
+### `bitcoin_get_block_headers`
+
+Returns block headers for a range of block heights.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `start_height` (`nat32`)
+  - `end_height` (`opt nat32`) — defaults to tip height
+  - `network` — `mainnet` or `testnet`
+- **Returns:**
+  - `tip_height` (`nat32`)
+  - `block_headers` (`vec blob`) — 80-byte headers in standard Bitcoin format
+
+For Bitcoin integration patterns, see the [Bitcoin guide](../guides/chain-fusion/bitcoin.md).
+
+## Canister logging
+
+### `fetch_canister_logs`
+
+Returns the most recent log entries for a canister. Logs are produced by `ic0.debug_print` and trap messages. Logs persist across upgrades but are purged on reinstall or uninstall. Total log size is capped at 4 KiB.
+
+- **Caller:** External users only (query call; not callable by canisters)
+- **Parameters:** `canister_id` (`principal`)
+- **Returns:**
+  - `canister_log_records` (`vec record { idx : nat64; timestamp_nanos : nat64; content : blob }`)
+
+Log visibility is controlled by the `log_visibility` canister setting.
+
+For practical usage, see the [canister logs guide](../guides/canister-management/logs.md).
+
+## Provisional methods (local testing only)
+
+These methods are only available on local development instances. They do not exist on mainnet.
+
+### `provisional_create_canister_with_cycles`
+
+Behaves like `create_canister` but initializes the canister with the specified number of cycles (or a default amount if `null`). If `specified_id` is provided, creates the canister with that exact ID.
+
+- **Caller:** Canisters or external users
+- **Parameters:**
+  - `amount` (`opt nat`) — initial cycle balance
+  - `settings` (`opt canister_settings`)
+  - `specified_id` (`opt principal`) — request a specific canister ID
+  - `sender_canister_version` (`opt nat64`)
+- **Returns:** `record { canister_id : principal }`
+
+### `provisional_top_up_canister`
+
+Adds cycles to any canister out of thin air.
+
+- **Caller:** Canisters or external users (any caller)
+- **Parameters:**
+  - `canister_id` (`principal`)
+  - `amount` (`nat`) — cycles to add
+- **Returns:** Nothing
+
+## Cycle costs
+
+Cycle costs for management canister calls vary depending on subnet replication factor and are subject to change. Rather than hardcoding costs, use the System API cost functions to query current prices programmatically:
+
+- `ic0.cost_create_canister` — cost of `create_canister`
+- `ic0.cost_call` — cost of an inter-canister call (base + per-byte)
+- `ic0.cost_http_request` — cost of `http_request`
+- `ic0.cost_sign_with_ecdsa` — cost of `sign_with_ecdsa`
+- `ic0.cost_sign_with_schnorr` — cost of `sign_with_schnorr`
+- `ic0.cost_vetkd_derive_key` — cost of `vetkd_derive_key`
+
+Methods that require explicit cycle attachment (`create_canister`, `sign_with_ecdsa`, `sign_with_schnorr`, `vetkd_derive_key`, `http_request`) will fail if insufficient cycles are provided.
+
+## Next steps
+
+- [Canister lifecycle guide](../guides/canister-management/lifecycle.md) — practical workflows for creating, upgrading, and managing canisters
+- [Canister settings guide](../guides/canister-management/settings.md) — configuring controllers, memory, compute, and freezing thresholds
+- [HTTPS outcalls](../concepts/https-outcalls.md) — architecture and constraints of outbound HTTP requests
+- [Bitcoin integration](../guides/chain-fusion/bitcoin.md) — building Bitcoin-native applications with chain-key signing
+- [IC interface specification](ic-interface-spec.md) — the complete formal specification
+
+<!-- Upstream: informed by dfinity/portal — docs/references/system-canisters/management-canister.mdx, docs/references/ic-interface-spec.md -->

From 3455de2c8869fb028ea4bac0a198df2769bc3c9a Mon Sep 17 00:00:00 2001
From: Marco Walz <marco.walz@dfinity.org>
Date: Thu, 19 Mar 2026 13:27:45 +0100
Subject: [PATCH 2/3] docs: address review feedback for management canister
 reference

- Add missing methods: canister_metadata, read/upload snapshot methods,
  node_metrics_history, subnet_info
- Add missing canister_status return fields (canister_version, ready_for_migration)
- Fix create_canister controller note to cover default behavior
- Clarify http_request PUT/DELETE non-replicated restriction
- Add cycles-management to icskills frontmatter
- Update Upstream comment to include icskills reference
---
 docs/reference/management-canister.md | 94 +++++++++++++++++++++++++--
 1 file changed, 90 insertions(+), 4 deletions(-)

diff --git a/docs/reference/management-canister.md b/docs/reference/management-canister.md
index 19ecc77f..0ade3d37 100644
--- a/docs/reference/management-canister.md
+++ b/docs/reference/management-canister.md
@@ -3,7 +3,7 @@ title: "Management Canister"
 description: "API reference for the IC management canister (aaaaa-aa): canister lifecycle, signing, randomness, and more"
 sidebar:
   order: 1
-icskills: []
+icskills: [cycles-management]
 ---
 
 The management canister provides access to system features on the Internet Computer: creating and managing canisters, chain-key signing, HTTPS outcalls, randomness, and Bitcoin integration. It is not a real canister with its own state or Wasm module. It is a virtual canister implemented as part of the IC protocol itself.
@@ -45,7 +45,7 @@ Registers a new canister on the IC and returns its canister ID. The canister sta
 - **Returns:** `record { canister_id : principal }`
 - **Cycles:** Must be explicitly attached to the call (not deducted automatically)
 
-The caller is **not** automatically a controller unless included in the `controllers` list.
+If you provide a `controllers` list, the caller is only a controller if included in that list. If you omit `controllers`, it defaults to a list containing only the caller.
 
 For the lifecycle workflow, see the [canister lifecycle guide](../guides/canister-management/lifecycle.md).
 
@@ -123,6 +123,8 @@ Returns detailed information about a canister: status, settings, module hash, cy
   - `canister_id` (`principal`)
 - **Returns:** A record containing:
   - `status` — `running`, `stopping`, or `stopped`
+  - `ready_for_migration` (`bool`) — whether a stopped canister is ready for subnet migration (always `false` unless `stopped`)
+  - `canister_version` (`nat64`) — the canister's current version number
   - `settings` — the definite canister settings currently in effect
   - `module_hash` (`opt blob`) — SHA-256 of installed module (`null` if empty)
   - `memory_size` (`nat`) — total memory consumed
@@ -148,6 +150,19 @@ Returns the history, current module hash, and controllers of any canister. Unlik
 
 The system keeps at least the 20 most recent changes.
 
+### `canister_metadata`
+
+Reads custom-section metadata from a canister. Custom sections with names of the form `icp:public <name>` are readable by any canister. Custom sections with names of the form `icp:private <name>` are only readable by controllers.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `canister_id` (`principal`) — the canister to read metadata from
+  - `name` (`text`) — identifies the custom section (`icp:public <name>` or `icp:private <name>`)
+- **Returns:**
+  - `value` (`blob`) — the content of the custom section
+
+Common uses include reading `candid:service` for Candid interface discovery.
+
 ### `start_canister`
 
 Sets a stopped or stopping canister to `running`.
@@ -255,6 +270,49 @@ Deletes a specific snapshot.
   - `snapshot_id` (`snapshot_id`)
 - **Returns:** Nothing
 
+### `read_canister_snapshot_metadata`
+
+Returns all metadata of a snapshot: source (taken or uploaded), creation timestamp, Wasm size, Wasm globals, heap and stable memory sizes, chunk store hashes, canister version, certified data, and optionally the global timer and low-memory hook state.
+
+- **Caller:** Controllers (canisters or external users)
+- **Parameters:**
+  - `canister_id` (`principal`)
+  - `snapshot_id` (`snapshot_id`)
+- **Returns:** Snapshot metadata record
+
+### `read_canister_snapshot_data`
+
+Returns a requested chunk of binary data from a snapshot: Wasm binary, heap memory, stable memory, or a chunk store entry.
+
+- **Caller:** Controllers (canisters or external users)
+- **Parameters:**
+  - `canister_id` (`principal`)
+  - `snapshot_id` (`snapshot_id`)
+  - `kind` — which data to read (`wasm`, `wasm_memory`, `stable_memory`, or `chunk_store`), with `offset` and `size` (or `hash` for chunk store)
+- **Returns:** `blob` — the requested data chunk
+
+### `upload_canister_snapshot_metadata`
+
+Creates a new snapshot by uploading metadata (Wasm size, globals, memory sizes, certified data, and optionally timer/hook state). Data is uploaded separately via `upload_canister_snapshot_data`.
+
+- **Caller:** Controllers (canisters or external users)
+- **Parameters:**
+  - `canister_id` (`principal`)
+  - `replace_snapshot` (`opt snapshot_id`) — delete this snapshot after creating the new one
+  - Snapshot metadata fields (Wasm size, globals, memory sizes, certified data, timer state, hook state)
+- **Returns:** Snapshot metadata including `snapshot_id`
+
+### `upload_canister_snapshot_data`
+
+Uploads a chunk of binary data to a snapshot created via `upload_canister_snapshot_metadata`. Supports Wasm binary, heap memory, stable memory, and chunk store entries (max 1 MiB per chunk store entry).
+
+- **Caller:** Controllers (canisters or external users)
+- **Parameters:**
+  - `canister_id` (`principal`)
+  - `snapshot_id` (`snapshot_id`)
+  - `kind` — which data to upload, with `offset` and chunk content
+- **Returns:** Nothing
+
 For practical usage, see the [canister snapshots guide](../guides/canister-management/snapshots.md).
 
 ## Randomness
@@ -372,7 +430,7 @@ Makes an HTTP request to an external URL and returns the response. This enables
 - **Parameters:**
   - `url` (`text`) — must start with `https://`; max 8192 characters
   - `max_response_bytes` (`opt nat64`) — max response size (up to 2 MB; defaults to 2 MB if not set)
-  - `method` — `GET`, `HEAD`, or `POST` (also `PUT` and `DELETE` in non-replicated mode)
+  - `method` — `GET`, `HEAD`, or `POST` (replicated); additionally `PUT` and `DELETE` (non-replicated mode only)
   - `headers` (`vec record { name : text; value : text }`) — request headers (max 64 headers, 8 KiB per name/value, 48 KiB total)
   - `body` (`opt blob`) — request body
   - `transform` (`opt record { function : func; context : blob }`) — response transformation function exported by the calling canister
@@ -470,6 +528,34 @@ Log visibility is controlled by the `log_visibility` canister setting.
 
 For practical usage, see the [canister logs guide](../guides/canister-management/logs.md).
 
+## Subnet and node information
+
+### `node_metrics_history`
+
+> This API is **experimental** and may change in a non-backward-compatible way.
+
+Returns a time series of node metrics for a given subnet. Returns up to 60 timestamps (no two from the same UTC day), starting from `start_at_timestamp_nanos`. A sample only includes metrics for nodes whose values changed since the previous sample — consumers must handle resets when a node disappears and reappears.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `subnet_id` (`principal`)
+  - `start_at_timestamp_nanos` (`nat64`)
+- **Returns:** A list of timestamped records, each containing a list of node metrics:
+  - `node_id` (`principal`)
+  - `num_blocks_proposed_total` (`nat64`)
+  - `num_block_failures_total` (`nat64`)
+
+### `subnet_info`
+
+Returns metadata about a subnet.
+
+- **Caller:** Canisters only
+- **Parameters:**
+  - `subnet_id` (`principal`)
+- **Returns:**
+  - `replica_version` (`text`) — the replica version running on the subnet
+  - `registry_version` (`nat64`) — the registry version of the subnet
+
 ## Provisional methods (local testing only)
 
 These methods are only available on local development instances. They do not exist on mainnet.
@@ -517,4 +603,4 @@ Methods that require explicit cycle attachment (`create_canister`, `sign_with_ec
 - [Bitcoin integration](../guides/chain-fusion/bitcoin.md) — building Bitcoin-native applications with chain-key signing
 - [IC interface specification](ic-interface-spec.md) — the complete formal specification
 
-<!-- Upstream: informed by dfinity/portal — docs/references/system-canisters/management-canister.mdx, docs/references/ic-interface-spec.md -->
+<!-- Upstream: informed by dfinity/portal — docs/references/system-canisters/management-canister.mdx, docs/references/ic-interface-spec.md; dfinity/icskills — skills/cycles-management/SKILL.md -->

From a998a09527a1b33b189c477b25a2740b5f5dff47 Mon Sep 17 00:00:00 2001
From: Marco Walz <marco.walz@dfinity.org>
Date: Thu, 19 Mar 2026 13:35:42 +0100
Subject: [PATCH 3/3] docs: add ic.did Candid interface and submodule bump
 checklist

- Copy ic.did from portal into docs/reference/_attachments/
- Reference it from management canister page for binding generation
- Add "Synced files from submodules" section to AGENTS.md with portal
  bump checklist for ic.did
- Record decision in decisions.md
---
 .docs-plan/decisions.md               |   7 +
 AGENTS.md                             |  15 +
 docs/reference/_attachments/ic.did    | 678 ++++++++++++++++++++++++++
 docs/reference/management-canister.md |   8 +-
 4 files changed, 707 insertions(+), 1 deletion(-)
 create mode 100644 docs/reference/_attachments/ic.did

diff --git a/.docs-plan/decisions.md b/.docs-plan/decisions.md
index 1ebedbc3..6135501a 100644
--- a/.docs-plan/decisions.md
+++ b/.docs-plan/decisions.md
@@ -177,6 +177,13 @@ Record decisions that constrain future work — things an agent needs to know th
 **Rationale:** Alternatives were evaluated and rejected: (1) Symlinking `.sources/` to the main repo's copy — works for file access but causes 13 spurious deletion entries in `git status` that could confuse agents into staging them; symlinking individual submodule dirs causes a hard `git status` error (exit 128). (2) `submodule.recurse=true` git config — does not auto-init submodules on `git worktree add`. (3) Vendoring skills into the repo — loses automatic sync with upstream skill repos. The submodule init approach is the only one with zero git side effects (clean status, no surprises), which is critical for agents operating autonomously.
 **Alternatives considered:** Shared `.sources/` symlink (dirty git status confuses agents), `submodule.recurse` config (doesn't work for worktree creation), vendored skills (manual sync burden)
 
+## 2026-03-19: Sync ic.did from portal and check on submodule bumps
+
+**Context:** The management canister Candid interface (`ic.did`) is the machine-readable type definition for all management canister methods. It lives in the portal repo at `docs/references/_attachments/ic.did` and is embedded in the IC interface spec page. The IC repo (`dfinity/ic`) also has a copy in `packages/ic-management-canister-types/tests/ic.did`, but it may include unreleased changes. The portal version represents the released spec.
+**Decision:** Copy `ic.did` from `.sources/portal/` into `docs/reference/_attachments/ic.did`. Reference it from the management canister page. On portal submodule bumps, diff `ic.did` — if it changed, re-copy and update `management-canister.md` plus any guides referencing affected methods. Added "Synced files from submodules" section to AGENTS.md with a bump checklist.
+**Rationale:** Developers need the Candid interface for binding generation and type checking. Copying rather than symlinking ensures the file is served by the docs site. The portal version is the released source of truth; the IC repo version may be ahead with unreleased changes.
+**Alternatives considered:** Symlink to `.sources/` (not served by Astro build), link to GitHub raw URL (breaks offline, no version control), add IC repo as submodule (too large)
+
 ## 2026-03-18: Move wallet-integration from authentication to DeFi section
 
 **Context:** The wallet-integration page covers ICRC signer standards (ICRC-21/25/27/29/49) for transaction approval, not authentication. The wallet-integration icskill itself distinguishes wallet signers (transaction approval) from Internet Identity (authentication/login). Under `guides/authentication/`, the page was grouped with II and verifiable credentials — a different concern.
diff --git a/AGENTS.md b/AGENTS.md
index ad14e30a..af3173e8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -487,6 +487,21 @@ Only the project maintainer bumps submodule refs. When bumped:
 2. Review if any existing docs pages are affected by the upstream changes
 3. Update affected pages and note the bump in the PR description
 
+### Synced files from submodules
+
+Some files are copied from `.sources/` into the docs repo because they need to be served or referenced directly. When bumping the source submodule, these files must be diffed and re-copied if changed.
+
+| Local file | Source | Affects |
+|-----------|--------|---------|
+| `docs/reference/_attachments/ic.did` | `.sources/portal/docs/references/_attachments/ic.did` | Management canister reference — new/changed methods require updating `docs/reference/management-canister.md` and any guides that reference affected methods |
+
+**Portal bump checklist for `ic.did`:**
+1. Diff: `diff docs/reference/_attachments/ic.did .sources/portal/docs/references/_attachments/ic.did`
+2. If changed, copy: `cp .sources/portal/docs/references/_attachments/ic.did docs/reference/_attachments/ic.did`
+3. Review the diff for new methods, changed signatures, or removed methods
+4. Update `docs/reference/management-canister.md` to reflect any interface changes
+5. Check guides that reference affected methods (chain-fusion, canister-management, backends)
+
 ## Planning artifacts (`.docs-plan/`)
 
 Check these every session:
diff --git a/docs/reference/_attachments/ic.did b/docs/reference/_attachments/ic.did
new file mode 100644
index 00000000..f412d699
--- /dev/null
+++ b/docs/reference/_attachments/ic.did
@@ -0,0 +1,678 @@
+type canister_id = principal;
+type wasm_module = blob;
+type snapshot_id = blob;
+
+type log_visibility = variant {
+    controllers;
+    public;
+    allowed_viewers : vec principal;
+};
+
+type environment_variable = record { 
+    name: text; 
+    value: text;
+};
+
+type canister_settings = record {
+    controllers : opt vec principal;
+    compute_allocation : opt nat;
+    memory_allocation : opt nat;
+    freezing_threshold : opt nat;
+    reserved_cycles_limit : opt nat;
+    log_visibility : opt log_visibility;
+    wasm_memory_limit : opt nat;
+    wasm_memory_threshold : opt nat;
+    environment_variables : opt vec environment_variable;
+};
+
+type definite_canister_settings = record {
+    controllers : vec principal;
+    compute_allocation : nat;
+    memory_allocation : nat;
+    freezing_threshold : nat;
+    reserved_cycles_limit : nat;
+    log_visibility : log_visibility;
+    wasm_memory_limit : nat;
+    wasm_memory_threshold : nat;
+    environment_variables : vec environment_variable;
+};
+
+type change_origin = variant {
+    from_user : record {
+        user_id : principal;
+    };
+    from_canister : record {
+        canister_id : canister_id;
+        canister_version : opt nat64;
+    };
+};
+
+type change_details = variant {
+    creation : record {
+        controllers : vec principal;
+        environment_variables_hash : opt blob; 
+    };
+    code_uninstall;
+    code_deployment : record {
+        mode : variant { install; reinstall; upgrade };
+        module_hash : blob;
+    };
+    load_snapshot : record {
+        from_canister_id : opt principal;
+        snapshot_id : snapshot_id;
+        canister_version : nat64;
+        taken_at_timestamp : nat64;
+        source : variant {
+          taken_from_canister : reserved;
+          metadata_upload : reserved;
+        };
+    };
+    controllers_change : record {
+        controllers : vec principal;
+    };
+    rename_canister : record {
+        canister_id : canister_id;
+        total_num_changes : nat64;
+        rename_to : record {
+            canister_id : canister_id;
+            version : nat64;
+            total_num_changes : nat64;
+        };
+        requested_by : principal;
+    };
+};
+
+type change = record {
+    timestamp_nanos : nat64;
+    canister_version : nat64;
+    origin : change_origin;
+    details : change_details;
+};
+
+type chunk_hash = record {
+    hash : blob;
+};
+
+type http_header = record {
+    name : text;
+    value : text;
+};
+
+type http_request_result = record {
+    status : nat;
+    headers : vec http_header;
+    body : blob;
+};
+
+type ecdsa_curve = variant {
+    secp256k1;
+};
+
+type vetkd_curve = variant {
+    bls12_381_g2;
+};
+
+type schnorr_algorithm = variant {
+    bip340secp256k1;
+    ed25519;
+};
+
+type satoshi = nat64;
+
+type bitcoin_network = variant {
+    mainnet;
+    testnet;
+};
+
+type bitcoin_address = text;
+
+type bitcoin_block_hash = blob;
+
+type bitcoin_block_header = blob;
+
+type millisatoshi_per_byte = nat64;
+
+type bitcoin_block_height = nat32;
+
+type outpoint = record {
+    txid : blob;
+    vout : nat32;
+};
+
+type utxo = record {
+    outpoint : outpoint;
+    value : satoshi;
+    height : nat32;
+};
+
+type bitcoin_get_utxos_args = record {
+    address : bitcoin_address;
+    network : bitcoin_network;
+    filter : opt variant {
+        min_confirmations : nat32;
+        page : blob;
+    };
+};
+
+type bitcoin_get_utxos_result = record {
+    utxos : vec utxo;
+    tip_block_hash : bitcoin_block_hash;
+    tip_height : bitcoin_block_height;
+    next_page : opt blob;
+};
+
+type bitcoin_get_balance_args = record {
+    address : bitcoin_address;
+    network : bitcoin_network;
+    min_confirmations : opt nat32;
+};
+
+type bitcoin_get_balance_result = satoshi;
+
+type bitcoin_get_current_fee_percentiles_args = record {
+    network : bitcoin_network;
+};
+
+type bitcoin_get_current_fee_percentiles_result = vec millisatoshi_per_byte;
+
+type bitcoin_send_transaction_args = record {
+    transaction : blob;
+    network : bitcoin_network;
+};
+
+type bitcoin_get_block_headers_args = record {
+    start_height : bitcoin_block_height;
+    end_height : opt bitcoin_block_height;
+    network : bitcoin_network;
+};
+
+type bitcoin_get_block_headers_result = record {
+    tip_height : bitcoin_block_height;
+    block_headers : vec bitcoin_block_header;
+};
+
+type node_metrics = record {
+    node_id : principal;
+    num_blocks_proposed_total : nat64;
+    num_block_failures_total : nat64;
+};
+
+type create_canister_args = record {
+    settings : opt canister_settings;
+    sender_canister_version : opt nat64;
+};
+
+type create_canister_result = record {
+    canister_id : canister_id;
+};
+
+type update_settings_args = record {
+    canister_id : canister_id;
+    settings : canister_settings;
+    sender_canister_version : opt nat64;
+};
+
+type upload_chunk_args = record {
+    canister_id : canister_id;
+    chunk : blob;
+};
+
+type clear_chunk_store_args = record {
+    canister_id : canister_id;
+};
+
+type stored_chunks_args = record {
+    canister_id : canister_id;
+};
+
+type canister_install_mode = variant {
+    install;
+    reinstall;
+    upgrade : opt record {
+        skip_pre_upgrade : opt bool;
+        wasm_memory_persistence : opt variant {
+            keep;
+            replace;
+        };
+    };
+};
+
+type install_code_args = record {
+    mode : canister_install_mode;
+    canister_id : canister_id;
+    wasm_module : wasm_module;
+    arg : blob;
+    sender_canister_version : opt nat64;
+};
+
+type install_chunked_code_args = record {
+    mode : canister_install_mode;
+    target_canister : canister_id;
+    store_canister : opt canister_id;
+    chunk_hashes_list : vec chunk_hash;
+    wasm_module_hash : blob;
+    arg : blob;
+    sender_canister_version : opt nat64;
+};
+
+type uninstall_code_args = record {
+    canister_id : canister_id;
+    sender_canister_version : opt nat64;
+};
+
+type start_canister_args = record {
+    canister_id : canister_id;
+};
+
+type stop_canister_args = record {
+    canister_id : canister_id;
+};
+
+type canister_status_args = record {
+    canister_id : canister_id;
+};
+
+type canister_status_result = record {
+    status : variant {
+        running;
+        stopping;
+        stopped;
+    };
+    ready_for_migration : bool;
+    version : nat64;
+    settings : definite_canister_settings;
+    module_hash : opt blob;
+    memory_size : nat;
+    memory_metrics : record {
+        wasm_memory_size : nat;
+        stable_memory_size : nat;
+        global_memory_size : nat;
+        wasm_binary_size : nat;
+        custom_sections_size : nat;
+        canister_history_size : nat;
+        wasm_chunk_store_size : nat;
+        snapshots_size : nat;
+    };
+    cycles : nat;
+    reserved_cycles : nat;
+    idle_cycles_burned_per_day : nat;
+    query_stats : record {
+        num_calls_total : nat;
+        num_instructions_total : nat;
+        request_payload_bytes_total : nat;
+        response_payload_bytes_total : nat;
+    };
+};
+
+type canister_info_args = record {
+    canister_id : canister_id;
+    num_requested_changes : opt nat64;
+};
+
+type canister_info_result = record {
+    total_num_changes : nat64;
+    recent_changes : vec change;
+    module_hash : opt blob;
+    controllers : vec principal;
+};
+
+type canister_metadata_args = record {
+    canister_id : canister_id;
+    name : text;
+};
+
+type canister_metadata_result = record {
+    value : blob;
+};
+
+type delete_canister_args = record {
+    canister_id : canister_id;
+};
+
+type deposit_cycles_args = record {
+    canister_id : canister_id;
+};
+
+type http_request_args = record {
+    url : text;
+    max_response_bytes : opt nat64;
+    method : variant { get; head; post; put; delete };
+    headers : vec http_header;
+    body : opt blob;
+    transform : opt record {
+        function : func(record { response : http_request_result; context : blob }) -> (http_request_result) query;
+        context : blob;
+    };
+    is_replicated : opt bool;
+};
+
+type ecdsa_public_key_args = record {
+    canister_id : opt canister_id;
+    derivation_path : vec blob;
+    key_id : record { curve : ecdsa_curve; name : text };
+};
+
+type ecdsa_public_key_result = record {
+    public_key : blob;
+    chain_code : blob;
+};
+
+type sign_with_ecdsa_args = record {
+    message_hash : blob;
+    derivation_path : vec blob;
+    key_id : record { curve : ecdsa_curve; name : text };
+};
+
+type sign_with_ecdsa_result = record {
+    signature : blob;
+};
+
+type schnorr_public_key_args = record {
+    canister_id : opt canister_id;
+    derivation_path : vec blob;
+    key_id : record { algorithm : schnorr_algorithm; name : text };
+};
+
+type schnorr_public_key_result = record {
+    public_key : blob;
+    chain_code : blob;
+};
+
+type schnorr_aux = variant {
+    bip341 : record {
+        merkle_root_hash : blob;
+    };
+};
+
+type sign_with_schnorr_args = record {
+    message : blob;
+    derivation_path : vec blob;
+    key_id : record { algorithm : schnorr_algorithm; name : text };
+    aux : opt schnorr_aux;
+};
+
+type sign_with_schnorr_result = record {
+    signature : blob;
+};
+
+type vetkd_public_key_args = record {
+    canister_id : opt canister_id;
+    context : blob;
+    key_id : record { curve : vetkd_curve; name : text };
+};
+
+type vetkd_public_key_result = record {
+    public_key : blob;
+};
+
+type vetkd_derive_key_args = record {
+    input : blob;
+    context : blob;
+    transport_public_key : blob;
+    key_id : record { curve : vetkd_curve; name : text };
+};
+
+type vetkd_derive_key_result = record {
+    encrypted_key : blob;
+};
+
+type node_metrics_history_args = record {
+    subnet_id : principal;
+    start_at_timestamp_nanos : nat64;
+};
+
+type node_metrics_history_result = vec record {
+    timestamp_nanos : nat64;
+    node_metrics : vec node_metrics;
+};
+
+type subnet_info_args = record {
+    subnet_id : principal;
+};
+
+type subnet_info_result = record {
+    replica_version : text;
+    registry_version : nat64;
+};
+
+type provisional_create_canister_with_cycles_args = record {
+    amount : opt nat;
+    settings : opt canister_settings;
+    specified_id : opt canister_id;
+    sender_canister_version : opt nat64;
+};
+
+type provisional_create_canister_with_cycles_result = record {
+    canister_id : canister_id;
+};
+
+type provisional_top_up_canister_args = record {
+    canister_id : canister_id;
+    amount : nat;
+};
+
+type raw_rand_result = blob;
+
+type stored_chunks_result = vec chunk_hash;
+
+type upload_chunk_result = chunk_hash;
+
+type snapshot = record {
+    id : snapshot_id;
+    taken_at_timestamp : nat64;
+    total_size : nat64;
+};
+
+type take_canister_snapshot_args = record {
+    canister_id : canister_id;
+    replace_snapshot : opt snapshot_id;
+    uninstall_code : opt bool;
+    sender_canister_version : opt nat64;
+};
+
+type take_canister_snapshot_result = snapshot;
+
+type load_canister_snapshot_args = record {
+    canister_id : canister_id;
+    snapshot_id : snapshot_id;
+    sender_canister_version : opt nat64;
+};
+
+type list_canister_snapshots_args = record {
+    canister_id : canister_id;
+};
+
+type list_canister_snapshots_result = vec snapshot;
+
+type delete_canister_snapshot_args = record {
+    canister_id : canister_id;
+    snapshot_id : snapshot_id;
+};
+
+type fetch_canister_logs_args = record {
+    canister_id : canister_id;
+};
+
+type canister_log_record = record {
+    idx : nat64;
+    timestamp_nanos : nat64;
+    content : blob;
+};
+
+type fetch_canister_logs_result = record {
+    canister_log_records : vec canister_log_record;
+};
+
+type read_canister_snapshot_metadata_args = record {
+    canister_id : canister_id;
+    snapshot_id : snapshot_id;
+};
+
+type read_canister_snapshot_metadata_response = record {
+    source : variant {
+        taken_from_canister: reserved;
+        metadata_upload : reserved;
+    };
+    taken_at_timestamp : nat64;
+    wasm_module_size : nat64;
+    globals : vec variant {
+        i32 : int32;
+        i64 : int64;
+        f32 : float32;
+        f64 : float64;
+        v128 : nat;
+    };
+    wasm_memory_size : nat64;
+    stable_memory_size : nat64;
+    wasm_chunk_store : vec record {
+        hash : blob;
+    };
+    canister_version : nat64;
+    certified_data : blob;
+    global_timer : opt variant {
+        inactive;
+        active : nat64;
+    };
+    on_low_wasm_memory_hook_status : opt variant {
+        condition_not_satisfied;
+        ready;
+        executed;
+    };
+};
+
+type read_canister_snapshot_data_args = record {
+    canister_id : canister_id;
+    snapshot_id : snapshot_id;
+    kind : variant {
+        wasm_module : record {
+            offset : nat64;
+            size : nat64;
+        };
+        wasm_memory : record {
+            offset : nat64;
+            size : nat64;
+        };
+        stable_memory : record {
+            offset : nat64;
+            size : nat64;
+        };
+        wasm_chunk : record {
+            hash : blob;
+        };
+    };
+};
+
+type read_canister_snapshot_data_response  = record {
+    chunk : blob;
+};
+
+type upload_canister_snapshot_metadata_args = record {
+    canister_id : canister_id;
+    replace_snapshot : opt snapshot_id;
+    wasm_module_size : nat64;
+    globals : vec variant {
+        i32 : int32;
+        i64 : int64;
+        f32 : float32;
+        f64 : float64;
+        v128 : nat;
+    };
+    wasm_memory_size : nat64;
+    stable_memory_size : nat64;
+    certified_data : blob;
+    global_timer : opt variant {
+        inactive;
+        active : nat64;
+    };
+    on_low_wasm_memory_hook_status : opt variant {
+        condition_not_satisfied;
+        ready;
+        executed;
+    };
+};
+
+type upload_canister_snapshot_metadata_response = record {
+    snapshot_id : snapshot_id;
+};
+
+type upload_canister_snapshot_data_args = record {
+    canister_id : canister_id;
+    snapshot_id : snapshot_id;
+    kind : variant {
+        wasm_module : record {
+            offset : nat64;
+        };
+        wasm_memory : record {
+            offset : nat64;
+        };
+        stable_memory : record {
+            offset : nat64;
+        };
+        wasm_chunk;
+    };
+    chunk : blob;
+};
+
+service ic : {
+    create_canister : (create_canister_args) -> (create_canister_result);
+    update_settings : (update_settings_args) -> ();
+    upload_chunk : (upload_chunk_args) -> (upload_chunk_result);
+    clear_chunk_store : (clear_chunk_store_args) -> ();
+    stored_chunks : (stored_chunks_args) -> (stored_chunks_result);
+    install_code : (install_code_args) -> ();
+    install_chunked_code : (install_chunked_code_args) -> ();
+    uninstall_code : (uninstall_code_args) -> ();
+    start_canister : (start_canister_args) -> ();
+    stop_canister : (stop_canister_args) -> ();
+    canister_status : (canister_status_args) -> (canister_status_result) query;
+    delete_canister : (delete_canister_args) -> ();
+    deposit_cycles : (deposit_cycles_args) -> ();
+    raw_rand : () -> (raw_rand_result);
+    http_request : (http_request_args) -> (http_request_result);
+
+    // Public canister data
+    canister_info : (canister_info_args) -> (canister_info_result);
+    canister_metadata : (canister_metadata_args) -> (canister_metadata_result);
+
+    // Threshold ECDSA signature
+    ecdsa_public_key : (ecdsa_public_key_args) -> (ecdsa_public_key_result);
+    sign_with_ecdsa : (sign_with_ecdsa_args) -> (sign_with_ecdsa_result);
+
+    // Threshold Schnorr signature
+    schnorr_public_key : (schnorr_public_key_args) -> (schnorr_public_key_result);
+    sign_with_schnorr : (sign_with_schnorr_args) -> (sign_with_schnorr_result);
+
+    // Threshold key derivation
+    vetkd_public_key : (vetkd_public_key_args) -> (vetkd_public_key_result);
+    vetkd_derive_key : (vetkd_derive_key_args) -> (vetkd_derive_key_result);
+
+    // bitcoin interface
+    bitcoin_get_balance : (bitcoin_get_balance_args) -> (bitcoin_get_balance_result);
+    bitcoin_get_utxos : (bitcoin_get_utxos_args) -> (bitcoin_get_utxos_result);
+    bitcoin_send_transaction : (bitcoin_send_transaction_args) -> ();
+    bitcoin_get_current_fee_percentiles : (bitcoin_get_current_fee_percentiles_args) -> (bitcoin_get_current_fee_percentiles_result);
+    bitcoin_get_block_headers : (bitcoin_get_block_headers_args) -> (bitcoin_get_block_headers_result);
+
+    // metrics interface
+    node_metrics_history : (node_metrics_history_args) -> (node_metrics_history_result);
+
+    // subnet info
+    subnet_info : (subnet_info_args) -> (subnet_info_result);
+
+    // provisional interfaces for the pre-ledger world
+    provisional_create_canister_with_cycles : (provisional_create_canister_with_cycles_args) -> (provisional_create_canister_with_cycles_result);
+    provisional_top_up_canister : (provisional_top_up_canister_args) -> ();
+
+    // Canister snapshots
+    take_canister_snapshot : (take_canister_snapshot_args) -> (take_canister_snapshot_result);
+    load_canister_snapshot : (load_canister_snapshot_args) -> ();
+    read_canister_snapshot_metadata : (read_canister_snapshot_metadata_args) -> (read_canister_snapshot_metadata_response);
+    read_canister_snapshot_data : (read_canister_snapshot_data_args) -> (read_canister_snapshot_data_response);
+    upload_canister_snapshot_metadata : (upload_canister_snapshot_metadata_args) -> (upload_canister_snapshot_metadata_response);
+    upload_canister_snapshot_data : (upload_canister_snapshot_data_args) -> ();
+    list_canister_snapshots : (list_canister_snapshots_args) -> (list_canister_snapshots_result);
+    delete_canister_snapshot : (delete_canister_snapshot_args) -> ();
+
+    // canister logging
+    fetch_canister_logs : (fetch_canister_logs_args) -> (fetch_canister_logs_result) query;
+};
diff --git a/docs/reference/management-canister.md b/docs/reference/management-canister.md
index 0ade3d37..799dd96e 100644
--- a/docs/reference/management-canister.md
+++ b/docs/reference/management-canister.md
@@ -595,6 +595,12 @@ Cycle costs for management canister calls vary depending on subnet replication f
 
 Methods that require explicit cycle attachment (`create_canister`, `sign_with_ecdsa`, `sign_with_schnorr`, `vetkd_derive_key`, `http_request`) will fail if insufficient cycles are provided.
 
+## Candid interface
+
+The complete Candid interface definition for the management canister is available at [`ic.did`](_attachments/ic.did). This file defines all types and method signatures in machine-readable Candid format and can be used for binding generation and type checking.
+
+<!-- sync from .sources/portal/docs/references/_attachments/ic.did -->
+
 ## Next steps
 
 - [Canister lifecycle guide](../guides/canister-management/lifecycle.md) — practical workflows for creating, upgrading, and managing canisters
@@ -603,4 +609,4 @@ Methods that require explicit cycle attachment (`create_canister`, `sign_with_ec
 - [Bitcoin integration](../guides/chain-fusion/bitcoin.md) — building Bitcoin-native applications with chain-key signing
 - [IC interface specification](ic-interface-spec.md) — the complete formal specification
 
-<!-- Upstream: informed by dfinity/portal — docs/references/system-canisters/management-canister.mdx, docs/references/ic-interface-spec.md; dfinity/icskills — skills/cycles-management/SKILL.md -->
+<!-- Upstream: informed by dfinity/portal — docs/references/system-canisters/management-canister.mdx, docs/references/ic-interface-spec.md, docs/references/_attachments/ic.did; dfinity/icskills — skills/cycles-management/SKILL.md -->