@lifi/perps-sdk-provider-lighter 30.0.0 → 31.0.0

package/src/utils/apiClient.ts

@@ -15,6 +15,15 @@ import { lighterErrorCodeFromBody } from './lighterErrorCode.js'
 /** @internal */
 export type ApiParams = Record<string, string | number | boolean>
 
+/**
+ * Short excerpt of a parsed Lighter body for an error message. `undefined`
+ * stands for a body that did not parse as JSON.
+ *
+ * @internal
+ */
+export const lighterBodyExcerpt = (data: unknown): string =>
+  data === undefined ? 'non-JSON body' : JSON.stringify(data).slice(0, 200)
+
 /**
  * Lighter signals errors on two channels: a non-2xx HTTP status, or an HTTP 200
  * carrying an error `code` in the JSON body. Returns the body error `code` when
@@ -269,7 +278,7 @@ export class LighterApiClient {
   async getWithStatus<T>(
     path: string,
     params?: ApiParams
-  ): Promise<{ status: number; data: T }> {
+  ): Promise<{ status: number; data: T | undefined }> {
     return this.sendGet<T>(path, params)
   }
 
@@ -277,7 +286,7 @@ export class LighterApiClient {
     path: string,
     params?: ApiParams,
     headers?: Record<string, string>
-  ): Promise<{ status: number; data: T }> {
+  ): Promise<{ status: number; data: T | undefined }> {
     this.assertRequestAllowed()
     const url = this.buildUrl(path, params)
     const response = await fetchWithRetry(
@@ -290,7 +299,7 @@ export class LighterApiClient {
       }
     )
     this.assertNotRateLimited(response)
-    const data = (await response.json().catch(() => undefined)) as T
+    const data = (await response.json().catch(() => undefined)) as T | undefined
     return { status: response.status, data }
   }
 
@@ -305,7 +314,7 @@ export class LighterApiClient {
     path: string,
     authToken: string,
     params: ApiParams
-  ): Promise<{ status: number; data: T }> {
+  ): Promise<{ status: number; data: T | undefined }> {
     const body = new URLSearchParams()
     for (const [k, v] of Object.entries(params)) {
       body.set(k, String(v))
@@ -320,7 +329,7 @@ export class LighterApiClient {
       signal: this.signal,
     })
     this.assertNotRateLimited(response)
-    const data = (await response.json().catch(() => undefined)) as T
+    const data = (await response.json().catch(() => undefined)) as T | undefined
     return { status: response.status, data }
   }
 
@@ -344,13 +353,13 @@ export class LighterApiClient {
     if (status < 200 || status >= 300) {
       throw new PerpsError(
         code,
-        `Lighter API request failed: ${status} — ${JSON.stringify(data).slice(0, 200)}`
+        `Lighter API request failed: ${status} — ${lighterBodyExcerpt(data)}`
       )
     }
     if (errorCode !== undefined) {
       throw new PerpsError(
         code,
-        `Lighter API error for ${path}: code ${errorCode} — ${JSON.stringify(data).slice(0, 200)}`
+        `Lighter API error for ${path}: code ${errorCode} — ${lighterBodyExcerpt(data)}`
       )
     }
   }

package/src/utils/fetchDetailedAccount.ts

@@ -3,7 +3,7 @@ import { PerpsErrorCode } from '@lifi/perps-types'
 import type { Address } from 'viem'
 import { LIGHTER_CODE_ACCOUNT_NOT_FOUND } from '../constants.js'
 import type { LtAccount, LtDetailedAccount } from '../types/index.js'
-import type { LighterApiClient } from './apiClient.js'
+import { type LighterApiClient, lighterBodyExcerpt } from './apiClient.js'
 import { wireList } from './wireList.js'
 
 /**
@@ -33,7 +33,7 @@ export const fetchDetailedAccount = async (
   if (status < 200 || status >= 300) {
     throw new PerpsError(
       PerpsErrorCode.ThirdPartyError,
-      `Lighter account request failed: ${status} — ${JSON.stringify(data).slice(0, 200)}`
+      `Lighter account request failed: ${status} — ${lighterBodyExcerpt(data)}`
     )
   }
 

package/src/utils/mapFill.ts

@@ -6,12 +6,9 @@ import {
 import type { Fill, MarketDisplay } from '@lifi/perps-types'
 import { LiquidityRole, OrderSide, OrderType } from '@lifi/perps-types'
 import Big from 'big.js'
-import {
-  LIGHTER_FEE_TICK_SCALE,
-  LIGHTER_IMF_PERCENT_SCALE,
-} from '../constants.js'
+import { LIGHTER_FEE_TICK_SCALE } from '../constants.js'
 import type { LtTrade } from '../types/index.js'
-import { leverageFromImf } from './mapPosition.js'
+import { leverageFromScaledImf } from './mapPosition.js'
 import { isPlaceholderTxHash } from './txHash.js'
 
 /**
@@ -36,16 +33,12 @@ const tickToFeeAmount = (
     .toFixed()
 
 /**
- * Display leverage the viewer had set on the market when the trade executed.
- * Lighter reports it as the pre-trade initial margin fraction, an integer
- * percent on `LIGHTER_IMF_PERCENT_SCALE`: `500` is 5.00%, so 20x. Returns
- * `undefined` when the row omits the fraction. Lighter declares the fraction a
- * `StrictInt`, so the scale division is exact and `toFixed()` loses nothing.
+ * Display leverage the viewer had set on the market when the trade executed,
+ * from the pre-trade initial margin fraction. Returns `undefined` when the
+ * row omits the fraction.
  */
 const leverageFromTradeImf = (imf: number | undefined): number | undefined =>
