@lifi/perps-sdk 0.1.1-alpha.9 → 0.2.0-alpha.0

package/src/index.ts

@@ -2,6 +2,9 @@
 
 // Types
 export * from '@lifi/perps-types'
+// Utils
+// biome-ignore lint/correctness/useImportExtensions: package subpath export
+export { HlAbstractionMode } from '@lifi/perps-types/providers/hyperliquid'
 // Agent
 export { AgentManager } from './agent/AgentManager.js'
 export { createMemoryStorage, localStorageAdapter } from './agent/storage.js'
@@ -18,74 +21,139 @@ export {
   DEFAULT_API_URL,
 } from './client/createPerpsClient.js'
 export { PerpsClient } from './client/PerpsClient.js'
+export { projectAccountConfigSettings } from './client/projectAccountConfigSettings.js'
 export type {
-  BuildAuthorizationParams,
-  BuildWithdrawalParams,
   CancelOrdersParams,
-  ExecuteAuthorizationsParams,
-  ExecuteAuthorizationsResult,
-  GetRequiredAuthorizationsParams,
+  CheckPrerequisitesParams,
+  GetAccountResult,
+  GetSetupParams,
+  HyperliquidConfig,
+  ModifyOrdersParams,
   PerpsClientOptions,
-  PlaceOrderParams,
-  RequiredAuthorizationsResult,
-  SigningMode,
+  PlaceOrderParams as ClientPlaceOrderParams,
+  PlaceTriggerOrderParams as ClientPlaceTriggerOrderParams,
+  ProviderConfig,
+  ProviderConfigs,
+  SatisfySetupParams,
+  SatisfySetupResult,
+  SetupResult,
 } from './client/types.js'
-// Dex
-export { getDexAuthProvider } from './dex/registry.js'
-export type { DexAuthInputs, DexAuthProvider } from './dex/types.js'
-export { AgentError } from './errors/AgentError.js'
-export { PerpsErrorMessage, PerpsErrorName } from './errors/constants.js'
+export { SigningMode } from './client/types.js'
 // Errors
-export { HTTPError } from './errors/HTTPError.js'
+export { PerpsErrorMessage } from './errors/constants.js'
 export { PerpsError } from './errors/PerpsError.js'
-export { PerpsSDKError } from './errors/PerpsSDKError.js'
-export { ServerError } from './errors/ServerError.js'
-export {
-  findErrorType,
-  getErrorChain,
-  getRootCause,
-  getRootCauseMessage,
-  hasErrorType,
-} from './errors/utils/rootCause.js'
-export { ValidationError } from './errors/ValidationError.js'
+export { projectHyperliquidConfigSettings } from './providers/hyperliquid/accountConfig.js'
+export { projectLighterConfigSettings } from './providers/lighter/accountConfig.js'
 // Realtime
 export { PerpsWsClient } from './realtime/PerpsWsClient.js'
 export type { EventForSubscription } from './realtime/types.js'
-export type { CancelOrderParams } from './services/cancelOrder.js'
 // Services
-export { cancelOrder } from './services/cancelOrder.js'
-export type { CreateAuthorizationParams } from './services/createAuthorization.js'
-export { createAuthorization } from './services/createAuthorization.js'
-export type { CreateOrderParams } from './services/createOrder.js'
-export { createOrder } from './services/createOrder.js'
-export type { CreateWithdrawalParams } from './services/createWithdrawal.js'
-export { createWithdrawal } from './services/createWithdrawal.js'
+export type { CreateActionParams } from './services/createAction.js'
+export { createAction } from './services/createAction.js'
+export type { ExecuteActionParams } from './services/executeAction.js'
+export { executeAction } from './services/executeAction.js'
 export type { GetAccountParams } from './services/getAccount.js'
 export { getAccount } from './services/getAccount.js'
-export { getDexes } from './services/getDexes.js'
-export type { GetHistoryParams } from './services/getHistory.js'
-export { getHistory } from './services/getHistory.js'
-export type { GetMarketParams } from './services/getMarket.js'
-export { getMarket } from './services/getMarket.js'
-export type { GetMarketsParams } from './services/getMarkets.js'
-export { getMarkets } from './services/getMarkets.js'
+export type { GetActivityParams } from './services/getActivity.js'
+export { getActivity } from './services/getActivity.js'
+export type { GetAssetParams } from './services/getAsset.js'
+export { getAsset } from './services/getAsset.js'
+export type { GetAssetsParams } from './services/getAssets.js'
+export { getAssets } from './services/getAssets.js'
+export type { GetFillsParams } from './services/getFills.js'
+export { getFills } from './services/getFills.js'
 export type { GetOhlcvParams } from './services/getOhlcv.js'
 export { getOhlcv } from './services/getOhlcv.js'
 export type { GetOrderParams } from './services/getOrder.js'
 export { getOrder } from './services/getOrder.js'
 export type { GetOrderbookParams } from './services/getOrderbook.js'
 export { getOrderbook } from './services/getOrderbook.js'
