[Feature] Introduce resource limits for JSON-RPC (batch size, response size, address size, timeout)

[317787106]

Problem Statement

The current JSON-RPC service in java-tron lacks unified constraints on both request scale and response payload size. While this “unbounded” design works in simple scenarios, it introduces significant stability risks when the node is exposed to public traffic or operates under high concurrency.

Specifically:

• For batch array requests, it may contain a large array of sub-requests. A single request can occupy processing threads for an extended period, degrading overall throughput.
• Certain APIs (e.g., eth_getLogs, eth_getFilterChanges) may return extremely large result sets. Without response size limits, this can lead to excessive memory consumption and even trigger OOM conditions.
• Some requests may become long-running due to I/O latency, holding node resources for prolonged periods.
• Log-related APIs (eth_getLogs, eth_newFilter) currently allow an unbounded number of address filters, significantly increasing query complexity and directly impacting node performance.

These issues are further amplified when handling untrusted external requests. Therefore, it is necessary to introduce fundamental constraint mechanisms at the JSON-RPC layer.

Proposed Solution

The implementation prioritizes low-overhead approaches focusing on early validation and resource control.

• For all JSON-RPC requests, if its json type is array, the length should be validated during the parsing phase to enable early rejection, avoiding unnecessary downstream processing.
• For eth_getLogs and eth_newFilter, the address array should be validated before entering query execution, preventing expensive database or index scans.
• Response size control should not rely on constructing the full payload in memory before validation. Instead, size tracking should be performed incrementally during serialization, using streaming or chunked output to enforce limits and reduce memory pressure.
• Request execution time should be controlled via asynchronous execution. Requests exceeding a configured timeout should be interrupted.

Error handling should remain consistent with the JSON-RPC specification and align with Ethereum conventions for better client interoperability. Different constraint violations should map to clear error codes:

• Address limit exceeded → -32602 (JsonRpcInvalidParamsException)
• Batch size exceeded → -32005
• Response too large → -32003
• Request timeout → -32002

Specification

Introduce a set of configurable limits for the JSON-RPC service to constrain request size and response payload, with validation performed as early as possible in the request lifecycle to improve system stability and predictability.

The following configuration items are proposed:

1. node.jsonrpc.maxBatchSize: Limits the maximum number of sub-requests in a batch JSON-RPC call. Default: 1. Requests exceeding this limit should be rejected immediately after parsing to avoid further processing. Note: values greater than 1 may bypass existing per-method QPS controls.

2. node.jsonrpc.maxAddressSize: Limits the number of address filters in log-related APIs (eth_getLogs, eth_newFilter). Default: 1000. Validation must occur before query execution to avoid high-cost operations. This follows the same design pattern as the existing node.jsonrpc.maxSubTopics.

3. node.jsonrpc.maxResponseSize: Limits the maximum size (in bytes) of a JSON-RPC response. Default: 25MB. The size should be tracked incrementally during serialization. Once the limit is exceeded, the response should be terminated immediately instead of continuing to build the full payload.

4. node.jsonrpc.maxRequestTimeout: Limits the execution time of a JSON-RPC request. Default: 30s. Requests exceeding the timeout should be interrupted and return an error.

All configurations should be integrated into the existing configuration system and follow the current JSON-RPC configuration conventions.

Configuration Changes

Add the following configuration items:

• node.jsonrpc.maxBatchSize
• node.jsonrpc.maxResponseSize
• node.jsonrpc.maxAddressSize
• node.jsonrpc.maxRequestTimeout

Scope of Impact

• API/RPC

Breaking Changes
These constraints effectively reduce the impact of oversized or abnormal requests on node resources, mitigate memory risks, and improve stability under high-load conditions. They also enhance the predictability of the JSON-RPC service, making it more suitable for production environments exposed to external users.

Backward Compatibility
There are no changes to API fields, so protocol-level compatibility is preserved. However, additional constraints on request inputs and response outputs may require minor client-side adaptations.

Implementation

Do you have ideas regarding the implementation?
Yes

Are you willing to implement this feature?
Yes

Estimated Complexity
Medium (moderate changes)

