@nktkas/hyperliquid 0.25.7 → 0.25.8

package/src/src/api/exchange/withdraw3.ts

@@ -6,7 +6,6 @@ import {
   type ExtractRequestAction,
   type ExtractRequestOptions,
   getSignatureChainId,
-  globalNonceManager,
   type MultiSignRequestConfig,
   Signature,
 } from "./_base/mod.js";
@@ -123,16 +122,20 @@ export async function withdraw3(
   params: DeepImmutable<Withdraw3Parameters>,
   opts?: Withdraw3Options,
 ): Promise<SuccessResponse> {
-  const action = parser(Withdraw3Request.entries.action)({
-    type: "withdraw3",
-    hyperliquidChain: config.transport.isTestnet ? "Testnet" : "Mainnet",
-    signatureChainId: await getSignatureChainId(config),
-    time: globalNonceManager.getNonce(),
-    ...params,
+  const request = parser(Withdraw3Request)({
+    action: {
+      type: "withdraw3",
+      hyperliquidChain: config.transport.isTestnet ? "Testnet" : "Mainnet",
+      signatureChainId: await getSignatureChainId(config),
+      time: 0, // Placeholder; actual nonce generated in `executeUserSignedAction` to prevent race conditions
+      ...params,
+    },
+    nonce: 0, // Placeholder; actual nonce generated in `executeUserSignedAction` to prevent race conditions
+    signature: { // Placeholder; actual signature generated in `executeUserSignedAction`
+      r: "0x0000000000000000000000000000000000000000000000000000000000000000",
+      s: "0x0000000000000000000000000000000000000000000000000000000000000000",
+      v: 27,
+    },
   });
-  return await executeUserSignedAction(
-    config,
-    { action, types: Withdraw3Types },
-    opts?.signal,
-  );
+  return await executeUserSignedAction(config, request, Withdraw3Types, opts?.signal);
 }

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

@@ -2,7 +2,7 @@ import type { MaybePromise, OmitFirst, OverloadedParameters } from "../_base.js"
 import type { ExchangeRequestConfig, MultiSignRequestConfig } from "./_base/mod.js";
 import type { IRequestTransport } from "../../transport/base.js";
 import type { AbstractWallet } from "../../signing/mod.js";
-import { PrivateKeyEIP712Signer } from "../../utils/_minimalEIP712Signer.js";
+import { PrivateKeyEIP712Signer } from "../../utils/_eip712.js";
 
 import { agentEnableDexAbstraction } from "./agentEnableDexAbstraction.js";
 import { approveAgent } from "./approveAgent.js";
@@ -19,6 +19,7 @@ import { cSignerAction } from "./cSignerAction.js";
 import { cValidatorAction } from "./cValidatorAction.js";
 import { cWithdraw } from "./cWithdraw.js";
 import { evmUserModify } from "./evmUserModify.js";
+import { linkStakingUser } from "./linkStakingUser.js";
 import { modify } from "./modify.js";
 import { multiSig } from "./multiSig.js";
 import { order } from "./order.js";
@@ -64,6 +65,7 @@ export type { CSignerActionOptions, CSignerActionParameters } from "./cSignerAct
 export type { CValidatorActionOptions, CValidatorActionParameters } from "./cValidatorAction.js";
 export type { CWithdrawOptions, CWithdrawParameters } from "./cWithdraw.js";
 export type { EvmUserModifyOptions, EvmUserModifyParameters } from "./evmUserModify.js";
+export type { LinkStakingUserOptions, LinkStakingUserParameters } from "./linkStakingUser.js";
 export type { ModifyOptions, ModifyParameters } from "./modify.js";
 export type { MultiSigOptions, MultiSigParameters } from "./multiSig.js";
 export type { OrderOptions, OrderParameters } from "./order.js";
@@ -118,7 +120,6 @@ export class ExchangeClient<
   signatureChainId?: string | (() => MaybePromise<string>);
   defaultVaultAddress?: string;
   defaultExpiresAfter?: number | (() => MaybePromise<number>);
-  sequentialRequests?: boolean;
 
   /**
    * Initialises a new instance.
@@ -181,7 +182,6 @@ export class ExchangeClient<
     this.defaultVaultAddress = args.defaultVaultAddress;
     this.defaultExpiresAfter = args.defaultExpiresAfter;
     this.signatureChainId = args.signatureChainId;
-    this.sequentialRequests = args.sequentialRequests;
   }
 
   /**
@@ -609,7 +609,7 @@ export class ExchangeClient<
    * Configure block type for EVM transactions.
    * @param params - Parameters specific to the API request.
    * @param opts - Request execution options.
-   * @returns Response for creating a sub-account.
+   * @returns Successful response without specific data.
    *
    * @throws {ApiRequestError} When the API returns an unsuccessful response.
    * @throws {TransportError} When the transport layer throws an error.
@@ -630,6 +630,31 @@ export class ExchangeClient<
     return evmUserModify(this, ...args);
   }
 
+  /**
+   * Link staking and trading accounts for fee discount attribution.
+   * @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 https://hyperliquid.gitbook.io/hyperliquid-docs/trading/fees#staking-linking
+   * @example
+   * ```ts
+   * import * as hl from "@nktkas/hyperliquid";
+   *
+   * const pk = "0x..."; // viem, ethers or private key
+   * const transport = new hl.HttpTransport(); // or `WebSocketTransport`
+   *
+   * const client = new hl.ExchangeClient({ transport, wallet: pk });
+   * await client.linkStakingUser({ user: "0x...", isFinalize: false });
+   * ```
+   */
+  linkStakingUser(...args: OmitFirst<OverloadedParameters<typeof linkStakingUser>>) {
+    return linkStakingUser(this, ...args);
+  }
+
   /**
    * Modify an order.
    * @param params - Parameters specific to the API request.
@@ -1492,7 +1517,7 @@ export class MultiSignClient<
   /**
    * @note Is the first wallet from {@linkcode signers}. Changing the property also changes the first element in the {@linkcode signers} array.
    */
-  declare readonly wallet: S[0];
+  declare wallet: S[0];
 
   /**
    * Initialises a new multi-signature client instance.

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

@@ -55,6 +55,7 @@ export * from "./cSignerAction.js";
 export * from "./cValidatorAction.js";
 export * from "./cWithdraw.js";
 export * from "./evmUserModify.js";
+export * from "./linkStakingUser.js";
 export * from "./modify.js";
 export * from "./multiSig.js";
 export * from "./order.js";

package/src/src/api/info/meta.ts

@@ -73,6 +73,13 @@ export const MetaResponse = /* @__PURE__ */ (() => {
                 v.optional(v.literal(true)),
                 v.description("Indicates if the universe is delisted."),
               ),
+              /** Trading margin mode constraint. */
+              marginMode: v.pipe(
+                v.optional(
+                  v.union([v.literal("strictIsolated"), v.literal("noCross")]),
+                ),
+                v.description("Trading margin mode constraint."),
+              ),
             }),
             v.description("Trading universe parameters for perpetual asset."),
           ),

