JSON RPC Error codes standardization using open-rpc extension specs

[simsonraj]

Goal

A standard for JSON-RPC error codes and messages across EVM-compatible chains and execution clients to improve interoperability, facilitate consistent error handling, and provide a better developer experience.

Motivation

Different Ethereum clients and EVM-compatible chains often use overlapping error codes or generic messages in their JSON-RPC API responses. This inconsistency confuses end users and developers, complicates cross-client tooling, and hampers interoperability.

Solution Abstract

• This is made possible by extending the Open-RPC spec to support Extension specs, particularly by utilizing the x-error-group extension spec
• This solution aims to address the inconsistent error codes by categorising common error scenarios
• Each category could have a reserved range (200 in this case) error codes allotted between (-31999 to -30000), excluding the ranges specified in the JSON-RPC 2.0 specification.
• Example: Below is an example categorisation to imagine how the standardization could look like & can be amended as per feedback with different stakeholders

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	$800$ to $999$	gas-error-groups.yaml
Execution errors	EXECUTION_ERRORS	$1$ to $199$	execution-errors.yaml
TxPool errors	TXPOOL_ERRORS	$1000$ to $1199$	txpool-errors.yaml
ZK execution errors	ZK_EXECUTION_ERRORS	$2000$ to $2199$	zk-execution-errors.yaml

• Expected Error codes response validation implementation can be found here
• Error test suite for different clients https://github.com/simsonraj/eth-err-tests

[sambacha]

STOP THIS A.I. SLOP NOW!!!!!!!!!!!!

[zcstarr]

@sambacha this is not AI, but the culmination of many months and pretty close to a year of work, to put together a PR that can help move the ecosystem forward. If you have a criticism of the PR or something about it's content please feel free to comment with something constructive or instructive.

If you don't have anything constructive to add to this conversation, please refrain from spamming the PR with comments

[fjl]

One thing to note, is that there is no requirement for RPC errors to be negative numbers. The JSON-RPC specification itself uses a specific range of negative numbers for its errors, but the predefined errors are just for reporting protocol-level faults.

The entire range of positive integer values is available to us, so we should use it.

[fjl]

Same with this one, what is the meaning of this particular code? The term "step counters" has no defined meaning in Ethereum.

[simsonraj]

This is ZK stack specific, I will move this out to a separate category

[fjl]

We have just rewritten the spec build system in Go. For this change, it means we will have to find another way to integrate the error groups into the YAML files, but I think it's for the better anyway.

The spec extension always felt a bit much, and it is something every single tool would have to support to use the spec possibly.

Let's just implement this in a pragmatic way. We can define the error groups in a separate YAML file and change the specgen tool to inline all applicable errors into the methods.

[zcstarr]

@fjl From OpenRPC here, just for clarity every tool in OpenRPC ecosystem implements the extensions and extension framework.

Is there some complication in the implementation of spec gen that is preventing you from supporting extensions?

It's how we support OpenRPC specification upgrades(it's a part of the process) and application specific extensions. We've had more explicit support/clarity for extensions for about two years, and before then x-(extensions) have always been apart of the spec maybe 7 years.

All extensions are defined within the doc or may be externally referenced, but for the most part are inlined in the specification itself, so it's not that tools will need some other system to then deal with the extension.

If you're a downstream consumer of the spec the expectation is that you'll have the spec and therefore knowledge of the extension that is in use. We're also adding additional extensions that will support bidirectional signaling for client/server relations and pub/sub so, it's an increasingly important aspect of the spec.

In other things with regards to specgen, I wouldn't worry too deeply about linting, as we have a linter that we're rolling out at the end of Apr, that will allow you to place rules to the spec to keep the spec implementation clean.

I assume that no refs or feature bans like allOf are things that we will be able to specify fairly easy as a lint rule. I'm just mentioning it here so if there something with regards to linting or general OpenRPC concerns can like address/capture them.

[fjl]

It works a bit different now. Since we have the tool right here, we can apply any transform on our input files.

I like the idea with error groups, but it doesn't make sense for me to have this feature in the JSON output. And how will we document it anyway? In the end, what matters is that each method has a set of errors that can be produced, and they have to have unique codes.

There is some value in documenting the group association of errors, but I see it more like a secondary concern.

For the validation (speccheck), we'd have to implement the extension as well.

I think it's best to add the error codes in the YAML and change specgen to copy them into each method for now. We can use the extension in the spec JSON later by simply changing specgen again.

[fjl]

This is similar to how we handle allOf and $ref. They are standard features of JSON-Schema but our tool processes them to make it easier for consumers of the spec. The spec consumers don't have to implement JSON-pointer because we resolve everything. AFAIK we remove allOf because it makes the documentation complicated, certainly it is easier to understand the input format when it is given as a simple alternation instead of a union of constraints.

[zcstarr]

It makes sense to have a native expansion and parse tool for sure.

To answer your question about documentation, documentation for x-error-groups is already implemented across the tools in open-rpc. Playground, docs gen, inspector... . Visually in the docs, it appears as the errors currently do, and if there's a category it shows the category there as well.

I agree that speccheck would then need to do the full validation if it were to support extensions.

We like that you're doubling down on the golang tooling infrastructure, we'd like to offer our support to make that better and more fully supported.

We're currently working on tooling for this repo, it'd be great to sync with both you and @lightclient , because I think there's alot of overlap, and opportunity to make things better!

[simsonraj]

We have just rewritten the spec build system in Go. For this change, it means we will have to find another way to integrate the error groups into the YAML files, but I think it's for the better anyway.

The spec extension always felt a bit much, and it is something every single tool would have to support to use the spec possibly.

Let's just implement this in a pragmatic way. We can define the error groups in a separate YAML file and change the specgen tool to inline all applicable errors into the methods.

@fjl Just to clarify, the errors are already inlined per method, flattened & de-referenced.
The only difference here is that it will be under x-error-group instead of errors, thats because errors doesnt support array of arrays, and we are keeping the extension spec in the generated json for the readers to reference the ranges & for downstream validations ( rpctestgen/hive)
I do see your point, we could discuss this in the upcoming call to understand where else users would consume this and changes required