@lifi/perps-sdk-provider-lighter 0.2.0-alpha.0

package/src/utils/mapFill.ts

@@ -0,0 +1,108 @@
+import {
+  classifyFillFromPosition,
+  ExplorerChainId,
+  explorerTxUrl,
+} from '@lifi/perps-sdk'
+import type { Fill, MarketDisplay } from '@lifi/perps-types'
+import {
+  FillStatus,
+  LiquidityRole,
+  OrderSide,
+  OrderType,
+} from '@lifi/perps-types'
+import Big from 'big.js'
+import type { LtTrade } from '../types/index.js'
+
+/**
+ * Realized PnL on a position-reducing fill, derived from the pre-trade entry
+ * basis. Returns `undefined` for opens/increases (nothing closes) or when the
+ * entry-quote snapshot is absent, and `null` when the closed portion realizes
+ * exactly zero — mirroring the Hyperliquid mapper's `null`-for-zero convention.
+ */
+const deriveRealizedPnl = (
+  startPosition: string,
+  entryQuoteBefore: string | undefined,
+  fillSize: string,
+  fillPrice: string,
+  isBuyer: boolean
+): string | null | undefined => {
+  if (entryQuoteBefore === undefined) {
+    return undefined
+  }
+  const start = new Big(startPosition)
+  if (start.eq(0)) {
+    return undefined
+  }
+  const isLong = start.gt(0)
+  const reducing = isLong ? !isBuyer : isBuyer
+  if (!reducing) {
+    return undefined
+  }
+
+  const absStart = start.abs()
+  const fill = new Big(fillSize)
+  // A fill larger than the open size flips the position; only the portion that
+  // unwinds the existing position realizes PnL.
+  const closedSize = fill.gt(absStart) ? absStart : fill
+  const avgEntry = new Big(entryQuoteBefore).abs().div(absStart)
+  const price = new Big(fillPrice)
+  const pnl = isLong
+    ? price.minus(avgEntry).times(closedSize)
+    : avgEntry.minus(price).times(closedSize)
+  return pnl.eq(0) ? null : pnl.toString()
+}
+
+/**
+ * Map a raw Lighter trade to the generic Fill type.
+ * @param accountIndex - The viewer's Lighter account index (selects buy/sell side and maker/taker role).
+ * @param market - Backend-resolved market identity for `trade.market_id`.
+ * @public
+ */
+export const mapFill = (
+  trade: LtTrade,
+  accountIndex: number,
+  market: MarketDisplay
+): Fill => {
+  const isBuyer = trade.bid_account_id === accountIndex
+  const isMaker =
+    (trade.is_maker_ask && !isBuyer) || (!trade.is_maker_ask && isBuyer)
+
+  // Lighter publishes both counterparties' position-before snapshots on every
+  // trade row; reading the wrong one mis-classifies when they differ.
+  const startPosition = isMaker
+    ? trade.maker_position_size_before
+    : trade.taker_position_size_before
+  const entryQuoteBefore = isMaker
+    ? trade.maker_entry_quote_before
+    : trade.taker_entry_quote_before
+
+  return {
+    id: trade.trade_id.toString(),
+    orderId: String(isBuyer ? trade.bid_id : trade.ask_id),
+    market,
+    side: isBuyer ? OrderSide.BUY : OrderSide.SELL,
+    type: OrderType.LIMIT,
+    size: trade.size,
+    price: trade.price,
+    status: FillStatus.FILLED,
+    liquidity: isMaker ? LiquidityRole.MAKER : LiquidityRole.TAKER,
+    fee: isMaker ? trade.maker_fee?.toString() : trade.taker_fee?.toString(),
+    realizedPnl: deriveRealizedPnl(
+      startPosition,
+      entryQuoteBefore,
+      trade.size,
+      trade.price,
+      isBuyer
+    ),
+    startPosition,
+    // `classifyFillFromPosition` takes an HL-encoded side: `'B'` for buy,
+    // anything else for sell.
+    classification: classifyFillFromPosition(
+      startPosition,
+      isBuyer ? 'B' : 'A',
+      trade.size
+    ),
+    createdAt: new Date(trade.timestamp).toISOString(),
+    explorerLink: explorerTxUrl(ExplorerChainId.LIGHTER, trade.tx_hash),
+  }
+}

