@nktkas/hyperliquid 0.25.8 → 0.26.0

package/src/api/exchange/_base/_errors.ts

@@ -0,0 +1,57 @@
+import { HyperliquidError } from "../../../_base.ts";
+import type { ErrorResponse } from "./_schemas.ts";
+import type { CancelResponse } from "../cancel.ts";
+import type { OrderResponse } from "../order.ts";
+import type { TwapOrderResponse } from "../twapOrder.ts";
+import type { TwapCancelResponse } from "../twapCancel.ts";
+import type { AnyResponse, AnySuccessResponse } from "./_types.ts";
+
+type AnyErrorResponse = ErrorResponse | CancelResponse | OrderResponse | TwapOrderResponse | TwapCancelResponse;
+
+/** Thrown when Exchange API returns an error response (e.g., insufficient funds). */
+export class ApiRequestError extends HyperliquidError {
+  response: AnyErrorResponse;
+  constructor(response: AnyErrorResponse) {
+    let message;
+    if (response.status === "err") {
+      // ErrorResponse
+      message = response.response;
+    } else {
+      if ("statuses" in response.response.data) {
+        // OrderResponse | CancelResponse
+        const errors = response.response.data.statuses.reduce<string[]>((acc, status, index) => {
+          if (typeof status === "object" && "error" in status) {
+            acc.push(`Order ${index}: ${status.error}`);
+          }
+          return acc;
+        }, []);
+        if (errors.length > 0) {
+          message = errors.join(", ");
+        }
+      } else {
+        // TwapOrderResponse | TwapCancelResponse
+        if (typeof response.response.data.status === "object" && "error" in response.response.data.status) {
+          message = response.response.data.status.error;
+        }
+      }
+    }
+
+    super(message || "An unknown error occurred while processing an API request. See `response` for more details.");
+    this.name = "ApiRequestError";
+    this.response = response;
+  }
+}
+
+export function assertSuccessResponse(response: AnyResponse): asserts response is AnySuccessResponse {
+  if (response.status === "err") {
+    throw new ApiRequestError(response as ErrorResponse);
+  } else if (response.response.type === "order" || response.response.type === "cancel") {
+    if (response.response.data.statuses.some((status) => typeof status === "object" && "error" in status)) {
+      throw new ApiRequestError(response as OrderResponse | CancelResponse);
+    }
+  } else if (response.response.type === "twapOrder" || response.response.type === "twapCancel") {
+    if (typeof response.response.data.status === "object" && "error" in response.response.data.status) {
+      throw new ApiRequestError(response as TwapOrderResponse | TwapCancelResponse);
+    }
+  }
+}

package/src/api/exchange/_base/_execute.ts

