@hfunlabs/hyperliquid 0.27.1 → 0.30.0-hfunlabs.1

package/src/src/signing/mod.ts

@@ -1,15 +1,16 @@
 /**
- * This module contains functions for generating Hyperliquid transaction signatures.
+ * Low-level utilities for signing Hyperliquid transactions.
  *
  * @example Signing an L1 action
  * ```ts
  * import { signL1Action } from "@nktkas/hyperliquid/signing";
- * import { CancelRequest, parser } from "@nktkas/hyperliquid/api/exchange";
+ * import { CancelRequest } from "@nktkas/hyperliquid/api/exchange";
+ * import * as v from "npm:valibot";
  * import { privateKeyToAccount } from "npm:viem/accounts";
  *
  * const wallet = privateKeyToAccount("0x..."); // viem or ethers
  *
- * const action = parser(CancelRequest.entries.action)({ // for correct signature generation
+ * const action = v.parse(CancelRequest.entries.action, { // not required, but for correct generation
  *   type: "cancel",
  *   cancels: [
  *     { a: 0, o: 12345 },
@@ -31,12 +32,13 @@
  * @example Signing a user-signed action
  * ```ts
  * import { signUserSignedAction } from "@nktkas/hyperliquid/signing";
- * import { ApproveAgentRequest, ApproveAgentTypes, parser } from "@nktkas/hyperliquid/api/exchange";
+ * import { ApproveAgentRequest, ApproveAgentTypes } from "@nktkas/hyperliquid/api/exchange";
+ * import * as v from "npm:valibot";
  * import { privateKeyToAccount } from "npm:viem/accounts";
  *
  * const wallet = privateKeyToAccount("0x..."); // viem or ethers
  *
- * const action = parser(ApproveAgentRequest.entries.action)({ // for correct signature generation
+ * const action = v.parse(ApproveAgentRequest.entries.action, { // not required, but for correct generation
  *   type: "approveAgent",
  *   signatureChainId: "0x66eee",
  *   hyperliquidChain: "Mainnet",
@@ -56,92 +58,36 @@
  * const body = await response.json();
  * ```
  *
- * @example Signing a multi-signature action
- * ```ts
- * import { signL1Action, signMultiSigAction } from "@nktkas/hyperliquid/signing";
- * import { MultiSigRequest, parser, ScheduleCancelRequest } from "@nktkas/hyperliquid/api/exchange";
- * import { privateKeyToAccount } from "npm:viem/accounts";
- *
- * const wallet = privateKeyToAccount("0x..."); // viem or ethers
- * const multiSigUser = "0x...";
- *
- * const action = parser(ScheduleCancelRequest.entries.action)({ // for correct signature generation
- *   type: "scheduleCancel",
- *   time: Date.now() + 10000,
- * });
- * const nonce = Date.now();
- *
- * // Create the required number of signatures
- * const signatures = await Promise.all(["0x...", "0x..."].map(async (signerPrivKey) => {
- *   return await signL1Action({
- *     wallet: privateKeyToAccount(signerPrivKey as `0x${string}`), // viem or ethers
- *     action: [multiSigUser.toLowerCase(), wallet.address.toLowerCase(), action],
- *     nonce,
- *   });
- * }));
- *
- * // // or user-signed action
- * // const signatures = await Promise.all(["0x...", "0x..."].map(async (signerPrivKey) => {
- * //   return await signUserSignedAction({
- * //     wallet: privateKeyToAccount(signerPrivKey as `0x${string}`), // viem or ethers
- * //     action: {
- * //       ...action,
- * //       payloadMultiSigUser: multiSigUser,
- * //       outerSigner: wallet.address,
- * //     },
- * //     types: SomeTypes,
- * //   });
- * // }));
- *
- * // Then use signatures in the multi-sig action
- * const multiSigAction = parser(MultiSigRequest.entries.action)({
- *   type: "multiSig",
- *   signatureChainId: "0x66eee",
- *   signatures,
- *   payload: {
- *     multiSigUser,
- *     outerSigner: wallet.address,
- *     action,
- *   },
- * });
- * const multiSigSignature = await signMultiSigAction({ wallet, action: multiSigAction, nonce });
- *
- * // Send the multi-sig action to the Hyperliquid API
- * const response = await fetch("https://api.hyperliquid.xyz/exchange", {
- *   method: "POST",
- *   headers: { "Content-Type": "application/json" },
- *   body: JSON.stringify({ action: multiSigAction, signature: multiSigSignature, nonce }),
- * });
- * const body = await response.json();
- * ```
- *
  * @module
  */
 
 import { keccak_256 } from "@noble/hashes/sha3.js";
 import { bytesToHex, concatBytes, hexToBytes } from "@noble/hashes/utils.js";
 import { encode as encodeMsgpack, type ValueType } from "../../deps/jsr.io/@std/msgpack/1.0.3/mod.js";
