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

package/src/accountSummary.ts

@@ -1,4 +1,9 @@
-import { PerpsError } from '@lifi/perps-sdk'
+import {
+  addDecimalString,
+  PerpsError,
+  subtractDecimalString,
+  unknownToDecimalString,
+} from '@lifi/perps-sdk'
 import type {
   AccountResponse,
   AccountSummary,
@@ -6,14 +11,12 @@ import type {
   Position,
 } from '@lifi/perps-types'
 import { PerpsErrorCode } from '@lifi/perps-types'
-import Big from 'big.js'
 import { atLeastZero } from './availableToTrade.js'
 import {
   LIGHTER_COLLATERAL_ASSETS,
   LIGHTER_PROVIDER_KEY,
   LIGHTER_RH_PROVIDER_KEY,
 } from './constants.js'
-import { toRequiredBig } from './utils/decimal.js'
 
 /**
  * The Lighter arm of `account.config`.
@@ -40,11 +43,15 @@ export const lighterConfig = (
  * Add marked holdings excluded from Lighter's settlement equity.
  */
 export const lighterPortfolioValue = (
-  perpsEquity: Big,
+  perpsEquity: string,
   holdingValuesUsd: readonly string[]
-): Big =>
+): string =>
   holdingValuesUsd.reduce(
-    (sum, valueUsd) => sum.plus(toRequiredBig(valueUsd, 'valueUsd')),
+    (sum, valueUsd) =>
+      addDecimalString(
+        sum,
+        unknownToDecimalString(valueUsd, 'valueUsd', LIGHTER_PROVIDER_KEY)
+      ),
     perpsEquity
   )
 
@@ -68,29 +75,41 @@ export function getAccountSummary(
       asset.id !== settlement.displaySymbol
   )
 
-  let marginUsed = new Big(0)
-  let unrealizedPnl = new Big(0)
-  for (const position of positions) {
-    marginUsed = marginUsed.plus(position.marginUsed)
-    unrealizedPnl = unrealizedPnl.plus(position.unrealizedPnl)
-  }
-
   return {
     portfolioValue: lighterPortfolioValue(
-      toRequiredBig(config.totalAssetValue, 'totalAssetValue').plus(
-        toRequiredBig(config.collateralSpotBalance, 'collateralSpotBalance')
+      addDecimalString(
+        unknownToDecimalString(
+          config.totalAssetValue,
+          'totalAssetValue',
+          LIGHTER_PROVIDER_KEY
+        ),
+        unknownToDecimalString(
+          config.collateralSpotBalance,
+          'collateralSpotBalance',
+          LIGHTER_PROVIDER_KEY
+        )
       ),
       holdings.map((balance) => balance.valueUsd)
-    ).toFixed(),
+    ),
     availableMargin: atLeastZero(
-      toRequiredBig(config.crossAssetValue, 'crossAssetValue').minus(
-        toRequiredBig(
+      subtractDecimalString(
+        unknownToDecimalString(
+          config.crossAssetValue,
+          'crossAssetValue',
+          LIGHTER_PROVIDER_KEY
+        ),
+        unknownToDecimalString(
           config.crossInitialMarginRequirement,
-          'crossInitialMarginRequirement'
+          'crossInitialMarginRequirement',
+          LIGHTER_PROVIDER_KEY
         )
       )
-    ).toFixed(),
-    marginUsed: marginUsed.toFixed(),
-    unrealizedPnl: unrealizedPnl.toFixed(),
+    ),
+    marginUsed: positions
+      .map((p) => p.marginUsed)
+      .reduce(addDecimalString, '0'),
+    unrealizedPnl: positions
+      .map((p) => p.unrealizedPnl)
+      .reduce(addDecimalString, '0'),
   }
 }

package/src/availableToTrade.ts

@@ -1,21 +1,36 @@
-import { toAssetDisplay } from '@lifi/perps-sdk'
+import {
+  addDecimalString,
+  isDecimalStringGreaterThan,
+  toAssetDisplay,
+  unknownToDecimalString,
+} from '@lifi/perps-sdk'
 import type { AvailableToTrade, Market, Position } from '@lifi/perps-types'
 import { MarginMode, PositionSide } from '@lifi/perps-types'
-import Big from 'big.js'
-import { toRequiredBig } from './utils/decimal.js'
+import { LIGHTER_PROVIDER_KEY } from './constants.js'
 
