feat(api): support int64_as_string parameter for GET requests

[waynercheung]

What does this PR do?

Adds an opt-in int64_as_string query parameter on TRON HTTP GET endpoints. When set, int64 / uint64 protobuf fields in the response are serialized as quoted JSON strings (e.g. "123456789012345" instead of 123456789012345), preventing precision loss in clients whose native number type cannot safely represent integers above 2^53 - 1 (e.g. JavaScript).

# Without flag (unchanged from current develop)
$ curl http://node/wallet/getnowblock | jq .block_header.raw_data.timestamp
1700000000000
 
# With flag
$ curl 'http://node/wallet/getnowblock?int64_as_string=true' | jq .block_header.raw_data.timestamp
"1700000000000"

Scope: GET only, by design.

POST is intentionally unsupported. Reading the body in a centralized location (RateLimiterServlet.service or a Servlet Filter) would consume request.getReader(), which TRON's existing 25 servlets already consume themselves for business logic. Centralizing POST would require introducing a CachingHttpServletRequestWrapper to make the body re-readable -- significant infrastructure (~150 lines), runtime overhead (every POST body byte-copied to memory), and edge cases (multipart, encoding, large bodies). The simpler and lower-risk approach is to limit this flag to GET.

Most TRON query endpoints support both GET and POST. JS clients that need precision can use the GET form. POST-only write endpoints (Transfer / Trigger / Proposal*) return Transaction proto whose int64 fields would break round-trip JsonFormat.merge if quoted -- those clients should not enable this flag in the first place.

Backward compatibility: when the parameter is absent or false, every response is byte-identical to current develop -- same JSON shape, same error messages, same log output, same exception paths.

---

Why are these changes required?

JavaScript Number is IEEE 754 double-precision with 53 bits of mantissa. Any int64 / uint64 value larger than 2^53 - 1 loses precision when consumed as a JS number -- for example, an account balance of 9007199254740993 becomes 9007199254740992. Many TRON HTTP fields routinely exceed this threshold (balance, frozen.amount, energy/bandwidth limits, transaction fee_limit, block timestamp in microseconds, etc.).