package/src/utils/mapOpenPositions.ts

@@ -0,0 +1,18 @@
+import type { MarketDisplay, Position } from '@lifi/perps-types'
+import type { LtAccountPosition } from '../types/index.js'
+import { mapPosition } from './mapPosition.js'
+
+/**
+ * Map raw Lighter account positions to open {@link Position}s, dropping
+ * zero-size rows. Only valid for payloads carrying the full position set —
+ * dropping zeros from a partial frame would make closes unobservable.
+ *
+ * @public
+ */
+export const mapOpenPositions = (
+  positions: LtAccountPosition[],
+  resolveMarket: (marketId: number) => MarketDisplay
+): Position[] =>
+  positions
+    .filter((p) => Number.parseFloat(p.position) !== 0)
+    .map((p) => mapPosition(p, resolveMarket(p.market_id)))

package/src/utils/mapOrder.ts

@@ -0,0 +1,258 @@
+import { isActiveOrderStatus } from '@lifi/perps-sdk'
+import type {
+  MarketDisplay,
+  OpenOrder,
+  Order,
+  TriggerOrder,
+} from '@lifi/perps-types'
+import {
+  OrderSide,
+  OrderStatus,
+  OrderType,
+  TimeInForce,
+} from '@lifi/perps-types'
+import type { LtOrder } from '../types/index.js'
+
+// Lighter's `type` enum uses hyphens in the OpenAPI spec but earlier API
+// versions emitted underscores. Tolerate both so we don't silently fall
+// through to LIMIT for stop/take-profit orders.
+const mapOrderType = (ltType: string): OrderType => {
+  const normalized = ltType.replace(/-/g, '_')
+  const map: Record<string, OrderType> = {
+    limit: OrderType.LIMIT,
+    market: OrderType.MARKET,
+    stop_loss: OrderType.STOP_MARKET,
+    stop_loss_limit: OrderType.STOP_LIMIT,
+    take_profit: OrderType.TAKE_PROFIT_MARKET,
+    take_profit_limit: OrderType.TAKE_PROFIT_LIMIT,
+  }
+  return map[normalized] ?? OrderType.LIMIT
+}
+
+const mapTimeInForce = (tif: string): TimeInForce | undefined => {
+  switch (tif.replace(/-/g, '_')) {
+    case 'good_till_time':
+      return TimeInForce.GTT
+    case 'immediate_or_cancel':
+      return TimeInForce.IOC
+    case 'post_only':
+      return TimeInForce.POST_ONLY
+    default:
+      return undefined
+  }
+}
+
+const mapOrderStatus = (status: string): OrderStatus => {
+  if (
+    status === 'open' ||
+    status === 'in-progress' ||
+    status === 'in_progress'
+  ) {
+    return OrderStatus.OPEN
+  }
+  if (status === 'pending') {
+    return OrderStatus.PENDING
+  }
+  if (status === 'filled') {
+    return OrderStatus.FILLED
+  }
+  if (status.startsWith('canceled')) {
+    return OrderStatus.CANCELLED
+  }
+  return OrderStatus.OPEN
+}
+
+/**
+ * Map a raw Lighter order status to a short English sentence describing
+ * *why* the order ended in a terminal non-FILLED state. Non-terminal
+ * statuses, plain `filled`, and unknown values return `undefined`.
+ * @public
+ */
+export const mapStatusReason = (status: string): string | undefined => {
+  switch (status) {
+    case 'canceled':
+      return 'Order cancelled.'
+    case 'canceled-post-only':
+      return 'Order cancelled: post-only order would have crossed the book.'
+    case 'canceled-reduce-only':
+      return 'Order cancelled: would not reduce your position.'
+    case 'canceled-position-not-allowed':
+      return 'Order cancelled: position not allowed.'
+    case 'canceled-margin-not-allowed':
+      return 'Order cancelled: insufficient margin.'
+    case 'canceled-too-much-slippage':
+      return 'Order cancelled: slippage exceeded tolerance.'
+    case 'canceled-not-enough-liquidity':
+      return 'Order cancelled: not enough liquidity to fill.'
+    case 'canceled-self-trade':
+      return 'Order cancelled: would self-trade against your own resting order.'
+    case 'canceled-expired':
+      return 'Order expired.'
+    case 'canceled-oco':
+      return 'Order cancelled: sibling OCO order filled or cancelled first.'
+    case 'canceled-child':
+      return 'Order cancelled: parent order was cancelled.'
+    case 'canceled-liquidation':
+      return 'Order cancelled: account was liquidated.'
+    case 'canceled-invalid-balance':
+      return 'Order cancelled: invalid balance.'
+    default:
+      return undefined
+  }
+}
+
+/**
+ * True for order types Lighter exposes as TP/SL legs. Mirrors the
+ * Hyperliquid helper of the same name so the backend can split a raw
+ * Lighter order list into the same `openOrders` / `triggerOrders`
+ * buckets the SDK declares on `OrdersResponse`.
+ * @public
+ */
+export const isTriggerType = (type: OrderType): boolean =>
+  type === OrderType.TAKE_PROFIT_MARKET ||
+  type === OrderType.TAKE_PROFIT_LIMIT ||
+  type === OrderType.STOP_MARKET ||
+  type === OrderType.STOP_LIMIT
+
+/**
+ * Decide whether a raw Lighter order belongs in the cross-provider
+ * `triggerOrders` bucket. Single source of truth for both the REST
+ * `getOrders` path and the `account_all_orders` WS handler.
+ *
+ * Authoritative signals, in order:
+ *   1. `trigger_status` — Lighter's own enum. `'ready' | 'mark-price' |
+ *      'parent-order'` all mean "this order has trigger semantics" (TP/SL
+ *      waiting on price, or a TP/SL leg of a parent placeOrder). `'twap'`
+ *      is intentionally excluded — TWAP child orders are scheduled resting
+ *      limits, not TP/SL triggers. `'na'` is "regular order".
+ *   2. `trigger_price > 0` — catches cases where `trigger_status`
+ *      momentarily lags during state transitions (e.g. right after an OCO
+ *      sibling cancels).
+ *   3. `type` — final fallback via the mapped `OrderType`.
+ * @public
+ */
+export const isTriggerOrder = (raw: LtOrder): boolean => {
+  if (
+    raw.trigger_status === 'ready' ||
+    raw.trigger_status === 'mark-price' ||
+    raw.trigger_status === 'parent-order'
+  ) {
+    return true
+  }
+  if (raw.trigger_price !== '' && parseFloat(raw.trigger_price) > 0) {
+    return true
+  }
+  return isTriggerType(mapOrderType(raw.type))
+}
+
+/**
+ * Map a raw Lighter trigger order (stop/take-profit, market or limit) to
+ * the generic `TriggerOrder` shape. For market variants the `limitPrice`
+ * field is omitted; for limit variants `order.price` is the limit and
+ * `order.trigger_price` is the activation level.
+ * @public
+ */
+export const mapTriggerOrder = (
+  order: LtOrder,
+  market: MarketDisplay
+): TriggerOrder => {
+  const type = mapOrderType(order.type)
+  const isLimit =
+    type === OrderType.TAKE_PROFIT_LIMIT || type === OrderType.STOP_LIMIT
+  return {
+    // `order_index` is the per-(account, market) numeric id Lighter's L2
+    // mutating txs (cancel, modify) require. The matching-engine string
+    // label `order_id` is internal to the SDK provider and never crosses
+    // this boundary — combined with `market.id` (=market_index), the
+    // numeric `order_index` uniquely pins a Lighter order.
+    orderId: String(order.order_index),
+    market,
+    type,
+    size: order.initial_base_amount,
+    triggerPrice: order.trigger_price,
+    ...(isLimit ? { limitPrice: order.price } : {}),
+    createdAt: new Date(order.created_at * 1000).toISOString(),
+  }
+}
+
+/**
+ * Map a raw Lighter order to the generic OpenOrder type.
+ * @param market - Backend-resolved market identity for `order.market_index`.
+ * @public
+ */
+export const mapOrder = (order: LtOrder, market: MarketDisplay): OpenOrder => ({
+  orderId: String(order.order_index),
+  market,
+  side: order.is_ask ? OrderSide.SELL : OrderSide.BUY,
+  type: mapOrderType(order.type),
+  size: order.initial_base_amount,
+  price: order.price,
+  filledSize: order.filled_base_amount,
+  reduceOnly: order.reduce_only,
+  createdAt: new Date(order.created_at * 1000).toISOString(),
+})
+
+/**
+ * Walk a flat list of raw Lighter orders and bucket each into the
+ * `OpenOrder` / `TriggerOrder` arrays the cross-provider `OrdersResponse`
+ * declares, plus a `terminated` list of orderIds whose status has reached
+ * a terminal state (filled / cancelled / rejected / expired) — consumers
+ * applying WS deltas evict those from the cached buckets. REST callers
+ * see `terminated: []` because `accountActiveOrders` returns active only.
+ * An order whose market the resolver does not know is skipped.
+ * @public
+ */
+export const classifyAndMapOrders = (
+  orders: LtOrder[],
+  resolveMarket: (marketIndex: number) => MarketDisplay | undefined
+): {
+  openOrders: OpenOrder[]
+  triggerOrders: TriggerOrder[]
+  terminated: string[]
+} => {
+  const openOrders: OpenOrder[] = []
+  const triggerOrders: TriggerOrder[] = []
+  const terminated: string[] = []
+  for (const raw of orders) {
+    const orderId = String(raw.order_index)
+    if (!isActiveOrderStatus(mapOrderStatus(raw.status))) {
+      terminated.push(orderId)
+      continue
+    }
+    const market = resolveMarket(raw.market_index)
+    if (market === undefined) {
+      continue
+    }
+    if (isTriggerOrder(raw)) {
+      triggerOrders.push(mapTriggerOrder(raw, market))
+    } else {
+      openOrders.push(mapOrder(raw, market))
+    }
+  }
+  return { openOrders, triggerOrders, terminated }
+}
+
+/**
+ * Map a raw Lighter order to the rich Order type — adds status, time-in-force
+ * and remaining/filled sizes on top of the OpenOrder fields.
+ * @public
+ */
+export const mapOrderDetail = (
+  order: LtOrder,
+  market: MarketDisplay
+): Order => ({
+  orderId: String(order.order_index),
+  market,
+  side: order.is_ask ? OrderSide.SELL : OrderSide.BUY,
+  type: mapOrderType(order.type),
+  price: order.price,
+  originalSize: order.initial_base_amount,
+  remainingSize: order.remaining_base_amount,
+  filledSize: order.filled_base_amount,
+  timeInForce: mapTimeInForce(order.time_in_force),
+  reduceOnly: order.reduce_only,
+  status: mapOrderStatus(order.status),
+  statusReason: mapStatusReason(order.status),
+  createdAt: new Date(order.created_at * 1000).toISOString(),
+  updatedAt: new Date(order.updated_at * 1000).toISOString(),
+})

