@lifi/perps-sdk 28.0.0 → 29.0.0

package/src/decimal/format.ts

@@ -1,6 +1,17 @@
 import type { DecimalString } from '@lifi/perps-types'
 import Big from 'big.js'
-import { decimalStringToBig } from './decimalStringToBig.js'
+import {
+  absDecimalString,
+  divideDecimalStringRoundDown,
+  multiplyDecimalString,
+} from './arithmetic.js'
+import { compareDecimalStrings } from './compare.js'
+import {
+  type DecimalRounding,
+  numberToDecimalString,
+  roundDecimalString,
+} from './convert.js'
+import { bigToDecimalString, decimalStringToBig } from './decimalStringToBig.js'
 
 /**
  * Options shared by the human-facing display formatters.
@@ -26,6 +37,21 @@ export interface FormatOptions {
   rounding?: RoundingMode
 }
 
+/**
+ * Options for {@link formatCompactUsd}.
+ *
+ * @public
+ */
+export interface CompactUsdOptions extends FormatOptions {
+  /**
+   * Significant digits of the compact mantissa, with trailing zeros dropped
+   * (`$84.5K`, `$1M`). Replaces `decimals` when set.
+   */
+  significantDigits?: number
+  /** Magnitudes below this value render as {@link formatUsd}, with no suffix. */
+  compactFrom?: DecimalString
+}
+
 /**
  * Rounding mode for {@link FormatOptions.rounding}.
  *
@@ -275,20 +301,76 @@ export function formatPrice(
   return `${sign}$${body}`
 }
 
+const COMPACT_TIER_SIZE = 1_000
+
+const COMPACT_TIERS = [
+  [1_000, 'K'],
+  [1_000_000, 'M'],
+] as const
+
+const COMPACT_DECIMAL_ROUNDING: Record<RoundingMode, DecimalRounding> = {
+  halfUp: 'round',
+  floor: 'truncate',
+}
+
+/** Significant digits span the whole number: one digit truncates `84.559` to `80`. */
+function roundToSignificantDigits(
+  value: string,
+  significantDigits: number,
+  rounding: DecimalRounding
+): string {
+  const integerPart = roundDecimalString(absDecimalString(value), 0, 'truncate')
+  const integerDigits = integerPart === '0' ? 0 : integerPart.length
+  const decimals = significantDigits - integerDigits
+  if (decimals >= 0) {
+    return roundDecimalString(value, decimals, rounding)
+  }
+  const scale = `1${'0'.repeat(-decimals)}`
+  return multiplyDecimalString(
+    roundDecimalString(divideDecimalStringRoundDown(value, scale), 0, rounding),
+    scale
+  )
+}
+
+function compactMantissa(
+  value: string,
+  divisor: number,
+  decimals: number,
+  significantDigits: number | undefined,
+  rounding: DecimalRounding
+): string {
+  const scaled = divideDecimalStringRoundDown(
+    value,
+    numberToDecimalString(divisor)
+  )
+  return significantDigits === undefined
+    ? roundDecimalString(scaled, decimals, rounding)
+    : roundToSignificantDigits(scaled, significantDigits, rounding)
+}
+
 /**
  * Format a USD value compactly with a `B`/`M`/`K` suffix: `$1.23B`, `$45.6M`,
  * `$789.0K`, `$12.34`.
  *
- * Negatives place the `-` before the `$`. Null/undefined/non-finite input
+ * Values below 1000 (or `compactFrom`) render as {@link formatUsd}. Negatives
+ * place the `-` before the `$`. `rounding: 'floor'` truncates toward zero, so
+ * a compact balance is never overstated. Null/undefined/non-finite input
  * renders the placeholder.
  *
  * @public
  */
 export function formatCompactUsd(
   value: FormatInput,
-  options: FormatOptions = {}
+  options: CompactUsdOptions = {}
 ): string {
-  const { decimals = 2, placeholder = DEFAULT_PLACEHOLDER } = options
+  const {
+    decimals = 2,
+    placeholder = DEFAULT_PLACEHOLDER,
+    locale,
+    rounding = 'halfUp',
+    significantDigits,
+    compactFrom,
+  } = options
   const n = toBig(value)
   if (n === null) {
     return placeholder
@@ -296,16 +378,48 @@ export function formatCompactUsd(
   if (typeof n === 'string') {
     return n
   }
-  const sign = n.lt(0) ? '-' : ''
-  const abs = n.abs()
-  if (abs.gte(1_000_000_000)) {
-    return `${sign}$${abs.div(1_000_000_000).toFixed(decimals)}B`
+  const decimal = bigToDecimalString(n)
+  const abs = absDecimalString(decimal)
+  if (
+    compareDecimalStrings(abs, numberToDecimalString(COMPACT_TIER_SIZE)) < 0 ||
+    (compactFrom !== undefined && compareDecimalStrings(abs, compactFrom) < 0)
+  ) {
+    return formatUsd(value, options)
   }
-  if (abs.gte(1_000_000)) {
-    return `${sign}$${abs.div(1_000_000).toFixed(decimals)}M`
+  const decimalRounding = COMPACT_DECIMAL_ROUNDING[rounding]
+  const render = (mantissa: string, suffix: string): string => {
+    const mantissaDecimals =
+      significantDigits === undefined
+        ? decimals
+        : (mantissa.split('.')[1]?.length ?? 0)
+    return `${formatUsd(mantissa, { locale, decimals: mantissaDecimals })}${suffix}`
   }
-  if (abs.gte(1_000)) {
-    return `${sign}$${abs.div(1_000).toFixed(decimals)}K`
+  // The tier is picked after rounding, so 999,999.99 promotes to M, not 1000K.
+  for (const [divisor, suffix] of COMPACT_TIERS) {
+    const mantissa = compactMantissa(
+      decimal,
+      divisor,
+      decimals,
+      significantDigits,
+      decimalRounding
+    )
+    if (
+      compareDecimalStrings(
+        absDecimalString(mantissa),
+        numberToDecimalString(COMPACT_TIER_SIZE)
+      ) < 0
+    ) {
+      return render(mantissa, suffix)
+    }
   }
-  return `${sign}$${abs.toFixed(decimals)}`
+  return render(
+    compactMantissa(
+      decimal,
+      1_000_000_000,
+      decimals,
+      significantDigits,
+      decimalRounding
+    ),
+    'B'
+  )
 }

package/src/index.ts

@@ -52,7 +52,11 @@ export {
   safeScaledIntegerToDecimalString,
   scaledIntegerToDecimalString,
 } from './decimal/convert.js'
-export type { FormatOptions, RoundingMode } from './decimal/format.js'
+export type {
+  CompactUsdOptions,
+  FormatOptions,
+  RoundingMode,
+} from './decimal/format.js'
 export {
   formatCompactUsd,
   formatNumber,
@@ -259,9 +263,9 @@ export type {
 export type {
   DeclaredDepositAsset,
   DepositFlow,
-  DepositFlowFirstDepositPipeline,
   DepositFlowLifiSwap,
   DepositFlowSetupRequired,
+  DepositFlowVenueDepositPipeline,
 } from './types/deposit.js'
 export type {
   ActionSignerContribution,

package/src/math/position.ts

@@ -15,6 +15,7 @@ import {
   type PerpsMarket,
   type Position,
   PositionMarginAdjustment,
+  PositionSide,
 } from '@lifi/perps-types'
 import { DivBig } from '../decimal/big.js'
 import {
@@ -174,16 +175,27 @@ export const safeCalculateEffectiveLeverage = createSafeFunction(
  *   margin_available = entryPrice × (1 / leverage - mmr)
  *   liq_price        = entryPrice - side × margin_available / (1 - mmr × side)
  *
+ * With `current`, the order of `size` adds to that position on the same side.
+ * The equity of the blended position at `entryPrice` is `current.margin`, the
+ * PnL of `current` at `entryPrice`, and the margin of the order. The margin
+ * available is that equity minus the maintenance margin of the blended size,
+ * and the formula above divides it by the blended size.
+ *
  * For existing positions, prefer `Position.liquidationPrice` from the venue.
  *
  * @param maintenanceMarginRate - Venue maintenance margin rate as a fraction
  *   (`'0.01'` = 1%).
- * @returns The estimate, or `undefined` when `1 / leverage` is at or below
- *   `maintenanceMarginRate`: the position opens at or past liquidation, so
- *   the model has no price on the correct side of entry.
+ * @param size - Order size as a non-negative magnitude. Read only with
+ *   `current`.
+ * @param current - Open isolated position on the same side that the order
+ *   adds to. `margin` is its collateral net of unrealized PnL.
+ * @returns The estimate, or `undefined` when the margin above the
+ *   maintenance requirement is not positive: the position opens at or past
+ *   liquidation, so the model has no price on the correct side of entry.
  * @throws {PerpsError} `ValidationError` when an input does not match the
- *   decimal pattern, `leverage` is zero, or `maintenanceMarginRate` gives a
- *   zero denominator (`1` for a long, `-1` for a short).
+ *   decimal pattern, `leverage` is zero, `maintenanceMarginRate` gives a
+ *   zero denominator (`1` for a long, `-1` for a short), `current` comes
+ *   without `size`, or `current.size + size` is not positive.
  * @public
  */
 export function estimateLiquidationPrice(params: {
@@ -191,6 +203,8 @@ export function estimateLiquidationPrice(params: {
   leverage: string
   isLong: boolean
   maintenanceMarginRate: string
+  size?: string
+  current?: { size: string; entryPrice: string; margin: string }
 }): string | undefined {
   const entryPrice = decimalStringToBig(params.entryPrice)
   const leverage = decimalStringToBig(params.leverage)
@@ -206,13 +220,38 @@ export function estimateLiquidationPrice(params: {
       `must not be ${params.isLong ? '1' : '-1'} for this side`
     )
   }
-  const marginFractionAvailable = new DivBig(1).div(leverage).minus(mmr)
-  if (marginFractionAvailable.lte(0)) {
+  if (params.current === undefined) {
+    const marginFractionAvailable = new DivBig(1).div(leverage).minus(mmr)
+    if (marginFractionAvailable.lte(0)) {
+      return undefined
+    }
+    const marginAvailable = marginFractionAvailable.times(entryPrice)
+    return bigToDecimalString(
+      entryPrice.minus(marginAvailable.times(side).div(denominator))
+    )
+  }
+  if (params.size === undefined) {
+    throw invalidInput('size', 'is required with `current`')
+  }
+  const addSize = decimalStringToBig(params.size)
+  const currentSize = decimalStringToBig(params.current.size)
+  const currentEntry = decimalStringToBig(params.current.entryPrice)
+  const currentMargin = decimalStringToBig(params.current.margin)
+  const totalSize = currentSize.plus(addSize)
+  if (totalSize.lte(0)) {
+    throw invalidInput('size + current.size', 'must be positive')
+  }
+  const equity = currentMargin
+    .plus(currentSize.times(entryPrice.minus(currentEntry)).times(side))
+    .plus(new DivBig(entryPrice).times(addSize).div(leverage))
+  const marginAvailablePerUnit = new DivBig(equity)
+    .minus(mmr.times(totalSize).times(entryPrice))
+    .div(totalSize)
+  if (marginAvailablePerUnit.lte(0)) {
     return undefined
   }
-  const marginAvailable = marginFractionAvailable.times(entryPrice)
   return bigToDecimalString(
-    entryPrice.minus(marginAvailable.times(side).div(denominator))
+    entryPrice.minus(marginAvailablePerUnit.times(side).div(denominator))
   )
 }
 
@@ -223,12 +262,16 @@ export const safeEstimateLiquidationPrice = createSafeFunction(
 )
 
 /**
- * Estimate the liquidation price of a new isolated position from the flat
- * `market.maintenanceMarginRate`.
+ * Estimate the liquidation price of the isolated position that an order
+ * leaves, from the flat `market.maintenanceMarginRate`: a new position, or
+ * the blend of the order into `params.position`. The collateral of the
+ * position is `position.marginUsed`, so the venue `marginUsed` must exclude
+ * the unrealized PnL, as Lighter `allocated_margin` does.
  *
  * @returns The estimate, or `undefined` when the market carries no
- *   `maintenanceMarginRate` or {@link estimateLiquidationPrice} gives
- *   `undefined`.
+ *   `maintenanceMarginRate`, when the order or the position is cross (the
+ *   liquidation depends on the whole account), when the order reduces the
+ *   position, or when {@link estimateLiquidationPrice} gives `undefined`.
  * @throws {PerpsError} `ValidationError` on an input that
  *   {@link estimateLiquidationPrice} rejects.
  * @public
@@ -237,7 +280,14 @@ export function estimateLiquidationPriceAtMarketRate(
   market: PerpsMarket,
   params: LiquidationEstimateParams
 ): string | undefined {
-  if (market.maintenanceMarginRate === undefined) {
+  const { position } = params
+  if (
+    market.maintenanceMarginRate === undefined ||
+    params.marginMode === MarginMode.CROSS ||
+    position?.marginMode === MarginMode.CROSS ||
+    (position !== undefined &&
+      (position.side === PositionSide.LONG) !== params.isLong)
+  ) {
     return undefined
   }
   return estimateLiquidationPrice({
@@ -245,6 +295,16 @@ export function estimateLiquidationPriceAtMarketRate(
     leverage: params.leverage,
     isLong: params.isLong,
     maintenanceMarginRate: market.maintenanceMarginRate,
+    size: params.size,
+    ...(position === undefined
+      ? {}
+      : {
+          current: {
+            size: position.size,
+            entryPrice: position.entryPrice,
+            margin: position.marginUsed,
+          },
+        }),
   })
 }
 

package/src/services/getGasRecommendation.ts

@@ -17,13 +17,13 @@ export const LIFI_API_URL = 'https://li.quest/v1'
  * @public
  */
 export interface GetGasRecommendationParams {
-  /** Chain to hold native gas on — a `firstDepositPipeline` flow's `chainId`. */
+  /** Chain to hold native gas on — a `venueDepositPipeline` flow's `chainId`. */
   chainId: number
 }
 
 /**
  * How much native gas LI.FI suggests holding on `params.chainId` to transact
- * there, for seeding the gas leg of a first-deposit pipeline. Read straight
+ * there, for seeding the gas leg of a venue-deposit pipeline. Read straight
  * from the LI.FI API by the user's client.
  *
  * @returns The suggestion, with `available: false` and no amounts on a chain

package/src/types/deposit.ts

@@ -37,20 +37,21 @@ export interface DepositFlowLifiSwap {
 }
 
 /**
- * Fund an address that has no venue account yet. Collateral and the native gas
- * to broadcast with are both needed on `chainId`, where the venue's
- * {@link ActionType.DEPOSIT} action stages the on-chain legs that open the
- * account.
+ * Fund an address that has no venue account yet, or an existing account on a
+ * venue whose collateral no LI.FI route credits directly. Collateral and the
+ * native gas to broadcast with are both needed on `chainId`, where the venue's
+ * {@link ActionType.DEPOSIT} action stages the on-chain legs that credit the
+ * account and open it when none exists.
  *
  * @public
  */
-export interface DepositFlowFirstDepositPipeline {
-  kind: 'firstDepositPipeline'
+export interface DepositFlowVenueDepositPipeline {
+  kind: 'venueDepositPipeline'
   /** Chain on which the deposit legs broadcast; the wallet must be switched here. */
   chainId: number
   /** Native gas asset needed to broadcast the deposit legs. */
   gasAsset: DeclaredDepositAsset
-  /** Collateral asset credited by the first deposit. */
+  /** Collateral asset the venue deposit credits. */
   collateral: DeclaredDepositAsset
   /** Action type used to stage the deposit pipeline. */
   bridgeAction: ActionType.DEPOSIT
@@ -77,5 +78,5 @@ export interface DepositFlowSetupRequired {
  */
 export type DepositFlow =
   | DepositFlowLifiSwap
-  | DepositFlowFirstDepositPipeline
+  | DepositFlowVenueDepositPipeline
   | DepositFlowSetupRequired

package/src/types/provider.ts

@@ -11,6 +11,7 @@ import type {
   AvailableToTrade,
   DecimalString,
   FillsResponse,
+  MarginMode,
   Market,
   MarketRef,
   MarketSettings,
@@ -160,7 +161,8 @@ export interface ActionSignerContribution {
 }
 
 /**
- * Inputs for {@link PerpsProviderPlugin.estimateLiquidationPrice}:
+ * Inputs for {@link PerpsProviderPlugin.estimateLiquidationPrice}: the order
+ * and, when the order adds to one, the open position on the market.
  * `leverage` is the user-selected leverage for the new position, `isLong`
  * carries direction.
  *
@@ -172,6 +174,14 @@ export interface LiquidationEstimateParams {
   leverage: string
   /** `true` for long, `false` for short. */
   isLong: boolean
+  marginMode: MarginMode
+  /**
+   * Order size in base-asset units. The estimate reads it only with
+   * `position`, to blend the order into that position.
+   */
+  size?: DecimalString
+  /** Open position on the market that the order joins. */
+  position?: Position
 }
 
 /**
@@ -633,16 +643,20 @@ export interface PerpsProviderPlugin {
   }
 
   /**
-   * Estimate the liquidation price of a new isolated position on `market`
-   * using the venue's margin model. A preview helper — for existing
+   * Estimate the liquidation price of the position that the order leaves on
+   * `market` using the venue's margin model: a new position, or the blend of
+   * the order into `params.position`. A preview helper — for existing
    * positions, prefer `Position.liquidationPrice` from the venue. Pure —
    * does no I/O.
    *
    * @returns The estimated liquidation price, or `undefined` when `market`
-   *   lacks the margin metadata the model needs or `leverage` leaves no
-   *   margin above the maintenance requirement.
+   *   lacks the margin metadata the model needs, `leverage` leaves no
+   *   margin above the maintenance requirement, or the venue model cannot
+   *   give a correct price for the margin mode and position, such as a cross
+   *   position whose liquidation depends on the whole account.
    * @throws {PerpsError} `ValidationError` when an input does not match the
-   *   decimal pattern or is degenerate, such as a zero leverage.
+   *   decimal pattern or is degenerate, such as a zero leverage or a
+   *   `position` without a `size`.
    */
   estimateLiquidationPrice(
     market: PerpsMarket,

package/src/utils/depositAssets.ts

@@ -3,7 +3,7 @@ import { zeroAddress } from 'viem'
 import type { DeclaredDepositAsset } from '../types/deposit.js'
 
 /**
- * USDC on Ethereum mainnet — the collateral leg of Lighter's first-deposit
+ * USDC on Ethereum mainnet — the collateral leg of Lighter's venue-deposit
  * pipeline, and the token Ondo's provisioned deposit address is funded in.
  *
  * @public
@@ -15,7 +15,7 @@ export const ETHEREUM_USDC: DeclaredDepositAsset = {
 }
 
 /**
- * Ether on Ethereum mainnet, to broadcast the first-deposit pipeline's legs
+ * Ether on Ethereum mainnet, to broadcast the venue-deposit pipeline's legs
  * with.
  *
  * @public
@@ -65,7 +65,7 @@ export const ROBINHOOD_USDG: DeclaredDepositAsset = {
 }
 
 /**
- * Ether on Robinhood Chain, to broadcast the Robinhood first-deposit pipeline's
+ * Ether on Robinhood Chain, to broadcast the Robinhood venue-deposit pipeline's
  * legs with.
  *
  * @public

package/src/version.ts

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