@deeeed/metamask-harness 0.86.1 → 0.87.0

package/library/actions/extension/perps/mutation-receipt.mjs

@@ -19,6 +19,14 @@ import path from 'node:path';
 
 import { isFixtureAccount } from '../../shared/wallet/fixture-accounts.mjs';
 import { MAINNET_HOUSE_LIMITS, orderNetwork, requirePerpsOrderAllowed } from '../../shared/perps/order-policy.mjs';
+import {
+  RATE_LIMIT_RETRIES,
+  RATE_LIMITED,
+  backoffSleep,
+  describeRateLimit,
+  isRateLimited,
+  rateLimitBackoffMs,
+} from '../../shared/perps/rate-limit.mjs';
 import { readWalletStateExpression } from '../wallet/state.mjs';
 import { readPerpsRuntimeStateExpression } from './state.mjs';
 
@@ -43,6 +51,14 @@ function recoveryError(receipt, detail) {
   );
 }
 
+// The outcome stays unknown, so the Next is still the receipt's, never a plain rerun.
+function rateLimitedRecoveryError(receipt, rateLimit, reason) {
+  return Object.assign(
+    new Error(`${RATE_LIMITED}: ${recoveryError(receipt, `${describeRateLimit(rateLimit)}; ${reason}`).message}`),
+    { code: RATE_LIMITED },
+  );
+}
+
 class ExternalMutationNotDispatchedError extends Error {}
 
 export function externalMutationNotDispatched(message) {
@@ -831,8 +847,27 @@ export async function recordExternalMutationCleanupCandidate(input, receipt, can
   });
 }
 
