@deeeed/metamask-harness 0.49.0 → 0.50.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.50.0 - 2026-09-08
+
+- Bind Mobile order assertions and cleanup to accepted receipts, exact TP/SL values and complete snapshots. iOS passed one limit cancellation and one protected-market close; protected limits, full recipes, CUF and Android remain unvalidated.
+- Fix Mobile stop helper lookup and detached-target discovery for an explicitly selected device.
+- Add Mobile amount/leverage input with exact mounted-form and native readback against the unchanged unsigned confirmation. Changed and already-satisfied $10.25/1x input passed on iOS.
+
+## 0.49.1 - 2026-09-08
+
+- fix(funding): bind balance evidence to the wallet runtime (#234).
+
 ## 0.49.0 - 2026-09-07
 
 - Simplify Mobile setup and sizing; correct nested-route verification, lifecycle portability, wallet selection, input clearing and token-sort restoration.

package/adapters/mobile/bridge-runtime/lib/cdp-broker.cjs

@@ -431,7 +431,12 @@ function createCdpBroker({
       readyOnly: true,
     });
     if (existing.length > 0) return Promise.resolve(existing);
-    requestDiscovery?.('');
+    const retained = targetList({ nameIncludes: params.nameIncludes });
+    requestDiscovery?.(
+      String(params.nameIncludes || '').trim() && retained.length === 1
+        ? retained[0].deviceId
+        : '',
+    );
     return new Promise((resolve, reject) => {
       const waiter = {
         nameIncludes: String(params.nameIncludes || ''),

package/adapters/mobile/stop-metro.sh

@@ -23,9 +23,9 @@ done
 
 TARGET="$(cd "$TARGET" && pwd -P)"
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MOBILE_STOP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
-. "$SCRIPT_DIR/../shared/harness-path.sh"
+. "$MOBILE_STOP_DIR/../shared/harness-path.sh"
 if ! command -v recipe_runtime_dir >/dev/null 2>&1; then
   echo "stop-metro: shared lib adapters/shared/harness-path.sh not found; reinstall the runner." >&2
   exit 1
@@ -35,7 +35,7 @@ fi
 # pool/formula fallbacks) so we stop THIS slot's Metro, not the 8081 default.
 if [ -z "$PORT" ]; then
   # shellcheck disable=SC1091
-  . "$SCRIPT_DIR/../shared/resolve-slot-ports.sh"
+  . "$MOBILE_STOP_DIR/../shared/resolve-slot-ports.sh"
   resolved_port="$(resolve_mobile_runtime_ports "$TARGET" 2>/dev/null | sed -n 's/^WATCHER_PORT=//p' | head -1 || true)"
   PORT="${resolved_port:-8081}"
 fi
@@ -45,7 +45,7 @@ PID_FILE="$LOG_DIR/metro.pid"
 TMUX_FILE="$LOG_DIR/metro.tmux"
 
 # shellcheck disable=SC1091
-. "$SCRIPT_DIR/lib/metro-listener.sh"
+. "$MOBILE_STOP_DIR/lib/metro-listener.sh"
 
 pids="$(metro_listener_pids 2>/dev/null || true)"
 if [ -n "$pids" ]; then
@@ -88,8 +88,8 @@ pkill -f "console-forwarder.cjs --port $PORT --out $TARGET/" 2>/dev/null
 # Reap a detached bundler for this exact port when its listener disappeared
 # before the normal stop path. Other ports in the same checkout are separate
 # runtime generations and must remain untouched.
-if [ -f "$SCRIPT_DIR/../shared/reap-checkout-metros.sh" ]; then
-  . "$SCRIPT_DIR/../shared/reap-checkout-metros.sh"
+if [ -f "$MOBILE_STOP_DIR/../shared/reap-checkout-metros.sh" ]; then
+  . "$MOBILE_STOP_DIR/../shared/reap-checkout-metros.sh"
   reap_checkout_metros_on_port "$TARGET" "$PORT" || true
 fi
 

package/library/actions/mobile/perps/assert_orders.mjs

@@ -1,6 +1,7 @@
 // Assert that selected Perps orders are open or absent using the Mobile controller.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertOrders } from './perps.mjs';
+import { useOrderReceipt } from './order-receipt.mjs';
 
 function expectedOpen(input) {
   if (input.node?.state == null) throw new Error('metamask.perps.assert_orders requires state=open or state=none.');
@@ -10,4 +11,6 @@ function expectedOpen(input) {
   throw new Error(`metamask.perps.assert_orders received unsupported state: ${state}`);
 }
 
-runAdapter((input) => assertOrders(input, expectedOpen(input)));
+runAdapter((input) => Object.hasOwn(input.node ?? {}, 'confirmation')
+  ? useOrderReceipt(input, 'orders')
+  : assertOrders(input, expectedOpen(input)));

package/library/actions/mobile/perps/assert_positions.mjs

@@ -1,6 +1,7 @@
 // Assert that selected Perps positions are open or absent using the Mobile controller.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertPositions } from './perps.mjs';
+import { useOrderReceipt } from './order-receipt.mjs';
 
 function expectedOpen(input) {
   if (input.node?.state == null) throw new Error('metamask.perps.assert_positions requires state=open or state=none.');
@@ -10,4 +11,6 @@ function expectedOpen(input) {
   throw new Error(`metamask.perps.assert_positions received unsupported state: ${state}`);
 }
 
-runAdapter((input) => assertPositions(input, expectedOpen(input)));
+runAdapter((input) => Object.hasOwn(input.node ?? {}, 'confirmation')
+  ? useOrderReceipt(input, 'positions')
+  : assertPositions(input, expectedOpen(input)));

package/library/actions/mobile/perps/close_orders.mjs

@@ -1,8 +1,10 @@
 // Cancel selected Perps orders through the Mobile controller and assert their absence.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertOrders, closeOrders } from './perps.mjs';
+import { useOrderReceipt } from './order-receipt.mjs';
 
 runAdapter(async (input) => {
+  if (Object.hasOwn(input.node ?? {}, 'confirmation')) return useOrderReceipt(input, 'cancel');
   const close = await closeOrders(input);
   const assertion = await assertOrders(input, false);
   return { ...assertion, close };

package/library/actions/mobile/perps/close_positions.mjs

@@ -1,8 +1,10 @@
 // Close selected Perps positions through the Mobile controller and assert their absence.
 import { runAdapter } from '../platform/bridge.mjs';
 import { assertPositions, closePositions } from './perps.mjs';
+import { useOrderReceipt } from './order-receipt.mjs';
 
 runAdapter(async (input) => {
+  if (Object.hasOwn(input.node ?? {}, 'confirmation')) return useOrderReceipt(input, 'close');
   const close = await closePositions(input);
   const assertion = await assertPositions(input, false);
   return { ...assertion, close };

package/library/actions/mobile/perps/configure_order.mjs

@@ -0,0 +1,90 @@
+// Set a visible leverage preset and USD notional, with independent native readback.
+// Requires an already-open instrumented order form; never submits or creates an order.
+import { bridgeCommand, runAdapter } from '../platform/bridge.mjs';
+import { observeNativeUi } from '../platform/observe-ui.mjs';
+import { readOrderInputState } from './order-input-state.mjs';
+
+async function configureOrder(input) {
+  const amount = String(input.node?.amount ?? '');
+  const leverage = Number(input.node?.leverage ?? 1);
+  if (![1, 2, 3, 5, 10, 20, 40].includes(leverage)) {
+    throw new Error('Perps leverage must use a supported visible preset.');
+  }
+  if (!/^(?:0|[1-9][0-9]{0,8})(?:\.[0-9]{1,2})?$/u.test(amount)
+    || amount.replace('.', '').length > 9 || Number(amount) <= 0) {
+    throw new Error('Perps amount requires positive USD notional with at most nine digits and two decimals.');
+  }
+  const timeout = Number(input.node?.timeout_ms ?? 30000);
+  if (!Number.isFinite(timeout) || timeout <= 0) throw new Error('Perps amount timeout must be positive.');
+  const deadline = Date.now() + timeout;
+  input = { ...input, node: { ...input.node, _action_deadline_epoch_ms: deadline } };
+  const initial = await readOrderInputState(input);
+  const observe = async () => {
+    if (Date.now() >= deadline) throw new Error('Perps amount input exceeded its deadline.');
+    const result = await observeNativeUi({ refs: ['ui.visible'], node: input.node }, input.context);
+    const visible = result.observations?.['ui.visible'];
+    if (!visible || visible.truncated) throw new Error(`Complete native Perps input observation is unavailable: ${result.warnings?.map((warning) => warning.message).join('; ') || 'truncated hierarchy'}.\nNext: mm-harness call ui.screenshot --adapter mobile`);
+    return visible.items ?? [];
+  };
+  const press = async (testId, long = false) => {
+    const result = await bridgeCommand(input, [long ? 'long-press-test-id' : 'press-test-id', testId]);
+    if (result?.ok !== true) throw new Error(`Perps input press failed: ${testId}.`);
+  };
+  const pressText = async (label) => {
+    const result = await bridgeCommand(input, ['press-text', label]);
+    if (result?.ok !== true) throw new Error(`Perps input press failed: ${label}.`);
+  };
+  const waitAmount = async (expected, keypadClosed = false) => {
+    let lastLabel = '';
+    while (Date.now() < deadline) {
+      const items = await observe();
+      const labels = items.filter((item) => item.test_id === 'perps-amount-display-amount');
+      const values = labels.length ? labels : items.filter((item) => item.test_id === 'perps-amount-display-touchable');
+      const label = values.length === 1 ? String(values[0].label ?? '').trim() : '';
+      lastLabel = label;
+      const match = /^\$((?:[0-9]{1,3}(?:,[0-9]{3})+|[0-9]+)(?:\.[0-9]{0,2})?)(?:,\s|$)/u.exec(label);
+      if (match && Math.round(Number(match[1].replaceAll(',', '')) * 100) === Math.round(expected * 100)
+        && (!keypadClosed || (!items.some((item) => ['perps-order-view-keypad', 'perps-order-view-keypad-done'].includes(item.test_id))
+          && items.some(leverageMatches)))) {
+        return label;
+      }
+      await new Promise((resolve) => setTimeout(resolve, Math.min(100, Math.max(0, deadline - Date.now()))));
+    }
+    throw new Error(`Visible Perps USD amount did not settle at ${expected}; last display was ${JSON.stringify(lastLabel)}.`);
+  };
+
+  const leverageMatches = (item) => {
+    if (item.test_id !== 'perps-order-view-leverage-row') return false;
+    const value = /(?:^|\s)([1-9][0-9]*)x(?:\s|$)/u.exec(String(item.label ?? '').trim());
+    return value !== null && Number(value[1]) === leverage;
+  };
+  const originalItems = await observe();
+  if (Number(initial.form.amount) === Number(amount) && initial.form.leverage === leverage
+    && !originalItems.some((item) => item.test_id === 'perps-order-view-keypad-done')) {
+    const observedAmount = await waitAmount(Number(amount), true);
+    const final = await readOrderInputState(input, initial.identity);
+    if (Number(final.form.amount) !== Number(amount) || final.form.leverage !== leverage) throw new Error('Committed Perps input changed during readback.');
+    return { action: input.action, amount, leverage, observedAmount, ...final, changed: false, submitted: false, proofPath: 'perps-input-native-and-mounted-form-readback' };
+  }
+  if (initial.form.leverage !== leverage) {
+    await press('perps-order-view-leverage-row');
+    if (leverage === 1) await pressText('1x');
+    else await press(`leverage-quick-select-${leverage}`);
+    await pressText(`Set ${leverage}x`);
+    if ((await readOrderInputState(input, initial.identity)).form.leverage !== leverage) throw new Error('Perps leverage selection did not commit.');
+  }
+  await press('perps-amount-display-touchable');
+  await press('keypad-delete-button', true);
+  if (Number((await readOrderInputState(input, initial.identity)).form.amount) !== 0) throw new Error('Perps keypad reset did not clear the amount.');
+  for (const digit of amount) {
+    await press(digit === '.' ? 'keypad-key-dot' : `keypad-key-${digit}`);
+  }
+  if (Number((await readOrderInputState(input, initial.identity)).form.amount) !== Number(amount)) throw new Error('Perps keypad input did not match the entered amount.');
+  await press('perps-order-view-keypad-done');
+  const observedAmount = await waitAmount(Number(amount), true);
+  const final = await readOrderInputState(input, initial.identity);
+  if (Number(final.form.amount) !== Number(amount) || final.form.leverage !== leverage) throw new Error('Committed Perps amount or leverage differs after Done.');
+  return { action: input.action, amount, leverage, observedAmount, ...final, changed: true, submitted: false, proofPath: 'perps-input-native-and-mounted-form-readback' };
+}
+
+runAdapter(configureOrder);

package/library/actions/mobile/perps/order-input-state.mjs

@@ -0,0 +1,48 @@
+// Read the mounted confirmation form and its unchanged unsigned funding request.
+import { bridgeCommand } from '../platform/bridge.mjs';
+
+export async function readOrderInputState(input, expectedIdentity) {
+  const state = await bridgeCommand(input, ['eval', `(() => {
+    const forms = [];
+    const hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    function walk(fiber) {
+      if (!fiber) return;
+      const value = fiber.memoizedProps?.value;
+      if (value?.orderForm && typeof value.setAmount === 'function') forms.push(value.orderForm);
+      walk(fiber.child);
+      walk(fiber.sibling);
+    }
+    for (const id of hook?.renderers?.keys() ?? []) {
+      for (const root of hook.getFiberRoots(id) ?? []) walk(root.current);
+    }
+    const approvals = Object.values(Engine.context.ApprovalController.state.pendingApprovals);
+    const approval = approvals[0];
+    const transaction = Engine.context.TransactionController.state.transactions.find(t => t.id === approval?.id);
+    const route = __AGENTIC__.getRoute();
+    const account = Engine.context.AccountsController.getSelectedAccount();
+    const perps = Engine.context.PerpsController.state;
+    if (forms.length !== 1 || approvals.length !== 1 || approval?.type !== 'transaction'
+      || transaction?.type !== 'perpsDepositAndOrder' || transaction.status !== 'unapproved' || transaction.hash
+      || route.name !== 'RedesignedConfirmations' || route.params?.asset !== forms[0].asset
+      || route.params?.direction !== forms[0].direction || account.address.toLowerCase() !== transaction.txParams.from.toLowerCase()) {
+      throw new Error('Perps input requires one selected unsigned confirmation and one matching mounted form.');
+    }
+    return {
+      identity: { approvalId: approval.id, transactionTime: transaction.time, routeKey: route.key,
+        account: account.address, chainId: transaction.chainId, provider: perps.activeProvider,
+        isTestnet: perps.isTestnet, asset: forms[0].asset, direction: forms[0].direction },
+      form: { amount: forms[0].amount, leverage: forms[0].leverage, orderType: forms[0].type,
+        limitPrice: forms[0].limitPrice ?? null,
+        takeProfitPrice: forms[0].takeProfitPrice ?? null, stopLossPrice: forms[0].stopLossPrice ?? null }
+    };
+  })()`]);
+  if (!state?.identity || ['approvalId', 'account', 'chainId', 'provider', 'routeKey', 'asset', 'direction']
+    .some((key) => typeof state.identity[key] !== 'string' || !state.identity[key])
+    || !Number.isFinite(state.identity.transactionTime) || typeof state.identity.isTestnet !== 'boolean') {
+    throw new Error('Perps input confirmation identity is incomplete.');
+  }
+  if (expectedIdentity && JSON.stringify(state.identity) !== JSON.stringify(expectedIdentity)) {
+    throw new Error('Perps input confirmation identity changed.');
+  }
+  return state;
+}

package/library/actions/mobile/perps/order-receipt.mjs

@@ -0,0 +1,241 @@
+// Bind live order results and cleanup to the exact UI approval, request and accepted fills.
+import { bridgeCommand } from '../platform/bridge.mjs';
+
+function confirmationFor(input) {
+  const confirmation = input.node?.confirmation;
+  const identity = confirmation?.identity;
+  if (!identity || ['approvalId', 'account', 'provider', 'chainId', 'routeKey', 'asset', 'direction']
+    .some((field) => typeof identity[field] !== 'string' || !identity[field])
+    || !Number.isSafeInteger(identity.transactionTime) || identity.isTestnet !== true
+    || identity.provider !== 'hyperliquid' || confirmation.form?.leverage !== 1
+    || !(Number(confirmation.form?.amount) > 0 && Number(confirmation.form.amount) <= 20)) {
+    throw new Error('Mobile receipt requires a frozen Hyperliquid testnet confirmation at 1x and at most $20.');
+  }
+  return confirmation;
+}
+
+function receiptExpression(confirmation, allowMissing = false) {
+  return `
+    const expected = ${JSON.stringify(confirmation)};
+    const controller = Engine.context.PerpsController;
+    function assertIdentity() {
+      const state = controller.state;
+      const account = Engine.context.AccountsController.getSelectedAccount();
+      if (account.address.toLowerCase() !== expected.identity.account.toLowerCase()
+        || state.activeProvider !== expected.identity.provider || state.isTestnet !== true) {
+        throw new Error('Mobile receipt account, provider or network changed.');
+      }
+    }
+    assertIdentity();
+    if (typeof __AGENTIC__.readPerpsOrderReceipts !== 'function') throw new Error('Mobile UI receipt observer is unavailable.');
+    const receipts = __AGENTIC__.readPerpsOrderReceipts(expected.identity.approvalId);
+    if (${allowMissing} && Array.isArray(receipts) && receipts.length === 0) return null;
+    if (!Array.isArray(receipts) || receipts.length !== 1) throw new Error('Exactly one UI submission receipt is required.');
+    const receipt = receipts[0];
+    for (const key of ['approvalId', 'transactionTime', 'account', 'provider', 'isTestnet', 'chainId', 'routeKey']) {
+      if (receipt.identity[key] !== expected.identity[key]) throw new Error('UI receipt identity differs from the frozen confirmation.');
+    }
+    for (const key of ['asset', 'direction']) if (receipt.request[key] !== expected.identity[key]) throw new Error('UI receipt market or direction differs.');
+    for (const key of ['amount', 'leverage', 'orderType', 'limitPrice', 'takeProfitPrice', 'stopLossPrice']) {
+      if ((receipt.request[key] ?? null) !== (expected.form[key] ?? null)) throw new Error('UI receipt request differs from committed ' + key + '.');
+    }
+    const ids = [...new Set([receipt.result?.orderId, ...(receipt.result?.childOrderIds ?? [])].filter(id => typeof id === 'string' && id))];
+  `;
+}
+
+export async function readOrderReceipt(input) {
+  const confirmation = confirmationFor(input);
+  const deadline = Date.now() + Number(input.node.timeout_ms ?? 30000);
+  input = { ...input, node: { ...input.node, _action_deadline_epoch_ms: deadline } };
+  for (;;) {
+    const receipt = await bridgeCommand(input, ['eval', `(() => { ${receiptExpression(confirmation, true)} return receipt; })()`]);
+    if (receipt?.status === 'settled') {
+      const protectionCount = ['takeProfitPrice', 'stopLossPrice'].filter((key) => receipt.request[key] != null).length;
+      if (receipt.result?.success === true && protectionCount) {
+        if (receipt.request.orderType !== 'market') throw new Error('Protected limit receipts remain unsupported.');
+        if (!receipt.protectionResult) {
+          if (Date.now() >= deadline) throw new Error('Mobile protection result is unknown; do not submit again.');
+          await new Promise((resolve) => setTimeout(resolve, 250));
+          continue;
+        }
+        const protectionIds = receipt.protectionResult.childOrderIds;
+        if (receipt.protectionResult.success !== true || !Array.isArray(protectionIds)
+          || protectionIds.length !== protectionCount || new Set(protectionIds).size !== protectionCount
+          || protectionIds.some((id) => typeof id !== 'string' || !/^[1-9][0-9]*$/u.test(id)
+            || id === receipt.result.orderId || receipt.result.childOrderIds?.includes(id))) {
+          throw new Error(`Mobile protection result lacks complete accepted IDs: ${JSON.stringify(receipt.protectionResult)}.`);
+        }
+      }
+      return { action: input.action, receipt };
+    }
+    if (Date.now() >= deadline) throw new Error('Mobile UI submission result is unknown; do not submit again.');
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+}
+
+export async function useOrderReceipt(input, operation) {
+  const confirmation = confirmationFor(input);
+  const deadline = Date.now() + Number(input.node.timeout_ms ?? 30000);
+  input = { ...input, node: { ...input.node, _action_deadline_epoch_ms: deadline } };
+  if ((input.node.market && input.node.market !== confirmation.identity.asset)
+    || (input.node.side && input.node.side !== confirmation.identity.direction)
+    || (['positions', 'orders'].includes(operation) && input.node.state !== 'open')) {
+    throw new Error('Receipt assertion requires the same market/direction and state=open.');
+  }
+  const mutation = operation === 'cancel' || operation === 'close';
+  const result = await bridgeCommand(input, ['eval-async', `(() => {
+    ${receiptExpression(confirmation)}
+    if (receipt.status !== 'settled' || receipt.result?.success !== true || !ids.length) throw new Error('Accepted UI receipt IDs are required before state assertion or cleanup.');
+    if (receipt.result.providerId && receipt.result.providerId !== expected.identity.provider) throw new Error('Accepted provider differs from UI receipt identity.');
+    if (!['market', 'limit'].includes(receipt.request.orderType)) throw new Error('Receipt cleanup supports ordinary market and limit orders only.');
+    const market = receipt.request.asset;
+    const protectionKeys = ['takeProfitPrice', 'stopLossPrice'].filter(key => receipt.request[key] != null);
+    const protectionIds = protectionKeys.length ? receipt.protectionResult?.childOrderIds : [];
+    if (protectionKeys.length && (receipt.request.orderType !== 'market' || receipt.protectionResult?.success !== true
+      || !Array.isArray(protectionIds) || protectionIds.length !== protectionKeys.length
+      || new Set(protectionIds).size !== protectionKeys.length
+      || protectionIds.some(id => typeof id !== 'string' || !/^[1-9][0-9]*$/.test(id) || ids.includes(id)))) {
+      throw new Error('Protected cleanup requires complete distinct accepted market protection IDs.');
+    }
+    const ownedIds = ids.concat(protectionIds);
+    const sign = receipt.request.direction === 'long' ? 1n : -1n;
+    function decimal(value) {
+      const match = /^(-?)(0|[1-9][0-9]{0,19})(?:\\.([0-9]{1,8}))?$/.exec(String(value));
+      if (!match) throw new Error('Receipt fill decimal is invalid.');
+      return BigInt(match[1] + match[2] + (match[3] ?? '').padEnd(8, '0'));
+    }
+    function readSnapshot() {
+      assertIdentity();
+      if (typeof controller.getUserDataSnapshot !== 'function') throw new Error('Complete user-data snapshots are unavailable.');
+      return controller.getUserDataSnapshot().then(snapshot => {
+        assertIdentity();
+        const identity = snapshot?.identity;
+        if (!Array.isArray(snapshot?.positions) || !Array.isArray(snapshot?.orders)
+          || typeof identity?.address !== 'string' || identity.address.toLowerCase() !== expected.identity.account.toLowerCase()
+          || identity.provider !== expected.identity.provider || identity.network !== 'testnet') {
+          throw new Error('Receipt snapshot is incomplete or belongs to another identity.');
+        }
+        const orders = snapshot.orders.filter(order => order.symbol === market);
+        if (orders.some(order => !ownedIds.includes(String(order.orderId)))
+          || new Set(orders.map(order => String(order.orderId))).size !== orders.length) {
+          throw new Error('Extra or unowned market orders prevent receipt assertion or cleanup.');
+        }
+        return {orders, positions: snapshot.positions.filter(position => position.symbol === market)};
+      });
+    }
+    function verifyProtection(position, orders, present) {
+      const matchedIds = [];
+      for (const [priceKey, ordersKey] of [['takeProfitPrice','takeProfitOrders'],['stopLossPrice','stopLossOrders']]) {
+        const wanted = present ? receipt.request[priceKey] : null;
+        const triggers = position[ordersKey];
+        const count = position[priceKey === 'takeProfitPrice' ? 'takeProfitCount' : 'stopLossCount'];
+        if (!Array.isArray(triggers)) throw new Error('Exact position protection arrays are unavailable.');
+        if (wanted == null) {
+          if (triggers.length || count !== 0 || position[priceKey] != null) throw new Error('Unexpected position protection remains.');
+          continue;
+        }
+        const direction = priceKey === 'takeProfitPrice' ? 'take_profit' : 'stop';
+        const type = direction === 'take_profit' ? 'take_profit_limit' : 'stop_market';
+        if (triggers.length !== 1 || count !== 1) throw new Error('Position protection count differs from the frozen UI request.');
+        const trigger = triggers[0];
+        const order = orders.find(candidate => String(candidate.orderId) === trigger.orderId);
+        if (!protectionIds.includes(trigger.orderId) || matchedIds.includes(trigger.orderId)
+          || trigger.direction !== direction || trigger.orderType !== type || decimal(trigger.triggerPrice) !== decimal(wanted)
+          || decimal(trigger.size) !== sign * decimal(position.size) || trigger.reduceOnly !== true || trigger.isPartial !== false
+          || !order || order.side !== (sign === 1n ? 'sell' : 'buy') || order.reduceOnly !== true
+          || order.isTrigger !== true || order.isPositionTpsl !== true || order.triggerOrderType !== type
+          || decimal(order.triggerPrice) !== decimal(wanted) || decimal(order.size) !== decimal(trigger.size)) {
+          throw new Error('Exact protection ID, price, size, side or type differs from the UI receipt.');
+        }
+        matchedIds.push(trigger.orderId);
+      }
+      if (present && matchedIds.length !== protectionIds.length) throw new Error('Accepted protection IDs are not all represented in the position.');
+    }
+    function verifyLineage(position) {
+      return controller.getOrderFills({aggregateByTime: false, startTime: receipt.identity.transactionTime, endTime: Date.now()}).then(fills => {
+        assertIdentity();
+        if (!Array.isArray(fills) || fills.length >= 2000) throw new Error('Receipt fill history is incomplete.');
+        const marketFills = fills.filter(fill => fill.symbol === market);
+        if (!marketFills.length || marketFills.some(fill => !ids.includes(String(fill.orderId)))) throw new Error('Another order changed the market or parent accepted fills are unavailable.');
+        marketFills.sort((a,b) => { const difference = sign * (decimal(a.startPosition) - decimal(b.startPosition)); return difference < 0n ? -1 : difference > 0n ? 1 : 0; });
+        let size = 0n;
+        for (const fill of marketFills) {
+          if (fill.side !== (sign === 1n ? 'buy' : 'sell') || decimal(fill.size) <= 0n || decimal(fill.startPosition) !== size) throw new Error('Parent accepted fills do not prove a position starting from zero.');
+          size += sign * decimal(fill.size);
+        }
+        if (size !== decimal(position.size) || position.leverage?.value !== receipt.request.leverage) throw new Error('Current position differs from exact parent fills or leverage.');
+        return marketFills;
+      });
+    }
+    function cancelOwned(orders, baseline) {
+      const results = [];
+      function waitForCancellation() {
+        return readSnapshot().then(after => {
+          if (baseline && (after.positions.length !== 1 || after.positions[0].size !== baseline.size
+            || after.positions[0].entryPrice !== baseline.entryPrice || after.positions[0].leverage?.value !== baseline.leverage.value)) {
+            throw new Error('Owned position changed during protective cancellation.');
+          }
+          if (!after.orders.length) {
+            if (baseline) verifyProtection(after.positions[0], after.orders, false);
+            return {after, results};
+          }
+          if (Date.now() >= ${deadline}) throw new Error('Accepted order cancellation is not independently confirmed.');
+          return new Promise(resolve => setTimeout(resolve, 250)).then(waitForCancellation);
+        });
+      }
+      return orders.reduce((previous, order) => previous.then(() => {
+        if (Date.now() >= ${deadline}) throw new Error('Receipt cleanup deadline elapsed before cancellation.');
+        assertIdentity();
+        return controller.cancelOrder({symbol: market, orderId: String(order.orderId)}).then(result => {
+          results.push({orderId: order.orderId, result});
+          if (result?.success !== true) throw new Error('Exact receipt cancellation failed: ' + JSON.stringify(results));
+        });
+      }), Promise.resolve()).then(waitForCancellation);
+    }
+    return readSnapshot().then(snapshot => {
+      const orders = snapshot.orders;
+      if (${JSON.stringify(operation)} === 'orders') {
+        if (!orders.length || orders.some(order => !ids.includes(String(order.orderId))
+          || order.side !== (sign === 1n ? 'buy' : 'sell'))) throw new Error('No matching exact accepted UI order remains open.');
+        return {receipt, orders};
+      }
+      if (${JSON.stringify(operation)} === 'cancel' && !protectionKeys.length) {
+        return cancelOwned(orders).then(({results}) => ({receipt, results, remainingOwnedOrders: 0}));
+      }
+      if (!snapshot.positions.length && ${JSON.stringify(operation)} === 'close' && !orders.length) return {receipt, closed: false, alreadyAbsent: true};
+      if (snapshot.positions.length !== 1) throw new Error('Receipt position is absent or ambiguous.');
+      const position = snapshot.positions[0];
+      if (protectionKeys.length && orders.some(order => !protectionIds.includes(String(order.orderId)))) throw new Error('Extra parent orders prevent protected position assertion or cleanup.');
+      return verifyLineage(position).then(fills => {
+        const protectionPresent = protectionIds.some(id => orders.some(order => String(order.orderId) === id));
+        verifyProtection(position, orders, ${JSON.stringify(operation)} === 'positions' || protectionPresent);
+        if (${JSON.stringify(operation)} === 'positions') return {receipt, position, fills};
+        if (orders.some(order => !protectionIds.includes(String(order.orderId)))) throw new Error('Parent order remainder prevents owned position cleanup.');
+        return cancelOwned(orders, position).then(({after, results}) => {
+          if (${JSON.stringify(operation)} === 'cancel') return {receipt, results, remainingOwnedOrders: 0};
+          const unchanged = after.positions[0];
+          return verifyLineage(unchanged).then(readSnapshot).then(beforeClose => {
+            if (beforeClose.positions.length !== 1 || beforeClose.orders.length
+              || beforeClose.positions[0].size !== unchanged.size || beforeClose.positions[0].entryPrice !== unchanged.entryPrice
+              || beforeClose.positions[0].leverage?.value !== unchanged.leverage.value) throw new Error('Owned position changed before close.');
+            verifyProtection(beforeClose.positions[0], beforeClose.orders, false);
+            if (Date.now() >= ${deadline}) throw new Error('Receipt cleanup deadline elapsed before close.');
+            assertIdentity();
+            return controller.closePosition({symbol: market, size: String(sign === 1n ? unchanged.size : String(unchanged.size).slice(1)), orderType: 'market', providerId: 'hyperliquid', position: unchanged}).then(closeResult => {
+              if (closeResult?.success !== true || !closeResult.orderId) throw new Error('Receipt-owned close has no accepted result: ' + JSON.stringify(closeResult));
+              function waitForClose() {
+                return readSnapshot().then(final => {
+                  if (!final.positions.length && !final.orders.length) return {receipt, results, closeResult, closed: true};
+                  if (Date.now() >= ${deadline}) throw new Error('Receipt-owned close is not independently confirmed.');
+                  return new Promise(resolve => setTimeout(resolve, 250)).then(waitForClose);
+                });
+              }
+              return waitForClose();
+            });
+          });
+        });
+      });
+    });
+  })()`]);
+  return { action: input.action, ...result, mutation };
+}

package/library/actions/mobile/perps/read_order_input.mjs

@@ -0,0 +1,33 @@
+// Freeze the visible unsigned order inputs and refuse a repeated or unobservable submission.
+import { bridgeCommand, runAdapter } from '../platform/bridge.mjs';
+import { readOrderInputState } from './order-input-state.mjs';
+import { observeNativeUi } from '../platform/observe-ui.mjs';
+
+runAdapter(async (input) => {
+  const confirmation = await readOrderInputState(input, input.node?.identity);
+  const { identity, form } = confirmation;
+  const observation = await observeNativeUi({ refs: ['ui.visible'], node: input.node }, input.context);
+  const visible = observation.observations?.['ui.visible'];
+  const payRows = visible?.items?.filter((item) => item.test_id === 'pay-with') ?? [];
+  if (!visible || visible.truncated || payRows.length !== 1 || payRows[0].label !== 'Pay with, Perps balance') {
+    throw new Error('Receipt proof requires the visible Perps balance payment source; funding is not permitted.');
+  }
+  if (identity.provider !== 'hyperliquid' || identity.isTestnet !== true
+    || form.leverage !== 1 || !(Number(form.amount) > 0 && Number(form.amount) <= 20)
+    || !['market', 'limit'].includes(form.orderType)) {
+    throw new Error('Mobile receipt proof requires Hyperliquid testnet, 1x and at most $20 on a market or limit order.');
+  }
+  if (Number(form.amount) !== Number(input.node.amount) || form.leverage !== Number(input.node.leverage)) {
+    throw new Error('Committed Mobile order inputs differ from the requested amount or leverage.');
+  }
+  const protection = input.node.protection ?? 'none';
+  for (const [field, required] of [['takeProfitPrice', ['take_profit', 'both'].includes(protection)], ['stopLossPrice', ['stop_loss', 'both'].includes(protection)]]) {
+    if (required ? !(Number(form[field]) > 0) : form[field] !== null) throw new Error(`Committed Mobile ${field} does not match requested protection.`);
+  }
+  const prior = await bridgeCommand(input, ['eval', `(() => {
+    if (typeof __AGENTIC__.readPerpsOrderReceipts !== 'function') throw new Error('Mobile UI receipt observer is unavailable.');
+    return __AGENTIC__.readPerpsOrderReceipts(${JSON.stringify(identity.approvalId)});
+  })()`]);
+  if (!Array.isArray(prior) || prior.length) throw new Error('This unsigned confirmation already has a submission attempt; do not submit it again.');
+  return { action: input.action, confirmation, submitted: false };
+});

package/library/actions/mobile/perps/read_order_receipt.mjs

@@ -0,0 +1,5 @@
+// Observe the actual result of one UI submission without dispatching an order.
+import { runAdapter } from '../platform/bridge.mjs';
+import { readOrderReceipt } from './order-receipt.mjs';
+
+runAdapter(readOrderReceipt);

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

@@ -2399,6 +2399,7 @@
       "schema": {
         "type": "object",
         "properties": {
+          "confirmation": { "type": "object", "description": "Frozen read_order_input output; requires exact live UI receipt identity." },
           "market": {
             "type": "string",
             "description": "Single market symbol, e.g. BTC or ETH. Alias: symbol."
@@ -2490,6 +2491,7 @@
       "schema": {
         "type": "object",
         "properties": {
+          "confirmation": { "type": "object", "description": "Frozen read_order_input output; requires exact live UI receipt identity." },
           "market": {
             "type": "string",
             "description": "Single market symbol, e.g. BTC or ETH. Alias: symbol."
@@ -2576,6 +2578,53 @@
       ],
       "execution_capabilities": ["app-mutation", "external-mutation"]
     },
+    "metamask.perps.read_order_input": {
+      "description": "Freeze committed unsigned Mobile inputs and require a receipt observer before UI submission.",
+      "examples": [{ "action": "metamask.perps.read_order_input", "amount": "10", "leverage": 1, "protection": "none", "intent": "Freeze the exact unsigned order before its UI submission", "next": "submit-order" }],
+      "schema": {
+        "type": "object", "required": ["amount", "leverage"], "additionalProperties": false,
+        "properties": {
+          "amount": { "type": ["string", "number"] },
+          "leverage": { "type": "number" },
+          "identity": { "type": "object" },
+          "protection": { "type": "string", "enum": ["none", "take_profit", "stop_loss", "both"], "default": "none" }
+        }
+      },
+      "execution_capabilities": []
+    },
+    "metamask.perps.read_order_receipt": {
+      "description": "Observe the actual Mobile UI submission result including failure and accepted IDs; never dispatch.",
+      "examples": [{ "action": "metamask.perps.read_order_receipt", "confirmation": "{{outputs.capture-input.confirmation}}", "intent": "Observe the result of the frozen UI submission", "next": "done" }],
+      "schema": {
+        "type": "object", "required": ["confirmation"], "additionalProperties": false,
+        "properties": {
+          "confirmation": { "type": "object" },
+          "timeout_ms": { "type": "number", "minimum": 1, "default": 30000 }
+        }
+      },
+      "execution_capabilities": []
+    },
+    "metamask.perps.configure_order": {
+      "description": "Set USD notional and visible leverage on an already-open instrumented Mobile confirmation; verify exact mounted values and native readback against its unchanged unsigned request, without submitting.",
+      "schema": {
+        "type": "object",
+        "required": ["amount"],
+        "properties": {
+          "amount": { "type": ["string", "number"] },
+          "leverage": { "type": "integer", "enum": [1, 2, 3, 5, 10, 20, 40], "default": 1 },
+          "timeout_ms": { "type": "number", "minimum": 1, "default": 30000 }
+        },
+        "additionalProperties": false
+      },
+      "examples": [{
+        "action": "metamask.perps.configure_order",
+        "amount": "10",
+        "leverage": 1,
+        "intent": "Prepare the requested USD notional without submitting",
+        "next": "done"
+      }],
+      "execution_capabilities": ["app-mutation"]
+    },
     "metamask.perps.place_order": {
       "description": "mobile Place a Perps order through a supported app/API path. Default to testnet; mainnet order placement requires an explicit user request.",
       "schema": {
@@ -2685,6 +2734,7 @@
       "schema": {
         "type": "object",
         "properties": {
+          "confirmation": { "type": "object", "description": "Frozen read_order_input output; requires exact live UI receipt identity." },
           "market": {
             "type": "string",
             "description": "Single market symbol, e.g. BTC or ETH. Alias: symbol."
@@ -2777,6 +2827,7 @@
       "schema": {
         "type": "object",
         "properties": {
+          "confirmation": { "type": "object", "description": "Frozen read_order_input output; requires exact live UI receipt identity." },
           "market": {
             "type": "string",
             "description": "Single market symbol, e.g. BTC or ETH. Alias: symbol."

package/package.json

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