@lifi/perps-sdk-provider-lighter 35.0.0 → 36.0.0

package/dist/types/websocket/orderBookSide.d.ts

@@ -0,0 +1,33 @@
+import type { LtWsOrderBook } from '../types/index.js';
+/**
+ * Orders two decimal-string prices: a negative result puts `a` before `b`.
+ *
+ * @throws {PerpsError} `ValidationError` when a price is not a decimal string.
+ */
+export type PriceOrder = (a: string, b: string) => number;
+export declare const bidOrder: PriceOrder;
+export declare const askOrder: PriceOrder;
+/**
+ * One side of a maintained order book, keyed by the wire price string. Levels
+ * stay in `order` across updates, so a read copies them without a sort.
+ */
+export declare class OrderBookSide {
+    private readonly order;
+    private readonly providerKey;
+    private readonly byPrice;
+    private readonly levels;
+    constructor(order: PriceOrder, providerKey: string);
+    /**
+     * Applies snapshot or delta levels; a zero size deletes the level. A level
+     * with an invalid size also deletes the level at its price, so the book
+     * never keeps a size the venue has replaced.
+     */
+    apply(updates: LtWsOrderBook['bids']): void;
+    toLevels(): Array<{
+        price: string;
+        size: string;
+    }>;
+    private remove;
+    private bound;
+}
+//# sourceMappingURL=orderBookSide.d.ts.map

