@lifi/perps-sdk-provider-lighter 2.0.0 → 2.2.0

package/src/LighterProvider.ts

@@ -202,6 +202,13 @@ export interface LighterProviderOptions {
   tokenLifetimeSeconds?: number
   /** Re-create when the cached standard token's remaining life is below this. Default 60s. */
   tokenRenewBufferSeconds?: number
+  /**
+   * LI.FI's Lighter referral code — the code `getAccount` compares the account's
+   * applied referral against to populate `LighterAccountConfig.referralPresent`.
+   * Must match the backend's configured `LIGHTER_REFERRAL_CODE`; when omitted,
+   * `referralPresent` is always `false` (the SDK has nothing to compare against).
+   */
+  referralCode?: string
 }
 
 interface CachedStandardToken {
@@ -283,6 +290,7 @@ export const lighterProvider = (
   })
   const tokenLifetimeSeconds = options.tokenLifetimeSeconds ?? 60 * 60
   const tokenRenewBufferSeconds = options.tokenRenewBufferSeconds ?? 60
+  const referralCode = options.referralCode
   const standardTokenByAddress: Map<string, CachedStandardToken> = new Map()
   // Single-flight + backoff for lazy read-only token creation. Without these,
   // concurrent reads on first load all race `tokens/create`, and any sustained
@@ -504,6 +512,22 @@ export const lighterProvider = (
       account_index: accountIndex,
     })
 
+  // `used_code` is the referral currently applied to the account (empty string
+  // when none). Keyed by L1 address, mirroring Lighter's `/referral/use` write
+  // contract.
+  const fetchAppliedReferralCode = async (
+    client: LighterApiClient,
+    l1Address: Address,
+    authToken: string
+  ): Promise<string> => {
+    const { used_code } = await client.getAuthed<{ used_code: string }>(
+      '/api/v1/referral/userReferrals',
+      authToken,
+      { l1_address: l1Address.toLowerCase() }
+    )
+    return used_code
+  }
+
   const fetchActiveOrdersForMarket = (
     client: LighterApiClient,
     authToken: string,
@@ -639,21 +663,40 @@ export const lighterProvider = (
       ])
 
       const registry = getMarketRegistry(requireClient(), LIGHTER_PROVIDER_KEY)
-      const [, registeredKey, limitsResult, localKey, storedReadOnlyToken] =
-        await Promise.all([
-          registry.sync(),
-          fetchRegisteredApiKey(client, account.index, DEFAULT_API_KEY_INDEX),
-          // No token is a legitimate unauthenticated read → undefined → zero fee
-          // tier. A fetch error is NOT: it must propagate, never be coerced to a
-          // fabricated 0%/0% fee tier.
-          token === undefined
-            ? Promise.resolve(undefined)
-            : retryOnRevoked(opts, params.address, token, (t) =>
-                fetchAccountLimits(client, account.index, t)
-              ),
-          keyStore ? keyStore.get(params.address) : Promise.resolve(null),
-          readOnlyTokenManager.get(params.address, account.index),
-        ])
+      const assetRegistry = getAssetRegistry(
+        requireClient(),
+        LIGHTER_PROVIDER_KEY
+      )
+      const [
+        markets,
+        ,
+        registeredKey,
+        limitsResult,
+        localKey,
+        storedReadOnlyToken,
+        appliedReferralCode,
+      ] = await Promise.all([
+        registry.sync(),
+        assetRegistry.sync(),
+        fetchRegisteredApiKey(client, account.index, DEFAULT_API_KEY_INDEX),
+        // No token is a legitimate unauthenticated read → undefined → zero fee
+        // tier. A fetch error is NOT: it must propagate, never be coerced to a
+        // fabricated 0%/0% fee tier.
+        token === undefined
+          ? Promise.resolve(undefined)
+          : retryOnRevoked(opts, params.address, token, (t) =>
+              fetchAccountLimits(client, account.index, t)
+            ),
+        keyStore ? keyStore.get(params.address) : Promise.resolve(null),
+        readOnlyTokenManager.get(params.address, account.index),
+        // No referral code to compare against, or no token to authenticate the
+        // read → undefined → `referralPresent: false`.
+        !referralCode || token === undefined
+          ? Promise.resolve(undefined)
+          : retryOnRevoked(opts, params.address, token, (t) =>
+              fetchAppliedReferralCode(client, params.address, t)
+            ),
+      ])
 
       // REGISTER_API_KEY is satisfied only when the locally-held keypair
       // matches the key registered on-chain at this slot — existence alone is
