@nktkas/hyperliquid 0.25.9 → 0.26.0

package/src/api/exchange/cSignerAction.ts

@@ -0,0 +1,136 @@
+import * as v from "valibot";
+import { type DeepImmutable, parser, UnsignedInteger } from "../_base.ts";
+import {
+  type ExchangeRequestConfig,
+  executeL1Action,
+  type ExtractRequestAction,
+  type ExtractRequestOptions,
+  type MultiSignRequestConfig,
+  Signature,
+} from "./_base/mod.ts";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Jail or unjail self as a validator signer.
+ * @see null
+ */
+export const CSignerActionRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.union([
+          v.object({
+            /** Type of action. */
+            type: v.pipe(
+              v.literal("CSignerAction"),
+              v.description("Type of action."),
+            ),
+            /** Jail the signer. */
+            jailSelf: v.pipe(
+              v.null(),
+              v.description("Jail the signer."),
+            ),
+          }),
+          v.object({
+            /** Type of action. */
+            type: v.pipe(
+              v.literal("CSignerAction"),
+              v.description("Type of action."),
+            ),
+            /** Unjail the signer. */
+            unjailSelf: v.pipe(
+              v.null(),
+              v.description("Unjail the signer."),
+            ),
+          }),
+        ]),
+        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("Jail or unjail self as a validator signer."),
+  );
+})();
+export type CSignerActionRequest = v.InferOutput<typeof CSignerActionRequest>;
+
+import { SuccessResponse } from "./_base/mod.ts";
+export { SuccessResponse };
+
+// -------------------- Function --------------------
+
+/** Action parameters for the {@linkcode CSignerAction} function. */
+export type CSignerActionParameters = ExtractRequestAction<v.InferInput<typeof CSignerActionRequest>>;
+/** Request options for the {@linkcode CSignerAction} function. */
+export type CSignerActionOptions = ExtractRequestOptions<v.InferInput<typeof CSignerActionRequest>>;
+
+/**
+ * Jail or unjail self as a validator signer.
+ * @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 { cSignerAction } from "@nktkas/hyperliquid/api/exchange";
+ * import { privateKeyToAccount } from "npm:viem/accounts";
+ *
+ * const wallet = privateKeyToAccount("0x..."); // viem or ethers
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ *
+ * // Jail self
+ * await cSignerAction(
+ *   { transport, wallet },
+ *   { jailSelf: null },
+ * );
+ *
+ * // Unjail self
+ * await cSignerAction(
+ *   { transport, wallet },
+ *   { unjailSelf: null },
+ * );
+ * ```
+ */
+export async function cSignerAction(
+  config: ExchangeRequestConfig | MultiSignRequestConfig,
+  params: DeepImmutable<CSignerActionParameters>,
+  opts?: CSignerActionOptions,
+): Promise<SuccessResponse> {
+  const request = parser(CSignerActionRequest)({
+    action: {
+      type: "CSignerAction",
+      ...params,
+    },
+    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);
+}

package/src/api/exchange/cValidatorAction.ts

@@ -0,0 +1,276 @@
+import * as v from "valibot";
+import { Address, type DeepImmutable, parser, UnsignedInteger } from "../_base.ts";
+import {
+  type ExchangeRequestConfig,
+  executeL1Action,
+  type ExtractRequestAction,
+  type ExtractRequestOptions,
+  type MultiSignRequestConfig,
+  Signature,
+} from "./_base/mod.ts";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Action related to validator management.
+ * @see null
+ */
+export const CValidatorActionRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.union([
+          v.object({
+            /** Type of action. */
+            type: v.pipe(
+              v.literal("CValidatorAction"),
+              v.description("Type of action."),
+            ),
+            /** Profile changes to apply. */
+            changeProfile: v.pipe(
+              v.object({
+                /** Validator node IP address. */
+                node_ip: v.pipe(
+                  v.nullable(
+                    v.object({
+                      /** IP address. */
+                      Ip: v.pipe(
+                        v.string(),
+                        v.ip(),
+                        v.description("IP address."),
+                      ),
+                    }),
+                  ),
+                  v.description("Validator node IP address."),
+                ),
+                /** Validator name. */
+                name: v.pipe(
+                  v.nullable(v.string()),
+                  v.description("Validator name."),
+                ),
+                /** Validator description. */
+                description: v.pipe(
+                  v.nullable(v.string()),
+                  v.description("Validator description."),
+                ),
+                /** Validator jail status. */
+                unjailed: v.pipe(
+                  v.boolean(),
+                  v.description("Validator jail status."),
+                ),
+                /** Enable or disable delegations. */
+                disable_delegations: v.pipe(
+                  v.nullable(v.boolean()),
+                  v.description("Enable or disable delegations."),
+                ),
+                /** Commission rate in basis points (1 = 0.0001%). */
+                commission_bps: v.pipe(
+                  v.nullable(UnsignedInteger),
+                  v.description("Commission rate in basis points (1 = 0.0001%)."),
+                ),
+                /** Signer address. */
+                signer: v.pipe(
+                  v.nullable(Address),
+                  v.description("Signer address."),
+                ),
+              }),
+              v.description("Profile changes to apply."),
+            ),
+          }),
+          v.object({
+            /** Type of action. */
+            type: v.pipe(
+              v.literal("CValidatorAction"),
+              v.description("Type of action."),
+            ),
+            /** Registration parameters. */
+            register: v.pipe(
+              v.object({
+                /** Validator profile information. */
+                profile: v.pipe(
+                  v.object({
+                    /** Validator node IP address. */
+                    node_ip: v.pipe(
+                      v.object({
+                        /** IP address. */
+                        Ip: v.pipe(
+                          v.string(),
+                          v.ip(),
+                          v.description("IP address."),
+                        ),
+                      }),
+                      v.description("Validator node IP address."),
+                    ),
+                    /** Validator name. */
+                    name: v.pipe(
+                      v.string(),
+                      v.description("Validator name."),
+                    ),
+                    /** Validator description. */
+                    description: v.pipe(
+                      v.string(),
+                      v.description("Validator description."),
+                    ),
+                    /** Whether delegations are disabled. */
+                    delegations_disabled: v.pipe(
+                      v.boolean(),
+                      v.description("Whether delegations are disabled."),
+                    ),
+                    /** Commission rate in basis points (1 = 0.0001%). */
+                    commission_bps: v.pipe(
+                      UnsignedInteger,
+                      v.description("Commission rate in basis points (1 = 0.0001%)."),
+                    ),
+                    /** Signer address. */
+                    signer: v.pipe(
+                      Address,
+                      v.description("Signer address."),
+                    ),
+                  }),
+                  v.description("Validator profile information."),
+                ),
+                /** Initial jail status. */
+                unjailed: v.pipe(
+                  v.boolean(),
+                  v.description("Initial jail status."),
+                ),
+                /** Initial stake amount in wei. */
+                initial_wei: v.pipe(
+                  UnsignedInteger,
+                  v.description("Initial stake amount in wei."),
+                ),
+              }),
+              v.description("Registration parameters."),
+            ),
+          }),
+          v.object({
+            /** Type of action. */
+            type: v.pipe(
+              v.literal("CValidatorAction"),
+              v.description("Type of action."),
+            ),
+            /** Unregister the validator. */
+            unregister: v.pipe(
+              v.null(),
+              v.description("Unregister the validator."),
+            ),
+          }),
+        ]),
+        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("Action related to validator management."),
+  );
+})();
+export type CValidatorActionRequest = v.InferOutput<typeof CValidatorActionRequest>;
+
+import { SuccessResponse } from "./_base/mod.ts";
+export { SuccessResponse };
+
+// -------------------- Function --------------------
+
+/** Action parameters for the {@linkcode CValidatorAction} function. */
+export type CValidatorActionParameters = ExtractRequestAction<v.InferInput<typeof CValidatorActionRequest>>;
+/** Request options for the {@linkcode CValidatorAction} function. */
+export type CValidatorActionOptions = ExtractRequestOptions<v.InferInput<typeof CValidatorActionRequest>>;
+
+/**
+ * Action related to validator management.
+ * @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 { cValidatorAction } from "@nktkas/hyperliquid/api/exchange";
+ * import { privateKeyToAccount } from "npm:viem/accounts";
+ *
+ * const wallet = privateKeyToAccount("0x..."); // viem or ethers
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ *
+ * // Change validator profile
+ * await cValidatorAction(
+ *   { transport, wallet },
+ *   {
+ *     changeProfile: {
+ *       node_ip: { Ip: "1.2.3.4" },
+ *       name: "...",
+ *       description: "...",
+ *       unjailed: true,
+ *       disable_delegations: false,
+ *       commission_bps: null,
+ *       signer: null,
+ *     },
+ *   },
+ * );
+ *
+ * // Register a new validator
+ * await cValidatorAction(
+ *   { transport, wallet },
+ *   {
+ *     register: {
+ *       profile: {
+ *         node_ip: { Ip: "1.2.3.4" },
+ *         name: "...",
+ *         description: "...",
+ *         delegations_disabled: true,
+ *         commission_bps: 1,
+ *         signer: "0x...",
+ *       },
+ *       unjailed: false,
+ *       initial_wei: 1,
+ *     },
+ *   },
+ * );
+ *
+ * // Unregister a validator
+ * await cValidatorAction(
+ *   { transport, wallet },
+ *   { unregister: null },
+ * );
+ * ```
+ */
+export async function cValidatorAction(
+  config: ExchangeRequestConfig | MultiSignRequestConfig,
+  params: DeepImmutable<CValidatorActionParameters>,
+  opts?: CValidatorActionOptions,
+): Promise<SuccessResponse> {
+  const request = parser(CValidatorActionRequest)({
+    action: {
+      type: "CValidatorAction",
+      ...params,
+    },
+    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);
+}

package/src/api/exchange/cWithdraw.ts

@@ -0,0 +1,135 @@
+import * as v from "valibot";
+import { type DeepImmutable, Hex, parser, UnsignedInteger } from "../_base.ts";
+import {
+  type ExchangeRequestConfig,
+  executeUserSignedAction,
+  type ExtractRequestAction,
+  type ExtractRequestOptions,
+  getSignatureChainId,
+  type MultiSignRequestConfig,
+  Signature,
+} from "./_base/mod.ts";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Transfer native token from staking into the user's spot account.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#withdraw-from-staking
+ */
+export const CWithdrawRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.object({
+          /** Type of action. */
+          type: v.pipe(
+            v.literal("cWithdraw"),
+            v.description("Type of action."),
+          ),
+          /** Chain ID used for signing. */
+          signatureChainId: v.pipe(
+            Hex,
+            v.description("Chain ID used for signing."),
+          ),
+          /** HyperLiquid network. */
+          hyperliquidChain: v.pipe(
+            v.union([v.literal("Mainnet"), v.literal("Testnet")]),
+            v.description("HyperLiquid network."),
+          ),
+          /** Amount of wei to withdraw from staking balance (float * 1e8). */
+          wei: v.pipe(
+            UnsignedInteger,
+            v.description("Amount of wei to withdraw from staking balance (float * 1e8)."),
+          ),
+          /** Unique request identifier (current timestamp in ms). */
+          nonce: v.pipe(
+            UnsignedInteger,
+            v.description("Unique request identifier (current timestamp in ms)."),
+          ),
+        }),
+        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."),
+      ),
+    }),
+    v.description("Transfer native token from staking into the user's spot account."),
+  );
+})();
+export type CWithdrawRequest = v.InferOutput<typeof CWithdrawRequest>;
+
+import { SuccessResponse } from "./_base/mod.ts";
+export { SuccessResponse };
+
+// -------------------- Function --------------------
+
+/** Action parameters for the {@linkcode cWithdraw} function. */
+export type CWithdrawParameters = ExtractRequestAction<v.InferInput<typeof CWithdrawRequest>>;
+/** Request options for the {@linkcode cWithdraw} function. */
+export type CWithdrawOptions = ExtractRequestOptions<v.InferInput<typeof CWithdrawRequest>>;
+
+/** EIP-712 types for the {@linkcode cWithdraw} function. */
+export const CWithdrawTypes = {
+  "HyperliquidTransaction:CWithdraw": [
+    { name: "hyperliquidChain", type: "string" },
+    { name: "wei", type: "uint64" },
+    { name: "nonce", type: "uint64" },
+  ],
+};
+
+/**
+ * Transfer native token from staking into the user's spot account.
+ * @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 https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#withdraw-from-staking
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { cWithdraw } 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 cWithdraw(
+ *   { transport, wallet },
+ *   { wei: 1 * 1e8 },
+ * );
+ * ```
+ */
+export async function cWithdraw(
+  config: ExchangeRequestConfig | MultiSignRequestConfig,
+  params: DeepImmutable<CWithdrawParameters>,
+  opts?: CWithdrawOptions,
+): Promise<SuccessResponse> {
+  const request = parser(CWithdrawRequest)({
+    action: {
+      type: "cWithdraw",
+      hyperliquidChain: config.transport.isTestnet ? "Testnet" : "Mainnet",
+      signatureChainId: await getSignatureChainId(config),
+      nonce: 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, request, CWithdrawTypes, opts?.signal);
+}