package/src/src/api/info/perpDexs.ts

@@ -63,6 +63,16 @@ export const PerpDexsResponse = /* @__PURE__ */ (() => {
               v.array(v.tuple([v.string(), v.string()])),
               v.description("Mapping of asset names to their streaming open interest caps."),
             ),
+            /** List of delegated function names and their authorized executor addresses. */
+            subDeployers: v.pipe(
+              v.array(
+                v.tuple([
+                  v.string(),
+                  v.array(Address),
+                ]),
+              ),
+              v.description("List of delegated function names and their authorized executor addresses."),
+            ),
           }),
           v.description(" Perpetual dex metadata."),
         ),

package/src/src/api/info/spotClearinghouseState.ts

@@ -2,6 +2,8 @@ import * as v from "valibot";
 import { Address, type DeepImmutable, parser, UnsignedDecimal, UnsignedInteger } from "../_base.js";
 import type { InfoRequestConfig } from "./_types.js";
 
+import { BalanceSchema } from "../_common_schemas.js";
+
 // -------------------- Schemas --------------------
 
 /**
@@ -41,39 +43,7 @@ export const SpotClearinghouseStateResponse = /* @__PURE__ */ (() => {
     v.object({
       /** Balance for each token. */
       balances: v.pipe(
-        v.array(
-          /** Balance for a specific spot token. */
-          v.pipe(
-            v.object({
-              /** Asset symbol. */
-              coin: v.pipe(
-                v.string(),
-                v.description("Asset symbol."),
-              ),
-              /** Unique identifier for the token. */
-              token: v.pipe(
-                UnsignedInteger,
-                v.description("Unique identifier for the token."),
-              ),
-              /** Total balance. */
-              total: v.pipe(
-                UnsignedDecimal,
-                v.description("Total balance."),
-              ),
-              /** Amount on hold. */
-              hold: v.pipe(
-                UnsignedDecimal,
-                v.description("Amount on hold."),
-              ),
-              /** Entry notional value. */
-              entryNtl: v.pipe(
-                UnsignedDecimal,
-                v.description("Entry notional value."),
-              ),
-            }),
-            v.description("Balance for a specific spot token."),
-          ),
-        ),
+        v.array(BalanceSchema),
         v.description("Balance for each token."),
       ),
       /** Escrowed balances. */

package/src/src/api/info/userFees.ts

@@ -225,7 +225,52 @@ export const UserFeesResponse = /* @__PURE__ */ (() => {
         v.nullable(v.unknown()),
         v.description("Timestamp when next trial becomes available."),
       ),
-      stakingLink: v.nullable(v.unknown()),
+      /**
+       * Permanent link between staking and trading accounts.
+       * Staking user gains full control of trading account funds.
+       * Staking user forfeits own fee discounts.
+       */
+      stakingLink: v.pipe(
+        v.nullable(
+          v.object({
+            /**
+             * Linked account address:
+             * - When queried by staking account: contains trading account address.
+             * - When queried by trading account: contains staking account address.
+             */
+            stakingUser: v.pipe(
+              Address,
+              v.description(
+                "Linked account address:" +
+                  "\n- When queried by staking account: contains trading account address." +
+                  "\n- When queried by trading account: contains staking account address.",
+              ),
+            ),
+            /**
+             * Link status:
+             * - `requested` = link initiated by trading user, awaiting staking user confirmation.
+             * - `stakingUser` = response queried by staking account.
+             * - `tradingUser` = response queried by trading account.
+             */
+            type: v.pipe(
+              v.union([
+                v.literal("requested"),
+                v.literal("stakingUser"),
+                v.literal("tradingUser"),
+              ]),
+              v.description(
+                "Link status:" +
+                  "\n- `requested` = link initiated by trading user, awaiting staking user confirmation" +
+                  "\n- `stakingUser` = response queried by staking account" +
+                  "\n- `tradingUser` = response queried by trading account",
+              ),
+            ),
+          }),
+        ),
+        v.description(
+          "Permanent link between staking and trading accounts. Staking user gains full control of trading account funds. Staking user forfeits own fee discounts.",
+        ),
+      ),
       /** Active staking discount details. */
       activeStakingDiscount: v.pipe(
         v.object({

package/src/src/api/subscription/spotState.ts

@@ -0,0 +1,96 @@
+import * as v from "valibot";
+import { Address, type DeepImmutable, parser } from "../_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
+import type { Subscription } from "../../transport/base.js";
+
+import { BalanceSchema } from "../_common_schemas.js";
+
+// -------------------- Schemas --------------------
+
+/** Subscription to spot state events for a specific user. */
+export const SpotStateRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of subscription. */
+      type: v.pipe(
+        v.literal("spotState"),
+        v.description("Type of subscription."),
+      ),
+      /** User address. */
+      user: v.pipe(
+        Address,
+        v.description("User address."),
+      ),
+    }),
+    v.description("Subscription to spot state events for a specific user."),
+  );
+})();
+export type SpotStateRequest = v.InferOutput<typeof SpotStateRequest>;
+
+/** Event of user spot state. */
+export const SpotStateEvent = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** User address. */
+      user: v.pipe(
+        Address,
+        v.description("User address."),
+      ),
+      /** Spot state of the user. */
+      spotState: v.pipe(
+        v.object({
+          /** Balance for each token. */
+          balances: v.pipe(
+            v.array(BalanceSchema),
+            v.description("Balance for each token."),
+          ),
+        }),
+        v.description("Spot state of the user."),
+      ),
+    }),
+    v.description("Event of user spot state."),
+  );
+})();
+export type SpotStateEvent = v.InferOutput<typeof SpotStateEvent>;
+
+// -------------------- Function --------------------
+
+/** Request parameters for the {@linkcode spotState} function. */
+export type SpotStateParameters = Omit<v.InferInput<typeof SpotStateRequest>, "type">;
+
+/**
+ * Subscribe to spot state updates for a specific user.
+ * @param config - General configuration for Subscription API subscriptions.
+ * @param params - Parameters specific to the API subscription.
+ * @param listener - A callback function to be called when the event is received.
+ * @returns A request-promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
+ *
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ * @example
+ * ```ts
+ * import { WebSocketTransport } from "@nktkas/hyperliquid";
+ * import { spotState } from "@nktkas/hyperliquid/api/subscription";
+ *
+ * const transport = new WebSocketTransport();
+ *
+ * const sub = await spotState(
+ *   { transport },
+ *   { user: "0x..." },
+ *   (data) => console.log(data),
+ * );
+ * ```
+ */
+export function spotState(
+  config: SubscriptionRequestConfig,
+  params: DeepImmutable<SpotStateParameters>,
+  listener: (data: SpotStateEvent) => void,
+): Promise<Subscription> {
+  const payload = parser(SpotStateRequest)({ type: "spotState", user: params.user });
+  return config.transport.subscribe<SpotStateEvent>(payload.type, payload, (e) => {
+    if (e.detail.user === payload.user) {
+      listener(e.detail);
+    }
+  });
+}

