@basedone/core 0.1.10 → 0.2.0

package/lib/ecommerce/utils/errors.ts

@@ -0,0 +1,113 @@
+/**
+ * Ecommerce API Error Utilities
+ * 
+ * This module contains error handling utilities for the ecommerce API.
+ */
+
+/**
+ * Ecommerce API error class
+ */
+export class EcommerceApiError extends Error {
+  /** HTTP status code */
+  public statusCode?: number;
+  
+  /** Response data */
+  public data?: any;
+  
+  /** Is network error */
+  public isNetworkError: boolean;
+  
+  /** Is timeout error */
+  public isTimeoutError: boolean;
+  
+  /** Is authentication error */
+  public isAuthError: boolean;
+
+  constructor(
+    message: string,
+    statusCode?: number,
+    data?: any,
+    isNetworkError = false,
+    isTimeoutError = false
+  ) {
+    super(message);
+    this.name = "EcommerceApiError";
+    this.statusCode = statusCode;
+    this.data = data;
+    this.isNetworkError = isNetworkError;
+    this.isTimeoutError = isTimeoutError;
+    this.isAuthError = statusCode === 401 || statusCode === 403;
+    
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, EcommerceApiError);
+    }
+  }
+}
+
+/**
+ * Parse error from axios error or API response
+ */
+export function parseError(error: any): EcommerceApiError {
+  // Network error
+  if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT") {
+    return new EcommerceApiError(
+      "Request timeout",
+      undefined,
+      undefined,
+      false,
+      true
+    );
+  }
+  
+  if (error.code === "ERR_NETWORK" || !error.response) {
+    return new EcommerceApiError(
+      error.message || "Network error",
+      undefined,
+      undefined,
+      true,
+      false
+    );
+  }
+  
+  // API error
+  const response = error.response;
+  const statusCode = response?.status;
+  const data = response?.data;
+  
+  const message = 
+    data?.error || 
+    data?.message || 
+    error.message || 
+    `API error (${statusCode})`;
+  
+  return new EcommerceApiError(message, statusCode, data);
+}
+
+/**
+ * Check if error is retryable
+ */
+export function isRetryableError(error: EcommerceApiError): boolean {
+  // Retry on network errors
+  if (error.isNetworkError) {
+    return true;
+  }
+  
+  // Retry on timeout
+  if (error.isTimeoutError) {
+    return true;
+  }
+  
+  // Retry on 5xx errors
+  if (error.statusCode && error.statusCode >= 500) {
+    return true;
+  }
+  
+  // Retry on 429 (rate limit)
+  if (error.statusCode === 429) {
+    return true;
+  }
+  
+  return false;
+}
+

package/lib/ecommerce/utils/helpers.ts

