[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 vm.constantCallTimeoutMs in config.conf:

vm {
  # Max TVM execution time (ms) for constant calls. Omit to keep the current
  # behaviour (constant calls share the block-processing deadline derived
  # from the network's maxCpuTimeOfOneTx). When set, must be a positive
  # integer; the value is used verbatim as the per-call deadline.
  # constantCallTimeoutMs = 100
}

Behavior:

• Applies only to constant calls — triggerconstantcontract, triggersmartcontract dispatched to view/pure functions, estimateenergy, eth_call, eth_estimateGas, and any other RPC routed through Wallet.callConstantContract.
• Does not affect TVM execution during block processing or transaction broadcasting.
• The configured value is used as the per-call deadline as-is. No clamp against the network's maxCpuTimeOfOneTx, no cpuLimitInUsRatio scaling.
• Operator opt-in is detected via Config#hasPath: the property is intentionally absent from reference.conf, so a node that does not write the property in its own config.conf is unaffected.
• Validation runs only when the operator opts in: explicit 0 and negative values are rejected at config-load time.

Safeguards

• Validation at config-load: when the operator sets vm.constantCallTimeoutMs, the value must be a positive integer; 0 and negative values are rejected with a clear error.
• Block-processing path is structurally unaffected: the new branch in VMActuator.create() / call() is gated by isConstantCall, so it is unreachable from block validation by structure, not by convention.
• Throttling concurrent constant calls is left to the operator's infrastructure (reverse proxy / API gateway / per-IP limits). Earlier drafts proposed an in-process vm.constantCallMaxConcurrency cap, but the in-PR review concluded that hard-gating at the node would false-positive on deployments that already throttle externally and that the additional surface area was not justified for the threat model.

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.

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 the constant-call timeout through the invoke / program context — not a new global flag, and not by mutating maxCpuTimeOfOneTx * ratio — so the block-processing deadline remains untouched by design, not by convention.
• Validate at config-load: reject 0 or negative values when the operator opts in.

Migration from --debug

Operators currently running with --debug purely to extend the constant-call window should switch to constantCallTimeoutMs=<ms> once this lands. --debug additionally extends the block-processing timeout, which is unsafe for any node serving traffic (see #6266). The release notes and the constantCallTimeoutMs config reference will cross-link this migration note so operators on the upgrade path see it in both places.

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.

[alan-eth]

Really appreciate how this proposal documents the design evolution — tracing #6266 → #6288 → here makes the reasoning easy to follow, and the separation-of-responsibility argument for a node-level config is clean. 👍

Documenting the migration path for one specific --debug use case. To be clear, I'm not suggesting --debug should be deprecated — it still has its own debugging value. But historically, operators who needed a longer constant-call window had only one lever: --debug, which unfortunately also extends the block-processing timeout (unsafe, per #6266). This proposal gives them a clean, scoped alternative for that specific need. It would help to explicitly call out in the docs/release notes: "if you were using --debug purely to unlock constant-call headroom, switch to constantCallTimeoutMs — you'll get the same headroom without the block-processing risk." Otherwise operators may keep reaching for --debug out of habit and continue carrying the block-processing risk unnecessarily.

[yanghang8612]

@alan-eth Thanks, good operational point. The "I've always run with --debug" habit is real and stickier than we tend to assume — the docs shouldn't rely on operators discovering the migration on their own.

When this lands I'll make sure both touchpoints spell it out:

• Release notes will include an explicit migration pointer along the lines of:

  If you were running with --debug primarily to extend the constant-call timeout, switch to constantCallTimeoutMs=<ms> in your config. --debug also extends the block-processing timeout, which is unsafe for any node serving traffic; the new option gives you the same constant-call headroom without that risk. See Using a full node for reading #6266 for background.

• constantCallTimeoutMs config reference will cross-link --debug with the same migration note, so anyone still on the old lever sees it in both places.

I'll fold both into the PR that ships this feature.

[alan-eth]

Thanks @yanghang8612, much appreciated! Covering both the release notes and the constantCallTimeoutMs config reference is exactly the right call — it catches operators on the upgrade path as well as anyone discovering the flag later. The example wording you drafted already reads well, especially the explicit link back to #6266 for context. Happy to help review the docs portion when the PR lands.

[warku123]

@yanghang8612 Fair pushback on all four points — I'll address them directly.

On the energy distribution data and the 50ms suggestion: you're right on both. The sample is circular (it only covers calls that already succeed), and pinning the ceiling at the current default defeats the purpose of the feature. I withdraw both arguments.

On DoS risk: agreed that operational mitigations are the correct layer. One question to sharpen the spec: are the concurrency safeguards (e.g. GlobalPreemptibleAdapter) intended as mandatory pre-conditions before constantCallTimeoutMs can be raised, or are they operator-optional recommendations? Making that distinction explicit would close the loop on my concern.

[yanghang8612]

@warku123 Appreciate you circling back on this — and the remaining question is a genuinely useful one to nail down in the spec.

I'd split it into two layers:

In-process mechanism — shipped together with a backward-compatible default. The concurrency cap for constant calls will land alongside constantCallTimeoutMs in the same PR. Crucially, the cap activates only when constantCallTimeoutMs is raised above the baseline default — so nodes that keep the existing configuration see zero behavior change (no new cap, no new queuing, no regression for high-throughput RPC deployments that rely on today's unthrottled constant-call path). The coupling is deliberate: the mode that enlarges the attack surface is exactly the mode that activates the safeguard.

Hard startup precondition — probably not the right lever. Even when the timeout is raised, my leaning is to not have the node refuse to start without an explicit cap tuning:

1. Many operators already throttle above the node (reverse proxy, API gateway, per-IP limits). A hard precondition would produce false-positive startup failures in environments that are already safe by construction.
2. It fits better with the separation-of-responsibility framing from Increase the CPU execution time limit in the TVM of the triggerconstantcontract API #6288 — the binary's role is to make the safe configuration easy and the unsafe one visible, rather than to refuse to run on configurations it can't fully see from the inside.

What the binary will actually do when the timeout is raised: apply the conservative cap default automatically, and emit a clear startup log summarizing the cap in effect and the operator tuning knobs. The config reference and release notes will document the two knobs as a pair, with worked examples for public-facing vs internal deployments.

Net: mechanism mandatory but scoped (no regression for unchanged configs), activation policy operator-owned, unsafe combinations surfaced rather than silently accepted. I'll fold this mandatory-vs-recommended wording — and the "cap activates only when timeout is raised" scoping — into the Safeguards section of the spec so the distinction is captured in the issue itself. Thanks for pushing on it.