feat(sync-call): [IC-1666] Endpoint for synchronous call requests

spec/index.md

@@ -536,6 +536,8 @@ The concrete mechanism that users use to send requests to the Internet Computer
 
 -   At `/api/v2/canister/<effective_canister_id>/call` the user can submit (asynchronous, potentially state-changing) calls.
 
+-   At `/api/v2/canister/<effective_canister_id>/sync_call` the user can submit (synchronous, potentially state-changing) calls.
+
 -   At `/api/v2/canister/<effective_canister_id>/read_state` or `/api/v2/subnet/<subnet_id>/read_state` the user can read various information about the state of the Internet Computer. In particular, they can poll for the status of a call here.
 
 -   At `/api/v2/canister/<effective_canister_id>/query` the user can perform (synchronous, non-state-changing) query calls.
@@ -554,7 +556,13 @@ This document does not yet explain how to find the location and port of the Inte
 
 ### Overview of canister calling {#http-call-overview}
 
-Users interact with the Internet Computer by calling canisters. By the very nature of a blockchain protocol, they cannot be acted upon immediately, but only with a delay. Moreover, the actual node that the user talks to may not be honest or, for other reasons, may fail to get the request on the way. This implies the following high-level workflow:
+Users interact with the Internet Computer by calling canisters. By the very nature of a blockchain protocol, they cannot be acted upon immediately, but only with a delay. Moreover, the actual node that the user talks to may not be honest or, for other reasons, may fail to get the request on the way.
+
+The Internet Computer has two HTTPS APIs for canister calling:
+- [*Asynchronous*](#http-async-call) canister calling, where the user must poll the Internet Computer for the status of the request.
+- [*Synchronous*](#http-sync-call) canister calling, where the user waits for a certified response from the Internet Computer for the initial call.
+
+#### Asynchronous canister calling {#http-async-call}
 
 1.  A user submits a call via the [HTTPS Interface](#http-interface). No useful information is returned in the immediate response (as such information cannot be trustworthy anyways).
 
@@ -613,6 +621,27 @@ Calls must stay in `replied` or `rejected` long enough for polling users to catc
 
 When asking the IC about the state or call of a request, the user uses the request id (see [Request ids](#request-id)) to read the request status (see [Request status](#state-tree-request-status)) from the state tree (see [Request: Read state](#http-read-state)).
 
+#### Synchronous canister calling {#http-sync-call}
+
+Unlike asynchronous canister calling, synchronous canister calling does not require the user to poll the Internet Computer for the status of the request. Instead, the user waits for a certified response from the Internet Computer for the initial call. However, The state transitions and semantics of the call are the same as for asynchronous canister calling.
+
+1.  A user submits a synchronous call via the [HTTPS Interface](#http-interface).
+
+2.  The IC asks the targeted canister if it is willing to accept this message and be charged for the expense of processing it. This uses the [Ingress message inspection](#system-api-inspect-message) API for normal calls. For calls to the management canister, the rules in [The IC management canister](#ic-management-canister) apply.
+
+3.  At some point, the IC may accept the call for processing and set its status to `received`. This indicates that the IC as a whole has received the call and plans on processing it (although it may still not get processed if the IC is under high load).
+
+4.  If the call is processed (sufficient resources, call not yet expired), it will be executed, for some calls this may be atomic, for others this involves multiple internal steps.
+
+5.  Eventually, a response will be produced which will be replied the user. The response can be a `reply`, indicating success, a `reject`, indicating some form of error.
+
+6.  In the case that the call has been retained for long enough before a response is generated, but the request has not expired yet, the IC can forget the response data and only remember the call as `done`, to prevent a replay attack.
+
+7. The user can also afterwards retrieve the state of the request via the [HTTPS Interface](#http-interface) for a certain amount of time.
+
+8.  Once the expiry time is past, the IC can prune the call and its response, and completely forget about it.
+
+
 ### Request: Call {#http-call}
 
 In order to call a canister, the user makes a POST request to `/api/v2/canister/<effective_canister_id>/call`. The request body consists of an authentication envelope with a `content` map with the following fields:
@@ -651,6 +680,50 @@ The functionality exposed via the [The IC management canister](#ic-management-ca
 
 :::
 
+### Request: Sync Call {#http-sync-call}
+A synchronous update call, or "call and await", is a type of update [call](#http-call) where the replica will wait with replying to the user until the call has been processed and the result has been added to the replicated state. This means the user will receive a certified result of the call, and thus __do not need to poll__ [`read_state`](#http-read-state) to determine the status of the call.
+In order to make a synchronous update call to a canister, the user makes a POST request to `/api/v2/canister/<effective_canister_id>/sync_call`. The request body consists of an authentication envelope with a `content` map with the following fields:
+
+-   `request_type` (`text`): Always `sync-call`
+
+-   `sender`, `nonce`, `ingress_expiry`: See [Authentication](#authentication)
+
+-   `canister_id` (`blob`): The principal of the canister to call.
+
+-   `method_name` (`text`): Name of the canister method to call
+
+-   `arg` (`blob`): Argument to pass to the canister method
+
+The HTTP response to this request can have the following responses:
+
+-   202 HTTP status with a non-empty body. Implying the request was processed.
+    -   `response` (`blob`): A certificate (see [Certification](#certification)).
+
+The returned certificate includes the subtree at `/request_status/<request_id>` and `/time`.
+
+-   200 HTTP status with a non-empty body. Implying an execution pre-processing error occurred. The body of the response contains more information about the IC specific error encountered. The body is a CBOR map with the following fields:
+
+    -   `reject_code` (`nat`): The reject code (see [Reject codes](#reject-codes)).
+
+    -   `reject_message` (`text`): a textual diagnostic message.
+
+    -   `error_code` (`text`): an optional implementation-specific textual error code (see [Error codes](#error-codes)).
+
+-   4xx HTTP status for client errors (e.g. malformed request). Except for 429 HTTP status, retrying the request will likely have the same outcome.
+
+-   5xx HTTP status when the server has encountered an error or is otherwise incapable of performing the request. The request might succeed if retried at a later time.
+
+This request type can *also* be used to call a query method (but not a composite query method). A user may choose to go this way, instead of via the faster and cheaper [Request: Query call](#http-query) below, if they want to get a *certified* response. Note that the canister state will not be changed by sending a call request type for a query method (except for cycle balance change due to message execution).
+
+:::note
+
+The functionality exposed via the [The IC management canister](#ic-management-canister) can be used this way.
+
+:::
+
+See [The system state tree](#state-tree) for details on the state tree.
+
+
 ### Request: Read state {#http-read-state}
 
 :::note