@deeeed/metamask-harness 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.23.0 - 2026-07-28
+
+### Added
+
+- Core Perps actions support trigger orders, attached and partial TP/SL, and position TP/SL updates.
+
+### Fixed
+
+- Core advanced-order mutations verify the submitted order fields, use executable trigger-limit defaults, honor bounded evidence polling, and classify mutation capabilities correctly.
+- Core advanced-order camelCase aliases validate consistently with their documented snake_case forms.
+
 ## 0.22.0 - 2026-07-26
 
 ### Added

package/dist/recipe-security.js

@@ -18,6 +18,7 @@ const APP_MUTATION_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.perps.close_positions",
   "metamask.perps.close_orders",
   "metamask.perps.place_order",
+  "metamask.perps.update_position_tpsl",
   "metamask.perps.ensure_positions",
   "metamask.perps.ensure_orders",
   "metamask.perps.start_state",
@@ -27,6 +28,7 @@ const EXTERNAL_MUTATION_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.perps.close_positions",
   "metamask.perps.close_orders",
   "metamask.perps.place_order",
+  "metamask.perps.update_position_tpsl",
   "metamask.perps.ensure_positions",
   "metamask.perps.ensure_orders",
   "metamask.perps.start_state",

package/library/actions/core/perps/_controller.mjs

@@ -625,6 +625,13 @@ export function redactOrder(order) {
     size: order.size ?? order.sz ?? order.szi ?? null,
     price: order.price ?? order.limitPx ?? order.px ?? null,
     type: order.orderType ?? order.type ?? null,
+    // Trigger data, so evidence shows what a stop / take-profit placement
+    // actually round-tripped from the exchange.
+    triggerOrderType: order.triggerOrderType ?? null,
+    triggerPrice: order.triggerPrice ?? order.triggerPx ?? null,
+    detailedOrderType: order.detailedOrderType ?? null,
+    isTrigger: order.isTrigger ?? null,
+    reduceOnly: order.reduceOnly ?? null,
   };
 }
 

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

