[Feature]Standardize JSON-RPC error handling(revert codes, LiteNode pruned-history responses, request fields validation)

[0xbigapple]

Summary

Align java-tron's JSON-RPC behavior with the Ethereum Execution API standard in three areas: contract revert error codes, LiteNode pruned-history responses, and JSON-RPC 2.0 request validation. This improves compatibility with Ethereum tooling, makes LiteNode failure modes explicit, and adds an opt-in strict protocol validation mode.

Problem

Motivation

java-tron's JSON-RPC behavior currently diverges from the Ethereum Execution API standard in ways that can break compatibility with wallets, DApps, SDKs, and debugging tools that assume Ethereum-compatible semantics.

Current State

1. eth_call and eth_estimateGas currently return -32000 for all execution failures, without distinguishing TVM revert from other failures such as OUT_OF_ENERGY.
2. On LiteNode which historical blocks have been pruned, clients cannot distinguish between "data was pruned" and "data does not exist". The earliest tag is also treated as the genesis block rather than the lowest available block on the node.
3. java-tron relies on jsonrpc4j's default behavior, which does not strictly validate the jsonrpc: "2.0" field. In addition, certain id values are handled in a way that is not suitable for blockchain node scenarios, for example treating "id": null as a notification and returning no response.

Limitations or Risks

• DApps and tooling cannot reliably distinguish contract revert from internal execution failures, which affects error handling and UX.
• LiteNode clients cannot make informed fallback decisions, such as retrying against an archive node, because pruned-history cases are not explicitly signaled.
• Protocol-level request handling is less consistent with mainstream Ethereum clients such as geth, which increases cross-client compatibility risk.

Proposed Solution

Proposed Design

Introduce the following behavior changes:

1. eth_call and eth_estimateGas return error code 3 for contract revert, and include the revert payload in the data field as hex. Non-revert execution failures continue to return -32000.
2. On LiteNode, return error code 4444 with message Pruned history unavailable when the requested block range is deterministically below the node's lowest available block. This applies to:
   • eth_getBlockByNumber
   • eth_getBlockTransactionCountByNumber
   • eth_getTransactionByBlockNumberAndIndex
   • eth_getBlockReceipts when block number/tag is used
   • eth_getLogs
   • eth_newFilter
3. Resolve earliest to the node's lowest available block number instead of always mapping it to the genesis block. For single-block queries, explicit 0x0 keeps its genesis-block meaning.
4. Add a new config item node.jsonrpc.strictComplianceMode, disabled by default. When enabled:
   • requests missing jsonrpc: "2.0" or carrying an invalid version return -32600 Invalid Request
   • invalid id types return responses with id: null
5. Limit pruned-history handling to selectors that can be deterministically evaluated by block number or tag. Hash-only methods such as eth_getBlockByHash and eth_getTransactionByHash remain out of scope.

Key Changes

• Modules
  • JSON-RPC execution error mapping
  • LiteNode block selector / history availability handling
  • JSON-RPC Servlet request validation
• Configuration
  • add node.jsonrpc.strictComplianceMode = false
• API / Behavior Surface
  • eth_call
  • eth_estimateGas
  • eth_getBlockByNumber
  • eth_getBlockTransactionCountByNumber
  • eth_getTransactionByBlockNumberAndIndex
  • eth_getBlockReceipts
  • eth_getLogs
  • eth_newFilter
• Testing
  • add regression coverage for error mapping, pruned-history handling, earliest resolution, and strict mode validation

Impact

This change primarily affects API compatibility and developer experience, with positive impact on interoperability with Ethereum tooling. Performance impact should be negligible: protocol validation is an O(1) field check, and pruned-history validation happens before deeper business logic, which can reduce unnecessary I/O on LiteNode.

Compatibility

• Breaking Change: Yes
• Default Behavior Change: Partial. eth_call / eth_estimateGas revert responses and LiteNode pruned-history responses change behavior immediately; strictComplianceMode is added but remains disabled by default.
• Migration Required: Possibly. Clients that currently rely on -32000 for all execution failures or expect null for pruned LiteNode data may need to adjust. Clients that omit the jsonrpc field are unaffected unless strictComplianceMode is explicitly enabled.

References

• Ethereum Execution API: https://ethereum.github.io/execution-apis/
• JSON-RPC 2.0 Specification: https://www.jsonrpc.org/specification

Additional Notes

• Do you have ideas regarding implementation? Yes
• Are you willing to implement this feature? Yes

[317787106]

@0xbigapple Excellent optimization! Maintaining compatibility with the Ethereum ecosystem helps reduce maintenance costs for TRON developers, and keeping track of already resolved bugs is also crucial for service stability as that #6632.

Is it necessary to set the default value of node.jsonrpc.strictComplianceMode to true? Because, in fact, the specification requires id and version to follow fixed formats. This requirement for id and version is created recently — it has been in place since the specification was first introduced.

[lxcmyf]

I checked the current JSON-RPC implementation and the proposal matches several real gaps in the code path:

• eth_call / eth_estimateGas currently collapse all execution failures into JsonRpcInternalException, and the interface annotation maps that to -32000. Even when revert data is present, the current code only puts it into data; it does not switch the code to 3 for revert.
• earliest is currently hard-wired to block 0 in both JsonRpcApiUtil.getByJsonBlockId(...) and Wallet.getByJsonBlockId(...), so the issue description about genesis behavior is accurate.
• For number/tag-based queries such as eth_getBlockByNumber, eth_getTransactionByBlockNumberAndIndex, and eth_getBlockReceipts, the current behavior is mostly null when the resolved block is unavailable. That means LiteNode pruned-history and true not-found are not distinguishable at the API layer.

