More improvements to 3668 (#4632)

Arachnid · web-flow · commit e112de7cf847 · 2022-01-06T01:25:47.000Z
* Rename Durin to CCIP read and make edits for clarity

* Rewrite to use continuation-passing style

* Tweaks based on Makoto's feedback

* Add process diagram

* Update to use a list of URLs, and support multiple lookups

* Fix spelling error

* Rewrite to use GET

* Change response type to JSON
diff --git a/EIPS/eip-3668.md b/EIPS/eip-3668.md
@@ -56,7 +56,7 @@ In step 3, the client calls the original contract, supplying the `response` from
    │                     callbackFunction, extraData) │             │
    │◄─────────────────────────────────────────────────┤             │
    │                                                  │             │
-   │ RPC (sender, callData)                           │             │
+   │ HTTP request (sender, callData)                  │             │
    ├──────────────────────────────────────────────────┼────────────►│
    │                                                  │             │
    │ Response (result)                                │             │
@@ -125,69 +125,64 @@ function balanceOf(address addr) public view returns(uint balance) {
 Note that in this example the contract is returning `addr` in both `callData` and `extraData`, because it is required both by the gateway (in order to look up the data) and the callback function (in order to verify it). The contract cannot simply pass it to the gateway and rely on it being returned in the response, as this would give the gateway an opportunity to respond with an answer to a different query than the one that was initially issued.
 
 ### Gateway Interface
-The URLs returned by a contract may be of any schema, but this specification only defines how clients should handle HTTPS URLs. Compliant gateways MUST accept POST requests with a Content-Type of `application/json`, matching the following schema:
+The URLs returned by a contract may be of any schema, but this specification only defines how clients should handle HTTPS URLs.
+
+Given a URL returned in an `OffchainLookup`, the URL to query is composed by concatenating the lower-case 0x-prefixed hexadecimal representations of the `sender` and `callData`, separated by forward slashes ('/').
+
+For example, if a contract returns the following data in an `OffchainLookup`:
+
+```
+urls = ["https://example.com/gateway"]
+sender = "0xaabbccddeeaabbccddeeaabbccddeeaabbccddee"
+callData = "0x00112233"
+```
+
+The request URL to query is `https://example.com/gateway/0xaabbccddeeaabbccddeeaabbccddeeaabbccddee/0x00112233`.
+
+Compliant gateways MUST respond with a Content-Type of `application/json`, with the body adhering to the following JSON schema:
 ```
 {
-    id: string,
-    data: {
-        to: string,
-        data: string
+    "type": "object",
+    "properties": {
+        "data": {
+            "type": "string",
+            "description: "0x-prefixed hex string containing the result data."
+        }
     }
 }
 ```
 
-Where:
- - `id` - string - A request ID, which will be returned in the response.
- - `to` - string - The Ethereum address of the contract that reverted with `OffchainLookup`, in '0x' prefixed hex format.
- - `data` - string - The value of the `callData` argument from the `OffchainLookup` error, in '0x' prefixed hex format.
-
-Compliant gateways MUST respond with a Content-Type of `application/json`, matching the following schema:
-
+Unsuccessful requests MUST return the appropriate HTTP status code - for example, 404 if the `sender` address is not supported by this gateway, 400 if the `callData` is in an invalid format, 500 if the server encountered an internal error, and so forth. The Content-Type of a 4xx or 5xx response MUST also be `application/json`, with the body adhering to the following JSON schema:
 ```
 {
-    jobRunID: string,
-    statusCode: integer,
-    data: {
-        result: string
-    },
-    error: {
-        name: string,
-        message: string
+    "type": "object",
+    "properties": {
+        "message": {
+            "type": "string",
+            "description: "A human-readable error message."
+        }
     }
 }
 ```
 
-Where:
- - `jobRunID` - string - The request ID from the original request.
- - `statusCode` - number - A status code, matching the semantics in [RFC 2616 §6.1.1](https://datatracker.ietf.org/doc/html/rfc2616#section-6.1.1). 200 indicates a successful response.
- - `data` - object - Required if the status code is between 200 and 299, forbidden otherwise. Contains the response data.
-   - `result` - string - The response data from the call to the gateway, in '0x' prefixed hex format.
- - `error` - object - Required if the status code is between 400 and 599, forbidden otherwise. Contains the error information.
-   - `name` - string - A short human-readable message giving the nature of the error.
-   - `message` - string - A human-readable message describing the error.
-
 #### Example
 ```
 // Request
-curl -X POST --data '{"id": "1","data":{to:"0x226159d592E2b063810a10Ebf6dcbADA94Ed68b8", data: "0xd5fa2b00...", }}"}'
+curl -D - https://example.com/gateway/0x226159d592E2b063810a10Ebf6dcbADA94Ed68b8/0xd5fa2b00
 
 // Successful result
-{
-    "jobRunID": 1,
-    "statusCode": 200,
-    "data": {
-        "result": "0x12345678..."
-    }
-}
+    HTTP/2 200
+    content-type: application/json; charset=UTF-8
+    ...
+    
+    {"data": "0xdeadbeefdecafbad"}
 
 // Error result
-{
-    "jobRunID": 1,
-    "statusCode": 400,
-    "error": {
-        "name": "InvalidArgument",
-        "message": "Could not decode input data"
-    }
+    HTTP/2 404
+    content-type: application/json; charset=UTF-8
+    ...
+
+    {"message": "Gateway address not supported."}
 }
 ```
 
@@ -200,33 +195,24 @@ A client that supports CCIP read MUST make contract calls using the following pr
  3. If the function returns an error other than `OffchainLookup`, return it to the caller in the usual fashion.
  4. Otherwise, decode the `sender`, `urls`, `callData`, `callbackFunction` and `extraData` arguments from the `OffchainLookup` error.
  5. If the `sender` field does not match the address of the contract that was called, return an error to the caller and stop.
- 6. Make an HTTP POST request to one of the URLs specified in `urls`. The client may choose which URLs to try in which order, but SHOULD prioritise URLs earlier in the list over those later in the list. POST requests are formatted as specified in [Gateway Interface](#gateway-interface).
- 7. If the response code from step (5) is in the range 400-499, return an error to the caller and stop.
- 8. If the response code from step (5) is in the range 500-599, go back to step (5) and pick a different URL, or stop if there are no further URLs to try.
- 9. Otherwise, replace `data` with an ABI-encoded call to the contract function specified by the 4-byte selector `callbackFunction`, supplying `data.result` from step (6) and `extraData` from step (4), and return to step (1).
+ 6. Construct a request URL by concatenating one of the URLs specified in `urls`, the lowercase 0x-prefixed hexadecimal representation of `sender`, and the lowercase 0x-prefixed hexadecimal representation of `callData`, separated by forward slashes ('/'). The client may choose which URLs to try in which order, but SHOULD prioritise URLs earlier in the list over those later in the list.
+ 7. Make an HTTP GET request to the request URL.
+ 8. If the response code from step (5) is in the range 400-499, return an error to the caller and stop.
+ 9. If the response code from step (5) is in the range 500-599, go back to step (5) and pick a different URL, or stop if there are no further URLs to try.
+ 10. Otherwise, replace `data` with an ABI-encoded call to the contract function specified by the 4-byte selector `callbackFunction`, supplying the data returned from step (7) and `extraData` from step (4), and return to step (1).
+
+Clients MUST handle HTTP status codes appropriately, employing best practices for error reporting and retries.
 
 This protocol can result in multiple lookups being requested by the same contract. Clients MUST implement a limit on the number of lookups they permit for a single contract call, and this limit SHOULD be at least 4.
 
 The lookup protocol for a client is described with the following pseudocode:
 
 ```javascript
-async function rpccall(urls, to, callData) {
+async function httpcall(urls, to, callData) {
     for(const url of urls) {
-        const response = await fetch(
-            url,
-            {
-                method: "POST",
-                "headers": {"Content-Type":"application/json"},
-                "body": JSON.stringify({
-                    "id": "1",
-                    "data": {
-                        "address": to,
-                        "data": callData
-                    }
-                })
-            }
-        );
-        const result = await response.json();
+        const queryUrl = `${url}/${to.toLowerCase()}/${callData.toLowerCase()}`;
+        const response = await fetch(queryUrl);
+        const result = await response.text();
         if(result.statusCode >= 400 && result.statusCode <= 499) {
             throw new Error(data.error.message);
         }
@@ -247,8 +233,8 @@ async function durin_call(provider, to, data) {
             if(sender !== to) {
                 throw new Error("Cannot handle OffchainLookup raised inside nested call");
             }
-            const result = rpccall(urls, to, callData);
-            data = abi.encodeWithSelector(callbackFunction, result.result, extraData);
+            const result = httpcall(urls, to, callData);
+            data = abi.encodeWithSelector(callbackFunction, result, extraData);
         }
     }
     throw new Error("Too many CCIP read redirects");
@@ -284,8 +270,8 @@ Using a revert, and conveying the required information in the revert data, allow
 ### Existence of `extraData` argument
 `extraData` allows the original contract function to pass information to a subsequent invocation. Since contracts are not persistent, without this data a contract has no state from the previous invocation. Aside from allowing arbitrary contextual information to be propagated between the two calls, this also allows the contract to verify that the query the gateway answered is in fact the one the contract originally requested.
 
-### Use of JSON for the gateway interface
-JSON is widely used as a low-overhead way of making RPC calls over HTTP. We have used it here in order to minimise cognitive and tooling overhead for developers.
+### Use of GET requests for the gateway interface
+Using a GET request, with query data encoded in the URL, minimises complexity and enables entirely static implementations of gateways - in some applications a gateway can simply be an HTTP server or IPFS instance with a static set of responses in text files.
 
 ## Backwards Compatibility
 Existing contracts that do not wish to use this specification are unaffected. Clients can add support for CCIP read to all contract calls without introducing any new overhead or incompatibilities.
