New HTTP outcalls pricing model

docs/references/_attachments/ic.did

@@ -324,6 +324,7 @@ type http_request_args = record {
         context : blob;
     };
     is_replicated : opt bool;
+    pricing_version : opt nat32;
 };
 
 type ecdsa_public_key_args = record {

docs/references/ic-interface-spec.md

@@ -1519,6 +1519,12 @@ The 32-bit stable memory System API (`ic0.stable_size`, `ic0.stable_grow`, `ic0.
 
 :::
 
+:::note
+
+The `ic0.cost_http_request` System API call is DEPRECATED. Canister developers are advised to use the `ic0.cost_http_request_v2` call instead.
+
+:::
+
 The following sections describe various System API functions, also referred to as system calls, which we summarize here.
 
 All the following functions belong to the `ic0` module (denoted by the prefix `ic0.`).
@@ -1601,6 +1607,7 @@ defaulting to `I = i32` if the canister declares no memory.
     ic0.cost_call : (method_name_size: i64, payload_size : i64, dst : I) -> ();           // * s
     ic0.cost_create_canister : (dst : I) -> ();                                           // * s
     ic0.cost_http_request : (request_size : i64, max_res_bytes : i64, dst : I) -> ();     // * s
+    ic0.cost_http_request_v2 : (params_src : I, params_size : I, dst : I) -> ();          // * s
     ic0.cost_sign_with_ecdsa : (src : I, size : I, ecdsa_curve: i32, dst : I) -> i32;     // * s
     ic0.cost_sign_with_schnorr : (src : I, size : I, algorithm: i32, dst : I) -> i32;     // * s
     ic0.cost_vetkd_derive_key : (src : I, size : I, vetkd_curve: i32, dst : I) -> i32;  // * s
@@ -2197,14 +2204,48 @@ These system calls return costs in Cycles, represented by 128 bits, which will b
 
 -   `ic0.cost_http_request(request_size : i64, max_res_bytes : i64, dst : I) -> ()`; `I ∈ {i32, i64}`
 
-    The cost of a canister http outcall via [`http_request`](#ic-http_request). `request_size` is the sum of the byte lengths of the following components of an http request: 
+    :::note
+
+    The `ic0.cost_http_request` System API call is DEPRECATED. Canister developers are advised to use the `ic0.cost_http_request_v2` call instead.
+
+    :::
+
+    The cost of a canister HTTP outcall via [`http_request`](#ic-http_request) with the pricing version set to `1` (currently the default). `request_size` is the sum of the byte lengths of the following components of an http request:
     - url
     - headers - i.e., the sum of the lengths of all keys and values 
     - body
     - transform - i.e., the sum of the transform method name length and the length of the transform context
 
     `max_res_bytes` is the maximum response length the caller wishes to accept (the caller should provide the default value of `2,000,000` if no maximum response length is provided in the actual request to the management canister). 
 
+-   `ic0.cost_http_request_v2(params_src: I, params_size: I, dst : I) -> ();    I ∈ {i32, i64}`
+
+    The cost of a canister HTTP outcall via [`http_request`](#ic-http_request) with the pricing version set to `2`. The blob described by `params_src` and `params_size` must be a valid Candid encoding of a value of the following type:
+    ```
+    record {
+        request_bytes : nat64;
+        http_roundtrip_time_ms : nat64;
+        raw_response_bytes : nat64;
+        transformed_response_bytes : nat64;
+        transform_instructions: nat64;
+    }
+    ```
+
+    The function may trap if `params_src` and `params_size` do not describe a valid Candid encoding of a value of the above type, or if the encoding contains additional fields other than the ones above. The function returns the cycle cost of an HTTP outcall whose execution uses up exactly the amount of resources specified by the individual fields:
+    - `request_bytes` is the sum of the byte lengths of the following components of an HTTP request:
+      - `url`
+      - `headers` - i.e., the sum of the lengths of all keys and values
+      - `body`
+      - `transform` - i.e., the sum of the transform method name length and the length of the transform context.
+
+    - `http_roundtrip_time_ms` is the amount of time between the time when the HTTP request starts being sent to the remote server and the time that the HTTP response is fully received (in milliseconds).
+
+    - `raw_response_bytes` is the length of the HTTP response.
+
+    - `transformed_response_bytes` is the length of the HTTP response after transformation.
+
+    - `transform_instructions` is the number of instructions the transform function takes.
+
 -   `ic0.cost_sign_with_ecdsa(src : I, size : I, ecdsa_curve: i32, dst : I) -> i32`; `I ∈ {i32, i64}`
 
 -   `ic0.cost_sign_with_schnorr(src : I, size : I, algorithm: i32, dst : I) -> i32`; `I ∈ {i32, i64}`
@@ -2906,7 +2947,7 @@ The following parameters should be supplied for the call:
 
 -   `url` - the requested URL. The URL must be valid according to [RFC-3986](https://www.ietf.org/rfc/rfc3986.txt), it might contain non-ASCII characters according to [RFC-3987](https://www.ietf.org/rfc/rfc3987.txt), and its length must not exceed `8192`. The URL may specify a custom port number.
 
--   `max_response_bytes` - optional, specifies the maximal size of the response in bytes. If provided, the value must not exceed `2MB` (`2,000,000B`). The call will be charged based on this parameter. If not provided, the maximum of `2MB` will be used.
+-   `max_response_bytes` - optional, specifies the maximal size of the response in bytes. If provided, the value must not exceed `2MB` (`2,000,000B`). If not provided, the maximum of `2MB` will be used. When the `pricing_version` is set to `1`, the call will be charged based on this parameter. When the `pricing_version` is set to `2`, this field is ignored.
 
 -   `method` - currently, only GET, HEAD, and POST are supported
 
@@ -2918,13 +2959,17 @@ The following parameters should be supplied for the call:
 
 -   `is_replicated` - optional, selecting between replicated and non-replicated modes.
 
-:::note
-
-The `is_replicated` field is considered EXPERIMENTAL.
+    :::note
+
+    The `is_replicated` field is considered EXPERIMENTAL.
+
+    :::
 
-:::
+-   `pricing_version` - the version of the pricing mechanism for HTTP outcalls that should be applied to this call; it can be either `1` or `2`. For compatibility reasons, the default is `1`; however, version `1` is deprecated.
 
-Cycles to pay for the call must be explicitly transferred with the call, i.e., they are not automatically deducted from the caller's balance implicitly (e.g., as for inter-canister calls).
+Cycles to pay for the call must be explicitly transferred with the call, i.e., they are not automatically deducted from the caller's balance implicitly (e.g., as for inter-canister calls). Extraneous cycles are refunded:
+- with pricing version `1`, the difference between the attached cycles and the cost returned by the `ic0.cost_http_request` API with the appropriate parameters
+- with pricing version `2`, any attached cycles exceeding those used by the outcall execution.
 
 The returned response (and the response provided to the `transform` function, if specified) contains the following fields:
 
@@ -8646,6 +8691,10 @@ I ∈ {i32, i64}
 ic0.cost_http_request<es>(request_size: i64, max_res_bytes: i64, dst: I) : () = 
   copy_cycles_to_canister<es>(dst, arbitrary())
 
+I ∈ {i32, i64}
+ic0.cost_http_request_v2<es>(params_src : I, params_size : I, dst : I) : ()= 
+  copy_cycles_to_canister<es>(dst, arbitrary())
+
 I ∈ {i32, i64}
 ic0.cost_sign_with_ecdsa<es>(src: I, size: I, ecdsa_curve: i32, dst: I) : i32 = 
   known_keys = arbitrary()