feat: pay-as-you-go pricing and flexible outcalls (5.0.0)

CHANGELOG.md

@@ -1,3 +1,70 @@
+## 5.0.0
+
+Adds the pay-as-you-go pricing field and the flexible HTTPS outcall interface, and picks up
+`status_visibility`, which had not been regenerated since it landed upstream.
+
+### Breaking type changes (aligned to upstream `.did`)
+
+- `HttpRequestArgs` gains `pricing_version : ?Nat32`, selecting the pricing mechanism for an
+  outcall: `1` (legacy, the default, deprecated) or `2` (pay-as-you-go). Motoko requires every
+  field in a record literal, so existing callers that construct `HttpRequestArgs` by hand must
+  add `pricing_version = null` to construct one. Callers using the `Call` builders do not need to:
+  the builders set it themselves.
+
+### Additive changes
+
+- New method: `flexible_http_request` — a variant of `http_request` in which a committee of nodes
+  return their individual HTTP responses instead of the subnet reaching consensus on one.
+- New types: `FlexibleHttpRequestArgs`, `FlexibleHttpRequestResult`, `FlexibleHttpRequestErr`,
+  `HttpRequestResourceReport`.
+- New type: `StatusVisibility`, and `status_visibility` on `CanisterSettings` and
+  `DefiniteCanisterSettings`.
+
+### Builders, replacing the record wrappers
+
+`Call.httpRequest` is now a builder that always selects pricing version `2`, and
+`Call.flexibleHttpRequest` is its counterpart for the new endpoint.
+
+```motoko
+let response = await Call.httpRequest("https://example.com/api")
+  .withMethod(#post)
+  .withMaxResponseBytes(4_000)
+  .withExpectedRoundtripTimeMs(300)
+  .send();
+```
+
+- `Call.httpRequest` changes from `(IC.HttpRequestArgs) -> async IC.HttpRequestResult` to
+  `(Text) -> HttpRequest`, so every call site fails to compile until it is migrated. Switching the
+  pricing version underneath an unchanged call would have been silent; this is deliberate.
+- `Call.httpRequestFromArgs(args)` and `Call.flexibleHttpRequestFromArgs(args)` take existing
+  arguments, so a call site can migrate without rewriting how it builds them. Both overwrite
+  `pricing_version` with `2`.
+- `withExpected*` on both builders narrows the reservation. Under version `2` the attached cycles
+  are also the budget each node may spend, so anything left unset falls back to the most that
+  parameter could reach. Two defaults are worth knowing: a request with no `transform` reserves
+  nothing for one, and a flexible outcall's expected transformed size is capped at the block
+  budget divided by `min_responses`, since responses larger than that average cannot be delivered
+  together.
+- `getCost()` returns what `send()` will attach; `args()` returns the arguments as they stand.
+- `Call.Cost.httpRequestV2` and `Call.Cost.flexibleHttpRequest` price an outcall directly, via the
+  new `ic0.cost_http_request_v2` system API.
+
+### Removed
+
+- `Call.Cost.httpRequest`, which priced version `1`. Version `2` is the only pricing the package
+  wraps. `Prim.costHttpRequest` still exposes version `1` for callers that need it.
+
+### Toolchain
+
+These wrappers require a `moc` that surfaces `ic0.cost_http_request_v2` and
+`ic0.subnet_self_node_count` as the `costHttpRequestV2` and `subnetSelfNodeCount` primitives.
+`[requirements] moc` must be raised to that release before publishing; the pinned `1.7.0` does not
+have them.
+
+### Housekeeping
+
+- Refreshed `did/ic.did` from `dfinity/developer-docs`.
+
 ## 4.2.0
 
 ### Additive changes

did/ic.did

@@ -14,7 +14,13 @@ type snapshot_visibility = variant {
     allowed_viewers : vec principal;
 };
 
