Specify the resource reservation mechanism (#257)

* Specify the resource reservation mechanism

Context:

  - https://forum.dfinity.org/t/23447
  - https://dashboard.internetcomputer.org/proposal/126094

This adds new fields to the management canister interface:

  - `reserved_cycles` to the result of `canister_status`.
  - `reserved_cycles_limit` to `canister_settings` and
    `definite_canister_settings`.

The corresponding fields are also added to the abstract state:

  - `reserved_balances`,
  - `reserved_balance_limits`.

Note that the naming matches the exiting naming of the main cycle
balance, which is `cycles` in the management canister and `balances` in
the abstract state.

A new unspecified function `cycles_to_reserve` models cycle reservation
for allocated resources depending on the old abstract state and the new
state of the canister (and its new allocation settings).

Since the reserved cycles also affect canister freezing, a new helper
function called `liquid_balance` is used to compute how many cycles
are available after taking the freezing limit and reserved cycles
into account.

* Apply suggestions from code review

Co-authored-by: mraszyk <[email protected]>

* Fix issues found by Martin

* Add a canister id parameter to cycles_to_reserve

* update changelog

---------

Co-authored-by: mraszyk <[email protected]>
Co-authored-by: Martin Raszyk <[email protected]>

spec/_attachments/ic.did

@@ -6,13 +6,15 @@ type canister_settings = record {
   compute_allocation : opt nat;
   memory_allocation : opt nat;
   freezing_threshold : opt nat;
+  reserved_cycles_limit : opt nat;
 };
 
 type definite_canister_settings = record {
   controllers : vec principal;
   compute_allocation : nat;
   memory_allocation : nat;
   freezing_threshold : nat;
+  reserved_cycles_limit : nat;
 };
 
 type change_origin = variant {
@@ -176,6 +178,7 @@ service ic : {
       memory_size: nat;
       cycles: nat;
       idle_cycles_burned_per_day: nat;
+      reserved_cycles: nat;
   });
   canister_info : (record {
       canister_id : canister_id;

spec/_attachments/interface-spec-changelog.md

@@ -6,6 +6,7 @@
 * Stop canister calls might be rejected upon timeout.
 * The IC sends a `user-agent` header with the value `ic/1.0` in canister HTTPS outcalls if the canister does not provide one.
 * Add a management canister method for retrieving node metrics.
+* Specify the resource reservation mechanism.
 
 ### 0.22.0 (2023-11-15) {#0_22_0}
 * Add metrics on subnet usage into the certified state tree and a new HTTP endpoint `/api/v2/subnet/<subnet_id>/read_state` for retrieving them.