@deeeed/metamask-harness 0.48.0 → 0.49.0

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

@@ -1,3 +1,6 @@
+// Implement Extension Perps state reads, UI setup and funded trade operations.
+// Funded paths check runtime identity and retain mutation receipts for cleanup.
+
 import { pathToFileURL } from 'node:url';
 import { createHash } from 'node:crypto';
 import { dataTestId, marketSymbol, normalizeMarketSymbol, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
@@ -323,6 +326,50 @@ async function closeOrderThroughBackground(input, page, timeoutMs) {
   };
 }
 
+async function readAcceptedFilledOrder(input, page, placement, requireTerminal = false) {
+  const accepted = placement.record?.acceptance;
+  if (!accepted?.venueOrderId) return null;
+  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');
+  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');
+  }
+  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),
+  });
+  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');
+  const order = result.order?.order;
+  if (result.status !== 'order' || String(order?.oid) !== accepted.venueOrderId
+    || order.coin !== placement.record.identity.market
+    || order.side !== (placement.record.identity.side === 'long' ? 'B' : 'A')
+    || order.orderType !== 'Limit'
+    || parseUsdBaseUnits(order.limitPx) !== accepted.limitPriceBaseUnits
+    || Number(order.origSz) !== Number(accepted.size)) {
+    throw new Error('Venue order status differs from the exact accepted placement identity.\nNext: mm-harness last --json');
+  }
+  if (result.order.status !== 'filled') {
+    if (requireTerminal && result.order.status !== 'canceled') {
+      throw new Error('Accepted order has not reached a verified canceled or filled outcome.\nNext: mm-harness last --json');
+    }
+    return null;
+  }
+  if (!/^0(?:\.0+)?$/u.test(String(order.sz)) || !Number.isSafeInteger(result.order.statusTimestamp)
+    || result.order.statusTimestamp <= 0) {
+    throw new Error('Venue status does not prove a complete accepted-order fill.\nNext: mm-harness last --json');
+  }
+  return { source: 'hyperliquid-orderStatus', orderId: accepted.venueOrderId, status: 'filled',
+    market: order.coin, size: String(order.origSz), remainingSize: String(order.sz),
+    statusTimestamp: result.order.statusTimestamp };
+}
+
 export async function closeOrders(input) {
   requireExplicitSelection(input);
   return withExtensionPage(input, async (page) => {
@@ -348,7 +395,8 @@ export async function closeOrders(input) {
       const limitPrice = String(input.node?.limit_price ?? '');
       const roundingToleranceBaseUnits = String(input.node?.identity_rounding_tolerance_base_units ?? '10000');
       if (!/^(?:long|short)$/u.test(side) || !Number.isInteger(leverage)
-        || !/^[1-9][0-9]*(?:\.[0-9]{1,6})?$/u.test(limitPrice)) {
+        || !/^(?:0|[1-9][0-9]*)(?:\.[0-9]{1,6})?$/u.test(limitPrice)
+        || !(Number(limitPrice) > 0)) {
         throw new Error('Visible Perps cancellation requires side, amount, leverage, and explicit limit_price identity.');
       }
       const operation = {
@@ -396,8 +444,57 @@ export async function closeOrders(input) {
         && BigInt(cleanupCandidate.observedNotionalBaseUnits) > BigInt(expectedOrder.notionalBaseUnits)
         && BigInt(cleanupCandidate.overageBaseUnits)
           === BigInt(cleanupCandidate.observedNotionalBaseUnits) - BigInt(expectedOrder.notionalBaseUnits);
-      const priorOrder = cleanupMode ? cleanupOrder : priorPlace.record?.observation?.order;
-      if (!priorOrder?.id || !(cleanupMode || orderIdentityMatches(priorOrder, expectedOrder))) {
+      let priorOrder = cleanupMode ? cleanupOrder : priorPlace.record?.observation?.order;
+      const accepted = priorPlace.record?.acceptance;
+      if (accepted && (accepted.limitPriceBaseUnits !== expectedOrder.limitPriceBaseUnits
+        || priorPlace.record.identity.amountBaseUnits !== priorLookupIdentity.amountBaseUnits
+        || priorPlace.record.identity.leverage !== leverage)) {
+        throw new Error('Cancellation parameters differ from the exact accepted placement identity.');
+      }
+      const matchesAcceptedRemainder = (order) => accepted?.status === 'resting'
+        && order.id === `order-card-${accepted.venueOrderId}`
+        && order.market === symbol && order.side === side && order.orderType === 'limit'
+        && order.limitPriceBaseUnits === accepted.limitPriceBaseUnits
+        && Number(order.size) > 0 && Number(order.size) <= Number(accepted.size);
+      const alreadyFilledResult = (filledOrder) => ({ action: input.action, canceled: false,
+        matchingCount: 0, symbols: [symbol], reason: 'already_filled', filledOrder,
+        proofPath: 'accepted-order-status' });
+      const openCancelModal = async () => {
+        const selector = `[data-testid=${JSON.stringify(priorOrder.id)}]`;
+        try {
+          await page.click(selector);
+          await page.waitForSelector(dataTestId('perps-cancel-order-modal'), { timeoutMs });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          if (message.includes(`Selector not found: ${selector}`)
+            || message.includes(`Click target readiness timed out: ${selector}`)
+            || message.includes('ui.wait_for timed out')) {
+            const filledOrder = await readAcceptedFilledOrder(input, page, priorPlace);
+            if (filledOrder) return filledOrder;
+          }
+          throw error;
+        }
+        return null;
+      };
+      if (accepted?.status === 'filled') {
+        const filledOrder = await readAcceptedFilledOrder(input, page, priorPlace);
+        if (filledOrder) return alreadyFilledResult(filledOrder);
+        throw new Error(`Accepted limit order ${accepted.venueOrderId} filled; do not cancel or infer ownership of a current position.`);
+      }
+      if (accepted?.status === 'resting') {
+        await requirePerpsTradingContext(input, page);
+        await page.navigateHash(`#/perps/market/${encodeURIComponent(symbol)}`);
+        await page.waitForSelector(dataTestId('perps-market-detail-pair'), { timeoutMs });
+        const exact = (await readVisibleOrderCards(page, symbol)).filter(matchesAcceptedRemainder);
+        priorOrder = exact.length === 1 ? exact[0] : null;
+      }
+      if (accepted && priorOrder?.id !== `order-card-${accepted.venueOrderId}`) {
+        const filledOrder = await readAcceptedFilledOrder(input, page, priorPlace);
+        if (filledOrder) return alreadyFilledResult(filledOrder);
+        throw new Error('Visible order does not match the exact venue acceptance in the placement receipt.');
+      }
+      if (!priorOrder?.id || !(accepted ? matchesAcceptedRemainder(priorOrder)
+        : cleanupMode || orderIdentityMatches(priorOrder, expectedOrder))) {
         throw new Error('Prior place receipt has no exact visible limit-order identity to cancel.');
       }
       const identity = trustedExternalMutationIdentity(input, page, {
@@ -413,14 +510,19 @@ export async function closeOrders(input) {
         await page.navigateHash(`#/perps/market/${encodeURIComponent(symbol)}`);
         await page.waitForSelector(dataTestId('perps-market-detail-pair'), { timeoutMs });
         const exact = (await readVisibleOrderCards(page, symbol))
-          .filter((order) => order.id === priorOrder.id && (cleanupMode
+          .filter((order) => order.id === priorOrder.id && (accepted ? matchesAcceptedRemainder(order) : cleanupMode
             ? cleanupCandidateIdentityMatches(order, expectedOrder)
               && String(order.notionalBaseUnits) === String(cleanupCandidate.observedNotionalBaseUnits)
             : orderIdentityMatches(order, priorOrder)));
-        if (exact.length !== 1) throw new Error('Exact authorized visible order is unavailable for cancellation.');
-        await page.click(`[data-testid=${JSON.stringify(priorOrder.id)}]`);
-        await page.waitForSelector(dataTestId('perps-cancel-order-modal'), { timeoutMs });
+        if (exact.length !== 1) {
+          const filledOrder = await readAcceptedFilledOrder(input, page, priorPlace);
+          if (filledOrder) return alreadyFilledResult(filledOrder);
+          throw new Error('Exact authorized visible order is unavailable for cancellation.');
+        }
+        const filledOrder = await openCancelModal();
+        if (filledOrder) return alreadyFilledResult(filledOrder);
       }
+      let filledBeforeDispatch = existingReceipt?.record?.observation?.filledOrder ?? null;
       const mutation = await runGuardedExternalMutation({
         input,
         identity,
@@ -433,18 +535,31 @@ export async function closeOrders(input) {
         dispatch: async () => {
           let dispatchTarget;
           try {
-            await requireCurrentVisibleFundingBalance(input, page, timeoutMs, fundingBalance.observedBaseUnits);
+            const currentBalance = await requireCurrentVisibleFundingBalance(input, page, timeoutMs);
+            if (currentBalance.observedBaseUnits !== fundingBalance.observedBaseUnits) {
+              filledBeforeDispatch = await readAcceptedFilledOrder(input, page, priorPlace);
+              if (filledBeforeDispatch) return;
+              throw new Error('Current visible Perps balance changed after receipt publication.');
+            }
             assertTrustedExternalMutationTarget(input, page, identity);
             await page.navigateHash(`#/perps/market/${encodeURIComponent(symbol)}`);
             await page.waitForSelector(dataTestId('perps-market-detail-pair'), { timeoutMs });
             const exact = (await readVisibleOrderCards(page, symbol))
-              .filter((order) => order.id === priorOrder.id && (cleanupMode
+              .filter((order) => order.id === priorOrder.id && (accepted ? matchesAcceptedRemainder(order) : cleanupMode
                 ? cleanupCandidateIdentityMatches(order, expectedOrder)
                   && String(order.notionalBaseUnits) === String(cleanupCandidate.observedNotionalBaseUnits)
                 : orderIdentityMatches(order, priorOrder)));
-            if (exact.length !== 1) throw new Error('Exact authorized visible order changed before cancellation.');
-            await page.click(`[data-testid=${JSON.stringify(priorOrder.id)}]`);
-            await page.waitForSelector(dataTestId('perps-cancel-order-modal'), { timeoutMs });
+            if (exact.length !== 1) {
+              filledBeforeDispatch = await readAcceptedFilledOrder(input, page, priorPlace);
+              if (filledBeforeDispatch) return;
+              throw new Error('Exact authorized visible order changed before cancellation.');
+            }
+            filledBeforeDispatch = await openCancelModal();
+            if (filledBeforeDispatch) return;
+            await requirePerpsTradingContext(input, page);
+            assertTrustedExternalMutationTarget(input, page, identity);
+            filledBeforeDispatch = await readAcceptedFilledOrder(input, page, priorPlace);
+            if (filledBeforeDispatch) return;
             dispatchTarget = await page.evaluate(`(() => {
               const element = document.querySelector('[data-testid="perps-cancel-order-button"]');
               if (!element || element.disabled || element.getAttribute('aria-disabled') === 'true') {
@@ -454,9 +569,12 @@ export async function closeOrders(input) {
               const rect = element.getBoundingClientRect();
               return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
             })()`);
-            await requirePerpsTradingContext(input, page);
-            assertTrustedExternalMutationTarget(input, page, identity);
           } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.includes('Visible Perps cancel control is unavailable.')) {
+              filledBeforeDispatch = await readAcceptedFilledOrder(input, page, priorPlace);
+              if (filledBeforeDispatch) return;
+            }
             throw externalMutationNotDispatched(error instanceof Error ? error.message : String(error));
           }
           await page.session.call('Input.dispatchMouseEvent', {
@@ -469,6 +587,8 @@ export async function closeOrders(input) {
           });
         },
         observe: async () => {
+        if (filledBeforeDispatch) return { success: true, canceled: false,
+          filledOrder: filledBeforeDispatch, reason: 'already_filled', cleanup: null };
         const deadline = Date.now() + timeoutMs;
         let absentSince = null;
         while (Date.now() < deadline) {
@@ -476,12 +596,17 @@ export async function closeOrders(input) {
           if (!present) {
             absentSince ??= Date.now();
             if (Date.now() - absentSince >= 1_000) {
+              const filledOrder = await readAcceptedFilledOrder(input, page, priorPlace, true);
+              if (filledOrder) return { success: true, canceled: false,
+                filledOrder, reason: 'already_filled', cleanup: null };
               await page.navigateHash('#/perps-home');
-              const cleanup = await waitForStableGlobalPerpsHome(page, { timeoutMs, requireZero: true });
+              const cleanup = await waitForStableGlobalPerpsHome(page, { timeoutMs, requireZero: !accepted });
+              if (cleanup.orderCount !== 0) throw new Error('An order remains after exact accepted-order cancellation.');
               return {
                 success: true,
+                canceled: true,
                 canceledOrder: priorOrder,
-                cleanup: { positionCount: 0, orderCount: 0, balanceBaseUnits: cleanup.balanceBaseUnits },
+                cleanup: { positionCount: cleanup.positionCount, orderCount: 0, balanceBaseUnits: cleanup.balanceBaseUnits },
               };
             }
           } else absentSince = null;
@@ -492,14 +617,15 @@ export async function closeOrders(input) {
       });
       return {
         action: input.action,
-        canceled: true,
-        matchingCount: 1,
+        canceled: mutation.observation.canceled !== false,
+        matchingCount: mutation.observation.canceled === false ? 0 : 1,
         symbols: [symbol],
         order: priorOrder,
         receipt: mutation.receipt,
         resumed: mutation.resumed,
         cleanup: mutation.observation.cleanup,
-        proofPath: 'visible-product-controls',
+        ...(mutation.observation.filledOrder ? { reason: 'already_filled', filledOrder: mutation.observation.filledOrder } : {}),
+        proofPath: mutation.observation.canceled === false ? 'accepted-order-status' : 'visible-product-controls',
       };
     }
     throw new Error('Visible Perps cancellation did not return a terminal result.');
@@ -868,6 +994,8 @@ function cleanupCandidateIdentityMatches(order, expected) {
 }
 
 async function observePolicyViolationCleanupCandidate(page, expected, receipt, timeoutMs) {
+  const acceptedId = receipt?.acceptance?.venueOrderId;
+  if (!acceptedId) return null;
   const baselineIds = Array.isArray(receipt?.facts?.baselineOrderIds) ? receipt.facts.baselineOrderIds : null;
   if (!baselineIds || baselineIds.length !== 0) return null;
   const deadline = Date.now() + Math.min(timeoutMs, 10_000);
@@ -875,7 +1003,7 @@ async function observePolicyViolationCleanupCandidate(page, expected, receipt, t
   let stableSince = 0;
   while (Date.now() < deadline) {
     const candidates = (await readVisibleOrderCards(page, expected.market))
-      .filter((order) => cleanupCandidateIdentityMatches(order, expected));
+      .filter((order) => order.id === `order-card-${acceptedId}` && cleanupCandidateIdentityMatches(order, expected));
     if (candidates.length > 1) throw new Error('More than one visible over-cap order matches the cleanup identity.');
     if (candidates.length === 1) {
       const key = JSON.stringify(candidates[0]);
@@ -908,6 +1036,31 @@ async function observePolicyViolationCleanupCandidate(page, expected, receipt, t
 }
 
 async function observeExactVisibleOrderResult(page, expected, receipt, timeoutMs) {
+  if (expected.fromCurrentForm && !receipt?.acceptance?.venueOrderId) {
+    throw new Error('Visible submission has no accepted venue order identity; do not infer ownership from current state.');
+  }
+  if (expected.fromCurrentForm && expected.orderType === 'market' && receipt.acceptance.status !== 'filled') {
+    throw new Error('Market submission has no accepted fill; its outcome requires exact-order inspection.');
+  }
+  if (expected.orderType === 'limit' && receipt?.acceptance?.status === 'filled') {
+    const deadline = Date.now() + timeoutMs;
+    let observed = false;
+    while (Date.now() < deadline) {
+      const state = await page.readPositions();
+      const matching = state.positions?.filter((position) => symbolForItem(position) === expected.market);
+      const visible = await readVisiblePositionIdentity(page);
+      if (state.available && matching?.length === 1
+        && Math.abs(Number(matching[0].size ?? matching[0].szi)) === Number(receipt.acceptance.size)
+        && positionIdentityMatches(visible, { ...expected, matchMargin: false })
+        && Number.parseFloat(visible.size) === Number(receipt.acceptance.size)) {
+        observed = true;
+        break;
+      }
+      await sleep(250);
+    }
+    if (!observed) throw new Error(`Accepted filled order ${receipt.acceptance.venueOrderId} has not reached its position read model; cleanup remains unresolved.`);
+    throw new Error(`Accepted limit order ${receipt.acceptance.venueOrderId} filled unexpectedly; exact fill-owned position cleanup requires separate verification.`);
+  }
   if (!expected.fromCurrentForm) {
     await page.navigateHash(`#/perps/market/${encodeURIComponent(expected.market)}`);
   }
@@ -920,6 +1073,12 @@ async function observeExactVisibleOrderResult(page, expected, receipt, timeoutMs
     if (expected.orderType === 'market') {
       const position = await readVisiblePositionIdentity(page);
       let observedNotionalBaseUnits = null;
+      if (expected.fromCurrentForm) {
+        const filledNotional = Math.ceil(Number(receipt.acceptance.filledSize) * Number(receipt.acceptance.averagePrice) * 1_000_000);
+        if (!Number.isSafeInteger(filledNotional) || BigInt(filledNotional) > BigInt(expected.maximumNotionalBaseUnits)) {
+          throw new Error('Accepted market fill exceeds the trusted operation cap.');
+        }
+      }
       if (position) {
         const size = Number(String(position.size).replace(/,/gu, '').match(/[0-9]+(?:\.[0-9]+)?/u)?.[0]);
         const price = await readCurrentMarketPrice(page, expected.market);
@@ -942,7 +1101,9 @@ async function observeExactVisibleOrderResult(page, expected, receipt, timeoutMs
           observedNotionalBaseUnits,
         } : null,
       };
-      if (observedNotionalBaseUnits && positionIdentityMatches(position, expected)) {
+      const exactFilledSize = !expected.fromCurrentForm || (Number.parseFloat(String(position?.size ?? '').replace(/,/gu, '')) === Number(expected.size)
+        && Number(receipt.acceptance.filledSize) === Number(expected.size));
+      if (observedNotionalBaseUnits && positionIdentityMatches(position, expected) && exactFilledSize) {
         const key = JSON.stringify(position);
         if (key !== stableIdentity) {
           stableIdentity = key;
@@ -954,7 +1115,8 @@ async function observeExactVisibleOrderResult(page, expected, receipt, timeoutMs
             observedNotionalBaseUnits,
             maximumNotionalBaseUnits: expected.maximumNotionalBaseUnits,
             order: null,
-            orderId: null,
+            orderId: receipt?.acceptance?.venueOrderId ?? null,
+            ...(expected.fromCurrentForm ? { filledSize: receipt.acceptance.filledSize, averagePrice: receipt.acceptance.averagePrice } : {}),
           };
         }
       } else {
@@ -978,7 +1140,10 @@ async function observeExactVisibleOrderResult(page, expected, receipt, timeoutMs
         })),
       };
       const matching = orders
-        .filter((order) => !baselineIds.has(order.id) && orderIdentityMatches(order, expected));
+        .filter((order) => !baselineIds.has(order.id)
+          && (!receipt?.acceptance || order.id === `order-card-${receipt.acceptance.venueOrderId}`)
+          && (expected.size == null || Number(order.size) === Number(expected.size))
+          && orderIdentityMatches(order, expected));
       if (matching.length > 1) throw new Error('More than one new visible order matches the authorized identity.');
       if (matching.length === 1) {
         const key = JSON.stringify(matching[0]);
@@ -1204,6 +1369,188 @@ async function readPreparedOrderConfiguration(page) {
   })()`);
 }
 
+async function readPreparedOrderSizing(page, expected, sizeDecimals) {
+  if (!expected.reduceOnly && expected.leverage !== 1) {
+    throw new Error('Prepared visible order sizing currently requires 1x leverage.\nNext: mm-harness actions --action metamask.perps.place_order --adapter extension --json');
+  }
+  const visible = await page.evaluate(`(() => {
+    const element = document.querySelector(${JSON.stringify(expected.reduceOnly ? '[data-testid="perps-market-detail-price"]' : '[data-testid="perps-order-entry-price"]')});
+    const rect = element?.getBoundingClientRect();
+    const slippage = document.querySelector('[data-testid="perps-order-summary-slippage-value"]');
+    return { priceText: rect?.width && rect?.height ? element.textContent.trim() : null,
+      slippageText: slippage ? slippage.textContent.trim() : null };
+  })()`);
+  const { priceText } = visible;
+  const match = /^\$([0-9][0-9,]*)(?:\.([0-9]+))?$/u.exec(String(priceText));
+  if (!match || !Number.isInteger(sizeDecimals) || sizeDecimals < 0 || sizeDecimals > 8) {
+    throw new Error('Prepared limit sizing requires the visible current price and valid venue lot precision.');
+  }
+  const price = Number(`${match[1].replace(/,/gu, '')}.${match[2] ?? '0'}`);
+  const priceHalfTick = 0.5 * 10 ** -(match[2]?.length ?? 0);
+  const multiplier = 10 ** sizeDecimals;
+  if (!(price > priceHalfTick)) throw new Error('Visible order price must be positive at its displayed precision.');
+  let size;
+  if (expected.reduceOnly) {
+    const match = /^(?:0|[1-9][0-9]{0,19})(?:\.([0-9]{1,8}))?$/u.exec(String(expected.size));
+    if (!match || !(Number(expected.size) > 0) || (match[1] ?? '').replace(/0+$/u, '').length > sizeDecimals) {
+      throw new Error('Full close size does not match the venue lot precision.');
+    }
+    size = String(expected.size);
+  } else {
+    const usd = Number(expected.amountBaseUnits) / 1_000_000;
+    const lotsAt = (currentPrice) => Math.ceil(usd / currentPrice * multiplier);
+    const lowerLots = lotsAt(price + priceHalfTick);
+    const upperLots = lotsAt(price - priceHalfTick);
+    if (lowerLots !== upperLots || !Number.isSafeInteger(lowerLots) || lowerLots <= 0) {
+      throw new Error('Displayed price precision cannot determine one exact limit-order size.');
+    }
+    size = (lowerLots / multiplier).toFixed(sizeDecimals);
+  }
+  if (expected.orderType === 'market') {
+    const maxPercent = expected.reduceOnly || visible.slippageText === null ? 3
+      : Number(/\bMax:\s*([0-9]+(?:\.[0-9]+)?)%/u.exec(visible.slippageText)?.[1]);
+    const slippageBps = Math.round(maxPercent * 100);
+    if (!Number.isInteger(slippageBps) || maxPercent !== slippageBps / 100
+      || slippageBps < 0 || slippageBps >= 10_000 || sizeDecimals > 6) {
+      throw new Error('Prepared market order has no valid displayed maximum slippage.');
+    }
+    const factor = 1 + (expected.side === 'long' ? 1 : -1) * slippageBps / 10_000;
+    const formatPrice = (value) => {
+      if (Number.isInteger(value)) return value;
+      const rounded = Number(value.toFixed(6 - sizeDecimals));
+      const decimals = Math.max(0, 5 - String(Math.trunc(rounded)).replace(/^0+/u, '').length);
+      return Number(rounded.toFixed(decimals));
+    };
+    const minimumPriceBaseUnits = parseUsdBaseUnits(String(formatPrice((price - priceHalfTick) * factor)));
+    const maximumPriceBaseUnits = parseUsdBaseUnits(String(formatPrice((price + priceHalfTick) * factor)));
+    if (!minimumPriceBaseUnits || !maximumPriceBaseUnits || BigInt(minimumPriceBaseUnits) <= 0n) {
+      throw new Error('Prepared market price cap could not be resolved at venue precision.');
+    }
+    const maximumExposure = Math.ceil(Number(size) * Math.max(price + priceHalfTick, Number(maximumPriceBaseUnits) / 1_000_000) * 1_000_000);
+    if (!Number.isSafeInteger(maximumExposure) || BigInt(maximumExposure) > BigInt(expected.maximumNotionalBaseUnits)) {
+      throw new Error('Prepared market size and slippage cap exceed the trusted operation cap.');
+    }
+    return { priceText, sizeDecimals, size, slippageBps, minimumPriceBaseUnits, maximumPriceBaseUnits };
+  }
+  const notionalBaseUnits = `${Math.round(Number(size) * Number(expected.limitPriceBaseUnits))}`;
+  const maximumCurrentNotionalBaseUnits = Math.ceil(Number(size) * (price + priceHalfTick) * 1_000_000);
+  if (!Number.isSafeInteger(maximumCurrentNotionalBaseUnits)
+    || BigInt(maximumCurrentNotionalBaseUnits) > BigInt(expected.maximumNotionalBaseUnits)
+    || BigInt(notionalBaseUnits) > BigInt(expected.maximumNotionalBaseUnits)) {
+    throw new Error('Rounded prepared limit exposure exceeds the trusted operation cap.');
+  }
+  return { priceText, sizeDecimals, size, notionalBaseUnits };
+}
+
+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),
+  });
+  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);
+  if (!Number.isInteger(asset) || asset < 0) throw new Error('Hyperliquid market has no exact asset identity.');
+  const sizing = await readPreparedOrderSizing(page, expected, metadata.universe[asset].szDecimals);
+  const { session, targetId } = await page.connectServiceWorker();
+  let armed = false;
+  let requestId = null;
+  let requestFacts = null;
+  let acceptance = null;
+  let failure = null;
+  let pending = null;
+  const unsubscribe = [];
+  const close = () => {
+    armed = false;
+    for (const stop of unsubscribe) stop();
+    session.close();
+  };
+  try {
+    unsubscribe.push(session.on('Network.requestWillBeSent', (event) => {
+      if (!armed || event.request?.url !== `${origin}/exchange` || event.request.method !== 'POST') return;
+      try {
+        const body = event.request.postData;
+        if (typeof body !== 'string' || body.length > 131_072) throw new Error();
+        const action = JSON.parse(body).action;
+        if (action?.type !== 'order') return;
+        if (requestId !== null || !Array.isArray(action.orders) || action.orders.length !== 1) throw new Error();
+        const order = action.orders[0];
+        const wirePrice = parseUsdBaseUnits(order.p);
+        const priceMatches = expected.orderType === 'limit'
+          ? wirePrice === expected.limitPriceBaseUnits
+          : wirePrice !== null && BigInt(wirePrice) >= BigInt(sizing.minimumPriceBaseUnits)
+            && BigInt(wirePrice) <= BigInt(sizing.maximumPriceBaseUnits);
+        if (order.a !== asset || order.b !== (expected.side === 'long') || order.r !== Boolean(expected.reduceOnly)
+          || order.t?.limit?.tif !== (expected.orderType === 'limit' ? 'Gtc' : 'FrontendMarket')
+          || !priceMatches
+          || !/^(?:0|[1-9][0-9]{0,19})(?:\.[0-9]{1,8})?$/u.test(String(order.s))
+          || Number(order.s) !== Number(sizing.size)) throw new Error();
+        requestId = String(event.requestId);
+        requestFacts = { asset, size: String(order.s), limitPriceBaseUnits: wirePrice };
+      } catch {
+        failure = new Error('Hyperliquid submission request is missing, ambiguous, or differs from the authorized form.');
+      }
+    }));
+    unsubscribe.push(session.on('Network.loadingFailed', (event) => {
+      if (event.requestId === requestId) failure = new Error('Hyperliquid submission response was not delivered.');
+    }));
+    unsubscribe.push(session.on('Network.loadingFinished', (event) => {
+      if (event.requestId !== requestId || pending) return;
+      pending = (async () => {
+        try {
+          const response = await session.call('Network.getResponseBody', { requestId }, { timeoutMs: 10_000 });
+          if (response.base64Encoded || typeof response.body !== 'string' || response.body.length > 32_768) throw new Error();
+          const result = JSON.parse(response.body);
+          const statuses = result.response?.data?.statuses;
+          if (result.status !== 'ok' || result.response?.type !== 'order' || !Array.isArray(statuses) || statuses.length !== 1) throw new Error();
+          const status = statuses[0];
+          const kind = status.resting ? 'resting' : status.filled ? 'filled' : null;
+          const order = kind && status[kind];
+          if (!kind || !Number.isSafeInteger(order.oid) || order.oid <= 0) throw new Error();
+          acceptance = {
+            venueOrderId: String(order.oid), status: kind,
+            requestId, serviceWorkerTargetId: targetId,
+            ...requestFacts,
+            ...(expected.orderType === 'market' && kind === 'filled'
+              ? { filledSize: String(order.totalSz), averagePrice: String(order.avgPx) } : {}),
+          };
+        } catch {
+          failure = new Error('Hyperliquid response has no unambiguous accepted venue order identity.');
+        }
+      })();
+    }));
+    await session.call('Network.enable', { maxPostDataSize: 131_072 }, { timeoutMs: 5_000 });
+    return {
+      sizing,
+      async checkSizing() {
+        const current = await readPreparedOrderSizing(page, expected, sizing.sizeDecimals);
+        if (Number(current.size) !== Number(sizing.size)) throw new Error('Prepared limit lot size changed before dispatch.');
+        if (expected.orderType === 'market' && (current.slippageBps !== sizing.slippageBps
+          || current.minimumPriceBaseUnits !== sizing.minimumPriceBaseUnits || current.maximumPriceBaseUnits !== sizing.maximumPriceBaseUnits)) {
+          throw new Error('Prepared market price or slippage changed before dispatch.');
+        }
+      },
+      arm() { armed = true; },
+      async accepted(timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (!failure && !acceptance && Date.now() < deadline) await sleep(50);
+        if (failure) throw failure;
+        if (!acceptance) throw new Error('Hyperliquid submission acceptance was not observed before timeout.');
+        return acceptance;
+      },
+      close,
+    };
+  } catch (error) {
+    close();
+    throw error;
+  }
+}
+
 export async function placeOrder(input) {
   requirePlaceOrderInputs(input);
   const symbol = marketSymbol(input);
@@ -1269,6 +1616,7 @@ export async function placeOrder(input) {
       ...(orderType === 'market' ? {
         maximumNotionalBaseUnits: placementBudget.maxBaseUnits,
       } : {}),
+      ...(fromCurrentForm && orderType === 'limit' ? { maximumNotionalBaseUnits: placementBudget.maxBaseUnits } : {}),
     };
     const hasBackgroundRequest = await page.evaluate(
       `typeof globalThis.stateHooks?.submitRequestToBackground === 'function'`,
@@ -1302,6 +1650,11 @@ export async function placeOrder(input) {
     }
     const existingReceipt = await readExternalMutationReceipt(input, identity);
     if (existingReceipt) {
+      const recordedSizing = orderType === 'market' ? existingReceipt.record?.facts?.marketSizing : existingReceipt.record?.facts?.limitSizing;
+      if (fromCurrentForm && recordedSizing) {
+        expectedVisibleIdentity.size = recordedSizing.size;
+        if (orderType === 'limit') expectedVisibleIdentity.notionalBaseUnits = recordedSizing.notionalBaseUnits;
+      }
       return withExternalMutationRecovery(existingReceipt, async () => {
         if (!fromCurrentForm) {
           await page.navigateHash(`#/perps/market/${encodeURIComponent(symbol)}`);
@@ -1378,6 +1731,7 @@ export async function placeOrder(input) {
           openOrderCount: mutation.observation.order ? 1 : null,
           configured: null,
           outcome: mutation.observation,
+          ...(fromCurrentForm && orderType === 'market' ? { venueOrderId: mutation.observation.orderId } : {}),
           proofPath: 'visible-product-controls',
         };
       });
@@ -1484,12 +1838,25 @@ export async function placeOrder(input) {
         || preparedConfiguration.direction !== side)) {
         throw new Error('Prepared Perps form does not match the requested market and direction.');
       }
-      const mutation = await runGuardedExternalMutation({
+      if (fromCurrentForm && orderType === 'market' && preparedConfiguration.autoCloseEnabled) {
+        throw new Error('Receipt-bound market submission requires protection disabled before proof.');
+      }
+      const submissionObserver = fromCurrentForm
+        ? await observeHyperliquidSubmission(page, { ...expectedVisibleIdentity, ...tradingContext })
+        : null;
+      if (submissionObserver) {
+        expectedVisibleIdentity.size = submissionObserver.sizing.size;
+        if (orderType === 'limit') expectedVisibleIdentity.notionalBaseUnits = submissionObserver.sizing.notionalBaseUnits;
+      }
+      let mutation;
+      try {
+        mutation = await runGuardedExternalMutation({
         input,
         identity,
         publicationFacts: {
           balanceBeforeBaseUnits, baselineOrderIds, fundingBalance, tradingContext,
           ...(preparedConfiguration ? { preparedConfiguration } : {}),
+          ...(submissionObserver ? { [orderType === 'market' ? 'marketSizing' : 'limitSizing']: submissionObserver.sizing } : {}),
         },
         dispatch: async () => {
           let dispatchTarget;
@@ -1527,9 +1894,11 @@ export async function placeOrder(input) {
             dispatchTarget = currentConfiguration.target;
             await requirePerpsTradingContext(input, page);
             assertTrustedExternalMutationTarget(input, page, identity);
+            await submissionObserver?.checkSizing();
           } catch (error) {
             throw externalMutationNotDispatched(error instanceof Error ? error.message : String(error));
           }
+          submissionObserver?.arm();
           await page.session.call('Input.dispatchMouseEvent', {
             type: 'mousePressed', x: dispatchTarget.x, y: dispatchTarget.y,
             button: 'left', buttons: 1, clickCount: 1,
@@ -1538,6 +1907,9 @@ export async function placeOrder(input) {
             type: 'mouseReleased', x: dispatchTarget.x, y: dispatchTarget.y,
             button: 'left', buttons: 0, clickCount: 1,
           });
+          return submissionObserver
+            ? submissionObserver.accepted(Number(input.node?.timeout_ms ?? 45000))
+            : undefined;
         },
         observe: async ({ receipt }) => observeExactVisibleOrderResult(
           page,
@@ -1545,7 +1917,10 @@ export async function placeOrder(input) {
           receipt,
           Number(input.node?.timeout_ms ?? 45000),
         ),
-      });
+        });
+      } finally {
+        submissionObserver?.close();
+      }
       let openOrderCount = null;
       if (orderType === 'limit') {
         openOrderCount = mutation.observation.order ? 1 : null;
@@ -1570,6 +1945,7 @@ export async function placeOrder(input) {
         openOrderCount,
         configured,
         outcome: mutation.observation,
+        ...(fromCurrentForm && orderType === 'market' ? { venueOrderId: mutation.observation.orderId } : {}),
         balanceBeforeBaseUnits,
         proofPath: 'visible-product-controls',
       };

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

@@ -1,3 +1,4 @@
+// Place a Perps order and return visible-control evidence or assert the resulting order or position state.
 import { runAdapter } from '../platform/cdp.mjs';
 import { assertOrders, assertPositions, placeOrder } from './perps.mjs';
 runAdapter(async (input) => {

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

@@ -1,3 +1,4 @@
+// Fetch MetaMask geolocation and report it alongside the product's current Perps eligibility state.
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 
 runAdapter(async (input) => {

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

@@ -1,3 +1,5 @@
+// Read the displayed Perps deposit or withdrawal confirmation and check requested UI expectations.
+// Report preview fields, submit availability, and layout without submitting funds.
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 
 function expectedList(value, name) {

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

@@ -1,3 +1,4 @@
+// Read live Perps orders with optional selection and network checks, returning redacted order fields.
 import { runAdapter } from '../platform/cdp.mjs';
 import { readOrders } from './perps.mjs';
 

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

@@ -1,3 +1,4 @@
+// Read runtime Perps positions with optional selection and network checks, returning redacted position fields.
 import { runAdapter } from '../platform/cdp.mjs';
 import { readPositions } from './perps.mjs';
 runAdapter(readPositions);