@@ -0,0 +1,131 @@
+/**
+ * Ecommerce API Helper Utilities
+ * 
+ * This module contains helper functions for the ecommerce API.
+ */
+
+/**
+ * Build query string from params object
+ */
+export function buildQueryString(params: Record<string, any>): string {
+  const searchParams = new URLSearchParams();
+  
+  Object.entries(params).forEach(([key, value]) => {
+    if (value !== undefined && value !== null) {
+      if (Array.isArray(value)) {
+        // Handle arrays (e.g., ids, tags)
+        searchParams.append(key, value.join(","));
+      } else {
+        searchParams.append(key, String(value));
+      }
+    }
+  });
+  
+  const queryString = searchParams.toString();
+  return queryString ? `?${queryString}` : "";
+}
+
+/**
+ * Sleep for specified milliseconds
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Calculate exponential backoff delay
+ */
+export function getBackoffDelay(attempt: number, baseDelay = 1000): number {
+  return Math.min(baseDelay * Math.pow(2, attempt), 30000);
+}
+
+/**
+ * Retry function with exponential backoff
+ */
+export async function retryWithBackoff<T>(
+  fn: () => Promise<T>,
+  maxRetries = 3,
+  baseDelay = 1000,
+  shouldRetry?: (error: any) => boolean
+): Promise<T> {
+  let lastError: any;
+  
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      
+      // Check if we should retry
+      if (attempt < maxRetries && (!shouldRetry || shouldRetry(error))) {
+        const delay = getBackoffDelay(attempt, baseDelay);
+        await sleep(delay);
+        continue;
+      }
+      
+      throw error;
+    }
+  }
+  
+  throw lastError;
+}
+
+/**
+ * Format price for display
+ */
+export function formatPrice(price: string | number, decimals = 2): string {
+  const num = typeof price === "string" ? parseFloat(price) : price;
+  return num.toFixed(decimals);
+}
+
+/**
+ * Validate email address
+ */
+export function isValidEmail(email: string): boolean {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return emailRegex.test(email);
+}
+
+/**
+ * Validate Ethereum address
+ */
+export function isValidAddress(address: string): boolean {
+  return /^0x[a-fA-F0-9]{40}$/.test(address);
+}
+
+/**
+ * Truncate address for display
+ */
+export function truncateAddress(address: string, start = 6, end = 4): string {
+  if (!address || address.length < start + end) {
+    return address;
+  }
+  return `${address.slice(0, start)}...${address.slice(-end)}`;
+}
+
+/**
+ * Calculate discount amount
+ */
+export function calculateDiscountAmount(
+  price: number,
+  discountType: "PERCENTAGE" | "FIXED_AMOUNT",
+  discountValue: number
+): number {
+  if (discountType === "PERCENTAGE") {
+    return (price * discountValue) / 100;
+  }
+  return Math.min(discountValue, price);
+}
+
+/**
+ * Calculate final price after discount
+ */
+export function calculateFinalPrice(
+  price: number,
+  discountType: "PERCENTAGE" | "FIXED_AMOUNT",
+  discountValue: number
+): number {
+  const discountAmount = calculateDiscountAmount(price, discountType, discountValue);
+  return Math.max(0, price - discountAmount);
+}
+

package/lib/hip3/market-info.ts

@@ -29,7 +29,7 @@ export interface PerpsUniverse {
   /** Indicates if the universe is delisted. */
   isDelisted?: true;
   /** Indicates if the universe is in growth mode, eligible for discounted fees */
-  growthMode?: true;
+  growthMode?: "enabled";
   /** Margin mode for the universe. */
   marginMode?: "strictIsolated" | "noCross";
 }

package/lib/instrument/client.ts

