add spec for portal_historyTraceRecursiveFindContent (#236)

* add spec for portal_historyTraceRecursiveFindContent * clarify description of the durationMs
ethereum · Oct 27, 2023 · 8ad5bc3 · 8ad5bc3
1 parent 0905bd5
commit 8ad5bc3
Show file tree

Hide file tree

Showing 3 changed files with 133 additions and 6 deletions.
diff --git a/jsonrpc/src/content/results.json b/jsonrpc/src/content/results.json
@@ -162,11 +162,11 @@
     "schema": {
       "type": "object",
       "required": [
-        "contentValue",
+        "content",
         "utpTransfer"
       ],
       "properties": {
-        "contentValue": {
+        "content": {
           "description": "Hex encoded content value",
           "$ref": "#/components/schemas/hexString"
         },
@@ -177,19 +177,39 @@
       }
     }
   },
-  "LocalContentResult": {
-    "name": "LocalContentResult",
-    "description": "Returns the hex encoded content value. If the content is not available, returns \"0x\"",
+  "TraceRecursiveFindContentResult": {
+    "name": "TraceRecursiveFindContentResult",
+    "description": "Returns the hex encoded content value and trace data object. If the content is not available, returns \"0x\"",
     "schema": {
       "type": "object",
+      "required": [
+        "content",
+        "utpTransfer",
+        "trace"
+      ],
       "properties": {
-        "contentValue": {
+        "content": {
           "description": "Hex encoded content value",
           "$ref": "#/components/schemas/hexString"
+        },
+        "utpTransfer": {
+          "description": "Indicates whether the content was transferred over a uTP connection or not.",
+          "type": "boolean"
+        },
+        "trace": {
+          "description": "Contains trace data for the request.",
+          "$ref": "#/components/schemas/traceResultObject"
         }
       }
     }
   },
+  "LocalContentResult": {
+    "name": "LocalContentResult",
+    "description": "Returns the hex encoded content value. If the content is not available, returns \"0x\"",
+    "schema": {
+      "$ref": "#/components/schemas/hexString"
+    }
+  },
   "GossipResult": {
     "name": "gossipResult",
     "description": "Returns the number of peers that the content was gossiped to",

diff --git a/jsonrpc/src/methods/history.json b/jsonrpc/src/methods/history.json
@@ -139,6 +139,18 @@
       "$ref": "#/components/contentDescriptors/RecursiveFindContentResult"
     }
   },
+  {
+    "name": "portal_historyTraceRecursiveFindContent",
+    "summary": "Look up a target content key in the network and get tracing data",
+    "params": [
+      {
+        "$ref": "#/components/contentDescriptors/ContentKey"
+      }
+    ],
+    "result": {
+      "$ref": "#/components/contentDescriptors/TraceRecursiveFindContentResult"
+    }
+  },
   {
     "name": "portal_historyStore",
     "summary": "Store history content key with content data",

diff --git a/jsonrpc/src/schemas/trace.json b/jsonrpc/src/schemas/trace.json
@@ -0,0 +1,95 @@
+{
+  "traceResultObject": {
+    "title": "traceResultObject",
+    "description": "Trace data for the result of tracing content request.",
+    "type": "object",
+    "required": [
+      "origin",
+      "targetId",
+      "responses",
+      "metadata",
+      "startedAtMs"
+    ],
+    "properties": {
+      "origin": {
+        "description": "Local Node ID",
+        "$ref": "#/components/schemas/uint256"
+      },
+      "targetId": {
+        "description": "Target content ID",
+        "$ref": "#/components/schemas/uint256"
+      },
+      "receivedFrom": {
+        "description": "Node ID from which the content was received.",
+        "$ref": "#/components/schemas/uint256"
+      },
+      "responses": {
+        "$ref": "#/components/schemas/traceResultResponses"
+      },
+      "metadata": {
+        "$ref": "#/components/schemas/traceResultMetadata"
+      },
+      "startedAtMs": {
+        "type": "integer",
+        "minimum": 0,
+        "description": "Timestamp of the beginning of this request in milliseconds."
+      },
+      "cancelled": {
+        "description": "List of node IDs requests to which were sent but cancelled due to receiving content from somewhere else, before receiving response from those nodes.",
+        "$ref": "#/components/schemas/listOfNodeIds"
+      }
+    }
+  },
+  "listOfNodeIds": {
+    "title": "listOfNodeIds",
+    "description": "Contains list of nodes IDs.",
+    "type": "array",
+    "items": {
+      "$ref": "#/components/schemas/uint256"
+    }
+  },
+  "traceResultResponses": {
+    "title": "traceResultResponses",
+    "description": "Contains a map of remote node IDs with the node IDs each node responded with. For the node ID that is in the `receivedFrom` field, `respondedWith` MUST be empty array.",
+    "type": "object",
+    "additionalProperties": {
+      "$ref": "#/components/schemas/traceResultResponseItem"
+    }
+  },
+  "traceResultResponseItem": {
+    "title": "traceResultResponseItem",
+    "description": "Contains the node's response, including the duration of the request.",
+    "type": "object",
+    "properties" : {
+      "durationsMs": {
+        "description": "Time it took from the beginning of the lookup(JSON-RPC request) up to receiving this response.",
+        "type": "integer",
+        "minimum": 0
+      },
+      "respondedWith": {
+        "$ref": "#/components/schemas/listOfNodeIds"
+      }
+    }
+  },
+  "traceResultMetadata": {
+    "title": "traceResultMetadata",
+    "description": "Contains a map from node ID to the metadata object for that node.",
+    "type": "object",
+    "additionalProperties": {
+      "$ref": "#/components/schemas/traceResultMetadataObject"
+    }
+  },
+  "traceResultMetadataObject": {
+    "title": "traceResultMetadataObject",
+    "description": "Contains metadata for each node ID mentioned in the trace response.",
+    "type": "object",
+    "properties": {
+      "enr": {
+        "$ref": "#/components/schemas/Enr"
+      },
+      "distance": {
+        "$ref": "#/components/schemas/uint256"
+      }
+    }
+  }
+}