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.

---

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.