perps-sdk-ts 1.0.1

package/src/feed/feed_client.ts

@@ -0,0 +1,288 @@
+import WebSocket from "ws";
+import { PriceFeedResponse, PriceFeedResponseSchema } from "../types";
+import { API_ENDPOINTS } from "../config";
+
+/**
+ * Callback function type for price updates
+ */
+export type PriceUpdateCallback = (priceData: PriceFeedResponse) => void;
+
+/**
+ * Normalize feed ID: remove 0x prefix and lowercase
+ * Pyth WebSocket sends IDs WITHOUT 0x prefix
+ */
+function normalizeFeedId(feedId: string): string {
+  let normalized = feedId.toLowerCase();
+  if (normalized.startsWith('0x')) {
+    normalized = normalized.slice(2);
+  }
+  return normalized;
+}
+
+/**
+ * WebSocket client for real-time price feeds from Pyth Network
+ */
+export class FeedClient {
+  private url: string;
+  private ws?: WebSocket;
+  private callbacks: Map<string, PriceUpdateCallback[]> = new Map();
+  private onError?: (error: Error) => void;
+  private onClose?: () => void;
+  private pairFeedMap: Map<string, string> = new Map();
+  private reconnectAttempts: number = 0;
+  private maxReconnectAttempts: number = 5;
+  private reconnectDelay: number = 1000;
+
+  constructor(
+    url: string = API_ENDPOINTS.PYTH_WS,
+    onError?: (error: Error) => void,
+    onClose?: () => void
+  ) {
+    this.url = url;
+    this.onError = onError;
+    this.onClose = onClose;
+  }
+
+  /**
+   * Register a callback for a specific price feed
+   */
+  registerPriceFeedCallback(
+    feedId: string,
+    callback: PriceUpdateCallback
+  ): void {
+    const id = normalizeFeedId(feedId);
+    if (!this.callbacks.has(id)) {
+      this.callbacks.set(id, []);
+    }
+    this.callbacks.get(id)!.push(callback);
+
+    if (this.callbacks.get(id)!.length === 1 && this.isConnected()) {
+      this.subscribeToPriceFeeds([id]);
+    }
+  }
+
+  /**
+   * Unregister a callback for a specific price feed
+   */
+  unregisterPriceFeedCallback(
+    feedId: string,
+    callback: PriceUpdateCallback
+  ): void {
+    const id = normalizeFeedId(feedId);
+    const cbs = this.callbacks.get(id);
+    if (!cbs) return;
+
+    const idx = cbs.indexOf(callback);
+    if (idx > -1) cbs.splice(idx, 1);
+
+    if (cbs.length === 0 && this.isConnected()) {
+      this.unsubscribeFromPriceFeeds([id]);
+      this.callbacks.delete(id);
+    }
+  }
+
+  /**
+   * Load pair to feed ID mappings
+   */
+  loadPairFeeds(pairFeeds: Map<string, string>): void {
+    this.pairFeedMap = pairFeeds;
+  }
+
+  /**
+   * Get feed ID for a trading pair
+   */
+  getFeedIdForPair(pairName: string): string | undefined {
+    return this.pairFeedMap.get(pairName);
+  }
+
+  /**
+   * Connect to WebSocket and listen for price updates
+   */
+  async listenForPriceUpdates(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      try {
+        this.ws = new WebSocket(this.url);
+
+        this.ws.on("open", () => {
+          console.log("WebSocket connected to Pyth Network");
+          this.reconnectAttempts = 0;
+
+          const feedIds = Array.from(this.callbacks.keys());
+          if (feedIds.length > 0) {
+            this.subscribeToPriceFeeds(feedIds);
+          }
+
+          resolve();
+        });
+
+        this.ws.on("message", (data: WebSocket.Data) => {
+          try {
+            const message = JSON.parse(data.toString());
+
+            if (message.type !== "price_update") {
+              console.log("Received non-update message:", message);
+            }
+
+            if (message.type === "price_update") {
+              this.handlePriceUpdate(message);
+            }
+          } catch (error) {
+            console.error("Error parsing WebSocket message:", error);
+          }
+        });
+
+        this.ws.on("error", (error: Error) => {
+          console.error("WebSocket error:", error);
+          if (this.onError) {
+            this.onError(error);
+          }
+          reject(error);
+        });
+
+        this.ws.on("close", () => {
+          console.log("WebSocket connection closed");
+          if (this.onClose) {
+            this.onClose();
+          }
+          this.attemptReconnect();
+        });
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Subscribe to specific price feeds
+   */
+  private subscribeToPriceFeeds(feedIds: string[]): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+
+    // Feed IDs should already be normalized, but ensure they are
+    const ids = feedIds.map(id => normalizeFeedId(id));
+
+    this.ws.send(JSON.stringify({ type: "subscribe", ids }));
+    console.log("Subscribed to Pyth feeds:", ids);
+  }
+
+  /**
+   * Unsubscribe from specific price feeds
+   */
+  private unsubscribeFromPriceFeeds(feedIds: string[]): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+
+    const ids = feedIds.map(id => normalizeFeedId(id));
+    this.ws.send(JSON.stringify({ type: "unsubscribe", ids }));
+    console.log("Unsubscribed from Pyth feeds:", ids);
+  }
+
+  /**
+   * Handle incoming price update
+   */
+  private handlePriceUpdate(message: any): void {
+    try {
+      if (message.price_feed) {
+        const priceUpdate = message.price_feed;
+
+        // ⭐ KEY FIX: Normalize the incoming feed ID (Pyth sends without 0x)
+        const feedId = normalizeFeedId(priceUpdate.id);
+
+        const priceFeed = {
+          id: feedId,
+          price: {
+            price: priceUpdate.price.price,
+            conf: priceUpdate.price.conf,
+            expo: priceUpdate.price.expo,
+            publishTime: priceUpdate.price.publish_time,
+          },
+          emaPrice: {
+            price: priceUpdate.ema_price.price,
+            conf: priceUpdate.ema_price.conf,
+            expo: priceUpdate.ema_price.expo,
+            publishTime: priceUpdate.ema_price.publish_time,
+          },
+        };
+
+        const validatedPriceFeed = PriceFeedResponseSchema.parse(priceFeed);
+
+        // Trigger callbacks
+        const callbacks = this.callbacks.get(validatedPriceFeed.id);
+        if (callbacks && callbacks.length > 0) {
+          console.log(`✅ Triggering ${callbacks.length} callback(s) for ${validatedPriceFeed.id}`);
+          callbacks.forEach((callback) => {
+            try {
+              callback(validatedPriceFeed);
+            } catch (error) {
+              console.error(
+                "Error in price update callback:",
+                error instanceof Error ? error.message : String(error)
+              );
+            }
+          });
+        } else {
+          console.warn(`⚠️ No callbacks registered for feed: ${validatedPriceFeed.id}`);
+          console.log(`Registered feeds: [${Array.from(this.callbacks.keys()).join(", ")}]`);
+        }
+      }
+    } catch (error) {
+      console.error(
+        "Error processing price update:",
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+
+  /**
+   * Attempt to reconnect to WebSocket
+   */
+  private attemptReconnect(): void {
+    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+      console.error("Max reconnection attempts reached");
+      return;
+    }
+
+    this.reconnectAttempts++;
+    const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
+
+    console.log(
+      `Attempting to reconnect in ${delay}ms (attempt ${this.reconnectAttempts})`
+    );
+
+    setTimeout(() => {
+      this.listenForPriceUpdates().catch((error) => {
+        console.error("Reconnection failed:", error);
+      });
+    }, delay);
+  }
+
+  /**
+   * Get latest prices via HTTP
+   */
+  async getLatestPriceUpdates(feedIds: string[]): Promise<any> {
+    const url = `${API_ENDPOINTS.PYTH_HTTP}?ids[]=${feedIds.join("&ids[]=")}`;
+
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch prices: ${response.statusText}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Close the WebSocket connection
+   */
+  close(): void {
+    if (this.ws) {
+      this.ws.close();
+      this.ws = undefined;
+    }
+  }
+
+  /**
+   * Check if WebSocket is connected
+   */
+  isConnected(): boolean {
+    return this.ws !== undefined && this.ws.readyState === WebSocket.OPEN;
+  }
+}

package/src/index.ts

@@ -0,0 +1,114 @@
+/**
+ * Avantis Trader SDK - TypeScript
+ *
+ * A comprehensive SDK for interacting with the Avantis decentralized
+ * leveraged trading platform.
+ */
+
+// Main client
+export { TraderClient } from './client';
+
+// Signers
+export { BaseSigner } from './signers/base';
+export { LocalSigner } from './signers/local';
+export { KMSSigner } from './signers/kms';
+
+// Feed client
+export { FeedClient, PriceUpdateCallback } from './feed/feed_client';
+
+// RPC modules
+export { PairsCache } from './rpc/pairs_cache';
+export { AssetParametersRPC } from './rpc/asset_parameters';
+export { CategoryParametersRPC } from './rpc/category_parameters';
+export { FeeParametersRPC } from './rpc/fee_parameters';
+export { TradingParametersRPC } from './rpc/trading_parameters';
+export { BlendedRPC } from './rpc/blended';
+export { TradeRPC } from './rpc/trade';
+export { SnapshotRPC } from './rpc/snapshot';
+export { TradingOperationsRPC } from './rpc/trading_operations';
+export { DelegationRPC } from './rpc/delegation';
+export { PairInfoQueriesRPC } from './rpc/pair_info_queries';
+export { ReferralOperationsRPC } from './rpc/referral_operations';
+export { MulticallRPC, type MulticallCall, type MulticallResult } from './rpc/multicall';
+
+// Types and enums
+export {
+  TradeInputOrderType,
+  MarginUpdateType,
+  type Spread,
+  type PairInfo,
+  type TradeInput,
+  type TradeResponse,
+  type Price,
+  type EmaPrice,
+  type PriceFeedResponse,
+  type OpenInterest,
+  type OpenInterestLimits,
+  type Utilization,
+  type Skew,
+  type Fee,
+  type Depth,
+  type LossProtectionInfo,
+  type PairData,
+  type Group,
+  type Snapshot,
+  type Trade,
+  type TradeInfo,
+  type OpenLimitOrder,
+  type ReferralTier,
+  type ReferralDiscount,
+  type ContractCallOptions,
+  type TransactionReceipt,
+  type PairsBackendReturn,
+  type ContractPairInfo,
+  type PairStruct,
+  type GroupStruct,
+  type FeeStruct,
+  type FeedStruct,
+  type BackupFeedStruct,
+  type LeverageStruct,
+  type ValuesStruct,
+  type PnlFeesStruct,
+  fromBlockchain10,
+  fromBlockchain6,
+  toBlockchain10,
+  toBlockchain6,
+  fromBlockchain12,
+  toBlockchain12,
+  fromBlockchain18,
+  toBlockchain18,
+} from './types';
+
+// Configuration
+export {
+  CONTRACTS,
+  API_ENDPOINTS,
+  type ContractAddresses,
+  type NetworkConfig,
+  getContractAddress,
+  setContractAddresses,
+} from './config';
+
+// Utilities
+export {
+  isTupleType,
+  isArrayType,
+  processOutputTypes,
+  decoder,
+  hexToNumber,
+  numberToHex,
+  isValidAddress,
+  toChecksumAddress,
+  sleep,
+  retryWithBackoff,
+} from './utils';
+
+// Crypto utilities (for advanced usage)
+export {
+  publicKeyIntToEthAddress,
+  derEncodedPublicKeyToEthAddress,
+  getSigRS,
+  getSigV,
+  getSigRSV,
+  signatureToHex,
+} from './crypto/spki';

package/src/rpc/asset_parameters.ts

@@ -0,0 +1,217 @@
+import { Contract, Provider } from 'ethers';
+import {
+  OpenInterest,
+  OpenInterestLimits,
+  Utilization,
+  Skew,
+  TradeInput,
+  fromBlockchain6,
+  fromBlockchain10,
+} from '../types';
+import { PairsCache } from './pairs_cache';
+
+/**
+ * RPC module for retrieving asset-level parameters
+ */
+export class AssetParametersRPC {
+  private provider: Provider;
+  private pairStorageContract: Contract;
+  private pairInfosContract: Contract;
+  private tradingStorageContract: Contract;
+  private pairsCache: PairsCache;
+
+  constructor(
+    provider: Provider,
+    pairStorageContract: Contract,
+    pairInfosContract: Contract,
+    pairsCache: PairsCache,
+    tradingStorageContract: Contract
+  ) {
+    this.provider = provider;
+    this.pairStorageContract = pairStorageContract;
+    this.pairInfosContract = pairInfosContract;
+    this.tradingStorageContract = tradingStorageContract;
+    this.pairsCache = pairsCache;
+  }
+
+  /**
+   * Get open interest limits for all pairs
+   * @returns Map of pair index to OI limits
+   */
+  async getOILimits(): Promise<Map<number, OpenInterestLimits>> {
+    const pairs = await this.pairsCache.getPairsInfo();
+    const limits = new Map<number, OpenInterestLimits>();
+
+    for (const [pairIndex, pairInfo] of pairs) {
+      limits.set(pairIndex, {
+        pairIndex,
+        maxLong: pairInfo.maxLongOiP,
+        maxShort: pairInfo.maxShortOiP,
+      });
+    }
+
+    return limits;
+  }
+
+  /**
+   * Get current open interest for all pairs
+   * @returns Map of pair index to OI
+   */
+  async getOI(): Promise<Map<number, OpenInterest>> {
+    const pairs = await this.pairsCache.getPairsInfo();
+    const oi = new Map<number, OpenInterest>();
+
+    for (const [pairIndex] of pairs) {
+      try {
+        // Use TradingStorage contract which has openInterestUSDC method
+        const pairOILong = await this.tradingStorageContract.openInterestUSDC(pairIndex, 0); // 0 = long
+        const pairOIShort = await this.tradingStorageContract.openInterestUSDC(pairIndex, 1); // 1 = short
+
+        const limits = await this.getOILimits();
+        const maxOI = limits.get(pairIndex)?.maxLong || 0;
+
+        oi.set(pairIndex, {
+          long: fromBlockchain6(pairOILong),
+          short: fromBlockchain6(pairOIShort),
+          max: maxOI,
+        });
+      } catch (error) {
+        console.error(`Error getting OI for pair ${pairIndex}:`, error);
+        // Set default values on error
+        oi.set(pairIndex, {
+          long: 0,
+          short: 0,
+          max: 0,
+        });
+      }
+    }
+
+    return oi;
+  }
+
+  /**
+   * Get utilization for all pairs
+   * @returns Map of pair index to utilization
+   */
+  async getUtilization(): Promise<Map<number, Utilization>> {
+    const oi = await this.getOI();
+    const utilization = new Map<number, Utilization>();
+
+    for (const [pairIndex, oiData] of oi) {
+      const utilizationLong = oiData.max > 0 ? (oiData.long / oiData.max) * 100 : 0;
+      const utilizationShort = oiData.max > 0 ? (oiData.short / oiData.max) * 100 : 0;
+
+      utilization.set(pairIndex, {
+        utilizationLong,
+        utilizationShort,
+      });
+    }
+
+    return utilization;
+  }
+
+  /**
+   * Get asset skew (long / total) for all pairs
+   * @returns Map of pair index to skew
+   */
+  async getAssetSkew(): Promise<Map<number, Skew>> {
+    const oi = await this.getOI();
+    const skew = new Map<number, Skew>();
+
+    for (const [pairIndex, oiData] of oi) {
+      const total = oiData.long + oiData.short;
+      const skewValue = total > 0 ? oiData.long / total : 0.5;
+
+      skew.set(pairIndex, { skew: skewValue });
+    }
+
+    return skew;
+  }
+
+  /**
+   * Get price impact spread for opening a position
+   * @param positionSize - Position size in USDC
+   * @param isLong - True for long, false for short
+   * @param pairIndex - Pair index
+   * @returns Price impact spread percentage
+   */
+  async getPriceImpactSpread(
+    positionSize: number,
+    isLong: boolean,
+    pairIndex: number
+  ): Promise<number> {
+    try {
+      const result = await this.pairInfosContract.getPriceImpactP(
+        pairIndex,
+        isLong,
+        BigInt(Math.floor(positionSize * 1e6))
+      );
+      return fromBlockchain10(result);
+    } catch (error) {
+      console.error('Error getting price impact spread:', error);
+      return 0;
+    }
+  }
+
+  /**
+   * Get skew impact spread
+   * @param pairIndex - Pair index
+   * @returns Skew impact spread
+   */
+  async getSkewImpactSpread(pairIndex: number): Promise<number> {
+    try {
+      const skewMap = await this.getAssetSkew();
+      const skew = skewMap.get(pairIndex);
+
+      if (!skew) return 0;
+
+      // Simple skew impact calculation (can be customized)
+      const deviation = Math.abs(skew.skew - 0.5);
+      return deviation * 100; // Convert to basis points
+    } catch (error) {
+      console.error('Error getting skew impact spread:', error);
+      return 0;
+    }
+  }
+
+  /**
+   * Get opening price impact spread for a trade
+   * @param tradeInput - Trade input parameters
+   * @returns Opening price impact spread
+   */
+  async getOpeningPriceImpactSpread(tradeInput: TradeInput): Promise<number> {
+    const pairIndex = await this.pairsCache.getPairIndex(tradeInput.pair);
+    if (pairIndex === undefined) {
+      throw new Error(`Pair ${tradeInput.pair} not found`);
+    }
+
+    const positionSize = tradeInput.collateralInTrade * tradeInput.leverage;
+    return await this.getPriceImpactSpread(positionSize, tradeInput.isLong, pairIndex);
+  }
+
+  /**
+   * Get one percent depth (liquidity depth)
+   * @returns Map of pair index to depth
+   */
+  async getOnePercentDepth(): Promise<Map<number, { above: number; below: number }>> {
+    const pairs = await this.pairsCache.getPairsInfo();
+    const depth = new Map<number, { above: number; below: number }>();
+
+    for (const [pairIndex] of pairs) {
+      try {
+        const depthAbove = await this.pairInfosContract.onePercentDepthAboveUsdc(pairIndex);
+        const depthBelow = await this.pairInfosContract.onePercentDepthBelowUsdc(pairIndex);
+
+        depth.set(pairIndex, {
+          above: fromBlockchain6(depthAbove),
+          below: fromBlockchain6(depthBelow),
+        });
+      } catch (error) {
+        // If method doesn't exist, set default values
+        depth.set(pairIndex, { above: 0, below: 0 });
+      }
+    }
+
+    return depth;
+  }
+}

package/src/rpc/blended.ts

@@ -0,0 +1,77 @@
+import { Contract, Provider } from 'ethers';
+import { Utilization, Skew } from '../types';
+import { AssetParametersRPC } from './asset_parameters';
+import { CategoryParametersRPC } from './category_parameters';
+import { PairsCache } from './pairs_cache';
+
+/**
+ * RPC module for blended calculations (25% asset + 75% category)
+ */
+export class BlendedRPC {
+  private assetParams: AssetParametersRPC;
+  private categoryParams: CategoryParametersRPC;
+  private pairsCache: PairsCache;
+
+  constructor(
+    assetParams: AssetParametersRPC,
+    categoryParams: CategoryParametersRPC,
+    pairsCache: PairsCache
+  ) {
+    this.assetParams = assetParams;
+    this.categoryParams = categoryParams;
+    this.pairsCache = pairsCache;
+  }
+
+  /**
+   * Calculate blended utilization (25% asset + 75% category)
+   * @returns Map of pair index to blended utilization
+   */
+  async getBlendedUtilization(): Promise<Map<number, Utilization>> {
+    const assetUtilization = await this.assetParams.getUtilization();
+    const categoryUtilization = await this.categoryParams.getUtilization();
+    const pairs = await this.pairsCache.getPairsInfo();
+
+    const blended = new Map<number, Utilization>();
+
+    for (const [pairIndex, pairInfo] of pairs) {
+      const assetUtil = assetUtilization.get(pairIndex);
+      const catUtil = categoryUtilization.get(pairInfo.groupIndex);
+
+      if (assetUtil && catUtil) {
+        blended.set(pairIndex, {
+          utilizationLong:
+            0.25 * assetUtil.utilizationLong + 0.75 * catUtil.utilizationLong,
+          utilizationShort:
+            0.25 * assetUtil.utilizationShort + 0.75 * catUtil.utilizationShort,
+        });
+      }
+    }
+
+    return blended;
+  }
+
+  /**
+   * Calculate blended skew (25% asset + 75% category)
+   * @returns Map of pair index to blended skew
+   */
+  async getBlendedSkew(): Promise<Map<number, Skew>> {
+    const assetSkew = await this.assetParams.getAssetSkew();
+    const categorySkew = await this.categoryParams.getCategorySkew();
+    const pairs = await this.pairsCache.getPairsInfo();
+
+    const blended = new Map<number, Skew>();
+
+    for (const [pairIndex, pairInfo] of pairs) {
+      const assetSk = assetSkew.get(pairIndex);
+      const catSk = categorySkew.get(pairInfo.groupIndex);
+
+      if (assetSk && catSk) {
+        blended.set(pairIndex, {
+          skew: 0.25 * assetSk.skew + 0.75 * catSk.skew,
+        });
+      }
+    }
+
+    return blended;
+  }
+}