@nktkas/hyperliquid 0.24.3 → 0.25.0-beta.2

package/src/src/schemas/info/validators.ts

@@ -0,0 +1,299 @@
+import * as v from "valibot";
+import { Hex, Integer, UnsignedDecimal, UnsignedInteger } from "../_base.js";
+
+/** User delegation to a validator. */
+export const Delegation = v.pipe(
+    v.object({
+        /** Validator address. */
+        validator: v.pipe(
+            v.pipe(Hex, v.length(42)),
+            v.description("Validator address."),
+        ),
+        /** Amount of tokens delegated to the validator. */
+        amount: v.pipe(
+            UnsignedDecimal,
+            v.description("Amount of tokens delegated to the validator."),
+        ),
+        /** Locked until timestamp (in ms since epoch). */
+        lockedUntilTimestamp: v.pipe(
+            UnsignedInteger,
+            v.description("Locked until timestamp (in ms since epoch)."),
+        ),
+    }),
+    v.description("User delegation to a validator."),
+);
+export type Delegation = v.InferOutput<typeof Delegation>;
+
+/** Reward received from staking activities. */
+export const DelegatorReward = v.pipe(
+    v.object({
+        /** Timestamp when the reward was received (in ms since epoch). */
+        time: v.pipe(
+            UnsignedInteger,
+            v.description("Timestamp when the reward was received (in ms since epoch)."),
+        ),
+        /** Source of the reward. */
+        source: v.pipe(
+            v.union([v.literal("delegation"), v.literal("commission")]),
+            v.description("Source of the reward."),
+        ),
+        /** Total reward amount. */
+        totalAmount: v.pipe(
+            UnsignedDecimal,
+            v.description("Total reward amount."),
+        ),
+    }),
+    v.description("Reward received from staking activities."),
+);
+export type DelegatorReward = v.InferOutput<typeof DelegatorReward>;
+
+/** Summary of a user staking delegations. */
+export const DelegatorSummary = v.pipe(
+    v.object({
+        /** Total amount of delegated tokens. */
+        delegated: v.pipe(
+            UnsignedDecimal,
+            v.description("Total amount of delegated tokens."),
+        ),
+        /** Total amount of undelegated tokens. */
+        undelegated: v.pipe(
+            UnsignedDecimal,
+            v.description("Total amount of undelegated tokens."),
+        ),
+        /** Total amount of tokens pending withdrawal. */
+        totalPendingWithdrawal: v.pipe(
+            UnsignedDecimal,
+            v.description("Total amount of tokens pending withdrawal."),
+        ),
+        /** Number of pending withdrawals. */
+        nPendingWithdrawals: v.pipe(
+            UnsignedInteger,
+            v.description("Number of pending withdrawals."),
+        ),
+    }),
+    v.description("Summary of a user staking delegations."),
+);
+export type DelegatorSummary = v.InferOutput<typeof DelegatorSummary>;
+
+/** Delegation operation in a delegator update. */
+export const DelegatorUpdateDelegate = v.pipe(
+    v.object({
+        /** Delegation operation details. */
+        delegate: v.pipe(
+            v.object({
+                /** Address of the validator receiving or losing delegation. */
+                validator: v.pipe(
+                    v.pipe(Hex, v.length(42)),
+                    v.description("Address of the validator receiving or losing delegation."),
+                ),
+                /** Amount of tokens being delegated or undelegated. */
+                amount: v.pipe(
+                    UnsignedDecimal,
+                    v.description("Amount of tokens being delegated or undelegated."),
+                ),
+                /** Whether this is an undelegation operation. */
+                isUndelegate: v.pipe(
+                    v.boolean(),
+                    v.description("Whether this is an undelegation operation."),
+                ),
+            }),
+            v.description("Delegation operation details."),
+        ),
+    }),
+    v.description("Delegation operation in a delegator update."),
+);
+export type DelegatorUpdateDelegate = v.InferOutput<typeof DelegatorUpdateDelegate>;
+
+/** Deposit operation in a delegator update. */
+export const DelegatorUpdateDeposit = v.pipe(
+    v.object({
+        /** Deposit details. */
+        cDeposit: v.pipe(
+            v.object({
+                /** Amount of tokens being deposited. */
+                amount: v.pipe(
+                    UnsignedDecimal,
+                    v.description("Amount of tokens being deposited."),
+                ),
+            }),
+            v.description("Deposit details."),
+        ),
+    }),
+    v.description("Deposit operation in a delegator update."),
+);
+export type DelegatorUpdateDeposit = v.InferOutput<typeof DelegatorUpdateDeposit>;
+
+/** Withdrawal operation in a delegator update. */
+export const DelegatorUpdateWithdrawal = v.pipe(
+    v.object({
+        /** Withdrawal details. */
+        withdrawal: v.pipe(
+            v.object({
+                /** Amount of tokens being withdrawn. */
+                amount: v.pipe(
+                    UnsignedDecimal,
+                    v.description("Amount of tokens being withdrawn."),
+                ),
+                /** Phase of the withdrawal process. */
+                phase: v.pipe(
+                    v.union([v.literal("initiated"), v.literal("finalized")]),
+                    v.description("Phase of the withdrawal process."),
+                ),
+            }),
+            v.description("Withdrawal details."),
+        ),
+    }),
+    v.description("Withdrawal operation in a delegator update."),
+);
+export type DelegatorUpdateWithdrawal = v.InferOutput<typeof DelegatorUpdateWithdrawal>;
+
+/** Record of a staking event by a delegator. */
+export const DelegatorUpdate = v.pipe(
+    v.object({
+        /** Timestamp of the delegation event (in ms since epoch). */
+        time: v.pipe(
+            UnsignedInteger,
+            v.description("Timestamp of the delegation event (in ms since epoch)."),
+        ),
+        /** Transaction hash of the delegation event. */
+        hash: v.pipe(
+            v.pipe(Hex, v.length(66)),
+            v.description("Transaction hash of the delegation event."),
+        ),
+        /** Details of the update. */
+        delta: v.pipe(
+            v.union([
+                DelegatorUpdateDelegate,
+                DelegatorUpdateDeposit,
+                DelegatorUpdateWithdrawal,
+            ]),
+            v.description("Details of the update."),
+        ),
+    }),
+    v.description("Record of a staking event by a delegator."),
+);
+export type DelegatorUpdate = v.InferOutput<typeof DelegatorUpdate>;
+
+/** Statistics for validator performance over a time period. */
+export const ValidatorStats = v.pipe(
+    v.object({
+        /** Fraction of time the validator was online. */
+        uptimeFraction: v.pipe(
+            v.string(),
+            v.description("Fraction of time the validator was online."),
+        ),
+        /** Predicted annual percentage rate of returns. */
+        predictedApr: v.pipe(
+            UnsignedDecimal,
+            v.description("Predicted annual percentage rate of returns."),
+        ),
+        /** Number of samples used for statistics calculation. */
+        nSamples: v.pipe(
+            UnsignedInteger,
+            v.description("Number of samples used for statistics calculation."),
+        ),
+    }),
+    v.description("Statistics for validator performance over a time period."),
+);
+export type ValidatorStats = v.InferOutput<typeof ValidatorStats>;
+
+/** Summary of a validator status and performance. */
+export const ValidatorSummary = v.pipe(
+    v.object({
+        /** Address of the validator. */
+        validator: v.pipe(
+            v.pipe(Hex, v.length(42)),
+            v.description("Address of the validator."),
+        ),
+        /** Address of the validator signer. */
+        signer: v.pipe(
+            v.pipe(Hex, v.length(42)),
+            v.description("Address of the validator signer."),
+        ),
+        /** Name of the validator. */
+        name: v.pipe(
+            v.string(),
+            v.description("Name of the validator."),
+        ),
+        /** Description of the validator. */
+        description: v.pipe(
+            v.string(),
+            v.description("Description of the validator."),
+        ),
+        /** Number of blocks produced recently. */
+        nRecentBlocks: v.pipe(
+            UnsignedInteger,
+            v.description("Number of blocks produced recently."),
+        ),
+        /** Total amount of tokens staked **(unsafe integer)**. */
+        stake: v.pipe(
+            v.pipe(v.number(), v.integer()),
+            v.description("Total amount of tokens staked **(unsafe integer)**."),
+        ),
+        /** Whether the validator is currently jailed. */
+        isJailed: v.pipe(
+            v.boolean(),
+            v.description("Whether the validator is currently jailed."),
+        ),
+        /** Timestamp when the validator can be unjailed (in ms since epoch). */
+        unjailableAfter: v.pipe(
+            v.union([UnsignedInteger, v.null()]),
+            v.description("Timestamp when the validator can be unjailed (in ms since epoch)."),
+        ),
+        /** Whether the validator is currently active. */
+        isActive: v.pipe(
+            v.boolean(),
+            v.description("Whether the validator is currently active."),
+        ),
+        /** Commission rate charged by the validator. */
+        commission: v.pipe(
+            UnsignedDecimal,
+            v.description("Commission rate charged by the validator."),
+        ),
+        /** Performance statistics over different time periods. */
+        stats: v.pipe(
+            v.tuple([
+                v.tuple([v.literal("day"), ValidatorStats]),
+                v.tuple([v.literal("week"), ValidatorStats]),
+                v.tuple([v.literal("month"), ValidatorStats]),
+            ]),
+            v.description("Performance statistics over different time periods."),
+        ),
+    }),
+    v.description("Summary of a validator status and performance."),
+);
+export type ValidatorSummary = v.InferOutput<typeof ValidatorSummary>;
+
+/** L1 governance vote cast by a validator. */
+export const ValidatorL1Vote = v.pipe(
+    v.array(
+        v.object({
+            /** Timestamp when the vote expires (in ms since epoch). */
+            expireTime: v.pipe(
+                v.pipe(Integer),
+                v.description("Timestamp when the vote expires (in ms since epoch)."),
+            ),
+            /** Vote decision or action identifier. */
+            action: v.object({
+                D: v.pipe(
+                    v.string(),
+                    v.description("Vote decision or action identifier."),
+                ),
+            }),
+            /** List of validator addresses that cast this vote. */
+            votes: v.pipe(
+                v.array(v.pipe(Hex, v.length(42))),
+                v.description("List of validator addresses that cast this vote."),
+            ),
+        }),
+    ),
+    v.description("L1 governance vote cast by a validator."),
+);
+export type ValidatorL1Vote = v.InferOutput<typeof ValidatorL1Vote>;
+
+/** List of gossip root IPs. */
+export const GossipRootIps = v.pipe(
+    v.array(v.pipe(v.string(), v.ipv4())),
+    v.description("List of gossip root IPs."),
+);
+export type GossipRootIps = v.InferOutput<typeof GossipRootIps>;

