@deeeed/metamask-harness 0.87.0 → 0.89.0

package/library/actions/shared/perps/mainnet-order-ledger.mjs

@@ -0,0 +1,378 @@
+// The mainnet limit orders a run opened and has not yet proven cancelled. The
+// ledger sits next to the checkout's wallet fixture, so every process of a run
+// sees it: the action children that place and cancel, and the run's teardown
+// and abort handler (src/adapters/perps-mainnet-cleanup.ts) that cancel what is
+// left. place_order writes a pending entry before dispatch and the order ID
+// after it; on mainnet close_orders cancels only orders listed here. Settling an
+// entry writes order ID, cancel result and the read proving it gone into the
+// placing run's artifacts (MAINNET_ORDER_EVIDENCE_FILE). Every write holds a
+// cross-process lock, and each entry names its run (the mm-harness process the
+// action descends from), so a run's cleanup leaves another live run's orders
+// alone. Whether an order is gone is read from the venue itself
+// (readHyperliquidVenue), never only from the app, whose reads can come back
+// empty on an outage or after a provider or account switch.
+
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rmdir, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { walletFixturePath } from '../../harness-exports.mjs';
+
+export const MAINNET_RUN_OWNER_ENV = 'RECIPE_RUN_OWNER_PID';
+export const MAINNET_ORDER_EVIDENCE_FILE = 'perps-mainnet-orders.json';
+// The only venue a mainnet limit order may use: its public info API proves the result.
+export const MAINNET_LIMIT_PROVIDER = 'hyperliquid';
+const HYPERLIQUID_INFO_URL = 'https://api.hyperliquid.xyz/info';
+
+export function mainnetOrderLedgerPath(projectRoot) {
+  return path.join(path.dirname(walletFixturePath(projectRoot)), 'perps-mainnet-orders.json');
+}
+
+async function readJson(file, empty) {
+  let raw;
+  try {
+    raw = await readFile(file, 'utf8');
+  } catch (error) {
+    // No file is the empty ledger (or evidence list); anything else throws.
+    if (error?.code === 'ENOENT') return empty;
+    throw error;
+  }
+  return JSON.parse(raw);
+}
+
+async function writeJson(file, value) {
+  await mkdir(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(temp, `${JSON.stringify(value, null, 2)}\n`);
+  await rename(temp, file);
+}
+
+/** @returns {Promise<{ entries: object[], networkSwitch?: object, abortingRuns?: number[] }>} */
+export async function readMainnetOrderLedger(projectRoot) {
+  const file = mainnetOrderLedgerPath(projectRoot);
+  const ledger = await readJson(file, { entries: [] });
+  if (!Array.isArray(ledger?.entries)) throw new Error(`${file} is not a Perps mainnet order ledger.`);
+  return ledger;
+}
+
+const LOCK_STALE_MS = 30_000;
+const LOCK_WAIT_MS = 15_000;
+
+// mkdir is atomic: whoever creates the directory holds the lock. A lock older
+// than LOCK_STALE_MS belonged to a process that died holding it.
+async function withLedgerLock(projectRoot, body) {
+  const lock = `${mainnetOrderLedgerPath(projectRoot)}.lock`;
+  await mkdir(path.dirname(lock), { recursive: true });
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      await mkdir(lock);
+      break;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      const held = await stat(lock).then((info) => Date.now() - info.mtimeMs, (statError) => {
+        // Released between mkdir and stat: try again at once.
+        if (statError?.code === 'ENOENT') return 0;
+        throw statError;
+      });
+      if (held > LOCK_STALE_MS) {
+        await rmdir(lock).catch((rmError) => {
+          // Another waiter removed the stale lock first.
+          if (rmError?.code !== 'ENOENT') throw rmError;
+        });
+        continue;
+      }
+      if (Date.now() >= deadline) throw new Error(`Mainnet order ledger is locked (${lock}) for over ${LOCK_WAIT_MS / 1000} s.`);
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+  }
+  try {
+    return await body();
+  } finally {
+    await rmdir(lock);
+  }
+}
+
+function updateLedger(projectRoot, change) {
+  return withLedgerLock(projectRoot, async () => {
+    const ledger = await readMainnetOrderLedger(projectRoot);
+    const result = change(ledger);
+    await writeJson(mainnetOrderLedgerPath(projectRoot), ledger);
+    return result;
+  });
+}
+
+// An explicitly registered provider process must be this process or an ancestor.
+// Existing mm-harness children also resolve their nearest CLI ancestor.
+export function currentRunPid() {
+  const owner = Number(process.env[MAINNET_RUN_OWNER_ENV]);
+  if (Number.isSafeInteger(owner) && owner === process.pid) return owner;
+  let pid = process.ppid;
+  for (let depth = 0; depth < 8 && pid > 1; depth += 1) {
+    const [parent, ...args] = execFileSync('ps', ['-o', 'ppid=,args=', '-p', String(pid)], { encoding: 'utf8' }).trim().split(/\s+/u);
+    if (Number.isSafeInteger(owner) && owner === pid) return pid;
+    if (args.some((arg) => /mm-harness-cli\.(?:js|ts)$/u.test(arg))) return pid;
+    pid = Number(parent);
+  }
+  return null;
+}
+
+async function venueInfo(body) {
+  const response = await fetch(HYPERLIQUID_INFO_URL, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (!response.ok) throw new Error(`Hyperliquid info ${body.type} answered HTTP ${response.status}`);
+  return response.json();
+}
+
+/**
+ * The account's open orders and signed position in one market, read from the
+ * Hyperliquid mainnet API (main dex markets only). Throws when it cannot read.
+ */
+export async function readHyperliquidVenue(address, symbol) {
+  if (String(symbol).includes(':')) throw new Error(`${symbol} is not a main-dex Hyperliquid market; its book cannot be verified`);
+  const [orders, state] = await Promise.all([
+    venueInfo({ type: 'frontendOpenOrders', user: address }),
+    venueInfo({ type: 'clearinghouseState', user: address }),
+  ]);
+  if (!Array.isArray(orders) || !Array.isArray(state?.assetPositions)) throw new Error('Hyperliquid info returned an unexpected shape');
+  return {
+    source: 'api.hyperliquid.xyz/info frontendOpenOrders+clearinghouseState',
+    openOrders: orders.map((order) => ({
+      orderId: String(order.oid),
+      symbol: order.coin,
+      side: order.side === 'B' ? 'long' : 'short',
+      price: order.limitPx,
+    })),
+    positionSize: state.assetPositions
+      .filter((entry) => entry.position?.coin === symbol)
+      .reduce((total, entry) => total + Number(entry.position.szi), 0),
+  };
+}
+
+// The venue's fields for ledgerOrderTargets.
+export const VENUE_ORDER_FIELDS = {
+  idOf: (order) => order.orderId,
+  symbolOf: (order) => order.symbol,
+  sideOf: (order) => order.side,
+  priceOf: (order) => order.price,
+};
+
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // ESRCH: gone. EPERM: alive under another user.
+    if (error?.code === 'ESRCH') return false;
+    if (error?.code === 'EPERM') return true;
+    throw error;
+  }
+}
+
+/** Whether `runPid` (the process cleaning up) may settle this record: its own, or one whose run is gone. */
+export function cleanupOwns(record, runPid) {
+  return !record.runPid || record.runPid === runPid || !processAlive(record.runPid);
+}
+
+/**
+ * Record a mainnet limit order before dispatch, so a run that dies before the
+ * venue answers still cancels it. `baselineOrderIds` are the account's open
+ * order IDs before dispatch; the venue's position in the market is recorded
+ * too. Refused once the run is aborting, or off Hyperliquid.
+ * `connection` is what reaches the app again from the run's process.
+ * @returns {Promise<string>} The entry ID.
+ */
+export async function recordPendingMainnetOrder(projectRoot, {
+  platform, provider, symbol, side, limitPrice, address, baselineOrderIds, artifactsDir, connection,
+}) {
+  if (provider !== MAINNET_LIMIT_PROVIDER) {
+    throw Object.assign(
+      new Error(`PERPS_MAINNET_ORDER_REFUSED: a mainnet limit order needs the ${MAINNET_LIMIT_PROVIDER} provider, not ${provider ?? 'an unknown one'}; refused before dispatch.`),
+      { code: 'PERPS_MAINNET_ORDER_REFUSED', knownNotDispatched: true },
+    );
+  }
+  // The run is resolved before anything is awaited: an aborted run's child,
+  // re-parented after its run exits, must still find it marked aborting.
+  const runPid = currentRunPid();
+  if (!runPid) {
+    throw Object.assign(
+      new Error('PERPS_MAINNET_ORDER_REFUSED: a mainnet limit order needs an mm-harness run or call to cancel it at its end; refused before dispatch.'),
+      { code: 'PERPS_MAINNET_ORDER_REFUSED', knownNotDispatched: true },
+    );
+  }
+  // The venue's book before the order: a fill shows as a position change, and
+  // a recovered pending order is never one that was already open.
+  const venue = await readHyperliquidVenue(address, symbol);
+  const id = randomUUID();
+  await updateLedger(projectRoot, (ledger) => {
+    if (ledger.abortingRuns?.includes(runPid)) throw runAbortingRefusal();
+    ledger.entries.push({
+      id,
+      platform,
+      provider,
+      state: 'pending',
+      orderId: null,
+      runPid,
+      symbol,
+      side,
+      limitPrice: String(limitPrice),
+      address: String(address).toLowerCase(),
+      baselineOrderIds: [...new Set([...baselineOrderIds.map(String), ...venue.openOrders.map((order) => order.orderId)])],
+      baselinePositionSize: venue.positionSize,
+      artifactsDir,
+      connection,
+      placedAt: new Date().toISOString(),
+    });
+  });
+  return id;
+}
+
+function runAbortingRefusal() {
+  return Object.assign(
+    new Error('PERPS_MAINNET_ORDER_REFUSED: the run is aborting; mainnet order not dispatched.'),
+    { code: 'PERPS_MAINNET_ORDER_REFUSED', knownNotDispatched: true },
+  );
+}
+
+// A redispatch reuses its pending entry: refused once the entry's run is aborting
+// or its cleanup has already settled the entry, as a first dispatch would be.
+export async function requirePendingMainnetOrder(projectRoot, id) {
+  await withLedgerLock(projectRoot, async () => {
+    const ledger = await readMainnetOrderLedger(projectRoot);
+    const entry = ledger.entries.find((candidate) => candidate.id === id);
+    if (!entry || ledger.abortingRuns?.includes(entry.runPid)) throw runAbortingRefusal();
+  });
+}
+
+export async function recordPlacedMainnetOrder(projectRoot, id, orderId) {
+  await updateLedger(projectRoot, (ledger) => {
+    const entry = ledger.entries.find((candidate) => candidate.id === id);
+    if (!entry) throw new Error(`Mainnet order ledger has no entry ${id}; the order ${orderId} is not tracked.`);
+    entry.state = 'placed';
+    entry.orderId = String(orderId);
+  });
+}
+
+// The order was refused before dispatch: nothing to cancel.
+export async function dropMainnetOrder(projectRoot, id) {
+  await updateLedger(projectRoot, (ledger) => {
+    ledger.entries = ledger.entries.filter((candidate) => candidate.id !== id);
+  });
+}
+
+/** The ledger entry of a placed, still open order this checkout's runs opened, or null. */
+export async function ownedMainnetOrder(projectRoot, orderId) {
+  const wanted = String(orderId ?? '');
+  // No order ID or no checkout: nothing this checkout's runs can own.
+  if (!wanted || !projectRoot) return null;
+  const { entries } = await readMainnetOrderLedger(projectRoot);
+  return entries.find((entry) => entry.state === 'placed' && entry.orderId === wanted) ?? null;
+}
+
+// close_orders cancelled it: the run's teardown still checks the market's
+// position (a partial fill) before settling the entry with this proof.
+export async function markMainnetOrderCancelled(projectRoot, id, cancelProof) {
+  await updateLedger(projectRoot, (ledger) => {
+    const entry = ledger.entries.find((candidate) => candidate.id === id);
+    if (!entry) throw new Error(`Mainnet order ledger has no entry ${id}.`);
+    entry.state = 'cancelled';
+    entry.cancelProof = cancelProof;
+  });
+}
+
+const LIMIT_PRICE_TOLERANCE = 0.001;
+
+/**
+ * The open orders a ledger entry stands for: its order by ID, or for a pending
+ * entry an order in its market and side at its limit price that was not open
+ * before dispatch.
+ */
+export function ledgerOrderTargets(entry, openOrders, { idOf, symbolOf, sideOf, priceOf }) {
+  if (entry.orderId) return openOrders.filter((order) => String(idOf(order)) === entry.orderId);
+  const baseline = new Set(entry.baselineOrderIds);
+  const limitPrice = Number(entry.limitPrice);
+  return openOrders.filter((order) => symbolOf(order) === entry.symbol
+    && sideOf(order) === entry.side
+    && !baseline.has(String(idOf(order)))
+    && Math.abs(Number(priceOf(order)) - limitPrice) <= limitPrice * LIMIT_PRICE_TOLERANCE);
+}
+
+/**
+ * Drop a cancelled entry and append its proof to the placing run's evidence.
+ * @param {object} proof - { via, canceled: [{ orderId, result }], read: { source, openOrderIds, positionSize, absent | notOpen } }
+ */
+export async function settleMainnetOrder(projectRoot, entry, proof) {
+  const evidencePath = path.join(entry.artifactsDir, MAINNET_ORDER_EVIDENCE_FILE);
+  await withLedgerLock(projectRoot, async () => {
+    const evidence = await readJson(evidencePath, { orders: [] });
+    evidence.orders.push({
+      // A pending entry learns its order ID from the cancel that found it.
+      orderId: entry.orderId ?? proof.canceled?.[0]?.orderId ?? null,
+      symbol: entry.symbol,
+      side: entry.side,
+      limitPrice: entry.limitPrice,
+      placedAt: entry.placedAt,
+      settledAt: new Date().toISOString(),
+      ...proof,
+    });
+    await writeJson(evidencePath, evidence);
+    const ledger = await readMainnetOrderLedger(projectRoot);
+    ledger.entries = ledger.entries.filter((candidate) => candidate.id !== entry.id);
+    await writeJson(mainnetOrderLedgerPath(projectRoot), ledger);
+  });
+  return evidencePath;
+}
+
+// From now on this run's action children dispatch no mainnet order.
+export async function markRunAborting(projectRoot, runPid) {
+  await updateLedger(projectRoot, (ledger) => {
+    ledger.abortingRuns = [...(ledger.abortingRuns ?? []).filter(processAlive), runPid];
+  });
+}
+
+// The Extension's set_network switched Perps to mainnet for this run: the run's
+// teardown switches it back to testnet.
+export async function recordMainnetSwitch(projectRoot, networkSwitch) {
+  await updateLedger(projectRoot, (ledger) => {
+    ledger.networkSwitch = { ...networkSwitch, runPid: currentRunPid(), at: new Date().toISOString() };
+  });
+}
+
+export async function clearMainnetSwitch(projectRoot) {
+  await updateLedger(projectRoot, (ledger) => {
+    delete ledger.networkSwitch;
+  });
+}
+
+// Leaving mainnet would strand the run's open orders: the forced cancel needs
+// the app on mainnet. Cancel them (close_orders) or let the run end first.
+export async function requireNoOpenMainnetOrders(projectRoot, action) {
+  if (!projectRoot) return;
+  const { entries } = await readMainnetOrderLedger(projectRoot);
+  const open = entries.filter((entry) => entry.state !== 'cancelled');
+  if (open.length === 0) return;
+  throw Object.assign(
+    new Error(
+      `PERPS_MAINNET_ORDER_OPEN: ${action} would leave mainnet while the run's mainnet order(s) ` +
+        `${open.map((entry) => entry.orderId ?? `pending ${entry.symbol}`).join(', ')} are open. ` +
+        'Next: cancel them with metamask.perps.close_orders first, or switch networks after the run ends.',
+    ),
+    { code: 'PERPS_MAINNET_ORDER_OPEN' },
+  );
+}
+
+export function mainnetOrderLeftOpenError(failures) {
+  return Object.assign(
+    new Error(
+      `PERPS_MAINNET_ORDER_LEFT_OPEN: ${failures.length} mainnet order(s) this checkout's runs placed are not proven closed out: ` +
+        `${failures.map(({ entry, error }) => `${entry.orderId ?? `pending ${entry.symbol} ${entry.side} @ ${entry.limitPrice}`} (${error instanceof Error ? error.message : String(error)})`).join('; ')}. ` +
+        'Next: cancel the order or close the position in the app on the account that placed it now; the next run on this checkout retries an order cancel while the app is on that account and mainnet.',
+    ),
+    { code: 'PERPS_MAINNET_ORDER_LEFT_OPEN' },
+  );
+}

