@lifi/perps-sdk 0.1.1-alpha.9 → 1.0.0

package/src/client/PerpsClient.ts

@@ -1,572 +1,686 @@
 import type {
-  Address,
-  AuthorizationsResponse,
-  CancelOrderPayloadResponse,
-  CreateAuthorizationResponse,
-  CreateOrderResponse,
-  CreateWithdrawalResponse,
-  OrderActionType,
-  SignedAuthorization,
-  SignedOrderAction,
-  SubmitOrderResponse,
-  SubmitWithdrawalResponse,
+  AccountResponse,
+  AccountSummary,
+  ActionParamsMap,
+  ActionStep,
+  CreateActionResponse,
+  ExecuteActionResponse,
+  MarketRef,
+  Position,
+  Provider,
+  ProviderAction,
+  SignedActionStep,
 } from '@lifi/perps-types'
-import { PerpsErrorCode } from '@lifi/perps-types'
-import { getDexAuthProvider } from '../dex/registry.js'
-import { PerpsErrorMessage } from '../errors/constants.js'
+import { ActionType, PerpsErrorCode } from '@lifi/perps-types'
+import type { Address } from 'viem'
 import { PerpsError } from '../errors/PerpsError.js'
-import { cancelOrder } from '../services/cancelOrder.js'
-import { createAuthorization } from '../services/createAuthorization.js'
-import { createOrder } from '../services/createOrder.js'
-import { createWithdrawal } from '../services/createWithdrawal.js'
-import type { SubmitAuthorizationParams } from '../services/submitAuthorization.js'
-import { submitAuthorization } from '../services/submitAuthorization.js'
-import type { SubmitOrderParams } from '../services/submitOrder.js'
-import { submitOrder } from '../services/submitOrder.js'
-import type { SubmitWithdrawalParams } from '../services/submitWithdrawal.js'
-import { submitWithdrawal } from '../services/submitWithdrawal.js'
-import { signTypedData } from '../utils/signTypedData.js'
-import { createPerpsClient, type PerpsSDKClient } from './createPerpsClient.js'
+import { createAction } from '../services/createAction.js'
+import { executeAction } from '../services/executeAction.js'
+import { getAccount as fetchAccount } from '../services/getAccount.js'
+import { getProviders } from '../services/getProviders.js'
 import type {
-  BuildAuthorizationParams,
-  BuildWithdrawalParams,
+  BuildProviderSetupParams,
   CancelOrdersParams,
-  ExecuteAuthorizationsParams,
-  ExecuteAuthorizationsResult,
-  GetRequiredAuthorizationsParams,
+  ExecuteProviderSetupParams,
+  ExecuteProviderSetupResult,
+  GetAccountResult,
+  GetSetupParams,
+  ModifyOrdersParams,
   PerpsClientOptions,
   PlaceOrderParams,
-  RequiredAuthorizationsResult,
-  SigningMode,
-} from './types.js'
+  PlaceTriggerOrderParams,
+  ProviderSetup,
+  WithdrawParams,
+} from '../types/api.js'
+import type {
+  ActionSignerContribution,
+  PerpsProvider,
+  PerpsSDKClient,
+  SignActionsContext,
+} from '../types/provider.js'
+import { createPerpsClient } from './createPerpsClient.js'
+import { requireProvider as resolveProvider } from './requireProvider.js'
 
 /**
- * Stateful client for managing signing modes and trading operations.
- *
- * The PerpsClient provides two signing modes:
- * - `USER`: User wallet signs each action (wallet popup per action)
- * - `USER_AGENT`: SDK-generated agent signs actions (no popups after setup)
- *
- * In `USER_AGENT` mode, the client:
- * - Generates an agent keypair stored in localStorage (or custom storage)
- * - Auto-injects agent address into authorization requests
- * - Auto-signs trading actions with the agent key
- *
- * @remarks
- * The example below uses Hyperliquid. Authorization keys and parameters are DEX-specific.
- *
- * @example
- * ```ts
- * const perps = new PerpsClient({ integrator: 'my-app' })
- *
- * // Set up agent signing for a user + DEX pair
- * await perps.setSigningMode(userAddress, 'hyperliquid', 'USER_AGENT')
- *
- * // Check and execute required authorizations
- * const required = await perps.getRequiredAuthorizations({
- *   dex: 'hyperliquid',
- *   address: userAddress,
- * })
- *
- * // ... sign actions with user wallet ...
+ * 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.
+ */
+function findActionDescriptor(
+  metadata: Provider,
+  action: ActionType
+): ProviderAction {
+  const descriptor = [
+    ...metadata.setup,
+    ...metadata.options,
+    ...metadata.actions,
+  ].find((d) => d.type === action)
+  if (!descriptor) {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Provider '${metadata.key}' does not declare action '${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.
  *
- * // Place orders (agent signs automatically)
- * const result = await perps.placeOrder({
- *   address: userAddress,
- *   dex: 'hyperliquid',
- *   symbol: 'BTC',
- *   side: 'BUY',
- *   type: 'MARKET',
- *   size: '0.1',
- *   price: '95000.00'
- * })
- * ```
+ * @public
  */
 export class PerpsClient {
   private sdkClient: PerpsSDKClient
-  private signingModes: Map<string, SigningMode> = new Map()
+  private providerMetadataCache: Map<string, Provider> = new Map()
+  private _userWallet: PerpsSDKClient['userWallet'] | undefined
 
   constructor(options: PerpsClientOptions) {
     this.sdkClient = createPerpsClient({
       integrator: options.integrator,
       apiKey: options.apiKey,
       apiUrl: options.apiUrl,
-      storage: options.storage,
+      providers: options.providers,
     })
   }
 
   /**
-   * Get the underlying SDK client for use with service functions.
+   * 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
    */
-  get client(): PerpsSDKClient {
-    return this.sdkClient
+  setUserWallet(userWallet: PerpsSDKClient['userWallet']): void {
+    this._userWallet = userWallet
+    Object.defineProperty(this.sdkClient, 'userWallet', {
+      get: () => this._userWallet,
+      configurable: true,
+    })
   }
 
   /**
-   * Get the storage key for a user + DEX pair.
+   * The underlying low-level {@link PerpsSDKClient} (config, user wallet,
+   * provider registry) backing this instance.
+   *
+   * @public
    */
-  private modeKey(address: Address, dex: string): string {
-    return `${address.toLowerCase()}:${dex.toLowerCase()}`
+  get client(): PerpsSDKClient {
+    return this.sdkClient
   }
 
-  /**
-   * Set the signing mode for a user + DEX pair.
-   *
-   * In `USER_AGENT` mode, generates an agent keypair if one doesn't exist.
-   *
-   * @param address - User wallet address
-   * @param dex - DEX identifier
-   * @param mode - Signing mode to set
-   */
-  async setSigningMode(
-    address: Address,
-    dex: string,
-    mode: SigningMode
-  ): Promise<void> {
-    const key = this.modeKey(address, dex)
-    this.signingModes.set(key, mode)
-
-    if (mode === 'USER_AGENT') {
-      // Generate agent keypair if not exists
-      await this.sdkClient.agentManager.getOrCreateAgent(address, dex)
+  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)
+    }
+
+    const metadata = this.providerMetadataCache.get(provider)
+    if (!metadata) {
+      const error = new PerpsError(
+        PerpsErrorCode.SDKError,
+        `Unsupported provider: ${provider}`
+      )
+      error.tool = '@lifi/perps-sdk'
+      throw error
     }
+    return metadata
   }
 
   /**
-   * Get the current signing mode for a user + DEX pair.
-   * Defaults to `USER` if not set.
+   * 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.
    */
-  getSigningMode(address: Address, dex: string): SigningMode {
-    return this.signingModes.get(this.modeKey(address, dex)) ?? 'USER'
+  private requireProvider(provider: string): PerpsProvider {
+    return resolveProvider(this.sdkClient, provider)
   }
 
   /**
-   * Get the agent address for a user + DEX pair.
-   *
-   * @throws {PerpsError} If in USER mode or agent not found
+   * 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 getAgentAddress(address: Address, dex: string): Promise<Address> {
-    const agent = await this.sdkClient.agentManager.getAgent(address, dex)
-    return agent.address
+  private async resolveActionRequest(
+    provider: string,
+    descriptor: ProviderAction,
+    address: Address
+  ): Promise<ActionSignerContribution> {
+    const plugin = this.requireProvider(provider)
+    if (typeof plugin.resolveActionRequest !== 'function') {
+      return {}
+    }
+    return plugin.resolveActionRequest(
+      descriptor.type,
+      address,
+      descriptor.signers
+    )
   }
 
   /**
-   * Check if an agent exists for a user + DEX pair.
+   * 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 hasAgent(address: Address, dex: string): Promise<boolean> {
-    return this.sdkClient.agentManager.hasAgent(address, dex)
+  private async delegateSignActions(
+    provider: string,
+    address: Address,
+    descriptor: ProviderAction,
+    actions: ActionStep[]
+  ): Promise<SignedActionStep[]> {
+    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}'.`
+      )
+    }
+    return plugin.signActions(
+      descriptor.signingMethod,
+      actions,
+      address,
+      this.buildSignActionsContext(descriptor)
+    )
   }
 
   /**
-   * Remove the agent for a user + DEX pair.
-   * Also resets signing mode to USER.
+   * 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 removeAgent(address: Address, dex: string): Promise<void> {
-    await this.sdkClient.agentManager.removeAgent(address, dex)
-    this.signingModes.delete(this.modeKey(address, dex))
+  private buildSignActionsContext(
+    descriptor: ProviderAction
+  ): SignActionsContext {
+    const ctx: SignActionsContext = { signers: descriptor.signers }
+    if (this.sdkClient.userWallet !== undefined) {
+      ctx.userWallet = this.sdkClient.userWallet
+    }
+    return ctx
   }
 
   /**
-   * Build authorization payloads for signing.
+   * 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.
    *
-   * In `USER` mode, `signerAddress` is omitted (backend defaults to `address`).
-   * In `USER_AGENT` mode, auto-injects the agent address as `signerAddress`.
+   * @throws {PerpsError} When the step's action is not declared by the provider.
+   * @public
+   */
+  async signProviderSetupAction(
+    provider: string,
+    address: Address,
+    step: ActionStep
+  ): Promise<SignedActionStep> {
+    const metadata = await this.getProviderMetadata(provider)
+    const descriptor = findActionDescriptor(metadata, step.action)
+    const [signed] = await this.delegateSignActions(
+      provider,
+      address,
+      descriptor,
+      [step]
+    )
+    return signed
+  }
+
+  /**
+   * Build (but do not sign or submit) the unsigned action steps for `action`,
+   * letting the provider plugin contribute any signer-bearing request fields.
    *
-   * @param params - Authorization parameters
-   * @returns Authorization actions with typed data for signing
+   * @public
    */