package/src/src/schemas/info/vaults.ts

@@ -0,0 +1,262 @@
+import * as v from "valibot";
+import { Decimal, Hex, UnsignedDecimal, UnsignedInteger } from "../_base.js";
+import { PortfolioPeriods } from "./accounts.js";
+
+/** Vault relationship configuration. */
+export const VaultRelationship = v.pipe(
+    v.union([
+        v.object({
+            /** Relationship type. */
+            type: v.pipe(
+                v.union([v.literal("normal"), v.literal("child")]),
+                v.description("Relationship type."),
+            ),
+        }),
+        v.object({
+            /** Relationship type. */
+            type: v.pipe(
+                v.literal("parent"),
+                v.description("Relationship type."),
+            ),
+            /** Child vault information. */
+            data: v.pipe(
+                v.object({
+                    /** Child vault addresses. */
+                    childAddresses: v.pipe(
+                        v.array(v.pipe(Hex, v.length(42))),
+                        v.description("Child vault addresses."),
+                    ),
+                }),
+                v.description("Child vault information."),
+            ),
+        }),
+    ]),
+    v.description("Vault relationship configuration."),
+);
+export type VaultRelationship = v.InferOutput<typeof VaultRelationship>;
+
+/** Vault follower state. */
+export const VaultFollowerState = v.pipe(
+    v.object({
+        /** Follower address. */
+        user: v.pipe(
+            v.pipe(Hex, v.length(42)),
+            v.description("Follower address."),
+        ),
+        /** Follower vault equity. */
+        vaultEquity: v.pipe(
+            UnsignedDecimal,
+            v.description("Follower vault equity."),
+        ),
+        /** Current profit and loss. */
+        pnl: v.pipe(
+            Decimal,
+            v.description("Current profit and loss."),
+        ),
+        /** All-time profit and loss. */
+        allTimePnl: v.pipe(
+            Decimal,
+            v.description("All-time profit and loss."),
+        ),
+        /** Subscription duration in days. */
+        daysFollowing: v.pipe(
+            UnsignedInteger,
+            v.description("Subscription duration in days."),
+        ),
+        /** Vault entry timestamp. */
+        vaultEntryTime: v.pipe(
+            UnsignedInteger,
+            v.description("Vault entry timestamp."),
+        ),
+        /** Timestamp when funds become unlocked. */
+        lockupUntil: v.pipe(
+            UnsignedInteger,
+            v.description("Timestamp when funds become unlocked."),
+        ),
+    }),
+    v.description("Vault follower state."),
+);
+export type VaultFollowerState = v.InferOutput<typeof VaultFollowerState>;
+
+/** Details about a vault. */
+export const VaultDetails = v.pipe(
+    v.object({
+        /** Vault name. */
+        name: v.pipe(
+            v.string(),
+            v.description("Vault name."),
+        ),
+        /** Vault address. */
+        vaultAddress: v.pipe(
+            v.pipe(Hex, v.length(42)),
+            v.description("Vault address."),
+        ),
+        /** Leader address. */
+        leader: v.pipe(
+            v.pipe(Hex, v.length(42)),
+            v.description("Leader address."),
+        ),
+        /** Vault description. */
+        description: v.pipe(
+            v.string(),
+            v.description("Vault description."),
+        ),
+        /** Vault portfolio metrics grouped by time periods. */
+        portfolio: v.pipe(
+            PortfolioPeriods,
+            v.description("Vault portfolio metrics grouped by time periods."),
+        ),
+        /** Annual percentage rate. */
+        apr: v.pipe(
+            v.number(),
+            v.description("Annual percentage rate."),
+        ),
+        /** Current user follower state */
+        followerState: v.pipe(
+            v.nullable(VaultFollowerState),
+            v.description("Current user follower state"),
+        ),
+        /** Ownership percentage held by leader. */
+        leaderFraction: v.pipe(
+            v.number(),
+            v.description("Ownership percentage held by leader."),
+        ),
+        /** Leader commission percentage. */
+        leaderCommission: v.pipe(
+            v.number(),
+            v.description("Leader commission percentage."),
+        ),
+        /** Vault followers list. */
+        followers: v.pipe(
+            v.array(
+                v.object({
+                    ...v.omit(v.object(VaultFollowerState.entries), ["user"]).entries,
+                    ...v.object({
+                        /** Follower address or Leader. */
+                        user: v.pipe(
+                            v.union([v.pipe(Hex, v.length(42)), v.literal("Leader")]),
+                            v.description("Follower address or Leader."),
+                        ),
+                    }).entries,
+                }),
+            ),
+            v.description("Vault followers list."),
+        ),
+        /** Maximum distributable amount. */
+        maxDistributable: v.pipe(
+            v.number(),
+            v.description("Maximum distributable amount."),
+        ),
+        /** Maximum withdrawable amount. */
+        maxWithdrawable: v.pipe(
+            v.number(),
+            v.description("Maximum withdrawable amount."),
+        ),
+        /** Vault closure status. */
+        isClosed: v.pipe(
+            v.boolean(),
+            v.description("Vault closure status."),
+        ),
+        /** Vault relationship type. */
+        relationship: v.pipe(
+            VaultRelationship,
+            v.description("Vault relationship type."),
+        ),
+        /** Deposit permission status. */
+        allowDeposits: v.pipe(
+            v.boolean(),
+            v.description("Deposit permission status."),
+        ),
+        /** Position closure policy on withdrawal. */
+        alwaysCloseOnWithdraw: v.pipe(
+            v.boolean(),
+            v.description("Position closure policy on withdrawal."),
+        ),
+    }),
+    v.description("Details about a vault."),
+);
+export type VaultDetails = v.InferOutput<typeof VaultDetails>;
+
+/** User vault equity details. */
+export const VaultEquity = v.pipe(
+    v.object({
+        /** Vault address. */
+        vaultAddress: v.pipe(
+            v.pipe(Hex, v.length(42)),
+            v.description("Vault address."),
+        ),
+        /** User deposited equity. */
+        equity: v.pipe(
+            UnsignedDecimal,
+            v.description("User deposited equity."),
+        ),
+        /** Timestamp when the user can withdraw their equity. */
+        lockedUntilTimestamp: v.pipe(
+            UnsignedInteger,
+            v.description("Timestamp when the user can withdraw their equity."),
+        ),
+    }),
+    v.description("User vault equity details."),
+);
+export type VaultEquity = v.InferOutput<typeof VaultEquity>;
+
+/** Summary of a vault. */
+export const VaultSummary = v.pipe(
+    v.object({
+        /** Vault name. */
+        name: v.pipe(
+            v.string(),
+            v.description("Vault name."),
+        ),
+        /** Vault address. */
+        vaultAddress: v.pipe(
+            v.pipe(Hex, v.length(42)),
+            v.description("Vault address."),
+        ),
+        /** Leader address. */
+        leader: v.pipe(
+            v.pipe(Hex, v.length(42)),
+            v.description("Leader address."),
+        ),
+        /** Total value locked. */
+        tvl: v.pipe(
+            UnsignedDecimal,
+            v.description("Total value locked."),
+        ),
+        /** Vault closure status. */
+        isClosed: v.pipe(
+            v.boolean(),
+            v.description("Vault closure status."),
+        ),
+        /** Vault relationship type. */
+        relationship: v.pipe(
+            VaultRelationship,
+            v.description("Vault relationship type."),
+        ),
+        /** Creation timestamp. */
+        createTimeMillis: v.pipe(
+            UnsignedInteger,
+            v.description("Creation timestamp."),
+        ),
+    }),
+    v.description("Summary of a vault."),
+);
+export type VaultSummary = v.InferOutput<typeof VaultSummary>;
+
+/** Vault that a user is leading. */
+export const VaultLeading = v.pipe(
+    v.object({
+        /** Vault address. */
+        address: v.pipe(
+            v.pipe(Hex, v.length(42)),
+            v.description("Vault address."),
+        ),
+        /** Vault name. */
+        name: v.pipe(
+            v.string(),
+            v.description("Vault name."),
+        ),
+    }),
+    v.description("Vault that a user is leading."),
+);
+export type VaultLeading = v.InferOutput<typeof VaultLeading>;