The standard mitigation across protobuf JSON ecosystems (proto3 JSON spec, Google's protobuf-java JsonFormat) is to emit 64-bit integers as quoted strings. This PR brings TRON's HTTP API in line with that convention while keeping the new behavior fully opt-in.

Closes #6568.

---

This PR has been tested by:

• Unit Tests -- 19 tests across 2 files, all passing locally:

  • JsonFormatInt64AsStringTest (13 tests): default behavior, int64 / uint64 quoting, non-int64 fields unaffected, nested / map / boundary values (2^53 ± 1, Long.MAX/MIN, -1), state cleanup (normal close, after exception, explicit clear), thread isolation, thread-reuse anti-pollution.
  • RateLimiterServletInt64Test (6 tests): end-to-end integration pinning four contracts:
    1. GET with ?int64_as_string=true produces quoted int64 fields.
    2. GET without flag produces unquoted int64 fields (regression baseline).
    3. POST never honors the flag (pins the GET-only design contract).
    4. service()'s finally block clears the ThreadLocal (defends against silent leak across reused Tomcat threads).
    5. Hand-built JSON servlets (GetBurnTrx / GetPendingSize / GetTransactionCountByBlockNum / GetReward) honor the flag through their isInt64AsString() ? quoted : unquoted ternary -- mutation-tested against ternary inversion.
    6. Hand-built JSON servlets default to unquoted output (regression baseline).

• Manual Testing -- recommended pre-merge: hit a few endpoints with and without the flag, diff the JSON shape, confirm no regression on the default path.

---

Follow up

1. Documentation update -- client-facing docs should note: (1) the flag is honored only on GET requests; (2) when set, responses containing Transaction / Block / TransactionExtention / TransactionSignWeight / TransactionApprovedList proto structures cannot be re-parsed by JsonFormat.merge (the parser does not accept quoted int64 input). Clients that need precision and only consume the response should enable the flag; clients that need round-trip should leave it off.
2. POST support (optional, future) -- if clients later request POST support, it can be added in an independent follow-up PR by introducing a Servlet Filter + CachingHttpServletRequestWrapper. The trade-offs of that approach (body memory caching, multipart edge cases) deserve their own scoped review.
3. JSON-RPC -- out of scope for this PR. If JS clients hit similar precision issues via the JSON-RPC layer, it would be addressed separately.
4. Two endpoints bypass JsonFormat -- /wallet/getnodeinfo and /monitor/getstatsinfo serialize their POJO responses (NodeInfo / MetricsInfo) directly via fastjson, so int64_as_string has no effect there. The long fields they expose (memory sizes, network counters, sync numbers, sampling intervals) are well within JS safe integer range in any realistic deployment, so this is a contract-consistency note rather than a precision concern. Can be addressed in a follow-up by passing SerializerFeature.BrowserCompatible to JSON.toJSONString conditionally.

---

Extra details

Files changed (9 total).

Core machinery:

• JsonFormat.java: INT64_AS_STRING ThreadLocal + setInt64AsString / clearInt64AsString / isInt64AsString helpers; split INT64 and UINT64 branches in printFieldValue to emit quoted strings only when the flag is set. When the flag is unset, the code path is byte-identical to develop.
• Util.java: INT64_AS_STRING constant + getInt64AsString (URL query, mirrors getVisible).
• RateLimiterServlet.service: set ThreadLocal from URL query on GET only; clear in finally so reused Tomcat threads do not leak state across requests. The finally clear has a defensive comment because removing it silently breaks request isolation.
  Hand-built JSON responses (4 files) -- these emit JSON literals manually instead of going through JsonFormat.printToString, so they read JsonFormat.isInt64AsString() to choose between quoted and unquoted format:
• GetBurnTrxServlet: burnTrxAmount field
• GetPendingSizeServlet: pendingSize field
• GetTransactionCountByBlockNumServlet: count field
• GetRewardServlet: reward field
  Test coverage:
• JsonFormatInt64AsStringTest (mechanism level)
• RateLimiterServletInt64Test (end-to-end integration, including critical defense against ThreadLocal leakage)
  ~50 other read-only query servlets automatically pick up the flag through the centralized RateLimiterServlet.service GET path with zero changes at the call site.

Sample contract for clients

int64_as_string parameter (issue #6568):
 
  Format:
    GET /wallet/<endpoint>?int64_as_string=true
 
  Behavior:
    When set, all int64/uint64 fields in the response are serialized as
    quoted JSON strings. This avoids precision loss in clients whose native
    number type cannot safely represent integers above 2^53 - 1 (e.g.,
    JavaScript).
 
  Limitation:
    Only honored on GET requests. POST requests always emit unquoted int64
    fields. If you need precision-safe responses, use GET; the same data is
    available on the GET form of every dual-method endpoint.
 
  Round-trip note:
    Responses containing Transaction / Block / TransactionExtention /
    TransactionSignWeight / TransactionApprovedList proto structures
    cannot be re-parsed by JsonFormat.merge when this flag is enabled.
    If your client needs round-trip (e.g., signing, broadcasting), do not
    enable this flag.

[halibobo1205]

LGTM

[317787106]

@waynercheung It’s a bit unfortunate that POST request parameters are not supported, as the functionality feels somewhat incomplete. Do you have plans to support this in the future?

This PR — java-tron PR #6728 — introduced CachedBodyRequestWrapper and added request validation.

[waynercheung]

@waynercheung It’s a bit unfortunate that POST request parameters are not supported, as the functionality feels somewhat incomplete. Do you have plans to support this in the future?

This PR — java-tron PR #6728 — introduced CachedBodyRequestWrapper and added request validation.

@317787106 Thanks for raising this. A few reasons this PR stays GET-only:

1. int64_as_string is a pure read-side format flag, the kind of parameter that semantically belongs on GET. REST conventions place query/format parameters on retrieval verbs, not on POST -- POST is conceptually for state-changing or non-idempotent operations. Extending a new format flag to POST would tie it into a legacy pattern (POST-for-read) that we'd rather not amplify going forward. Existing endpoints that historically accept POST for reads continue to work as before; we're simply not extending new format flags to that pattern.

2. POST body retrieval in TRON's HTTP layer is fragmented: 25+ servlets read the POST body in three different ways (PostParams.getPostParams, inline request.getReader(), Util.getRequestValue). There is no single chokepoint where int64_as_string can be extracted from POST body without either patching every servlet individually or introducing global request-body-caching infrastructure. The wrapper from feat(jsonrpc): add resource restrict for jsonrpc #6728 helps on the second point but does not address the first.

3. feat(jsonrpc): add resource restrict for jsonrpc #6728 is still open and registers CachedBodyRequestWrapper only inside JsonRpcServlet.service(), not at the HTTP servlet layer. There's also an unresolved spec-compliance comment from @bladehan1 about getInputStream() / getReader() mutual exclusivity. So the infrastructure is not directly reusable for the HTTP layer yet.

If POST support becomes a clear need, I'd rather do it properly as a follow-up once #6728 lands and the spec issue is resolved -- happy to file a tracking issue at that point so it doesn't get lost.