@basedone/core 0.1.8 → 0.2.0

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/meta.json

@@ -1346,10 +1346,8 @@
     {
       "szDecimals": 0,
       "name": "MON",
-      "maxLeverage": 3,
-      "marginTableId": 3,
-      "onlyIsolated": true,
-      "marginMode": "strictIsolated"
+      "maxLeverage": 5,
+      "marginTableId": 5
     },
     {
       "szDecimals": 0,

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

@@ -5,7 +5,7 @@
     "fullName": "XYZ",
     "deployer": "0x88806a71d74ad0a510b350545c9ae490912f0888",
     "oracleUpdater": null,
-    "feeRecipient": "0x79c0650064b10f73649b7b64c5ebf0b319606140",
+    "feeRecipient": "0x97f46f90c04efb91d0d740bd263e76683ca6f904",
     "assetToStreamingOiCap": [
       [
         "xyz:AAPL",
@@ -25,7 +25,7 @@
       ],
       [
         "xyz:GOOGL",
-        "25000000.0"
+        "50000000.0"
       ],
       [
         "xyz:HOOD",
@@ -73,7 +73,8 @@
       ]
     ],
     "deployerFeeScale": "1.0",
-    "lastDeployerFeeScaleChangeTime": "1970-01-01T00:00:00"
+    "lastDeployerFeeScaleChangeTime": "1970-01-01T00:00:00",
+    "assetToFundingMultiplier": []
   },
   {
     "name": "flx",
@@ -82,9 +83,13 @@
     "oracleUpdater": "0x94757f8dcb4bf73b850195660e959d1105cfedd5",
     "feeRecipient": "0xe2872b5ae7dcbba40cc4510d08c8bbea95b42d43",
     "assetToStreamingOiCap": [
+      [
+        "flx:COIN",
+        "2000000.0"
+      ],
       [
         "flx:CRCL",
-        "1.0"
+        "2000000.0"
       ],
       [
         "flx:TSLA",
@@ -142,10 +147,42 @@
           "0xae083732032a813f9142733cdf380e1bc9e518af",
           "0xd0d4ef34424af3da883672b8cdeca751293655a5"
         ]
+      ],
+      [
+        "setMarginModes",
+        [
+          "0xd0d4ef34424af3da883672b8cdeca751293655a5"
+        ]
+      ],
+      [
+        "setFeeScale",
+        [
+          "0xd0d4ef34424af3da883672b8cdeca751293655a5"
+        ]
+      ],
+      [
+        "setGrowthModes",
+        [
+          "0xd0d4ef34424af3da883672b8cdeca751293655a5"
+        ]
       ]
     ],
     "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",
@@ -154,13 +191,17 @@
     "oracleUpdater": null,
     "feeRecipient": "0x5afe865300895b96d20132a8d9fa8e7829334b52",
     "assetToStreamingOiCap": [
+      [
+        "vntl:ANTHROPIC",
+        "3000000.0"
+      ],
       [
         "vntl:OPENAI",
-        "1000000.0"
+        "3000000.0"
       ],
       [
         "vntl:SPACEX",
-        "1000000.0"
+        "3000000.0"
       ]
     ],
     "subDeployers": [
@@ -185,11 +226,58 @@
       [
         "setFundingMultipliers",
         [
-          "0x6bdf4b47b638a8bb8ba630fbf867dc0f458d953e"
+          "0x6bdf4b47b638a8bb8ba630fbf867dc0f458d953e",
+          "0x9f82ce39734468c213f46834d0189222e1fadf5b"
+        ]
+      ]
+    ],
+    "deployerFeeScale": "1.0",
+    "lastDeployerFeeScaleChangeTime": "1970-01-01T00:00:00",
+    "assetToFundingMultiplier": [
+      [
+        "vntl:ANTHROPIC",
+        "0.0053054031"
+      ],
+      [
+        "vntl:OPENAI",
+        "0.0050794237"
+      ],
+      [
+        "vntl:SPACEX",
+        "0.010663783"
+      ]
+    ]
+  },
+  {
+    "name": "hyna",
+    "fullName": "HyENA",
+    "deployer": "0x53e655101ea361537124ef814ad4e654b54d0637",
+    "oracleUpdater": "0xaab93501e78f5105e265a1eafda10ce6530de17e",
+    "feeRecipient": null,
+    "assetToStreamingOiCap": [
+      [
+        "hyna:BTC",
+        "500000.0"
+      ],
+      [
+        "hyna:ETH",
+        "500000.0"
+      ],
+      [
+        "hyna:HYPE",
+        "500000.0"
+      ]
+    ],
+    "subDeployers": [
+      [
+        "setOracle",
+        [
+          "0xaab93501e78f5105e265a1eafda10ce6530de17e"
         ]
       ]
     ],
     "deployerFeeScale": "1.0",
-    "lastDeployerFeeScaleChangeTime": "1970-01-01T00:00:00"
+    "lastDeployerFeeScaleChangeTime": "2025-12-03T10:32:09.252520621",
+    "assetToFundingMultiplier": []
   }
 ]

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

@@ -2141,6 +2141,51 @@
       "name": "@253",
       "index": 253,
       "isCanonical": false
