diff --git a/package-lock.json b/package-lock.json index 63b8c2590..fccde036b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -11,8 +11,11 @@ "dependencies": { "@graphql-inspector/core": "~3.3.0", "@mdx-js/react": "~3.0.0", + "@open-rpc/extensions": "^0.0.2", "@open-rpc/generator": "^2.1.0", + "@open-rpc/meta-schema": "^1.14.2", "@open-rpc/schema-utils-js": "^2.1.2", + "@open-rpc/specification-extension-spec": "^1.0.2", "gatsby": "^5.14.3", "graphql": "~16.3.0", "graphql-request": "~4.1.0", @@ -2976,6 +2979,12 @@ "node": ">= 8" } }, + "node_modules/@open-rpc/extensions": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/@open-rpc/extensions/-/extensions-0.0.2.tgz", + "integrity": "sha512-+sbOGMiY4dFsl8hvdizpdpxQmdjJIYJP87lz9uRKc71RIZGDPngve0Ad4BIyqQ37EuVbRejOXdwWGi8IjL6dLw==", + "license": "Apache-2.0" + }, "node_modules/@open-rpc/generator": { "version": "2.1.0", "resolved": "https://registry.npmjs.org/@open-rpc/generator/-/generator-2.1.0.tgz", diff --git a/package.json b/package.json index a7fa1934f..e20d9c1a0 100644 --- a/package.json +++ b/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", diff --git a/scripts/build.js b/scripts/build.js index 639081f7e..83be4c5a7 100644 --- a/scripts/build.js +++ b/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,37 @@ schemaFiles.forEach(file => { }; }); +let extensionSpecs = []; + +// 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 +123,9 @@ const doc = { version: "0.0.0" }, methods: sortByMethodName(methods), + "x-extensions": extensionSpecs, components: { + ...extensionsDef, schemas: schemas } } diff --git a/scripts/validate.js b/scripts/validate.js index c5f2efaab..eb88e2f0f 100644 --- a/scripts/validate.js +++ b/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); diff --git a/src/eth/submit.yaml b/src/eth/submit.yaml index dc5a93dfa..529672233 100644 --- a/src/eth/submit.yaml +++ b/src/eth/submit.yaml @@ -5,6 +5,12 @@ 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' + - $ref: '#/components/x-error-group/TxPoolErrors' result: name: Transaction hash schema: @@ -45,6 +51,12 @@ 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' + - $ref: '#/components/x-error-group/TxPoolErrors' result: name: Transaction hash schema: diff --git a/src/extensions/README.md b/src/extensions/README.md new file mode 100644 index 000000000..62db886ab --- /dev/null +++ b/src/extensions/README.md @@ -0,0 +1,113 @@ +# Extensions overview + +## Proposal +#### Goal +A standard for JSON-RPC error codes & ship a shared catalog of JSON-RPC error codes and messages for EVM clients to unlock consistent tooling and developer ergonomics. + +#### Motivation +Client implementations and EVM-compatible chains currently reuse codes or return generic error messages, making cross-client debugging brittle. + +#### Solution +The solution incorporates [OpenRPC's extension schemas](https://github.com/open-rpc/specification-extension-spec) feature, specifically `x-error-group` [extension](https://github.com/open-rpc/tools/blob/main/packages/extensions/src/x-error-groups/x-error-groups.json), so common scenarios can be bundled into reusable categories, each backed by a reserved range of **200 codes** between **-31999 and -30000** (outside the JSON-RPC 2.0 reserved bands). +With the error grouping and inline provisioning offered by the extension schemas, we could onboard methods over time with granular control over the errors or groups each method would need to handle without copy pasting in the final spec. + +The corresponding PR definition frames these groups as the canonical vocabulary for wallets, infra providers, and execution clients. + +## Solution Layout +- `components/` – YAML fragments exposing each error family as an OpenRPC `x-error-group` definition. +- `schemas/x-error-category-ranges.json` – Extension to official `x-error-groups` that enforces the reserved integer windows per category during validation. + - This is to achieve inbuild validation of the reserved ranges per category using native `minimum` & `maximum` properties of the extended schema. + - Validation happens while running `scripts/validate.js` after building the final `refs-openrpc.json` / `openrpc.json`. +- `scripts/build.js` – Loads the schema above, augments the `XErrorGroupsJSON` extension, and merges the groups into `refs-openrpc.json` / `openrpc.json`. + +## Implemented Methods +Currently, only below methods import all the error groups via `$ref` and may include inline method-specific codes while still inheriting the standard set. +- `eth_sendTransaction` in `src/eth/submit.yaml` +- `eth_sendRawTransaction` in `src/eth/submit.yaml` + + +## Reserved ranges at a glance +| Extension group | Category label | Reserved range | Source | +| --- | --- | --- | --- | +| JSON-RPC standard | — | $-32768$ to $-32000$ | JSON-RPC 2.0 spec | +| JSON-RPC non-standard | Client-specific | $-32099$ to $-32000$ | JSON-RPC 2.0 addendum | +| Gas errors | `GAS_ERRORS` | $-31999$ to $-31800$ | `gas-error-groups.yaml` | +| Execution errors | `EXECUTION_ERRORS` | $-31799$ to $-31600$ | `execution-errors.yaml` | +| (Future) consensus | — | $-31599$ to $-31400$ | +| (Future) networking | — | $-31399$ to $-31200$ | +| TxPool errors | `TXPOOL_ERRORS` | $-31199$ to $-31000$ | `txpool-errors.yaml` | + + +**Validation** of these bands happens through `XErrorGroupsJSON.schema` in `scripts/build.js`, so build failures flag any out-of-range additions early. + + +## Extending the catalog +1. Pick or create a YAML fragment under `components/` and add the new entry with `code`, `message`, `data`, and `x-error-category` per the proposal. +2. Stay within the reserved window; the JSON Schema guard in `schemas/x-error-category-ranges.json` will break the build if you drift. +3. Reference the group from the relevant method spec via `$ref: '#/components/x-error-group/'` and layer any bespoke errors inline. +4. Run the documentation build (e.g. `node scripts/build.js`) to regenerate `refs-openrpc.json` / `openrpc.json` and confirm validation passes. + +Following this flow keeps the execution client surface aligned with the standard and preserves interoperability for downstream consumers. + + +## Catalog reference + +### [JSON-RPC standard errors](https://www.jsonrpc.org/specification) (`rpc-standard-errors.yaml`) +| Code | Message | Notes | +| --- | --- | --- | +| $-32700$ | Parse error | An error occurred on the server while parsing the JSON text | +| $-32600$ | Invalid request | The JSON sent is not a valid request object | +| $-32601$ | Method not found | The method does not exist / is not available | +| $-32602$ | Invalid params | Invalid method parameter(s) | +| $-32603$ | Internal error | Internal JSON-RPC error | + +### [JSON-RPC non-standard errors](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1474.md) (`rpc-non-standard-errors.yaml`) +| Code | Message | Notes | +| --- | --- | --- | +| $-32000$ | Invalid input | Missing or invalid parameters | +| $-32001$ | Resource not found | Requested resource not found | +| $-32002$ | Resource unavailable | Requested resource not available | +| $-32003$ | Transaction rejected | Transaction creation failed | +| $-32004$ | Method not supported | Method is not implemented | +| $-32005$ | Limit exceeded | Request exceeds defined limit | +| $-32006$ | JSON-RPC version not supported | Version of JSON-RPC protocol is not supported | + +### Gas errors (`gas-error-groups.yaml`) +| Code | Message | Data | +| --- | --- | --- | +| $-31800$ | GAS_TOO_LOW | Transaction gas is too low / intrinsic gas too low | +| $-31801$ | OUT_OF_GAS | The transaction ran out of gas | +| $-31802$ | GAS_PRICE_TOO_LOW | Gas price too low / gas price below configured minimum gas price | +| $-31803$ | BLOCK_GAS_LIMIT_EXCEEDED | Tx gas limit exceeds max block gas limit / intrinsic gas exceeds gas limit | +| $-31804$ | FEE_CAP_EXCEEDED | Tx fee exceeds cap / max priority fee per gas higher than max fee per gas | +| $-31805$ | GAS_OVERFLOW | Gas overflow error | +| $-31806$ | INSUFFICIENT_TRANSACTION_PRICE | Transaction price must be greater than base fee / max fee per gas less than block base fee | +| $-31807$ | INVALID_MAX_PRIORITY_FEE_PER_GAS | Max priority fee per gas higher than $2^{256}-1$ | +| $-31808$ | INVALID_MAX_FEE_PER_GAS | Max fee per gas higher than $2^{256}-1$ | +| $-31809$ | INSUFFICIENT_FUNDS | Insufficient funds for gas * price + value | +| $-31810$ | TRANSACTION_UNDERPRICED | Transaction's gas price is below the minimum for txpool | +| $-31811$ | REPLACEMENT_TRANSACTION_UNDERPRICED | Replacement transaction is sent without the required price bump | + +### Execution errors (`execution-errors.yaml`) +| Code | Message | Data | +| --- | --- | --- | +| $-31600$ | NONCE_TOO_LOW | Transaction nonce is lower than the sender account's current nonce | +| $-31601$ | NONCE_TOO_HIGH | Transaction nonce is higher than the sender account's current nonce | +| $-31602$ | EXECUTION_REVERTED | Execution is reverted by REVERT Opcode | +| $-31603$ | INVALID_OPCODE | An invalid opcode was encountered during execution | +| $-31604$ | OUT_OF_COUNTERS | Not enough step counters to continue the execution | + +### TxPool errors (`txpool-errors.yaml`) +| Code | Message | Data | +| --- | --- | --- | +| $-31000$ | ALREADY_KNOWN | Transaction is already known to the transaction pool | +| $-31001$ | INVALID_SENDER | Transaction sender is invalid | +| $-31002$ | INVALID_SIGNATURE | Transaction signature is invalid | +| $-31003$ | TXPOOL_FULL | Transaction pool is full | +| $-31004$ | NEGATIVE_VALUE | Transaction with negative value | +| $-31005$ | OVERSIZED_DATA | Transaction input data exceeds the allowed limit | +| $-31006$ | SENDER_BLACKLISTED | Transaction sender is blacklisted | +| $-31007$ | RECEIVER_BLACKLISTED | Transaction receiver is blacklisted | +| $-31008$ | CHAIN_ID_MISMATCH | Transaction chain ID does not match the expected chain ID | +| $-31009$ | TX_NOT_PERMITTED | Transaction is protected and cannot be permitted for unauthorized users | +| $-31010$ | INVALID_RLP_DATA | Transaction Data contains invalid RLP encoding | diff --git a/src/extensions/components/execution-errors.yaml b/src/extensions/components/execution-errors.yaml new file mode 100644 index 000000000..b22541629 --- /dev/null +++ b/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" diff --git a/src/extensions/components/gas-error-groups.yaml b/src/extensions/components/gas-error-groups.yaml new file mode 100644 index 000000000..7efff8cb7 --- /dev/null +++ b/src/extensions/components/gas-error-groups.yaml @@ -0,0 +1,50 @@ +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" + - code: -31810 + message: "TRANSACTION_UNDERPRICED" + data: "Transaction's gas price is below the minimum for txpool" + x-error-category: "GAS_ERRORS" + - code: -31811 + message: "REPLACEMENT_TRANSACTION_UNDERPRICED" + data: "Replacement transaction is sent without the required price bump." + x-error-category: "GAS_ERRORS" diff --git a/src/extensions/components/rpc-non-standard-errors.yaml b/src/extensions/components/rpc-non-standard-errors.yaml new file mode 100644 index 000000000..13533f266 --- /dev/null +++ b/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" diff --git a/src/extensions/components/rpc-standard-errors.yaml b/src/extensions/components/rpc-standard-errors.yaml new file mode 100644 index 000000000..8807dac43 --- /dev/null +++ b/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" \ No newline at end of file diff --git a/src/extensions/components/txpool-errors.yaml b/src/extensions/components/txpool-errors.yaml new file mode 100644 index 000000000..89cf4d059 --- /dev/null +++ b/src/extensions/components/txpool-errors.yaml @@ -0,0 +1,46 @@ +x-error-group: + TxPoolErrors: + - code: -31000 + message: "ALREADY_KNOWN" + data: "Transaction is already known to the transaction pool" + x-error-category: "TXPOOL_ERRORS" + - code: -31001 + message: "INVALID_SENDER" + data: "Transaction sender is invalid" + x-error-category: "TXPOOL_ERRORS" + - code: -31002 + message: "INVALID_SIGNATURE" + data: "Transaction signature is invalid" + x-error-category: "TXPOOL_ERRORS" + - code: -31003 + message: "TXPOOL_FULL" + data: "Transaction pool is full" + x-error-category: "TXPOOL_ERRORS" + - code: -31004 + message: "NEGATIVE_VALUE" + data: "Transaction with negative value" + x-error-category: "TXPOOL_ERRORS" + - code: -31005 + message: "OVERSIZED_DATA" + data: "Transaction input data exceeds the allowed limit" + x-error-category: "TXPOOL_ERRORS" + - code: -31006 + message: "SENDER_BLACKLISTED" + data: "Transaction sender is blacklisted" + x-error-category: "TXPOOL_ERRORS" + - code: -31007 + message: "RECEIVER_BLACKLISTED" + data: "Transaction receiver is blacklisted" + x-error-category: "TXPOOL_ERRORS" + - code: -31008 + message: "CHAIN_ID_MISMATCH" + data: "Transaction chain ID does not match the expected chain ID" + x-error-category: "TXPOOL_ERRORS" + - code: -31009 + message: "TX_NOT_PERMITTED" + data: "Transaction is protected and cannot be permitted for unauthorized users" + x-error-category: "TXPOOL_ERRORS" + - code: -31010 + message: "INVALID_RLP_DATA" + data: "Transaction Data contains invalid RLP encoding" + x-error-category: "TXPOOL_ERRORS" \ No newline at end of file diff --git a/src/extensions/schemas/x-error-category-ranges.json b/src/extensions/schemas/x-error-category-ranges.json new file mode 100644 index 000000000..2aacc657b --- /dev/null +++ b/src/extensions/schemas/x-error-category-ranges.json @@ -0,0 +1,70 @@ +{ + "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 } + } + } + }, + { + "if": { + "properties": { + "x-error-category": { "const": "TXPOOL_ERRORS" } + }, + "required": ["x-error-category"] + }, + "then": { + "properties": { + "code": { "type": "integer", "minimum": -31199, "maximum": -31000 } + } + } + } + ] + } + }, + { + "type": "object", + "properties": { + "$ref": { "type": "string" } + }, + "required": ["$ref"] + } + ] + } +}