@hfunlabs/hyperliquid 0.27.1-hfunlabs.1

package/src/src/utils/_format.ts

@@ -0,0 +1,173 @@
+/**
+ * Format price according to Hyperliquid {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size | rules}:
+ * - Maximum 5 significant figures
+ * - Maximum 6 (for perp) or 8 (for spot) - `szDecimals` decimal places
+ * - Integer prices are always allowed regardless of significant figures
+ * @example
+ * ```ts
+ * import { formatPrice } from "@nktkas/hyperliquid/utils";
+ *
+ * //        `true` for perp (default), `false` for spot
+ * //                                              ⌄⌄⌄⌄⌄
+ * const price = formatPrice("0.0000123456789", 0, false); // → "0.00001234"
+ * ```
+ */
+export function formatPrice(price: string | number, szDecimals: number, isPerp: boolean = true): string {
+  price = price.toString().trim();
+  assertNumberString(price);
+
+  // Integer prices are always allowed
+  if (/^-?\d+$/.test(price)) return trimZeros(price);
+
+  // Apply decimal limit: max 6 (perp) or 8 (spot) - szDecimals
+  const maxDecimals = Math.max((isPerp ? 6 : 8) - szDecimals, 0);
+  price = StringMath.toFixedTruncate(price, maxDecimals);
+
+  // Apply sig figs limit: max 5 significant figures
+  price = StringMath.toPrecisionTruncate(price, 5);
+
+  return price;
+}
+
+/**
+ * Format size according to Hyperliquid {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size | rules}:
+ * - Truncate decimal places to `szDecimals`
+ * @example
+ * ```ts
+ * import { formatSize } from "@nktkas/hyperliquid/utils";
+ *
+ * const size = formatSize("1.23456789", 5); // → "1.23456"
+ * ```
+ * @note May return 0 if the value is not suitable, but when closing a position, a size of 0 means the full size.
+ */
+export function formatSize(size: string | number, szDecimals: number): string {
+  size = size.toString().trim();
+  assertNumberString(size);
+
+  // Apply decimal limit: szDecimals
+  size = StringMath.toFixedTruncate(size, szDecimals);
+
+  return size;
+}
+
+/** String-based Math operations for arbitrary precision */
+const StringMath = {
+  /** Floor log10 (magnitude): position of most significant digit */
+  log10Floor(value: string): number {
+    const abs = value[0] === "-" ? value.slice(1) : value;
+
+    // Check if zero or invalid
+    const num = Number(abs);
+    if (num === 0 || isNaN(num)) return -Infinity;
+
+    const [int, dec] = abs.split(".");
+
+    // Number >= 1: magnitude = length of integer part - 1
+    if (Number(int) !== 0) {
+      const trimmed = int.replace(/^0+/, "");
+      return trimmed.length - 1;
+    }
+
+    // Number < 1: count leading zeros in decimal part
+    const leadingZeros = dec.match(/^0*/)?.[0].length ?? 0;
+    return -(leadingZeros + 1);
+  },
+
+  /** Multiply by 10^exp: shift decimal point left (negative) or right (positive) */
+  multiplyByPow10(value: string, exp: number): string {
+    if (!Number.isInteger(exp)) throw new RangeError("Exponent must be an integer");
+    if (exp === 0) return trimZeros(value);
+
+    const neg = value[0] === "-";
+    const abs = neg ? value.slice(1) : value;
+    const [intRaw, dec = ""] = abs.split(".");
+    // Normalize empty integer part to "0" (handles ".5" → "0.5")
+    const int = intRaw || "0";
+
+    let result: string;
+
+    if (exp > 0) {
+      // Shift right: move digits from decimal to integer
+      if (exp >= dec.length) {
+        result = int + dec + "0".repeat(exp - dec.length);
+      } else {
+        result = int + dec.slice(0, exp) + "." + dec.slice(exp);
+      }
+    } else {
+      // Shift left: move digits from integer to decimal
+      const absExp = -exp;
+      if (absExp >= int.length) {
+        result = "0." + "0".repeat(absExp - int.length) + int + dec;
+      } else {
+        result = int.slice(0, -absExp) + "." + int.slice(-absExp) + dec;
+      }
+    }
+
+    return trimZeros((neg ? "-" : "") + result);
+  },
+
+  /** Returns the integer part of a number by removing any fractional digits */
+  trunc(value: string): string {
+    const dotIndex = value.indexOf(".");
+    return dotIndex === -1 ? value : value.slice(0, dotIndex) || "0";
+  },
+
+  /** Truncate to a certain number of significant figures */
+  toPrecisionTruncate(value: string, precision: number): string {
+    if (!Number.isInteger(precision)) throw new RangeError("Precision must be an integer");
+    if (precision < 1) throw new RangeError("Precision must be positive");
+    if (/^-?0+(\.0*)?$/.test(value)) return "0"; // zero is special case (don't work with log10)
+
+    const neg = value[0] === "-";
+    const abs = neg ? value.slice(1) : value;
+
+    // Calculate how much to shift: align most significant digit to ones place + (maxSigFigs-1)
+    const magnitude = StringMath.log10Floor(abs);
+    const shiftAmount = precision - magnitude - 1;
+
+    // Shift right, truncate integer part, shift back
+    const shifted = StringMath.multiplyByPow10(abs, shiftAmount);
+    const truncated = StringMath.trunc(shifted);
+    const result = StringMath.multiplyByPow10(truncated, -shiftAmount);
+
+    // build final result and trim zeros
+    return trimZeros(neg ? "-" + result : result);
+  },
+
+  /** Truncate to a certain number of decimal places */
+  toFixedTruncate(value: string, decimals: number): string {
+    if (!Number.isInteger(decimals)) throw new RangeError("Decimals must be an integer");
+    if (decimals < 0) throw new RangeError("Decimals must be non-negative");
+
+    // Match number with up to `decimals` decimal places
+    const regex = new RegExp(`^-?(?:\\d+)?(?:\\.\\d{0,${decimals}})?`);
+    const result = value.match(regex)?.[0];
+
+    if (!result) {
+      throw new TypeError("Invalid number format");
+    }
+
+    // Trim zeros after truncation
+    return trimZeros(result);
+  },
+};
+
+function trimZeros(value: string): string {
+  return value
+    // remove leading zeros
+    .replace(/^(-?)0+(?=\d)/, "$1") // "00123" → "123", "-00.5" → "-0.5"
+    // remove trailing zeros
+    .replace(/\.0*$|(\.\d+?)0+$/, "$1") // "1.2000" → "1.2", "5.0" → "5"
+    // add leading zero if starts with decimal point
+    .replace(/^(-?)\./, "$10.") // ".5" → "0.5", "-.5" → "-0.5"
+    // add "0" if string is empty after trimming
+    .replace(/^-?$/, "0") // "" → "0", "-" → "0"
+    // normalize negative zero
+    .replace(/^-0$/, "0"); // "-0" → "0"
+}
+
+function assertNumberString(value: string): void {
+  if (!/^-?(\d+\.?\d*|\.\d*)$/.test(value)) {
+    throw new TypeError("Invalid number format");
+  }
+}