@@ -677,6 +720,10 @@ export const lighterProvider = (
         0
       )
 
+      const quoteAssetByCategory = new Map(
+        markets.map((m) => [m.categoryId, m.quoteAsset])
+      )
+
       // 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
@@ -684,19 +731,24 @@ export const lighterProvider = (
       const collateralBalances: Balance[] = [
         {
           categoryId: LIGHTER_PROVIDER_KEY,
-          asset: lighterAsset('USDC', 'USDC'),
+          asset:
+            quoteAssetByCategory.get(LIGHTER_PROVIDER_KEY) ??
+            lighterAsset('USDC', 'USDC'),
           units: account.available_balance,
           valueUsd: account.available_balance,
         },
       ]
       // Spot token holdings — non-collateral. USDC value is 1:1; other tokens
       // have no price source at this boundary, so their USD value is unknown.
-      const balances: Balance[] = account.assets.map((a) => ({
-        categoryId: LIGHTER_PROVIDER_KEY,
-        asset: lighterAsset(String(a.asset_id), a.symbol),
-        units: a.balance,
-        valueUsd: a.symbol === 'USDC' ? a.balance : '0',
-      }))
+      const balances: Balance[] = account.assets.map((a) => {
+        const assetId = String(a.asset_id)
+        return {
+          categoryId: LIGHTER_PROVIDER_KEY,
+          asset: assetRegistry.get(assetId) ?? lighterAsset(assetId, a.symbol),
+          units: a.balance,
+          valueUsd: a.symbol === 'USDC' ? a.balance : '0',
+        }
+      })
 
       const assetCollateral = account.assets.flatMap((a) =>
         a.margin_mode === undefined
@@ -722,6 +774,9 @@ export const lighterProvider = (
         readOnlyTokenApproved: storedReadOnlyToken !== undefined,
         readOnlyTokenExpiry: storedReadOnlyToken?.expiry,
         readOnlyTokenScope: storedReadOnlyToken?.scope,
+        referralPresent:
+          appliedReferralCode !== undefined &&
+          appliedReferralCode === referralCode,
       }
 
       return {

package/src/accountConfig.ts

@@ -82,10 +82,20 @@ function projectLighterDescriptor(
         satisfied: config.readOnlyTokenApproved,
       }
 
-    // Backend-gated setup steps: `checkSetup` → `createAction` decides
+    // `SET_REFERRAL` is satisfied when LI.FI's referral code is the one applied
+    // to the account — an SDK-direct read (`getAccount` → `referralPresent`),
+    // since the applied referral is a per-user, auth-gated read. Lighter referral
+    // is mutable, so an account on another integrator's code stays gateable.
+    case ActionType.SET_REFERRAL:
+      return {
+        type: descriptor.type,
+        values: [],
+        satisfied: config.referralPresent,
+      }
+
+    // Backend-gated setup step: `checkSetup` → `createAction` decides
     // satisfaction (the backend emits no actions once satisfied), so the
     // projection carries no local state.
-    case ActionType.SET_REFERRAL:
     case ActionType.APPROVE_INTEGRATOR:
       return { type: descriptor.type, values: [] }
 

package/src/accountSummary.ts

@@ -8,9 +8,9 @@ import type {
 /**
  * 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` (free margin), so available margin
- * is the collateral as-is and the locked margin (carried by the positions'
- * `marginUsed`) is added back for the gross portfolio value.
+ * 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.
  *
  * @public
  */
@@ -18,5 +18,5 @@ export function getAccountSummary(
   account: AccountResponse,
   positions: Position[]
 ): AccountSummary {
-  return summarizeAccount(account, positions, 'free')
+  return summarizeAccount(account, positions, 'net')
 }

package/src/types/ws.ts

@@ -149,7 +149,18 @@ export type LtWsAccountAllTradesMessage = LtWsMessage & {
   data?: { trades?: Record<string, unknown[]> | unknown[] }
 }
 
-/** @public */
+/**
+ * `user_stats/{account_index}` frame; decimal strings in USD.
+ * @public
+ */
+export type LtWsUserStatsMessage = LtWsMessage & {
+  stats?: {
+    collateral?: string
+    portfolio_value?: string
+    available_balance?: string
+  }
+}
+
 export type LtWsAccountAllPositionsMessage = LtWsMessage & {
   type: 'subscribed/account_all_positions' | 'update/account_all_positions'
   positions?: Record<string, unknown>

package/src/websocket/LighterWsProvider.ts

@@ -40,6 +40,7 @@ import type {
   LtWsSpotMarketStats,
   LtWsSpotMarketStatsAllMessage,
   LtWsTradeMessage,
+  LtWsUserStatsMessage,
 } from '../types/index.js'
 import { LIGHTER_RETRY_DEFAULTS, LighterApiClient } from '../utils/apiClient.js'
 import {
@@ -310,6 +311,8 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
         return `fills:${sub.address.toLowerCase()}`
       case 'positions':
         return `positions:${sub.address.toLowerCase()}`
+      case 'accountSummary':
+        return `accountSummary:${sub.address.toLowerCase()}`
       // No live wire sub (openChannel returns a no-op), but a stable key is
       // still needed so the base's fan-out registry can track/release it.
       case 'candle':
@@ -369,6 +372,17 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       }
       return [{ channel: `trade/${id}`, needsAuth: false }]
     }
+    if (sub.channel === 'accountSummary') {
+      const accountIndex = await this.resolveAccountIndex(sub.address)
+      // `user_stats` is publicly readable; no token needed.
+      return [
+        {
+          channel: `user_stats/${accountIndex}`,
+          needsAuth: false,
+          address: sub.address,
+        },
+      ]
+    }
     if (
       sub.channel === 'orderUpdates' ||
       sub.channel === 'fills' ||
@@ -503,6 +517,14 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
       return
     }
 
+    if (
+      msg.type === 'subscribed/user_stats' ||
+      msg.type === 'update/user_stats'
+    ) {
+      this.handleUserStats(msg as LtWsUserStatsMessage)
+      return
+    }
+
     if (
       msg.type === 'subscribed/account_all_positions' ||
       msg.type === 'update/account_all_positions'
@@ -531,6 +553,33 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
     })
   }
 
+  private handleUserStats(msg: LtWsUserStatsMessage): void {
+    const address = this.addressFromChannel(msg.channel, 'user_stats')
+    if (!address) {
+      return
+    }
+    const stats = msg.stats
+    const portfolio = Number.parseFloat(stats?.portfolio_value ?? '')
+    const available = Number.parseFloat(stats?.available_balance ?? '')
+    if (!Number.isFinite(portfolio) || !Number.isFinite(available)) {
+      return
+    }
+    // Identities of the REST 'net' semantics: `available_balance` nets locked
+    // margin out with PnL marked in, and `collateral` is gross, PnL-exclusive.
+    const collateral = Number.parseFloat(stats?.collateral ?? '')
+    this.emit(`accountSummary:${address}`, {
+      channel: 'accountSummary',
+      data: {
+        portfolioValue: portfolio.toString(),
+        availableMargin: available.toString(),
+        marginUsed: Math.max(portfolio - available, 0).toString(),
+        unrealizedPnl: Number.isFinite(collateral)
+          ? (portfolio - collateral).toString()
+          : '0',
+      },
+    })
+  }
+
   private handleAccountTrades(msg: LtWsAccountAllTradesMessage): void {
     const address = this.addressFromChannel(msg.channel, 'account_all_trades')
     if (!address) {