package/src/utils/mapPosition.ts

@@ -0,0 +1,42 @@
+import type { MarketDisplay, Position } from '@lifi/perps-types'
+import { MarginMode, PositionSide } from '@lifi/perps-types'
+import type { LtAccountPosition } from '../types/index.js'
+import { LT_MARGIN_MODE_ISOLATED } from '../types/index.js'
+
+/**
+ * Map a raw Lighter account position to the generic Position type.
+ * @param market - Backend-resolved market identity for `pos.market_id`.
+ * @public
+ */
+export const mapPosition = (
+  pos: LtAccountPosition,
+  market: MarketDisplay
+): Position => {
+  const size = parseFloat(pos.position)
+  const isIsolated = pos.margin_mode === LT_MARGIN_MODE_ISOLATED
+
+  // `allocated_margin` is only populated for isolated positions (always "0"
+  // on cross accounts). For cross, derive margin as
+  // `position_value × initial_margin_fraction / 100` (IMF is in percent).
+  const positionValue = Math.abs(parseFloat(pos.position_value))
+  const imf = parseFloat(pos.initial_margin_fraction)
+  const marginUsed = isIsolated
+    ? pos.allocated_margin
+    : ((positionValue * imf) / 100).toString()
+
+  return {
+    market,
+    side: pos.sign >= 0 ? PositionSide.LONG : PositionSide.SHORT,
+    size: Math.abs(size).toString(),
+    entryPrice: pos.avg_entry_price,
+    markPrice:
+      pos.position_value === '0' || size === 0
+        ? '0'
+        : (parseFloat(pos.position_value) / Math.abs(size)).toString(),
+    liquidationPrice: pos.liquidation_price,
+    unrealizedPnl: pos.unrealized_pnl,
+    leverage: imf > 0 ? Math.round(100 / imf) : 1,
+    marginUsed,
+    marginMode: isIsolated ? MarginMode.ISOLATED : MarginMode.CROSS,
+  }
+}