@@ -0,0 +1,244 @@
+import { getSemaphore } from "@henrygd/semaphore";
+import { getWalletAddress, signL1Action, signMultiSigAction, signUserSignedAction } from "../../../signing/mod.ts";
+import { assertSuccessResponse } from "./_errors.ts";
+import type { AnyResponse, AnySuccessResponse, ExchangeRequestConfig, MultiSignRequestConfig } from "./_types.ts";
+import { globalNonceManager } from "./_nonce.ts";
+import { getSignatureChainId } from "./_helpers.ts";
+
+export async function executeL1Action<T extends AnySuccessResponse>(
+  config: ExchangeRequestConfig | MultiSignRequestConfig,
+  request: {
+    action: Record<string, unknown>;
+    vaultAddress?: `0x${string}`;
+    expiresAfter?: number;
+  },
+  signal?: AbortSignal,
+): Promise<T> {
+  const { transport } = config;
+  const { action, vaultAddress, expiresAfter } = request;
+
+  // Sequential request execution to prevent nonce race conditions at the network layer
+  const walletAddress = "signers" in config
+    ? await getWalletAddress(config.signers[0])
+    : await getWalletAddress(config.wallet);
+  const walletKey = `@nktkas/hyperliquid:${walletAddress}:${config.transport.isTestnet}`;
+
+  const sem = getSemaphore(walletKey);
+  await sem.acquire();
+
+  // Main logic
+  try {
+    const nonce = globalNonceManager.getNonce();
+
+    // Multi-signature request
+    if ("signers" in config) {
+      const { signers, multiSigUser } = config;
+      const outerSigner = walletAddress;
+
+      // Sign an L1 action for each signer
+      const signatures = await Promise.all(signers.map(async (signer) => {
+        const signature = await signL1Action({
+          wallet: signer,
+          action: [multiSigUser, outerSigner, action],
+          nonce,
+          isTestnet: transport.isTestnet,
+          vaultAddress,
+          expiresAfter,
+        });
+        signature.r = signature.r.replace(/^0x0+/, "0x") as `0x${string}`;
+        signature.s = signature.s.replace(/^0x0+/, "0x") as `0x${string}`;
+        return signature;
+      }));
+
+      // Send a request via multi-sign action
+      return await executeMultiSigAction(
+        { ...config, wallet: signers[0] },
+        {
+          action: {
+            type: "multiSig",
+            signatureChainId: await getSignatureChainId(config),
+            signatures,
+            payload: { multiSigUser, outerSigner, action },
+          },
+          vaultAddress,
+          expiresAfter,
+          nonce,
+        },
+        signal,
+        false,
+      );
+    } else { // Single-signature request
+      const { wallet } = config;
+
+      // Sign an L1 action
+      const signature = await signL1Action({
+        wallet,
+        action,
+        nonce,
+        isTestnet: transport.isTestnet,
+        vaultAddress,
+        expiresAfter,
+      });
+
+      // Send a request
+      const response = await transport.request(
+        "exchange",
+        { action, signature, nonce, vaultAddress, expiresAfter },
+        signal,
+      ) as AnyResponse;
+      assertSuccessResponse(response);
+      return response as T;
+    }
+  } finally {
+    // Release semaphore
+    sem.release();
+  }
+}
+
+export async function executeUserSignedAction<T extends AnySuccessResponse>(
+  config: ExchangeRequestConfig | MultiSignRequestConfig,
+  request: {
+    action:
+      & {
+        signatureChainId: `0x${string}`;
+        [key: string]: unknown;
+      }
+      & (
+        | { nonce: number; time?: undefined }
+        | { time: number; nonce?: undefined }
+      );
+  },
+  types: {
+    [key: string]: {
+      name: string;
+      type: string;
+    }[];
+  },
+  signal?: AbortSignal,
+): Promise<T> {
+  const { transport } = config;
+  const { action } = request;
+
+  // Sequential request execution to prevent nonce race conditions at the network layer
+  const walletAddress = "signers" in config
+    ? await getWalletAddress(config.signers[0])
+    : await getWalletAddress(config.wallet);
+  const walletKey = `@nktkas/hyperliquid:${walletAddress}:${config.transport.isTestnet}`;
+
+  const sem = getSemaphore(walletKey);
+  await sem.acquire();
+
+  // Main logic
+  try {
+    const nonce = globalNonceManager.getNonce();
+    if ("time" in action) request.action.time = nonce;
+    if ("nonce" in action) request.action.nonce = nonce;
+
+    // Multi-signature request
+    if ("signers" in config) {
+      const { signers, multiSigUser } = config;
+      const outerSigner = walletAddress;
+
+      // Sign a user-signed action for each signer
+      const signatures = await Promise.all(signers.map(async (signer) => {
+        const signature = await signUserSignedAction({
+          wallet: signer,
+          action: {
+            payloadMultiSigUser: multiSigUser as `0x${string}`,
+            outerSigner,
+            ...action,
+          },
+          types,
+        });
+        signature.r = signature.r.replace(/^0x0+/, "0x") as `0x${string}`;
+        signature.s = signature.s.replace(/^0x0+/, "0x") as `0x${string}`;
+        return signature;
+      }));
+
+      // Send a request via multi-sign action
+      return await executeMultiSigAction(
+        { ...config, wallet: signers[0] },
+        {
+          action: {
+            type: "multiSig",
+            signatureChainId: action.signatureChainId,
+            signatures,
+            payload: { multiSigUser, outerSigner, action },
+          },
+          nonce,
+        },
+        signal,
+        false,
+      );
+    } else { // Single-signature request
+      const { wallet } = config;
+
+      // Sign a user-signed action
+      const signature = await signUserSignedAction({ wallet, action, types });
+
+      // Send a request
+      const response = await transport.request(
+        "exchange",
+        { action, signature, nonce },
+        signal,
+      ) as AnyResponse;
+      assertSuccessResponse(response);
+      return response as T;
+    }
+  } finally {
+    // Release semaphore and nonce manager
+    sem.release();
+  }
+}
+
+export async function executeMultiSigAction<T extends AnySuccessResponse>(
+  config: ExchangeRequestConfig,
+  request: {
+    action: {
+      signatureChainId: `0x${string}`;
+      [key: string]: unknown;
+    };
+    nonce: number;
+    vaultAddress?: `0x${string}`;
+    expiresAfter?: number;
+  },
+  signal?: AbortSignal,
+  semaphore = true,
+): Promise<T> {
+  const { transport, wallet } = config;
+  const { action, nonce, vaultAddress, expiresAfter } = request;
+
+  // Sequential request execution to prevent nonce race conditions at the network layer
+  let sem: ReturnType<typeof getSemaphore> | undefined;
+  if (semaphore) {
+    const walletAddress = await getWalletAddress(config.wallet);
+    const walletKey = `@nktkas/hyperliquid:${walletAddress}:${config.transport.isTestnet}`;
+    sem = getSemaphore(walletKey);
+    await sem.acquire();
+  }
+
+  // Main logic
+  try {
+    // Sign a multi-signature action
+    const signature = await signMultiSigAction({
+      wallet,
+      action,
+      nonce,
+      isTestnet: transport.isTestnet,
+      vaultAddress,
+      expiresAfter,
+    });
+
+    // Send a request
+    const response = await transport.request(
+      "exchange",
+      { action, signature, nonce, vaultAddress, expiresAfter },
+      signal,
+    ) as AnyResponse;
+    assertSuccessResponse(response);
+    return response as T;
+  } finally {
+    // Release semaphore if used
+    sem?.release();
+  }
+}

