feat(api): add centralized int64_as_string support for #6568

Add a thread-local in JsonFormat that, when set, serializes int64/uint64
proto fields as quoted JSON strings to avoid precision loss in clients
whose native number type cannot safely represent integers above 2^53 - 1
(e.g. JavaScript). The flag is read in strict mode:

- GET requests:  URL query, parsed once in RateLimiterServlet.service
- POST requests: request body, parsed once in PostParams.getPostParams

The thread-local is cleared in service()'s finally block so reused threads
do not leak state across requests. POST URL query is intentionally not
read in service() because calling getParameter() on a POST consumes
application/x-www-form-urlencoded bodies and would break downstream
getReader(). This also gives clients a single, unambiguous contract:
GET reads the URL, POST reads the body.

- JsonFormat: add INT64_AS_STRING ThreadLocal + setInt64AsString /
  clearInt64AsString / isInt64AsString helpers; split printFieldValue
  INT64/SINT64/SFIXED64 and UINT64/FIXED64 branches so they emit quoted
  strings only when the flag is set.
- Util: add INT64_AS_STRING constant + getInt64AsString (URL query,
  mirrors getVisible) + getInt64AsStringPost (JSON body, mirrors
  getVisiblePost). Also extract Util.decodeAddress (shared between
  getAddress and servlets that read the address from a JSON body) and
  add Util.processAddressError (shared "INVALID address" error response).
- PostParams.getPostParams: call JsonFormat.setInt64AsString with the
  parsed body value; cleanup is centralized in RateLimiterServlet.
- RateLimiterServlet.service: set ThreadLocal from URL query on GET;
  clear in finally for both GET and POST.

Author: waynercheung

framework/src/main/java/org/tron/core/services/http/JsonFormat.java

@@ -90,6 +90,42 @@ public class JsonFormat {
       BalanceContract.TransactionBalanceTrace.class
   );
 
