@lifi/perps-sdk-provider-lighter 41.0.2 → 42.0.1

package/src/depositFlow.ts

@@ -11,31 +11,33 @@ import { ActionType, type LighterProviderKey } from '@lifi/perps-types'
 import { LIGHTER_PROVIDER_KEY, LIGHTER_RH_PROVIDER_KEY } from './constants.js'
 
 interface LighterDepositAssets {
-  /** Collateral token on the venue chain, credited to an account that exists. */
-  venueCollateral: DeclaredDepositAsset
-  /** Collateral the account-opening deposit is made in, on the chain that deposit runs on. */
-  firstDepositCollateral: DeclaredDepositAsset
-  firstDepositGas: DeclaredDepositAsset
+  /**
+   * Collateral token on the venue chain that a LI.FI route credits to an
+   * account that exists. Absent when only the venue deposit credits an account.
+   */
+  venueCollateral?: DeclaredDepositAsset
+  /** Collateral the venue deposit is made in, on the chain that deposit runs on. */
+  venueDepositCollateral: DeclaredDepositAsset
+  venueDepositGas: DeclaredDepositAsset
 }
 
 const DEPOSIT_ASSETS: Record<LighterProviderKey, LighterDepositAssets> = {
   [LIGHTER_PROVIDER_KEY]: {
     venueCollateral: LIGHTER_USDC,
-    firstDepositCollateral: ETHEREUM_USDC,
-    firstDepositGas: ETHEREUM_NATIVE_GAS,
+    venueDepositCollateral: ETHEREUM_USDC,
+    venueDepositGas: ETHEREUM_NATIVE_GAS,
   },
   [LIGHTER_RH_PROVIDER_KEY]: {
-    venueCollateral: ROBINHOOD_USDG,
-    firstDepositCollateral: ROBINHOOD_USDG,
-    firstDepositGas: ROBINHOOD_NATIVE_GAS,
+    venueDepositCollateral: ROBINHOOD_USDG,
+    venueDepositGas: ROBINHOOD_NATIVE_GAS,
   },
 }
 
 /**
  * Resolve one Lighter instance's deposit flow from whether the account already
- * exists: an existing account takes a swap into the instance's venue collateral,
- * while an address with no account runs the account-opening deposit on the chain
- * that instance's collateral is deposited from.
+ * exists: an existing account takes a swap into the instance's venue collateral
+ * when a LI.FI route credits it there. Every other case runs the venue deposit
+ * on the chain that instance's collateral is deposited from.
  *
  * @public
  */
