@reyaxyz/sdk 0.151.4 → 0.152.1

package/src/services/orders/orderV2.ts

@@ -1,100 +1,292 @@
-import { Signer, JsonRpcSigner, AbiCoder } from 'ethers';
+import { Signer, JsonRpcSigner, parseUnits } from 'ethers';
 import {
   OrderEntryApi,
   Configuration,
-  CancelOrderResponse,
   CreateOrderResponse,
-  MassCancelResponse,
   OrderType,
   TimeInForce,
+  CancelOrderResponse,
+  MassCancelResponse,
+  CancelAllAfterResponse,
+  ModifyOrderResponse,
+  ModifyOrderRequest,
 } from '@reyaxyz/api-v2-sdk';
 import {
-  signOrdersGatewayOrder,
-  signOrderCancel,
-  signMassCancel,
-  OrdersGatewayOrderType,
-  scale,
-  CONDITIONAL_ORDER_SIG_DEADLINE,
+  signOrder,
+  signMEOrderCancel,
+  signMEMassCancel,
+  signMECancelAllAfter,
+  OrderType as OnChainOrderType,
+  fullPositionStopQuantity,
 } from '@reyaxyz/common';
 import { getReyaNetwork } from '../../utils/network';
 import { getSdkConfig } from '../../config';
+import { nextNonce } from './nonce';
+import { assertSettlementHeadroom } from './triggerSettlementHeadroom';
+
+// A provided, non-zero order id. '' / whitespace / '0' / all-zeros are the
+// engine's "not provided" sentinels; normalize them consistently across cancel
+// + modify so a caller passing orderId:'0' (or '') can't sign/target the
+// sentinel or slip past the "requires an id" guard.
+const isProvidedNonZeroId = (value: string | undefined): value is string => {
+  const trimmed = value?.trim();
+  return !!trimmed && !/^0+$/.test(trimmed);
+};
 
-const DEFAULT_CANCEL_DEADLINE_SECONDS = 60;
+// Maps the REST-surface `OrderType` (string: 'LIMIT' / 'STOP_LOSS' / 'TAKE_PROFIT',
+// from @reyaxyz/api-v2-sdk) to the on-chain numeric enum signed into
+// `OrderDetails.orderType` (0 / 1 / 2, from @reyaxyz/common).
+export const toOnChainOrderType = (orderType: OrderType): OnChainOrderType => {
+  switch (orderType) {
+    case 'LIMIT':
+      return OnChainOrderType.Limit;
+    case 'STOP_LOSS':
+      return OnChainOrderType.StopLoss;
+    case 'TAKE_PROFIT':
+      return OnChainOrderType.TakeProfit;
+    default:
+      throw new Error(`Unsupported orderType: ${orderType}`);
+  }
+};
 
-export { TimeInForce };
+// Maps the REST-surface `TimeInForce` to the numeric value signed into
+// `OrderDetails.timeInForce`, matching the off-chain verifier's
+// REST_TIME_IN_FORCE_TO_NUMERIC (common-backend signature-validation):
+// GTC=0, IOC=1, GTT=2.
+export const toOnChainTimeInForce = (timeInForce: TimeInForce): number => {
+  switch (timeInForce) {
+    case 'GTC':
+      return 0;
+    case 'IOC':
+      return 1;
+    case 'GTT':
+      return 2;
+    default:
+      throw new Error(`Unsupported timeInForce: ${timeInForce}`);
+  }
+};
 