One implementation detail that seems important: JsonRpcServlet currently hands the request directly to jsonrpc4j (rpcServer.handle(req, resp)). So if strictComplianceMode is added, the jsonrpc / id validation likely has to happen before normal dispatch in the servlet layer, not just in JsonRpcErrorResolver, because notification handling and request-shape parsing already happen inside jsonrpc4j.

For the collaborator question about the default value: based on the current implementation, I think strictComplianceMode = false is the safer rollout. Switching it to true by default would immediately change protocol-level behavior for existing clients that rely on the current jsonrpc4j tolerance, while the revert-code and pruned-history changes can be scoped more narrowly and verified method by method.

A practical structure might be:

• add a dedicated exception for EVM-compatible revert responses and map that one to code 3
• add a dedicated pruned-history exception and map it to 4444
• centralize block tag resolution so earliest can resolve to lowest available in LiteNode-aware paths
• gate request-shape validation behind strictComplianceMode in JsonRpcServlet

[0xbigapple]

@0xbigapple Excellent optimization! Maintaining compatibility with the Ethereum ecosystem helps reduce maintenance costs for TRON developers, and keeping track of already resolved bugs is also crucial for service stability as that #6632.

Is it necessary to set the default value of node.jsonrpc.strictComplianceMode to true? Because, in fact, the specification requires id and version to follow fixed formats. This requirement for id and version is created recently — it has been in place since the specification was first introduced.

@317787106 Thanks for the feedback.
On the default value question: I'd prefer to keep strictComplianceMode = false for the initial rollout. While the spec has always required jsonrpc: "2.0", the reality is that java-tron has been tolerant of these deviations since day one, and some existing clients may depend on that tolerance. Flipping the default to true immediately would be a silent breaking change for those clients with no migration path.
Also, if downstream feedback shows most clients are already compliant, we can accelerate the timeline for defaulting to true. We can bring this topic to the developer meeting for broader community input on the right default.

[0xbigapple]

I checked the current JSON-RPC implementation and the proposal matches several real gaps in the code path:

• eth_call / eth_estimateGas currently collapse all execution failures into JsonRpcInternalException, and the interface annotation maps that to -32000. Even when revert data is present, the current code only puts it into data; it does not switch the code to 3 for revert.
• earliest is currently hard-wired to block 0 in both JsonRpcApiUtil.getByJsonBlockId(...) and Wallet.getByJsonBlockId(...), so the issue description about genesis behavior is accurate.
• For number/tag-based queries such as eth_getBlockByNumber, eth_getTransactionByBlockNumberAndIndex, and eth_getBlockReceipts, the current behavior is mostly null when the resolved block is unavailable. That means LiteNode pruned-history and true not-found are not distinguishable at the API layer.

One implementation detail that seems important: JsonRpcServlet currently hands the request directly to jsonrpc4j (rpcServer.handle(req, resp)). So if strictComplianceMode is added, the jsonrpc / id validation likely has to happen before normal dispatch in the servlet layer, not just in JsonRpcErrorResolver, because notification handling and request-shape parsing already happen inside jsonrpc4j.

For the collaborator question about the default value: based on the current implementation, I think strictComplianceMode = false is the safer rollout. Switching it to true by default would immediately change protocol-level behavior for existing clients that rely on the current jsonrpc4j tolerance, while the revert-code and pruned-history changes can be scoped more narrowly and verified method by method.

A practical structure might be:

• add a dedicated exception for EVM-compatible revert responses and map that one to code 3
• add a dedicated pruned-history exception and map it to 4444
• centralize block tag resolution so earliest can resolve to lowest available in LiteNode-aware paths
• gate request-shape validation behind strictComplianceMode in JsonRpcServlet

@lxcmyf Great analysis — the code-level verification is very helpful, especially the point about JsonRpcServlet and jsonrpc4j dispatch ordering.

I agree with the implementation structure you outlined. A few thoughts on each piece:

Revert error code 3: Yes, a dedicated exception (e.g. JsonRpcExecutionRevertedException) that carries the raw revert payload and maps to code 3 is the right approach. The current JsonRpcInternalException catch-all is the root cause of the -32000 conflation. The key implementation detail is detecting revert vs other failures — we can check for the REVERT result code from TVM execution and extract the revert data from the transaction result.

Pruned-history 4444: Agreed on a dedicated JsonRpcPrunedHistoryException. The check should happen early — right after block tag resolution and before any store lookups — to avoid unnecessary I/O on LiteNode.

earliest resolution: Centralizing block tag resolution is important. On FullNode earliest = genesis, on LiteNode earliest = lowest available. This should be a single utility method that both JsonRpcApiUtil.getByJsonBlockId() and Wallet.getByJsonBlockId() delegate to.

Servlet-layer validation: Good catch on the dispatch ordering. The jsonrpc/id validation must intercept the request before jsonrpc4j's handle(), since jsonrpc4j already makes its own assumptions about notifications and request shape. A pre-dispatch filter in JsonRpcServlet gated by strictComplianceMode is the right place.