A specification for the cycles minting canister.

docs/references/cmcspec.mdx

@@ -0,0 +1,241 @@
+import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
+
+# Cycles Minting Canister (CMC) API
+
+<MarkdownChipRow labels={["Reference"]} />
+
+## Overview
+
+The Cycles Minting Canister (CMC) is a system canister on the Internet Computer responsible for converting ICP tokens into **cycles**. It supports:
+
+- Topping up existing canisters
+- Creating new canisters
+- Depositing minted cycles into ledger-managed accounts
+- Fetching exchange rates and subnet configuration
+
+The CMC is governed entirely by the **NNS (Network Nervous System)** and receives configuration updates through proposals.
+
+## Configuration Parameters
+
+- **Conversion Rate Source**: The ICP/XDR exchange rate is **pushed** into the CMC by a dedicated *exchange rate canister*. This data reflects live market pricing and determines the ICP→cycles conversion.
+
+- **Governance Control**: All operations of the CMC — including upgrades, configuration, and authorized callers — are managed through NNS proposals.
+
+
+## API Endpoints
+
+The CMC exposes a set of core methods for converting ICP into cycles and interacting with subnet configuration. These include:
+
+- `notify_create_canister`: Processes an ICP payment by minting cycles and using them to create a new canister, assigning control to the specified principal and applying optional settings.
+- `notify_top_up`: Processes an ICP payment by minting cycles and sending them to an existing canister to increase its available balance.
+- `notify_mint_cycles`: Processes an ICP payment by minting cycles and depositing them into a cycles ledger account associated with a subaccount.
+- `create_canister`: Creates a canister using cycles directly attached to the call.
+- `get_icp_xdr_conversion_rate`: Returns the current ICP/XDR exchange rate with certification.
+- `get_subnet_types_to_subnets`: Lists available subnets grouped by their types.
+- `get_principals_authorized_to_create_canisters_to_subnets`: Indicates which principals are permitted to create canisters on which subnets.
+- `get_default_subnets`: Returns the subnets for general-purpose canister creation.
+- `get_build_metadata`: Displays internal version and build information for the CMC.
+
+
+## API Reference
+
+### `notify_create_canister`
+
+Creates a new canister after verifying an ICP payment recorded in the ICP Ledger.
+If the `subnet_selection field is omitted, the CMC will automatically choose a suitable subnet at random from the available options.
+
+The CMC expects the payment to follow a strict structure that encodes both the **intent** and the **recipient**:
+
+- The **destination account** of the ICP transfer must be the CMC's account with a subaccount derived from the intended controller's principal.
+- The **memo field** must explicitly indicate the intent to create a canister. This can be expressed as:
+  - A legacy 64-bit unsigned integer memo with value `0x41455243` (ASCII `"CREA"`)
+  - Or, for ICRC-1-compatible transfers (e.g., `icrc1_transfer`, `icrc2_transfer_from`), a memo blob equal to:
+    ```candid
+    "\43\52\45\41\00\00\00\00"
+    ```
+    which represents `"CREA"` padded to 8 bytes.
+
+- **Parameters:**
+  ```candid
+  record {
+    block_index: nat64;              // The ledger block containing the ICP payment
+    controller: principal;           // The principal who will control the new canister
+    settings: opt CanisterSettings;  // Optional settings like controllers, memory limits, etc.
+    subnet_type: opt text;           // Deprecated: legacy subnet selection
+    subnet_selection: opt SubnetSelection; // Preferred subnet selection method
+  }
+  ```
+
+- **Returns:**
+  ```candid
+  variant { Ok: principal; Err: NotifyError }
+  ```
+
+- **Notes:**
+  - The call is idempotent with respect to `block_index`; repeating it returns the same result.
+  - The controller must match the one encoded in the subaccount used for the payment.
+  - Only transactions that follow the exact memo format will be processed successfully.
+
+
+  ### `notify_top_up`
+
+  Tops up an existing canister by minting cycles based on an ICP payment recorded in the ICP Ledger.
+
+  The CMC expects the payment to follow a strict structure that encodes both the **intent** and the **target canister**:
+
+  - The **destination account** of the ICP transfer must be the CMC's account with a subaccount derived from the target canister’s principal.
+  - The **memo field** must explicitly indicate the intent to top up a canister. This can be expressed as:
+    - A legacy 64-bit unsigned integer memo with value `0x50555054` (ASCII `"PUPT"`)
+    - Or, for ICRC-1-compatible transfers (e.g., `icrc1_transfer`, `icrc2_transfer_from`), a memo blob equal to:
+      ```candid
+      "\50\55\50\54\00\00\00\00"
+      ```
+      which represents `"PUPT"` padded to 8 bytes.
+
+  - **Parameters:**
+    ```candid
+    record {
+      block_index: nat64;     // Block index of the ICP ledger payment
+      canister_id: principal; // Canister to be topped up
+    }
+    ```
+
+  - **Returns:**
+    ```candid
+    variant { Ok: nat; Err: NotifyError } // Number of cycles minted and sent
+    ```
+
+  - **Notes:**
+    - The subaccount used in the transfer must be derived from the target canister’s principal using the standard 32-byte encoding (see “Shared Logic” section).
+    - This method is idempotent by `block_index`: retrying the same request will return the same result if it already succeeded.
+    - Only transfers matching the expected structure and memo will be accepted.
+
+    ## `notify_mint_cycles`
+
+Mints cycles into a **cycles ledger account** based on an ICP payment recorded in the ICP Ledger.
+
+This method is used to deposit minted cycles into a specific subaccount in the **cycles ledger**. It supports minting from both legacy and ICRC-1-style transfers.
+
+The CMC expects the payment to follow a strict structure that encodes the **intent** and **destination**:
+
+- The **destination account** must be the CMC’s account with the subaccount matching the `to_subaccount` parameter.
+- The **memo field** must explicitly indicate the intent to mint cycles. This can be:
+  - For legacy `transfer` calls: a `u64` memo with value:
+    ```candid
+    0x544e494d  // ASCII "MINT"
+    ```
+  - For ICRC-1-compatible transfers (e.g., `icrc1_transfer`, `icrc2_transfer_from`): a `blob` memo equal to:
+    ```candid
+    "\4d\49\4e\54\00\00\00\00"
+    ```
+    which represents `"MINT"` padded to 8 bytes
+
+- **Parameters:**
+  ```candid
+  record {
+    block_index: nat64;         // Block index of the ICP ledger payment
+    to_subaccount: opt blob;    // 32-byte subaccount to credit in the cycles ledger
+    deposit_memo: opt blob;     // Optional application-specific memo
+  }
+  ```
+
+- **Returns:**
+  ```candid
+  variant {
+    Ok: record {
+      block_index: nat;  // Block index in the cycles ledger
+      minted: nat;       // Amount of cycles minted
+      balance: nat;      // Final balance of the cycles ledger account
+    };
+    Err: NotifyError;
+  }
+  ```
+
+- **Notes:**
+  - The caller must be authorized to invoke this method.
+  - The subaccount in the payment must match `to_subaccount` exactly.
+  - This method is idempotent by `block_index`.
+  - Both legacy and ICRC-1 memo formats are accepted if they correctly encode `"MINT"`.
+
+
+  ### `create_canister`
+
+Creates a new canister using cycles attached directly to the call (not from an ICP ledger payment).
+
+Unlike `notify_create_canister`, this method does not rely on an external ICP transaction. Instead, the calling canister must attach enough cycles to cover the creation cost.
+
+- If `subnet_selection` is omitted, the CMC will select a suitable subnet at random from the available subnets.
+- If `settings` is provided, it will override default configuration for the new canister.
+- If no `settings` are given, the calling principal becomes the sole controller.
+
+- **Parameters:**
+  ```candid
+  record {
+    settings: opt CanisterSettings;         // Optional settings: controller(s), allocations, limits, etc.
+    subnet_type: opt text;                  // (Deprecated) Legacy subnet type selection
+    subnet_selection: opt SubnetSelection;  // Preferred way to select the subnet
+  }
+  ```
+
+- **Returns:**
+  ```candid
+  variant { Ok: principal; Err: CreateCanisterError }
+  ```
+
+- **Notes:**
+  - This method requires cycles to be attached to the call.
+  - Returns the principal of the newly created canister.
+  - The result is **not idempotent** — calling it again will consume cycles and create a different canister.
+
+
+  ## Shared Logic
+
+### Canister Settings
+
+The `CanisterSettings` record allows configuration of the canister at the time of creation or through governance. Each field is optional and will default to system-provided values if not specified.
+
+```candid
+record {
+  controllers : opt vec principal;          // List of principals allowed to control the canister
+  compute_allocation : opt nat;             // Percentage (0-100) of guaranteed compute capacity
+  memory_allocation : opt nat;              // Memory reserved for the canister, in bytes
+  freezing_threshold : opt nat;             // Number of seconds the canister can go without being topped up before being frozen
+  reserved_cycles_limit : opt nat;          // Reserved minimum cycle balance for execution
+  log_visibility : opt variant {
+    controllers;
+    public;
+  };                                        // Visibility of canister logs
+  wasm_memory_limit : opt nat;              // Cap on wasm memory usage, in bytes
+  wasm_memory_threshold : opt nat;          // Threshold to trigger memory alerts or actions
+}
+```
+
+Unspecified fields are interpreted as:
+- `controllers`: Defaults to the caller of the method
+- Other fields: Use system-wide default configuration values
+
+---
+
+### Encoding a Principal into a Subaccount
+
+Several CMC methods require an ICP payment to be sent to a subaccount that encodes a principal (e.g., the controller of a new canister or the canister being topped up).
+
+To derive this subaccount, the principal is serialized and packed into a 32-byte array using the following logic:
+
+```motoko
+public func principalToSubAccount(id: Principal) : [Nat8] {
+    let p = Blob.toArray(Principal.toBlob(id));
+    Array.tabulate(32, func(i : Nat) : Nat8 {
+        if (i >= p.size() + 1) 0
+        else if (i == 0) (Nat8.fromNat(p.size()))
+        else (p[i - 1])
+    })
+};
+```
+
+This produces a 32-byte subaccount where:
+- The first byte contains the length of the principal
+- The next bytes contain the principal's raw byte encoding
+- The remainder is zero-padded to reach 32 bytes
+
+This convention ensures the CMC can determine which principal or canister an incoming payment was intended for.