package/src/src/schemas/mod.ts

@@ -0,0 +1,121 @@
+/**
+ * This module provides valibot schemas for validating, formatting, and inferring types for data used in the Hyperliquid API.
+ *
+ * @example
+ * ```ts
+ * import { OrderRequest, parser } from "@nktkas/hyperliquid/schemas";
+ * //       ^^^^^^^^^^^^
+ * //       both a Valibot schema and a TypeScript type
+ *
+ * const action = {
+ *   type: "order",
+ *   orders: [{
+ *       a: 0,
+ *       b: true,
+ *       p: "50000",
+ *       s: "0.1",
+ *       r: false,
+ *       t: { limit: { tif: "Gtc" } },
+ *   }],
+ *   grouping: "na",
+ * } satisfies OrderRequest["action"]; // can be used as type
+ *
+ * //                             or as valibot schema
+ * //                             ⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄
+ * const validatedAction = parser(OrderRequest.entries.action)(action);
+ * //                      ^^^^^^
+ * //                      validates, formats, sorts object keys for correct signature generation
+ * //                      and returns typed data
+ * ```
+ *
+ * Also valibot schema can be converted to JSON Schema:
+ *
+ * @example
+ * ```ts
+ * import { OrderRequest } from "@nktkas/hyperliquid/schemas";
+ * import { toJsonSchema } from "npm:@valibot/to-json-schema";
+ *
+ * const schema = toJsonSchema(OrderRequest, { errorMode: "ignore" });
+ *
+ * console.log(JSON.stringify(schema, null, 2));
+ * // {
+ * //   "$schema": "http://json-schema.org/draft-07/schema#",
+ * //   "type": "object",
+ * //   "properties": {
+ * //     "action": {
+ * //       "type": "object",
+ * //       "properties": {
+ * //         "type": { "const": "order" },
+ * //         "orders": { "type": "array", "items": {...} },
+ * //         "grouping": { "anyOf": [...] },
+ * //         "builder": { "type": "object", ... }
+ * //       },
+ * //       "required": ["type", "orders", "grouping"]
+ * //     },
+ * //     "nonce": { "type": "number" },
+ * //     "signature": {
+ * //       "type": "object",
+ * //       "properties": {
+ * //         "r": { "type": "string", ... },
+ * //         "s": { "type": "string", ... },
+ * //         "v": { "anyOf": [{"const": 27}, {"const": 28}] }
+ * //       },
+ * //       "required": ["r", "s", "v"]
+ * //     },
+ * //     "vaultAddress": { "type": "string", ... },
+ * //     "expiresAfter": { "type": "number" }
+ * //   },
+ * //   "required": ["action", "nonce", "signature"]
+ * // }
+ * ```
+ *
+ * @module
+ */
+
+import * as v from "valibot";
+import { HyperliquidError } from "../errors.js";
+
+/** Thrown when a schema validation error occurs.  */
+export class SchemaError extends HyperliquidError {
+    constructor(message: string) {
+        super(message);
+        this.name = "SchemaError";
+    }
+}
+
+/**
+ * Creates a valibot parser with summarized error messages.
+ * Used for validating, formatting, and sorting object keys for correct signature generation.
+ * @param schema - The valibot schema to validate against.
+ * @returns A parser function that validates input against the schema.
+ */
+export function parser<TSchema extends v.GenericSchema>(schema: TSchema): v.Parser<TSchema, undefined> {
+    const safeParser = v.safeParser(schema);
+    const parser = (input: unknown) => {
+        const result = safeParser(input);
+        if (result.issues) throw new SchemaError("\n" + v.summarize(result.issues));
+        return result.output;
+    };
+    parser.schema = schema;
+    parser.config = undefined;
+    return parser;
+}
+
+export { Hex } from "./_base.js";
+
+export * from "./exchange/requests.js";
+export * from "./exchange/responses.js";
+
+export * from "./explorer/requests.js";
+export * from "./explorer/responses.js";
+
+export * from "./info/accounts.js";
+export * from "./info/assets.js";
+export * from "./info/markets.js";
+export * from "./info/orders.js";
+export * from "./info/requests.js";
+export * from "./info/validators.js";
+export * from "./info/vaults.js";
+
+export * from "./subscriptions/responses.js";
+export * from "./subscriptions/requests.js";