@lifi/perps-sdk 10.0.2 → 10.2.0

package/src/client/PerpsClient.ts

@@ -8,6 +8,7 @@ import type {
   ExecuteActionResponse,
   MarketRef,
   MarketSettings,
+  MetaActionType,
   Position,
   PositionMarginConstraints,
   Provider,
@@ -16,6 +17,7 @@ import type {
 } from '@lifi/perps-types'
 import {
   ActionType,
+  META_PROVIDER,
   PerpsErrorCode,
   PerpsSigner,
   SigningMethod,
@@ -32,6 +34,8 @@ import type {
   BuildProviderSetupParams,
   CancelOrdersParams,
   CancelTwapOrderParams,
+  CreateReferralCodeActionParams,
+  ExecuteMetaActionParams,
   ExecuteProviderSetupParams,
   ExecuteProviderSetupResult,
   GetAccountResult,
@@ -45,6 +49,7 @@ import type {
   PlaceTwapOrderParams,
   ProviderSetup,
   SendAssetActionParams,
+  SubmitOnboardingParams,
   WithdrawParams,
 } from '../types/api.js'
 import type { PerpsClientSigner, SwitchChainHook } from '../types/config.js'
@@ -57,7 +62,9 @@ import type {
   SignActionsContext,
 } from '../types/provider.js'
 import type { WithdrawableBalance } from '../types/withdrawal.js'
+import { signTypedDataWithSigner } from '../utils/signTypedData.js'
 import {
+  eip712DomainChainId,
   switchSigningChain,
   userEip712TargetChainId,
 } from '../utils/switchChain.js'
@@ -292,6 +299,28 @@ export class PerpsClient {
     return switchSigningChain(wallet, targetChainId, this._switchChain)
   }
 
+  /**
+   * Resolve the wallet that signs a meta action's steps. Meta actions carry no
+   * provider descriptor, so the target chain comes from the step's EIP-712
+   * domain. The switch is transient — `sdkClient.userWallet` is never mutated.
+   */
+  private async resolveMetaSigningWallet(
+    actions: ActionStep[]
+  ): Promise<PerpsClientSigner> {
+    const wallet = this.sdkClient.userWallet
+    if (!wallet) {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        'No user wallet configured; call setUserWallet() before signing a meta action.'
+      )
+    }
+    const targetChainId = eip712DomainChainId(actions)
+    if (targetChainId === undefined) {
+      return wallet
+    }
+    return switchSigningChain(wallet, targetChainId, this._switchChain)
+  }
+
   /**
    * 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
@@ -553,6 +582,9 @@ export class PerpsClient {
   /**
    * Return the unsatisfied entries on `Provider.setup` for this account as a
    * flat, self-describing list. Trading is gated on `isReady === true`.
+   * `checklist` carries the renderable onboarding list: every USER-signed
+   * descriptor with its satisfied state, with not-required conditional steps
+   * omitted.
    *
    * `Provider.options` descriptors are NEVER returned here — options are
    * post-setup tunables and never gate trading. Option state is surfaced
@@ -574,7 +606,12 @@ export class PerpsClient {
     // SIWE-first providers (Ondo) are the exception: they cannot reliably probe
     // account existence before the user signs in, so setup must still stage.
     if (!hasSiweSetup && !(await this.accountExists(provider, address))) {
-      return { accountExists: false, setup: [], isReady: false }
+      return {
+        accountExists: false,
+        setup: [],
+        isReady: false,
+        checklist: [],
+      }
     }
 
     const satisfiedSetup = await this.resolveSatisfiedSetup(provider, address)
@@ -582,13 +619,13 @@ export class PerpsClient {
       (descriptor) => !satisfiedSetup.has(descriptor.type)
     )
 
-    const hiddenSetup = await this.resolveInternalSetup(
-      provider,
-      address,
-      pendingSetup
-    )
+    const plugin = this.sdkClient.getProvider(provider)
+    const internalTypes = new Set(plugin?.internalSetupActions ?? [])
+    const isInternal = (descriptor: ProviderAction): boolean =>
+      internalTypes.has(descriptor.type) &&
+      !descriptor.signers.includes(PerpsSigner.USER)
     const visibleSetup = pendingSetup.filter(
-      (descriptor) => !hiddenSetup.has(descriptor.type)
+      (descriptor) => !isInternal(descriptor)
     )
 
     // The backend filters already-satisfied setup actions and returns typed
@@ -600,10 +637,38 @@ export class PerpsClient {
       visibleSetup
     )
 
+    // A staged step is one the build produced actions for — a pending
+    // descriptor the backend staged nothing for is either satisfied
+    // (backend-gated) or not applicable to this account.
+    const stagedTypes = new Set(actions.map((step) => step.action))
+    const conditionalTypes = new Set(plugin?.conditionalSetupActions ?? [])
+    const sequenceOf = (descriptor: ProviderAction): number =>
+      descriptor.sequence ?? Number.MAX_SAFE_INTEGER
+    const checklist = metadata.setup
+      .filter((descriptor) => descriptor.signers.includes(PerpsSigner.USER))
+      .filter(
+        (descriptor) =>
+          !conditionalTypes.has(descriptor.type) ||
+          stagedTypes.has(descriptor.type)
+      )
+      .sort((a, b) => sequenceOf(a) - sequenceOf(b))
+      .map((descriptor) => ({
+        descriptor,
+        satisfied: !stagedTypes.has(descriptor.type),
+      }))
+
+    await this.drainInternalSetup(
+      provider,
+      address,
+      pendingSetup.filter(isInternal),
+      visibleSetup.filter((descriptor) => stagedTypes.has(descriptor.type))
+    )
+
     return {
       accountExists: true,
       setup: actions,
       isReady: actions.length === 0,
+      checklist,
     }
   }
 
@@ -639,33 +704,32 @@ export class PerpsClient {
 
   /**
    * Drain the pending setup steps the provider declares as internal via
-   * `PerpsProviderPlugin.internalSetupActions`, returning the set of action
-   * types to omit from the caller-facing setup list. Each such step is built,
-   * signed, and executed in place with the provider's own credentials. A
-   * descriptor whose `signers` include {@link PerpsSigner.USER} is left to
-   * render as a normal step. A drain failure is swallowed so it never blocks
-   * setup — the step stays unsatisfied and is retried on a later `checkSetup`.
+   * `PerpsProviderPlugin.internalSetupActions`. Each step is built, signed,
+   * and executed in place with the provider's own credentials. A step is
+   * deferred while any staged user-facing step with a lower `sequence` is
+   * outstanding — it cannot succeed before its prerequisite (e.g. SET_REFERRAL
+   * authenticates with the credential REGISTER_API_KEY installs) and each
+   * doomed attempt is venue traffic. A drain failure is swallowed so it never
+   * blocks setup — the step stays unsatisfied and is retried on a later
+   * `checkSetup`.
    */
-  private async resolveInternalSetup(
+  private async drainInternalSetup(
     provider: string,
     address: Address,
-    pending: ProviderAction[]
-  ): Promise<Set<ActionType>> {
-    const plugin = this.sdkClient.getProvider(provider)
-    const internal = plugin?.internalSetupActions
-    if (!internal || internal.length === 0) {
-      return new Set()
-    }
-    const internalTypes = new Set(internal)
-    const hidden = new Set<ActionType>()
-    for (const descriptor of pending) {
-      if (
-        !internalTypes.has(descriptor.type) ||
-        descriptor.signers.includes(PerpsSigner.USER)
-      ) {
+    internalPending: ProviderAction[],
+    stagedVisible: ProviderAction[]
+  ): Promise<void> {
+    const sequenceOf = (descriptor: ProviderAction): number =>
+      descriptor.sequence ?? Number.MAX_SAFE_INTEGER
+    for (const descriptor of internalPending) {
+      // A tie (equal sequences, or both absent) declares no order, so the
+      // internal step defers to the next checkSetup rather than racing.
+      const blocked = stagedVisible.some(
+        (staged) => sequenceOf(staged) <= sequenceOf(descriptor)
+      )
+      if (blocked) {
         continue
       }
-      hidden.add(descriptor.type)
       try {
         const steps = await this.buildProviderSetupActions(provider, address, [
           descriptor,
@@ -692,7 +756,6 @@ export class PerpsClient {
         )
       }
     }
-    return hidden
   }
 
   /**
@@ -1126,4 +1189,114 @@ export class PerpsClient {
 
     return { results }
   }
+
+  /**
+   * Accept the current terms and, when a code is supplied and the backend
+   * accepts it, attach that internal referral code — in one signature.
+   * Convenience wrapper over {@link executeMetaAction} with
+   * `ActionType.META_ONBOARD`.
+   *
+   * Resolves to `{ results: [] }` when the backend requires no consent from
+   * this address.
+   *
+   * @throws {PerpsError} When no user wallet is configured, or the action
+   *   cannot be signed/submitted.
+   * @public
+   */
+  async submitOnboarding(
+    params: SubmitOnboardingParams
+  ): Promise<ExecuteActionResponse> {
+    const { address, ...onboard } = params
+    return this.executeMetaAction({
+      address,
+      action: ActionType.META_ONBOARD,
+      params: onboard,
+    })
+  }
+
+  /**
+   * Reserve the shareable internal referral code `address` owns. Convenience
+   * wrapper over {@link executeMetaAction} with
+   * `ActionType.META_CREATE_REFERRAL_CODE`.
+   *
+   * @throws {PerpsError} When no user wallet is configured, or the action
+   *   cannot be signed/submitted.
+   * @public
+   */
+  async createReferralCode(
+    params: CreateReferralCodeActionParams
+  ): Promise<ExecuteActionResponse> {
+    const { address, ...createCode } = params
+    return this.executeMetaAction({
+      address,
+      action: ActionType.META_CREATE_REFERRAL_CODE,
+      params: createCode,
+    })
+  }
+
+  /**
+   * Execute a provider-independent action through the same
+   * createAction/executeAction pipeline {@link execute} uses. Meta actions are
+   * dispatched with the {@link META_PROVIDER} sentinel: they have no venue
+   * plugin and no `ProviderAction` descriptor, so the step is signed as EIP-712
+   * typed data with the configured user wallet.
+   *
+   * The backend returns at most one step. Resolves to `{ results: [] }` when it
+   * returns none, meaning no consent is outstanding for this address.
+   *
+   * @throws {PerpsError} When no user wallet is configured, the backend returns
+   *   more than one step or a non-EIP-712 step, or the submitted step reports a
+   *   failed result. A signature refusal from the wallet client propagates as
+   *   the wallet's own error.
+   * @public
+   */
+  async executeMetaAction<T extends MetaActionType>(
+    params: ExecuteMetaActionParams<T>
+  ): Promise<ExecuteActionResponse> {
+    const { address, action } = params
+    const { actions } = await createAction(this.sdkClient, {
+      provider: META_PROVIDER,
+      address,
+      action,
+      params: params.params,
+    })
+
+    if (actions.length === 0) {
+      return { results: [] }
+    }
+    if (actions.length > 1) {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `Action '${action}' returned ${actions.length} steps; a meta action carries at most one.`
+      )
+    }
+
+    const [step] = actions
+    if (!('typedData' in step)) {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `Action '${action}' returned a step without typedData; meta actions are signed as EIP-712 typed data.`
+      )
+    }
+
+    const wallet = await this.resolveMetaSigningWallet(actions)
+    const signature = await signTypedDataWithSigner(wallet, step.typedData)
+
+    const response = await executeAction(this.sdkClient, {
+      provider: META_PROVIDER,
+      address,
+      action,
+      actions: [{ ...step, signature }],
+    })
+
+    const failure = response.results.find((r) => !r.success)
+    if (failure) {
+      throw new PerpsError(
+        failure.errorCode ?? PerpsErrorCode.ExchangeRejected,
+        failure.error
+      )
+    }
+
+    return response
+  }
 }

package/src/index.ts

@@ -65,6 +65,10 @@ export { getPositions } from './services/getPositions.js'
 export { getProviders } from './services/getProviders.js'
 export type { GetQuoteParams } from './services/getQuote.js'
 export { getQuote } from './services/getQuote.js'
+export type { GetReferralActivityParams } from './services/getReferralActivity.js'
+export { getReferralActivity } from './services/getReferralActivity.js'
+export type { GetReferralStatusParams } from './services/getReferralStatus.js'
+export { getReferralStatus } from './services/getReferralStatus.js'
 export { getTermsAcceptance } from './services/getTermsAcceptance.js'
 export { resolveQuote, resolveQuoteMarket } from './services/resolveQuote.js'
 export {
@@ -99,6 +103,8 @@ export type {
   BuildProviderSetupParams,
   CancelOrdersParams,
   CancelTwapOrderParams as ClientCancelTwapOrderParams,
+  CreateReferralCodeActionParams,
+  ExecuteMetaActionParams,
   GetAccountResult,
   GetDepositFlowParams,
   GetSetupParams,
@@ -111,6 +117,8 @@ export type {
   PlaceTwapOrderParams as ClientPlaceTwapOrderParams,
   ProviderSetup,
   SendAssetActionParams,
+  SetupChecklistItem,
+  SubmitOnboardingParams,
   WithdrawParams,
 } from './types/api.js'
 export type {

package/src/services/getReferralActivity.ts

@@ -0,0 +1,51 @@
+import type { ReferralActivityResponse } from '@lifi/perps-types'
+import type { Address } from 'viem'
+import { buildUrl, request } from '../transport/request.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type { PerpsSDKClient } from '../types/provider.js'
+
+/**
+ * Parameters for {@link getReferralActivity}.
+ *
+ * @public
+ */
+export interface GetReferralActivityParams {
+  address: Address
+  /** Maximum items returned; backend defaults and caps apply. */
+  limit?: number
+  /** Opaque pagination cursor from the previous response. */
+  cursor?: string
+}
+
+/**
+ * Get the addresses attached to `address`'s owned internal referral code, with
+ * the executed notional recorded against each attachment. Provider-independent
+ * — reads from the platform `meta` surface, not a venue plugin.
+ *
+ * An address that owns no code resolves to `items: []` with `hasMore: false`
+ * and no cursor.
+ *
+ * @throws {PerpsError} On backend error responses, network, or parsing errors.
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ apiKey: 'your-api-key' })
+ * const { items, pagination } = await getReferralActivity(client, {
+ *   address: '0x1234...',
+ *   limit: 50,
+ * })
+ * ```
+ * @public
+ */
+export async function getReferralActivity(
+  client: PerpsSDKClient,
+  params: GetReferralActivityParams,
+  options?: SDKRequestOptions
+): Promise<ReferralActivityResponse> {
+  const url = buildUrl(`${client.config.apiUrl}/meta/referral/activity`, {
+    address: params.address,
+    limit: params.limit,
+    cursor: params.cursor,
+  })
+  return request<ReferralActivityResponse>(client.config, url, {}, options)
+}

package/src/services/getReferralStatus.ts

@@ -0,0 +1,57 @@
+import type { ReferralStatus } from '@lifi/perps-types'
+import type { Address } from 'viem'
+import { buildUrl, request } from '../transport/request.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type { PerpsSDKClient } from '../types/provider.js'
+
+/**
+ * Parameters for {@link getReferralStatus}.
+ *
+ * @public
+ */
+export interface GetReferralStatusParams {
+  address: Address
+  /**
+   * Candidate internal referral code to validate in the same read. The
+   * response carries the backend's verdict on `candidate`, and reflects the
+   * candidate in `onboarding.referralCode` when it is attachable.
+   */
+  code?: string
+}
+
+/**
+ * Get an address's onboarding and internal-referral state: terms acceptance,
+ * the code attached to it, the code it owns, whether it may create one, the
+ * verdict on a candidate code, and the one onboarding step it must sign next.
+ * Provider-independent — reads from the platform `meta` surface, not a venue
+ * plugin.
+ *
+ * An address the backend holds no record for resolves to a well-formed
+ * payload with `termsAccepted: false` and the optional state fields absent.
+ *
+ * @throws {PerpsError} On backend error responses, network, or parsing errors.
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ apiKey: 'your-api-key' })
+ * const status = await getReferralStatus(client, {
+ *   address: '0x1234...',
+ *   code: 'ABC123',
+ * })
+ * if (status.onboarding) {
+ *   // one signature is outstanding; submit it via PerpsClient.submitOnboarding
+ * }
+ * ```
+ * @public
+ */
+export async function getReferralStatus(
+  client: PerpsSDKClient,
+  params: GetReferralStatusParams,
+  options?: SDKRequestOptions
+): Promise<ReferralStatus> {
+  const url = buildUrl(`${client.config.apiUrl}/meta/referral`, {
+    address: params.address,
+    code: params.code,
+  })
+  return request<ReferralStatus>(client.config, url, {}, options)
+}

package/src/types/api.ts

@@ -2,14 +2,19 @@ import type {
   AccountConfigSetting,
   AccountResponse,
   CancelTwapOrderParams as ActionCancelTwapOrderParams,
+  CreateReferralCodeParams as ActionCreateReferralCodeParams,
+  ActionParamsMap,
   PlaceTwapOrderParams as ActionPlaceTwapOrderParams,
   ActionStep,
   ExecuteActionResponse,
   MarginMode,
   MarketRef,
+  MetaActionType,
   ModifyOrderInput,
+  OnboardParams,
   OrderSide,
   OrderType,
+  ProviderAction,
   SignedActionStep,
   TimeInForce,
   TriggerOrderInput,
@@ -283,6 +288,19 @@ export interface GetWithdrawableBalancesParams {
   address: Address
 }
 
+/**
+ * One entry on {@link ProviderSetup.checklist}: a user-facing setup
+ * descriptor plus its satisfied state for the queried account.
+ *
+ * @public
+ */
+export interface SetupChecklistItem {
+  /** The `Provider.setup` descriptor for this step. */
+  descriptor: ProviderAction
+  /** Whether the step is already satisfied for this account. */
+  satisfied: boolean
+}
+
 /**
  * Result from {@link PerpsClient.checkSetup}.
  *
@@ -308,6 +326,15 @@ export interface ProviderSetup {
   setup: ActionStep[]
   /** Whether all setup items are already satisfied (ready to trade) */
   isReady: boolean
+  /**
+   * The renderable onboarding list: every USER-signed setup descriptor with
+   * its satisfied state, ordered by `sequence`. SDK-internal steps and
+   * conditional steps that staged no work for this account (see
+   * `PerpsProviderPlugin.conditionalSetupActions`) are omitted. Consumers
+   * render this list directly instead of joining `Provider.setup` metadata
+   * with the staged `setup` steps.
+   */
+  checklist: SetupChecklistItem[]
 }
 
 /**
@@ -344,3 +371,33 @@ export interface GetAccountResult extends AccountResponse {
   /** SDK-projected current state of every setup + options descriptor. */
   settings: AccountConfigSetting[]
 }
+
+/**
+ * Parameters for {@link PerpsClient.submitOnboarding}.
+ *
+ * @public
+ */
+export interface SubmitOnboardingParams extends OnboardParams {
+  address: Address
+}
+
+/**
+ * Parameters for {@link PerpsClient.createReferralCode}.
+ *
+ * @public
+ */
+export interface CreateReferralCodeActionParams
+  extends ActionCreateReferralCodeParams {
+  address: Address
+}
+
+/**
+ * Parameters for {@link PerpsClient.executeMetaAction}.
+ *
+ * @public
+ */
+export interface ExecuteMetaActionParams<T extends MetaActionType> {
+  address: Address
+  action: T
+  params: ActionParamsMap[T]
+}

package/src/types/provider.ts

@@ -358,6 +358,16 @@ export interface PerpsProviderPlugin {
    */
   readonly internalSetupActions?: readonly ActionType[]
 
+  /**
+   * Setup actions that stage work only when the account needs remediation
+   * (e.g. Hyperliquid's REVOKE_AGENT frees an agent slot only when every
+   * named slot is taken). When such a step stages no actions,
+   * `PerpsClient.checkSetup` omits it from `ProviderSetup.checklist` instead
+   * of rendering it as satisfied. Omit when every setup step is
+   * unconditional.
+   */
+  readonly conditionalSetupActions?: readonly ActionType[]
+
   /**
    * Inject the runtime {@link PerpsSDKClient} into the plugin once, during
    * {@link createPerpsClient}. The plugin captures it (config, fetch, retry,

package/src/utils/setupActions.ts

@@ -8,9 +8,10 @@ import { PerpsSigner } from '@lifi/perps-types'
  * them inline, so surfacing them would render inert cards the user can't act on.
  *
  * Membership is a property of the descriptor's `signers` alone, independent of
- * any account: use this to build the onboarding list, then layer each entry's
- * satisfied/unsatisfied state on top from a live `checkSetup` so the tick never
- * goes stale.
+ * any account. When an account is available, prefer `ProviderSetup.checklist`
+ * from `checkSetup` for the onboarding list — it applies this filter, omits
+ * not-required conditional steps, and carries each entry's satisfied state.
+ * This function remains the static, account-free projection.
  *
  * @param setup The provider's `setup` descriptors, in their declared order.
  * @public

package/src/utils/switchChain.ts

@@ -8,12 +8,26 @@ import { getChainId } from 'viem/actions'
 import { PerpsError } from '../errors/PerpsError.js'
 import type { PerpsClientSigner, SwitchChainHook } from '../types/config.js'
 
+/**
+ * The chain `actions` are signed on: the first numeric
+ * `typedData.domain.chainId` across the batch, or `undefined` when no step
+ * carries one.
+ */
+export function eip712DomainChainId(actions: ActionStep[]): number | undefined {
+  for (const step of actions) {
+    const chainId = (step as Eip712ActionStep).typedData?.domain?.chainId
+    if (typeof chainId === 'number') {
+      return chainId
+    }
+  }
+  return undefined
+}
+
 /**
  * The chain a batch of `actions` must be signed on, or `undefined` when no
  * wallet chain switch applies. Only USER-signed EIP-712 batches carry a target
  * (agent-signed batches sign with a chain-bound keypair; other schemes are not
- * EIP-712). Reads the first numeric `typedData.domain.chainId`; a batch whose
- * steps omit `chainId` yields `undefined`.
+ * EIP-712).
  */
 export function userEip712TargetChainId(
   descriptor: ProviderAction,
@@ -25,13 +39,7 @@ export function userEip712TargetChainId(
   ) {
     return undefined
   }
-  for (const step of actions) {
-    const chainId = (step as Eip712ActionStep).typedData?.domain?.chainId
-    if (typeof chainId === 'number') {
-      return chainId
-    }
-  }
-  return undefined
+  return eip712DomainChainId(actions)
 }
 
 /**

package/src/version.ts

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