fix: token contract handling and test validation (#33)

* feat(tests): add randomization for cron test variance

Add --sample, --random-lifecycle, and --random-token flags to support
randomized test runs. This provides variance across cron executions
while ensuring full endpoint coverage over the course of a day.

- Add shuffle(), sampleArray(), pickRandom() helpers
- Update test runner to support sampling flags
- Update cron script to use randomization (3 stateless + 2 lifecycle)
- For mainnet: randomly select STX/sBTC/USDCx each run
- Document new flags in CLAUDE.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: correct testnet USDCx contract address

- Testnet USDCx: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(tests): validate asset against expected contract ID not token symbol

The test runner was comparing requirements.asset (full contract ID like
SM3VDXK3...sbtc-token) against tokenType (symbol like "sBTC"). This worked
for STX but failed for sBTC and USDCx.

- Add EXPECTED_ASSETS mapping matching TOKEN_CONTRACTS in middleware
- Add getExpectedAsset() helper to resolve token type to contract ID
- Update validation to compare against expected asset string

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(tests): add input validation to sampling helpers

Address Copilot review feedback:
- sampleArray: validate n for NaN/negative/non-integer values
- pickRandom: throw on empty array instead of returning undefined

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(tests): validate CLI args and fix random token display

Address additional Copilot review feedback:
- Validate --sample and --random-lifecycle args for NaN/invalid values
- Clear randomToken flag when tokens are explicitly specified to avoid
  misleading "(random)" suffix in output

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: whoabuddy

CLAUDE.md

@@ -34,6 +34,12 @@ npm run test:kv       # Just KV lifecycle test
 # Filter tests
 bun run tests/_run_all_tests.ts --category=hashing
 bun run tests/_run_all_tests.ts --filter=sha256 --all-tokens
+
+# Randomized tests (for cron variance)
+bun run tests/_run_all_tests.ts --sample=5                      # 5 random stateless
+bun run tests/_run_all_tests.ts --random-lifecycle=2            # 2 random lifecycle
+bun run tests/_run_all_tests.ts --random-token                  # Random STX/sBTC/USDCx
+bun run tests/_run_all_tests.ts --mode=full --sample=3 --random-lifecycle=2 --random-token
 ```
 
 ## Domains

scripts/run-tests-cron.sh

@@ -1,8 +1,16 @@
 #!/bin/bash
-# Cron script to run full test suite - only logs failures
+# Cron script to run randomized test samples - ensures full coverage over time
 # Usage: ./scripts/run-tests-cron.sh [--network=testnet|mainnet]
-# Cron:  0 4,12,20 * * * /path/to/run-tests-cron.sh
-#        0 10      * * * /path/to/run-tests-cron.sh --network=mainnet
+#
+# Recommended cron schedule (every 2 hours for testnet, every 4 hours for mainnet):
+#   0 */2 * * * /path/to/run-tests-cron.sh                        # testnet (12x/day)
+#   0 2,6,10,14,18,22 * * * /path/to/run-tests-cron.sh --network=mainnet  # mainnet (6x/day)
+#
+# Coverage calculation:
+#   - 14 stateless endpoints, 7 lifecycle categories
+#   - Each run: 3 stateless + 2 lifecycle = good variance
+#   - Testnet (12x/day): 36 stateless + 24 lifecycle = ~2.5x coverage
+#   - Mainnet (6x/day): 18 stateless + 12 lifecycle = ~1.3x coverage, random token each run
 
 # Set up PATH for cron environment (bun, node, npm, etc.)
 NODE_VERSIONS_DIR="$HOME/.nvm/versions/node"
@@ -73,8 +81,17 @@ echo "Network: ${X402_NETWORK}" >> "$TEMP_LOG"
 echo "Server: (derived from network)" >> "$TEMP_LOG"
 echo "" >> "$TEMP_LOG"
 
-# Run the full test suite
-bun run tests/_run_all_tests.ts --mode=full >> "$TEMP_LOG" 2>&1
+# Build test command based on network
+# - Both: sample 3 stateless endpoints + 2 random lifecycle categories
+# - Mainnet: also randomize token (STX/sBTC/USDCx)
+if [ "$X402_NETWORK" = "mainnet" ]; then
+  TEST_ARGS="--mode=full --sample=3 --random-lifecycle=2 --random-token"
+else
+  TEST_ARGS="--mode=full --sample=3 --random-lifecycle=2"
+fi
+
+# Run the randomized test suite
+bun run tests/_run_all_tests.ts $TEST_ARGS >> "$TEMP_LOG" 2>&1
 EXIT_CODE=$?
 
 echo "" >> "$TEMP_LOG"

src/middleware/x402.ts

@@ -60,7 +60,7 @@ const TOKEN_CONTRACTS: Record<"mainnet" | "testnet", Record<"sBTC" | "USDCx", To
   },
   testnet: {
     sBTC: { address: "ST1F7QA2MDF17S807EPA36TSS8AMEFY4KA9TVGWXT", name: "sbtc-token" },
-    USDCx: { address: "ST1NXBK3K5YYMD6FD41MVNP3JS1GABZ8TRVX023PT", name: "token-susdc" },
+    USDCx: { address: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM", name: "usdcx" },
   },
 };
 

tests/_run_all_tests.ts

@@ -18,6 +18,12 @@
  *   bun run tests/_run_all_tests.ts --delay=1000       # 1s delay between tests
  *   bun run tests/_run_all_tests.ts --retries=3        # 3 retries for rate limits
  *
+ * Randomization (for cron variance):
+ *   bun run tests/_run_all_tests.ts --sample=5         # Run 5 random stateless endpoints
+ *   bun run tests/_run_all_tests.ts --random-lifecycle=2  # Run 2 random lifecycle categories
+ *   bun run tests/_run_all_tests.ts --random-token     # Pick one random token (STX/sBTC/USDCx)
+ *   bun run tests/_run_all_tests.ts --mode=full --sample=5 --random-lifecycle=2 --random-token
+ *
  * Environment:
  *   X402_CLIENT_PK      - Mnemonic for payments (required)
  *   X402_NETWORK        - Network (default: testnet)
@@ -43,6 +49,7 @@ import {
   X402_CLIENT_PK,
   X402_NETWORK,
   X402_WORKER_URL,
+  TEST_TOKENS,
   createTestLogger,
   DEFAULT_TEST_DELAY_MS,
   POST_LIFECYCLE_DELAY_MS,
@@ -51,6 +58,8 @@ import {
   calculateBackoff,
   sleep,
   NONCE_CONFLICT_DELAY_MS,
+  sampleArray,
+  pickRandom,
 } from "./_shared_utils";
 
 // Import lifecycle test runners
@@ -79,6 +88,35 @@ const LIFECYCLE_RUNNERS: Record<
   inference: runInferenceLifecycle,
 };
 
+// =============================================================================
+// Expected Assets (must match TOKEN_CONTRACTS in src/middleware/x402.ts)
+// =============================================================================
+
+/**
+ * Expected asset strings for each token type per network.
+ * STX is always "STX", SIP-010 tokens use "address.contract-name" format.
+ */
+const EXPECTED_ASSETS: Record<"mainnet" | "testnet", Record<TokenType, string>> = {
+  mainnet: {
+    STX: "STX",
+    sBTC: "SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token",
+    USDCx: "SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx",
+  },
+  testnet: {
+    STX: "STX",
+    sBTC: "ST1F7QA2MDF17S807EPA36TSS8AMEFY4KA9TVGWXT.sbtc-token",
+    USDCx: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx",
+  },
+};
+
+/**
+ * Get expected asset string for a token type on current network
+ */
+function getExpectedAsset(tokenType: TokenType): string {
+  const network = X402_NETWORK as "mainnet" | "testnet";
+  return EXPECTED_ASSETS[network][tokenType];
+}
+
 // =============================================================================
 // Error Types
 // =============================================================================
@@ -162,6 +200,10 @@ interface RunConfig {
   verbose: boolean;
   delayMs: number;
   maxRetries: number;
+  // Randomization options
+  sampleSize: number | null; // --sample=N: run N random stateless endpoints
+  randomLifecycleCount: number | null; // --random-lifecycle=N: run N random lifecycle categories
+  randomToken: boolean; // --random-token: pick one random token
 }
 
 function parseArgs(): RunConfig {
@@ -175,6 +217,10 @@ function parseArgs(): RunConfig {
     verbose: process.env.VERBOSE === "1",
     delayMs: parseInt(process.env.TEST_DELAY_MS || String(DEFAULT_TEST_DELAY_MS), 10),
     maxRetries: parseInt(process.env.TEST_MAX_RETRIES || "3", 10),
+    // Randomization defaults
+    sampleSize: null,
+    randomLifecycleCount: null,
+    randomToken: false,
   };
 
   let tokenSpecified = false;
@@ -187,6 +233,9 @@ function parseArgs(): RunConfig {
     } else if (arg === "--all-tokens") {
       config.tokens = ["STX", "sBTC", "USDCx"];
       tokenSpecified = true;
+    } else if (arg === "--random-token") {
+      // Pick one random token - applied after parsing
+      config.randomToken = true;
     } else if (arg.startsWith("--token=")) {
       const rawToken = arg.split("=")[1].toUpperCase();
       // Normalize token name (SBTC -> sBTC, USDCX -> USDCx)
@@ -204,6 +253,16 @@ function parseArgs(): RunConfig {
           config.tokens.push(token);
         }
       }
+    } else if (arg.startsWith("--sample=")) {
+      const sampleValue = parseInt(arg.split("=")[1], 10);
+      if (!Number.isNaN(sampleValue) && sampleValue > 0) {
+        config.sampleSize = sampleValue;
+      }
+    } else if (arg.startsWith("--random-lifecycle=")) {
+      const lifecycleValue = parseInt(arg.split("=")[1], 10);
+      if (!Number.isNaN(lifecycleValue) && lifecycleValue > 0) {
+        config.randomLifecycleCount = lifecycleValue;
+      }
     } else if (arg.startsWith("--category=")) {
       config.category = arg.split("=")[1].toLowerCase();
     } else if (arg.startsWith("--filter=")) {
@@ -219,6 +278,14 @@ function parseArgs(): RunConfig {
     }
   }
 
+  // Apply random token selection if requested (only if tokens weren't explicitly specified)
+  if (config.randomToken && !tokenSpecified) {
+    config.tokens = [pickRandom(TEST_TOKENS)];
+  } else if (config.randomToken && tokenSpecified) {
+    // Clear randomToken flag if tokens were explicitly set (so we don't print "(random)")
+    config.randomToken = false;
+  }
+
   return config;
 }
 
@@ -308,11 +375,12 @@ async function testEndpointWithToken(
       // Get the payment requirements from accepts array (inside loop to use fresh requirements after retry)
       const requirements = paymentReq.accepts[0];
 
-      // Validate that the accepted asset matches the requested token type
-      if (requirements.asset !== tokenType) {
+      // Validate that the accepted asset matches the expected asset for this token type
+      const expectedAsset = getExpectedAsset(tokenType);
+      if (requirements.asset !== expectedAsset) {
         return {
           passed: false,
-          error: `Payment requirements asset ${requirements.asset} does not match requested token type ${tokenType}`,
+          error: `Payment requirements asset ${requirements.asset} does not match expected ${expectedAsset} for token type ${tokenType}`,
         };
       }
 
@@ -665,6 +733,16 @@ async function runTests(runConfig: RunConfig): Promise<RunStats> {
     );
   }
 
+  // Apply random sampling if specified
+  if (runConfig.sampleSize !== null && endpointsToTest.length > 0) {
+    endpointsToTest = sampleArray(endpointsToTest, runConfig.sampleSize);
+  }
+
+  // Apply random lifecycle sampling if specified
+  if (runConfig.randomLifecycleCount !== null && lifecycleCategories.length > 0) {
+    lifecycleCategories = sampleArray(lifecycleCategories, runConfig.randomLifecycleCount);
+  }
+
   // Print header
   console.log(`\n${COLORS.bright}${"=".repeat(70)}${COLORS.reset}`);
   console.log(`${COLORS.bright}  X402 API ENDPOINT TEST RUNNER${COLORS.reset}`);
@@ -676,12 +754,17 @@ async function runTests(runConfig: RunConfig): Promise<RunStats> {
   if (runConfig.category) {
     console.log(`  Category:   ${runConfig.category}`);
   }
-  console.log(`  Tokens:     ${runConfig.tokens.join(", ")}`);
+  console.log(`  Tokens:     ${runConfig.tokens.join(", ")}${runConfig.randomToken ? " (random)" : ""}`);
   if (endpointsToTest.length > 0) {
-    console.log(`  Endpoints:  ${endpointsToTest.length} stateless`);
+    const sampleNote = runConfig.sampleSize !== null ? ` (sampled from ${STATELESS_ENDPOINTS.length})` : "";
+    console.log(`  Endpoints:  ${endpointsToTest.length} stateless${sampleNote}`);
+    if (runConfig.sampleSize !== null) {
+      console.log(`              [${endpointsToTest.map((e) => e.name).join(", ")}]`);
+    }
   }
   if (lifecycleCategories.length > 0) {
-    console.log(`  Lifecycle:  ${lifecycleCategories.join(", ")}`);
+    const lifecycleNote = runConfig.randomLifecycleCount !== null ? ` (sampled from ${STATEFUL_CATEGORIES.length})` : "";
+    console.log(`  Lifecycle:  ${lifecycleCategories.join(", ")}${lifecycleNote}`);
   }
   console.log(`  Delay:      ${runConfig.delayMs}ms between tests`);
   console.log(`  Retries:    ${runConfig.maxRetries} for rate-limited requests`);

tests/_shared_utils.ts

@@ -41,6 +41,47 @@ export const X402_WORKER_URL = getWorkerUrl();
 
 export const TEST_TOKENS: TokenType[] = ["STX", "sBTC", "USDCx"];
 
+// =============================================================================
+// Randomization Helpers
+// =============================================================================
+
+/**
+ * Fisher-Yates shuffle - returns a new shuffled array
+ */
+export function shuffle<T>(array: T[]): T[] {
+  const result = [...array];
+  for (let i = result.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [result[i], result[j]] = [result[j], result[i]];
+  }
+  return result;
+}
+
+/**
+ * Pick N random items from an array (without replacement)
+ */
+export function sampleArray<T>(array: T[], n: number): T[] {
+  if (array.length === 0) return [];
+
+  // Normalize n to a safe, non-negative integer within array bounds
+  let count = Math.floor(n);
+  if (!Number.isFinite(count)) count = 0;
+  if (count <= 0) return [];
+  if (count >= array.length) return shuffle(array);
+
+  return shuffle(array).slice(0, count);
+}
+
+/**
+ * Pick a random item from an array
+ */
+export function pickRandom<T>(array: T[]): T {
+  if (array.length === 0) {
+    throw new Error("pickRandom: cannot pick from an empty array");
+  }
+  return array[Math.floor(Math.random() * array.length)];
+}
+
 // =============================================================================
 // Timing Constants
 // =============================================================================

tests/check-setup.ts

@@ -30,7 +30,7 @@ const MIN_BALANCES = {
 // Token contract identifiers (testnet)
 const TESTNET_TOKENS = {
   sBTC: "ST1F7QA2MDF17S807EPA36TSS8AMEFY4KA9TVGWXT.sbtc-token::sbtc-token",
-  USDCx: "ST1F7QA2MDF17S807EPA36TSS8AMEFY4KA9TVGWXT.usdcx-token::usdcx-token",
+  USDCx: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx::usdcx-token",
 };
 
 // Token contract identifiers (mainnet)