refactor(vm): make constant-call throttle per-RPC, not per-VM-call

estimateEnergy and view-method dispatch invoke callConstantContract many
times per request; the prior per-call tryAcquire/release made long
estimates fragile under load. Track permit ownership via a static final
ThreadLocal<Boolean> with no withInitial, set after a successful acquire
and remove()d in finally so worker threads in the gRPC/HTTP pool leave
no map entry behind.

Author: yanghang8612

framework/src/main/java/org/tron/core/Wallet.java

@@ -283,14 +283,48 @@ public class Wallet {
 
   private static volatile Semaphore constantCallSemaphore;
 
+  /**
+   * Reentrancy flag for the constant-call concurrency cap. Only the OUTERMOST
+   * {@link #callConstantContract} frame on a given thread takes/releases a
+   * permit; inner frames (e.g., the binary-search loop inside
+   * {@link #estimateEnergy}, or {@link #triggerContract} dispatching to a
+   * view/pure method) read this flag and skip the throttle, so a single
+   * top-level RPC occupies one slot for its full lifetime regardless of how
+   * many internal VM invocations it performs. Issue #6681.
+   *
+   * <p>Memory-safety:
+   * <ul>
+   *   <li>The field is {@code static final}, so the {@code WeakReference} key
+   *       inside each worker thread's {@code ThreadLocalMap} stays live for
+   *       the JVM lifetime — no stale-key cleanup story to worry about.</li>
+   *   <li>No {@code withInitial(...)}: a thread that never enters the
+   *       throttled path never has an entry created in its
+   *       {@code ThreadLocalMap}. {@link ThreadLocal#get() get()} returns
+   *       {@code null} for those threads.</li>
+   *   <li>The value is always {@code Boolean.TRUE} (a JVM-cached singleton).
+   *       The outermost frame {@link ThreadLocal#remove() remove()}s the
+   *       entry in {@code finally} so the map slot is reclaimed before the
+   *       worker returns to the gRPC/HTTP pool.</li>
+   * </ul>
+   *
+   * <p>Correctness depends on the codebase's single-thread-per-request
+   * invariant for both gRPC sync handlers (see {@code RpcService} which wires
+   * a {@code newFixedThreadPool} into {@code NettyServerBuilder.executor}) and
+   * the HTTP servlet handlers. Any future refactor that offloads VM work to
+   * a different thread mid-request must re-evaluate this guard.
+   */
+  private static final ThreadLocal<Boolean> CONSTANT_CALL_PERMIT_HELD =
+      new ThreadLocal<>();
+
   private static Semaphore getConstantCallSemaphore() {
     Semaphore s = constantCallSemaphore;
     if (s == null) {
       synchronized (Wallet.class) {
         s = constantCallSemaphore;
         if (s == null) {
-          s = new Semaphore(
-              CommonParameter.getInstance().getConstantCallMaxConcurrency(), true);
+          // Non-fair: tryAcquire() (no-arg) bypasses the fair queue regardless
+          // of this flag, so requesting fairness here is misleading.
+          s = new Semaphore(CommonParameter.getInstance().getConstantCallMaxConcurrency());
           constantCallSemaphore = s;
         }
       }
@@ -3177,15 +3211,31 @@ public Transaction callConstantContract(TransactionCapsule trxCap,
       throw new ContractValidateException("this node does not support constant");
     }
 
-    long networkMaxCpuTimeOfOneTxMs = chainBaseManager.getDynamicPropertiesStore()
-        .getMaxCpuTimeOfOneTx();
-    boolean throttled = VmTimeoutPolicy.isCapEngaged(
-        CommonParameter.getInstance().getConstantCallTimeoutMs(), networkMaxCpuTimeOfOneTxMs);
-    Semaphore sem = throttled ? getConstantCallSemaphore() : null;
-    if (sem != null && !sem.tryAcquire()) {
-      throw new ContractValidateException(
-          "too many concurrent constant calls; configured cap is "
-              + CommonParameter.getInstance().getConstantCallMaxConcurrency());
+    // Reentrancy guard: a single top-level RPC may invoke this method many
+    // times on the same thread — estimateEnergy's binary search runs ~25-30
+    // iterations, and triggerContract dispatches view/pure functions through
+    // here. Only the OUTERMOST frame takes a permit; inner frames see the
+    // ThreadLocal flag and skip the throttle so per-RPC concurrency, not
+    // per-VM-call concurrency, is what we cap. Issue #6681.
+    Semaphore sem = null;
+    boolean acquiredHere = false;
+    if (!Boolean.TRUE.equals(CONSTANT_CALL_PERMIT_HELD.get())) {
+      long networkMaxCpuTimeOfOneTxMs = chainBaseManager.getDynamicPropertiesStore()
+          .getMaxCpuTimeOfOneTx();
+      if (VmTimeoutPolicy.isCapEngaged(
+          CommonParameter.getInstance().getConstantCallTimeoutMs(),
+          networkMaxCpuTimeOfOneTxMs)) {
+        sem = getConstantCallSemaphore();
+        if (!sem.tryAcquire()) {
+          // Throw before set(TRUE) so a failed acquire never pollutes the
+          // ThreadLocalMap.
+          throw new ContractValidateException(
+              "too many concurrent constant calls; configured cap is "
+                  + CommonParameter.getInstance().getConstantCallMaxConcurrency());
+        }
+        CONSTANT_CALL_PERMIT_HELD.set(Boolean.TRUE);
+        acquiredHere = true;
+      }
     }
     try {
       Block headBlock;
@@ -3236,7 +3286,11 @@ public Transaction callConstantContract(TransactionCapsule trxCap,
       trxCap.setResult(ret);
       return trxCap.getInstance();
     } finally {
-      if (sem != null) {
+      if (acquiredHere) {
+        // remove() before release(): clears the slot from this worker's
+        // ThreadLocalMap so it goes back to the pool clean. Required because
+        // the field has no withInitial — only set/remove pairs touch the map.
+        CONSTANT_CALL_PERMIT_HELD.remove();
         sem.release();
       }
     }

framework/src/test/java/org/tron/core/WalletConstantCallThrottleTest.java

@@ -2,11 +2,13 @@
 
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNull;
 import static org.junit.Assert.assertSame;
 import static org.junit.Assert.assertTrue;
 
 import java.lang.reflect.Field;
 import java.lang.reflect.Method;
+import java.lang.reflect.Modifier;
 import java.util.concurrent.Semaphore;
 
 import org.junit.After;
@@ -25,12 +27,15 @@
 public class WalletConstantCallThrottleTest {
 
   private static final Field SEMAPHORE_FIELD;
+  private static final Field PERMIT_HELD_FIELD;
   private static final Method GET_SEMAPHORE_METHOD;
 
   static {
     try {
       SEMAPHORE_FIELD = Wallet.class.getDeclaredField("constantCallSemaphore");
       SEMAPHORE_FIELD.setAccessible(true);
+      PERMIT_HELD_FIELD = Wallet.class.getDeclaredField("CONSTANT_CALL_PERMIT_HELD");
+      PERMIT_HELD_FIELD.setAccessible(true);
       GET_SEMAPHORE_METHOD = Wallet.class.getDeclaredMethod("getConstantCallSemaphore");
       GET_SEMAPHORE_METHOD.setAccessible(true);
     } catch (NoSuchFieldException | NoSuchMethodException e) {
@@ -103,4 +108,48 @@ public void semaphoreSaturatesAtConfiguredCap() throws Exception {
     sem.release();
     sem.release();
   }
+
+  // ===========================================================================
+  // ThreadLocal reentrancy guard (issue #6681). The flag lets a single
+  // top-level RPC (estimateEnergy's binary search, triggerContract dispatching
+  // a view/pure function, etc.) hold ONE permit across many internal
+  // callConstantContract invocations. These tests pin the memory-safety
+  // invariants the implementation relies on.
+  // ===========================================================================
+
+  @Test
+  public void permitFlagFieldIsStaticFinal() {
+    int mods = PERMIT_HELD_FIELD.getModifiers();
+    // static: one ThreadLocal instance per JVM, key never goes stale in any
+    // worker's ThreadLocalMap.
+    assertTrue("CONSTANT_CALL_PERMIT_HELD must be static",
+        Modifier.isStatic(mods));
+    // final: the WeakReference key inside each worker's ThreadLocalMap stays
+    // valid for the JVM lifetime, so there is no "key collected, value
+    // orphaned" leak path.
+    assertTrue("CONSTANT_CALL_PERMIT_HELD must be final",
+        Modifier.isFinal(mods));
+  }
+
+  @Test
+  @SuppressWarnings("unchecked")
+  public void permitFlagIsLazyAndCleansUpAfterRemove() throws Exception {
+    ThreadLocal<Boolean> tl = (ThreadLocal<Boolean>) PERMIT_HELD_FIELD.get(null);
+
+    // No withInitial(...) — fresh state must read null. Threads that never
+    // enter the throttled path leave no entry behind in their ThreadLocalMap.
+    assertNull("ThreadLocal must not pre-populate; null = not held", tl.get());
+
+    try {
+      tl.set(Boolean.TRUE);
+      assertEquals(Boolean.TRUE, tl.get());
+    } finally {
+      tl.remove();
+    }
+
+    // After remove(), get() must return null again — guarantees that the
+    // worker thread's ThreadLocalMap slot is reclaimed, not left holding a
+    // stale Boolean reference across requests.
+    assertNull("after remove(), get() must return null again", tl.get());
+  }
 }