@lifi/perps-sdk-provider-lighter 34.0.0 → 35.1.0

package/src/accountSummary.ts

@@ -50,7 +50,8 @@ export const lighterPortfolioValue = (
 
 /**
  * Roll up settlement equity, spot holdings and non-settlement margin holdings.
- * Settlement margin is already included in `totalAssetValue`.
+ * The settlement asset counts as `totalAssetValue` plus its spot-route balance,
+ * so a row that pools both routes is not counted again.
  *
  * @throws {PerpsError} `SDKError` when the account is not a Lighter one.
  * @public
@@ -61,14 +62,11 @@ export function getAccountSummary(
 ): AccountSummary {
   const config = lighterConfig(account)
   const settlement = LIGHTER_COLLATERAL_ASSETS[config.provider]
-  const holdings = [
-    ...account.balances,
-    ...account.collateralBalances.filter(
-      ({ asset }) =>
-        asset.id !== String(settlement.assetIndex) &&
-        asset.id !== settlement.displaySymbol
-    ),
-  ]
+  const holdings = [...account.balances, ...account.collateralBalances].filter(
+    ({ asset }) =>
+      asset.id !== String(settlement.assetIndex) &&
+      asset.id !== settlement.displaySymbol
+  )
 
   let marginUsed = new Big(0)
   let unrealizedPnl = new Big(0)
@@ -79,7 +77,9 @@ export function getAccountSummary(
 
   return {
     portfolioValue: lighterPortfolioValue(
-      toRequiredBig(config.totalAssetValue, 'totalAssetValue'),
+      toRequiredBig(config.totalAssetValue, 'totalAssetValue').plus(
+        toRequiredBig(config.collateralSpotBalance, 'collateralSpotBalance')
+      ),
       holdings.map((balance) => balance.valueUsd)
     ).toFixed(),
     availableMargin: atLeastZero(

package/src/constants.ts

@@ -193,6 +193,15 @@ export const DEFAULT_TRADES_LIMIT = 50
  */
 export const LIGHTER_FEE_TICK_SCALE = 1_000_000
 
+/**
+ * Decimal places a client may use for Lighter leverage. Lighter stores
+ * leverage as an integer basis-point IMF (`round(10000 / leverage)`), and at
+ * this precision a read-back leverage always re-saves the same IMF.
+ *
+ * @public
+ */
+export const LIGHTER_LEVERAGE_PRECISION = 2
+
 /**
  * Scale of the integer `initial_margin_fraction` values Lighter publishes on
  * trade rows and order-book details: the integer is a percent times 100, so

package/src/index.ts

@@ -25,6 +25,7 @@ export {
   DEFAULT_LIGHTER_WS_URL,
   LIGHTER_CLIENT_ORDER_INDEX_ID_PREFIX,
   LIGHTER_COLLATERAL_ASSETS,
+  LIGHTER_LEVERAGE_PRECISION,
   LIGHTER_MAINNET_DEPLOYMENT,
   LIGHTER_MAINNET_SIGNER_CHAIN_ID,
   LIGHTER_PROVIDER_KEY,

package/src/signers/createAuthToken.ts

@@ -33,8 +33,7 @@ export interface CreateAuthTokenInputs {
  * endpoints (`getOrders`, `getOrder`, `getActivity`, etc.).
  *
  * This utility carries no SDK-wide coupling — pass an explicit `signer` +
- * `apiKey` and consume the returned bearer however the caller likes
- * (per-call `options.lighterAuthToken`, persisted cache, etc.).
+ * `apiKey` and consume the returned bearer however the caller likes.
  * @public
  */
 export async function createAuthToken(

package/src/utils/mapPosition.ts

@@ -1,16 +1,20 @@
 import type { PerpsMarketDisplay, Position } from '@lifi/perps-types'
 import { MarginMode, PositionSide } from '@lifi/perps-types'
 import Big from 'big.js'
-import { LIGHTER_IMF_PERCENT_SCALE } from '../constants.js'
+import {
+  LIGHTER_IMF_PERCENT_SCALE,
+  LIGHTER_LEVERAGE_PRECISION,
+} from '../constants.js'
 import type { LtAccountPosition } from '../types/index.js'
 import { LT_MARGIN_MODE_ISOLATED } from '../types/index.js'
 import { toPositiveRequiredBig, toRequiredBig } from './decimal.js'
 
 /**
  * Display leverage from an IMF percent string: `100 / IMF` in exact decimal
- * arithmetic before conversion to `number`. This value is for displaying the
- * venue setting; provider risk calculations consume the original decimal IMF
- * instead. `undefined` for a non-positive or unparsable IMF.
+ * arithmetic, rounded half-up to `LIGHTER_LEVERAGE_PRECISION` before
+ * conversion to `number`, so the value a client reads is the value it saved.
+ * Provider risk calculations consume the original decimal IMF instead.
+ * `undefined` for a non-positive or unparsable IMF.
  * @public
  */
 export const leverageFromImf = (imf: string): number | undefined => {
@@ -23,7 +27,10 @@ export const leverageFromImf = (imf: string): number | undefined => {
   if (parsed.lte(0)) {
     return undefined
   }
-  return new Big(100).div(parsed).toNumber()
+  return new Big(100)
+    .div(parsed)
+    .round(LIGHTER_LEVERAGE_PRECISION, Big.roundHalfUp)
+    .toNumber()
 }
 
 /**

package/src/utils/settlementPool.ts

@@ -0,0 +1,36 @@
+import type Big from 'big.js'
+import type { LtAccountAsset } from '../types/account.js'
+import { toRequiredBig } from './decimal.js'
+
+/** Both routes of a unified account's settlement asset, as one holding. */
+export const pooledSettlementUnits = (asset: LtAccountAsset): Big =>
+  toRequiredBig(asset.balance, 'balance').plus(
+    toRequiredBig(asset.margin_balance, 'margin_balance')
+  )
+
+/**
+ * Spot units a unified account can spend from its settlement pool: the free
+ * spot route plus the margin route up to the account's `available_balance`.
+ * This is `computeSpotAvailableToTradeMarket` in Lighter's `lighter-ts` for an
+ * asset priced 1:1 with a `loan_to_value` of 1. The result can be negative.
+ */
+export const pooledSettlementSpendable = (
+  asset: LtAccountAsset,
+  availableBalance: Big
+): Big => {
+  const marginBalance = toRequiredBig(asset.margin_balance, 'margin_balance')
+  return toRequiredBig(asset.balance, 'balance')
+    .minus(toRequiredBig(asset.locked_balance, 'locked_balance'))
+    .plus(marginBalance.lt(availableBalance) ? marginBalance : availableBalance)
+}
+
+/** Spot-route `balance` of the collateral asset; `'0'` when the account holds none. */
+export const collateralSpotBalance = (
+  assets: readonly LtAccountAsset[],
+  settlementAssetIndex: number
+): string => {
+  const asset = assets.find((a) => a.asset_id === settlementAssetIndex)
+  return asset === undefined
+    ? '0'
+    : toRequiredBig(asset.balance, 'balance').toFixed()
+}

package/src/utils/transferMargin.ts

@@ -2,6 +2,7 @@ import {
   PerpsError,
   positionSupportsMarginAdjustment,
   positionSupportsMarginRemoval,
+  validateDecimalString,
 } from '@lifi/perps-sdk'
 import {
   type DecimalString,
@@ -12,18 +13,11 @@ import Big from 'big.js'
 
 const AMOUNT_DECIMALS = 6
 
-function positionAmount(value: string, field: string): Big {
-  try {
-    return new Big(value)
-  } catch {
-    throw new PerpsError(
-      PerpsErrorCode.ValidationError,
-      `Invalid decimal string on Position.${field}: '${value}'`
-    )
-  }
+function positionAmount(value: DecimalString, field: string): Big {
+  return new Big(validateDecimalString(value, `Position.${field}`))
 }
 
-function positivePositionAmount(value: string, field: string): Big {
+function positivePositionAmount(value: DecimalString, field: string): Big {
   const amount = positionAmount(value, field)
   if (amount.lte(0)) {
     throw new PerpsError(