@lifi/perps-sdk 28.1.0 → 29.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk",
-  "version": "28.1.0",
+  "version": "29.0.0",
   "description": "LI.FI Perps SDK for perpetuals trading",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -46,7 +46,7 @@
     "big.js": "^7.0.1",
     "partysocket": "^1.1.19",
     "viem": "^2.55.18",
-    "@lifi/perps-types": "^25.0.1"
+    "@lifi/perps-types": "^26.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -263,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.1.0'
+export const version = '29.0.0'