@@ -11,6 +11,13 @@ import {
 // over the controller's standalone getOpenOrders path (no signer / provider init
 // needed) — throws on mismatch so the recipe fails loudly. Mirrors
 // assert_positions.mjs.
+//
+// Optional expect_* fields additionally assert the TRIGGER DATA the exchange
+// round-tripped for every matching order: expect_trigger_order_type (the
+// normalized placement type, e.g. stop_market), expect_trigger_price,
+// expect_execution (market | limit once triggered), expect_reduce_only, and
+// expect_size (proves a partial TP/SL quantity). They use the controller's own
+// field names (triggerOrderType, triggerPrice, orderType, reduceOnly, size).
 
 export function expectedOpen(input) {
   if (input.node?.state == null) throw new Error('metamask.perps.assert_orders requires state=open or state=none.');
@@ -20,6 +27,79 @@ export function expectedOpen(input) {
   throw new Error(`metamask.perps.assert_orders received unsupported state: ${state}`);
 }
 
+/**
+ * Collect the optional trigger-data expectations from the node.
+ *
+ * @param input - Adapter input.
+ * @returns The expectations the node set, keyed by controller field name.
+ */
+/**
+ * Whether the node narrowed matching to trigger orders only.
+ *
+ * @param input - Adapter input.
+ * @returns True when only trigger orders should be considered.
+ */
+export function onlyTriggerOrders(input) {
+  const value = input.node?.only_trigger_orders ?? input.node?.onlyTriggerOrders;
+  return value === true || String(value).toLowerCase() === 'true';
+}
+
+export function expectedTriggerData(input) {
+  const node = input.node ?? {};
+  const expectations = {
+    triggerOrderType:
+      node.expect_trigger_order_type ?? node.expectTriggerOrderType,
+    triggerPrice: node.expect_trigger_price ?? node.expectTriggerPrice,
+    orderType: node.expect_execution ?? node.expectExecution,
+    reduceOnly: node.expect_reduce_only ?? node.expectReduceOnly,
+    size: node.expect_size ?? node.expectSize,
+  };
+  return Object.fromEntries(
+    Object.entries(expectations).filter(
+      ([, value]) => value !== undefined && value !== null,
+    ),
+  );
+}
+
+/**
+ * Assert every matching order carries the expected trigger data.
+ *
+ * @param orders - Matching open orders.
+ * @param expectations - Expectations from `expectedTriggerData`.
+ */
+export function assertTriggerData(orders, expectations) {
+  const fields = Object.keys(expectations);
+  if (fields.length === 0) return;
+
+  for (const order of orders) {
+    for (const field of fields) {
+      const expected = expectations[field];
+      const actual = order[field];
+      const expectedNumber = Number(expected);
+      const actualNumber = Number(actual);
+      const numeric =
+        typeof expected !== 'boolean' &&
+        expected !== '' &&
+        actual !== null &&
+        actual !== undefined &&
+        Number.isFinite(expectedNumber) &&
+        Number.isFinite(actualNumber);
+      const matches =
+        typeof expected === 'boolean'
+          ? Boolean(actual) === expected
+          : // Prices and sizes round-trip with exchange formatting
+            // ('44000' -> '44000.0'), so compare them numerically.
+            (numeric && expectedNumber === actualNumber) ||
+            String(actual) === String(expected);
+      if (!matches) {
+        throw new Error(
+          `Open Perps order ${order.orderId ?? '?'} (${order.symbol ?? '?'}) has ${field}=${JSON.stringify(actual)}, expected ${JSON.stringify(expected)}.`,
+        );
+      }
+    }
+  }
+}
+
 export async function assertOrders(input, expectOpen = expectedOpen(input)) {
   requireExplicitSelection(input);
   const { controller, accountAddress, network } = await getCoreController(input);
@@ -33,6 +113,11 @@ export async function assertOrders(input, expectOpen = expectedOpen(input)) {
       userAddress: accountAddress,
     });
     matching = selectedItems(input, orders);
+    if (onlyTriggerOrders(input)) {
+      // Narrow to the trigger orders on the market so expectations are not
+      // applied to an unrelated parent order resting alongside them.
+      matching = matching.filter((order) => order.isTrigger === true);
+    }
     if (expectOpen ? matching.length > 0 : matching.length === 0) break;
     if (Date.now() >= deadline) break;
     await new Promise((resolve) =>
@@ -44,6 +129,11 @@ export async function assertOrders(input, expectOpen = expectedOpen(input)) {
   if (expectOpen && !hasOrder) {
     throw new Error('Expected at least one matching open Perps order, but found none.');
   }
+
+  const triggerExpectations = expectedTriggerData(input);
+  if (expectOpen) {
+    assertTriggerData(matching, triggerExpectations);
+  }
   if (!expectOpen && hasOrder) {
     throw new Error(`Expected no matching open Perps orders, but found ${matching.length}.`);
   }
@@ -54,6 +144,8 @@ export async function assertOrders(input, expectOpen = expectedOpen(input)) {
     network,
     account: accountAddress,
     expectedOpen: expectOpen,
+    expectedTrigger:
+      Object.keys(triggerExpectations).length === 0 ? null : triggerExpectations,
     matchingCount: matching.length,
     orders: matching.map(redactOrder),
     proofPath: 'perps-controller-getOpenOrders',

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

@@ -27,6 +27,17 @@ import {
 // on-exchange notional (size * limitPrice) clears HyperLiquid's ~$10 minimum even
 // though the limit sits far from mid. After placing we verify the resting open
 // order exists (not a filled position).
+//
+// TRIGGER placements (order_type=stop_market | stop_limit | take_profit_market |
+// take_profit_limit) rest off-book until `trigger_price` is reached, then execute
+// as a market or limit order per the suffix. `trigger_price` is absolute, or
+// derived from mid via `trigger_offset_pct`; `*_limit` types also take the
+// execution limit price (`limit_price` / `offset_pct`). Like limit orders they are
+// verified as RESTING open orders. `reduce_only` is passed through as a
+// first-class placement flag, and `take_profit_price`/`take_profit_size` +
+// `stop_loss_price`/`stop_loss_size` (with `tpsl_linkage`) exercise attached and
+// partial TP/SL. Controller param names are used verbatim (triggerPrice,
+// reduceOnly, takeProfitSize, stopLossSize, tpslLinkage).
 
 function resolveSymbol(input) {
   const symbols = configuredSymbols(input, []);
@@ -38,16 +49,105 @@ function resolveSymbol(input) {
   return symbols[0];
 }
 
+const ORDER_TYPES = [
+  'market',
+  'limit',
+  'stop_market',
+  'stop_limit',
+  'take_profit_market',
+  'take_profit_limit',
+];
+
+const TRIGGER_ORDER_TYPES = ORDER_TYPES.filter((type) => type.includes('_'));
+
+// Order types whose price field is a real limit price the exchange must honour.
+const LIMIT_EXECUTION_ORDER_TYPES = ['limit', 'stop_limit', 'take_profit_limit'];
+
 function resolveOrderType(input) {
   const raw = String(
     input.node?.order_type ?? input.node?.orderType ?? 'market',
   ).toLowerCase();
-  if (raw !== 'market' && raw !== 'limit') {
-    throw new Error(`metamask.perps.place_order received unsupported order_type: ${raw}.`);
+  if (!ORDER_TYPES.includes(raw)) {
+    throw new Error(
+      `metamask.perps.place_order received unsupported order_type: ${raw}. Supported: ${ORDER_TYPES.join(' | ')}.`,
+    );
   }
   return raw;
 }
 
+const isTriggerOrderType = (orderType) => TRIGGER_ORDER_TYPES.includes(orderType);
+const isLimitExecution = (orderType) => LIMIT_EXECUTION_ORDER_TYPES.includes(orderType);
+
+/**
+ * Resolve the trigger price for a stop / take-profit placement.
+ * Precedence: absolute `trigger_price` → `trigger_offset_pct` from mid.
+ * Defaults keep the trigger far from mid so it will not fire during the proof:
+ * a stop sits below mid for a long (sell-side protection) and above for a short;
+ * a take profit sits on the opposite side.
+ *
+ * @param input - Adapter input (node.trigger_price / node.trigger_offset_pct).
+ * @param orderType - Resolved placement type.
+ * @param isBuy - Order direction.
+ * @param mid - Current mid price.
+ */
+function resolveTriggerPrice(input, orderType, isBuy, mid) {
+  const absolute = input.node?.trigger_price ?? input.node?.triggerPrice;
+  if (absolute !== undefined && absolute !== null && String(absolute).length > 0) {
+    const numeric = Number(absolute);
+    if (!Number.isFinite(numeric) || numeric <= 0) {
+      throw new Error(
+        `metamask.perps.place_order received invalid trigger_price: ${absolute}.`,
+      );
+    }
+    return numeric;
+  }
+  const rawOffset = input.node?.trigger_offset_pct ?? input.node?.triggerOffsetPct;
+  const isStop = orderType.startsWith('stop');
+  // A stop fires against the position: below mid when selling to close a long.
+  const defaultOffset = isStop === isBuy ? 30 : -30;
+  const offsetPct =
+    rawOffset === undefined || rawOffset === null ? defaultOffset : Number(rawOffset);
+  if (!Number.isFinite(offsetPct)) {
+    throw new Error(
+      `metamask.perps.place_order received invalid trigger_offset_pct: ${rawOffset}.`,
+    );
+  }
+  const price = mid * (1 + offsetPct / 100);
+  if (!Number.isFinite(price) || price <= 0) {
+    throw new Error(
+      `metamask.perps.place_order computed a non-positive trigger price (${price}).`,
+    );
+  }
+  return price;
+}
+
+/**
+ * Collect the attached TP/SL fields, using the controller's own param names.
+ *
+ * @param input - Adapter input.
+ * @returns Attached TP/SL params, omitting anything the node did not set.
+ */
+function resolveAttachedTpsl(input) {
+  const node = input.node ?? {};
+  const pick = (snake, camel) => {
+    const value = node[snake] ?? node[camel];
+    return value === undefined || value === null ? undefined : String(value);
+  };
+  const attached = {
+    takeProfitPrice: pick('take_profit_price', 'takeProfitPrice'),
+    takeProfitSize: pick('take_profit_size', 'takeProfitSize'),
+    stopLossPrice: pick('stop_loss_price', 'stopLossPrice'),
+    stopLossSize: pick('stop_loss_size', 'stopLossSize'),
+  };
+  const linkage = node.tpsl_linkage ?? node.tpslLinkage;
+  if (linkage !== undefined && linkage !== null) {
+    attached.tpslLinkage = String(linkage);
+  }
+  return Object.fromEntries(
+    Object.entries(attached).filter(([, value]) => value !== undefined),
+  );
+}
+
 /**
  * Resolve the resting limit price for a limit order.
  * Precedence: explicit absolute `limit_price` → `offset_pct` from mid.
@@ -80,6 +180,89 @@ function resolveLimitPrice(input, isBuy, mid) {
   return price;
 }
 
+export function resolveTriggerLimitPrice(input, isBuy, triggerPrice) {
+  const node = input.node ?? {};
+  const hasExplicitPrice =
+    node.limit_price !== undefined ||
+    node.limitPrice !== undefined ||
+    node.price !== undefined;
+  const hasExplicitOffset =
+    node.offset_pct !== undefined || node.offsetPct !== undefined;
+  if (hasExplicitPrice || hasExplicitOffset) {
+    return resolveLimitPrice(input, isBuy, triggerPrice);
+  }
+
+  return triggerPrice * (isBuy ? 1.01 : 0.99);
+}
+
+function numericValuesMatch(actual, expected) {
+  const actualNumber = Number(actual);
+  const expectedNumber = Number(expected);
+  if (!Number.isFinite(actualNumber) || !Number.isFinite(expectedNumber)) {
+    return String(actual) === String(expected);
+  }
+  const tolerance = Math.max(1e-12, Math.abs(expectedNumber) * 1e-4);
+  return Math.abs(actualNumber - expectedNumber) <= tolerance;
+}
+
+export function orderMatchesPlacement(order, expected) {
+  const orderId = order.orderId ?? order.oid ?? order.id;
+  if (
+    expected.orderId !== undefined &&
+    expected.orderId !== null &&
+    String(orderId) !== String(expected.orderId)
+  ) {
+    return false;
+  }
+  if (expected.triggerOrderType) {
+    if (order.isTrigger !== true) return false;
+    if (order.triggerOrderType !== expected.triggerOrderType) return false;
+    if (!numericValuesMatch(order.triggerPrice ?? order.triggerPx, expected.triggerPrice)) {
+      return false;
+    }
+  } else if (order.isTrigger === true) {
+    return false;
+  }
+  if (
+    expected.limitPrice !== null &&
+    expected.limitPrice !== undefined &&
+    !numericValuesMatch(order.price ?? order.limitPx ?? order.px, expected.limitPrice)
+  ) {
+    return false;
+  }
+  if (
+    expected.size !== undefined &&
+    !numericValuesMatch(order.size ?? order.sz ?? order.szi, expected.size)
+  ) {
+    return false;
+  }
+  return Boolean(order.reduceOnly) === Boolean(expected.reduceOnly);
+}
+
+async function waitForPlacedOrder(
+  controller,
+  accountAddress,
+  input,
+  expected,
+  timeoutMs,
+) {
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+  let matching = [];
+  for (;;) {
+    const openOrders = await controller.getOpenOrders({
+      standalone: true,
+      userAddress: accountAddress,
+    });
+    matching = selectedItems(input, openOrders).filter((order) =>
+      orderMatchesPlacement(order, expected),
+    );
+    if (matching.length > 0 || Date.now() >= deadline) return matching;
+    await new Promise((resolve) =>
+      setTimeout(resolve, Math.min(500, Math.max(1, deadline - Date.now()))),
+    );
+  }
+}
+
 export async function placeOrder(input) {
   const symbol = resolveSymbol(input);
   if (input.node?.side == null) throw new Error('metamask.perps.place_order requires side=long or side=short.');
@@ -95,6 +278,34 @@ export async function placeOrder(input) {
   const maxSlippageBps = Number(
     input.node?.max_slippage_bps ?? input.node?.maxSlippageBps ?? 300,
   );
+  const postOnly = input.node?.post_only ?? input.node?.postOnly;
+  const requestedTimeInForce =
+    input.node?.time_in_force ?? input.node?.timeInForce;
+  if (
+    orderType !== 'limit' &&
+    (postOnly !== undefined || requestedTimeInForce !== undefined)
+  ) {
+    throw new Error(
+      'metamask.perps.place_order supports time_in_force/post_only only for order_type=limit.',
+    );
+  }
+  const timeInForce =
+    orderType === 'limit'
+      ? String(requestedTimeInForce ?? (postOnly ? 'ALO' : 'GTC')).toUpperCase()
+      : null;
+  if (timeInForce !== null && !['GTC', 'ALO'].includes(timeInForce)) {
+    throw new Error(
+      `metamask.perps.place_order received unsupported time_in_force: ${timeInForce}. Supported: GTC | ALO.`,
+    );
+  }
+  if (
+    postOnly !== undefined &&
+    Boolean(postOnly) !== (timeInForce === 'ALO')
+  ) {
+    throw new Error(
+      'metamask.perps.place_order received conflicting post_only and time_in_force values.',
+    );
+  }
 
   const usdNumeric = Number(usdAmount);
   if (!Number.isFinite(usdNumeric) || usdNumeric <= 0) {
@@ -106,9 +317,38 @@ export async function placeOrder(input) {
 
   const currentPrice = await currentMarketPrice(controller, symbol);
 
+  const reduceOnly =
+    input.node?.reduce_only ?? input.node?.reduceOnly ?? undefined;
+  const attachedTpsl = resolveAttachedTpsl(input);
+
   let orderParams;
   let limitPrice = null;
-  if (orderType === 'limit') {
+  let triggerPrice = null;
+  if (isTriggerOrderType(orderType)) {
+    triggerPrice = resolveTriggerPrice(input, orderType, isBuy, currentPrice);
+    if (isLimitExecution(orderType)) {
+      limitPrice = resolveTriggerLimitPrice(input, isBuy, triggerPrice);
+    }
+    // A trigger placement rests off-book and executes near the trigger, so size
+    // from the trigger price (or the execution limit price) to clear HL's ~$10
+    // minimum; omit usdAmount so the controller keeps the explicit size.
+    const sizeAnchor = limitPrice ?? triggerPrice;
+    const size = ((usdNumeric * leverage) / sizeAnchor).toString();
+    orderParams = {
+      symbol,
+      isBuy,
+      size,
+      orderType,
+      triggerPrice: String(triggerPrice),
+      ...(limitPrice === null ? {} : { price: String(limitPrice) }),
+      leverage,
+      currentPrice,
+      priceAtCalculation: currentPrice,
+      maxSlippageBps,
+      ...(reduceOnly === undefined ? {} : { reduceOnly: Boolean(reduceOnly) }),
+      ...attachedTpsl,
+    };
+  } else if (orderType === 'limit') {
     limitPrice = resolveLimitPrice(input, isBuy, currentPrice);
     // Size from the LIMIT price so size * limitPrice clears HL's ~$10 minimum;
     // omit usdAmount so the controller does NOT recompute size from mid.
@@ -119,11 +359,13 @@ export async function placeOrder(input) {
       size,
       orderType: 'limit',
       price: String(limitPrice),
-      timeInForce: 'GTC',
+      timeInForce,
       leverage,
       currentPrice,
       priceAtCalculation: currentPrice,
       maxSlippageBps,
+      ...(reduceOnly === undefined ? {} : { reduceOnly: Boolean(reduceOnly) }),
+      ...attachedTpsl,
     };
   } else {
     const size = ((usdNumeric * leverage) / currentPrice).toString();
@@ -137,6 +379,8 @@ export async function placeOrder(input) {
       currentPrice,
       priceAtCalculation: currentPrice,
       maxSlippageBps,
+      ...(reduceOnly === undefined ? {} : { reduceOnly: Boolean(reduceOnly) }),
+      ...attachedTpsl,
     };
   }
 
@@ -150,28 +394,38 @@ export async function placeOrder(input) {
   // For limit orders, confirm a RESTING open order exists (not a filled position);
   // for market orders, confirm the position opened. Both read the real
   // provider/exchange state (not the submit ack) before reporting success.
-  let openOrders = [];
+  const restsOnBook = orderType === 'limit' || isTriggerOrderType(orderType);
+  let matchingOrders = [];
   let positions = [];
-  if (orderType === 'limit') {
-    openOrders = await controller.getOpenOrders({
-      standalone: true,
-      userAddress: accountAddress,
-    });
+  if (restsOnBook) {
+    matchingOrders = await waitForPlacedOrder(
+      controller,
+      accountAddress,
+      input,
+      {
+        orderId: result.orderId,
+        triggerOrderType: isTriggerOrderType(orderType) ? orderType : null,
+        triggerPrice,
+        limitPrice,
+        size: result.submittedSize ?? orderParams.size,
+        reduceOnly: orderParams.reduceOnly ?? false,
+      },
+      Number(input.node?.timeout_ms ?? 30000),
+    );
   } else {
     positions = await controller.getPositions({
       standalone: true,
       userAddress: accountAddress,
     });
   }
-  const matchingOrders = selectedItems(input, openOrders);
   const matchingPositions = selectedItems(input, positions);
 
-  if (orderType === 'limit' && matchingOrders.length === 0) {
+  if (restsOnBook && matchingOrders.length === 0) {
     throw new Error(
-      `core placeOrder (limit) for ${symbol} reported success but no resting open order is visible (orderId=${result.orderId ?? 'null'}, limitPrice=${limitPrice}).`,
+      `core placeOrder (${orderType}) for ${symbol} reported success but no resting open order is visible (orderId=${result.orderId ?? 'null'}, limitPrice=${limitPrice}, triggerPrice=${triggerPrice}).`,
     );
   }
-  if (orderType === 'market' && matchingPositions.length === 0) {
+  if (!restsOnBook && matchingPositions.length === 0) {
     throw new Error(
       `core placeOrder (market) for ${symbol} reported success but no matching position is visible (orderId=${result.orderId ?? 'null'}).`,
     );
@@ -187,14 +441,18 @@ export async function placeOrder(input) {
     orderType,
     notional: usdAmount,
     leverage,
+    timeInForce,
     size: orderParams.size,
     currentPrice,
     limitPrice,
+    triggerPrice,
+    reduceOnly: orderParams.reduceOnly ?? false,
+    attachedTpsl: Object.keys(attachedTpsl).length === 0 ? null : attachedTpsl,
     submitted: true,
     orderId: result.orderId ?? null,
     filledSize: result.filledSize ?? null,
     averagePrice: result.averagePrice ?? null,
-    matchingCount: orderType === 'limit' ? matchingOrders.length : matchingPositions.length,
+    matchingCount: restsOnBook ? matchingOrders.length : matchingPositions.length,
     orders: matchingOrders.map(redactOrder),
     positions: matchingPositions.map(redactPosition),
     order: result,

package/library/actions/core/perps/update_position_tpsl.mjs

@@ -0,0 +1,185 @@
+import {
+  configuredSymbols,
+  getCoreControllerWithSigner,
+  isDirectRun,
+  redactOrder,
+  requireExplicitSelection,
+  runAdapter,
+  selectedItems,
+} from './_controller.mjs';
+
+// core Set or replace the TP/SL attached to an existing Perps POSITION by driving
+// the headless PerpsController.updatePositionTPSL() through the full
+// signing/provider path. This is the position-bound half of the advanced-order
+// contract (TAT-3511): it covers both whole-position TP/SL and PARTIAL
+// (quantity-scoped) TP/SL, which the provider must express as standalone
+// reduce-only trigger orders because a position-bound TP/SL always closes the
+// whole position.
+//
+// Params use the controller's own provider-agnostic names: take_profit_price /
+// take_profit_size / stop_loss_price / stop_loss_size (camelCase aliases
+// accepted). Omitting a price removes that side; omitting a size covers the
+// whole position. After submitting we re-read live open orders so the resulting
+// trigger orders — including their partial sizes — are visible as evidence.
+
+function optionalString(node, snake, camel) {
+  const value = node?.[snake] ?? node?.[camel];
+  return value === undefined || value === null ? undefined : String(value);
+}
+
+function numericValuesMatch(actual, expected) {
+  const actualNumber = Number(actual);
+  const expectedNumber = Number(expected);
+  if (!Number.isFinite(actualNumber) || !Number.isFinite(expectedNumber)) {
+    return String(actual) === String(expected);
+  }
+  const tolerance = Math.max(1e-12, Math.abs(expectedNumber) * 1e-4);
+  return Math.abs(actualNumber - expectedNumber) <= tolerance;
+}
+
+export function orderMatchesTpslRequest(order, request) {
+  if (order.isTrigger !== true || order.reduceOnly !== true) return false;
+  if (order.triggerOrderType !== request.triggerOrderType) return false;
+  if (
+    !numericValuesMatch(
+      order.triggerPrice ?? order.triggerPx,
+      request.triggerPrice,
+    )
+  ) {
+    return false;
+  }
+  return (
+    request.size === undefined ||
+    numericValuesMatch(order.size ?? order.sz ?? order.szi, request.size)
+  );
+}
+
+async function waitForRequestedTpsl(
+  controller,
+  accountAddress,
+  input,
+  requests,
+  timeoutMs,
+) {
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+  let matching = [];
+  for (;;) {
+    const openOrders = await controller.getOpenOrders({
+      standalone: true,
+      userAddress: accountAddress,
+    });
+    const selected = selectedItems(input, openOrders);
+    matching = requests
+      .map((request) =>
+        selected.find((order) => orderMatchesTpslRequest(order, request)),
+      )
+      .filter(Boolean);
+    if (matching.length === requests.length || Date.now() >= deadline) {
+      return matching;
+    }
+    await new Promise((resolve) =>
+      setTimeout(resolve, Math.min(500, Math.max(1, deadline - Date.now()))),
+    );
+  }
+}
+
+export async function updatePositionTpsl(input) {
+  requireExplicitSelection(input);
+  const symbols = configuredSymbols(input, []);
+  if (symbols.length !== 1) {
+    throw new Error(
+      `metamask.perps.update_position_tpsl requires exactly one market; got ${JSON.stringify(symbols)}.`,
+    );
+  }
+  const symbol = symbols[0];
+
+  const node = input.node ?? {};
+  const takeProfitPrice = optionalString(node, 'take_profit_price', 'takeProfitPrice');
+  const stopLossPrice = optionalString(node, 'stop_loss_price', 'stopLossPrice');
+  const takeProfitSize = optionalString(node, 'take_profit_size', 'takeProfitSize');
+  const stopLossSize = optionalString(node, 'stop_loss_size', 'stopLossSize');
+
+  if (takeProfitPrice === undefined && stopLossPrice === undefined) {
+    throw new Error(
+      'metamask.perps.update_position_tpsl requires take_profit_price and/or stop_loss_price (omit both only to clear, which is not supported here).',
+    );
+  }
+
+  const { controller, accountAddress, network } = await getCoreControllerWithSigner(input);
+
+  // The controller resolves the position itself when none is passed; read it
+  // first so the proof records what the TP/SL was attached to.
+  const positions = await controller.getPositions({
+    standalone: true,
+    userAddress: accountAddress,
+  });
+  const position = positions.find((item) => (item.symbol ?? item.coin) === symbol);
+  if (!position) {
+    throw new Error(
+      `metamask.perps.update_position_tpsl found no open ${symbol} position to attach TP/SL to.`,
+    );
+  }
+
+  const params = {
+    symbol,
+    ...(takeProfitPrice === undefined ? {} : { takeProfitPrice }),
+    ...(stopLossPrice === undefined ? {} : { stopLossPrice }),
+    ...(takeProfitSize === undefined ? {} : { takeProfitSize }),
+    ...(stopLossSize === undefined ? {} : { stopLossSize }),
+  };
+
+  const result = await controller.updatePositionTPSL(params);
+  if (!result || result.success !== true) {
+    throw new Error(
+      `core updatePositionTPSL failed for ${symbol}: ${result?.error ?? 'unknown error'}.`,
+    );
+  }
+
+  const requests = [
+    ...(takeProfitPrice === undefined
+      ? []
+      : [{
+          triggerOrderType: 'take_profit_limit',
+          triggerPrice: takeProfitPrice,
+          size: takeProfitSize,
+        }]),
+    ...(stopLossPrice === undefined
+      ? []
+      : [{
+          triggerOrderType: 'stop_market',
+          triggerPrice: stopLossPrice,
+          size: stopLossSize,
+        }]),
+  ];
+  const triggerOrders = await waitForRequestedTpsl(
+    controller,
+    accountAddress,
+    input,
+    requests,
+    Number(input.node?.timeout_ms ?? 30000),
+  );
+
+  if (triggerOrders.length !== requests.length) {
+    throw new Error(
+      `core updatePositionTPSL for ${symbol} reported success but only ${triggerOrders.length}/${requests.length} requested trigger orders are visible.`,
+    );
+  }
+
+  return {
+    action: input.action,
+    source: 'perps-controller-updatePositionTPSL',
+    network,
+    account: accountAddress,
+    market: symbol,
+    positionSize: position.size ?? null,
+    requested: params,
+    isPartial: takeProfitSize !== undefined || stopLossSize !== undefined,
+    submitted: true,
+    triggerOrderCount: triggerOrders.length,
+    orders: triggerOrders.map(redactOrder),
+    result,
+    proofPath: 'perps-controller-updatePositionTPSL',
+  };
+}
+
+if (isDirectRun(import.meta.url)) runAdapter(updatePositionTpsl);

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

@@ -707,6 +707,14 @@
           },
           "timeout_ms": {
             "type": "number"
+          },
+          "network": {
+            "type": "string",
+            "enum": [
+              "testnet",
+              "mainnet"
+            ],
+            "description": "Venue to act on. Defaults to testnet. Mainnet uses REAL funds: reads work with network=mainnet alone, while signing additionally requires CORE_PERPS_ALLOW_MAINNET_WRITES=1 in the environment."
           }
         },
         "additionalProperties": false
@@ -721,7 +729,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.place_order": {
-      "description": "core Place a real Perps order on HyperLiquid testnet by driving the headless perps controller placeOrder() through the full signing/provider path. Testnet only Supports market (default) and resting limit orders (order_type=limit with price/offset_pct).",
+      "description": "core Place a real Perps order on HyperLiquid testnet by driving the headless perps controller placeOrder() through the full signing/provider path. Supports market (default), resting limit orders (order_type=limit with price/offset_pct), and resting trigger placements (stop_market | stop_limit | take_profit_market | take_profit_limit with trigger_price/trigger_offset_pct), plus reduce_only and attached/partial TP/SL (take_profit_price/take_profit_size, stop_loss_price/stop_loss_size, tpsl_linkage). Venue is selected with network (testnet default; mainnet signs with REAL funds and also requires CORE_PERPS_ALLOW_MAINNET_WRITES=1). Plain limit orders accept time_in_force GTC | ALO (post-only).",
       "schema": {
         "type": "object",
         "properties": {
@@ -797,17 +805,45 @@
             "type": "string",
             "enum": [
               "market",
-              "limit"
+              "limit",
+              "stop_market",
+              "stop_limit",
+              "take_profit_market",
+              "take_profit_limit"
+            ],
+            "description": "market (default) fills immediately; limit places a RESTING order at price/offset_pct that does not fill; stop_market | stop_limit | take_profit_market | take_profit_limit place a RESTING TRIGGER order that activates at trigger_price and then executes as a market or limit order per the suffix. Alias: orderType."
+          },
+          "orderType": {
+            "type": "string",
+            "enum": [
+              "market",
+              "limit",
+              "stop_market",
+              "stop_limit",
+              "take_profit_market",
+              "take_profit_limit"
             ],
-            "description": "market (default) fills immediately; limit places a RESTING order at price/offset_pct that does not fill. Alias: orderType."
+            "description": "Alias for order_type."
           },
           "limit_price": {
             "type": "string",
             "description": "Absolute resting limit price (limit orders). Takes precedence over offset_pct. Alias: price/limitPrice."
           },
+          "limitPrice": {
+            "type": "string",
+            "description": "Alias for limit_price."
+          },
+          "price": {
+            "type": "string",
+            "description": "Alias for limit_price."
+          },
           "offset_pct": {
             "type": "number",
-            "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."
+            "description": "Limit price as a percent offset from live mid for plain limits, or from the trigger for *_limit orders. Plain limits default to -30 buy / +30 sell; trigger limits default to +1 buy / -1 sell so they are executable after activation. Alias: offsetPct."
+          },
+          "offsetPct": {
+            "type": "number",
+            "description": "Alias for offset_pct."
           },
           "amount": {
             "type": [
@@ -833,6 +869,120 @@
           },
           "timeout_ms": {
             "type": "number"
+          },
+          "trigger_price": {
+            "type": "string",
+            "description": "Absolute trigger price for stop_*/take_profit_* placements. Takes precedence over trigger_offset_pct. Alias: triggerPrice."
+          },
+          "triggerPrice": {
+            "type": "string",
+            "description": "Alias for trigger_price."
+          },
+          "trigger_offset_pct": {
+            "type": "number",
+            "description": "Trigger price as a percent offset from live mid (default keeps the trigger ~30% away so it does not fire during a proof). Alias: triggerOffsetPct."
+          },
+          "triggerOffsetPct": {
+            "type": "number",
+            "description": "Alias for trigger_offset_pct."
+          },
+          "reduce_only": {
+            "type": "boolean",
+            "description": "Place as reduce-only, so the order can only close an existing position. Alias: reduceOnly."
+          },
+          "reduceOnly": {
+            "type": "boolean",
+            "description": "Alias for reduce_only."
+          },
+          "take_profit_price": {
+            "type": "string",
+            "description": "Attached take profit price. Alias: takeProfitPrice."
+          },
+          "takeProfitPrice": {
+            "type": "string",
+            "description": "Alias for take_profit_price."
+          },
+          "take_profit_size": {
+            "type": "string",
+            "description": "Quantity covered by the attached take profit (partial TP). Omit to cover the whole order. Alias: takeProfitSize."
+          },
+          "takeProfitSize": {
+            "type": "string",
+            "description": "Alias for take_profit_size."
+          },
+          "stop_loss_price": {
+            "type": "string",
+            "description": "Attached stop loss price. Alias: stopLossPrice."
+          },
+          "stopLossPrice": {
+            "type": "string",
+            "description": "Alias for stop_loss_price."
+          },
+          "stop_loss_size": {
+            "type": "string",
+            "description": "Quantity covered by the attached stop loss (partial SL). Omit to cover the whole order. Alias: stopLossSize."
+          },
+          "stopLossSize": {
+            "type": "string",
+            "description": "Alias for stop_loss_size."
+          },
+          "tpsl_linkage": {
+            "type": "string",
+            "enum": [
+              "none",
+              "order",
+              "position"
+            ],
+            "description": "How an attached TP/SL is linked: to this order ('order'), to the resulting position ('position'), or absent ('none'). Provider-agnostic replacement for HyperLiquid grouping. Alias: tpslLinkage."
+          },
+          "tpslLinkage": {
+            "type": "string",
+            "enum": [
+              "none",
+              "order",
+              "position"
+            ],
+            "description": "Alias for tpsl_linkage."
+          },
+          "max_slippage_bps": {
+            "type": "number",
+            "description": "Slippage tolerance in basis points; also caps the limit price derived from the trigger for *_market trigger placements. Alias: maxSlippageBps."
+          },
+          "maxSlippageBps": {
+            "type": "number",
+            "description": "Alias for max_slippage_bps."
+          },
+          "network": {
+            "type": "string",
+            "enum": [
+              "testnet",
+              "mainnet"
+            ],
+            "description": "Venue to act on. Defaults to testnet. Mainnet uses REAL funds: reads work with network=mainnet alone, while signing additionally requires CORE_PERPS_ALLOW_MAINNET_WRITES=1 in the environment."
+          },
+          "time_in_force": {
+            "type": "string",
+            "enum": [
+              "GTC",
+              "ALO"
+            ],
+            "description": "Time in force for plain limit orders: GTC (default) or ALO (post-only). Alias: timeInForce."
+          },
+          "timeInForce": {
+            "type": "string",
+            "enum": [
+              "GTC",
+              "ALO"
+            ],
+            "description": "Alias for time_in_force."
+          },
+          "post_only": {
+            "type": "boolean",
+            "description": "Protocol-agnostic post-only flag; maps to the controller time-in-force ALO. Alias: postOnly."
+          },
+          "postOnly": {
+            "type": "boolean",
+            "description": "Alias for post_only."
           }
         },
         "additionalProperties": false
@@ -951,6 +1101,14 @@
           },
           "timeout_ms": {
             "type": "number"
+          },
+          "network": {
+            "type": "string",
+            "enum": [
+              "testnet",
+              "mainnet"
+            ],
+            "description": "Venue to act on. Defaults to testnet. Mainnet uses REAL funds: reads work with network=mainnet alone, while signing additionally requires CORE_PERPS_ALLOW_MAINNET_WRITES=1 in the environment."
           }
         },
         "additionalProperties": false
@@ -1208,6 +1366,14 @@
           },
           "timeout_ms": {
             "type": "number"
+          },
+          "network": {
+            "type": "string",
+            "enum": [
+              "testnet",
+              "mainnet"
+            ],
+            "description": "Venue to act on. Defaults to testnet. Mainnet uses REAL funds: reads work with network=mainnet alone, while signing additionally requires CORE_PERPS_ALLOW_MAINNET_WRITES=1 in the environment."
           }
         },
         "required": [
@@ -1321,6 +1487,14 @@
           },
           "timeout_ms": {
             "type": "number"
+          },
+          "network": {
+            "type": "string",
+            "enum": [
+              "testnet",
+              "mainnet"
+            ],
+            "description": "Venue to act on. Defaults to testnet. Mainnet uses REAL funds: reads work with network=mainnet alone, while signing additionally requires CORE_PERPS_ALLOW_MAINNET_WRITES=1 in the environment."
           }
         },
         "additionalProperties": false
@@ -1345,7 +1519,7 @@
       ]
     },
     "metamask.perps.assert_orders": {
-      "description": "core Assert live Perps open orders are present or absent for an explicit market selection or mode=all.",
+      "description": "core Assert live Perps open orders are present or absent for an explicit market selection or mode=all. Optional expect_* fields assert the trigger data of the matching orders (placement type, trigger price, execution mode, reduce-only flag, size).",
       "schema": {
         "type": "object",
         "properties": {
@@ -1447,6 +1621,40 @@
               "present"
             ],
             "description": "Desired/expected selected collection state."
+          },
+          "expect_trigger_order_type": {
+            "type": "string",
+            "enum": [
+              "stop_market",
+              "stop_limit",
+              "take_profit_market",
+              "take_profit_limit"
+            ],
+            "description": "Require every matching order to be this trigger placement type (read back from the exchange)."
+          },
+          "expect_trigger_price": {
+            "type": "string",
+            "description": "Require every matching order to carry this trigger price."
+          },
+          "expect_execution": {
+            "type": "string",
+            "enum": [
+              "market",
+              "limit"
+            ],
+            "description": "Require the execution mode a matching trigger order runs as once it fires."
+          },
+          "expect_reduce_only": {
+            "type": "boolean",
+            "description": "Require the reduce-only flag on every matching order."
+          },
+          "expect_size": {
+            "type": "string",
+            "description": "Require this size on every matching order (proves a partial TP/SL quantity)."
+          },
+          "only_trigger_orders": {
+            "type": "boolean",
+            "description": "Consider only trigger orders (stop / take profit) on the selected market, so expectations are not applied to a plain parent order resting alongside them. Alias: onlyTriggerOrders."
           }
         },
         "required": [
@@ -1577,6 +1785,14 @@
               "present"
             ],
             "description": "Desired/expected selected collection state."