-  async buildAuthorization(
-    params: BuildAuthorizationParams
-  ): Promise<CreateAuthorizationResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
-    let { signerAddress } = params
-
-    if (mode === 'USER_AGENT') {
-      const agent = await this.sdkClient.agentManager.getAgent(
-        params.address,
-        params.dex
+  async buildAction<T extends ActionType>(
+    action: T,
+    params: { provider: string; address: Address; params: ActionParamsMap[T] }
+  ): Promise<CreateActionResponse> {
+    const metadata = await this.getProviderMetadata(params.provider)
+    const descriptor = findActionDescriptor(metadata, action)
+    const { signerAddress, params: signerParams } =
+      await this.resolveActionRequest(
+        params.provider,
+        descriptor,
+        params.address
       )
-      signerAddress = signerAddress ?? agent.address
-    }
-
-    return createAuthorization(this.sdkClient, {
-      ...params,
+    return createAction(this.sdkClient, {
+      provider: params.provider,
+      address: params.address,
       signerAddress,
+      action,
+      params: {
+        ...params.params,
+        ...signerParams,
+      } as ActionParamsMap[T],
     })
   }
 
   /**
-   * Submit signed authorizations.
+   * 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`.
    *
-   * In `USER` mode, `signerAddress` is omitted (backend defaults to `address`).
-   * In `USER_AGENT` mode, auto-injects the agent address as `signerAddress`.
+   * @throws {PerpsError} When the provider plugin is not registered, or the
+   *   backend account fetch fails.
+   * @public
+   */
+  async getAccount(params: {
+    provider: string
+    address: Address
+  }): Promise<GetAccountResult> {
+    const plugin = this.requireProvider(params.provider)
+    const [response, metadata] = await Promise.all([
+      fetchAccount(this.sdkClient, params),
+      this.getProviderMetadata(params.provider),
+    ])
+    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: AccountResponse,
+    positions: Position[]
+  ): AccountSummary {
+    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).
    *
-   * @param params - Signed authorization parameters
+   * @throws {PerpsError} On any backend error other than
+   *   `PerpsErrorCode.AccountNotFound`.
+   * @public
    */
-  async submitAuthorizations(
-    params: SubmitAuthorizationParams
-  ): Promise<AuthorizationsResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
-    let { signerAddress } = params
-
-    if (mode === 'USER_AGENT') {
-      const agent = await this.sdkClient.agentManager.getAgent(
-        params.address,
-        params.dex
-      )
-      signerAddress = signerAddress ?? agent.address
+  async accountExists(provider: string, address: Address): Promise<boolean> {
+    try {
+      await fetchAccount(this.sdkClient, { provider, address })
+      return true
+    } catch (err) {
+      if (
+        err instanceof PerpsError &&
+        err.code === PerpsErrorCode.AccountNotFound
+      ) {
+        return false
+      }
+      throw err
     }
-
-    return submitAuthorization(this.sdkClient, { ...params, signerAddress })
   }
 
   /**
-   * Build order payloads for signing.
+   * Return the unsatisfied entries on `Provider.setup` for this account as a
+   * flat, self-describing list. Trading is gated on `isReady === true`.
    *
-   * In `USER` mode, `signerAddress` is omitted (backend defaults to `address`).
-   * In `USER_AGENT` mode, auto-injects the agent address as `signerAddress`.
+   * `Provider.options` descriptors are NEVER returned here — options are
+   * post-setup tunables and never gate trading. Option state is surfaced
+   * separately via `getAccount().settings`.
    *
-   * @param params - Order parameters
-   * @returns Order actions with typed data for signing
+   * @public
    */
-  async buildOrder(params: PlaceOrderParams): Promise<CreateOrderResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
-    let signerAddress: Address | undefined
-
-    if (mode === 'USER_AGENT') {
-      const agent = await this.sdkClient.agentManager.getAgent(
-        params.address,
-        params.dex
-      )
-      signerAddress = agent.address
-    }
+  async checkSetup(params: GetSetupParams): Promise<ProviderSetup> {
+    const { provider, address } = params
 
-    return createOrder(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      signerAddress,
-      clientOrderId: params.clientOrderId,
-      symbol: params.symbol,
-      side: params.side,
-      type: params.type,
-      size: params.size,
-      price: params.price,
-      leverage: params.leverage,
-      reduceOnly: params.reduceOnly,
-      timeInForce: params.timeInForce,
-      expiresAt: params.expiresAt,
-      takeProfit: params.takeProfit,
-      stopLoss: params.stopLoss,
-    })
+    // 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 {
+      setup: actions,
+      isReady: actions.length === 0,
+    }
   }
 
   /**
-   * Build cancel order payloads for signing.
-   *
-   * In `USER` mode, `signerAddress` is omitted (backend defaults to `address`).
-   * In `USER_AGENT` mode, auto-injects the agent address as `signerAddress`.
+   * 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).
    *
-   * @param params - Cancel parameters
-   * @returns Cancel actions with typed data for signing
+   * @public
    */
-  async buildCancelOrder(
-    params: CancelOrdersParams
-  ): Promise<CancelOrderPayloadResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
-    let signerAddress: Address | undefined
-
-    if (mode === 'USER_AGENT') {
-      const agent = await this.sdkClient.agentManager.getAgent(
-        params.address,
-        params.dex
-      )
-      signerAddress = agent.address
+  async buildProviderSetup(
+    params: BuildProviderSetupParams
+  ): Promise<CreateActionResponse> {
+    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: ActionStep[] = []
+    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,
+        address,
+        signerAddress,
+        action,
+        params: {
+          ...signerParams,
+          ...localParams,
+        } as Record<string, never>,
+      })
+      allActions.push(...actions)
     }
 
-    return cancelOrder(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      signerAddress,
-      ids: params.ids,
-    })
+    return { actions: allActions }
   }
 
   /**
-   * Place an order with automatic agent signing.
+   * 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.
    *
-   * **Requires USER_AGENT mode.** For USER mode, use `buildOrder()` + `submitSignedOrder()`.
-   *
-   * @param params - Order parameters
-   * @returns Order submission results
-   * @throws {PerpsError} If not in USER_AGENT mode
+   * @public
    */
