@nktkas/hyperliquid 0.30.3 → 0.32.0

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

@@ -0,0 +1,373 @@
+/**
+ * Execute helpers for L1 and user-signed Exchange API actions.
+ * @module
+ */
+
+import * as v from "valibot";
+import { parse } from "../../../../_base.js";
+import {
+  type AbstractWallet,
+  getWalletAddress,
+  getWalletChainId,
+  signL1Action,
+  signMultiSigAction,
+  signUserSignedAction,
+} from "../../../../signing/mod.js";
+import type { IRequestTransport } from "../../../../transport/mod.js";
+import { Address, Hex, UnsignedInteger } from "../../../_schemas.js";
+import { globalNonceManager } from "./_nonce.js";
+import { withLock } from "./_semaphore.js";
+import type { SignatureSchema } from "./commonSchemas.js";
+import { assertSuccessResponse } from "./errors.js";
+
+// ============================================================
+// Type Utilities
+// ============================================================
+
+type MaybePromise<T> = T | Promise<T>;
+
+// deno-lint-ignore ban-types
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+/** Options for any execute functions. */
+interface BaseOptions {
+  /** {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel a request. */
+  signal?: AbortSignal;
+}
+
+/** Extract request options from a request type (excludes action, nonce, signature). */
+export type ExtractRequestOptions<T extends { action: Record<string, unknown> }> = Prettify<
+  & BaseOptions
+  & Omit<T, "action" | "nonce" | "signature">
+>;
+
+// ============================================================
+// Config
+// ============================================================
+
+/** Base configuration shared by single-wallet and multi-sig configs. */
+interface BaseConfig<T extends IRequestTransport = IRequestTransport> {
+  /** The transport used to connect to the Hyperliquid Exchange API. */
+  transport: T;
+
+  /** Signature chain ID for EIP-712 signing, defaults to wallet's chain ID. */
+  signatureChainId?: `0x${string}` | (() => MaybePromise<`0x${string}`>);
+
+  /**
+   * Default vault address for vault-based operations, used when not specified in action options.
+   * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#subaccounts-and-vaults
+   */
+  defaultVaultAddress?: `0x${string}`;
+
+  /**
+   * Default expiration time in milliseconds, used when not specified in action options.
+   * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#expires-after
+   */
+  defaultExpiresAfter?: number | (() => MaybePromise<number>);
+
+  /**
+   * Custom nonce generator function.
+   * Defaults to a global manager using timestamp with auto-increment.
+   * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/nonces-and-api-wallets#hyperliquid-nonces
+   */
+  nonceManager?: (address: string) => MaybePromise<number>;
+}
+
+/** Configuration for single-wallet Exchange API requests. */
+export interface ExchangeSingleWalletConfig<T extends IRequestTransport = IRequestTransport> extends BaseConfig<T> {
+  /** The wallet used to sign requests. */
+  wallet: AbstractWallet;
+}
+
+/** Configuration for multi-signature Exchange API requests. */
+export interface ExchangeMultiSigConfig<T extends IRequestTransport = IRequestTransport> extends BaseConfig<T> {
+  /** Array of wallets for multi-sig. First wallet is the leader. */
+  signers: readonly [AbstractWallet, ...AbstractWallet[]];
+  /** The multi-signature account address. */
+  multiSigUser: `0x${string}`;
+}
+
+/** Union type for all Exchange API configurations. */
+export type ExchangeConfig = ExchangeSingleWalletConfig | ExchangeMultiSigConfig;
+
+// ============================================================
+// Execute L1 Action
+// ============================================================
+
+/**
+ * Execute an L1 action on the Hyperliquid Exchange.
+ *
+ * Handles both single-wallet and multi-sig signing.
+ *
+ * @param config Exchange API configuration
+ * @param action Action payload to execute
+ * @param options Additional options for the request
+ * @return API response
+ *
+ * @throws {ApiRequestError} If the API returns an error response
+ */
+export async function executeL1Action<T>(
+  config: ExchangeConfig,
+  action: Record<string, unknown>,
+  options?: {
+    vaultAddress?: string;
+    expiresAfter?: string | number;
+    signal?: AbortSignal;
+  },
+): Promise<T> {
+  const { transport } = config;
+  const leader = getLeader(config);
+  const walletAddress = await getWalletAddress(leader);
+
+  // 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) ?? globalNonceManager.getNonce(key));
+
+    // Validate and resolve options
+    const vaultAddress = parse(
+      v.optional(Address),
+      options?.vaultAddress ?? config.defaultVaultAddress,
+    );
+    const expiresAfter = parse(
+      v.optional(UnsignedInteger),
+      options?.expiresAfter ??
+        (typeof config.defaultExpiresAfter === "number"
+          ? config.defaultExpiresAfter
+          : await config.defaultExpiresAfter?.()),
+    );
+    const signal = options?.signal;
+
+    // Sign action (multi-sig or single wallet)
+    const [finalAction, signature] = "wallet" in config
+      ? [
+        action,
+        await signL1Action({
+          wallet: leader,
+          action,
+          nonce,
+          isTestnet: transport.isTestnet,
+          vaultAddress,
+          expiresAfter,
+        }),
+      ]
+      : await signMultiSigL1(config, action, walletAddress, nonce, vaultAddress, expiresAfter);
+
+    // Send request and validate response
+    const response = await transport.request("exchange", {
+      action: finalAction,
+      signature,
+      nonce,
+      vaultAddress,
+      expiresAfter,
+    }, signal);
+    assertSuccessResponse(response);
+    return response as T;
+  });
+}
+
+// ============================================================
+// Execute User-Signed Action
+// ============================================================
+
+/** Extract nonce field name from EIP-712 types ("nonce" or "time"). */
+function getNonceFieldName(types: Record<string, { name: string; type: string }[]>): "nonce" | "time" {
+  const primaryType = Object.keys(types)[0];
+  const field = types[primaryType].find((f) => f.name === "nonce" || f.name === "time") as {
+    name: "nonce" | "time";
+    type: string;
+  } | undefined;
+  return field?.name ?? "nonce";
+}
+
+/**
+ * Execute a user-signed action (EIP-712) on the Hyperliquid Exchange.
+ *
+ * Handles both single-wallet and multi-sig signing.
+ * Automatically adds signatureChainId, hyperliquidChain, and nonce/time.
+ *
+ * @param config Exchange API configuration
+ * @param action Action payload to execute
+ * @param types EIP-712 type definitions for signing
+ * @param options Additional options for the request
+ * @return API response
+ *
+ * @throws {ApiRequestError} If the API returns an error response
+ */
+export async function executeUserSignedAction<T>(
+  config: ExchangeConfig,
+  action: Record<string, unknown>,
+  types: Record<string, { name: string; type: string }[]>,
+  options?: {
+    signal?: AbortSignal;
+  },
+): Promise<T> {
+  const { transport } = config;
+  const leader = getLeader(config);
+  const walletAddress = await getWalletAddress(leader);
+
+  // 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) ?? globalNonceManager.getNonce(key));
+    const signal = options?.signal;
+
+    // Add system fields for user-signed actions
+    const { type, ...restAction } = action;
+    const nonceFieldName = getNonceFieldName(types);
+    const fullAction = { // Key order is important for multi-sig
+      type,
+      signatureChainId: await getSignatureChainId(config),
+      hyperliquidChain: transport.isTestnet ? "Testnet" : "Mainnet",
+      ...restAction,
+      [nonceFieldName]: nonce,
+    };
+
+    // Sign action (multi-sig or single wallet)
+    const [finalAction, signature] = "wallet" in config
+      ? [fullAction, await signUserSignedAction({ wallet: leader, action: fullAction, types })]
+      : await signMultiSigUserSigned(config, fullAction, types, walletAddress, nonce);
+
+    // Send request and validate response
+    const response = await transport.request("exchange", {
+      action: finalAction,
+      signature,
+      nonce,
+    }, signal);
+    assertSuccessResponse(response);
+    return response as T;
+  });
+}
+
+// ============================================================
+// Multi-sig signing
+// ============================================================
+
+/** Remove leading zeros from signature components (required by Hyperliquid). */
+function trimSignature(sig: SignatureSchema): SignatureSchema {
+  return {
+    r: sig.r.replace(/^0x0+/, "0x") as `0x${string}`,
+    s: sig.s.replace(/^0x0+/, "0x") as `0x${string}`,
+    v: sig.v,
+  };
+}
+
+/** Sign an L1 action with multi-sig. */
+async function signMultiSigL1(
+  config: ExchangeMultiSigConfig,
+  action: Record<string, unknown>,
+  outerSigner: `0x${string}`,
+  nonce: number,
+  vaultAddress?: `0x${string}`,
+  expiresAfter?: number,
+): Promise<[Record<string, unknown>, SignatureSchema]> {
+  const { transport: { isTestnet }, signers, multiSigUser } = config;
+  const multiSigUser_ = parse(Address, multiSigUser);
+  const outerSigner_ = parse(Address, outerSigner);
+
+  // Collect signatures from all signers
+  const signatures = await Promise.all(signers.map(async (signer) => {
+    const signature = await signL1Action({
+      wallet: signer,
+      action: [multiSigUser_, outerSigner_, action],
+      nonce,
+      isTestnet,
+      vaultAddress,
+      expiresAfter,
+    });
+    return trimSignature(signature);
+  }));
+
+  // Build multi-sig action wrapper
+  const multiSigAction = {
+    type: "multiSig",
+    signatureChainId: await getSignatureChainId(config),
+    signatures,
+    payload: {
+      multiSigUser: multiSigUser_,
+      outerSigner: outerSigner_,
+      action,
+    },
+  };
+
+  // Sign the wrapper with the leader
+  const signature = await signMultiSigAction({
+    wallet: signers[0],
+    action: multiSigAction,
+    nonce,
+    isTestnet,
+    vaultAddress,
+    expiresAfter,
+  });
+
+  return [multiSigAction, signature];
+}
+
+/** Sign a user-signed action (EIP-712) with multi-sig. */
+async function signMultiSigUserSigned(
+  config: ExchangeMultiSigConfig,
+  action: Record<string, unknown> & { signatureChainId: `0x${string}` },
+  types: Record<string, { name: string; type: string }[]>,
+  outerSigner: `0x${string}`,
+  nonce: number,
+): Promise<[Record<string, unknown>, SignatureSchema]> {
+  const { signers, multiSigUser, transport: { isTestnet } } = config;
+  const multiSigUser_ = parse(Address, multiSigUser);
+  const outerSigner_ = parse(Address, outerSigner);
+
+  // Collect signatures from all signers
+  const signatures = await Promise.all(signers.map(async (signer) => {
+    const signature = await signUserSignedAction({
+      wallet: signer,
+      action: {
+        payloadMultiSigUser: multiSigUser_,
+        outerSigner: outerSigner_,
+        ...action,
+      },
+      types,
+    });
+    return trimSignature(signature);
+  }));
+
+  // Build multi-sig action wrapper
+  const multiSigAction = {
+    type: "multiSig",
+    signatureChainId: await getSignatureChainId(config),
+    signatures,
+    payload: {
+      multiSigUser: multiSigUser_,
+      outerSigner: outerSigner_,
+      action,
+    },
+  };
+
+  // Sign the wrapper with the leader
+  const signature = await signMultiSigAction({
+    wallet: signers[0],
+    action: multiSigAction,
+    nonce,
+    isTestnet,
+  });
+
+  return [multiSigAction, signature];
+}
+
+// ============================================================
+// Helpers
+// ============================================================
+
+/** Get the leader wallet (first signer for the single wallet, or multi-sig). */
+function getLeader(config: ExchangeConfig): AbstractWallet {
+  return "wallet" in config ? config.wallet : config.signers[0];
+}
+
+/** Resolve signature chain ID from config or wallet. */
+async function getSignatureChainId(config: ExchangeConfig): Promise<`0x${string}`> {
+  if (config.signatureChainId) {
+    const id = typeof config.signatureChainId === "function"
+      ? await config.signatureChainId()
+      : config.signatureChainId;
+    return parse(Hex, id);
+  }
+  return getWalletChainId(getLeader(config));
+}

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

