@lifi/perps-sdk-provider-lighter 28.0.0 → 29.1.0

package/dist/types/accountSummary.d.ts

@@ -2,9 +2,9 @@ import type { AccountResponse, AccountSummary, Position } from '@lifi/perps-type
 /**
  * Roll a Lighter account up into an {@link AccountSummary}. `totalAssetValue`
  * is perps-route equity and excludes the spot route, so `portfolioValue` adds
- * every spot `balances` row, settlement included; the `collateralBalances` row
- * is buying power already inside `totalAssetValue`. The positions supply only
- * the margin and PnL breakdown.
+ * every spot `balances` row, settlement included; the `collateralBalances` rows
+ * are the perps-route holding already inside `totalAssetValue`. The positions
+ * supply only the margin and PnL breakdown.
  *
  * @throws {PerpsError} `SDKError` when the account is not a Lighter one.
  * @public

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

@@ -1 +1 @@
-{"version":3,"file":"accountSummary.d.ts","sourceRoot":"","sources":["../../src/accountSummary.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EAEd,QAAQ,EACT,MAAM,mBAAmB,CAAA;AAe1B;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,QAAQ,EAAE,GACpB,cAAc,CA0BhB"}
+{"version":3,"file":"accountSummary.d.ts","sourceRoot":"","sources":["../../src/accountSummary.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EAEd,QAAQ,EACT,MAAM,mBAAmB,CAAA;AAoB1B;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,QAAQ,EAAE,GACpB,cAAc,CA0BhB"}

package/dist/types/availableToTrade.d.ts

@@ -0,0 +1,15 @@
+import type { AvailableToTrade, Market, Position } from '@lifi/perps-types';
+/**
+ * The amounts the account can still buy and sell on one Lighter perps
+ * market. The side that adds to an open position on `market` gets
+ * `availableMargin`. The side that reduces or flips it gets the position's
+ * initial margin requirement, which the closing part of the order consumes,
+ * plus `availableMargin` and the margin that closing releases, floored at 0.
+ * A deficit therefore never cuts the closing part. Both amounts are at least 0.
+ *
+ * @param availableMargin - The account's {@link AccountSummary.availableMargin}.
+ * @throws {PerpsError} `SDKError` when a decimal the formula reads is malformed.
+ * @internal
+ */
+export declare const lighterAvailableToTrade: (market: Market, availableMargin: string, positions: readonly Position[]) => AvailableToTrade;
+//# sourceMappingURL=availableToTrade.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"availableToTrade.d.ts","sourceRoot":"","sources":["../../src/availableToTrade.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAwB3E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,GAClC,QAAQ,MAAM,EACd,iBAAiB,MAAM,EACvB,WAAW,SAAS,QAAQ,EAAE,KAC7B,gBAmBF,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk-provider-lighter",
-  "version": "28.0.0",
+  "version": "29.1.0",
   "description": "Lighter provider plugin for @lifi/perps-sdk",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -44,10 +44,10 @@
   "dependencies": {
     "big.js": "^7.0.1",
     "viem": "^2.55.18",
-    "@lifi/perps-types": "^16.0.0"
+    "@lifi/perps-types": "^16.1.0"
   },
   "peerDependencies": {
-    "@lifi/perps-sdk": "^17.0.0"
+    "@lifi/perps-sdk": "^18.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/LighterProvider.ts

@@ -15,6 +15,7 @@ import {
   type ProviderAccountExistsParams,
   type ProviderGetAccountParams,
   type ProviderGetActivityParams,
+  type ProviderGetAvailableToTradeParams,
   type ProviderGetDepositFlowParams,
   type ProviderGetFillsParams,
   type ProviderGetMarketSettingsParams,
@@ -41,6 +42,8 @@ import type {
   ActionStep,
   ActivitiesResponse,
   ActivityItem,
+  Asset,
+  AvailableToTrade,
   Balance,
   Fill,
   FillsResponse,
@@ -68,6 +71,7 @@ import Big from 'big.js'
 import type { Address } from 'viem'
 import { projectLighterConfigSettings } from './accountConfig.js'
 import { getAccountSummary } from './accountSummary.js'
+import { lighterAvailableToTrade } from './availableToTrade.js'
 import {
   DEFAULT_TRADES_LIMIT,
   LIGHTER_ALL_MARKETS_WILDCARD,
@@ -94,6 +98,7 @@ import {
 } from './signers/signActions.js'
 import type {
   LtAccount,
+  LtAccountAsset,
   LtAccountLimits,
   LtAccountOrdersResponse,
   LtAccountPnL,
@@ -159,6 +164,13 @@ const ZERO_FEE_TIER = { maker: '0', taker: '0' }
 const tickToFeeString = (tick: number): string =>
   String(tick / LIGHTER_FEE_TICK_SCALE)
 
+const transferableWithin = (venueFigure: Big, units: Big): string => {
+  if (venueFigure.lt(0)) {
+    return '0'
+  }
+  return (venueFigure.gt(units) ? units : venueFigure).toFixed()
+}
+
 const projectFeeTier = (
   limits: LtAccountLimits
 ): { maker: string; taker: string } => ({
@@ -784,7 +796,7 @@ export const createLighterProvider = (
     }
   }
 
-  return {
+  const plugin: LighterPerpsProvider = {
     type: providerKey,
 
     internalSetupActions: [ActionType.SET_REFERRAL],
@@ -848,12 +860,12 @@ export const createLighterProvider = (
       )
 
       const totalMarginUsed = positions.reduce(
-        (sum, p) => sum + Number.parseFloat(p.marginUsed),
-        0
+        (sum, p) => sum.plus(toRequiredBig(p.marginUsed, 'marginUsed')),
+        new Big(0)
       )
       const totalUnrealizedPnl = positions.reduce(
-        (sum, p) => sum + Number.parseFloat(p.unrealizedPnl),
-        0
+        (sum, p) => sum.plus(toRequiredBig(p.unrealizedPnl, 'unrealizedPnl')),
+        new Big(0)
       )
 
       const instanceMeta = providers.find((p) => p.key === providerKey)
@@ -867,59 +879,75 @@ export const createLighterProvider = (
         account.available_balance,
         'available_balance'
       )
-      // An underwater account reports no buying power. That is a margin
-      // deficit, not a holding, so it carries no collateral row either.
-      const collateralBalances: Balance[] = availableBalance.gt(0)
-        ? [
-            {
-              categoryId: perpsCategory?.id ?? providerKey,
-              asset:
-                perpsCategory?.quoteAsset ??
-                lighterAsset(
-                  collateral.displaySymbol,
-                  collateral.displaySymbol,
-                  providerKey
-                ),
-              units: availableBalance.toString(),
-              valueUsd: availableBalance.toString(),
-              price: '1',
-            },
-          ]
-        : []
-      // Spot token holdings — non-collateral. The instance's settlement asset
-      // is valued 1:1; an asset no spot market prices keeps a zero USD value.
+      // Each asset has a spot route (`balance`) and a perps route
+      // (`margin_balance`). The instance's settlement asset is valued 1:1; an
+      // asset no spot market prices keeps a zero USD value.
       const heldAssets = account.assets.filter((asset) =>
         toRequiredBig(asset.balance, 'balance').gt(0)
       )
+      const marginAssets = account.assets.filter((asset) =>
+        toRequiredBig(asset.margin_balance, 'margin_balance').gt(0)
+      )
       const spotPrices = spotPriceByAssetId(
         registry.markets,
         spotCategoryId,
         prices,
         new Set(
-          heldAssets
+          [...heldAssets, ...marginAssets]
             .filter((a) => a.asset_id !== collateral.assetIndex)
             .map((a) => String(a.asset_id))
         )
       )
-      const balances: Balance[] = heldAssets.map((a) => {
-        const assetId = String(a.asset_id)
+      const toBalance = (
+        a: LtAccountAsset,
+        categoryId: string,
+        asset: Asset,
+        units: string
+      ): Balance => {
         const price =
           a.asset_id === collateral.assetIndex
             ? new Big(1)
-            : spotPrices.get(assetId)
+            : spotPrices.get(String(a.asset_id))
         return {
-          categoryId: spotCategoryId,
-          asset:
-            assetRegistry.get(assetId) ??
-            lighterAsset(assetId, a.symbol, providerKey),
-          units: a.balance,
+          categoryId,
+          asset,
+          units,
           valueUsd:
-            price === undefined
-              ? '0'
-              : toRequiredBig(a.balance, 'balance').times(price).toFixed(),
+            price === undefined ? '0' : new Big(units).times(price).toFixed(),
           ...(price === undefined ? {} : { price: price.toFixed() }),
         }
+      }
+      const registryAsset = (a: LtAccountAsset): Asset =>
+        assetRegistry.get(String(a.asset_id)) ??
+        lighterAsset(String(a.asset_id), a.symbol, providerKey)
+      // The perps category names the settlement asset by its quote asset, so
+      // the settlement row carries that descriptor rather than the spot one.
+      const settlementAsset =
+        perpsCategory?.quoteAsset ??
+        lighterAsset(
+          collateral.displaySymbol,
+          collateral.displaySymbol,
+          providerKey
+        )
+      // A category transfer moves only the settlement asset, capped by the
+      // account's free margin; every other perps-route asset releases none.
+      const collateralBalances: Balance[] = marginAssets.map((a) => {
+        const isSettlement = a.asset_id === collateral.assetIndex
+        return {
+          ...toBalance(
+            a,
+            perpsCategory?.id ?? providerKey,
+            isSettlement ? settlementAsset : registryAsset(a),
+            a.margin_balance
+          ),
+          transferable: isSettlement
+            ? transferableWithin(availableBalance, new Big(a.margin_balance))
+            : '0',
+        }
       })
+      const balances: Balance[] = heldAssets.map((a) =>
+        toBalance(a, spotCategoryId, registryAsset(a), a.balance)
+      )
 
       const assetCollateral = account.assets.flatMap((a) =>
         a.margin_mode === undefined
@@ -961,8 +989,8 @@ export const createLighterProvider = (
         balances,
         collateralBalances,
         positions,
-        marginUsed: totalMarginUsed.toString(),
-        unrealizedPnl: totalUnrealizedPnl.toString(),
+        marginUsed: totalMarginUsed.toFixed(),
+        unrealizedPnl: totalUnrealizedPnl.toFixed(),
         feeTier:
           limitsResult === undefined
             ? ZERO_FEE_TIER
@@ -1025,6 +1053,25 @@ export const createLighterProvider = (
       }
     },
 
+    /**
+     * Lighter publishes no per-market figure, so this derives one from the
+     * account's `available_balance` and its open position on the market.
+     */
+    async getAvailableToTrade(
+      params: ProviderGetAvailableToTradeParams,
+      opts?: SDKRequestOptions
+    ): Promise<AvailableToTrade | undefined> {
+      const registry = getMarketRegistry(requireClient(), providerKey)
+      await registry.sync()
+      const market = registry.require(params.marketId)
+      if (market.categoryId === LIGHTER_SPOT_CATEGORY_ID) {
+        return undefined
+      }
+      const account = await plugin.getAccount({ address: params.address }, opts)
+      const { availableMargin } = getAccountSummary(account, account.positions)
+      return lighterAvailableToTrade(market, availableMargin, account.positions)
+    },
+
     /**
      * 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
@@ -1695,6 +1742,7 @@ export const createLighterProvider = (
       )
     },
   }
+  return plugin
 }
 
 /**

package/src/accountSummary.ts

@@ -7,24 +7,29 @@ import type {
 } from '@lifi/perps-types'
 import { PerpsErrorCode } from '@lifi/perps-types'
 import Big from 'big.js'
+import { LIGHTER_PROVIDER_KEY, LIGHTER_RH_PROVIDER_KEY } from './constants.js'
 import { toRequiredBig } from './utils/decimal.js'
 
 const lighterConfig = (account: AccountResponse): LighterAccountConfig => {
-  if (account.config.provider !== 'lighter') {
+  const { config } = account
+  if (
+    config.provider !== LIGHTER_PROVIDER_KEY &&
+    config.provider !== LIGHTER_RH_PROVIDER_KEY
+  ) {
     throw new PerpsError(
       PerpsErrorCode.SDKError,
-      `Lighter account summary received a '${account.config.provider}' account config`
+      `Lighter account summary received a '${config.provider}' account config`
     )
   }
-  return account.config
+  return config
 }
 
 /**
  * Roll a Lighter account up into an {@link AccountSummary}. `totalAssetValue`
  * is perps-route equity and excludes the spot route, so `portfolioValue` adds
- * every spot `balances` row, settlement included; the `collateralBalances` row
- * is buying power already inside `totalAssetValue`. The positions supply only
- * the margin and PnL breakdown.
+ * every spot `balances` row, settlement included; the `collateralBalances` rows
+ * are the perps-route holding already inside `totalAssetValue`. The positions
+ * supply only the margin and PnL breakdown.
  *
  * @throws {PerpsError} `SDKError` when the account is not a Lighter one.
  * @public

package/src/availableToTrade.ts

@@ -0,0 +1,61 @@
+import { toAssetDisplay } from '@lifi/perps-sdk'
+import type { AvailableToTrade, Market, Position } from '@lifi/perps-types'
+import { MarginMode, PositionSide } from '@lifi/perps-types'
+import Big from 'big.js'
+import { toRequiredBig } from './utils/decimal.js'
+
+const atLeastZero = (value: Big): Big => (value.lt(0) ? new Big(0) : value)
+
+// Lighter's `available_balance` already nets cross unrealized PnL and counts
+// an isolated position's equity above its IMR, so only the rest is released.
+const releasedOnClose = (position: Position): Big => {
+  const marginUsed = toRequiredBig(position.marginUsed, 'marginUsed')
+  if (position.marginMode !== MarginMode.ISOLATED) {
+    return marginUsed
+  }
+  const equity = marginUsed.plus(
+    toRequiredBig(position.unrealizedPnl, 'unrealizedPnl')
+  )
+  const imr = toRequiredBig(
+    position.initialMarginRequirement,
+    'initialMarginRequirement'
+  )
+  return equity.lt(imr) ? equity : imr
+}
+
+/**
+ * The amounts the account can still buy and sell on one Lighter perps
+ * market. The side that adds to an open position on `market` gets
+ * `availableMargin`. The side that reduces or flips it gets the position's
+ * initial margin requirement, which the closing part of the order consumes,
+ * plus `availableMargin` and the margin that closing releases, floored at 0.
+ * A deficit therefore never cuts the closing part. Both amounts are at least 0.
+ *
+ * @param availableMargin - The account's {@link AccountSummary.availableMargin}.
+ * @throws {PerpsError} `SDKError` when a decimal the formula reads is malformed.
+ * @internal
+ */
+export const lighterAvailableToTrade = (
+  market: Market,
+  availableMargin: string,
+  positions: readonly Position[]
+): AvailableToTrade => {
+  const available = toRequiredBig(availableMargin, 'availableMargin')
+  const adding = atLeastZero(available)
+  const position = positions.find((p) => p.market.id === market.id)
+  const reducing =
+    position === undefined
+      ? adding
+      : toRequiredBig(
+          position.initialMarginRequirement,
+          'initialMarginRequirement'
+        ).plus(atLeastZero(available.plus(releasedOnClose(position))))
+  const isShort = position?.side === PositionSide.SHORT
+  return {
+    providerId: market.providerId,
+    marketId: market.id,
+    asset: toAssetDisplay(market.quoteAsset),
+    buy: (isShort ? reducing : adding).toFixed(),
+    sell: (isShort ? adding : reducing).toFixed(),
+  }
+}

package/src/websocket/LighterWsProvider.ts

@@ -660,10 +660,10 @@ export class LighterWsProvider extends WsProviderBase<SubState> {
     this.emit(`accountSummary:${address}`, {
       channel: 'accountSummary',
       data: {
-        portfolioValue: portfolio.toString(),
-        availableMargin: available.toString(),
-        marginUsed: marginUsed.toString(),
-        unrealizedPnl: portfolio.minus(collateral).toString(),
+        portfolioValue: portfolio.toFixed(),
+        availableMargin: available.toFixed(),
+        marginUsed: marginUsed.toFixed(),
+        unrealizedPnl: portfolio.minus(collateral).toFixed(),
       },
     })
   }
@@ -1008,5 +1008,5 @@ export const lighterWsProvider = (
   Object.assign(
     ({ provider, wsUrl, client }: WsProviderFactoryParams) =>
       new LighterWsProvider(wsUrl, provider, options, client),
-    { streamsCandles: false }
+    { streamsCandles: false, streamsAvailableToTrade: false }
   )