@@ -0,0 +1,351 @@
+import { SpotMeta, SpotToken } from "@nktkas/hyperliquid";
+import { AllPerpsMeta, PerpsMeta } from "../hip3/market-info";
+
+export interface BaseInstrument {
+  assetId: number;
+  symbol: string; // Display name (e.g., "BTC/USDC" for spot, "BTC" for perps)
+  coin: string; // Internal name used by Hyperliquid API (e.g., "@107" for spot, "BTC" for perps)
+  szDecimals: number; // Size decimals for formatting
+  type: "spot" | "futures";
+  isDelisted?: boolean;
+}
+
+// Futures-specific types (metadata only - no asset context data)
+export interface PerpsInstrument extends BaseInstrument {
+  type: "futures";
+  leverage: number;
+  collateralTokenSymbol: string;
+  dex?: string; // HIP3 dex name (e.g., "xyz" for "xyz:MSTR")
+  collateralTokenIndex?: number;
+}
+
+// Spot-specific types (metadata only - no asset context data)
+export interface SpotInstrument extends BaseInstrument {
+  type: "spot";
+  baseToken: SpotToken;
+  quoteToken: SpotToken;
+}
+
+export type MarketInstrument = PerpsInstrument | SpotInstrument;
+
+/**
+ * Asset ID calculation utilities
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/asset-ids
+ */
+export const AssetIdUtils = {
+  /**
+   * Calculate perp asset ID
+   * - Root dex: assetIndex (0, 1, 2, ...)
+   * - HIP3 dex: 100000 + dexIndex * 10000 + assetIndex
+   */
+  calcPerpAssetId(dexIndex: number, assetIndex: number): number {
+    if (dexIndex === 0) return assetIndex;
+    return 100000 + dexIndex * 10000 + assetIndex;
+  },
+
+  /**
+   * Calculate spot asset ID: 10000 + pairIndex
+   */
+  calcSpotAssetId(pairIndex: number): number {
+    return 10000 + pairIndex;
+  },
+
+  /**
+   * Check if symbol is HIP3 format (contains ":")
+   */
+  isHip3Symbol(symbol: string): boolean {
+    return symbol?.includes(":") ?? false;
+  },
+
+  /**
+   * Extract dex name from HIP3 symbol (e.g., "xyz:MSTR" -> "xyz")
+   */
+  extractDexName(symbol: string): string | undefined {
+    if (!this.isHip3Symbol(symbol)) return undefined;
+    return symbol.split(":")[0];
+  },
+};
+
+/**
+ * Hyperliquid Instrument Client
+ *
+ * Processes spotMeta and allPerpsMeta into a unified instrument registry
+ * with O(1) lookups by symbol, coin, or assetId.
+ *
+ * Usage:
+ * ```ts
+ * const client = new InstrumentClient(spotMeta, allPerpsMeta).init();
+ * const btc = client.getInstrument("BTC");
+ * const spot = client.getInstrumentByAssetId(10001);
+ * ```
+ */
+export class InstrumentClient {
+  private instruments: MarketInstrument[] = [];
+
+  // O(1) lookup maps for efficient retrieval
+  private instrumentsBySymbol = new Map<string, MarketInstrument>();
+  private instrumentsByCoin = new Map<string, MarketInstrument>();
+  private instrumentsByAssetId = new Map<number, MarketInstrument>();
+
+  // Additional spot lookups (base token -> instrument)
+  private spotByBaseToken = new Map<string, SpotInstrument>();
+
+  // Dex metadata map (dex name -> PerpsMeta)
+  // Key: "" for root dex, dex name for HIP3 (e.g., "xyz")
+  private dexMetaMap = new Map<string, PerpsMeta>();
+
+  // Token index lookup for spot
+  private spotTokensByIndex = new Map<number, SpotToken>();
+
+  constructor(
+    public spotMeta: SpotMeta,
+    public allPerpsMeta: AllPerpsMeta,
+  ) {}
+
+  /**
+   * Initialize the client by processing meta into instruments.
+   * Call this after construction to populate the instrument registry.
+   * @returns this for chaining
+   */
+  init(): this {
+    if (!this.spotMeta || !this.allPerpsMeta) {
+      throw new Error("SpotMeta and allPerpsMeta are required");
+    }
+    // Pre-index spot tokens for O(1) lookup
+    this.indexSpotTokens();
+
+    // Process instruments
+    this.processPerpsInstruments();
+    this.processSpotInstruments();
+
+    return this;
+  }
+
+  // ===== Perps Meta Accessors =====
+
+  getAllPerpsMeta(): AllPerpsMeta {
+    return this.allPerpsMeta;
+  }
+
+  /**
+   * Get PerpsMeta for a specific dex
+   * @param dex - Dex name ("" for root dex, or HIP3 dex name)
+   */
+  getPerpDex(dex: string): PerpsMeta | undefined {
+    return this.dexMetaMap.get(dex);
+  }
+
+  /**
+   * Get PerpsMeta by dex index in allPerpsMeta array
+   */
+  getPerpDexByIndex(index: number): PerpsMeta | undefined {
+    return this.allPerpsMeta[index];
+  }
+
+  // ===== Instrument Accessors =====
+
+  /**
+   * Get all instruments
+   */
+  getAllInstruments(): MarketInstrument[] {
+    return this.instruments;
+  }
+
+  /**
+   * Get all perps instruments
+   */
+  getPerpsInstruments(): PerpsInstrument[] {
+    return this.instruments.filter(
+      (i): i is PerpsInstrument => i.type === "futures",
+    );
+  }
+
+  getHip3Instruments(): PerpsInstrument[] {
+    return this.instruments.filter(
+      (i): i is PerpsInstrument => i.type === "futures" && !!i.dex,
+    );
+  }
+
+  /**
+   * Get all spot instruments
+   */
+  getSpotInstruments(): SpotInstrument[] {
+    return this.instruments.filter(
+      (i): i is SpotInstrument => i.type === "spot",
+    );
+  }
+
+  /**
+   * Get instrument by symbol or coin (tries both)
+   * @param coinOrSymbol - Symbol (e.g., "BTC", "BTC/USDC") or coin (e.g., "@107")
+   */
+  getInstrument(coinOrSymbol: string): MarketInstrument | undefined {
+    return (
+      this.instrumentsByCoin.get(coinOrSymbol) ??
+      this.instrumentsBySymbol.get(coinOrSymbol)
+    );
+  }
+
+  /**
+   * Get instrument by display symbol
+   * @param symbol - Display symbol (e.g., "BTC", "BTC/USDC", "xyz:MSTR")
+   */
+  getInstrumentBySymbol(symbol: string): MarketInstrument | undefined {
+    return this.instrumentsBySymbol.get(symbol);
+  }
+
+  /**
+   * Get instrument by Hyperliquid API coin format
+   * @param coin - API coin name (e.g., "BTC", "@107", "xyz:MSTR")
+   */
+  getInstrumentByCoin(coin: string): MarketInstrument | undefined {
+    return this.instrumentsByCoin.get(coin);
+  }
+
+  /**
+   * Get instrument by asset ID
+   * @param assetId - Numeric asset ID (e.g., 1 for perps, 10001 for spot)
+   */
+  getInstrumentByAssetId(assetId: number): MarketInstrument | undefined {
+    return this.instrumentsByAssetId.get(assetId);
+  }
+
+  /**
+   * Get spot instrument by base token symbol
+   * @param baseSymbol - Base token symbol (e.g., "HYPE" to find "HYPE/USDC")
+   */
+  getSpotInstrumentByBaseToken(baseSymbol: string): SpotInstrument | undefined {
+    return this.spotByBaseToken.get(baseSymbol);
+  }
+
+  /** Search instruments by symbol, coin, or assetId */
+  searchInstruments(
+    query: string,
+    type?: "spot" | "futures",
+  ): MarketInstrument[] {
+    return this.instruments.filter((i) => {
+      if (type && i.type !== type) return false;
+      return (
+        i.symbol.toLowerCase().includes(query.toLowerCase()) ||
+        i.coin.toLowerCase().includes(query.toLowerCase())
+      );
+    });
+  }
+
+  /**
+   * Get spot token by index
+   */
+  getSpotToken(index: number): SpotToken | undefined {
+    return this.spotTokensByIndex.get(index);
+  }
+
+  // ===== Internal Processing =====
+
+  private indexSpotTokens(): void {
+    for (const token of this.spotMeta.tokens) {
+      this.spotTokensByIndex.set(token.index, token);
+    }
+  }
+
+  private processPerpsInstruments(): void {
+    for (let dexIndex = 0; dexIndex < this.allPerpsMeta.length; dexIndex++) {
+      const perpMeta = this.allPerpsMeta[dexIndex];
+      const dexName = this.extractDexNameFromMeta(perpMeta, dexIndex);
+
+      // Store dex meta for later lookup
+      this.dexMetaMap.set(dexName, perpMeta);
+
+      // Get collateral token symbol for this dex
+      const collateralToken = this.spotTokensByIndex.get(
+        perpMeta.collateralToken,
+      );
+      const collateralTokenSymbol = collateralToken?.name ?? "USDC";
+
+      for (
+        let assetIndex = 0;
+        assetIndex < perpMeta.universe.length;
+        assetIndex++
+      ) {
+        const info = perpMeta.universe[assetIndex];
+        const assetId = AssetIdUtils.calcPerpAssetId(dexIndex, assetIndex);
+
+        const instrument: PerpsInstrument = {
+          assetId,
+          symbol: info.name,
+          coin: info.name,
+          szDecimals: info.szDecimals,
+          leverage: info.maxLeverage,
+          collateralTokenSymbol,
+          type: "futures",
+          isDelisted: info.isDelisted,
+          dex: AssetIdUtils.extractDexName(info.name),
+          collateralTokenIndex: perpMeta.collateralToken,
+        };
+
+        this.addInstrument(instrument);
+      }
+    }
+  }
+
+  private processSpotInstruments(): void {
+    const seenSymbols = new Set<string>();
+
+    for (const pair of this.spotMeta.universe) {
+      const [baseTokenIndex, quoteTokenIndex] = pair.tokens;
+
+      // O(1) token lookup using pre-indexed map
+      const baseToken = this.spotTokensByIndex.get(baseTokenIndex);
+      const quoteToken = this.spotTokensByIndex.get(quoteTokenIndex);
+
+      if (!baseToken || !quoteToken) continue;
+
+      const symbol = `${baseToken.name}/${quoteToken.name}`;
+
+      // Skip duplicate display symbols
+      if (seenSymbols.has(symbol)) continue;
+      seenSymbols.add(symbol);
+
+      const assetId = AssetIdUtils.calcSpotAssetId(pair.index);
+
+      const instrument: SpotInstrument = {
+        assetId,
+        symbol,
+        coin: pair.name, // e.g., "@107"
+        szDecimals: baseToken.szDecimals,
+        type: "spot",
+        baseToken,
+        quoteToken,
+      };
+
+      this.addInstrument(instrument);
+
+      // Index by base token for convenience lookups (first occurrence wins)
+      if (!this.spotByBaseToken.has(baseToken.name)) {
+        this.spotByBaseToken.set(baseToken.name, instrument);
+      }
+    }
+  }
+
+  private addInstrument(instrument: MarketInstrument): void {
+    this.instruments.push(instrument);
+    this.instrumentsBySymbol.set(instrument.symbol, instrument);
+    this.instrumentsByCoin.set(instrument.coin, instrument);
+    this.instrumentsByAssetId.set(instrument.assetId, instrument);
+  }
+
+  /**
+   * Extract dex name from PerpsMeta
+   * Root dex (index 0) returns "", HIP3 dexes return the dex name (e.g., "xyz")
+   */
+  private extractDexNameFromMeta(
+    perpMeta: PerpsMeta,
+    dexIndex: number,
+  ): string {
+    if (dexIndex === 0) return ""; // Root dex
+
+    const firstAsset = perpMeta.universe[0];
+    if (!firstAsset) return "";
+
+    return AssetIdUtils.extractDexName(firstAsset.name) ?? "";
+  }
+}