@@ -0,0 +1,84 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { UnsignedInteger } from "../../_schemas.js";
+import { type ErrorResponse, SignatureSchema, type SuccessResponse } from "./_base/commonSchemas.js";
+
+/**
+ * Enable HIP-3 DEX abstraction.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#enable-hip-3-dex-abstraction-agent
+ */
+export const AgentEnableDexAbstractionRequest = /* @__PURE__ */ (() => {
+  return v.object({
+    /** Action to perform. */
+    action: v.object({
+      /** Type of action. */
+      type: v.literal("agentEnableDexAbstraction"),
+    }),
+    /** Nonce (timestamp in ms) used to prevent replay attacks. */
+    nonce: UnsignedInteger,
+    /** ECDSA signature components. */
+    signature: SignatureSchema,
+    /** Expiration time of the action. */
+    expiresAfter: v.optional(UnsignedInteger),
+  });
+})();
+export type AgentEnableDexAbstractionRequest = v.InferOutput<typeof AgentEnableDexAbstractionRequest>;
+
+/**
+ * Successful response without specific data or error response.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#enable-hip-3-dex-abstraction-agent
+ */
+export type AgentEnableDexAbstractionResponse = SuccessResponse | ErrorResponse;
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import type { ExcludeErrorResponse } from "./_base/errors.js";
+import { type ExchangeConfig, executeL1Action, type ExtractRequestOptions } from "./_base/execute.js";
+
+/** Request options for the {@linkcode agentEnableDexAbstraction} function. */
+export type AgentEnableDexAbstractionOptions = ExtractRequestOptions<
+  v.InferInput<typeof AgentEnableDexAbstractionRequest>
+>;
+
+/** Successful variant of {@linkcode AgentEnableDexAbstractionResponse} without errors. */
+export type AgentEnableDexAbstractionSuccessResponse = ExcludeErrorResponse<AgentEnableDexAbstractionResponse>;
+
+/**
+ * Enable HIP-3 DEX abstraction.
+ *
+ * @param config General configuration for Exchange API requests.
+ * @param opts Request execution options.
+ * @return Successful response without specific data.
+ *
+ * @throws {ValidationError} When the request parameters fail validation (before sending).
+ * @throws {TransportError} When the transport layer throws an error.
+ * @throws {ApiRequestError} When the API returns an unsuccessful response.
+ *
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { agentEnableDexAbstraction } from "@nktkas/hyperliquid/api/exchange";
+ * import { privateKeyToAccount } from "npm:viem/accounts";
+ *
+ * const wallet = privateKeyToAccount("0x..."); // viem or ethers
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ *
+ * await agentEnableDexAbstraction({ transport, wallet });
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#enable-hip-3-dex-abstraction-agent
+ *
+ * @deprecated Use {@link agentSetAbstraction} instead.
+ */
+export function agentEnableDexAbstraction(
+  config: ExchangeConfig,
+  opts?: AgentEnableDexAbstractionOptions,
+): Promise<AgentEnableDexAbstractionSuccessResponse> {
+  return executeL1Action(config, { type: "agentEnableDexAbstraction" }, opts);
+}

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