package/src/api/exchange/_base/_helpers.ts

@@ -0,0 +1,26 @@
+import { type AbstractWallet, getWalletChainId } from "../../../signing/mod.ts";
+import { Hex, type MaybePromise, parser } from "../../_base.ts";
+
+/** Get the signature chain ID from the config value / function or from the wallet. */
+export async function getSignatureChainId(
+  config:
+    | {
+      wallet: AbstractWallet;
+      signatureChainId?: string | (() => MaybePromise<string>);
+    }
+    | {
+      signers: readonly AbstractWallet[];
+      signatureChainId?: string | (() => MaybePromise<string>);
+    },
+): Promise<`0x${string}`> {
+  if ("signatureChainId" in config && config.signatureChainId) {
+    const signatureChainId = typeof config.signatureChainId === "string"
+      ? config.signatureChainId
+      : await config.signatureChainId();
+    return parser(Hex)(signatureChainId);
+  } else if ("wallet" in config) {
+    return await getWalletChainId(config.wallet);
+  } else {
+    return await getWalletChainId(config.signers[0]);
+  }
+}

package/src/api/exchange/_base/_schemas.ts

@@ -0,0 +1,73 @@
+import * as v from "valibot";
+import { Hex } from "../../_base.ts";
+
+/** ECDSA signature components for Ethereum typed data. */
+export const Signature = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** First 32-byte component of ECDSA signature. */
+      r: v.pipe(
+        v.pipe(Hex, v.length(66)),
+        v.description("First 32-byte component of ECDSA signature."),
+      ),
+      /** Second 32-byte component of ECDSA signature. */
+      s: v.pipe(
+        v.pipe(Hex, v.length(66)),
+        v.description("Second 32-byte component of ECDSA signature."),
+      ),
+      /** Recovery identifier. */
+      v: v.pipe(
+        v.union([v.literal(27), v.literal(28)]),
+        v.description("Recovery identifier."),
+      ),
+    }),
+    v.description("ECDSA signature components for Ethereum typed data."),
+  );
+})();
+export type Signature = v.InferOutput<typeof Signature>;
+
+/** Error response for failed operations. */
+export const ErrorResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Error status. */
+      status: v.pipe(
+        v.literal("err"),
+        v.description("Error status."),
+      ),
+      /** Error message. */
+      response: v.pipe(
+        v.string(),
+        v.description("Error message."),
+      ),
+    }),
+    v.description("Error response for failed operations."),
+  );
+})();
+export type ErrorResponse = v.InferOutput<typeof ErrorResponse>;
+
+/** Successful response without specific data. */
+export const SuccessResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Successful status. */
+      status: v.pipe(
+        v.literal("ok"),
+        v.description("Successful status."),
+      ),
+      /** Response details. */
+      response: v.pipe(
+        v.object({
+          /** Type of response. */
+          type: v.pipe(
+            v.literal("default"),
+            v.description("Type of response."),
+          ),
+        }),
+        v.description("Response details."),
+      ),
+    }),
+    v.description("Successful response without specific data."),
+  );
+})();
+export type SuccessResponse = v.InferOutput<typeof SuccessResponse>;