-  async placeOrder(params: PlaceOrderParams): Promise<SubmitOrderResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
+  async executeProviderSetup(
+    params: ExecuteProviderSetupParams
+  ): Promise<ExecuteProviderSetupResult> {
+    const { provider, address, setup, signedActions } = params
 
-    if (mode !== 'USER_AGENT') {
-      throw new PerpsError(
-        PerpsErrorCode.ValidationError,
-        `${PerpsErrorMessage.InvalidSigningMode} placeOrder() requires USER_AGENT mode. Use createOrder() + submitOrder() for USER mode.`
-      )
+    if (signedActions.length === 0) {
+      return { results: { results: [] } }
     }
 
-    const agent = await this.sdkClient.agentManager.getAgent(
-      params.address,
-      params.dex
+    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
     )
 
-    // 1. Create order payloads
-    const { actions } = await createOrder(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      signerAddress: agent.address,
-      clientOrderId: params.clientOrderId,
-      symbol: params.symbol,
-      side: params.side,
-      type: params.type,
-      size: params.size,
-      price: params.price,
-      leverage: params.leverage,
-      reduceOnly: params.reduceOnly,
-      timeInForce: params.timeInForce,
-      expiresAt: params.expiresAt,
-      takeProfit: params.takeProfit,
-      stopLoss: params.stopLoss,
+    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,
     })
 
-    // 2. Sign each action with agent key
-    const signedActions: SignedOrderAction[] = await Promise.all(
-      actions.map(async (a) => ({
-        action: a.action,
-        typedData: a.typedData,
-        signature: await signTypedData(agent.privateKey, a.typedData),
-      }))
-    )
+    const failure = results.results.find((r) => !r.success)
+    if (failure) {
+      throw new PerpsError(PerpsErrorCode.ExchangeRejected, failure.error)
+    }
 
-    // 3. Submit
-    return submitOrder(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      signerAddress: agent.address,
-      actions: signedActions,
-    })
+    return { results }
   }
 
   /**
-   * Cancel orders with automatic agent signing.
+   * Sign and submit one pre-staged setup `ActionStep` end-to-end.
    *
-   * **Requires USER_AGENT mode.** For USER mode, use `buildCancelOrder()` + `submitSignedOrder()`.
+   * 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.
    *
-   * @param params - Cancel parameters
-   * @returns Cancel submission results
-   * @throws {PerpsError} If not in USER_AGENT mode
+   * @throws {PerpsError} When the step's action is not in the provider's
+   *   `setup` descriptors.
+   * @public
    */