package/src/src/api/subscription/~client.ts

@@ -16,6 +16,7 @@ import { l2Book } from "./l2Book.js";
 import { notification } from "./notification.js";
 import { openOrders } from "./openOrders.js";
 import { orderUpdates } from "./orderUpdates.js";
+import { spotState } from "./spotState.js";
 import { trades } from "./trades.js";
 import { userEvents } from "./userEvents.js";
 import { userFills } from "./userFills.js";
@@ -68,6 +69,7 @@ export type {
   OrderUpdatesEvent as WsOrderUpdatesEvent,
   OrderUpdatesParameters as WsOrderUpdatesParameters,
 } from "./orderUpdates.js";
+export type { SpotStateEvent as WsSpotStateEvent, SpotStateParameters as WsSpotStateParameters } from "./spotState.js";
 export type { TradesEvent as WsTradesEvent, TradesParameters as WsTradesParameters } from "./trades.js";
 export type {
   UserEventsEvent as WsUserEventsEvent,
@@ -454,6 +456,29 @@ export class SubscriptionClient<
     return orderUpdates(this, ...args);
   }
 
+  /**
+   * Subscribe to spot state updates for a specific user.
+   * @param params - Parameters specific to the API subscription.
+   * @param listener - A callback function to be called when the event is received.
+   * @returns A request-promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
+   *
+   * @throws {TransportError} When the transport layer throws an error.
+   *
+   * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+   * @example
+   * ```ts
+   * import * as hl from "@nktkas/hyperliquid";
+   *
+   * const transport = new hl.WebSocketTransport();
+   *
+   * const client = new hl.SubscriptionClient({ transport });
+   * const sub = await client.spotState({ user: "0x..." }, (data) => console.log(data));
+   * ```
+   */
+  spotState(...args: OmitFirst<OverloadedParameters<typeof spotState>>) {
+    return spotState(this, ...args);
+  }
+
   /**
    * Subscribe to real-time trade updates for a specific asset.
    * @param params - Parameters specific to the API subscription.

package/src/src/api/subscription/~mod.ts

@@ -40,6 +40,7 @@ export * from "./l2Book.js";
 export * from "./notification.js";
 export * from "./openOrders.js";
 export * from "./orderUpdates.js";
+export * from "./spotState.js";
 export * from "./trades.js";
 export * from "./userEvents.js";
 export * from "./userFills.js";

package/src/src/signing/_signTypedData.ts

@@ -218,7 +218,7 @@ export async function getWalletChainId(wallet: AbstractWallet): Promise<`0x${str
   }
 }
 
-/** Get the wallet address from various wallet types. */
+/** Get the lowercase wallet address from various wallet types. */
 export async function getWalletAddress(wallet: AbstractWallet): Promise<`0x${string}`> {
   if (isAbstractViemWallet(wallet)) {
     if ("address" in wallet && wallet.address) {

package/src/src/utils/{_minimalEIP712Signer.ts → _eip712.ts}

@@ -1,5 +1,3 @@
-// -------------------- EIP-712 --------------------
-
 import { keccak_256 } from "@noble/hashes/sha3.js";
 import * as secp from "@noble/secp256k1";
 
@@ -19,7 +17,7 @@ export interface Domain {
 }
 
 /** Signs typed data with a private key. */
-async function signTypedData(args: {
+export async function signTypedData(args: {
   privateKey: string | Uint8Array;
   domain?: Domain;
   types: Types;
@@ -36,20 +34,18 @@ async function signTypedData(args: {
 
   const hash = hashTypedData({ domain, types, primaryType, message });
 
-  const signature = await secp.signAsync(
-    hash,
-    privateKey instanceof Uint8Array ? privateKey : secp.etc.hexToBytes(cleanHex(privateKey)),
-    { prehash: false, format: "recovered" },
-  );
+  const pk = typeof privateKey === "string" ? secp.etc.hexToBytes(cleanHex(privateKey)) : privateKey;
+  const sigr = await secp.signAsync(hash, pk, { prehash: false, format: "recovered" });
 
-  const r = secp.etc.bytesToHex(signature.slice(1, 33));
-  const s = secp.etc.bytesToHex(signature.slice(33, 65));
-  const v = (signature[0] + 27).toString(16).padStart(2, "0");
+  const r = secp.etc.bytesToHex(sigr.slice(1, 33));
+  const s = secp.etc.bytesToHex(sigr.slice(33, 65));
+  const v = (sigr[0] + 27).toString(16).padStart(2, "0");
 
   return `0x${r}${s}${v}`;
 }
 
-function hashTypedData(args: {
+/** Hashes typed data according to EIP-712. */
+export function hashTypedData(args: {
   domain: Domain;
   types: Types;
   primaryType: string;
@@ -211,7 +207,7 @@ function cleanHex(hex: string): string {
   return hex.startsWith("0x") ? hex.slice(2) : hex;
 }
 
-// -------------------- Interaction API --------------------
+// -------------------- For SDK --------------------
 
 import type { AbstractViemLocalAccount } from "../signing/mod.js";
 
@@ -221,30 +217,27 @@ export class PrivateKeyEIP712Signer implements AbstractViemLocalAccount {
   address: `0x${string}`;
   constructor(privateKey: string | Uint8Array) {
     this.#privateKey = privateKey;
-    this.address = privateKeyToAddress(privateKey); // and validate the key
-  }
-  signTypedData(
-    params: {
-      domain: Domain;
-      types: Types;
-      primaryType: string;
-      message: Record<string, unknown>;
-    },
-  ): Promise<`0x${string}`> {
+    this.address = privateKeyToAddress(privateKey); // and validate the private key
+  }
+  signTypedData(params: {
+    domain: Domain;
+    types: Types;
+    primaryType: string;
+    message: Record<string, unknown>;
+  }): Promise<`0x${string}`> {
     return signTypedData({ privateKey: this.#privateKey, ...params });
   }
 }
 
 function privateKeyToAddress(privateKey: string | Uint8Array): `0x${string}` {
   const pk = typeof privateKey === "string" ? secp.etc.hexToBytes(cleanHex(privateKey)) : privateKey;
-
   const publicKey = secp.getPublicKey(pk, false);
-  const publicKeyWithoutPrefix = publicKey.slice(1);
+  return publicKeyToAddress(publicKey);
+}
 
+function publicKeyToAddress(publicKey: Uint8Array): `0x${string}` {
+  const publicKeyWithoutPrefix = publicKey.slice(1);
   const hash = keccak_256(publicKeyWithoutPrefix);
-
   const addressBytes = hash.slice(-20);
-  const address = secp.etc.bytesToHex(addressBytes);
-
-  return `0x${address}`;
+  return `0x${secp.etc.bytesToHex(addressBytes)}`;
 }