package/lib/meta/data/mainnet/perpDexs.json

@@ -73,7 +73,8 @@
       ]
     ],
     "deployerFeeScale": "1.0",
-    "lastDeployerFeeScaleChangeTime": "1970-01-01T00:00:00"
+    "lastDeployerFeeScaleChangeTime": "1970-01-01T00:00:00",
+    "assetToFundingMultiplier": []
   },
   {
     "name": "flx",
@@ -167,7 +168,21 @@
       ]
     ],
     "deployerFeeScale": "1.0",
-    "lastDeployerFeeScaleChangeTime": "1970-01-01T00:00:00"
+    "lastDeployerFeeScaleChangeTime": "1970-01-01T00:00:00",
+    "assetToFundingMultiplier": [
+      [
+        "flx:COIN",
+        "0.0396816138"
+      ],
+      [
+        "flx:CRCL",
+        "0.6849327969"
+      ],
+      [
+        "flx:TSLA",
+        "0.055534957"
+      ]
+    ]
   },
   {
     "name": "vntl",
@@ -217,7 +232,21 @@
       ]
     ],
     "deployerFeeScale": "1.0",
-    "lastDeployerFeeScaleChangeTime": "1970-01-01T00:00:00"
+    "lastDeployerFeeScaleChangeTime": "1970-01-01T00:00:00",
+    "assetToFundingMultiplier": [
+      [
+        "vntl:ANTHROPIC",
+        "0.0053054031"
+      ],
+      [
+        "vntl:OPENAI",
+        "0.0050794237"
+      ],
+      [
+        "vntl:SPACEX",
+        "0.010663783"
+      ]
+    ]
   },
   {
     "name": "hyna",
@@ -248,6 +277,7 @@
       ]
     ],
     "deployerFeeScale": "1.0",
-    "lastDeployerFeeScaleChangeTime": "2025-12-03T10:32:09.252520621"
+    "lastDeployerFeeScaleChangeTime": "2025-12-03T10:32:09.252520621",
+    "assetToFundingMultiplier": []
   }
 ]