-  async cancelOrders(params: CancelOrdersParams): Promise<SubmitOrderResponse> {
-    const mode = this.getSigningMode(params.address, params.dex)
-
-    if (mode !== 'USER_AGENT') {
+  async executeProviderSetupAction(params: {
+    provider: string
+    address: Address
+    step: ActionStep
+  }): Promise<void> {
+    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.ValidationError,
-        `${PerpsErrorMessage.InvalidSigningMode} cancelOrders() requires USER_AGENT mode. Use cancelOrder() + submitOrder() for USER mode.`
+        PerpsErrorCode.SDKError,
+        `Action '${step.action}' is not in '${provider}'.setup`
       )
     }
 
-    const agent = await this.sdkClient.agentManager.getAgent(
-      params.address,
-      params.dex
-    )
-
-    // 1. Create cancel payloads
-    const { actions } = await cancelOrder(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      signerAddress: agent.address,
-      ids: params.ids,
-    })
-
-    // 2. Sign each action with agent key
-    const signedActions: SignedOrderAction[] = await Promise.all(
-      actions.map(async (a) => ({
-        action: a.action as OrderActionType,
-        typedData: a.typedData,
-        signature: await signTypedData(agent.privateKey, a.typedData),
-      }))
-    )
-
-    // 3. Submit
-    return submitOrder(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      signerAddress: agent.address,
-      actions: signedActions,
+    const signed = await this.signProviderSetupAction(provider, address, step)
+    await this.executeProviderSetup({
+      provider,
+      address,
+      setup: [step],
+      signedActions: [signed],
     })
   }
 
   /**
-   * Submit pre-signed order actions.
+   * 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.
    *
-   * Use this for USER mode when you've already signed the actions with the user's wallet.
-   * Auto-injects `signerAddress` if not provided (defaults to `address`).
+   * `execute` itself is unchanged — it still returns results without throwing,
+   * which the trade hooks rely on for partial-fill handling.
    *
-   * @param params - Signed order parameters
+   * @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
    */