-export const atLeastZero = (value: Big): Big =>
-  value.lt(0) ? new Big(0) : value
+export const atLeastZero = (value: string): string =>
+  isDecimalStringGreaterThan('0', value) ? '0' : value
 
 // `availableMargin` is the cross free collateral and holds nothing of an
 // isolated position, so closing one releases its whole equity.
-const releasedOnClose = (position: Position): Big => {
-  const marginUsed = toRequiredBig(position.marginUsed, 'marginUsed')
+const releasedOnClose = (position: Position): string => {
+  const marginUsed = unknownToDecimalString(
+    position.marginUsed,
+    'marginUsed',
+    LIGHTER_PROVIDER_KEY
+  )
   if (position.marginMode !== MarginMode.ISOLATED) {
     return marginUsed
   }
   return atLeastZero(
-    marginUsed.plus(toRequiredBig(position.unrealizedPnl, 'unrealizedPnl'))
+    addDecimalString(
+      marginUsed,
+      unknownToDecimalString(
+        position.unrealizedPnl,
+        'unrealizedPnl',
+        LIGHTER_PROVIDER_KEY
+      )
+    )
   )
 }
 
@@ -36,22 +51,30 @@ export const lighterAvailableToTrade = (
   availableMargin: string,
   positions: readonly Position[]
 ): AvailableToTrade => {
-  const available = toRequiredBig(availableMargin, 'availableMargin')
+  const available = unknownToDecimalString(
+    availableMargin,
+    'availableMargin',
+    LIGHTER_PROVIDER_KEY
+  )
   const adding = atLeastZero(available)
   const position = positions.find((p) => p.market.id === market.id)
   const reducing =
     position === undefined
       ? adding
-      : toRequiredBig(
-          position.initialMarginRequirement,
-          'initialMarginRequirement'
-        ).plus(atLeastZero(available.plus(releasedOnClose(position))))
+      : addDecimalString(
+          unknownToDecimalString(
+            position.initialMarginRequirement,
+            'initialMarginRequirement',
+            LIGHTER_PROVIDER_KEY
+          ),
+          atLeastZero(addDecimalString(available, releasedOnClose(position)))
+        )
   const isShort = position?.side === PositionSide.SHORT
   return {
     providerId: market.providerId,
     marketId: market.id,
     asset: toAssetDisplay(market.quoteAsset),
-    buy: (isShort ? reducing : adding).toFixed(),
-    sell: (isShort ? adding : reducing).toFixed(),
+    buy: isShort ? reducing : adding,
+    sell: isShort ? adding : reducing,
   }
 }

package/src/constants.ts

@@ -193,6 +193,15 @@ export const DEFAULT_TRADES_LIMIT = 50
  */
 export const LIGHTER_FEE_TICK_SCALE = 1_000_000
 
+/**
+ * Decimal places a client may use for Lighter leverage. Lighter stores
+ * leverage as an integer basis-point IMF (`round(10000 / leverage)`), and at
+ * this precision a read-back leverage always re-saves the same IMF.
+ *
+ * @public
+ */
+export const LIGHTER_LEVERAGE_PRECISION = 2
+
 /**
  * Scale of the integer `initial_margin_fraction` values Lighter publishes on
  * trade rows and order-book details: the integer is a percent times 100, so

package/src/index.ts

@@ -25,6 +25,7 @@ export {
   DEFAULT_LIGHTER_WS_URL,
   LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX,
   LIGHTER_COLLATERAL_ASSETS,
+  LIGHTER_LEVERAGE_PRECISION,
   LIGHTER_MAINNET_DEPLOYMENT,
   LIGHTER_MAINNET_SIGNER_CHAIN_ID,
   LIGHTER_PROVIDER_KEY,

package/src/signers/LighterSigner.ts

@@ -1,6 +1,9 @@
-import { decimalToBaseUnits, PerpsError } from '@lifi/perps-sdk'
+import {
+  decimalStringToScaledInteger,
+  isDecimalStringGreaterThan,
+  PerpsError,
+} from '@lifi/perps-sdk'
 import { ActionType, PerpsErrorCode } from '@lifi/perps-types'
-import Big from 'big.js'
 import { LT_ROUTE_PERP, LT_ROUTE_SPOT } from '../types/action.js'
 import { assetMarginModeInt } from '../utils/assetCollateral.js'
 import {
@@ -622,7 +625,7 @@ export class LighterSigner {
         const symbol = stringField(p, 'symbol')
         const amount = stringField(p, 'amount')
         const minimum = stringField(p, 'min_withdrawal_amount')
-        if (new Big(amount).lt(new Big(minimum))) {
+        if (isDecimalStringGreaterThan(minimum, amount)) {
           throw new PerpsError(
             PerpsErrorCode.ValidationError,
             `Lighter WITHDRAWAL of ${amount} ${symbol} is below the venue ` +
@@ -632,7 +635,11 @@ export class LighterSigner {
         return wasm.SignWithdraw(
           numberField(p, 'asset_index'),
           routeType,
-          decimalToBaseUnits(amount, numberField(p, 'decimals'), 'truncate'),
+          decimalStringToScaledInteger(
+            amount,
+            numberField(p, 'decimals'),
+            'truncate'
+          ),
           SKIP_NONCE_DISABLED,
           nonce,
           ctx.apiKeyIndex,

package/src/types/submit.ts

@@ -85,6 +85,21 @@ export interface LtFastwithdrawInfoResponse {
   max_withdrawal_amount: string
 }
 
+/**
+ * `GET /api/v1/transferFeeInfo` (Lighter `TransferFeeInfo`).
+ *
+ * `transfer_fee_usdc` is the fee for an L2 transfer from `account_index` to
+ * `to_account_index`, in the same L2 6-decimal integer scale as
+ * {@link LtFastwithdrawInfoResponse}.
+ *
+ * @public
+ */
+export interface LtTransferFeeInfoResponse {
+  code: number
+  message?: string
+  transfer_fee_usdc: number
+}
+
 /**
  * `POST /api/v1/fastwithdraw` (Lighter `ResultCode`).
  *

package/src/utils/index.ts

@@ -9,13 +9,11 @@ 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'
 export { mapFill } from './mapFill.js'
 export { mapMarketContext } from './mapMarketContext.js'
-export { mapOpenPositions } from './mapOpenPositions.js'
+export { isOpenPosition, mapOpenPositions } from './mapOpenPositions.js'
 export { mapOrder, mapOrderUpdates } from './mapOrder.js'
 export { mapPortfolioHistory } from './mapPortfolioHistory.js'
 export { leverageFromImf, mapPosition } from './mapPosition.js'
@@ -33,3 +31,11 @@ export {
   resolveTimeInForce,
 } from './wireEncoding.js'
 export { lighterWithdrawableBalances } from './withdrawableBalances.js'
+export type {
+  LighterFastWithdrawal,
+  LighterWithdrawalOptions,
+} from './withdrawalTypes.js'
+export {
+  lighterFastWithdrawal,
+  lighterWithdrawalTypes,
+} from './withdrawalTypes.js'

package/src/utils/mapFill.ts

@@ -1,14 +1,24 @@
 import {
+  absDecimalString,
+  calculateRealizedPnl,
   classifyFillFromPosition,
+  divideDecimalString,
   ExplorerChainId,
   explorerTxUrl,
+  isDecimalString,
+  isDecimalStringGreaterThan,
+  isDecimalStringZero,
+  safeAddDecimalString,
+  safeDivideDecimalString,
+  safeMultiplyDecimalString,
+  warnSkippedVenueRow,
 } from '@lifi/perps-sdk'
 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 } from '../constants.js'
+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 { isPlaceholderTxHash } from './txHash.js'
 
 /**
@@ -20,31 +30,44 @@ import { isPlaceholderTxHash } from './txHash.js'
  * The product keeps the sign of both inputs. A rebate tick therefore maps to a
  * negative amount, which `Fee.amount` permits and the Ondo mapper already emits
  * when a rebate exceeds the fee, so this helper never clamps the sign. A zero
- * notional charges a zero fee at every tick.
+ * notional charges a zero fee at every tick. A malformed notional gives
+ * `undefined`.
  */
 const tickToFeeAmount = (
   notional: string,
   ownTick: number,
   integratorTick: number | undefined
-): string =>
-  new Big(notional)
-    .times(new Big(ownTick).plus(integratorTick ?? 0))
-    .div(LIGHTER_FEE_TICK_SCALE)
-    .toFixed()
+): string | undefined => {
+  if (!isDecimalString(notional)) {
+    return undefined
+  }
+  const tickSum = safeAddDecimalString(
+    String(ownTick),
+    String(integratorTick ?? 0)
+  )
+  const scaledFee =
+    tickSum === undefined
+      ? undefined
+      : safeMultiplyDecimalString(notional, tickSum)
+  return scaledFee === undefined
+    ? undefined
+    : safeDivideDecimalString(scaledFee, String(LIGHTER_FEE_TICK_SCALE))
+}
 
 /**
  * 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 =>
+const leverageFromTradeImf = (imf: number | undefined): string | undefined =>
   imf === undefined ? undefined : leverageFromScaledImf(imf)
 
 /**
  * Realized PnL on a position-reducing fill, derived from the pre-trade entry
  * basis. Returns `undefined` for opens/increases (nothing closes) or when the
- * entry-quote snapshot is absent, and `null` when the closed portion realizes
- * exactly zero — mirroring the Hyperliquid mapper's `null`-for-zero convention.
+ * entry-quote snapshot is absent or an input is malformed, and `null` when the
+ * closed portion realizes exactly zero — mirroring the Hyperliquid mapper's
+ * `null`-for-zero convention.
  */
 const deriveRealizedPnl = (
   startPosition: string,
@@ -53,30 +76,39 @@ const deriveRealizedPnl = (
   fillPrice: string,
   isBuyer: boolean
 ): string | null | undefined => {
-  if (entryQuoteBefore === undefined) {
+  if (
+    entryQuoteBefore === undefined ||
+    ![startPosition, entryQuoteBefore, fillSize, fillPrice].every(
+      isDecimalString
+    )
+  ) {
     return undefined
   }
-  const start = new Big(startPosition)
-  if (start.eq(0)) {
+  if (isDecimalStringZero(startPosition)) {
     return undefined
   }
-  const isLong = start.gt(0)
+  const isLong = isDecimalStringGreaterThan(startPosition, '0')
   const reducing = isLong ? !isBuyer : isBuyer
   if (!reducing) {
     return undefined
   }
 
-  const absStart = start.abs()
-  const fill = new Big(fillSize)
+  const absStart = absDecimalString(startPosition)
   // A fill larger than the open size flips the position; only the portion that
   // unwinds the existing position realizes PnL.
-  const closedSize = fill.gt(absStart) ? absStart : fill
-  const avgEntry = new Big(entryQuoteBefore).abs().div(absStart)
-  const price = new Big(fillPrice)
-  const pnl = isLong
-    ? price.minus(avgEntry).times(closedSize)
-    : avgEntry.minus(price).times(closedSize)
-  return pnl.eq(0) ? null : pnl.toFixed()
+  const closedSize = isDecimalStringGreaterThan(fillSize, absStart)
+    ? absStart
+    : fillSize
+  const pnl = calculateRealizedPnl({
+    entryPrice: divideDecimalString(
+      absDecimalString(entryQuoteBefore),
+      absStart
+    ),
+    closePrice: fillPrice,
+    closeSize: closedSize,
+    isLong,
+  })
+  return isDecimalStringZero(pnl) ? null : pnl
 }
 
 /**
@@ -89,7 +121,19 @@ export const mapFill = (
   trade: LtTrade,
   accountIndex: number,
   market: MarketDisplay
-): Fill => {
+): Fill | undefined => {
+  const { size, price } = trade
+  const createdAt = rowTimestampToIsoStringOrUndefined(trade.timestamp)
+  if (createdAt === undefined) {
+    warnSkippedVenueRow(
+      LIGHTER_PROVIDER_KEY,
+      'fill',
+      'timestamp',
+      trade.timestamp,
+      'timestamp'
+    )
+    return undefined
+  }
   const isBuyer = trade.bid_account_id === accountIndex
   const isMaker =
     (trade.is_maker_ask && !isBuyer) || (!trade.is_maker_ask && isBuyer)
@@ -111,6 +155,10 @@ export const mapFill = (
   const imfBefore = isMaker
     ? trade.maker_initial_margin_fraction_before
     : trade.taker_initial_margin_fraction_before
+  const feeAmount =
+    feeTick === undefined
+      ? undefined
+      : tickToFeeAmount(trade.usd_amount, feeTick, integratorFeeTick)
 
   return {
     id: trade.trade_id.toString(),
@@ -118,38 +166,29 @@ export const mapFill = (
     market,
     side: isBuyer ? OrderSide.BUY : OrderSide.SELL,
     type: OrderType.LIMIT,
-    size: trade.size,
-    price: trade.price,
+    size,
+    price,
     liquidity: isMaker ? LiquidityRole.MAKER : LiquidityRole.TAKER,
     // Lighter charges the fill fee in the market's quote asset.
     fee:
-      feeTick === undefined
+      feeAmount === undefined
         ? undefined
-        : {
-            amount: tickToFeeAmount(
-              trade.usd_amount,
-              feeTick,
-              integratorFeeTick
-            ),
-            asset: market.quoteAsset.displaySymbol,
-          },
+        : { amount: feeAmount, asset: market.quoteAsset.displaySymbol },
     leverage: leverageFromTradeImf(imfBefore),
     realizedPnl: deriveRealizedPnl(
       startPosition,
       entryQuoteBefore,
-      trade.size,
-      trade.price,
+      size,
+      price,
       isBuyer
     ),
     startPosition,
-    // `classifyFillFromPosition` takes an HL-encoded side: `'B'` for buy,
-    // anything else for sell.
     classification: classifyFillFromPosition(
       startPosition,
-      isBuyer ? 'B' : 'A',
-      trade.size
+      isBuyer ? OrderSide.BUY : OrderSide.SELL,
+      size
     ),
-    createdAt: new Date(trade.timestamp).toISOString(),
+    createdAt,
     explorerLink: isPlaceholderTxHash(trade.tx_hash)
       ? undefined
       : explorerTxUrl(ExplorerChainId.LIGHTER, trade.tx_hash),

package/src/utils/mapOpenPositions.ts

@@ -1,11 +1,26 @@
-import type { PerpsMarketDisplay, Position } from '@lifi/perps-types'
+import { PerpsError, safeIsDecimalStringZero } from '@lifi/perps-sdk'
+import {
+  PerpsErrorCode,
+  type PerpsMarketDisplay,
+  type Position,
+} from '@lifi/perps-types'
+import { LIGHTER_PROVIDER_KEY } from '../constants.js'
 import type { LtAccountPosition } from '../types/index.js'
 import { mapPosition } from './mapPosition.js'
 
+/**
+ * True when the Lighter position row has a non-zero size. A malformed size
+ * keeps the row.
+ * @public
+ */
+export const isOpenPosition = (p: LtAccountPosition): boolean =>
+  safeIsDecimalStringZero(p.position) !== true
+
 /**
  * Map raw Lighter account positions to open {@link Position}s, dropping
- * zero-size rows. Only valid for payloads carrying the full position set —
- * dropping zeros from a partial frame would make closes unobservable.
+ * zero-size rows and rows that `mapPosition` skips. Only valid for payloads
+ * carrying the full position set — dropping zeros from a partial frame would
+ * make closes unobservable.
  *
  * @public
  */
@@ -13,6 +28,30 @@ export const mapOpenPositions = (
   positions: LtAccountPosition[],
   resolveMarket: (marketId: number) => PerpsMarketDisplay
 ): Position[] =>
-  positions
-    .filter((p) => Number.parseFloat(p.position) !== 0)
-    .map((p) => mapPosition(p, resolveMarket(p.market_id)))
+  positions.filter(isOpenPosition).flatMap((p) => {
+    const position = mapPosition(p, resolveMarket(p.market_id))
+    return position === undefined ? [] : [position]
+  })
+
+/**
+ * Map every open Lighter position for account totals, which must not leave a
+ * position out.
+ *
+ * @throws {PerpsError} `SDKError` when `mapPosition` skips an open row.
+ */
+export const requireOpenPositions = (
+  positions: LtAccountPosition[],
+  resolveMarket: (marketId: number) => PerpsMarketDisplay
+): Position[] =>
+  positions.filter(isOpenPosition).map((p) => {
+    const position = mapPosition(p, resolveMarket(p.market_id))
+    if (position !== undefined) {
+      return position
+    }
+    const error = new PerpsError(
+      PerpsErrorCode.SDKError,
+      `${LIGHTER_PROVIDER_KEY} position for market ${p.market_id} is not valid, so the account totals are unknown.`
+    )
+    error.tool = LIGHTER_PROVIDER_KEY
+    throw error
+  })