@lifi/perps-sdk-provider-lighter 8.0.0 → 8.0.1

package/src/signers/LighterSigner.ts

@@ -21,7 +21,13 @@ import {
 // is process-global inside the Go runtime; we track which keys are already
 // initialized so CreateClient runs once per keypair.
 
-/** @public */
+/**
+ * Credentials needed to initialize the Lighter WASM client for one account
+ * and API-key slot. The private key is Lighter-native signing material; the
+ * account and slot indexes select the registered L2 key.
+ *
+ * @public
+ */
 export interface LighterSignerContext {
   /** Lighter-native private key (from GenerateAPIKey, NOT an Ethereum key). */
   apiKeyPrivateKey: string
@@ -31,7 +37,12 @@ export interface LighterSignerContext {
   accountIndex: number
 }
 
-/** @public */
+/**
+ * Configuration for {@link LighterSigner}, including optional WASM asset
+ * overrides and the Lighter REST base URL and signing chain ID.
+ *
+ * @public
+ */
 export interface LighterSignerConfig extends LoadLighterWasmOptions {
   /** Lighter REST API base URL. */
   apiUrl?: string
@@ -39,26 +50,47 @@ export interface LighterSignerConfig extends LoadLighterWasmOptions {
   chainId?: number
 }
 
-/** @public */
+/**
+ * Signed Lighter transaction blob returned by the WASM signer. `txType`,
+ * `txInfo`, and `txHash` are passed to the venue's transaction submission
+ * endpoint; `txInfo` is an encoded transaction payload.
+ *
+ * @public
+ */
 export interface LighterSignedBlob {
   txType: number
   txInfo: string
   txHash: string
 }
 
-/** @public */
+/**
+ * Signed REGISTER_API_KEY (ChangePubKey) result, including the EIP-191 message
+ * that the user's L1 wallet must countersign before submission.
+ *
+ * @public
+ */
 export interface ChangePubKeyResult extends LighterSignedBlob {
   /** EIP-191 message the L1 Ethereum wallet must sign to authorize the key rotation. */
   messageToSign: string
 }
 
-/** @public */
+/**
+ * Signed APPROVE_INTEGRATOR result, including the EIP-191 L1 message required
+ * to authorize the integrator approval.
+ *
+ * @public
+ */
 export interface ApproveIntegratorResult extends LighterSignedBlob {
   /** EIP-191 `L2ApproveIntegrator` L1 body the user's wallet must countersign to authorize the integrator approval. */
   messageToSign: string
 }
 
-/** @public */
+/**
+ * Lighter-native API keypair generated by the WASM signer. These keys are
+ * distinct from an Ethereum wallet keypair.
+ *
+ * @public
+ */
 export interface ApiKeyPair {
   publicKey: string
   privateKey: string
@@ -94,7 +126,13 @@ const LIGHTER_ROUTE_BY_DEX: Record<string, number> = {
   spot: LT_ROUTE_SPOT,
 }
 
-/** @public */
+/**
+ * WASM-backed signer for Lighter API-key transactions and L1-countersigned
+ * hybrid flows. The instance memoizes WASM initialization and registered
+ * `(apiKeyIndex, accountIndex)` clients.
+ *
+ * @public
+ */
 export class LighterSigner {
   private readonly apiUrl: string
   private readonly chainId: number
@@ -112,6 +150,10 @@ export class LighterSigner {
     }
   }
 
+  /**
+   * Load and cache the Go WASM signer exports. Most signing methods initialize
+   * lazily, so callers only need this method when they want an explicit warm-up.
+   */
   async initialize(): Promise<void> {
     if (!this.wasm) {
       this.wasm = await loadLighterWasm(this.loaderOptions)

package/src/signers/createAuthToken.ts

@@ -5,7 +5,13 @@ import type { LighterSigner } from './LighterSigner.js'
 const DEFAULT_LIFETIME_SECONDS = 60 * 60
 const DEFAULT_THRESHOLD_SECONDS = 30 * 86_400
 
-/** @public */
+/**
+ * Inputs for creating a standard Lighter auth token. The signer and API-key
+ * fields identify the registered Lighter account; `lifetimeSeconds` is capped
+ * by Lighter's token policy and defaults to one hour.
+ *
+ * @public
+ */
 export interface CreateAuthTokenInputs {
   signer: LighterSigner
   apiKey: Pick<
@@ -17,7 +23,7 @@ export interface CreateAuthTokenInputs {
    * Defaults to 1 hour, matching the previous `PerpsClient` behaviour.
    */
   lifetimeSeconds?: number
-  /** Optional clock injection for tests. */
+  /** Optional clock injection for deterministic token-expiry tests. */
   now?: () => number
 }
 

package/src/signers/wasmLoader.ts

@@ -48,7 +48,13 @@ function defaultAssetUrl(filename: string): URL {
   return new URL(`../../wasm/${filename}`, currentModuleUrl())
 }
 
-/** @public */
+/**
+ * Overrides for locating the Lighter Go WASM binary and its runtime loader.
+ * Supplying explicit URLs or source is useful when a bundler does not preserve
+ * the package's relative asset layout.
+ *
+ * @public
+ */
 export interface LoadLighterWasmOptions {
   /** Override URL for the `.wasm` binary (browser: fetch; Node: fs). */
   wasmBinaryUrl?: string | URL
@@ -68,7 +74,13 @@ export interface LoadLighterWasmOptions {
   wasmExecJsSource?: string
 }
 
-/** @public */
+/**
+ * Function table installed by the Lighter Go WASM runtime. Methods mirror the
+ * venue signer ABI and return a result containing either signed transaction
+ * fields or an error; positional argument contracts are documented per method.
+ *
+ * @public
+ */
 export interface LighterWasmExports {
   GenerateAPIKey: () => {
     publicKey?: string

package/src/types/account.ts

@@ -1,7 +1,16 @@
 // Account / balance shapes returned by Lighter's `/api/v1/account` and
 // `/api/v1/accountLimits` endpoints.
 
-/** @public */
+/**
+ * Per-market position row returned by Lighter's account endpoints.
+ *
+ * Amounts and prices are decimal strings in the market's native precision.
+ * `position` is the size magnitude as a decimal string. `sign` is the
+ * authoritative side indicator: values greater than or equal to zero represent
+ * long positions and values less than zero represent short positions.
+ *
+ * @public
+ */
 export type LtAccountPosition = {
   market_id: number
   /** Present on REST `/api/v1/account` rows; WS position frames may omit it. */
@@ -23,7 +32,14 @@ export type LtAccountPosition = {
   total_discount: string
 }
 
-/** @public */
+/**
+ * Collateral asset row returned in a Lighter account response. `balance` and
+ * `locked_balance` are decimal strings in the asset's native precision.
+ * `margin_mode`, when present, is Lighter's cross-margin flag: `0` disables
+ * margin use for the asset and `1` enables it.
+ *
+ * @public
+ */
 export type LtAccountAsset = {
   symbol: string
   asset_id: number
@@ -46,7 +62,13 @@ export type LtAccountAsset = {
  */
 export type LtDetailedAccountPosition = LtAccountPosition
 
-/** @public */
+/**
+ * Integrator approval and fee caps attached to a detailed account.
+ * Fee values are Lighter's integer fee ticks; `approval_expiry` is a Unix
+ * timestamp.
+ *
+ * @public
+ */
 export interface LtApprovedIntegrator {
   account_index: number
   name: string
@@ -57,7 +79,14 @@ export interface LtApprovedIntegrator {
   approval_expiry: number
 }
 
-/** @public */
+/**
+ * Detailed account payload returned by Lighter's account endpoint, including
+ * account metadata, aggregate collateral values, assets, and positions.
+ * Balance and value fields are decimal strings in the relevant asset/quote
+ * precision; numeric status and mode fields are Lighter wire enums.
+ *
+ * @public
+ */
 export interface LtDetailedAccount {
   code: number
   account_type: number
@@ -85,14 +114,25 @@ export interface LtDetailedAccount {
   approved_integrators?: LtApprovedIntegrator[]
 }
 
-/** @public */
+/**
+ * Response envelope for a detailed-account lookup. `code` is Lighter's
+ * endpoint result code and `total` is the number of account rows returned.
+ *
+ * @public
+ */
 export interface LtDetailedAccountsResponse {
   code: number
   total: number
   accounts: LtDetailedAccount[]
 }
 
-/** @public */
+/**
+ * Account-level limits and fee information returned by Lighter's
+ * `/api/v1/accountLimits` endpoint. Amount fields are decimal strings;
+ * `current_*_fee_tick` values use Lighter's integer fee-tick scale.
+ *
+ * @public
+ */
 export interface LtAccountLimits {
   code: number
   message?: string
@@ -107,7 +147,13 @@ export interface LtAccountLimits {
   effective_lit_stakes: string
 }
 
-/** @public */
+/**
+ * Sub-account summary returned by Lighter's `accountsByL1Address` endpoint.
+ * Balance and collateral values are decimal strings; status and trading-mode
+ * fields are Lighter wire values.
+ *
+ * @public
+ */
 export interface LtSubAccount {
   code: number
   account_type: number
@@ -124,7 +170,11 @@ export interface LtSubAccount {
   account_trading_mode: number
 }
 
-/** @public */
+/**
+ * Response envelope for an L1-address sub-account lookup.
+ *
+ * @public
+ */
 export interface LtAccountsByL1AddressResponse {
   code: number
   l1_address: string

package/src/types/action.ts

@@ -109,47 +109,101 @@ export type LtChangePubKeyWasmParams = {
   nonce: number
 }
 
-/** @public */
+/**
+ * Lighter wire value for limit orders.
+ * @public
+ */
 export const LT_ORDER_TYPE_LIMIT = 0
-/** @public */
+/**
+ * Lighter wire value for market orders.
+ * @public
+ */
 export const LT_ORDER_TYPE_MARKET = 1
-/** @public */
+/**
+ * Lighter wire value for stop-loss market orders.
+ * @public
+ */
 export const LT_ORDER_TYPE_STOP_LOSS = 2
-/** @public */
+/**
+ * Lighter wire value for stop-loss limit orders.
+ * @public
+ */
 export const LT_ORDER_TYPE_STOP_LOSS_LIMIT = 3
-/** @public */
+/**
+ * Lighter wire value for take-profit market orders.
+ * @public
+ */
 export const LT_ORDER_TYPE_TAKE_PROFIT = 4
-/** @public */
+/**
+ * Lighter wire value for take-profit limit orders.
+ * @public
+ */
 export const LT_ORDER_TYPE_TAKE_PROFIT_LIMIT = 5
-/** @public */
+/**
+ * Lighter wire value for TWAP orders.
+ * @public
+ */
 export const LT_ORDER_TYPE_TWAP = 6
 
-/** @public */
+/**
+ * Lighter wire value for immediate-or-cancel time in force.
+ * @public
+ */
 export const LT_TIME_IN_FORCE_IOC = 0
-/** @public */
+/**
+ * Lighter wire value for good-til-cancelled time in force.
+ * @public
+ */
 export const LT_TIME_IN_FORCE_GTC = 1
-/** @public */
+/**
+ * Lighter wire value for post-only time in force.
+ * @public
+ */
 export const LT_TIME_IN_FORCE_POST_ONLY = 2
 
-/** @public */
+/**
+ * Lighter cross-margin mode value.
+ * @public
+ */
 export const LT_MARGIN_MODE_CROSS = 0
-/** @public */
+/**
+ * Lighter isolated-margin mode value.
+ * @public
+ */
 export const LT_MARGIN_MODE_ISOLATED = 1
 
-/** @public */
+/**
+ * Lighter margin-direction value for removing margin.
+ * @public
+ */
 export const LT_MARGIN_DIRECTION_REMOVE = 0
-/** @public */
+/**
+ * Lighter margin-direction value for adding margin.
+ * @public
+ */
 export const LT_MARGIN_DIRECTION_ADD = 1
 
-/** @public */
+/**
+ * Lighter route selector for perpetuals transfers.
+ * @public
+ */
 export const LT_ROUTE_PERP = 0
-/** @public */
+/**
+ * Lighter route selector for spot transfers.
+ * @public
+ */
 export const LT_ROUTE_SPOT = 1
 
-/** @public */
+/**
+ * Lighter spot USDC asset id.
+ * @public
+ */
 export const LT_ASSET_ID_USDC = 3
 
-/** @public */
+/**
+ * Wire sentinel for an omitted trigger price.
+ * @public
+ */
 export const LT_NIL_TRIGGER_PRICE = 0
 /**
  * Sentinel the lighter-go WASM signer translates to "default 28-day expiry

package/src/types/activity.ts

@@ -1,7 +1,13 @@
 // Activity history shapes returned by Lighter's REST API
 // (deposits, withdrawals, funding payments, liquidations, transfers).
 
-/** @public */
+/**
+ * Deposit history row returned by Lighter. `amount` is a decimal asset amount,
+ * `timestamp` is Unix milliseconds, and `l1_tx_hash` identifies the settlement
+ * transaction on the L1 bridge.
+ *
+ * @public
+ */
 export interface LtDepositHistoryItem {
   id: string
   asset_id: number
@@ -11,14 +17,25 @@ export interface LtDepositHistoryItem {
   l1_tx_hash: string
 }
 
-/** @public */
+/**
+ * Paginated deposit-history response from Lighter. `cursor` is an opaque
+ * continuation value for the next page.
+ *
+ * @public
+ */
 export interface LtDepositHistoryResponse {
   code: number
   deposits: LtDepositHistoryItem[]
   cursor?: string
 }
 
-/** @public */
+/**
+ * Withdrawal history row returned by Lighter. `amount` is a decimal asset
+ * amount, `timestamp` is Unix milliseconds, and `l1_tx_hash` identifies the
+ * associated L1 transaction.
+ *
+ * @public
+ */
 export interface LtWithdrawHistoryItem {
   id: string
   asset_id: number
@@ -29,14 +46,25 @@ export interface LtWithdrawHistoryItem {
   l1_tx_hash: string
 }
 
-/** @public */
+/**
+ * Paginated withdrawal-history response from Lighter. `cursor` is an opaque
+ * continuation value for the next page.
+ *
+ * @public
+ */
 export interface LtWithdrawHistoryResponse {
   code: number
   withdraws: LtWithdrawHistoryItem[]
   cursor?: string
 }
 
-/** @public */
+/**
+ * Funding-payment history row for one perpetual position. `change`,
+ * `position_size`, and `rate` are decimal strings; `timestamp` is a Unix
+ * timestamp in seconds and `position_side` is Lighter's side literal.
+ *
+ * @public
+ */
 export interface LtPositionFunding {
   timestamp: number
   market_id: number
@@ -47,14 +75,24 @@ export interface LtPositionFunding {
   position_side: string
 }
 
-/** @public */
+/**
+ * Paginated position-funding response from Lighter. `next_cursor` is an opaque
+ * continuation value for the next page.
+ *
+ * @public
+ */
 export interface LtPositionFundingsResponse {
   code: number
   position_fundings: LtPositionFunding[]
   next_cursor?: string
 }
 
-/** @public */
+/**
+ * Liquidation event row returned by Lighter. `executed_at` is a Unix timestamp
+ * in milliseconds.
+ *
+ * @public
+ */
 export interface LtLiquidation {
   id: number
   market_id: number
@@ -62,14 +100,25 @@ export interface LtLiquidation {
   executed_at: number
 }
 
-/** @public */
+/**
+ * Paginated liquidation-history response from Lighter. `next_cursor` is an
+ * opaque continuation value for the next page.
+ *
+ * @public
+ */
 export interface LtLiquidationsResponse {
   code: number
   liquidations: LtLiquidation[]
   next_cursor?: string
 }
 
-/** @public */
+/**
+ * Asset transfer-history row returned by Lighter. Amounts and fees are decimal
+ * strings in the asset's precision; route literals identify the source and
+ * destination account ledger (`spot` or `perps`).
+ *
+ * @public
+ */
 export interface LtTransfer {
   id: string
   asset_id: number
@@ -86,7 +135,12 @@ export interface LtTransfer {
   tx_hash: string
 }
 
-/** @public */
+/**
+ * Paginated transfer-history response from Lighter. `cursor` is an opaque
+ * continuation value for the next page.
+ *
+ * @public
+ */
 export interface LtTransferHistoryResponse {
   code: number
   transfers: LtTransfer[]

package/src/types/asset.ts

@@ -1,6 +1,12 @@
 // Market / asset / orderbook metadata returned by Lighter's REST API.
 
-/** @public */
+/**
+ * Venue configuration nested in a Lighter perpetual-market descriptor.
+ * Numeric fields are Lighter wire mode values; booleans indicate whether the
+ * market is currently restricted or hidden.
+ *
+ * @public
+ */
 export interface LtMarketConfig {
   market_margin_mode: number
   insurance_fund_account_index: number
@@ -11,7 +17,14 @@ export interface LtMarketConfig {
   hidden: boolean
 }
 
-/** @public */
+/**
+ * Perpetual-market metadata returned by Lighter's order-book-details endpoint.
+ * Decimal strings use the market's native asset/quote precision. Decimal-count
+ * fields describe supported and canonical order precision; fee and margin
+ * fractions use Lighter's wire representation.
+ *
+ * @public
+ */
 export interface LtPerpsOrderBookDetail {
   symbol: string
   market_id: number
@@ -48,7 +61,13 @@ export interface LtPerpsOrderBookDetail {
   strategy_index: number
 }
 
-/** @public */
+/**
+ * Spot-market metadata returned by Lighter's order-book-details endpoint.
+ * Decimal strings use the market's native asset/quote precision; decimal-count
+ * fields describe supported order precision.
+ *
+ * @public
+ */
 export interface LtSpotOrderBookDetail {
   symbol: string
   market_id: number
@@ -77,14 +96,23 @@ export interface LtSpotOrderBookDetail {
   daily_chart: Record<string, unknown>
 }
 
-/** @public */
+/**
+ * Response envelope containing both perpetual and spot market descriptors.
+ *
+ * @public
+ */
 export interface LtOrderBookDetailsResponse {
   code: number
   order_book_details: LtPerpsOrderBookDetail[]
   spot_order_book_details: LtSpotOrderBookDetail[]
 }
 
-/** @public */
+/**
+ * Token metadata returned by Lighter's token-list endpoint. `market` identifies
+ * whether the token is associated with a perpetual or spot market.
+ *
+ * @public
+ */
 export interface LtToken {
   symbol: string
   name: string
@@ -93,13 +121,22 @@ export interface LtToken {
   market: 'PERPS' | 'SPOT'
 }
 
-/** @public */
+/**
+ * Response envelope for Lighter's token-list endpoint.
+ *
+ * @public
+ */
 export interface LtTokenListResponse {
   code: number
   tokens: LtToken[]
 }
 
-/** @public */
+/**
+ * Asset metadata returned by Lighter. `l1_decimals` is the token precision on
+ * L1; `decimals` is the Lighter ledger precision.
+ *
+ * @public
+ */
 export interface LtAssetDetail {
   asset_id: number
   symbol: string
@@ -108,13 +145,22 @@ export interface LtAssetDetail {
   l1_address: string
 }
 
-/** @public */
+/**
+ * Response envelope for Lighter's asset-details endpoint.
+ *
+ * @public
+ */
 export interface LtAssetDetailsResponse {
   code: number
   asset_details: LtAssetDetail[]
 }
 
-/** @public */
+/**
+ * OHLCV candle returned by Lighter. `t` is the candle timestamp in Unix
+ * milliseconds; `o`, `h`, `l`, and `c` are prices and `v` is volume.
+ *
+ * @public
+ */
 export interface LtCandle {
   t: number
   o: number
@@ -124,14 +170,24 @@ export interface LtCandle {
   v: number
 }
 
-/** @public */
+/**
+ * Response envelope for a Lighter candle query. `r` is the endpoint's result
+ * value and `c` contains the returned candles.
+ *
+ * @public
+ */
 export interface LtCandlesResponse {
   code: number
   r: string
   c: LtCandle[]
 }
 
-/** @public */
+/**
+ * Funding-rate snapshot for one Lighter perpetual market. `rate` is the
+ * venue-provided funding-rate value for the named exchange and market.
+ *
+ * @public
+ */
 export interface LtFundingRate {
   market_id: number
   exchange: string
@@ -139,7 +195,11 @@ export interface LtFundingRate {
   rate: number
 }
 
-/** @public */
+/**
+ * Response envelope containing current funding rates by market.
+ *
+ * @public
+ */
 export interface LtFundingRatesResponse {
   code: number
   funding_rates: LtFundingRate[]