@lifi/perps-sdk 6.2.0 → 6.3.0

package/src/client/PerpsClient.ts

@@ -20,8 +20,10 @@ import {
   PerpsSigner,
   SigningMethod,
 } from '@lifi/perps-types'
+import Big from 'big.js'
 import type { Address } from 'viem'
 import { PerpsError } from '../errors/PerpsError.js'
+import { getAssetRegistry } from '../registry/assetRegistry.js'
 import { createAction } from '../services/createAction.js'
 import { executeAction } from '../services/executeAction.js'
 import { getAccount as fetchAccount } from '../services/getAccount.js'
@@ -34,6 +36,7 @@ import type {
   GetAccountResult,
   GetDepositFlowParams,
   GetSetupParams,
+  GetWithdrawableBalancesParams,
   ModifyOrdersParams,
   PerpsClientOptions,
   PlaceOrderParams,
@@ -51,6 +54,7 @@ import type {
   SignActionProgress,
   SignActionsContext,
 } from '../types/provider.js'
+import type { WithdrawableBalance } from '../types/withdrawal.js'
 import {
   switchSigningChain,
   userEip712TargetChainId,
@@ -493,6 +497,57 @@ export class PerpsClient {
     return plugin.getDepositFlow?.({ address: params.address })
   }
 
+  /**
+   * The `(asset, route)` selections `params.address` can actually withdraw at
+   * `params.provider`. The venue owns how its balances split across routes;
+   * this join adds the core `/assets` metadata — precision, L1 identity and
+   * the per-asset minimum — and drops every row the minimum rules out, plus
+   * any row whose asset the provider's registry does not carry, since without
+   * that metadata the amount can be neither scaled nor validated.
+   *
+   * @returns `undefined` when the registered plugin declares no withdrawable
+   *   read.
+   * @throws {PerpsError} When the provider plugin is not registered, or either
+   *   the plugin read or the asset sync fails.
+   * @public
+   */
+  async getWithdrawableBalances(
+    params: GetWithdrawableBalancesParams
+  ): Promise<WithdrawableBalance[] | undefined> {
+    const plugin = this.requireProvider(params.provider)
+    const rows = await plugin.getWithdrawableBalances?.({
+      address: params.address,
+    })
+    if (rows === undefined) {
+      return undefined
+    }
+
+    const registry = getAssetRegistry(this.sdkClient, params.provider)
+    await registry.sync()
+    return rows.flatMap((row) => {
+      const asset = registry.get(row.assetId)
+      if (asset === undefined) {
+        return []
+      }
+      const minimum = asset.minWithdrawalAmount
+      if (minimum !== undefined) {
+        let floor: Big
+        try {
+          floor = new Big(minimum)
+        } catch {
+          throw new PerpsError(
+            PerpsErrorCode.SDKError,
+            `Asset '${asset.id}' field \`minWithdrawalAmount\` is not a valid decimal.`
+          )
+        }
+        if (new Big(row.available).lt(floor)) {
+          return []
+        }
+      }
+      return [{ asset, route: row.route, available: row.available }]
+    })
+  }
+
   /**
    * Return the unsatisfied entries on `Provider.setup` for this account as a
    * flat, self-describing list. Trading is gated on `isReady === true`.

package/src/index.ts

@@ -101,6 +101,7 @@ export type {
   GetAccountResult,
   GetDepositFlowParams,
   GetSetupParams,
+  GetWithdrawableBalancesParams,
   ModifyOrdersParams,
   PerpsClientOptions,
   PerpsConfig,
@@ -143,10 +144,16 @@ export type {
   ProviderGetOrdersParams,
   ProviderGetPositionsParams,
   ProviderGetQuoteParams,
+  ProviderGetWithdrawableBalancesParams,
   QuoteListener,
   SignActionProgress,
   SignActionsContext,
 } from './types/provider.js'
+export type {
+  ProviderWithdrawableBalance,
+  WithdrawableBalance,
+  WithdrawalRoute,
+} from './types/withdrawal.js'
 export {
   type CollateralSemantics,
   summarizeAccount,

package/src/types/api.ts

@@ -243,6 +243,16 @@ export interface GetDepositFlowParams {
   address: Address
 }
 
+/**
+ * Parameters for {@link PerpsClient.getWithdrawableBalances}.
+ *
+ * @public
+ */
+export interface GetWithdrawableBalancesParams {
+  provider: string
+  address: Address
+}
+
 /**
  * Result from {@link PerpsClient.checkSetup}.
  *

package/src/types/provider.ts

@@ -33,6 +33,7 @@ import type {
   SDKRequestOptions,
 } from './config.js'
 import type { DepositFlow } from './deposit.js'
+import type { ProviderWithdrawableBalance } from './withdrawal.js'
 
 /**
  * Low-level SDK client: resolved config, the optional end-user wallet, and the
@@ -176,6 +177,15 @@ export interface ProviderGetDepositFlowParams {
   address: Address
 }
 
+/**
+ * Read params for {@link PerpsProviderPlugin.getWithdrawableBalances}.
+ *
+ * @public
+ */
+export interface ProviderGetWithdrawableBalancesParams {
+  address: Address
+}
+
 /**
  * Read params for {@link PerpsProvider.getPositions}.
  *
@@ -377,6 +387,21 @@ export interface PerpsProviderPlugin {
     options?: SDKRequestOptions
   ): Promise<DepositFlow>
 
+  /**
+   * The `(asset, route)` pairs `params.address` currently has something to
+   * withdraw from, keyed by provider-native asset id. Only the venue knows how
+   * its balance payload splits across routes, so the split is owned here; the
+   * per-asset venue minimum is applied by `PerpsClient.getWithdrawableBalances`,
+   * which holds the core asset registry.
+   *
+   * Optional: a provider whose withdrawals are not a per-route selection omits
+   * it, and `PerpsClient.getWithdrawableBalances` then resolves `undefined`.
+   */
+  getWithdrawableBalances?(
+    params: ProviderGetWithdrawableBalancesParams,
+    options?: SDKRequestOptions
+  ): Promise<ProviderWithdrawableBalance[]>
+
   getPositions(
     params: ProviderGetPositionsParams,
     options?: SDKRequestOptions

package/src/types/withdrawal.ts

@@ -0,0 +1,39 @@
+import type { Asset } from '@lifi/perps-types'
+
+/**
+ * Which of a venue's two balance routes a withdrawal is drawn from. Lighter's
+ * own vocabulary, carried in the signed tx as `AssetRouteType` (`perps` = 0,
+ * `spot` = 1); an account's mode changes what the two balances mean, never
+ * which route the tx names.
+ *
+ * @public
+ */
+export type WithdrawalRoute = 'perps' | 'spot'
+
+/**
+ * One withdrawable `(asset, route)` selection as the provider reports it, keyed
+ * by provider-native asset id and awaiting the core asset-metadata join.
+ *
+ * @public
+ */
+export interface ProviderWithdrawableBalance {
+  /** Provider-native `Asset.id`; never a display symbol. */
+  assetId: string
+  route: WithdrawalRoute
+  /** Withdrawable amount in the asset's own units. Always greater than zero. */
+  available: string
+}
+
+/**
+ * One withdrawable `(asset, route)` selection a caller can act on: the amount
+ * clears the asset's venue minimum, and `asset` carries the precision and
+ * minimum needed to scale and validate the withdrawal.
+ *
+ * @public
+ */
+export interface WithdrawableBalance {
+  asset: Asset
+  route: WithdrawalRoute
+  /** Withdrawable amount in the asset's own units. */
+  available: string
+}

package/src/version.ts

@@ -1,2 +1,13 @@
+/**
+ * Package name used in SDK telemetry and request metadata.
+ *
+ * @public
+ */
 export const name = '@lifi/perps-sdk'
-export const version = '6.2.0'
+
+/**
+ * Published SDK version sent in the `x-lifi-perps-sdk` request header.
+ *
+ * @public
+ */
+export const version = '6.3.0'