@lifi/perps-sdk 23.1.0 → 25.0.0

package/src/client/PerpsClient.ts

@@ -30,8 +30,9 @@ import {
   PerpsSigner,
   SigningMethod,
 } from '@lifi/perps-types'
-import Big from 'big.js'
 import type { Address } from 'viem'
+import { isDecimalStringGreaterThan } from '../decimal/compare.js'
+import { unknownToDecimalString } from '../decimal/parse.js'
 import { PerpsError } from '../errors/PerpsError.js'
 import { getAssetRegistry, toAssetDisplay } from '../registry/assetRegistry.js'
 import { getMarketRegistry } from '../registry/marketRegistry.js'
@@ -60,6 +61,7 @@ import type {
   GetPortfolioHistoryParams,
   GetSetupParams,
   GetWithdrawableBalancesParams,
+  GetWithdrawalTypesParams,
   GetWithdrawFlowParams,
   ModifyOrdersParams,
   PerpsClientOptions,
@@ -85,7 +87,11 @@ import type {
   SignActionProgress,
   SignActionsContext,
 } from '../types/provider.js'
-import type { WithdrawableBalance, WithdrawFlow } from '../types/withdrawal.js'
+import type {
+  WithdrawableBalance,
+  WithdrawalSourceTypes,
+  WithdrawFlow,
+} from '../types/withdrawal.js'
 import { isUserFacingSetupStep } from '../utils/setupActions.js'
 import { signTypedDataWithSigner } from '../utils/signTypedData.js'
 import {
@@ -219,7 +225,10 @@ function assertAllSucceeded(results: ActionResult[]): void {
 
 function isNonNegativeDecimal(value: string): boolean {
   try {
-    return new Big(value).gte(0)
+    return !isDecimalStringGreaterThan(
+      '0',
+      unknownToDecimalString(value, 'withdrawalFee', 'perps-sdk')
+    )
   } catch {
     return false
   }
@@ -838,8 +847,9 @@ export class PerpsClient {
   }
 
   /**
-   * The `(asset, route)` selections `params.address` can actually withdraw at
-   * `params.provider`. The venue owns how its balances split across routes;
+   * The `(asset, category)` selections `params.address` can actually withdraw
+   * at `params.provider`. The venue owns how its balances split across
+   * categories;
    * this join adds the core `/assets` metadata — precision, L1 identity and
    * the per-asset minimum — and drops every row the minimum rules out, plus
    * any row whose asset the provider's registry does not carry, since without
@@ -878,22 +888,31 @@ export class PerpsClient {
       }
       const minimum = asset.minWithdrawalAmount
       if (minimum !== undefined) {
-        let floor: Big
+        let floor: string
         try {
-          floor = new Big(minimum)
+          floor = unknownToDecimalString(
+            minimum,
+            'minWithdrawalAmount',
+            'perps-sdk'
+          )
         } catch {
           throw new PerpsError(
             PerpsErrorCode.SDKError,
             `Asset '${asset.id}' field \`minWithdrawalAmount\` is not a valid decimal.`
           )
         }
-        if (new Big(row.available).lt(floor)) {
+        if (isDecimalStringGreaterThan(floor, row.available)) {
           return []
         }
       }
       if (row.withdrawalFee === undefined) {
         return [
-          { asset, route: row.route, available: row.available, max: row.max },
+          {
+            asset,
+            categoryId: row.categoryId,
+            available: row.available,
+            max: row.max,
+          },
         ]
       }
       if (!isNonNegativeDecimal(row.withdrawalFee)) {
@@ -905,7 +924,7 @@ export class PerpsClient {
       return [
         {
           asset,
-          route: row.route,
+          categoryId: row.categoryId,
           available: row.available,
           max: row.max,
           withdrawalFee: row.withdrawalFee,
@@ -917,6 +936,25 @@ export class PerpsClient {
     })
   }
 
+  /**
+   * The withdrawal types `params.address` can choose per holding at
+   * `params.provider`, each with its cap and the `withdrawalOptions` to pass
+   * unchanged in `WithdrawalParams`.
+   *
+   * @returns `undefined` when the registered plugin declares no withdrawal
+   *   types read.
+   * @throws {PerpsError} When the provider plugin is not registered, or when
+   *   the plugin read fails.
+   * @public
+   */
+  async getWithdrawalTypes(
+    params: GetWithdrawalTypesParams,
+    options?: SDKRequestOptions
+  ): Promise<WithdrawalSourceTypes[] | undefined> {
+    const plugin = this.requireProvider(params.provider)
+    return plugin.getWithdrawalTypes?.({ address: params.address }, options)
+  }
+
   /**
    * The account's portfolio value and cumulative PnL over `params.range` at
    * `params.provider`, read directly from the venue.

package/src/decimal/arithmetic.ts

@@ -0,0 +1,170 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+import type Big from 'big.js'
+import { PerpsError } from '../errors/PerpsError.js'
+import { createSafeFunction } from '../utils/createSafeFunction.js'
+import { DivBig, TruncBig } from './big.js'
+import { bigToDecimalString, decimalStringToBig } from './decimalStringToBig.js'
+
+/**
+ * Exact `a + b`.
+ *
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
+ * @public
+ */
+export function addDecimalString(a: string, b: string): string {
+  return bigToDecimalString(decimalStringToBig(a).plus(decimalStringToBig(b)))
+}
+
+/**
+ * {@link addDecimalString}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export const safeAddDecimalString = createSafeFunction(
+  'addDecimalString',
+  addDecimalString
+)
+
+/**
+ * Exact sum of every value; `'0'` for an empty list.
+ *
+ * @throws {PerpsError} `ValidationError` when a value does not match the
+ *   decimal pattern.
+ * @public
+ */
+export function addDecimalStrings(values: readonly string[]): string {
+  return bigToDecimalString(
+    values.reduce<Big>(
+      (sum, value) => sum.plus(decimalStringToBig(value)),
+      decimalStringToBig('0')
+    )
+  )
+}
+
+/**
+ * {@link addDecimalStrings}, or `undefined` with a warning when it throws.
+ * One bad value gives `undefined`, never a partial sum.
+ *
+ * @public
+ */
+export const safeAddDecimalStrings = createSafeFunction(
+  'addDecimalStrings',
+  addDecimalStrings
+)
+
+/**
+ * Exact `a - b`.
+ *
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
+ * @public
+ */
+export function subtractDecimalString(a: string, b: string): string {
+  return bigToDecimalString(decimalStringToBig(a).minus(decimalStringToBig(b)))
+}
+
+/**
+ * {@link subtractDecimalString}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export const safeSubtractDecimalString = createSafeFunction(
+  'subtractDecimalString',
+  subtractDecimalString
+)
+
+/**
+ * Exact `a × b`.
+ *
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
+ * @public
+ */
+export function multiplyDecimalString(a: string, b: string): string {
+  return bigToDecimalString(decimalStringToBig(a).times(decimalStringToBig(b)))
+}
+
+/**
+ * {@link multiplyDecimalString}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export const safeMultiplyDecimalString = createSafeFunction(
+  'multiplyDecimalString',
+  multiplyDecimalString
+)
+
+function requireNonZeroDivisor(divisor: string): Big {
+  const parsed = decimalStringToBig(divisor)
+  if (parsed.eq(0)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Division by zero: divisor '${divisor}'.`
+    )
+  }
+  return parsed
+}
+
+/**
+ * `a ÷ b` to 40 decimal places, rounded half up.
+ *
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `b` is zero.
+ * @public
+ */
+export function divideDecimalString(a: string, b: string): string {
+  const divisor = requireNonZeroDivisor(b)
+  return bigToDecimalString(new DivBig(decimalStringToBig(a)).div(divisor))
+}
+
+/**
+ * {@link divideDecimalString}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export const safeDivideDecimalString = createSafeFunction(
+  'divideDecimalString',
+  divideDecimalString
+)
+
+/**
+ * `a ÷ b` to 40 decimal places, truncated toward zero, so a derived amount
+ * never exceeds the exact quotient.
+ *
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `b` is zero.
+ * @public
+ */
+export function divideDecimalStringRoundDown(a: string, b: string): string {
+  const divisor = requireNonZeroDivisor(b)
+  return bigToDecimalString(new TruncBig(decimalStringToBig(a)).div(divisor))
+}
+
+/**
+ * {@link divideDecimalStringRoundDown}, or `undefined` with a warning when it
+ * throws.
+ *
+ * @public
+ */
+export const safeDivideDecimalStringRoundDown = createSafeFunction(
+  'divideDecimalStringRoundDown',
+  divideDecimalStringRoundDown
+)
+
+/**
+ * Exact `|value|`.
+ *
+ * @throws {PerpsError} `ValidationError` when `value` does not match the decimal pattern.
+ * @public
+ */
+export function absDecimalString(value: string): string {
+  return bigToDecimalString(decimalStringToBig(value).abs())
+}
+
+/**
+ * {@link absDecimalString}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export const safeAbsDecimalString = createSafeFunction(
+  'absDecimalString',
+  absDecimalString
+)

package/src/decimal/big.ts

@@ -14,8 +14,3 @@ DivBig.DP = 40
 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)
-}

package/src/decimal/compare.ts

@@ -1,17 +1,67 @@
-import type { DecimalString } from '@lifi/perps-types'
-import { requireDecimal } from './requireDecimal.js'
+import { createSafeFunction } from '../utils/createSafeFunction.js'
+import { decimalStringToBig } from './decimalStringToBig.js'
 
 /**
- * Exact `a > b` on two {@link DecimalString}s, with no float rounding, so a
- * funds gate can tell `'1.0000000000000001'` from `'1'`. The other relations
- * follow from it: `a <= b` is `!isDecimalStringGreaterThan(a, b)`.
+ * Exact `a > b` on two decimal strings, with no float rounding, so a funds
+ * gate can tell `'1.0000000000000001'` from `'1'`. The other relations follow
+ * from it: `a <= b` is `!isDecimalStringGreaterThan(a, b)`.
  *
- * @throws {PerpsError} `ValidationError` when either operand is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when either operand does not match the decimal pattern.
  * @public
  */
-export function isDecimalStringGreaterThan(
-  a: DecimalString,
-  b: DecimalString
-): boolean {
-  return requireDecimal(a, 'a').gt(requireDecimal(b, 'b'))
+export function isDecimalStringGreaterThan(a: string, b: string): boolean {
+  return decimalStringToBig(a).gt(decimalStringToBig(b))
 }
+
+/**
+ * {@link isDecimalStringGreaterThan}, or `undefined` with a warning when it
+ * throws.
+ *
+ * @public
+ */
+export const safeIsDecimalStringGreaterThan = createSafeFunction(
+  'isDecimalStringGreaterThan',
+  isDecimalStringGreaterThan
+)
+
+/**
+ * Exact `value == 0`, so a flat-position check never reads `'0.0'` as
+ * non-zero.
+ *
+ * @throws {PerpsError} `ValidationError` when `value` does not match the decimal pattern.
+ * @public
+ */
+export function isDecimalStringZero(value: string): boolean {
+  return decimalStringToBig(value).eq(0)
+}
+
+/**
+ * {@link isDecimalStringZero}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export const safeIsDecimalStringZero = createSafeFunction(
+  'isDecimalStringZero',
+  isDecimalStringZero
+)
+
+/**
+ * Exact three-way compare for a sort: `-1` when `a < b`, `0` when equal, `1`
+ * when `a > b`.
+ *
+ * @throws {PerpsError} `ValidationError` when either operand does not match the decimal pattern.
+ * @public
+ */
+export function compareDecimalStrings(a: string, b: string): -1 | 0 | 1 {
+  return decimalStringToBig(a).cmp(decimalStringToBig(b))
+}
+
+/**
+ * {@link compareDecimalStrings}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export const safeCompareDecimalStrings = createSafeFunction(
+  'compareDecimalStrings',
+  compareDecimalStrings
+)

package/src/decimal/convert.ts

@@ -1,44 +1,92 @@
-import { type DecimalString, PerpsErrorCode } from '@lifi/perps-types'
+import { PerpsErrorCode } from '@lifi/perps-types'
 import Big from 'big.js'
 import { formatUnits } from 'viem'
 import { PerpsError } from '../errors/PerpsError.js'
-import { requireDecimal } from './requireDecimal.js'
+import { createSafeFunction } from '../utils/createSafeFunction.js'
+import { bigToDecimalString, decimalStringToBig } from './decimalStringToBig.js'
+import { isDecimalString } from './parse.js'
 
 /**
- * Off-grid resolution for {@link decimalToBaseUnits}:
- * - `truncate` — toward zero, for sizes and collateral amounts. The wire
- *   value never exceeds the caller's intent.
- * - `round` — half away from zero, for prices, which snap to the nearest
- *   tick.
+ * Off-grid resolution for {@link roundDecimalString}:
+ * - `truncate`: toward zero, for sizes and collateral amounts. The result
+ *   never exceeds the caller's intent.
+ * - `round`: half away from zero, for prices, which snap to the nearest tick.
+ * - `up`: away from zero, for an amount that must cover a target.
  * @public
  */
-export type BaseUnitsRounding = 'truncate' | 'round'
+export type DecimalRounding = 'truncate' | 'round' | 'up'
+
+const BIG_ROUNDING = {
+  truncate: Big.roundDown,
+  round: Big.roundHalfUp,
+  up: Big.roundUp,
+} as const
 
 /**
- * Scale a decimal string to a scaled integer in exact decimal arithmetic — an
- * on-grid input maps to its exact scaled integer with no binary float
- * artifacts (`'0.29'` at 2 decimals is 29, never 28). Off-grid input resolves
- * per `rounding`; there is no silent default.
+ * Round a decimal string to `decimals` places with exact decimal arithmetic.
+ * The result has no trailing zeros: `roundDecimalString('1.50', 1, 'round')`
+ * is `'1.5'`.
  *
- * @throws {PerpsError} `ValidationError` when `value` is not a
- *   {@link DecimalString}, `decimals` is not a non-negative integer, or the scaled
- *   result's magnitude exceeds `Number.MAX_SAFE_INTEGER`.
+ * @throws {PerpsError} `ValidationError` when `value` does not match the decimal pattern,
+ *   or `decimals` is not a non-negative integer.
  * @public
  */
-export const decimalToBaseUnits = (
-  value: DecimalString,
+export function roundDecimalString(
+  value: string,
   decimals: number,
-  rounding: BaseUnitsRounding
-): number => {
+  rounding: DecimalRounding
+): string {
+  if (!Number.isInteger(decimals) || decimals < 0) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid decimals for rounding: ${decimals}`
+    )
+  }
+  return bigToDecimalString(
+    decimalStringToBig(value).round(decimals, BIG_ROUNDING[rounding])
+  )
+}
+
+/**
+ * {@link roundDecimalString}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export const safeRoundDecimalString = createSafeFunction(
+  'roundDecimalString',
+  roundDecimalString
+)
+
+/**
+ * Scale a decimal string to an integer at `decimals` places in exact decimal
+ * arithmetic: `'0.29'` at 2 decimals is 29, never 28. Off-grid input resolves
+ * per `rounding`. No `$`, `%` or `,` is removed first.
+ *
+ * @throws {PerpsError} `ValidationError` when `value` does not match the decimal pattern,
+ *   `decimals` is not a non-negative integer, or the result's magnitude
+ *   exceeds `Number.MAX_SAFE_INTEGER`.
+ * @public
+ */
+export function decimalStringToScaledInteger(
+  value: string,
+  decimals: number,
+  rounding: DecimalRounding
+): number {
+  if (!isDecimalString(value)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `'${value}' does not match the decimal pattern.`
+    )
+  }
   if (!Number.isInteger(decimals) || decimals < 0) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
       `Invalid decimals for integer scaling: ${decimals}`
     )
   }
-  const scaled = requireDecimal(value, 'decimalToBaseUnits(value)')
+  const scaled = new Big(value)
     .times(new Big(10).pow(decimals))
-    .round(0, rounding === 'truncate' ? Big.roundDown : Big.roundHalfUp)
+    .round(0, BIG_ROUNDING[rounding])
   if (scaled.abs().gt(Number.MAX_SAFE_INTEGER)) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
@@ -48,72 +96,56 @@ export const decimalToBaseUnits = (
   return scaled.toNumber()
 }
 
-const BASE_UNITS_PATTERN = /^-?\d+$/
+/**
+ * {@link decimalStringToScaledInteger}, or `undefined` with a warning when it
+ * throws.
+ *
+ * @public
+ */
+export const safeDecimalStringToScaledInteger = createSafeFunction(
+  'decimalStringToScaledInteger',
+  decimalStringToScaledInteger
+)
+
+export const BASE_UNITS_PATTERN = /^-?\d+$/
 
 /**
- * Convert a base-unit amount (integer string) to a decimal string.
+ * Convert a scaled integer string (a token amount in base units) to a decimal
+ * string: `scaledIntegerToDecimalString('1000000', 6)` is `'1'`.
  *
- * @param amount - Amount in base units (e.g. "1000000" for 1 USDC)
- * @param decimals - Token decimals (e.g. 6 for USDC)
  * @throws {PerpsError} `ValidationError` when `amount` is not an integer
  *   string, or `decimals` is not a non-negative integer.
- * @example
- * ```ts
- * baseUnitsToDecimal('1000000', 6) // '1'
- * ```
  * @public
  */
-export function baseUnitsToDecimal(
-  amount: DecimalString,
+export function scaledIntegerToDecimalString(
+  amount: string,
   decimals: number
-): DecimalString {
+): string {
   if (!Number.isInteger(decimals) || decimals < 0) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
-      `Invalid \`baseUnitsToDecimal(decimals)\`: ${decimals} is not a non-negative integer.`
+      `Invalid \`scaledIntegerToDecimalString(decimals)\`: ${decimals} is not a non-negative integer.`
     )
   }
   if (!BASE_UNITS_PATTERN.test(amount)) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
-      `Invalid \`baseUnitsToDecimal(amount)\`: '${amount}' is not an integer base-unit string.`
+      `Invalid \`scaledIntegerToDecimalString(amount)\`: '${amount}' is not an integer base-unit string.`
     )
   }
   return formatUnits(BigInt(amount), decimals)
 }
 
 /**
- * Round `value` down to `decimals` and pad the result to exactly that many
- * decimal places. The padding is the point: this seeds a fixed-decimal input,
- * where `'500.00'` and `'500'` are two renderings of one amount and the field
- * wants the first. For a canonical wire amount with no trailing zeros, read
- * the amount off `calculateOrderAmounts` or a provider snap instead.
- *
- * Exact decimal arithmetic throughout, so there is no 2^53 ceiling and no
- * float artifact: `'0.01'` at 18 decimals gives
- * `'0.010000000000000000'`, which `Number#toFixed` cannot.
+ * {@link scaledIntegerToDecimalString}, or `undefined` with a warning when it
+ * throws.
  *
- * @throws {PerpsError} `ValidationError` when `value` is not a
- *   {@link DecimalString}, or `decimals` is not a non-negative integer.
  * @public
  */
-export function truncateDecimal(
-  value: DecimalString,
-  decimals: number
-): DecimalString {
-  if (!Number.isInteger(decimals) || decimals < 0) {
-    throw new PerpsError(
-      PerpsErrorCode.ValidationError,
-      `Invalid decimals for truncation: ${decimals}`
-    )
-  }
-  const truncated = requireDecimal(value, 'truncateDecimal(value)').round(
-    decimals,
-    Big.roundDown
-  )
-  // big.js carries the sign through a round to zero; '-0.00' is not a spelling.
-  return (truncated.eq(0) ? new Big(0) : truncated).toFixed(decimals)
-}
+export const safeScaledIntegerToDecimalString = createSafeFunction(
+  'scaledIntegerToDecimalString',
+  scaledIntegerToDecimalString
+)
 
 /**
  * Spell a `number` as a {@link DecimalString} in plain notation: `1e-7`
@@ -125,7 +157,7 @@ export function truncateDecimal(
  * @throws {PerpsError} `ValidationError` when `value` is `NaN` or infinite.
  * @public
  */
-export function numberToDecimalString(value: number): DecimalString {
+export function numberToDecimalString(value: number): string {
   if (!Number.isFinite(value)) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
@@ -135,3 +167,13 @@ export function numberToDecimalString(value: number): DecimalString {
   const parsed = new Big(value)
   return (parsed.eq(0) ? new Big(0) : parsed).toFixed()
 }
+
+/**
+ * {@link numberToDecimalString}, or `undefined` with a warning when it throws.
+ *
+ * @public
+ */
+export const safeNumberToDecimalString = createSafeFunction(
+  'numberToDecimalString',
+  numberToDecimalString
+)

package/src/decimal/decimalStringToBig.ts

@@ -0,0 +1,42 @@
+import { DECIMAL_PATTERN, PerpsErrorCode } from '@lifi/perps-types'
+import Big from 'big.js'
+import { PerpsError } from '../errors/PerpsError.js'
+import { DivBig } from './big.js'
+
+/**
+ * Read a decimal string as a `Big`. The string must match `DECIMAL_PATTERN`,
+ * so `'$1,234.5'`, `'0.05%'` and the exponent form `'1e5'` are rejected.
+ *
+ * @throws {PerpsError} `ValidationError` when `value` does not match the
+ *   decimal pattern.
+ * @internal
+ */
+export function decimalStringToBig(value: string): Big {
+  if (typeof value !== 'string' || !DECIMAL_PATTERN.test(value)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `'${String(value)}' does not match the decimal pattern.`
+    )
+  }
+  return new Big(value)
+}
+
+/**
+ * Spell a `Big` as a canonical decimal string, with no exponent and no `-0`.
+ *
+ * @internal
+ */
+export function bigToDecimalString(value: Big): string {
+  return value.eq(0) ? '0' : value.toFixed()
+}
+
+/**
+ * {@link decimalStringToBig} as a `DivBig`, so a later `div` keeps 40 decimal
+ * places.
+ *
+ * @throws {PerpsError} `ValidationError` as {@link decimalStringToBig}.
+ * @internal
+ */
+export function decimalStringToDivBig(value: string): Big {
+  return new DivBig(decimalStringToBig(value))
+}