@lifi/perps-sdk 0.0.0-preview-abcdac5a → 0.0.0-preview-1e136edd

package/src/math/position.ts

@@ -15,13 +15,21 @@ import {
   type PerpsMarket,
   type Position,
   PositionMarginAdjustment,
+  PositionSide,
 } from '@lifi/perps-types'
+import {
+  absDecimalString,
+  divideDecimalString,
+  multiplyDecimalString,
+} from '../decimal/arithmetic.js'
 import { DivBig } from '../decimal/big.js'
+import { isDecimalStringGreaterThan } from '../decimal/compare.js'
 import {
   bigToDecimalString,
   decimalStringToBig,
   decimalStringToDivBig,
 } from '../decimal/decimalStringToBig.js'
+import { isDecimalString } from '../decimal/parse.js'
 import { invalidInput } from '../errors/invalidInput.js'
 import type { LiquidationEstimateParams } from '../types/provider.js'
 import { createSafeFunction } from '../utils/createSafeFunction.js'
@@ -88,6 +96,52 @@ export function calculateRoe(pnl: string, margin: string): string {
 /** @public */
 export const safeCalculateRoe = createSafeFunction('calculateRoe', calculateRoe)
 
+/**
+ * Calculate ROE as `pnl × leverage ÷ (|size| × entryPrice) × 100`.
+ * @throws {PerpsError} `ValidationError` for malformed inputs, zero `size`,
+ *   or non-positive `entryPrice` and `leverage`.
+ * @public
+ */
+export function calculateInitialMarginRoe(
+  pnl: string,
+  size: string,
+  entryPrice: string,
+  leverage: string
+): string {
+  for (const [parameter, value] of [
+    ['pnl', pnl],
+    ['size', size],
+    ['entryPrice', entryPrice],
+    ['leverage', leverage],
+  ] as const) {
+    if (!isDecimalString(value)) {
+      throw invalidInput(parameter, 'must be a decimal string')
+    }
+  }
+  const absoluteSize = absDecimalString(size)
+  if (!isDecimalStringGreaterThan(absoluteSize, '0')) {
+    throw invalidInput('size', 'must not be zero')
+  }
+  if (!isDecimalStringGreaterThan(entryPrice, '0')) {
+    throw invalidInput('entryPrice', 'must be positive')
+  }
+  if (!isDecimalStringGreaterThan(leverage, '0')) {
+    throw invalidInput('leverage', 'must be positive')
+  }
+  const numerator = multiplyDecimalString(pnl, leverage)
+  const denominator = multiplyDecimalString(absoluteSize, entryPrice)
+  return multiplyDecimalString(
+    divideDecimalString(numerator, denominator),
+    '100'
+  )
+}
+
+/** @public */
+export const safeCalculateInitialMarginRoe = createSafeFunction(
+  'calculateInitialMarginRoe',
+  calculateInitialMarginRoe
+)
+
 /**
  * Required margin: `notionalValue ÷ leverage`.
  *
@@ -174,16 +228,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 +256,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 +273,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,28 +315,93 @@ 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: a new position, or the blend of the order into `params.position`.
+ * The venue callbacks run only after the margin-mode and side checks pass.
  *
- * @returns The estimate, or `undefined` when the market carries no
- *   `maintenanceMarginRate` or {@link estimateLiquidationPrice} gives
+ * @param venue.maintenanceMarginRate - Venue maintenance margin rate as a
+ *   fraction (`'0.01'` = 1%).
+ * @param venue.positionCollateral - Collateral of `position`, net of
+ *   unrealized PnL. It depends on the venue meaning of `Position.marginUsed`.
+ * @returns The estimate, or `undefined` 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
+ * @throws {PerpsError} `ValidationError` when `params.position` comes
+ *   without `params.size`, or on an input that
  *   {@link estimateLiquidationPrice} rejects.
  * @public
  */
-export function estimateLiquidationPriceAtMarketRate(
-  market: PerpsMarket,
-  params: LiquidationEstimateParams
+export function estimateOrderLiquidationPrice(
+  params: LiquidationEstimateParams,
+  venue: {
+    maintenanceMarginRate: () => string
+    positionCollateral: (position: Position) => string
+  }
 ): string | undefined {
-  if (market.maintenanceMarginRate === undefined) {
+  const { position } = params
+  if (
+    params.marginMode === MarginMode.CROSS ||
+    position?.marginMode === MarginMode.CROSS ||
+    (position !== undefined &&
+      (position.side === PositionSide.LONG) !== params.isLong)
+  ) {
     return undefined
   }
+  const maintenanceMarginRate = venue.maintenanceMarginRate()
+  if (position === undefined) {
+    return estimateLiquidationPrice({
+      entryPrice: params.entryPrice,
+      leverage: params.leverage,
+      isLong: params.isLong,
+      maintenanceMarginRate,
+      size: params.size,
+    })
+  }
+  const margin = venue.positionCollateral(position)
+  if (params.size === undefined) {
+    throw invalidInput('size', 'is required with `position`')
+  }
   return estimateLiquidationPrice({
     entryPrice: params.entryPrice,
     leverage: params.leverage,
     isLong: params.isLong,
-    maintenanceMarginRate: market.maintenanceMarginRate,
+    maintenanceMarginRate,
+    size: params.size,
+    current: { size: position.size, entryPrice: position.entryPrice, margin },
+  })
+}
+
+/** @public */
+export const safeEstimateOrderLiquidationPrice = createSafeFunction(
+  'estimateOrderLiquidationPrice',
+  estimateOrderLiquidationPrice
+)
+
+/**
+ * Estimate the liquidation price of the isolated position that an order
+ * leaves, from the flat `market.maintenanceMarginRate`. 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 as {@link estimateOrderLiquidationPrice}
+ *   documents.
+ * @throws {PerpsError} `ValidationError` as {@link estimateOrderLiquidationPrice}
+ *   documents.
+ * @public
+ */
+export function estimateLiquidationPriceAtMarketRate(
+  market: PerpsMarket,
+  params: LiquidationEstimateParams
+): string | undefined {
+  const { maintenanceMarginRate } = market
+  if (maintenanceMarginRate === undefined) {
+    return undefined
+  }
+  return estimateOrderLiquidationPrice(params, {
+    maintenanceMarginRate: () => maintenanceMarginRate,
+    positionCollateral: (position) => 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 = '0.0.0-preview-abcdac5a'
+export const version = '0.0.0-preview-1e136edd'