-  async submitSignedOrder(
-    params: SubmitOrderParams
-  ): Promise<SubmitOrderResponse> {
-    return submitOrder(this.sdkClient, params)
+  async executeProviderOption<T extends ActionType>(params: {
+    provider: string
+    address: Address
+    action: T
+    params: ActionParamsMap[T]
+  }): Promise<void> {
+    const { results } = await this.execute(params)
+    const failure = results.find((r) => !r.success)
+    if (failure) {
+      throw new PerpsError(PerpsErrorCode.ExchangeRejected, failure.error)
+    }
   }
 
   /**
-   * Build a withdrawal payload for the user to sign.
+   * Place a market or limit order. Convenience wrapper over {@link execute}
+   * with `ActionType.PLACE_ORDER`.
    *
-   * Withdrawals are user-signed only — agents cannot initiate withdrawals.
-   * No agent injection is performed regardless of signing mode.
+   * @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 placeOrder(params: PlaceOrderParams): Promise<ExecuteActionResponse> {
+    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`.
    *
-   * @param params - Withdrawal parameters
-   * @returns Withdrawal action with typed data for signing
+   * @throws {PerpsError} When the provider is unregistered or the action
+   *   cannot be signed/submitted.
+   * @public
    */
-  async buildWithdrawal(
-    params: BuildWithdrawalParams
-  ): Promise<CreateWithdrawalResponse> {
-    return createWithdrawal(this.sdkClient, {
-      dex: params.dex,
-      address: params.address,
-      withdrawal: params.withdrawal,
+  async placeTriggerOrder(
+    params: PlaceTriggerOrderParams
+  ): Promise<ExecuteActionResponse> {
+    return this.execute({
+      ...params,
+      action: ActionType.PLACE_TRIGGER_ORDER,
+      params,
     })
   }
 
   /**
-   * Submit a signed withdrawal.
+   * Cancel one or more open orders. Convenience wrapper over {@link execute}
+   * with `ActionType.CANCEL_ORDER`.
    *
-   * Withdrawals are user-signed only — agents cannot initiate withdrawals.
-   *
-   * @param params - Signed withdrawal parameters
-   * @returns Withdrawal result
+   * @throws {PerpsError} When the provider is unregistered or the action
+   *   cannot be signed/submitted.
+   * @public
    */
-  async submitWithdrawal(
-    params: SubmitWithdrawalParams
-  ): Promise<SubmitWithdrawalResponse> {
-    return submitWithdrawal(this.sdkClient, params)
+  async cancelOrders(
+    params: CancelOrdersParams
+  ): Promise<ExecuteActionResponse> {
+    return this.execute({ ...params, action: ActionType.CANCEL_ORDER, params })
   }
 
   /**
-   * Determine which authorizations (if any) the user needs to sign before trading.
-   *
-   * Uses the dex auth provider to determine what authorizations to request,
-   * then calls buildAuthorization — the backend filters already-valid auths
-   * and returns only what's needed.
+   * Modify one or more open orders. Convenience wrapper over {@link execute}
+   * with `ActionType.MODIFY_ORDER`.
    *
-   * @param params - Parameters including dex, address, and dex-specific config
-   * @returns Which authorizations are needed and whether the user is ready to trade
+   * @throws {PerpsError} When the provider is unregistered or the action
+   *   cannot be signed/submitted.
+   * @public
    */
-  async getRequiredAuthorizations(
-    params: GetRequiredAuthorizationsParams
-  ): Promise<RequiredAuthorizationsResult> {
-    const { dex, address } = params
-    const mode = this.getSigningMode(address, dex)
-    const provider = getDexAuthProvider(dex)
-
-    // Ensure agent exists in USER_AGENT mode
-    let agentAddress: Address | undefined
-    if (mode === 'USER_AGENT') {
-      const agent = await this.sdkClient.agentManager.getOrCreateAgent(
-        address,
-        dex
-      )
-      agentAddress = agent.address
-    }
+  async modifyOrders(
+    params: ModifyOrdersParams
+  ): Promise<ExecuteActionResponse> {
+    return this.execute({ ...params, action: ActionType.MODIFY_ORDER, params })
+  }
 
-    // Provider declares auth inputs categorized as user/agent
-    const authInputs = provider.getAuthorizationInputs({
-      signingMode: mode,
-      agentAddress,
+  /**
+   * 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: {
+    provider: string
+    address: Address
+    market: MarketRef
+    action: 'add' | 'remove'
+    amount: string
+  }): Promise<ExecuteActionResponse> {
+    return this.execute({
+      ...params,
+      action: ActionType.UPDATE_POSITION_MARGIN,
+      params,
     })
+  }
 
-    const allInputs = [...authInputs.user, ...authInputs.agent]
-    if (allInputs.length === 0) {
-      return { userAuthorizations: [], agentAuthorizations: [], isReady: true }
-    }
-
-    // Send ALL to backend — it filters already-satisfied ones and returns typed data
-    const { actions } = await this.buildAuthorization({
-      dex,
-      address,
-      authorizations: allInputs,
+  /**
+   * 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: WithdrawParams): Promise<ExecuteActionResponse> {
+    return this.execute({
+      provider: params.provider,
+      address: params.address,
+      action: ActionType.WITHDRAWAL,
+      params: params.withdrawal,
     })
-
-    if (actions.length === 0) {
-      return { userAuthorizations: [], agentAuthorizations: [], isReady: true }
-    }
-
-    // Categorize backend results using provider's original key sets
-    const agentKeys = new Set(authInputs.agent.map((a) => a.key))
-    const userAuthorizations = actions.filter((a) => !agentKeys.has(a.action))
-    const agentAuthorizations = actions.filter((a) => agentKeys.has(a.action))
-
-    return {
-      userAuthorizations,
-      agentAuthorizations,
-      isReady: false,
-    }
   }
 
   /**
-   * Execute authorizations: submit user-signed actions, then auto-sign and submit
-   * any agent authorizations.
+   * 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.
    *
-   * @param params - User-signed actions and the required authorizations result
-   * @returns Combined results from user and agent submissions
+   * @throws {PerpsError} When the action is not declared by the provider,
+   *   the plugin cannot sign it, or submission fails.
+   * @public
    */
-  async executeAuthorizations(
-    params: ExecuteAuthorizationsParams
-  ): Promise<ExecuteAuthorizationsResult> {
-    const { dex, address, required, userSignedActions } = params
-    const mode = this.getSigningMode(address, dex)
-
-    // 1. Submit user-signed actions (if any)
-    let userResults: AuthorizationsResponse = { results: [] }
-    if (userSignedActions.length > 0) {
-      const signerAddress =
-        mode === 'USER_AGENT'
-          ? (await this.sdkClient.agentManager.getAgent(address, dex)).address
-          : address
-      userResults = await submitAuthorization(this.sdkClient, {
-        dex,
-        address,
-        signerAddress,
-        actions: userSignedActions,
-      })
-
-      // Check for failures - return early if any user auth failed
-      const failed = userResults.results.find((r) => !r.success)
-      if (failed) {
-        return { userResults }
-      }
-    }
-
-    // 2. Auto-sign and submit agent authorizations (if any)
-    // Typed data already built by getRequiredAuthorizations — just sign and submit
-    if (required.agentAuthorizations.length > 0 && mode === 'USER_AGENT') {
-      const agent = await this.sdkClient.agentManager.getAgent(address, dex)
-
-      const signedAgentActions: SignedAuthorization[] = await Promise.all(
-        required.agentAuthorizations.map(async (action) => ({
-          action: action.action,
-          typedData: action.typedData,
-          signature: await signTypedData(agent.privateKey, action.typedData),
-        }))
-      )
-
-      const agentResults = await submitAuthorization(this.sdkClient, {
-        dex,
-        address,
-        signerAddress: agent.address,
-        actions: signedAgentActions,
-      })
+  async execute<T extends ActionType>(params: {
+    provider: string
+    address: Address
+    action: T
+    params: ActionParamsMap[T]
+  }): Promise<ExecuteActionResponse> {
+    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,
+      } as ActionParamsMap[T],
+    })
 
-      return { userResults, agentResults }
-    }
+    const signedActions = await this.delegateSignActions(
+      provider,
+      address,
+      descriptor,
+      actions
+    )
 
-    return { userResults }
+    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,
+    })
   }
 }