@lifi/perps-sdk 5.0.0 → 6.0.0

package/src/types/provider.ts

@@ -10,11 +10,14 @@ import type {
   ActivityType,
   FillsResponse,
   Market,
+  MarketRef,
+  MarketSettings,
   Order,
   OrdersResponse,
   PerpsMarket,
   PerpsSigner,
   Position,
+  PositionMarginConstraints,
   PositionsResponse,
   ProviderAction,
   Quote,
@@ -185,6 +188,18 @@ export interface ProviderGetPositionsParams {
   cursor?: string
 }
 
+/**
+ * Read params for {@link PerpsProviderPlugin.getMarketSettings}.
+ *
+ * @public
+ */
+export interface ProviderGetMarketSettingsParams {
+  address: Address
+  /** The market's `id` and `categoryId`; the category identifies spot
+   * markets, which carry no venue leverage state. */
+  market: MarketRef
+}
+
 /**
  * Read params for {@link PerpsProvider.getOrders}.
  *
@@ -350,6 +365,18 @@ export interface PerpsProviderPlugin {
     options?: SDKRequestOptions
   ): 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.
+   */
+  getMarketSettings?(
+    params: ProviderGetMarketSettingsParams,
+    options?: SDKRequestOptions
+  ): Promise<MarketSettings | undefined>
+
   getOrders(
     params: ProviderGetOrdersParams,
     options?: SDKRequestOptions
@@ -436,6 +463,18 @@ export interface PerpsProviderPlugin {
     params: LiquidationEstimateParams
   ): number | undefined
 
+  /**
+   * Exact venue-owned constraints for changing `position`'s dedicated margin.
+   * Pure — providers normalize raw venue quantities onto the position before
+   * returning these inputs.
+   *
+   * @returns `undefined` when this position has no individual margin
+   *   adjustment (for example a cross position or a cross-only venue).
+   */
+  positionMarginConstraints(
+    position: Position
+  ): PositionMarginConstraints | undefined
+
   /**
    * Project a typed {@link AccountConfig} against the provider's `setup`
    * + `options` descriptors into `AccountConfigSetting[]`. Used by

package/src/utils/calculations.ts

@@ -169,34 +169,6 @@ export function effectiveLeverage(params: {
   return positionValueUsd / marginUsd
 }
 
-/**
- * Margin that can be removed from a position while keeping its leverage at or
- * below the asset's maximum.
- *
- * The minimum margin to stay within `maxLeverage` is the required margin for
- * the position's notional (see {@link calculateRequiredMargin}); anything above
- * that is removable.
- *
- * @param marginUsed - Margin currently backing the position in USD
- * @param positionValueUsd - Position notional value in USD
- * @param maxLeverage - Maximum leverage allowed for the asset
- * @returns Removable margin in USD (never negative); falls back to the full
- *   `marginUsed` when `maxLeverage` is zero (no constraint available)
- * @public
- */
-export function removableMargin(params: {
-  marginUsed: number
-  positionValueUsd: number
-  maxLeverage: number
-}): number {
-  const { marginUsed, positionValueUsd, maxLeverage } = params
-  if (maxLeverage === 0) {
-    return marginUsed
-  }
-  const minMargin = calculateRequiredMargin(positionValueUsd, maxLeverage)
-  return Math.max(0, marginUsed - minMargin)
-}
-
 /**
  * Signed expected PnL for a trigger price — see {@link calculateExpectedPnl}.
  *

package/src/utils/transferMargin.ts

@@ -0,0 +1,103 @@
+import {
+  MarginMode,
+  PerpsErrorCode,
+  type Position,
+  PositionMarginAdjustment,
+  type PositionMarginConstraints,
+} from '@lifi/perps-types'
+import Big from 'big.js'
+import { PerpsError } from '../errors/PerpsError.js'
+
+function positionAmount(value: string, field: string): Big {
+  try {
+    return new Big(value)
+  } catch {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid decimal string on Position.${field}: '${value}'`
+    )
+  }
+}
+
+function constraintAmount(value: string, field: string): Big {
+  try {
+    return new Big(value)
+  } catch {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid decimal string on PositionMarginConstraints.${field}: '${value}'`
+    )
+  }
+}
+
+function requirePositive(value: Big, field: string): Big {
+  if (value.lte(0)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `${field} must be greater than zero.`
+    )
+  }
+  return value
+}
+
+/**
+ * Exact inputs for {@link removableIsolatedMargin}.
+ *
+ * @public
+ */
+export interface RemovableIsolatedMarginParams {
+  position: Position
+  constraints: PositionMarginConstraints
+}
+
+/**
+ * Calculate margin that can be removed from an isolated position using the
+ * provider's exact retained-margin requirement. Position equity is allocated
+ * margin plus unrealized PnL.
+ *
+ * The result snaps down to the provider's accepted amount increment. Markets
+ * that are add-only and cross-margined positions return `'0'`.
+ *
+ * @throws {PerpsError} `ValidationError` for malformed, non-positive, or
+ *   inconsistent risk inputs.
+ * @public
+ */
+export function removableIsolatedMargin({
+  position,
+  constraints,
+}: RemovableIsolatedMarginParams): string {
+  if (
+    position.marginMode !== MarginMode.ISOLATED ||
+    position.market.positionMarginAdjustment !==
+      PositionMarginAdjustment.ADD_AND_REMOVE
+  ) {
+    return '0'
+  }
+
+  const marginUsed = requirePositive(
+    positionAmount(position.marginUsed, 'marginUsed'),
+    'Position.marginUsed'
+  )
+  const unrealizedPnl = positionAmount(position.unrealizedPnl, 'unrealizedPnl')
+  const minimumMargin = requirePositive(
+    constraintAmount(
+      constraints.minimumMarginRequirement,
+      'minimumMarginRequirement'
+    ),
+    'PositionMarginConstraints.minimumMarginRequirement'
+  )
+  const amountIncrement = requirePositive(
+    constraintAmount(constraints.amountIncrement, 'amountIncrement'),
+    'PositionMarginConstraints.amountIncrement'
+  )
+
+  const removable = marginUsed.plus(unrealizedPnl).minus(minimumMargin)
+  if (removable.lte(0)) {
+    return '0'
+  }
+  return removable
+    .div(amountIncrement)
+    .round(0, Big.roundDown)
+    .times(amountIncrement)
+    .toFixed()
+}

package/src/version.ts

@@ -1,2 +1,2 @@
 export const name = '@lifi/perps-sdk'
-export const version = '5.0.0'
+export const version = '6.0.0'