JSON RPC Error codes standardization: open-rpc extension specs [A Sample implementation]

package.json

@@ -34,6 +34,9 @@
     "@graphql-inspector/core": "~3.3.0",
     "@open-rpc/generator": "^2.1.0",
     "@open-rpc/schema-utils-js": "^2.1.2",
+    "@open-rpc/extensions": "^0.0.2",
+    "@open-rpc/specification-extension-spec": "^1.0.2",
+    "@open-rpc/meta-schema": "^1.14.2",
     "gatsby": "^5.14.3",
     "graphql": "~16.3.0",
     "graphql-request": "~4.1.0",

scripts/build.js

@@ -2,6 +2,7 @@ import fs from "fs";
 import yaml from "js-yaml";
 import mergeAllOf from "json-schema-merge-allof";
 import { dereferenceDocument } from "@open-rpc/schema-utils-js";
+import  { XErrorGroupsJSON } from "@open-rpc/extensions";
 
 function sortByMethodName(methods) {
   return methods.slice().sort((a, b) => {
@@ -79,6 +80,49 @@ schemaFiles.forEach(file => {
   };
 });
 
+let extensionSpecs = [];
+let extensionSpecsBase = "src/extensions/"
+let extensionsSpecsFiles = fs.readdirSync(extensionSpecsBase);
+extensionsSpecsFiles.forEach(file => {
+  console.log(file);
+  // skip if directory
+  if (fs.lstatSync(extensionSpecsBase + file).isDirectory()) {
+    return;
+  }
+  let raw = fs.readFileSync(extensionSpecsBase + file);
+  let parsed = yaml.load(raw);
+  extensionSpecs.push(parsed);
+});
+
+// Enhance the existing XErrorGroupsJSON extension with conditional validation for different error categories
+const enhancedErrorGroupSchema = JSON.parse(fs.readFileSync('src/extensions/schemas/x-error-category-ranges.json', 'utf8'));
+XErrorGroupsJSON.schema = enhancedErrorGroupSchema;
+
+extensionSpecs.push(XErrorGroupsJSON);
+
+let extensions = [];
+let extensionsBase = "src/extensions/components/"
+let extensionsFiles = fs.readdirSync(extensionsBase);
+extensionsFiles.forEach(file => {
+  console.log(file);
+  let raw = fs.readFileSync(extensionsBase + file);
+  let parsed = yaml.load(raw);  
+  extensions.push(parsed);
+});
+
+// if extensions key matches with extensionSpecs name, then add it to an array of extensionSpec name
+let extensionsDef = {};
+extensionSpecs.forEach((extensionSpec) => {
+  extensions.forEach((extension) => {
+    if (extension.hasOwnProperty(extensionSpec.name)) {     
+      extensionsDef[extensionSpec.name] ={
+        ...extensionsDef[extensionSpec.name],
+        ...extension[extensionSpec.name]  
+      }
+    }
+  });
+});
+
 const doc = {
   openrpc: "1.2.4",
   info: {
@@ -91,7 +135,9 @@ const doc = {
     version: "0.0.0"
   },
   methods: sortByMethodName(methods),
+  "x-extensions": extensionSpecs,
   components: {
+    ...extensionsDef,
     schemas: schemas
   }
 }

scripts/validate.js

@@ -1,13 +1,19 @@
 import fs from "fs";
 import { 
   parseOpenRPCDocument,
+  dereferenceDocument,
   validateOpenRPCDocument
 } from "@open-rpc/schema-utils-js";
+import OpenrpcDocument from "@open-rpc/meta-schema";
 
 let rawdata = fs.readFileSync("openrpc.json");
 let openrpc = JSON.parse(rawdata);
 
-const error = validateOpenRPCDocument(openrpc);
+/** @type {OpenrpcDocument} */
+const document = openrpc;
+const dereffed = await dereferenceDocument(document);
+
+const error = validateOpenRPCDocument(dereffed);
 if (error != true) {
   console.log(error.name);
   console.log(error.message);

src/eth/submit.yaml

@@ -5,6 +5,19 @@
       required: true
       schema:
         $ref: '#/components/schemas/GenericTransaction'
+  x-error-group:    
+      - $ref: '#/components/x-error-group/JSONRPCNonStandardErrors'
+      - $ref: '#/components/x-error-group/JSONRPCStandardErrors'
+      - $ref: '#/components/x-error-group/GasErrors'
+      - $ref: '#/components/x-error-group/ExecutionErrors'
+      # Inline additional errors specific to this method
+      - 
+        - code: -31000
+          message: "Already known transaction"
+          data: "Transaction is already known to the transaction pool"
+        - code: -31001
+          message: "Invalid sender"
+          data: "Transaction sender is invalid."
   result:
     name: Transaction hash
     schema:
@@ -45,6 +58,19 @@
       required: true
       schema:
         $ref: '#/components/schemas/bytes'
+  x-error-group:    
+    - $ref: '#/components/x-error-group/JSONRPCNonStandardErrors'
+    - $ref: '#/components/x-error-group/JSONRPCStandardErrors'
+    - $ref: '#/components/x-error-group/GasErrors'
+    - $ref: '#/components/x-error-group/ExecutionErrors'
+    # Inline additional errors specific to this method
+    - 
+      - code: -31000
+        message: "Already known transaction"
+        data: "Transaction is already known to the transaction pool"
+      - code: -31001
+        message: "Invalid sender"
+        data: "Transaction sender is invalid."
   result:
     name: Transaction hash
     schema:

src/extensions/components/execution-errors.yaml

@@ -0,0 +1,22 @@
+x-error-group:
+  ExecutionErrors:
+    - code: -31600
+      message: "NONCE_TOO_LOW"
+      data: "Transaction nonce is lower than the sender account's current nonce"
+      x-error-category: "EXECUTION_ERRORS"
+    - code: -31601
+      message: "NONCE_TOO_HIGH"
+      data: "Transaction nonce is higher than the sender account's current nonce"
+      x-error-category: "EXECUTION_ERRORS"
+    - code: -31602
+      message: "EXECUTION_REVERTED"
+      data: "Execution is reverted by REVERT Opcode"
+      x-error-category: "EXECUTION_ERRORS"
+    - code: -31603
+      message: "INVALID_OPCODE"
+      data: "An invalid opcode was encountered during execution"
+      x-error-category: "EXECUTION_ERRORS"
+    - code: -31604
+      message: "OUT_OF_COUNTERS"
+      data: "Not enough step counters to continue the execution"
+      x-error-category: "EXECUTION_ERRORS"

src/extensions/components/gas-error-groups.yaml

@@ -0,0 +1,42 @@
+x-error-group:
+  GasErrors:
+    - code: -31800
+      message: "GAS_TOO_LOW"
+      data: "Transaction gas is too low / intrinsic gas too low"
+      x-error-category: "GAS_ERRORS"
+    - code: -31801
+      message: "OUT_OF_GAS"
+      data: "The transaction ran out of gas"
+      x-error-category: "GAS_ERRORS"
+    - code: -31802
+      message: "GAS_PRICE_TOO_LOW"
+      data: "Gas price too low / gas price below configured minimum gas price"
+      x-error-category: "GAS_ERRORS"
+    - code: -31803
+      message: "BLOCK_GAS_LIMIT_EXCEEDED"
+      data: "Tx gas limit exceeds max block gas limit / intrinsic gas exceeds gas limit"
+      x-error-category: "GAS_ERRORS"
+    - code: -31804
+      message: "FEE_CAP_EXCEEDED"
+      data: "Tx fee exceeds cap / max priority fee per gas higher than max fee per gas"
+      x-error-category: "GAS_ERRORS"
+    - code: -31805
+      message: "GAS_OVERFLOW"
+      data: "Gas overflow error"
+      x-error-category: "GAS_ERRORS"
+    - code: -31806
+      message: "INSUFFICIENT_TRANSACTION_PRICE"
+      data: "Transaction price must be greater than base fee / max fee per gas less than block base fee"
+      x-error-category: "GAS_ERRORS"
+    - code: -31807
+      message: "INVALID_MAX_PRIORITY_FEE_PER_GAS"
+      data: "Max priority fee per gas higher than 2^256-1"
+      x-error-category: "GAS_ERRORS"
+    - code: -31808
+      message: "INVALID_MAX_FEE_PER_GAS"
+      data: "Max fee per gas higher than 2^256-1"
+      x-error-category: "GAS_ERRORS"
+    - code: -31809
+      message: "INSUFFICIENT_FUNDS"
+      data: "Insufficient funds for gas * price + value"
+      x-error-category: "GAS_ERRORS"

src/extensions/components/rpc-non-standard-errors.yaml

@@ -0,0 +1,23 @@
+x-error-group:
+  JSONRPCNonStandardErrors:
+      - code: -32000
+        message: "Invalid input"
+        data: "Missing or invalid parameters"
+      - code: -32001
+        message: "Resource not found"
+        data: "Requested resource not found"
+      - code: -32002
+        message: "Resource unavailable"
+        data: "Requested resource not available"
+      - code: -32003
+        message: "Transaction rejected"
+        data: "Transaction creation failed"
+      - code: -32004
+        message: "Method not supported"
+        data: "Method is not implemented"
+      - code: -32005
+        message: "Limit exceeded"
+        data: "Request exceeds defined limit"
+      - code: -32006
+        message: "JSON-RPC version not supported"
+        data: "Version of JSON-RPC protocol is not supported"

src/extensions/components/rpc-standard-errors.yaml

@@ -0,0 +1,17 @@
+x-error-group:
+  JSONRPCStandardErrors:
+      - code: -32700
+        message: "Parse error"
+        data: "An error occurred on the server while parsing the JSON text"
+      - code: -32600
+        message: "Invalid request"
+        data: "The JSON sent is not a valid request object"
+      - code: -32601
+        message: "Method not found"
+        data: "The method does not exist / is not available"
+      - code: -32602
+        message: "Invalid params"
+        data: "Invalid method parameter(s)"
+      - code: -32603
+        message: "Internal error"
+        data: "Internal JSON-RPC error"

src/extensions/schemas/x-error-category-ranges.json

@@ -0,0 +1,57 @@
+{
+  "type": "array",
+  "items": {
+    "oneOf": [
+      {
+        "type": "array",
+        "items": {
+          "allOf": [
+            {
+              "type": "object",
+              "properties": {
+                "code": { "type": "integer", "description": "The code of the error." },
+                "message": { "type": "string", "description": "The message of the error." },
+                "data": {"description": "The data of the error." },
+                "x-error-category": { "type": "string"}
+              },
+              "required": ["code", "message"]
+            },
+            {
+              "if": {
+                "properties": {
+                  "x-error-category": { "const": "GAS_ERRORS" }
+                },
+                "required": ["x-error-category"]
+              },
+              "then": {
+                "properties": {
+                  "code": { "type": "integer", "minimum": -31999, "maximum": -31800 }
+                }
+              }
+            },
+            {
+              "if": {
+                "properties": {
+                  "x-error-category": { "const": "EXECUTION_ERRORS" }
+                },
+                "required": ["x-error-category"]
+              },
+              "then": {
+                "properties": {
+                  "code": { "type": "integer", "minimum": -31799, "maximum": -31600 }
+                }
+              }
+            }
+          ]
+        }
+      },
+      {
+        "type": "object",
+        "properties": {
+          "$ref": { "type": "string" }
+        },
+        "required": ["$ref"]
+      }
+    ]
+  }
+}