@@ -0,0 +1,107 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { UnsignedInteger } from "../../_schemas.js";
+import { type ErrorResponse, SignatureSchema, type SuccessResponse } from "./_base/commonSchemas.js";
+
+/**
+ * Set User abstraction mode (method for agent wallet).
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#set-user-abstraction-agent
+ */
+export const AgentSetAbstractionRequest = /* @__PURE__ */ (() => {
+  return v.object({
+    /** Action to perform. */
+    action: v.object({
+      /** Type of action. */
+      type: v.literal("agentSetAbstraction"),
+      /**
+       * User abstraction mode.
+       * - `"i"`: disabled
+       * - `"u"`: unifiedAccount
+       * - `"p"`: portfolioMargin
+       */
+      abstraction: v.picklist(["i", "u", "p"]),
+    }),
+    /** Nonce (timestamp in ms) used to prevent replay attacks. */
+    nonce: UnsignedInteger,
+    /** ECDSA signature components. */
+    signature: SignatureSchema,
+    /** Expiration time of the action. */
+    expiresAfter: v.optional(UnsignedInteger),
+  });
+})();
+export type AgentSetAbstractionRequest = v.InferOutput<typeof AgentSetAbstractionRequest>;
+
+/**
+ * Successful response without specific data or error response.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#set-user-abstraction-agent
+ */
+export type AgentSetAbstractionResponse = SuccessResponse | ErrorResponse;
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { parse } from "../../../_base.js";
+import type { ExcludeErrorResponse } from "./_base/errors.js";
+import { type ExchangeConfig, executeL1Action, type ExtractRequestOptions } from "./_base/execute.js";
+
+/** Schema for user-provided action parameters (excludes system fields). */
+const AgentSetAbstractionParameters = /* @__PURE__ */ (() => {
+  return v.omit(
+    v.object(AgentSetAbstractionRequest.entries.action.entries),
+    ["type"],
+  );
+})();
+
+/** Action parameters for the {@linkcode agentSetAbstraction} function. */
+export type AgentSetAbstractionParameters = v.InferInput<typeof AgentSetAbstractionParameters>;
+
+/** Request options for the {@linkcode agentSetAbstraction} function. */
+export type AgentSetAbstractionOptions = ExtractRequestOptions<
+  v.InferInput<typeof AgentSetAbstractionRequest>
+>;
+
+/** Successful variant of {@linkcode AgentSetAbstractionResponse} without errors. */
+export type AgentSetAbstractionSuccessResponse = ExcludeErrorResponse<AgentSetAbstractionResponse>;
+
+/**
+ * Set User abstraction mode (method for agent wallet).
+ *
+ * @param config General configuration for Exchange API requests.
+ * @param params Parameters specific to the API request.
+ * @param opts Request execution options.
+ * @return Successful response without specific data.
+ *
+ * @throws {ValidationError} When the request parameters fail validation (before sending).
+ * @throws {TransportError} When the transport layer throws an error.
+ * @throws {ApiRequestError} When the API returns an unsuccessful response.
+ *
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { agentSetAbstraction } from "@nktkas/hyperliquid/api/exchange";
+ * import { privateKeyToAccount } from "npm:viem/accounts";
+ *
+ * const wallet = privateKeyToAccount("0x..."); // viem or ethers
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ *
+ * await agentSetAbstraction(
+ *   { transport, wallet },
+ *   { abstraction: "u" },
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#set-user-abstraction-agent
+ */
+export function agentSetAbstraction(
+  config: ExchangeConfig,
+  params: AgentSetAbstractionParameters,
+  opts?: AgentSetAbstractionOptions,
+): Promise<AgentSetAbstractionSuccessResponse> {
+  const action = parse(AgentSetAbstractionParameters, params);
+  return executeL1Action(config, { type: "agentSetAbstraction", ...action }, opts);
+}