package/src/utils/ohlcvInterval.ts

@@ -0,0 +1,34 @@
+import { PerpsError } from '@lifi/perps-sdk'
+import { PerpsErrorCode } from '@lifi/perps-types'
+
+/**
+ * Map our `OhlcvInterval` literal to Lighter's `resolution` enum.
+ *
+ * Lighter exposes only the timeframes listed below. SDK intervals without a
+ * direct match (3m, 2h, 8h, 3d, 1M) raise a validation error rather than
+ * silently rounding — the caller picks a supported timeframe.
+ */
+const LIGHTER_SUPPORTED_INTERVALS: Record<string, string> = {
+  '1m': '1m',
+  '5m': '5m',
+  '15m': '15m',
+  '30m': '30m',
+  '1h': '1h',
+  '4h': '4h',
+  '12h': '12h',
+  '1d': '1d',
+  '1w': '1w',
+}
+
+/** @public */
+export const mapInterval = (interval: string): string => {
+  const resolution = LIGHTER_SUPPORTED_INTERVALS[interval]
+  if (!resolution) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Lighter does not support OHLCV interval '${interval}'. ` +
+        `Supported: ${Object.keys(LIGHTER_SUPPORTED_INTERVALS).join(', ')}.`
+    )
+  }
+  return resolution
+}

package/src/utils/orderFormatting.ts

@@ -0,0 +1,46 @@
+/**
+ * Lighter order size and price formatting for exchange submission.
+ *
+ * Lighter publishes a flat per-market decimal budget on its order books
+ * (`supported_price_decimals` / `supported_size_decimals`), surfaced on the
+ * generic {@link Market} as `priceDecimals` / `szDecimals`. Prices round to
+ * the tick grid; sizes truncate to the lot grid.
+ */
+
+import { PerpsError } from '@lifi/perps-sdk'
+import { type Market, PerpsErrorCode } from '@lifi/perps-types'
+import Big from 'big.js'
+
+/**
+ * Format a price onto a Lighter market's tick grid: rounded to the market's
+ * `priceDecimals` (Lighter's `supported_price_decimals`), trailing zeros
+ * stripped.
+ *
+ * @throws {PerpsError} `ValidationError` when `market.priceDecimals` is
+ *   absent — without the venue's tick grid no correct price can be produced.
+ * @public
+ */
+export function formatOrderPrice(market: Market, price: number): string {
+  if (market.priceDecimals === undefined) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Market '${market.id}' carries no priceDecimals; Lighter order prices ` +
+        `cannot be formatted without the market's tick grid.`
+    )
+  }
+  const rounded = new Big(price).round(market.priceDecimals, Big.roundHalfUp)
+  return rounded.eq(0) ? '0' : rounded.toFixed()
+}
+
+/**
+ * Format a size onto a Lighter market's lot grid: truncated (never rounded
+ * up, so the size cannot exceed the user's balance) to the market's
+ * `szDecimals` (Lighter's `supported_size_decimals`), trailing zeros stripped.
+ *
+ * @param size - Size in base-asset units as a non-negative magnitude.
+ * @public
+ */
+export function formatOrderSize(market: Market, size: number): string {
+  const truncated = new Big(size).round(market.szDecimals, Big.roundDown)
+  return truncated.eq(0) ? '0' : truncated.toFixed()
+}

