@deeeed/metamask-harness 0.86.2 → 0.88.0

package/library/actions/extension/perps/perps.mjs

@@ -31,6 +31,20 @@ import {
   marketOrderLot,
   requireHouseNotional,
 } from '../../shared/perps/order-policy.mjs';
+import { liveAdapterDeadline } from '../../shared/app/live-adapter-deadline.mjs';
+import { withRateLimitRetry } from '../../shared/perps/rate-limit.mjs';
+import {
+  clearMainnetSwitch,
+  dropMainnetOrder,
+  ledgerOrderTargets,
+  markMainnetOrderCancelled,
+  ownedMainnetOrder,
+  recordMainnetSwitch,
+  recordPendingMainnetOrder,
+  recordPlacedMainnetOrder,
+  requireNoOpenMainnetOrders,
+  requirePendingMainnetOrder,
+} from '../../shared/perps/mainnet-order-ledger.mjs';
 import {
   orderIdentityMatches,
   parseOrderCard,
@@ -238,8 +252,13 @@ export async function closePositions(input) {
 }
 
 async function closeOrderThroughBackground(input, page, timeoutMs) {
-  ({ input } = await withFixturePolicyContext(input, page, {
+  // On mainnet the fixture lane cancels only an order this checkout's runs placed.
+  const owned = await ownedMainnetOrder(input.context?.projectRoot, input.node?.order_id);
+  let network;
+  ({ input, network } = await withFixturePolicyContext(input, page, {
     operations: [{ operation: 'perps-cancel-order', amount: String(input.node?.amount ?? '') }],
+    mainnetAllowed: Boolean(owned),
+    mainnetRefusal: 'cancels only orders this run placed',
   }));
   await requirePerpsTradingContext(input, page);
   const symbol = marketSymbol(input);
@@ -333,6 +352,10 @@ async function closeOrderThroughBackground(input, page, timeoutMs) {
       throw new Error('Exact background order did not become absent after cancellation.');
     },
   });
+  // The run's teardown settles it once the market's position is checked too.
+  if (network === 'mainnet' && owned) {
+    await markMainnetOrderCancelled(input.context.projectRoot, owned.id, { via: input.action, canceled: [{ orderId, receipt: mutation.receipt }] });
+  }
   return {
     action: input.action,
     canceled: true,
@@ -345,23 +368,36 @@ async function closeOrderThroughBackground(input, page, timeoutMs) {
   };
 }
 
-async function readAcceptedFilledOrder(input, page, placement, requireTerminal = false) {
-  const accepted = placement.record?.acceptance;
-  if (!accepted?.venueOrderId) return null;
+function hyperliquidOrigin(network) {
+  return network === 'testnet' ? 'https://api.hyperliquid-testnet.xyz' : 'https://api.hyperliquid.xyz';
+}
+
+function postHyperliquidInfo(network, body, signal = AbortSignal.timeout(10_000)) {
+  return fetch(`${hyperliquidOrigin(network)}/info`, {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body), signal,
+  });
+}
+
+// The Hyperliquid network and user a receipt's order went to, read from the live
+// app and bound to the receipt's selected-account hash.
+async function receiptVenueUser(input, page, identity, purpose) {
   const { provider, network } = await requirePerpsTradingContext(input, page);
-  if (provider !== 'hyperliquid') throw new Error('Accepted-order status requires the original Hyperliquid provider.\nNext: mm-harness last --json');
+  if (provider !== 'hyperliquid') throw new Error(`${purpose} requires the original Hyperliquid provider.\nNext: mm-harness last --json`);
   const wallet = await page.evaluate(readWalletStateExpression());
   const user = String(wallet.selectedAccount?.address ?? '').toLowerCase();
   if (!/^0x[a-f0-9]{40}$/u.test(user)
-    || createHash('sha256').update(user).digest('hex') !== placement.record.identity.selectedIdentitySha256) {
-    throw new Error('Accepted-order status wallet differs from the placement receipt.\nNext: mm-harness last --json');
+    || createHash('sha256').update(user).digest('hex') !== identity.selectedIdentitySha256) {
+    throw new Error(`${purpose} wallet differs from the placement receipt.\nNext: mm-harness last --json`);
   }
-  const origin = network === 'testnet' ? 'https://api.hyperliquid-testnet.xyz' : 'https://api.hyperliquid.xyz';
-  const response = await fetch(`${origin}/info`, {
-    method: 'POST', headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ type: 'orderStatus', user, oid: Number(accepted.venueOrderId) }),
-    signal: AbortSignal.timeout(10_000),
-  });
+  return { network, user };
+}
+
+async function readAcceptedFilledOrder(input, page, placement, requireTerminal = false) {
+  const accepted = placement.record?.acceptance;
+  if (!accepted?.venueOrderId) return null;
+  const { network, user } = await receiptVenueUser(input, page, placement.record.identity, 'Accepted-order status');
+  const response = await postHyperliquidInfo(network, { type: 'orderStatus', user, oid: Number(accepted.venueOrderId) });
   if (!response.ok) throw new Error('Accepted-order status request failed.\nNext: mm-harness last --json');
   const result = await response.json();
   if (result.status === 'unknownOid') throw new Error('Accepted venue order status is unavailable.\nNext: mm-harness last --json');
@@ -671,7 +707,7 @@ async function readCurrentMarketPrice(page, symbol, explicitPrice) {
     if (Number.isFinite(parsed) && parsed > 0) return parsed;
     throw new Error(`Invalid explicit current price for ${symbol}: ${String(explicitPrice)}`);
   }
-  const price = await page.evaluate(String.raw`(async () => {
+  const price = await withRateLimitRetry('perpsGetMarketDataWithPrices', () => page.evaluate(String.raw`(async () => {
     const request = globalThis.stateHooks?.submitRequestToBackground;
     const manager = globalThis.stateHooks?.getPerpsStreamManager?.();
     const symbol = ${JSON.stringify(symbol)};
@@ -709,7 +745,7 @@ async function readCurrentMarketPrice(page, symbol, explicitPrice) {
     const line = body.split('\n').find((text) => /\$[0-9][0-9,]*(?:\.[0-9]+)?/.test(text));
     const fromBody = parsePrice(line);
     return fromBody ? { price: fromBody, source: 'document-body-price-line' } : null;
-  })()`);
+  })()`), { deadline: page.actionDeadline });
   const numericPrice = Number(price?.price ?? price);
   if (!Number.isFinite(numericPrice) || numericPrice <= 0) throw new Error(`Unable to determine current Perps price for ${symbol}.`);
   return numericPrice;
@@ -871,6 +907,7 @@ async function dispatchBackgroundPlace(page, {
   orderType,
   resolvedPrice,
   symbol,
+  timeInForce = 'GTC',
 }) {
   return page.evaluate(`(async () => {
     const request = globalThis.stateHooks?.submitRequestToBackground;
@@ -887,7 +924,7 @@ async function dispatchBackgroundPlace(page, {
       size: ((Number(usdAmount) * Number(leverage)) / Number(limitPrice)).toString(),
       orderType,
       price: String(limitPrice),
-      timeInForce: 'GTC',
+      timeInForce: ${JSON.stringify(timeInForce)},
       leverage,
       currentPrice,
       priceAtCalculation: currentPrice,
@@ -915,7 +952,7 @@ async function dispatchBackgroundPlace(page, {
 }
 
 async function readOpenOrdersState(page) {
-  const state = await page.evaluate(`(async () => {
+  const state = await withRateLimitRetry('perpsGetOpenOrders', () => page.evaluate(`(async () => {
     const request = globalThis.stateHooks?.submitRequestToBackground;
     const manager = globalThis.stateHooks?.getPerpsStreamManager?.();
     const cached = manager?.orders?.cache;
@@ -933,13 +970,13 @@ async function readOpenOrdersState(page) {
       connected: Boolean(manager?.orders?.isConnected),
       orders: Array.isArray(cached) ? cached : [],
     };
-  })()`);
+  })()`), { deadline: page.actionDeadline });
   if (!state.available) throw new Error('Perps orders are unavailable from both background and stream manager cache.');
   return state;
 }
 
 async function readAccountState(page) {
-  const state = await page.evaluate(`(async () => {
+  const state = await withRateLimitRetry('perpsGetAccountState', () => page.evaluate(`(async () => {
     const request = globalThis.stateHooks?.submitRequestToBackground;
     const manager = globalThis.stateHooks?.getPerpsStreamManager?.();
     const cached = manager?.account?.cache;
@@ -957,7 +994,7 @@ async function readAccountState(page) {
       connected: Boolean(manager?.account?.isConnected),
       account: cached && typeof cached === 'object' ? cached : null,
     };
-  })()`);
+  })()`), { deadline: page.actionDeadline });
   if (!state.available) throw new Error('Perps account state is unavailable from both background and stream manager cache.');
   return state.account;
 }
@@ -1242,9 +1279,56 @@ async function observeExactVisibleOrderResult(page, expected, receipt, timeoutMs
   throw new Error(`matching ${expected.orderType} ${identity} identity was not stably visible before timeout; last observed: ${JSON.stringify(lastObserved)}`);
 }
 
+// Fills and open orders up to this long before the first dispatch count as this
+// order's, so a local clock behind the venue's cannot hide one.
+const VENUE_CLOCK_SKEW_MS = 30_000;
+// All three venue reads together; a retry starts only if they fit before its deadline.
+const VENUE_VERIFY_TIMEOUT_MS = 5_000;
+
+// After a 429 on a background placement: Hyperliquid's own account state, not the
+// extension's cache, shows no open order and no fill in the market since the first
+// dispatch, and for a market order no position on its side (the pre-order baseline
+// had none). Open orders are read before fills, so an order of ours that fills
+// between the two reads still shows in one of them. Anything else, or a failed
+// read, leaves the outcome unproven.
+async function verifyNothingPlacedOnVenue(input, page, identity, sinceMs) {
+  const coin = identity.market;
+  if (coin.includes(':')) {
+    return { proven: false, reason: `the venue read covers only the main Hyperliquid dex, not ${coin}` };
+  }
+  const { network, user } = await receiptVenueUser(input, page, identity, 'Rate-limit verification');
+  const startTime = sinceMs - VENUE_CLOCK_SKEW_MS;
+  const signal = AbortSignal.timeout(VENUE_VERIFY_TIMEOUT_MS);
+  const read = async (body) => {
+    const response = await postHyperliquidInfo(network, body, signal);
+    if (!response.ok) throw new Error(`Hyperliquid ${body.type} answered HTTP ${response.status}`);
+    return response.json();
+  };
+  const orders = await read({ type: 'openOrders', user });
+  const fills = await read({ type: 'userFillsByTime', user, startTime });
+  const account = await read({ type: 'clearinghouseState', user });
+  if (!Array.isArray(fills) || !Array.isArray(orders) || !Array.isArray(account?.assetPositions)) {
+    return { proven: false, reason: 'the Hyperliquid account reads returned an unexpected shape' };
+  }
+  const size = Number(account.assetPositions.find((entry) => entry?.position?.coin === coin)?.position?.szi ?? 0);
+  if (!Number.isFinite(size)) return { proven: false, reason: `the Hyperliquid ${coin} position size is unreadable` };
+  const facts = {
+    source: 'hyperliquid-info',
+    startTime,
+    openOrders: orders.filter((order) => order?.coin === coin && !(Number(order?.timestamp) < startTime)).length,
+    fills: fills.filter((fill) => fill?.coin === coin && !(Number(fill?.time) < startTime)).length,
+    sameSidePosition: identity.orderType === 'market' && (identity.side === 'long' ? size > 0 : size < 0),
+  };
+  if (facts.openOrders > 0 || facts.fills > 0 || facts.sameSidePosition) {
+    return { proven: false, reason: `Hyperliquid shows ${coin} activity since the first dispatch`, facts };
+  }
+  return { proven: true, facts };
+}
+
 async function placeOrderThroughBackground(input, page, {
   amount,
   bound = null,
+  mainnetLimit = false,
   onDispatch = () => {},
   expected,
   identity,
@@ -1293,9 +1377,30 @@ async function placeOrderThroughBackground(input, page, {
   // A resume checks the fill against the lot sized at publication, not one
   // recomputed at a price that has since moved.
   const marketLot = existing?.record?.facts?.marketLot ?? expected.marketLot ?? null;
+  const projectRoot = input.context?.projectRoot;
+  // A mainnet limit order is tracked for the run's forced cancel (mainnet-order-ledger.mjs).
+  const ledgerFields = mainnetLimit ? {
+    platform: 'extension',
+    provider: String(input.node?.provider ?? '').toLowerCase(),
+    symbol,
+    side: expected.side,
+    limitPrice,
+    address: bound.address,
+    baselineOrderIds: [...baselineIds],
+    artifactsDir: input.context.artifactsDir,
+    connection: { cdpPort: page.runtimeIdentity?.cdpPort },
+  } : null;
+  let ledgerId = null;
   const mutation = await runGuardedExternalMutation({
     input,
     identity,
+    rateLimit: {
+      call: 'perpsPlaceOrder',
+      // A retry leaves the postcondition its timeout_ms and 5 s before the runner's process limit.
+      deadline: liveAdapterDeadline(input.node, Number(input.node?.timeout_ms ?? 30_000) + 5_000),
+      verifyBudgetMs: VENUE_VERIFY_TIMEOUT_MS,
+      verifyNotPlaced: ({ sinceMs }) => verifyNothingPlacedOnVenue(input, page, identity, sinceMs),
+    },
     // The pre-order balance lets a receipt-bound close reconcile its final balance.
     publicationFacts: {
       balanceBeforeBaseUnits: fundingBalance.observedBaseUnits,
@@ -1303,19 +1408,27 @@ async function placeOrderThroughBackground(input, page, {
       fundingBalance,
       ...(expected.marketLot ? { marketLot: expected.marketLot } : {}),
     },
-    dispatch: async () => {
+    dispatch: async ({ deadline = null } = {}) => {
       try {
+        const timeoutMs = Number(input.node?.timeout_ms ?? 30_000);
         await requireCurrentVisibleFundingBalance(
           input,
           page,
-          Number(input.node?.timeout_ms ?? 30_000),
+          deadline == null ? timeoutMs : Math.max(0, Math.min(timeoutMs, deadline - Date.now())),
           fundingBalance.observedBaseUnits,
         );
         await requirePerpsTradingContext(input, page);
         assertTrustedExternalMutationTarget(input, page, identity);
+        // A 429 retry (proven not placed) reuses the pending entry and its pre-order
+        // baseline, unless the run began aborting or its cleanup settled the entry.
+        if (ledgerId) await requirePendingMainnetOrder(projectRoot, ledgerId);
+        if (deadline != null && Date.now() >= deadline) {
+          throw new Error('it reached the action deadline before dispatch');
+        }
       } catch (error) {
         throw externalMutationNotDispatched(error instanceof Error ? error.message : String(error));
       }
+      if (ledgerFields && !ledgerId) ledgerId = await recordPendingMainnetOrder(projectRoot, ledgerFields);
       onDispatch();
       const accepted = await dispatchBackgroundPlace(page, {
         amount,
@@ -1327,8 +1440,11 @@ async function placeOrderThroughBackground(input, page, {
         orderType,
         resolvedPrice,
         symbol,
+        // Post-only on mainnet: the venue rejects a limit that would fill now.
+        timeInForce: mainnetLimit ? 'ALO' : 'GTC',
       });
       if (accepted?.changed) {
+        if (ledgerId) await dropMainnetOrder(projectRoot, ledgerId);
         throw externalMutationNotDispatched('the selected account or Perps network changed after the order rule allowed it');
       }
       // The venue's filled order ID goes into the receipt, so cleanup can prove the
@@ -1353,6 +1469,14 @@ async function placeOrderThroughBackground(input, page, {
       receipt?.acceptance,
     ),
   });
+  const placedOrderId = mutation.observation?.order?.id;
+  if (ledgerFields && placedOrderId) {
+    // A resumed placement dispatched in an earlier attempt: track it if that attempt did not.
+    if (ledgerId) await recordPlacedMainnetOrder(projectRoot, ledgerId, placedOrderId);
+    else if (!(await ownedMainnetOrder(projectRoot, placedOrderId))) {
+      await recordPlacedMainnetOrder(projectRoot, await recordPendingMainnetOrder(projectRoot, ledgerFields), placedOrderId);
+    }
+  }
   return {
     action: input.action,
     market: symbol,
@@ -1567,12 +1691,8 @@ export async function observeHyperliquidSubmission(page, expected) {
   if (expected.provider !== 'hyperliquid' || !['market', 'limit'].includes(expected.orderType)) {
     throw new Error('Exact visible submission observation requires a Hyperliquid market or limit order.');
   }
-  const origin = expected.network === 'testnet'
-    ? 'https://api.hyperliquid-testnet.xyz' : 'https://api.hyperliquid.xyz';
-  const metadataResponse = await fetch(`${origin}/info`, {
-    method: 'POST', headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ type: 'meta' }), signal: AbortSignal.timeout(10_000),
-  });
+  const origin = hyperliquidOrigin(expected.network);
+  const metadataResponse = await postHyperliquidInfo(expected.network, { type: 'meta' });
   if (!metadataResponse.ok) throw new Error('Hyperliquid market metadata is unavailable before submission.');
   const metadata = await metadataResponse.json();
   const asset = metadata.universe?.findIndex((market) => market.name === expected.market);
@@ -1718,11 +1838,15 @@ export async function placeOrder(input) {
   // The account and network the order rule allowed, rechecked before any close.
   let bound = null;
   const place = () => withExtensionPage(input, async (page) => {
+    const hasBackgroundRequest = await page.evaluate(
+      `typeof globalThis.stateHooks?.submitRequestToBackground === 'function'`,
+    );
     const lane = await withFixturePolicyContext(input, page, {
       operations: [
         { operation: orderType === 'limit' ? 'perps-limit-order' : 'perps-market-order', amount, order: true },
       ],
-      order: { amount, leverage, orderType, closeImmediately },
+      // Only the background placement tracks a limit order for the run's forced cancel.
+      order: { amount, leverage, orderType, closeImmediately, runCancelsLimit: hasBackgroundRequest && !fromCurrentForm },
     });
     input = lane.input;
     if (lane.network) {
@@ -1788,9 +1912,6 @@ export async function placeOrder(input) {
       } : {}),
       ...(fromCurrentForm && orderType === 'limit' ? { maximumNotionalBaseUnits: placementBudget.maxBaseUnits } : {}),
     };
-    const hasBackgroundRequest = await page.evaluate(
-      `typeof globalThis.stateHooks?.submitRequestToBackground === 'function'`,
-    );
     if (closeImmediately) {
       // The close goes through the background request, so the order must too.
       if (!hasBackgroundRequest) throw new Error('close_immediately needs the background Perps request; it is unavailable.');
@@ -1805,6 +1926,9 @@ export async function placeOrder(input) {
     }
     if (hasBackgroundRequest && !fromCurrentForm) {
       await requirePerpsTradingContext(input, page);
+      if (lane.network === 'mainnet' && (input.node?.current_price ?? input.node?.currentPrice) != null) {
+        throw new Error('Mainnet orders are bounded at the live market price; drop current_price.');
+      }
       const resolvedPrice = await readCurrentMarketPrice(
         page,
         symbol,
@@ -1812,6 +1936,9 @@ export async function placeOrder(input) {
       );
       const szDecimals = lane.network === 'mainnet' || orderType === 'market'
         ? await readSizeDecimals(page, symbol) : null;
+      const backgroundLimitPrice = orderType === 'limit'
+        ? resolveLimitPrice(input, isBuy, resolvedPrice)
+        : null;
       houseNotional = requireHouseNotional({
         network: lane.network,
         symbol,
@@ -1820,14 +1947,13 @@ export async function placeOrder(input) {
         price: resolvedPrice,
         szDecimals,
         maxSlippageBps: Number(input.node?.max_slippage_bps ?? input.node?.maxSlippageBps ?? 300),
+        limit: orderType === 'limit' ? { price: backgroundLimitPrice, isBuy } : null,
       });
       const marketLot = orderType === 'market' ? marketOrderLot({ amount, leverage, price: resolvedPrice, szDecimals }) : null;
-      const backgroundLimitPrice = orderType === 'limit'
-        ? resolveLimitPrice(input, isBuy, resolvedPrice)
-        : null;
       return placeOrderThroughBackground(input, page, {
         amount,
         bound,
+        mainnetLimit: lane.network === 'mainnet' && orderType === 'limit',
         onDispatch: () => {
           dispatchMayHaveHappened = true;
         },
@@ -2178,7 +2304,7 @@ export async function placeOrder(input) {
 // read in one evaluation with the context guard before, between and after the
 // reads, so a switch to another account's book and back can't pass as flat.
 async function readBoundBook(page, bound) {
-  const book = await page.evaluate(`(async () => {
+  const book = await withRateLimitRetry('perpsGetPositions/perpsGetOpenOrders', () => page.evaluate(`(async () => {
     const request = globalThis.stateHooks?.submitRequestToBackground;
     if (typeof request !== 'function') return { unavailable: true };
     const guard = async () => { ${boundContextGuard(bound)} return null; };
@@ -2188,7 +2314,7 @@ async function readBoundBook(page, bound) {
     const orders = await request('perpsGetOpenOrders', []);
     if (await guard()) return { changed: true };
     return { positions, orders };
-  })()`);
+  })()`), { deadline: page.actionDeadline });
   if (book?.changed) {
     throw Object.assign(
       new Error('Perps order not dispatched: the selected account or network changed while the market was checked flat.'),
@@ -2202,9 +2328,9 @@ async function readBoundBook(page, bound) {
 }
 
 async function readSizeDecimals(page, symbol) {
-  const markets = await page.evaluate(
+  const markets = await withRateLimitRetry('perpsGetMarkets', () => page.evaluate(
     `globalThis.stateHooks.submitRequestToBackground('perpsGetMarkets', [{ symbols: [${JSON.stringify(symbol)}] }])`,
-  );
+  ), { deadline: page.actionDeadline });
   const market = (Array.isArray(markets) ? markets : []).find((item) => normalizeMarketSymbol(item?.name ?? '') === symbol);
   return market?.szDecimals ?? null;
 }
@@ -2482,6 +2608,139 @@ async function ensureNetwork(input, config) {
   return withExtensionPage(input, (page) => assertNetwork(page, config.network));
 }
 
+// metamask.perps.set_network network=<testnet|mainnet> (default testnet): switch
+// the Perps network when it differs; the fixture loads testnet. A switch to
+// mainnet is recorded so the run's teardown switches back to testnet
+// (mainnet-order-ledger.mjs): mainnet lasts one run.
+export async function setNetwork(input) {
+  const network = String(input.node?.network ?? 'testnet').toLowerCase();
+  if (network !== 'testnet' && network !== 'mainnet') throw new Error(`${input.action} network must be testnet or mainnet, got ${JSON.stringify(input.node?.network)}.`);
+  await applyStateNavigation(input, { page: 'home' });
+  return withExtensionPage(input, async (page) => {
+    if (network === 'testnet') {
+      const state = await readPerpsRuntimeState(page);
+      if (state.networkKnown && !state.isTestnet) await requireNoOpenMainnetOrders(input.context.projectRoot, input.action);
+    }
+    // Recorded before the toggle, so an abort mid-switch still switches back.
+    if (network === 'mainnet') {
+      await recordMainnetSwitch(input.context.projectRoot, {
+        platform: 'extension',
+        artifactsDir: input.context.artifactsDir,
+        connection: { cdpPort: page.runtimeIdentity?.cdpPort },
+      });
+    }
+    const switched = await togglePerpsNetwork(page, network, Number(input.node?.timeout_ms ?? 30_000));
+    if (network === 'testnet' && switched.changed) await clearMainnetSwitch(input.context.projectRoot);
+    return { action: input.action, ...switched, proofPath: 'background-perpsToggleTestnet' };
+  });
+}
+
+async function togglePerpsNetwork(page, network, timeoutMs) {
+  const before = await readPerpsRuntimeState(page);
+  if (!before.available || !before.networkKnown) {
+    throw new Error('Cannot verify the current Perps network.\nNext: mm-harness verify');
+  }
+  if ((before.isTestnet ? 'testnet' : 'mainnet') === network) return { requested: network, isTestnet: before.isTestnet, changed: false };
+  await requestBackground(page, 'perpsToggleTestnet', []);
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const after = await readPerpsRuntimeState(page);
+    if (after.networkKnown && (after.isTestnet ? 'testnet' : 'mainnet') === network) {
+      return { requested: network, isTestnet: after.isTestnet, changed: true };
+    }
+    if (Date.now() >= deadline) throw new Error(`Perps network did not switch to ${network} within ${timeoutMs} ms of perpsToggleTestnet.`);
+    await sleep(250);
+  }
+}
+
+function cleanupInput(projectRoot, artifactsDir, cdpPort) {
+  return {
+    action: 'metamask.perps.close_orders',
+    node: { cdp_port: cdpPort },
+    context: { nodeId: 'mainnet-order-cleanup', projectRoot, artifactsDir },
+  };
+}
+
+// The order book fields the mainnet order ledger matches on.
+const LEDGER_ORDER_FIELDS = {
+  idOf: (order) => order?.orderId ?? order?.id,
+  symbolOf: symbolForItem,
+  sideOf: sideForItem,
+  priceOf: (order) => order?.price ?? order?.limitPrice ?? order?.limitPx ?? order?.px,
+};
+
+// The account's open orders and the market's signed position size, from the
+// background requests only: a stream cache can be stale or empty after a
+// reload, which would read as "cancelled".
+async function readAuthoritativeBook(page, symbol) {
+  const orders = await readOpenOrdersState(page);
+  const positions = await page.readPositions();
+  if (orders.source !== 'background-perpsGetOpenOrders' || positions.source !== 'background-perpsGetPositions') {
+    throw new Error(`cannot read the ${symbol} book from the Extension background (got ${orders.source} and ${positions.source})`);
+  }
+  return {
+    orders: orders.orders,
+    positionSize: positions.positions
+      .filter((position) => symbolForItem(position) === symbol)
+      .reduce((total, position) => total + Number(position.size ?? position.szi ?? 0), 0),
+  };
+}
+
+// The run's forced cancel of one mainnet limit order it opened (see
+// mainnet-order-ledger.mjs), from the run's process: on the account that placed
+// it, still on mainnet, cancel it and read the book until it is gone. The read
+// also carries the market's position, which the caller compares with the one
+// before the order (a fill is reported, never closed here).
+export async function cancelMainnetLedgerOrder(entry, { projectRoot }) {
+  const bound = { address: entry.address, network: 'mainnet' };
+  // Only the proof: withExtensionPage adds the page's runtime identity to its result.
+  const { canceled, read } = await withExtensionPage(cleanupInput(projectRoot, entry.artifactsDir, entry.connection?.cdpPort), async (page) => {
+    const guard = await page.evaluate(`(async () => { ${boundContextGuard(bound)} return { changed: false }; })()`, { awaitPromise: true });
+    const runtime = await readPerpsRuntimeState(page);
+    if (guard?.changed || String(runtime.activeProvider ?? '').toLowerCase() !== entry.provider) {
+      throw new Error(`the Extension is not on mainnet ${entry.provider} with the placing account ${entry.address} selected`);
+    }
+    const bookRead = (book, outcome) => ({
+      source: 'background-perpsGetOpenOrders+perpsGetPositions',
+      openOrderIds: book.orders.map((order) => String(LEDGER_ORDER_FIELDS.idOf(order) ?? '')),
+      positionSize: book.positionSize,
+      ...outcome,
+    });
+    const before = await readAuthoritativeBook(page, entry.symbol);
+    const targets = ledgerOrderTargets(entry, before.orders, LEDGER_ORDER_FIELDS);
+    if (targets.length === 0) return { canceled: [], read: bookRead(before, { notOpen: true }) };
+    const canceled = [];
+    for (const order of targets) {
+      const orderId = String(LEDGER_ORDER_FIELDS.idOf(order));
+      const result = await page.evaluate(`(async () => {
+        ${boundContextGuard(bound)}
+        return globalThis.stateHooks.submitRequestToBackground('perpsCancelOrder', [${JSON.stringify({ orderId, symbol: entry.symbol })}]);
+      })()`, { awaitPromise: true });
+      if (result?.changed) throw new Error(`the Extension left mainnet or account ${entry.address} before the cancel`);
+      if (!result || result.success === false) throw new Error(`perpsCancelOrder ${orderId} failed: ${result?.error ?? JSON.stringify(result)}`);
+      canceled.push({ orderId, result });
+    }
+    const deadline = Date.now() + 30_000;
+    for (;;) {
+      const after = await readAuthoritativeBook(page, entry.symbol);
+      const open = after.orders.map((order) => String(LEDGER_ORDER_FIELDS.idOf(order))).filter((id) => canceled.some((item) => item.orderId === id));
+      if (open.length === 0) return { canceled, read: bookRead(after, { absent: true }) };
+      if (Date.now() >= deadline) throw new Error(`order(s) ${open.join(', ')} still open 30 s after the cancel`);
+      await sleep(500);
+    }
+  });
+  return { canceled, read };
+}
+
+// The run's teardown: switch Perps back to the fixture's testnet after a
+// start_state network=mainnet.
+export async function restoreTestnetAfterRun(networkSwitch, { projectRoot }) {
+  return withExtensionPage(
+    cleanupInput(projectRoot, networkSwitch.artifactsDir, networkSwitch.connection?.cdpPort),
+    (page) => togglePerpsNetwork(page, 'testnet', 30_000),
+  );
+}
+
 async function assertReadyToTrade(input, config) {
   if (config.readyToTrade === undefined || config.readyToTrade === false) return { skipped: true };
   return withExtensionPage(input, async (page) => {

package/library/actions/extension/perps/read_snapshot.mjs

@@ -3,6 +3,7 @@
 import { pathToFileURL } from 'node:url';
 
 import { normalizeMarketSymbol, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import { withRateLimitRetry } from '../../shared/perps/rate-limit.mjs';
 
 const ALL_SECTIONS = ['account', 'markets', 'positions', 'orders', 'history', 'watchlist'];
 const DEFAULT_HISTORY_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
@@ -533,8 +534,11 @@ export async function readSnapshot(input, testOptions = {}) {
     const pause = testOptions.pause ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     const samples = [];
     for (let index = 0; index < options.sampling.count; index += 1) {
-      const raw = await page.evaluate(snapshotRequestExpression(options));
-      samples.push(normalizeSnapshotResult(raw, options));
+      // A section a 429 left unavailable fails normalization; the sample reruns.
+      samples.push(await withRateLimitRetry('Perps snapshot', async () => normalizeSnapshotResult(
+        await page.evaluate(snapshotRequestExpression(options)),
+        options,
+      ), { sleep: pause, deadline: page.actionDeadline }));
       if (index + 1 < options.sampling.count) await pause(options.sampling.intervalMs);
     }
     const sections = samples.at(-1);

package/library/actions/extension/perps/set_network.mjs

@@ -0,0 +1,6 @@
+// Switch the Extension's Perps network (default testnet). A switch to mainnet
+// lasts one run: the run's teardown switches back to testnet.
+import { runAdapter } from '../platform/cdp.mjs';
+import { setNetwork } from './perps.mjs';
+
+runAdapter(setNetwork);

package/library/actions/extension/platform/cdp.mjs

@@ -22,6 +22,8 @@ import path from 'node:path';
 
 import { captureActiveRecipeRecordingSnapshot, recipeHarnessPath } from '@farmslot/recipe-cli/harness';
 import { importRecipeHarnessRuntimeBrowserExtension, importRecipeHarnessRuntimeCdp, extensionIdPath, walletFixturePath } from '../../harness-exports.mjs';
+import { liveAdapterDeadline } from '../../shared/app/live-adapter-deadline.mjs';
+import { withRateLimitRetry } from '../../shared/perps/rate-limit.mjs';
 
 // Resolve the Farmslot harness through normal package dependencies by default.
 // Local Farmslot source is only a dev override handled by the harness paths module.
@@ -843,6 +845,8 @@ export async function withExtensionPage(input, callback) {
     const origin = `chrome-extension://${extensionId}`;
     const runtimeIdentity = extensionRuntimeIdentity({ port, target, browserVersion });
     const page = new ExtensionPage(session, origin, target, port, runtimeIdentity);
+    // Rate-limit retries on this page's reads stop before the runner's process limit.
+    page.actionDeadline = liveAdapterDeadline(input.node);
     const recoverVisibleWallet = input.action === 'metamask.wallet.import' && input.node?.method === 'ui';
     if (recoverVisibleWallet) {
       try {
@@ -1030,7 +1034,7 @@ export class ExtensionPage extends CdpWebPage {
   }
 
   async readPositions() {
-    return this.evaluate(`(async () => {
+    return withRateLimitRetry('perpsGetPositions', () => this.evaluate(`(async () => {
       const request = globalThis.stateHooks?.submitRequestToBackground;
       const manager = globalThis.stateHooks?.getPerpsStreamManager?.();
       const cached = manager?.positions?.cache;
@@ -1050,7 +1054,7 @@ export class ExtensionPage extends CdpWebPage {
         connected: Boolean(manager?.positions?.isConnected),
         positions: Array.isArray(cached) ? cached : [],
       };
-    })()`);
+    })()`), { deadline: this.actionDeadline });
   }
 
   async screenshot(contextOrInput, relPath, metadata = {}) {

package/library/actions/extension/ui/navigate.mjs

@@ -280,6 +280,8 @@ export async function openPerpsHome(page, timeoutMs) {
     await pauseForUi(page);
   }
 
+  // The sample is capped at 30 and the header and tabs come first in the DOM, so loading
+  // markers are listed first; otherwise a Perps view still loading reads as a wrong route.
   const state = await page.evaluate(`({
     href: location.href,
     title: document.title,
@@ -291,8 +293,14 @@ export async function openPerpsHome(page, timeoutMs) {
       })
       .map((element) => element.getAttribute('data-testid'))
       .filter(Boolean)
+      .sort((a, b) => Number(b.endsWith('-loading')) - Number(a.endsWith('-loading')))
       .slice(0, 30),
   })`);
+  if (await hasVisibleSelector(page, perpsLoading)) {
+    throw new Error(
+      `extension ui.navigate page=perps: Perps home stayed on its loading view (perps-view-loading visible) within the ${timeoutMs}ms budget; observed ${JSON.stringify(state)}.\nNext: check the Perps stream/provider, or raise timeout_ms; a raw hash route does not wait for Perps readiness.`,
+    );
+  }
   throw new Error(
     `extension ui.navigate page=perps could not resolve the Perps home through visible UI; observed ${JSON.stringify(state)}. Capture the current UI with mm-harness call ui.screenshot, then use a verified visible control or raw hash/path.`,
   );