@lifi/perps-sdk 23.1.0 → 25.0.0

package/src/transport/request.ts

@@ -20,6 +20,11 @@ import {
 export interface RequestOptions extends RequestInit {
   /** Per-call retry override. Falls back to the resolved client-level policy. */
   retry?: RetryPolicy | false
+  /**
+   * Send `x-lifi-perps-sdk`. Defaults to `true`. The LI.FI API CORS preflight
+   * does not allow the header, so a browser blocks a LI.FI API call that sends it.
+   */
+  perpsSdkHeader?: boolean
   /** Successful response metadata, delivered only after JSON decoding. */
   onResponse?: (
     headers: Headers,
@@ -40,7 +45,7 @@ export async function request<T>(
   options: RequestOptions = {},
   sdkOptions?: SDKRequestOptions
 ): Promise<T> {
-  const { retry, onResponse, ...fetchInit } = options
+  const { retry, onResponse, perpsSdkHeader = true, ...fetchInit } = options
   const policy =
     retry !== undefined
       ? resolveRetryPolicy(LIFI_RETRY_DEFAULTS, retry, LIFI_REQUEST_KEY)
@@ -48,7 +53,7 @@ export async function request<T>(
 
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
-    'x-lifi-perps-sdk': version,
+    ...(perpsSdkHeader && { 'x-lifi-perps-sdk': version }),
     ...(fetchInit.headers as Record<string, string>),
   }
 

package/src/types/api.ts

@@ -293,6 +293,16 @@ export interface GetWithdrawableBalancesParams {
   address: Address
 }
 
+/**
+ * Parameters for {@link PerpsClient.getWithdrawalTypes}.
+ *
+ * @public
+ */
+export interface GetWithdrawalTypesParams {
+  provider: string
+  address: Address
+}
+
 /**
  * Parameters for {@link PerpsClient.getPortfolioHistory}.
  *

package/src/types/provider.ts

@@ -37,7 +37,11 @@ import type {
   SDKRequestOptions,
 } from './config.js'
 import type { DepositFlow } from './deposit.js'
-import type { ProviderWithdrawableBalance, WithdrawFlow } from './withdrawal.js'
+import type {
+  ProviderWithdrawableBalance,
+  WithdrawalSourceTypes,
+  WithdrawFlow,
+} from './withdrawal.js'
 
 /**
  * Low-level SDK client: resolved config, the optional end-user wallet, and the
@@ -147,8 +151,8 @@ export interface ActionSignerContribution {
  */
 export interface LiquidationEstimateParams {
   /** Entry price in quote currency per base unit. */
-  entryPrice: number
-  leverage: number
+  entryPrice: string
+  leverage: string
   /** `true` for long, `false` for short. */
   isLong: boolean
 }
@@ -199,6 +203,15 @@ export interface ProviderGetWithdrawableBalancesParams {
   address: Address
 }
 
+/**
+ * Read params for {@link PerpsProviderPlugin.getWithdrawalTypes}.
+ *
+ * @public
+ */
+export interface ProviderGetWithdrawalTypesParams {
+  address: Address
+}
+
 /**
  * Read params for {@link PerpsProvider.getPositions}.
  *
@@ -322,7 +335,7 @@ export interface ProviderGetQuoteParams {
   /** Trade direction used to choose asks for buys or bids for sells. */
   side: QuoteSide
   /** USD notional to fill. */
-  size: number
+  size: string
   /** Product family used to disambiguate spot and perpetual markets. */
   type: TradeType
 }
@@ -434,20 +447,33 @@ export interface PerpsProviderPlugin {
   ): Promise<WithdrawFlow>
 
   /**
-   * The `(asset, route)` pairs `params.address` currently has something to
+   * The `(asset, category)` pairs `params.address` currently has something to
    * withdraw from, keyed by provider-native asset id. Only the venue knows how
-   * its balance payload splits across routes, so the split is owned here; the
+   * its balance payload splits across categories, so the split is owned here; the
    * per-asset venue minimum is applied by `PerpsClient.getWithdrawableBalances`,
    * which holds the core asset registry.
    *
-   * Optional: a provider whose withdrawals are not a per-route selection omits
-   * it, and `PerpsClient.getWithdrawableBalances` then resolves `undefined`.
+   * Optional: a provider whose withdrawals are not a per-category selection
+   * omits it, and `PerpsClient.getWithdrawableBalances` then resolves
+   * `undefined`.
    */
   getWithdrawableBalances?(
     params: ProviderGetWithdrawableBalancesParams,
     options?: SDKRequestOptions
   ): Promise<ProviderWithdrawableBalance[]>
 
+  /**
+   * The withdrawal types `params.address` can choose per withdrawable holding,
+   * each with its cap and the `withdrawalOptions` to send with it.
+   *
+   * Optional: a provider with one withdrawal type omits it, and
+   * `PerpsClient.getWithdrawalTypes` then resolves `undefined`.
+   */
+  getWithdrawalTypes?(
+    params: ProviderGetWithdrawalTypesParams,
+    options?: SDKRequestOptions
+  ): Promise<WithdrawalSourceTypes[]>
+
   getPositions(
     params: ProviderGetPositionsParams,
     options?: SDKRequestOptions
@@ -573,18 +599,15 @@ export interface PerpsProviderPlugin {
    * positions, prefer `Position.liquidationPrice` from the venue. Pure —
    * does no I/O.
    *
-   * Numbers, in and out, on purpose: this is a display-tier estimate that
-   * feeds a screen, not a wire amount. It is not a `snap*` method and must
-   * not be converted to {@link DecimalString}.
-   *
-   * @returns The estimated liquidation price, or `undefined` when the venue's
-   *   model cannot be evaluated client-side (degenerate inputs, or `market`
-   *   lacks the margin metadata the model needs).
+   * @returns The estimated liquidation price, or `undefined` when `market`
+   *   lacks the margin metadata the model needs.
+   * @throws {PerpsError} `ValidationError` when an input does not match the
+   *   decimal pattern or is degenerate, such as a zero leverage.
    */
   estimateLiquidationPrice(
     market: PerpsMarket,
     params: LiquidationEstimateParams
-  ): number | undefined
+  ): string | undefined
 
   /**
    * Margin that can be removed from `position` under the venue margin rules,

package/src/types/withdrawal.ts

@@ -2,22 +2,22 @@ import type {
   ActionType,
   Asset,
   DecimalString,
-  WithdrawalRoute,
+  WithdrawalAssetRef,
+  WithdrawalType,
 } from '@lifi/perps-types'
 import type { Address } from 'viem'
 
-export type { WithdrawalRoute }
-
 /**
- * One withdrawable `(asset, route)` selection as the provider reports it, keyed
- * by provider-native asset id and awaiting the core asset-metadata join.
+ * One withdrawable `(asset, category)` selection as the provider reports it,
+ * keyed by provider-native asset id and awaiting the core asset-metadata join.
  *
  * @public
  */
 export interface ProviderWithdrawableBalance {
   /** Provider-native `Asset.id`; never a display symbol. */
   assetId: string
-  route: WithdrawalRoute
+  /** The provider category the row draws from; the same value as `Balance.categoryId`. */
+  categoryId: string
   /** Withdrawable amount in the asset's own units. Always greater than zero. */
   available: DecimalString
   /**
@@ -41,7 +41,7 @@ export interface ProviderWithdrawableBalance {
 }
 
 /**
- * One withdrawable `(asset, route)` selection a caller can act on: the amount
+ * One withdrawable `(asset, category)` selection a caller can act on: the amount
  * clears the asset's venue minimum, and `asset` carries the precision and
  * minimum needed to scale and validate the withdrawal.
  *
@@ -49,7 +49,8 @@ export interface ProviderWithdrawableBalance {
  */
 export interface WithdrawableBalance {
   asset: Asset
-  route: WithdrawalRoute
+  /** The provider category the row draws from; the same value as `Balance.categoryId`. */
+  categoryId: string
   /** Withdrawable amount in the asset's own units. */
   available: DecimalString
   /**
@@ -77,6 +78,32 @@ export interface WithdrawableBalance {
   isFeeDeducted?: boolean
 }
 
+/**
+ * One way a venue can settle a withdrawal from a holding.
+ *
+ * @public
+ */
+export interface WithdrawalTypeOption {
+  type: WithdrawalType
+  /** Largest `amount` this type accepts from the holding, in the asset's own units. */
+  max: DecimalString
+  /**
+   * Provider-specific options to pass unchanged as
+   * `WithdrawalParams.withdrawalOptions` when the user picks this type.
+   */
+  withdrawalOptions: Record<string, unknown>
+}
+
+/**
+ * The withdrawal types a venue offers for one holding.
+ *
+ * @public
+ */
+export interface WithdrawalSourceTypes {
+  source: WithdrawalAssetRef
+  options: WithdrawalTypeOption[]
+}
+
 /**
  * The venue accepts a withdrawal to `destination` now.
  *

package/src/utils/createSafeFunction.ts

@@ -0,0 +1,20 @@
+/**
+ * Wrap a throwing function so that it gives `undefined` in place of a throw.
+ * The wrapper logs a warning with `name` and the error, which carries the
+ * stack trace.
+ *
+ * @public
+ */
+export function createSafeFunction<Args extends unknown[], Result>(
+  name: string,
+  throwingFunction: (...args: Args) => Result
+): (...args: Args) => Result | undefined {
+  return (...args) => {
+    try {
+      return throwingFunction(...args)
+    } catch (error) {
+      console.warn(`[perps-sdk] ${name} failed`, error)
+      return undefined
+    }
+  }
+}

package/src/utils/timestampToIsoString.ts

@@ -0,0 +1,31 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { PerpsError } from '../errors/PerpsError.js'
+import { createSafeFunction } from './createSafeFunction.js'
+
+/**
+ * Read a venue time (epoch milliseconds or a date string) as an ISO-8601
+ * string.
+ *
+ * @throws {PerpsError} `ValidationError` when `Date` cannot read `value`.
+ * @public
+ */
+export function timestampToIsoString(value: string | number): string {
+  const time = value === '' ? Number.NaN : new Date(value).getTime()
+  if (Number.isNaN(time)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `'${String(value)}' is not a valid timestamp.`
+    )
+  }
+  return new Date(time).toISOString()
+}
+
+/**
+ * {@link timestampToIsoString}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export const safeTimestampToIsoString = createSafeFunction(
+  'timestampToIsoString',
+  timestampToIsoString
+)

package/src/utils/warnOnce.ts

@@ -27,3 +27,63 @@ export const createWarnOnce = (): ((key: string, message: string) => void) => {
     console.warn(message)
   }
 }
+
+const MAX_VALUE_CHARS = 64
+
+/**
+ * Cut venue text to a fixed length, so a warner key or message built from it
+ * stays small.
+ *
+ * @internal
+ */
+export const cutVenueText = (value: unknown): string => {
+  const text = String(value)
+  return text.length > MAX_VALUE_CHARS
+    ? `${text.slice(0, MAX_VALUE_CHARS)}…`
+    : text
+}
+
+/**
+ * Describe a skipped venue row. The venue value is cut to a fixed length, so
+ * a warner key built from the text stays small.
+ *
+ * @internal
+ */
+export const skippedRowMessage = (
+  source: string,
+  row: string,
+  field: string,
+  value: unknown,
+  expected: string,
+  marketId?: string
+): string => {
+  const market = marketId === undefined ? '' : ` on market '${marketId}'`
+  return `[${source}] skipping ${row} row${market}: \`${field}\` is not a valid ${expected}: '${cutVenueText(value)}'`
+}
+
+const warnSkippedRowOnce = createWarnOnce()
+
+/**
+ * Warn once for each provider, row, field, expected kind and market that a
+ * provider mapper skipped a venue row because a required field is not valid.
+ * The key holds no venue value, so a second bad value for the same field on
+ * the same market stays silent.
+ *
+ * @param options.expected - What the field must be. Defaults to `'decimal'`.
+ * @internal
+ */
+export const warnSkippedVenueRow = (
+  provider: string,
+  row: string,
+  field: string,
+  value: unknown,
+  {
+    marketId,
+    expected = 'decimal',
+  }: { marketId?: string; expected?: string } = {}
+): void => {
+  warnSkippedRowOnce(
+    `${provider}|${row}|${field}|${expected}|${marketId ?? ''}`,
+    skippedRowMessage(provider, row, field, value, expected, marketId)
+  )
+}

package/src/version.ts

@@ -10,4 +10,4 @@ export const name = '@lifi/perps-sdk'
  *
  * @public
  */
-export const version = '23.1.0'
+export const version = '25.0.0'

package/src/websocket/PerpsWsClient.ts

@@ -1,4 +1,8 @@
-import { PerpsErrorCode, type Subscription } from '@lifi/perps-types'
+import {
+  PerpsErrorCode,
+  type ProvidersResponse,
+  type Subscription,
+} from '@lifi/perps-types'
 import { PerpsError } from '../errors/PerpsError.js'
 import { getProviders } from '../services/getProviders.js'
 import type { GetQuoteParams } from '../services/getQuote.js'
@@ -70,6 +74,7 @@ export class PerpsWsClient {
   private readonly options: PerpsWsClientOptions
   private providers = new Map<string, WsProvider>()
   private initPromises = new Map<string, Promise<WsProvider>>()
+  private discovery: Promise<ProvidersResponse> | undefined
   private closed = false
 
   constructor(client: PerpsSDKClient, options: PerpsWsClientOptions = {}) {
@@ -220,7 +225,7 @@ export class PerpsWsClient {
       )
     }
 
-    const { providers } = await getProviders(this.client)
+    const { providers } = await this.discoverProviders()
     this.assertOpen()
 
     const providerInfo = providers.find((d) => d.key === provider)
@@ -236,4 +241,22 @@ export class PerpsWsClient {
     this.providers.set(provider, wsProvider)
     return wsProvider
   }
+
+  /**
+   * Shares one in-flight `/providers` request between concurrent venue
+   * inits. The slot clears on settlement, so a later init fetches fresh
+   * metadata and a rejection is never cached.
+   */
+  private discoverProviders(): Promise<ProvidersResponse> {
+    if (this.discovery) {
+      return this.discovery
+    }
+    const discovery = getProviders(this.client).finally(() => {
+      if (this.discovery === discovery) {
+        this.discovery = undefined
+      }
+    })
+    this.discovery = discovery
+    return discovery
+  }
 }

package/src/websocket/wsLog.ts

@@ -1,3 +1,9 @@
+import {
+  createWarnOnce,
+  cutVenueText,
+  skippedRowMessage,
+} from '../utils/warnOnce.js'
+
 const MAX_PAYLOAD_CHARS = 512
 
 const truncate = (raw: string): string =>
@@ -5,6 +11,8 @@ const truncate = (raw: string): string =>
     ? `${raw.slice(0, MAX_PAYLOAD_CHARS)}…(${raw.length} chars)`
     : raw
 
+const warnSkippedRowOnce = createWarnOnce()
+
 /**
  * Structured logger for WS message-handling and subscription failures, shared
  * by the provider packages so a malformed frame, a throwing mapper, or a failed
@@ -58,6 +66,42 @@ export const wsLog = {
       `[${provider}:ws] skipping item for unknown market '${marketId}'`
     )
   },
+  /**
+   * A frame row or order-book level with a required field that is not valid.
+   * Only that row is skipped. Logged once at `warn` for each provider, row,
+   * field and market; the key holds no venue value.
+   */
+  skippedRow(
+    provider: string,
+    row: string,
+    field: string,
+    value: unknown,
+    marketId?: string
+  ): void {
+    warnSkippedRowOnce(
+      `${provider}|${row}|${field}|${marketId ?? ''}`,
+      skippedRowMessage(
+        `${provider}:ws`,
+        row,
+        field,
+        value,
+        'decimal',
+        marketId
+      )
+    )
+  },
+  /**
+   * A frame row the mapper rejected for a reason other than one field, such as
+   * a lifecycle state the SDK does not carry. Logged once at `warn` for each
+   * provider, row and reason; the reason is cut to a fixed length.
+   */
+  droppedRow(provider: string, row: string, reason: string): void {
+    const shown = cutVenueText(reason)
+    warnSkippedRowOnce(
+      `${provider}|${row}|dropped|${shown}`,
+      `[${provider}:ws] skipping ${row} row: ${shown}`
+    )
+  },
   /**
    * A background market-registry refetch rejected. Unknown-market items keep
    * being skipped until the next cooldown-gated retry, so logged at `warn`.

package/src/wire/orderAmounts.ts

@@ -1,8 +1,16 @@
-import type { DecimalString, Market } from '@lifi/perps-types'
-import Big from 'big.js'
+import {
+  type DecimalString,
+  type Market,
+  PerpsErrorCode,
+} from '@lifi/perps-types'
+import type Big from 'big.js'
 import { DivBig, TruncBig } from '../decimal/big.js'
+import { isDecimalStringZero } from '../decimal/compare.js'
 import { isDecimalString } from '../decimal/parse.js'
+import { invalidInput } from '../errors/invalidInput.js'
+import { PerpsError } from '../errors/PerpsError.js'
 import type { PerpsSDKClient } from '../types/provider.js'
+import { createSafeFunction } from '../utils/createSafeFunction.js'
 import { snapOrderSize } from './snap.js'
 
 /** @public */
@@ -30,14 +38,20 @@ export interface OrderAmounts {
   notional: DecimalString
 }
 
-function positiveDecimal(value: DecimalString): Big | null {
-  if (!isDecimalString(value)) {
-    return null
+function requirePositiveDecimal(value: DecimalString, parameter: string): Big {
+  const parsed = isDecimalString(value) ? new TruncBig(value) : undefined
+  if (parsed === undefined || !parsed.gt(0)) {
+    throw invalidInput(
+      parameter,
+      `must be a positive decimal, got '${String(value)}'`
+    )
   }
-  const parsed = new TruncBig(value)
-  return parsed.gt(0) ? parsed : null
+  return parsed
 }
 
+const lotSize = (market: Market): DecimalString =>
+  market.sizeIncrement ?? new TruncBig(`1e-${market.szDecimals}`).toFixed()
+
 /**
  * The three order-entry amounts, derived from whichever one the user typed.
  * Only `size` snaps, onto the market's venue lot grid, because an order sends
@@ -45,26 +59,22 @@ function positiveDecimal(value: DecimalString): Big | null {
  * `notional` is the snapped size × price, and a derived margin is
  * `notional ÷ leverage` in `DivBig` (40 places, half-up).
  *
- * @returns `null` when `amount` or `price` is not a positive
- *   {@link DecimalString}, when `leverage` is not a positive finite number, or
- *   when the snapped size is zero (below one lot).
- * @throws {PerpsError} `SDKError` when `market.providerId` names no registered
- *   provider plugin.
+ * @throws {PerpsError} `ValidationError` that names `amount` or `price` when
+ *   it is not a positive decimal, or `leverage` when it is not a finite number
+ *   above zero. `ValidationError` with the lot size when the snapped size is
+ *   zero (below one lot). `SDKError` when `market.providerId` names no
+ *   registered provider plugin.
  * @public
  */
-export function calculateOrderAmounts(
-  input: OrderAmountsInput
-): OrderAmounts | null {
+export function calculateOrderAmounts(input: OrderAmountsInput): OrderAmounts {
   const { sdk, market, held, leverage } = input
-  const amount = positiveDecimal(input.amount)
-  const price = positiveDecimal(input.price)
-  if (
-    amount === null ||
-    price === null ||
-    !Number.isFinite(leverage) ||
-    leverage <= 0
-  ) {
-    return null
+  const amount = requirePositiveDecimal(input.amount, 'amount')
+  const price = requirePositiveDecimal(input.price, 'price')
+  if (!Number.isFinite(leverage) || leverage <= 0) {
+    throw invalidInput(
+      'leverage',
+      `must be a finite number above zero, got ${leverage}`
+    )
   }
 
   const requested =
@@ -74,8 +84,11 @@ export function calculateOrderAmounts(
         ? amount.div(price).toFixed()
         : amount.times(leverage).div(price).toFixed()
   const size = snapOrderSize(sdk, market, requested)
-  if (new Big(size).eq(0)) {
-    return null
+  if (isDecimalStringZero(size)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `The order size ${requested} is below the lot size ${lotSize(market)}.`
+    )
   }
 
   const notional = new TruncBig(size).times(price)
@@ -88,3 +101,9 @@ export function calculateOrderAmounts(
     notional: notional.toFixed(),
   }
 }
+
+/** @public */
+export const safeCalculateOrderAmounts = createSafeFunction(
+  'calculateOrderAmounts',
+  calculateOrderAmounts
+)