@lifi/perps-sdk-provider-lighter 6.0.0 → 8.0.0

package/src/LighterProvider.ts

@@ -1,4 +1,5 @@
 import {
+  type DepositFlow,
   explorerTxUrlFromBase,
   getAssetRegistry,
   getMarketRegistry,
@@ -9,7 +10,9 @@ import {
   type ProviderAccountExistsParams,
   type ProviderGetAccountParams,
   type ProviderGetActivityParams,
+  type ProviderGetDepositFlowParams,
   type ProviderGetFillsParams,
+  type ProviderGetMarketSettingsParams,
   type ProviderGetOrderParams,
   type ProviderGetOrdersParams,
   type ProviderGetPositionsParams,
@@ -18,6 +21,7 @@ import {
   resolveRetryPolicy,
   type SDKRequestOptions,
   type SignActionsContext,
+  toPerpsMarketDisplay,
 } from '@lifi/perps-sdk'
 import type {
   AccountConfig,
@@ -31,6 +35,7 @@ import type {
   FillsResponse,
   LighterAccountConfig,
   LighterProviderKey,
+  MarketSettings,
   Order,
   OrdersResponse,
   Position,
@@ -40,7 +45,12 @@ import type {
   SignedActionStep,
   SigningMethod,
 } from '@lifi/perps-types'
-import { ActionType, ActivityType, PerpsErrorCode } from '@lifi/perps-types'
+import {
+  ActionType,
+  ActivityType,
+  MarginMode,
+  PerpsErrorCode,
+} from '@lifi/perps-types'
 import type { Address } from 'viem'
 import { projectLighterConfigSettings } from './accountConfig.js'
 import { getAccountSummary } from './accountSummary.js'
@@ -56,6 +66,7 @@ import {
   LIGHTER_PROVIDER_KEY,
   LIGHTER_SPOT_CATEGORY_ID,
 } from './constants.js'
+import { lighterDepositFlow } from './depositFlow.js'
 import { createAuthToken } from './signers/createAuthToken.js'
 import type { LighterKeyStore } from './signers/LighterKeyStore.js'
 import type { LighterReadOnlyTokenManagerOptions } from './signers/LighterReadOnlyTokenManager.js'
@@ -74,6 +85,7 @@ import type {
   LtTransferHistoryResponse,
   LtWithdrawHistoryResponse,
 } from './types/index.js'
+import { LT_MARGIN_MODE_ISOLATED } from './types/index.js'
 import {
   decodeActivityCursor,
   encodeActivityCursor,
@@ -91,12 +103,15 @@ import {
   fetchDetailedAccount,
   formatOrderPrice,
   formatOrderSize,
+  leverageFromImf,
   lighterAsset,
   mapFill,
   mapOpenPositions,
   mapOrderDetail,
+  positionMarginConstraints,
   toIsoFromMs,
   toIsoFromSeconds,
+  toRequiredBig,
 } from './utils/index.js'
 
 const ZERO_FEE_TIER = { maker: '0', taker: '0' }
@@ -666,6 +681,24 @@ export const lighterProvider = (
     return { deposits, withdraws, fundings, liquidations, transfers }
   }
 
+  const resolveAccountExists = async (
+    address: Address,
+    opts?: SDKRequestOptions
+  ): Promise<boolean> => {
+    try {
+      await fetchDetailedAccount(apiClient(opts), address)
+      return true
+    } catch (err) {
+      if (
+        err instanceof PerpsError &&
+        err.code === PerpsErrorCode.AccountNotFound
+      ) {
+        return false
+      }
+      throw err
+    }
+  }
+
   return {
     type: providerKey,
 
@@ -734,7 +767,7 @@ export const lighterProvider = (
           normalizeLighterPublicKey(registeredKey.public_key)
 
       const positions: Position[] = mapOpenPositions(account.positions, (id) =>
-        registry.require(String(id))
+        toPerpsMarketDisplay(registry.require(String(id)))
       )
 
       const totalMarginUsed = positions.reduce(
@@ -753,16 +786,24 @@ export const lighterProvider = (
         categories.find((c) => c.quoteAsset === null)?.id ??
         LIGHTER_SPOT_CATEGORY_ID
 
-      // USDC collateral is the category quote asset → collateralBalances.
-      // `available_balance` is the free collateral (Lighter's `collateral` is
-      // gross, i.e. includes margin locked in positions); the locked portion is
-      // carried by the positions' `marginUsed`.
+      // Cross buying power is isolated from per-position allocations. Lighter
+      // reports cross equity (already marked by cross uPnL) separately from
+      // the initial margin locked by cross positions.
+      const availableMargin = toRequiredBig(
+        account.cross_asset_value,
+        'cross_asset_value'
+      ).minus(
+        toRequiredBig(
+          account.cross_initial_margin_requirement,
+          'cross_initial_margin_requirement'
+        )
+      )
       const collateralBalances: Balance[] = [
         {
           categoryId: perpsCategory?.id ?? providerKey,
           asset: perpsCategory?.quoteAsset ?? lighterAsset('USDC', 'USDC'),
-          units: account.available_balance,
-          valueUsd: account.available_balance,
+          units: availableMargin.toString(),
+          valueUsd: availableMargin.toString(),
         },
       ]
       // Spot token holdings — non-collateral. USDC value is 1:1; other tokens
@@ -826,18 +867,17 @@ export const lighterProvider = (
       params: ProviderAccountExistsParams,
       opts?: SDKRequestOptions
     ): Promise<boolean> {
-      try {
-        await fetchDetailedAccount(apiClient(opts), params.address)
-        return true
-      } catch (err) {
-        if (
-          err instanceof PerpsError &&
-          err.code === PerpsErrorCode.AccountNotFound
-        ) {
-          return false
-        }
-        throw err
-      }
+      return resolveAccountExists(params.address, opts)
+    },
+
+    async getDepositFlow(
+      params: ProviderGetDepositFlowParams,
+      opts?: SDKRequestOptions
+    ): Promise<DepositFlow> {
+      return lighterDepositFlow(
+        providerKey,
+        await resolveAccountExists(params.address, opts)
+      )
     },
 
     async getPositions(
@@ -852,7 +892,7 @@ export const lighterProvider = (
       ])
 
       let positions: Position[] = mapOpenPositions(account.positions, (id) =>
-        registry.require(String(id))
+        toPerpsMarketDisplay(registry.require(String(id)))
       )
 
       if (params.marketId !== undefined) {
@@ -866,6 +906,50 @@ export const lighterProvider = (
       }
     },
 
+    /**
+     * Lighter reports a market's margin mode and leverage only on the
+     * account's position row, so a market the account never touched (or a
+     * missing account) resolves `undefined` rather than a venue default.
+     */
+    async getMarketSettings(
+      params: ProviderGetMarketSettingsParams,
+      opts?: SDKRequestOptions
+    ): Promise<MarketSettings | undefined> {
+      // Spot markets carry no margin mode or leverage.
+      if (params.market.categoryId === LIGHTER_SPOT_CATEGORY_ID) {
+        return undefined
+      }
+      let account: LtDetailedAccount
+      try {
+        account = await fetchDetailedAccount(apiClient(opts), params.address)
+      } catch (err) {
+        if (
+          err instanceof PerpsError &&
+          err.code === PerpsErrorCode.AccountNotFound
+        ) {
+          return undefined
+        }
+        throw err
+      }
+      const row = account.positions.find(
+        (p) => String(p.market_id) === params.market.marketId
+      )
+      if (!row) {
+        return undefined
+      }
+      const leverage = leverageFromImf(row.initial_margin_fraction)
+      if (leverage === undefined) {
+        return undefined
+      }
+      return {
+        marginMode:
+          row.margin_mode === LT_MARGIN_MODE_ISOLATED
+            ? MarginMode.ISOLATED
+            : MarginMode.CROSS,
+        leverage,
+      }
+    },
+
     /**
      * Lighter's `accountActiveOrders` endpoint takes no limit/cursor and
      * returns every active order for the account, so the response is always
@@ -1235,6 +1319,8 @@ export const lighterProvider = (
 
     estimateLiquidationPrice,
 
+    positionMarginConstraints,
+
     projectConfig(
       config: AccountConfig,
       setup: ProviderAction[],

package/src/accountSummary.ts

@@ -1,16 +1,18 @@
-import { summarizeAccount } from '@lifi/perps-sdk'
 import type {
   AccountResponse,
   AccountSummary,
   Position,
 } from '@lifi/perps-types'
+import { MarginMode } from '@lifi/perps-types'
+import Big from 'big.js'
 
 /**
  * Roll a Lighter {@link AccountResponse} up into an {@link AccountSummary}.
- * Lighter has a single flat collateral model with no abstraction modes: the
- * collateral rows hold `available_balance`, which nets locked margin out but
- * marks unrealized PnL in — so only the positions' `marginUsed` is added
- * back for the portfolio value, never their PnL.
+ *
+ * Lighter's cross available balance is already marked to market, while an
+ * isolated position's unrealized PnL remains inside that position's isolated
+ * sub-account. Reconciliation therefore adds every position's locked margin,
+ * but adds unrealized PnL only for isolated positions.
  *
  * @public
  */
@@ -18,5 +20,35 @@ export function getAccountSummary(
   account: AccountResponse,
   positions: Position[]
 ): AccountSummary {
-  return summarizeAccount(account, positions, 'net')
+  let availableMargin = new Big(0)
+  for (const balance of account.collateralBalances) {
+    availableMargin = availableMargin.plus(balance.valueUsd)
+  }
+
+  let nonCollateralValue = new Big(0)
+  for (const balance of account.balances) {
+    nonCollateralValue = nonCollateralValue.plus(balance.valueUsd)
+  }
+
+  let marginUsed = new Big(0)
+  let unrealizedPnl = new Big(0)
+  let isolatedUnrealizedPnl = new Big(0)
+  for (const position of positions) {
+    marginUsed = marginUsed.plus(position.marginUsed)
+    unrealizedPnl = unrealizedPnl.plus(position.unrealizedPnl)
+    if (position.marginMode === MarginMode.ISOLATED) {
+      isolatedUnrealizedPnl = isolatedUnrealizedPnl.plus(position.unrealizedPnl)
+    }
+  }
+
+  return {
+    portfolioValue: nonCollateralValue
+      .plus(availableMargin)
+      .plus(marginUsed)
+      .plus(isolatedUnrealizedPnl)
+      .toString(),
+    availableMargin: availableMargin.toString(),
+    marginUsed: marginUsed.toString(),
+    unrealizedPnl: unrealizedPnl.toString(),
+  }
 }

package/src/depositFlow.ts

@@ -0,0 +1,59 @@
+import {
+  type DeclaredDepositAsset,
+  type DepositFlow,
+  ETHEREUM_NATIVE_GAS,
+  ETHEREUM_USDC,
+  LIGHTER_USDC,
+  ROBINHOOD_NATIVE_GAS,
+  ROBINHOOD_USDG,
+} from '@lifi/perps-sdk'
+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
+}
+
+const DEPOSIT_ASSETS: Record<LighterProviderKey, LighterDepositAssets> = {
+  [LIGHTER_PROVIDER_KEY]: {
+    venueCollateral: LIGHTER_USDC,
+    firstDepositCollateral: ETHEREUM_USDC,
+    firstDepositGas: ETHEREUM_NATIVE_GAS,
+  },
+  [LIGHTER_RH_PROVIDER_KEY]: {
+    venueCollateral: ROBINHOOD_USDG,
+    firstDepositCollateral: ROBINHOOD_USDG,
+    firstDepositGas: 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.
+ *
+ * @public
+ */
+export function lighterDepositFlow(
+  providerKey: LighterProviderKey,
+  accountExists: boolean
+): DepositFlow {
+  const assets = DEPOSIT_ASSETS[providerKey]
+
+  if (accountExists) {
+    return { kind: 'lifiSwap', destination: assets.venueCollateral }
+  }
+
+  return {
+    kind: 'firstDepositPipeline',
+    chainId: assets.firstDepositCollateral.chainId,
+    gasAsset: assets.firstDepositGas,
+    collateral: assets.firstDepositCollateral,
+    bridgeAction: ActionType.DEPOSIT,
+  }
+}

package/src/index.ts

@@ -33,6 +33,7 @@ export {
   LIGHTER_SPOT_CATEGORY_ID,
   lighterRhInstance,
 } from './constants.js'
+export { lighterDepositFlow } from './depositFlow.js'
 export type {
   LighterPerpsProvider,
   LighterProviderOptions,

package/src/types/account.ts

@@ -79,6 +79,9 @@ export interface LtDetailedAccount {
   assets: LtAccountAsset[]
   total_asset_value: string
   cross_asset_value: string
+  /** Initial margin locked by cross positions; isolated positions carry
+   * their own `allocated_margin` instead. */
+  cross_initial_margin_requirement: string
   approved_integrators?: LtApprovedIntegrator[]
 }
 

package/src/types/ws.ts

@@ -150,7 +150,10 @@ export type LtWsAccountAllTradesMessage = LtWsMessage & {
 }
 
 /**
- * `user_stats/{account_index}` frame; decimal strings in USD.
+ * `user_stats/{account_index}` frame; decimal strings in USD. The top-level
+ * figures span the whole account (`available_balance` = total withdrawable,
+ * including isolated positions' excess margin); `cross_stats` scopes them to
+ * the cross pool, whose `available_balance` is the free tradable collateral.
  * @public
  */
 export type LtWsUserStatsMessage = LtWsMessage & {
@@ -158,6 +161,11 @@ export type LtWsUserStatsMessage = LtWsMessage & {
     collateral?: string
     portfolio_value?: string
     available_balance?: string
+    cross_stats?: {
+      collateral: string
+      portfolio_value: string
+      available_balance: string
+    }
   }
 }
 

package/src/utils/decimal.ts

@@ -0,0 +1,52 @@
+import { PerpsError } from '@lifi/perps-sdk'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import Big from 'big.js'
+
+/**
+ * Exact-decimal parse of a venue decimal string; null when absent or
+ * unparsable, so callers can gate on presence before deriving.
+ * @public
+ */
+export const toBigOrNull = (value: string | undefined): Big | null => {
+  if (value === undefined) {
+    return null
+  }
+  try {
+    return new Big(value)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Parse a required venue decimal and identify the bad field on failure.
+ * @public
+ */
+export const toRequiredBig = (
+  value: string | undefined,
+  field: string
+): Big => {
+  const parsed = toBigOrNull(value)
+  if (parsed !== null) {
+    return parsed
+  }
+  throw new PerpsError(
+    PerpsErrorCode.SDKError,
+    `Lighter field \`${field}\` is not a valid decimal.`
+  )
+}
+
+/** Parse a required venue decimal that must be greater than zero. */
+export const toPositiveRequiredBig = (
+  value: string | undefined,
+  field: string
+): Big => {
+  const parsed = toRequiredBig(value, field)
+  if (parsed.lte(0)) {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Lighter field \`${field}\` must be greater than zero.`
+    )
+  }
+  return parsed
+}

package/src/utils/index.ts

@@ -9,6 +9,7 @@ export {
 } from './activityCursor.js'
 export { LighterApiClient } from './apiClient.js'
 export { assetMarginModeInt, isAssetMarginEnabled } from './assetCollateral.js'
+export { toBigOrNull, toRequiredBig } from './decimal.js'
 export { fetchDetailedAccount } from './fetchDetailedAccount.js'
 export { lighterAsset } from './lighterAsset.js'
 export { estimateLiquidationPrice } from './liquidation.js'
@@ -24,10 +25,11 @@ export {
   mapStatusReason,
   mapTriggerOrder,
 } from './mapOrder.js'
-export { mapPosition } from './mapPosition.js'
+export { leverageFromImf, mapPosition } from './mapPosition.js'
 export { mapInterval } from './ohlcvInterval.js'
 export { formatOrderPrice, formatOrderSize } from './orderFormatting.js'
 export { toIsoFromMs, toIsoFromSeconds } from './time.js'
+export { positionMarginConstraints } from './transferMargin.js'
 export {
   leverageToFraction,
   mapOrderTypeToInt,

package/src/utils/mapOpenPositions.ts

@@ -1,4 +1,4 @@
-import type { MarketDisplay, Position } from '@lifi/perps-types'
+import type { PerpsMarketDisplay, Position } from '@lifi/perps-types'
 import type { LtAccountPosition } from '../types/index.js'
 import { mapPosition } from './mapPosition.js'
 
@@ -11,7 +11,7 @@ import { mapPosition } from './mapPosition.js'
  */
 export const mapOpenPositions = (
   positions: LtAccountPosition[],
-  resolveMarket: (marketId: number) => MarketDisplay
+  resolveMarket: (marketId: number) => PerpsMarketDisplay
 ): Position[] =>
   positions
     .filter((p) => Number.parseFloat(p.position) !== 0)

package/src/utils/mapPosition.ts

@@ -1,7 +1,29 @@
-import type { MarketDisplay, Position } from '@lifi/perps-types'
+import type { PerpsMarketDisplay, Position } from '@lifi/perps-types'
 import { MarginMode, PositionSide } from '@lifi/perps-types'
+import Big from 'big.js'
 import type { LtAccountPosition } from '../types/index.js'
 import { LT_MARGIN_MODE_ISOLATED } from '../types/index.js'
+import { toPositiveRequiredBig, toRequiredBig } from './decimal.js'
+
+/**
+ * Display leverage from an IMF percent string: `100 / IMF` in exact decimal
+ * arithmetic before conversion to `number`. This value is for displaying the
+ * venue setting; provider risk calculations consume the original decimal IMF
+ * instead. `undefined` for a non-positive or unparsable IMF.
+ * @public
+ */
+export const leverageFromImf = (imf: string): number | undefined => {
+  let parsed: Big
+  try {
+    parsed = new Big(imf)
+  } catch {
+    return undefined
+  }
+  if (parsed.lte(0)) {
+    return undefined
+  }
+  return new Big(100).div(parsed).toNumber()
+}
 
 /**
  * Map a raw Lighter account position to the generic Position type.
@@ -10,33 +32,37 @@ import { LT_MARGIN_MODE_ISOLATED } from '../types/index.js'
  */
 export const mapPosition = (
   pos: LtAccountPosition,
-  market: MarketDisplay
+  market: PerpsMarketDisplay
 ): Position => {
-  const size = parseFloat(pos.position)
+  const size = toRequiredBig(pos.position, '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 positionValue = toRequiredBig(
+    pos.position_value,
+    'position_value'
+  ).abs()
+  const imf = toPositiveRequiredBig(
+    pos.initial_margin_fraction,
+    'initial_margin_fraction'
+  )
+  const initialMarginRequirement = positionValue.times(imf).div(100)
   const marginUsed = isIsolated
     ? pos.allocated_margin
-    : ((positionValue * imf) / 100).toString()
+    : initialMarginRequirement.toFixed()
 
   return {
     market,
     side: pos.sign >= 0 ? PositionSide.LONG : PositionSide.SHORT,
-    size: Math.abs(size).toString(),
+    size: size.abs().toFixed(),
     entryPrice: pos.avg_entry_price,
     markPrice:
-      pos.position_value === '0' || size === 0
+      positionValue.eq(0) || size.eq(0)
         ? '0'
-        : (parseFloat(pos.position_value) / Math.abs(size)).toString(),
+        : positionValue.div(size.abs()).toFixed(),
     liquidationPrice: pos.liquidation_price,
     unrealizedPnl: pos.unrealized_pnl,
-    leverage: imf > 0 ? Math.round(100 / imf) : 1,
+    leverage: leverageFromImf(pos.initial_margin_fraction) ?? 1,
     marginUsed,
+    initialMarginRequirement: initialMarginRequirement.toFixed(),
     marginMode: isIsolated ? MarginMode.ISOLATED : MarginMode.CROSS,
   }
 }

package/src/utils/transferMargin.ts

@@ -0,0 +1,35 @@
+import {
+  MarginMode,
+  type Position,
+  PositionMarginAdjustment,
+  type PositionMarginConstraints,
+} from '@lifi/perps-types'
+import { toPositiveRequiredBig } from './decimal.js'
+
+const AMOUNT_INCREMENT = '0.000001'
+
+/**
+ * Lighter's exact isolated-margin requirement. Lighter publishes no separate
+ * notional floor, so the provider-normalized initial-margin requirement is
+ * the retained amount.
+ *
+ * @see https://docs.lighter.xyz/trading/liquidations-and-llp-insurance-fund
+ * @public
+ */
+export function positionMarginConstraints(
+  position: Position
+): PositionMarginConstraints | undefined {
+  if (
+    position.marginMode !== MarginMode.ISOLATED ||
+    position.market.positionMarginAdjustment === PositionMarginAdjustment.NONE
+  ) {
+    return undefined
+  }
+  return {
+    minimumMarginRequirement: toPositiveRequiredBig(
+      position.initialMarginRequirement,
+      'initialMarginRequirement'
+    ).toFixed(),
+    amountIncrement: AMOUNT_INCREMENT,
+  }
+}