+export type { GetOrdersParams } from './services/getOrders.js'
+export { getOrders } from './services/getOrders.js'
+export type { GetPositionsParams } from './services/getPositions.js'
+export { getPositions } from './services/getPositions.js'
 export type { GetPricesParams } from './services/getPrices.js'
 export { getPrices } from './services/getPrices.js'
-export type { SubmitAuthorizationParams } from './services/submitAuthorization.js'
-export { submitAuthorization } from './services/submitAuthorization.js'
-export type { SubmitOrderParams } from './services/submitOrder.js'
-export { submitOrder } from './services/submitOrder.js'
-export type { SubmitWithdrawalParams } from './services/submitWithdrawal.js'
-export { submitWithdrawal } from './services/submitWithdrawal.js'
-
-// Utils
+export { getProviders } from './services/getProviders.js'
+// Signers
+export type {
+  ApiKeyPair,
+  ApproveReadOnlyTokenInputs,
+  ApproveReadOnlyTokenResult,
+  ChangePubKeyResult,
+  LighterApiKey,
+  LighterCreateTokenResponse,
+  LighterReadOnlyToken,
+  LighterReadOnlyTokenManagerOptions,
+  LighterSignedBlob,
+  LighterSignerConfig,
+  LighterSignerContext,
+  LighterTokenFetcher,
+  LighterWalletSigner,
+  LighterWasmExports,
+  LoadLighterWasmOptions,
+} from './signers/lighter/index.js'
+export {
+  buildReadOnlyTokenMessage,
+  DEFAULT_API_KEY_INDEX,
+  DEFAULT_LIGHTER_API_URL,
+  DEFAULT_READ_ONLY_TOKEN_NAME,
+  defaultLighterTokenFetcher,
+  LIGHTER_PROVIDER_KEY,
+  LighterKeyStore,
+  LighterReadOnlyTokenManager,
+  LighterSigner,
+  loadLighterWasm,
+  resetLighterWasmCache,
+  walletClientSigner,
+} from './signers/lighter/index.js'
+export type { AccountSummary } from './utils/accountSummary.js'
+export { calculateAccountSummary } from './utils/accountSummary.js'
+export type { ExpectedPnl } from './utils/calculations.js'
+export {
+  applySlippage,
+  calculateExpectedPnl,
+  calculateNotionalValue,
+  calculatePositionSize,
+  calculateRealizedPnlPercent,
+  calculateRequiredMargin,
+  calculateRoe,
+  calculateUnrealizedPnl,
+  estimateFees,
+  percentFromPrice,
+  priceFromPercent,
+} from './utils/calculations.js'
+export {
+  calculateLiquidationPrice,
+  calculateMaintenanceMarginRate,
+  formatOrderPrice,
+  formatOrderSize,
+  getMaxPriceDecimals,
+} from './utils/hyperliquid/index.js'
+export {
+  classifyFill,
+  FillClassification,
+  isStopLossOrder,
+  isTakeProfitOrder,
+  isTpSlOrder,
+} from './utils/orderClassification.js'
+export {
+  expectedRealizedPnlForOpenOrder,
+  expectedRealizedPnlForTriggerOrder,
+  findMatchingPosition,
+  resolveCloseSize,
+} from './utils/orderMath.js'
+export { stringToFloat } from './utils/parse.js'
+export {
+  directionSign,
+  predictAverageEntryPrice,
+  predictNewLeverage,
+  predictUnrealizedPnl,
+  realizedPnlOnClose,
+} from './utils/positionMath.js'
 export { signTypedData } from './utils/signTypedData.js'
+export { fromBaseUnits, fromBaseUnitsNumber } from './utils/units.js'
+export { validateMargin } from './utils/validation.js'
 
 // Version
 export { name, version } from './version.js'

package/src/providers/hyperliquid/accountConfig.ts

