@hfunlabs/hyperliquid 0.30.0-hfunlabs.1 → 0.30.2-hfunlabs.2

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

@@ -0,0 +1,146 @@
+// Copyright 2018-2025 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).
+   */
+  constructor(max: number = 1) {
+    if (max < 1) {
+      throw new TypeError(
+        `Cannot create semaphore as 'max' must be at least 1: current value is ${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/src/api/exchange/_methods/_base/_nonce.ts

@@ -1,5 +1,6 @@
 /**
  * Nonce manager for generating unique nonces per wallet address and network.
+ *
  * Uses lazy cleanup: removes entries when Date.now() > lastNonce.
  */
 class NonceManager {
@@ -24,5 +25,5 @@ class NonceManager {
   }
 }
 
-/** Default nonce manager, used when custom nonceManager is not provided in config. */
-export const defaultNonceManager = /* @__PURE__ */ new NonceManager();
+/** Global nonce manager instance. */
+export const globalNonceManager = /* @__PURE__ */ new NonceManager();

package/src/src/api/exchange/_methods/_base/_semaphore.ts

@@ -1,67 +1,32 @@
-// ============================================================
-// Semaphore
-// ============================================================
-
-// TODO: Replace with @std/async/semaphore if the PR (https://github.com/denoland/std/pull/6894) will be merged
-
-interface Node {
-  res: () => void;
-  next: Node | undefined;
-}
-
-export class Semaphore {
-  #max: number;
-  #count: number;
-  #head: Node | undefined;
-  #tail: Node | undefined;
-
-  constructor(max: number = 1) {
-    if (max < 1) {
-      throw new TypeError(
-        `Cannot create semaphore as 'max' must be at least 1: current value is ${max}`,
-      );
-    }
-    this.#count = this.#max = max;
-  }
-
-  acquire(): Promise<void> {
-    if (this.#count > 0) {
-      this.#count--;
-      return Promise.resolve();
-    }
-    return new Promise((res) => {
-      const node: Node = { res, next: undefined };
-      if (this.#tail) {
-        this.#tail = this.#tail.next = node;
-      } else {
-        this.#head = this.#tail = node;
-      }
-    });
-  }
-
-  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++;
-    }
-  }
-}
-
-// ============================================================
-// RefCounted Registry
-// ============================================================
+import { Semaphore } from "../../../../../deps/jsr.io/@std/async/1.0.16/unstable_semaphore.js";
 
+/**
+ * A reference-counted registry for lazily creating and reusing per-key values.
+ *
+ * @template K - Map key type.
+ * @template V - Stored value type.
+ */
 class RefCountedRegistry<K, V> {
   #map = new Map<K, { value: V; refs: number }>();
   #factory: () => V;
 
+  /**
+   * Creates a new registry instance.
+   *
+   * @param factory - Factory function used to create a new value when a key is first referenced.
+   */
   constructor(factory: () => V) {
     this.#factory = factory;
   }
 
+  /**
+   * Increments the reference count for a key and returns its value.
+   *
+   * If the key is not present, a new value is created via the factory.
+   *
+   * @param key - Registry key.
+   * @returns The value associated with the key.
+   */
   ref(key: K): V {
     let entry = this.#map.get(key);
     if (!entry) {
@@ -72,6 +37,13 @@ class RefCountedRegistry<K, V> {
     return entry.value;
   }
 
+  /**
+   * Decrements the reference count for a key.
+   *
+   * When the count reaches zero, the entry is removed.
+   *
+   * @param key - Registry key.
+   */
   unref(key: K): void {
     const entry = this.#map.get(key);
     if (!entry) return;
@@ -81,12 +53,15 @@ class RefCountedRegistry<K, V> {
   }
 }
 
-// ============================================================
-// Helper
-// ============================================================
-
 const semaphores = new RefCountedRegistry(() => new Semaphore(1));
 
+/**
+ * Acquires a lock for the given key, executes the provided async function, and releases the lock.
+ *
+ * @param key The key to lock on.
+ * @param fn The async function to execute while holding the lock.
+ * @returns The result of the async function.
+ */
 export async function withLock<K, T>(key: K, fn: () => Promise<T>): Promise<T> {
   const semaphore = semaphores.ref(key);
   await semaphore.acquire();

package/src/src/api/exchange/_methods/_base/execute.ts

@@ -10,7 +10,7 @@ import {
   signUserSignedAction,
 } from "../../../../signing/mod.js";
 import { assertSuccessResponse } from "./errors.js";
-import { defaultNonceManager } from "./_nonce.js";
+import { globalNonceManager } from "./_nonce.js";
 import { withLock } from "./_semaphore.js";
 import type { SignatureSchema } from "./commonSchemas.js";
 
@@ -81,8 +81,20 @@ export interface ExchangeMultiSigConfig<T extends IRequestTransport = IRequestTr
   multiSigUser: `0x${string}`;
 }
 
+/**
+ * Configuration for external signing Exchange API requests.
+ * Use this when signing is handled externally (e.g., by a gRPC server or HSM).
+ * The transport receives unsigned action payloads and is responsible for signing.
+ */
+export interface ExchangeExternalSigningConfig<T extends IRequestTransport = IRequestTransport> extends BaseConfig<T> {
+  /** Marks this config as external signing mode. */
+  externalSigning: true;
+  /** The user address for nonce management. */
+  userAddress: `0x${string}`;
+}
+
 /** Union type for all Exchange API configurations. */
-export type ExchangeConfig = ExchangeSingleWalletConfig | ExchangeMultiSigConfig;
+export type ExchangeConfig = ExchangeSingleWalletConfig | ExchangeMultiSigConfig | ExchangeExternalSigningConfig;
 
 // =============================================================
 // Execute L1 Action
@@ -90,7 +102,7 @@ export type ExchangeConfig = ExchangeSingleWalletConfig | ExchangeMultiSigConfig
 
 /**
  * Execute an L1 action on the Hyperliquid Exchange.
- * Handles both single-wallet and multi-sig signing.
+ * Handles single-wallet, multi-sig, and external signing.
  */
 export async function executeL1Action<T>(
   config: ExchangeConfig,
@@ -102,13 +114,14 @@ export async function executeL1Action<T>(
   },
 ): Promise<T> {
   const { transport } = config;
-  const leader = getLeader(config);
-  const walletAddress = await getWalletAddress(leader);
+  const walletAddress = "externalSigning" in config
+    ? v.parse(Address, config.userAddress)
+    : await getWalletAddress(getLeader(config));
 
   // Semaphore ensures requests arrive at server in nonce order (prevents out-of-order delivery)
   const key = `${walletAddress}:${transport.isTestnet}`;
   return await withLock(key, async () => {
-    const nonce = await (config.nonceManager?.(walletAddress) ?? defaultNonceManager.getNonce(key));
+    const nonce = await (config.nonceManager?.(walletAddress) ?? globalNonceManager.getNonce(key));
 
     // Validate and resolve options
     const vaultAddress = v.parse(
@@ -124,7 +137,22 @@ export async function executeL1Action<T>(
     );
     const signal = options?.signal;
 
+    // Handle external signing - send unsigned action to transport
+    if ("externalSigning" in config) {
+      const response = await transport.request("exchange", {
+        action,
+        nonce,
+        vaultAddress,
+        expiresAfter,
+        isTestnet: transport.isTestnet,
+        userAddress: walletAddress,
+      }, signal);
+      assertSuccessResponse(response);
+      return response as T;
+    }
+
     // Sign action (multi-sig or single wallet)
+    const leader = getLeader(config);
     const [finalAction, signature] = "wallet" in config
       ? [
         action,
@@ -168,7 +196,7 @@ function getNonceFieldName(types: Record<string, { name: string; type: string }[
 
 /**
  * Execute a user-signed action (EIP-712) on the Hyperliquid Exchange.
- * Handles both single-wallet and multi-sig signing.
+ * Handles single-wallet, multi-sig, and external signing.
  * Automatically adds signatureChainId, hyperliquidChain, and nonce/time.
  */
 export async function executeUserSignedAction<T>(
@@ -180,27 +208,43 @@ export async function executeUserSignedAction<T>(
   },
 ): Promise<T> {
   const { transport } = config;
-  const leader = getLeader(config);
-  const walletAddress = await getWalletAddress(leader);
+  const walletAddress = "externalSigning" in config
+    ? v.parse(Address, config.userAddress)
+    : await getWalletAddress(getLeader(config));
 
   // Semaphore ensures requests arrive at server in nonce order (prevents out-of-order delivery)
   const key = `${walletAddress}:${transport.isTestnet}`;
   return withLock(key, async () => {
-    const nonce = await (config.nonceManager?.(walletAddress) ?? defaultNonceManager.getNonce(key));
+    const nonce = await (config.nonceManager?.(walletAddress) ?? globalNonceManager.getNonce(key));
     const signal = options?.signal;
 
     // Add system fields for user-signed actions
     const { type, ...restAction } = action;
     const nonceFieldName = getNonceFieldName(types);
+    const signatureChainId = await getSignatureChainId(config);
     const fullAction = { // key order is important for multi-sig
       type,
-      signatureChainId: await getSignatureChainId(config),
+      signatureChainId,
       hyperliquidChain: transport.isTestnet ? "Testnet" : "Mainnet",
       ...restAction,
       [nonceFieldName]: nonce,
     };
 
+    // Handle external signing - send unsigned action with types to transport
+    if ("externalSigning" in config) {
+      const response = await transport.request("exchange", {
+        action: fullAction,
+        types,
+        nonce,
+        isTestnet: transport.isTestnet,
+        userAddress: walletAddress,
+      }, signal);
+      assertSuccessResponse(response);
+      return response as T;
+    }
+
     // Sign action (multi-sig or single wallet)
+    const leader = getLeader(config);
     const [finalAction, signature] = "wallet" in config
       ? [fullAction, await signUserSignedAction({ wallet: leader, action: fullAction, types })]
       : await signMultiSigUserSigned(config, fullAction, types, walletAddress, nonce);
@@ -334,7 +378,7 @@ async function signMultiSigUserSigned(
 // =============================================================
 
 /** Get the leader wallet (first signer for the single wallet, or multi-sig). */
-function getLeader(config: ExchangeConfig): AbstractWallet {
+function getLeader(config: ExchangeSingleWalletConfig | ExchangeMultiSigConfig): AbstractWallet {
   return "wallet" in config ? config.wallet : config.signers[0];
 }
 
@@ -346,5 +390,9 @@ async function getSignatureChainId(config: ExchangeConfig): Promise<`0x${string}
       : config.signatureChainId;
     return v.parse(Hex, id);
   }
+  // External signing defaults to chain ID 1 (mainnet) if not specified
+  if ("externalSigning" in config) {
+    return "0x1";
+  }
   return getWalletChainId(getLeader(config));
 }

package/src/src/api/exchange/_methods/order.ts

@@ -141,11 +141,11 @@ export const OrderRequest = /* @__PURE__ */ (() => {
                 Address,
                 v.description("Builder address."),
               ),
-              /** Builder fee in 0.1bps (1 = 0.0001%). */
+              /** Builder fee in 0.1bps (1 = 0.0001%). Max 100 for perps (0.1%), 1000 for spot (1%). */
               f: v.pipe(
                 UnsignedInteger,
-                v.maxValue(100),
-                v.description("Builder fee in 0.1bps (1 = 0.0001%)."),
+                v.maxValue(1000),
+                v.description("Builder fee in 0.1bps (1 = 0.0001%). Max 100 for perps (0.1%), 1000 for spot (1%)."),
               ),
             })),
             v.description("Builder fee."),