package/src/utils/time.ts

@@ -0,0 +1,6 @@
+/** Convert seconds since unix epoch to ISO-8601. */
+export const toIsoFromSeconds = (seconds: number): string =>
+  new Date(seconds * 1000).toISOString()
+
+/** Convert milliseconds since unix epoch to ISO-8601. */
+export const toIsoFromMs = (ms: number): string => new Date(ms).toISOString()

package/src/utils/wireEncoding.ts

@@ -0,0 +1,179 @@
+/**
+ * Lighter wire encoding for the WASM signer: scaled-integer decimal values,
+ * basis-point margin fractions, and order-type/TIF/expiry resolution
+ * mirroring the lighter-go signer's rules.
+ */
+
+import { PerpsError } from '@lifi/perps-sdk'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import Big from 'big.js'
+import {
+  LT_DEFAULT_ORDER_EXPIRY,
+  LT_ORDER_TYPE_LIMIT,
+  LT_ORDER_TYPE_MARKET,
+  LT_ORDER_TYPE_STOP_LOSS,
+  LT_ORDER_TYPE_STOP_LOSS_LIMIT,
+  LT_ORDER_TYPE_TAKE_PROFIT,
+  LT_ORDER_TYPE_TAKE_PROFIT_LIMIT,
+  LT_TIME_IN_FORCE_GTC,
+  LT_TIME_IN_FORCE_IOC,
+  LT_TIME_IN_FORCE_POST_ONLY,
+} from '../types/action.js'
+
+/**
+ * Lighter uses basis-points (1/10000) for margin fractions.
+ * Convert to a decimal multiplier: 1000 → 0.1 (10x leverage).
+ * @public
+ */
+export const marginFractionToMaxLeverage = (fraction: number): number => {
+  if (!Number.isFinite(fraction) || fraction <= 0) {
+    return 1
+  }
+  return Math.floor(10_000 / fraction)
+}
+
+/**
+ * Convert leverage to margin fraction in basis points for WASM signer.
+ * @public
+ */
+export const leverageToFraction = (leverage: number): number => {
+  if (leverage <= 0) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid leverage: ${leverage}`
+    )
+  }
+  return Math.round(10_000 / leverage)
+}
+
+/**
+ * Off-grid resolution for {@link scaleToInteger}:
+ * - `truncate` — toward zero, for sizes and collateral amounts. The wire
+ *   value never exceeds the caller's intent.
+ * - `round` — half away from zero, for prices, which snap to the nearest
+ *   tick.
+ * @public
+ */
+export type ScaleToIntegerPolicy = 'truncate' | 'round'
+
+/**
+ * Scale a human-readable decimal string to a scaled integer for the WASM
+ * signer, in exact decimal arithmetic — an on-grid input maps to its exact
+ * scaled integer with no binary float artifacts (`'0.29'` at 2 decimals is
+ * 29, never 28). Off-grid input resolves per `policy`; there is no silent
+ * default.
+ *
+ * @throws {PerpsError} `ValidationError` when `value` is not a decimal
+ *   numeric string, `decimals` is not a non-negative integer, or the scaled
+ *   result's magnitude exceeds `Number.MAX_SAFE_INTEGER`.
+ * @public
+ */
+export const scaleToInteger = (
+  value: string,
+  decimals: number,
+  policy: ScaleToIntegerPolicy
+): number => {
+  if (!Number.isInteger(decimals) || decimals < 0) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid decimals for Lighter integer scaling: ${decimals}`
+    )
+  }
+  let parsed: Big
+  try {
+    parsed = new Big(value)
+  } catch {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid decimal string for Lighter integer scaling: '${value}'`
+    )
+  }
+  const scaled = parsed
+    .times(new Big(10).pow(decimals))
+    .round(0, policy === 'truncate' ? Big.roundDown : Big.roundHalfUp)
+  if (scaled.abs().gt(Number.MAX_SAFE_INTEGER)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Scaled value ${scaled.toFixed()} exceeds Number.MAX_SAFE_INTEGER and cannot be encoded exactly.`
+    )
+  }
+  return scaled.toNumber()
+}
+
+/**
+ * Map our OrderType enum to Lighter's integer order type.
+ * @public
+ */
+export const mapOrderTypeToInt = (type?: string): number => {
+  const map: Record<string, number> = {
+    LIMIT: LT_ORDER_TYPE_LIMIT,
+    MARKET: LT_ORDER_TYPE_MARKET,
+    STOP_MARKET: LT_ORDER_TYPE_STOP_LOSS,
+    STOP_LIMIT: LT_ORDER_TYPE_STOP_LOSS_LIMIT,
+    TAKE_PROFIT_MARKET: LT_ORDER_TYPE_TAKE_PROFIT,
+    TAKE_PROFIT_LIMIT: LT_ORDER_TYPE_TAKE_PROFIT_LIMIT,
+  }
+  return map[type ?? 'LIMIT'] ?? LT_ORDER_TYPE_LIMIT
+}
+
+/**
+ * Lighter pairs each `order_type` with a permitted set of `time_in_force`
+ * values: market-style orders (MARKET, STOP_MARKET, TAKE_PROFIT_MARKET) are
+ * IOC by definition; limit-style orders may carry any TIF. The Go WASM
+ * signer rejects mismatches with `OrderTimeInForce is not valid`. Resolve
+ * the caller's optional `timeInForce` against the order type so unspecified
+ * values land on the correct default and explicit values are validated up
+ * front.
+ * @public
+ */
+export const resolveTimeInForce = (
+  orderTypeInt: number,
+  tif?: string
+): number => {
+  const requested = tif === undefined ? undefined : mapTimeInForceToInt(tif)
+  const isMarketStyle =
+    orderTypeInt === LT_ORDER_TYPE_MARKET ||
+    orderTypeInt === LT_ORDER_TYPE_STOP_LOSS ||
+    orderTypeInt === LT_ORDER_TYPE_TAKE_PROFIT
+  if (isMarketStyle) {
+    if (requested !== undefined && requested !== LT_TIME_IN_FORCE_IOC) {
+      throw new PerpsError(
+        PerpsErrorCode.ValidationError,
+        `Lighter market-style orders only accept IOC (got tif=${tif}).`
+      )
+    }
+    return LT_TIME_IN_FORCE_IOC
+  }
+  return requested ?? LT_TIME_IN_FORCE_GTC
+}
+
+/**
+ * Map our TimeInForce enum to Lighter's integer time-in-force.
+ * @public
+ */
+export const mapTimeInForceToInt = (tif?: string): number => {
+  const map: Record<string, number> = {
+    IOC: LT_TIME_IN_FORCE_IOC,
+    GTC: LT_TIME_IN_FORCE_GTC,
+    POST_ONLY: LT_TIME_IN_FORCE_POST_ONLY,
+  }
+  return map[tif ?? 'GTC'] ?? LT_TIME_IN_FORCE_GTC
+}
+
+/**
+ * Pick the `order_expiry` value Lighter expects for a given TIF on a
+ * regular limit order. `lighter-go/types/txtypes/create_order.go:121-128`
+ * enforces:
+ *   - IOC limit orders → `OrderExpiry == NilOrderExpiry (0)`
+ *   - non-IOC limit orders → `OrderExpiry != NilOrderExpiry`
+ * For non-IOC we pass the `-1` sentinel, which the WASM signer rewrites
+ * to `now + 28d` (absolute ms). Trigger orders take a different rule —
+ * see {@link LT_DEFAULT_ORDER_EXPIRY} call sites.
+ * @public
+ */
+export const orderExpiryForTif = (tifInt: number): number => {
+  if (tifInt === LT_TIME_IN_FORCE_IOC) {
+    return 0
+  }
+  return LT_DEFAULT_ORDER_EXPIRY
+}