@@ -0,0 +1,92 @@
+import type {
+  AccountConfigSetting,
+  HyperliquidAccountConfig,
+  ProviderActionDescriptor,
+  ProviderOption,
+  ProviderSetup,
+} from '@lifi/perps-types'
+import { ActionType, PerpsErrorCode } from '@lifi/perps-types'
+import { PerpsError } from '../../errors/PerpsError.js'
+import { assertNever } from '../../utils/assertNever.js'
+
+/**
+ * Project a single Hyperliquid descriptor against the typed
+ * `HyperliquidAccountConfig` into an `AccountConfigSetting`.
+ *
+ * Mapping table:
+ *
+ * | descriptor.type          | projected values
+ * |--------------------------|-----------------------------------------------
+ * | APPROVE_AGENT            | []                  (no parameters)
+ * | APPROVE_BUILDER_FEE      | []                  (no parameters)
+ * | ACCOUNT_MODE             | [{ name: 'mode', value: config.abstractionMode }]
+ *
+ * The switch is exhaustive over `ActionType` so enum additions force a
+ * compile error in the `default` arm. ActionTypes that are not valid on
+ * `Provider.setup` / `Provider.options` throw at runtime.
+ */
+function projectHyperliquidDescriptor(
+  descriptor: ProviderActionDescriptor,
+  config: HyperliquidAccountConfig
+): AccountConfigSetting {
+  switch (descriptor.type) {
+    // Zero-parameter user-approval descriptors. The "satisfied or not"
+    // state for these comes from `checkSetup`'s unsatisfied list, not from
+    // a projected value.
+    case ActionType.APPROVE_AGENT:
+    case ActionType.APPROVE_BUILDER_FEE:
+      return { type: descriptor.type, values: [] }
+
+    // `config.abstractionMode === null` means abstraction has never been set;
+    // callers fall back to the descriptor's `default` ParamOption.
+    case ActionType.ACCOUNT_MODE:
+      return {
+        type: descriptor.type,
+        values: [{ name: 'mode', value: config.abstractionMode }],
+      }
+
+    case ActionType.ACCOUNT_TYPE:
+    case ActionType.SEND_ASSET:
+    case ActionType.WITHDRAWAL:
+    case ActionType.TRANSFER:
+    case ActionType.PLACE_ORDER:
+    case ActionType.PLACE_TRIGGER_ORDER:
+    case ActionType.CANCEL_ORDER:
+    case ActionType.CANCEL_ALL_ORDERS:
+    case ActionType.MODIFY_ORDER:
+    case ActionType.UPDATE_LEVERAGE:
+    case ActionType.UPDATE_POSITION_MARGIN:
+    case ActionType.REGISTER_API_KEY:
+    case ActionType.APPROVE_READ_ONLY_TOKEN:
+    case ActionType.DEPOSIT:
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `Hyperliquid account-config mapper has no projection for ` +
+          `descriptor type '${descriptor.type}' — this ActionType is not ` +
+          `valid on Provider.setup / Provider.options for Hyperliquid.`
+      )
+
+    default:
+      return assertNever(descriptor.type)
+  }
+}
+
+/**
+ * Project the union of Hyperliquid setup + options descriptors against the
+ * typed `HyperliquidAccountConfig`. Produces exactly one
+ * `AccountConfigSetting` per descriptor, in `setup`-then-`options` order
+ * (preserving the order in which the backend emits them).
+ *
+ * @param config Typed account state for the Hyperliquid account.
+ * @param setup  `Provider.setup` array as emitted by `/providers`.
+ * @param options `Provider.options` array as emitted by `/providers`.
+ */
+export function projectHyperliquidConfigSettings(
+  config: HyperliquidAccountConfig,
+  setup: ProviderSetup[],
+  options: ProviderOption[]
+): AccountConfigSetting[] {
+  return [...setup, ...options].map((descriptor) =>
+    projectHyperliquidDescriptor(descriptor, config)
+  )
+}

package/src/providers/lighter/accountConfig.ts

