spec: clarify nominal cycles and subnet metrics semantics

Author: mraszyk

docs/references/ic-interface-spec/index.md

@@ -289,6 +289,23 @@ Once the IC frees the resources of a canister, its id, *cycle* balances, *contro
 
 :::
 
+#### Cost schedules {#cost-schedules}
+
+A subnet's *cost schedule* determines how the protocol charges canisters for resource use, such as instruction execution and memory usage. There are two schedules:
+
+- **Normal:** applies the protocol's ordinary resource charges in cycles.
+- **Free:** waives these resource charges, so they do not deduct cycles from canister balances.
+
+The cost schedule has no impact on explicit cycle burning: they are still burnt from canister balances.
+
+#### Nominal cycles {#nominal-cycles}
+
+*Nominal cycles* are accounting quantities used to measure consumption in cycle metrics.
+
+For resource charges, the nominal amount is the amount calculated under the [normal cost schedule](#cost-schedules). Under that schedule, the nominal charge equals the cycles actually charged. Under a free cost schedule, resource use such as instruction execution or memory usage still records the nominal charge in metrics, while the actual charge to canister balances is zero. Nominal consumption therefore measures the accounted cost even when no cycles are deducted from a canister's balance.
+
+Hence, nominal consumption metrics must not be interpreted as the number of cycles actually removed from circulation.
+
 #### Canister status {#canister-status}
 
 The canister status can be used to control whether the canister is processing calls:
@@ -519,7 +536,7 @@ The state tree contains information about the topology of the Internet Computer.
 
      - `num_canisters` (`nat`): The number of canisters on this subnet. This is a current value, not a counter, so it decreases when canisters are deleted.
      - `canister_state_bytes` (`nat`): The total size of the state in bytes currently taken by canisters on this subnet. This is a current value, not a counter. Recomputing it is expensive, so it is refreshed only every 10 blocks, at heights that are multiples of 10, and reads 0 until the first refresh after this subnet was created.
-     - `consumed_cycles_total` (`map`): The total number of cycles removed from circulation on this subnet since this subnet was created. Besides the cycles charged to the canisters currently on this subnet, this includes the cycles charged to canisters that have since been deleted, together with the balance those canisters still held when they were deleted, and the cycles consumed on behalf of the subnet itself rather than charged to any individual canister. Cycles that are charged in advance and later refunded are excluded once the refund is accounted for, so this value can also decrease. It's a map of two values, a low part of type `nat` and a high part of type `opt nat`.
+     - `consumed_cycles_total` (`map`): The total [nominal cycles](#nominal-cycles) accounted for by the subnet. This sums the historical consumption of canisters currently on the subnet and the subnet's retained accounting for deleted canisters (including their remaining balances at deletion) and consumption on behalf of the subnet itself. Refunds of prepaid charges reduce the total. Subnet splitting preserves canister histories and redistributes them with the canisters, so the original subnet loses their contribution and the new subnet inherits consumption from before its creation. The total can therefore decrease and is not limited to consumption that occurred on this subnet. It's a map of two values, a low part of type `nat` and a high part of type `opt nat`.
      - `update_transactions_total` (`nat`): The total number of transactions processed on this subnet since this subnet was created, i.e., the total number of messages executed in the replicated mode. The value is monotonically non-decreasing.
 
 

docs/references/ic-interface-spec/management-canister.md

@@ -877,15 +877,15 @@ The fields returned are:
 
 - `num_canisters` (`nat`): the number of canisters on the subnet. This is a current value, not a counter, so it decreases when canisters are deleted.
 
-- `canister_state_bytes` (`nat`): the total size in bytes of the state taken by canisters on the subnet. This is a current value, not a counter. Recomputing it is expensive, so it is refreshed only every 10 blocks, at heights that are multiples of 10, and can therefore be up to 10 blocks staler than the other fields. It reads 0 until the first refresh after the subnet was created.
+- `canister_state_bytes` (`nat`): the total size in bytes of the state taken by canisters on the subnet. This is a current value, not a counter. Recomputing it is expensive, so it is refreshed only every 10 blocks, at heights that are multiples of 10. It can be up to 10 blocks behind `block_height` and up to 9 blocks behind the other aggregates. It reads 0 until the first refresh after the subnet was created.
 
-- `consumed_cycles_total` (`nat`): the total number of cycles removed from circulation on the subnet. Besides the cycles charged to the canisters currently on the subnet, this includes the cycles charged to canisters that have since been deleted, together with the balance those canisters still held when they were deleted, and the cycles consumed on behalf of the subnet itself rather than charged to any individual canister. Cycles that are charged in advance and later refunded are excluded once the refund is accounted for, so this value can also decrease.
+- `consumed_cycles_total` (`nat`): the total [nominal cycles](./index.md#nominal-cycles) accounted for by the subnet. This sums the historical consumption of canisters currently on the subnet and the subnet's retained accounting for deleted canisters (including their remaining balances at deletion) and consumption on behalf of the subnet itself. Refunds of prepaid charges reduce the total. Subnet splitting preserves canister histories and redistributes them with the canisters, so the original subnet loses their contribution and the new subnet inherits consumption from before its creation. The total can therefore decrease and is not limited to consumption that occurred on this subnet.
 
 - `update_transactions_total` (`nat`): the total number of transactions processed on the subnet, i.e., the total number of messages executed in the replicated mode. The value is monotonically non-decreasing for a given subnet.
 
-- `million_round_instructions_total` (`nat`): the total number of instructions the subnet accounted for across the execution phases of all rounds, in units of one million and rounded up, so a value of `42` means 42 million instructions. Besides the executed Wasm instructions this also covers the fixed per-execution and per-canister overheads charged by the scheduler, and the charges for work performed outside of Wasm execution, such as compilation, chunk assembly, and snapshot operations. It is therefore not a Wasm instruction meter. The value is monotonically non-decreasing for a given subnet.
+- `million_round_instructions_total` (`nat`): the total number of instructions the subnet accounted for across the execution phases of all rounds, in units of one million and rounded up, so a value of `42` represents an underlying count from 41,000,001 through 42,000,000 instructions. Besides the executed Wasm instructions this also covers the fixed per-execution and per-canister overheads charged by the scheduler, and the charges for work performed outside of Wasm execution, such as compilation, chunk assembly, and snapshot operations. It is therefore not a Wasm instruction meter. The value is monotonically non-decreasing for a given subnet.
 
-`consumed_cycles_total`, `update_transactions_total`, and `million_round_instructions_total` cover the whole lifetime of the subnet, or the period since the respective metric was introduced for subnets that predate it.
+`update_transactions_total` and `million_round_instructions_total` cover the whole lifetime of the subnet, or the period since the respective metric was introduced for subnets that predate it.
 
 ### IC method `subnet_info` {#ic-subnet_info}
 

docs/references/management-canister.md

@@ -602,15 +602,15 @@ Returns subnet-wide metrics for a given subnet, which does not have to be the su
   - `block_height` (`nat`): the target subnet's current block height, i.e. the height of the block in whose execution the call is processed
   - `num_canisters` (`nat`): canisters on the subnet
   - `canister_state_bytes` (`nat`): total size of canister state in bytes
-  - `consumed_cycles_total` (`nat`): total cycles removed from circulation on the subnet
+  - `consumed_cycles_total` (`nat`): total [nominal cycles](ic-interface-spec/index.md#nominal-cycles) accounted for by the subnet
   - `update_transactions_total` (`nat`): total transactions processed on the subnet
   - `million_round_instructions_total` (`nat`): total instructions the subnet accounted for across the execution phases of all rounds, in units of one million and rounded up
 
-Only `block_height` is as of the block that processes the call. The other five fields are aggregates refreshed at block boundaries, so they describe an earlier block, and they are not refreshed in lockstep with each other. `canister_state_bytes` is the stalest: it is recomputed only every 10 blocks, at heights that are multiples of 10, so it can be up to 10 blocks behind the others, and it reads 0 until the first recomputation after the subnet was created.
+Only `block_height` is as of the block that processes the call. The other five fields are aggregates refreshed at block boundaries, so they describe an earlier block, and they are not refreshed in lockstep with each other. `canister_state_bytes` is the stalest: it is recomputed only every 10 blocks, at heights that are multiples of 10, so it can be up to 10 blocks behind `block_height` and up to 9 blocks behind the other aggregates, and it reads 0 until the first recomputation after the subnet was created.
 
-`update_transactions_total` and `million_round_instructions_total` only ever grow. `consumed_cycles_total` covers deleted canisters (including the balance they still held when deleted) and cycles consumed by the subnet itself, and it nets out refunds of cycles charged in advance, so it can decrease. `num_canisters` and `canister_state_bytes` are current values, not counters.
+`update_transactions_total` and `million_round_instructions_total` only ever grow. `consumed_cycles_total` sums the historical nominal consumption of current canisters and the subnet's retained accounting for deleted canisters (including their remaining balances at deletion) and consumption on behalf of the subnet itself. Nominal charges can increase this metric under a free cost schedule without deducting cycles from canister balances. Refunds reduce it, and subnet splitting redistributes canisters' historical contributions, so the total can decrease and can include consumption from before the receiving subnet was created. `num_canisters` and `canister_state_bytes` are current values, not counters.
 
-`million_round_instructions_total` counts the executed Wasm instructions plus the scheduler's per-execution and per-canister overheads and the charges for work outside Wasm execution (compilation, chunk assembly, snapshots), so it is not a Wasm instruction meter. Like the other counters, it covers the subnet's whole lifetime, or the period since the metric was introduced for subnets that predate it.
+`million_round_instructions_total` counts the executed Wasm instructions plus the scheduler's per-execution and per-canister overheads and the charges for work outside Wasm execution (compilation, chunk assembly, snapshots), so it is not a Wasm instruction meter. A reported value of `42` represents an underlying count from 41,000,001 through 42,000,000 instructions. Both instruction and transaction counters cover the subnet's whole lifetime, or the period since each metric was introduced for subnets that predate it.
 
 ### `subnet_info`
 

public/references/ic.did

@@ -510,25 +510,31 @@ type subnet_metrics_result = record {
     num_canisters : nat;
     // Total size in bytes of the state taken by canisters on the subnet. A
     // current value, not a counter. Recomputing it is expensive, so it is
-    // refreshed only every 10 blocks, at heights that are multiples of 10, and
-    // reads 0 until the first refresh after the subnet was created.
+    // refreshed only every 10 blocks, at heights that are multiples of 10. It
+    // can be up to 10 blocks behind block_height and up to 9 blocks behind the
+    // other aggregates. Reads 0 until the first refresh after subnet creation.
     canister_state_bytes : nat;
-    // Total cycles removed from circulation on the subnet: the cycles charged
-    // to the canisters currently on the subnet, plus those charged to canisters
-    // that have since been deleted together with the balance those canisters
-    // still held when deleted, plus those consumed on behalf of the subnet
-    // itself. Refunds of cycles charged in advance are netted out, so this
-    // value can also decrease.
+    // Nominal cycles record consumption at normal cost-schedule rates even
+    // when resource use is free; they are not a spendable balance.
+    // Total nominal cycles accounted for by the subnet: current canisters'
+    // historical consumption plus the subnet's retained accounting for deleted
+    // canisters (including their remaining balances at deletion) and consumption
+    // on behalf of the subnet itself. Free cost schedules can produce nominal
+    // charges without deducting cycles from canister balances. Refunds reduce
+    // the total. Subnet splitting redistributes canisters' histories, so the
+    // total can decrease and can include consumption from before the receiving
+    // subnet was created. It is not limited to consumption on this subnet.
     consumed_cycles_total : nat;
     // Total number of transactions processed on the subnet, i.e. the total
     // number of messages executed in the replicated mode. Monotonically
     // non-decreasing.
     update_transactions_total : nat;
     // Total instructions the subnet accounted for across the execution phases
     // of all rounds, in units of one million and rounded up: a value of 42
-    // means 42 million instructions. Besides the executed Wasm instructions it
-    // covers the fixed per-execution and per-canister overheads charged by the
-    // scheduler and the charges for work performed outside of Wasm execution,
+    // represents 41,000,001 through 42,000,000 instructions. Besides the executed
+    // Wasm instructions it covers the fixed per-execution and per-canister
+    // overheads charged by the scheduler and the charges for work performed
+    // outside of Wasm execution,
     // so it is not a Wasm instruction meter. Monotonically non-decreasing.
     // Unlike the four fields above, it has no counterpart under
     // `/subnet/<subnet_id>/metrics` in the certified state tree.