JSON RPC Error codes standardization using open-rpc extension specs

package.json

@@ -26,9 +26,12 @@
   "homepage": "https://github.com/ethereum/execution-apis#readme",
   "devDependencies": {
     "@graphql-inspector/core": "~3.3.0",
-    "@open-rpc/generator": "1.18.6",
-    "@open-rpc/schema-utils-js": "1.15.0",
-    "gatsby": "~4.16.0",
+    "@open-rpc/extensions": "^0.0.2",
+    "@open-rpc/generator": "^2.0.0",
+    "@open-rpc/meta-schema": "^1.14.2",
+    "@open-rpc/schema-utils-js": "2.1.0",
+    "@open-rpc/specification-extension-spec": "^1.0.2",
+    "gatsby": "^5.0.0",
     "gh-pages": "~4.0.0",
     "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,45 @@ 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);
+});
+
+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 +131,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,14 @@
+x-error-group:
+  ExecutionErrors:
+      - code: -31800
+        message: "Nonce too low"
+        data: "Transaction nonce is lower than the sender account's current nonce"
+      - code: -31801
+        message: "Nonce too high"
+        data: "Transaction nonce is higher than the sender account's current nonce"
+      - code: -31802
+        message: "Execution reverted"
+        data: "Execution is reverted by REVERT Opcode"
+      - code: -31803
+        message: "Invalid opcode"
+        data: "An invalid opcode was encountered during execution"

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

@@ -0,0 +1,32 @@
+x-error-group:
+  GasErrors:
+      - code: -31800
+        message: "Gas too low"
+        data: "Transaction gas is too low / intrinsic gas too low"
+      - code: -31801
+        message: "Out of gas"
+        data: "The transaction ran out of gas"
+      - code: -31802
+        message: "Gas Price too low"
+        data: "Gas price too low / gas price below configured minimum gas price"
+      - code: -31803
+        message: "Exceeded Block gas limit"
+        data: "Tx gas limit exceeds max block gas limit / intrinsic gas exceeds gas limit"
+      - code: -31804
+        message: "Exceeded Fee cap"
+        data: "Tx fee exceeds cap / max priority fee per gas higher than max fee per gas"
+      - code: -31805
+        message: "Gas overflow"
+        data: "Gas overflow error"
+      - code: -31806
+        message: "Price lower than the base fee"
+        data: "Transaction price must be greater than base fee / max fee per gas less than block base fee"
+      - code: -31807
+        message: "Max priority fee overflow"
+        data: "Max priority fee per gas higher than 2^256-1"
+      - code: -31808
+        message: "Max fee overflow"
+        data: "Max fee per gas higher than 2^256-1"
+      - code: -31809
+        message: "Insufficient funds"
+        data: "Insufficient funds for gas * price + value"

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"