@nktkas/hyperliquid 0.24.3 → 0.25.0-beta.2

package/src/src/signing/mod.ts

@@ -0,0 +1,572 @@
+/**
+ * This module contains functions for generating Hyperliquid transaction signatures.
+ *
+ * @example Signing an L1 action
+ * ```ts
+ * import { signL1Action } from "@nktkas/hyperliquid/signing";
+ * import { CancelRequest, parser } from "@nktkas/hyperliquid/schemas";
+ *
+ * const privateKey = "0x..."; // `viem`, `ethers`, or private key directly
+ *
+ * const action = parser(CancelRequest.entries.action)({ // for correct signature generation
+ *   type: "cancel",
+ *   cancels: [
+ *     { a: 0, o: 12345 },
+ *   ],
+ * });
+ * const nonce = Date.now();
+ *
+ * const signature = await signL1Action({ wallet: privateKey, action, nonce });
+ *
+ * // Send the signed 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, signature, nonce }),
+ * });
+ * const body = await response.json();
+ * ```
+ *
+ * @example Signing a user-signed action
+ * ```ts
+ * import { signUserSignedAction, userSignedActionEip712Types } from "@nktkas/hyperliquid/signing";
+ * import { ApproveAgentRequest, parser } from "@nktkas/hyperliquid/schemas";
+ *
+ * const privateKey = "0x..."; // `viem`, `ethers`, or private key directly
+ *
+ * const action = parser(ApproveAgentRequest.entries.action)({ // for correct signature generation
+ *   type: "approveAgent",
+ *   signatureChainId: "0x66eee",
+ *   hyperliquidChain: "Mainnet",
+ *   agentAddress: "0x...",
+ *   agentName: "Agent",
+ *   nonce: Date.now(),
+ * });
+ *
+ * const signature = await signUserSignedAction({
+ *   wallet: privateKey,
+ *   action,
+ *   types: userSignedActionEip712Types[action.type],
+ * });
+ *
+ * // Send the signed 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, signature, nonce: action.nonce }),
+ * });
+ * 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/schemas";
+ * import { privateKeyToAccount } from "npm:viem/accounts";
+ *
+ * const wallet = privateKeyToAccount("0x..."); // or `ethers`, private key directly
+ * 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: signerPrivKey as `0x${string}`,
+ *     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: signerPrivKey as `0x${string}`,
+ * //     action: {
+ * //       ...action,
+ * //       payloadMultiSigUser: multiSigUser,
+ * //       outerSigner: wallet.address,
+ * //     },
+ * //     types: userSignedActionEip712Types[action.type],
+ * //   });
+ * // }));
+ *
+ * // 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";
+import { etc } from "@noble/secp256k1";
+import { encode as encodeMsgpack } from "@msgpack/msgpack";
+import {
+    type AbstractWallet,
+    getWalletAddress,
+    getWalletChainId,
+    type Signature,
+    signTypedData,
+} from "./_signTypedData/mod.js";
+
+export { type AbstractWallet, getWalletAddress, getWalletChainId, type Signature };
+
+/** EIP-712 type definitions for user-signed actions. */
+export const userSignedActionEip712Types = {
+    approveAgent: {
+        "HyperliquidTransaction:ApproveAgent": [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "agentAddress", type: "address" },
+            { name: "agentName", type: "string" },
+            { name: "nonce", type: "uint64" },
+        ],
+    },
+    approveBuilderFee: {
+        "HyperliquidTransaction:ApproveBuilderFee": [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "maxFeeRate", type: "string" },
+            { name: "builder", type: "address" },
+            { name: "nonce", type: "uint64" },
+        ],
+    },
+    cDeposit: {
+        "HyperliquidTransaction:CDeposit": [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "wei", type: "uint64" },
+            { name: "nonce", type: "uint64" },
+        ],
+    },
+    convertToMultiSigUser: {
+        "HyperliquidTransaction:ConvertToMultiSigUser": [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "signers", type: "string" },
+            { name: "nonce", type: "uint64" },
+        ],
+    },
+    cWithdraw: {
+        "HyperliquidTransaction:CWithdraw": [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "wei", type: "uint64" },
+            { name: "nonce", type: "uint64" },
+        ],
+    },
+    multiSig: {
+        "HyperliquidTransaction:SendMultiSig": [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "multiSigActionHash", type: "bytes32" },
+            { name: "nonce", type: "uint64" },
+        ],
+    },
+    sendAsset: {
+        "HyperliquidTransaction:SendAsset": [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "destination", type: "string" },
+            { name: "sourceDex", type: "string" },
+            { name: "destinationDex", type: "string" },
+            { name: "token", type: "string" },
+            { name: "amount", type: "string" },
+            { name: "fromSubAccount", type: "string" },
+            { name: "nonce", type: "uint64" },
+        ],
+    },
+    spotSend: {
+        "HyperliquidTransaction:SpotSend": [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "destination", type: "string" },
+            { name: "token", type: "string" },
+            { name: "amount", type: "string" },
+            { name: "time", type: "uint64" },
+        ],
+    },
+    tokenDelegate: {
+        "HyperliquidTransaction:TokenDelegate": [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "validator", type: "address" },
+            { name: "wei", type: "uint64" },
+            { name: "isUndelegate", type: "bool" },
+            { name: "nonce", type: "uint64" },
+        ],
+    },
+    usdClassTransfer: {
+        "HyperliquidTransaction:UsdClassTransfer": [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "amount", type: "string" },
+            { name: "toPerp", type: "bool" },
+            { name: "nonce", type: "uint64" },
+        ],
+    },
+    usdSend: {
+        "HyperliquidTransaction:UsdSend": [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "destination", type: "string" },
+            { name: "amount", type: "string" },
+            { name: "time", type: "uint64" },
+        ],
+    },
+    withdraw3: {
+        "HyperliquidTransaction:Withdraw": [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "destination", type: "string" },
+            { name: "amount", type: "string" },
+            { name: "time", type: "uint64" },
+        ],
+    },
+};
+
+/**
+ * Create a hash of the L1 action.
+ * @example
+ * ```ts
+ * import { signL1Action } from "@nktkas/hyperliquid/signing";
+ * import { CancelRequest, parser } from "@nktkas/hyperliquid/schemas";
+ *
+ * const action = parser(CancelRequest.entries.action)({ // for correct signature generation
+ *   type: "cancel",
+ *   cancels: [
+ *     { a: 0, o: 12345 },
+ *   ],
+ * });
+ * const nonce = Date.now();
+ *
+ * const actionHash = createL1ActionHash({ action, nonce });
+ * ```
+ */
+export function createL1ActionHash(args: {
+    /** The action to be hashed (hash depends on key order). */
+    action: Record<string, unknown> | unknown[];
+    /** The current timestamp in ms. */
+    nonce: number;
+    /** Optional vault address used in the action. */
+    vaultAddress?: `0x${string}`;
+    /** Optional expiration time of the action in ms since the epoch. */
+    expiresAfter?: number;
+}): `0x${string}` {
+    const { action, nonce, vaultAddress, expiresAfter } = args;
+
+    // 1. Action
+    const actionBytes = encodeMsgpack(action);
+
+    // 2. Nonce
+    const nonceBytes = toUint64Bytes(nonce);
+
+    // 3. Vault address
+    const vaultMarker = vaultAddress ? new Uint8Array([1]) : new Uint8Array([0]);
+    const vaultBytes = vaultAddress ? etc.hexToBytes(vaultAddress.slice(2)) : new Uint8Array();
+
+    // 4. Expires after
+    const expiresMarker = expiresAfter !== undefined ? new Uint8Array([0]) : new Uint8Array();
+    const expiresBytes = expiresAfter !== undefined ? toUint64Bytes(expiresAfter) : new Uint8Array();
+
+    // Create a hash
+    const bytes = etc.concatBytes(
+        actionBytes,
+        nonceBytes,
+        vaultMarker,
+        vaultBytes,
+        expiresMarker,
+        expiresBytes,
+    );
+    const hash = keccak_256(bytes);
+    return `0x${etc.bytesToHex(hash)}`;
+}
+
+function toUint64Bytes(n: bigint | number | string): Uint8Array {
+    const bytes = new Uint8Array(8);
+    new DataView(bytes.buffer).setBigUint64(0, BigInt(n));
+    return bytes;
+}
+
+/**
+ * Sign an L1 action.
+ * @example
+ * ```ts
+ * import { signL1Action } from "@nktkas/hyperliquid/signing";
+ * import { CancelRequest, parser } from "@nktkas/hyperliquid/schemas";
+ *
+ * const privateKey = "0x..."; // `viem`, `ethers`, or private key directly
+ *
+ * const action = parser(CancelRequest.entries.action)({ // for correct signature generation
+ *   type: "cancel",
+ *   cancels: [
+ *     { a: 0, o: 12345 },
+ *   ],
+ * });
+ * const nonce = Date.now();
+ *
+ * const signature = await signL1Action({ wallet: privateKey, action, nonce });
+ *
+ * // Send the signed 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, signature, nonce }),
+ * });
+ * const body = await response.json();
+ * ```
+ */
+export async function signL1Action(args: {
+    /** Wallet to sign the action. */
+    wallet: AbstractWallet;
+    /** The action to be signed (hash depends on key order). */
+    action: Record<string, unknown> | unknown[];
+    /** The current timestamp in ms. */
+    nonce: number;
+    /** 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,
+    };
+
+    return await signTypedData({
+        wallet,
+        domain: {
+            name: "Exchange",
+            version: "1",
+            chainId: 1337, // hyperliquid requires chainId to be 1337
+            verifyingContract: "0x0000000000000000000000000000000000000000",
+        },
+        types: {
+            Agent: [
+                { name: "source", type: "string" },
+                { name: "connectionId", type: "bytes32" },
+            ],
+        },
+        primaryType: "Agent",
+        message,
+    });
+}
+
+/**
+ * Sign a user-signed action.
+ * @example
+ * ```ts
+ * import { signUserSignedAction, userSignedActionEip712Types } from "@nktkas/hyperliquid/signing";
+ * import { ApproveAgentRequest, parser } from "@nktkas/hyperliquid/schemas";
+ *
+ * const privateKey = "0x..."; // `viem`, `ethers`, or private key directly
+ *
+ * const action = parser(ApproveAgentRequest.entries.action)({ // for correct signature generation
+ *   type: "approveAgent",
+ *   signatureChainId: "0x66eee",
+ *   hyperliquidChain: "Mainnet",
+ *   agentAddress: "0x...",
+ *   agentName: "Agent",
+ *   nonce: Date.now(),
+ * });
+ *
+ * const signature = await signUserSignedAction({
+ *   wallet: privateKey,
+ *   action,
+ *   types: userSignedActionEip712Types[action.type],
+ * });
+ *
+ * // Send the signed 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, signature, nonce: action.nonce }),
+ * });
+ * const body = await response.json();
+ * ```
+ */
+export async function signUserSignedAction(args: {
+    /** Wallet to sign the action. */
+    wallet: AbstractWallet;
+    /** The action to be signed (hex strings must be in lower case). */
+    action:
+        & {
+            signatureChainId: `0x${string}`;
+            [key: string]: unknown;
+        }
+        // special case for multi-sign payload
+        & (
+            | { payloadMultiSigUser: `0x${string}`; outerSigner: `0x${string}` }
+            | { payloadMultiSigUser?: undefined; outerSigner?: undefined }
+        );
+    /** The types of the action (hash depends on key order). */
+    types: {
+        [key: string]: {
+            name: string;
+            type: string;
+        }[];
+    };
+}): Promise<Signature> {
+    let { wallet, action, types } = args;
+
+    if (action.type === "approveAgent" && !action.agentName) { // special case for `approveAgent`
+        action = { ...action, agentName: "" }; // set to empty string instead of null
+    }
+    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" },
+        );
+    }
+
+    return await signTypedData({
+        wallet,
+        domain: {
+            name: "HyperliquidSignTransaction",
+            version: "1",
+            chainId: parseInt(action.signatureChainId),
+            verifyingContract: "0x0000000000000000000000000000000000000000",
+        },
+        types,
+        primaryType: Object.keys(types)[0],
+        message: action,
+    });
+}
+
+/**
+ * Sign a multi-signature action.
+ * @example
+ * ```ts
+ * import { signL1Action, signMultiSigAction } from "@nktkas/hyperliquid/signing";
+ * import { MultiSigRequest, parser, ScheduleCancelRequest } from "@nktkas/hyperliquid/schemas";
+ * import { privateKeyToAccount } from "npm:viem/accounts";
+ *
+ * const wallet = privateKeyToAccount("0x..."); // or `ethers`, private key directly
+ * 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: signerPrivKey as `0x${string}`,
+ *     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: signerPrivKey as `0x${string}`,
+ * //     action: {
+ * //       ...action,
+ * //       payloadMultiSigUser: multiSigUser,
+ * //       outerSigner: wallet.address,
+ * //     },
+ * //     types: userSignedActionEip712Types[action.type],
+ * //   });
+ * // }));
+ *
+ * // 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();
+ * ```
+ */
+export async function signMultiSigAction(args: {
+    /** Wallet to sign the action. */
+    wallet: AbstractWallet;
+    /** The action to be signed (hash depends on key order). */
+    action: {
+        signatureChainId: `0x${string}`;
+        [key: string]: unknown;
+    };
+    /** The current timestamp in ms. */
+    nonce: number;
+    /** 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;
+
+    if ("type" in action) {
+        action = structuredClone(action); // for safe mutation
+        delete action.type;
+    }
+
+    const multiSigActionHash = createL1ActionHash({ action, nonce, vaultAddress, expiresAfter });
+    const message = {
+        hyperliquidChain: isTestnet ? "Testnet" : "Mainnet",
+        multiSigActionHash,
+        nonce,
+    };
+
+    return await signTypedData({
+        wallet,
+        domain: {
+            name: "HyperliquidSignTransaction",
+            version: "1",
+            chainId: parseInt(action.signatureChainId),
+            verifyingContract: "0x0000000000000000000000000000000000000000",
+        },
+        types: userSignedActionEip712Types.multiSig,
+        primaryType: Object.keys(userSignedActionEip712Types.multiSig)[0],
+        message,
+    });
+}

package/src/src/transports/base.ts

@@ -0,0 +1,54 @@
+import { HyperliquidError } from "../errors.js";
+
+/**
+ * Interface representing a REST transport.
+ * Handles communication with Hyperliquid API endpoints.
+ * @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 extends Partial<AsyncDisposable> {
+    /** 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 - An {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal}. If this option is set, the request can be canceled by calling {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort | abort()} on the corresponding {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/AbortController | AbortController}.
+     * @returns A promise that resolves with parsed JSON response body.
+     */
+    request<T>(endpoint: "info" | "exchange", payload: unknown, signal?: AbortSignal): Promise<T>;
+    request<T>(endpoint: "info" | "exchange" | "explorer", payload: unknown, signal?: AbortSignal): Promise<T>;
+}
+
+/**
+ * Interface representing an event subscription transport.
+ * Handles WebSocket subscriptions for real-time updates.
+ * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions | Websocket subscriptions}
+ */
+export interface ISubscriptionTransport extends Partial<AsyncDisposable> {
+    /**
+     * 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 Subscription} object to manage the subscription lifecycle.
+     */
+    subscribe<T>(channel: string, payload: unknown, listener: (data: CustomEvent<T>) => void): Promise<Subscription>;
+}
+
+/** Controls event subscription lifecycle. */
+export interface Subscription {
+    /** Unsubscribes from the event and sends an unsubscribe request to the server. */
+    unsubscribe(): Promise<void>;
+    /** Signal that aborts when resubscription fails during reconnection. */
+    resubscribeSignal?: AbortSignal;
+}
+
+/** Thrown when a transport error occurs. */
+export class TransportError extends HyperliquidError {
+    constructor(message?: string, options?: ErrorOptions) {
+        super(message, options);
+        this.name = "TransportError";
+    }
+}