Skip to content

Commit 8ab56cf

Browse files
simsonrajsimsonraj
committed
updated & re-organized error ranges & codes after review
1 parent 490218e commit 8ab56cf

File tree

7 files changed

+83
-146
lines changed

7 files changed

+83
-146
lines changed

‎src/eth/submit.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
- $ref: '#/components/x-error-group/GasErrors'
1212
- $ref: '#/components/x-error-group/ExecutionErrors'
1313
- $ref: '#/components/x-error-group/TxPoolErrors'
14+
- $ref: '#/components/x-error-group/ZKExecutionErrors'
1415
result:
1516
name: Transaction hash
1617
schema:
@@ -57,6 +58,7 @@
5758
- $ref: '#/components/x-error-group/GasErrors'
5859
- $ref: '#/components/x-error-group/ExecutionErrors'
5960
- $ref: '#/components/x-error-group/TxPoolErrors'
61+
- $ref: '#/components/x-error-group/ZKExecutionErrors'
6062
result:
6163
name: Transaction hash
6264
schema:

‎src/extensions/README.md‎

Lines changed: 6 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ A standard for JSON-RPC error codes & ship a shared catalog of JSON-RPC error co
88
Client implementations and EVM-compatible chains currently reuse codes or return generic error messages, making cross-client debugging brittle.
99

1010
#### 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).
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** outside the JSON-RPC 2.0 reserved bands.
1212
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.
1313

1414
The corresponding PR definition frames these groups as the canonical vocabulary for wallets, infra providers, and execution clients.
@@ -31,11 +31,10 @@ Currently, only below methods import all the error groups via `$ref` and may inc
3131
| --- | --- | --- | --- |
3232
| JSON-RPC standard | — | $-32768$ to $-32000$ | JSON-RPC 2.0 spec |
3333
| JSON-RPC non-standard | Client-specific | $-32099$ to $-32000$ | JSON-RPC 2.0 addendum |
34-
| Gas errors | `GAS_ERRORS` | $-31999$ to $-31800$ | `gas-error-groups.yaml` |
35-
| Execution errors | `EXECUTION_ERRORS` | $-31799$ to $-31600$ | `execution-errors.yaml` |
36-
| (Future) consensus | — | $-31599$ to $-31400$ |
37-
| (Future) networking | — | $-31399$ to $-31200$ |
38-
| TxPool errors | `TXPOOL_ERRORS` | $-31199$ to $-31000$ | `txpool-errors.yaml` |
34+
| Gas errors | `GAS_ERRORS` | $800$ to $999$ | `gas-error-groups.yaml` |
35+
| Execution errors | `EXECUTION_ERRORS` | $1$ to $999$ | `execution-errors.yaml` |
36+
| TxPool errors | `TXPOOL_ERRORS` | $1000$ to $1200$ | `txpool-errors.yaml` |
37+
| ZK execution errors | `ZK_EXECUTION_ERRORS` | $2000$ to $2200$ | `zk-execution-errors.yaml` |
3938

4039

4140
**Validation** of these bands happens through `XErrorGroupsJSON.schema` in `scripts/build.js`, so build failures flag any out-of-range additions early.
@@ -47,67 +46,4 @@ Currently, only below methods import all the error groups via `$ref` and may inc
4746
3. Reference the group from the relevant method spec via `$ref: '#/components/x-error-group/<GroupName>'` and layer any bespoke errors inline.
4847
4. Run the documentation build (e.g. `node scripts/build.js`) to regenerate `refs-openrpc.json` / `openrpc.json` and confirm validation passes.
4948

