@lifi/perps-types 0.1.1-alpha.9 → 0.2.0-alpha.0

package/src/providers/hyperliquid/mappers/position.ts

@@ -1,21 +1,19 @@
 import { MarginMode, PositionSide } from '../../../enums.js'
 import type { Position } from '../../../account.js'
 import type { HlAssetPosition } from '../types.js'
+import { deriveMarket } from './_market.js'
 
-import { resolveAssetIdFromLookup } from './shared.js'
-
-export const mapPosition = (
-  ap: HlAssetPosition,
-  dexKey: string,
-  assetIdLookup: Map<string, number>
-): Position => {
+export const mapPosition = (ap: HlAssetPosition): Position => {
   const pos = ap.position
   const szi = parseFloat(pos.szi)
 
   return {
-    symbol: pos.coin,
-    assetId: resolveAssetIdFromLookup(assetIdLookup, pos.coin),
-    dex: dexKey,
+    asset: {
+      assetId: pos.coin,
+      market: deriveMarket(pos.coin),
+      displaySymbol: pos.coin,
+      displayQuote: null,
+    },
     side: szi >= 0 ? PositionSide.LONG : PositionSide.SHORT,
     size: Math.abs(szi).toString(),
     entryPrice: pos.entryPx ?? '0',

package/src/providers/hyperliquid/mappers/shared.ts

@@ -1,15 +0,0 @@
-/**
- * Look up an asset ID by symbol, throwing if the symbol is unknown.
- * Asset ID 0 is a valid Hyperliquid asset (BTC-PERP), so a fallback
- * to 0 would silently corrupt data.
- */
-export const resolveAssetIdFromLookup = (
-  lookup: Map<string, number>,
-  symbol: string
-): number => {
-  const id = lookup.get(symbol)
-  if (id === undefined) {
-    throw new Error(`Unknown asset symbol: ${symbol}`)
-  }
-  return id
-}

package/src/providers/hyperliquid/types.ts

@@ -1,3 +1,5 @@
+import type { Address } from 'viem'
+
 // ---------------------------------------------------------------------------
 // Hyperliquid /info response types
 // ---------------------------------------------------------------------------
@@ -20,6 +22,7 @@ export type HlAssetCtx = {
   funding: string
   openInterest: string
   dayNtlVlm: string
+  prevDayPx: string
   markPx: string
 }
 
@@ -123,6 +126,13 @@ export type HlFrontendOpenOrder = {
   origSz: string
   reduceOnly: boolean
   timestamp: number
+  isTrigger: boolean
+  isPositionTpsl: boolean
+  triggerCondition: string
+  triggerPx: string
+  children: HlFrontendOpenOrder[]
+  tif: string | null
+  cloid: string | null
 }
 
 export type HlFrontendOpenOrders = HlFrontendOpenOrder[]
@@ -135,6 +145,7 @@ export type HlExtraAgents = Record<string, unknown>[]
 
 export type HlUserFill = {
   tid: number
+  oid: number
   coin: string
   side: string
   sz: string
@@ -142,7 +153,9 @@ export type HlUserFill = {
   dir: string
   fee: string
   closedPnl: string
+  crossed: boolean
   time: number
+  startPosition: string
 }
 
 export type HlUserFills = HlUserFill[]
@@ -182,12 +195,80 @@ export type HlOrderStatusResponse =
 
 // -- userNonFundingLedgerUpdates --------------------------------------------
 
-export type HlLedgerDelta = {
-  type: string
-  usdc: string
-  [key: string]: unknown
+/**
+ * Hyperliquid `spotTransfer` ledger delta. Emitted for transfers of spot
+ * tokens between Hyperliquid accounts. `user` is the sender, `destination`
+ * the recipient; direction is derived at the call site from the queried
+ * address.
+ */
+export type HlSpotTransferDelta = {
+  type: 'spotTransfer'
+  token: string
+  amount: string
+  usdcValue: string
+  user: Address
+  destination: Address
+  fee?: string
+  nativeTokenFee?: string
+  nonce?: number
 }
 
+/**
+ * Hyperliquid ledger delta emitted for the `sendAsset` exchange action. The
+ * wire `type` literal is `'send'` (NOT `'sendAsset'`); the TS name retains
+ * the `SendAsset` prefix to match `HL_PRIMARY_TYPE_SEND_ASSET`.
+ *
+ * - `user` is the sender, `destination` the recipient. For same-user dex
+ *   moves both equal the queried address.
+ * - `sourceDex` / `destinationDex` use `""` for the main USDC perp DEX,
+ *   `"spot"` for spot, or the perp DEX name otherwise.
+ * - `token` is a wire token identifier (e.g. `"USDC"` or `"TOKEN:0x..."`).
+ * - `nonce` is the wire nonce (ms timestamp); always present on `send`
+ *   deltas, unlike `spotTransfer` where it may be null.
+ */
+export type HlSendAssetDelta = {
+  type: 'send'
+  user: Address
+  destination: Address
+  sourceDex: string
+  destinationDex: string
+  token: string
+  amount: string
+  usdcValue: string
+  fee: string
+  nativeTokenFee: string
+  nonce: number
+  feeToken: string
+}
+
+export type HlLedgerDelta =
+  | HlSpotTransferDelta
+  | HlSendAssetDelta
+  | {
+      type: string
+      usdc?: string
+      [key: string]: unknown
+    }
+
+/**
+ * Type guard for `HlSpotTransferDelta` — TypeScript cannot narrow off the
+ * `type` discriminant alone because the catch-all arm of `HlLedgerDelta` has
+ * `type: string` (a supertype of the literal `'spotTransfer'`). Use this at
+ * call sites that need the strongly-typed shape.
+ */
+export const isSpotTransferDelta = (
+  delta: HlLedgerDelta
+): delta is HlSpotTransferDelta => delta.type === 'spotTransfer'
+
+/**
+ * Type guard for `HlSendAssetDelta`. The wire `type` literal is `'send'`;
+ * see `HlSendAssetDelta` for the naming-vs-wire-format rationale. Same
+ * catch-all-arm caveat as `isSpotTransferDelta`.
+ */
+export const isSendAssetDelta = (
+  delta: HlLedgerDelta
+): delta is HlSendAssetDelta => delta.type === 'send'
+
 export type HlLedgerUpdate = {
   time: number
   hash: string
@@ -214,6 +295,22 @@ export type HlFundingUpdate = {
 
 export type HlUserFunding = HlFundingUpdate[]
 
+// -- abstraction mode -------------------------------------------------------
+
+/**
+ * Possible values returned by the `userAbstraction` info endpoint.
+ * `null` means abstraction has never been set (standard mode).
+ */
+export const HlAbstractionMode = {
+  DISABLED: 'disabled',
+  UNIFIED_ACCOUNT: 'unifiedAccount',
+  PORTFOLIO_MARGIN: 'portfolioMargin',
+  DEX_ABSTRACTION: 'dexAbstraction',
+} as const
+
+export type HlAbstractionMode =
+  (typeof HlAbstractionMode)[keyof typeof HlAbstractionMode]
+
 // -- perpDexs ---------------------------------------------------------------
 
 export type HlPerpDexs = (null | { name: string })[]
@@ -253,3 +350,30 @@ export type HlExchangeResponse = {
         }
       }
 }
+
+// ---------------------------------------------------------------------------
+// Hyperliquid EIP-712 primary type constants
+// ---------------------------------------------------------------------------
+
+export const HL_PRIMARY_TYPE_APPROVE_AGENT =
+  'HyperliquidTransaction:ApproveAgent' as const
+export const HL_PRIMARY_TYPE_APPROVE_BUILDER_FEE =
+  'HyperliquidTransaction:ApproveBuilderFee' as const
+export const HL_PRIMARY_TYPE_USER_SET_ABSTRACTION =
+  'HyperliquidTransaction:UserSetAbstraction' as const
+export const HL_PRIMARY_TYPE_AGENT_SET_ABSTRACTION =
+  'HyperliquidTransaction:AgentSetAbstraction' as const
+export const HL_PRIMARY_TYPE_WITHDRAW =
+  'HyperliquidTransaction:Withdraw' as const
+export const HL_PRIMARY_TYPE_SEND_ASSET =
+  'HyperliquidTransaction:SendAsset' as const
+export const HL_PRIMARY_TYPE_AGENT = 'Agent' as const
+
+export type HlPrimaryType =
+  | typeof HL_PRIMARY_TYPE_APPROVE_AGENT
+  | typeof HL_PRIMARY_TYPE_APPROVE_BUILDER_FEE
+  | typeof HL_PRIMARY_TYPE_USER_SET_ABSTRACTION
+  | typeof HL_PRIMARY_TYPE_AGENT_SET_ABSTRACTION
+  | typeof HL_PRIMARY_TYPE_WITHDRAW
+  | typeof HL_PRIMARY_TYPE_SEND_ASSET
+  | typeof HL_PRIMARY_TYPE_AGENT

package/src/providers/lighter/apiTypes.ts

@@ -0,0 +1,87 @@
+// ---------------------------------------------------------------------------
+// Lighter raw API response types — shared between backend (REST) and SDK (WS)
+// ---------------------------------------------------------------------------
+
+export type LtAccountPosition = {
+  market_id: number
+  symbol: string
+  initial_margin_fraction: string
+  open_order_count: number
+  pending_order_count: number
+  position_tied_order_count: number
+  sign: number
+  position: string
+  avg_entry_price: string
+  position_value: string
+  unrealized_pnl: string
+  realized_pnl: string
+  liquidation_price: string
+  total_funding_paid_out: string
+  margin_mode: number
+  allocated_margin: string
+  total_discount: string
+}
+
+export type LtAccountAsset = {
+  symbol: string
+  asset_id: number
+  balance: string
+  locked_balance: string
+}
+
+export type LtTrade = {
+  trade_id: number
+  tx_hash: string
+  type: string
+  market_id: number
+  size: string
+  price: string
+  usd_amount: string
+  ask_id: number
+  bid_id: number
+  ask_account_id: number
+  bid_account_id: number
+  is_maker_ask: boolean
+  block_height: number
+  timestamp: number
+  // Lighter's OpenAPI spec marks these as required `StrictInt`, but the live
+  // /api/v1/trades endpoint omits them on some `type: "trade"` rows (observed
+  // on older trades) — keep optional and let the mapper emit `undefined`.
+  taker_fee?: number
+  maker_fee?: number
+  transaction_time: number
+  // Per-counterparty position snapshot BEFORE the trade is applied. Signed
+  // strings: positive = long, negative = short, "0" / "0.00000" = flat.
+  taker_position_size_before: string
+  maker_position_size_before: string
+}
+
+export type LtOrder = {
+  order_index: number
+  client_order_index: number
+  order_id: string
+  client_order_id: string
+  market_index: number
+  owner_account_index: number
+  initial_base_amount: string
+  price: string
+  nonce: number
+  remaining_base_amount: string
+  is_ask: boolean
+  filled_base_amount: string
+  filled_quote_amount: string
+  side: string
+  type: string
+  time_in_force: string
+  reduce_only: boolean
+  trigger_price: string
+  order_expiry: number
+  status: string
+  trigger_status: string
+  trigger_time: number
+  block_height: number
+  timestamp: number
+  created_at: number
+  updated_at: number
+  transaction_time: number
+}

package/src/providers/lighter/index.ts

@@ -0,0 +1,3 @@
+export * from './types.js'
+export * from './apiTypes.js'
+export * from './mappers/index.js'

package/src/providers/lighter/mappers/fill.ts

@@ -0,0 +1,57 @@
+import {
+  FillStatus,
+  LiquidityRole,
+  OrderSide,
+  OrderType,
+} from '../../../enums.js'
+import type { Fill } from '../../../account.js'
+import type { LtTrade } from '../apiTypes.js'
+import { classifyFillFromPosition } from '../../_shared/fillClassification.js'
+
+/**
+ * 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 symbol - Resolved symbol (market_id → symbol lookup).
+ */
+export const mapFill = (
+  trade: LtTrade,
+  accountIndex: number,
+  symbol: string
+): 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
+
+  return {
+    id: trade.trade_id.toString(),
+    orderId: String(isBuyer ? trade.bid_id : trade.ask_id),
+    asset: {
+      assetId: symbol,
+      market: 'lighter',
+      displaySymbol: symbol,
+      displayQuote: 'USDC',
+    },
+    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(),
+    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(),
+  }
+}

package/src/providers/lighter/mappers/index.ts

@@ -0,0 +1,8 @@
+export { mapPosition } from './position.js'
+export { mapFill } from './fill.js'
+export {
+  isTriggerType,
+  mapOrder,
+  mapOrderDetail,
+  mapTriggerOrder,
+} from './order.js'

package/src/providers/lighter/mappers/order.ts

@@ -0,0 +1,184 @@
+import {
+  OrderSide,
+  OrderStatus,
+  OrderType,
+  TimeInForce,
+} from '../../../enums.js'
+import type { OpenOrder, TriggerOrder } from '../../../account.js'
+import type { Order } from '../../../action.js'
+import type { LtOrder } from '../apiTypes.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`.
+ */
+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`.
+ */
+export const isTriggerType = (type: OrderType): boolean =>
+  type === OrderType.TAKE_PROFIT_MARKET ||
+  type === OrderType.TAKE_PROFIT_LIMIT ||
+  type === OrderType.STOP_MARKET ||
+  type === OrderType.STOP_LIMIT
+
+/**
+ * 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.
+ */
+export const mapTriggerOrder = (
+  order: LtOrder,
+  symbol: string
+): TriggerOrder => {
+  const type = mapOrderType(order.type)
+  const isLimit =
+    type === OrderType.TAKE_PROFIT_LIMIT || type === OrderType.STOP_LIMIT
+  return {
+    id: order.order_id,
+    asset: {
+      assetId: symbol,
+      market: 'lighter',
+      displaySymbol: symbol,
+      displayQuote: 'USDC',
+    },
+    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 symbol - Resolved symbol (market_index → symbol lookup)
+ */
+export const mapOrder = (order: LtOrder, symbol: string): OpenOrder => ({
+  id: order.order_id,
+  asset: {
+    assetId: symbol,
+    market: 'lighter',
+    displaySymbol: symbol,
+    displayQuote: 'USDC',
+  },
+  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(),
+})
+
+/**
+ * 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.
+ */
+export const mapOrderDetail = (order: LtOrder, symbol: string): Order => ({
+  orderId: order.order_id,
+  asset: {
+    assetId: symbol,
+    market: 'lighter',
+    displaySymbol: symbol,
+    displayQuote: 'USDC',
+  },
+  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/providers/lighter/mappers/position.ts

@@ -0,0 +1,46 @@
+import { MarginMode, PositionSide } from '../../../enums.js'
+import type { Position } from '../../../account.js'
+import type { LtAccountPosition } from '../apiTypes.js'
+import { LT_MARGIN_MODE_ISOLATED } from '../types.js'
+
+/**
+ * Map a raw Lighter account position to the generic Position type.
+ * @param symbol Resolved symbol (market_id → symbol lookup, or `pos.symbol`).
+ */
+export const mapPosition = (
+  pos: LtAccountPosition,
+  symbol: string
+): 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 {
+    asset: {
+      assetId: symbol,
+      market: 'lighter',
+      displaySymbol: symbol,
+      displayQuote: 'USDC',
+    },
+    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,
+  }
+}