@pear-protocol/exchanges-sdk 0.3.0 → 0.5.0

package/dist/tracker/lighter/mapper.js

@@ -1,36 +1,53 @@
 import BigNumber from 'bignumber.js';
 import { positionKey } from '../utils';
 import { QUOTE_ASSET } from './const';
-import { LighterAccountType } from './types';
+import { LighterAccountType, LighterAccountTier } from './types';
 
-function mapBalance(summary, assetsByAssetId) {
+function buildAssetBalances(rawAssets) {
   const free = {};
   const used = {};
   const total = {};
   const assets = [];
-  for (const a of assetsByAssetId.values()) {
-    const balBN = new BigNumber(a.balance || "0");
-    const lockedBN = new BigNumber(a.locked_balance || "0");
-    const totalAmt = balBN.plus(lockedBN).toFixed();
-    free[a.symbol] = a.balance;
-    used[a.symbol] = a.locked_balance;
-    total[a.symbol] = totalAmt;
+  for (const rawAsset of rawAssets) {
+    const balance = new BigNumber(rawAsset.balance || "0");
+    const lockedBalance = new BigNumber(rawAsset.locked_balance || "0");
+    const marginBalance = new BigNumber(rawAsset.margin_balance || "0");
+    const totalAmount = balance.plus(marginBalance).toFixed();
+    const freeAmount = BigNumber.max(balance.plus(marginBalance).minus(lockedBalance), 0).toFixed();
+    free[rawAsset.symbol] = freeAmount;
+    used[rawAsset.symbol] = rawAsset.locked_balance;
+    total[rawAsset.symbol] = totalAmount;
     assets.push({
-      asset: a.symbol,
-      free: a.balance,
-      used: a.locked_balance,
-      total: totalAmt,
-      walletBalance: totalAmt,
-      usdValue: a.symbol === QUOTE_ASSET ? totalAmt : "0"
+      asset: rawAsset.symbol,
+      free: freeAmount,
+      used: rawAsset.locked_balance,
+      total: totalAmount,
+      walletBalance: totalAmount,
+      usdValue: rawAsset.symbol === QUOTE_ASSET ? totalAmount : "0"
     });
   }
+  return { free, used, total, assets };
+}
+function mapBalance(summary, assetsByAssetId, rawPositions, marketsByMarketId) {
+  const { free, used, total, assets } = buildAssetBalances(assetsByAssetId.values());
   const portfolioValueBN = new BigNumber(summary.portfolioValue);
   const marginUsageFrac = new BigNumber(summary.marginUsagePct).div(100);
   const unrealizedPnl = portfolioValueBN.minus(summary.collateral).toFixed(6);
   const initialMarginUsed = marginUsageFrac.multipliedBy(portfolioValueBN).toFixed(6);
-  const marginRatio = marginUsageFrac.toFixed(4);
+  const positionRisks = calculatePositionRisks(rawPositions, marketsByMarketId);
+  const maintenanceMargin = positionRisks.reduce(
+    (totalMaintenance, positionRisk) => totalMaintenance.plus(positionRisk.maintenance),
+    new BigNumber(0)
+  );
+  const isolatedEquity = positionRisks.reduce(
+    (totalEquity, positionRisk) => positionRisk.marginMode === "isolated" ? totalEquity.plus(positionRisk.equity) : totalEquity,
+    new BigNumber(0)
+  );
+  const crossEquity = new BigNumber(summary.crossPortfolioValue ?? portfolioValueBN.minus(isolatedEquity));
+  const marginRatio = maximumMarginRatio(positionRisks, crossEquity);
   return {
-    accountType: LighterAccountType.BASIC,
+    accountType: summary.accountType,
+    accountTier: summary.accountTier,
     free,
     used,
     total,
@@ -39,32 +56,79 @@ function mapBalance(summary, assetsByAssetId) {
     walletBalance: summary.collateral,
     unrealizedPnl,
     initialMarginUsed,
-    maintenanceMargin: "0",
+    maintenanceMargin: maintenanceMargin.toFixed(6),
     marginRatio,
     assets,
     timestamp: Date.now()
   };
 }
-function mapPositions(raw) {
+function buildAccountBalance(account, marketsByMarketId, accountTier) {
+  const { free, used, total, assets } = buildAssetBalances(account.assets ?? []);
+  const positions = account.positions ?? [];
+  const allocatedMargin = sumPositionField(positions, "allocated_margin", (position) => position.margin_mode === 1);
+  const totalCollateral = new BigNumber(account.collateral).plus(allocatedMargin);
+  const isolatedInitialMargin = positions.reduce((totalInitialMargin, position) => {
+    if (position.margin_mode !== 1 || new BigNumber(position.position).isZero()) {
+      return totalInitialMargin;
+    }
+    return totalInitialMargin.plus(
+      new BigNumber(position.position_value).abs().times(position.initial_margin_fraction).div(100)
+    );
+  }, new BigNumber(0));
+  const initialMargin = new BigNumber(account.cross_initial_margin_requirement).plus(isolatedInitialMargin);
+  const positionRisks = calculatePositionRisks(positions, marketsByMarketId);
+  const isolatedMaintenanceMargin = positionRisks.reduce(
+    (totalMaintenance, positionRisk) => positionRisk.marginMode === "isolated" ? totalMaintenance.plus(positionRisk.maintenance) : totalMaintenance,
+    new BigNumber(0)
+  );
+  const maintenanceMarginBN = new BigNumber(account.cross_maintenance_margin_requirement).plus(
+    isolatedMaintenanceMargin
+  );
+  const marginRatio = maximumMarginRatio(
+    positionRisks.filter((positionRisk) => positionRisk.marginMode === "isolated"),
+    new BigNumber(account.cross_asset_value),
+    new BigNumber(account.cross_maintenance_margin_requirement)
+  );
+  const unrealizedPnl = sumPositionField(positions, "unrealized_pnl").toFixed(6);
+  return {
+    accountType: toLighterAccountType(account.account_trading_mode),
+    accountTier,
+    free,
+    used,
+    total,
+    availableToTrade: account.available_balance,
+    totalEquity: account.total_asset_value,
+    walletBalance: totalCollateral.toFixed(6),
+    unrealizedPnl,
+    initialMarginUsed: initialMargin.toFixed(6),
+    maintenanceMargin: maintenanceMarginBN.toFixed(6),
+    marginRatio,
+    assets,
+    timestamp: Date.now()
+  };
+}
+function mapPositions(raw, includeZeroPositions = false) {
   const positions = /* @__PURE__ */ new Map();
   const trackedAssets = /* @__PURE__ */ new Map();
-  for (const p of Object.values(raw)) {
-    const sizeBN = new BigNumber(p.position || "0");
-    const side = p.sign === -1 ? "short" : "long";
-    const leverage = leverageFromImf(p.initial_margin_fraction);
-    const marginType = p.margin_mode === 1 ? "isolated" : "cross";
-    const marketId = String(p.market_id);
-    positions.set(positionKey(p.symbol, side), {
-      symbol: p.symbol,
+  for (const rawPosition of Object.values(raw)) {
+    const unsignedSize = new BigNumber(rawPosition.position || "0");
+    const side = rawPosition.sign === -1 ? "short" : "long";
+    const size = rawPosition.sign === -1 ? unsignedSize.negated() : unsignedSize;
+    const leverage = leverageFromImf(rawPosition.initial_margin_fraction);
+    const marginType = rawPosition.margin_mode === 1 ? "isolated" : "cross";
+    const marketId = String(rawPosition.market_id);
+    trackedAssets.set(marketId, { coin: rawPosition.symbol, leverage, marginType });
+    if (!includeZeroPositions && unsignedSize.isZero()) continue;
+    positions.set(positionKey(rawPosition.symbol, side), {
+      symbol: rawPosition.symbol,
       side,
-      size: sizeBN.isFinite() && !sizeBN.isZero() ? sizeBN.toFixed() : "0",
-      entryPrice: p.avg_entry_price || "0",
-      unrealizedPnl: p.unrealized_pnl || "0",
+      size: size.isFinite() && !size.isZero() ? size.toFixed() : "0",
+      entryPrice: rawPosition.avg_entry_price || "0",
+      unrealizedPnl: rawPosition.unrealized_pnl || "0",
       leverage,
       marginType,
-      liquidationPrice: p.liquidation_price && p.liquidation_price !== "0" ? p.liquidation_price : null
+      liquidationPrice: rawPosition.liquidation_price && rawPosition.liquidation_price !== "0" ? rawPosition.liquidation_price : null
     });
-    trackedAssets.set(marketId, { coin: p.symbol, leverage, marginType });
   }
   return { positions, trackedAssets };
 }
@@ -73,5 +137,71 @@ function leverageFromImf(imfPct) {
   if (!pct.isFinite() || pct.lte(0)) return "1";
   return new BigNumber(100).div(pct).integerValue(BigNumber.ROUND_FLOOR).toFixed();
 }
+function mapMarketDefaultAssetInfo(market) {
+  return {
+    coin: market.symbol,
+    leverage: leverageFromImf(new BigNumber(market.default_initial_margin_fraction).div(100).toFixed()),
+    marginType: "cross"
+  };
+}
+function toLighterAccountType(accountTradingMode) {
+  return accountTradingMode === 1 ? LighterAccountType.UNIFIED : LighterAccountType.CLASSIC;
+}
+function toLighterAccountTier(userTier) {
+  switch (userTier?.trim().toLowerCase()) {
+    case "std":
+    case "standard":
+      return LighterAccountTier.STANDARD;
+    case "premium":
+      return LighterAccountTier.PREMIUM;
+    case "plus":
+      return LighterAccountTier.PLUS;
+    default:
+      return void 0;
+  }
+}
+function calculatePositionRisks(rawPositions, marketsByMarketId) {
+  const positionRisks = [];
+  for (const rawPosition of rawPositions) {
+    const market = marketsByMarketId.get(rawPosition.market_id);
+    if (!market || new BigNumber(rawPosition.position).isZero()) {
+      continue;
+    }
+    const marginMode = rawPosition.margin_mode === 1 ? "isolated" : "cross";
+    const maintenance = new BigNumber(rawPosition.position_value).abs().times(market.maintenance_margin_fraction).div(1e4);
+    const equity = marginMode === "isolated" ? new BigNumber(rawPosition.allocated_margin).plus(rawPosition.unrealized_pnl) : new BigNumber(0);
+    positionRisks.push({ marginMode, maintenance, equity });
+  }
+  return positionRisks;
+}
+function maximumMarginRatio(positionRisks, crossEquity, authoritativeCrossMaintenance) {
+  const calculatedCrossMaintenance = positionRisks.reduce(
+    (totalMaintenance, positionRisk) => positionRisk.marginMode === "cross" ? totalMaintenance.plus(positionRisk.maintenance) : totalMaintenance,
+    new BigNumber(0)
+  );
+  const crossMaintenance = authoritativeCrossMaintenance ?? calculatedCrossMaintenance;
+  let maximumRatio = maintenanceRatio(crossMaintenance, crossEquity);
+  for (const positionRisk of positionRisks) {
+    if (positionRisk.marginMode === "isolated") {
+      maximumRatio = BigNumber.max(maximumRatio, maintenanceRatio(positionRisk.maintenance, positionRisk.equity));
+    }
+  }
+  return maximumRatio.toFixed(4);
+}
+function maintenanceRatio(maintenance, equity) {
+  if (equity.gt(0)) {
+    return maintenance.div(equity);
+  }
+  return maintenance.gt(0) ? new BigNumber(1) : new BigNumber(0);
+}
+function sumPositionField(positions, field, include = () => true) {
+  let total = new BigNumber(0);
+  for (const position of positions) {
+    if (include(position)) {
+      total = total.plus(position[field] || "0");
+    }
+  }
+  return total;
+}
 
-export { leverageFromImf, mapBalance, mapPositions };
+export { buildAccountBalance, leverageFromImf, mapBalance, mapMarketDefaultAssetInfo, mapPositions, toLighterAccountTier, toLighterAccountType };

package/dist/tracker/lighter/mapper.test.js

@@ -0,0 +1,199 @@
+import { describe, it, expect } from 'vitest';
+import { buildAccountBalance, mapBalance, toLighterAccountTier, mapPositions } from './mapper';
+import { LighterAccountTier, LighterAccountType } from './types';
+
+const markets = /* @__PURE__ */ new Map([
+  [
+    1,
+    {
+      market_id: 1,
+      symbol: "BTC",
+      status: "active",
+      default_initial_margin_fraction: 1e3,
+      maintenance_margin_fraction: 1e3
+    }
+  ],
+  [
+    2,
+    {
+      market_id: 2,
+      symbol: "ETH",
+      status: "active",
+      default_initial_margin_fraction: 2e3,
+      maintenance_margin_fraction: 500
+    }
+  ]
+]);
+describe("Lighter account mapping", () => {
+  it("combines cross and isolated collateral, risk requirements, and unrealized PnL", () => {
+    const balance = buildAccountBalance(
+      {
+        account_type: 2,
+        account_trading_mode: 1,
+        collateral: "1000",
+        total_asset_value: "1145",
+        available_balance: "800",
+        cross_asset_value: "1020",
+        cross_initial_margin_requirement: "100",
+        cross_maintenance_margin_requirement: "50",
+        assets: [
+          {
+            symbol: "USDC",
+            balance: "10",
+            locked_balance: "2",
+            margin_balance: "1000"
+          }
+        ],
+        positions: [
+          {
+            market_id: 1,
+            symbol: "BTC",
+            initial_margin_fraction: "10",
+            sign: 1,
+            position: "1",
+            avg_entry_price: "1000",
+            position_value: "1000",
+            unrealized_pnl: "20",
+            liquidation_price: "500",
+            margin_mode: 0,
+            allocated_margin: "0"
+          },
+          {
+            market_id: 2,
+            symbol: "ETH",
+            initial_margin_fraction: "20",
+            sign: -1,
+            position: "2",
+            avg_entry_price: "250",
+            position_value: "500",
+            unrealized_pnl: "-25",
+            liquidation_price: "400",
+            margin_mode: 1,
+            allocated_margin: "150"
+          }
+        ]
+      },
+      markets,
+      LighterAccountTier.PLUS
+    );
+    expect(balance).toMatchObject({
+      accountType: "unified",
+      accountTier: "plus",
+      totalEquity: "1145",
+      walletBalance: "1150.000000",
+      unrealizedPnl: "-5.000000",
+      initialMarginUsed: "200.000000",
+      maintenanceMargin: "75.000000",
+      marginRatio: "0.2000",
+      free: { USDC: "1008" },
+      used: { USDC: "2" },
+      total: { USDC: "1010" }
+    });
+  });
+  it("uses the riskiest independently liquidatable bucket for live margin ratio", () => {
+    const balance = mapBalance(
+      {
+        collateral: "1050",
+        portfolioValue: "950",
+        crossPortfolioValue: "900",
+        availableToTrade: "800",
+        marginUsagePct: "0",
+        accountType: LighterAccountType.CLASSIC
+      },
+      /* @__PURE__ */ new Map(),
+      [
+        rawPosition({ position_value: "100", margin_mode: 0 }),
+        rawPosition({
+          market_id: 2,
+          symbol: "ETH",
+          position_value: "500",
+          unrealized_pnl: "-100",
+          margin_mode: 1,
+          allocated_margin: "150"
+        })
+      ],
+      markets
+    );
+    expect(balance.maintenanceMargin).toBe("35.000000");
+    expect(balance.marginRatio).toBe("0.5000");
+  });
+  it.each(["0", "-1"])("fails closed for live maintenance risk with nonpositive equity %s", (portfolioValue) => {
+    const balance = mapBalance(
+      {
+        collateral: "0",
+        portfolioValue,
+        availableToTrade: "0",
+        marginUsagePct: "0",
+        accountType: LighterAccountType.CLASSIC
+      },
+      /* @__PURE__ */ new Map(),
+      [rawPosition({ position_value: "1000" })],
+      markets
+    );
+    expect(balance.maintenanceMargin).toBe("100.000000");
+    expect(balance.marginRatio).toBe("1.0000");
+  });
+  it.each(["0", "-1"])("fails closed for REST maintenance risk with nonpositive equity %s", (totalAssetValue) => {
+    const balance = buildAccountBalance(
+      {
+        account_type: 0,
+        account_trading_mode: 0,
+        collateral: "0",
+        total_asset_value: totalAssetValue,
+        available_balance: "0",
+        cross_asset_value: totalAssetValue,
+        cross_initial_margin_requirement: "0",
+        cross_maintenance_margin_requirement: "10"
+      },
+      markets
+    );
+    expect(balance.maintenanceMargin).toBe("10.000000");
+    expect(balance.marginRatio).toBe("1.0000");
+  });
+  it("maps authenticated account-limit tier names and never infers a tier from account_type", () => {
+    expect(toLighterAccountTier("std")).toBe(LighterAccountTier.STANDARD);
+    expect(toLighterAccountTier("STANDARD")).toBe(LighterAccountTier.STANDARD);
+    expect(toLighterAccountTier("premium")).toBe(LighterAccountTier.PREMIUM);
+    expect(toLighterAccountTier("plus")).toBe(LighterAccountTier.PLUS);
+    expect(toLighterAccountTier("unknown")).toBeUndefined();
+    const balance = buildAccountBalance(
+      {
+        account_type: 2,
+        account_trading_mode: 0,
+        collateral: "0",
+        total_asset_value: "0",
+        available_balance: "0",
+        cross_asset_value: "0",
+        cross_initial_margin_requirement: "0",
+        cross_maintenance_margin_requirement: "0"
+      },
+      /* @__PURE__ */ new Map()
+    );
+    expect(balance.accountTier).toBeUndefined();
+  });
+  it("filters full-snapshot zero rows and preserves signed short exposure", () => {
+    const positions = mapPositions({
+      1: rawPosition({ market_id: 1, symbol: "BTC", sign: -1, position: "2" }),
+      2: rawPosition({ market_id: 2, symbol: "ETH", sign: 1, position: "0.0000" })
+    }).positions;
+    expect(Array.from(positions.values())).toEqual([
+      expect.objectContaining({ symbol: "BTC", side: "short", size: "-2" })
+    ]);
+  });
+});
+function rawPosition(overrides) {
+  return {
+    market_id: 1,
+    symbol: "BTC",
+    initial_margin_fraction: "10",
+    sign: 1,
+    position: "1",
+    avg_entry_price: "1000",
+    position_value: "1000",
+    unrealized_pnl: "0",
+    liquidation_price: "500",
+    margin_mode: 0,
+    allocated_margin: "0",
+    ...overrides
+  };
+}