Testing Strategy

Focus primarily on boundary conditions, ensuring that exceptions are triggered as early as possible in the request lifecycle.

Test Scenarios

Since request timeout enforcement introduces asynchronous control and may shift execution toward a more serialized model, there could be an impact on performance. Changes in QPS should be evaluated and benchmarked accordingly.

[waynercheung]

Hi @317787106 It is a good work.

I compared the proposed defaults with current geth behavior, and I think 3 of the 4 numbers are easy to justify, while 1 deserves more discussion.

• maxAddressSize = 1000 looks reasonable. Geth also uses 1000 as the default log query limit for addresses / topic alternatives.
• maxResponseSize = 25MB also has a clear geth reference. Geth’s default batch response cap is 25000000 bytes.
• maxRequestTimeout = 30s is also close to geth’s default HTTP RPC timeout behavior (WriteTimeout = 30s), and -32002 is consistent with geth’s timeout error code.

The only default that is clearly much stricter than geth is maxBatchSize = 1.

Geth’s default batch request limit is 1000, while the proposal here is 1, which effectively disables batch requests by default.

Given the current java-tron architecture, I can understand the motivation for a very conservative default from a safety perspective. At the same time, this is a significant divergence from geth.

So I’d like to clarify one point first: is maxBatchSize = 1 intentionally chosen as a hardened default for public-node protection, or could this value be too small in practice?

If the goal is security-first behavior, 1 may be reasonable, but it would be good to document that explicitly.
If the goal is to stay closer to geth/ecosystem expectations, then it may be worth discussing whether a small-but-enabled default would be more appropriate.

[317787106]

@waynercheung Thank you for your review. We choose maxBatchSize = 1 mainly for public-node protection. If the current value is set to 1000, an attacker can easily bypass the RateLimit restrictions and launch attacks, placing a significant resource burden on our services. In reality, our system is designed with a value of 1. So this change is essentially fixing a bug. I don’t think setting the default value to 1000, as in Ethereum, is a good approach. Internal nodes may increase this value if needed, but public nodes should not.

[waynercheung]

@317787106
Thanks, this makes the intent much clearer.

If maxBatchSize = 1 is an intentional security-first default for public-node protection, and the expected behavior of the system is effectively single-request mode by default, then I agree we do not need to align this value with geth.

In that case, I think the next discussion should move from the default value itself to how we document and enforce it:

• it would be good to state explicitly in config/docs that 1 is a hardened default for public nodes
• implementation-wise, I suggest we make sure oversized batch requests are rejected as early as possible, before method dispatch, and add tests for that behavior

[vividctrlalt]

The other three limits (maxAddressSize, maxResponseSize, maxRequestTimeout) are well-justified with clear geth references.

However, maxBatchSize = 1 effectively disables batch requests, which is a breaking change for clients using standard Ethereum SDKs (ethers.js, web3.js) that rely on batch calls by default.

The concern about batch requests bypassing rate limiting is valid, but the correct fix is to make the rate limiter count sub-requests, not to disable batch entirely. This is industry standard practice:

• Infura — each sub-request in a batch counts as a separate API call
• Alchemy — batch sub-requests are individually counted as compute units
• geth — allows batch up to 1000 by default, controls resource usage via --rpc.batch-request-limit and --rpc.batch-response-max-size

The rate limiter should parse the batch array before throttling and deduct QPS proportionally to the number of sub-requests. This way batch remains functional for legitimate clients while preventing abuse.

Suggest: keep maxBatchSize at a reasonable default (e.g. 100), and fix the rate limiter to count per sub-request as a follow-up.

As a general note, I'd strongly recommend aligning with established industry practices (geth defaults, Infura/Alchemy behavior) when designing JSON-RPC resource limits. Deviating from ecosystem conventions without strong justification creates unnecessary friction for developers and operators migrating from or integrating with Ethereum-compatible tooling.

[317787106]

@vividctrlalt Your suggestion is excellent ! To address the security vulnerability while maintaining compatibility with Ethereum, this issue will adjust maxBatchSize to 100, and a follow-up issue or PR will count each sub request toward the total request limit.