@lifi/perps-sdk 18.0.0 → 19.0.0

package/src/index.ts

@@ -118,6 +118,7 @@ export type {
   GetPortfolioHistoryParams,
   GetSetupParams,
   GetWithdrawableBalancesParams,
+  GetWithdrawFlowParams,
   ModifyOrdersParams,
   PerpsClientOptions,
   PerpsConfig,
@@ -166,6 +167,7 @@ export type {
   ProviderGetPositionsParams,
   ProviderGetQuoteParams,
   ProviderGetWithdrawableBalancesParams,
+  ProviderGetWithdrawFlowParams,
   QuoteListener,
   SignActionProgress,
   SignActionsContext,
@@ -174,6 +176,9 @@ export type {
   ProviderWithdrawableBalance,
   WithdrawableBalance,
   WithdrawalRoute,
+  WithdrawFlow,
+  WithdrawFlowReady,
+  WithdrawFlowSetupRequired,
 } from './types/withdrawal.js'
 export { paginateActivity } from './utils/activityPaging.js'
 export type { ExpectedPnl } from './utils/calculations.js'
@@ -247,7 +252,10 @@ export {
 } from './utils/positionMath.js'
 export type { ScaleToIntegerPolicy } from './utils/scaleToInteger.js'
 export { scaleToInteger } from './utils/scaleToInteger.js'
-export { selectUserSetupActions } from './utils/setupActions.js'
+export {
+  isSetupOptionFor,
+  selectUserSetupActions,
+} from './utils/setupActions.js'
 export {
   signTypedData,
   signTypedDataWithSigner,

package/src/types/api.ts

@@ -15,7 +15,8 @@ import type {
   OrderSide,
   OrderType,
   PortfolioHistoryRange,
-  ProviderAction,
+  SetupAction,
+  SetupOption,
   SignedActionStep,
   TimeInForce,
   TriggerOrderInput,
@@ -71,8 +72,8 @@ export interface PerpsConfig {
    */
   providers?: PerpsProviderPlugin[] | ProviderConfigs
   /**
-   * The end-user's wallet, used whenever an action's descriptor names the user
-   * wallet in its `signers` list. Accepts any viem-compatible WalletClient:
+   * The end-user's wallet, used whenever an action's descriptor names
+   * `PerpsSigner.USER` as its `signer`. Accepts any viem-compatible WalletClient:
    *   - Browser wallet: wagmi's useWalletClient() result
    *   - Private key:    createWalletClient({ account: privateKeyToAccount('0x...'), transport: http() })
    *   - Mnemonic:       createWalletClient({ account: mnemonicToAccount('word1 ...'), transport: http() })
@@ -289,6 +290,16 @@ export interface GetDepositFlowParams {
   address: Address
 }
 
+/**
+ * Parameters for {@link PerpsClient.getWithdrawFlow}.
+ *
+ * @public
+ */
+export interface GetWithdrawFlowParams {
+  provider: string
+  address: Address
+}
+
 /**
  * Parameters for {@link PerpsClient.getWithdrawableBalances}.
  *
@@ -318,9 +329,21 @@ export interface GetPortfolioHistoryParams {
  */
 export interface SetupChecklistItem {
   /** The `Provider.setup` descriptor for this step. */
-  descriptor: ProviderAction
+  descriptor: SetupAction
   /** Whether the step is already satisfied for this account. */
   satisfied: boolean
+  /**
+   * For a choice step, the option whose bound params match the projected
+   * account value. `null` when none matches or the step is not a choice.
+   */
+  selected: SetupOption | null
+  /**
+   * For a choice step, the account's current value as the venue names it
+   * (the raw projected value, e.g. `standard` or `dexAbstraction`), even when
+   * no option binds it. `null` when the venue reports none or the value is
+   * unreadable, and always `null` for a non-choice step.
+   */
+  currentValue: string | null
 }
 
 /**
@@ -331,8 +354,10 @@ export interface SetupChecklistItem {
  * to the provider's `setup` descriptor, which declares the step's signer and
  * scheme), so no signer-role partition is exposed here.
  *
- * `Provider.options` items are NEVER included here — they don't gate trading
- * and are surfaced separately via `getAccount().settings`.
+ * A non-choice step with `signer: SDK` is NEVER included here — the SDK
+ * drains it itself. A choice step is listed on `checklist` but never staged or
+ * executed: the user picks an option through
+ * `PerpsClient.executeProviderOption`.
  *
  * @public
  */
@@ -346,12 +371,15 @@ export interface ProviderSetup {
   accountExists: boolean
   /** Unsatisfied setup steps, ordered by descriptor `sequence`. */
   setup: ActionStep[]
-  /** Whether all setup items are already satisfied (ready to trade) */
+  /**
+   * `true` only when nothing is staged and every choice on `checklist` is
+   * satisfied: the account is ready to trade.
+   */
   isReady: boolean
   /**
-   * The renderable onboarding list: every USER-signed setup descriptor with
-   * its satisfied state, ordered by `sequence`. SDK-internal steps and
-   * conditional steps that staged no work for this account (see
+   * The renderable onboarding list: every choice step and every `USER`-signed
+   * setup step with its satisfied state, ordered by `sequence`. SDK-drained
+   * steps and conditional steps that staged no work for this account (see
    * `PerpsProviderPlugin.conditionalSetupActions`) are omitted. Consumers
    * render this list directly instead of joining `Provider.setup` metadata
    * with the staged `setup` steps.
@@ -383,14 +411,14 @@ export interface ExecuteProviderSetupResult {
  * backend's `AccountResponse` with a single SDK-projected `settings` array.
  *
  * `settings` contains exactly one `AccountConfigSetting` per descriptor on
- * `Provider.setup` + `Provider.options` (in that order). Index the
- * projection by `setting.type === descriptor.type` and read
- * `setting.values[i].value` for each `Param` the descriptor declared.
+ * `Provider.setup`, in that order. Index the projection by
+ * `setting.type === descriptor.type` and read `setting.values[i].value` for
+ * each `Param` the descriptor declared.
  *
  * @public
  */
 export interface GetAccountResult extends AccountResponse {
-  /** SDK-projected current state of every setup + options descriptor. */
+  /** SDK-projected current state of every `Provider.setup` descriptor. */
   settings: AccountConfigSetting[]
 }
 

package/src/types/provider.ts

@@ -22,9 +22,9 @@ import type {
   PortfolioHistoryResponse,
   Position,
   PositionsResponse,
-  ProviderAction,
   Quote,
   QuoteSide,
+  SetupAction,
   SignedActionStep,
   SigningMethod,
   TradeType,
@@ -36,7 +36,7 @@ import type {
   SDKRequestOptions,
 } from './config.js'
 import type { DepositFlow } from './deposit.js'
-import type { ProviderWithdrawableBalance } from './withdrawal.js'
+import type { ProviderWithdrawableBalance, WithdrawFlow } from './withdrawal.js'
 
 /**
  * Low-level SDK client: resolved config, the optional end-user wallet, and the
@@ -86,12 +86,12 @@ export interface SignActionsContext {
   /** End-user wallet used for USER-signed or EVM transaction legs. */
   userWallet?: PerpsClientSigner
   /**
-   * The signing batch's declared signers, from the action's `ProviderAction`
+   * The signing batch's declared signer, from the action's `ProviderAction`
    * descriptor. The plugin branches on this to pick WHO signs (e.g.
-   * Hyperliquid: `USER` → end-user wallet, `AGENT` → session keypair). Core
-   * forwards the descriptor's `signers` as data; it does not branch on them.
+   * Hyperliquid: `USER` → end-user wallet, `SDK` → session keypair). Core
+   * forwards the descriptor's `signer` as data; it does not branch on it.
    */
-  signers?: PerpsSigner[]
+  signer?: PerpsSigner
   /**
    * Switch `userWallet` to `chainId` and resolve the client to broadcast with.
    * Bound by core to the consumer's `switchChain` hook and the resolved
@@ -180,6 +180,15 @@ export interface ProviderGetDepositFlowParams {
   address: Address
 }
 
+/**
+ * Read params for {@link PerpsProviderPlugin.getWithdrawFlow}.
+ *
+ * @public
+ */
+export interface ProviderGetWithdrawFlowParams {
+  address: Address
+}
+
 /**
  * Read params for {@link PerpsProviderPlugin.getWithdrawableBalances}.
  *
@@ -361,23 +370,12 @@ export interface PerpsProviderPlugin {
   readonly type: string
 
   /**
-   * Setup actions the provider completes on its own, without surfacing a card
-   * to the caller. `PerpsClient.checkSetup` drains each such pending step in
-   * place — building, signing, and executing it with the provider's own
-   * credentials — and omits it from the returned `setup` list. A descriptor
-   * whose `signers` include {@link PerpsSigner.USER} is never treated as
-   * internal, even when named here. Omit when the provider has no
-   * self-completed setup steps.
-   */
-  readonly internalSetupActions?: readonly ActionType[]
-
-  /**
-   * Setup actions that stage work only when the account needs remediation
-   * (e.g. Hyperliquid's REVOKE_AGENT frees an agent slot only when every
-   * named slot is taken). When such a step stages no actions,
+   * Non-choice setup actions that stage work only when the account needs
+   * remediation (e.g. Hyperliquid's REVOKE_AGENT frees an agent slot only
+   * when every named slot is taken). When such a step stages no actions,
    * `PerpsClient.checkSetup` omits it from `ProviderSetup.checklist` instead
-   * of rendering it as satisfied. Omit when every setup step is
-   * unconditional.
+   * of rendering it as satisfied. Choices are always rendered because they
+   * are never staged. Omit when every setup step is unconditional.
    */
   readonly conditionalSetupActions?: readonly ActionType[]
 
@@ -421,6 +419,19 @@ export interface PerpsProviderPlugin {
     options?: SDKRequestOptions
   ): Promise<DepositFlow>
 
+  /**
+   * The withdrawal flow this venue offers `params.address`, resolved from the
+   * venue's own account and setup state — the destination a withdrawal goes
+   * to, or the venue setup that must come first.
+   *
+   * Optional: a provider without a gated withdrawal destination omits it, and
+   * `PerpsClient.getWithdrawFlow` then resolves `undefined`.
+   */
+  getWithdrawFlow?(
+    params: ProviderGetWithdrawFlowParams,
+    options?: SDKRequestOptions
+  ): Promise<WithdrawFlow>
+
   /**
    * The `(asset, route)` pairs `params.address` currently has something to
    * withdraw from, keyed by provider-native asset id. Only the venue knows how
@@ -576,9 +587,12 @@ export interface PerpsProviderPlugin {
 
   /**
    * Project a typed {@link AccountConfig} against the provider's `setup`
-   * + `options` descriptors into `AccountConfigSetting[]`. Used by
+   * descriptors into `AccountConfigSetting[]`. Used by
    * `PerpsClient.getAccount` to attach a `settings` array to the response —
-   * one entry per descriptor, in `setup`-then-`options` order.
+   * one entry per descriptor, in `setup` order. Every choice descriptor
+   * (`options` is not `null`) carries a boolean `satisfied`, because
+   * `PerpsClient.checkSetup` reads a choice's satisfied state and `selected`
+   * option from this projection alone.
    *
    * Implementations receive the union-typed `AccountConfig` and narrow on
    * `config.provider` themselves; the dispatcher in `PerpsClient` does not
@@ -586,8 +600,7 @@ export interface PerpsProviderPlugin {
    */
   projectConfig(
     config: AccountConfig,
-    setup: ProviderAction[],
-    options: ProviderAction[]
+    setup: SetupAction[]
   ): AccountConfigSetting[]
 
   /**
@@ -595,7 +608,8 @@ export interface PerpsProviderPlugin {
    * when staging the provider setup. Used for plugin-side state the backend
    * needs to make a correct idempotency decision (e.g. Lighter's known local
    * API public key). Returns an empty object when the plugin has no params
-   * to contribute for the action. Optional — providers without local state
+   * to contribute for the action. A choice option runs with its bound params
+   * alone and never reads these. Optional — providers without local state
    * can omit it entirely.
    */
   resolveSetupParams?(
@@ -606,7 +620,7 @@ export interface PerpsProviderPlugin {
   /**
    * Contribute the signer-bearing wire fields for an action — the plugin owns
    * signer identity (WHO signs), so core asks the plugin rather than resolving
-   * a `signerAddress` itself. The descriptor's `signers` are forwarded so the
+   * a `signerAddress` itself. The descriptor's `signer` is forwarded so the
    * plugin can branch on signer role: a provider that signs on the user's
    * behalf with a session keypair (Hyperliquid's agent) resolves — provisioning
    * one if needed — and returns the agent address as `signerAddress`; for
@@ -622,7 +636,7 @@ export interface PerpsProviderPlugin {
   resolveActionRequest?(
     action: ActionType,
     address: Address,
-    signers: PerpsSigner[]
+    signer: PerpsSigner
   ): Promise<ActionSignerContribution>
 
   /**
@@ -637,7 +651,7 @@ export interface PerpsProviderPlugin {
    * provider has no `signActions`.
    *
    * `method` mirrors the descriptor's `signingMethod`. The plugin owns every
-   * arm, branching on the descriptor's `signers` internally: the EIP712 arm
+   * arm, branching on the descriptor's `signer` internally: the EIP712 arm
    * signs with the user's wallet (read from `ctx.userWallet`) or the provider's
    * session keypair (Hyperliquid's agent), and `WASM_BLOB` / `EVM_TX` sign with
    * the provider's local credential (Lighter).

package/src/types/withdrawal.ts

@@ -1,4 +1,5 @@
-import type { Asset } from '@lifi/perps-types'
+import type { ActionType, Asset } from '@lifi/perps-types'
+import type { Address } from 'viem'
 
 /**
  * Which of a venue's two balance routes a withdrawal is drawn from. Lighter's
@@ -49,3 +50,34 @@ export interface WithdrawableBalance {
    */
   withdrawalFee?: string
 }
+
+/**
+ * The venue accepts a withdrawal to `destination` now.
+ *
+ * @public
+ */
+export interface WithdrawFlowReady {
+  kind: 'ready'
+  destination: Address
+}
+
+/**
+ * The venue cannot accept a withdrawal until the listed setup actions are
+ * satisfied — Ondo sends funds only to an address in its address book, behind
+ * a signed-in session.
+ *
+ * @public
+ */
+export interface WithdrawFlowSetupRequired {
+  kind: 'setupRequired'
+  /** Setup action types that must be completed, in execution order. */
+  setup: ActionType[]
+}
+
+/**
+ * The single withdrawal flow a venue offers one address, resolved from the
+ * venue's account and setup state.
+ *
+ * @public
+ */
+export type WithdrawFlow = WithdrawFlowReady | WithdrawFlowSetupRequired

package/src/utils/setupActions.ts

@@ -1,14 +1,14 @@
-import type { ProviderAction } from '@lifi/perps-types'
+import type { ActionType, SetupAction, SetupOption } from '@lifi/perps-types'
 import { PerpsSigner } from '@lifi/perps-types'
 
 /**
- * Select the `Provider.setup` descriptors a user is responsible for satisfying:
- * those whose `signers` include {@link PerpsSigner.USER}. Descriptors the SDK
- * signs on its own (no `USER` signer) are held back — `checkSetup` completes
- * them inline, so surfacing them would render inert cards the user can't act on.
+ * Select the `Provider.setup` descriptors a user sees: every choice step, and
+ * every non-choice step signed by {@link PerpsSigner.USER}. A non-choice step
+ * the SDK signs on its own is held back — `checkSetup` completes it inline, so
+ * surfacing it would render an inert card the user can't act on.
  *
- * Membership is a property of the descriptor's `signers` alone, independent of
- * any account. When an account is available, prefer `ProviderSetup.checklist`
+ * Membership is a property of the descriptor alone, independent of any
+ * account. When an account is available, prefer `ProviderSetup.checklist`
  * from `checkSetup` for the onboarding list — it applies this filter, omits
  * not-required conditional steps, and carries each entry's satisfied state.
  * This function remains the static, account-free projection.
@@ -16,10 +16,24 @@ import { PerpsSigner } from '@lifi/perps-types'
  * @param setup The provider's `setup` descriptors, in their declared order.
  * @public
  */
-export function selectUserSetupActions(
-  setup: ProviderAction[]
-): ProviderAction[] {
-  return setup.filter((descriptor) =>
-    descriptor.signers.includes(PerpsSigner.USER)
-  )
+export function selectUserSetupActions(setup: SetupAction[]): SetupAction[] {
+  return setup.filter(isUserFacingSetupStep)
+}
+
+/** Whether a setup step is shown to the user rather than drained silently. */
+export function isUserFacingSetupStep(descriptor: SetupAction): boolean {
+  return descriptor.options !== null || descriptor.signer === PerpsSigner.USER
+}
+
+/**
+ * Narrow a setup option to the action it executes, so its bound `params` read
+ * with that action's param shape.
+ *
+ * @public
+ */
+export function isSetupOptionFor<T extends ActionType>(
+  option: SetupOption,
+  type: T
+): option is SetupOption<T> {
+  return option.type === type
 }

package/src/utils/switchChain.ts

@@ -35,7 +35,7 @@ export function userEip712TargetChainId(
 ): number | undefined {
   if (
     descriptor.signingMethod !== SigningMethod.EIP712 ||
-    !descriptor.signers.includes(PerpsSigner.USER)
+    descriptor.signer !== PerpsSigner.USER
   ) {
     return undefined
   }

package/src/version.ts

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