@lifi/perps-sdk-provider-lighter 31.0.1 → 33.0.0

package/src/LighterProvider.ts

@@ -1,5 +1,6 @@
 import {
   ACTIVE_ORDER_STATUSES,
+  calculateTransferable,
   type DepositFlow,
   explorerTxUrl,
   explorerTxUrlFromBase,
@@ -9,8 +10,6 @@ import {
   getProviders,
   isActiveOrderStatus,
   localStorageAdapter,
-  maxOf,
-  minOf,
   PerpsError,
   type PerpsProviderPlugin,
   type PerpsSDKClient,
@@ -66,6 +65,7 @@ import type {
 import {
   ActionType,
   ActivityType,
+  isDecimalString,
   MarginMode,
   PerpsErrorCode,
 } from '@lifi/perps-types'
@@ -142,8 +142,6 @@ import { isAssetMarginEnabled } from './utils/assetCollateral.js'
 import {
   estimateLiquidationPrice,
   fetchDetailedAccount,
-  formatOrderPrice,
-  formatOrderSize,
   leverageFromImf,
   lighterAsset,
   lighterWithdrawableBalances,
@@ -152,6 +150,8 @@ import {
   mapOrder,
   mapPortfolioHistory,
   positionRemovableMargin,
+  snapOrderPrice,
+  snapOrderSize,
   toBigOrNull,
   toIsoFromMs,
   toIsoFromSeconds,
@@ -275,10 +275,26 @@ interface ReadOnlyCreationBackoff {
  *   4. Fresh 1h create via this instance's WASM signer + the user's registered
  *      API key
  *
- * When none of these yields a token the auth-gated reads degrade gracefully:
- *   - `getOrders`, `getActivity` return empty results (mirrors backend behaviour)
- *   - `getOrder` throws `Unauthorized`
- *   - `getAccount` returns zero fee tier rather than failing
+ * Status reads report the account's state and do not throw for a missing
+ * credential: `getAccount` returns a zero fee tier and
+ * `apiKeyRegistered: false` when the wallet has no locally stored API key
+ * matching the key registered on Lighter; otherwise it reads the fee tier
+ * with the resolved token and throws `Unauthorized` if Lighter rejects it.
+ * `accountExists` and `getDepositFlow` need no token.
+ *
+ * Data reads throw `PerpsError`, one code per fact:
+ *   - `SetupRequired` when none of these sources yields a token. The SDK
+ *     sends no venue request. `getOrders`, `getOrder`, `getFills`,
+ *     `getPortfolioHistory` and `getActivity` need a token.
+ *   - `Unauthorized` when Lighter rejects the token that was sent. An
+ *     SDK-owned read-only token that Lighter reports as revoked is replaced
+ *     and the read retried once first.
+ *   - `AccountNotFound` when the wallet has no Lighter account. This also
+ *     applies to `getPositions`, `getWithdrawableBalances` and
+ *     `getAvailableToTrade`, which need no token. `getAvailableToTrade`
+ *     reads the fee tier through `getAccount`, so it also throws
+ *     `Unauthorized` when a matching local key's token is rejected.
+ * An account with no rows resolves an empty list.
  *
  * @public
  */
@@ -328,8 +344,7 @@ export interface LighterPerpsProvider extends PerpsProviderPlugin {
   /**
    * Resolve a Lighter auth token for `address`, following the resolution order
    * documented on {@link LighterProviderOptions} (the per-call override does not
-   * apply here). Returns `undefined` when no source can produce a token —
-   * callers degrade gracefully.
+   * apply here). Returns `undefined` when no source can produce a token.
    */
   resolveAuthToken(address: Address): Promise<string | undefined>
 }
@@ -454,8 +469,7 @@ export const createLighterProvider = (
    *      as the credential that authorises read-only token creation, and as
    *      the fallback while creation is failing, bounded by the
    *      creation-retry backoff.
-   * Returns `undefined` when no source can produce a token — reads degrade
-   * gracefully.
+   * Returns `undefined` when no source can produce a token.
    */
   const resolveAuthToken = async (
     opts: SDKRequestOptions | undefined,
@@ -549,6 +563,25 @@ export const createLighterProvider = (
     return attempt
   }
 
+  /** {@link resolveAuthToken}, throwing `SetupRequired` when no source yields a token. */
+  const requireAuthToken = async (
+    read: string,
+    opts: SDKRequestOptions | undefined,
+    address: Address,
+    knownApiKey?: LighterApiKey
+  ): Promise<string> => {
+    const token = await resolveAuthToken(opts, address, knownApiKey)
+    if (token === undefined) {
+      throw new PerpsError(
+        PerpsErrorCode.SetupRequired,
+        `Lighter ${read} requires an auth token. Pass \`authToken\` to ` +
+          'lighterProvider, register an API key + signer for on-demand creation, or ' +
+          'forward `options.lighterAuthToken` on the call.'
+      )
+    }
+    return token
+  }
+
   const replaceRevokedReadOnlyToken = async (
     address: Address,
     revokedToken: string
@@ -945,6 +978,7 @@ export const createLighterProvider = (
         localKey !== null &&
         normalizeLighterPublicKey(localKey.apiKeyPublicKey) ===
           normalizeLighterPublicKey(registeredKey.public_key)
+      // Status read: a missing or stale credential reports `apiKeyRegistered: false`, not a throw.
       const token = apiKeyRegistered
         ? await resolveAuthToken(opts, params.address, localKey)
         : undefined
@@ -1042,37 +1076,37 @@ 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(
+          a.margin_balance,
+          'margin_balance'
+        ).toFixed()
         return {
           ...toBalance(
             a,
             perpsCategory?.id ?? providerKey,
             isSettlement ? settlementAsset : registryAsset(a),
-            a.margin_balance
+            isDecimalString(a.margin_balance) ? a.margin_balance : marginBalance
           ),
           transferable: isSettlement
-            ? minOf(
-                maxOf(availableBalance, new Big(0)),
-                new Big(a.margin_balance)
-              ).toFixed()
+            ? calculateTransferable(availableBalance.toFixed(), marginBalance)
             : '0',
         }
       })
       const balances: Balance[] = heldAssets.map((a) => {
-        const balance = new Big(a.balance)
+        const balance = toRequiredBig(a.balance, 'balance')
         return {
           ...toBalance(
             a,
             LIGHTER_SPOT_CATEGORY_ID,
             registryAsset(a),
-            a.balance
+            isDecimalString(a.balance) ? a.balance : balance.toFixed()
           ),
-          transferable: minOf(
-            maxOf(
-              balance.minus(toRequiredBig(a.locked_balance, 'locked_balance')),
-              new Big(0)
-            ),
+          transferable: calculateTransferable(
             balance
-          ).toFixed(),
+              .minus(toRequiredBig(a.locked_balance, 'locked_balance'))
+              .toFixed(),
+            balance.toFixed()
+          ),
         }
       })
 
@@ -1149,13 +1183,11 @@ export const createLighterProvider = (
       params: ProviderGetWithdrawableBalancesParams,
       opts?: SDKRequestOptions
     ): Promise<ProviderWithdrawableBalance[]> {
-      const account = await fetchAccountIfExists(
+      const account = await fetchDetailedAccount(
         apiClient(opts),
         params.address
       )
-      return account === undefined
-        ? []
-        : lighterWithdrawableBalances(account, collateral.assetIndex)
+      return lighterWithdrawableBalances(account, collateral.assetIndex)
     },
 
     async getPositions(
@@ -1165,16 +1197,9 @@ export const createLighterProvider = (
       const client = apiClient(opts)
       const registry = getMarketRegistry(requireClient(), providerKey)
       const [account] = await Promise.all([
-        fetchAccountIfExists(client, params.address),
+        fetchDetailedAccount(client, params.address),
         registry.sync(),
       ])
-      if (account === undefined) {
-        return {
-          provider: providerKey,
-          positions: [],
-          pagination: { limit: params.limit ?? 0, hasMore: false },
-        }
-      }
 
       let positions: Position[] = mapOpenPositions(account.positions, (id) =>
         toPerpsMarketDisplay(registry.require(String(id)))
@@ -1279,10 +1304,7 @@ export const createLighterProvider = (
       if (statuses.size === 0) {
         return empty
       }
-      const token = await resolveAuthToken(opts, params.address)
-      if (token === undefined) {
-        return empty
-      }
+      const token = await requireAuthToken('orders read', opts, params.address)
 
       const client = apiClient(opts)
       const registry = getMarketRegistry(requireClient(), providerKey)
@@ -1371,15 +1393,7 @@ export const createLighterProvider = (
       params: ProviderGetOrderParams,
       opts?: SDKRequestOptions
     ): Promise<Order> {
-      const token = await resolveAuthToken(opts, params.address)
-      if (token === undefined) {
-        throw new PerpsError(
-          PerpsErrorCode.SDKError,
-          'Lighter order lookup requires an auth token. Pass `authToken` to ' +
-            'lighterProvider, register an API key + signer for on-demand creation, or ' +
-            'forward `options.lighterAuthToken` on the call.'
-        )
-      }
+      const token = await requireAuthToken('order lookup', opts, params.address)
 
       const client = apiClient(opts)
       const registry = getMarketRegistry(requireClient(), providerKey)
@@ -1477,14 +1491,7 @@ export const createLighterProvider = (
       params: ProviderGetFillsParams,
       opts?: SDKRequestOptions
     ): Promise<FillsResponse> {
-      const token = await resolveAuthToken(opts, params.address)
-      if (token === undefined) {
-        return {
-          provider: providerKey,
-          items: [],
-          pagination: { limit: params.limit ?? 0, hasMore: false },
-        }
-      }
+      const token = await requireAuthToken('fills read', opts, params.address)
 
       const client = apiClient(opts)
       const registry = getMarketRegistry(requireClient(), providerKey)
@@ -1541,14 +1548,12 @@ export const createLighterProvider = (
       const sdkOwnsToken =
         opts?.lighterAuthToken === undefined && authTokenSource === undefined
       const apiKey = sdkOwnsToken ? await keyStore.get(params.address) : null
-      const token = await resolveAuthToken(
+      const token = await requireAuthToken(
+        'portfolio history read',
         opts,
         params.address,
         apiKey ?? undefined
       )
-      if (token === undefined) {
-        return { range: params.range, points: [] }
-      }
 
       const client = apiClient(opts)
       const account = await plugin.getAccount({ address: params.address }, opts)
@@ -1603,14 +1608,11 @@ export const createLighterProvider = (
       params: ProviderGetActivityParams,
       opts?: SDKRequestOptions
     ): Promise<ActivitiesResponse> {
-      const token = await resolveAuthToken(opts, params.address)
-      if (token === undefined) {
-        return {
-          provider: providerKey,
-          items: [],
-          pagination: { limit: params.limit ?? 0, hasMore: false },
-        }
-      }
+      const token = await requireAuthToken(
+        'activity read',
+        opts,
+        params.address
+      )
 
       const inputCursor = decodeActivityCursor(params.cursor)
       const client = apiClient(opts)
@@ -1814,9 +1816,9 @@ export const createLighterProvider = (
       return getAccountSummary(account, positions)
     },
 
-    formatOrderPrice,
+    snapOrderPrice,
 
-    formatOrderSize,
+    snapOrderSize,
 
     estimateLiquidationPrice,
 

package/src/constants.ts

@@ -18,8 +18,10 @@ export const LIGHTER_RH_PROVIDER_KEY = 'lighter-rh'
 
 /**
  * Category id for Lighter spot token holdings, matching the backend's Lighter
- * spot asset category. The perps category id is not a constant — it is read
- * from the fetched markets so it tracks the backend taxonomy.
+ * spot asset category. Every Lighter call site, REST and WebSocket, uses this
+ * constant for the spot category. The perps category id is not a constant:
+ * `LighterProvider.getAccount` reads it from the `/providers` category whose
+ * `quoteAsset` is not null.
  *
  * @public
  */

package/src/signers/LighterSigner.ts

@@ -1,4 +1,4 @@
-import { PerpsError, scaleToInteger } from '@lifi/perps-sdk'
+import { decimalToBaseUnits, 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'
@@ -632,7 +632,7 @@ export class LighterSigner {
         return wasm.SignWithdraw(
           numberField(p, 'asset_index'),
           routeType,
-          scaleToInteger(amount, numberField(p, 'decimals'), 'truncate'),
+          decimalToBaseUnits(amount, numberField(p, 'decimals'), 'truncate'),
           SKIP_NONCE_DISABLED,
           nonce,
           ctx.apiKeyIndex,

package/src/utils/index.ts

@@ -21,7 +21,7 @@ export { mapPortfolioHistory } from './mapPortfolioHistory.js'
 export { leverageFromImf, mapPosition } from './mapPosition.js'
 export { mapMarketOrderLimits } from './marketLimits.js'
 export { mapInterval } from './ohlcvInterval.js'
-export { formatOrderPrice, formatOrderSize } from './orderFormatting.js'
+export { snapOrderPrice, snapOrderSize } from './orderFormatting.js'
 export { toIsoFromMs, toIsoFromSeconds } from './time.js'
 export { positionRemovableMargin } from './transferMargin.js'
 export {

package/src/utils/liquidation.ts

@@ -8,7 +8,7 @@
  */
 
 import {
-  estimateIsolatedLiquidationPrice,
+  estimateLiquidationPrice as estimateIsolatedLiquidationPrice,
   type LiquidationEstimateParams,
 } from '@lifi/perps-sdk'
 import type { PerpsMarket } from '@lifi/perps-types'

package/src/utils/mapMarketContext.ts

@@ -1,3 +1,4 @@
+import { numberToDecimalString } from '@lifi/perps-sdk'
 import type { MarketContext } from '@lifi/perps-types'
 import type { LtWsMarketStats, LtWsSpotMarketStats } from '../types/index.js'
 
@@ -7,6 +8,27 @@ const isPerpStats = (
   stats: LtWsMarketStats | LtWsSpotMarketStats
 ): stats is LtWsMarketStats => 'mark_price' in stats
 
+const isFiniteFigure = (value: number | null | undefined): value is number =>
+  typeof value === 'number' && Number.isFinite(value)
+
+/**
+ * The 24h figures of one record, omitted where the frame carries no finite
+ * number. The venue publishes them as unvalidated JSON, and `market_stats/all`
+ * maps every market in one pass, so a single absent figure must not cost the
+ * whole frame.
+ */
+const dailyFigures = (stats: {
+  daily_price_change?: number | null
+  daily_quote_token_volume?: number | null
+}): Pick<MarketContext, 'priceChange24h' | 'volume24h'> => ({
+  ...(isFiniteFigure(stats.daily_price_change)
+    ? { priceChange24h: numberToDecimalString(stats.daily_price_change) }
+    : {}),
+  ...(isFiniteFigure(stats.daily_quote_token_volume)
+    ? { volume24h: numberToDecimalString(stats.daily_quote_token_volume) }
+    : {}),
+})
+
 /**
  * Map a Lighter market-stats record to a {@link MarketContext}: `index_price`
  * is the oracle, `mid_price` the mid. Perp records carry the venue
@@ -24,8 +46,7 @@ export const mapMarketContext = (
       midPrice: stats.mid_price,
       markPrice: stats.mark_price,
       oraclePrice: stats.index_price,
-      priceChange24h: String(stats.daily_price_change),
-      volume24h: String(stats.daily_quote_token_volume),
+      ...dailyFigures(stats),
       openInterest: stats.open_interest,
       funding: {
         rate: stats.current_funding_rate,
@@ -38,7 +59,6 @@ export const mapMarketContext = (
     midPrice: stats.mid_price,
     markPrice: stats.mid_price,
     oraclePrice: stats.index_price,
-    priceChange24h: String(stats.daily_price_change),
-    volume24h: String(stats.daily_quote_token_volume),
+    ...dailyFigures(stats),
   }
 }

package/src/utils/orderFormatting.ts

@@ -1,31 +1,38 @@
 /**
- * Lighter order size and price formatting for exchange submission.
+ * Lighter order size and price snapping for exchange submission.
  *
  * Lighter publishes a flat per-market decimal budget on its order books
  * (`supported_price_decimals` / `supported_size_decimals`), surfaced on the
- * generic {@link Market} as `priceDecimals` / `szDecimals`. Prices round to
- * the tick grid; sizes truncate to the lot grid.
+ * generic {@link Market} as `priceDecimals` / `szDecimals`. Prices round onto
+ * the tick grid; sizes truncate onto the lot grid.
  */
 
 import { PerpsError } from '@lifi/perps-sdk'
-import { type Market, PerpsErrorCode } from '@lifi/perps-types'
+import {
+  type DecimalString,
+  type Market,
+  PerpsErrorCode,
+} from '@lifi/perps-types'
 import Big from 'big.js'
 
 /**
- * Format a price onto a Lighter market's tick grid: rounded to the market's
- * `priceDecimals` (Lighter's `supported_price_decimals`), trailing zeros
- * stripped.
+ * Snap a price onto a Lighter market's tick grid: rounded half-up to the
+ * market's `priceDecimals` (Lighter's `supported_price_decimals`), trailing
+ * zeros stripped.
  *
  * @throws {PerpsError} `ValidationError` when `market.priceDecimals` is
  *   absent — without the venue's tick grid no correct price can be produced.
  * @public
  */
-export function formatOrderPrice(market: Market, price: number): string {
+export function snapOrderPrice(
+  market: Market,
+  price: DecimalString
+): DecimalString {
   if (market.priceDecimals === undefined) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
       `Market '${market.id}' carries no priceDecimals; Lighter order prices ` +
-        `cannot be formatted without the market's tick grid.`
+        `cannot be snapped without the market's tick grid.`
     )
   }
   const rounded = new Big(price).round(market.priceDecimals, Big.roundHalfUp)
@@ -33,14 +40,17 @@ export function formatOrderPrice(market: Market, price: number): string {
 }
 
 /**
- * Format a size onto a Lighter market's lot grid: truncated (never rounded
- * up, so the size cannot exceed the user's balance) to the market's
+ * Snap a size onto a Lighter market's lot grid: truncated toward zero (never
+ * rounded up, so the size cannot exceed the user's balance) to the market's
  * `szDecimals` (Lighter's `supported_size_decimals`), trailing zeros stripped.
  *
  * @param size - Size in base-asset units as a non-negative magnitude.
  * @public
  */
-export function formatOrderSize(market: Market, size: number): string {
+export function snapOrderSize(
+  market: Market,
+  size: DecimalString
+): DecimalString {
   const truncated = new Big(size).round(market.szDecimals, Big.roundDown)
   return truncated.eq(0) ? '0' : truncated.toFixed()
 }

package/src/utils/withdrawableBalances.ts

@@ -1,4 +1,8 @@
-import { maxOf, minOf, type ProviderWithdrawableBalance } from '@lifi/perps-sdk'
+import {
+  calculateTransferable,
+  calculateWithdrawMax,
+  type ProviderWithdrawableBalance,
+} from '@lifi/perps-sdk'
 import Big from 'big.js'
 import type { LtAccount } from '../types/account.js'
 import { toRequiredBig } from './decimal.js'
@@ -29,21 +33,32 @@ export const lighterWithdrawableBalances = (
       toRequiredBig(asset.locked_balance, 'locked_balance')
     )
     if (spot.gt(0)) {
-      rows.push({ assetId, route: 'spot', available: spot.toFixed() })
+      const available = spot.toFixed()
+      rows.push({
+        assetId,
+        route: 'spot',
+        available,
+        max: calculateWithdrawMax({ available }),
+      })
     }
     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
+        ? calculateTransferable(
+            toRequiredBig(
+              account.available_balance,
+              'available_balance'
+            ).toFixed(),
+            marginBalance.toFixed()
           )
-        : marginBalance
-    if (perps.gt(0)) {
-      rows.push({ assetId, route: 'perps', available: perps.toFixed() })
+        : marginBalance.toFixed()
+    if (new Big(perps).gt(0)) {
+      rows.push({
+        assetId,
+        route: 'perps',
+        available: perps,
+        max: calculateWithdrawMax({ available: perps }),
+      })
     }
   }
   return rows

package/src/websocket/LighterWsProvider.ts

@@ -293,15 +293,6 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
 
     const wireChannels = await this.resolveChannel(sub)
 
-    // Reject before any wire sub registers: a registered sub whose token can
-    // never be resolved is retried on every reopen without the caller ever
-    // seeing the failure.
-    for (const { channel, needsAuth, address } of wireChannels) {
-      if (needsAuth) {
-        await this.requireAuthToken(channel, address)
-      }
-    }
-
     // Acquired before the wire subs register, so a rejected spot-mark open
     // leaves no `user_stats`/`account_all` entry behind for the next replay.
     const releaseSpotMarks =
@@ -392,8 +383,9 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
    * The auth token a gated channel's subscribe frame carries, or a throw when
    * no resolver is wired or the resolver yields none. Shared by the
    * subscribe-time guard and the per-send resolve so both report one message.
-   * Throws {@link PerpsError} with `Unauthorized` so a caller branches on the
-   * code, as it does for the Ondo and Lighter REST auth failures.
+   * Throws {@link PerpsError}: `SetupRequired` when the resolver yields no
+   * token, the code the REST reads throw for the same missing credential, and
+   * `SDKError` when no resolver is wired, which no account setup can fix.
    */
   private async requireAuthToken(
     channel: string,
@@ -402,7 +394,7 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
     const resolve = this.authTokenResolver()
     if (!resolve || !address) {
       throw new PerpsError(
-        PerpsErrorCode.Unauthorized,
+        PerpsErrorCode.SDKError,
         `Lighter WS channel '${channel}' requires authentication but no auth-token resolver was available. ` +
           'Register `lighterProvider()` on the same client, or pass `resolveAuthToken` to `lighterWsProvider`.'
       )
@@ -410,7 +402,7 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
     const token = await resolve(address)
     if (!token) {
       throw new PerpsError(
-        PerpsErrorCode.Unauthorized,
+        PerpsErrorCode.SetupRequired,
         `Lighter WS channel '${channel}' requires authentication but no token was available for ${address}.`
       )
     }
@@ -534,13 +526,18 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       sub.channel === 'fills' ||
       sub.channel === 'positions'
     ) {
-      const accountIndex = await this.resolveAccountIndex(sub.address)
       const lighterChannel = LIGHTER_AUTH_CHANNEL[sub.channel]
       // `account_all_trades` is publicly readable per the Lighter WS spec —
       // an auth token only filters events to the user's own account, which
       // we don't currently use to scope further. Skip the token here so a
       // user without a registered API key still gets their fill stream.
       const needsAuth = sub.channel !== 'fills'
+      // Before the account lookup and before registration: a registered sub
+      // with no token would fail on every reopen without the caller seeing it.
+      if (needsAuth) {
+        await this.requireAuthToken(lighterChannel, sub.address)
+      }
+      const accountIndex = await this.resolveAccountIndex(sub.address)
       return [
         {
           channel: `${lighterChannel}/${accountIndex}`,