@@ -0,0 +1,103 @@
+import type {
+  AccountConfigSetting,
+  LighterAccountConfig,
+  ProviderActionDescriptor,
+  ProviderOption,
+  ProviderSetup,
+} from '@lifi/perps-types'
+import { ActionType, PerpsErrorCode } from '@lifi/perps-types'
+import { PerpsError } from '../../errors/PerpsError.js'
+import { assertNever } from '../../utils/assertNever.js'
+
+/**
+ * Project a single Lighter descriptor against the typed
+ * `LighterAccountConfig` into an `AccountConfigSetting`.
+ *
+ * Mapping table:
+ *
+ * | descriptor.type           | projected values
+ * |---------------------------|--------------------------------------------------
+ * | REGISTER_API_KEY          | []                  (no parameters)
+ * | APPROVE_READ_ONLY_TOKEN   | []                  (no parameters)
+ * | ACCOUNT_MODE              | [{ name: 'mode', value: null }]  (Lighter has no
+ * |                           |  abstraction-mode equivalent; read-only here)
+ * | ACCOUNT_TYPE              | [{ name: 'tier', value: config.accountType }]
+ *
+ * The switch is exhaustive over `ActionType` so enum additions force a
+ * compile error in the `default` arm. ActionTypes that are not valid on
+ * `Provider.setup` / `Provider.options` throw at runtime.
+ */
+function projectLighterDescriptor(
+  descriptor: ProviderActionDescriptor,
+  config: LighterAccountConfig
+): AccountConfigSetting {
+  switch (descriptor.type) {
+    // Zero-parameter user-approval descriptors. The "satisfied or not"
+    // state comes from `checkSetup`'s unsatisfied list and the
+    // `config.apiKeyRegistered` / `config.readOnlyTokenApproved` flags,
+    // not from a projected value.
+    case ActionType.REGISTER_API_KEY:
+    case ActionType.APPROVE_READ_ONLY_TOKEN:
+      return { type: descriptor.type, values: [] }
+
+    // Lighter exposes no abstraction-mode equivalent; if a backend descriptor
+    // surfaces ACCOUNT_MODE on Lighter it always projects `null` and callers
+    // fall back to the descriptor's `default` ParamOption.
+    case ActionType.ACCOUNT_MODE:
+      return {
+        type: descriptor.type,
+        values: [{ name: 'mode', value: null }],
+      }
+
+    // `tier` maps to the raw integer `config.accountType` Lighter publishes;
+    // decoding to a human label is the caller's responsibility.
+    case ActionType.ACCOUNT_TYPE:
+      return {
+        type: descriptor.type,
+        values: [{ name: 'tier', value: config.accountType }],
+      }
+
+    case ActionType.APPROVE_AGENT:
+    case ActionType.APPROVE_BUILDER_FEE:
+    case ActionType.SEND_ASSET:
+    case ActionType.WITHDRAWAL:
+    case ActionType.TRANSFER:
+    case ActionType.PLACE_ORDER:
+    case ActionType.PLACE_TRIGGER_ORDER:
+    case ActionType.CANCEL_ORDER:
+    case ActionType.CANCEL_ALL_ORDERS:
+    case ActionType.MODIFY_ORDER:
+    case ActionType.UPDATE_LEVERAGE:
+    case ActionType.UPDATE_POSITION_MARGIN:
+    case ActionType.DEPOSIT:
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `Lighter account-config mapper has no projection for ` +
+          `descriptor type '${descriptor.type}' — this ActionType is not ` +
+          `valid on Provider.setup / Provider.options for Lighter.`
+      )
+
+    default:
+      return assertNever(descriptor.type)
+  }
+}
+
+/**
+ * Project the union of Lighter setup + options descriptors against the typed
+ * `LighterAccountConfig`. Produces exactly one `AccountConfigSetting` per
+ * descriptor, in `setup`-then-`options` order (preserving the order in which
+ * the backend emits them).
+ *
+ * @param config Typed account state for the Lighter account.
+ * @param setup  `Provider.setup` array as emitted by `/providers`.
+ * @param options `Provider.options` array as emitted by `/providers`.
+ */
+export function projectLighterConfigSettings(
+  config: LighterAccountConfig,
+  setup: ProviderSetup[],
+  options: ProviderOption[]
+): AccountConfigSetting[] {
+  return [...setup, ...options].map((descriptor) =>
+    projectLighterDescriptor(descriptor, config)
+  )
+}

package/src/realtime/PerpsWsClient.ts

@@ -1,24 +1,44 @@
 import type { Subscription } from '@lifi/perps-types'
 import type { PerpsSDKClient } from '../client/createPerpsClient.js'
-import { getDexes } from '../services/getDexes.js'
-import { getMarkets } from '../services/getMarkets.js'
+import { getProviders } from '../services/getProviders.js'
 import { HyperliquidWsProvider } from './hyperliquid/HyperliquidWsProvider.js'
