@deeeed/metamask-harness 0.19.0 → 0.20.0

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

@@ -1,31 +1,249 @@
-import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import { pathToFileURL } from 'node:url';
 
-const PAGE_HASHES = {
-  home: '#/',
-  perps: '#/perps-home',
-};
+import {
+  dataTestId,
+  normalizeMarketSymbol,
+  runAdapter,
+  withExtensionPage,
+} from '../platform/cdp.mjs';
+
+const BACK_CONTROLS = [
+  'perps-order-entry-back-button',
+  'perps-market-detail-back-button',
+  'perps-activity-back-button',
+  'perps-withdraw-back-button',
+  'back-button',
+].map(dataTestId);
 
 function text(value) {
   return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
 
-function pageHash(node) {
+function pageIntent(node) {
   const page = text(node?.page);
   if (!page) return undefined;
-  if (PAGE_HASHES[page]) return { page, hash: PAGE_HASHES[page] };
+  if (page === 'home' || page === 'perps') return { page };
   if (page === 'perps-market') {
     const market = text(node.market) ?? text(node.symbol);
     if (!market) throw new Error('extension ui.navigate page=perps-market requires market or symbol.');
-    return { page, hash: `#/perps/market/${encodeURIComponent(market)}` };
+    return { page, market };
   }
-  throw new Error('extension ui.navigate supported page aliases: home, perps, perps-market.');
+  throw new Error('extension ui.navigate supported page intents: home, perps, perps-market.');
+}
+
+async function hasVisibleSelector(page, selector) {
+  return page.evaluate(`(() => {
+    const element = document.querySelector(${JSON.stringify(selector)});
+    if (!element) return false;
+    const style = getComputedStyle(element);
+    const rect = element.getBoundingClientRect();
+    return style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0;
+  })()`);
+}
+
+async function pauseForUi(page) {
+  await page.evaluate('new Promise((resolve) => setTimeout(resolve, 200))');
 }
 
-runAdapter((input) => withExtensionPage(input, async (page) => {
-  const alias = pageHash(input.node);
-  if (alias) {
-    const navigation = await page.navigateHash(alias.hash);
-    return { action: input.action, ...alias, navigation, proofPath: 'ui-navigation' };
+async function waitForFirstVisible(page, selectors, deadline) {
+  while (Date.now() < deadline) {
+    for (const selector of selectors) {
+      if (await hasVisibleSelector(page, selector)) return selector;
+    }
+    await pauseForUi(page);
+  }
+  return undefined;
+}
+
+async function currentHref(page) {
+  return page.evaluate('location.href');
+}
+
+async function activateSemanticControl(page, selector) {
+  return {
+    activation: 'trusted-pointer',
+    interaction: await page.click(selector),
+  };
+}
+
+export async function openHome(page, timeoutMs) {
+  const home = dataTestId('bottom-nav-home');
+  const selectedHome = `${home}[aria-current="page"]`;
+  const deadline = Date.now() + timeoutMs;
+  const steps = [];
+  let pendingActivation;
+
+  while (Date.now() < deadline) {
+    if (await hasVisibleSelector(page, selectedHome)) {
+      return { method: 'visible-ui', href: await currentHref(page), steps };
+    }
+    const href = await currentHref(page);
+    if (pendingActivation && pendingActivation.href !== href) {
+      pendingActivation = undefined;
+      await pauseForUi(page);
+      continue;
+    }
+    if (await hasVisibleSelector(page, home)) {
+      if (pendingActivation?.selector !== home) pendingActivation = undefined;
+      if (!pendingActivation) {
+        await activateSemanticControl(page, home);
+        steps.push(home);
+        pendingActivation = { selector: home, href };
+      }
+      await pauseForUi(page);
+      continue;
+    }
+    let backControl;
+    for (const selector of BACK_CONTROLS) {
+      if (await hasVisibleSelector(page, selector)) {
+        backControl = selector;
+        break;
+      }
+    }
+    if (backControl) {
+      if (pendingActivation?.selector !== backControl) pendingActivation = undefined;
+      if (!pendingActivation || pendingActivation.selector !== backControl) {
+        await activateSemanticControl(page, backControl);
+        steps.push(backControl);
+        pendingActivation = { selector: backControl, href };
+      }
+    }
+    await pauseForUi(page);
+  }
+
+  throw new Error(
+    `extension ui.navigate page=home could not resolve Home through visible controls; observed href ${JSON.stringify(await currentHref(page))}.`,
+  );
+}
+
+export async function openPerpsHome(page, timeoutMs) {
+  const bottomNav = dataTestId('bottom-nav-perps');
+  const legacyTab = dataTestId('account-overview__perps-tab');
+  const perpsHome = dataTestId('perps-home-page');
+  const steps = [];
+  const deadline = Date.now() + timeoutMs;
+  let pendingActivation;
+  let perpsActivation;
+
+  while (Date.now() < deadline) {
+    if (await hasVisibleSelector(page, perpsHome)) {
+      return {
+        ...(perpsActivation ? { navigation: perpsActivation, selector: bottomNav } : {}),
+        method: 'visible-ui',
+        href: await currentHref(page),
+        steps,
+      };
+    }
+    if (await hasVisibleSelector(page, bottomNav)) {
+      if (!perpsActivation) {
+        perpsActivation = await activateSemanticControl(page, bottomNav);
+        steps.push(bottomNav);
+      }
+      await pauseForUi(page);
+      continue;
+    }
+    if (await hasVisibleSelector(page, legacyTab)) {
+      const navigation = await activateSemanticControl(page, legacyTab);
+      await page.waitForSelector(dataTestId('perps-view'), {
+        timeoutMs: Math.max(1, deadline - Date.now()),
+      });
+      return {
+        navigation,
+        method: 'visible-ui',
+        href: await currentHref(page),
+        selector: legacyTab,
+        steps,
+      };
+    }
+
+    let backControl;
+    for (const selector of BACK_CONTROLS) {
+      if (await hasVisibleSelector(page, selector)) {
+        backControl = selector;
+        break;
+      }
+    }
+    if (backControl) {
+      const href = await currentHref(page);
+      if (pendingActivation && pendingActivation.href !== href) {
+        pendingActivation = undefined;
+      }
+      if (!pendingActivation || pendingActivation.selector !== backControl) {
+        await activateSemanticControl(page, backControl);
+        steps.push(backControl);
+        pendingActivation = { selector: backControl, href };
+      }
+    }
+    await pauseForUi(page);
+  }
+
+  const state = await page.evaluate(`({
+    href: location.href,
+    title: document.title,
+    visibleTestIds: [...document.querySelectorAll('[data-testid]')]
+      .filter((element) => {
+        const style = getComputedStyle(element);
+        const rect = element.getBoundingClientRect();
+        return style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0;
+      })
+      .map((element) => element.getAttribute('data-testid'))
+      .filter(Boolean)
+      .slice(0, 30),
+  })`);
+  throw new Error(
+    `extension ui.navigate page=perps could not resolve the Perps home through visible UI; observed ${JSON.stringify(state)}. Capture the current UI with mm-harness call ui.screenshot, then use a verified visible control or raw hash/path.`,
+  );
+}
+
+export async function openPerpsMarket(page, market, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  const home = await openPerpsHome(page, Math.max(1, deadline - Date.now()));
+  const normalizedMarket = normalizeMarketSymbol(market.trim());
+  const selectors = [
+    dataTestId(`perps-watchlist-${normalizedMarket}`),
+    dataTestId(`explore-markets-${normalizedMarket.replaceAll(':', '-')}`),
+  ];
+  const marketControl = await waitForFirstVisible(page, selectors, deadline);
+  if (!marketControl) {
+    const visibleMarketControls = await page.evaluate(`[
+      ...document.querySelectorAll('[data-testid^="perps-watchlist-"], [data-testid^="explore-markets-"]')
+    ].filter((element) => {
+      const style = getComputedStyle(element);
+      const rect = element.getBoundingClientRect();
+      return style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0;
+    }).map((element) => element.getAttribute('data-testid')).filter(Boolean)`);
+    throw new Error(
+      `extension ui.navigate page=perps-market could not find ${JSON.stringify(normalizedMarket)} in the current visible market controls ${JSON.stringify(visibleMarketControls)}.`,
+    );
+  }
+  const navigation = await activateSemanticControl(page, marketControl);
+  await page.waitForSelector(dataTestId('perps-market-detail-page'), {
+    timeoutMs: Math.max(1, deadline - Date.now()),
+  });
+  return {
+    navigation,
+    method: 'visible-ui',
+    href: await currentHref(page),
+    selector: marketControl,
+    steps: [...home.steps, marketControl],
+  };
+}
+
+export async function navigateExtensionUi(input) {
+  return withExtensionPage(input, async (page) => {
+  const intent = pageIntent(input.node);
+  if (intent) {
+    const timeoutMs = Number(input.node?.timeout_ms ?? 20000);
+    if (intent.page === 'home') {
+      const result = await openHome(page, timeoutMs);
+      return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };
+    }
+    if (intent.page === 'perps') {
+      const result = await openPerpsHome(page, timeoutMs);
+      return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };
+    }
+    const result = await openPerpsMarket(page, intent.market, timeoutMs);
+    return { action: input.action, ...intent, ...result, proofPath: 'ui-navigation' };
   }
 
   const url = input.node?.url;
@@ -40,5 +258,10 @@ runAdapter((input) => withExtensionPage(input, async (page) => {
     return { action: input.action, hash, navigation, proofPath: 'ui-navigation' };
   }
 
-  throw new Error('extension ui.navigate requires page, raw extension url, hash, or path.');
-}));
+    throw new Error('extension ui.navigate requires page, raw extension url, hash, or path.');
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runAdapter(navigateExtensionUi);
+}

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

@@ -24,7 +24,10 @@ function symbolForItem(item) {
 }
 
 function sideForItem(item) {
-  return String(item?.side ?? item?.direction ?? '').toLowerCase();
+  const side = String(item?.side ?? item?.direction ?? '').toLowerCase();
+  if (side === 'buy' || side === 'b') return 'long';
+  if (side === 'sell' || side === 'a' || side === 's') return 'short';
+  return side;
 }
 
 function configuredSymbols(input, items) {
@@ -67,6 +70,35 @@ function requirePlaceOrderInputs(input) {
   if (node.amount == null && node.notional == null) throw new Error(`${input.action} requires amount=<usd> or notional=<usd>.`);
 }
 
+function resolveOrderType(input) {
+  const value = String(input.node?.order_type ?? input.node?.orderType ?? 'market').toLowerCase();
+  if (value !== 'market' && value !== 'limit') {
+    throw new Error(`${input.action} received unsupported order_type: ${value}.`);
+  }
+  return value;
+}
+
+function resolveLimitPrice(input, isBuy, currentPrice) {
+  const explicit = input.node?.limit_price ?? input.node?.limitPrice ?? input.node?.price;
+  if (explicit != null && String(explicit).length > 0) {
+    const value = Number(explicit);
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new Error(`${input.action} received invalid limit_price: ${explicit}.`);
+    }
+    return value;
+  }
+  const rawOffset = input.node?.offset_pct ?? input.node?.offsetPct;
+  const offset = rawOffset == null ? (isBuy ? -30 : 30) : Number(rawOffset);
+  if (!Number.isFinite(offset)) {
+    throw new Error(`${input.action} received invalid offset_pct: ${rawOffset}.`);
+  }
+  const value = currentPrice * (1 + offset / 100);
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${input.action} computed a non-positive limit price (${value}).`);
+  }
+  return value;
+}
+
 function uniqueSymbols(symbols) {
   return Array.from(new Set(symbols.filter(Boolean)));
 }
@@ -143,6 +175,20 @@ async function waitForPositionPresent(input, symbol, timeoutMs = 30000) {
   return last;
 }
 
+async function waitForSelectedState(input, readItems, expectedOpen, timeoutMs) {
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+  let items;
+  while (true) {
+    items = await readItems(input);
+    const matching = selectedItems(input, items);
+    if (expectedOpen ? matching.length > 0 : matching.length === 0) {
+      return matching;
+    }
+    if (Date.now() >= deadline) return matching;
+    await sleep(Math.min(500, Math.max(1, deadline - Date.now())));
+  }
+}
+
 function redactPosition(position) {
   return {
     symbol: position.symbol ?? position.coin ?? null,
@@ -270,8 +316,13 @@ export async function readOrders(input) {
 
 export async function assertPositions(input, expectedOpen) {
   requireExplicitSelection(input);
-  const positions = await readPositions(input);
-  const matching = selectedItems(input, positions);
+  const timeoutMs = Number(input.node?.timeout_ms ?? 0);
+  const matching = await waitForSelectedState(
+    input,
+    readPositions,
+    expectedOpen,
+    timeoutMs,
+  );
   const hasPosition = matching.length > 0;
   if (expectedOpen && !hasPosition) throw new Error('Expected at least one matching open Perps position, but found none.');
   if (!expectedOpen && hasPosition) throw new Error(`Expected no matching open Perps positions, but found ${matching.length}.`);
@@ -280,8 +331,13 @@ export async function assertPositions(input, expectedOpen) {
 
 export async function assertOrders(input, expectedOpen) {
   requireExplicitSelection(input);
-  const orders = await readOpenOrders(input);
-  const matching = selectedItems(input, orders);
+  const timeoutMs = Number(input.node?.timeout_ms ?? 0);
+  const matching = await waitForSelectedState(
+    input,
+    readOpenOrders,
+    expectedOpen,
+    timeoutMs,
+  );
   const hasOrders = matching.length > 0;
   if (expectedOpen && !hasOrders) throw new Error('Expected at least one matching open Perps order, but found none.');
   if (!expectedOpen && hasOrders) throw new Error(`Expected no matching open Perps orders, but found ${matching.length}.`);
@@ -407,12 +463,43 @@ export async function placeOrder(input) {
   const symbol = marketSymbol(input);
   const side = String(input.node.side).toLowerCase();
   const amount = String(input.node.amount ?? input.node.notional);
-  const size = String(input.node?.size ?? '0.0001');
   const leverage = Number(input.node?.leverage ?? 3);
   const maxSlippageBps = Number(input.node?.max_slippage_bps ?? input.node?.maxSlippageBps ?? 300);
   const isBuy = orderSideIsBuy(side);
+  const orderType = resolveOrderType(input);
   const currentPrice = await currentPriceForOrder(input, symbol);
-  const result = await evalAsync(input, `Engine.context.PerpsController.placeOrder({ symbol: ${JSON.stringify(symbol)}, isBuy: ${JSON.stringify(isBuy)}, orderType: 'market', size: ${JSON.stringify(size)}, usdAmount: ${JSON.stringify(amount)}, leverage: ${JSON.stringify(leverage)}, currentPrice: ${JSON.stringify(currentPrice)}, maxSlippageBps: ${JSON.stringify(maxSlippageBps)} }).then(function(r){return JSON.stringify(r)})`);
+  const limitPrice = orderType === 'limit'
+    ? resolveLimitPrice(input, isBuy, currentPrice)
+    : null;
+  const size = String(
+    input.node?.size
+      ?? ((Number(amount) * leverage) / (limitPrice ?? currentPrice)),
+  );
+  const orderParams = orderType === 'limit'
+    ? {
+      symbol,
+      isBuy,
+      orderType,
+      size,
+      price: String(limitPrice),
+      timeInForce: 'GTC',
+      leverage,
+      currentPrice,
+      priceAtCalculation: currentPrice,
+      maxSlippageBps,
+    }
+    : {
+      symbol,
+      isBuy,
+      orderType,
+      size,
+      usdAmount: amount,
+      leverage,
+      currentPrice,
+      priceAtCalculation: currentPrice,
+      maxSlippageBps,
+    };
+  const result = await evalAsync(input, `Engine.context.PerpsController.placeOrder(${JSON.stringify(orderParams)}).then(function(r){return JSON.stringify(r)})`);
   if (result?.success === false || result == null) {
     throw new Error(`Failed to place ${symbol} ${side}: ${result?.error || JSON.stringify(result)}`);
   }
@@ -420,8 +507,12 @@ export async function placeOrder(input) {
     input,
     'globalThis.__AGENTIC__ && globalThis.__AGENTIC__.refreshPerpsStreams ? globalThis.__AGENTIC__.refreshPerpsStreams().then(function(r){return JSON.stringify(r)}) : Promise.resolve(JSON.stringify({ ok: false, reason: "refreshPerpsStreams unavailable" }))',
   );
-  await waitForPositionPresent(input, symbol, Number(input.node?.timeout_ms ?? 30000));
-  return { action: input.action, market: symbol, side, amount, size, leverage, submitted: true, result, refresh, proofPath: 'mobile-perps-controller-place-order' };
+  if (orderType === 'limit') {
+    await waitForSelectedState(input, readOpenOrders, true, Number(input.node?.timeout_ms ?? 30000));
+  } else {
+    await waitForPositionPresent(input, symbol, Number(input.node?.timeout_ms ?? 30000));
+  }
+  return { action: input.action, market: symbol, side, orderType, amount, size, leverage, limitPrice, submitted: true, result, refresh, proofPath: 'mobile-perps-controller-place-order' };
 }
 
 export async function ensurePositions(input) {
@@ -448,7 +539,14 @@ export async function ensureOrders(input) {
     const close = await closeOrders(input);
     return { ...(await assertOrders(input, false)), close };
   }
-  if (state === 'open' || state === 'present') return assertOrders(input, true);
+  if (state === 'open' || state === 'present') {
+    const current = await readOpenOrders(input);
+    let order = null;
+    if (selectedItems(input, current).length === 0) {
+      order = await placeOrder({ ...input, node: { ...input.node, order_type: 'limit' } });
+    }
+    return { ...(await assertOrders(input, true)), order };
+  }
   throw new Error(`metamask.perps.ensure_orders received unsupported state: ${state}`);
 }
 

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

@@ -18,7 +18,7 @@ function pageRoute(node) {
     if (!market) throw new Error('mobile ui.navigate page=perps-market requires market or symbol.');
     return { page, route: 'PerpsMarketDetails', params: { market: { symbol: market } } };
   }
-  throw new Error('mobile ui.navigate supported page aliases: home, perps, perps-market.');
+  throw new Error('mobile ui.navigate supported page intents: home, perps, perps-market.');
 }
 
 runAdapter(async (input) => {

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

@@ -590,6 +590,15 @@
             "type": "string",
             "description": "EVM address to read positions for; defaults to the canonical wallet fixture account."
           },
+          "network": {
+            "type": "string",
+            "enum": [
+              "testnet",
+              "mainnet"
+            ],
+            "default": "testnet",
+            "description": "Controller network for this isolated Core read."
+          },
           "timeout_ms": {
             "type": "number"
           }
@@ -607,7 +616,7 @@
         }
       ],
       "proof_effect": "E2E validation must record this action in trace.json; live-proof actions include liveAdapter/proofPath or controller output.",
-      "safety_notes": "Read-only HyperLiquid testnet HTTP query; must not inject controller/UI state to fabricate proof.",
+      "safety_notes": "Read-only HyperLiquid query on the explicitly selected network; must not inject controller/UI state to fabricate proof.",
       "execution_capabilities": []
     },
     {
@@ -697,6 +706,15 @@
             "type": "string",
             "description": "EVM address to read orders for; defaults to the canonical wallet fixture account."
           },
+          "network": {
+            "type": "string",
+            "enum": [
+              "testnet",
+              "mainnet"
+            ],
+            "default": "testnet",
+            "description": "Controller network for this isolated Core read."
+          },
           "timeout_ms": {
             "type": "number"
           }
@@ -714,7 +732,7 @@
         }
       ],
       "proof_effect": "E2E validation must record this action in trace.json; live-proof actions include liveAdapter/proofPath or controller output.",
-      "safety_notes": "Read-only HyperLiquid testnet HTTP query; must not inject controller/UI state to fabricate proof.",
+      "safety_notes": "Read-only HyperLiquid query on the explicitly selected network; must not inject controller/UI state to fabricate proof.",
       "execution_capabilities": []
     },
     {
@@ -820,7 +838,7 @@
               "long",
               "short"
             ],
-            "description": "Order direction (default: long)."
+            "description": "Required order direction."
           },
           "order_type": {
             "type": "string",
@@ -839,11 +857,17 @@
             "description": "Resting limit price as a percent offset from live mid for limit orders (e.g. -30 = 30%% below mid for a non-filling BUY; default -30 buy / +30 sell). Alias: offsetPct."
           },
           "amount": {
-            "type": "string",
+            "type": [
+              "string",
+              "number"
+            ],
             "description": "USD notional alias."
           },
           "notional": {
-            "type": "string",
+            "type": [
+              "string",
+              "number"
+            ],
             "description": "USD notional alias."
           },
           "leverage": {
@@ -1101,6 +1125,15 @@
             "type": "string",
             "description": "EVM address to read for; defaults to the canonical wallet fixture account."
           },
+          "network": {
+            "type": "string",
+            "enum": [
+              "testnet",
+              "mainnet"
+            ],
+            "default": "testnet",
+            "description": "Controller network for this isolated Core assertion."
+          },
           "timeout_ms": {
             "type": "number"
           }
@@ -1122,7 +1155,7 @@
         }
       ],
       "proof_effect": "E2E validation must record this action in trace.json; live-proof actions include liveAdapter/proofPath or controller output.",
-      "safety_notes": "Read-only HyperLiquid testnet HTTP query; must not inject controller state to fabricate proof.",
+      "safety_notes": "Read-only HyperLiquid query on the explicitly selected network; must not inject controller state to fabricate proof.",
       "execution_capabilities": []
     },
     {
@@ -1206,7 +1239,7 @@
               "long",
               "short"
             ],
-            "description": "Order/position direction (default: long when placing)."
+            "description": "Required when state=open/present; otherwise filters selected positions."
           },
           "state": {
             "type": "string",
@@ -1220,11 +1253,17 @@
             "description": "Desired selected position state to converge to."
           },
           "amount": {
-            "type": "string",
+            "type": [
+              "string",
+              "number"
+            ],
             "description": "USD notional alias (used when placing to reach state open)."
           },
           "notional": {
-            "type": "string",
+            "type": [
+              "string",
+              "number"
+            ],
             "description": "USD notional alias."
           },
           "leverage": {
@@ -1252,6 +1291,17 @@
             "market": "BTC",
             "intent": "Converge Perps positions to the requested state via the headless controller"
           }
+        },
+        {
+          "description": "Ensure one ETH long position exists",
+          "node": {
+            "action": "metamask.perps.ensure_positions",
+            "market": "ETH",
+            "side": "long",
+            "state": "open",
+            "notional": "10",
+            "intent": "Converge ETH positions to one explicit testnet precondition"
+          }
         }
       ],
       "proof_effect": "E2E validation must record this action in trace.json; live-proof actions include liveAdapter/proofPath or controller output.",
@@ -1458,6 +1508,15 @@
             ],
             "description": "Optional position/order side filter."
           },
+          "network": {
+            "type": "string",
+            "enum": [
+              "testnet",
+              "mainnet"
+            ],
+            "default": "testnet",
+            "description": "Controller network for this isolated Core assertion."
+          },
           "timeout_ms": {
             "type": "number"
           },
@@ -1490,7 +1549,7 @@
         }
       ],
       "proof_effect": "E2E validation must record this action in trace.json; live-proof actions include liveAdapter/proofPath or target runtime output.",
-      "safety_notes": "Must not inject mid-recipe UI/app state to fabricate proof.",
+      "safety_notes": "Read-only HyperLiquid query on the explicitly selected network; must not inject mid-recipe state to fabricate proof.",
       "execution_capabilities": []
     },
     {
@@ -1574,11 +1633,29 @@
               "long",
               "short"
             ],
-            "description": "Optional position/order side filter."
+            "description": "Required when state=open/present; otherwise filters selected orders."
           },
           "timeout_ms": {
             "type": "number"
           },
+          "amount": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "Explicit USD notional used only when creating a missing open order. Alias: notional."
+          },
+          "notional": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "Alias for amount."
+          },
+          "leverage": {
+            "type": "number",
+            "description": "Leverage used only when creating a missing open order."
+          },
           "state": {
             "type": "string",
             "enum": [
@@ -1605,6 +1682,18 @@
             "mode": "all",
             "intent": "Converge Perps orders to the requested state"
           }
+        },
+        {
+          "description": "Ensure one resting ETH short order exists",
+          "node": {
+            "action": "metamask.perps.ensure_orders",
+            "market": "ETH",
+            "side": "short",
+            "state": "open",
+            "notional": "10",
+            "leverage": 2,
+            "intent": "Converge ETH open orders to one explicit testnet precondition"
+          }
         }
       ],
       "proof_effect": "E2E validation must record this action in trace.json; live-proof actions include liveAdapter/proofPath or target runtime output.",