@lifi/perps-types 0.1.1-alpha.21 → 0.1.1-alpha.23

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

@@ -0,0 +1,48 @@
+import {
+  FillClassification,
+  FillStatus,
+  LiquidityRole,
+  OrderSide,
+  OrderType,
+} from '../../../enums.js'
+import type { Fill } from '../../../account.js'
+import type { LtTrade } from '../apiTypes.js'
+
+const classifyFill = (isBuy: boolean): FillClassification =>
+  isBuy ? FillClassification.OPENED_LONG : FillClassification.OPENED_SHORT
+
+/**
+ * Map a raw Lighter trade to the generic Fill type.
+ * @param trade - Raw trade from REST or WS
+ * @param accountIndex - The viewer's Lighter account index (to determine buy/sell side)
+ * @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)
+
+  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(),
+    classification: classifyFill(isBuyer),
+    createdAt: new Date(trade.timestamp).toISOString(),
+  }
+}

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

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

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

@@ -0,0 +1,105 @@
+import {
+  OrderSide,
+  OrderStatus,
+  OrderType,
+  TimeInForce,
+} from '../../../enums.js'
+import type { OpenOrder } 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 to the generic OpenOrder type.
+ * @param order - Raw order from REST or WS
+ * @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 used by getOrder.
+ * Includes status, time-in-force, and remaining/filled sizes.
+ */
+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),
+  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,43 @@
+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 pos - Raw position from REST or WS
+ * @param symbol - Resolved symbol (market_id → symbol lookup, or pos.symbol)
+ */
+export const mapPosition = (
+  pos: LtAccountPosition,
+  symbol: string
+): Position => {
+  const size = parseFloat(pos.position)
+
+  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:
+      parseFloat(pos.initial_margin_fraction) > 0
+        ? Math.round(100 / parseFloat(pos.initial_margin_fraction))
+        : 1,
+    marginUsed: pos.allocated_margin,
+    marginMode:
+      pos.margin_mode === LT_MARGIN_MODE_ISOLATED
+        ? MarginMode.ISOLATED
+        : MarginMode.CROSS,
+  }
+}

package/src/providers/lighter/types.ts

@@ -0,0 +1,115 @@
+// ---------------------------------------------------------------------------
+// Lighter WASM signer parameter types
+//
+// These define the exact shapes that `wasmSignParams` takes for each Lighter
+// action type. The backend populates these; the SDK passes them to the WASM
+// signer along with SDK-managed fields (nonce, account_index, api_key_index).
+// ---------------------------------------------------------------------------
+
+/** Backend-provided params for SignCreateOrder. */
+export type LtCreateOrderWasmParams = {
+  market_index: number
+  client_order_index: number
+  base_amount: number
+  price: number
+  is_ask: number
+  order_type: number
+  time_in_force: number
+  reduce_only: boolean
+  trigger_price: number
+  order_expiry: number
+  integrator_account_index: number
+  integrator_taker_fee: number
+  integrator_maker_fee: number
+}
+
+/** Backend-provided params for SignCancelOrder. */
+export type LtCancelOrderWasmParams = {
+  market_index: number
+  order_index: number
+}
+
+/** Backend-provided params for SignModifyOrder. */
+export type LtModifyOrderWasmParams = {
+  market_index: number
+  order_index: number
+  base_amount: number
+  price: number
+  trigger_price: number
+  integrator_account_index: number
+  integrator_taker_fee: number
+  integrator_maker_fee: number
+}
+
+/** Backend-provided params for SignUpdateLeverage. */
+export type LtUpdateLeverageWasmParams = {
+  market_index: number
+  fraction: number
+  margin_mode: number
+}
+
+/** Backend-provided params for SignUpdateMargin. */
+export type LtUpdateMarginWasmParams = {
+  market_index: number
+  usdc_amount: number
+  direction: number
+}
+
+/** Backend-provided params for SignWithdraw. */
+export type LtWithdrawWasmParams = {
+  asset_index: number
+  route_type: number
+  amount: number
+}
+
+/** Backend-provided params for SignCancelAllOrders. */
+export type LtCancelAllOrdersWasmParams = {
+  /** 0=immediate (cancel GTC), 1=scheduled, 2=abort scheduled */
+  time_in_force: number
+  /** Unix timestamp in milliseconds. Use Date.now() for immediate cancels. */
+  timestamp_ms: number
+}
+
+/**
+ * Backend-provided params for SignChangePubKey (REGISTER_API_KEY).
+ *
+ * NOTE: `new_public_key` is a placeholder here — the SDK generates the actual
+ * keypair via the WASM signer and fills this in before calling SignChangePubKey.
+ * This action also requires an L1 Ethereum signature (the user's wallet signs
+ * the ChangePubKey message), so it is a hybrid: WASM blob + EIP-191 eth_sign.
+ */
+export type LtChangePubKeyWasmParams = {
+  /** API key slot index to register (0-255). SDK fills in the generated public key. */
+  api_key_index: number
+  nonce: number
+}
+
+// ---------------------------------------------------------------------------
+// Lighter WASM signer constants
+// ---------------------------------------------------------------------------
+
+export const LT_ORDER_TYPE_LIMIT = 0
+export const LT_ORDER_TYPE_MARKET = 1
+export const LT_ORDER_TYPE_STOP_LOSS = 2
+export const LT_ORDER_TYPE_STOP_LOSS_LIMIT = 3
+export const LT_ORDER_TYPE_TAKE_PROFIT = 4
+export const LT_ORDER_TYPE_TAKE_PROFIT_LIMIT = 5
+export const LT_ORDER_TYPE_TWAP = 6
+
+export const LT_TIME_IN_FORCE_IOC = 0
+export const LT_TIME_IN_FORCE_GTC = 1
+export const LT_TIME_IN_FORCE_POST_ONLY = 2
+
+export const LT_MARGIN_MODE_CROSS = 0
+export const LT_MARGIN_MODE_ISOLATED = 1
+
+export const LT_MARGIN_DIRECTION_REMOVE = 0
+export const LT_MARGIN_DIRECTION_ADD = 1
+
+export const LT_ROUTE_PERP = 0
+export const LT_ROUTE_SPOT = 1
+
+export const LT_ASSET_ID_USDC = 3
+
+export const LT_NIL_TRIGGER_PRICE = 0
+export const LT_DEFAULT_ORDER_EXPIRY = -1

