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

package/dist/types/types/ws.d.ts

@@ -1,13 +1,30 @@
-/** @public */
+/**
+ * Common envelope fields on every Lighter WebSocket frame.
+ *
+ * `channel` identifies the subscribed stream when present; `type` is the
+ * subscription, update, or control-frame discriminator.
+ *
+ * @public
+ */
 export type LtWsMessage = {
     channel?: string;
     type: string;
 };
-/** @public */
+/**
+ * Lighter WebSocket keepalive frame.
+ *
+ * @public
+ */
 export type LtWsPingMessage = LtWsMessage & {
     type: 'ping';
 };
-/** @public */
+/**
+ * Perpetual-market statistics pushed by Lighter's `market_stats` channels.
+ * Price, interest, volume, and funding values are decimal strings; the funding
+ * timestamp is a Unix timestamp in milliseconds.
+ *
+ * @public
+ */
 export type LtWsMarketStats = {
     market_id: number;
     index_price: string;
@@ -59,18 +76,32 @@ export type LtWsSpotMarketStatsAllMessage = LtWsMessage & {
     type: 'subscribed/spot_market_stats' | 'update/spot_market_stats';
     spot_market_stats?: LtWsSpotMarketStats | Record<string, LtWsSpotMarketStats>;
 };
-/** @public */
+/**
+ * One bid or ask level in a Lighter order-book snapshot or delta. Price and
+ * size are decimal strings in the market's native precision.
+ *
+ * @public
+ */
 export type LtWsOrderBookLevel = {
     price: string;
     size: string;
 };
-/** @public */
+/**
+ * Lighter order-book state containing ask and bid levels. `offset`, when
+ * present, identifies the sequence offset used for stateful delta updates.
+ *
+ * @public
+ */
 export type LtWsOrderBook = {
     asks: LtWsOrderBookLevel[];
     bids: LtWsOrderBookLevel[];
     offset?: number;
 };
-/** @public */
+/**
+ * Subscription or update frame carrying a Lighter order-book snapshot/delta.
+ *
+ * @public
+ */
 export type LtWsOrderBookMessage = LtWsMessage & {
     type: 'subscribed/order_book' | 'update/order_book';
     order_book: LtWsOrderBook;
@@ -89,7 +120,11 @@ export type LtWsTrade = {
     is_maker_ask: boolean;
     timestamp: number;
 };
-/** @public */
+/**
+ * Subscription or update frame carrying public trades from a Lighter market.
+ *
+ * @public
+ */
 export type LtWsTradeMessage = LtWsMessage & {
     type: 'subscribed/trade' | 'update/trade';
     trades?: LtWsTrade[];
@@ -118,7 +153,13 @@ export type LtWsAccountAllOrdersMessage = LtWsMessage & {
         orders?: Record<string, unknown[]> | unknown[];
     };
 };
-/** @public */
+/**
+ * Authenticated account trade-history frame. Trade arrays may be flat or
+ * market-indexed depending on whether the frame is an initial snapshot or
+ * update.
+ *
+ * @public
+ */
 export type LtWsAccountAllTradesMessage = LtWsMessage & {
     type: 'subscribed/account_all_trades' | 'update/account_all_trades';
     trades?: Record<string, unknown[]> | unknown[];
@@ -149,6 +190,13 @@ export type LtWsUserStatsMessage = LtWsMessage & {
         };
     };
 };
+/**
+ * Authenticated account-position frame. Position and funding maps are keyed
+ * by Lighter market index; the provider normalizes the payload before emitting
+ * account updates.
+ *
+ * @public
+ */
 export type LtWsAccountAllPositionsMessage = LtWsMessage & {
     type: 'subscribed/account_all_positions' | 'update/account_all_positions';
     positions?: Record<string, unknown>;

package/dist/types/types/ws.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../../../src/types/ws.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../../../src/types/ws.ts"],"names":[],"mappings":"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"}

package/dist/types/utils/lighterAsset.d.ts

@@ -1,4 +1,10 @@
 import type { Asset } from '@lifi/perps-types';
-/** @public */
+/**
+ * Create the SDK asset descriptor for a Lighter asset identifier and display
+ * symbol. Lighter assets do not provide a package-level logo URI, so this
+ * helper leaves that field empty.
+ *
+ * @public
+ */
 export declare const lighterAsset: (id: string, displaySymbol: string) => Asset;
 //# sourceMappingURL=lighterAsset.d.ts.map

package/dist/types/utils/lighterAsset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lighterAsset.d.ts","sourceRoot":"","sources":["../../../src/utils/lighterAsset.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAG9C,cAAc;AACd,eAAO,MAAM,YAAY,GAAI,IAAI,MAAM,EAAE,eAAe,MAAM,KAAG,KAK/D,CAAA"}
+{"version":3,"file":"lighterAsset.d.ts","sourceRoot":"","sources":["../../../src/utils/lighterAsset.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAG9C;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,IAAI,MAAM,EAAE,eAAe,MAAM,KAAG,KAK/D,CAAA"}

package/dist/types/utils/ohlcvInterval.d.ts

@@ -1,3 +1,8 @@
-/** @public */
+/**
+ * Validate and map an SDK OHLCV interval to Lighter's resolution string.
+ * Unsupported intervals raise a validation error instead of being rounded.
+ *
+ * @public
+ */
 export declare const mapInterval: (interval: string) => string;
 //# sourceMappingURL=ohlcvInterval.d.ts.map

package/dist/types/utils/ohlcvInterval.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ohlcvInterval.d.ts","sourceRoot":"","sources":["../../../src/utils/ohlcvInterval.ts"],"names":[],"mappings":"AAsBA,cAAc;AACd,eAAO,MAAM,WAAW,GAAI,UAAU,MAAM,KAAG,MAU9C,CAAA"}
+{"version":3,"file":"ohlcvInterval.d.ts","sourceRoot":"","sources":["../../../src/utils/ohlcvInterval.ts"],"names":[],"mappings":"AAsBA;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,MAAM,KAAG,MAU9C,CAAA"}

package/dist/types/utils/transferMargin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transferMargin.d.ts","sourceRoot":"","sources":["../../../src/utils/transferMargin.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,QAAQ,EAEb,KAAK,yBAAyB,EAC/B,MAAM,mBAAmB,CAAA;AAK1B;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,QAAQ,GACjB,yBAAyB,GAAG,SAAS,CAcvC"}
+{"version":3,"file":"transferMargin.d.ts","sourceRoot":"","sources":["../../../src/utils/transferMargin.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,yBAAyB,EAE/B,MAAM,mBAAmB,CAAA;AAK1B;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,QAAQ,GACjB,yBAAyB,GAAG,SAAS,CAWvC"}

package/dist/types/utils/wireEncoding.d.ts

@@ -1,49 +1,84 @@
 /**
- * Lighter wire encoding for the WASM signer: scaled-integer decimal values,
- * basis-point margin fractions, and order-type/TIF/expiry resolution
- * mirroring the lighter-go signer's rules.
+ * Lighter wire encoding for the WASM signer: basis-point margin fractions and
+ * order-type/time-in-force/expiry resolution mirroring lighter-go's rules.
  */
 /**
- * Lighter uses basis-points (1/10000) for margin fractions.
- * Convert to a decimal multiplier: 1000 → 0.1 (10x leverage).
+ * Convert Lighter's initial-margin fraction to the largest whole-number
+ * leverage exposed by the provider.
+ *
+ * Lighter expresses margin fractions in basis points (`10_000` = 100%), so
+ * the conversion is `floor(10_000 / fraction)`. Non-finite or non-positive
+ * input uses the safe `1x` fallback.
+ *
+ * @param fraction - Lighter's basis-point initial-margin fraction.
+ * @returns The floored maximum leverage, or `1` for invalid input.
  * @public
  */
 export declare const marginFractionToMaxLeverage: (fraction: number) => number;
 /**
- * Convert leverage to margin fraction in basis points for WASM signer.
+ * Convert requested leverage to Lighter's basis-point margin fraction.
+ *
+ * The signer expects `round(10_000 / leverage)`, where the result is the
+ * margin requirement in basis points.
+ *
+ * @param leverage - Requested leverage multiplier.
+ * @returns The rounded basis-point margin fraction.
+ * @throws {PerpsError} With `ValidationError` when leverage is less than
+ * or equal to zero.
  * @public
  */
 export declare const leverageToFraction: (leverage: number) => number;
 /**
- * Map our OrderType enum to Lighter's integer order type.
+ * Map a LI.FI `OrderType` value to Lighter's integer wire type.
+ *
+ * Supported mappings are LIMIT → 0, MARKET → 1, STOP_MARKET → 2,
+ * STOP_LIMIT → 3, TAKE_PROFIT_MARKET → 4, and TAKE_PROFIT_LIMIT → 5.
+ * Omitted or unknown values fall back to LIMIT.
+ *
+ * @param type - LI.FI order type value.
+ * @returns The corresponding Lighter order-type integer.
  * @public
  */
 export declare const mapOrderTypeToInt: (type?: string) => number;
 /**
- * Lighter pairs each `order_type` with a permitted set of `time_in_force`
- * values: market-style orders (MARKET, STOP_MARKET, TAKE_PROFIT_MARKET) are
- * IOC by definition; limit-style orders may carry any TIF. The Go WASM
- * signer rejects mismatches with `OrderTimeInForce is not valid`. Resolve
- * the caller's optional `timeInForce` against the order type so unspecified
- * values land on the correct default and explicit values are validated up
- * front.
+ * Resolve a Lighter `time_in_force` value that is valid for an order type.
+ *
+ * Market-style orders (MARKET, STOP_MARKET, TAKE_PROFIT_MARKET) are IOC-only.
+ * Limit-style orders default to GTC when no TIF is supplied. An explicit
+ * non-IOC TIF on a market-style order raises a validation error. For
+ * limit-style orders, unknown TIF strings use the GTC fallback from
+ * {@link mapTimeInForceToInt}.
+ *
+ * @param orderTypeInt - Lighter order-type integer.
+ * @param tif - Optional LI.FI time-in-force value.
+ * @returns The validated Lighter time-in-force integer.
+ * @throws {PerpsError} With `ValidationError` for a market-style/TIF mismatch.
  * @public
  */
 export declare const resolveTimeInForce: (orderTypeInt: number, tif?: string) => number;
 /**
- * Map our TimeInForce enum to Lighter's integer time-in-force.
+ * Map a LI.FI time-in-force value to Lighter's integer wire value.
+ *
+ * IOC maps to 0, GTC maps to 1, and POST_ONLY maps to 2. Omitted or unknown
+ * values fall back to GTC.
+ *
+ * @param tif - LI.FI time-in-force value.
+ * @returns The corresponding Lighter time-in-force integer.
  * @public
  */
 export declare const mapTimeInForceToInt: (tif?: string) => number;
 /**
- * Pick the `order_expiry` value Lighter expects for a given TIF on a
- * regular limit order. `lighter-go/types/txtypes/create_order.go:121-128`
- * enforces:
- *   - IOC limit orders → `OrderExpiry == NilOrderExpiry (0)`
- *   - non-IOC limit orders → `OrderExpiry != NilOrderExpiry`
- * For non-IOC we pass the `-1` sentinel, which the WASM signer rewrites
- * to `now + 28d` (absolute ms). Trigger orders take a different rule —
- * see {@link LT_DEFAULT_ORDER_EXPIRY} call sites.
+ * Select the `order_expiry` sentinel required for a regular Lighter limit
+ * order from its resolved time-in-force.
+ *
+ * IOC uses Lighter's nil expiry (`0`). Every other TIF uses
+ * `LT_DEFAULT_ORDER_EXPIRY` (`-1`), which the WASM signer expands to its
+ * canonical future expiry (`now + 28d`) as an absolute Unix-millisecond
+ * timestamp. Trigger-order expiry handling is provider-specific; see
+ * {@link LT_DEFAULT_ORDER_EXPIRY} and its call sites.
+ *
+ * @param tifInt - Lighter time-in-force integer.
+ * @returns `0` for IOC, otherwise the default-expiry sentinel.
  * @public
  */
 export declare const orderExpiryForTif: (tifInt: number) => number;

package/dist/types/utils/wireEncoding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wireEncoding.d.ts","sourceRoot":"","sources":["../../../src/utils/wireEncoding.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAiBH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,GAAI,UAAU,MAAM,KAAG,MAK9D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,MAQrD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,MAUjD,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAC7B,cAAc,MAAM,EACpB,MAAM,MAAM,KACX,MAgBF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,KAAG,MAOlD,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,MAAM,KAAG,MAKlD,CAAA"}
+{"version":3,"file":"wireEncoding.d.ts","sourceRoot":"","sources":["../../../src/utils/wireEncoding.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiBH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,GAAI,UAAU,MAAM,KAAG,MAK9D,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,MAQrD,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,MAUjD,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,GAC7B,cAAc,MAAM,EACpB,MAAM,MAAM,KACX,MAgBF,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,KAAG,MAOlD,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,MAAM,KAAG,MAKlD,CAAA"}

package/dist/types/websocket/LighterWsProvider.d.ts

@@ -69,6 +69,12 @@ export declare class LighterWsProvider extends WsProviderBase<SubState> {
      * `resolveAuthToken`. `undefined` when neither is available.
      */
     private authTokenResolver;
+    /**
+     * Subscribe to a live quote stream resolved through the registered Lighter
+     * market registry. Returns an unsubscribe function; quote subscription
+     * requires the provider to be constructed through `lighterWsProvider` with a
+     * bound {@link PerpsSDKClient}.
+     */
     subscribeQuote(params: ProviderGetQuoteParams, onQuote: QuoteListener): Promise<() => void>;
     protected openChannel(sub: Subscription): Promise<() => void>;
     protected onClose(): void;

package/dist/types/websocket/LighterWsProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LighterWsProvider.d.ts","sourceRoot":"","sources":["../../../src/websocket/LighterWsProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAKlB,cAAc,EACd,KAAK,iBAAiB,EAEvB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAIV,YAAY,EACb,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AA4EnC;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,OAAO,KACb,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;AAEhC,UAAU,QAAQ;IAChB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,yEAAyE;IACzE,SAAS,EAAE,OAAO,CAAA;CACnB;AAkBD;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,wBAAwB,CAAA;CAC5C;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,cAAc,CAAC,QAAQ,CAAC;IAC7D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IACtC,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAE5B;IACb,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IAEnD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAC/D,OAAO,CAAC,cAAc,CAAoC;IAE1D;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA2C;IAE9E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IAErD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4B;IAC9D,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAqC;gBAGxE,KAAK,GAAE,MAA+B,EACtC,WAAW,GAAE,MAA6B,EAC1C,OAAO,GAAE,wBAA6B,EACtC,MAAM,CAAC,EAAE,cAAc;IAsBzB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAWnB,cAAc,CAClB,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC;cAkBN,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;cA4ChD,OAAO,IAAI,IAAI;cAMlB,aAAa,CAAC,EAC5B,OAAO,EACP,SAAS,EACT,OAAO,GACR,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB3B,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM;YA2B5B,cAAc;YAsFd,mBAAmB;YAqBnB,iBAAiB;IAK/B,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAqB1C,OAAO,CAAC,QAAQ;IAkFhB,OAAO,CAAC,mBAAmB;IAgB3B,OAAO,CAAC,eAAe;IAuDvB,OAAO,CAAC,mBAAmB;IAiB3B,OAAO,CAAC,sBAAsB;IAiC9B;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAuB1B,OAAO,CAAC,iBAAiB;IAuCzB,OAAO,CAAC,eAAe;IA+BvB,OAAO,CAAC,YAAY;IAwBpB,OAAO,CAAC,mBAAmB;CAc5B;AAkID;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,GAC3B,UAAU,wBAAwB,KAAG,iBAEmB,CAAA"}
+{"version":3,"file":"LighterWsProvider.d.ts","sourceRoot":"","sources":["../../../src/websocket/LighterWsProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAKlB,cAAc,EACd,KAAK,iBAAiB,EAEvB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAIV,YAAY,EACb,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AA4EnC;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,OAAO,KACb,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;AAEhC,UAAU,QAAQ;IAChB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,yEAAyE;IACzE,SAAS,EAAE,OAAO,CAAA;CACnB;AAkBD;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,wBAAwB,CAAA;CAC5C;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,cAAc,CAAC,QAAQ,CAAC;IAC7D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IACtC,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAE5B;IACb,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IAEnD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAC/D,OAAO,CAAC,cAAc,CAAoC;IAE1D;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA2C;IAE9E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IAErD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4B;IAC9D,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAqC;gBAGxE,KAAK,GAAE,MAA+B,EACtC,WAAW,GAAE,MAA6B,EAC1C,OAAO,GAAE,wBAA6B,EACtC,MAAM,CAAC,EAAE,cAAc;IAsBzB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;;;OAKG;IACG,cAAc,CAClB,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC;cAkBN,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;cA4ChD,OAAO,IAAI,IAAI;cAMlB,aAAa,CAAC,EAC5B,OAAO,EACP,SAAS,EACT,OAAO,GACR,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB3B,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM;YA2B5B,cAAc;YAsFd,mBAAmB;YAqBnB,iBAAiB;IAK/B,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAqB1C,OAAO,CAAC,QAAQ;IAkFhB,OAAO,CAAC,mBAAmB;IAgB3B,OAAO,CAAC,eAAe;IAuDvB,OAAO,CAAC,mBAAmB;IAiB3B,OAAO,CAAC,sBAAsB;IAiC9B;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAuB1B,OAAO,CAAC,iBAAiB;IAuCzB,OAAO,CAAC,eAAe;IA+BvB,OAAO,CAAC,YAAY;IAwBpB,OAAO,CAAC,mBAAmB;CAc5B;AAkID;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,GAC3B,UAAU,wBAAwB,KAAG,iBAEmB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk-provider-lighter",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "Lighter provider plugin for @lifi/perps-sdk",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -46,10 +46,10 @@
   "dependencies": {
     "big.js": "^7.0.1",
     "viem": "^2.48.8",
-    "@lifi/perps-types": "^4.0.0"
+    "@lifi/perps-types": "^4.2.0"
   },
   "peerDependencies": {
-    "@lifi/perps-sdk": "^6.0.0"
+    "@lifi/perps-sdk": "^6.2.0"
   },
   "publishConfig": {
     "access": "public"

package/src/LighterProvider.ts

@@ -1359,6 +1359,14 @@ export const lighterProvider = (
       return { knownPublicKey: local.apiKeyPublicKey }
     },
 
+    /**
+     * Lighter's WASM signer computes the L2 tx hash before submission, so an
+     * execute result carries it and resolves against this instance's explorer.
+     */
+    resolveExplorerLink(txHash: string): string | undefined {
+      return explorerTxUrlFromBase(explorerTxBaseUrl, txHash)
+    },
+
     async signActions(
       method: SigningMethod,
       steps: ActionStep[],

package/src/constants.ts

@@ -22,6 +22,11 @@ export const LIGHTER_SPOT_CATEGORY_ID = 'spot'
  * @public
  */
 export const DEFAULT_LIGHTER_REST_URL = 'https://mainnet.zklighter.elliot.ai'
+/**
+ * Default mainnet WebSocket stream URL for Lighter.
+ *
+ * @public
+ */
 export const DEFAULT_LIGHTER_WS_URL = 'wss://mainnet.zklighter.elliot.ai/stream'
 
 /**
@@ -85,9 +90,17 @@ export const LIGHTER_MAINNET_INSTANCE: LighterInstanceConfig = {
  */
 export const LIGHTER_RH_PROVIDER_KEY = 'lighter-rh'
 
-/** @public */
+/**
+ * Default REST base URL for the Lighter Robinhood deployment.
+ *
+ * @public
+ */
 export const LIGHTER_RH_REST_URL = 'https://api.rh.lighter.xyz'
-/** @public */
+/**
+ * Default WebSocket URL for the Lighter Robinhood deployment.
+ *
+ * @public
+ */
 export const LIGHTER_RH_WS_URL = 'wss://api.rh.lighter.xyz/stream'
 
 /**

package/src/signers/LighterKeyStore.ts

@@ -11,7 +11,13 @@ import { LIGHTER_PROVIDER_KEY } from '../constants.js'
 
 const STORAGE_PREFIX = 'lifi-perps-lighter-key'
 
-/** @public */
+/**
+ * Persisted Lighter API-key material associated with one L2 account.
+ * `apiKeyPrivateKey` is a Lighter-native signing key, not an Ethereum key;
+ * `apiKeyIndex` identifies its registered on-chain slot.
+ *
+ * @public
+ */
 export interface LighterApiKey {
   /** Lighter account index, looked up once via accountsByL1Address. */
   accountIndex: number
@@ -41,12 +47,23 @@ const isLighterApiKey = (value: unknown): value is LighterApiKey => {
   )
 }
 
-/** @public */
+/**
+ * Storage-backed cache for Lighter API keys. Records are namespaced by L1
+ * address and provider instance so multiple Lighter deployments can share one
+ * {@link StorageAdapter} without collisions.
+ *
+ * @public
+ */
 export class LighterKeyStore {
   private readonly storage: StorageAdapter
   private readonly cache = new Map<string, LighterApiKey>()
   private providerKey: LighterProviderKey
 
+  /**
+   * Create a key store using `storage` and the optional provider namespace.
+   * The default provider key preserves the package's standard Lighter storage
+   * namespace.
+   */
   constructor(
     storage: StorageAdapter,
     providerKey: LighterProviderKey = LIGHTER_PROVIDER_KEY
@@ -74,6 +91,10 @@ export class LighterKeyStore {
       : `${STORAGE_PREFIX}:${this.providerKey}:${lower}`
   }
 
+  /**
+   * Load the API key for an L1 address, or `null` when no valid record exists.
+   * Invalid persisted records are ignored by the storage validation boundary.
+   */
   async get(address: Address): Promise<LighterApiKey | null> {
     const key = this.storageKey(address)
     const cached = this.cache.get(key)
@@ -88,12 +109,20 @@ export class LighterKeyStore {
     return parsed
   }
 
+  /**
+   * Persist an API key for an L1 address, replacing any existing record under
+   * that provider namespace.
+   */
   async set(address: Address, value: LighterApiKey): Promise<void> {
     const key = this.storageKey(address)
     this.cache.set(key, value)
     await this.storage.set(key, JSON.stringify(value))
   }
 
+  /**
+   * Remove the persisted API key for an L1 address and clear its in-memory
+   * cache entry.
+   */
   async remove(address: Address): Promise<void> {
     const key = this.storageKey(address)
     this.cache.delete(key)

package/src/signers/LighterReadOnlyTokenManager.ts

@@ -69,7 +69,13 @@ export type LighterTokenFetcher = (params: {
   scopes: string
 }) => Promise<LighterCreateTokenResponse>
 
-/** @public */
+/**
+ * Dependencies and overrides for {@link LighterReadOnlyTokenManager}.
+ * Storage and token-fetching defaults target the browser's local storage and
+ * Lighter's mainnet REST API.
+ *
+ * @public
+ */
 export interface LighterReadOnlyTokenManagerOptions {
   storage?: StorageAdapter
   /**
@@ -87,13 +93,23 @@ export interface LighterReadOnlyTokenManagerOptions {
   now?: () => number
 }
 
-/** @public */
+/**
+ * Input to the read-only-token approval flow. Extends the shared approval
+ * parameters with the L1 address whose wallet authorizes token creation.
+ *
+ * @public
+ */
 export interface ApproveReadOnlyTokenInputs extends ApproveReadOnlyTokenParams {
   /** L1 wallet address that signs the create message. */
   address: Address
 }
 
-/** @public */
+/**
+ * Result of approving or creating a Lighter read-only token. `config` is the
+ * account-state projection callers can persist alongside the token.
+ *
+ * @public
+ */
 export interface ApproveReadOnlyTokenResult {
   token: LighterReadOnlyToken
   /** Projection of the post-create Lighter account state. */
@@ -239,6 +255,10 @@ export class LighterReadOnlyTokenManager {
     await this.storage.set(key, JSON.stringify(token))
   }
 
+  /**
+   * Remove the stored token for an `(address, accountIndex)` pair and clear
+   * the corresponding cache entry.
+   */
   async remove(address: Address, accountIndex: number): Promise<void> {
     const key = this.storageKey(address, accountIndex)
     this.cache.delete(key)

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
 }