+    },
+    {
+      "tokens": [
+        124,
+        360
+      ],
+      "name": "@254",
+      "index": 254,
+      "isCanonical": false
+    },
+    {
+      "tokens": [
+        150,
+        235
+      ],
+      "name": "@255",
+      "index": 255,
+      "isCanonical": false
+    },
+    {
+      "tokens": [
+        374,
+        0
+      ],
+      "name": "@256",
+      "index": 256,
+      "isCanonical": false
+    },
+    {
+      "tokens": [
+        403,
+        0
+      ],
+      "name": "@257",
+      "index": 257,
+      "isCanonical": false
+    },
+    {
+      "tokens": [
+        398,
+        0
+      ],
+      "name": "@258",
+      "index": 258,
+      "isCanonical": false
     }
   ],
   "tokens": [
@@ -2151,7 +2196,10 @@
       "index": 0,
       "tokenId": "0x6d1e7cde53ba9467b783cb7c530ce054",
       "isCanonical": true,
-      "evmContract": null,
+      "evmContract": {
+        "address": "0x6b9e773128f453f5c2c60935ee2de2cbc5390a24",
+        "evm_extra_wei_decimals": -2
+      },
       "fullName": null,
       "deployerTradingFeeShare": "0.0"
     },
@@ -3572,9 +3620,12 @@
       "index": 124,
       "tokenId": "0xbd31bd605c0a1b82c72aae3587f9061f",
       "isCanonical": false,
-      "evmContract": null,
+      "evmContract": {
+        "address": "0x000000000000780555bd0bca3791f89f9542c2d6",
+        "evm_extra_wei_decimals": 10
+      },
       "fullName": "Kinetiq",
-      "deployerTradingFeeShare": "0.0"
+      "deployerTradingFeeShare": "1.0"
     },
     {
       "name": "BUSSY",
@@ -4066,7 +4117,7 @@
         "evm_extra_wei_decimals": 10
       },
       "fullName": null,
-      "deployerTradingFeeShare": "0.0"
+      "deployerTradingFeeShare": "1.0"
     },
     {
       "name": "ANIME",
@@ -6562,7 +6613,10 @@
       "index": 374,
       "tokenId": "0x83a0bf54708a0236a49f7301677ffdc2",
       "isCanonical": false,
-      "evmContract": null,
+      "evmContract": {
+        "address": "0x4f96b683714377c38123631f2d17cdf18b3f46a7",
+        "evm_extra_wei_decimals": 10
+      },
       "fullName": "SEDA",
       "deployerTradingFeeShare": "1.0"
     },
@@ -6639,7 +6693,10 @@
       "index": 381,
       "tokenId": "0xbd6af8c18f3e56d2da95a3c81d18e814",
       "isCanonical": false,
-      "evmContract": null,
+      "evmContract": {
+        "address": "0x99603f5cb890faca5cc5495ccc74391cdffa28bc",
+        "evm_extra_wei_decimals": 10
+      },
       "fullName": "Funnel BNB",
       "deployerTradingFeeShare": "1.0"
     },
@@ -6802,7 +6859,10 @@
       "index": 395,
       "tokenId": "0xedfb8d993ee8cb935338601d8673dfcf",
       "isCanonical": false,
-      "evmContract": null,
+      "evmContract": {
+        "address": "0x3073f7aaa4db83f95e9fff17424f71d4751a3073",
+        "evm_extra_wei_decimals": 0
+      },
       "fullName": null,
       "deployerTradingFeeShare": "1.0"
     },
@@ -6835,7 +6895,10 @@
       "index": 398,
       "tokenId": "0xec43194f64d555bdaef5afb5b6c6c686",
       "isCanonical": false,
-      "evmContract": null,
+      "evmContract": {
+        "address": "0xa51dc81944a15623874981181a99d6c56b20ed56",
+        "evm_extra_wei_decimals": 11
+      },
       "fullName": "Stable",
       "deployerTradingFeeShare": "1.0"
     },
@@ -6882,6 +6945,17 @@
       "evmContract": null,
       "fullName": "UltraSolid",
       "deployerTradingFeeShare": "1.0"
+    },
+    {
+      "name": "UMEGA",
+      "szDecimals": 1,
+      "weiDecimals": 6,
+      "index": 403,
+      "tokenId": "0xc99926509a189b40651055a15d3be621",
+      "isCanonical": false,
+      "evmContract": null,
+      "fullName": "Unit MegaETH",
+      "deployerTradingFeeShare": "1.0"
     }
   ]
 }

package/lib/meta/data/testnet/meta.json

@@ -505,9 +505,7 @@
       "szDecimals": 0,
       "name": "WIF",
       "maxLeverage": 5,
-      "marginTableId": 5,
-      "onlyIsolated": true,
-      "marginMode": "strictIsolated"
+      "marginTableId": 5
     },
     {
       "szDecimals": 1,
@@ -1240,10 +1238,8 @@
     {
       "szDecimals": 0,
       "name": "MON",
-      "maxLeverage": 3,
-      "marginTableId": 3,
-      "onlyIsolated": true,
-      "marginMode": "strictIsolated"
+      "maxLeverage": 5,
+      "marginTableId": 5
     },
     {
       "szDecimals": 0,