package/dist/types/websocket/orderBookSide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orderBookSide.d.ts","sourceRoot":"","sources":["../../../src/websocket/orderBookSide.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEtD;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;AAEzD,eAAO,MAAM,QAAQ,EAAE,UAAkD,CAAA;AACzE,eAAO,MAAM,QAAQ,EAAE,UAAkD,CAAA;AAOzE;;;GAGG;AACH,qBAAa,aAAa;IAKtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAL9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;gBAGtB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,MAAM;IAGtC;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI;IAgC3C,QAAQ,IAAI,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAIlD,OAAO,CAAC,MAAM;IAed,OAAO,CAAC,KAAK;CAad"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk-provider-lighter",
-  "version": "35.0.0",
+  "version": "36.0.0",
   "description": "Lighter provider plugin for @lifi/perps-sdk",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -44,10 +44,10 @@
   "dependencies": {
     "big.js": "^7.0.1",
     "viem": "^2.55.18",
-    "@lifi/perps-types": "^20.1.0"
+    "@lifi/perps-types": "^21.0.0"
   },
   "peerDependencies": {
-    "@lifi/perps-sdk": "^23.0.0"
+    "@lifi/perps-sdk": "^24.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/LighterProvider.ts

@@ -2,6 +2,7 @@ import {
   ACTIVE_ORDER_STATUSES,
   calculateTransferable,
   type DepositFlow,
+  estimateLiquidationPriceAtMarketRate,
   explorerTxUrl,
   explorerTxUrlFromBase,
   getAssetRegistry,
@@ -9,7 +10,7 @@ import {
   getMarketsContext,
   getProviders,
   isActiveOrderStatus,
-  isDecimalString,
+  isDecimalStringGreaterThan,
   localStorageAdapter,
   numberToDecimalString,
   PerpsError,
@@ -28,6 +29,7 @@ import {
   type ProviderGetPositionsParams,
   type ProviderGetQuoteParams,
   type ProviderGetWithdrawableBalancesParams,
+  type ProviderGetWithdrawalTypesParams,
   type ProviderWithdrawableBalance,
   paginateActivity,
   resolveQuote,
@@ -35,7 +37,13 @@ import {
   type SDKRequestOptions,
   type SignActionsContext,
   type StorageAdapter,
+  safeAbsDecimalString,
+  safeAddDecimalString,
+  safeMultiplyDecimalString,
+  subtractDecimalString,
   toPerpsMarketDisplay,
+  unknownToDecimalString,
+  type WithdrawalSourceTypes,
 } from '@lifi/perps-sdk'
 import type {
   AccountConfig,
@@ -70,7 +78,6 @@ import {
   MarginMode,
   PerpsErrorCode,
 } from '@lifi/perps-types'
-import Big from 'big.js'
 import type { Address } from 'viem'
 import {
   boundAccountTiers,
@@ -111,6 +118,7 @@ import type {
   LtAccountPnL,
   LtDepositHistoryItem,
   LtDepositHistoryResponse,
+  LtFastwithdrawInfoResponse,
   LtLiquidation,
   LtLiquidationsResponse,
   LtOrder,
@@ -119,6 +127,7 @@ import type {
   LtPositionFundingsResponse,
   LtTradesResponse,
   LtTransfer,
+  LtTransferFeeInfoResponse,
   LtTransferHistoryResponse,
   LtWithdrawHistoryItem,
   LtWithdrawHistoryResponse,
@@ -142,11 +151,13 @@ import {
 } from './utils/apiClient.js'
 import { isAssetMarginEnabled } from './utils/assetCollateral.js'
 import {
-  estimateLiquidationPrice,
   fetchDetailedAccount,
+  type LighterFastWithdrawal,
   leverageFromImf,
   lighterAsset,
+  lighterFastWithdrawal,
   lighterWithdrawableBalances,
+  lighterWithdrawalTypes,
   mapFill,
   mapOpenPositions,
   mapOrder,
@@ -154,11 +165,10 @@ import {
   positionRemovableMargin,
   snapOrderPrice,
   snapOrderSize,
-  toBigOrNull,
   toIsoFromMs,
   toIsoFromSeconds,
-  toRequiredBig,
 } from './utils/index.js'
+import { requireOpenPositions } from './utils/mapOpenPositions.js'
 import {
   fetchRegisteredApiKey,
   normalizeLighterPublicKey,
@@ -174,6 +184,14 @@ import { wireList } from './utils/wireList.js'
 
 const ZERO_FEE_TIER = { maker: '0', taker: '0' }
 
+/** The sum of `values`, or `undefined` when any term is not a decimal string. */
+const safeSum = (values: readonly string[]): string | undefined =>
+  values.reduce<string | undefined>(
+    (sum, value) =>
+      sum === undefined ? undefined : safeAddDecimalString(sum, value),
+    '0'
+  )
+
 const tickToFeeString = (tick: number): string =>
   numberToDecimalString(tick / LIGHTER_FEE_TICK_SCALE)
 
@@ -638,6 +656,86 @@ export const createLighterProvider = (
     }
   }
 
+  /**
+   * {@link retryOnRevoked}, then one retry with the standard token when the
+   * venue rejects the read-only one. The fallback sits outside
+   * `retryOnRevoked`, so a revocation the standard token reports never
+   * replaces the read-only one. The key is re-read at retry time because
+   * `REGISTER_API_KEY` can rotate it.
+   */
+  const retryWithStandardToken = <T>(
+    address: Address,
+    apiKey: LighterApiKey | null,
+    token: string,
+    run: (token: string) => Promise<T>
+  ): Promise<T> =>
+    retryOnRevoked(address, token, run).catch(async (err: unknown) => {
+      if (!(err instanceof LighterAuthRejectedError) || apiKey === null) {
+        throw err
+      }
+      const current = (await keyStore.get(address)) ?? apiKey
+      return run(
+        await getStandardAuthToken(address, current.apiKeyPrivateKey, {
+          apiKeyIndex: current.apiKeyIndex,
+          accountIndex: current.accountIndex,
+        })
+      )
+    })
+
+  const perpsCategoryId = async (): Promise<string> => {
+    const { providers } = await getProviders(requireClient())
+    return (
+      providers
+        .find((p) => p.key === providerKey)
+        ?.categories.find((c) => c.quoteAsset !== null)?.id ?? providerKey
+    )
+  }
+
+  /**
+   * The fast-withdraw terms for `accountIndex`, or `undefined` when no token
+   * resolves, a read fails, or Lighter offers no fast withdrawal.
+   */
+  const readFastWithdrawal = async (
+    client: LighterApiClient,
+    address: Address,
+    accountIndex: number
+  ): Promise<LighterFastWithdrawal | undefined> => {
+    try {
+      const apiKey = await keyStore.get(address)
+      const token = await resolveAuthToken(address, apiKey ?? undefined)
+      if (token === undefined) {
+        return undefined
+      }
+      const info = await retryWithStandardToken(address, apiKey, token, (t) =>
+        client.getAuthed<LtFastwithdrawInfoResponse>(
+          '/api/v1/fastwithdraw/info',
+          t,
+          { account_index: accountIndex }
+        )
+      )
+      if (info.code !== 200 || !(info.to_account_index > 0)) {
+        return undefined
+      }
+      const feeInfo = await retryWithStandardToken(
+        address,
+        apiKey,
+        token,
+        (t) =>
+          client.getAuthed<LtTransferFeeInfoResponse>(
+            '/api/v1/transferFeeInfo',
+            t,
+            {
+              account_index: accountIndex,
+              to_account_index: info.to_account_index,
+            }
+          )
+      )
+      return lighterFastWithdrawal(info, feeInfo)
+    } catch {
+      return undefined
+    }
+  }
+
   const fetchAccountLimits = (
     client: LighterApiClient,
     accountIndex: number,
@@ -830,7 +928,10 @@ export const createLighterProvider = (
         `The backend market '${marketId}' carries no positive Lighter default leverage`
       )
     }
-    return { marginMode: MarginMode.CROSS, leverage }
+    return {
+      marginMode: MarginMode.CROSS,
+      leverage: numberToDecimalString(leverage),
+    }
   }
 
   const resolveAccountExists = async (
@@ -994,26 +1095,22 @@ export const createLighterProvider = (
             ? readOnlyTokenManager.get(params.address, localKey.accountIndex)
             : Promise.resolve(undefined),
         ])
-      const positions: Position[] = mapOpenPositions(account.positions, (id) =>
-        toPerpsMarketDisplay(registry.require(String(id)))
+      const positions: Position[] = requireOpenPositions(
+        account.positions,
+        (id) => toPerpsMarketDisplay(registry.require(String(id)))
       )
 
-      const totalMarginUsed = positions.reduce(
-        (sum, p) => sum.plus(toRequiredBig(p.marginUsed, 'marginUsed')),
-        new Big(0)
-      )
-      const totalUnrealizedPnl = positions.reduce(
-        (sum, p) => sum.plus(toRequiredBig(p.unrealizedPnl, 'unrealizedPnl')),
-        new Big(0)
-      )
+      const totalMarginUsed = safeSum(positions.map((p) => p.marginUsed))
+      const totalUnrealizedPnl = safeSum(positions.map((p) => p.unrealizedPnl))
 
       const instanceMeta = providers.find((p) => p.key === providerKey)
       const categories = instanceMeta?.categories ?? []
       const perpsCategory = categories.find((c) => c.quoteAsset !== null)
 
-      const availableBalance = toRequiredBig(
+      const availableBalance = unknownToDecimalString(
         account.available_balance,
-        'available_balance'
+        'available_balance',
+        providerKey
       )
       // Each asset has a spot route (`balance`) and a perps route
       // (`margin_balance`). The instance's settlement asset is valued 1:1; an
@@ -1023,15 +1120,24 @@ export const createLighterProvider = (
         account.account_trading_mode === LT_ACCOUNT_TRADING_MODE_UNIFIED &&
         asset.asset_id === collateral.assetIndex
       const heldAssets = account.assets.filter((asset) =>
-        (isPooled(asset)
-          ? pooledSettlementUnits(asset)
-          : toRequiredBig(asset.balance, 'balance')
-        ).gt(0)
+        isDecimalStringGreaterThan(
+          isPooled(asset)
+            ? pooledSettlementUnits(asset)
+            : unknownToDecimalString(asset.balance, 'balance', providerKey),
+          '0'
+        )
       )
       const marginAssets = account.assets.filter(
         (asset) =>
           !isPooled(asset) &&
-          toRequiredBig(asset.margin_balance, 'margin_balance').gt(0)
+          isDecimalStringGreaterThan(
+            unknownToDecimalString(
+              asset.margin_balance,
+              'margin_balance',
+              providerKey
+            ),
+            '0'
+          )
       )
       const spotPrices = spotPriceByAssetId(
         registry.markets,
@@ -1060,7 +1166,7 @@ export const createLighterProvider = (
           asset,
           units,
           valueUsd,
-          ...(price === undefined ? {} : { price: price.toFixed() }),
+          ...(price === undefined ? {} : { price }),
         }
       }
       const registryAsset = (a: LtAccountAsset): Asset =>
@@ -1079,46 +1185,51 @@ export const createLighterProvider = (
       // account's free margin; every other perps-route asset releases none.
       const collateralBalances: Balance[] = marginAssets.map((a) => {
         const isSettlement = a.asset_id === collateral.assetIndex
-        const marginBalance = toRequiredBig(
+        const marginBalance = unknownToDecimalString(
           a.margin_balance,
-          'margin_balance'
-        ).toFixed()
+          'margin_balance',
+          providerKey
+        )
         return {
           ...toBalance(
             a,
             perpsCategory?.id ?? providerKey,
             isSettlement ? settlementAsset : registryAsset(a),
-            isDecimalString(a.margin_balance) ? a.margin_balance : marginBalance
+            marginBalance
           ),
           transferable: isSettlement
-            ? calculateTransferable(availableBalance.toFixed(), marginBalance)
+            ? calculateTransferable(availableBalance, marginBalance)
             : '0',
         }
       })
       const balances: Balance[] = heldAssets.map((a) => {
         if (isPooled(a)) {
-          const units = pooledSettlementUnits(a).toFixed()
+          const units = pooledSettlementUnits(a)
           return {
             ...toBalance(a, LIGHTER_SPOT_CATEGORY_ID, registryAsset(a), units),
             transferable: calculateTransferable(
-              pooledSettlementSpendable(a, availableBalance).toFixed(),
+              pooledSettlementSpendable(a, availableBalance),
               units
             ),
           }
         }
-        const balance = toRequiredBig(a.balance, 'balance')
+        const balance = unknownToDecimalString(
+          a.balance,
+          'balance',
+          providerKey
+        )
         return {
-          ...toBalance(
-            a,
-            LIGHTER_SPOT_CATEGORY_ID,
-            registryAsset(a),
-            isDecimalString(a.balance) ? a.balance : balance.toFixed()
-          ),
+          ...toBalance(a, LIGHTER_SPOT_CATEGORY_ID, registryAsset(a), balance),
           transferable: calculateTransferable(
+            subtractDecimalString(
+              balance,
+              unknownToDecimalString(
+                a.locked_balance,
+                'locked_balance',
+                providerKey
+              )
+            ),
             balance
-              .minus(toRequiredBig(a.locked_balance, 'locked_balance'))
-              .toFixed(),
-            balance.toFixed()
           ),
         }
       })
@@ -1169,8 +1280,12 @@ export const createLighterProvider = (
         balances,
         collateralBalances,
         positions,
-        marginUsed: totalMarginUsed.toFixed(),
-        unrealizedPnl: totalUnrealizedPnl.toFixed(),
+        ...(totalMarginUsed === undefined
+          ? {}
+          : { marginUsed: totalMarginUsed }),
+        ...(totalUnrealizedPnl === undefined
+          ? {}
+          : { unrealizedPnl: totalUnrealizedPnl }),
         feeTier:
           limitsResult === undefined
             ? ZERO_FEE_TIER
@@ -1200,11 +1315,41 @@ export const createLighterProvider = (
       params: ProviderGetWithdrawableBalancesParams,
       opts?: SDKRequestOptions
     ): Promise<ProviderWithdrawableBalance[]> {
-      const account = await fetchDetailedAccount(
-        apiClient(opts),
-        params.address
+      const [account, categoryId] = await Promise.all([
+        fetchDetailedAccount(apiClient(opts), params.address),
+        perpsCategoryId(),
+      ])
+      return lighterWithdrawableBalances(
+        account,
+        collateral.assetIndex,
+        categoryId
+      )
+    },
+
+    async getWithdrawalTypes(
+      params: ProviderGetWithdrawalTypesParams,
+      opts?: SDKRequestOptions
+    ): Promise<WithdrawalSourceTypes[]> {
+      const client = apiClient(opts)
+      const [account, categoryId] = await Promise.all([
+        fetchDetailedAccount(client, params.address),
+        perpsCategoryId(),
+      ])
+      const rows = lighterWithdrawableBalances(
+        account,
+        collateral.assetIndex,
+        categoryId
+      )
+      const fast = await readFastWithdrawal(
+        client,
+        params.address,
+        account.index
+      )
+      return lighterWithdrawalTypes(
+        rows,
+        { categoryId, asset: { id: String(collateral.assetIndex) } },
+        fast
       )
-      return lighterWithdrawableBalances(account, collateral.assetIndex)
     },
 
     async getPositions(
@@ -1249,18 +1394,20 @@ export const createLighterProvider = (
       }
       const account = await plugin.getAccount({ address: params.address }, opts)
       const config = lighterConfig(account)
-      const crossFreeCollateral = toRequiredBig(
-        config.crossAssetValue,
-        'crossAssetValue'
-      ).minus(
-        toRequiredBig(
-          config.crossInitialMarginRequirement,
-          'crossInitialMarginRequirement'
-        )
-      )
       return lighterAvailableToTrade(
         market,
-        crossFreeCollateral.toFixed(),
+        subtractDecimalString(
+          unknownToDecimalString(
+            config.crossAssetValue,
+            'crossAssetValue',
+            providerKey
+          ),
+          unknownToDecimalString(
+            config.crossInitialMarginRequirement,
+            'crossInitialMarginRequirement',
+            providerKey
+          )
+        ),
         account.positions
       )
     },
@@ -1291,10 +1438,11 @@ export const createLighterProvider = (
         row === undefined
           ? undefined
           : leverageFromImf(
-              toRequiredBig(
+              unknownToDecimalString(
                 row.initial_margin_fraction,
-                'initial_margin_fraction'
-              ).toFixed()
+                'initial_margin_fraction',
+                providerKey
+              )
             )
       if (row === undefined || leverage === undefined) {
         return resolveDefaultMarketSettings(marketId)
@@ -1378,7 +1526,7 @@ export const createLighterProvider = (
             continue
           }
           const order = mapOrder(raw, market)
-          if (statuses.has(order.status)) {
+          if (order !== undefined && statuses.has(order.status)) {
             orders.push(order)
           }
         }
@@ -1423,8 +1571,15 @@ export const createLighterProvider = (
           PerpsErrorCode.OrderNotFound,
           `Lighter order ${params.id} not found for ${params.address}`
         )
-      const detail = (order: LtOrder): Order =>
+      const mapDetail = (order: LtOrder): Order | undefined =>
         mapOrder(order, registry.require(String(order.market_index)))
+      const detail = (order: LtOrder): Order => {
+        const mapped = mapDetail(order)
+        if (mapped === undefined) {
+          throw notFound()
+        }
+        return mapped
+      }
 
       // A tx-hash route would require mapping the caller's executeAction tx
       // hash → wasm nonce → matching order, which the LI.FI backend did via
@@ -1464,7 +1619,7 @@ export const createLighterProvider = (
         // client order index can match more than one row. Prefer the live one.
         const matches = orders
           .filter((o) => String(o.client_order_index) === clientOrderIndex)
-          .map(detail)
+          .flatMap((o) => mapDetail(o) ?? [])
         const hit =
           matches.find((o) => isActiveOrderStatus(o.status)) ?? matches[0]
         if (hit === undefined) {
@@ -1536,10 +1691,8 @@ export const createLighterProvider = (
       // resolves, so its rows stay.
       const items = wireList(response.trades).flatMap((t): Fill[] => {
         const market = registry.get(String(t.market_id))
-        if (market === undefined) {
-          return []
-        }
-        return [mapFill(t, account.index, market)]
+        const mapped = market && mapFill(t, account.index, market)
+        return mapped ? [mapped] : []
       })
 
       return {
@@ -1583,34 +1736,18 @@ export const createLighterProvider = (
       const read = (tok: string) =>
         client.getAuthed<LtAccountPnL>('/api/v1/pnl', tok, queryParams)
 
-      // The read-only token may not be accepted on `/pnl`; the standard token
-      // is, so a read signed from the SDK's own key retries once with it. The
-      // fallback sits outside `retryOnRevoked`, so a revocation the standard
-      // token reports never replaces the read-only one. The key is re-read at
-      // retry time because `REGISTER_API_KEY` can rotate it.
-      const response = await retryOnRevoked(params.address, token, read).catch(
-        async (err: unknown) => {
-          if (!(err instanceof LighterAuthRejectedError) || apiKey === null) {
-            throw err
-          }
-          const current = (await keyStore.get(params.address)) ?? apiKey
-          return read(
-            await getStandardAuthToken(
-              params.address,
-              current.apiKeyPrivateKey,
-              {
-                apiKeyIndex: current.apiKeyIndex,
-                accountIndex: current.accountIndex,
-              }
-            )
-          )
-        }
+      // The read-only token may not be accepted on `/pnl`; the standard token is.
+      const response = await retryWithStandardToken(
+        params.address,
+        apiKey,
+        token,
+        read
       )
 
       return mapPortfolioHistory(
         params.range,
         wireList(response.pnl),
-        new Big(getAccountSummary(account, account.positions).portfolioValue)
+        getAccountSummary(account, account.positions).portfolioValue
       )
     },
 
@@ -1706,8 +1843,12 @@ export const createLighterProvider = (
           if (market === undefined) {
             return []
           }
-          const price = toBigOrNull(l.trade.price)
-          const size = toBigOrNull(l.trade.size)
+          const notional = safeMultiplyDecimalString(
+            l.trade.price,
+            l.trade.size
+          )
+          const liquidatedNotionalPosition =
+            notional === undefined ? undefined : safeAbsDecimalString(notional)
           const marginMode = wireList(l.info.positions).find(
             (p) => p.market_id === l.market_id
           )?.margin_mode
@@ -1728,14 +1869,9 @@ export const createLighterProvider = (
               provider: providerKey,
               timestamp: toIsoFromMs(l.executed_at),
               type: ActivityType.LIQUIDATION,
-              ...(price === null || size === null
+              ...(liquidatedNotionalPosition === undefined
                 ? {}
-                : {
-                    liquidatedNotionalPosition: price
-                      .times(size)
-                      .abs()
-                      .toFixed(),
-                  }),
+                : { liquidatedNotionalPosition }),
               // The account value at liquidation time is the pre-trade
               // snapshot, not the settled one Lighter also reports.
               ...(accountValue === undefined ? {} : { accountValue }),
@@ -1826,7 +1962,7 @@ export const createLighterProvider = (
 
     snapOrderSize,
 
-    estimateLiquidationPrice,
+    estimateLiquidationPrice: estimateLiquidationPriceAtMarketRate,
 
     positionRemovableMargin,