package/src/src/utils/_recover.ts

@@ -0,0 +1,178 @@
+import { keccak_256 } from "@noble/hashes/sha3.js";
+import * as secp from "@noble/secp256k1";
+import { createL1ActionHash, type Signature } from "../signing/mod.js";
+import { hashTypedData } from "./_eip712.js";
+
+/**
+ * Recover the Ethereum address that signed an L1 action.
+ * @example
+ * ```ts
+ * import { recoverUserFromL1Action } from "@nktkas/hyperliquid/utils";
+ *
+ * const action = {
+ *   type: "cancel",
+ *   cancels: [{ a: 0, o: 12345 }],
+ * };
+ * const nonce = 1700000000000;
+ * const signature = {
+ *   r: "0x...",
+ *   s: "0x...",
+ *   v: 27,
+ * } as const;
+ *
+ * const address = await recoverUserFromL1Action({ action, nonce, signature });
+ * console.log(`Signer address: ${address}`);
+ * ```
+ */
+export async function recoverUserFromL1Action(params: {
+  /** The action that was signed (hash depends on key order). */
+  action: Record<string, unknown>;
+  /** The timestamp in ms used when signing. */
+  nonce: number;
+  /** The signature to recover the address from. */
+  signature: Signature;
+  /** Indicates if the action is for the testnet. (default: false) */
+  isTestnet?: boolean;
+  /** Optional vault address used in the action. */
+  vaultAddress?: `0x${string}`;
+  /** Optional expiration time in ms used in the action. */
+  expiresAfter?: number;
+}): Promise<`0x${string}`> {
+  const {
+    action,
+    signature,
+    nonce,
+    isTestnet = false,
+    vaultAddress,
+    expiresAfter,
+  } = params;
+
+  // 1. Create the action hash
+  const actionHash = createL1ActionHash({ action, nonce, vaultAddress, expiresAfter });
+
+  // 2. Hash the typed data according to EIP-712
+  const hash = hashTypedData({
+    domain: {
+      name: "Exchange",
+      version: "1",
+      chainId: 1337,
+      verifyingContract: "0x0000000000000000000000000000000000000000",
+    },
+    types: {
+      Agent: [
+        { name: "source", type: "string" },
+        { name: "connectionId", type: "bytes32" },
+      ],
+    },
+    primaryType: "Agent",
+    message: {
+      source: isTestnet ? "b" : "a",
+      connectionId: actionHash,
+    },
+  });
+
+  // 3. Convert signature to recovery format (v, r, s)
+  const sigr = secp.etc.concatBytes(
+    new Uint8Array([signature.v - 27]),
+    secp.etc.hexToBytes(signature.r.slice(2)),
+    secp.etc.hexToBytes(signature.s.slice(2)),
+  );
+
+  // 4. Recover the public key from the signature and hash
+  const compressedPubKey = await secp.recoverPublicKeyAsync(sigr, hash, { prehash: false });
+  const uncompressedPubKey = secp.Point.fromBytes(compressedPubKey).toBytes(false);
+
+  // 5. Convert the public key to an Ethereum address
+  return publicKeyToAddress(uncompressedPubKey);
+}
+
+/**
+ * Recover the Ethereum address that signed a user-signed action.
+ * @example
+ * ```ts
+ * import { recoverUserFromUserSigned } from "@nktkas/hyperliquid/utils";
+ *
+ * const action = {
+ *   type: "approveAgent",
+ *   signatureChainId: "0x66eee" as const,
+ *   hyperliquidChain: "Mainnet",
+ *   agentAddress: "0x...",
+ *   agentName: "Agent",
+ *   nonce: 1700000000000,
+ * };
+ * const types = {
+ *   HyperliquidTransaction: [
+ *     { name: "hyperliquidChain", type: "string" },
+ *     // ... other fields
+ *   ],
+ * };
+ * const signature = {
+ *   r: "0x...",
+ *   s: "0x...",
+ *   v: 27,
+ * } as const;
+ *
+ * const address = await recoverUserFromUserSigned({ action, types, signature });
+ * console.log(`Signer address: ${address}`);
+ * ```
+ */
+export async function recoverUserFromUserSigned(params: {
+  /** The action that was signed (hex strings must be in lower case). */
+  action:
+    & {
+      signatureChainId: `0x${string}`;
+      [key: string]: unknown;
+    }
+    & (
+      | { nonce: number; time?: undefined }
+      | { time: number; nonce?: undefined }
+    );
+  /** The types of the action (hash depends on key order). */
+  types: {
+    [key: string]: {
+      name: string;
+      type: string;
+    }[];
+  };
+  /** The signature to recover the address from. */
+  signature: Signature;
+}): Promise<`0x${string}`> {
+  const { action, types, signature } = params;
+
+  // 1. Hash the typed data according to EIP-712
+  const hash = hashTypedData({
+    domain: {
+      name: "HyperliquidSignTransaction",
+      version: "1",
+      chainId: parseInt(action.signatureChainId),
+      verifyingContract: "0x0000000000000000000000000000000000000000",
+    },
+    types,
+    primaryType: Object.keys(types)[0],
+    message: action,
+  });
+
+  // 2. Convert signature to recovery format (v, r, s)
+  const sigr = secp.etc.concatBytes(
+    new Uint8Array([signature.v - 27]),
+    secp.etc.hexToBytes(signature.r.slice(2)),
+    secp.etc.hexToBytes(signature.s.slice(2)),
+  );
+
+  // 3. Recover the public key from the signature and hash
+  const compressedPubKey = await secp.recoverPublicKeyAsync(sigr, hash, { prehash: false });
+  const uncompressedPubKey = secp.Point.fromBytes(compressedPubKey).toBytes(false);
+
+  // 4. Convert the public key to an Ethereum address
+  return publicKeyToAddress(uncompressedPubKey);
+}
+
+/** Convert a public key to an Ethereum address. */
+function publicKeyToAddress(publicKey: Uint8Array): `0x${string}` {
+  // Remove the 0x04 prefix from uncompressed public key
+  const publicKeyWithoutPrefix = publicKey.slice(1);
+  // Hash the public key and take the last 20 bytes as the address
+  const hash = keccak_256(publicKeyWithoutPrefix);
+  const addressBytes = hash.slice(-20);
+  return `0x${secp.etc.bytesToHex(addressBytes)}`;
+}