50-
Following this flow keeps the execution client surface aligned with the standard and preserves interoperability for downstream consumers.
51-
52-
53-
## Catalog reference
54-
55-
### [JSON-RPC standard errors](https://www.jsonrpc.org/specification) (`rpc-standard-errors.yaml`)
56-
| Code | Message | Notes |
57-
| --- | --- | --- |
58-
| $-32700$ | Parse error | An error occurred on the server while parsing the JSON text |
59-
| $-32600$ | Invalid request | The JSON sent is not a valid request object |
60-
| $-32601$ | Method not found | The method does not exist / is not available |
61-
| $-32602$ | Invalid params | Invalid method parameter(s) |
62-
| $-32603$ | Internal error | Internal JSON-RPC error |
63-
64-
### [JSON-RPC non-standard errors](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1474.md) (`rpc-non-standard-errors.yaml`)
65-
| Code | Message | Notes |
66-
| --- | --- | --- |
67-
| $-32000$ | Invalid input | Missing or invalid parameters |
68-
| $-32001$ | Resource not found | Requested resource not found |
69-
| $-32002$ | Resource unavailable | Requested resource not available |
70-
| $-32003$ | Transaction rejected | Transaction creation failed |
71-
| $-32004$ | Method not supported | Method is not implemented |
72-
| $-32005$ | Limit exceeded | Request exceeds defined limit |
73-
| $-32006$ | JSON-RPC version not supported | Version of JSON-RPC protocol is not supported |
74-
75-
### Gas errors (`gas-error-groups.yaml`)
76-
| Code | Message | Data |
77-
| --- | --- | --- |
78-
| $-31800$ | GAS_TOO_LOW | Transaction gas is too low / intrinsic gas too low |
79-
| $-31801$ | OUT_OF_GAS | The transaction ran out of gas |
80-
| $-31802$ | GAS_PRICE_TOO_LOW | Gas price too low / gas price below configured minimum gas price |
81-
| $-31803$ | BLOCK_GAS_LIMIT_EXCEEDED | Tx gas limit exceeds max block gas limit / intrinsic gas exceeds gas limit |
82-
| $-31804$ | FEE_CAP_EXCEEDED | Tx fee exceeds cap / max priority fee per gas higher than max fee per gas |
83-
| $-31805$ | GAS_OVERFLOW | Gas overflow error |
84-
| $-31806$ | INSUFFICIENT_TRANSACTION_PRICE | Transaction price must be greater than base fee / max fee per gas less than block base fee |
85-
| $-31807$ | INVALID_MAX_PRIORITY_FEE_PER_GAS | Max priority fee per gas higher than $2^{256}-1$ |
86-
| $-31808$ | INVALID_MAX_FEE_PER_GAS | Max fee per gas higher than $2^{256}-1$ |
87-
| $-31809$ | INSUFFICIENT_FUNDS | Insufficient funds for gas * price + value |
88-
| $-31810$ | TRANSACTION_UNDERPRICED | Transaction's gas price is below the minimum for txpool |
89-
| $-31811$ | REPLACEMENT_TRANSACTION_UNDERPRICED | Replacement transaction is sent without the required price bump |
90-
91-
### Execution errors (`execution-errors.yaml`)
92-
| Code | Message | Data |
93-
| --- | --- | --- |
94-
| $-31600$ | NONCE_TOO_LOW | Transaction nonce is lower than the sender account's current nonce |
95-
| $-31601$ | NONCE_TOO_HIGH | Transaction nonce is higher than the sender account's current nonce |
96-
| $-31602$ | EXECUTION_REVERTED | Execution is reverted by REVERT Opcode |
97-
| $-31603$ | INVALID_OPCODE | An invalid opcode was encountered during execution |
98-
| $-31604$ | OUT_OF_COUNTERS | Not enough step counters to continue the execution |
99-
100-
### TxPool errors (`txpool-errors.yaml`)
101-
| Code | Message | Data |
102-
| --- | --- | --- |
103-
| $-31000$ | ALREADY_KNOWN | Transaction is already known to the transaction pool |
104-
| $-31001$ | INVALID_SENDER | Transaction sender is invalid |
105-
| $-31002$ | INVALID_SIGNATURE | Transaction signature is invalid |
106-
| $-31003$ | TXPOOL_FULL | Transaction pool is full |
107-
| $-31004$ | NEGATIVE_VALUE | Transaction with negative value |
108-
| $-31005$ | OVERSIZED_DATA | Transaction input data exceeds the allowed limit |
109-
| $-31006$ | SENDER_BLACKLISTED | Transaction sender is blacklisted |
110-
| $-31007$ | RECEIVER_BLACKLISTED | Transaction receiver is blacklisted |
111-
| $-31008$ | CHAIN_ID_MISMATCH | Transaction chain ID does not match the expected chain ID |
112-
| $-31009$ | TX_NOT_PERMITTED | Transaction is protected and cannot be permitted for unauthorized users |
113-
| $-31010$ | INVALID_RLP_DATA | Transaction Data contains invalid RLP encoding |
49+
Following this flow keeps the execution client surface aligned with the standard and preserves interoperability for downstream consumers.

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

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,18 @@
11
x-error-group:
22
ExecutionErrors:
3-
- code: -31600
3+
- code: 1
44
message: "NONCE_TOO_LOW"
5-
data: "Transaction nonce is lower than the sender account's current nonce"
5+
data: "Nonce too low"
66
x-error-category: "EXECUTION_ERRORS"
7-
- code: -31601
7+
- code: 2
88
message: "NONCE_TOO_HIGH"
9-
data: "Transaction nonce is higher than the sender account's current nonce"
9+
data: "Nonce too high"
1010
x-error-category: "EXECUTION_ERRORS"
11-
- code: -31602
11+
- code: 3
1212
message: "EXECUTION_REVERTED"
13-
data: "Execution is reverted by REVERT Opcode"
13+
data: "Execution reverted by REVERT Opcode"
1414
x-error-category: "EXECUTION_ERRORS"
15-
- code: -31603
15+
- code: 4
1616
message: "INVALID_OPCODE"
17-
data: "An invalid opcode was encountered during execution"
18-
x-error-category: "EXECUTION_ERRORS"
19-
- code: -31604
20-
message: "OUT_OF_COUNTERS"
21-
data: "Not enough step counters to continue the execution"
17+
data: "Invalid opcode"
2218
x-error-category: "EXECUTION_ERRORS"

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

