@lifi/perps-sdk-provider-lighter 26.0.0 → 28.0.0

package/src/accountSummary.ts

@@ -1,54 +1,61 @@
+import { PerpsError } from '@lifi/perps-sdk'
 import type {
   AccountResponse,
   AccountSummary,
+  LighterAccountConfig,
   Position,
 } from '@lifi/perps-types'
-import { MarginMode } from '@lifi/perps-types'
+import { PerpsErrorCode } from '@lifi/perps-types'
 import Big from 'big.js'
+import { toRequiredBig } from './utils/decimal.js'
+
+const lighterConfig = (account: AccountResponse): LighterAccountConfig => {
+  if (account.config.provider !== 'lighter') {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Lighter account summary received a '${account.config.provider}' account config`
+    )
+  }
+  return account.config
+}
 
 /**
- * Roll a Lighter {@link AccountResponse} up into an {@link AccountSummary}.
- *
- * 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.
+ * Roll a Lighter account up into an {@link AccountSummary}. `totalAssetValue`
+ * is perps-route equity and excludes the spot route, so `portfolioValue` adds
+ * every spot `balances` row, settlement included; the `collateralBalances` row
+ * is buying power already inside `totalAssetValue`. The positions supply only
+ * the margin and PnL breakdown.
  *
+ * @throws {PerpsError} `SDKError` when the account is not a Lighter one.
  * @public
  */
 export function getAccountSummary(
   account: AccountResponse,
   positions: Position[]
 ): AccountSummary {
-  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)
-  }
+  const config = lighterConfig(account)
 
   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)
-    }
+  }
+
+  let portfolioValue = toRequiredBig(config.totalAssetValue, 'totalAssetValue')
+  for (const balance of account.balances) {
+    portfolioValue = portfolioValue.plus(
+      toRequiredBig(balance.valueUsd, 'valueUsd')
+    )
   }
 
   return {
-    portfolioValue: nonCollateralValue
-      .plus(availableMargin)
-      .plus(marginUsed)
-      .plus(isolatedUnrealizedPnl)
-      .toString(),
-    availableMargin: availableMargin.toString(),
-    marginUsed: marginUsed.toString(),
-    unrealizedPnl: unrealizedPnl.toString(),
+    portfolioValue: portfolioValue.toFixed(),
+    availableMargin: toRequiredBig(
+      config.availableBalance,
+      'availableBalance'
+    ).toFixed(),
+    marginUsed: marginUsed.toFixed(),
+    unrealizedPnl: unrealizedPnl.toFixed(),
   }
 }

package/src/utils/index.ts

@@ -23,7 +23,7 @@ export { mapMarketOrderLimits } from './marketLimits.js'
 export { mapInterval } from './ohlcvInterval.js'
 export { formatOrderPrice, formatOrderSize } from './orderFormatting.js'
 export { toIsoFromMs, toIsoFromSeconds } from './time.js'
-export { positionMarginConstraints } from './transferMargin.js'
+export { positionRemovableMargin } from './transferMargin.js'
 export {
   leverageToFraction,
   mapOrderTypeToInt,

package/src/utils/mapOrder.ts

@@ -61,9 +61,10 @@ const mapOrderStatus = (
   filledSize = new Big(order.filled_base_amount)
 ): OrderStatus => {
   switch (order.status) {
-    case 'pending':
     case 'in-progress':
       return OrderStatus.ACCEPTED
+    case 'pending':
+      return OrderStatus.OPEN
     case 'open':
       if (order.trigger_status === 'parent-order') {
         return OrderStatus.PENDING

package/src/utils/spotPrice.ts

@@ -0,0 +1,39 @@
+import type { Market, MarketContext } from '@lifi/perps-types'
+import type Big from 'big.js'
+import { toRequiredBig } from './decimal.js'
+
+/**
+ * Unit prices keyed by spot base `Asset.id` (the venue `asset_id`), read from
+ * each spot market's `markPrice` for the base assets in `assetIds` only. A
+ * market without a context row or with a non-positive mark adds no entry; when
+ * several spot markets share a base asset, the first priced one in `markets`
+ * order wins. The mark is read as a USD price; `quoteAsset` is not checked.
+ *
+ * @throws {PerpsError} `SDKError` when a context row for a requested asset
+ * carries a non-decimal mark.
+ */
+export const spotPriceByAssetId = (
+  markets: readonly Market[],
+  spotCategoryId: string,
+  contexts: readonly MarketContext[],
+  assetIds: ReadonlySet<string>
+): Map<string, Big> => {
+  const markByMarketId = new Map(contexts.map((c) => [c.marketId, c.markPrice]))
+  const priceByAssetId = new Map<string, Big>()
+  for (const market of markets) {
+    const mark = markByMarketId.get(market.id)
+    if (
+      market.categoryId !== spotCategoryId ||
+      mark === undefined ||
+      !assetIds.has(market.baseAsset.id) ||
+      priceByAssetId.has(market.baseAsset.id)
+    ) {
+      continue
+    }
+    const price = toRequiredBig(mark, 'markPrice')
+    if (price.gt(0)) {
+      priceByAssetId.set(market.baseAsset.id, price)
+    }
+  }
+  return priceByAssetId
+}

package/src/utils/transferMargin.ts

@@ -1,31 +1,69 @@
+import { PerpsError } from '@lifi/perps-sdk'
 import {
+  PerpsErrorCode,
   type Position,
-  type PositionMarginConstraints,
   positionSupportsMarginAdjustment,
+  positionSupportsMarginRemoval,
 } from '@lifi/perps-types'
-import { toPositiveRequiredBig } from './decimal.js'
+import Big from 'big.js'
 
-const AMOUNT_INCREMENT = '0.000001'
+const AMOUNT_DECIMALS = 6
+
+function positionAmount(value: string, field: string): Big {
+  try {
+    return new Big(value)
+  } catch {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid decimal string on Position.${field}: '${value}'`
+    )
+  }
+}
+
+function positivePositionAmount(value: string, field: string): Big {
+  const amount = positionAmount(value, field)
+  if (amount.lte(0)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Position.${field} must be greater than zero.`
+    )
+  }
+  return amount
+}
 
 /**
- * Lighter's exact isolated-margin requirement. Lighter publishes no separate
- * notional floor, so the provider-normalized initial-margin requirement is
- * the retained amount.
+ * Lighter removable isolated margin:
+ * `allocated_margin + unrealized PnL − initial margin requirement`. Lighter
+ * `allocated_margin` (`Position.marginUsed`) excludes the unrealized PnL, and
+ * Lighter publishes no separate notional floor.
  *
+ * @returns `undefined` for cross positions and markets without individual
+ *   margin adjustment; `'0'` for add-only markets and when nothing is
+ *   removable.
+ * @throws {PerpsError} `ValidationError` when a required `Position` decimal
+ *   is malformed or not positive.
  * @see https://docs.lighter.xyz/trading/liquidations-and-llp-insurance-fund
  * @public
  */
-export function positionMarginConstraints(
+export function positionRemovableMargin(
   position: Position
-): PositionMarginConstraints | undefined {
+): string | undefined {
   if (!positionSupportsMarginAdjustment(position)) {
     return undefined
   }
-  return {
-    minimumMarginRequirement: toPositiveRequiredBig(
-      position.initialMarginRequirement,
-      'initialMarginRequirement'
-    ).toFixed(),
-    amountIncrement: AMOUNT_INCREMENT,
+  if (!positionSupportsMarginRemoval(position)) {
+    return '0'
+  }
+  const removable = positivePositionAmount(position.marginUsed, 'marginUsed')
+    .plus(positionAmount(position.unrealizedPnl, 'unrealizedPnl'))
+    .minus(
+      positivePositionAmount(
+        position.initialMarginRequirement,
+        'initialMarginRequirement'
+      )
+    )
+  if (removable.lte(0)) {
+    return '0'
   }
+  return removable.round(AMOUNT_DECIMALS, Big.roundDown).toFixed()
 }

package/src/websocket/LighterWsProvider.ts

@@ -374,6 +374,7 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
         return `accountSummary:${sub.address.toLowerCase()}`
       case 'candle':
       case 'spotBalances':
+      case 'availableToTrade':
         throw new Error(`Lighter WS does not support channel: ${sub.channel}.`)
     }
   }