+// A market order placed through the background Perps request reports the venue's
+// filled order itself; there is no observed network request to bind.
+export const BACKGROUND_ACCEPTANCE_SOURCE = 'background-perpsPlaceOrder';
+
+function validFilledOrder(filledSize, averagePrice) {
+  return /^(?:0|[1-9][0-9]{0,19})(?:\.[0-9]{1,8})?$/u.test(String(filledSize)) && Number(filledSize) > 0
+    && /^(?:0|[1-9][0-9]{0,19})(?:\.[0-9]{1,18})?$/u.test(String(averagePrice)) && Number(averagePrice) > 0;
+}
+
 async function recordSubmissionAcceptance(input, receipt, acceptance) {
   const { venueOrderId, status, requestId, serviceWorkerTargetId, asset, size, limitPriceBaseUnits, filledSize, averagePrice } = acceptance;
+  if (acceptance.source === BACKGROUND_ACCEPTANCE_SOURCE) {
+    if (receipt.record.identity.operation !== 'perps-market-order' || receipt.record.identity.provider !== 'hyperliquid'
+      || !/^[1-9][0-9]{0,19}$/u.test(String(venueOrderId)) || status !== 'filled' || size !== filledSize
+      || !validFilledOrder(filledSize, averagePrice)) {
+      throw recoveryError(receipt, 'background market acceptance has invalid filled order identity');
+    }
+    return amendOutcomeUnknownReceipt(input, receipt, { acceptance: {
+      source: BACKGROUND_ACCEPTANCE_SOURCE, venueOrderId, status, size, filledSize, averagePrice,
+    } }, 'submission acceptance');
+  }
   const closing = receipt.record.identity.operation === 'perps-close-position';
   const market = closing || receipt.record.identity.operation === 'perps-market-order';
   const sizing = closing ? receipt.record.facts?.closeSizing
@@ -849,20 +884,28 @@ async function recordSubmissionAcceptance(input, receipt, acceptance) {
     || !BASE_UNITS.test(String(limitPriceBaseUnits))) {
     throw recoveryError(receipt, 'submission acceptance has invalid order identity');
   }
-  if (market && status === 'filled' && (!/^(?:0|[1-9][0-9]{0,19})(?:\.[0-9]{1,8})?$/u.test(String(filledSize))
-    || !(Number(filledSize) > 0) || Number(filledSize) > Number(size)
-    || !/^(?:0|[1-9][0-9]{0,19})(?:\.[0-9]{1,18})?$/u.test(String(averagePrice)) || !(Number(averagePrice) > 0))) {
+  if (market && status === 'filled' && (!validFilledOrder(filledSize, averagePrice) || Number(filledSize) > Number(size))) {
     throw recoveryError(receipt, 'market acceptance has invalid filled size or price');
   }
+  return amendOutcomeUnknownReceipt(input, receipt, { acceptance: {
+    venueOrderId, status, requestId, serviceWorkerTargetId, asset, size, limitPriceBaseUnits,
+    ...(market && status === 'filled' ? { filledSize, averagePrice } : {}),
+  } }, 'submission acceptance');
+}
+
+// Adds fields to a still outcome-unknown receipt: the accepted order, or a 429
+// and the venue read that followed it.
+async function amendOutcomeUnknownReceipt(input, receipt, fields, label) {
   const destination = await receiptDestination(input);
   const current = await readPublished(destination);
   if (!current || current.sha256 !== receipt.sha256 || current.record?.state !== 'outcome-unknown') {
-    throw recoveryError(receipt, 'the receipt changed before submission acceptance was recorded');
+    throw recoveryError(receipt, `the receipt changed before ${label} was recorded`);
+  }
+  const record = { ...current.record, ...fields };
+  const bytes = canonical(record);
+  if (bytes.length > 12_288 || /secret|password|srp|mnemonic|private.?key/iu.test(bytes)) {
+    throw recoveryError(receipt, `the ${label} receipt is unsafe`);
   }
-  const record = { ...current.record, acceptance: {
-    venueOrderId, status, requestId, serviceWorkerTargetId, asset, size, limitPriceBaseUnits,
-    ...(market && status === 'filled' ? { filledSize, averagePrice } : {}),
-  } };
   const staged = await stagedRecord(destination.directory, record);
   try {
     await rename(staged.stagedPath, destination.absolute);
@@ -872,12 +915,21 @@ async function recordSubmissionAcceptance(input, receipt, acceptance) {
   }
   const published = await readPublished(destination);
   if (!published || canonical(published.record) !== canonical(record)) {
-    throw recoveryError(receipt, 'submission acceptance could not be reread');
+    throw recoveryError(receipt, `${label} could not be reread`);
   }
   return { ...published, resumed: receipt.resumed };
 }
 
-export async function runGuardedExternalMutation({ input, identity, dispatch, observe, publicationFacts, receiptIo }) {
+/**
+ * Publish the receipt, dispatch once, observe the postcondition and complete the receipt.
+ * @param rateLimit - Optional retry of a dispatch the venue refused with a 429:
+ *   { call, deadline, verifyBudgetMs, verifyNotPlaced({ sinceMs }) -> { proven, reason?, facts? }, sleep?, random? }.
+ *   A retry runs only when the dispatch itself threw the 429 (nothing accepted), the backoff and
+ *   the venue read fit before the deadline, and verifyNotPlaced then proves from the venue that
+ *   nothing was placed since the first dispatch. Every 429 is recorded in the receipt with its
+ *   verification or the reason it was not retried.
+ */
+export async function runGuardedExternalMutation({ input, identity, dispatch, observe, publicationFacts, receiptIo, rateLimit = null }) {
   let receipt = await beginExternalMutation(input, identity, receiptIo, publicationFacts);
   if (receipt.record?.state === 'observed-policy-violation') {
     throw new Error('External mutation receipt records an observed policy violation and is cleanup-only.');
@@ -886,27 +938,93 @@ export async function runGuardedExternalMutation({ input, identity, dispatch, ob
     throw new Error('External mutation receipt state is unsafe.');
   }
   if (!receipt.resumed) {
-    try {
-      const acceptance = await dispatch();
-      if (acceptance?.venueOrderId) receipt = await recordSubmissionAcceptance(input, receipt, acceptance);
-    } catch (error) {
-      if (error instanceof ExternalMutationNotDispatchedError) {
-        await markExternalMutationNotDispatched(input, receipt, error, receiptIo);
-        throw Object.assign(
-          new Error(
-            `External mutation was safely not dispatched (${error.message}). ` +
-            'Next: correct the observed state and create a fresh consent request, claim, and artifact root.',
-          ),
-          { knownNotDispatched: true },
-        );
+    const call = rateLimit?.call ?? `${identity.action} dispatch`;
+    const sinceMs = Date.now();
+    let waitedMs = 0;
+    for (let attempt = 1; ; attempt += 1) {
+      let returned = false;
+      try {
+        // A retry must reach the venue before the deadline, its pre-dispatch checks included.
+        const acceptance = await dispatch(attempt > 1 ? { deadline: rateLimit.deadline } : {});
+        returned = true;
+        if (acceptance?.venueOrderId) receipt = await recordSubmissionAcceptance(input, receipt, acceptance);
+        break;
+      } catch (error) {
+        if (error instanceof ExternalMutationNotDispatchedError) {
+          await markExternalMutationNotDispatched(input, receipt, error, receiptIo);
+          // A retry that was not sent still ends the action on the 429 that called for it.
+          const retried = attempt > 1;
+          throw Object.assign(
+            new Error(
+              `${retried ? `${RATE_LIMITED}: ` : ''}External mutation was safely not dispatched (` +
+              `${retried ? `${describeRateLimit({ call, attempts: attempt - 1, waitedMs })}; the retry was not sent: ` : ''}` +
+              `${error.message}). ` +
+              'Next: correct the observed state and create a fresh consent request, claim, and artifact root.',
+            ),
+            { knownNotDispatched: true, ...(retried ? { code: RATE_LIMITED } : {}) },
+          );
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        if (returned || !isRateLimited(error)) {
+          throw recoveryError(receipt, `pointer dispatch may have occurred (${message})`);
+        }
+        const deadline = rateLimit?.deadline;
+        const passesDeadline = (ms) => Number.isFinite(deadline) && Date.now() + ms >= deadline;
+        const backoffMs = attempt > RATE_LIMIT_RETRIES ? 0 : rateLimitBackoffMs(attempt, rateLimit?.random);
+        let refusal = !rateLimit?.verifyNotPlaced ? 'this mutation has no venue read that can prove nothing was placed'
+          : receipt.record.acceptance ? 'the receipt already records an accepted order'
+            : attempt > RATE_LIMIT_RETRIES ? 'its retries are spent'
+              : passesDeadline(backoffMs + (rateLimit.verifyBudgetMs ?? 0))
+                ? `the next ${backoffMs} ms backoff and the venue read would pass the action deadline` : null;
+        let verification = null;
+        if (!refusal) {
+          await (rateLimit.sleep ?? backoffSleep)(backoffMs);
+          waitedMs += backoffMs;
+          try {
+            verification = await rateLimit.verifyNotPlaced({ sinceMs });
+          } catch (verifyError) {
+            verification = {
+              proven: false,
+              reason: `the venue read failed (${verifyError instanceof Error ? verifyError.message : String(verifyError)})`,
+            };
+          }
+          if (verification?.proven !== true) {
+            refusal = verification?.reason ?? 'the venue read did not prove that nothing was placed';
+          } else if (passesDeadline(0)) {
+            refusal = 'the venue read ended past the action deadline';
+          }
+        }
+        receipt = await amendOutcomeUnknownReceipt(input, receipt, {
+          rateLimitedDispatches: [...(receipt.record.rateLimitedDispatches ?? []), {
+            attempt,
+            error: message.slice(0, 200),
+            ...(verification ? {
+              backoffMs,
+              verification: {
+                proven: verification.proven === true,
+                ...(verification.facts ? { facts: verification.facts } : {}),
+              },
+            } : {}),
+            ...(refusal ? { refusal: String(refusal).slice(0, 500) } : {}),
+          }],
+        }, 'the rate-limited dispatch');
+        if (refusal) {
+          throw rateLimitedRecoveryError(receipt, { call, attempts: attempt, waitedMs }, receipt.record.rateLimitedDispatches.at(-1).refusal);
+        }
       }
-      throw recoveryError(receipt, `pointer dispatch may have occurred (${error instanceof Error ? error.message : String(error)})`);
     }
   }
   let observation;
   try {
     observation = await observe({ resumed: receipt.resumed, receipt: receipt.record });
   } catch (error) {
+    if (isRateLimited(error)) {
+      throw rateLimitedRecoveryError(receipt, {
+        call: error.call ?? 'the postcondition read',
+        attempts: error.attempts ?? 1,
+        waitedMs: error.waitedMs ?? 0,
+      }, 'the postcondition read could not run, so the dispatched order is not proven');
+    }
     throw recoveryError(receipt, error instanceof Error ? error.message : String(error));
   }
   if (!observation || observation.success !== true) {

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

@@ -8,6 +8,7 @@ import path from 'node:path';
 import { dataTestId, marketSymbol, normalizeMarketSymbol, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 import {
   assertTrustedExternalMutationTarget,
+  BACKGROUND_ACCEPTANCE_SOURCE,
   externalMutationNotDispatched,
   readExternalMutationReceipt,
   readPriorMutationReceipt,
@@ -27,8 +28,11 @@ import {
   assertFlatBeforeRoundTrip,
   assertHouseLimitPosition,
   closeImmediatelyRequested,
+  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 {
   orderIdentityMatches,
   parseOrderCard,
@@ -343,23 +347,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');
@@ -669,7 +686,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)};
@@ -707,7 +724,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;
@@ -780,8 +797,33 @@ function backgroundPositionObservation(position) {
   return { market, side, leverage, size: String(position?.size ?? position?.szi), marginBaseUnits };
 }
 
-async function observeBackgroundPlace(page, expected, baselineIds, timeoutMs) {
+// Whole size steps in a size, or null when it is off the step grid.
+function sizeLots(size, sizeDecimals) {
+  const scaled = Math.abs(Number(size)) * 10 ** sizeDecimals;
+  const lots = Math.round(scaled);
+  return Number.isSafeInteger(lots) && lots > 0 && Math.abs(scaled - lots) < 1e-6 ? lots : null;
+}
+
+async function observeBackgroundPlace(page, expected, baselineIds, timeoutMs, acceptance) {
   const deadline = Date.now() + timeoutMs;
+  const lot = expected.orderType === 'market' ? expected.marketLot : null;
+  // A venue-reported fill fixes the exact size; without one the size may be a step
+  // off the lot computed here, since the controller sizes at its own fresh price.
+  const acceptedLots = lot && acceptance?.source === BACKGROUND_ACCEPTANCE_SOURCE
+    ? sizeLots(acceptance.filledSize, lot.sizeDecimals) : null;
+  if (lot && acceptance?.source === BACKGROUND_ACCEPTANCE_SOURCE
+    && (acceptedLots == null || Math.abs(acceptedLots - lot.lots) > 1)) {
+    throw new Error('Background Perps market fill size is not within one size step of the requested amount.');
+  }
+  const marginToleranceBaseUnits = lot
+    ? `${BigInt(expected.roundingToleranceBaseUnits) + BigInt(lot.stepMarginBaseUnits)}`
+    : expected.roundingToleranceBaseUnits;
+  const reported = acceptance?.source === BACKGROUND_ACCEPTANCE_SOURCE;
+  const sizeMatches = (size) => {
+    if (!lot) return !reported || Math.abs(Number(size)) === Number(acceptance.filledSize);
+    const observed = sizeLots(size, lot.sizeDecimals);
+    return observed != null && (acceptedLots != null ? observed === acceptedLots : Math.abs(observed - lot.lots) <= 1);
+  };
   while (Date.now() <= deadline) {
     if (expected.orderType === 'limit') {
       const matches = (await readOpenOrders(page))
@@ -798,12 +840,20 @@ async function observeBackgroundPlace(page, expected, baselineIds, timeoutMs) {
           && position.market === expected.market
           && position.side === expected.side
           && position.leverage === expected.leverage
+          && sizeMatches(position.size)
           && withinBaseUnitTolerance(
             position.marginBaseUnits,
             expected.amountBaseUnits,
-            expected.roundingToleranceBaseUnits,
+            marginToleranceBaseUnits,
           ));
-      if (matches.length === 1) return { success: true, position: matches[0] };
+      if (matches.length === 1) {
+        // The step tolerance widens the identity match, never the exposure the run allowed.
+        if (expected.maximumNotionalBaseUnits != null
+          && BigInt(matches[0].marginBaseUnits) * BigInt(matches[0].leverage) > BigInt(expected.maximumNotionalBaseUnits)) {
+          throw new Error('Background Perps position exposure exceeds the runner-trusted operation cap.');
+        }
+        return { success: true, position: matches[0] };
+      }
       if (matches.length > 1) throw new Error('Background position postcondition matched more than one position.');
     }
     await sleep(250);
@@ -870,12 +920,17 @@ async function dispatchBackgroundPlace(page, {
     };
     const result = await request('perpsPlaceOrder', [orderParams]);
     if (!result || result.success !== true) throw new Error(result?.error || 'perpsPlaceOrder failed.');
-    return { success: true };
+    return {
+      success: true,
+      orderId: result.orderId == null ? null : String(result.orderId),
+      filledSize: result.filledSize == null ? null : String(result.filledSize),
+      averagePrice: result.averagePrice == null ? null : String(result.averagePrice),
+    };
   })()`, { awaitPromise: true });
 }
 
 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;
@@ -893,13 +948,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;
@@ -917,7 +972,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;
 }
@@ -1202,6 +1257,52 @@ 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,
@@ -1246,20 +1347,44 @@ async function placeOrderThroughBackground(input, page, {
       }
     }
   }
+  if (!existing && expected.marketLot
+    && BigInt(expected.marketLot.notionalBaseUnits) > BigInt(expected.maximumNotionalBaseUnits)) {
+    throw new Error('Rounded Perps market lot exceeds the runner-trusted operation cap.');
+  }
+  // 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 mutation = await runGuardedExternalMutation({
     input,
     identity,
-    publicationFacts: { baselineOrderIds: [...baselineIds], fundingBalance },
-    dispatch: async () => {
+    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,
+      baselineOrderIds: [...baselineIds],
+      fundingBalance,
+      ...(expected.marketLot ? { marketLot: expected.marketLot } : {}),
+    },
+    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);
+        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));
       }
@@ -1278,13 +1403,26 @@ async function placeOrderThroughBackground(input, page, {
       if (accepted?.changed) {
         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
+      // position is this order's own.
+      if (orderType === 'market' && accepted?.orderId != null && accepted.filledSize != null && accepted.averagePrice != null) {
+        return {
+          source: BACKGROUND_ACCEPTANCE_SOURCE,
+          venueOrderId: accepted.orderId,
+          status: 'filled',
+          size: accepted.filledSize,
+          filledSize: accepted.filledSize,
+          averagePrice: accepted.averagePrice,
+        };
+      }
       return accepted;
     },
-    observe: async () => observeBackgroundPlace(
+    observe: async ({ receipt }) => observeBackgroundPlace(
       page,
-      expected,
+      { ...expected, marketLot },
       baselineIds,
       Number(input.node?.timeout_ms ?? 30_000),
+      receipt?.acceptance,
     ),
   });
   return {
@@ -1501,12 +1639,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);
@@ -1676,8 +1810,9 @@ export async function placeOrder(input) {
         const slippage = Number(input.node?.max_slippage_bps ?? input.node?.maxSlippageBps ?? 300) / 10_000;
         const margin = Number(amount);
         if (szDecimals == null) throw new Error(`close_immediately cannot read the ${symbol} size decimals; not dispatched.`);
-        const tolerance = Math.ceil(((10 ** -Number(szDecimals)) * Number(price) / leverage + margin * slippage) * 1_000_000) + 10_000;
-        if (!Number.isInteger(Number(szDecimals)) || !Number.isFinite(tolerance) || tolerance > 1_000_000) {
+        const lot = marketOrderLot({ amount, leverage, price, szDecimals });
+        const tolerance = lot ? Number(lot.stepMarginBaseUnits) + Math.ceil(margin * slippage * 1_000_000) + 10_000 : Number.NaN;
+        if (!Number.isFinite(tolerance) || tolerance > 1_000_000) {
           throw new Error(`close_immediately cannot prove a ${symbol} fill within $1 (size step or slippage too coarse); pass identity_rounding_tolerance_base_units or choose another market.`);
         }
         // The receipt identity must not move with the price, so a resume finds it:
@@ -1743,15 +1878,18 @@ export async function placeOrder(input) {
         symbol,
         input.node?.current_price ?? input.node?.currentPrice,
       );
+      const szDecimals = lane.network === 'mainnet' || orderType === 'market'
+        ? await readSizeDecimals(page, symbol) : null;
       houseNotional = requireHouseNotional({
         network: lane.network,
         symbol,
         amount,
         leverage,
         price: resolvedPrice,
-        szDecimals: lane.network === 'mainnet' ? await readSizeDecimals(page, symbol) : null,
+        szDecimals,
         maxSlippageBps: Number(input.node?.max_slippage_bps ?? input.node?.maxSlippageBps ?? 300),
       });
+      const marketLot = orderType === 'market' ? marketOrderLot({ amount, leverage, price: resolvedPrice, szDecimals }) : null;
       const backgroundLimitPrice = orderType === 'limit'
         ? resolveLimitPrice(input, isBuy, resolvedPrice)
         : null;
@@ -1764,6 +1902,7 @@ export async function placeOrder(input) {
         expected: {
           ...expectedVisibleIdentity,
           limitPriceBaseUnits: backgroundLimitPrice == null ? null : parseUsdBaseUnits(backgroundLimitPrice),
+          ...(marketLot ? { marketLot } : {}),
         },
         identity,
         isBuy,
@@ -2107,7 +2246,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; };
@@ -2117,7 +2256,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.'),
@@ -2131,9 +2270,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;
 }

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);