@lifi/perps-sdk 25.0.2 → 27.0.0

package/src/errors/PerpsExecutionError.ts

@@ -0,0 +1,54 @@
+import {
+  type ActionResult,
+  type ExecuteActionResponse,
+  PerpsErrorCode,
+} from '@lifi/perps-types'
+import { PerpsError } from './PerpsError.js'
+
+/**
+ * Error thrown when an execution stage fails after part of the execution
+ * report is known. `response` holds every result known at the failure, and
+ * `cause` holds the original error. Its `code` is the cause's code when the
+ * cause is a {@link PerpsError}, else `SDKError`.
+ *
+ * @public
+ */
+export class PerpsExecutionError extends PerpsError {
+  override name = 'PerpsExecutionError'
+  readonly response: ExecuteActionResponse
+
+  constructor(response: ExecuteActionResponse, cause: unknown) {
+    super(
+      cause instanceof PerpsError ? cause.code : PerpsErrorCode.SDKError,
+      cause instanceof Error ? cause.message : String(cause)
+    )
+    this.response = response
+    this.cause = cause
+    if (cause instanceof PerpsError && cause.tool !== undefined) {
+      this.tool = cause.tool
+    }
+  }
+}
+
+/**
+ * Rethrow `error` unchanged when `known` is empty. Otherwise throw a
+ * {@link PerpsExecutionError} whose report holds `known`, then any results
+ * `error` already carries.
+ *
+ * @public
+ */
+export function rethrowWithKnownResults(
+  known: ActionResult[],
+  error: unknown
+): never {
+  if (known.length === 0) {
+    throw error
+  }
+  if (error instanceof PerpsExecutionError) {
+    throw new PerpsExecutionError(
+      { results: [...known, ...error.response.results] },
+      error.cause
+    )
+  }
+  throw new PerpsExecutionError({ results: known }, error)
+}

package/src/index.ts