package/src/providers.ts

@@ -1,8 +1,40 @@
-import type { ActionType, PerpsSigner } from './enums.js'
+import type { ActionType, PerpsSigner, SigningMethod } from './enums.js'
 
 export interface ActionDescriptor {
   type: ActionType
   signers: PerpsSigner[]
+  /**
+   * How the SDK must sign this specific action. Most actions match the
+   * provider's dominant pattern (Hyperliquid: EIP712, Lighter: WASM_BLOB),
+   * but on-chain bridge actions like DEPOSIT are EVM_TX regardless of
+   * provider — the SDK dispatches by this field rather than by
+   * `Provider.signingMethod`.
+   */
+  signingMethod: SigningMethod
+}
+
+/**
+ * Self-documenting account-setup step the user must (or may) fulfill before
+ * trading with a given provider. Mirrors a single entry of the `config`
+ * object returned by `GET /perps/account` — that endpoint reports the
+ * *state* of these items, while `Provider.accountConfiguration` declares
+ * what items exist and how to fulfill them.
+ *
+ * Extends `ActionDescriptor` because each item resolves to exactly one
+ * action the SDK dispatches when the user proceeds; the additional fields
+ * are the presentation and gating metadata the widget needs to render the
+ * onboarding overlay without hardcoded labels.
+ *
+ * `optional: false` means the item must be fulfilled before the user can
+ * proceed; `optional: true` means the user may skip it.
+ */
+export interface AccountConfigurationItem extends ActionDescriptor {
+  /** User-facing row title rendered in the onboarding overlay. */
+  title: string
+  /** User-facing description rendered in the onboarding overlay. */
+  description: string
+  /** When true the user may skip the item; when false it gates the trade flow. */
+  optional: boolean
 }
 
 export interface ProviderMarketInfo {
@@ -14,7 +46,14 @@ export interface Provider {
   key: string
   name: string
   logoURI: string
-  prepareAccountActions: ActionDescriptor[]
+  signingMethod: SigningMethod
+  /**
+   * Account-setup items required (or optional) for trading with this
+   * provider. Replaces the previous `prepareAccountActions: ActionDescriptor[]`:
+   * same operational fields, plus the user-facing metadata the widget needs.
+   * An empty array is valid and indicates the provider has no setup gates.
+   */
+  accountConfiguration: AccountConfigurationItem[]
   actions: ActionDescriptor[]
   markets: ProviderMarketInfo[]
   wsUrl?: string

package/src/typedData.ts

@@ -1,12 +1,22 @@
-import type { TypedData, SignedTypedData } from '@lifi/types'
 import type { Address, Hex, TypedDataDomain, TypedDataParameter } from 'viem'
+import type { HlPrimaryType } from './providers/hyperliquid/types.js'
 
-export type PerpsTypedData = Omit<TypedData, 'primaryType'> & {
-  primaryType: string
+/**
+ * All known EIP-712 primaryType values across supported providers.
+ * Extend this union when adding a new EIP-712 provider.
+ */
+export type PerpsPrimaryType = HlPrimaryType
+
+export type PerpsTypedData = {
+  domain: TypedDataDomain
+  types: Record<string, readonly TypedDataParameter[]>
+  primaryType: PerpsPrimaryType
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  message: Record<string, any>
 }
 
-export type PerpsSignedTypedData = Omit<SignedTypedData, 'primaryType'> & {
-  primaryType: string
+export type PerpsSignedTypedData = PerpsTypedData & {
+  signature: Hex
 }
 
 // Re-export viem primitives used across perps types