@lifi/perps-sdk 0.2.0-alpha.0 → 1.0.0

package/dist/esm/client/PerpsClient.js

@@ -1,17 +1,11 @@
-import { ActionType, PerpsErrorCode, PerpsSigner, SigningMethod, } from '@lifi/perps-types';
-import { parseAbi } from 'viem';
-import { localStorageAdapter } from '../agent/storage.js';
+import { ActionType, PerpsErrorCode } from '@lifi/perps-types';
 import { PerpsError } from '../errors/PerpsError.js';
 import { createAction } from '../services/createAction.js';
 import { executeAction } from '../services/executeAction.js';
-import { getAccount } from '../services/getAccount.js';
+import { getAccount as fetchAccount } from '../services/getAccount.js';
 import { getProviders } from '../services/getProviders.js';
-import { DEFAULT_API_KEY_INDEX, LighterKeyStore, LighterReadOnlyTokenManager, LighterSigner, walletClientSigner, } from '../signers/lighter/index.js';
-import { signTypedData, signTypedDataWithSigner, } from '../utils/signTypedData.js';
 import { createPerpsClient } from './createPerpsClient.js';
-import { projectAccountConfigSettings } from './projectAccountConfigSettings.js';
-import { SigningMode, } from './types.js';
-const MAX_NONCE_RETRIES = 3;
+import { requireProvider as resolveProvider } from './requireProvider.js';
 /**
  * Look up an action's descriptor in the provider's metadata. Throws if the
  * action isn't declared — defensive: better to fail loudly than to mis-sign.
@@ -27,71 +21,48 @@ function findActionDescriptor(metadata, action) {
     }
     return descriptor;
 }
+/**
+ * The primary high-level perps API: wraps a {@link PerpsSDKClient} and owns the
+ * end-to-end signing pipeline for provider setup, orders, and account-level
+ * actions. Construct via `new PerpsClient(options)` or the SDK's higher-level
+ * wiring.
+ *
+ * @public
+ */
 export class PerpsClient {
     sdkClient;
-    storage;
-    signingModes = new Map();
     providerMetadataCache = new Map();
-    _signer;
-    lighterConfig;
-    lighterReadOnlyTokenOptions;
-    _lighterSigner;
-    _lighterKeyStore;
-    _lighterReadOnlyTokenManager;
+    _userWallet;
     constructor(options) {
-        this.storage = options.storage ?? localStorageAdapter;
-        this.lighterConfig = options.lighter;
-        this.lighterReadOnlyTokenOptions = options.lighterReadOnlyToken;
         this.sdkClient = createPerpsClient({
             integrator: options.integrator,
             apiKey: options.apiKey,
             apiUrl: options.apiUrl,
-            storage: this.storage,
             providers: options.providers,
         });
     }
-    getLighterSigner() {
-        if (!this._lighterSigner) {
-            this._lighterSigner = new LighterSigner(this.lighterConfig);
-        }
-        return this._lighterSigner;
-    }
-    getLighterKeyStore() {
-        if (!this._lighterKeyStore) {
-            this._lighterKeyStore = new LighterKeyStore(this.storage);
-        }
-        return this._lighterKeyStore;
-    }
-    getLighterReadOnlyTokenManager() {
-        if (!this._lighterReadOnlyTokenManager) {
-            this._lighterReadOnlyTokenManager = new LighterReadOnlyTokenManager({
-                storage: this.storage,
-                ...this.lighterReadOnlyTokenOptions,
-            });
-        }
-        return this._lighterReadOnlyTokenManager;
-    }
     /**
-     * Set or update the wallet signer. Used whenever an action's descriptor
+     * 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.
+     *
+     * @public
      */
-    setSigner(signer) {
-        this._signer = signer;
-        // Override the signer on the sdkClient
-        Object.defineProperty(this.sdkClient, 'signer', {
-            get: () => this._signer,
+    setUserWallet(userWallet) {
+        this._userWallet = userWallet;
+        Object.defineProperty(this.sdkClient, 'userWallet', {
+            get: () => this._userWallet,
             configurable: true,
         });
     }
+    /**
+     * The underlying low-level {@link PerpsSDKClient} (config, user wallet,
+     * provider registry) backing this instance.
+     *
+     * @public
+     */
     get client() {
         return this.sdkClient;
     }
-    modeKey(address, provider) {
-        return `${address.toLowerCase()}:${provider.toLowerCase()}`;
-    }
-    signingModeStorageKey(address, provider) {
-        return `lifi-perps-mode:${address.toLowerCase()}:${provider.toLowerCase()}`;
-    }
     async getProviderMetadata(provider) {
         const cached = this.providerMetadataCache.get(provider);
         if (cached) {
@@ -110,524 +81,134 @@ export class PerpsClient {
         return metadata;
     }
     /**
-     * Action types that require explicit user input (a chosen mode or tier)
-     * and therefore cannot be bulk-staged through `buildPrerequisites` with
-     * empty params. Callers must dispatch these via `execute(...)` once a
-     * value is picked. The post-`APPROVE_AGENT` auto-upgrade path also
-     * dispatches `ACCOUNT_MODE` directly with `mode: 'unifiedAccount'`.
+     * Resolve the registered provider plugin for `provider`, throwing a
+     * `PerpsError` when the caller has not registered one via the SDK's
+     * `providers` option. The plugin owns signer identity and write-side signing.
      */
-    static EXPLICIT_INPUT_PREREQUISITES = new Set([ActionType.ACCOUNT_MODE, ActionType.ACCOUNT_TYPE]);
-    buildPrerequisiteInputs(prerequisites, mode, agentAddress) {
-        return prerequisites
-            .filter((p) => {
-            // ACCOUNT_MODE / ACCOUNT_TYPE require explicit params; they're
-            // dispatched separately via `execute(...)` (or the post-APPROVE_AGENT
-            // auto-upgrade chain) rather than bulk-staged.
-            if (PerpsClient.EXPLICIT_INPUT_PREREQUISITES.has(p.type)) {
-                return false;
-            }
-            if (mode === SigningMode.USER) {
-                // USER mode: only items the user can sign, and never APPROVE_AGENT
-                // (no agent is created in this mode).
-                if (!p.signers.includes(PerpsSigner.USER)) {
-                    return false;
-                }
-                if (p.type === ActionType.APPROVE_AGENT) {
-                    return false;
-                }
-                return true;
-            }
-            // USER_AGENT mode: include every remaining declared prerequisite.
-            return true;
-        })
-            .map((p) => {
-            const params = {};
-            if (p.type === ActionType.APPROVE_AGENT && agentAddress) {
-                params.agentAddress = agentAddress;
-            }
-            return {
-                key: p.type,
-                ...(Object.keys(params).length > 0 ? { params } : {}),
-            };
-        });
-    }
-    async resolveSignerForAction(action, address, provider) {
-        const mode = await this.loadSigningMode(address, provider);
-        if (mode !== SigningMode.USER_AGENT) {
-            return undefined;
-        }
-        // Only AGENT-signed actions surface a distinct signerAddress on the wire.
-        // API_KEY signers (e.g. Lighter's LighterKeyStore) are managed per-provider
-        // and don't have an EVM address — the backend identifies the action by the
-        // L1 `address` instead.
-        const metadata = await this.getProviderMetadata(provider);
-        const allActions = [
-            ...metadata.setup,
-            ...metadata.options,
-            ...metadata.actions,
-        ];
-        const descriptor = allActions.find((d) => d.type === action);
-        if (!descriptor?.signers.includes(PerpsSigner.AGENT)) {
-            return undefined;
-        }
-        const agent = await this.sdkClient.agentManager.getAgent(address, provider);
-        return agent.address;
+    requireProvider(provider) {
+        return resolveProvider(this.sdkClient, provider);
     }
     /**
-     * True if any descriptor for the provider lists `PerpsSigner.AGENT`.
-     * Providers like Lighter sign with their own keystore and never need an
-     * AgentManager-managed agent.
+     * 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
+     * plugin signs as the user or with a non-EVM credential. Core constructs no
+     * `signerAddress` itself; signer identity is plugin-owned.
      */
-    async providerUsesAgent(provider) {
-        const metadata = await this.getProviderMetadata(provider);
-        const all = [...metadata.setup, ...metadata.options, ...metadata.actions];
-        return all.some((d) => d.signers.includes(PerpsSigner.AGENT));
-    }
-    async autoSignAndExecute(provider, address, action, actions, descriptor) {
-        switch (descriptor.signingMethod) {
-            case SigningMethod.EIP712: {
-                const eip712Actions = actions;
-                if (descriptor.signers.includes(PerpsSigner.AGENT)) {
-                    const agent = await this.sdkClient.agentManager.getAgent(address, provider);
-                    const signedActions = await Promise.all(eip712Actions.map(async (a) => ({
-                        action: a.action,
-                        typedData: a.typedData,
-                        signature: await signTypedData(agent.privateKey, a.typedData),
-                    })));
-                    return executeAction(this.sdkClient, {
-                        provider,
-                        address,
-                        signerAddress: agent.address,
-                        action,
-                        actions: signedActions,
-                    });
-                }
-                if (descriptor.signers.includes(PerpsSigner.USER)) {
-                    const signer = this.sdkClient.signer;
-                    if (!signer) {
-                        throw new PerpsError(PerpsErrorCode.SDKError, `Action '${action}' requires a user-wallet signature, but no signer was configured. Pass a WalletClient to createPerpsClient({ signer }).`);
-                    }
-                    const signedActions = await Promise.all(eip712Actions.map(async (a) => ({
-                        action: a.action,
-                        typedData: a.typedData,
-                        signature: await signTypedDataWithSigner(signer, a.typedData),
-                    })));
-                    return executeAction(this.sdkClient, {
-                        provider,
-                        address,
-                        signerAddress: address,
-                        action,
-                        actions: signedActions,
-                    });
-                }
-                throw new PerpsError(PerpsErrorCode.SDKError, `Action '${action}' descriptor names no supported signer (signers=[${descriptor.signers.join(', ')}]).`);
-            }
-            case SigningMethod.WASM_BLOB: {
-                const wasmActions = actions;
-                const signedActions = await this.signWasmBlobActions(provider, address, wasmActions);
-                return executeAction(this.sdkClient, {
-                    provider,
-                    address,
-                    signerAddress: address,
-                    action,
-                    actions: signedActions,
-                });
-            }
-            case SigningMethod.EVM_TX: {
-                const evmActions = actions;
-                const signedActions = await this.signEvmTxActions(evmActions);
-                return executeAction(this.sdkClient, {
-                    provider,
-                    address,
-                    signerAddress: address,
-                    action,
-                    actions: signedActions,
-                });
-            }
-            default:
-                throw new Error(`Unknown signingMethod: ${descriptor.signingMethod}`);
+    async resolveActionRequest(provider, descriptor, address) {
+        const plugin = this.requireProvider(provider);
+        if (typeof plugin.resolveActionRequest !== 'function') {
+            return {};
         }
+        return plugin.resolveActionRequest(descriptor.type, address, descriptor.signers);
     }
     /**
-     * Sign a single prerequisite step using whichever signing path matches the
-     * step's shape — EIP-712 typed data, WASM blob (with the hybrid EIP-191 +
-     * WASM flow for REGISTER_API_KEY), or EVM transaction. Lets consumers
-     * collect signed prereqs without embedding per-method signing logic.
+     * Delegate signing of `actions` to the provider plugin. The plugin owns
+     * every signing arm and branches on the descriptor's `signers` internally,
+     * reading the end-user's wallet from the {@link SignActionsContext} when an
+     * arm signs as the user.
      */
-    async signPrerequisite(provider, address, step) {
-        if ('typedData' in step) {
-            if (!this.sdkClient.signer) {
-                throw new PerpsError(PerpsErrorCode.SDKError, 'EIP-712 prerequisite signing requires a wallet signer. Pass ' +
-                    '`signer` to createPerpsClient or call setSigner(walletClient).');
-            }
-            return {
-                action: step.action,
-                typedData: step.typedData,
-                signature: await signTypedDataWithSigner(this.sdkClient.signer, step.typedData),
-            };
-        }
-        if ('wasmSignParams' in step) {
-            const [signed] = await this.signWasmBlobActions(provider, address, [step]);
-            return signed;
+    async delegateSignActions(provider, address, descriptor, actions) {
+        const plugin = this.requireProvider(provider);
+        if (typeof plugin.signActions !== 'function') {
+            throw new PerpsError(PerpsErrorCode.SDKError, `Provider '${provider}' does not implement signActions for ` +
+                `signingMethod '${descriptor.signingMethod}'.`);
         }
-        if ('txParams' in step) {
-            const [signed] = await this.signEvmTxActions([step]);
-            return signed;
-        }
-        throw new PerpsError(PerpsErrorCode.SDKError, 'Unknown ActionStep shape — expected typedData, wasmSignParams, or txParams.');
+        return plugin.signActions(descriptor.signingMethod, actions, address, this.buildSignActionsContext(descriptor));
     }
     /**
-     * Sign and broadcast a sequence of EVM transactions via the user's wallet
-     * client. Steps are submitted serially so a later step (e.g. deposit) can
-     * rely on an earlier step (e.g. approve) having mined. Each step's
-     * `txParams` carries chainId, target, function name, args, and a
-     * human-readable abi from the backend.
+     * 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
+     * keypair, Lighter's API key) are resolved inside the provider's
+     * `signActions`, not threaded through here.
      */
-    async signEvmTxActions(actions) {
-        if (!this.sdkClient.signer) {
-            throw new PerpsError(PerpsErrorCode.SDKError, 'EVM_TX signing requires a wallet signer. Pass `signer` to ' +
-                'createPerpsClient or call setSigner(walletClient).');
-        }
-        const { signer } = this.sdkClient;
-        const signed = [];
-        for (const step of actions) {
-            const params = step.txParams;
-            const txHash = await signer.writeContract({
-                address: params.to,
-                abi: parseAbi(params.abi),
-                functionName: params.functionName,
-                args: params.args,
-                chain: signer.chain,
-                account: signer.account,
-            });
-            signed.push({
-                action: step.action,
-                txParams: step.txParams,
-                txHash,
-            });
+    buildSignActionsContext(descriptor) {
+        const ctx = { signers: descriptor.signers };
+        if (this.sdkClient.userWallet !== undefined) {
+            ctx.userWallet = this.sdkClient.userWallet;
         }
-        return signed;
+        return ctx;
     }
     /**
-     * Sign a batch of WASM_BLOB action steps (Lighter). Ensures the user's
-     * Lighter API keypair is registered first — generating one and running the
-     * REGISTER_API_KEY hybrid flow via the L1 signer if not — then feeds each
-     * subsequent step through the WASM signer and returns signed blobs.
+     * Sign a single provider setup action step by delegating to the provider
+     * plugin, which branches on the step's signing scheme internally. Lets
+     * consumers collect signed setup actions without embedding per-method
+     * signing logic.
      *
-     * `ACCOUNT_TYPE` (Lighter `/api/v1/changeAccountTier`) is dispatched as a
-     * WASM_BLOB envelope by the backend but is NOT a wasm-signed transaction —
-     * Lighter authenticates the endpoint with an auth token and enforces
-     * anti-replay server-side (24h cooldown, no open positions). The signer
-     * mints a Lighter auth token via the same WASM `CreateAuthToken` the read
-     * endpoints use and parks it in `signedTx.txInfo`; the backend's
-     * `executeChangeAccountTier` consumes that field as the `auth` form
-     * parameter. `txType`/`txHash` are unused for this action — they carry
-     * placeholder values to satisfy the `WasmBlobSignedActionStep` shape.
+     * @throws {PerpsError} When the step's action is not declared by the provider.
+     * @public
      */
-    async signWasmBlobActions(provider, address, actions) {
-        const signed = [];
-        for (const step of actions) {
-            if (step.action === ActionType.REGISTER_API_KEY) {
-                signed.push(await this.signRegisterApiKey(provider, address, step));
-            }
-            else if (step.action === ActionType.ACCOUNT_TYPE) {
-                signed.push(await this.signAccountTierChange(address, step));
-            }
-            else {
-                signed.push(await this.signStandardWasmAction(provider, address, step));
-            }
-        }
+    async signProviderSetupAction(provider, address, step) {
+        const metadata = await this.getProviderMetadata(provider);
+        const descriptor = findActionDescriptor(metadata, step.action);
+        const [signed] = await this.delegateSignActions(provider, address, descriptor, [step]);
         return signed;
     }
-    async signStandardWasmAction(provider, address, step) {
-        const apiKey = await this.getLighterKeyStore().get(address);
-        if (!apiKey) {
-            throw new PerpsError(PerpsErrorCode.SDKError, `No Lighter API key registered for ${address}. ` +
-                'Run prepareAccount / REGISTER_API_KEY first.');
-        }
-        const signer = this.getLighterSigner();
-        const signedTx = await signer.sign(step.action, step.wasmSignParams, {
-            apiKeyPrivateKey: apiKey.apiKeyPrivateKey,
-            apiKeyIndex: apiKey.apiKeyIndex,
-            accountIndex: apiKey.accountIndex,
-        });
-        void provider;
-        return {
-            action: step.action,
-            wasmSignParams: step.wasmSignParams,
-            signedTx,
-        };
-    }
-    /**
-     * REGISTER_API_KEY flow:
-     *   1. Look up the user's Lighter accountIndex from getAccount()
-     *   2. Generate a fresh Lighter API keypair via the WASM signer
-     *   3. Call SignChangePubKey to produce the WASM blob + EIP-191 message
-     *   4. Have the user's L1 Ethereum wallet sign the message
-     *   5. Inject the L1 signature into the ChangePubKey txInfo JSON
-     *   6. Persist the keypair and return the signed blob
-     *
-     * Requires a USER wallet signer to be set via `setSigner` or passed at
-     * construction — the L1 signature is the user's consent to rotate keys.
-     */
-    async signRegisterApiKey(provider, address, step) {
-        if (!this.sdkClient.signer) {
-            throw new PerpsError(PerpsErrorCode.SDKError, 'REGISTER_API_KEY requires a wallet signer — pass `signer` to ' +
-                'createPerpsClient or call setSigner(walletClient).');
-        }
-        const params = step.wasmSignParams;
-        const apiKeyIndex = params.api_key_index ?? DEFAULT_API_KEY_INDEX;
-        const nonce = params.nonce;
-        if (typeof nonce !== 'number') {
-            throw new PerpsError(PerpsErrorCode.SDKError, 'REGISTER_API_KEY wasmSignParams is missing `nonce`.');
-        }
-        const account = await getAccount(this.sdkClient, { provider, address });
-        if (account.config.provider !== 'lighter') {
-            throw new PerpsError(PerpsErrorCode.SDKError, `REGISTER_API_KEY requires a Lighter account, but getAccount ` +
-                `returned config for provider '${account.config.provider}'.`);
-        }
-        const accountIndex = account.config.accountIndex;
-        const signer = this.getLighterSigner();
-        const keypair = await signer.generateAPIKey();
-        const changePubKey = await signer.signChangePubKey(keypair.publicKey, keypair.privateKey, nonce, apiKeyIndex, accountIndex);
-        const l1Signature = await this.sdkClient.signer.signMessage({
-            account: this.sdkClient.signer.account,
-            message: changePubKey.messageToSign,
-        });
-        const txInfoWithL1Sig = signer.embedL1Signature(changePubKey.txInfo, l1Signature);
-        const apiKey = {
-            accountIndex,
-            apiKeyIndex,
-            apiKeyPrivateKey: keypair.privateKey,
-            apiKeyPublicKey: keypair.publicKey,
-        };
-        await this.getLighterKeyStore().set(address, apiKey);
-        return {
-            action: step.action,
-            wasmSignParams: {
-                ...step.wasmSignParams,
-                new_public_key: keypair.publicKey,
-            },
-            signedTx: {
-                txType: changePubKey.txType,
-                txInfo: txInfoWithL1Sig,
-                txHash: changePubKey.txHash,
-            },
-        };
-    }
-    /**
-     * Sign an `ACCOUNT_TYPE` step (Lighter `changeAccountTier`).
-     *
-     * Lighter's `/api/v1/changeAccountTier` is an HTTP-only mutation —
-     * Lighter does NOT consume a wasm-signed transaction here; it
-     * authenticates the request with the same auth token its read endpoints
-     * use, and enforces anti-replay business rules server-side. The backend
-     * therefore declares the step as a `WasmBlobActionStep` with
-     * `wasmSignParams.kind = 'changeAccountTier'` and expects the SDK to
-     * mint an auth token in lieu of a transaction signature. That contract
-     * is documented in `lifi-perps-backend/src/providers/lighter/actions/
-     * lighter.actions.accountType.ts` and consumed by `executeChangeAccountTier`.
-     *
-     * The auth-token deadline mirrors {@link createLighterAuthToken}'s 1h
-     * default — Lighter caps tokens at 8h hard, and the backend's executor
-     * runs `verifyPendingAction` then a single `/changeAccountTier` POST,
-     * which completes well inside an hour.
-     */
-    async signAccountTierChange(address, step) {
-        const apiKey = await this.getLighterKeyStore().get(address);
-        if (!apiKey) {
-            throw new PerpsError(PerpsErrorCode.SDKError, `No Lighter API key registered for ${address}. ` +
-                'Run prepareAccount / REGISTER_API_KEY first.');
-        }
-        const signer = this.getLighterSigner();
-        const deadline = Math.floor(Date.now() / 1000) + 60 * 60;
-        const authToken = await signer.createAuthToken(deadline, {
-            apiKeyPrivateKey: apiKey.apiKeyPrivateKey,
-            apiKeyIndex: apiKey.apiKeyIndex,
-            accountIndex: apiKey.accountIndex,
-        });
-        return {
-            action: step.action,
-            wasmSignParams: step.wasmSignParams,
-            signedTx: {
-                // `/changeAccountTier` reads only `txInfo` (the auth token); `txType`
-                // and `txHash` are placeholders to satisfy the envelope shape.
-                txType: 0,
-                txInfo: authToken,
-                txHash: '',
-            },
-        };
-    }
     /**
-     * Return a bearer token that authenticates Lighter's read endpoints
-     * (getOrders, getOrder, getActivity, getFills).
+     * Build (but do not sign or submit) the unsigned action steps for `action`,
+     * letting the provider plugin contribute any signer-bearing request fields.
      *
-     * Resolution order:
-     *   1. The long-lived read-only token persisted by `approveReadOnlyToken`,
-     *      when one is stored for this `(address, accountIndex)` AND has not
-     *      passed its recorded `expiry`. The SDK never returns an expired
-     *      stored token.
-     *   2. A freshly minted 8h Lighter auth token, signed off the user's
-     *      Lighter API key. Requires `REGISTER_API_KEY` to have completed.
-     *   3. `undefined` — caller falls back to public reads.
-     *
-     * `accountIndex` lets callers in pure read-only mode (no API key
-     * registered) target the RO token. When omitted, the SDK derives it from
-     * the user's registered API key.
-     *
-     * `deadlineSeconds` only affects the standard-token fallback (Lighter caps
-     * those tokens at 8h). Read-only tokens carry their own mint-time expiry
-     * recorded by {@link approveReadOnlyToken}.
+     * @public
      */
-    async createLighterAuthToken(address, deadlineSeconds, accountIndex) {
-        const apiKey = await this.getLighterKeyStore().get(address);
-        const resolvedAccountIndex = accountIndex ?? apiKey?.accountIndex;
-        if (resolvedAccountIndex !== undefined) {
-            const stored = await this.getLighterReadOnlyTokenManager().get(address, resolvedAccountIndex);
-            if (stored) {
-                return stored.token;
-            }
-        }
-        if (!apiKey) {
-            return undefined;
-        }
-        const deadline = deadlineSeconds ?? Math.floor(Date.now() / 1000) + 60 * 60;
-        const signer = this.getLighterSigner();
-        return signer.createAuthToken(deadline, {
-            apiKeyPrivateKey: apiKey.apiKeyPrivateKey,
-            apiKeyIndex: apiKey.apiKeyIndex,
-            accountIndex: apiKey.accountIndex,
-        });
-    }
-    /**
-     * Mint a long-lived Lighter read-only token via Lighter's
-     * `tokens/create` endpoint and persist it through the configured
-     * `StorageAdapter`, keyed by `(L1 address, accountIndex)`.
-     *
-     * The user's connected wallet signs an EIP-191 message describing the
-     * mint request; the resulting `Authorization` header authenticates the
-     * Lighter HTTP call. The bearer string Lighter returns is persisted
-     * alongside its `expiry` and `scope`; subsequent calls to
-     * {@link createLighterAuthToken} prefer it over the 8h standard token.
-     *
-     * `expirySeconds` is the absolute unix-seconds expiry recorded on
-     * Lighter's row. Lighter enforces 1 day ≤ lifetime ≤ 10 years
-     * server-side; the SDK does NOT pre-validate and surfaces Lighter's 400
-     * verbatim. `scope` defaults to `'all'`; the `'single'` variant is wired
-     * through but only useful when the caller has a specific reason to scope
-     * the token to one account.
-     *
-     * Requires a USER wallet signer to be set via {@link setSigner} or
-     * passed at construction — the L1 signature is the user's consent.
-     */
-    async approveReadOnlyToken(address, params) {
-        if (!this.sdkClient.signer) {
-            throw new PerpsError(PerpsErrorCode.SDKError, 'approveReadOnlyToken requires a wallet signer — pass `signer` to ' +
-                'createPerpsClient or call setSigner(walletClient).');
-        }
-        const signer = walletClientSigner(this.sdkClient.signer);
-        return this.getLighterReadOnlyTokenManager().approve(signer, {
-            address,
-            ...params,
-        });
-    }
-    /**
-     * Whether the stored Lighter read-only token for `(address, accountIndex)`
-     * falls within `thresholdDays` of its `expiry`. Returns `false` when no
-     * token is stored, when the stored token has already expired, or when
-     * more than `thresholdDays` of life remain. Intended for widget renewal
-     * banners (default threshold: 30 days).
-     */
-    async isLighterReadOnlyTokenExpiringSoon(address, accountIndex, thresholdDays) {
-        return this.getLighterReadOnlyTokenManager().isReadOnlyTokenExpiringSoon(address, accountIndex, thresholdDays);
-    }
-    // ---------------------------------------------------------------------------
-    // Generic action helpers
-    // ---------------------------------------------------------------------------
     async buildAction(action, params) {
-        const signerAddress = await this.resolveSignerForAction(action, params.address, params.provider);
+        const metadata = await this.getProviderMetadata(params.provider);
+        const descriptor = findActionDescriptor(metadata, action);
+        const { signerAddress, params: signerParams } = await this.resolveActionRequest(params.provider, descriptor, params.address);
         return createAction(this.sdkClient, {
             provider: params.provider,
             address: params.address,
             signerAddress,
             action,
-            params: params.params,
+            params: {
+                ...params.params,
+                ...signerParams,
+            },
         });
     }
-    // ---------------------------------------------------------------------------
-    // Signing mode management
-    // ---------------------------------------------------------------------------
-    async setSigningMode(address, provider, mode) {
-        const key = this.modeKey(address, provider);
-        this.signingModes.set(key, mode);
-        await this.storage.set(this.signingModeStorageKey(address, provider), mode);
-        if (mode === SigningMode.USER_AGENT &&
-            (await this.providerUsesAgent(provider))) {
-            await this.sdkClient.agentManager.getOrCreateAgent(address, provider);
-        }
-    }
-    getSigningMode(address, provider) {
-        return (this.signingModes.get(this.modeKey(address, provider)) ??
-            SigningMode.USER_AGENT);
-    }
-    async loadSigningMode(address, provider) {
-        const key = this.modeKey(address, provider);
-        if (this.signingModes.has(key)) {
-            return this.signingModes.get(key);
-        }
-        const stored = await this.storage.get(this.signingModeStorageKey(address, provider));
-        const mode = stored === SigningMode.USER_AGENT || stored === SigningMode.USER
-            ? stored
-            : SigningMode.USER_AGENT;
-        this.signingModes.set(key, mode);
-        return mode;
-    }
-    async loadAgentMode(address, provider) {
-        const mode = await this.loadSigningMode(address, provider);
-        return mode === SigningMode.USER_AGENT;
-    }
-    async setAgentMode(address, provider, useAgent) {
-        await this.setSigningMode(address, provider, useAgent ? SigningMode.USER_AGENT : SigningMode.USER);
-    }
-    async getAgentAddress(address, provider) {
-        const agent = await this.sdkClient.agentManager.getAgent(address, provider);
-        return agent.address;
-    }
-    async hasAgent(address, provider) {
-        return this.sdkClient.agentManager.hasAgent(address, provider);
-    }
-    async removeAgent(address, provider) {
-        await this.sdkClient.agentManager.removeAgent(address, provider);
-        this.signingModes.delete(this.modeKey(address, provider));
-        await this.storage.remove(this.signingModeStorageKey(address, provider));
-    }
-    // ---------------------------------------------------------------------------
-    // Account
-    // ---------------------------------------------------------------------------
     /**
      * 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
      * `result.settings` directly without re-deriving values from the typed
      * `AccountConfig`.
+     *
+     * @throws {PerpsError} When the provider plugin is not registered, or the
+     *   backend account fetch fails.
+     * @public
      */
     async getAccount(params) {
+        const plugin = this.requireProvider(params.provider);
         const [response, metadata] = await Promise.all([
-            getAccount(this.sdkClient, params),
+            fetchAccount(this.sdkClient, params),
             this.getProviderMetadata(params.provider),
         ]);
-        const settings = projectAccountConfigSettings(response.config, metadata.setup, metadata.options);
+        const settings = plugin.projectConfig(response.config, metadata.setup, metadata.options);
         return { ...response, settings };
     }
+    /**
+     * Roll an already-fetched {@link AccountResponse} (plus its positions) up
+     * into an {@link AccountSummary}, delegating to the owning provider so the
+     * venue-specific collateral and margin semantics are applied correctly.
+     */
+    getAccountSummary(account, positions) {
+        return this.requireProvider(account.provider).getAccountSummary(account, positions);
+    }
     /**
      * Thin existence check for a provider account at `address`. Returns
      * `true` when `getAccount` resolves, `false` when the backend reports
      * `PerpsErrorCode.AccountNotFound`, and re-throws on any other error
      * (transport failures, validation errors, server errors).
+     *
+     * @throws {PerpsError} On any backend error other than
+     *   `PerpsErrorCode.AccountNotFound`.
+     * @public
      */
     async accountExists(provider, address) {
         try {
-            await getAccount(this.sdkClient, { provider, address });
+            await fetchAccount(this.sdkClient, { provider, address });
             return true;
         }
         catch (err) {
@@ -638,292 +219,185 @@ export class PerpsClient {
             throw err;
         }
     }
-    // ---------------------------------------------------------------------------
-    // Setup
-    // ---------------------------------------------------------------------------
     /**
-     * Return the unsatisfied entries on `Provider.setup` for this account,
-     * split by signer role. Trading is gated on `isReady === true`.
+     * Return the unsatisfied entries on `Provider.setup` for this account as a
+     * flat, self-describing list. Trading is gated on `isReady === true`.
      *
      * `Provider.options` descriptors are NEVER returned here — options are
      * post-setup tunables and never gate trading. Option state is surfaced
      * separately via `getAccount().settings`.
+     *
+     * @public
      */
     async checkSetup(params) {
         const { provider, address } = params;
-        const mode = await this.loadSigningMode(address, provider);
-        const metadata = await this.getProviderMetadata(provider);
-        const usesAgent = [
-            ...metadata.setup,
-            ...metadata.options,
-            ...metadata.actions,
-        ].some((d) => d.signers.includes(PerpsSigner.AGENT));
-        let agentAddress;
-        if (mode === SigningMode.USER_AGENT && usesAgent) {
-            const agent = await this.sdkClient.agentManager.getOrCreateAgent(address, provider);
-            agentAddress = agent.address;
-        }
-        const allInputs = this.buildPrerequisiteInputs(metadata.setup, mode, agentAddress);
-        if (allInputs.length === 0) {
-            return { userPrerequisites: [], agentPrerequisites: [], isReady: true };
-        }
-        // Build a signer lookup from setup descriptors.
-        const signersByAction = new Map();
-        for (const desc of metadata.setup) {
-            signersByAction.set(desc.type, desc.signers);
-        }
-        // Send all to backend via createAction for the first prerequisite type
-        // The backend filters already-satisfied ones and returns typed data
-        const { actions } = await this.buildPrerequisites({
-            provider,
-            address,
-            signerAddress: agentAddress,
-        });
-        if (actions.length === 0) {
-            return { userPrerequisites: [], agentPrerequisites: [], isReady: true };
-        }
-        const userPrerequisites = actions.filter((a) => {
-            const signers = signersByAction.get(a.action) ?? [];
-            return signers.includes(PerpsSigner.USER);
-        });
-        const agentPrerequisites = actions.filter((a) => {
-            const signers = signersByAction.get(a.action) ?? [];
-            return signers.includes(PerpsSigner.AGENT);
-        });
+        // 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.buildProviderSetup({ provider, address });
         return {
-            userPrerequisites,
-            agentPrerequisites,
-            isReady: false,
+            setup: actions,
+            isReady: actions.length === 0,
         };
     }
-    async buildPrerequisites(params) {
-        const mode = await this.loadSigningMode(params.address, params.provider);
-        let { signerAddress } = params;
-        if (mode === SigningMode.USER_AGENT && !signerAddress) {
-            const agent = await this.sdkClient.agentManager.getAgent(params.address, params.provider);
-            signerAddress = agent.address;
-        }
-        const metadata = await this.getProviderMetadata(params.provider);
-        const allInputs = this.buildPrerequisiteInputs(metadata.setup, mode, signerAddress);
-        // Use the first prerequisite type as the action type for the batch
-        // The backend handles all prerequisites in a single createPrerequisite call
+    /**
+     * 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).
+     *
+     * @public
+     */
+    async buildProviderSetup(params) {
+        const { provider, address } = params;
+        const metadata = await this.getProviderMetadata(provider);
+        const orderedSetup = [...metadata.setup].sort((a, b) => (a.sequence ?? Number.MAX_SAFE_INTEGER) -
+            (b.sequence ?? Number.MAX_SAFE_INTEGER));
+        const plugin = this.sdkClient.getProvider(provider);
         const allActions = [];
-        for (const input of allInputs) {
+        for (const descriptor of orderedSetup) {
+            const action = descriptor.type;
+            const { signerAddress, params: signerParams } = await this.resolveActionRequest(provider, descriptor, address);
+            const localParams = plugin?.resolveSetupParams
+                ? await plugin.resolveSetupParams(action, address)
+                : {};
             const { actions } = await createAction(this.sdkClient, {
-                provider: params.provider,
-                address: params.address,
+                provider,
+                address,
                 signerAddress,
-                action: input.key,
-                params: (input.params ?? {}),
+                action,
+                params: {
+                    ...signerParams,
+                    ...localParams,
+                },
             });
             allActions.push(...actions);
         }
         return { actions: allActions };
     }
     /**
-     * Default mode the SDK auto-applies after `APPROVE_AGENT` on a provider
-     * whose `options` array exposes a writable `ACCOUNT_MODE` (today
-     * Hyperliquid). Callers can override this through a subsequent
-     * `ACCOUNT_MODE` dispatch.
+     * Submit the signed setup steps returned by `checkSetup` (and signed by the
+     * caller / `signProviderSetupAction`). Routes the batch on the first step's
+     * action and lets the plugin contribute that action's `signerAddress`.
+     * Throws on any per-step venue rejection.
+     *
+     * @public
      */
-    static DEFAULT_ACCOUNT_MODE = 'unifiedAccount';
+    async executeProviderSetup(params) {
+        const { provider, address, setup, signedActions } = params;
+        if (signedActions.length === 0) {
+            return { results: { results: [] } };
+        }
+        const action = setup[0]?.action ?? signedActions[0].action;
+        const metadata = await this.getProviderMetadata(provider);
+        const descriptor = findActionDescriptor(metadata, action);
+        const { signerAddress } = await this.resolveActionRequest(provider, descriptor, address);
+        const results = await executeAction(this.sdkClient, {
+            provider,
+            address,
+            // The submitting account: the plugin-resolved signer (Hyperliquid's
+            // agent) when present, else the end-user's address.
+            signerAddress: signerAddress ?? address,
+            action,
+            actions: signedActions,
+        });
+        const failure = results.results.find((r) => !r.success);
+        if (failure) {
+            throw new PerpsError(PerpsErrorCode.ExchangeRejected, failure.error);
+        }
+        return { results };
+    }
     /**
-     * Prepare an `ACCOUNT_MODE` change by proactively reading the account's
-     * current `config.abstractionMode` and routing to the correct signer:
+     * Sign and submit one pre-staged setup `ActionStep` end-to-end.
      *
-     * - `abstractionMode == null` (never set, e.g. a fresh HL account):
-     *   the change MAY be performed by the agent signer. Build, sign with
-     *   the agent key, and dispatch. Returns `{ results }`.
-     * - `abstractionMode === mode`: idempotent no-op. Returns an empty
-     *   results envelope without contacting `/createAction` or `/executeAction`.
-     * - `abstractionMode` set to any other value: HL requires a user-wallet
-     *   signature to change the abstraction once it has been set. Build the
-     *   action unsigned and return it as `{ fallback }` so the caller can
-     *   surface a wallet prompt via `fallbackUserPrerequisites`.
+     * 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.
      *
-     * Network errors from `/account` propagate — we never guess the signer.
-     * `account.config.provider !== 'hyperliquid'` also throws: this helper
-     * is HL-specific and the dispatcher should never reach it for another
-     * provider (gated by `hasWritableAccountMode`).
+     * @throws {PerpsError} When the step's action is not in the provider's
+     *   `setup` descriptors.
+     * @public
      */
-    async prepareAccountModeChange(provider, address, mode) {
-        const account = await getAccount(this.sdkClient, { provider, address });
-        if (account.config.provider !== 'hyperliquid') {
-            throw new PerpsError(PerpsErrorCode.SDKError, `prepareAccountModeChange is Hyperliquid-specific, but ` +
-                `getAccount returned config for provider ` +
-                `'${account.config.provider}'.`);
-        }
-        const currentStatus = account.config.abstractionMode;
-        // Idempotent short-circuit: already in the requested mode.
-        if (currentStatus === mode) {
-            return {};
-        }
-        // Never set → the agent is authorised to perform the change.
-        if (currentStatus == null) {
-            const agent = await this.sdkClient.agentManager.getAgent(address, provider);
-            const { actions } = await createAction(this.sdkClient, {
-                provider,
-                address,
-                signerAddress: agent.address,
-                action: ActionType.ACCOUNT_MODE,
-                params: { mode },
-            });
-            if (actions.length === 0) {
-                // Backend's per-mode early-exit (defensive — shouldn't fire given
-                // the short-circuit above, but covers a race between our /account
-                // read and the backend's view of the current status).
-                return { results: { results: [] } };
-            }
-            const signedActions = await Promise.all(actions.map(async (a) => ({
-                action: a.action,
-                typedData: a.typedData,
-                signature: await signTypedData(agent.privateKey, a.typedData),
-            })));
-            const results = await executeAction(this.sdkClient, {
-                provider,
-                address,
-                signerAddress: agent.address,
-                action: ActionType.ACCOUNT_MODE,
-                actions: signedActions,
-            });
-            return { results };
+    async executeProviderSetupAction(params) {
+        const { provider, address, step } = 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`);
         }
-        // Already set to a different mode → HL requires a user-wallet signature.
-        // Build the action unsigned and surface it as a fallback to the caller.
-        const { actions: fallbackActions } = await createAction(this.sdkClient, {
+        const signed = await this.signProviderSetupAction(provider, address, step);
+        await this.executeProviderSetup({
             provider,
             address,
-            action: ActionType.ACCOUNT_MODE,
-            params: { mode },
+            setup: [step],
+            signedActions: [signed],
         });
-        return {
-            fallback: fallbackActions.length > 0 ? fallbackActions : undefined,
-        };
     }
     /**
-     * True when the provider exposes an `ACCOUNT_MODE` descriptor (in `setup`
-     * or `options`) whose `mode` Param has a writable enumeration of values.
-     * Providers that omit `ACCOUNT_MODE` or expose it as read-only / free-form
-     * input return false.
+     * 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.
+     *
+     * Options are dispatched through the same {@link execute} pipeline as
+     * trades, but unlike a trade an option change is a single mandatory action:
+     * 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.
+     *
+     * @throws {PerpsError} `PerpsErrorCode.ExchangeRejected` carrying the venue
+     *   error when any returned result has `success: false`; also the errors
+     *   `execute` itself can throw (unregistered provider, no signer, signing
+     *   failure).
+     * @public
      */
-    static hasWritableAccountMode(metadata) {
-        const item = [...metadata.setup, ...metadata.options].find((i) => i.type === ActionType.ACCOUNT_MODE);
-        if (!item) {
-            return false;
-        }
-        const modeParam = item.params.find((p) => p.name === 'mode');
-        if (!modeParam) {
-            return false;
+    async executeProviderOption(params) {
+        const { results } = await this.execute(params);
+        const failure = results.find((r) => !r.success);
+        if (failure) {
+            throw new PerpsError(PerpsErrorCode.ExchangeRejected, failure.error);
         }
-        // Writable multi-option: `values` enumerates choices and `readOnly`
-        // is not set (treat absence as writable, matching the descriptor
-        // contract in `Param`).
-        if (!modeParam.values || modeParam.values.length === 0) {
-            return false;
-        }
-        return !modeParam.readOnly;
     }
     /**
-     * Submit the signed setup steps returned by `checkSetup` (and seeded
-     * with user-wallet signatures by the caller). Internally splits into:
+     * Place a market or limit order. Convenience wrapper over {@link execute}
+     * with `ActionType.PLACE_ORDER`.
      *
-     *   1. Submit user-signed setup actions.
-     *   2. After a successful `APPROVE_AGENT`, auto-upgrade `ACCOUNT_MODE`
-     *      to the SDK's default when the provider exposes a writable
-     *      `ACCOUNT_MODE` Param (Hyperliquid today). The SDK reads
-     *      `account.config.abstractionMode` to choose the signer: `null` →
-     *      agent dispatch; non-null → wallet fallback returned in
-     *      `fallbackUserPrerequisites`.
-     *   3. Sign and submit any pre-staged agent-side setup actions the
-     *      backend returned alongside the user-signed ones.
+     * @throws {PerpsError} When the provider is unregistered or the action
+     *   cannot be signed/submitted.
+     * @example
+     * ```ts
+     * await client.placeOrder({
+     *   provider: 'hyperliquid',
+     *   address: '0xUser',
+     *   market: { symbol: 'ETH' },
+     *   side: 'buy',
+     *   size: '0.1',
+     * })
+     * ```
+     * @public
      */
-    async satisfySetup(params) {
-        const { provider, address, required, userSignedActions } = params;
-        const mode = await this.loadSigningMode(address, provider);
-        // 1. Submit user-signed prerequisites
-        let userResults = { results: [] };
-        if (userSignedActions.length > 0) {
-            const signerAddress = mode === SigningMode.USER_AGENT
-                ? (await this.sdkClient.agentManager.getAgent(address, provider))
-                    .address
-                : address;
-            // Submit all user-signed actions — use first action's type for routing
-            const firstAction = required.userPrerequisites[0]?.action;
-            userResults = await executeAction(this.sdkClient, {
-                provider,
-                address,
-                signerAddress,
-                action: (firstAction ?? ActionType.APPROVE_AGENT),
-                actions: userSignedActions,
-            });
-            const mandatoryFailure = userResults.results.find((r) => !r.success);
-            if (mandatoryFailure) {
-                return { userResults };
-            }
-        }
-        // 2. Auto-upgrade ACCOUNT_MODE after APPROVE_AGENT.
-        //
-        // When the user-signed setup included a successful APPROVE_AGENT, the
-        // freshly approved agent is now authorised to sign account-level
-        // actions for accounts whose abstraction has never been set. If the
-        // provider exposes a writable `ACCOUNT_MODE` descriptor (Hyperliquid
-        // today), the SDK reads `account.config.abstractionMode` to decide
-        // the signer: `null` → agent-dispatch silently to the SDK's preferred
-        // default; non-null → return a wallet-signing fallback step. Either
-        // way the chain does NOT abort onboarding — `ACCOUNT_MODE` lives on
-        // `Provider.options`, not `Provider.setup`, and so does not gate
-        // trading.
-        let agentResults;
-        let fallbackUserPrerequisites;
-        if (mode === SigningMode.USER_AGENT) {
-            const justApprovedAgent = userResults.results.some((r) => r.success && r.action === ActionType.APPROVE_AGENT);
-            if (justApprovedAgent) {
-                const metadata = await this.getProviderMetadata(provider);
-                if (PerpsClient.hasWritableAccountMode(metadata)) {
-                    const upgrade = await this.prepareAccountModeChange(provider, address, PerpsClient.DEFAULT_ACCOUNT_MODE);
-                    agentResults = upgrade.results;
-                    fallbackUserPrerequisites = upgrade.fallback;
-                }
-            }
-        }
-        // 3. Sign and submit any pre-staged agent prerequisites returned by the
-        //    backend's `buildPrerequisites` call. ACCOUNT_MODE is filtered out of
-        //    bulk staging (it requires explicit `mode` params), so this block
-        //    today only runs for future agent-signed steps the backend chooses
-        //    to stage.
-        if (required.agentPrerequisites.length > 0 &&
-            mode === SigningMode.USER_AGENT) {
-            const agent = await this.sdkClient.agentManager.getAgent(address, provider);
-            const signedAgentActions = await Promise.all(required.agentPrerequisites.map(async (action) => ({
-                action: action.action,
-                typedData: action.typedData,
-                signature: await signTypedData(agent.privateKey, action.typedData),
-            })));
-            const firstAction = required.agentPrerequisites[0]?.action;
-            const stagedResults = await executeAction(this.sdkClient, {
-                provider,
-                address,
-                signerAddress: agent.address,
-                action: (firstAction ?? ActionType.ACCOUNT_MODE),
-                actions: signedAgentActions,
-            });
-            // Merge staged-prereq results with any auto-upgrade results from step 2.
-            agentResults = {
-                results: [...(agentResults?.results ?? []), ...stagedResults.results],
-            };
-        }
-        return {
-            userResults,
-            ...(agentResults ? { agentResults } : {}),
-            ...(fallbackUserPrerequisites ? { fallbackUserPrerequisites } : {}),
-        };
-    }
-    // ---------------------------------------------------------------------------
-    // Typed action helpers
-    // ---------------------------------------------------------------------------
     async placeOrder(params) {
         return this.execute({ ...params, action: ActionType.PLACE_ORDER, params });
     }
+    /**
+     * Place a trigger (take-profit / stop-loss) order. Convenience wrapper over
+     * {@link execute} with `ActionType.PLACE_TRIGGER_ORDER`.
+     *
+     * @throws {PerpsError} When the provider is unregistered or the action
+     *   cannot be signed/submitted.
+     * @public
+     */
     async placeTriggerOrder(params) {
         return this.execute({
             ...params,
@@ -931,12 +405,36 @@ export class PerpsClient {
             params,
         });
     }
+    /**
+     * Cancel one or more open orders. Convenience wrapper over {@link execute}
+     * with `ActionType.CANCEL_ORDER`.
+     *
+     * @throws {PerpsError} When the provider is unregistered or the action
+     *   cannot be signed/submitted.
+     * @public
+     */
     async cancelOrders(params) {
         return this.execute({ ...params, action: ActionType.CANCEL_ORDER, params });
     }
+    /**
+     * Modify one or more open orders. Convenience wrapper over {@link execute}
+     * with `ActionType.MODIFY_ORDER`.
+     *
+     * @throws {PerpsError} When the provider is unregistered or the action
+     *   cannot be signed/submitted.
+     * @public
+     */
     async modifyOrders(params) {
         return this.execute({ ...params, action: ActionType.MODIFY_ORDER, params });
     }
+    /**
+     * Add or remove isolated-position margin. Convenience wrapper over
+     * {@link execute} with `ActionType.UPDATE_POSITION_MARGIN`.
+     *
+     * @throws {PerpsError} When the provider is unregistered or the action
+     *   cannot be signed/submitted.
+     * @public
+     */
     async updatePositionMargin(params) {
         return this.execute({
             ...params,
@@ -944,6 +442,14 @@ export class PerpsClient {
             params,
         });
     }
+    /**
+     * Withdraw funds from the provider account. Convenience wrapper over
+     * {@link execute} with `ActionType.WITHDRAWAL`.
+     *
+     * @throws {PerpsError} When the provider is unregistered or the action
+     *   cannot be signed/submitted.
+     * @public
+     */
     async withdraw(params) {
         return this.execute({
             provider: params.provider,
@@ -953,35 +459,40 @@ export class PerpsClient {
         });
     }
     /**
-     * Execute any action through the SDK's signing pipeline. Signing is routed
-     * by the action's descriptor in provider metadata — the agent keypair, the
-     * configured WalletClient signer, the Lighter API key, or an EVM tx — as
-     * the descriptor's `signers` and `signingMethod` dictate.
+     * Execute any action through the SDK's signing pipeline: fetch the unsigned
+     * steps, delegate signing to the provider plugin (which branches on the
+     * descriptor's scheme and signer internally), and submit. Core stays
+     * signer-agnostic — the plugin owns WHO signs and HOW.
+     *
+     * @throws {PerpsError} When the action is not declared by the provider,
+     *   the plugin cannot sign it, or submission fails.
+     * @public
      */
     async execute(params) {
-        await this.loadSigningMode(params.address, params.provider);
-        const metadata = await this.getProviderMetadata(params.provider);
-        const descriptor = findActionDescriptor(metadata, params.action);
-        let lastError;
-        for (let attempt = 0; attempt < MAX_NONCE_RETRIES; attempt++) {
-            const { actions } = await this.buildAction(params.action, {
-                provider: params.provider,
-                address: params.address,
-                params: params.params,
-            });
-            try {
-                return await this.autoSignAndExecute(params.provider, params.address, params.action, actions, descriptor);
-            }
-            catch (err) {
-                if (err instanceof PerpsError &&
-                    err.code === PerpsErrorCode.InvalidNonce) {
-                    lastError = err;
-                    continue;
-                }
-                throw err;
-            }
-        }
-        throw lastError;
+        const { provider, address, action } = params;
+        const metadata = await this.getProviderMetadata(provider);
+        const descriptor = findActionDescriptor(metadata, action);
+        const { signerAddress, params: signerParams } = await this.resolveActionRequest(provider, descriptor, address);
+        const { actions } = await createAction(this.sdkClient, {
+            provider,
+            address,
+            signerAddress,
+            action,
+            params: {
+                ...params.params,
+                ...signerParams,
+            },
+        });
+        const signedActions = await this.delegateSignActions(provider, address, descriptor, actions);
+        return executeAction(this.sdkClient, {
+            provider,
+            address,
+            // The submitting account: the plugin-resolved signer (Hyperliquid's
+            // agent) when present, else the end-user's address.
+            signerAddress: signerAddress ?? address,
+            action,
+            actions: signedActions,
+        });
     }
 }
 //# sourceMappingURL=PerpsClient.js.map