@hfunlabs/hyperliquid 0.30.2-hfunlabs.2 → 0.32.2-hfunlabs.3

package/src/deps/jsr.io/@std/async/1.1.1/unstable_semaphore.ts

@@ -0,0 +1,147 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+// This module is browser compatible.
+
+/** Internal node for the FIFO waiting queue. */
+interface Node {
+  res: () => void;
+  next: Node | undefined;
+}
+
+/**
+ * A counting semaphore for limiting concurrent access to a resource.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @example Usage
+ * ```ts
+ * import { Semaphore } from "@std/async/unstable-semaphore";
+ *
+ * const sem = new Semaphore(2);
+ * {
+ *   using _permit = await sem.acquire();
+ *   // critical section
+ * } // permit is automatically released when exiting the block
+ * ```
+ */
+export class Semaphore {
+  #max: number;
+  /** Current number of available permits. */
+  #count: number;
+  /** Head of the waiting queue. */
+  #head: Node | undefined;
+  /** Tail of the waiting queue. */
+  #tail: Node | undefined;
+
+  /**
+   * Creates a new semaphore with the specified number of permits.
+   *
+   * @param max Maximum concurrent permits. Defaults to 1 (mutex).
+   * @throws {TypeError} If `max` is not a positive integer.
+   */
+  constructor(max: number = 1) {
+    if (!Number.isInteger(max) || max < 1) {
+      throw new TypeError(
+        `Cannot create semaphore as 'max' must be a positive integer: received ${max}`,
+      );
+    }
+    this.#count = this.#max = max;
+  }
+
+  /**
+   * Acquires a permit, waiting if none are available.
+   *
+   * @example Usage
+   * ```ts no-assert
+   * import { Semaphore } from "@std/async/unstable-semaphore";
+   *
+   * const sem = new Semaphore(1);
+   * await sem.acquire();
+   * try {
+   *   // critical section
+   * } finally {
+   *   sem.release();
+   * }
+   * ```
+   *
+   * @example Using `using` statement
+   * ```ts no-assert
+   * import { Semaphore } from "@std/async/unstable-semaphore";
+   *
+   * const sem = new Semaphore(1);
+   * {
+   *   using _permit = await sem.acquire();
+   *   // critical section
+   * } // permit is automatically released when exiting the block
+   * ```
+   *
+   * @returns A promise that resolves to a {@linkcode Disposable} when a permit is acquired.
+   */
+  acquire(): Promise<Disposable> {
+    const disposable: Disposable = { [Symbol.dispose]: () => this.release() };
+    if (this.#count > 0) {
+      this.#count--;
+      return Promise.resolve(disposable);
+    }
+    return new Promise((res) => {
+      const node: Node = { res: () => res(disposable), next: undefined };
+      if (this.#tail) {
+        this.#tail = this.#tail.next = node;
+      } else {
+        this.#head = this.#tail = node;
+      }
+    });
+  }
+
+  /**
+   * Tries to acquire a permit without waiting.
+   *
+   * @example Usage
+   * ```ts no-assert
+   * import { Semaphore } from "@std/async/unstable-semaphore";
+   *
+   * const sem = new Semaphore(1);
+   * const permit = sem.tryAcquire();
+   * if (permit) {
+   *   using _ = permit;
+   *   // critical section
+   * } else {
+   *   // resource is busy
+   * }
+   * ```
+   *
+   * @returns A {@linkcode Disposable} if a permit was acquired, `undefined` otherwise.
+   */
+  tryAcquire(): Disposable | undefined {
+    if (this.#count > 0) {
+      this.#count--;
+      return { [Symbol.dispose]: () => this.release() };
+    }
+    return undefined;
+  }
+
+  /**
+   * Releases a permit, allowing the next waiter to proceed.
+   *
+   * @example Usage
+   * ```ts no-assert
+   * import { Semaphore } from "@std/async/unstable-semaphore";
+   *
+   * const sem = new Semaphore(1);
+   * await sem.acquire();
+   * try {
+   *   // critical section
+   * } finally {
+   *   sem.release();
+   * }
+   * ```
+   */
+  release(): void {
+    if (this.#head) {
+      this.#head.res();
+      this.#head = this.#head.next;
+      if (!this.#head) this.#tail = undefined;
+    } else if (this.#count < this.#max) {
+      this.#count++;
+    }
+  }
+}

package/src/mod.ts

@@ -0,0 +1,35 @@
+/**
+ * Hyperliquid API TypeScript SDK.
+ *
+ * The main entrypoint exports:
+ * - Transports: {@link HttpTransport}, {@link WebSocketTransport}
+ * - Clients: {@link InfoClient}, {@link ExchangeClient}, {@link SubscriptionClient}
+ *
+ * For tree-shakeable, low-level access you can import request methods directly from:
+ * - `@nktkas/hyperliquid/api/info`
+ * - `@nktkas/hyperliquid/api/exchange`
+ * - `@nktkas/hyperliquid/api/subscription`
+ *
+ * Extra utilities are available in:
+ * - `@nktkas/hyperliquid/utils` (formatting, symbol conversion)
+ * - `@nktkas/hyperliquid/signing` (low-level signing helpers)
+ *
+ * @example Quick start
+ * ```ts
+ * import { HttpTransport, InfoClient } from "@nktkas/hyperliquid";
+ *
+ * const transport = new HttpTransport();
+ * const info = new InfoClient({ transport });
+ *
+ * const mids = await info.allMids();
+ * console.log(mids);
+ * ```
+ *
+ * @module
+ */
+
+export { HyperliquidError, ValidationError } from "./_base.js";
+export * from "./transport/mod.js";
+export * from "./api/exchange/client.js";
+export * from "./api/info/client.js";
+export * from "./api/subscription/client.js";

package/src/signing/_abstractWallet.ts

@@ -0,0 +1,285 @@
+/**
+ * Abstract wallet interfaces and signing utilities for EIP-712 typed data.
+ * @module
+ */
+
+import { HyperliquidError } from "../_base.js";
+
+// ============================================================
+// Common Types
+// ============================================================
+
+/** Common domain type for EIP-712 typed data signing. */
+interface TypedDataDomain {
+  name: string;
+  version: string;
+  chainId: number;
+  verifyingContract: `0x${string}`;
+}
+
+/** Common types structure for EIP-712 typed data. */
+interface TypedDataTypes {
+  [key: string]: { name: string; type: string }[];
+}
+
+// ============================================================
+// Ethers V6
+// ============================================================
+
+/** Abstract interface for an {@link https://docs.ethers.org/v6/api/providers/#Signer | ethers.js v6}. */
+export interface AbstractEthersV6Signer {
+  signTypedData(
+    domain: TypedDataDomain,
+    types: TypedDataTypes,
+    value: Record<string, unknown>,
+  ): Promise<string>;
+  getAddress(): Promise<string>;
+  provider?:
+    | { getNetwork(): Promise<{ chainId: number | bigint }> }
+    | null;
+}
+
+function isEthersV6Signer(wallet: AbstractWallet): wallet is AbstractEthersV6Signer {
+  return "signTypedData" in wallet && typeof wallet.signTypedData === "function" &&
+    wallet.signTypedData.length === 3 &&
+    "getAddress" in wallet && typeof wallet.getAddress === "function";
+}
+
+// ============================================================
+// Ethers V5
+// ============================================================
+
+/** Abstract interface for an {@link https://docs.ethers.org/v5/api/signer/ | ethers.js v5}. */
+export interface AbstractEthersV5Signer {
+  _signTypedData(
+    domain: TypedDataDomain,
+    types: TypedDataTypes,
+    value: Record<string, unknown>,
+  ): Promise<string>;
+  getAddress(): Promise<string>;
+  provider?:
+    | { getNetwork(): Promise<{ chainId: number | bigint }> }
+    | null;
+}
+
+function isEthersV5Signer(wallet: AbstractWallet): wallet is AbstractEthersV5Signer {
+  return "_signTypedData" in wallet && typeof wallet._signTypedData === "function" &&
+    wallet._signTypedData.length === 3 &&
+    "getAddress" in wallet && typeof wallet.getAddress === "function";
+}
+
+// ============================================================
+// Viem
+// ============================================================
+
+/** Viem-style typed data parameters. */
+interface ViemTypedDataParams {
+  domain: {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: `0x${string}`;
+  };
+  types: TypedDataTypes;
+  primaryType: string;
+  message: Record<string, unknown>;
+}
+
+/** Abstract interface for a {@link https://viem.sh/docs/accounts/jsonRpc#json-rpc-account | viem JSON-RPC Account}. */
+export interface AbstractViemJsonRpcAccount {
+  /** `options` is not in {@link https://viem.sh/docs/actions/wallet/signTypedData | base viem}; accepted for wallet extensions like {@link https://docs.privy.io/wallets/using-wallets/ethereum/sign-typed-data | Privy}. */
+  signTypedData(params: ViemTypedDataParams, options?: unknown): Promise<`0x${string}`>;
+  getAddresses(): Promise<`0x${string}`[]>;
+  getChainId(): Promise<number>;
+}
+
+function isViemJsonRpcAccount(wallet: AbstractWallet): wallet is AbstractViemJsonRpcAccount {
+  return "signTypedData" in wallet && typeof wallet.signTypedData === "function" &&
+    (wallet.signTypedData.length === 1 || wallet.signTypedData.length === 2) &&
+    "getAddresses" in wallet && typeof wallet.getAddresses === "function" &&
+    "getChainId" in wallet && typeof wallet.getChainId === "function";
+}
+
+/** Abstract interface for a {@link https://viem.sh/docs/accounts/local | viem Local Account}. */
+export interface AbstractViemLocalAccount {
+  /** `options` is not in {@link https://viem.sh/docs/actions/wallet/signTypedData | base viem}; accepted for wallet extensions like {@link https://docs.privy.io/wallets/using-wallets/ethereum/sign-typed-data | Privy}. */
+  signTypedData(params: ViemTypedDataParams, options?: unknown): Promise<`0x${string}`>;
+  address: `0x${string}`;
+}
+
+function isViemLocalAccount(wallet: AbstractWallet): wallet is AbstractViemLocalAccount {
+  return "signTypedData" in wallet && typeof wallet.signTypedData === "function" &&
+    (wallet.signTypedData.length === 1 || wallet.signTypedData.length === 2) &&
+    "address" in wallet && typeof wallet.address === "string";
+}
+
+// ============================================================
+// Abstract Signer
+// ============================================================
+
+/** Abstract interface for a wallet that can sign typed data. */
+export type AbstractWallet =
+  | AbstractViemJsonRpcAccount
+  | AbstractViemLocalAccount
+  | AbstractEthersV6Signer
+  | AbstractEthersV5Signer;
+
+/** ECDSA signature components. */
+export interface Signature {
+  /** First 32-byte component of ECDSA signature. */
+  r: `0x${string}`;
+  /** Second 32-byte component of ECDSA signature. */
+  s: `0x${string}`;
+  /** Recovery identifier. */
+  v: 27 | 28;
+}
+
+/** Thrown when an error occurs in AbstractWallet operations (e.g., signing, getting address). */
+export class AbstractWalletError extends HyperliquidError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "AbstractWalletError";
+  }
+}
+
+/**
+ * Signs EIP-712 typed data using the provided wallet.
+ *
+ * @param args The wallet, domain, types, primary type, and message to sign
+ * @return The ECDSA signature components
+ *
+ * @throws {AbstractWalletError} If the wallet type is unknown or signing fails
+ */
+export async function signTypedData(args: {
+  wallet: AbstractWallet;
+  domain: TypedDataDomain;
+  types: TypedDataTypes;
+  primaryType: string;
+  message: Record<string, unknown>;
+}): Promise<Signature> {
+  const { wallet, domain, types, primaryType } = args;
+
+  // Filter message to only contain fields defined in types (required by some wallets)
+  const typeFields = types[primaryType];
+  const message = typeFields
+    ? Object.fromEntries(Object.entries(args.message).filter(([k]) => typeFields.some((f) => f.name === k)))
+    : args.message;
+
+  const isViemWallet = isViemJsonRpcAccount(wallet) || isViemLocalAccount(wallet);
+  const isEthersV6 = isEthersV6Signer(wallet);
+  const isEthersV5 = isEthersV5Signer(wallet);
+
+  let signature: `0x${string}`;
+  try {
+    if (isViemWallet) {
+      signature = await wallet.signTypedData({
+        domain,
+        types: {
+          EIP712Domain: [
+            { name: "name", type: "string" },
+            { name: "version", type: "string" },
+            { name: "chainId", type: "uint256" },
+            { name: "verifyingContract", type: "address" },
+          ],
+          ...types,
+        },
+        primaryType,
+        message,
+      }) as `0x${string}`;
+    } else if (isEthersV6) {
+      signature = await wallet.signTypedData(domain, types, message) as `0x${string}`;
+    } else if (isEthersV5) {
+      signature = await wallet._signTypedData(domain, types, message) as `0x${string}`;
+    } else {
+      throw new AbstractWalletError("Failed to sign typed data: unknown wallet type");
+    }
+  } catch (error) {
+    if (error instanceof AbstractWalletError) throw error;
+    const walletType = isViemWallet ? "viem" : isEthersV6 ? "ethers v6" : "ethers v5";
+    throw new AbstractWalletError(`Failed to sign typed data with ${walletType} wallet`, { cause: error });
+  }
+
+  return splitSignature(signature);
+}
+
+function splitSignature(signature: `0x${string}`): Signature {
+  if (signature.length !== 132) {
+    throw new AbstractWalletError(`Expected 65-byte signature (132 hex chars), got ${signature.length}`);
+  }
+  const r = `0x${signature.slice(2, 66)}` as `0x${string}`;
+  const s = `0x${signature.slice(66, 130)}` as `0x${string}`;
+  let v = parseInt(signature.slice(130, 132), 16);
+  if (v === 0 || v === 1) v += 27;
+  if (v !== 27 && v !== 28) {
+    throw new AbstractWalletError(`Invalid signature recovery value: ${v}, expected 27 or 28`);
+  }
+  return { r, s, v };
+}
+
+// ============================================================
+// Helpers
+// ============================================================
+
+/**
+ * Gets the chain ID of the wallet.
+ *
+ * @param wallet The wallet to query
+ * @return The chain ID as a hex string
+ *
+ * @throws {AbstractWalletError} If getting the chain ID fails
+ */
+export async function getWalletChainId(wallet: AbstractWallet): Promise<`0x${string}`> {
+  try {
+    // Viem JSON-RPC account
+    if (isViemJsonRpcAccount(wallet)) {
+      const chainId = await wallet.getChainId() as number;
+      return `0x${chainId.toString(16)}`;
+    }
+
+    // Ethers V6 and V5 signer
+    const isEthersSigner = isEthersV6Signer(wallet) || isEthersV5Signer(wallet);
+    if (isEthersSigner && wallet.provider) {
+      const network = await wallet.provider.getNetwork() as { chainId: number | bigint };
+      return `0x${network.chainId.toString(16)}`;
+    }
+  } catch (error) {
+    throw new AbstractWalletError("Failed to get chain ID from wallet", { cause: error });
+  }
+
+  // Default chain ID
+  return "0x1";
+}
+
+/**
+ * Gets the lowercase wallet address from various wallet types.
+ *
+ * @param wallet The wallet to query
+ * @return The lowercase wallet address as a hex string
+ *
+ * @throws {AbstractWalletError} If getting the address fails or wallet type is unknown
+ */
+export async function getWalletAddress(wallet: AbstractWallet): Promise<`0x${string}`> {
+  try {
+    // Viem JSON-RPC account
+    if (isViemJsonRpcAccount(wallet)) {
+      const addresses = await wallet.getAddresses() as `0x${string}`[];
+      if (!addresses.length) throw new AbstractWalletError("Wallet returned no addresses");
+      return addresses[0].toLowerCase() as `0x${string}`;
+    }
+
+    // Viem local account
+    if (isViemLocalAccount(wallet)) {
+      return wallet.address.toLowerCase() as `0x${string}`;
+    }
+
+    // Ethers V6 and V5 signer
+    if (isEthersV6Signer(wallet) || isEthersV5Signer(wallet)) {
+      const address = await wallet.getAddress() as string;
+      return address.toLowerCase() as `0x${string}`;
+    }
+  } catch (error) {
+    throw new AbstractWalletError("Failed to get address from wallet", { cause: error });
+  }
+
+  throw new AbstractWalletError("Failed to get wallet address: unknown wallet type");
+}

