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

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,EAIlB,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;AA2EnC;;;;;;;;;;;;;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;IA2BvB,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": "7.0.0",
+  "version": "8.0.1",
   "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": "^3.3.2"
+    "@lifi/perps-types": "^4.1.0"
   },
   "peerDependencies": {
-    "@lifi/perps-sdk": "^5.0.0"
+    "@lifi/perps-sdk": "^6.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/LighterProvider.ts

@@ -12,6 +12,7 @@ import {
   type ProviderGetActivityParams,
   type ProviderGetDepositFlowParams,
   type ProviderGetFillsParams,
+  type ProviderGetMarketSettingsParams,
   type ProviderGetOrderParams,
   type ProviderGetOrdersParams,
   type ProviderGetPositionsParams,
@@ -20,6 +21,7 @@ import {
   resolveRetryPolicy,
   type SDKRequestOptions,
   type SignActionsContext,
+  toPerpsMarketDisplay,
 } from '@lifi/perps-sdk'
 import type {
   AccountConfig,
@@ -33,6 +35,7 @@ import type {
   FillsResponse,
   LighterAccountConfig,
   LighterProviderKey,
+  MarketSettings,
   Order,
   OrdersResponse,
   Position,
@@ -42,7 +45,12 @@ import type {
   SignedActionStep,
   SigningMethod,
 } from '@lifi/perps-types'
-import { ActionType, ActivityType, PerpsErrorCode } from '@lifi/perps-types'
+import {
+  ActionType,
+  ActivityType,
+  MarginMode,
+  PerpsErrorCode,
+} from '@lifi/perps-types'
 import type { Address } from 'viem'
 import { projectLighterConfigSettings } from './accountConfig.js'
 import { getAccountSummary } from './accountSummary.js'
@@ -77,6 +85,7 @@ import type {
   LtTransferHistoryResponse,
   LtWithdrawHistoryResponse,
 } from './types/index.js'
+import { LT_MARGIN_MODE_ISOLATED } from './types/index.js'
 import {
   decodeActivityCursor,
   encodeActivityCursor,
@@ -94,12 +103,15 @@ import {
   fetchDetailedAccount,
   formatOrderPrice,
   formatOrderSize,
+  leverageFromImf,
   lighterAsset,
   mapFill,
   mapOpenPositions,
   mapOrderDetail,
+  positionMarginConstraints,
   toIsoFromMs,
   toIsoFromSeconds,
+  toRequiredBig,
 } from './utils/index.js'
 
 const ZERO_FEE_TIER = { maker: '0', taker: '0' }
@@ -755,7 +767,7 @@ export const lighterProvider = (
           normalizeLighterPublicKey(registeredKey.public_key)
 
       const positions: Position[] = mapOpenPositions(account.positions, (id) =>
-        registry.require(String(id))
+        toPerpsMarketDisplay(registry.require(String(id)))
       )
 
       const totalMarginUsed = positions.reduce(
@@ -774,16 +786,24 @@ export const lighterProvider = (
         categories.find((c) => c.quoteAsset === null)?.id ??
         LIGHTER_SPOT_CATEGORY_ID
 
-      // USDC collateral is the category quote asset → collateralBalances.
-      // `available_balance` is the free collateral (Lighter's `collateral` is
-      // gross, i.e. includes margin locked in positions); the locked portion is
-      // carried by the positions' `marginUsed`.
+      // Cross buying power is isolated from per-position allocations. Lighter
+      // reports cross equity (already marked by cross uPnL) separately from
+      // the initial margin locked by cross positions.
+      const availableMargin = toRequiredBig(
+        account.cross_asset_value,
+        'cross_asset_value'
+      ).minus(
+        toRequiredBig(
+          account.cross_initial_margin_requirement,
+          'cross_initial_margin_requirement'
+        )
+      )
       const collateralBalances: Balance[] = [
         {
           categoryId: perpsCategory?.id ?? providerKey,
           asset: perpsCategory?.quoteAsset ?? lighterAsset('USDC', 'USDC'),
-          units: account.available_balance,
-          valueUsd: account.available_balance,
+          units: availableMargin.toString(),
+          valueUsd: availableMargin.toString(),
         },
       ]
       // Spot token holdings — non-collateral. USDC value is 1:1; other tokens
@@ -872,7 +892,7 @@ export const lighterProvider = (
       ])
 
       let positions: Position[] = mapOpenPositions(account.positions, (id) =>
-        registry.require(String(id))
+        toPerpsMarketDisplay(registry.require(String(id)))
       )
 
       if (params.marketId !== undefined) {
@@ -886,6 +906,50 @@ export const lighterProvider = (
       }
     },
 
+    /**
+     * Lighter reports a market's margin mode and leverage only on the
+     * account's position row, so a market the account never touched (or a
+     * missing account) resolves `undefined` rather than a venue default.
+     */
+    async getMarketSettings(
+      params: ProviderGetMarketSettingsParams,
+      opts?: SDKRequestOptions
+    ): Promise<MarketSettings | undefined> {
+      // Spot markets carry no margin mode or leverage.
+      if (params.market.categoryId === LIGHTER_SPOT_CATEGORY_ID) {
+        return undefined
+      }
+      let account: LtDetailedAccount
+      try {
+        account = await fetchDetailedAccount(apiClient(opts), params.address)
+      } catch (err) {
+        if (
+          err instanceof PerpsError &&
+          err.code === PerpsErrorCode.AccountNotFound
+        ) {
+          return undefined
+        }
+        throw err
+      }
+      const row = account.positions.find(
+        (p) => String(p.market_id) === params.market.marketId
+      )
+      if (!row) {
+        return undefined
+      }
+      const leverage = leverageFromImf(row.initial_margin_fraction)
+      if (leverage === undefined) {
+        return undefined
+      }
+      return {
+        marginMode:
+          row.margin_mode === LT_MARGIN_MODE_ISOLATED
+            ? MarginMode.ISOLATED
+            : MarginMode.CROSS,
+        leverage,
+      }
+    },
+
     /**
      * Lighter's `accountActiveOrders` endpoint takes no limit/cursor and
      * returns every active order for the account, so the response is always
@@ -1255,6 +1319,8 @@ export const lighterProvider = (
 
     estimateLiquidationPrice,
 
+    positionMarginConstraints,
+
     projectConfig(
       config: AccountConfig,
       setup: ProviderAction[],

package/src/accountSummary.ts

@@ -1,16 +1,18 @@
-import { summarizeAccount } from '@lifi/perps-sdk'
 import type {
   AccountResponse,
   AccountSummary,
   Position,
 } from '@lifi/perps-types'
+import { MarginMode } from '@lifi/perps-types'
+import Big from 'big.js'
 
 /**
  * Roll a Lighter {@link AccountResponse} up into an {@link AccountSummary}.
- * Lighter has a single flat collateral model with no abstraction modes: the
- * collateral rows hold `available_balance`, which nets locked margin out but
- * marks unrealized PnL in — so only the positions' `marginUsed` is added
- * back for the portfolio value, never their PnL.
+ *
+ * Lighter's cross available balance is already marked to market, while an
+ * isolated position's unrealized PnL remains inside that position's isolated
+ * sub-account. Reconciliation therefore adds every position's locked margin,
+ * but adds unrealized PnL only for isolated positions.
  *
  * @public
  */
@@ -18,5 +20,35 @@ export function getAccountSummary(
   account: AccountResponse,
   positions: Position[]
 ): AccountSummary {
-  return summarizeAccount(account, positions, 'net')
+  let availableMargin = new Big(0)
+  for (const balance of account.collateralBalances) {
+    availableMargin = availableMargin.plus(balance.valueUsd)
+  }
+
+  let nonCollateralValue = new Big(0)
+  for (const balance of account.balances) {
+    nonCollateralValue = nonCollateralValue.plus(balance.valueUsd)
+  }
+
+  let marginUsed = new Big(0)
+  let unrealizedPnl = new Big(0)
+  let isolatedUnrealizedPnl = new Big(0)
+  for (const position of positions) {
+    marginUsed = marginUsed.plus(position.marginUsed)
+    unrealizedPnl = unrealizedPnl.plus(position.unrealizedPnl)
+    if (position.marginMode === MarginMode.ISOLATED) {
+      isolatedUnrealizedPnl = isolatedUnrealizedPnl.plus(position.unrealizedPnl)
+    }
+  }
+
+  return {
+    portfolioValue: nonCollateralValue
+      .plus(availableMargin)
+      .plus(marginUsed)
+      .plus(isolatedUnrealizedPnl)
+      .toString(),
+    availableMargin: availableMargin.toString(),
+    marginUsed: marginUsed.toString(),
+    unrealizedPnl: unrealizedPnl.toString(),
+  }
 }

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)