Skip to content

Commit 4019acd

Browse files
simsonrajsimsonraj
committed
Added TXPOOL errors, README file and fixes
1 parent 5c8daea commit 4019acd

File tree

6 files changed

+180
-28
lines changed

6 files changed

+180
-28
lines changed

‎scripts/build.js‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -81,18 +81,6 @@ schemaFiles.forEach(file => {
8181
});
8282

8383
let extensionSpecs = [];
84-
let extensionSpecsBase = "src/extensions/"
85-
let extensionsSpecsFiles = fs.readdirSync(extensionSpecsBase);
86-
extensionsSpecsFiles.forEach(file => {
87-
console.log(file);
88-
// skip if directory
89-
if (fs.lstatSync(extensionSpecsBase + file).isDirectory()) {
90-
return;
91-
}
92-
let raw = fs.readFileSync(extensionSpecsBase + file);
93-
let parsed = yaml.load(raw);
94-
extensionSpecs.push(parsed);
95-
});
9684

9785
// Enhance the existing XErrorGroupsJSON extension with conditional validation for different error categories
9886
const enhancedErrorGroupSchema = JSON.parse(fs.readFileSync('src/extensions/schemas/x-error-category-ranges.json', 'utf8'));

‎src/eth/submit.yaml‎

Lines changed: 2 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -10,14 +10,7 @@
1010
- $ref: '#/components/x-error-group/JSONRPCStandardErrors'
1111
- $ref: '#/components/x-error-group/GasErrors'
1212
- $ref: '#/components/x-error-group/ExecutionErrors'
13-
# Inline additional errors specific to this method
14-
-
15-
- code: -31000
16-
message: "Already known transaction"
17-
data: "Transaction is already known to the transaction pool"
18-
- code: -31001
19-
message: "Invalid sender"
20-
data: "Transaction sender is invalid."
13+
- $ref: '#/components/x-error-group/TxPoolErrors'
2114
result:
2215
name: Transaction hash
2316
schema:
@@ -63,14 +56,7 @@
6356
- $ref: '#/components/x-error-group/JSONRPCStandardErrors'
6457
- $ref: '#/components/x-error-group/GasErrors'
6558
- $ref: '#/components/x-error-group/ExecutionErrors'
66-
# Inline additional errors specific to this method
67-
-
68-
- code: -31000
69-
message: "Already known transaction"
70-
data: "Transaction is already known to the transaction pool"
71-
- code: -31001
72-
message: "Invalid sender"
73-
data: "Transaction sender is invalid."
59+
- $ref: '#/components/x-error-group/TxPoolErrors'
7460
result:
7561
name: Transaction hash
7662
schema:

