error-groups: tx validation, execution and txpool error codes

src/debug/getters.yaml

@@ -52,8 +52,6 @@
   errors:
     - code: 4444
       message: Pruned history unavailable
-    - code: -32602
-      message: Invalid params
   result:
     name: EIP-2718 binary-encoded transaction
     schema:

src/error-groups/README.md

@@ -17,24 +17,18 @@ During spec generation, `tools/specgen` resolves those references into each meth
 - `tools/specgen` – builds `refs-openrpc.json` and `openrpc.json` and resolves `error-groups` references.
 - `Makefile` – passes `-error-groups 'src/error-groups'` to `tools/specgen`.
 
-## 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 | Reserved range | Source |
-| --- | --- | --- |
-| JSON-RPC standard | $-32768$ to $-32000$ | JSON-RPC 2.0 spec |
-| JSON-RPC non-standard | $-32099$ to $-32000$ | JSON-RPC 2.0 addendum |
-| Execution errors | $1$ to $199$ | `execution-errors.yaml` |
-| Gas errors | $800$ to $999$ | `gas-errors.yaml` |
-| TxPool errors | $1000$ to $1199$ | `txpool-errors.yaml` |
-| ZK execution errors | $2000$ to $2199$ | `zk-execution-errors.yaml` |
+## Groups
+| Group | File |
+| --- | --- |
+| `JSONRPCNonStandardErrors` | `rpc-non-standard-errors.yaml` |
+| `TransactionValidationErrors` | `transaction-validation-errors.yaml` |
+| `ExecutionResultErrors` | `execution-result-errors.yaml` |
+| `SimulationErrors` | `simulation-errors.yaml` |
+| `TxPoolErrors` | `txpool-errors.yaml` |
 
 ## Extending the catalog
-1. Add or update a group file in `src/error-groups/` with `category`, `range`, and `errors`.
-2. Keep codes within that group's declared range.
-3. Reference the group from a method with `$ref: '#/components/error-groups/<GroupName>'` in `error-groups`.
-4. Rebuild specs using `make build` (or run `./tools/specgen ...` with the same flags from `Makefile`).
+1. Add or update a group file in `src/error-groups/` with `errors` (and an optional `range`).
+2. Reference the group from a method with `$ref: '#/components/error-groups/<GroupName>'` in `error-groups`.
+3. Rebuild specs using `make build` (or run `./tools/specgen ...` with the same flags from `Makefile`).
 
 This keeps method definitions concise while preserving consistent error semantics across clients.

src/error-groups/execution-result-errors.yaml

@@ -0,0 +1,10 @@
+ExecutionResultErrors:
+  # Errors produced while executing the EVM.
+  errors:
+    - code: 3
+      message: "Execution reverted"
+      data:
+        title: "raw EVM revert data"
+        $ref: "#/components/schemas/bytes"
+    - code: -32015
+      message: "VM execution error"

src/error-groups/rpc-non-standard-errors.yaml

@@ -1,16 +1,7 @@
 JSONRPCNonStandardErrors:
+  # EIP-1474 server-error codes observed in client implementations.
   errors:
     - code: -32000
       message: "Invalid input"
     - code: -32001
       message: "Resource not found"
-    - code: -32002
-      message: "Resource unavailable"
-    - code: -32003
-      message: "Transaction rejected"
-    - code: -32004
-      message: "Method not supported"
-    - code: -32005
-      message: "Limit exceeded"
-    - code: -32006
-      message: "JSON-RPC version not supported"

src/error-groups/simulation-errors.yaml

@@ -0,0 +1,13 @@
+SimulationErrors:
+  # Errors specific to the eth_simulateV1 multi-block payload.
+  errors:
+    - code: -38020
+      message: "Block number in sequence did not increase"
+    - code: -38021
+      message: "Block timestamp in sequence did not increase or stay the same"
+    - code: -38022
+      message: "MovePrecompileToAddress referenced itself in replacement"
+    - code: -38023
+      message: "Multiple MovePrecompileToAddress referencing the same address to replace"
+    - code: -38026
+      message: "Client adjustable limit exceeded"

src/error-groups/transaction-validation-errors.yaml