@@ -45,15 +47,15 @@ export function lighterDepositFlow(
 ): DepositFlow {
   const assets = DEPOSIT_ASSETS[providerKey]
 
-  if (accountExists) {
+  if (accountExists && assets.venueCollateral) {
     return { kind: 'lifiSwap', destination: assets.venueCollateral }
   }
 
   return {
-    kind: 'firstDepositPipeline',
-    chainId: assets.firstDepositCollateral.chainId,
-    gasAsset: assets.firstDepositGas,
-    collateral: assets.firstDepositCollateral,
+    kind: 'venueDepositPipeline',
+    chainId: assets.venueDepositCollateral.chainId,
+    gasAsset: assets.venueDepositGas,
+    collateral: assets.venueDepositCollateral,
     bridgeAction: ActionType.DEPOSIT,
   }
 }

package/src/types/ws.ts

@@ -142,8 +142,10 @@ export type LtWsTrade = {
   trade_id: number
   trade_id_str?: string
   market_id?: number
+  type: string
   size: string
   price: string
+  usd_amount: string
   is_maker_ask: boolean
   timestamp: number
 }

package/src/utils/mapFill.ts

@@ -13,12 +13,13 @@ import {
   safeMultiplyDecimalString,
   warnSkippedVenueRow,
 } from '@lifi/perps-sdk'
-import type { Fill, MarketDisplay } from '@lifi/perps-types'
-import { LiquidityRole, OrderSide, OrderType } from '@lifi/perps-types'
+import type { Fill, FillLiquidation, MarketDisplay } from '@lifi/perps-types'
+import { LiquidationMethod, LiquidityRole, OrderSide } from '@lifi/perps-types'
 import { LIGHTER_FEE_TICK_SCALE, LIGHTER_PROVIDER_KEY } from '../constants.js'
 import type { LtTrade } from '../types/index.js'
 import { leverageFromScaledImf } from './mapPosition.js'
 import { rowTimestampToIsoStringOrUndefined } from './rowTimestamp.js'
+import { resolveTradePrice } from './tradePrice.js'
 import { isPlaceholderTxHash } from './txHash.js'
 
 /**
@@ -111,8 +112,28 @@ const deriveRealizedPnl = (
   return isDecimalStringZero(pnl) ? null : pnl
 }
 
+// The liquidation engine trades as the taker for the liquidated account; the
+// maker of a forced trade is its counterparty.
+const mapFillLiquidation = (
+  type: string,
+  isMaker: boolean
+): FillLiquidation | undefined => {
+  if (isMaker) {
+    return undefined
+  }
+  switch (type) {
+    case 'liquidation':
+      return { method: LiquidationMethod.MARKET }
+    case 'deleverage':
+      return { method: LiquidationMethod.DELEVERAGE }
+    default:
+      return undefined
+  }
+}
+
 /**
- * Map a raw Lighter trade to the generic Fill type.
+ * Map a raw Lighter trade to the generic Fill type. Leaves `type` absent: a
+ * trade row does not name the originating order 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
@@ -122,7 +143,8 @@ export const mapFill = (
   accountIndex: number,
   market: MarketDisplay
 ): Fill | undefined => {
-  const { size, price } = trade
+  const { size } = trade
+  const price = resolveTradePrice(trade)
   const createdAt = rowTimestampToIsoStringOrUndefined(trade.timestamp)
   if (createdAt === undefined) {
     warnSkippedVenueRow(
@@ -159,13 +181,13 @@ export const mapFill = (
     feeTick === undefined
       ? undefined
       : tickToFeeAmount(trade.usd_amount, feeTick, integratorFeeTick)
+  const liquidation = mapFillLiquidation(trade.type, isMaker)
 
   return {
     id: trade.trade_id_str,
     orderId: isBuyer ? trade.bid_id_str : trade.ask_id_str,
     market,
     side: isBuyer ? OrderSide.BUY : OrderSide.SELL,
-    type: OrderType.LIMIT,
     size,
     price,
     liquidity: isMaker ? LiquidityRole.MAKER : LiquidityRole.TAKER,
@@ -192,5 +214,6 @@ export const mapFill = (
     explorerLink: isPlaceholderTxHash(trade.tx_hash)
       ? undefined
       : explorerTxUrl(ExplorerChainId.LIGHTER, trade.tx_hash),
+    ...(liquidation === undefined ? {} : { liquidation }),
   }
 }

package/src/utils/mapOrder.ts

@@ -221,6 +221,7 @@ export const mapOrder = (
         price: order.price,
         timeInForce: mapTimeInForce(order.time_in_force),
         ...(expiresAt === undefined ? {} : { expiresAt }),
+        ...(order.type === 'liquidation' ? { isLiquidation: true } : {}),
       }
   }
 }

package/src/utils/mapPosition.ts

@@ -79,7 +79,9 @@ const warnUnreadableField = (field: string, value: unknown): void => {
  * an invalid size gives `undefined`. An invalid position value or a
  * non-positive initial margin fraction keeps the row, leaves `leverage` and
  * `initialMarginRequirement` absent, sets a cross `marginUsed` to `'0'` and
- * warns once. Prices, PnL, funding and isolated margin pass through raw.
+ * warns once. Prices, PnL, funding and isolated margin pass through raw. A
+ * zero or empty `liquidation_price`, which Lighter sends for a position that
+ * no price liquidates, leaves `liquidationPrice` absent.
  * @param market - Backend-resolved market identity for `pos.market_id`.
  * @public
  */
@@ -107,6 +109,10 @@ export const mapPosition = (
     positionValue === undefined || leverage === undefined
       ? undefined
       : divideDecimalString(multiplyDecimalString(positionValue, imf), '100')
+  const liquidationPrice = pos.liquidation_price
+  const hasLiquidationPrice = isDecimalString(liquidationPrice)
+    ? !isDecimalStringZero(liquidationPrice)
+    : liquidationPrice !== ''
 
   return {
     market,
@@ -121,7 +127,7 @@ export const mapPosition = (
               ? '0'
               : divideDecimalString(positionValue, size),
         }),
-    liquidationPrice: pos.liquidation_price,
+    ...(hasLiquidationPrice ? { liquidationPrice } : {}),
     unrealizedPnl: pos.unrealized_pnl,
     accruedFunding: pos.total_funding_paid_out ?? '0',
     ...(leverage === undefined ? {} : { leverage }),

package/src/utils/tradePrice.ts

@@ -0,0 +1,20 @@
+import {
+  safeDivideDecimalString,
+  safeIsDecimalStringZero,
+} from '@lifi/perps-sdk'
+import type { LtTrade } from '../types/index.js'
+
+/**
+ * Execution price of a Lighter trade row. Lighter reports a zero `price` on a
+ * `deleverage` row, but `usd_amount` still carries the execution notional, so
+ * that row resolves to `usd_amount / size`. Every other row, and a row whose
+ * division fails, keeps the venue `price`.
+ *
+ * @internal
+ */
+export const resolveTradePrice = (
+  trade: Pick<LtTrade, 'type' | 'price' | 'size' | 'usd_amount'>
+): string =>
+  trade.type === 'deleverage' && safeIsDecimalStringZero(trade.price) === true
+    ? (safeDivideDecimalString(trade.usd_amount, trade.size) ?? trade.price)
+    : trade.price

package/src/websocket/LighterWsProvider.ts

@@ -73,6 +73,7 @@ import {
   mapPosition,
 } from '../utils/index.js'
 import { spotPriceByAssetId, spotValuation } from '../utils/spotPrice.js'
+import { resolveTradePrice } from '../utils/tradePrice.js'
 import { askOrder, bidOrder, OrderBookSide } from './orderBookSide.js'
 
 // Public channels: `marketsContext` (market_stats/all + spot_market_stats/all),
@@ -1097,7 +1098,7 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       data: trades.map((t) => ({
         provider: this.providerKey,
         marketId: assetId,
-        price: t.price,
+        price: resolveTradePrice(t),
         size: t.size,
         timestamp: t.timestamp,
         side: t.is_maker_ask ? 'buy' : 'sell',