[Feature] Add a node-level configuration to control the TVM execution time limit for constant calls

[yanghang8612]

Background

In the TRON network, the triggerconstantcontract API (and the Ethereum-compatible eth_call) is widely used for constant calls — including state queries via view/pure functions and transaction simulation (dry-runs). However, both are constrained by the TVM execution time limit (mainnet default: 80ms). When executing complex contract logic or intensive state access, this can lead to out_of_time exceptions, reducing the reliability of development tools, data services, and analytics platforms.

Running the FullNode with the --debug flag can remove the TVM timeout restriction for constant calls, but it also removes the timeout limit for transactions during normal block processing. As discussed in #6266, this can cause the local execution result to diverge from the result carried in the block (the block may report OUT_OF_TIME while the local node does not), which in turn causes the node to stop syncing. --debug is therefore not suitable for production nodes.

This issue supersedes #6288. After extensive discussion in that thread, the community reached consensus that a node-level configuration is preferable to the originally proposed request-body parameter approach. This new issue reflects the revised direction.

Related issues: #6266, #6288

Rationale

Why should this feature exist?

Node operators should be able to extend the TVM execution time window for constant calls only, without affecting block validation behavior. This would:

• Improve the stability of off-chain analysis tools and data services
• Prevent false negatives when querying or simulating complex contracts
• Reduce misleading error codes that confuse developers
• Avoid the sync-halt side effect of --debug

What are the use-cases?

• Data services performing bulk state queries via contract calls
• Deep cross-contract call simulation
• Simulating complex logic (e.g., loops or large mappings) that exceed the default execution window

Why a node-level config instead of a request parameter?

As discussed in #6288, we decided against adding a timeout_ms field to the request body, for the following reasons:

• API standard compatibility. Adding a non-standard field to eth_call would diverge from the Ethereum JSON-RPC specification and complicate integration for Ethereum tooling (ref).
• Separation of responsibility. Execution policy belongs to the node operator, not the caller. Operators that need extended simulation windows opt in explicitly; public-facing nodes keep the default (ref).
• No consensus risk. Constant calls are not broadcast on-chain, so a node-level knob does not risk SR consensus divergence (ref).
• Backward compatible. No API surface change, no SDK updates required.

Specification

Introduce a new node configuration option (name TBD, e.g. vm.constantCallTimeoutMs) in config.conf:

vm {
  # Max TVM execution time (ms) for constant calls
  # (triggerconstantcontract / eth_call). Default: 80.
  # Must be within [80, MAX_ALLOWED].
  constantCallTimeoutMs = 80
}

Behavior:

• Applies only to constant calls (triggerconstantcontract, eth_call, and equivalent read-only execution paths).
• Does not affect TVM execution during block processing or transaction broadcasting.
• A strict upper bound (e.g. 500ms) must be enforced to bound DoS risk.
• The effective timeout used for a given call should be observable (e.g. logged / returned in diagnostics) so operators can reason about behavior.

Safeguards

Regardless of the exact value chosen, extending the window increases per-call cost. The implementation should include:

• A hard upper bound on the configurable value.
• Rate limiting / concurrency cap for constant calls, especially when the configured timeout exceeds the default.
• Clear operator-facing documentation describing the trade-off and recommended values for public vs. private node deployments.

Test Specification

• Unit tests covering: default behavior unchanged; custom timeout respected for constant calls; block-processing timeout unchanged regardless of the new config.
• Integration tests verifying that a node with an extended constantCallTimeoutMs still syncs correctly against the main network (no OUT_OF_TIME divergence like --debug).
• Stress tests under concurrent constant-call load at the configured upper bound.

Scope Of Impact

• Non-breaking. No API signature change; existing clients and SDKs unaffected.
• TVM executor must branch on call context (block processing vs. constant call) when selecting the timeout.
• Operator documentation and release notes must describe the new option and its risks.

Implementation

Tentative outline:

• Add the config field and wire it through Args / VM config.
• Plumb a per-invocation timeout into the constant-call execution path (TVM executor) without touching the block-processing path.
• Enforce the upper bound at config-load time; reject invalid values with a clear error.
• Add rate-limiting hooks around constant-call execution.

Are you willing to implement this feature?

Yes.

[lxcmyf]

A couple of implementation questions seem worth pinning down first:

• Where should the split actually happen? Right now Program.checkCPUTimeLimit() is gated by global debug, while constant-call execution in VMActuator still reuses the same maxCpuTimeOfOneTx * ratio path. Is the plan to introduce a constant-call-specific deadline in the invoke/context, instead of adding more global flags?
• What is the expected operator-visible signal when the extended timeout is in effect? Since constant-call failures are often flattened into generic execution errors on the API side, would logs alone be enough, or should the effective timeout / timeout-hit reason be surfaced more directly for triggerconstantcontract / eth_call?