Lines changed: 21 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,34 @@
11
x-error-group:
22
GasErrors:
3-
- code: -31800
3+
- code: 800
44
message: "GAS_TOO_LOW"
5-
data: "Transaction gas is too low / intrinsic gas too low"
5+
data: "Intrinsic gas too low / Intrinsic gas exceeds gas limit"
66
x-error-category: "GAS_ERRORS"
7-
- code: -31801
7+
- code: 801
88
message: "OUT_OF_GAS"
9-
data: "The transaction ran out of gas"
9+
data: "Insufficient gas for floor data gas cost"
1010
x-error-category: "GAS_ERRORS"
11-
- code: -31802
12-
message: "GAS_PRICE_TOO_LOW"
13-
data: "Gas price too low / gas price below configured minimum gas price"
14-
x-error-category: "GAS_ERRORS"
15-
- code: -31803
11+
- code: 802
1612
message: "BLOCK_GAS_LIMIT_EXCEEDED"
1713
data: "Tx gas limit exceeds max block gas limit / intrinsic gas exceeds gas limit"
1814
x-error-category: "GAS_ERRORS"
19-
- code: -31804
20-
message: "FEE_CAP_EXCEEDED"
21-
data: "Tx fee exceeds cap / max priority fee per gas higher than max fee per gas"
22-
x-error-category: "GAS_ERRORS"
23-
- code: -31805
24-
message: "GAS_OVERFLOW"
25-
data: "Gas overflow error"
26-
x-error-category: "GAS_ERRORS"
27-
- code: -31806
28-
message: "INSUFFICIENT_TRANSACTION_PRICE"
29-
data: "Transaction price must be greater than base fee / max fee per gas less than block base fee"
30-
x-error-category: "GAS_ERRORS"
31-
- code: -31807
32-
message: "INVALID_MAX_PRIORITY_FEE_PER_GAS"
33-
data: "Max priority fee per gas higher than 2^256-1"
34-
x-error-category: "GAS_ERRORS"
35-
- code: -31808
36-
message: "INVALID_MAX_FEE_PER_GAS"
37-
data: "Max fee per gas higher than 2^256-1"
38-
x-error-category: "GAS_ERRORS"
39-
- code: -31809
15+
- code: 803
16+
message: "TRANSACTION_GAS_LIMIT_EXCEEDED"
17+
data: "Transaction gas limit too high"
18+
- code: 804
19+
message: "GAS_PRICE_TOO_LOW"
20+
data: "Gas price below configured minimum gas price / transaction gas price below minimum"
21+
x-error-category: "GAS_ERRORS"
22+
- code: 805
4023
message: "INSUFFICIENT_FUNDS"
41-
data: "Insufficient funds for gas * price + value"
24+
data: "Insufficient funds for gas * price + value / Upfront cost exceeds account balance"
4225
x-error-category: "GAS_ERRORS"
43-
- code: -31810
44-
message: "TRANSACTION_UNDERPRICED"
45-
data: "Transaction's gas price is below the minimum for txpool"
26+
- code: 806
27+
message: "TIP_ABOVE_FEE_CAP"
28+
data: "Max priority fee per gas higher than max fee per gas"
4629
x-error-category: "GAS_ERRORS"
47-
- code: -31811
48-
message: "REPLACEMENT_TRANSACTION_UNDERPRICED"
49-
data: "Replacement transaction is sent without the required price bump."
30+
- code: 807
31+
message: "FEE_CAP_EXCEEDED"
32+
data: "Tx fee exceeds the configured cap / Transaction fee cap exceeded"
5033
x-error-category: "GAS_ERRORS"
34+

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

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,46 @@
11
x-error-group:
22
TxPoolErrors:
3-
- code: -31000
3+
- code: 1000
44
message: "ALREADY_KNOWN"
55
data: "Transaction is already known to the transaction pool"
66
x-error-category: "TXPOOL_ERRORS"
7-
- code: -31001
8-
message: "INVALID_SENDER"
9-
data: "Transaction sender is invalid"
7+
- code: 1001
8+
message: "REPLACEMENT_TRANSACTION_UNDERPRICED"
9+
data: "Replacement transaction is sent without the required price bump"
1010
x-error-category: "TXPOOL_ERRORS"
11-
- code: -31002
12-
message: "INVALID_SIGNATURE"
13-
data: "Transaction signature is invalid"
11+
- code: 1002
12+
message: "OVERSIZED_DATA"
13+
data: "Oversized data: Transaction input data exceeds the allowed limit"
14+
x-error-category: "TXPOOL_ERRORS"
15+
- code: 1003
16+
message: "TX_NOT_PERMITTED"
17+
data: "Only replay-protected (EIP-155) transactions allowed over RPC"
1418
x-error-category: "TXPOOL_ERRORS"
15-
- code: -31003
19+
- code: 1004
1620
message: "TXPOOL_FULL"
1721
data: "Transaction pool is full"
1822
x-error-category: "TXPOOL_ERRORS"
19-
- code: -31004
23+
- code: 1005
24+
message: "INVALID_RLP_DATA"
25+
data: "Transaction Data contains invalid RLP encoding"
26+
x-error-category: "TXPOOL_ERRORS"
27+
- code: 1006
28+
message: "INVALID_SENDER"
29+
data: "Transaction sender is invalid"
30+
x-error-category: "TXPOOL_ERRORS"
31+
- code: 1007
2032
message: "NEGATIVE_VALUE"
2133
data: "Transaction with negative value"
2234
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
35+
- code: 1008
2836
message: "SENDER_DENYLISTED"
2937
data: "Transaction sender is denylisted"
3038
x-error-category: "TXPOOL_ERRORS"
31-
- code: -31007
39+
- code: 1009
3240
message: "RECEIVER_DENYLISTED"
3341
data: "Transaction receiver is denylisted"
3442
x-error-category: "TXPOOL_ERRORS"
35-
- code: -31008
43+
- code: 1010
3644
message: "CHAIN_ID_MISMATCH"
3745
data: "Transaction chain ID does not match the expected chain ID"
3846
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/components/zk-execution-errors.yaml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
x-error-group:
2+
ZKExecutionErrors:
3+
- code: 2000
4+
message: "OUT_OF_COUNTERS"
5+
data: "Not enough step counters to continue the execution"
6+
x-error-category: "ZK_EXECUTION_ERRORS"

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

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
},
2626
"then": {
2727
"properties": {
28-
"code": { "type": "integer", "minimum": -31999, "maximum": -31800 }
28+
"code": { "type": "integer", "minimum": 800, "maximum": 999 }
2929
}
3030
}
3131
},
@@ -38,7 +38,7 @@
3838
},
3939
"then": {
4040
"properties": {
41-
"code": { "type": "integer", "minimum": -31799, "maximum": -31600 }
41+
"code": { "type": "integer", "minimum": 1, "maximum": 199 }
4242
}
4343
}
4444
},
@@ -51,7 +51,20 @@
5151
},
5252
"then": {
5353
"properties": {
54-
"code": { "type": "integer", "minimum": -31199, "maximum": -31000 }
54+
"code": { "type": "integer", "minimum": 1000, "maximum": 1200 }
55+
}
56+
}
57+
},
58+
{
59+
"if": {
60+
"properties": {
61+
"x-error-category": { "const": "ZK_EXECUTION_ERRORS" }
62+
},
63+
"required": ["x-error-category"]
64+
},
65+
"then": {
66+
"properties": {
67+
"code": { "type": "integer", "minimum": 2000, "maximum": 2200 }
5568
}
5669
}
5770
}

0 commit comments

Comments
 (0)