-type environment_variable = record { 
+type status_visibility = variant {
+    controllers;
+    public;
+    allowed_viewers : vec principal;
+};
+
+type environment_variable = record {
     name: text; 
     value: text;
 };
@@ -25,8 +31,11 @@ type canister_settings = record {
     memory_allocation : opt nat;
     freezing_threshold : opt nat;
     reserved_cycles_limit : opt nat;
+    minimum_incoming_canister_call_cycles : opt nat;
     log_visibility : opt log_visibility;
+    log_memory_limit : opt nat;
     snapshot_visibility : opt snapshot_visibility;
+    status_visibility : opt status_visibility;
     wasm_memory_limit : opt nat;
     wasm_memory_threshold : opt nat;
     environment_variables : opt vec environment_variable;
@@ -38,8 +47,11 @@ type definite_canister_settings = record {
     memory_allocation : nat;
     freezing_threshold : nat;
     reserved_cycles_limit : nat;
+    minimum_incoming_canister_call_cycles : nat;
     log_visibility : log_visibility;
+    log_memory_limit : nat;
     snapshot_visibility : snapshot_visibility;
+    status_visibility : status_visibility;
     wasm_memory_limit : nat;
     wasm_memory_threshold : nat;
     environment_variables : vec environment_variable;
@@ -112,6 +124,34 @@ type http_request_result = record {
     body : blob;
 };
 
+type http_request_resource_report = record {
+    raw_response_bytes : opt variant { used : nat64; exceeded : reserved };
+    http_roundtrip_time_ms : opt variant { used : nat64; exceeded : reserved };
+    transform_instructions : opt variant { used : nat64; exceeded : reserved };
+    transformed_response_bytes : opt variant { used : nat64; exceeded : reserved };
+    cycles : opt variant { used : nat; exceeded : reserved };
+};
+
+type flexible_http_request_err = record {
+    global_error : opt variant {
+        timeout : reserved;
+        out_of_cycles : reserved;
+        responses_too_large : reserved;
+        too_many_rejects : reserved;
+    };
+    node_details : vec record {
+        node_id : principal;
+        report : http_request_resource_report;
+        error : opt record { code : text; message : text };
+    };
+    message : text;
+};
+
+type flexible_http_request_result = variant {
+    ok : vec http_request_result;
+    err : flexible_http_request_err;
+};
+
 type ecdsa_curve = variant {
     secp256k1;
 };
@@ -300,6 +340,7 @@ type canister_status_result = record {
         canister_history_size : nat;
         wasm_chunk_store_size : nat;
         snapshots_size : nat;
+        log_memory_store_size : nat;
     };
     cycles : nat;
     reserved_cycles : nat;
@@ -352,6 +393,24 @@ type http_request_args = record {
         context : blob;
     };
     is_replicated : opt bool;
+    pricing_version : opt nat32;
+};
+
+type flexible_http_request_args = record {
+    url : text;
+    max_response_bytes : opt nat64;
+    method : variant { get; head; post; put; delete; patch };
+    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;
+    };
+    replication : opt record {
+        min_responses : nat32;
+        max_responses : nat32;
+        total_requests : nat32;
+    };
 };
 
 type ecdsa_public_key_args = record {
@@ -499,6 +558,10 @@ type delete_canister_snapshot_args = record {
 
 type fetch_canister_logs_args = record {
     canister_id : canister_id;
+    filter : opt variant {
+        by_idx : record { start : nat64; end : nat64 };
+        by_timestamp_nanos : record { start : nat64; end : nat64 };
+    };
 };
 
 type canister_log_record = record {
@@ -672,9 +735,10 @@ service ic : {
     deposit_cycles : (deposit_cycles_args) -> ();
     raw_rand : () -> (raw_rand_result);
     http_request : (http_request_args) -> (http_request_result);
+    flexible_http_request : (flexible_http_request_args) -> (flexible_http_request_result);
 
     // Public canister data
-    canister_info : (canister_info_args) -> (canister_info_result);
+    canister_info : (canister_info_args) -> (canister_info_result) query;
     canister_metadata : (canister_metadata_args) -> (canister_metadata_result);
 
     // Threshold ECDSA signature

mops.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ic"
-version = "4.2.0"
+version = "5.0.0"
 description = "IC management canister interface (aaaaa-aa)"
 repository = "https://github.com/caffeinelabs/mops-ic"
 keywords = ["ic", "types", "interface", "http"]