‎src/extensions/README.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Extensions overview
2+
3+
## Proposal
4+
#### Goal
5+
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.
6+
7+
#### Motivation
8+
Client implementations and EVM-compatible chains currently reuse codes or return generic error messages, making cross-client debugging brittle.
9+
10+
#### Solution
11+
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).
12+
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.
13+
14+
The corresponding PR definition frames these groups as the canonical vocabulary for wallets, infra providers, and execution clients.
15+
16+
## Solution Layout
17+
- `components/` – YAML fragments exposing each error family as an OpenRPC `x-error-group` definition.
18+
- `schemas/x-error-category-ranges.json` – Extension to official `x-error-groups` that enforces the reserved integer windows per category during validation.
19+
- `scripts/build.js` – Loads the schema above, augments the `XErrorGroupsJSON` extension, and merges the groups into `refs-openrpc.json` / `openrpc.json`.
20+
21+
## Implemented Methods
22+
Currently, only below methods import all the error groups via `$ref` and may include inline method-specific codes while still inheriting the standard set.
23+
- `eth_sendTransaction` in `src/eth/submit.yaml`
24+
- `eth_sendRawTransaction` in `src/eth/submit.yaml`
25+
26+
27+
## Reserved ranges at a glance
28+
| Extension group | Category label | Reserved range | Source |
29+
| --- | --- | --- | --- |
30+
| JSON-RPC standard | — | $-32768$ to $-32000$ | JSON-RPC 2.0 spec |
31+
| JSON-RPC non-standard | Client-specific | $-32099$ to $-32000$ | JSON-RPC 2.0 addendum |
32+
| Gas errors | `GAS_ERRORS` | $-31999$ to $-31800$ | `gas-error-groups.yaml` |
33+
| Execution errors | `EXECUTION_ERRORS` | $-31799$ to $-31600$ | `execution-errors.yaml` |
34+
| (Future) consensus | — | $-31599$ to $-31400$ |
35+
| (Future) networking | — | $-31399$ to $-31200$ |
36+
| TxPool errors | `TXPOOL_ERRORS` | $-31199$ to $-31000$ | `txpool-errors.yaml` |
37+
38+
39+
**Validation** of these bands happens through `XErrorGroupsJSON.schema` in `scripts/build.js`, so build failures flag any out-of-range additions early.
40+
41+
42+
## Extending the catalog
43+
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.
44+
2. Stay within the reserved window; the JSON Schema guard in `schemas/x-error-category-ranges.json` will break the build if you drift.
45+
3. Reference the group from the relevant method spec via `$ref: '#/components/x-error-group/<GroupName>'` and layer any bespoke errors inline.
46+
4. Run the documentation build (e.g. `node scripts/build.js`) to regenerate `refs-openrpc.json` / `openrpc.json` and confirm validation passes.
47+
48+
Following this flow keeps the execution client surface aligned with the standard and preserves interoperability for downstream consumers.
49+
50+
51+
## Catalog reference
52+
53+
### [JSON-RPC standard errors](https://www.jsonrpc.org/specification) (`rpc-standard-errors.yaml`)
54+
| Code | Message | Notes |
55+
| --- | --- | --- |
56+
| $-32700$ | Parse error | An error occurred on the server while parsing the JSON text |
57+
| $-32600$ | Invalid request | The JSON sent is not a valid request object |
58+
| $-32601$ | Method not found | The method does not exist / is not available |
59+
| $-32602$ | Invalid params | Invalid method parameter(s) |
60+
| $-32603$ | Internal error | Internal JSON-RPC error |
61+
62+
### [JSON-RPC non-standard errors](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1474.md) (`rpc-non-standard-errors.yaml`)
63+
| Code | Message | Notes |
64+
| --- | --- | --- |
65+
| $-32000$ | Invalid input | Missing or invalid parameters |
66+
| $-32001$ | Resource not found | Requested resource not found |
67+
| $-32002$ | Resource unavailable | Requested resource not available |
68+
| $-32003$ | Transaction rejected | Transaction creation failed |
69+
| $-32004$ | Method not supported | Method is not implemented |
70+
| $-32005$ | Limit exceeded | Request exceeds defined limit |
71+
| $-32006$ | JSON-RPC version not supported | Version of JSON-RPC protocol is not supported |
72+
73+
### Gas errors (`gas-error-groups.yaml`)
74+
| Code | Message | Data |
75+
| --- | --- | --- |
76+
| $-31800$ | GAS_TOO_LOW | Transaction gas is too low / intrinsic gas too low |
77+
| $-31801$ | OUT_OF_GAS | The transaction ran out of gas |
78+
| $-31802$ | GAS_PRICE_TOO_LOW | Gas price too low / gas price below configured minimum gas price |
79+
| $-31803$ | BLOCK_GAS_LIMIT_EXCEEDED | Tx gas limit exceeds max block gas limit / intrinsic gas exceeds gas limit |
80+
| $-31804$ | FEE_CAP_EXCEEDED | Tx fee exceeds cap / max priority fee per gas higher than max fee per gas |
81+
| $-31805$ | GAS_OVERFLOW | Gas overflow error |
82+
| $-31806$ | INSUFFICIENT_TRANSACTION_PRICE | Transaction price must be greater than base fee / max fee per gas less than block base fee |
83+
| $-31807$ | INVALID_MAX_PRIORITY_FEE_PER_GAS | Max priority fee per gas higher than $2^{256}-1$ |
84+
| $-31808$ | INVALID_MAX_FEE_PER_GAS | Max fee per gas higher than $2^{256}-1$ |
85+
| $-31809$ | INSUFFICIENT_FUNDS | Insufficient funds for gas * price + value |
86+
| $-31810$ | TRANSACTION_UNDERPRICED | Transaction's gas price is below the minimum for txpool |
87+
| $-31811$ | REPLACEMENT_TRANSACTION_UNDERPRICED | Replacement transaction is sent without the required price bump |
88+
89+
### Execution errors (`execution-errors.yaml`)
90+
| Code | Message | Data |
91+
| --- | --- | --- |
92+
| $-31600$ | NONCE_TOO_LOW | Transaction nonce is lower than the sender account's current nonce |
93+
| $-31601$ | NONCE_TOO_HIGH | Transaction nonce is higher than the sender account's current nonce |
94+
| $-31602$ | EXECUTION_REVERTED | Execution is reverted by REVERT Opcode |
95+
| $-31603$ | INVALID_OPCODE | An invalid opcode was encountered during execution |
96+
| $-31604$ | OUT_OF_COUNTERS | Not enough step counters to continue the execution |
97+
98+
### TxPool errors (`txpool-errors.yaml`)
99+
| Code | Message | Data |
100+
| --- | --- | --- |
101+
| $-31000$ | ALREADY_KNOWN | Transaction is already known to the transaction pool |
102+
| $-31001$ | INVALID_SENDER | Transaction sender is invalid |
103+
| $-31002$ | INVALID_SIGNATURE | Transaction signature is invalid |
104+
| $-31003$ | TXPOOL_FULL | Transaction pool is full |
105+
| $-31004$ | NEGATIVE_VALUE | Transaction with negative value |
106+
| $-31005$ | OVERSIZED_DATA | Transaction input data exceeds the allowed limit |
107+
| $-31006$ | SENDER_BLACKLISTED | Transaction sender is blacklisted |
108+
| $-31007$ | RECEIVER_BLACKLISTED | Transaction receiver is blacklisted |
109+
| $-31008$ | CHAIN_ID_MISMATCH | Transaction chain ID does not match the expected chain ID |
110+
| $-31009$ | TX_NOT_PERMITTED | Transaction is protected and cannot be permitted for unauthorized users |
111+
| $-31010$ | INVALID_RLP_DATA | Transaction Data contains invalid RLP encoding |

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,11 @@ x-error-group:
4040
message: "INSUFFICIENT_FUNDS"
4141
data: "Insufficient funds for gas * price + value"
4242
x-error-category: "GAS_ERRORS"
43+
- code: -31810
44+
message: "TRANSACTION_UNDERPRICED"
45+
data: "Transaction's gas price is below the minimum for txpool"
46+
x-error-category: "GAS_ERRORS"
47+
- code: -31811
48+
message: "REPLACEMENT_TRANSACTION_UNDERPRICED"
49+
data: "Replacement transaction is sent without the required price bump."
50+
x-error-category: "GAS_ERRORS"

