@deeeed/metamask-harness 0.86.2 → 0.87.0

package/library/actions/shared/perps/rate-limit.mjs

@@ -0,0 +1,93 @@
+// Classify a Hyperliquid HTTP 429 (Too Many Requests) as RATE_LIMITED and retry
+// Perps reads a bounded number of times with exponential backoff and jitter.
+// Farm runs share one testnet account and egress IP, so a 429 is load on the
+// venue, not a product result. Placements never retry here: see
+// runGuardedExternalMutation, which retries only once the venue proves nothing
+// was placed.
+
+export const RATE_LIMITED = 'RATE_LIMITED';
+export const RATE_LIMIT_RETRIES = 3;
+const BASE_BACKOFF_MS = 1_000;
+
+const TOO_MANY_REQUESTS = /too many requests|\b(?:http|status(?:\s*code)?)\s*:?\s*429\b/iu;
+
+export function isRateLimited(error) {
+  if (error?.code === RATE_LIMITED) return true;
+  return TOO_MANY_REQUESTS.test(error instanceof Error ? error.message : String(error ?? ''));
+}
+
+// Retry n (1-based) waits between half and all of 1 s, 2 s, 4 s: at most 7 s over
+// the three retries.
+export function rateLimitBackoffMs(retry, random = Math.random) {
+  const ceiling = BASE_BACKOFF_MS * 2 ** (retry - 1);
+  return Math.round(ceiling / 2 + random() * (ceiling / 2));
+}
+
+// The sentence naming the call, its attempts and the backoff it used.
+export function describeRateLimit({ call, attempts, waitedMs }) {
+  return `Hyperliquid answered 429 Too Many Requests to ${call} on ${attempts} attempt${attempts === 1 ? '' : 's'} `
+    + `after ${waitedMs} ms of backoff (exponential from ${BASE_BACKOFF_MS} ms with jitter, at most ${RATE_LIMIT_RETRIES} retries)`;
+}
+
+export function rateLimitedError({ call, attempts, waitedMs, reason = null, next = 'wait a minute and rerun' }) {
+  return Object.assign(
+    new Error(`${RATE_LIMITED}: ${describeRateLimit({ call, attempts, waitedMs })}${reason ? `; ${reason}` : ''}. Next: ${next}.`),
+    { code: RATE_LIMITED, call, attempts, waitedMs },
+  );
+}
+
+export function backoffSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// A retry that has not answered by the deadline fails there; the read itself
+// keeps running, but the action no longer waits for it.
+async function beforeDeadline(promise, deadline, timedOut) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(timedOut()), Math.max(0, deadline - Date.now()));
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Run a read, retrying it after a 429 up to RATE_LIMIT_RETRIES times.
+ * @param call - The request named in the error, e.g. perpsGetPositions.
+ * @param read - The read to run; any other error is rethrown at once.
+ * @param options.deadline - Epoch ms the action must finish by. A retry starts only if its backoff
+ *   and another attempt as long as the last one end before it, and fails RATE_LIMITED at it.
+ * @returns The read's result, or throws RATE_LIMITED once the retries or the deadline are spent.
+ */
+export async function withRateLimitRetry(call, read, { deadline = null, sleep = backoffSleep, random = Math.random } = {}) {
+  let waitedMs = 0;
+  for (let attempt = 1; ; attempt += 1) {
+    const startedAt = Date.now();
+    try {
+      if (attempt === 1 || !Number.isFinite(deadline)) return await read();
+      return await beforeDeadline(read(), deadline, () => rateLimitedError({
+        call, attempts: attempt, waitedMs, reason: 'the last retry did not answer before the action deadline',
+      }));
+    } catch (error) {
+      // A nested read already spent its retries.
+      if (error?.code === RATE_LIMITED || !isRateLimited(error)) throw error;
+      if (attempt > RATE_LIMIT_RETRIES) {
+        throw rateLimitedError({ call, attempts: attempt, waitedMs });
+      }
+      const backoffMs = rateLimitBackoffMs(attempt, random);
+      if (Number.isFinite(deadline) && Date.now() + backoffMs + (Date.now() - startedAt) >= deadline) {
+        throw rateLimitedError({
+          call, attempts: attempt, waitedMs,
+          reason: `the next ${backoffMs} ms backoff and another attempt would pass the action deadline`,
+        });
+      }
+      await sleep(backoffMs);
+      waitedMs += backoffMs;
+    }
+  }
+}

