@lifi/perps-sdk 18.1.0 → 20.0.0

package/src/client/PerpsClient.ts

@@ -1,4 +1,5 @@
 import type {
+  AccountConfigSetting,
   AccountResponse,
   AccountSummary,
   ActionParamsMap,
@@ -16,9 +17,12 @@ import type {
   Position,
   Provider,
   ProviderAction,
+  SetupAction,
+  SetupOption,
   SignedActionStep,
 } from '@lifi/perps-types'
 import {
+  ActionRelay,
   ActionType,
   META_PROVIDER,
   PerpsErrorCode,
@@ -63,6 +67,7 @@ import type {
   PlaceTwapOrderParams,
   ProviderSetup,
   SendAssetActionParams,
+  SetupChecklistItem,
   SubmitOnboardingParams,
   WithdrawParams,
 } from '../types/api.js'
@@ -80,6 +85,7 @@ import type {
   SignActionsContext,
 } from '../types/provider.js'
 import type { WithdrawableBalance, WithdrawFlow } from '../types/withdrawal.js'
+import { isUserFacingSetupStep } from '../utils/setupActions.js'
 import { signTypedDataWithSigner } from '../utils/signTypedData.js'
 import {
   eip712DomainChainId,
@@ -89,6 +95,127 @@ import {
 import { createPerpsClient } from './createPerpsClient.js'
 import { requireProvider as resolveProvider } from './requireProvider.js'
 
+/** Absent `sequence` sorts last, so an unordered step gates nothing. */
+function sequenceOf(descriptor: ProviderAction): number {
+  return descriptor.sequence ?? Number.MAX_SAFE_INTEGER
+}
+
+const SIGNERS: ReadonlySet<string> = new Set(Object.values(PerpsSigner))
+const RELAYS: ReadonlySet<string> = new Set(Object.values(ActionRelay))
+
+/**
+ * Reject provider metadata whose steps the SDK cannot classify. A step with no
+ * known `signer`, `relay`, `options` or `revoke` would otherwise read as
+ * satisfied and report a not-onboarded account as ready.
+ */
+function assertSetupContract(metadata: Provider): void {
+  const reject = (step: ActionType, problem: string): never => {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Provider '${metadata.key}' step '${step}' ${problem}; this SDK needs a ` +
+        `backend that emits signer, relay, options and revoke.`
+    )
+  }
+  for (const descriptor of [...metadata.setup, ...metadata.actions]) {
+    if (!SIGNERS.has(descriptor.signer)) {
+      reject(descriptor.type, 'declares no known signer')
+    }
+    if (!RELAYS.has(descriptor.relay)) {
+      reject(descriptor.type, 'declares no known relay')
+    }
+  }
+  const actionTypes = new Set(metadata.actions.map((d) => d.type))
+  for (const descriptor of metadata.setup) {
+    if (descriptor.options === undefined) {
+      reject(descriptor.type, 'declares no options')
+    }
+    if (descriptor.options !== null && descriptor.options.length === 0) {
+      reject(descriptor.type, 'declares an empty options list')
+    }
+    if (descriptor.revoke === undefined) {
+      reject(descriptor.type, 'declares no revoke')
+    }
+    if (descriptor.revoke !== null && !actionTypes.has(descriptor.revoke)) {
+      reject(
+        descriptor.type,
+        `revokes with '${descriptor.revoke}', which Provider.actions does not declare`
+      )
+    }
+    const defaults = (descriptor.options ?? []).filter(
+      (option) => option.default === true
+    )
+    if (defaults.length > 1) {
+      reject(descriptor.type, 'marks more than one option default')
+    }
+  }
+}
+
+/** Only a USER-signed non-choice step is staged for the user to sign. */
+function isStageable(descriptor: SetupAction): boolean {
+  return descriptor.options === null && descriptor.signer === PerpsSigner.USER
+}
+
+function satisfiedTypes(settings: AccountConfigSetting[]): Set<ActionType> {
+  return new Set(
+    settings.filter((setting) => setting.satisfied).map((s) => s.type)
+  )
+}
+
+/** The choice option whose every bound param equals the projected value. */
+function selectedOption(
+  descriptor: SetupAction,
+  settings: AccountConfigSetting[]
+): SetupOption | null {
+  if (descriptor.options === null) {
+    return null
+  }
+  const values =
+    settings.find((setting) => setting.type === descriptor.type)?.values ?? []
+  return (
+    descriptor.options.find((option) => {
+      const bound = Object.entries(option.params)
+      return (
+        bound.length > 0 &&
+        bound.every(([name, value]) =>
+          values.some((v) => v.name === name && v.value === value)
+        )
+      )
+    }) ?? null
+  )
+}
+
+/**
+ * The projected value of the param a choice's options bind, as the venue
+ * names it, whether or not an option binds that value.
+ */
+function currentChoiceValue(
+  descriptor: SetupAction,
+  settings: AccountConfigSetting[]
+): string | null {
+  if (descriptor.options === null) {
+    return null
+  }
+  const names = new Set(
+    descriptor.options.flatMap((option) => Object.keys(option.params))
+  )
+  const value =
+    settings
+      .find((setting) => setting.type === descriptor.type)
+      ?.values.find((v) => names.has(v.name))?.value ?? null
+  return value === null ? null : String(value)
+}
+
+/** Throw the first per-action failure a 200 OK `/executeAction` carried. */
+function assertAllSucceeded(results: ActionResult[]): void {
+  const failure = results.find((r) => !r.success)
+  if (failure) {
+    throw new PerpsError(
+      failure.errorCode ?? PerpsErrorCode.ExchangeRejected,
+      failure.error
+    )
+  }
+}
+
 function isNonNegativeDecimal(value: string): boolean {
   try {
     return new Big(value).gte(0)
@@ -105,11 +232,9 @@ function findActionDescriptor(
   metadata: Provider,
   action: ActionType
 ): ProviderAction {
-  const descriptor = [
-    ...metadata.setup,
-    ...metadata.options,
-    ...metadata.actions,
-  ].find((d) => d.type === action)
+  const descriptor = [...metadata.setup, ...metadata.actions].find(
+    (d) => d.type === action
+  )
   if (!descriptor) {
     throw new PerpsError(
       PerpsErrorCode.SDKError,
@@ -171,7 +296,7 @@ export class PerpsClient {
 
   /**
    * Set or update the end-user's wallet. Used whenever an action's descriptor
-   * names the user wallet in its `signers` list. Pass undefined to clear.
+   * names `PerpsSigner.USER` as its `signer`. Pass undefined to clear.
    *
    * @public
    */
@@ -205,17 +330,15 @@ export class PerpsClient {
   }
 
   private async getProviderMetadata(provider: string): Promise<Provider> {
-    const cached = this.providerMetadataCache.get(provider)
-    if (cached) {
-      return cached
-    }
-
-    const { providers } = await getProviders(this.sdkClient)
-    for (const d of providers) {
-      this.providerMetadataCache.set(d.key, d)
+    let metadata = this.providerMetadataCache.get(provider)
+    if (!metadata) {
+      const { providers } = await getProviders(this.sdkClient)
+      for (const d of providers) {
+        this.providerMetadataCache.set(d.key, d)
+      }
+      metadata = this.providerMetadataCache.get(provider)
     }
 
-    const metadata = this.providerMetadataCache.get(provider)
     if (!metadata) {
       const error = new PerpsError(
         PerpsErrorCode.SDKError,
@@ -224,6 +347,7 @@ export class PerpsClient {
       error.tool = '@lifi/perps-sdk'
       throw error
     }
+    assertSetupContract(metadata)
     return metadata
   }
 
@@ -256,7 +380,7 @@ export class PerpsClient {
    * Ask the provider plugin for the signer-bearing wire fields of `action` —
    * the on-wire `signerAddress` and any signer-derived params (e.g.
    * Hyperliquid's `agentAddress` for `APPROVE_AGENT`). Forwards the descriptor's
-   * `signers` so the plugin can branch on signer role. Returns empty when the
+   * `signer` so the plugin can branch on signer role. Returns empty when the
    * plugin signs as the user or with a non-EVM credential. Core constructs no
    * `signerAddress` itself; signer identity is plugin-owned.
    */
@@ -272,17 +396,17 @@ export class PerpsClient {
     return plugin.resolveActionRequest(
       descriptor.type,
       address,
-      descriptor.signers
+      descriptor.signer
     )
   }
 
   /**
    * Delegate signing of `actions` to the provider plugin, one call per
    * consecutive run of steps sharing a descriptor. Each call carries that
-   * descriptor's `signingMethod` and `signers`, so a mixed batch signs every
+   * descriptor's `signingMethod` and `signer`, so a mixed batch signs every
    * step with the signer its own descriptor declares; the signed steps come
    * back in the batch's original order. The plugin owns every signing arm and
-   * branches on `signers` internally, reading the end-user's wallet from the
+   * branches on `signer` internally, reading the end-user's wallet from the
    * {@link SignActionsContext} when an arm signs as the user.
    *
    * @throws {PerpsError} When a step's action is not declared by the provider,
@@ -405,9 +529,9 @@ export class PerpsClient {
 
   /**
    * Assemble the per-call context the provider plugin needs in order to sign:
-   * the end-user's wallet and the descriptor's declared `signers`. Core
-   * forwards `signers` as data so the plugin can pick WHO signs; it does not
-   * branch on them. Provider-owned session credentials (the Hyperliquid agent
+   * the end-user's wallet and the descriptor's declared `signer`. Core
+   * forwards `signer` as data so the plugin can pick WHO signs; it does not
+   * branch on it. Provider-owned session credentials (the Hyperliquid agent
    * keypair, Lighter's API key) are resolved inside the provider's
    * `signActions`, not threaded through here.
    *
@@ -425,7 +549,7 @@ export class PerpsClient {
     userWallet?: PerpsClientSigner,
     onProgress?: (progress: SignActionProgress) => void
   ): SignActionsContext {
-    const ctx: SignActionsContext = { signers: descriptor.signers }
+    const ctx: SignActionsContext = { signer: descriptor.signer }
     if (onProgress !== undefined) {
       ctx.onProgress = onProgress
     }
@@ -501,7 +625,7 @@ export class PerpsClient {
   /**
    * Fetch the user's account state from the backend and attach the
    * SDK-projected `settings` array — one `AccountConfigSetting` per
-   * descriptor on `Provider.setup` + `Provider.options`. Callers read
+   * descriptor on `Provider.setup`. Callers read
    * `result.settings` directly without re-deriving values from the typed
    * `AccountConfig`.
    *
@@ -518,30 +642,27 @@ export class PerpsClient {
       fetchAccount(this.sdkClient, params),
       this.getProviderMetadata(params.provider),
     ])
-    const settings = plugin.projectConfig(
-      response.config,
-      metadata.setup,
-      metadata.options
-    )
+    const settings = plugin.projectConfig(response.config, metadata.setup)
     return { ...response, settings }
   }
 
   /**
-   * The user's current venue-side settings for a market — the margin mode
-   * and leverage the next order on it will use. Resolves `undefined` when
-   * the venue exposes no readable setting for the market (or the provider
-   * has no such read at all).
+   * The user's current venue-side settings for a perps market — the margin
+   * mode and leverage the next order on it will use. Resolves the venue value
+   * or throws.
    *
-   * @throws {PerpsError} When the provider plugin is not registered.
+   * @throws {PerpsError} When the provider plugin is not registered,
+   *   `ValidationError` for a spot market, or any other `PerpsError` when the
+   *   venue read fails or carries no usable value.
    * @public
    */
   async getMarketSettings(params: {
     provider: string
     address: Address
     market: MarketRef
-  }): Promise<MarketSettings | undefined> {
+  }): Promise<MarketSettings> {
     const plugin = this.requireProvider(params.provider)
-    return plugin.getMarketSettings?.({
+    return plugin.getMarketSettings({
       address: params.address,
       market: params.market,
     })
@@ -690,7 +811,7 @@ export class PerpsClient {
    * @returns `undefined` when the registered plugin declares no withdrawable
    *   read.
    * @throws {PerpsError} When the provider plugin is not registered, when
-   *   either the plugin read or the asset sync fails, or when a row's
+   *   either the plugin read or the asset sync fails, when a row's
    *   `withdrawalFee` is not a non-negative decimal.
    * @public
    */
@@ -742,6 +863,9 @@ export class PerpsClient {
           route: row.route,
           available: row.available,
           withdrawalFee: row.withdrawalFee,
+          ...(row.isFeeDeducted === undefined
+            ? {}
+            : { isFeeDeducted: row.isFeeDeducted }),
         },
       ]
     })
@@ -773,15 +897,17 @@ export class PerpsClient {
   }
 
   /**
-   * Return the unsatisfied entries on `Provider.setup` for this account as a
-   * flat, self-describing list. Trading is gated on `isReady === true`.
-   * `checklist` carries the renderable onboarding list: every USER-signed
-   * descriptor with its satisfied state, with not-required conditional steps
-   * omitted.
+   * Return the setup steps this account must still sign as a flat,
+   * self-describing list. Trading is gated on `isReady === true`.
+   * `checklist` carries the renderable onboarding list: every choice step and
+   * every `USER`-signed step with its satisfied state, with not-required
+   * conditional steps omitted.
    *
-   * `Provider.options` descriptors are NEVER returned here — options are
-   * post-setup tunables and never gate trading. Option state is surfaced
-   * separately via `getAccount().settings`.
+   * A non-choice `SDK`-signed step is NEVER returned here — the SDK drains it
+   * with the provider's own credentials. A choice is listed but never staged
+   * or executed, whatever its `signer`: the user picks an option through
+   * {@link executeProviderOption}, and `isReady` stays `false` until every
+   * choice on `checklist` is satisfied.
    *
    * @public
    */
@@ -807,19 +933,15 @@ export class PerpsClient {
       }
     }
 
-    const satisfiedSetup = await this.resolveSatisfiedSetup(provider, address)
+    const settings = await this.resolveSetupSettings(provider, address)
+    const satisfiedSetup = satisfiedTypes(settings)
     const pendingSetup = metadata.setup.filter(
       (descriptor) => !satisfiedSetup.has(descriptor.type)
     )
 
     const plugin = this.sdkClient.getProvider(provider)
-    const internalTypes = new Set(plugin?.internalSetupActions ?? [])
-    const isInternal = (descriptor: ProviderAction): boolean =>
-      internalTypes.has(descriptor.type) &&
-      !descriptor.signers.includes(PerpsSigner.USER)
-    const visibleSetup = pendingSetup.filter(
-      (descriptor) => !isInternal(descriptor)
-    )
+
+    const stageable = pendingSetup.filter(isStageable)
 
     // The backend filters already-satisfied setup actions and returns typed
     // data for those still outstanding; each plugin contributes its own
@@ -827,7 +949,7 @@ export class PerpsClient {
     const actions = await this.buildProviderSetupActions(
       provider,
       address,
-      visibleSetup
+      stageable
     )
 
     // A staged step is one the build produced actions for — a pending
@@ -835,69 +957,64 @@ export class PerpsClient {
     // (backend-gated) or not applicable to this account.
     const stagedTypes = new Set(actions.map((step) => step.action))
     const conditionalTypes = new Set(plugin?.conditionalSetupActions ?? [])
-    const sequenceOf = (descriptor: ProviderAction): number =>
-      descriptor.sequence ?? Number.MAX_SAFE_INTEGER
     const checklist = metadata.setup
-      .filter((descriptor) => descriptor.signers.includes(PerpsSigner.USER))
+      .filter(isUserFacingSetupStep)
       .filter(
         (descriptor) =>
+          descriptor.options !== null ||
           !conditionalTypes.has(descriptor.type) ||
           stagedTypes.has(descriptor.type)
       )
       .sort((a, b) => sequenceOf(a) - sequenceOf(b))
       .map((descriptor) => ({
         descriptor,
-        satisfied: !stagedTypes.has(descriptor.type),
+        satisfied:
+          descriptor.options !== null
+            ? satisfiedSetup.has(descriptor.type)
+            : !stagedTypes.has(descriptor.type),
+        selected: selectedOption(descriptor, settings),
+        currentValue: currentChoiceValue(descriptor, settings),
       }))
 
-    await this.drainInternalSetup(
+    await this.drainSetup(
       provider,
       address,
-      pendingSetup.filter(isInternal),
-      visibleSetup.filter((descriptor) => stagedTypes.has(descriptor.type))
+      pendingSetup.filter(
+        (descriptor) =>
+          descriptor.options === null && descriptor.signer === PerpsSigner.SDK
+      ),
+      stageable.filter((descriptor) => stagedTypes.has(descriptor.type))
     )
 
     return {
       accountExists: true,
       setup: actions,
-      isReady: actions.length === 0,
+      isReady:
+        actions.length === 0 && checklist.every((item) => item.satisfied),
       checklist,
     }
   }
 
   /**
-   * Resolve setup descriptors already satisfied from the provider's own typed
-   * account config projection. This catches client-held auth state (e.g. Ondo
-   * SIWE/JWT) that the backend cannot observe.
+   * Project the provider's own typed account config onto its setup steps. This
+   * catches client-held auth state (e.g. Ondo SIWE/JWT) that the backend
+   * cannot observe, and carries the current value of each choice.
    */
-  private async resolveSatisfiedSetup(
+  private async resolveSetupSettings(
     provider: string,
     address: Address
-  ): Promise<Set<ActionType>> {
+  ): Promise<AccountConfigSetting[]> {
     const metadata = await this.getProviderMetadata(provider)
     const plugin = this.sdkClient.getProvider(provider)
     if (!plugin || typeof plugin.getAccount !== 'function') {
-      return new Set()
+      return []
     }
     const account = await plugin.getAccount({ address })
-    const settings = plugin.projectConfig(
-      account.config,
-      metadata.setup,
-      metadata.options
-    )
-    const setupTypes = new Set(
-      metadata.setup.map((descriptor) => descriptor.type)
-    )
-    return new Set(
-      settings
-        .filter((setting) => setting.satisfied && setupTypes.has(setting.type))
-        .map((setting) => setting.type)
-    )
+    return plugin.projectConfig(account.config, metadata.setup)
   }
 
   /**
-   * Drain the pending setup steps the provider declares as internal via
-   * `PerpsProviderPlugin.internalSetupActions`. Each step is built, signed,
+   * Drain the pending `SDK`-signed non-choice steps: each is built, signed,
    * and executed in place with the provider's own credentials. A step is
    * deferred while any staged user-facing step with a lower `sequence` is
    * outstanding — it cannot succeed before its prerequisite (e.g. SET_REFERRAL
@@ -906,17 +1023,15 @@ export class PerpsClient {
    * blocks setup — the step stays unsatisfied and is retried on a later
    * `checkSetup`.
    */
-  private async drainInternalSetup(
+  private async drainSetup(
     provider: string,
     address: Address,
-    internalPending: ProviderAction[],
-    stagedVisible: ProviderAction[]
+    drainable: SetupAction[],
+    stagedVisible: SetupAction[]
   ): Promise<void> {
-    const sequenceOf = (descriptor: ProviderAction): number =>
-      descriptor.sequence ?? Number.MAX_SAFE_INTEGER
-    for (const descriptor of internalPending) {
+    for (const descriptor of drainable) {
       // A tie (equal sequences, or both absent) declares no order, so the
-      // internal step defers to the next checkSetup rather than racing.
+      // drained step defers to the next checkSetup rather than racing.
       const blocked = stagedVisible.some(
         (staged) => sequenceOf(staged) <= sequenceOf(descriptor)
       )
@@ -944,7 +1059,7 @@ export class PerpsClient {
         }
       } catch (error) {
         console.debug(
-          `[perps-sdk] internal setup step '${descriptor.type}' for '${provider}' did not complete; will retry on the next checkSetup.`,
+          `[perps-sdk] setup step '${descriptor.type}' for '${provider}' did not drain; will retry on the next checkSetup.`,
           error
         )
       }
@@ -958,7 +1073,7 @@ export class PerpsClient {
   private async buildProviderSetupActions(
     provider: string,
     address: Address,
-    descriptors: ProviderAction[]
+    descriptors: SetupAction[]
   ): Promise<ActionStep[]> {
     const setupPriority = (descriptor: ProviderAction): number =>
       descriptor.signingMethod === SigningMethod.SIWE ? 0 : 1
@@ -996,9 +1111,11 @@ export class PerpsClient {
 
   /**
    * Build the unsigned setup `ActionStep`s still outstanding for an account,
-   * ordered by descriptor `sequence`. The backend filters already-satisfied
-   * setup; each plugin contributes its own signer-bearing request fields and
-   * any local-state params (e.g. Lighter's known pubkey).
+   * ordered by descriptor `sequence`. Only a `USER`-signed non-choice step is
+   * staged: an `SDK`-signed non-choice step drains inside {@link checkSetup}
+   * and a choice executes the option the user picks. The backend filters
+   * already-satisfied setup; each plugin contributes its own signer-bearing
+   * request fields and any local-state params (e.g. Lighter's known pubkey).
    *
    * @public
    */
@@ -1011,7 +1128,7 @@ export class PerpsClient {
     const actions = await this.buildProviderSetupActions(
       provider,
       address,
-      metadata.setup
+      metadata.setup.filter(isStageable)
     )
     return { actions }
   }
@@ -1054,13 +1171,7 @@ export class PerpsClient {
 
     await this.notifyExecuteResults(provider, address, results)
 
-    const failure = results.find((r) => !r.success)
-    if (failure) {
-      throw new PerpsError(
-        failure.errorCode ?? PerpsErrorCode.ExchangeRejected,
-        failure.error
-      )
-    }
+    assertAllSucceeded(results)
 
     return { results: { results } }
   }
@@ -1068,25 +1179,23 @@ export class PerpsClient {
   /**
    * Sign and submit one pre-staged setup `ActionStep` end-to-end.
    *
-   * The caller is expected to have already obtained the step from a prior
-   * {@link checkSetup} call (typically cached by the widget's react-query) —
-   * we do NOT refetch. This avoids the double `createAction` round-trip and
-   * keeps the nonce that was allocated at staging time committed all the way
-   * through submit. If the cached step has gone stale (Lighter's `/nextNonce`
-   * advanced underneath us), `executeProviderSetup` will surface a nonce
-   * conflict that the caller invalidates on, refetches `checkSetup`, and
-   * retries with a fresh step.
+   * `step` and `checklist` must come from the same {@link checkSetup} result.
+   * This preserves the nonce allocated while staging and validates sequence
+   * prerequisites against that same snapshot, without another `createAction`
+   * round-trip.
    *
    * @throws {PerpsError} When the step's action is not in the provider's
-   *   `setup` descriptors.
+   *   `setup` descriptors, or when a lower-`sequence` step on the same
+   *   checklist, a choice included, is still unsatisfied.
    * @public
    */
   async executeProviderSetupAction(params: {
     provider: string
     address: Address
     step: ActionStep
+    checklist: SetupChecklistItem[]
   }): Promise<void> {
-    const { provider, address, step } = params
+    const { provider, address, step, checklist } = params
 
     const metadata = await this.getProviderMetadata(provider)
     const descriptor = metadata.setup.find((d) => d.type === step.action)
@@ -1097,6 +1206,17 @@ export class PerpsClient {
       )
     }
 
+    const blockingStep = checklist.find(
+      (item) =>
+        !item.satisfied && sequenceOf(item.descriptor) < sequenceOf(descriptor)
+    )
+    if (blockingStep) {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `Setup step '${step.action}' for '${provider}' is blocked: '${blockingStep.descriptor.type}' runs first and is not satisfied.`
+      )
+    }
+
     const signed = await this.signProviderSetupAction(provider, address, step)
 
     // A client-executed setup action (Lighter SET_REFERRAL) produces no
@@ -1115,22 +1235,13 @@ export class PerpsClient {
   }
 
   /**
-   * Sign and submit a single provider-option change (a `Provider.options`
-   * tunable such as Lighter `ACCOUNT_TYPE` or Hyperliquid `ACCOUNT_MODE`)
-   * end-to-end, throwing on a venue rejection.
+   * Execute one option of a choice setup step (Lighter `ACCOUNT_TYPE`,
+   * Hyperliquid `ACCOUNT_MODE`) end-to-end with its bound `{ type, params }`,
+   * throwing on a venue rejection.
    *
-   * Options are dispatched through the same {@link execute} pipeline as
-   * trades, but unlike a trade an option change is a single mandatory action:
+   * The option runs through the same {@link execute} pipeline as a trade, but
    * a per-action `success: false` (returned as a 200 OK) means the user's
-   * selection was rejected and must surface, not be silently dropped. This
-   * wrapper inspects the result and throws a {@link PerpsError} carrying the
-   * venue `error`, giving options the same throw contract that setup has via
-   * {@link executeProviderSetupAction}. The only structural difference is that
-   * an option carries `params` (the selected value) rather than a pre-staged
-   * step.
-   *
-   * `execute` itself is unchanged — it still returns results without throwing,
-   * which the trade hooks rely on for partial-fill handling.
+   * selection was rejected and must surface, not be silently dropped.
    *
    * @throws {PerpsError} Carrying the venue error when any returned result has
    *   `success: false`, under that result's `errorCode` when the backend
@@ -1139,20 +1250,56 @@ export class PerpsClient {
    *   signer, signing failure).
    * @public
    */
-  async executeProviderOption<T extends ActionType>(params: {
+  async executeProviderOption(params: {
     provider: string
     address: Address
-    action: T
-    params: ActionParamsMap[T]
+    option: SetupOption
   }): Promise<void> {
-    const { results } = await this.execute(params)
-    const failure = results.find((r) => !r.success)
-    if (failure) {
+    const { provider, address, option } = params
+    const { results } = await this.execute({
+      provider,
+      address,
+      action: option.type,
+      params: option.params,
+    })
+    assertAllSucceeded(results)
+  }
+
+  /**
+   * Undo a satisfied setup step by executing its `revoke` action through
+   * create, sign and execute, signed with that action's `Provider.actions`
+   * descriptor. The step stages again on the next {@link checkSetup}.
+   *
+   * @throws {PerpsError} `SDKError` when `step.revoke` is `null` or when
+   *   `createAction` stages nothing to revoke; otherwise the errors
+   *   {@link executeProviderOption} throws.
+   * @public
+   */
+  async executeProviderRevoke(params: {
+    provider: string
+    address: Address
+    step: SetupAction
+  }): Promise<void> {
+    const { provider, address, step } = params
+    if (step.revoke === null) {
       throw new PerpsError(
-        failure.errorCode ?? PerpsErrorCode.ExchangeRejected,
-        failure.error
+        PerpsErrorCode.SDKError,
+        `Setup step '${step.type}' for '${provider}' declares no revoke.`
       )
     }
+    const { staged, results } = await this.runAction({
+      provider,
+      address,
+      action: step.revoke,
+      params: {},
+    })
+    if (staged.length === 0) {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `Nothing to revoke for setup step '${step.type}' on '${provider}'.`
+      )
+    }
+    assertAllSucceeded(results)
   }
 
   /**
@@ -1333,6 +1480,18 @@ export class PerpsClient {
      * deposit); called as each leg is submitted and confirmed. */
     onProgress?: (progress: SignActionProgress) => void
   }): Promise<ExecuteActionResponse> {
+    const { results } = await this.runAction(params)
+    return { results }
+  }
+
+  /** {@link execute}, also returning the steps `createAction` staged. */
+  private async runAction<T extends ActionType>(params: {
+    provider: string
+    address: Address
+    action: T
+    params: ActionParamsMap[T]
+    onProgress?: (progress: SignActionProgress) => void
+  }): Promise<{ staged: ActionStep[]; results: ActionResult[] }> {
     const { provider, address, action, onProgress } = params
     const metadata = await this.getProviderMetadata(provider)
     const descriptor = findActionDescriptor(metadata, action)
@@ -1363,7 +1522,7 @@ export class PerpsClient {
     // token-authenticated venue mutations), leaving no backend-bound step. With
     // nothing to submit, skip the `/executeAction` hop.
     if (signedActions.length === 0) {
-      return { results: [] }
+      return { staged: actions, results: [] }
     }
 
     const response = await executeAction(this.sdkClient, {
@@ -1380,7 +1539,7 @@ export class PerpsClient {
 
     await this.notifyExecuteResults(provider, address, results)
 
-    return { results }
+    return { staged: actions, results }
   }
 
   /**