package/src/src/utils/_symbolConverter.ts

@@ -0,0 +1,203 @@
+import type { IRequestTransport } from "../transport/base.js";
+import { meta, type MetaResponse } from "../api/info/meta.js";
+import { spotMeta, type SpotMetaResponse } from "../api/info/spotMeta.js";
+import { perpDexs, type PerpDexsResponse } from "../api/info/perpDexs.js";
+
+export type DexOption = string[] | boolean;
+
+/** Options for creating a SymbolConverter instance. */
+export interface SymbolConverterOptions {
+  /** Transport instance to use for API requests. */
+  transport: IRequestTransport;
+  /** Optional dex support: array of dex names, true for all dexs, or false/undefined to skip. */
+  dexs?: DexOption;
+}
+
+/**
+ * Utility class for converting asset symbols to their corresponding IDs and size decimals.
+ * Supports perpetuals, spot markets, and optional builder dexs.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/asset-ids
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { SymbolConverter } from "@nktkas/hyperliquid/utils";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ * const converter = await SymbolConverter.create({ transport });
+ *
+ * // By default, dexs are not loaded; specify them when creating an instance
+ * // const converter = await SymbolConverter.create({ transport, dexs: ["test"] });
+ *
+ * const btcId = converter.getAssetId("BTC"); // perpetual → 0
+ * const hypeUsdcId = converter.getAssetId("HYPE/USDC"); // spot market → 10107
+ * const dexAbcId = converter.getAssetId("test:ABC"); // builder dex (if enabled) → 110000
+ *
+ * const btcSzDecimals = converter.getSzDecimals("BTC"); // perpetual → 5
+ * const hypeUsdcSzDecimals = converter.getSzDecimals("HYPE/USDC"); // spot market → 2
+ * const dexAbcSzDecimals = converter.getSzDecimals("test:ABC"); // builder dex (if enabled) → 0
+ *
+ * const spotPairId = converter.getSpotPairId("HFUN/USDC"); // → "@2"
+ * ```
+ */
+export class SymbolConverter {
+  private readonly transport: IRequestTransport;
+  private readonly dexOption: DexOption;
+  private readonly nameToAssetId = new Map<string, number>();
+  private readonly nameToSzDecimals = new Map<string, number>();
+  private readonly nameToSpotPairId = new Map<string, string>();
+
+  private constructor(options: SymbolConverterOptions) {
+    this.transport = options.transport;
+    this.dexOption = options.dexs ?? false;
+  }
+
+  /**
+   * Create and initialize a SymbolConverter instance.
+   * @param options - Configuration options including transport and optional dex support.
+   * @returns Initialized SymbolConverter instance.
+   * @example
+   * ```ts
+   * import { HttpTransport } from "@nktkas/hyperliquid";
+   * import { SymbolConverter } from "@nktkas/hyperliquid/utils";
+   *
+   * const transport = new HttpTransport(); // or `WebSocketTransport`
+   * const converter = await SymbolConverter.create({ transport });
+   * ```
+   */
+  static async create(options: SymbolConverterOptions): Promise<SymbolConverter> {
+    const instance = new SymbolConverter(options);
+    await instance.reload();
+    return instance;
+  }
+
+  /**
+   * Reload asset mappings from the API.
+   * Useful for refreshing data when new assets are added.
+   */
+  async reload(): Promise<void> {
+    const config = { transport: this.transport };
+    const [perpMetaData, spotMetaData, perpDexsData] = await Promise.all([
+      meta(config),
+      spotMeta(config),
+      perpDexs(config),
+    ]);
+
+    if (!perpMetaData?.universe?.length) {
+      throw new Error("Invalid perpetual metadata response");
+    }
+
+    if (!spotMetaData?.universe?.length || !spotMetaData?.tokens?.length) {
+      throw new Error("Invalid spot metadata response");
+    }
+
+    this.nameToAssetId.clear();
+    this.nameToSzDecimals.clear();
+    this.nameToSpotPairId.clear();
+
+    this.processDefaultPerps(perpMetaData);
+    this.processSpotAssets(spotMetaData);
+
+    // Only process builder dexs if dex support is enabled
+    if (this.dexOption !== false) {
+      await this.processBuilderDexs(perpDexsData);
+    }
+  }
+
+  private processDefaultPerps(perpMeta: MetaResponse): void {
+    perpMeta.universe.forEach((asset, index) => {
+      this.nameToAssetId.set(asset.name, index);
+      this.nameToSzDecimals.set(asset.name, asset.szDecimals);
+    });
+  }
+
+  private async processBuilderDexs(perpDexs: PerpDexsResponse): Promise<void> {
+    if (!perpDexs || perpDexs.length <= 1) return;
+
+    const builderDexs = perpDexs
+      .map((dex, index) => ({ dex, index }))
+      .filter((item): item is { dex: NonNullable<PerpDexsResponse[number]>; index: number } => {
+        return item.index > 0 && item.dex !== null && item.dex.name.length > 0;
+      });
+
+    if (builderDexs.length === 0) return;
+
+    // Filter dexs based on the dexOption
+    const dexsToProcess = Array.isArray(this.dexOption)
+      ? builderDexs.filter((item) => (this.dexOption as string[]).includes(item.dex.name))
+      : builderDexs; // true means process all
+
+    if (dexsToProcess.length === 0) return;
+
+    const config = { transport: this.transport };
+    const results = await Promise.allSettled(
+      dexsToProcess.map((item) => meta(config, { dex: item.dex.name })),
+    );
+
+    results.forEach((result, idx) => {
+      if (result.status !== "fulfilled") return;
+      this.processBuilderDexResult(result.value, dexsToProcess[idx].index);
+    });
+  }
+
+  private processBuilderDexResult(meta: MetaResponse, perpDexIndex: number): void {
+    const offset = 100000 + perpDexIndex * 10000;
+
+    meta.universe.forEach((asset, index) => {
+      const assetId = offset + index;
+      this.nameToAssetId.set(asset.name, assetId);
+      this.nameToSzDecimals.set(asset.name, asset.szDecimals);
+    });
+  }
+
+  private processSpotAssets(spotMeta: SpotMetaResponse): void {
+    const tokenMap = new Map<number, { name: string; szDecimals: number }>();
+    spotMeta.tokens.forEach((token) => {
+      tokenMap.set(token.index, { name: token.name, szDecimals: token.szDecimals });
+    });
+
+    spotMeta.universe.forEach((market) => {
+      if (market.tokens.length < 2) return;
+      const baseToken = tokenMap.get(market.tokens[0]);
+      const quoteToken = tokenMap.get(market.tokens[1]);
+      if (!baseToken || !quoteToken) return;
+
+      const assetId = 10000 + market.index;
+      const baseQuoteKey = `${baseToken.name}/${quoteToken.name}`;
+      this.nameToAssetId.set(baseQuoteKey, assetId);
+      this.nameToSzDecimals.set(baseQuoteKey, baseToken.szDecimals);
+      this.nameToSpotPairId.set(baseQuoteKey, market.name);
+    });
+  }
+
+  /**
+   * Get asset ID for a coin.
+   * - For Perpetuals, use the coin name (e.g., "BTC").
+   * - For Spot markets, use the "BASE/QUOTE" format (e.g., "HYPE/USDC").
+   * - For Builder Dex assets, use the "DEX_NAME:ASSET_NAME" format (e.g., "test:ABC").
+   * @example "BTC" → 0, "HYPE/USDC" → 10107, "test:ABC" → 110000
+   */
+  getAssetId(name: string): number | undefined {
+    return this.nameToAssetId.get(name);
+  }
+
+  /**
+   * Get size decimals for a coin.
+   * - For Perpetuals, use the coin name (e.g., "BTC").
+   * - For Spot markets, use the "BASE/QUOTE" format (e.g., "HYPE/USDC").
+   * - For Builder Dex assets, use the "DEX_NAME:ASSET_NAME" format (e.g., "test:ABC").
+   * @example "BTC" → 5, "HYPE/USDC" → 2, "test:ABC" → 0
+   */
+  getSzDecimals(name: string): number | undefined {
+    return this.nameToSzDecimals.get(name);
+  }
+
+  /**
+   * Get spot pair ID for info endpoints and subscriptions (e.g., l2book, trades).
+   *
+   * Accepts spot markets in the "BASE/QUOTE" format (e.g., "HFUN/USDC").
+   * @example "HFUN/USDC" → "@2", "PURR/USDC" → "PURR/USDC"
+   */
+  getSpotPairId(name: string): string | undefined {
+    return this.nameToSpotPairId.get(name);
+  }
+}

package/src/src/utils/mod.ts

@@ -0,0 +1,3 @@
+export * from "./_symbolConverter.js";
+export * from "./_format.js";
+export * from "./_recover.js";