‎src/extensions/components/txpool-errors.yaml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
x-error-group:
2+
TxPoolErrors:
3+
- code: -31000
4+
message: "ALREADY_KNOWN"
5+
data: "Transaction is already known to the transaction pool"
6+
x-error-category: "TXPOOL_ERRORS"
7+
- code: -31001
8+
message: "INVALID_SENDER"
9+
data: "Transaction sender is invalid"
10+
x-error-category: "TXPOOL_ERRORS"
11+
- code: -31002
12+
message: "INVALID_SIGNATURE"
13+
data: "Transaction signature is invalid"
14+
x-error-category: "TXPOOL_ERRORS"
15+
- code: -31003
16+
message: "TXPOOL_FULL"
17+
data: "Transaction pool is full"
18+
x-error-category: "TXPOOL_ERRORS"
19+
- code: -31004
20+
message: "NEGATIVE_VALUE"
21+
data: "Transaction with negative value"
22+
x-error-category: "TXPOOL_ERRORS"
23+
- code: -31005
24+
message: "OVERSIZED_DATA"
25+
data: "Transaction input data exceeds the allowed limit"
26+
x-error-category: "TXPOOL_ERRORS"
27+
- code: -31006
28+
message: "SENDER_BLACKLISTED"
29+
data: "Transaction sender is blacklisted"
30+
x-error-category: "TXPOOL_ERRORS"
31+
- code: -31007
32+
message: "RECEIVER_BLACKLISTED"
33+
data: "Transaction receiver is blacklisted"
34+
x-error-category: "TXPOOL_ERRORS"
35+
- code: -31008
36+
message: "CHAIN_ID_MISMATCH"
37+
data: "Transaction chain ID does not match the expected chain ID"
38+
x-error-category: "TXPOOL_ERRORS"
39+
- code: -31009
40+
message: "TX_NOT_PERMITTED"
41+
data: "Transaction is protected and cannot be permitted for unauthorized users"
42+
x-error-category: "TXPOOL_ERRORS"
43+
- code: -31010
44+
message: "INVALID_RLP_DATA"
45+
data: "Transaction Data contains invalid RLP encoding"
46+
x-error-category: "TXPOOL_ERRORS"

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,19 @@
4141
"code": { "type": "integer", "minimum": -31799, "maximum": -31600 }
4242
}
4343
}
44+
},
45+
{
46+
"if": {
47+
"properties": {
48+
"x-error-category": { "const": "TXPOOL_ERRORS" }
49+
},
50+
"required": ["x-error-category"]
51+
},
52+
"then": {
53+
"properties": {
54+
"code": { "type": "integer", "minimum": -31199, "maximum": -31000 }
55+
}
56+
}
4457
}
4558
]
4659
}

0 commit comments

Comments
 (0)