@basedone/core 0.0.1 → 0.0.7

package/lib/meta/metadata.ts

@@ -0,0 +1,717 @@
+import {
+  HttpTransport,
+  InfoClient,
+  PerpsAssetCtx,
+  PerpsMeta,
+  SpotMeta,
+  SpotToken,
+} from "@nktkas/hyperliquid";
+import { isHip3Symbol } from "../hip3/utils";
+import { Hex } from "@nktkas/hyperliquid/script/src/types/mod";
+
+export interface PerpDex {
+  /** Short name of the perpetual dex. */
+  name: string;
+  /** Complete name of the perpetual dex. */
+  fullName: string;
+  /** Hex address of the dex deployer. */
+  deployer: Hex;
+  /** Hex address of the oracle updater, or null if not available. */
+  oracleUpdater: Hex | null;
+
+  feeRecipient: Hex | null;
+  assetToStreamingOiCap: [string, string][];
+}
+
+/**
+ * Market information for trading operations
+ */
+export interface MarketInfo {
+  symbol: string; // Human-readable symbol (e.g., "BTC", "PURR/USDC")
+  assetId: number; // Trading asset ID (perps: index, spot: 10000+index, hip3: 100000+dex*10000+index)
+  szDecimals: number; // Size decimals for order amounts
+  type: "perps" | "spot" | "hip3";
+  coin: string; // Format used in info endpoint (e.g., "@107") for spot hype, "HYPE" for perps, "dex:coin" for hip3
+
+  displayName?: string; // Display name for the market
+  imageUrl?: string; // Image URL for the market
+
+  maxLeverage?: number; // For perps only
+
+  // Spot-specific fields
+  baseToken?: SpotToken; // Base token symbol (e.g., "PURR")
+  quoteToken?: SpotToken; // Quote token symbol (e.g., "USDC")
+
+  // HIP-3 specific fields
+  dexName?: string; // DEX name for HIP-3 markets
+  dexIndex?: number; // DEX index for asset ID calculation
+  dexDisplayName?: string; // Display name override for the DEX
+  dexImageUrl?: string; // Image URL override for the DEX
+}
+
+export interface DexInfo {
+  meta: PerpsMeta;
+  assetContext: PerpsAssetCtx[];
+  dexFullName: string; // DEX full name for HIP-3 markets
+  dexName: string; // DEX name for HIP-3 markets
+  dexIndex: number; // DEX index for asset ID calculation
+  collateralTokenSymbol: string;
+  displayName?: string; // Display name override for the DEX
+  imageUrl?: string; // Image URL override for the DEX
+}
+
+export type ExtendedPerpsMeta = PerpsMeta & {
+  collateralToken?: number; // spot token index
+};
+
+/**
+ * Spot token information
+ */
+export interface TokenInfo {
+  name: string;
+  index: number;
+  szDecimals: number;
+  weiDecimals: number;
+  tokenId: string;
+}
+
+/**
+ * Static metadata structure for display overrides
+ */
+interface StaticMetadata {
+  coins?: {
+    [symbol: string]: {
+      displayName?: string;
+      imageUrl?: string;
+    };
+  };
+  dexs?: {
+    [dexName: string]: {
+      displayName?: string;
+      imageUrl?: string;
+    };
+  };
+}
+
+/**
+ * Configuration for MetadataClient
+ */
+interface MetadataClientConfig {
+  /** List of HIP-3 DEX names to load metadata for */
+  hip3Dexs?: string[];
+  /** Whether to lazily initialize (fetch metadata on first use) */
+  lazyInit?: boolean;
+  /** Whether to use testnet (default: false for mainnet) */
+  isTestnet?: boolean;
+  /** Use static fallback data only, no API fetch */
+  onlyUseStaticFallback?: boolean;
+  /** Whether to use static fallback data if API fetch fails (default: true) */
+  useStaticFallback?: boolean;
+}
+
+/**
+ * MetadataClient - Handles Hyperliquid metadata for trading operations
+ *
+ * Provides a clean interface to:
+ * - Convert symbols to asset IDs and decimals
+ * - Handle spot markets with multiple quote assets (USDC, USDT0, USDH)
+ * - Support perpetuals and HIP-3 deployed DEXs
+ * - Calculate correct asset IDs per Hyperliquid spec
+ *
+ * Asset ID Calculation:
+ * - Perps: index in meta universe
+ * - Spot: 10000 + index
+ * - HIP-3: 100000 + perp_dex_index * 10000 + index_in_meta
+ */
+export const ROOT_DEX = "hyperliquid";
+
+export class MetadataClient {
+  private infoClient: InfoClient;
+  private config: MetadataClientConfig;
+  private isTestnet: boolean;
+
+  // Core metadata
+  private spotMeta: SpotMeta | null = null;
+  private perpsMeta: PerpsMeta | null = null;
+  private perpDexs: (PerpDex | null)[] = [];
+  private staticMeta: StaticMetadata | null = null;
+
+  // HIP-3 metadata cache
+  private hip3DexsMeta: Map<string, DexInfo> = new Map();
+
+  // Pre-computed lookup maps (populated on initialize)
+  private perpsSymbolToIndex: Map<string, number> = new Map();
+  private spotTokenNameToIndex: Map<string, number> = new Map();
+  private spotPairToMarket: Map<string, MarketInfo> = new Map();
+  private baseTokenToMarkets: Map<string, MarketInfo[]> = new Map();
+  private quoteAssets: string[] = [];
+
+  // Unified symbol lookup (used by getMarketBySymbol for O(1) access)
+  // Maps symbol to MarketInfo for quick lookups
+  private coinToMarket: Map<string, MarketInfo> = new Map();
+
+  // HIP-3 optimized lookups
+  // Maps "dex:coin" symbol to MarketInfo
+  private hip3SymbolToMarket: Map<string, MarketInfo> = new Map();
+  // Maps dex name to dex index for quick lookups
+  private dexNameToIndex: Map<string, number> = new Map();
+
+  // Lazy init flag
+  private initialized: boolean = false;
+
+  constructor(config: MetadataClientConfig = {}) {
+    const transport = new HttpTransport({
+      isTestnet: config.isTestnet ?? false,
+    });
+    this.infoClient = new InfoClient({ transport });
+    this.config = {
+      ...config,
+      hip3Dexs: config.hip3Dexs?.filter((dex) => dex !== ROOT_DEX),
+      useStaticFallback: config.useStaticFallback ?? true,
+    };
+    this.isTestnet = config.isTestnet ?? false;
+    this.initialize();
+  }
+
+  /**
+   * Initialize metadata by fetching from Hyperliquid
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+
+    // Always load staticMeta.json regardless of config.useStaticFallback
+    await this.loadStaticMetaOverrides();
+
+    if (this.config.onlyUseStaticFallback) {
+      await this.loadStaticMetadata();
+      this.buildLookupMaps();
+
+      // Fetch HIP-3 metadata if configured
+      if (this.config.hip3Dexs && this.config.hip3Dexs.length > 0) {
+        await Promise.all(
+          this.config.hip3Dexs.map((dex) => this.loadHip3Metadata(dex)),
+        );
+      }
+
+      this.initialized = true;
+      return;
+    }
+
+    try {
+      // Fetch core metadata from API
+      [this.spotMeta, this.perpsMeta, this.perpDexs] = await Promise.all([
+        this.infoClient.spotMeta(),
+        this.infoClient.meta(),
+        this.infoClient.perpDexs() as Promise<PerpDex[] | null[]>,
+      ]);
+
+      // Build optimized lookup maps
+      this.buildLookupMaps();
+
+      // Fetch HIP-3 metadata if configured
+      if (this.config.hip3Dexs && this.config.hip3Dexs.length > 0) {
+        await Promise.all(
+          this.config.hip3Dexs.map((dex) => this.loadHip3Metadata(dex)),
+        );
+      }
+
+      this.initialized = true;
+    } catch (error) {
+      // Fall back to static data if API fetch fails and fallback is enabled
+      if (this.config.useStaticFallback) {
+        console.warn(
+          "Failed to fetch metadata from API, using static fallback data",
+          error,
+        );
+        await this.loadStaticMetadata();
+        this.buildLookupMaps();
+        this.initialized = true;
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * Load staticMeta.json for display overrides
+   * This is always loaded regardless of config.useStaticFallback
+   */
+  private async loadStaticMetaOverrides(): Promise<void> {
+    const network = this.isTestnet ? "testnet" : "mainnet";
+
+    try {
+      const staticMetaModule = await import(
+        `./data/${network}/staticMeta.json`
+      );
+      this.staticMeta = staticMetaModule.default as StaticMetadata;
+    } catch (error) {
+      console.warn(`Failed to load staticMeta.json for ${network}:`, error);
+      this.staticMeta = null;
+    }
+  }
+
+  /**
+   * Load static metadata from bundled JSON files
+   */
+  private async loadStaticMetadata(): Promise<void> {
+    const network = this.isTestnet ? "testnet" : "mainnet";
+
+    try {
+      // Dynamic imports for static data
+      const [
+        spotMetaModule,
+        perpsMetaModule,
+        perpDexsModule,
+        staticMetaModule,
+      ] = await Promise.all([
+        import(`./data/${network}/spotMeta.json`),
+        import(`./data/${network}/meta.json`),
+        import(`./data/${network}/perpDexs.json`),
+        import(`./data/${network}/staticMeta.json`),
+      ]);
+
+      this.spotMeta = spotMetaModule.default as SpotMeta;
+      this.perpsMeta = perpsMetaModule.default as PerpsMeta;
+      this.perpDexs = perpDexsModule.default as (PerpDex | null)[];
+      this.staticMeta = staticMetaModule.default as StaticMetadata;
+
+      console.warn(`Using static ${network} metadata`);
+    } catch (error) {
+      console.error(`Failed to load static ${network} metadata:`, error);
+      throw new Error(`Could not load metadata for ${network}`);
+    }
+  }
+
+  /**
+   * Build optimized lookup maps from raw metadata
+   * Called after metadata is loaded (from API or static files)
+   */
+  private buildLookupMaps(): void {
+    // Clear existing maps
+    this.perpsSymbolToIndex.clear();
+    this.spotTokenNameToIndex.clear();
+    this.spotPairToMarket.clear();
+    this.baseTokenToMarkets.clear();
+    this.coinToMarket.clear();
+    this.hip3SymbolToMarket.clear();
+    this.dexNameToIndex.clear();
+    this.quoteAssets = [];
+
+    // Build dex name to index map
+    if (this.perpDexs) {
+      this.perpDexs.forEach((dex, index) => {
+        if (dex && dex.name) {
+          this.dexNameToIndex.set(dex.name.toLowerCase(), index);
+        }
+      });
+    }
+
+    // Build perps symbol to index map
+    if (this.perpsMeta) {
+      this.perpsMeta.universe.forEach((market, index) => {
+        const marketInfo: MarketInfo = {
+          symbol: market.name,
+          coin: market.name,
+          assetId: index,
+          szDecimals: market.szDecimals,
+          type: "perps",
+          maxLeverage: market.maxLeverage,
+        };
+
+        // Apply static metadata overrides for perps
+        const staticOverrides = this.staticMeta?.coins?.[market.name];
+        if (staticOverrides) {
+          if (staticOverrides.displayName) {
+            marketInfo.displayName = staticOverrides.displayName;
+          }
+          if (staticOverrides.imageUrl) {
+            marketInfo.imageUrl = staticOverrides.imageUrl;
+          }
+        }
+
+        // Case-insensitive lookup
+        this.perpsSymbolToIndex.set(market.name.toUpperCase(), index);
+
+        // Add to unified symbol lookup
+        this.coinToMarket.set(market.name, marketInfo);
+      });
+    }
+
+    // Build spot token name to index map and collect quote assets
+    if (this.spotMeta) {
+      this.spotMeta.tokens.forEach((token) => {
+        // Case-insensitive lookup
+        this.spotTokenNameToIndex.set(token.name.toUpperCase(), token.index);
+      });
+
+      // Track unique quote assets
+      const quoteIndices = new Set<number>();
+
+      // Build spot pair to market map and base token to markets map
+      this.spotMeta.universe.forEach((universe) => {
+        const baseToken = this.spotMeta!.tokens[universe.tokens[0]];
+        const quoteToken = this.spotMeta!.tokens[universe.tokens[1]];
+
+        if (!baseToken || !quoteToken) return;
+
+        const coin = universe.name;
+
+        // Track quote asset
+        quoteIndices.add(quoteToken.index);
+
+        const marketInfo: MarketInfo = {
+          coin,
+          symbol: `${baseToken.name}/${quoteToken.name}`,
+          assetId: 10000 + universe.index,
+          szDecimals: baseToken.szDecimals,
+          type: "spot",
+          baseToken: baseToken,
+          quoteToken: quoteToken,
+        };
+
+        // Apply static metadata overrides for spot
+        const staticOverrides = this.staticMeta?.coins?.[coin];
+        if (staticOverrides) {
+          if (staticOverrides.displayName) {
+            marketInfo.displayName = staticOverrides.displayName;
+          }
+          if (staticOverrides.imageUrl) {
+            marketInfo.imageUrl = staticOverrides.imageUrl;
+          }
+        }
+
+        // Store by full pair (case-insensitive)
+        const pairKey = `${baseToken.name}/${quoteToken.name}`.toUpperCase();
+        this.spotPairToMarket.set(pairKey, marketInfo);
+
+        // Add to unified symbol lookup
+        this.coinToMarket.set(pairKey, marketInfo);
+
+        this.coinToMarket.set(coin, marketInfo);
+
+        // Group by base token (case-insensitive)
+        const baseKey = baseToken.name.toUpperCase();
+        const existing = this.baseTokenToMarkets.get(baseKey) || [];
+        existing.push(marketInfo);
+        this.baseTokenToMarkets.set(baseKey, existing);
+      });
+
+      // Pre-compute sorted quote assets list
+      this.quoteAssets = Array.from(quoteIndices)
+        .map((idx) => this.spotMeta!.tokens[idx].name)
+        .sort();
+    }
+  }
+
+  /**
+   * Load metadata for a specific HIP-3 DEX
+   * Also builds optimized lookups for this DEX's markets
+   */
+  async loadHip3Metadata(dexName: string): Promise<DexInfo> {
+    if (this.hip3DexsMeta.has(dexName)) return this.hip3DexsMeta.get(dexName)!;
+
+    try {
+      const [meta, contexts] = await this.infoClient.metaAndAssetCtxs({
+        dex: dexName,
+      });
+
+      // O(1) lookup using pre-computed map
+      let dexIndex = this.dexNameToIndex.get(dexName.toLowerCase());
+
+      // Fallback to array search if not in map (shouldn't happen after initialization)
+      if (dexIndex === undefined) {
+        dexIndex = this.perpDexs.findIndex(
+          (d) => d && d.name.toLowerCase() === dexName.toLowerCase(),
+        );
+      }
+
+      if (dexIndex === -1 || dexIndex === undefined) {
+        throw new Error(`DEX ${dexName} not found`);
+      }
+
+      const dex = this.perpDexs[dexIndex!];
+
+      const collateralTokenIndex =
+        (meta as ExtendedPerpsMeta).collateralToken ?? 0;
+
+      const spotMetaTokens = this.spotMeta?.tokens;
+
+      const collateralTokenSymbol =
+        spotMetaTokens?.[collateralTokenIndex]?.name ?? "USDC";
+
+      const dexInfo: DexInfo = {
+        meta,
+        assetContext: contexts,
+        collateralTokenSymbol,
+        dexFullName: dex?.fullName ?? dexName,
+        dexName: dex?.name ?? dexName,
+        dexIndex: dexIndex,
+      };
+
+      // Apply static metadata overrides for DEX
+      const staticDexOverrides = this.staticMeta?.dexs?.[dexName];
+      if (staticDexOverrides) {
+        if (staticDexOverrides.displayName) {
+          dexInfo.displayName = staticDexOverrides.displayName;
+        }
+        if (staticDexOverrides.imageUrl) {
+          dexInfo.imageUrl = staticDexOverrides.imageUrl;
+        }
+      }
+
+      this.hip3DexsMeta.set(dexName, dexInfo);
+
+      // Build HIP-3 market lookups for this DEX
+      this.buildHip3MarketsForDex(dexName, dexInfo);
+
+      return dexInfo;
+    } catch (error) {
+      console.error(`Failed to load HIP-3 metadata for ${dexName}:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Build optimized lookups for HIP-3 markets of a specific DEX
+   */
+  private buildHip3MarketsForDex(dexName: string, dexInfo: DexInfo): void {
+    dexInfo.meta.universe.forEach((market, index) => {
+      const symbol = market.name;
+
+      const marketInfo: MarketInfo = {
+        coin: symbol,
+        symbol,
+        assetId: 100000 + dexInfo.dexIndex * 10000 + index,
+        szDecimals: market.szDecimals,
+        type: "hip3",
+        maxLeverage: market.maxLeverage,
+        dexName,
+        dexIndex: dexInfo.dexIndex,
+        dexDisplayName: dexInfo.displayName,
+        dexImageUrl: dexInfo.imageUrl,
+      };
+
+      // Apply static metadata overrides for HIP-3
+      const staticOverrides = this.staticMeta?.coins?.[symbol];
+      if (staticOverrides) {
+        if (staticOverrides.displayName) {
+          marketInfo.displayName = staticOverrides.displayName;
+        }
+        if (staticOverrides.imageUrl) {
+          marketInfo.imageUrl = staticOverrides.imageUrl;
+        }
+      }
+
+      this.coinToMarket.set(symbol, marketInfo);
+      this.hip3SymbolToMarket.set(symbol, marketInfo);
+    });
+  }
+
+  /**
+   * Ensure metadata is loaded (for lazy init)
+   */
+  private async ensureInitialized(): Promise<void> {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+  }
+
+  /**
+   * Get market information by symbol
+   * Optimized: O(1) direct map lookup for most cases
+   * Lazily initialize hip-3 metadata if not already initialized
+   *
+   * @param symbol - Market symbol (e.g., "BTC", "PURR/USDC", "vntls:ABC")
+   * @param quoteAsset - Quote asset for spot markets (default: "USDC")
+   * @returns Market information or null if not found
+   */
+  async getMarketBySymbolAsync(
+    symbol: string,
+    quoteAsset: string = "USDC",
+  ): Promise<MarketInfo | null> {
+    await this.ensureInitialized();
+
+    // Check if HIP-3 market (format: "dex:coin")
+    if (symbol.includes(":")) {
+      return this.getHip3Market(symbol);
+    }
+
+    // Try O(1) direct lookup first
+    let lookupKey = symbol.toUpperCase();
+
+    // If no "/" in symbol, it could be perps or need quote asset
+    if (!symbol.includes("/") && !symbol.includes("@")) {
+      // Try perps lookup first (O(1))
+      const perpsMarket = this.coinToMarket.get(symbol);
+      if (perpsMarket?.type === "perps") {
+        return perpsMarket;
+      }
+
+      // Construct spot pair with quote asset
+      lookupKey = `${symbol}/${quoteAsset}`.toUpperCase();
+    }
+
+    // O(1) lookup in unified map
+    return this.coinToMarket.get(lookupKey) || null;
+  }
+
+  getMarketByCoin(coin: string): MarketInfo | null {
+    return this.coinToMarket.get(coin) || null;
+  }
+
+  /**
+   * Get perpetuals market information
+   * Optimized: O(1) map lookup instead of O(n) array search
+   */
+  getPerpsMarket(symbol: string): MarketInfo | null {
+    if (!this.perpsMeta) return null;
+
+    if (isHip3Symbol(symbol)) {
+      const [dexName, coinName] = symbol.split(":");
+      if (!dexName || !coinName) return null;
+
+      // Try O(1) lookup first (if DEX metadata already loaded)
+      let cachedMarket = this.hip3SymbolToMarket.get(symbol);
+      return cachedMarket || null;
+    }
+
+    // O(1) lookup using pre-computed map
+    const index = this.perpsSymbolToIndex.get(symbol.toUpperCase());
+    if (index === undefined) return null;
+
+    const market = this.perpsMeta.universe[index];
+
+    return {
+      coin: symbol,
+      symbol: market.name,
+      assetId: index, // Perps asset ID is just the index
+      szDecimals: market.szDecimals,
+      type: "perps",
+      maxLeverage: market.maxLeverage,
+    };
+  }
+
+  /**
+   * Get spot market information
+   * Optimized: O(1) map lookup instead of O(n) array searches
+   *
+   * @param baseSymbol - Base token symbol (e.g., "PURR", "UHYPE")
+   * @param quoteSymbol - Quote token symbol (default: "USDC")
+   */
+  getSpotMarket(
+    baseSymbol: string,
+    quoteSymbol: string = "USDC",
+  ): MarketInfo | null {
+    if (!this.spotMeta) return null;
+
+    // O(1) lookup using pre-computed map
+    const pairKey = `${baseSymbol}/${quoteSymbol}`.toUpperCase();
+    const market = this.spotPairToMarket.get(pairKey);
+
+    return market || null;
+  }
+
+  /**
+   * Get HIP-3 market information
+   * Optimized: O(1) map lookup after DEX metadata is loaded
+   *
+   * @param symbol - HIP-3 market symbol (format: "dex:coin")
+   */
+  async getHip3Market(symbol: string): Promise<MarketInfo | null> {
+    const [dexName, coinName] = symbol.split(":");
+    if (!dexName || !coinName) return null;
+
+    // Try O(1) lookup first (if DEX metadata already loaded)
+    let cachedMarket = this.hip3SymbolToMarket.get(symbol);
+    if (cachedMarket) return cachedMarket;
+
+    // If not found, check if we need to load DEX metadata
+    const dexMeta = this.hip3DexsMeta.get(dexName);
+    if (!dexMeta && this.config.lazyInit) {
+      // Load and build lookups for this DEX
+      await this.loadHip3Metadata(dexName);
+      // Try lookup again after loading
+      cachedMarket = this.hip3SymbolToMarket.get(symbol);
+      return cachedMarket || null;
+    }
+
+    // If DEX is loaded but symbol not found in map, return null
+    return null;
+  }
+
+  async getHip3Dex(dexName: string): Promise<DexInfo | null> {
+    await this.ensureInitialized();
+    let dexInfo = this.hip3DexsMeta.get(dexName) ?? null;
+    if (this.config.lazyInit && !dexInfo) {
+      dexInfo = await this.loadHip3Metadata(dexName);
+    }
+
+    return dexInfo;
+  }
+
+  /**
+   * Get all available markets for a base token
+   * Optimized: O(1) map lookup instead of O(n) filter + map
+   * Useful for showing all quote asset options
+   */
+  getAllMarketsForBase(baseSymbol: string): MarketInfo[] {
+    if (!this.spotMeta) return [];
+
+    // O(1) lookup using pre-computed map
+    const baseKey = baseSymbol.toUpperCase();
+    return this.baseTokenToMarkets.get(baseKey) || [];
+  }
+
+  /**
+   * Get spot token information
+   * Optimized: O(1) map lookup instead of O(n) array search
+   */
+  getSpotTokenInfo(tokenSymbol: string): TokenInfo | null {
+    if (!this.spotMeta) return null;
+
+    // O(1) lookup using pre-computed map
+    const tokenIndex = this.spotTokenNameToIndex.get(tokenSymbol.toUpperCase());
+    if (tokenIndex === undefined) return null;
+
+    const token = this.spotMeta.tokens[tokenIndex];
+
+    return {
+      name: token.name,
+      index: token.index,
+      szDecimals: token.szDecimals,
+      weiDecimals: token.weiDecimals,
+      tokenId: token.tokenId,
+    };
+  }
+
+  /**
+   * Get all available quote assets
+   * Optimized: O(1) pre-computed array instead of O(n) computation
+   */
+  getAvailableQuoteAssets(): string[] {
+    return this.quoteAssets;
+  }
+
+  /**
+   * Get raw metadata (for advanced use cases)
+   */
+  getRawMetadata() {
+    return {
+      spotMeta: this.spotMeta,
+      perpsMeta: this.perpsMeta,
+      perpDexs: this.perpDexs,
+      hip3DexsMeta: Object.fromEntries(this.hip3DexsMeta),
+    };
+  }
+
+  /**
+   * Get network configuration
+   */
+  getNetworkInfo() {
+    return {
+      isTestnet: this.isTestnet,
+      useStaticFallback: this.config.useStaticFallback,
+      initialized: this.initialized,
+    };
+  }
+}