@lifi/perps-sdk 0.0.0-preview-c95cec0 → 0.0.0-preview-e1b82a0

package/src/client/PerpsClient.ts

@@ -60,6 +60,7 @@ import type {
   GetPortfolioHistoryParams,
   GetSetupParams,
   GetWithdrawableBalancesParams,
+  GetWithdrawalTypesParams,
   GetWithdrawFlowParams,
   ModifyOrdersParams,
   PerpsClientOptions,
@@ -85,7 +86,11 @@ import type {
   SignActionProgress,
   SignActionsContext,
 } from '../types/provider.js'
-import type { WithdrawableBalance, WithdrawFlow } from '../types/withdrawal.js'
+import type {
+  WithdrawableBalance,
+  WithdrawalSourceTypes,
+  WithdrawFlow,
+} from '../types/withdrawal.js'
 import { isUserFacingSetupStep } from '../utils/setupActions.js'
 import { signTypedDataWithSigner } from '../utils/signTypedData.js'
 import {
@@ -648,13 +653,16 @@ export class PerpsClient {
    *   backend account fetch fails.
    * @public
    */
-  async getAccount(params: {
-    provider: string
-    address: Address
-  }): Promise<GetAccountResult> {
+  async getAccount(
+    params: {
+      provider: string
+      address: Address
+    },
+    options?: SDKRequestOptions
+  ): Promise<GetAccountResult> {
     const plugin = this.requireProvider(params.provider)
     const [response, metadata] = await Promise.all([
-      fetchAccount(this.sdkClient, params),
+      fetchAccount(this.sdkClient, params, options),
       this.getProviderMetadata(params.provider),
     ])
     const settings = plugin.projectConfig(response.config, metadata.setup)
@@ -674,16 +682,19 @@ export class PerpsClient {
    * @throws {PerpsError} `Unauthorized` when the venue rejects the credential.
    * @public
    */
-  async getMarketSettings(params: {
-    provider: string
-    address: Address
-    market: MarketRef
-  }): Promise<MarketSettings> {
+  async getMarketSettings(
+    params: {
+      provider: string
+      address: Address
+      market: MarketRef
+    },
+    options?: SDKRequestOptions
+  ): Promise<MarketSettings> {
     const plugin = this.requireProvider(params.provider)
-    return plugin.getMarketSettings({
-      address: params.address,
-      market: params.market,
-    })
+    return plugin.getMarketSettings(
+      { address: params.address, market: params.market },
+      options
+    )
   }
 
   /**
@@ -787,8 +798,12 @@ export class PerpsClient {
    *   plugin's existence probe fails.
    * @public
    */
-  async accountExists(provider: string, address: Address): Promise<boolean> {
-    return this.requireProvider(provider).accountExists({ address })
+  async accountExists(
+    provider: string,
+    address: Address,
+    options?: SDKRequestOptions
+  ): Promise<boolean> {
+    return this.requireProvider(provider).accountExists({ address }, options)
   }
 
   /**
@@ -802,10 +817,11 @@ export class PerpsClient {
    * @public
    */
   async getDepositFlow(
-    params: GetDepositFlowParams
+    params: GetDepositFlowParams,
+    options?: SDKRequestOptions
   ): Promise<DepositFlow | undefined> {
     const plugin = this.requireProvider(params.provider)
-    return plugin.getDepositFlow?.({ address: params.address })
+    return plugin.getDepositFlow?.({ address: params.address }, options)
   }
 
   /**
@@ -819,15 +835,17 @@ export class PerpsClient {
    * @public
    */
   async getWithdrawFlow(
-    params: GetWithdrawFlowParams
+    params: GetWithdrawFlowParams,
+    options?: SDKRequestOptions
   ): Promise<WithdrawFlow | undefined> {
     const plugin = this.requireProvider(params.provider)
-    return plugin.getWithdrawFlow?.({ address: params.address })
+    return plugin.getWithdrawFlow?.({ address: params.address }, options)
   }
 
   /**
-   * The `(asset, route)` selections `params.address` can actually withdraw at
-   * `params.provider`. The venue owns how its balances split across routes;
+   * The `(asset, category)` selections `params.address` can actually withdraw
+   * at `params.provider`. The venue owns how its balances split across
+   * categories;
    * 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
@@ -845,12 +863,14 @@ export class PerpsClient {
    * @public
    */
   async getWithdrawableBalances(
-    params: GetWithdrawableBalancesParams
+    params: GetWithdrawableBalancesParams,
+    options?: SDKRequestOptions
   ): Promise<WithdrawableBalance[] | undefined> {
     const plugin = this.requireProvider(params.provider)
-    const rows = await plugin.getWithdrawableBalances?.({
-      address: params.address,
-    })
+    const rows = await plugin.getWithdrawableBalances?.(
+      { address: params.address },
+      options
+    )
     if (rows === undefined) {
       return undefined
     }
@@ -879,7 +899,12 @@ export class PerpsClient {
       }
       if (row.withdrawalFee === undefined) {
         return [
-          { asset, route: row.route, available: row.available, max: row.max },
+          {
+            asset,
+            categoryId: row.categoryId,
+            available: row.available,
+            max: row.max,
+          },
         ]
       }
       if (!isNonNegativeDecimal(row.withdrawalFee)) {
@@ -891,7 +916,7 @@ export class PerpsClient {
       return [
         {
           asset,
-          route: row.route,
+          categoryId: row.categoryId,
           available: row.available,
           max: row.max,
           withdrawalFee: row.withdrawalFee,
@@ -903,6 +928,25 @@ export class PerpsClient {
     })
   }
 
+  /**
+   * The withdrawal types `params.address` can choose per holding at
+   * `params.provider`, each with its cap and the `withdrawalOptions` to pass
+   * unchanged in `WithdrawalParams`.
+   *
+   * @returns `undefined` when the registered plugin declares no withdrawal
+   *   types read.
+   * @throws {PerpsError} When the provider plugin is not registered, or when
+   *   the plugin read fails.
+   * @public
+   */
+  async getWithdrawalTypes(
+    params: GetWithdrawalTypesParams,
+    options?: SDKRequestOptions
+  ): Promise<WithdrawalSourceTypes[] | undefined> {
+    const plugin = this.requireProvider(params.provider)
+    return plugin.getWithdrawalTypes?.({ address: params.address }, options)
+  }
+
   /**
    * The account's portfolio value and cumulative PnL over `params.range` at
    * `params.provider`, read directly from the venue.

package/src/index.ts

@@ -17,7 +17,6 @@ export {
 } from './client/createPerpsClient.js'
 export { PerpsClient } from './client/PerpsClient.js'
 export { requireProvider } from './client/requireProvider.js'
-export { isDecimalStringGreaterThan } from './decimal/compare.js'
 export type { BaseUnitsRounding } from './decimal/convert.js'
 export {
   baseUnitsToDecimal,
@@ -173,6 +172,7 @@ export type {
   GetPortfolioHistoryParams,
   GetSetupParams,
   GetWithdrawableBalancesParams,
+  GetWithdrawalTypesParams,
   GetWithdrawFlowParams,
   ModifyOrdersParams,
   PerpsClientOptions,
@@ -219,6 +219,7 @@ export type {
   ProviderGetPositionsParams,
   ProviderGetQuoteParams,
   ProviderGetWithdrawableBalancesParams,
+  ProviderGetWithdrawalTypesParams,
   ProviderGetWithdrawFlowParams,
   QuoteListener,
   SignActionProgress,
@@ -227,7 +228,8 @@ export type {
 export type {
   ProviderWithdrawableBalance,
   WithdrawableBalance,
-  WithdrawalRoute,
+  WithdrawalSourceTypes,
+  WithdrawalTypeOption,
   WithdrawFlow,
   WithdrawFlowReady,
   WithdrawFlowSetupRequired,

package/src/types/api.ts

@@ -293,6 +293,16 @@ export interface GetWithdrawableBalancesParams {
   address: Address
 }
 
+/**
+ * Parameters for {@link PerpsClient.getWithdrawalTypes}.
+ *
+ * @public
+ */
+export interface GetWithdrawalTypesParams {
+  provider: string
+  address: Address
+}
+
 /**
  * Parameters for {@link PerpsClient.getPortfolioHistory}.
  *

package/src/types/config.ts

@@ -41,17 +41,6 @@ export type RequestInterceptor = (
 export interface SDKRequestOptions {
   /** Abort the request and any pending backoff delay. */
   signal?: AbortSignal
-  /**
-   * Lighter auth token consumed by provider-direct venue reads (getOrders,
-   * getOrder, getActivity, getAccount). Create via
-   * `lighterSigner.createAuthToken(deadline, context)`. Sent only to Lighter
-   * venue endpoints, never to the LI.FI backend — read-only by design
-   * (8h max TTL, cannot authorize writes). Each call routes to a single Lighter
-   * instance via `params.provider`, so this token scopes to that instance's
-   * venue; token caches are held per `lighterProvider()` instance and do not
-   * cross between instances.
-   */
-  lighterAuthToken?: string
 }
 
 /**

package/src/types/provider.ts

@@ -37,7 +37,11 @@ import type {
   SDKRequestOptions,
 } from './config.js'
 import type { DepositFlow } from './deposit.js'
-import type { ProviderWithdrawableBalance, WithdrawFlow } from './withdrawal.js'
+import type {
+  ProviderWithdrawableBalance,
+  WithdrawalSourceTypes,
+  WithdrawFlow,
+} from './withdrawal.js'
 
 /**
  * Low-level SDK client: resolved config, the optional end-user wallet, and the
@@ -199,6 +203,15 @@ export interface ProviderGetWithdrawableBalancesParams {
   address: Address
 }
 
+/**
+ * Read params for {@link PerpsProviderPlugin.getWithdrawalTypes}.
+ *
+ * @public
+ */
+export interface ProviderGetWithdrawalTypesParams {
+  address: Address
+}
+
 /**
  * Read params for {@link PerpsProvider.getPositions}.
  *
@@ -434,20 +447,33 @@ export interface PerpsProviderPlugin {
   ): Promise<WithdrawFlow>
 
   /**
-   * The `(asset, route)` pairs `params.address` currently has something to
+   * The `(asset, category)` 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
+   * its balance payload splits across categories, 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`.
+   * Optional: a provider whose withdrawals are not a per-category selection
+   * omits it, and `PerpsClient.getWithdrawableBalances` then resolves
+   * `undefined`.
    */
   getWithdrawableBalances?(
     params: ProviderGetWithdrawableBalancesParams,
     options?: SDKRequestOptions
   ): Promise<ProviderWithdrawableBalance[]>
 
+  /**
+   * The withdrawal types `params.address` can choose per withdrawable holding,
+   * each with its cap and the `withdrawalOptions` to send with it.
+   *
+   * Optional: a provider with one withdrawal type omits it, and
+   * `PerpsClient.getWithdrawalTypes` then resolves `undefined`.
+   */
+  getWithdrawalTypes?(
+    params: ProviderGetWithdrawalTypesParams,
+    options?: SDKRequestOptions
+  ): Promise<WithdrawalSourceTypes[]>
+
   getPositions(
     params: ProviderGetPositionsParams,
     options?: SDKRequestOptions

package/src/types/withdrawal.ts

@@ -2,22 +2,22 @@ import type {
   ActionType,
   Asset,
   DecimalString,
-  WithdrawalRoute,
+  WithdrawalAssetRef,
+  WithdrawalType,
 } from '@lifi/perps-types'
 import type { Address } from 'viem'
 
-export type { WithdrawalRoute }
-
 /**
- * One withdrawable `(asset, route)` selection as the provider reports it, keyed
- * by provider-native asset id and awaiting the core asset-metadata join.
+ * One withdrawable `(asset, category)` 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
+  /** The provider category the row draws from; the same value as `Balance.categoryId`. */
+  categoryId: string
   /** Withdrawable amount in the asset's own units. Always greater than zero. */
   available: DecimalString
   /**
@@ -41,7 +41,7 @@ export interface ProviderWithdrawableBalance {
 }
 
 /**
- * One withdrawable `(asset, route)` selection a caller can act on: the amount
+ * One withdrawable `(asset, category)` 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.
  *
@@ -49,7 +49,8 @@ export interface ProviderWithdrawableBalance {
  */
 export interface WithdrawableBalance {
   asset: Asset
-  route: WithdrawalRoute
+  /** The provider category the row draws from; the same value as `Balance.categoryId`. */
+  categoryId: string
   /** Withdrawable amount in the asset's own units. */
   available: DecimalString
   /**
@@ -77,6 +78,32 @@ export interface WithdrawableBalance {
   isFeeDeducted?: boolean
 }
 
+/**
+ * One way a venue can settle a withdrawal from a holding.
+ *
+ * @public
+ */
+export interface WithdrawalTypeOption {
+  type: WithdrawalType
+  /** Largest `amount` this type accepts from the holding, in the asset's own units. */
+  max: DecimalString
+  /**
+   * Provider-specific options to pass unchanged as
+   * `WithdrawalParams.withdrawalOptions` when the user picks this type.
+   */
+  withdrawalOptions: Record<string, unknown>
+}
+
+/**
+ * The withdrawal types a venue offers for one holding.
+ *
+ * @public
+ */
+export interface WithdrawalSourceTypes {
+  source: WithdrawalAssetRef
+  options: WithdrawalTypeOption[]
+}
+
 /**
  * The venue accepts a withdrawal to `destination` now.
  *

package/src/version.ts

@@ -10,4 +10,4 @@ export const name = '@lifi/perps-sdk'
  *
  * @public
  */
-export const version = '0.0.0-preview-c95cec0'
+export const version = '0.0.0-preview-e1b82a0'

package/dist/cjs/decimal/compare.d.ts

@@ -1,3 +0,0 @@
-import type { DecimalString } from '@lifi/perps-types';
-export declare function isDecimalStringGreaterThan(a: DecimalString, b: DecimalString): boolean;
-//# sourceMappingURL=compare.d.ts.map

package/dist/cjs/decimal/compare.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../../src/decimal/compare.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAWtD,wBAAgB,0BAA0B,CACxC,CAAC,EAAE,aAAa,EAChB,CAAC,EAAE,aAAa,GACf,OAAO,CAET"}

package/dist/cjs/decimal/compare.js

@@ -1,8 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isDecimalStringGreaterThan = isDecimalStringGreaterThan;
-const requireDecimal_js_1 = require("./requireDecimal.js");
-function isDecimalStringGreaterThan(a, b) {
-    return (0, requireDecimal_js_1.requireDecimal)(a, 'a').gt((0, requireDecimal_js_1.requireDecimal)(b, 'b'));
-}
-//# sourceMappingURL=compare.js.map

package/dist/cjs/decimal/compare.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../../src/decimal/compare.ts"],"names":[],"mappings":";;AAWA,gEAKC;AAfD,2DAAoD;AAUpD,SAAgB,0BAA0B,CACxC,CAAgB,EAChB,CAAgB;IAEhB,OAAO,IAAA,kCAAc,EAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,IAAA,kCAAc,EAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;AAC1D,CAAC"}

package/dist/esm/decimal/compare.d.ts

@@ -1,11 +0,0 @@
-import type { DecimalString } from '@lifi/perps-types';
-/**
- * Exact `a > b` on two {@link DecimalString}s, with no float rounding, so a
- * funds gate can tell `'1.0000000000000001'` from `'1'`. The other relations
- * follow from it: `a <= b` is `!isDecimalStringGreaterThan(a, b)`.
- *
- * @throws {PerpsError} `ValidationError` when either operand is not a decimal string.
- * @public
- */
-export declare function isDecimalStringGreaterThan(a: DecimalString, b: DecimalString): boolean;
-//# sourceMappingURL=compare.d.ts.map

package/dist/esm/decimal/compare.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../../src/decimal/compare.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAGtD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,CAAC,EAAE,aAAa,EAChB,CAAC,EAAE,aAAa,GACf,OAAO,CAET"}

package/dist/esm/decimal/compare.js

@@ -1,13 +0,0 @@
-import { requireDecimal } from './requireDecimal.js';
-/**
- * Exact `a > b` on two {@link DecimalString}s, with no float rounding, so a
- * funds gate can tell `'1.0000000000000001'` from `'1'`. The other relations
- * follow from it: `a <= b` is `!isDecimalStringGreaterThan(a, b)`.
- *
- * @throws {PerpsError} `ValidationError` when either operand is not a decimal string.
- * @public
- */
-export function isDecimalStringGreaterThan(a, b) {
-    return requireDecimal(a, 'a').gt(requireDecimal(b, 'b'));
-}
-//# sourceMappingURL=compare.js.map

package/dist/esm/decimal/compare.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../../src/decimal/compare.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEpD;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CACxC,CAAgB,EAChB,CAAgB;IAEhB,OAAO,cAAc,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;AAC1D,CAAC"}

package/dist/types/decimal/compare.d.ts

@@ -1,11 +0,0 @@
-import type { DecimalString } from '@lifi/perps-types';
-/**
- * Exact `a > b` on two {@link DecimalString}s, with no float rounding, so a
- * funds gate can tell `'1.0000000000000001'` from `'1'`. The other relations
- * follow from it: `a <= b` is `!isDecimalStringGreaterThan(a, b)`.
- *
- * @throws {PerpsError} `ValidationError` when either operand is not a decimal string.
- * @public
- */
-export declare function isDecimalStringGreaterThan(a: DecimalString, b: DecimalString): boolean;
-//# sourceMappingURL=compare.d.ts.map

package/dist/types/decimal/compare.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../../src/decimal/compare.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAGtD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,CAAC,EAAE,aAAa,EAChB,CAAC,EAAE,aAAa,GACf,OAAO,CAET"}

package/src/decimal/compare.ts

@@ -1,17 +0,0 @@
-import type { DecimalString } from '@lifi/perps-types'
-import { requireDecimal } from './requireDecimal.js'
-
-/**
- * Exact `a > b` on two {@link DecimalString}s, with no float rounding, so a
- * funds gate can tell `'1.0000000000000001'` from `'1'`. The other relations
- * follow from it: `a <= b` is `!isDecimalStringGreaterThan(a, b)`.
- *
- * @throws {PerpsError} `ValidationError` when either operand is not a decimal string.
- * @public
- */
-export function isDecimalStringGreaterThan(
-  a: DecimalString,
-  b: DecimalString
-): boolean {
-  return requireDecimal(a, 'a').gt(requireDecimal(b, 'b'))
-}