@nktkas/hyperliquid 0.26.0 → 0.27.1

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

@@ -1,57 +0,0 @@
-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

@@ -1,244 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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/_nonce.ts

@@ -1,18 +0,0 @@
-/**
- * Nonce manager for generating unique nonces for signing transactions.
- * Uses the current timestamp, and increments if the timestamp is not greater than the last nonce.
- */
-class NonceManager {
-  private lastNonce = 0;
-  getNonce(): number {
-    let nonce = Date.now();
-    if (nonce <= this.lastNonce) {
-      nonce = ++this.lastNonce;
-    } else {
-      this.lastNonce = nonce;
-    }
-    return nonce;
-  }
-}
-
-export const globalNonceManager = /* @__PURE__ */ new NonceManager();

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

@@ -1,73 +0,0 @@
-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

@@ -1,88 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

@@ -1,104 +0,0 @@
-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);
-}