test(vm): add Wallet throttle test, tighten cap-engagement docs

Reflective test on Wallet.constantCallSemaphore covers permit
count, lazy-init idempotency, and freeze-at-first-call. Sample
docs now state the exact engagement condition.

Author: yanghang8612

common/src/main/java/org/tron/common/parameter/CommonParameter.java

@@ -68,9 +68,9 @@ public class CommonParameter {
   @Setter
   public long constantCallTimeoutMs = 0L;
   /**
-   * Max concurrent constant-call executions. Cap is engaged only when
-   * constantCallTimeoutMs exceeds the baseline default; nodes leaving the
-   * timeout at its default see no behaviour change.
+   * Max concurrent constant-call executions. The cap engages strictly when
+   * constantCallTimeoutMs exceeds the network's current maxCpuTimeOfOneTx;
+   * nodes leaving constantCallTimeoutMs at its default see no throttling.
    */
   @Getter
   @Setter

common/src/main/resources/reference.conf

@@ -717,8 +717,11 @@ vm = {
   # block-processing, which is unsafe; see issue #6266).
   constantCallTimeoutMs = 0
 
-  # Max concurrent constant-call executions. Engages only when
-  # constantCallTimeoutMs is raised above 80.
+  # Max concurrent constant-call executions. The cap engages strictly when
+  # constantCallTimeoutMs exceeds the network's current maxCpuTimeOfOneTx;
+  # nodes leaving constantCallTimeoutMs at 0 see no throttling. Note: a
+  # committee proposal that lowers maxCpuTimeOfOneTx may newly engage the
+  # cap on nodes that previously satisfied configured <= network.
   constantCallMaxConcurrency = 10
 }
 

framework/src/main/resources/config.conf

@@ -713,15 +713,17 @@ vm = {
 
   # -- Constant-call timeout (issue #6681) --
   # Max TVM execution time (ms) for constant calls (triggerconstantcontract /
-  # eth_call). 0 = use the same deadline as block processing. Allowed values:
-  # 0 or in [80, 500]. Raising this value engages a concurrency cap (see
-  # constantCallMaxConcurrency). If you previously ran with --debug to extend
-  # constant calls, switch to this option: --debug also extends block-processing
-  # time which can desync the node (see issue #6266).
+  # eth_call). 0 = use the same deadline as block processing. When set, must
+  # be in [80, 500]. Migration note: if previously running --debug to extend
+  # constant calls, switch to this option (--debug also extends block-processing,
+  # which is unsafe; see issue #6266).
   # constantCallTimeoutMs = 0
 
-  # Max concurrent constant-call executions. Engages only when
-  # constantCallTimeoutMs is raised above 80. Default: 10.
+  # Max concurrent constant-call executions. The cap engages strictly when
+  # constantCallTimeoutMs exceeds the network's current maxCpuTimeOfOneTx;
+  # nodes leaving constantCallTimeoutMs at 0 see no throttling. Note: a
+  # committee proposal that lowers maxCpuTimeOfOneTx may newly engage the
+  # cap on nodes that previously satisfied configured <= network. Default: 10.
   # constantCallMaxConcurrency = 10
 }
 

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

@@ -0,0 +1,106 @@
+package org.tron.core;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.util.concurrent.Semaphore;
+
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+import org.tron.common.parameter.CommonParameter;
+
+/**
+ * Verifies the lazy-init contract for {@code Wallet.constantCallSemaphore}:
+ * permit count is taken from {@code CommonParameter.constantCallMaxConcurrency}
+ * at first call, and subsequent calls return the same instance. Together with
+ * {@link org.tron.core.vm.VmTimeoutPolicyTest} (which covers
+ * {@code isCapEngaged}), this is the integration-level coverage for the
+ * constant-call throttle wired up in {@code Wallet.callConstantContract}.
+ */
+public class WalletConstantCallThrottleTest {
+
+  private static final Field SEMAPHORE_FIELD;
+  private static final Method GET_SEMAPHORE_METHOD;
+
+  static {
+    try {
+      SEMAPHORE_FIELD = Wallet.class.getDeclaredField("constantCallSemaphore");
+      SEMAPHORE_FIELD.setAccessible(true);
+      GET_SEMAPHORE_METHOD = Wallet.class.getDeclaredMethod("getConstantCallSemaphore");
+      GET_SEMAPHORE_METHOD.setAccessible(true);
+    } catch (NoSuchFieldException | NoSuchMethodException e) {
+      throw new ExceptionInInitializerError(e);
+    }
+  }
+
+  private int savedMaxConcurrency;
+
+  @Before
+  public void setUp() throws Exception {
+    savedMaxConcurrency = CommonParameter.getInstance().getConstantCallMaxConcurrency();
+    SEMAPHORE_FIELD.set(null, null);
+  }
+
+  @After
+  public void tearDown() throws Exception {
+    CommonParameter.getInstance().setConstantCallMaxConcurrency(savedMaxConcurrency);
+    SEMAPHORE_FIELD.set(null, null);
+  }
+
+  private static Semaphore invokeFactory() throws Exception {
+    return (Semaphore) GET_SEMAPHORE_METHOD.invoke(null);
+  }
+
+  @Test
+  public void permitCountTracksConfiguredMaxConcurrency() throws Exception {
+    CommonParameter.getInstance().setConstantCallMaxConcurrency(3);
+
+    Semaphore sem = invokeFactory();
+
+    assertEquals(3, sem.availablePermits());
+  }
+
+  @Test
+  public void factoryIsIdempotent() throws Exception {
+    CommonParameter.getInstance().setConstantCallMaxConcurrency(2);
+
+    Semaphore first = invokeFactory();
+    Semaphore second = invokeFactory();
+
+    assertSame(first, second);
+  }
+
+  @Test
+  public void permitCountFrozenAtFirstCall() throws Exception {
+    CommonParameter.getInstance().setConstantCallMaxConcurrency(1);
+    Semaphore sem = invokeFactory();
+
+    // Mutating the parameter after the semaphore has been created must not
+    // resize it — confirms that operators cannot widen the cap on a live node.
+    CommonParameter.getInstance().setConstantCallMaxConcurrency(99);
+
+    assertSame(sem, invokeFactory());
+    assertEquals(1, sem.availablePermits());
+  }
+
+  @Test
+  public void semaphoreSaturatesAtConfiguredCap() throws Exception {
+    CommonParameter.getInstance().setConstantCallMaxConcurrency(2);
+    Semaphore sem = invokeFactory();
+
+    assertTrue(sem.tryAcquire());
+    assertTrue(sem.tryAcquire());
+    assertFalse("3rd acquire must fail when cap=2", sem.tryAcquire());
+
+    sem.release();
+    assertTrue("permit must replenish after release", sem.tryAcquire());
+
+    sem.release();
+    sem.release();
+  }
+}