@@ -71,35 +71,38 @@ export {
 export { PerpsErrorMessage } from './errors/constants.js'
 export { PerpsError } from './errors/PerpsError.js'
 export {
-  classifyFill,
+  PerpsExecutionError,
+  rethrowWithKnownResults,
+} from './errors/PerpsExecutionError.js'
+export {
   classifyFillFromPosition,
   FillClassification,
 } from './math/fills.js'
 export type { ExpectedPnl } from './math/order.js'
 export {
-  applySlippageToPrice,
   buildQuote,
   calculateExpectedPnl,
+  calculateOrderbookWalk,
   calculateRealizedPnlPercent,
   calculateSize,
+  calculateSlippagePrice,
   calculateTriggerPercent,
   calculateTriggerPrice,
   estimateFees,
   estimateRealizedPnl,
-  findMatchingPosition,
   resolveCloseSize,
-  safeApplySlippageToPrice,
+  resolveMatchingPosition,
   safeBuildQuote,
   safeCalculateExpectedPnl,
+  safeCalculateOrderbookWalk,
   safeCalculateRealizedPnlPercent,
   safeCalculateSize,
+  safeCalculateSlippagePrice,
   safeCalculateTriggerPercent,
   safeCalculateTriggerPrice,
   safeEstimateFees,
   safeEstimateRealizedPnl,
   safeResolveCloseSize,
-  safeWalkOrderbook,
-  walkOrderbook,
 } from './math/order.js'
 export {
   calculateEffectiveLeverage,
@@ -114,8 +117,8 @@ export {
   estimateLiquidationPriceAtMarketRate,
   estimateNewLeverage,
   estimateUnrealizedPnl,
-  positionSupportsMarginAdjustment,
-  positionSupportsMarginRemoval,
+  isPositionMarginAdjustable,
+  isPositionMarginRemovable,
   safeCalculateEffectiveLeverage,
   safeCalculateLiquidationDistance,
   safeCalculateNotionalValue,
@@ -283,6 +286,7 @@ export type {
   QuoteListener,
   SignActionProgress,
   SignActionsContext,
+  SignActionsResult,
 } from './types/provider.js'
 export type {
   ProviderWithdrawableBalance,
@@ -293,6 +297,7 @@ export type {
   WithdrawFlowReady,
   WithdrawFlowSetupRequired,
 } from './types/withdrawal.js'
+export { isSubmittedOrAccepted } from './utils/actionResult.js'
 export { paginateActivity } from './utils/activityPaging.js'
 export { createSafeFunction } from './utils/createSafeFunction.js'
 export {

package/src/math/fills.ts

@@ -4,7 +4,6 @@ import {
   OrderSide,
 } from '@lifi/perps-types'
 import Big from 'big.js'
-import { isDecimalStringZero } from '../decimal/compare.js'
 import { isDecimalString } from '../decimal/parse.js'
 
 /**
@@ -69,31 +68,3 @@ export function classifyFillFromPosition(
   }
   return FillClassification.REDUCED_SHORT
 }
-
-/**
- * Classify a fill as open or close based on realizedPnl.
- * @deprecated Use `Fill.classification` instead — it uses startPosition
- * for accurate open/increase/reduce/close/reverse classification.
- * @returns `BUY` or `SELL` when `realizedPnl` is a string that does not match the
- *   decimal pattern.
- * @public
- */
-export function classifyFill(
-  side: OrderSide,
-  realizedPnl: DecimalString | null | undefined
-): FillClassification {
-  if (realizedPnl != null && !isDecimalString(realizedPnl)) {
-    return side === OrderSide.BUY
-      ? FillClassification.BUY
-      : FillClassification.SELL
-  }
-  const isClose = realizedPnl != null && !isDecimalStringZero(realizedPnl)
-  if (side === OrderSide.BUY) {
-    return isClose
-      ? FillClassification.CLOSED_SHORT
-      : FillClassification.OPENED_LONG
-  }
-  return isClose
-    ? FillClassification.CLOSED_LONG
-    : FillClassification.OPENED_SHORT
-}

package/src/math/order.ts

@@ -96,7 +96,7 @@ export const safeEstimateFees = createSafeFunction('estimateFees', estimateFees)
  *   decimal pattern, or `slippagePercent` is -100 or less.
  * @public
  */
-export function applySlippageToPrice(
+export function calculateSlippagePrice(
   price: string,
   slippagePercent: string,
   isBuy: boolean
@@ -116,9 +116,9 @@ export function applySlippageToPrice(
 }
 
 /** @public */
-export const safeApplySlippageToPrice = createSafeFunction(
-  'applySlippageToPrice',
-  applySlippageToPrice
+export const safeCalculateSlippagePrice = createSafeFunction(
+  'calculateSlippagePrice',
+  calculateSlippagePrice
 )
 
 /**
@@ -277,7 +277,7 @@ export const safeCalculateRealizedPnlPercent = createSafeFunction(
   calculateRealizedPnlPercent
 )
 
-/** Result of {@link walkOrderbook} — the fill obtained for a USD-notional walk. */
+/** Result of {@link calculateOrderbookWalk} — the fill obtained for a USD-notional walk. */
 interface BookWalk {
   /** Base amount filled. */
   baseSize: string
@@ -301,7 +301,7 @@ interface BookWalk {
  *   or `size` does not match the decimal pattern.
  * @public
  */
-export function walkOrderbook(
+export function calculateOrderbookWalk(
   levels: OrderbookLevel[],
   sizeUsd: string
 ): BookWalk {
@@ -333,9 +333,9 @@ export function walkOrderbook(
 }
 
 /** @public */
-export const safeWalkOrderbook = createSafeFunction(
-  'walkOrderbook',
-  walkOrderbook
+export const safeCalculateOrderbookWalk = createSafeFunction(
+  'calculateOrderbookWalk',
+  calculateOrderbookWalk
 )
 
 /** Inputs to {@link buildQuote} — the resolved market, its live price, its book, and the trade ask. */
@@ -369,7 +369,7 @@ export function buildQuote(input: BuildQuoteInput): Quote {
   const { market, price, side, sizeUsd, feeTier } = input
   const markPrice = decimalStringToDivBig(price.markPrice)
   const levels = side === 'buy' ? input.asks : input.bids
-  const walk = walkOrderbook(levels, sizeUsd)
+  const walk = calculateOrderbookWalk(levels, sizeUsd)
   const vwap = decimalStringToBig(walk.vwap)
   const priceImpactBps =
     markPrice.eq(0) || vwap.eq(0)
@@ -407,7 +407,7 @@ export const safeBuildQuote = createSafeFunction('buildQuote', buildQuote)
  * @param positions - Open positions list (any market).
  * @public
  */
-export function findMatchingPosition(
+export function resolveMatchingPosition(
   marketId: string,
   positions: readonly Position[]
 ): Position | undefined {

package/src/math/position.ts

@@ -417,7 +417,7 @@ export const safeCalculateRealizedPnl = createSafeFunction(
  *
  * @public
  */
-export function positionSupportsMarginAdjustment(position: Position): boolean {
+export function isPositionMarginAdjustable(position: Position): boolean {
   return (
     position.marginMode === MarginMode.ISOLATED &&
     position.market.positionMarginAdjustment !== PositionMarginAdjustment.NONE
@@ -430,9 +430,9 @@ export function positionSupportsMarginAdjustment(position: Position): boolean {
  *
  * @public
  */
-export function positionSupportsMarginRemoval(position: Position): boolean {
+export function isPositionMarginRemovable(position: Position): boolean {
   return (
-    positionSupportsMarginAdjustment(position) &&
+    isPositionMarginAdjustable(position) &&
     position.market.positionMarginAdjustment ===
       PositionMarginAdjustment.ADD_AND_REMOVE
   )

package/src/types/api.ts

@@ -7,7 +7,6 @@ import type {
   PlaceTwapOrderParams as ActionPlaceTwapOrderParams,
   ActionStep,
   DecimalString,
-  ExecuteActionResponse,
   MarginMode,
   MarketRef,
   MetaActionType,
@@ -18,7 +17,6 @@ import type {
   PortfolioHistoryRange,
   SetupAction,
   SetupOption,
-  SignedActionStep,
   TimeInForce,
   TriggerOrderInput,
   WithdrawalParams,
@@ -380,25 +378,6 @@ export interface ProviderSetup {
   checklist: SetupChecklistItem[]
 }
 
-/**
- * Parameters for the internal `PerpsClient.executeProviderSetup` batch submit.
- */
-export interface ExecuteProviderSetupParams {
-  provider: string
-  address: Address
-  /** The unsatisfied setup steps from checkSetup() */
-  setup: ActionStep[]
-  /** Signed counterparts of `setup`, in the same order */
-  signedActions: SignedActionStep[]
-}
-
-/**
- * Result from the internal `PerpsClient.executeProviderSetup` batch submit.
- */
-export interface ExecuteProviderSetupResult {
-  results: ExecuteActionResponse
-}
-
 /**
  * Result envelope returned by {@link PerpsClient.getAccount} — wraps the
  * backend's `AccountResponse` with a single SDK-projected `settings` array.

package/src/types/provider.ts

@@ -79,6 +79,23 @@ export interface SignActionProgress {
   txHash: string
 }
 
+/**
+ * Output of {@link PerpsProviderPlugin.signActions}, in batch order.
+ *
+ * A plugin that executes a step itself while signing (a venue REST mutation,
+ * a reverted on-chain leg) puts that step's real result in `executed` and
+ * leaves it out of `signed`. The plugin stops at the first `executed` result
+ * that is not `Submitted` or `Accepted`. Core submits `signed` to
+ * `/executeAction` only when every `executed` result is `Submitted` or
+ * `Accepted`, and reports `executed` before the `/executeAction` results.
+ *
+ * @public
+ */
+export interface SignActionsResult {
+  signed: SignedActionStep[]
+  executed: ActionResult[]
+}
+
 /**
  * Per-call context passed by `PerpsClient` to a provider's
  * {@link PerpsProviderPlugin.signActions} implementation. Carries the
@@ -699,12 +716,13 @@ export interface PerpsProviderPlugin {
     steps: ActionStep[],
     address: Address,
     ctx?: SignActionsContext
-  ): Promise<SignedActionStep[]>
+  ): Promise<SignActionsResult>
 
   /**
-   * Observe the per-step results of an `/executeAction` round trip before the
-   * core surfaces failures. Lets a provider react to structured failure codes
-   * — e.g. evicting a locally stored credential the venue no longer accepts.
+   * Observe the execution report of each `execute` call: the results of the
+   * steps the plugin executed while signing, then the `/executeAction`
+   * results. Lets a provider react to structured statuses — e.g. evicting a
+   * locally stored credential the venue refused.
    */
   onExecuteResults?(address: Address, results: ActionResult[]): Promise<void>
 

package/src/utils/actionResult.ts

@@ -0,0 +1,10 @@
+import type { ActionResult } from '@lifi/perps-types'
+import { UserActionStatus } from '@lifi/perps-types'
+
+/** Whether the action took effect: its status is `Submitted` or `Accepted`. */
+export function isSubmittedOrAccepted(result: ActionResult): boolean {
+  return (
+    result.status === UserActionStatus.Submitted ||
+    result.status === UserActionStatus.Accepted
+  )
+}

package/src/version.ts

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