-import { type AbstractWallet, type Signature, signTypedData } from "./_signTypedData.js";
+import { type AbstractWallet, type Signature, signTypedData } from "./_abstractWallet.js";
 
 export {
   type AbstractEthersV5Signer,
   type AbstractEthersV6Signer,
   type AbstractViemJsonRpcAccount,
   type AbstractViemLocalAccount,
+  type AbstractWallet,
   AbstractWalletError,
   getWalletAddress,
   getWalletChainId,
-} from "./_signTypedData.js";
-export type { AbstractWallet, Signature };
+  type Signature,
+} from "./_abstractWallet.js";
+export { PrivateKeySigner } from "./_privateKeySigner.js";
 
 /**
  * Create a hash of the L1 action.
  * @example
  * ```ts
  * import { createL1ActionHash } from "@nktkas/hyperliquid/signing";
- * import { CancelRequest, parser } from "@nktkas/hyperliquid/api/exchange";
+ * import { CancelRequest } from "@nktkas/hyperliquid/api/exchange";
+ * import * as v from "npm:valibot";
  *
- * const action = parser(CancelRequest.entries.action)({ // for correct signature generation
+ * const action = v.parse(CancelRequest.entries.action, { // not required, but for correct generation
  *   type: "cancel",
  *   cancels: [
  *     { a: 0, o: 12345 },
@@ -208,7 +154,7 @@ function largeIntToBigInt(obj: ValueType): ValueType {
   if (Array.isArray(obj)) return obj.map(largeIntToBigInt);
   if (typeof obj === "object" && obj !== null) {
     const result: Record<string, ValueType> = {};
-    for (const k in obj) result[k] = largeIntToBigInt(obj[k]);
+    for (const key in obj) result[key] = largeIntToBigInt(obj[key]);
     return result;
   }
   return obj;
@@ -218,9 +164,9 @@ function removeUndefinedKeys(obj: ValueType): ValueType {
   if (Array.isArray(obj)) return obj.map(removeUndefinedKeys);
   if (typeof obj === "object" && obj !== null) {
     const result: Record<string, ValueType> = {};
-    for (const k in obj) {
-      if (obj[k] !== undefined) {
-        result[k] = removeUndefinedKeys(obj[k]);
+    for (const key in obj) {
+      if (obj[key] !== undefined) {
+        result[key] = removeUndefinedKeys(obj[key]);
       }
     }
     return result;
@@ -233,12 +179,13 @@ function removeUndefinedKeys(obj: ValueType): ValueType {
  * @example
  * ```ts
  * import { signL1Action } from "@nktkas/hyperliquid/signing";
- * import { CancelRequest, parser } from "@nktkas/hyperliquid/api/exchange";
+ * import { CancelRequest } from "@nktkas/hyperliquid/api/exchange";
+ * import * as v from "npm:valibot";
  * import { privateKeyToAccount } from "npm:viem/accounts";
  *
  * const wallet = privateKeyToAccount("0x..."); // viem or ethers
  *
- * const action = parser(CancelRequest.entries.action)({ // for correct signature generation
+ * const action = v.parse(CancelRequest.entries.action, { // not required, but for correct generation
  *   type: "cancel",
  *   cancels: [
  *     { a: 0, o: 12345 },
@@ -264,28 +211,17 @@ export async function signL1Action(args: {
   action: Record<string, unknown> | unknown[];
   /** The current timestamp in ms. */
   nonce: number;