+  /**
+   * Thread-local flag controlling whether int64/uint64 fields are serialized as JSON strings.
+   * Set via {@link #setInt64AsString(boolean)} early in request handling and cleared via
+   * {@link #clearInt64AsString()} in a finally block. Centralized in
+   * {@code RateLimiterServlet.service} for GET and in {@code PostParams.getPostParams} for POST.
+   * Does not support nested scopes — a single set/clear pair per request.
+   */
+  private static final ThreadLocal<Boolean> INT64_AS_STRING =
+      ThreadLocal.withInitial(() -> false);
+
+  /**
+   * Set whether int64/uint64 protobuf fields are serialized as quoted JSON strings to avoid
+   * precision loss in clients whose native number type cannot safely represent integers above
+   * 2^53 - 1 (e.g. JavaScript). Must be paired with {@link #clearInt64AsString()} in a
+   * finally block.
+   */
+  public static void setInt64AsString(boolean enabled) {
+    INT64_AS_STRING.set(enabled);
+  }
+
+  /**
+   * Clear the int64-as-string thread-local. Always call from a finally block to avoid
+   * polluting subsequent requests on the same (reused) thread.
+   */
+  public static void clearInt64AsString() {
+    INT64_AS_STRING.remove();
+  }
+
+  /**
+   * Whether the current thread is in int64-as-string mode. Used by servlets that build
+   * JSON literals manually (i.e. do not go through {@link #printToString}).
+   */
+  public static boolean isInt64AsString() {
+    return INT64_AS_STRING.get();
+  }
+
   /**
    * Outputs a textual representation of the Protocol Message supplied into the parameter output.
    * (This representation is the new version of the classic "ProtocolPrinter" output from the
@@ -340,26 +376,41 @@ private static void printFieldValue(FieldDescriptor field, Object value,
       throws IOException {
     switch (field.getType()) {
       case INT32:
-      case INT64:
       case SINT32:
-      case SINT64:
       case SFIXED32:
-      case SFIXED64:
       case FLOAT:
       case DOUBLE:
       case BOOL:
         // Good old toString() does what we want for these types.
         generator.print(value.toString());
         break;
 
+      case INT64:
+      case SINT64:
+      case SFIXED64:
+        if (INT64_AS_STRING.get()) {
+          generator.print("\"");
+          generator.print(value.toString());
+          generator.print("\"");
+        } else {
+          generator.print(value.toString());
+        }
+        break;
+
       case UINT32:
       case FIXED32:
         generator.print(unsignedToString((Integer) value));
         break;
 
       case UINT64:
       case FIXED64:
-        generator.print(unsignedToString((Long) value));
+        if (INT64_AS_STRING.get()) {
+          generator.print("\"");
+          generator.print(unsignedToString((Long) value));
+          generator.print("\"");
+        } else {
+          generator.print(unsignedToString((Long) value));
+        }
         break;
 
       case STRING:

framework/src/main/java/org/tron/core/services/http/PostParams.java

@@ -28,6 +28,10 @@ public static PostParams getPostParams(HttpServletRequest request) throws Except
       input = getJsonString(input);
     }
     boolean visible = Util.getVisiblePost(input);
+    // Strict mode: POST reads int64_as_string from the body only. Set the ThreadLocal here
+    // so all downstream JsonFormat.printToString calls in this request see the right value.
+    // Cleared in RateLimiterServlet.service finally block.
+    JsonFormat.setInt64AsString(Util.getInt64AsStringPost(input));
     return new PostParams(input, visible);
   }
 }

framework/src/main/java/org/tron/core/services/http/RateLimiterServlet.java

@@ -102,6 +102,13 @@ protected void service(HttpServletRequest req, HttpServletResponse resp)
     String contextPath = req.getContextPath();
     String url = Strings.isNullOrEmpty(req.getServletPath())
         ? MetricLabels.UNDEFINED : contextPath + req.getServletPath();
+    // Strict mode: GET reads int64_as_string from URL query here; POST reads it from the
+    // request body in PostParams.getPostParams (or in servlets that manually parse the body).
+    // Calling getParameter() on POST would consume application/x-www-form-urlencoded bodies
+    // and break downstream getReader() — so we deliberately skip URL parsing on POST.
+    if ("GET".equalsIgnoreCase(req.getMethod())) {
+      JsonFormat.setInt64AsString(Util.getInt64AsString(req));
+    }
     try {
       resp.setContentType("application/json; charset=utf-8");
 
@@ -119,6 +126,7 @@ protected void service(HttpServletRequest req, HttpServletResponse resp)
     } catch (Exception unexpected) {
       logger.error("Http Api {}, Method:{}. Error：", url, req.getMethod(), unexpected);
     } finally {
+      JsonFormat.clearInt64AsString();
       if (rateLimiter instanceof IPreemptibleRateLimiter && acquireResource) {
         ((IPreemptibleRateLimiter) rateLimiter).release();
       }

framework/src/main/java/org/tron/core/services/http/Util.java

@@ -66,6 +66,7 @@ public class Util {
 
   public static final String PERMISSION_ID = "Permission_id";
   public static final String VISIBLE = "visible";
+  public static final String INT64_AS_STRING = "int64_as_string";
   public static final String TRANSACTION = "transaction";
   public static final String TRANSACTION_EXTENSION = "transactionExtension";
   public static final String VALUE = "value";
@@ -346,6 +347,18 @@ public static boolean existVisible(final HttpServletRequest request) {
     return Objects.nonNull(request.getParameter(VISIBLE));
   }
 
+  /**
+   * Read int64_as_string from URL query parameter. Mirrors
+   * {@link #getVisible(HttpServletRequest)}. Intended for doGet on whitelisted query
+   * servlets and for any doPost that reads visible from the URL query.
+   */
+  public static boolean getInt64AsString(final HttpServletRequest request) {
+    if (StringUtil.isNotBlank(request.getParameter(INT64_AS_STRING))) {
+      return Boolean.parseBoolean(request.getParameter(INT64_AS_STRING));
+    }
+    return false;
+  }
+
   public static boolean getVisiblePost(final String input) {
     boolean visible = false;
     if (StringUtil.isNotBlank(input)) {
@@ -358,6 +371,21 @@ public static boolean getVisiblePost(final String input) {
     return visible;
   }
 
+  /**
+   * Read int64_as_string from the POST body JSON string. Mirrors
+   * {@link #getVisiblePost(String)}. Used by {@link PostParams#getPostParams} and by
+   * servlets that manually read the request body (e.g. GetPaginatedProposalListServlet).
+   */
+  public static boolean getInt64AsStringPost(final String input) {
+    if (StringUtil.isNotBlank(input)) {
+      JSONObject jsonObject = JSON.parseObject(input);
+      if (jsonObject.containsKey(INT64_AS_STRING)) {
+        return Boolean.parseBoolean(jsonObject.getString(INT64_AS_STRING));
+      }
+    }
+    return false;
+  }
+
   public static String getContractType(final String input) {
     String contractType = null;
     JSONObject jsonObject = JSON.parseObject(input);
@@ -483,6 +511,20 @@ public static void processError(Exception e, HttpServletResponse response) {
     }
   }
 
+  /**
+   * Write an "INVALID address" error JSON to the response. Used by servlets that decode an
+   * address from the request (e.g. GetRewardServlet, GetBrokerageServlet) to keep the error
+   * payload shape consistent and avoid duplicating the catch block.
+   */
+  public static void processAddressError(Exception e, HttpServletResponse response) {
+    try {
+      response.getWriter()
+          .println("{\"Error\": " + "\"INVALID address, " + e.getMessage() + "\"}");
+    } catch (IOException ioe) {
+      logger.debug("IOException: {}", ioe.getMessage());
+    }
+  }
+
   public static String convertOutput(Account account) {
     if (account.getAssetIssuedID().isEmpty()) {
       return JsonFormat.printToString(account, false);
@@ -509,17 +551,22 @@ public static void printAccount(Account reply, HttpServletResponse response, Boo
   }
 
   public static byte[] getAddress(HttpServletRequest request) throws Exception {
-    byte[] address = null;
-    String addressParam = "address";
-    String addressStr = checkGetParam(request, addressParam);
-    if (StringUtils.isNotBlank(addressStr)) {
-      if (StringUtils.startsWith(addressStr, Constant.ADD_PRE_FIX_STRING_MAINNET)) {
-        address = Hex.decode(addressStr);
-      } else {
-        address = decodeFromBase58Check(addressStr);
-      }
+    return decodeAddress(checkGetParam(request, "address"));
+  }
+
+  /**
+   * Decode an address string (hex with mainnet prefix, or base58check) to raw bytes.
+   * Returns null for blank input. Shared by {@link #getAddress(HttpServletRequest)} and by
+   * servlets that parse the address from a manually-read JSON body (e.g. GetRewardServlet).
+   */
+  public static byte[] decodeAddress(String addressStr) {
+    if (StringUtils.isBlank(addressStr)) {
+      return null;
+    }
+    if (StringUtils.startsWith(addressStr, Constant.ADD_PRE_FIX_STRING_MAINNET)) {
+      return Hex.decode(addressStr);
     }
-    return address;
+    return decodeFromBase58Check(addressStr);
   }
 
   private static String checkGetParam(HttpServletRequest request, String key) throws Exception {