-export type CreateSpotOrderParams = {
+export type CreateOrderParams = {
   signer: Signer | JsonRpcSigner;
   accountId: number;
   exchangeId: number;
+  /** Unified market id: core_id for perp, core_id + 1e10 for spot. */
   marketId: number;
   isBuy: boolean;
   limitPx: string;
-  qty: string;
+  /**
+   * Order quantity. Type-conditional, mirroring the modify-trigger path:
+   *  - LIMIT: REQUIRED — signed as ±qty (positive buy, negative sell) and sent
+   *    on the wire.
+   *  - STOP_LOSS / TAKE_PROFIT: OMIT — the signed quantity is the ±int256.max
+   *    full-position sentinel (sign from `isBuy`; protect the whole position)
+   *    and qty is dropped from the wire payload. Passing a qty on a trigger
+   *    create throws (the backend rejects it).
+   */
+  qty?: string;
   symbol: string;
+  orderType: OrderType;
+  /**
+   * REQUIRED for every order class — signed and sent on the wire. On a
+   * STOP_LOSS / TAKE_PROFIT it chooses what the stop becomes when it fires:
+   * IOC fills what the book offers and cancels the rest, GTC rests the
+   * remainder until cancelled, GTT rests it until one settlement headroom
+   * before `expiresAfter`.
+   */
   timeInForce: TimeInForce;
-  clientOrderId?: number;
-};
-
-const encodeSpotLimitOrderInputs = (
-  isBuy: boolean,
-  limitPx: string,
-  qty: string,
-): string => {
-  const baseDelta = isBuy
-    ? scale(18)(parseFloat(qty))
-    : -scale(18)(parseFloat(qty));
-  const price = scale(18)(parseFloat(limitPx));
-  return AbiCoder.defaultAbiCoder().encode(
-    ['int256', 'uint256'],
-    [baseDelta, price],
-  );
+  /** Required for STOP_LOSS / TAKE_PROFIT; omit for LIMIT. */
+  triggerPx?: string;
+  /** Perp only; spot markets must set this to false / omit. */
+  reduceOnly?: boolean;
+  /**
+   * Maker-only intent. Signed into OrderDetails. Valid on GTC/GTT; the API
+   * rejects it on IOC + TP/SL. Omit / false for a normal order.
+   */
+  postOnly?: boolean;
+  /** Off-chain correlation id. Signed but not on-chain-enforced. */
+  clientOrderId?: string;
+  /** Unix seconds. On-chain order lifetime; omit for no-expiry orders. */
+  expiresAfter?: number;
+  /**
+   * Unix seconds. EIP-712 signature deadline (envelope). API-enforced at entry.
+   * Defaults to now + 30s when omitted.
+   */
+  deadline?: number;
+  /**
+   * Seconds of settlement headroom a GTT `expiresAfter` must outlast. Defaults
+   * to the production value; set it only for a deployment running a different
+   * one.
+   */
+  settlementHeadroomSeconds?: number;
+  /**
+   * Optional explicit nonce. Must be strictly greater than the signer's last
+   * accepted nonce in the matching engine. Defaults to a per-signer monotonic
+   * µs value.
+   */
+  nonce?: bigint;
 };
 
-export const createSpotOrder = async (
-  params: CreateSpotOrderParams,
+export type CancelMEOrderParams = {
+  signer: Signer | JsonRpcSigner;
+  accountId: number;
+  marketId: number;
+  symbol: string;
+  orderId?: string;
+  clientOrderId?: string;
+  /** Unix seconds; EIP-712 signature deadline. Defaults to now + 30s. */
+  deadline?: number;
+  /** Optional explicit nonce; otherwise per-signer monotonic µs. */
+  nonce?: bigint;
+};
+
+export type MassCancelMEOrdersParams = {
+  signer: Signer | JsonRpcSigner;
+  accountId: number;
+  marketId?: number;
+  symbol?: string;
+  /** Unix seconds; EIP-712 signature deadline. Defaults to now + 30s. */
+  deadline?: number;
+  /** Optional explicit nonce; otherwise per-signer monotonic µs. */
+  nonce?: bigint;
+};
+
+const DEFAULT_DEADLINE_SECONDS = 30;
+
+const isZeroClientOrderId = (clientOrderId: string | undefined): boolean =>
+  clientOrderId !== undefined && /^0+$/.test(clientOrderId.trim());
+
+const assertNonZeroClientOrderId = (
+  clientOrderId: string | undefined,
+): void => {
+  if (isZeroClientOrderId(clientOrderId)) {
+    throw new Error('clientOrderId must be omitted rather than set to 0');
+  }
+};
+
+// Spot unified market ids are offset by 1e10 (see CreateOrderParams.marketId).
+// Spot markets don't support reduceOnly, so reject it at the SDK boundary
+// rather than sign a request the backend will reject.
+const SPOT_MARKET_ID_OFFSET = 10_000_000_000;
+
+export const createOrder = async (
+  params: CreateOrderParams,
 ): Promise<CreateOrderResponse> => {
+  assertNonZeroClientOrderId(params.clientOrderId);
+
   const reyaChainId = getReyaNetwork();
   const config = getSdkConfig();
 
-  const inputs = encodeSpotLimitOrderInputs(
-    params.isBuy,
-    params.limitPx,
-    params.qty,
-  );
+  const isTrigger =
+    params.orderType === OrderType.STOP_LOSS ||
+    params.orderType === OrderType.TAKE_PROFIT;
 
-  const creationTimestampMs = Date.now();
-  // IOC orders are capped at 10 minutes by the API; GTC orders use the
-  // conditional-order sentinel deadline so they rest until cancelled.
-  const deadline = (() => {
-    switch (params.timeInForce) {
-      case TimeInForce.IOC:
-        return Math.floor(creationTimestampMs / 1000) + 30;
-      case TimeInForce.GTC:
-        return CONDITIONAL_ORDER_SIG_DEADLINE;
-      default:
-        throw new Error(`Unsupported timeInForce: ${params.timeInForce}`);
-    }
-  })();
-
-  // For spot orders, nonce is just the timestamp (uint64)
-  const spotNonce = BigInt(creationTimestampMs);
-
-  const { serializedSignature, nonce } = await signOrdersGatewayOrder(
-    params.signer,
-    reyaChainId,
-    params.accountId,
-    params.marketId,
-    params.exchangeId,
-    [],
-    OrdersGatewayOrderType.LIMIT_ORDER_SPOT,
-    inputs,
-    deadline,
-    creationTimestampMs,
-    spotNonce, // custom nonce for spot orders
-  );
+  if (
+    isTrigger &&
+    (params.reduceOnly !== undefined || params.postOnly !== undefined)
+  ) {
+    throw new Error('reduceOnly and postOnly must be omitted for TP/SL orders');
+  }
+
+  if (isTrigger && params.triggerPx === undefined) {
+    throw new Error(`triggerPx is required for ${params.orderType} orders`);
+  }
+
+  // qty is type-conditional (mirrors the modify-trigger path):
+  //  - STOP_LOSS / TAKE_PROFIT: qty MUST be omitted; the signed quantity is
+  //    the ±int256.max full-position sentinel (sign from `isBuy`) and qty is
+  //    dropped from the wire below. The backend rejects a trigger create that
+  //    carries qty.
+  //  - LIMIT: qty is REQUIRED and signed as ±qty.
+  // Validated up front (before a nonce is minted), like the triggerPx guard.
+  if (isTrigger && params.qty !== undefined) {
+    throw new Error(
+      `qty must be omitted for ${params.orderType} orders (the signed quantity is the full-position sentinel)`,
+    );
+  }
+  if (!isTrigger && params.qty === undefined) {
+    throw new Error('qty is required for a LIMIT order');
+  }
+
+  // Convert once while validation is still side-effect free. timeInForce is
+  // required for every order class — on a trigger it chooses what the fired
+  // child becomes, so there is no value the SDK could supply on the caller's
+  // behalf. Runtime callers can bypass the TypeScript type; reject a missing or
+  // unrecognised value before resolving the signer or advancing its nonce.
+  const onChainTimeInForce = toOnChainTimeInForce(params.timeInForce);
+
+  // Only GTT carries a lifetime, for triggers as for book orders. On a trigger
+  // the one timestamp bounds the armed window AND is the fired child's on-chain
+  // settlement deadline; GTC and IOC triggers have no lifetime of their own.
+  const hasExpiry =
+    params.expiresAfter !== undefined && params.expiresAfter !== 0;
+  if (params.timeInForce === TimeInForce.GTT && !hasExpiry) {
+    throw new Error('expiresAfter is required for GTT orders');
+  }
+  if (params.timeInForce !== TimeInForce.GTT && hasExpiry) {
+    throw new Error(
+      'expiresAfter must be omitted for IOC / GTC orders — only GTT carries a lifetime',
+    );
+  }
+
+  if (params.reduceOnly && params.marketId >= SPOT_MARKET_ID_OFFSET) {
+    throw new Error('reduceOnly is not supported for spot markets');
+  }
+
+  // Venue admission rules the SDK can evaluate itself, checked while validation
+  // is still side-effect free — a nonce burnt on an order the engine refuses
+  // has to be resynced before the next one can be signed.
+  if (hasExpiry) {
+    assertSettlementHeadroom(
+      params.expiresAfter!,
+      params.settlementHeadroomSeconds,
+    );
+  }
 
   const signerAddress = await params.signer.getAddress();
+  const defaultDeadline =
+    Math.floor(Date.now() / 1000) + DEFAULT_DEADLINE_SECONDS;
+  const deadline = params.deadline ?? defaultDeadline;
+  const expiresAfter = params.expiresAfter ?? 0;
+  const nonce = params.nonce ?? nextNonce(signerAddress);
+
+  // On-chain `OrderDetails.quantity` is signed int256 (E18 for real sizes): a
+  // trigger signs the ±int256.max full-position sentinel — sign from `isBuy`
+  // (−max sells out a long, +max buys back a short; reya-network #738 enforces
+  // SL/TP <=> ±sentinel, and quantity 0 now reverts) — while a LIMIT signs ±qty
+  // (positive buy, negative sell). The REST surface keeps `isBuy + qty`
+  // (unsigned) for symmetry with the rest of the API; reconstruct the signed
+  // value here.
+  //
+  // Use `parseUnits(str, 18)` to match the off-chain verifier exactly
+  // (signature-validation/index.ts). The previous `scale(18)(parseFloat(str))`
+  // diverged for |x| < 1e-6 or >= 1e21 (parseFloat exponential form) → a
+  // signature mismatch on extreme sizes.
+  const quantity = isTrigger
+    ? fullPositionStopQuantity(params.isBuy)
+    : params.isBuy
+      ? parseUnits(params.qty!, 18)
+      : -parseUnits(params.qty!, 18);
+  const limitPrice = parseUnits(params.limitPx, 18);
+  const triggerPrice = params.triggerPx
+    ? parseUnits(params.triggerPx, 18)
+    : BigInt(0);
+
+  const { serializedSignature } = await signOrder(params.signer, reyaChainId, {
+    accountId: params.accountId,
+    marketId: params.marketId,
+    exchangeId: params.exchangeId,
+    orderType: toOnChainOrderType(params.orderType),
+    quantity,
+    limitPrice,
+    triggerPrice,
+    timeInForce: onChainTimeInForce,
+    clientOrderId: BigInt(params.clientOrderId ?? 0),
+    reduceOnly: isTrigger ? false : params.reduceOnly ?? false,
+    postOnly: isTrigger ? false : params.postOnly ?? false,
+    expiresAfter: BigInt(expiresAfter),
+    nonce,
+    deadline,
+  });
 
   const apiConfig = new Configuration({
     basePath: `${config.apiEndpoint}/v2`,
@@ -109,51 +301,72 @@ export const createSpotOrder = async (
       accountId: params.accountId,
       isBuy: params.isBuy,
       limitPx: params.limitPx,
-      qty: params.qty,
-      orderType: OrderType.LIMIT,
+      // qty is omitted on a trigger create (guaranteed undefined by the
+      // isTrigger guard above); sent for a LIMIT create.
+      ...(params.qty !== undefined && { qty: params.qty }),
+      orderType: params.orderType,
       timeInForce: params.timeInForce,
-      clientOrderId: params.clientOrderId,
+      ...(params.triggerPx !== undefined && { triggerPx: params.triggerPx }),
+      ...(params.reduceOnly !== undefined && { reduceOnly: params.reduceOnly }),
+      ...(params.postOnly !== undefined && { postOnly: params.postOnly }),
+      ...(params.clientOrderId !== undefined && {
+        clientOrderId: params.clientOrderId,
+      }),
       signature: serializedSignature,
       nonce: nonce.toString(),
       signerWallet: signerAddress,
-      expiresAfter: deadline,
+      deadline,
+      ...(params.expiresAfter !== undefined &&
+        params.expiresAfter !== 0 && { expiresAfter }),
     },
   });
 
   return response;
 };
 
-export type CancelSpotOrderParams = {
-  signer: Signer | JsonRpcSigner;
-  accountId: number;
-  marketId: number;
-  symbol: string;
-  orderId?: string;
-  clientOrderId?: number;
-  expiresAfterSeconds?: number;
-};
-
-export const cancelSpotOrder = async (
-  params: CancelSpotOrderParams,
+export const cancelMEOrder = async (
+  params: CancelMEOrderParams,
 ): Promise<CancelOrderResponse> => {
-  if (!params.orderId && params.clientOrderId === undefined) {
-    throw new Error('Either orderId or clientOrderId must be provided');
-  }
+  assertNonZeroClientOrderId(params.clientOrderId);
 
   const reyaChainId = getReyaNetwork();
   const config = getSdkConfig();
 
-  const nowMs = Date.now();
-  const expiresAfter =
-    Math.floor(nowMs / 1000) +
-    (params.expiresAfterSeconds ?? DEFAULT_CANCEL_DEADLINE_SECONDS);
-  const nonce = BigInt(nowMs);
+  // Validation: at least one of orderId or clientOrderId must be provided.
+  // Without this check the SDK would sign for `cancel(orderId=0, clOrdId=0)`
+  // and the API would either reject with a cryptic signature-mismatch error
+  // or — worse — accept and look up a sentinel "order zero" that doesn't
+  // exist. Better to surface the misuse at the SDK boundary. (PRO-81 C.2.26)
+  // Treat '0' as "not provided" for both ids — '0' is the engine's
+  // not-provided sentinel, so a caller passing clientOrderId:'0' (or
+  // orderId:'0') must NOT slip past this guard and sign the sentinel
+  // cancel(0,0) it is meant to block. (PRO-81 C.2.26)
+  const orderIdProvided = isProvidedNonZeroId(params.orderId);
+  const clientOrderIdProvided = isProvidedNonZeroId(params.clientOrderId);
+  if (!orderIdProvided && !clientOrderIdProvided) {
+    throw new Error(
+      'cancelMEOrder requires either `orderId` or `clientOrderId`',
+    );
+  }
 
-  const useOrderId = !!params.orderId;
-  const signedOrderId = useOrderId ? BigInt(params.orderId!) : BigInt(0);
-  const signedClOrdId = useOrderId ? BigInt(0) : BigInt(params.clientOrderId!);
+  // When orderId is set, it is the canonical handle — drop clientOrderId
+  // from both the signature and the request body. Forwarding both creates
+  // ambiguity in server logging and would let a malicious / buggy caller
+  // sign one order id while requesting cancellation by a different
+  // (client-supplied) id. (PRO-81 C.2.26)
+  const signedOrderId = orderIdProvided ? BigInt(params.orderId!) : BigInt(0);
+  const signedClOrdId =
+    !orderIdProvided && clientOrderIdProvided
+      ? BigInt(params.clientOrderId!)
+      : BigInt(0);
 
-  const { serializedSignature } = await signOrderCancel(
+  const signerAddress = await params.signer.getAddress();
+  const defaultDeadline =
+    Math.floor(Date.now() / 1000) + DEFAULT_DEADLINE_SECONDS;
+  const deadline = params.deadline ?? defaultDeadline;
+  const nonce = params.nonce ?? nextNonce(signerAddress);
+
+  const signature = await signMEOrderCancel(
     params.signer,
     reyaChainId,
     params.accountId,
@@ -161,7 +374,7 @@ export const cancelSpotOrder = async (
     signedOrderId,
     signedClOrdId,
     nonce,
-    expiresAfter,
+    deadline,
   );
 
   const apiConfig = new Configuration({
@@ -172,54 +385,54 @@ export const cancelSpotOrder = async (
 
   const response = await orderEntryApi.cancelOrder({
     cancelOrderRequest: {
-      symbol: params.symbol,
       accountId: params.accountId,
-      orderId: useOrderId ? params.orderId : undefined,
-      clientOrderId: useOrderId ? undefined : params.clientOrderId,
-      signature: serializedSignature,
+      symbol: params.symbol,
+      orderId: orderIdProvided ? params.orderId!.trim() : undefined,
+      // See validation block above: clientOrderId is suppressed in the body
+      // whenever orderId is the canonical handle.
+      clientOrderId: orderIdProvided ? undefined : params.clientOrderId?.trim(),
+      signature: signature,
       nonce: nonce.toString(),
-      expiresAfter,
+      deadline,
     },
   });
 
   return response;
 };
 
-export type MassCancelSpotOrdersParams = {
-  signer: Signer | JsonRpcSigner;
-  accountId: number;
-  symbol?: string;
-  marketId?: number;
-  expiresAfterSeconds?: number;
-};
-
-export const massCancelSpotOrders = async (
-  params: MassCancelSpotOrdersParams,
+export const massCancelMEOrders = async (
+  params: MassCancelMEOrdersParams,
 ): Promise<MassCancelResponse> => {
+  const reyaChainId = getReyaNetwork();
+  const config = getSdkConfig();
+
+  // Validation: symbol and marketId must be provided together or not at all.
+  // The API resolves a symbol → marketId server-side; the signature locks
+  // marketId at sign time. If only one is provided we'd ship a body whose
+  // server-derived marketId doesn't match the signed marketId (=> opaque
+  // signature-validation failure), or — worse — a body that silently
+  // cancels the wrong market. (PRO-81 C.2.26)
   const hasSymbol = params.symbol !== undefined;
   const hasMarketId = params.marketId !== undefined;
   if (hasSymbol !== hasMarketId) {
     throw new Error(
-      'symbol and marketId must be provided together (or both omitted to cancel across all markets)',
+      'massCancelMEOrders requires both `symbol` and `marketId` together, or neither (to mass-cancel across all markets)',
     );
   }
 
-  const reyaChainId = getReyaNetwork();
-  const config = getSdkConfig();
-
-  const nowMs = Date.now();
-  const expiresAfter =
-    Math.floor(nowMs / 1000) +
-    (params.expiresAfterSeconds ?? DEFAULT_CANCEL_DEADLINE_SECONDS);
-  const nonce = BigInt(nowMs);
+  const signerAddress = await params.signer.getAddress();
+  const defaultDeadline =
+    Math.floor(Date.now() / 1000) + DEFAULT_DEADLINE_SECONDS;
+  const deadline = params.deadline ?? defaultDeadline;
+  const nonce = params.nonce ?? nextNonce(signerAddress);
 
-  const { serializedSignature } = await signMassCancel(
+  const signature = await signMEMassCancel(
     params.signer,
     reyaChainId,
     params.accountId,
     params.marketId ?? 0,
     nonce,
-    expiresAfter,
+    deadline,
   );
 
   const apiConfig = new Configuration({
@@ -230,11 +443,407 @@ export const massCancelSpotOrders = async (
 
   const response = await orderEntryApi.cancelAll({
     massCancelRequest: {
+      accountId: params.accountId,
+      symbol: params.symbol,
+      signature: signature,
+      nonce: nonce.toString(),
+      deadline,
+    },
+  });
+
+  return response;
+};
+
+// Convenience wrapper: LIMIT order with IOC timeInForce. UI teams may call
+// createOrder directly with `timeInForce: TimeInForce.IOC` instead.
+export const createIOCOrder = async (
+  params: Omit<CreateOrderParams, 'timeInForce'>,
+): Promise<CreateOrderResponse> => {
+  return createOrder({
+    ...params,
+    timeInForce: TimeInForce.IOC,
+  });
+};
+
+export type ClosePositionParams = {
+  signer: Signer | JsonRpcSigner;
+  accountId: number;
+  exchangeId: number;
+  marketId: number;
+  /** Closing direction — opposite of the current position side. */
+  isBuy: boolean;
+  /** Slippage gate. */
+  limitPx: string;
+  /** Position size to close. */
+  qty: string;
+  symbol: string;
+  clientOrderId?: string;
+  /** Unix seconds; EIP-712 signature deadline. Defaults to now + 30s. */
+  deadline?: number;
+  /** Optional explicit nonce override; otherwise generated per-signer. */
+  nonce?: bigint;
+};
+
+// Convenience wrapper: close a perp position by submitting a reduce-only LIMIT
+// IOC. The ME will bust fills that overflow the position at the clearing layer.
+export const closePosition = async (
+  params: ClosePositionParams,
+): Promise<CreateOrderResponse> => {
+  return createOrder({
+    signer: params.signer,
+    accountId: params.accountId,
+    exchangeId: params.exchangeId,
+    marketId: params.marketId,
+    isBuy: params.isBuy,
+    limitPx: params.limitPx,
+    qty: params.qty,
+    symbol: params.symbol,
+    orderType: OrderType.LIMIT,
+    timeInForce: TimeInForce.IOC,
+    reduceOnly: true,
+    clientOrderId: params.clientOrderId,
+    deadline: params.deadline,
+    nonce: params.nonce,
+  });
+};
+
+export type CancelAllAfterParams = {
+  signer: Signer | JsonRpcSigner;
+  accountId: number;
+  /**
+   * Countdown duration in milliseconds. `0` disarms; any non-zero value must
+   * be within [5000, 60000] and arms a fresh countdown of that duration,
+   * replacing any previously armed one (re-arming = the refresh/heartbeat).
+   * Recommended pattern: arm with 30000 and refresh every ~10-15s.
+   */
+  timeoutMs: number;
+  deadline?: number;
+  /**
+   * Optional explicit nonce; otherwise a per-signer monotonic µs value. Must be
+   * strictly greater than the signer's last accepted nonce in the matching
+   * engine. See `cancelAllAfter` below for retry semantics; the default
+   * `nextNonce` advances automatically.
+   */
+  nonce?: bigint;
+};
+
+const CANCEL_ALL_AFTER_TIMEOUT_MIN_MS = 5000;
+const CANCEL_ALL_AFTER_TIMEOUT_MAX_MS = 60000;
+
+/**
+ * Arm, refresh, or disarm the account-scoped cancel-on-disconnect
+ * dead-man's-switch. The countdown lives in the matching engine; when it
+ * elapses, all of the account's open orders (all markets) are mass-cancelled.
+ *
+ * The matching engine owns nonce replay protection. A request rejected by
+ * local validation before it is forwarded does not consume its nonce. Once a
+ * request is sent, a transport failure may be outcome-unknown, and a request
+ * that reaches the matching engine may record its nonce in the WAL. Retry with
+ * a strictly higher nonce after an ME response or transport uncertainty.
+ * Reusing an explicit nonce is safe only after a definite local pre-forward
+ * rejection. When `nonce` is omitted, `nextNonce` advances automatically.
+ */
+export const cancelAllAfter = async (
+  params: CancelAllAfterParams,
+): Promise<CancelAllAfterResponse> => {
+  const reyaChainId = getReyaNetwork();
+  const config = getSdkConfig();
+
+  // Fail fast before signing or sending a request the server will reject with
+  // INPUT_VALIDATION_ERROR anyway.
+  if (
+    !Number.isInteger(params.timeoutMs) ||
+    params.timeoutMs < 0 ||
+    (params.timeoutMs !== 0 &&
+      (params.timeoutMs < CANCEL_ALL_AFTER_TIMEOUT_MIN_MS ||
+        params.timeoutMs > CANCEL_ALL_AFTER_TIMEOUT_MAX_MS))
+  ) {
+    throw new Error(
+      `cancelAllAfter timeoutMs must be 0 (disarm) or between ${CANCEL_ALL_AFTER_TIMEOUT_MIN_MS} and ${CANCEL_ALL_AFTER_TIMEOUT_MAX_MS} milliseconds`,
+    );
+  }
+
+  const signerAddress = await params.signer.getAddress();
+  const defaultDeadline =
+    Math.floor(Date.now() / 1000) + DEFAULT_DEADLINE_SECONDS;
+  const deadline = params.deadline ?? defaultDeadline;
+  const nonce = params.nonce ?? nextNonce(signerAddress);
+
+  const signature = await signMECancelAllAfter(
+    params.signer,
+    reyaChainId,
+    params.accountId,
+    params.timeoutMs,
+    nonce,
+    deadline,
+  );
+
+  const apiConfig = new Configuration({
+    basePath: `${config.apiEndpoint}/v2`,
+  });
+
+  const orderEntryApi = new OrderEntryApi(apiConfig);
+
+  const response = await orderEntryApi.cancelAllAfter({
+    cancelAllAfterRequest: {
+      accountId: params.accountId,
+      timeoutMs: params.timeoutMs,
+      signature: signature,
+      nonce: nonce.toString(),
+      signerWallet: signerAddress,
+      deadline,
+    },
+  });
+
+  return response;
+};
+
+type ModifyMEOrderCommonParams = {
+  signer: Signer | JsonRpcSigner;
+  accountId: number;
+  exchangeId: number;
+  /** Unified market id: core_id for perp, core_id + 1e10 for spot. */
+  marketId: number;
+  symbol: string;
+  /** Targeting: provide `orderId`, or a non-zero `clientOrderId`; both may be provided. */
+  orderId?: string;
+  clientOrderId?: string;
+  /**
+   * Full post-modify order state. The SDK does not fetch the resting order —
+   * the caller supplies every field, and the EIP-712 signature commits to
+   * all of them. Modifiable fields are limitPx, qty, postOnly, expiresAfter,
+   * and triggerPx. There is no omitted-means-inherited shorthand, so unchanged
+   * values must be restated explicitly; LIMIT orders omit triggerPx and sign
+   * triggerPrice = 0. Non-modifiable fields (isBuy, orderType, timeInForce,
+   * reduceOnly) must match the resting order's values.
+   */
+  isBuy: boolean;
+  limitPx: string;
+  /**
+   * TOTAL order quantity (not remaining). Type-conditional, mirroring the
+   * create-trigger path:
+   *  - LIMIT: REQUIRED — must exceed the order's cumQty; signed as the total
+   *    post-modify quantity.
+   *  - STOP_LOSS / TAKE_PROFIT: OMIT — the signed quantity restates the
+   *    ±int256.max full-position sentinel (sign from `isBuy`; protect the whole
+   *    position) and qty is dropped from the wire payload. Passing a qty on a
+   *    trigger modify throws (the backend rejects it).
+   */
+  qty?: string;
+  /** Immutable; restate the resting order's value. */
+  timeInForce: TimeInForce;
+  triggerPx?: string;
+  /** Unix seconds. Post-modify on-chain order lifetime; omit for no-expiry orders. */
+  expiresAfter?: number;
+  /**
+   * Resting order's clientOrderId, signed into OrderDetails.clientOrderId.
+   * If orderId is absent this is also the lookup target and must be non-zero.
+   * If orderId is present, orderId targets and clientOrderId only restates the
+   * immutable; omit it when the resting order has no client id.
+   */
+  /** Unix seconds; EIP-712 signature deadline. Defaults to now + 30s. */
+  deadline?: number;
+  /**
+   * Seconds of settlement headroom a GTT `expiresAfter` must outlast. Defaults
+   * to the production value; set it only for a deployment running a different
+   * one.
+   */
+  settlementHeadroomSeconds?: number;
+  /** Optional explicit nonce; otherwise per-signer monotonic µs. */
+  nonce?: bigint;
+};
+
+// Keep the helper's discriminant/flag rules tied to the generated wire types.
+// LIMIT reduceOnly retains the helper's false default; raw requests require it.
+type LimitModifyMEOrderFields = Pick<
+  Extract<ModifyOrderRequest, { orderType: 'LIMIT' }>,
+  'orderType' | 'postOnly'
+> & { reduceOnly?: boolean };
+type TriggerModifyMEOrderFields = Pick<
+  Extract<ModifyOrderRequest, { orderType: 'STOP_LOSS' | 'TAKE_PROFIT' }>,
+  'orderType' | 'postOnly' | 'reduceOnly'
+>;
+
+export type ModifyMEOrderParams = ModifyMEOrderCommonParams &
+  (LimitModifyMEOrderFields | TriggerModifyMEOrderFields);
+
+/**
+ * Modify a resting order in place. The order keeps its orderId and
+ * clientOrderId; queue priority is preserved only for a qty decrease at an
+ * unchanged limitPx. The params carry the COMPLETE post-modify state; a request
+ * restating the resting order's exact current state is rejected with
+ * EMPTY_MODIFY_ERROR.
+ */
+export const modifyMEOrder = async (
+  params: ModifyMEOrderParams,
+): Promise<ModifyOrderResponse> => {
+  assertNonZeroClientOrderId(params.clientOrderId);
+
+  const reyaChainId = getReyaNetwork();
+  const config = getSdkConfig();
+
+  // Validate targeting before signing so misuse doesn't burn a nonce. `orderId`
+  // wins when both are present; `clientOrderId` still rides along as the
+  // restated signed immutable.
+  const hasOrderId = isProvidedNonZeroId(params.orderId);
+  const hasClientOrderIdTarget = isProvidedNonZeroId(params.clientOrderId);
+  if (!hasOrderId && !hasClientOrderIdTarget) {
+    throw new Error(
+      'modifyMEOrder requires `orderId` or a non-zero `clientOrderId`',
+    );
+  }
+
+  const isTrigger =
+    params.orderType === OrderType.STOP_LOSS ||
+    params.orderType === OrderType.TAKE_PROFIT;
+
+  if (
+    isTrigger &&
+    (params.reduceOnly !== undefined || params.postOnly !== undefined)
+  ) {
+    throw new Error('reduceOnly and postOnly must be omitted for TP/SL orders');
+  }
+
+  if (!isTrigger && typeof params.postOnly !== 'boolean') {
+    throw new Error('postOnly is required for LIMIT modifications');
+  }
+
+  // Convert once while validation is still side-effect free. Runtime callers
+  // can bypass the TypeScript enum; reject those values before resolving the
+  // signer or advancing its nonce.
+  const onChainTimeInForce = toOnChainTimeInForce(params.timeInForce);
+
+  // triggerPx is required for trigger orders — without it we would silently
+  // sign triggerPrice=0. Fail at the SDK boundary (mirrors the cancel/mass-
+  // cancel SDK-boundary validation) instead of signing a 0-trigger order.
+  if (isTrigger && params.triggerPx === undefined) {
+    throw new Error(`triggerPx is required for ${params.orderType} orders`);
+  }
+
+  // qty is type-conditional (mirrors the create-trigger path):
+  //  - STOP_LOSS / TAKE_PROFIT: qty MUST be omitted; the signed quantity is
+  //    the ±int256.max full-position sentinel (sign from `isBuy`) and qty is
+  //    dropped from the wire below. The backend rejects a trigger modify that
+  //    carries qty.
+  //  - LIMIT: qty is REQUIRED and signed as the total post-modify quantity.
+  // Validated up front (before a nonce is minted), like the triggerPx guard.
+  if (isTrigger && params.qty !== undefined) {
+    throw new Error(
+      `qty must be omitted for ${params.orderType} orders (the signed quantity is the full-position sentinel)`,
+    );
+  }
+  if (!isTrigger && params.qty === undefined) {
+    throw new Error('qty is required when modifying a LIMIT order');
+  }
+
+  // Only GTT carries a lifetime, for triggers as for book orders. The modify
+  // restates that pair immutably, so an inconsistent one can only be refused by
+  // the backend — catch it here, before a nonce is minted and burnt.
+  const hasExpiry =
+    params.expiresAfter !== undefined && params.expiresAfter !== 0;
+  if (params.timeInForce === TimeInForce.GTT && !hasExpiry) {
+    throw new Error('expiresAfter is required for GTT orders');
+  }
+  if (params.timeInForce !== TimeInForce.GTT && hasExpiry) {
+    throw new Error(
+      'expiresAfter must be omitted for IOC / GTC orders — only GTT carries a lifetime',
+    );
+  }
+
+  if (params.reduceOnly && params.marketId >= SPOT_MARKET_ID_OFFSET) {
+    throw new Error('reduceOnly is not supported for spot markets');
+  }
+
+  // Same venue admission rule as the create path: a restated GTT lifetime must
+  // still outlast the settlement headroom.
+  if (hasExpiry) {
+    assertSettlementHeadroom(
+      params.expiresAfter!,
+      params.settlementHeadroomSeconds,
+    );
+  }
+
+  const signerAddress = await params.signer.getAddress();
+  const defaultDeadline =
+    Math.floor(Date.now() / 1000) + DEFAULT_DEADLINE_SECONDS;
+  const deadline = params.deadline ?? defaultDeadline;
+  const nonce = params.nonce ?? nextNonce(signerAddress);
+
+  // Signed quantity: a trigger restates the ±int256.max full-position sentinel
+  // (sign from `isBuy`; reya-network #738); a LIMIT signs ±qty. Sign over the
+  // exact integers the off-chain verifier reconstructs
+  // with `parseUnits(str, 18)` (signature-validation/index.ts). The previous
+  // `scale(18)(parseFloat(str))` diverged for |x| < 1e-6 or >= 1e21 (parseFloat
+  // renders those in exponential form, which `scale` mishandles) → a signature
+  // mismatch on extreme sizes. `parseUnits` is exact.
+  const quantity = isTrigger
+    ? fullPositionStopQuantity(params.isBuy)
+    : params.isBuy
+      ? parseUnits(params.qty!, 18)
+      : -parseUnits(params.qty!, 18);
+  const limitPrice = parseUnits(params.limitPx, 18);
+  const triggerPrice = params.triggerPx
+    ? parseUnits(params.triggerPx, 18)
+    : BigInt(0);
+
+  const { serializedSignature } = await signOrder(params.signer, reyaChainId, {
+    accountId: params.accountId,
+    marketId: params.marketId,
+    exchangeId: params.exchangeId,
+    orderType: toOnChainOrderType(params.orderType),
+    quantity,
+    limitPrice,
+    triggerPrice,
+    timeInForce: onChainTimeInForce,
+    clientOrderId: BigInt(params.clientOrderId ?? '0'),
+    reduceOnly: isTrigger ? false : params.reduceOnly ?? false,
+    postOnly: isTrigger ? false : params.postOnly!,
+    expiresAfter: BigInt(params.expiresAfter ?? 0),
+    nonce,
+    deadline,
+  });
+
+  const apiConfig = new Configuration({
+    basePath: `${config.apiEndpoint}/v2`,
+  });
+
+  const orderEntryApi = new OrderEntryApi(apiConfig);
+
+  // Full restate: the body must carry the COMPLETE signed OrderDetails so it
+  // reproduces the signed digest exactly. The off-chain verifier
+  // `isModifyOrderSignatureValid` reconstructs from these fields with
+  // `timeInForce` required and never defaulted, so an omitted one cannot
+  // verify at all. The immutables are restated at the resting order's values;
+  // the ME rejects a mismatch with MODIFY_IMMUTABLE_MISMATCH.
+  const response = await orderEntryApi.modifyOrder({
+    modifyOrderRequest: {
+      ...(hasOrderId ? { orderId: params.orderId!.trim() } : {}),
+      ...(hasClientOrderIdTarget
+        ? { clientOrderId: params.clientOrderId!.trim() }
+        : {}),
       symbol: params.symbol,
       accountId: params.accountId,
+      exchangeId: params.exchangeId,
+      isBuy: params.isBuy,
+      ...(params.orderType === OrderType.LIMIT
+        ? {
+            orderType: params.orderType,
+            reduceOnly: params.reduceOnly ?? false,
+            postOnly: params.postOnly,
+          }
+        : { orderType: params.orderType }),
+      timeInForce: params.timeInForce,
+      ...(params.triggerPx !== undefined && { triggerPx: params.triggerPx }),
+      limitPx: params.limitPx,
+      // qty is omitted on a trigger modify (guaranteed undefined by the
+      // isTrigger guard above); sent for a LIMIT modify.
+      ...(params.qty !== undefined && { qty: params.qty }),
+      ...(params.expiresAfter !== undefined &&
+        params.expiresAfter !== 0 && { expiresAfter: params.expiresAfter }),
       signature: serializedSignature,
       nonce: nonce.toString(),
-      expiresAfter,
+      signerWallet: signerAddress,
+      deadline,
     },
   });