package/src/signing/_canonicalize.ts

@@ -0,0 +1,179 @@
+/**
+ * Schema-driven key canonicalization for Hyperliquid action objects.
+ * @module
+ */
+
+import type { GenericSchema } from "valibot";
+import { HyperliquidError } from "../_base.js";
+
+/** Thrown when canonicalization fails due to schema/data key mismatch. */
+export class CanonicalizeError extends HyperliquidError {
+  constructor(message: string) {
+    super(message);
+    this.name = "CanonicalizeError";
+  }
+}
+
+/**
+ * Recursively rebuilds a value with object keys in schema-definition order.
+ *
+ * @param schema A valibot schema defining the canonical key order.
+ * @param value The value whose keys should be reordered.
+ * @return A new value with keys in schema-definition order.
+ *
+ * @throws {CanonicalizeError} If keys in data don't match the schema.
+ *
+ * @example
+ * ```ts
+ * import { canonicalize } from "@nktkas/hyperliquid/signing";
+ * import { CancelRequest } from "@nktkas/hyperliquid/api/exchange";
+ *
+ * const action = canonicalize(CancelRequest.entries.action, {
+ *   type: "cancel",
+ *   cancels: [{ a: 0, o: 12345 }],
+ * });
+ * ```
+ */
+export function canonicalize<T>(schema: GenericSchema, value: T): T {
+  return walk(schema, value) as T;
+}
+
+// ============================================================
+// Internal schema interface
+// ============================================================
+
+interface SchemaNode {
+  readonly type: string;
+  readonly entries?: Record<string, SchemaNode>;
+  readonly wrapped?: SchemaNode;
+  readonly item?: SchemaNode;
+  readonly items?: readonly SchemaNode[];
+  readonly key?: string;
+  readonly options?: readonly SchemaNode[];
+  readonly literal?: unknown;
+}
+
+// ============================================================
+// Recursive walker
+// ============================================================
+
+function walk(schema: SchemaNode, value: unknown): unknown {
+  const t = schema.type;
+
+  // Unwrap optional / nullable / nullish
+  if (t === "optional" || t === "nullable" || t === "nullish") {
+    return value === null || value === undefined ? value : walk(schema.wrapped!, value);
+  }
+
+  // Object → reorder keys by schema.entries
+  if (t === "object" && isRecord(value)) {
+    return reorderObject(schema.entries!, value);
+  }
+
+  // Array → canonicalize each item
+  if (t === "array" && Array.isArray(value)) {
+    return value.map((item) => walk(schema.item!, item));
+  }
+
+  // Tuple → canonicalize each item by index
+  if (t === "tuple" && Array.isArray(value)) {
+    return value.map((item, i) => walk(schema.items![i], item));
+  }
+
+  // Variant → match option by discriminator + structural fallback
+  if (t === "variant" && isRecord(value)) {
+    const option = matchVariantOption(schema.key!, schema.options!, value);
+    if (option) return walk(option, value);
+    throw new CanonicalizeError(
+      `No variant option matches data (discriminator "${schema.key}" = ${JSON.stringify(value[schema.key!])})`,
+    );
+  }
+
+  // Union → match option structurally
+  if (t === "union" && isRecord(value)) {
+    const option = matchByStructure(schema.options!, value);
+    if (option) return walk(option, value);
+    return value;
+  }
+
+  // Primitives, literals, picklists, enums → return as-is
+  return value;
+}
+
+// ============================================================
+// Helpers
+// ============================================================
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function reorderObject(entries: Record<string, SchemaNode>, value: Record<string, unknown>): Record<string, unknown> {
+  for (const key of Object.keys(value)) {
+    if (!(key in entries)) {
+      throw new CanonicalizeError(`Key "${key}" exists in data but not in schema`);
+    }
+  }
+
+  for (const key of Object.keys(entries)) {
+    if (!(key in value)) {
+      const t = entries[key].type;
+      if (t !== "optional" && t !== "nullable" && t !== "nullish") {
+        throw new CanonicalizeError(`Required key "${key}" exists in schema but not in data`);
+      }
+    }
+  }
+
+  const result: Record<string, unknown> = {};
+  for (const key of Object.keys(entries)) {
+    if (key in value) {
+      result[key] = walk(entries[key], value[key]);
+    }
+  }
+  return result;
+}
+
+function matchVariantOption(
+  discriminatorKey: string,
+  options: readonly SchemaNode[],
+  value: Record<string, unknown>,
+): SchemaNode | undefined {
+  const discriminatorValue = value[discriminatorKey];
+
+  const matching: SchemaNode[] = [];
+  for (const option of options) {
+    if (option.type === "object" && option.entries && discriminatorKey in option.entries) {
+      const keySchema = option.entries[discriminatorKey];
+      if (keySchema.type === "literal" && keySchema.literal === discriminatorValue) {
+        matching.push(option);
+      }
+    }
+  }
+
+  if (matching.length === 1) return matching[0];
+  if (matching.length > 1) return matchByStructure(matching, value);
+
+  return undefined;
+}
+
+function matchByStructure(
+  options: readonly SchemaNode[],
+  value: Record<string, unknown>,
+): SchemaNode | undefined {
+  const dataKeys = new Set(Object.keys(value));
+
+  for (const option of options) {
+    if (option.type === "object" && option.entries) {
+      if ([...dataKeys].every((k) => k in option.entries!)) {
+        const allRequired = Object.keys(option.entries).every((k) => {
+          if (dataKeys.has(k)) return true;
+          const t = option.entries![k].type;
+          return t === "optional" || t === "nullable" || t === "nullish";
+        });
+        if (allRequired) return option;
+      }
+    }
+  }
+
+  return undefined;
+}