[warku123]

Thanks for this proposal. I've been researching DoS protection for triggerConstantContract / eth_call and have some data that may be relevant to the timeout discussion.

Real-world Energy consumption of constant calls

I measured the actual Energy consumption of the Top 100 most-called contracts (by trxCount) on the TRON mainnet, covering 456 view/pure functions:

Statistic	Energy
Min	261
P50	471
P90	1,024
P95	1,458
P99	3,490
Max	4,818

Even the most complex function among the top 100 contracts (PumpSmartExchangeRouter) only consumes 4,818 Energy, with 90% of functions under 1,024 Energy. These calls complete well within the current timeout.

The following charts visualize our analysis of the top 100 contracts on the TRON network:

Energy Distribution (Top 100 Contracts)

Distribution of Energy consumption across top 100 contracts (456 functions from 93 contracts). 90% of functions consume less than 1,024 Energy, with the median at 471 Energy.

Top Energy-Consuming Contracts

Contracts with the highest Energy consumption. The highest-consuming function is PumpSmartExchangeRouter.isAllowedTradingPair() at 4,818 Energy, followed by USDT.name() at 4,098 Energy.

Timeout increase amplifies DoS attack surface

In our pressure testing on an AWS c6a.4xlarge (16 vCPU) instance, we found that the real execution boundary for constant calls is maxCpuTimeOfOneTx (currently 50ms on our test environment), not maxEnergyLimitForConstant. Raising this timeout directly increases the CPU time an attacker can consume per request:

• At 50ms per request, an attacker with 10 concurrent connections occupies 500ms of CPU per second
• At 80ms per request, the same attack occupies 800ms of CPU per second (+60%)
• At 500ms (the proposed upper bound), it becomes 5,000ms of CPU per second (10x)

Combined with the fact that triggerConstantContract is free and requires no TRX, raising the timeout without concurrent execution limits significantly lowers the cost of DoS attacks.

Suggestion: keep 50ms as the minimum default

Given that:

1. 99% of real-world constant calls consume < 3,490 Energy, which completes in single-digit milliseconds
2. The use case for longer timeouts is complex contract development/debugging, not production queries
3. Raising the timeout increases DoS surface proportionally

I'd suggest:

• Keep the default at 50ms (or current mainnet value) as the minimum safe baseline
• If users need to test complex contracts that exceed this timeout, they can use java-tron Toolkit to fork mainnet locally and run tests on a private chain with relaxed limits, rather than requiring public API nodes to serve these heavy computations
• If constantCallTimeoutMs is implemented, pair it with mandatory concurrent execution limits (e.g., GlobalPreemptibleAdapter) to cap the total CPU a node exposes to free constant calls — this is mentioned in the implementation requirements but deserves emphasis

This way, public API nodes stay protected, while developers with specialized needs can self-serve via local forks.

[yanghang8612]

Thanks @warku123 for the detailed data — but I'd like to push back on several points, because the analysis and the conclusion don't quite line up with the intent of this proposal.

1. On the first section (Energy distribution of the top 100 contracts).

I'm not sure what this data is meant to argue for. The fact that 90% of existing mainnet calls finish under 1,024 Energy shows that the current 80ms ceiling is fine for those calls — but it says nothing about the calls that cannot be served today precisely because they hit OUT_OF_TIME. Those are exactly the use cases this feature targets (bulk state queries, deep cross-contract simulation, complex view functions). Selecting from the population that already fits in 80ms and then concluding 80ms is enough is circular.

2. On the pressure-testing section.

The "CPU consumed per second = timeout × concurrency" calculation is just arithmetic — it isn't a pressure test. A real evaluation would need to measure the actual impact on node health under load: block processing latency, mempool handling, gRPC/HTTP responsiveness, GC behavior, etc. Without those numbers, we can't claim that raising the cap meaningfully degrades node operation; we can only claim that an operator who fails to rate-limit could in theory burn more CPU. That risk is already called out in the proposal's Safeguards section.

3. On the suggestion to keep 50ms / 80ms as the minimum.

If the configurable upper bound is pinned at today's mainnet value, the feature has no purpose — that value is already the status quo. The entire point of this proposal is to give operators the ability to opt in to a longer window when their workload justifies it. Pinning the ceiling at the current default defeats the design.

4. On the framing of DoS risk.

DoS exposure on triggerconstantcontract / eth_call is not a new risk introduced by this feature — it is an inherent property of any free, read-only RPC. The correct mitigation layer is operational: rate limiting, per-IP concurrency caps, auth, reverse-proxy throttling, and separating public from internal RPC endpoints. Those are the operator's responsibility, not something we should attempt to solve by hard-coding a single global TVM timeout. This proposal already lists these safeguards; I'd rather strengthen that section than retreat from the configurability the feature is meant to provide.