[Feature]Standardize JSON-RPC error handling(revert codes, LiteNode pruned-history responses, request fields validation)
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 42/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Active
- Tech stack
- java
- Domain
- api, backend, blockchain
Research direction
Begin with the JSON-RPC execution error mapping, LiteNode block selector/history availability handling, and JSON-RPC Servlet request validation modules; inspect the handlers for the listed API methods and the node.jsonrpc.strictComplianceMode configuration. Compare current behavior with the referenced Ethereum Execution API and JSON-RPC 2.0 specifications. Done means regression coverage verifies revert codes, pruned-history and earliest handling, and strict request validation.
Written by the indexing model from the issue text.
Description
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 validates the JSON-RPC 2.0 request envelope before dispatch.
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
eth_callandeth_estimateGascurrently return-32000for all execution failures, without distinguishing TVMrevertfrom other failures such asOUT_OF_ENERGY.- On LiteNode which historical blocks have been pruned, clients cannot distinguish between "data was pruned" and "data does not exist". The
earliesttag is also treated as the genesis block rather than the lowest available block on the node. - java-tron relies on jsonrpc4j's default behavior, which does not strictly validate the
jsonrpc: "2.0"field. In addition, certainidvalues are handled in a way that is not suitable for blockchain node scenarios, for example treating"id": nullas a notification and returning no response.
Limitations or Risks
- DApps and tooling cannot reliably distinguish contract
revertfrom 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:
-
eth_callandeth_estimateGasreturn error code3for contractrevert, and include the revert payload in thedatafield as hex. Non-revert execution failures continue to return-32000. -
On LiteNode, return error code
4444with messagePruned history unavailablewhen the requested block range is deterministically below the node's lowest available block. This applies to:eth_getBlockByNumbereth_getBlockTransactionCountByNumbereth_getTransactionByBlockNumberAndIndexeth_getBlockReceiptswhen block number/tag is usedeth_getLogseth_newFilter
-
Resolve
earliestto the node's lowest available block number instead of always mapping it to the genesis block. For single-block queries, explicit0x0keeps its genesis-block meaning. -
Validate the request envelope unconditionally, with no configuration switch (decision). Each of the following returns
-32600 Invalid Requestbefore dispatch; in a batch only the offending element is rejected and valid siblings still run:- missing
jsonrpcor a value other than"2.0", with the messagejsonrpc must be "2.0" - missing, non-string or empty
method - explicit
"id": null, answered withid: nullinstead of being treated as a notification - an
idthat is not a String, Number or Null, answered withid: null(landed in #6985)
Requests without an
idremain notifications. - missing
-
Limit pruned-history handling to selectors that can be deterministically evaluated by block number or tag. Hash-only methods such as
eth_getBlockByHashandeth_getTransactionByHashremain out of scope.
Key Changes
- Modules
- JSON-RPC execution error mapping
- LiteNode block selector / history availability handling
- JSON-RPC Servlet request validation
- API / Behavior Surface
eth_calleth_estimateGaseth_getBlockByNumbereth_getBlockTransactionCountByNumbereth_getTransactionByBlockNumberAndIndexeth_getBlockReceiptseth_getLogseth_newFilter
- Testing
- add regression coverage for error mapping, pruned-history handling,
earliestresolution, and request envelope validation.
- add regression coverage for error mapping, pruned-history handling,
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: Yes. All changes above apply by default; there is no configuration switch.
- Migration Required: Possibly. Clients that currently rely on
-32000for all execution failures or expectnullfor pruned LiteNode data may need to adjust. Clients must send"jsonrpc": "2.0"; requests that omit it, or send"id": null, now receive-32600.
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
- Dominant language
- Java
- Stars
- 4.2k
- Forks
- 1.8k
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 51
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from tronprotocol/java-tron
-
Difficulty 3/5 1-2 days Newbie friendliness 70/100
tronprotocol/java-tron#7044 · 4 comments ·
Maintainers usually reply within 1 day
-
[Feature] Remove unused discovery message definitionsPossibly taken A pull request linked to this issue is open or already merged. Opentype:feature
Difficulty 4/5 3-5 days Newbie friendliness 35/100
tronprotocol/java-tron#7013 · 3 comments ·
Maintainers usually reply within 1 day
-
[Feature] Validate ECKey inputs and improve key handlingPossibly taken A pull request linked to this issue is open or already merged. Opentype:feature
Difficulty 4/5 3-5 days Newbie friendliness 40/100
tronprotocol/java-tron#6994 · 5 comments ·
Maintainers usually reply within 1 day
-
type:feature
Difficulty 5/5 Over a week Newbie friendliness 25/100
tronprotocol/java-tron#6989 · 7 comments ·
Maintainers usually reply within 1 day
-
[Feature] decouple json-rpc filter processing from ManagerPossibly taken A pull request linked to this issue is open or already merged. Opentype:feature
Difficulty 5/5 Over a week Newbie friendliness 48/100
tronprotocol/java-tron#6963 · 8 comments ·
Maintainers usually reply within 1 day
All issues in tronprotocol/java-tron
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
citrusframework/citrus#2044 ·
Maintainers usually reply within 1 day
-
[bug]打火石不能被放在厨具架上Open
Difficulty 2/5 1-3 hours Newbie friendliness 63/100
KaleidoscopeMods/KaleidoscopeCookery#237 · 1 comment ·
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
molgenis/molgenis-emx2#7059 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
quarkiverse/quarkus-flow#1169 ·
Maintainers usually reply within 1 day