package/library/actions/shared/perps/visible-state.mjs

@@ -191,7 +191,7 @@ function visibleFeatures(items) {
   const long = has(/(?:long-cta-button|direction-long|market-details-long-button)$/u);
   const short = has(/(?:short-cta-button|direction-short|market-details-short-button)$/u);
   return {
-    activity: has(/^(?:transaction-card-|perps-(?:recent-activity|activity))/u),
+    activity: has(/^(?:transaction-card-|perps-(?:recent-activity|activity|market-trades-row-))/u),
     balance: has(/^(?:perps-balance-dropdown|perps-balance-actions-available-value|perps-market-(?:balance-value|available-balance-text))/u),
     chart: has(/^(?:chart_surface|tv_chart_container)$/u) ||
       has(/perps-(?:candlestick-chart|market-detail-chart|market-details-fullscreen-chart|pro-market-chart)/u),
@@ -283,7 +283,8 @@ export function normalizeVisiblePerpsState(raw, options, platform) {
       options.maxItems,
     ),
     activity: compactEntries(
-      selected(unique, (item) => /^(?:transaction-card-|transaction-item(?:-|$)|perps-activity-row-)/u.test(item.testId), options.maxItems),
+      // Mobile previews: Perps home Recent activity and the market's recent trades.
+      selected(unique, (item) => /^(?:transaction-card-|transaction-item(?:-|$)|perps-activity-row-|perps-(?:recent-activity|market-trades)-row-\d+$)/u.test(item.testId), options.maxItems),
       options.maxItems,
     ),
     orderEntry: raw.orderEntry && typeof raw.orderEntry === 'object' ? {

package/library/manifests/extension.action-manifest.json

@@ -3788,7 +3788,7 @@
       ]
     },
     "metamask.perps.read_snapshot": {
-      "description": "Read a bounded, redacted source-dev snapshot of Extension Perps state through the optional product background hook.",
+      "description": "Read a bounded, redacted source-dev snapshot of Extension Perps state through the optional product background hook. The history section is the funds ledger from perpsGetUserHistory (deposits, withdrawals and transfers): it holds no trades or orders, so zero history items does not mean no trading history. Read trade and order rows with metamask.perps.read_visible_state activity.",
       "schema": {
         "type": "object",
         "properties": {
@@ -3830,6 +3830,7 @@
           },
           "history": {
             "type": "object",
+            "description": "Funds-ledger window (deposits, withdrawals and transfers) passed to perpsGetUserHistory; trades and orders are not part of it.",
             "properties": {
               "start_time_ms": {
                 "type": "integer",

package/library/manifests/mobile.action-manifest.json

@@ -930,7 +930,7 @@
       ]
     },
     "ui.wait_for": {
-      "description": "Wait for a React Native testID/test_id or text target. expected=visible requires a measured viewport intersection; expected=present only requires the mounted tree.",
+      "description": "Wait for a React Native testID/test_id or text target. expected=visible requires a measured viewport intersection; expected=present only requires the mounted tree. expected=absent also passes when every mounted match is on a screen the navigator hides (an inactive tab, or a non-modal stack screen under a non-modal screen) and a native observation does not show the test ID.",
       "schema": {
         "type": "object",
         "properties": {
@@ -960,7 +960,8 @@
             "type": "boolean"
           },
           "timeout_ms": {
-            "type": "number"
+            "type": "number",
+            "description": "Total wait in milliseconds (default 10000). The hidden-screen check for expected=absent needs about 3 s of it left for its native read."
           }
         },
         "additionalProperties": false
@@ -3544,7 +3545,7 @@
           "trading_state": {
             "type": "string",
             "enum": ["preserve", "clean_selected_testnet_market"],
-            "description": "High-level state policy. The clean policy removes matching positions, ordinary orders, TWAPs, and Chase sessions only on testnet and preserves them on mainnet."
+            "description": "High-level state policy that sets positions, orders and strategies itself: preserve leaves them untouched, and the clean policy removes matching positions, ordinary orders, TWAPs, and Chase sessions only on testnet and preserves them on mainnet. Cannot be combined with an explicit positions, orders or strategies request other than false; omit it to apply such a request."
           },
           "positions": {
             "description": "Requested position state. Omit it or pass false to preserve current positions.",
@@ -3768,7 +3769,19 @@
             "additionalProperties": false
           },
           "timeout_ms": {
-            "type": "number"
+            "type": "number",
+            "minimum": 1,
+            "description": "Overall budget for the whole start state setup: every phase runs inside it. Default 30000 on emulators and simulators, 60000 on a physical Android device (explicit non-emulator adb serial), or MM_HARNESS_MOBILE_SETUP_TIMEOUT_MS. A phase that runs out fails as DOMAIN_SETUP_DEADLINE naming the phase."
+          },
+          "navigation_timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Slice of the setup budget for each navigation phase. Default 15000 on emulators and simulators, 30000 on a physical Android device, or MM_HARNESS_MOBILE_NAVIGATION_TIMEOUT_MS."
+          },
+          "cdp_timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Limit for each bridge command inside the setup, capped by the phase deadline. Default 15000. A command that hits it fails as CDP_TIMEOUT (CDP_COMMAND_TIMEOUT in the message)."
           },
           "side": {
             "type": "string",
@@ -4104,7 +4117,19 @@
             "additionalProperties": false
           },
           "timeout_ms": {
-            "type": "number"
+            "type": "number",
+            "minimum": 1,
+            "description": "Overall budget for the whole teardown: every phase runs inside it. Default 30000 on emulators and simulators, 60000 on a physical Android device (explicit non-emulator adb serial), or MM_HARNESS_MOBILE_SETUP_TIMEOUT_MS. A phase that runs out fails as DOMAIN_SETUP_DEADLINE naming the phase."
+          },
+          "navigation_timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Slice of the setup budget for each navigation phase. Default 15000 on emulators and simulators, 30000 on a physical Android device, or MM_HARNESS_MOBILE_NAVIGATION_TIMEOUT_MS."
+          },
+          "cdp_timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Limit for each bridge command inside the setup, capped by the phase deadline. Default 15000. A command that hits it fails as CDP_TIMEOUT (CDP_COMMAND_TIMEOUT in the message)."
           },
           "side": {
             "type": "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.86.2",
+  "version": "0.87.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"

package/site/assets/help-recipes.json

@@ -202,6 +202,7 @@
         "Flake risk: wait on observable state instead of sleeping, keep device and runtime identity explicit, and never overwrite a prior run's artifacts.",
         "Mutation: require an independent state assertion and identity-bound receipt. Bind activity to that operation's accepted ID; an old row or nonzero count is insufficient. Opening and closing orders have different IDs. Schedule authorized cleanup in teardown, verify its result, and report any residue. Testnet cleanup closes what the task opened and never silently undoes another task's live proof on a reserved account or market.",
         "Testnet account state: on a testnet account or market the task owns for its run (the slot's fixture account, or one reserved with exclusive_testnet_market=true), converging is an explicit, ownership-scoped setup choice, not a violation. Use the team library's perps.ensure-market-state or perps.clean-market-testnet, or on Mobile and Core metamask.perps.ensure_positions / metamask.perps.ensure_orders (mode=all for strays), record what was closed in the trace, then prove. A pre-existing position or order on an account the task owns is never a reason to block, skip, or refuse, and a fixture that demands an empty account must converge rather than refuse. Extension ensure_* and teardown_state only assert; converge there through an explicitly funded leaf action. Never broaden cleanup onto an account or market the task does not own; obtain an owned one instead of blocking. On mainnet, orders follow the shared Perps order rule (PERPS_MAINNET_ORDER_REFUSED), Core needs CORE_PERPS_ALLOW_MAINNET_WRITES=1 for any write, Mobile cleanup acts on whatever network the app is on, and Extension refuses mainnet writes other than orders and `close_visible_position` in the fixture-policy lane.",
+        "Rate limits: RATE_LIMITED means Hyperliquid answered 429 Too Many Requests and bounded retries did not get through; it says nothing about the product. Wait a minute and rerun a read. A placement left outcome-unknown is never rerun before the market's positions, orders and fills are checked.",
         {
           "text": "An accepted order can fill before the UI updates. Preserve its receipt even when the expected resting-order assertion fails; one empty read does not prove cleanup. Check the read API's cache and freshness options before adding polling. Reconcile returned margin against the pre-placement balance. A successful close does not turn the original failed proof into a pass.",
           "adapters": [