@@ -259,6 +259,8 @@ export const OrderResponse = /* @__PURE__ */ (() => {
                         v.description("Error message."),
                       ),
                     }),
+                    v.literal("waitingForFill"),
+                    v.literal("waitingForTrigger"),
                   ]),
                 ),
                 v.description("Array of statuses for each placed order."),

package/src/src/api/exchange/client.ts

@@ -681,7 +681,11 @@ export class ExchangeClient<C extends ExchangeConfig = ExchangeSingleWalletConfi
 // Type Re-exports
 // =============================================================
 
-export type { ExchangeMultiSigConfig, ExchangeSingleWalletConfig } from "./_methods/_base/execute.js";
+export type {
+  ExchangeExternalSigningConfig,
+  ExchangeMultiSigConfig,
+  ExchangeSingleWalletConfig,
+} from "./_methods/_base/execute.js";
 export { ApiRequestError } from "./_methods/_base/errors.js";
 
 export type {

package/src/src/api/exchange/mod.ts

@@ -37,7 +37,11 @@
  * @module
  */
 
-export type { ExchangeMultiSigConfig, ExchangeSingleWalletConfig } from "./_methods/_base/execute.js";
+export type {
+  ExchangeExternalSigningConfig,
+  ExchangeMultiSigConfig,
+  ExchangeSingleWalletConfig,
+} from "./_methods/_base/execute.js";
 export { ApiRequestError } from "./_methods/_base/errors.js";
 
 export * from "./_methods/agentEnableDexAbstraction.js";

package/src/src/api/info/_methods/userFunding.ts

@@ -25,7 +25,7 @@ export const UserFundingRequest = /* @__PURE__ */ (() => {
       ),
       /** Start time (in ms since epoch). */
       startTime: v.pipe(
-        UnsignedInteger,
+        v.nullish(UnsignedInteger),
         v.description("Start time (in ms since epoch)."),
       ),
       /** End time (in ms since epoch). */
@@ -131,7 +131,7 @@ export type UserFundingParameters = Omit<v.InferInput<typeof UserFundingRequest>
  *
  * const data = await userFunding(
  *   { transport },
- *   { user: "0x...", startTime: Date.now() - 1000 * 60 * 60 * 24 },
+ *   { user: "0x..." },
  * );
  * ```
  *

package/src/src/api/subscription/_methods/assetCtxs.ts

@@ -80,6 +80,8 @@ export type AssetCtxsParameters = Omit<v.InferInput<typeof AssetCtxsRequest>, "t
  *   (data) => console.log(data),
  * );
  * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
  */
 export function assetCtxs(
   config: SubscriptionConfig,

package/src/src/api/subscription/_methods/clearinghouseState.ts

@@ -92,6 +92,8 @@ export type ClearinghouseStateParameters = Omit<v.InferInput<typeof Clearinghous
  *   (data) => console.log(data),
  * );
  * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
  */
 export function clearinghouseState(
   config: SubscriptionConfig,

package/src/src/api/subscription/_methods/explorerBlock.ts

@@ -89,6 +89,8 @@ import type { ISubscription } from "../../../transport/mod.js";
  *   (data) => console.log(data),
  * );
  * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
  */
 export function explorerBlock(
   config: SubscriptionConfig,

package/src/src/api/subscription/_methods/explorerTxs.ts

@@ -59,6 +59,8 @@ import type { ISubscription } from "../../../transport/mod.js";
  *   (data) => console.log(data),
  * );
  * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
  */
 export function explorerTxs(
   config: SubscriptionConfig,

package/src/src/api/subscription/_methods/twapStates.ts

@@ -21,6 +21,11 @@ export const TwapStatesRequest = /* @__PURE__ */ (() => {
         Address,
         v.description("User address."),
       ),
+      /** DEX name (empty string for main dex). */
+      dex: v.pipe(
+        v.optional(v.string()),
+        v.description("DEX name (empty string for main dex)."),
+      ),
     }),
     v.description("Subscribe to TWAP states updates for a specific user."),
   );
@@ -87,6 +92,8 @@ export type TwapStatesParameters = Omit<v.InferInput<typeof TwapStatesRequest>,
  *   (data) => console.log(data),
  * );
  * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
  */
 export function twapStates(
   config: SubscriptionConfig,
@@ -96,9 +103,10 @@ export function twapStates(
   const payload = v.parse(TwapStatesRequest, {
     type: "twapStates",
     ...params,
+    dex: params.dex ?? "", // same value as in response
   });
   return config.transport.subscribe<TwapStatesEvent>(payload.type, payload, (e) => {
-    if (e.detail.user === payload.user) {
+    if (e.detail.user === payload.user && e.detail.dex === payload.dex) {
       listener(e.detail);
     }
   });

package/src/src/signing/_privateKeySigner.ts

@@ -1,4 +1,4 @@
-import { addr, signTyped } from "micro-eth-signer";
+import { addr, signTyped } from "../../deps/jsr.io/@paulmillr/micro-eth-signer/0.18.1/src/index.js";
 import type { AbstractViemLocalAccount } from "./_abstractWallet.js";
 
 /**

package/src/src/signing/mod.ts

@@ -63,7 +63,7 @@
 
 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 { encode as encodeMsgpack, type ValueType } from "../../deps/jsr.io/@std/msgpack/1.0.3/encode.js";
 import { type AbstractWallet, type Signature, signTypedData } from "./_abstractWallet.js";
 
 export {

package/esm/deps/jsr.io/@std/msgpack/1.0.3/decode.d.ts

@@ -1,21 +0,0 @@
-import type { ValueType } from "./encode.js";
-/**
- * Decode a value from the {@link https://msgpack.org/ | MessagePack} binary format.
- *
- * If the input is not in valid message pack format, an error will be thrown.
- *
- * @example Usage
- * ```ts
- * import { decode } from "@std/msgpack/decode";
- * import { assertEquals } from "@std/assert";
- *
- * const encoded = new Uint8Array([163, 72, 105, 33]);
- *
- * assertEquals(decode(encoded), "Hi!");
- * ```
- *
- * @param data MessagePack binary data.
- * @returns Decoded value from the MessagePack binary data.
- */
-export declare function decode(data: Uint8Array): ValueType;
-//# sourceMappingURL=decode.d.ts.map

package/esm/deps/jsr.io/@std/msgpack/1.0.3/decode.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../../../../../../src/deps/jsr.io/@std/msgpack/1.0.3/decode.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,CAclD"}