+          },
+          "network": {
+            "type": "string",
+            "enum": [
+              "testnet",
+              "mainnet"
+            ],
+            "description": "Venue to act on. Defaults to testnet. Mainnet uses REAL funds: reads work with network=mainnet alone, while signing additionally requires CORE_PERPS_ALLOW_MAINNET_WRITES=1 in the environment."
           }
         },
         "required": [
@@ -2239,6 +2455,109 @@
         "app-mutation",
         "external-mutation"
       ]
+    },
+    "metamask.perps.update_position_tpsl": {
+      "description": "core Set or replace the TP/SL attached to an existing Perps POSITION by driving the headless perps controller updatePositionTPSL() through the full signing/provider path. Covers whole-position TP/SL and PARTIAL (quantity-scoped) TP/SL via take_profit_size / stop_loss_size, which the provider expresses as standalone reduce-only trigger orders because a position-bound TP/SL always closes the whole position. Venue is selected with network (testnet default; mainnet signs with REAL funds and also requires CORE_PERPS_ALLOW_MAINNET_WRITES=1).",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "market": {
+            "type": "string",
+            "description": "Single market symbol whose position the TP/SL attaches to. Alias: symbol."
+          },
+          "symbol": {
+            "type": "string",
+            "description": "Alias for market."
+          },
+          "markets": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Explicit market list (requires exactly one)."
+          },
+          "symbols": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Alias for markets."
+          },
+          "selector": {
+            "type": "object",
+            "description": "Optional structured selector with mode and symbols/markets."
+          },
+          "take_profit_price": {
+            "type": "string",
+            "description": "Take profit trigger price. Omit to leave the take profit unset. Alias: takeProfitPrice."
+          },
+          "takeProfitPrice": {
+            "type": "string",
+            "description": "Alias for take_profit_price."
+          },
+          "take_profit_size": {
+            "type": "string",
+            "description": "Quantity the take profit covers (partial TP). Omit to cover the whole position. Alias: takeProfitSize."
+          },
+          "takeProfitSize": {
+            "type": "string",
+            "description": "Alias for take_profit_size."
+          },
+          "stop_loss_price": {
+            "type": "string",
+            "description": "Stop loss trigger price. Omit to leave the stop loss unset. Alias: stopLossPrice."
+          },
+          "stopLossPrice": {
+            "type": "string",
+            "description": "Alias for stop_loss_price."
+          },
+          "stop_loss_size": {
+            "type": "string",
+            "description": "Quantity the stop loss covers (partial SL). Omit to cover the whole position. Alias: stopLossSize."
+          },
+          "stopLossSize": {
+            "type": "string",
+            "description": "Alias for stop_loss_size."
+          },
+          "network": {
+            "type": "string",
+            "enum": [
+              "testnet",
+              "mainnet"
+            ],
+            "description": "Venue to act on. Defaults to testnet. Mainnet uses REAL funds and additionally requires CORE_PERPS_ALLOW_MAINNET_WRITES=1."
+          },
+          "account": {
+            "type": "string",
+            "description": "EVM address to act for; defaults to MM_TEST_ACCOUNT_ADDRESS."
+          },
+          "timeout_ms": {
+            "type": "number"
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.perps.update_position_tpsl",
+          "market": "BTC",
+          "take_profit_price": "120000",
+          "intent": "Attach a whole-position take profit to the open BTC position",
+          "next": "done"
+        },
+        {
+          "action": "metamask.perps.update_position_tpsl",
+          "market": "BTC",
+          "take_profit_price": "120000",
+          "take_profit_size": "0.0002",
+          "intent": "Attach a partial (quantity-scoped) take profit to the open BTC position",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": [
+        "app-mutation",
+        "external-mutation"
+      ]
     }
   }
 }

package/package.json

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