package/library/actions/shared/perps/order-policy.mjs

@@ -1,15 +1,18 @@
 // The Perps order rule every adapter applies before dispatch (F21).
 // Testnet orders need no funding proof. A mainnet order is allowed only from a
 // synced fixture account within the house limits: 1x isolated, notional at
-// most $15, closed again inside the same action (close_immediately: true).
+// most $15, and either a market order closed again inside the same action
+// (close_immediately: true) or a resting dev1 limit order the run cancels at
+// its end (mainnet-order-ledger.mjs).
 
-import { isFixtureAccount } from '../wallet/fixture-accounts.mjs';
+import { fixtureAccountNameOf } from '../wallet/fixture-accounts.mjs';
 
 export const MAINNET_HOUSE_LIMITS = Object.freeze({
   maxNotionalUsd: '15',
   maxNotionalBaseUnits: 15_000_000n,
   leverage: 1,
   marginType: 'isolated',
+  limitOrderAccount: 'dev1',
 });
 
 const USDC_DECIMAL = /^(?:0|[1-9][0-9]{0,11})(?:\.([0-9]{1,6}))?$/u;
@@ -57,9 +60,13 @@ export function closeImmediatelyRequested(node) {
  * @param {'market'|'limit'} [order.orderType]
  * @param {boolean} order.closeImmediately
  * @param {boolean} order.fixtureAccount - The selected account is a synced fixture account.
- * @returns {{ lane: 'testnet' } | { lane: 'mainnet-house-limits', notionalBaseUnits: string }}
+ * @param {string|null} [order.accountName] - Its fixture name.
+ * @param {boolean} [order.runCancelsLimit] - The caller records a limit order for the run's forced cancel.
+ * @returns {{ lane: 'testnet' } | { lane: 'mainnet-house-limits', notionalBaseUnits: string, autoCancel?: 'end-of-run' }}
  */
-export function decidePerpsOrder({ network, amount, leverage, orderType = 'market', closeImmediately, fixtureAccount }) {
+export function decidePerpsOrder({
+  network, amount, leverage, orderType = 'market', closeImmediately, fixtureAccount, accountName = null, runCancelsLimit = false,
+}) {
   if (closeImmediately && orderType !== 'market') {
     throw new Error('close_immediately needs a market order: a resting limit order is not a position the action can close.');
   }
@@ -76,29 +83,42 @@ export function decidePerpsOrder({ network, amount, leverage, orderType = 'marke
   if (notionalBaseUnits > MAINNET_HOUSE_LIMITS.maxNotionalBaseUnits) {
     broken.push(`notional ${formatUsd(notionalBaseUnits)} is above $${MAINNET_HOUSE_LIMITS.maxNotionalUsd}`);
   }
-  if (orderType !== 'market') broken.push(`order type is ${orderType}, not market`);
-  if (!closeImmediately) broken.push('close_immediately is not true');
+  if (orderType === 'limit') {
+    if (fixtureAccount && accountName !== MAINNET_HOUSE_LIMITS.limitOrderAccount) {
+      broken.push(`a limit order needs the ${MAINNET_HOUSE_LIMITS.limitOrderAccount} account, not ${accountName ?? 'an unnamed account'}`);
+    }
+    if (!runCancelsLimit) broken.push('this action cannot leave a limit order for the run to cancel at its end');
+  } else if (orderType !== 'market') {
+    broken.push(`order type is ${orderType}, not market or limit`);
+  } else if (!closeImmediately) {
+    broken.push('close_immediately is not true');
+  }
   if (broken.length > 0) {
     throw Object.assign(
       new Error(
         // The code leads the message: it is what survives a live adapter's process
         // boundary, and the wording avoids the words bounded healing reads as wallet state.
         `PERPS_MAINNET_ORDER_REFUSED: Mainnet Perps order refused before dispatch: ${broken.join('; ')}. ` +
-          `Mainnet orders need a synced test account, a 1x isolated market order, notional at most $${MAINNET_HOUSE_LIMITS.maxNotionalUsd} and close_immediately: true. ` +
+          `Mainnet orders need a synced test account, 1x isolated, notional at most $${MAINNET_HOUSE_LIMITS.maxNotionalUsd}, and either a market order with close_immediately: true ` +
+          `or a ${MAINNET_HOUSE_LIMITS.limitOrderAccount} limit order away from the market, which the run cancels at its end. ` +
           'Next: use testnet, or stay within those limits.',
       ),
       { code: 'PERPS_MAINNET_ORDER_REFUSED' },
     );
   }
-  return { lane: 'mainnet-house-limits', notionalBaseUnits: `${notionalBaseUnits}` };
+  return {
+    lane: 'mainnet-house-limits',
+    notionalBaseUnits: `${notionalBaseUnits}`,
+    ...(orderType === 'limit' ? { autoCancel: 'end-of-run' } : {}),
+  };
 }
 
 // decidePerpsOrder with the fixture check resolved from the checkout's fixture.
 export async function requirePerpsOrderAllowed({ projectRoot, selectedAddress, ...order }) {
-  const fixtureAccount = order.network === 'mainnet'
-    ? await isFixtureAccount(projectRoot, selectedAddress)
-    : false;
-  return decidePerpsOrder({ ...order, fixtureAccount });
+  const accountName = order.network === 'mainnet'
+    ? await fixtureAccountNameOf(projectRoot, selectedAddress)
+    : null;
+  return decidePerpsOrder({ ...order, fixtureAccount: accountName !== null, accountName });
 }
 
 // close_immediately closes the market's whole position (positions are netted
@@ -143,26 +163,43 @@ export function marketOrderLot({ amount, leverage, price, szDecimals }) {
 }
 
 // Mainnet only: refuse before dispatch when the size the controller would submit
-// could fill above the house notional limit. Testnet needs no bound.
-export function requireHouseNotional({ network, symbol, amount, leverage, price, szDecimals, maxSlippageBps }) {
+// could fill above the house notional limit. Testnet needs no bound. A limit
+// order (`limit: { price, isBuy }`) must rest away from the market, so it is
+// bounded at its own price with no slippage: one that would fill now is refused.
+export function requireHouseNotional({ network, symbol, amount, leverage, price, szDecimals, maxSlippageBps, limit = null }) {
   if (network !== 'mainnet') return null;
   // A missing value is unknown, never zero (Number(null) is 0).
   const known = (value) => (value == null || value === '' ? Number.NaN : Number(value));
-  const inputs = { price: known(price), szDecimals: known(szDecimals), maxSlippageBps: known(maxSlippageBps) };
+  const inputs = {
+    price: known(price),
+    szDecimals: known(szDecimals),
+    maxSlippageBps: limit ? 0 : known(maxSlippageBps),
+  };
+  const limitPrice = limit ? known(limit.price) : null;
   if (!(inputs.price > 0) || !Number.isInteger(inputs.szDecimals) || inputs.szDecimals < 0
-    || !Number.isFinite(inputs.maxSlippageBps) || inputs.maxSlippageBps < 0) {
+    || !Number.isFinite(inputs.maxSlippageBps) || inputs.maxSlippageBps < 0 || (limit && !(limitPrice > 0))) {
     throw Object.assign(
       new Error(`PERPS_MAINNET_ORDER_REFUSED: Mainnet Perps order refused before dispatch: cannot bound the ${symbol} order size (price, size decimals or slippage unknown).`),
       { code: 'PERPS_MAINNET_ORDER_REFUSED' },
     );
   }
-  const worst = worstCaseNotionalUsd({ amount, leverage, ...inputs });
+  if (limit && (limit.isBuy ? limitPrice >= inputs.price : limitPrice <= inputs.price)) {
+    throw Object.assign(
+      new Error(
+        `PERPS_MAINNET_ORDER_REFUSED: Mainnet Perps order refused before dispatch: a ${limit.isBuy ? 'buy' : 'sell'} limit at $${limitPrice} ` +
+          `would fill now against the ${symbol} price $${inputs.price} and open a position. Next: set limit_price ${limit.isBuy ? 'below' : 'above'} the market.`,
+      ),
+      { code: 'PERPS_MAINNET_ORDER_REFUSED' },
+    );
+  }
+  const boundPrice = limit ? limitPrice : inputs.price;
+  const worst = worstCaseNotionalUsd({ amount, leverage, ...inputs, price: boundPrice });
   if (worst > Number(MAINNET_HOUSE_LIMITS.maxNotionalUsd)) {
     throw Object.assign(
       new Error(
         `PERPS_MAINNET_ORDER_REFUSED: Mainnet Perps order refused before dispatch: a ${symbol} order for $${Number(amount) * Number(leverage)} can fill at up to $${worst.toFixed(2)} ` +
-          `(size step ${10 ** -inputs.szDecimals} at $${inputs.price}, max slippage ${inputs.maxSlippageBps} bps), above $${MAINNET_HOUSE_LIMITS.maxNotionalUsd}. ` +
-          'Next: order less, or lower max_slippage_bps.',
+          `(size step ${1 / 10 ** inputs.szDecimals} at $${boundPrice}, max slippage ${inputs.maxSlippageBps} bps), above $${MAINNET_HOUSE_LIMITS.maxNotionalUsd}. ` +
+          `Next: order less${limit ? '' : ', or lower max_slippage_bps'}.`,
       ),
       { code: 'PERPS_MAINNET_ORDER_REFUSED' },
     );

package/library/actions/shared/wallet/fixture-accounts.mjs

@@ -73,12 +73,18 @@ export async function readFixtureAccounts(projectRoot) {
 // Whether an address is one of the fixture's accounts. A missing or unreadable
 // fixture is "not a fixture account": the caller refuses, it never assumes.
 export async function isFixtureAccount(projectRoot, address) {
+  return (await fixtureAccountNameOf(projectRoot, address)) !== null;
+}
+
+// The fixture name of an address (dev1, Trading, ...), or null when it is not
+// one of the fixture's accounts or the fixture is missing or unreadable.
+export async function fixtureAccountNameOf(projectRoot, address) {
   const wanted = String(address ?? '').toLowerCase();
-  if (!/^0x[0-9a-f]{40}$/u.test(wanted) || !projectRoot) return false;
+  if (!/^0x[0-9a-f]{40}$/u.test(wanted) || !projectRoot) return null;
   try {
     const loaded = await readFixtureAccounts(projectRoot);
-    return Boolean(loaded?.accounts.some((account) => account.address.toLowerCase() === wanted));
+    return loaded?.accounts.find((account) => account.address.toLowerCase() === wanted)?.name ?? null;
   } catch {
-    return false;
+    return null;
   }
 }

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

@@ -4132,7 +4132,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.close_orders": {
-      "description": "extension Cancel selected live Perps open orders. Use selector/mode params to cancel matching symbols or all orders. On mainnet, cancel is refused in the fixture-policy lane and needs the funded release lane. Extension ensure_* only assert existing state; converge an owned testnet account through an explicitly funded leaf action.",
+      "description": "extension Cancel selected live Perps open orders. Use selector/mode params to cancel matching symbols or all orders. On mainnet, the fixture-policy lane cancels only orders this run placed; any other cancel needs the funded release lane. Extension ensure_* only assert existing state; converge an owned testnet account through an explicitly funded leaf action.",
       "schema": {
         "type": "object",
         "properties": {
@@ -4253,7 +4253,7 @@
           },
           "order_id": {
             "type": "string",
-            "description": "Exact product order ID required for receipt-bound background cancellation."
+            "description": "Exact product order ID required for receipt-bound background cancellation. On mainnet without funding files, only an order this run placed."
           },
           "offset_pct": {
             "type": "number"
@@ -4410,7 +4410,7 @@
           },
           "close_immediately": {
             "type": "boolean",
-            "description": "Close the opened position again inside this action and prove the market flat (market orders only; the market must start flat). Required on mainnet, with leverage 1 and notional at most $15 from a fixture account."
+            "description": "Close the opened position again inside this action and prove the market flat (market orders only; the market must start flat). A mainnet market order needs it, with leverage 1 and notional at most $15 from a fixture account; a mainnet limit order takes none (the run cancels it at its end)."
           },
           "provider": {
             "type": "string",
@@ -4422,7 +4422,7 @@
               "mainnet",
               "testnet"
             ],
-            "description": "Exact Perps network required before background dispatch; the action never toggles it."
+            "description": "Exact Perps network required before background dispatch; the action never toggles it (metamask.perps.set_network does). A mainnet order is a market order with close_immediately, or a dev1 limit order away from the market at 1x and at most $15 notional at its limit price, which the run cancels at its end (success, failure or abort) and records in perps-mainnet-orders.json."
           },
           "order_type": {
             "type": "string",
@@ -5161,6 +5161,36 @@
         "app-mutation"
       ]
     },
+    "metamask.perps.set_network": {
+      "description": "Switch the Extension's Perps network through the background perpsToggleTestnet request and wait until the app reports it. The fixture loads testnet; network=mainnet is the explicit opt-in and lasts one run: the run's teardown switches back to testnet (success, failure or abort).",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "network": {
+            "type": "string",
+            "enum": ["testnet", "mainnet"],
+            "default": "testnet",
+            "description": "Perps network to select; unchanged when already selected."
+          },
+          "timeout_ms": {
+            "type": "number",
+            "description": "How long to wait for the app to report the new network."
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.perps.set_network",
+          "network": "mainnet",
+          "intent": "Switch Perps to mainnet for this run",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": [
+        "app-mutation"
+      ]
+    },
     "metamask.deeplink.open": {
       "description": "Open an HTTPS deeplink through real browser ingress so the Extension owns parsing, verification, and destination navigation.",
       "execution_capabilities": [