-import type { EventForSubscription, SubscriptionListener } from './types.js'
+import {
+  type LighterAuthProvider,
+  LighterWsProvider,
+} from './lighter/LighterWsProvider.js'
+import type {
+  EventForSubscription,
+  SubscriptionListener,
+  WsProvider,
+} from './types.js'
+
+export interface PerpsWsClientOptions {
+  /**
+   * Async function that mints a Lighter auth token for an L1 address. When
+   * provided, authenticated Lighter channels (orderUpdates, positions) will
+   * use the returned token. The provider is invoked on each subscribe send,
+   * including reconnects, so callers can transparently rotate tokens.
+   */
+  lighterAuthProvider?: LighterAuthProvider
+}
 
 export class PerpsWsClient {
   private readonly client: PerpsSDKClient
-  private providers = new Map<string, HyperliquidWsProvider>()
-  private initPromises = new Map<string, Promise<HyperliquidWsProvider>>()
+  private readonly options: PerpsWsClientOptions
+  private providers = new Map<string, WsProvider>()
+  private initPromises = new Map<string, Promise<WsProvider>>()
 
-  constructor(client: PerpsSDKClient) {
+  constructor(client: PerpsSDKClient, options: PerpsWsClientOptions = {}) {
     this.client = client
+    this.options = options
   }
 
   async subscribe<S extends Subscription>(
     sub: S,
     listener: (event: EventForSubscription<S>) => void
   ): Promise<() => void> {
-    const provider = await this.getOrCreateProvider(sub.dex)
+    const providerKey = sub.dex
+    const provider = await this.getOrCreateProvider(providerKey)
     return provider.subscribe(sub, listener as SubscriptionListener)
   }
 
@@ -30,44 +50,59 @@ export class PerpsWsClient {
     this.initPromises.clear()
   }
 
-  private async getOrCreateProvider(
-    dex: string
-  ): Promise<HyperliquidWsProvider> {
-    const existing = this.providers.get(dex)
+  private async getOrCreateProvider(provider: string): Promise<WsProvider> {
+    const existing = this.providers.get(provider)
     if (existing) {
       return existing
     }
 
-    let initPromise = this.initPromises.get(dex)
+    let initPromise = this.initPromises.get(provider)
     if (!initPromise) {
-      initPromise = this.initProvider(dex)
-      this.initPromises.set(dex, initPromise)
+      initPromise = this.initProvider(provider)
+      this.initPromises.set(provider, initPromise)
     }
     return initPromise
   }
 
-  private async initProvider(dex: string): Promise<HyperliquidWsProvider> {
-    const [{ dexes }, { markets }] = await Promise.all([
-      getDexes(this.client),
-      getMarkets(this.client, { dex }),
-    ])
+  private async initProvider(provider: string): Promise<WsProvider> {
+    const { providers } = await getProviders(this.client)
 
-    const dexInfo = dexes.find((d) => d.key === dex)
-    if (!dexInfo?.wsUrl) {
-      throw new Error(`No WebSocket URL found for dex: ${dex}`)
+    const providerInfo = providers.find((d) => d.key === provider)
+    if (!providerInfo?.wsUrl) {
+      throw new Error(`No WebSocket URL found for provider: ${provider}`)
     }
 
-    const assetIdLookup = new Map<string, number>()
-    for (const m of markets) {
-      assetIdLookup.set(m.symbol, m.assetId)
-    }
+    const allMarkets = (providerInfo.markets ?? []) as Array<{
+      id: string
+    }>
+    const providerConfig = this.client.config.providers?.[provider]
+    const configuredMarkets = providerConfig?.markets
+    const filteredMarkets = configuredMarkets
+      ? allMarkets.filter((m) => configuredMarkets.includes(m.id))
+      : allMarkets
+    const subProviders = filteredMarkets
+      .map((m) => m.id)
+      .filter((id) => id !== provider && id !== 'spot')
 
-    const provider = new HyperliquidWsProvider(
-      dexInfo.wsUrl,
-      dex,
-      assetIdLookup
+    const wsProvider = this.createWsProvider(
+      provider,
+      providerInfo.wsUrl,
+      subProviders
     )
-    this.providers.set(dex, provider)
-    return provider
+    this.providers.set(provider, wsProvider)
+    return wsProvider
+  }
+
+  private createWsProvider(
+    provider: string,
+    wsUrl: string,
+    subProviders: string[]
+  ): WsProvider {
+    if (provider === 'lighter') {
+      return new LighterWsProvider(wsUrl, provider, {
+        authProvider: this.options.lighterAuthProvider,
+      })
+    }
+    return new HyperliquidWsProvider(wsUrl, provider, subProviders)
   }
 }