@lifi/perps-sdk 19.0.0 → 20.1.0

package/src/registry/referenceDataRegistry.ts

@@ -1,14 +1,64 @@
 import { PerpsErrorCode } from '@lifi/perps-types'
 import { PerpsError } from '../errors/PerpsError.js'
+import type { RequestOptions } from '../transport/request.js'
 import type { PerpsSDKClient } from '../types/provider.js'
 import { createWarnOnce } from '../utils/warnOnce.js'
 
+function freshUntil(
+  headers: Headers,
+  requestStartedAt: number,
+  responseReceivedAt: number
+): number {
+  const directives = (headers.get('cache-control') ?? '')
+    .toLowerCase()
+    .split(',')
+    .map((directive) => directive.trim())
+  if (
+    directives.some((directive) =>
+      /^(no-store|no-cache)(?:\s*=|$)/.test(directive)
+    ) ||
+    headers
+      .get('vary')
+      ?.split(',')
+      .some((name) => name.trim() === '*')
+  ) {
+    return 0
+  }
+  const maxAges = directives.filter((directive) =>
+    /^max-age(?:\s*=|$)/.test(directive)
+  )
+  const maxAge =
+    maxAges.length === 1
+      ? /^max-age\s*=\s*(?:"(\d+)"|(\d+))$/.exec(maxAges[0])
+      : null
+  if (!maxAge) {
+    return 0
+  }
+  const age = headers.get('age') ?? '0'
+  const date = headers.get('date')
+  const dateTime = date === null ? responseReceivedAt : Date.parse(date)
+  if (!/^\d+$/.test(age) || !Number.isFinite(dateTime)) {
+    return 0
+  }
+  const lifetime = Number(maxAge[1] ?? maxAge[2]) * 1000
+  const currentAge = Math.max(
+    responseReceivedAt - dateTime,
+    Number(age) * 1000 + Math.max(0, responseReceivedAt - requestStartedAt)
+  )
+  return Number.isFinite(lifetime)
+    ? responseReceivedAt + lifetime - currentAge
+    : 0
+}
+
 /** Atomic provider reference indexes; HTTP cache headers govern freshness. @internal */
 export abstract class ReferenceDataRegistry<T> {
   private index = new Map<string, T>()
   private secondaryIndexes = new Map<string, Map<string, T>>()
   private current: readonly T[] = []
   private inflight: Promise<readonly T[]> | undefined
+  private inflightIdentity: string | undefined
+  private cacheIdentity: string | undefined
+  private freshUntil = 0
   private readonly warnOnce = createWarnOnce()
 
   protected constructor(
@@ -21,21 +71,37 @@ export abstract class ReferenceDataRegistry<T> {
   ) {}
 
   /** Fetch the provider's full list through the HTTP layer. */
-  protected abstract fetchItems(): Promise<T[]>
+  protected abstract fetchItems(
+    onResponse: RequestOptions['onResponse']
+  ): Promise<T[]>
 
   /** The item's primary key — what {@link get} is keyed by. */
   protected abstract keyOf(item: T): string
 
-  /**
-   * Fetch the list through the HTTP cache and rebuild the index. Concurrent
-   * callers share one in-flight fetch; a settled fetch is never reused, so
-   * HTTP `cache-control` alone governs freshness.
-   */
+  /** Sync reference indexes, reusing only explicitly fresh Node responses. */
   sync(): Promise<readonly T[]> {
-    if (!this.inflight) {
-      this.inflight = this.load().finally(() => {
-        this.inflight = undefined
+    const { config } = this.client
+    // Hooks can change credentials or cache policy on every call.
+    if (config.requestInterceptor || config.fetch) {
+      return this.load()
+    }
+    const identity = JSON.stringify([
+      config.apiUrl,
+      config.apiKey,
+      config.integrator,
+    ])
+    if (identity === this.cacheIdentity && Date.now() < this.freshUntil) {
+      return Promise.resolve(this.current)
+    }
+    if (!this.inflight || this.inflightIdentity !== identity) {
+      const inflight = this.load(identity).finally(() => {
+        if (this.inflight === inflight) {
+          this.inflight = undefined
+          this.inflightIdentity = undefined
+        }
       })
+      this.inflight = inflight
+      this.inflightIdentity = identity
     }
     return this.inflight
   }
@@ -59,8 +125,18 @@ export abstract class ReferenceDataRegistry<T> {
     return this.secondaryIndexes.get(key)?.get(id)
   }
 
-  private async load(): Promise<readonly T[]> {
-    const items = await this.fetchItems()
+  private async load(identity?: string): Promise<readonly T[]> {
+    let expiresAt = 0
+    const items = await this.fetchItems((headers, startedAt, receivedAt) => {
+      // Browsers retain their native HTTP cache and its resident response age.
+      if (
+        identity !== undefined &&
+        typeof process !== 'undefined' &&
+        process.versions?.node
+      ) {
+        expiresAt = freshUntil(headers, startedAt, receivedAt)
+      }
+    })
     const index = new Map<string, T>()
     for (const item of items) {
       const key = this.keyOf(item)
@@ -93,6 +169,8 @@ export abstract class ReferenceDataRegistry<T> {
     this.index = index
     this.secondaryIndexes = secondaryIndexes
     this.current = items
+    this.cacheIdentity = identity
+    this.freshUntil = expiresAt
     return items
   }
 }

package/src/services/getOhlcv.ts

@@ -12,6 +12,7 @@ export interface GetOhlcvParams {
   provider: string
   /** Opaque provider `Market.id`, not a display symbol. */
   marketId: string
+  /** Pick from the provider's `Provider.supportedIntervals`; support varies per provider. */
   interval: OhlcvInterval
   /** Unix timestamp in milliseconds for the start bound. */
   startTime?: number

package/src/transport/request.ts

@@ -20,6 +20,12 @@ import {
 export interface RequestOptions extends RequestInit {
   /** Per-call retry override. Falls back to the resolved client-level policy. */
   retry?: RetryPolicy | false
+  /** Successful response metadata, delivered only after JSON decoding. */
+  onResponse?: (
+    headers: Headers,
+    requestStartedAt: number,
+    responseReceivedAt: number
+  ) => void
 }
 
 /**
@@ -34,7 +40,7 @@ export async function request<T>(
   options: RequestOptions = {},
   sdkOptions?: SDKRequestOptions
 ): Promise<T> {
-  const { retry, ...fetchInit } = options
+  const { retry, onResponse, ...fetchInit } = options
   const policy =
     retry !== undefined
       ? resolveRetryPolicy(LIFI_RETRY_DEFAULTS, retry, LIFI_REQUEST_KEY)
@@ -64,11 +70,13 @@ export async function request<T>(
   }
 
   try {
+    const requestStartedAt = onResponse ? Date.now() : 0
     const response = await fetchWithRetry(url, finalOptions, {
       policy,
       fetchImpl: config.fetch,
       signal: sdkOptions?.signal ?? finalOptions.signal ?? undefined,
     })
+    const responseReceivedAt = onResponse ? Date.now() : 0
 
     if (!response.ok) {
       let body: PerpsErrorBody | undefined
@@ -94,7 +102,9 @@ export async function request<T>(
       throw error
     }
 
-    return (await response.json()) as T
+    const data = (await response.json()) as T
+    onResponse?.(response.headers, requestStartedAt, responseReceivedAt)
+    return data
   } catch (error) {
     if (error instanceof PerpsError) {
       throw error

package/src/types/api.ts

@@ -24,11 +24,7 @@ import type {
 } from '@lifi/perps-types'
 import type { Account, Address, WalletClient } from 'viem'
 import type { RetryConfig } from '../transport/retryPolicy.js'
-import type {
-  ProviderConfigs,
-  RequestInterceptor,
-  SwitchChainHook,
-} from './config.js'
+import type { RequestInterceptor, SwitchChainHook } from './config.js'
 import type { PerpsProviderPlugin } from './provider.js'
 
 /**
@@ -52,25 +48,15 @@ export interface PerpsConfig {
   apiKey?: string
   /** Perps API base URL; defaults to {@link DEFAULT_API_URL}. */
   apiUrl?: string
-  /** Skip the SDK-version compatibility check when set. */
-  disableVersionCheck?: boolean
   /** Hook that can rewrite URL/request options before transport. */
   requestInterceptor?: RequestInterceptor
   /**
-   * Provider plugins or per-provider config. Two shapes are accepted:
-   *
-   * - `PerpsProviderPlugin[]` — plugin objects implementing the read surface
-   *   for one DEX each. Bound to the client at construction and looked up at
-   *   runtime as bound {@link PerpsProvider}s via `client.getProvider(key)`.
-   *   Modelled on `@lifi/sdk`'s `providers: SDKProvider[]`.
-   * - `ProviderConfigs` — keyed config object (e.g.
-   *   `{ hyperliquid: { markets: [...] } }`). Used internally by
-   *   `PerpsWsClient` to filter which markets are subscribed to.
-   *
-   * Both may be supplied during the migration to provider packages;
-   * the array form is preferred for new code.
+   * Provider plugins, one per DEX. Bound to the client at construction and
+   * looked up at runtime as bound {@link PerpsProvider}s via
+   * `client.getProvider(key)`. Modelled on `@lifi/sdk`'s
+   * `providers: SDKProvider[]`.
    */
-  providers?: PerpsProviderPlugin[] | ProviderConfigs
+  providers?: PerpsProviderPlugin[]
   /**
    * The end-user's wallet, used whenever an action's descriptor names
    * `PerpsSigner.USER` as its `signer`. Accepts any viem-compatible WalletClient:
@@ -117,12 +103,8 @@ export interface PerpsClientOptions {
   apiKey?: string
   /** Perps API base URL; defaults to {@link DEFAULT_API_URL}. */
   apiUrl?: string
-  /**
-   * Provider plugins or per-provider config. Accepts the same two shapes as
-   * {@link PerpsConfig.providers}: an array of `PerpsProviderPlugin` plugins or
-   * a keyed `ProviderConfigs` map.
-   */
-  providers?: PerpsProviderPlugin[] | ProviderConfigs
+  /** Provider plugins; see {@link PerpsConfig.providers}. */
+  providers?: PerpsProviderPlugin[]
   /**
    * Hook invoked before a USER-signed EIP-712 action is signed, to switch the
    * user's wallet to the action's target chain. Also settable at runtime via

package/src/types/config.ts

@@ -23,32 +23,6 @@ export type SwitchChainHook = (
   chainId: number
 ) => Promise<PerpsClientSigner | undefined>
 
-/**
- * Per-provider config — restricts which `markets` the WS client subscribes
- * to. Indexed by provider key.
- *
- * @public
- */
-export interface ProviderConfig {
-  /** Optional provider category/market ids used to filter WS subscriptions. */
-  markets?: string[]
-}
-
-/**
- * @deprecated Use {@link ProviderConfig}.
- * @public
- */
-export type HyperliquidConfig = ProviderConfig
-
-/**
- * Map of per-provider {@link ProviderConfig}, keyed by provider key.
- *
- * @public
- */
-export interface ProviderConfigs {
-  [provider: string]: ProviderConfig | undefined
-}
-
 /**
  * Hook to rewrite each outgoing request's URL/`RequestInit` before it is sent.
  *
@@ -101,12 +75,8 @@ export interface PerpsBaseConfig {
   apiKey: string
   /** Resolved perps API base URL. */
   apiUrl: string
-  /** Whether SDK version compatibility checks are disabled. */
-  disableVersionCheck?: boolean
   /** Optional outgoing-request URL/options interceptor. */
   requestInterceptor?: RequestInterceptor
-  /** Optional per-provider WS market filters. */
-  providers?: ProviderConfigs
   /** Optional global or per-provider retry configuration. */
   retry?: RetryConfig
   /** Fetch implementation used by core HTTP transport. */

package/src/types/provider.ts

@@ -453,16 +453,17 @@ export interface PerpsProviderPlugin {
   ): Promise<PositionsResponse>
 
   /**
-   * The user's current venue-side settings for one market — the margin mode
-   * and leverage the next order on it will use. Optional because venues
-   * expose this unevenly: Hyperliquid reads it directly (`activeAssetData`),
-   * Lighter only reports it on an account's position row. `undefined` means
-   * the venue has nothing to read for this market.
+   * The user's current venue-side settings for one perps market — the margin
+   * mode and leverage the next order on it will use. Resolves the venue value
+   * or throws.
+   *
+   * @throws {PerpsError} `ValidationError` for a spot market; any other
+   *   `PerpsError` when the venue read fails or carries no usable value.
    */
-  getMarketSettings?(
+  getMarketSettings(
     params: ProviderGetMarketSettingsParams,
     options?: SDKRequestOptions
-  ): Promise<MarketSettings | undefined>
+  ): Promise<MarketSettings>
 
   /**
    * The amounts the account can still buy and sell on one market, in that

package/src/types/withdrawal.ts

@@ -1,15 +1,7 @@
-import type { ActionType, Asset } from '@lifi/perps-types'
+import type { ActionType, Asset, WithdrawalRoute } from '@lifi/perps-types'
 import type { Address } from 'viem'
 
-/**
- * Which of a venue's two balance routes a withdrawal is drawn from. Lighter's
- * own vocabulary, carried in the signed tx as `AssetRouteType` (`perps` = 0,
- * `spot` = 1); an account's mode changes what the two balances mean, never
- * which route the tx names.
- *
- * @public
- */
-export type WithdrawalRoute = 'perps' | 'spot'
+export type { WithdrawalRoute }
 
 /**
  * One withdrawable `(asset, route)` selection as the provider reports it, keyed
@@ -25,10 +17,16 @@ export interface ProviderWithdrawableBalance {
   available: string
   /**
    * Flat venue fee on a withdrawal from this row, in the asset's own units.
-   * Absent when the venue publishes no fee for the asset. The client rejects a
-   * value that is not a non-negative decimal.
+   * Absent when the venue publishes no fee for the asset. The client rejects
+   * a value that is not a non-negative decimal.
    */
   withdrawalFee?: string
+  /**
+   * `true` when the venue takes `withdrawalFee` out of the requested amount,
+   * `false` when it charges the fee in addition. Set together with
+   * `withdrawalFee`; the client drops it from a row without a fee.
+   */
+  isFeeDeducted?: boolean
 }
 
 /**
@@ -44,11 +42,22 @@ export interface WithdrawableBalance {
   /** Withdrawable amount in the asset's own units. */
   available: string
   /**
-   * Flat venue fee on a withdrawal from this row, in the asset's own units. An
-   * amount at or below it delivers nothing. Absent when the venue publishes no
-   * fee for the asset.
+   * Flat venue fee on a withdrawal from this row, in the asset's own units.
+   * Absent when the venue publishes no fee for the asset. With
+   * `isFeeDeducted` `true`, the venue takes the fee out of the requested
+   * amount, and an amount at or below the fee delivers nothing. With `false`,
+   * the venue charges the fee in addition to the requested amount, so the
+   * largest amount the row can fund is `available` minus the fee. That result
+   * is zero or negative when the fee is at or above `available`, and the row
+   * then funds no withdrawal.
    */
   withdrawalFee?: string
+  /**
+   * Present only together with `withdrawalFee`. Absent on a row from a
+   * provider plugin that does not report it; absence means unknown, not
+   * `true`.
+   */
+  isFeeDeducted?: boolean
 }
 
 /**

package/src/utils/calculations.ts

@@ -16,7 +16,9 @@ import {
   type QuoteSide,
   type TradeType,
 } from '@lifi/perps-types'
+import type Big from 'big.js'
 import { PerpsError } from '../errors/PerpsError.js'
+import { areFinite, DivBig } from './decimal.js'
 
 /**
  * Calculate position size in asset units from margin.
@@ -36,7 +38,13 @@ export function calculatePositionSize(
   leverage: number,
   price: number
 ): number {
-  return (marginUsd * leverage) / price
+  if (price === 0) {
+    return (marginUsd * leverage) / price
+  }
+  if (!areFinite(marginUsd, leverage, price)) {
+    return Number.NaN
+  }
+  return new DivBig(marginUsd).times(leverage).div(price).toNumber()
 }
 
 /**
@@ -48,7 +56,10 @@ export function calculatePositionSize(
  * @public
  */
 export function calculateNotionalValue(size: number, price: number): number {
-  return Math.abs(size) * price
+  if (!areFinite(size, price)) {
+    return Number.NaN
+  }
+  return new DivBig(size).abs().times(price).toNumber()
 }
 
 /**
@@ -65,7 +76,10 @@ export function calculateUnrealizedPnl(
   currentPrice: number,
   size: number
 ): number {
-  return (currentPrice - entryPrice) * size
+  if (!areFinite(entryPrice, currentPrice, size)) {
+    return Number.NaN
+  }
+  return new DivBig(currentPrice).minus(entryPrice).times(size).toNumber()
 }
 
 /**
@@ -80,7 +94,10 @@ export function calculateRoe(pnl: number, margin: number): number {
   if (margin === 0) {
     return 0
   }
-  return (pnl / margin) * 100
+  if (!areFinite(pnl, margin)) {
+    return Number.NaN
+  }
+  return new DivBig(pnl).div(margin).times(100).toNumber()
 }
 
 /**
@@ -95,7 +112,13 @@ export function calculateRequiredMargin(
   notionalValue: number,
   leverage: number
 ): number {
-  return notionalValue / leverage
+  if (leverage === 0) {
+    return notionalValue / leverage
+  }
+  if (!areFinite(notionalValue, leverage)) {
+    return Number.NaN
+  }
+  return new DivBig(notionalValue).div(leverage).toNumber()
 }
 
 /**
@@ -107,7 +130,10 @@ export function calculateRequiredMargin(
  * @public
  */
 export function estimateFees(sizeUsd: number, feeRate: number): number {
-  return sizeUsd * feeRate
+  if (!areFinite(sizeUsd, feeRate)) {
+    return Number.NaN
+  }
+  return new DivBig(sizeUsd).times(feeRate).toNumber()
 }
 
 /**
@@ -124,8 +150,17 @@ export function applySlippage(
   slippagePercent: number,
   isBuy: boolean
 ): number {
-  const multiplier = 1 + slippagePercent / 100
-  return isBuy ? price * multiplier : price / multiplier
+  if (!areFinite(price, slippagePercent)) {
+    return Number.NaN
+  }
+  const multiplier = new DivBig(slippagePercent).div(100).plus(1)
+  if (isBuy) {
+    return new DivBig(price).times(multiplier).toNumber()
+  }
+  if (multiplier.eq(0)) {
+    return price / multiplier.toNumber()
+  }
+  return new DivBig(price).div(multiplier).toNumber()
 }
 
 /**
@@ -166,7 +201,10 @@ export function effectiveLeverage(params: {
   if (marginUsd === 0) {
     return 0
   }
-  return positionValueUsd / marginUsd
+  if (!areFinite(positionValueUsd, marginUsd)) {
+    return Number.NaN
+  }
+  return new DivBig(positionValueUsd).div(marginUsd).toNumber()
 }
 
 /**
@@ -202,12 +240,15 @@ export function calculateExpectedPnl(
   if (!triggerPrice || entryPrice === 0 || margin === 0) {
     return null
   }
+  if (!areFinite(triggerPrice, entryPrice, leverage, margin)) {
+    return { amount: Number.NaN, percent: Number.NaN }
+  }
   const priceDiff = isLong
-    ? triggerPrice - entryPrice
-    : entryPrice - triggerPrice
-  const percent = (priceDiff / entryPrice) * leverage * 100
-  const amount = margin * (percent / 100)
-  return { amount, percent }
+    ? new DivBig(triggerPrice).minus(entryPrice)
+    : new DivBig(entryPrice).minus(triggerPrice)
+  const percent = priceDiff.div(entryPrice).times(leverage).times(100)
+  const amount = percent.times(margin).div(100)
+  return { amount: amount.toNumber(), percent: percent.toNumber() }
 }
 
 /**
@@ -228,8 +269,14 @@ export function priceFromPercent(
   if (entryPrice === 0 || leverage === 0) {
     return 0
   }
-  const priceDelta = (percent / 100 / leverage) * entryPrice
-  return isLong ? entryPrice + priceDelta : entryPrice - priceDelta
+  if (!areFinite(percent, entryPrice, leverage)) {
+    return Number.NaN
+  }
+  const priceDelta = new DivBig(percent)
+    .times(entryPrice)
+    .div(new DivBig(leverage).times(100))
+  const entry = new DivBig(entryPrice)
+  return (isLong ? entry.plus(priceDelta) : entry.minus(priceDelta)).toNumber()
 }
 
 /**
@@ -250,8 +297,13 @@ export function percentFromPrice(
   if (entryPrice === 0 || leverage === 0) {
     return 0
   }
-  const priceDiff = isLong ? price - entryPrice : entryPrice - price
-  return (priceDiff / entryPrice) * leverage * 100
+  if (!areFinite(price, entryPrice, leverage)) {
+    return Number.NaN
+  }
+  const priceDiff = isLong
+    ? new DivBig(price).minus(entryPrice)
+    : new DivBig(entryPrice).minus(price)
+  return priceDiff.div(entryPrice).times(leverage).times(100).toNumber()
 }
 
 /**
@@ -268,11 +320,14 @@ export function calculateRealizedPnlPercent(
   size: number,
   price: number
 ): number {
-  const positionValue = Math.abs(size) * price
-  if (positionValue === 0) {
+  if (!areFinite(realizedPnl, size, price)) {
+    return Number.NaN
+  }
+  const positionValue = new DivBig(size).abs().times(price)
+  if (positionValue.eq(0)) {
     return 0
   }
-  return (realizedPnl / positionValue) * 100
+  return new DivBig(realizedPnl).div(positionValue).times(100).toNumber()
 }
 
 /** Result of {@link walkOrderbook} — the fill obtained for a USD-notional walk. */
@@ -283,7 +338,7 @@ interface BookWalk {
   filledNotional: number
   /** Volume-weighted average fill price, or 0 when the book is empty. */
   vwap: number
-  /** True when the levels could not absorb the requested notional. */
+  /** True when the levels could not absorb the requested notional, and for a non-finite notional. */
   insufficientLiquidity: boolean
 }
 
@@ -293,7 +348,8 @@ interface BookWalk {
  * in array order — the caller passes asks for a buy and bids for a sell, each
  * already ordered best-price-first. When the book cannot absorb the full
  * notional, the walk stops at the last level and flags `insufficientLiquidity`,
- * returning the best obtainable fill.
+ * returning the best obtainable fill. A non-finite `sizeUsd` gives NaN fill
+ * fields with `insufficientLiquidity` set.
  *
  * @throws {PerpsError} `ValidationError` when a level's `price` or `size`
  *   does not parse to a finite number.
@@ -303,32 +359,47 @@ export function walkOrderbook(
   levels: OrderbookLevel[],
   sizeUsd: number
 ): BookWalk {
-  let remaining = sizeUsd
-  let baseSize = 0
-  let filledNotional = 0
+  if (!Number.isFinite(sizeUsd)) {
+    return {
+      baseSize: Number.NaN,
+      filledNotional: Number.NaN,
+      vwap: Number.NaN,
+      insufficientLiquidity: true,
+    }
+  }
+  let remaining = new DivBig(sizeUsd)
+  let baseSize = new DivBig(0)
+  let filledNotional = new DivBig(0)
   for (const level of levels) {
-    if (remaining <= 0) {
+    if (remaining.lte(0)) {
       break
     }
-    const price = Number.parseFloat(level.price)
-    const size = Number.parseFloat(level.size)
-    if (!Number.isFinite(price) || !Number.isFinite(size)) {
-      throw new PerpsError(
-        PerpsErrorCode.ValidationError,
-        `Malformed orderbook level: price='${level.price}', size='${level.size}'`
-      )
+    const { price, size } = parseLevel(level)
+    const levelNotional = size.times(price)
+    const take = remaining.lt(levelNotional) ? remaining : levelNotional
+    if (take.eq(0)) {
+      continue
     }
-    const levelNotional = size * price
-    const take = Math.min(remaining, levelNotional)
-    filledNotional += take
-    baseSize += take / price
-    remaining -= take
+    filledNotional = filledNotional.plus(take)
+    baseSize = baseSize.plus(take.div(price))
+    remaining = remaining.minus(take)
   }
   return {
-    baseSize,
-    filledNotional,
-    vwap: baseSize === 0 ? 0 : filledNotional / baseSize,
-    insufficientLiquidity: remaining > 0,
+    baseSize: baseSize.toNumber(),
+    filledNotional: filledNotional.toNumber(),
+    vwap: baseSize.eq(0) ? 0 : filledNotional.div(baseSize).toNumber(),
+    insufficientLiquidity: remaining.gt(0),
+  }
+}
+
+function parseLevel(level: OrderbookLevel): { price: Big; size: Big } {
+  try {
+    return { price: new DivBig(level.price), size: new DivBig(level.size) }
+  } catch {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Malformed orderbook level: price='${level.price}', size='${level.size}'`
+    )
   }
 }
 

package/src/utils/decimal.ts

@@ -0,0 +1,21 @@
+import Big from 'big.js'
+
+/**
+ * Scoped big.js constructor with 40 decimal places for division, so the
+ * shared global `Big.DP` and `Big.RM` stay untouched.
+ */
+export const DivBig = Big()
+DivBig.DP = 40
+
+/**
+ * As `DivBig`, but truncating, so a derived amount never rounds up past the
+ * exact quotient.
+ */
+export const TruncBig = Big()
+TruncBig.DP = 40
+TruncBig.RM = Big.roundDown
+
+/** True when every value is a finite number, so `new DivBig(value)` cannot throw. */
+export function areFinite(...values: number[]): boolean {
+  return values.every(Number.isFinite)
+}