@basedone/core 0.0.6 → 0.0.8

package/lib/meta/metadata.ts

@@ -1,13 +1,27 @@
 import {
   HttpTransport,
   InfoClient,
-  PerpDex,
   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
@@ -19,6 +33,9 @@ export interface MarketInfo {
   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
@@ -28,6 +45,8 @@ export interface MarketInfo {
   // 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 {
@@ -37,6 +56,9 @@ export interface DexInfo {
   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
+  accountName?: string; // Account name override for the DEX
 }
 
 export type ExtendedPerpsMeta = PerpsMeta & {
@@ -54,6 +76,25 @@ export interface TokenInfo {
   tokenId: string;
 }
 
+/**
+ * Static metadata structure for display overrides
+ */
+interface StaticMetadata {
+  coins?: {
+    [symbol: string]: {
+      displayName?: string;
+      imageUrl?: string;
+    };
+  };
+  dexs?: {
+    [dexName: string]: {
+      displayName?: string;
+      imageUrl?: string;
+      accountName?: string;
+    };
+  };
+}
+
 /**
  * Configuration for MetadataClient
  */
@@ -84,6 +125,8 @@ interface MetadataClientConfig {
  * - 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;
@@ -93,6 +136,7 @@ export class MetadataClient {
   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();
@@ -116,6 +160,7 @@ export class MetadataClient {
 
   // Lazy init flag
   private initialized: boolean = false;
+  private initializing: Promise<void> | null = null;
 
   constructor(config: MetadataClientConfig = {}) {
     const transport = new HttpTransport({
@@ -124,6 +169,7 @@ export class MetadataClient {
     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;
@@ -135,54 +181,82 @@ export class MetadataClient {
    */
   async initialize(): Promise<void> {
     if (this.initialized) return;
+    if (this.initializing) return this.initializing;
+    this.initializing = new Promise(async (resolve, reject) => {
+      // Always load staticMeta.json regardless of config.useStaticFallback
+      await this.loadStaticMetaOverrides();
 
-    if (this.config.onlyUseStaticFallback) {
-      await this.loadStaticMetadata();
-      this.buildLookupMaps();
+      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)),
-        );
+        // 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)),
+          );
+        }
+        resolve();
+        this.initialized = true;
+        return;
       }
 
-      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(),
-      ]);
+      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();
+        // 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)),
-        );
+        // 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;
+        resolve();
+      } 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;
+          resolve();
+        } else {
+          reject(error);
+        }
+      } finally {
+        this.initialized = true;
+        resolve();
       }
+    });
+    return this.initializing;
+  }
 
-      this.initialized = true;
+  /**
+   * 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) {
-      // 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;
-      }
+      console.warn(`Failed to load staticMeta.json for ${network}:`, error);
+      this.staticMeta = null;
     }
   }
 
@@ -194,16 +268,22 @@ export class MetadataClient {
 
     try {
       // Dynamic imports for static data
-      const [spotMetaModule, perpsMetaModule, perpDexsModule] =
-        await Promise.all([
-          import(`./data/${network}/spotMeta.json`),
-          import(`./data/${network}/meta.json`),
-          import(`./data/${network}/perpDexs.json`),
-        ]);
+      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) {
@@ -223,10 +303,16 @@ export class MetadataClient {
     this.spotPairToMarket.clear();
     this.baseTokenToMarkets.clear();
     this.coinToMarket.clear();
-    this.hip3SymbolToMarket.clear();
     this.dexNameToIndex.clear();
     this.quoteAssets = [];
 
+    console.info(
+      "[MetadataClient] Building lookup maps",
+      this.perpDexs,
+      this.perpsMeta,
+      this.spotMeta,
+    );
+
     // Build dex name to index map
     if (this.perpDexs) {
       this.perpDexs.forEach((dex, index) => {
@@ -248,6 +334,17 @@ export class MetadataClient {
           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);
 
@@ -288,6 +385,17 @@ export class MetadataClient {
           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);
@@ -347,15 +455,29 @@ export class MetadataClient {
       const collateralTokenSymbol =
         spotMetaTokens?.[collateralTokenIndex]?.name ?? "USDC";
 
-      const dexInfo = {
+      const dexInfo: DexInfo = {
         meta,
         assetContext: contexts,
         collateralTokenSymbol,
-        dexFullName: dex?.full_name ?? dexName,
+        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;
+        }
+        if (staticDexOverrides.accountName) {
+          dexInfo.accountName = staticDexOverrides.accountName;
+        }
+      }
+
       this.hip3DexsMeta.set(dexName, dexInfo);
 
       // Build HIP-3 market lookups for this DEX
@@ -374,6 +496,7 @@ export class MetadataClient {
   private buildHip3MarketsForDex(dexName: string, dexInfo: DexInfo): void {
     dexInfo.meta.universe.forEach((market, index) => {
       const symbol = market.name;
+
       const marketInfo: MarketInfo = {
         coin: symbol,
         symbol,
@@ -383,8 +506,23 @@ export class MetadataClient {
         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;
+        }
+      }
+
+      console.info("[MetadataClient] caching market", symbol, marketInfo);
+
       this.coinToMarket.set(symbol, marketInfo);
       this.hip3SymbolToMarket.set(symbol, marketInfo);
     });
@@ -425,7 +563,7 @@ export class MetadataClient {
     // 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(lookupKey);
+      const perpsMarket = this.coinToMarket.get(symbol);
       if (perpsMarket?.type === "perps") {
         return perpsMarket;
       }
@@ -507,6 +645,7 @@ export class MetadataClient {
     // Try O(1) lookup first (if DEX metadata already loaded)
     let cachedMarket = this.hip3SymbolToMarket.get(symbol);
     if (cachedMarket) return cachedMarket;
+    console.warn("Missing market", symbol, this.hip3SymbolToMarket);
 
     // If not found, check if we need to load DEX metadata
     const dexMeta = this.hip3DexsMeta.get(dexName);
@@ -584,6 +723,8 @@ export class MetadataClient {
       perpsMeta: this.perpsMeta,
       perpDexs: this.perpDexs,
       hip3DexsMeta: Object.fromEntries(this.hip3DexsMeta),
+      coinToMarket: Object.fromEntries(this.coinToMarket),
+      hip3SymbolToMarket: Object.fromEntries(this.hip3SymbolToMarket),
     };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basedone/core",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Core utilities for Based One",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",