-  /** Indicates if the action is for the testnet. (default: false) */
+  /**
+   * 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 of the action in ms since the epoch. */
   expiresAfter?: number;
 }): Promise<Signature> {
-  const {
-    wallet,
-    action,
-    nonce,
-    isTestnet = false,
-    vaultAddress,
-    expiresAfter,
-  } = args;
-
-  const actionHash = createL1ActionHash({ action, nonce, vaultAddress, expiresAfter });
-  const message = {
-    source: isTestnet ? "b" : "a",
-    connectionId: actionHash,
-  };
-
+  const { wallet, action, nonce, isTestnet = false, vaultAddress, expiresAfter } = args;
   return await signTypedData({
     wallet,
     domain: {
@@ -301,7 +237,10 @@ export async function signL1Action(args: {
       ],
     },
     primaryType: "Agent",
-    message,
+    message: {
+      source: isTestnet ? "b" : "a",
+      connectionId: createL1ActionHash({ action, nonce, vaultAddress, expiresAfter }),
+    },
   });
 }
 
@@ -310,12 +249,13 @@ export async function signL1Action(args: {
  * @example
  * ```ts
  * import { signUserSignedAction } from "@nktkas/hyperliquid/signing";
- * import { ApproveAgentRequest, ApproveAgentTypes, parser } from "@nktkas/hyperliquid/api/exchange";
+ * import { ApproveAgentRequest, ApproveAgentTypes } from "@nktkas/hyperliquid/api/exchange";
+ * import * as v from "npm:valibot";
  * import { privateKeyToAccount } from "npm:viem/accounts";
  *
  * const wallet = privateKeyToAccount("0x..."); // viem or ethers
  *
- * const action = parser(ApproveAgentRequest.entries.action)({ // for correct signature generation
+ * const action = v.parse(ApproveAgentRequest.entries.action, { // not required, but for correct generation
  *   type: "approveAgent",
  *   signatureChainId: "0x66eee",
  *   hyperliquidChain: "Mainnet",
@@ -358,20 +298,34 @@ export async function signUserSignedAction(args: {
   };
 }): Promise<Signature> {
   let { wallet, action, types } = args;
+  const primaryType = Object.keys(types)[0];
 
-  if (action.type === "approveAgent" && !action.agentName) { // special case for `approveAgent`
-    action = { ...action, agentName: "" }; // set to empty string instead of null
+  // Special case: for `approveAgent`
+  // If `agentName` is null or undefined, set it to an empty string
+  if (action.type === "approveAgent" && !action.agentName) {
+    action = { ...action, agentName: "" };
   }
-  if ("payloadMultiSigUser" in action && "outerSigner" in action) { // special case for multi-sign payload
-    types = structuredClone(types); // for safe mutation
-    Object.values(types)[0].splice( // array mutation
-      1, // after `hyperliquidChain`
-      0, // do not remove any elements
-      { name: "payloadMultiSigUser", type: "address" },
-      { name: "outerSigner", type: "address" },
-    );
+
+  // Special case: for multi-sign payload
+  // If the action contains `payloadMultiSigUser` and `outerSigner`, add them to the types
+  if ("payloadMultiSigUser" in action && "outerSigner" in action) {
+    const primaryTypeArray = types[primaryType];
+    types = {
+      ...types,
+      [primaryType]: [
+        primaryTypeArray[0], // after `hyperliquidChain`
+        { name: "payloadMultiSigUser", type: "address" },
+        { name: "outerSigner", type: "address" },
+        ...primaryTypeArray.slice(1),
+      ],
+    };
   }
 
+  // Special case: for some wallets
+  // If the action has extra keys not in the types, filter them out
+  const knownKeys = new Set(types[primaryType].map((f) => f.name));
+  const message = Object.fromEntries(Object.entries(action).filter(([k]) => knownKeys.has(k)));
+
   return await signTypedData({
     wallet,
     domain: {
@@ -381,8 +335,8 @@ export async function signUserSignedAction(args: {
       verifyingContract: "0x0000000000000000000000000000000000000000",
     },
     types,
-    primaryType: Object.keys(types)[0],
-    message: action,
+    primaryType,
+    message,
   });
 }
 
@@ -391,14 +345,15 @@ export async function signUserSignedAction(args: {
  * @example
  * ```ts
  * import { signL1Action, signMultiSigAction } from "@nktkas/hyperliquid/signing";
- * import { MultiSigRequest, parser, ScheduleCancelRequest } from "@nktkas/hyperliquid/api/exchange";
+ * import { ScheduleCancelRequest } from "@nktkas/hyperliquid/api/exchange";
+ * import * as v from "npm:valibot";
  * import { privateKeyToAccount } from "npm:viem/accounts";
  *
  * const wallet = privateKeyToAccount("0x..."); // viem or ethers
  * const multiSigUser = "0x...";
  *
  * const nonce = Date.now();
- * const action = parser(ScheduleCancelRequest.entries.action)({ // for correct signature generation
+ * const action = v.parse(ScheduleCancelRequest.entries.action, { // not required, but for correct generation
  *   type: "scheduleCancel",
  *   time: Date.now() + 10000,
  * });
@@ -426,16 +381,16 @@ export async function signUserSignedAction(args: {
  * // }));
  *
  * // Then use signatures in the multi-sig action
- * const multiSigAction = parser(MultiSigRequest.entries.action)({
+ * const multiSigAction = {
  *   type: "multiSig",
- *   signatureChainId: "0x66eee",
+ *   signatureChainId: "0x66eee" as const,
  *   signatures,
  *   payload: {
  *     multiSigUser,
  *     outerSigner: wallet.address,
  *     action,
  *   },
- * });
+ * };
  * const multiSigSignature = await signMultiSigAction({ wallet, action: multiSigAction, nonce });
  *
  * // Send the multi-sig action to the Hyperliquid API
@@ -457,34 +412,23 @@ export async function signMultiSigAction(args: {
   };
   /** The current timestamp in ms. */
   nonce: number;
-  /** Indicates if the action is for the testnet. (default: false) */
+  /**
+   * 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 of the action in ms since the epoch. */
   expiresAfter?: number;
 }): Promise<Signature> {
-  let {
-    wallet,
-    action,
-    nonce,
-    isTestnet = false,
-    vaultAddress,
-    expiresAfter,
-  } = args;
+  let { wallet, action, nonce, isTestnet = false, vaultAddress, expiresAfter } = args;
 
   if ("type" in action) {
-    action = structuredClone(action); // for safe mutation
-    delete action.type;
+    const { type: _, ...actionWithoutType } = action;
+    action = actionWithoutType;
   }
 
-  const multiSigActionHash = createL1ActionHash({ action, nonce, vaultAddress, expiresAfter });
-  const message = {
-    hyperliquidChain: isTestnet ? "Testnet" : "Mainnet",
-    multiSigActionHash,
-    nonce,
-  };
-
   return await signTypedData({
     wallet,
     domain: {
@@ -501,6 +445,10 @@ export async function signMultiSigAction(args: {
       ],
     },
     primaryType: "HyperliquidTransaction:SendMultiSig",
-    message,
+    message: {
+      hyperliquidChain: isTestnet ? "Testnet" : "Mainnet",
+      multiSigActionHash: createL1ActionHash({ action, nonce, vaultAddress, expiresAfter }),
+      nonce,
+    },
   });
 }

package/src/src/transport/_base.ts

@@ -0,0 +1,57 @@
+import { HyperliquidError } from "../_base.js";
+
+/**
+ * Transport interface for executing requests to Hyperliquid servers.
+ *
+ * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint | Info endpoint}
+ * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint | Exchange endpoint}
+ * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/post-requests | WebSocket POST requests}
+ */
+export interface IRequestTransport {
+  /** Indicates this transport uses testnet endpoint(s). */
+  isTestnet: boolean;
+  /**
+   * Sends a request to the Hyperliquid API.
+   *
+   * @param endpoint - The API endpoint to send the request to.
+   * @param payload - The payload to send with the request.
+   * @param signal - {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the request.
+   *
+   * @returns A promise that resolves with parsed JSON response body.
+   */
+  request<T>(endpoint: "info" | "exchange" | "explorer", payload: unknown, signal?: AbortSignal): Promise<T>;
+}
+
+/**
+ * Transport interface for WebSocket subscriptions (real-time updates).
+ *
+ * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions | WebSocket subscriptions}
+ */
+export interface ISubscriptionTransport {
+  /**
+   * Subscribes to a Hyperliquid event channel.
+   *
+   * @param channel - The event channel to listen to.
+   * @param payload - The payload to send with the subscription request.
+   * @param listener - The function to call when the event is dispatched.
+   *
+   * @returns A promise that resolves with a {@link ISubscription} object to manage the subscription lifecycle.
+   */
+  subscribe<T>(channel: string, payload: unknown, listener: (data: CustomEvent<T>) => void): Promise<ISubscription>;
+}
+
+/** WebSocket subscription with failure signal. */
+export interface ISubscription {
+  /** Removes the event listener and unsubscribes from the event channel. */
+  unsubscribe(): Promise<void>;
+  /** {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} that is aborted if the subscription fails to restore after reconnection. */
+  failureSignal: AbortSignal;
+}
+
+/** Thrown when an error occurs at the transport level (e.g., timeout). */
+export class TransportError extends HyperliquidError {
+  constructor(message?: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "TransportError";
+  }
+}

package/src/src/transport/_polyfills.ts

@@ -1,7 +1,4 @@
 // deno-lint-ignore-file no-explicit-any
-/**
- * Polyfills for Node.js < 22 and React Native
- */
 
 export const Promise_ = /* @__PURE__ */ (() => {
   return {
@@ -15,6 +12,16 @@ export const Promise_ = /* @__PURE__ */ (() => {
   };
 })();
 
+/** @see https://developer.mozilla.org/en-US/docs/Web/API/DOMException */
+export const DOMException_ = /* @__PURE__ */ (() => {
+  return globalThis.DOMException || class DOMExceptionPolyfill extends Error {
+    constructor(message = "", name = "Error") {
+      super(message);
+      this.name = name;
+    }
+  };
+})();
+
 export const AbortSignal_ = /* @__PURE__ */ (() => {
   return {
     /** @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/any_static */
@@ -37,7 +44,7 @@ export const AbortSignal_ = /* @__PURE__ */ (() => {
     /** @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static */
     timeout: AbortSignal.timeout ? (ms: number) => AbortSignal.timeout(ms) : (ms: number) => {
       const controller = new AbortController();
-      setTimeout(() => controller.abort(new DOMException("Signal timed out.", "TimeoutError")), ms);
+      setTimeout(() => controller.abort(new DOMException_("Signal timed out.", "TimeoutError")), ms);
       return controller.signal;
     },
   };
@@ -45,11 +52,11 @@ export const AbortSignal_ = /* @__PURE__ */ (() => {
 
 /** @see https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent */
 export const CustomEvent_ = /* @__PURE__ */ (() => {
-  return globalThis.CustomEvent || class<T> extends Event {
-    readonly detail: T;
+  return globalThis.CustomEvent || class CustomEventPolyfill<T> extends Event {
+    readonly detail: T | null;
     constructor(type: string, eventInitDict?: CustomEventInit<T>) {
       super(type, eventInitDict);
-      this.detail = eventInitDict?.detail ?? null as T;
+      this.detail = eventInitDict?.detail ?? null;
     }
   };
 })();