@pear-protocol/exchanges-sdk 0.8.0 → 0.9.0

package/dist/tracker/lighter/mapper.js

@@ -138,6 +138,22 @@ function toLighterAccountType(accountTradingMode) {
   return accountTradingMode === 1 ? LighterAccountType.UNIFIED : LighterAccountType.CLASSIC;
 }
 __name(toLighterAccountType, "toLighterAccountType");
+function toLighterAccountTier(userTier) {
+  switch (userTier?.trim().toLowerCase()) {
+    case "std":
+    case "standard": {
+      return "standard";
+    }
+    case "plus": {
+      return "plus";
+    }
+    case "premium": {
+      return "premium";
+    }
+  }
+  return null;
+}
+__name(toLighterAccountTier, "toLighterAccountTier");
 function toLighterBalance(figures) {
   const spotEquity = figures.equity.spot;
   const perpetualsEquity = figures.equity.perpetuals;
@@ -393,4 +409,4 @@ function signed(value) {
 }
 __name(signed, "signed");
 
-export { buildSpotPriceIndex, leverageFromImf, mapLiveBalance, mapMarketDefaultAssetInfo, mapPositions, mapRestBalance, toLighterAccountType };
+export { buildSpotPriceIndex, leverageFromImf, mapLiveBalance, mapMarketDefaultAssetInfo, mapPositions, mapRestBalance, toLighterAccountTier, toLighterAccountType };

package/dist/tracker/lighter/tracker.js

@@ -1,14 +1,17 @@
 import BigNumber from 'bignumber.js';
 import { createExchangeWs } from '../../client';
-import { fetchOrderBookDetails, fetchAccount } from '../../client/lighter/rest';
+import { fetchAccount, fetchPublicAccount, fetchOrderBookDetails, fetchPublicOrderBookDetails, fetchAccountLimits } from '../../client/lighter/rest';
+import { retrieveLighterAuthToken } from '../../helper/lighter/auth-token.helper';
 import { BaseAccountTracker } from '../base';
 import { computeMaxBasketSize } from '../basket-size';
 import { toLighterBasketCalculation } from './basket-size';
-import { buildSpotPriceIndex, mapPositions, mapRestBalance, mapMarketDefaultAssetInfo, toLighterAccountType, mapLiveBalance } from './mapper';
+import { buildSpotPriceIndex, mapPositions, mapRestBalance, mapMarketDefaultAssetInfo, toLighterAccountType, mapLiveBalance, toLighterAccountTier } from './mapper';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 const POSITION_POLL_INTERVAL_MS = 2e3;
+const SUBSCRIBE_RETRY_BASE_DELAY_MS = 1e3;
+const SUBSCRIBE_RETRY_MAX_DELAY_MS = 3e4;
 const MARKET_REFRESH_INTERVAL_MS = 6e4;
 const DECIMAL_PATTERN = /^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/;
 function isZeroSize(size) {
@@ -30,7 +33,10 @@ class LighterAccountTracker extends BaseAccountTracker {
   static {
     __name(this, "LighterAccountTracker");
   }
+  sdk;
   accountIdentifier;
+  apiKeyIndex;
+  apiPrivateKey;
   ws = null;
   messageListenerId = null;
   openListenerId = null;
@@ -38,8 +44,10 @@ class LighterAccountTracker extends BaseAccountTracker {
   positionPollInFlight = null;
   marketRefreshTimer = null;
   marketRefreshInFlight = null;
+  subscribeRetryTimer = null;
   startInFlight = null;
   lifecycleVersion = 0;
+  wsConnectionVersion = 0;
   stateVersion = 0;
   assetsByAssetId = /* @__PURE__ */ new Map();
   // Written only by `account_all`. The live balance reads its unrealized PnL and maintenance
@@ -51,16 +59,59 @@ class LighterAccountTracker extends BaseAccountTracker {
   // market data arrives, and a balance the index cannot price would otherwise read as unknown.
   spotPriceBySymbol = buildSpotPriceIndex([]);
   stats = null;
+  // Null until the authenticated read lands, and null for good where nothing can authenticate it.
+  accountTier = null;
+  accountTierListeners = /* @__PURE__ */ new Set();
+  accountTierInFlight = null;
   hasAssets = false;
   constructor(config) {
     super(config);
+    const credentials = config.credentials;
+    this.sdk = config.sdk;
     this.accountIdentifier = config.account.exchangeIdentifier;
+    this.apiKeyIndex = credentials.api_key_index;
+    this.apiPrivateKey = credentials.api_private_key;
   }
-  /** Stateless one-shot account read — public endpoints only, and no websocket. */
+  /**
+  * The tier Lighter has the account on, and every later change to it.
+  *
+  * A separate channel from the balance on purpose: tier is account configuration, so it neither
+  * moves with the account's figures nor belongs to a trading mode. No websocket channel carries
+  * it — `/accountLimits` is the only source — so this reports what the last read said, and
+  * `refreshAccountTier` is what asks again.
+  */
+  trackAccountTier(callback) {
+    this.accountTierListeners.add(callback);
+    callback(this.accountTier);
+    return () => this.accountTierListeners.delete(callback);
+  }
+  /** The tier as the last read left it, without asking the venue again. */
+  getAccountTier() {
+    return this.accountTier;
+  }
+  /**
+  * Re-reads the tier and tells every subscriber what changed.
+  *
+  * Called after something moves the tier — a change this account submitted — because nothing on
+  * the socket announces one. Repeated callers share one in-flight read.
+  */
+  refreshAccountTier() {
+    if (this.accountTierInFlight) {
+      return this.accountTierInFlight;
+    }
+    const refresh = this.performAccountTierRead(this.lifecycleVersion).finally(() => {
+      if (this.accountTierInFlight === refresh) {
+        this.accountTierInFlight = null;
+      }
+    });
+    this.accountTierInFlight = refresh;
+    return refresh;
+  }
+  /** Stateless one-shot account read — authenticated for connected accounts, and no websocket. */
   async snapshot() {
     const [account, markets] = await Promise.all([
       this.fetchPrimaryAccount(),
-      fetchOrderBookDetails(this.demo)
+      this.fetchMarkets()
     ]);
     if (!account) return {
       balance: null,
@@ -81,7 +132,7 @@ class LighterAccountTracker extends BaseAccountTracker {
   async fetchAssetSnapshots(marketIds) {
     const [account, markets] = await Promise.all([
       this.fetchPrimaryAccount(),
-      fetchOrderBookDetails(this.demo)
+      this.fetchMarkets()
     ]);
     const settings = toAccountSettings(markets.perp, account?.positions ?? []);
     const result = {};
@@ -105,7 +156,7 @@ class LighterAccountTracker extends BaseAccountTracker {
   async snapshotMaxBasketSize(input) {
     const [account, markets] = await Promise.all([
       this.fetchPrimaryAccount(),
-      fetchOrderBookDetails(this.demo)
+      this.fetchMarkets()
     ]);
     if (!account) {
       return computeMaxBasketSize({
@@ -138,7 +189,7 @@ class LighterAccountTracker extends BaseAccountTracker {
   /** Creates one tracker lifecycle while repeated callers share the same pending start. */
   async performStart() {
     const lifecycleVersion = ++this.lifecycleVersion;
-    const markets = await fetchOrderBookDetails(this.demo);
+    const markets = await this.fetchMarkets();
     if (lifecycleVersion !== this.lifecycleVersion) return;
     this.spotPriceBySymbol = buildSpotPriceIndex(markets.spot);
     const trackedAssets = /* @__PURE__ */ new Map();
@@ -165,10 +216,14 @@ class LighterAccountTracker extends BaseAccountTracker {
     void this.pollPositions();
     this.positionPollTimer = setInterval(() => void this.pollPositions(), POSITION_POLL_INTERVAL_MS);
     this.marketRefreshTimer = setInterval(() => void this.refreshMarkets(), MARKET_REFRESH_INTERVAL_MS);
+    void this.refreshAccountTier();
   }
   async cleanupConnections() {
     this.lifecycleVersion += 1;
+    this.wsConnectionVersion += 1;
     this.startInFlight = null;
+    this.accountTierInFlight = null;
+    this.clearSubscribeRetry();
     if (this.positionPollTimer) {
       clearInterval(this.positionPollTimer);
       this.positionPollTimer = null;
@@ -197,6 +252,8 @@ class LighterAccountTracker extends BaseAccountTracker {
   }
   /** Starts a clean account-data epoch before subscribing on each websocket connection. */
   handleWsOpen() {
+    const wsConnectionVersion = ++this.wsConnectionVersion;
+    this.clearSubscribeRetry();
     this.stateVersion += 1;
     this.assetsByAssetId.clear();
     this.wsPositionsByMarketId.clear();
@@ -210,18 +267,47 @@ class LighterAccountTracker extends BaseAccountTracker {
     this.onStateUpdate({
       trackedAssets
     });
-    this.sendStaticSubs();
+    this.subscribeAccountChannels(wsConnectionVersion, 0);
   }
-  sendStaticSubs() {
-    this.ws?.send({
-      type: "subscribe",
-      channel: `account_all/${this.accountIdentifier}`
-    });
-    this.ws?.send({
-      type: "subscribe",
-      channel: `user_stats/${this.accountIdentifier}`
+  /**
+  * Subscribes this socket epoch's account channels, and keeps trying until one attempt lands.
+  *
+  * This is the sole subscriber of `account_all` and `user_stats`, and the live balance is built
+  * from those two channels alone — see `buildBalance`. A mint that failed once and was never
+  * retried therefore left the tracker connected but permanently unsubscribed: the 2s REST poll
+  * kept positions moving while the balance silently froze until some incidental reconnect.
+  *
+  * The wait doubles up to a ceiling, and only a new connection epoch or teardown ends it.
+  */
+  subscribeAccountChannels(wsConnectionVersion, attempt) {
+    void this.sendAccountSubscriptions(wsConnectionVersion).catch((error) => {
+      if (wsConnectionVersion !== this.wsConnectionVersion) {
+        return;
+      }
+      this.onError(error instanceof Error ? error : new Error(String(error)));
+      const delayMs = Math.min(SUBSCRIBE_RETRY_BASE_DELAY_MS * 2 ** attempt, SUBSCRIBE_RETRY_MAX_DELAY_MS);
+      this.subscribeRetryTimer = setTimeout(() => {
+        this.subscribeRetryTimer = null;
+        this.subscribeAccountChannels(wsConnectionVersion, attempt + 1);
+      }, delayMs);
     });
   }
+  /** Mints a live token for this socket epoch and authenticates every account subscription. */
+  async sendAccountSubscriptions(wsConnectionVersion) {
+    const authToken = await this.retrieveRequiredAuthToken();
+    if (wsConnectionVersion !== this.wsConnectionVersion || !this.ws?.connected) {
+      return;
+    }
+    this.ws.subscribe(`account_all/${this.accountIdentifier}`, authToken);
+    this.ws.subscribe(`user_stats/${this.accountIdentifier}`, authToken);
+  }
+  /** Drops a pending subscription retry, so nothing outlives the connection that scheduled it. */
+  clearSubscribeRetry() {
+    if (this.subscribeRetryTimer) {
+      clearTimeout(this.subscribeRetryTimer);
+      this.subscribeRetryTimer = null;
+    }
+  }
   routeRaw(raw) {
     try {
       const msg = JSON.parse(raw);
@@ -339,10 +425,40 @@ class LighterAccountTracker extends BaseAccountTracker {
     }
     return settings;
   }
+  /** Reads the account with credentials when present, or explicitly uses the read-only verifier path. */
   async fetchPrimaryAccount() {
-    const data = await fetchAccount(Number(this.accountIdentifier), this.demo);
+    const authToken = await this.retrieveAuthToken();
+    const accountIndex = Number(this.accountIdentifier);
+    const data = authToken ? await fetchAccount(accountIndex, authToken, this.demo) : await fetchPublicAccount(accountIndex, this.demo);
     return data.accounts[0];
   }
+  /** Reads market context under the same account identity as the snapshot that consumes it. */
+  async fetchMarkets() {
+    const authToken = await this.retrieveAuthToken();
+    return authToken ? fetchOrderBookDetails(authToken, this.demo) : fetchPublicOrderBookDetails(this.demo);
+  }
+  /** Returns this account's cached auth token, or no token for the explicit empty-key verifier. */
+  async retrieveAuthToken() {
+    if (!this.apiPrivateKey) {
+      return void 0;
+    }
+    if (!this.sdk) {
+      throw new Error("Lighter authenticated account reads require a Pear SDK client");
+    }
+    return retrieveLighterAuthToken(this.sdk, {
+      accountIndex: Number(this.accountIdentifier),
+      apiKeyIndex: this.apiKeyIndex,
+      apiPrivateKey: this.apiPrivateKey
+    }, this.demo);
+  }
+  /** Requires credentials for private WebSocket channels even when REST is in verifier mode. */
+  async retrieveRequiredAuthToken() {
+    const authToken = await this.retrieveAuthToken();
+    if (!authToken) {
+      throw new Error("Lighter WebSocket account channels require API credentials");
+    }
+    return authToken;
+  }
   pollPositions() {
     if (this.positionPollInFlight) return this.positionPollInFlight;
     const lifecycleVersion = this.lifecycleVersion;
@@ -384,6 +500,42 @@ class LighterAccountTracker extends BaseAccountTracker {
       }
     }
   }
+  /**
+  * Reads the tier Lighter currently has the account on, and publishes it when it moved.
+  *
+  * `/accountLimits` is authenticated, so a tracker with no SDK to mint a token through — and demo,
+  * where no such account exists — reports no tier rather than a wrong one. A failed read does the
+  * same and leaves the last known tier standing: the endpoint failing is not the account losing
+  * its tier, and blanking it would announce a change nobody made.
+  */
+  async performAccountTierRead(lifecycleVersion) {
+    if (!this.sdk || this.demo) {
+      return;
+    }
+    try {
+      const credentials = this.credentials;
+      const accountIndex = Number(this.accountIdentifier);
+      const authToken = await retrieveLighterAuthToken(this.sdk, {
+        accountIndex,
+        apiKeyIndex: credentials.api_key_index,
+        apiPrivateKey: credentials.api_private_key
+      }, this.demo);
+      const limits = await fetchAccountLimits(accountIndex, authToken, this.demo);
+      const accountTier = toLighterAccountTier(limits.user_tier);
+      if (lifecycleVersion !== this.lifecycleVersion) {
+        return;
+      }
+      if (accountTier === null || accountTier === this.accountTier) {
+        return;
+      }
+      this.accountTier = accountTier;
+      for (const listener of this.accountTierListeners) {
+        listener(accountTier);
+      }
+    } catch (err) {
+      this.onError(err instanceof Error ? err : new Error(String(err)));
+    }
+  }
   /** Shares one in-flight market read, so a slow response cannot stack requests behind the WAF. */
   refreshMarkets() {
     if (this.marketRefreshInFlight) return this.marketRefreshInFlight;
@@ -422,7 +574,7 @@ class LighterAccountTracker extends BaseAccountTracker {
   */
   async performMarketRefresh(lifecycleVersion) {
     try {
-      const markets = await fetchOrderBookDetails(this.demo);
+      const markets = await this.fetchMarkets();
       if (lifecycleVersion !== this.lifecycleVersion) return;
       for (const market of markets.perp) {
         this.marketsByMarketId.set(market.market_id, market);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/exchanges-sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Pear Protocol Exchanges SDK",
   "private": false,
   "type": "module",
@@ -22,12 +22,14 @@
   "scripts": {
     "build": "tsup",
     "clean": "rm -rf dist .turbo",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
-    "@pear-protocol/core-sdk": "^1.18.0",
-    "@pear-protocol/types": "^1.27.0",
-    "@pear-protocol/utils": "^0.5.1",
+    "@pear-protocol/core-sdk": "^1.19.0",
+    "@pear-protocol/types": "^1.28.0",
+    "@pear-protocol/utils": "^0.5.3",
     "bignumber.js": "^11.1.1",
     "partysocket": "^1.0.3",
     "viem": "^2.48.8",
@@ -36,6 +38,7 @@
   "devDependencies": {
     "@backend/typescript-config": "workspace:*",
     "tsup": "8.5.1",
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "vitest": "4.1.2"
   }
 }