package/src/api/exchange/_base/_types.ts

@@ -0,0 +1,88 @@
+import type { IRequestTransport } from "../../../transport/base.ts";
+import type { AbstractWallet } from "../../../signing/_signTypedData.ts";
+import type { MaybePromise, Prettify } from "../../_base.ts";
+
+import type { CancelResponse, CancelSuccessResponse } from "../cancel.ts";
+import type { CreateSubAccountResponse } from "../createSubAccount.ts";
+import type { CreateVaultResponse } from "../createVault.ts";
+import type { OrderResponse, OrderSuccessResponse } from "../order.ts";
+import type { TwapCancelResponse, TwapCancelSuccessResponse } from "../twapCancel.ts";
+import type { TwapOrderResponse, TwapOrderSuccessResponse } from "../twapOrder.ts";
+import type { ErrorResponse, SuccessResponse } from "./_schemas.ts";
+
+export type AnyResponse =
+  | SuccessResponse
+  | ErrorResponse
+  | CancelResponse
+  | CreateSubAccountResponse
+  | CreateVaultResponse
+  | OrderResponse
+  | TwapOrderResponse
+  | TwapCancelResponse;
+export type AnySuccessResponse =
+  | SuccessResponse
+  | CancelSuccessResponse
+  | CreateSubAccountResponse
+  | CreateVaultResponse
+  | OrderSuccessResponse
+  | TwapOrderSuccessResponse
+  | TwapCancelSuccessResponse;
+
+/** Configuration for Exchange API requests. */
+export interface ExchangeRequestConfig<
+  T extends IRequestTransport = IRequestTransport,
+  W extends AbstractWallet = AbstractWallet,
+> {
+  /** The transport used to connect to the Hyperliquid Exchange API. */
+  transport: T;
+  /** The wallet used to sign requests. */
+  wallet: W;
+  /**
+   * The network that will be used to sign transactions.
+   * Must match the network of the {@link wallet}.
+   *
+   * Defaults to get chain id from wallet otherwise `0x1`.
+   */
+  signatureChainId?: string | (() => MaybePromise<string>);
+  /**
+   * Sets a default vaultAddress to be used if no vaultAddress is explicitly passed to a method.
+   * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#subaccounts-and-vaults
+   */
+  defaultVaultAddress?: string;
+  /**
+   * Sets a default expiresAfter to be used if no expiresAfter is explicitly passed to a method.
+   * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#expires-after
+   */
+  defaultExpiresAfter?: number | (() => MaybePromise<number>);
+}
+
+/** Configuration for Exchange API requests using multi-signature wallets. */
+export interface MultiSignRequestConfig<
+  T extends IRequestTransport = IRequestTransport,
+  S extends readonly AbstractWallet[] = AbstractWallet[],
+> extends Omit<ExchangeRequestConfig<T, S[0]>, "wallet"> {
+  /** The multi-signature account address. */
+  multiSigUser: string;
+  /** Array of wallets used for multi-signature operations. The first wallet acts as the leader. */
+  signers: S;
+}
+
+// deno-lint-ignore no-explicit-any
+type DistributiveOmit<T, K extends keyof any> = T extends unknown ? Omit<T, K> : never;
+export type ExtractRequestAction<T extends { action: Record<string, unknown> }> = Prettify<
+  T["action"] extends { signatureChainId: unknown }
+    ? DistributiveOmit<T["action"], "type" | "signatureChainId" | "hyperliquidChain" | "nonce" | "time"> // user-signed actions
+    : DistributiveOmit<T["action"], "type"> // L1 actions
+>;
+
+export type ExtractRequestOptions<T extends { action: Record<string, unknown> }> = Prettify<
+  & {
+    /**
+     * An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+     * If this option is set, the request can be canceled by calling [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort)
+     * on the corresponding [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+     */
+    signal?: AbortSignal;
+  }
+  & Omit<T, "action" | "nonce" | "signature">
+>;

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

