@lifi/perps-sdk 18.0.0 → 19.0.0

package/dist/esm/client/PerpsClient.js

@@ -1,4 +1,4 @@
-import { ActionType, META_PROVIDER, PerpsErrorCode, PerpsSigner, SigningMethod, } from '@lifi/perps-types';
+import { ActionRelay, ActionType, META_PROVIDER, PerpsErrorCode, PerpsSigner, SigningMethod, } from '@lifi/perps-types';
 import Big from 'big.js';
 import { PerpsError } from '../errors/PerpsError.js';
 import { getAssetRegistry, toAssetDisplay } from '../registry/assetRegistry.js';
@@ -9,10 +9,95 @@ import { getAccount as fetchAccount } from '../services/getAccount.js';
 import { getOrder as fetchOrder, } from '../services/getOrder.js';
 import { getOrders as fetchOrders, } from '../services/getOrders.js';
 import { getProviders } from '../services/getProviders.js';
+import { isUserFacingSetupStep } from '../utils/setupActions.js';
 import { signTypedDataWithSigner } from '../utils/signTypedData.js';
 import { eip712DomainChainId, switchSigningChain, userEip712TargetChainId, } from '../utils/switchChain.js';
 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) {
+    return descriptor.sequence ?? Number.MAX_SAFE_INTEGER;
+}
+const SIGNERS = new Set(Object.values(PerpsSigner));
+const RELAYS = 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) {
+    const reject = (step, problem) => {
+        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) {
+    return descriptor.options === null && descriptor.signer === PerpsSigner.USER;
+}
+function satisfiedTypes(settings) {
+    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, settings) {
+    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, settings) {
+    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) {
+    const failure = results.find((r) => !r.success);
+    if (failure) {
+        throw new PerpsError(failure.errorCode ?? PerpsErrorCode.ExchangeRejected, failure.error);
+    }
+}
 function isNonNegativeDecimal(value) {
     try {
         return new Big(value).gte(0);
@@ -26,11 +111,7 @@ function isNonNegativeDecimal(value) {
  * action isn't declared — defensive: better to fail loudly than to mis-sign.
  */
 function findActionDescriptor(metadata, action) {
-    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, `Provider '${metadata.key}' does not declare action '${action}'.`);
     }
@@ -82,7 +163,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
      */
@@ -113,20 +194,20 @@ export class PerpsClient {
         return this.sdkClient;
     }
     async getProviderMetadata(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, `Unsupported provider: ${provider}`);
             error.tool = '@lifi/perps-sdk';
             throw error;
         }
+        assertSetupContract(metadata);
         return metadata;
     }
     /**
@@ -149,7 +230,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.
      */
@@ -158,15 +239,15 @@ export class PerpsClient {
         if (typeof plugin.resolveActionRequest !== 'function') {
             return {};
         }
-        return plugin.resolveActionRequest(descriptor.type, address, descriptor.signers);
+        return plugin.resolveActionRequest(descriptor.type, address, 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,
@@ -250,9 +331,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.
      *
@@ -266,7 +347,7 @@ export class PerpsClient {
      * `sdkClient.userWallet`.
      */
     buildSignActionsContext(descriptor, userWallet, onProgress) {
-        const ctx = { signers: descriptor.signers };
+        const ctx = { signer: descriptor.signer };
         if (onProgress !== undefined) {
             ctx.onProgress = onProgress;
         }
@@ -321,7 +402,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`.
      *
@@ -335,7 +416,7 @@ 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 };
     }
     /**
@@ -436,6 +517,20 @@ export class PerpsClient {
         const plugin = this.requireProvider(params.provider);
         return plugin.getDepositFlow?.({ address: params.address });
     }
+    /**
+     * The withdrawal flow for `params.address` at `params.provider`, delegated to
+     * the provider plugin — the withdrawal destination and any setup gate before
+     * it are venue-owned.
+     *
+     * @returns `undefined` when the registered plugin declares no withdrawal flow.
+     * @throws {PerpsError} When the provider plugin is not registered, or the
+     *   plugin's flow resolution fails.
+     * @public
+     */
+    async getWithdrawFlow(params) {
+        const plugin = this.requireProvider(params.provider);
+        return plugin.getWithdrawFlow?.({ address: params.address });
+    }
     /**
      * The `(asset, route)` selections `params.address` can actually withdraw at
      * `params.provider`. The venue owns how its balances split across routes;
@@ -511,15 +606,17 @@ export class PerpsClient {
         return plugin.getPortfolioHistory({ address: params.address, range: params.range }, options);
     }
     /**
-     * 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
      */
@@ -540,61 +637,58 @@ export class PerpsClient {
                 checklist: [],
             };
         }
-        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) => 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
         // signer-bearing request fields.
-        const actions = await this.buildProviderSetupActions(provider, address, visibleSetup);
+        const actions = await this.buildProviderSetupActions(provider, address, stageable);
         // A staged step is one the build produced actions for — a pending
         // descriptor the backend staged nothing for is either satisfied
         // (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) => descriptor.sequence ?? Number.MAX_SAFE_INTEGER;
         const checklist = metadata.setup
-            .filter((descriptor) => descriptor.signers.includes(PerpsSigner.USER))
-            .filter((descriptor) => !conditionalTypes.has(descriptor.type) ||
+            .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(provider, address, pendingSetup.filter(isInternal), visibleSetup.filter((descriptor) => stagedTypes.has(descriptor.type)));
+        await this.drainSetup(provider, address, 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.
      */
-    async resolveSatisfiedSetup(provider, address) {
+    async resolveSetupSettings(provider, address) {
         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
@@ -603,11 +697,10 @@ export class PerpsClient {
      * blocks setup — the step stays unsatisfied and is retried on a later
      * `checkSetup`.
      */
-    async drainInternalSetup(provider, address, internalPending, stagedVisible) {
-        const sequenceOf = (descriptor) => descriptor.sequence ?? Number.MAX_SAFE_INTEGER;
-        for (const descriptor of internalPending) {
+    async drainSetup(provider, address, drainable, stagedVisible) {
+        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));
             if (blocked) {
                 continue;
@@ -629,7 +722,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.`, error);
+                console.debug(`[perps-sdk] setup step '${descriptor.type}' for '${provider}' did not drain; will retry on the next checkSetup.`, error);
             }
         }
     }
@@ -666,16 +759,18 @@ 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
      */
     async buildProviderSetup(params) {
         const { provider, address } = params;
         const metadata = await this.getProviderMetadata(provider);
-        const actions = await this.buildProviderSetupActions(provider, address, metadata.setup);
+        const actions = await this.buildProviderSetupActions(provider, address, metadata.setup.filter(isStageable));
         return { actions };
     }
     /**
@@ -704,35 +799,33 @@ export class PerpsClient {
         });
         const results = this.resolveExplorerLinks(provider, response.results);
         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 } };
     }
     /**
      * 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) {
-        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);
         if (!descriptor) {
             throw new PerpsError(PerpsErrorCode.SDKError, `Action '${step.action}' is not in '${provider}'.setup`);
         }
+        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
         // backend-bound step — it already ran during signing, so there is nothing
@@ -748,22 +841,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
@@ -773,11 +857,40 @@ export class PerpsClient {
      * @public
      */
     async executeProviderOption(params) {
-        const { results } = await this.execute(params);
-        const failure = results.find((r) => !r.success);
-        if (failure) {
-            throw new PerpsError(failure.errorCode ?? PerpsErrorCode.ExchangeRejected, failure.error);
+        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) {
+        const { provider, address, step } = params;
+        if (step.revoke === null) {
+            throw new PerpsError(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);
     }
     /**
      * Place a market or limit order. Convenience wrapper over {@link execute}
@@ -922,6 +1035,11 @@ export class PerpsClient {
      * @public
      */
     async execute(params) {
+        const { results } = await this.runAction(params);
+        return { results };
+    }
+    /** {@link execute}, also returning the steps `createAction` staged. */
+    async runAction(params) {
         const { provider, address, action, onProgress } = params;
         const metadata = await this.getProviderMetadata(provider);
         const descriptor = findActionDescriptor(metadata, action);
@@ -941,7 +1059,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, {
             provider,
@@ -954,7 +1072,7 @@ export class PerpsClient {
         });
         const results = this.resolveExplorerLinks(provider, response.results);
         await this.notifyExecuteResults(provider, address, results);
-        return { results };
+        return { staged: actions, results };
     }
     /**
      * Accept the current terms and, when a code is supplied and the backend