@@ -0,0 +1,20 @@
+TransactionValidationErrors:
+  # Errors detected when validating a transaction against state and block context,
+  # before EVM execution.
+  errors:
+    - code: -38010
+      message: "Nonce too low"
+    - code: -38011
+      message: "Nonce too high"
+    - code: -38012
+      message: "Max fee per gas less than block base fee"
+    - code: -38013
+      message: "Intrinsic gas too low"
+    - code: -38014
+      message: "Insufficient funds for gas * price + value"
+    - code: -38015
+      message: "Block gas limit exceeded"
+    - code: -38024
+      message: "Sender is not an EOA"
+    - code: -38025
+      message: "Max init code size exceeded"

src/error-groups/txpool-errors.yaml

@@ -1,9 +1,11 @@
 TxPoolErrors:
-  range:
-    min: 1000
-    max: 1199
+  # Errors raised when admitting a transaction to the mempool.
   errors:
-    - code: 1000
+    - code: -38030
       message: "Already known transaction"
-    - code: 1001
+    - code: -38031
       message: "Invalid sender"
+    - code: -38032
+      message: "Replacement transaction underpriced"
+    - code: -38033
+      message: "Transaction pool limit reached"

src/eth/execute.yaml

@@ -126,42 +126,10 @@
     name: Result of calls
     schema:
       $ref: '#/components/schemas/EthSimulateResult'
+  error-groups:
+    - $ref: '#/components/error-groups/TransactionValidationErrors'
+    - $ref: '#/components/error-groups/ExecutionResultErrors'
+    - $ref: '#/components/error-groups/SimulationErrors'
   errors:
-    - code: -32000
-      message: Invalid request
-    - code: -32602
-      message: Missing or invalid parameters
-    - code: -32005
-      message: Transactions maxFeePerGas is too low
-    - code: -32015
-      message: Execution error
     - code: -32016
-      message: Timeout
-    - code: -32603
-      message: The Ethereum node encountered an internal error
-    - code: -38010
-      message: Transactions nonce is too low
-    - code: -38011
-      message: Transactions nonce is too high
-    - code: -38012
-      message: Transactions baseFeePerGas is too low
-    - code: -38013
-      message: Not enough gas provided to pay for intrinsic gas for a transaction
-    - code: -38014
-      message: Insufficient funds to pay for gas fees and value for a transaction
-    - code: -38015
-      message: Block gas limit exceeded by the block's transactions
-    - code: -38020
-      message: Block number in sequence did not increase
-    - code: -38021
-      message: Block timestamp in sequence did not increase or stay the same
-    - code: -38022
-      message: MovePrecompileToAddress referenced itself in replacement
-    - code: -38023
-      message: Multiple MovePrecompileToAddress referencing the same address to replace
-    - code: -38024
-      message: Sender is not an EOA
-    - code: -38025
-      message: Max init code size exceeded
-    - code: -38026
-      message: Client adjustable limit exceeded
+      message: "Timeout"

src/eth/submit.yaml

@@ -6,10 +6,7 @@
       schema:
         $ref: '#/components/schemas/GenericTransaction'
   error-groups:
-    - $ref: '#/components/error-groups/JSONRPCStandardErrors'
-    - $ref: '#/components/error-groups/JSONRPCNonStandardErrors'
-    - $ref: '#/components/error-groups/GasErrors'
-    - $ref: '#/components/error-groups/ExecutionErrors'
+    - $ref: '#/components/error-groups/TransactionValidationErrors'
     - $ref: '#/components/error-groups/TxPoolErrors'
   result:
     name: Transaction hash
@@ -52,10 +49,7 @@
       schema:
         $ref: '#/components/schemas/bytes'
   error-groups:
-    - $ref: '#/components/error-groups/JSONRPCStandardErrors'
-    - $ref: '#/components/error-groups/JSONRPCNonStandardErrors'
-    - $ref: '#/components/error-groups/GasErrors'
-    - $ref: '#/components/error-groups/ExecutionErrors'
+    - $ref: '#/components/error-groups/TransactionValidationErrors'
     - $ref: '#/components/error-groups/TxPoolErrors'
   result:
     name: Transaction hash

src/testing/testing_buildBlockV1.yaml

@@ -89,11 +89,6 @@
           type: array
           items:
             $ref: '#/components/schemas/bytes'
-  errors:
-    - code: -32602
-      message: Invalid parameters
-    - code: -32603
-      message: Internal error
   examples:
     - name: testing_buildBlockV1 example
       params: