@syldel/hl-shared-types 0.0.17 → 0.0.19

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './interfaces';
 export * from './format';
+export * from './market';

package/dist/index.js

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./interfaces"), exports);
 __exportStar(require("./format"), exports);
+__exportStar(require("./market"), exports);

package/dist/interfaces/perp/meta.interfaces.d.ts

@@ -46,6 +46,29 @@ export interface HLPerpMeta {
     universe: HLPerpMarketInfo[];
     /** Margin configuration tables. */
     marginTables: HLPerpMarginTableEntry[];
+    /**
+     * Index du token qui sert de collatéral à **tout** ce dex — `0` pour USDC.
+     *
+     * C'est la correspondance dex → collatéral que l'exchange publie, et la seule
+     * qui ne vieillit pas. Les trois dépôts en tenaient jusqu'ici une copie en
+     * dur (`cash → USDT`, `hyna → USDE`, sinon USDC) : elle était **juste** quand
+     * elle a été écrite — les marchés Dreamcash s'appelaient bien `TSLA-USDT` et
+     * la marge HyENA était rendue en USDE — mais ces deux dex ont été éteints en
+     * juin et août 2026, et elle ne couvrait de toute façon que 2 des 10 dex
+     * déployés. Relevé le 2026-09-30 : les quatre dex vivants (`xyz`, `para`,
+     * `mkts`, `io`) rendent tous `collateralToken: 0`.
+     *
+     * Un `index`, et non un symbole : c'est ce que fait le calcul officiel du
+     * ratio de compte unifié, qui apparie ensuite `spotBalances[].token`. Deux
+     * tokens peuvent porter le même nom ; aucun ne partage un index. Le symbole
+     * se retrouve dans `spotMeta.tokens[].name`, pour l'affichage seulement.
+     *
+     * ⚠️ Optionnel, bien que l'API le rende sur tous les dex mesurés — y compris
+     * le principal : la doc de `meta` ne le montre pas dans son exemple (celle de
+     * `metaAndAssetCtxs`, si). Une réponse qui ne le porterait pas doit se
+     * traiter comme une absence de réponse, jamais comme « USDC par défaut ».
+     */
+    collateralToken?: number;
 }
 /**
  * Market metadata including its index in the universe list.

package/dist/market/index.d.ts

@@ -0,0 +1 @@
+export * from './market-name';

package/dist/market/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./market-name"), exports);

package/dist/market/market-name.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ============================================================================
+ * LE NOM D'UN MARCHÉ DIT DE QUEL CATALOGUE IL RELÈVE
+ *
+ * Source : doc Hyperliquid « Asset IDs », relevée le 2026-09-30.
+ *
+ * - un perp déployé par un builder porte **toujours** un nom `{dex}:{coin}` —
+ *   la doc écrit « always », ce n'est pas une heuristique ;
+ * - une paire spot se désigne par `10000 + spotInfo.index`, d'où la forme
+ *   protocolaire `@<index>` ; seules les canoniques portent `BASE/QUOTE`.
+ *   L'exemple HYPE de la doc (token 150, spot 107) recoupe le relevé du
+ *   2026-09-30 : le solde porte `token: 150`, la paire s'appelle `@107` ;
+ * - tout le reste est un perp du dex principal, que l'API désigne par un `dex`
+ *   vide.
+ *
+ * Ce module vit ici, et non dans le bot ou le mobile, pour la même raison que
+ * `tick-and-lot` : qu'il n'en existe **qu'une seule implémentation**. Les deux
+ * doivent décider à l'identique de quel univers relève un marché — sans quoi
+ * l'un signalerait comme morte une paire que l'autre continuerait de trader,
+ * ou l'inverse. Une divergence silencieuse entre l'écran et le moteur est
+ * exactement ce qu'on ne peut pas se permettre ici.
+ *
+ * L'incident qui l'a motivé, le 2026-09-30 : `vntl:ROBOT` était configurée sur
+ * l'écran Bot Strategies, ratio et protections comprises, sur un dex dont les
+ * 15 marchés sont délistés — et rien ne le disait. Le dex principal n'est pas
+ * épargné : 56 de ses 234 marchés le sont aussi.
+ *
+ * ⚠️ Le piège est le spot. Sur 330 paires spot relevées, la grande majorité
+ * s'appelle `@N` et ne porte **ni** barre oblique **ni** deux-points. Les
+ * traiter par défaut comme des perps les ferait chercher — en vain — dans
+ * l'univers du dex principal, et déclarer inexistant un marché vivant.
+ * ============================================================================
+ */
+/** Ce qu'un nom de marché désigne, du point de vue du catalogue à consulter. */
+export type HLMarketKind = 
+/** Perp du dex principal : `BTC`, `ETH`. L'API le désigne par un `dex` vide. */
+'perp'
+/** Perp déployé par un builder (HIP-3) : `vntl:ROBOT`, `xyz:AAPL`. */
+ | 'builderPerp'
+/** Paire spot : `PURR/USDC` (canonique) ou `@107` (forme protocolaire). */
+ | 'spot';
+/**
+ * Le genre de marché que ce nom désigne, ou `null` quand le nom n'en désigne
+ * aucun.
+ */
+export declare function hlMarketKind(name: string): HLMarketKind | null;
+/**
+ * Le dex perp dont relève ce marché — `''` pour le dex principal, le préfixe
+ * pour un HIP-3 —, ou `null` quand ce n'est pas un marché perp.
+ *
+ * C'est la valeur à passer à `meta({ dex })` : l'API accepte la chaîne vide
+ * pour le dex principal, et `null` dit qu'il n'y a rien à charger.
+ */
+export declare function hlPerpDexOf(name: string): string | null;

package/dist/market/market-name.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * ============================================================================
+ * LE NOM D'UN MARCHÉ DIT DE QUEL CATALOGUE IL RELÈVE
+ *
+ * Source : doc Hyperliquid « Asset IDs », relevée le 2026-09-30.
+ *
+ * - un perp déployé par un builder porte **toujours** un nom `{dex}:{coin}` —
+ *   la doc écrit « always », ce n'est pas une heuristique ;
+ * - une paire spot se désigne par `10000 + spotInfo.index`, d'où la forme
+ *   protocolaire `@<index>` ; seules les canoniques portent `BASE/QUOTE`.
+ *   L'exemple HYPE de la doc (token 150, spot 107) recoupe le relevé du
+ *   2026-09-30 : le solde porte `token: 150`, la paire s'appelle `@107` ;
+ * - tout le reste est un perp du dex principal, que l'API désigne par un `dex`
+ *   vide.
+ *
+ * Ce module vit ici, et non dans le bot ou le mobile, pour la même raison que
+ * `tick-and-lot` : qu'il n'en existe **qu'une seule implémentation**. Les deux
+ * doivent décider à l'identique de quel univers relève un marché — sans quoi
+ * l'un signalerait comme morte une paire que l'autre continuerait de trader,
+ * ou l'inverse. Une divergence silencieuse entre l'écran et le moteur est
+ * exactement ce qu'on ne peut pas se permettre ici.
+ *
+ * L'incident qui l'a motivé, le 2026-09-30 : `vntl:ROBOT` était configurée sur
+ * l'écran Bot Strategies, ratio et protections comprises, sur un dex dont les
+ * 15 marchés sont délistés — et rien ne le disait. Le dex principal n'est pas
+ * épargné : 56 de ses 234 marchés le sont aussi.
+ *
+ * ⚠️ Le piège est le spot. Sur 330 paires spot relevées, la grande majorité
+ * s'appelle `@N` et ne porte **ni** barre oblique **ni** deux-points. Les
+ * traiter par défaut comme des perps les ferait chercher — en vain — dans
+ * l'univers du dex principal, et déclarer inexistant un marché vivant.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hlMarketKind = hlMarketKind;
+exports.hlPerpDexOf = hlPerpDexOf;
+/**
+ * Le genre de marché que ce nom désigne, ou `null` quand le nom n'en désigne
+ * aucun.
+ */
+function hlMarketKind(name) {
+    if (!name)
+        return null;
+    // Le spot se teste en premier : un nom peut porter les deux marques
+    // (`cash:XYZ/USDT`), et c'est alors la paire qui prime sur le dex.
+    if (name.includes('/') || name.startsWith('@'))
+        return 'spot';
+    const separator = name.indexOf(':');
+    if (separator === -1)
+        return 'perp';
+    // Un nom de builder doit porter ses deux moitiés. Les accepter amputées
+    // serait pire que les refuser : `:BTC` rendrait un dex vide, donc le dex
+    // **principal**, et ferait juger un marché contre un univers qui n'est pas
+    // le sien.
+    const dex = name.slice(0, separator);
+    const coin = name.slice(separator + 1);
+    return dex && coin ? 'builderPerp' : null;
+}
+/**
+ * Le dex perp dont relève ce marché — `''` pour le dex principal, le préfixe
+ * pour un HIP-3 —, ou `null` quand ce n'est pas un marché perp.
+ *
+ * C'est la valeur à passer à `meta({ dex })` : l'API accepte la chaîne vide
+ * pour le dex principal, et `null` dit qu'il n'y a rien à charger.
+ */
+function hlPerpDexOf(name) {
+    const kind = hlMarketKind(name);
+    if (kind === 'perp')
+        return '';
+    if (kind === 'builderPerp')
+        return name.slice(0, name.indexOf(':'));
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syldel/hl-shared-types",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "Shared TypeScript interfaces and types for Hyperliquid integration.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",