@@ -0,0 +1,5 @@
+export * from "./_errors.ts";
+export * from "./_execute.ts";
+export * from "./_helpers.ts";
+export * from "./_schemas.ts";
+export * from "./_types.ts";

package/src/api/exchange/agentEnableDexAbstraction.ts

@@ -0,0 +1,104 @@
+import * as v from "valibot";
+import { parser, UnsignedInteger } from "../_base.ts";
+import {
+  type ExchangeRequestConfig,
+  executeL1Action,
+  type ExtractRequestOptions,
+  type MultiSignRequestConfig,
+  Signature,
+} from "./_base/mod.ts";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Enable HIP-3 DEX abstraction.
+ * @see null
+ */
+export const AgentEnableDexAbstractionRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.object({
+          /** Type of action. */
+          type: v.pipe(
+            v.literal("agentEnableDexAbstraction"),
+            v.description("Type of action."),
+          ),
+        }),
+        v.description("Action to perform."),
+      ),
+      /** Unique request identifier (current timestamp in ms). */
+      nonce: v.pipe(
+        UnsignedInteger,
+        v.description("Unique request identifier (current timestamp in ms)."),
+      ),
+      /** Cryptographic signature. */
+      signature: v.pipe(
+        Signature,
+        v.description("Cryptographic signature."),
+      ),
+      /** Expiration time of the action. */
+      expiresAfter: v.pipe(
+        v.optional(UnsignedInteger),
+        v.description("Expiration time of the action."),
+      ),
+    }),
+    v.description("Enable HIP-3 DEX abstraction request."),
+  );
+})();
+export type AgentEnableDexAbstractionRequest = v.InferOutput<typeof AgentEnableDexAbstractionRequest>;
+
+import { SuccessResponse } from "./_base/mod.ts";
+export { SuccessResponse };
+
+// -------------------- Function --------------------
+
+/** Request options for the {@linkcode agentEnableDexAbstraction} function. */
+export type AgentEnableDexAbstractionOptions = ExtractRequestOptions<
+  v.InferInput<typeof AgentEnableDexAbstractionRequest>
+>;
+
+/**
+ * Enable HIP-3 DEX abstraction.
+ * @param config - General configuration for Exchange API requests.
+ * @param params - Parameters specific to the API request.
+ * @param opts - Request execution options.
+ * @returns Successful response without specific data.
+ *
+ * @throws {ApiRequestError} When the API returns an unsuccessful response.
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see null
+ * @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 });
+ * ```
+ */
+export async function agentEnableDexAbstraction(
+  config: ExchangeRequestConfig | MultiSignRequestConfig,
+  opts?: AgentEnableDexAbstractionOptions,
+): Promise<SuccessResponse> {
+  const request = parser(AgentEnableDexAbstractionRequest)({
+    action: {
+      type: "agentEnableDexAbstraction",
+    },
+    nonce: 0, // Placeholder; actual nonce generated in `executeL1Action`
+    signature: { // Placeholder; actual signature generated in `executeL1Action`
+      r: "0x0000000000000000000000000000000000000000000000000000000000000000",
+      s: "0x0000000000000000000000000000000000000000000000000000000000000000",
+      v: 27,
+    },
+    expiresAfter: typeof config.defaultExpiresAfter === "number"
+      ? config.defaultExpiresAfter
+      : await config.defaultExpiresAfter?.(),
+  });
+  return await executeL1Action(config, request, opts?.signal);
+}