-  imf === undefined
-    ? undefined
-    : leverageFromImf(new Big(imf).div(LIGHTER_IMF_PERCENT_SCALE).toFixed())
+  imf === undefined ? undefined : leverageFromScaledImf(imf)
 
 /**
  * Realized PnL on a position-reducing fill, derived from the pre-trade entry

package/src/utils/mapPortfolioHistory.ts

@@ -5,48 +5,63 @@ import type {
 import Big from 'big.js'
 import type { LtPnLEntry } from '../types/pnl.js'
 
+function getCumulativePnl(snapshot: LtPnLEntry): Big {
+  return new Big(snapshot.trade_pnl).plus(snapshot.trade_spot_pnl)
+}
+
+function getCumulativeNetFlow(snapshot: LtPnLEntry): Big {
+  return new Big(snapshot.inflow)
+    .minus(snapshot.outflow)
+    .plus(snapshot.spot_inflow)
+    .minus(snapshot.spot_outflow)
+}
+
 /**
- * Build the portfolio series from Lighter PnL buckets and the account's
- * current value. Lighter reports no historical account value, so each
- * point's `accountValue` is `currentValue` with every later bucket's
- * `trade_pnl + trade_spot_pnl + inflow - outflow` removed. `pnl` is the
- * running `trade_pnl + trade_spot_pnl`, so both series unwind the same PnL.
+ * Derive window-relative history from Lighter's cumulative PnL snapshots.
+ * Historical account values are anchored to the current account value.
  */
 export const mapPortfolioHistory = (
   range: PortfolioHistoryRange,
-  entries: LtPnLEntry[],
+  snapshots: LtPnLEntry[],
   currentValue: Big
 ): PortfolioHistoryResponse => {
-  const ordered = [...entries].sort((a, b) => a.timestamp - b.timestamp)
-
-  const accountValues: Big[] = []
-  let value = currentValue
-  for (let i = ordered.length - 1; i >= 0; i -= 1) {
-    accountValues[i] = value
-    const entry = ordered[i]
-    value = value
-      .minus(new Big(entry.trade_pnl))
-      .minus(new Big(entry.trade_spot_pnl))
-      .minus(new Big(entry.inflow))
-      .plus(new Big(entry.outflow))
+  const orderedSnapshots = [...snapshots].sort(
+    (a, b) => a.timestamp - b.timestamp
+  )
+  const firstSnapshot = orderedSnapshots[0]
+  const latestSnapshot = orderedSnapshots.at(-1)
+  if (!firstSnapshot || !latestSnapshot) {
+    return {
+      range,
+      points: [],
+      volume: '0',
+      totalPnl: undefined,
+    }
   }
 
-  let pnl = new Big(0)
-  let volume = new Big(0)
-  const points = ordered.map((entry, i) => {
-    pnl = pnl.plus(new Big(entry.trade_pnl)).plus(new Big(entry.trade_spot_pnl))
-    volume = volume.plus(new Big(entry.volume))
+  const firstPnl = getCumulativePnl(firstSnapshot)
+  const latestPnl = getCumulativePnl(latestSnapshot)
+  const accountValueOffset = currentValue
+    .minus(latestPnl)
+    .minus(getCumulativeNetFlow(latestSnapshot))
+  const points = orderedSnapshots.map((snapshot) => {
+    const pnl = getCumulativePnl(snapshot)
     return {
-      timestamp: entry.timestamp,
-      accountValue: accountValues[i].toFixed(),
-      pnl: pnl.toFixed(),
+      timestamp: snapshot.timestamp * 1_000,
+      accountValue: accountValueOffset
+        .plus(pnl)
+        .plus(getCumulativeNetFlow(snapshot))
+        .toFixed(),
+      pnl: pnl.minus(firstPnl).toFixed(),
     }
   })
 
   return {
     range,
     points,
-    volume: volume.toFixed(),
+    volume: new Big(latestSnapshot.volume)
+      .minus(firstSnapshot.volume)
+      .toFixed(),
     totalPnl: points.at(-1)?.pnl,
   }
 }

package/src/utils/mapPosition.ts

@@ -1,6 +1,7 @@
 import type { PerpsMarketDisplay, Position } from '@lifi/perps-types'
 import { MarginMode, PositionSide } from '@lifi/perps-types'
 import Big from 'big.js'
+import { LIGHTER_IMF_PERCENT_SCALE } from '../constants.js'
 import type { LtAccountPosition } from '../types/index.js'
 import { LT_MARGIN_MODE_ISOLATED } from '../types/index.js'
 import { toPositiveRequiredBig, toRequiredBig } from './decimal.js'
@@ -25,6 +26,22 @@ export const leverageFromImf = (imf: string): number | undefined => {
   return new Big(100).div(parsed).toNumber()
 }
 
+/**
+ * Display leverage from an integer IMF on `LIGHTER_IMF_PERCENT_SCALE`, the
+ * unit of trade rows and order-book details: `500` is 5.00%, so 20x.
+ * `undefined` for a non-positive or unparsable IMF. Lighter declares the
+ * fraction a `StrictInt`, so the scale division is exact.
+ */
+export const leverageFromScaledImf = (imf: number): number | undefined => {
+  let percent: string
+  try {
+    percent = new Big(imf).div(LIGHTER_IMF_PERCENT_SCALE).toFixed()
+  } catch {
+    return undefined
+  }
+  return leverageFromImf(percent)
+}
+
 /**
  * Map a raw Lighter account position to the generic Position type.
  * @param market - Backend-resolved market identity for `pos.market_id`.

package/src/utils/ohlcvInterval.ts

@@ -5,9 +5,11 @@ import { PerpsErrorCode } from '@lifi/perps-types'
 /**
  * Map our `OhlcvInterval` literal to Lighter's `resolution` enum.
  *
- * Lighter exposes only the timeframes listed below. SDK intervals without a
- * direct match (3m, 2h, 8h, 3d, 1w, 1M) raise a validation error rather than
- * silently rounding — the caller picks a supported timeframe.
+ * The keys are exactly the `resolution` enum of Lighter's `GET /api/v1/candles`.
+ * Lighter has no weekly candle (its API answers `1w` with code 20001,
+ * `invalid param`), so `1w` stays out. SDK intervals without a direct match
+ * (3m, 2h, 8h, 3d, 1w, 1M) raise a validation error rather than silently
+ * rounding — the caller picks a supported timeframe.
  */
 const LIGHTER_SUPPORTED_INTERVALS: Partial<Record<OhlcvInterval, string>> = {
   '1m': '1m',

package/src/utils/spotPrice.ts

@@ -1,5 +1,5 @@
 import type { Market, MarketContext } from '@lifi/perps-types'
-import type Big from 'big.js'
+import Big from 'big.js'
 import { toRequiredBig } from './decimal.js'
 
 /**
@@ -37,3 +37,23 @@ export const spotPriceByAssetId = (
   }
   return priceByAssetId
 }
+
+/**
+ * USD value of `units` of a Lighter asset, with the unit price it used: the
+ * settlement asset at 1, any other at its `spotPrices` entry. An asset absent
+ * from `spotPrices` values at 0 and carries no price.
+ */
+export const spotValuation = (
+  assetId: number,
+  units: string,
+  settlementAssetIndex: number,
+  spotPrices: ReadonlyMap<string, Big>
+): { valueUsd: string; price?: Big } => {
+  const price =
+    assetId === settlementAssetIndex
+      ? new Big(1)
+      : spotPrices.get(String(assetId))
+  return price === undefined
+    ? { valueUsd: '0' }
+    : { valueUsd: new Big(units).times(price).toFixed(), price }
+}

package/src/utils/withdrawableBalances.ts

@@ -1,20 +1,29 @@
-import type { ProviderWithdrawableBalance } from '@lifi/perps-sdk'
-import type { LtAccountAsset } from '../types/account.js'
+import { maxOf, minOf, type ProviderWithdrawableBalance } from '@lifi/perps-sdk'
+import Big from 'big.js'
+import type { LtAccount } from '../types/account.js'
 import { toRequiredBig } from './decimal.js'
 
 /**
  * Split each held asset into the two routes a Lighter withdrawal can name:
  * spot draws on `balance` net of `locked_balance`, perps draws on
- * `margin_balance`. Routes with nothing left to draw are dropped; the
- * per-asset venue minimum is applied by the caller holding the asset registry.
+ * `margin_balance`. The settlement asset's perps route is also capped by the
+ * account `available_balance`, which excludes the margin open positions use.
+ * Every other asset's perps route reports its full `margin_balance`, uncapped,
+ * although `getAccount` reports `transferable: '0'` for it: a category
+ * transfer moves only the settlement asset. Routes with nothing left to draw
+ * are dropped; the per-asset venue minimum is applied by the caller holding
+ * the asset registry.
  *
+ * @param settlementAssetIndex - L2 asset index of the deployment's collateral
+ * asset, the only asset that `available_balance` is denominated in.
  * @public
  */
 export const lighterWithdrawableBalances = (
-  assets: LtAccountAsset[]
+  account: Pick<LtAccount, 'assets' | 'available_balance'>,
+  settlementAssetIndex: number
 ): ProviderWithdrawableBalance[] => {
   const rows: ProviderWithdrawableBalance[] = []
-  for (const asset of assets) {
+  for (const asset of account.assets) {
     const assetId = String(asset.asset_id)
     const spot = toRequiredBig(asset.balance, 'balance').minus(
       toRequiredBig(asset.locked_balance, 'locked_balance')
@@ -22,7 +31,17 @@ export const lighterWithdrawableBalances = (
     if (spot.gt(0)) {
       rows.push({ assetId, route: 'spot', available: spot.toFixed() })
     }
-    const perps = toRequiredBig(asset.margin_balance, 'margin_balance')
+    const marginBalance = toRequiredBig(asset.margin_balance, 'margin_balance')
+    const perps =
+      asset.asset_id === settlementAssetIndex
+        ? minOf(
+            maxOf(
+              toRequiredBig(account.available_balance, 'available_balance'),
+              new Big(0)
+            ),
+            marginBalance
+          )
+        : marginBalance
     if (perps.gt(0)) {
       rows.push({ assetId, route: 'perps', available: perps.toFixed() })
     }