hypervibes 0.0.0-stage → 0.4.0

package/dist/hyperliquid/orders/order-math.js

@@ -0,0 +1,89 @@
+import { HyperliquidError } from "../errors.js";
+/** Signing-path decimal arithmetic. No conversion of financial values to Number. */
+export function decimal(value) {
+    if (typeof value !== "string" || value.length > 80 || value.trim() !== value || !/^(0|[1-9]\d*)(\.\d+)?$/.test(value))
+        throw new HyperliquidError("Use a positive plain decimal string.");
+    const [whole = "", fraction = ""] = value.split(".");
+    const trimmed = fraction.replace(/0+$/, "");
+    const units = BigInt(whole + trimmed);
+    if (units <= 0n)
+        throw new HyperliquidError("Order prices and sizes must be greater than zero.");
+    return { units, scale: trimmed.length, text: trimmed ? `${whole}.${trimmed}` : whole };
+}
+export function compare(left, right) {
+    const a = decimal(left), b = decimal(right);
+    const x = a.units * 10n ** BigInt(b.scale), y = b.units * 10n ** BigInt(a.scale);
+    return x === y ? 0 : x < y ? -1 : 1;
+}
+export function precisionRules(sizeDecimals) {
+    if (!Number.isInteger(sizeDecimals) || sizeDecimals < 0 || sizeDecimals > 6)
+        throw new HyperliquidError("Exchange size precision unavailable or unsupported", 502);
+    return { sizeDecimals, sizeStep: format(1n, sizeDecimals), priceMaxDecimals: 6 - sizeDecimals, priceMaxSignificantFigures: 5, integerPricesAllowed: true, minOpeningNotional: "10" };
+}
+export function size(value, decimals) {
+    const parsed = decimal(value);
+    if (parsed.scale > decimals)
+        throw new HyperliquidError(`Size exceeds exchange precision: received ${JSON.stringify(value)}; at most ${decimals} decimal places (size step ${format(1n, decimals)}). Choose a valid base-asset size within the requested budget; do not automatically increase it.`);
+    return parsed.text;
+}
+export function price(value, sizeDecimals) {
+    const parsed = decimal(value);
+    // Integers are always permitted. Fractional perp prices have <=5 significant
+    // figures and <=(6 - szDecimals) decimal places, per Hyperliquid's tick rules.
+    if (parsed.scale && (parsed.scale > 6 - sizeDecimals || parsed.units.toString().length > 5)) {
+        throw new HyperliquidError(`Price exceeds exchange tick/significant-figure precision: received ${JSON.stringify(value)}; fractional perpetual prices allow at most ${6 - sizeDecimals} decimal places AND 5 significant figures. Positive integer prices are exempt from both precision limits. Choose an explicit valid price consistent with the requested levels.`);
+    }
+    return parsed.text;
+}
+export function format(units, scale) {
+    const padded = units.toString().padStart(scale + 1, "0");
+    return scale ? `${padded.slice(0, -scale)}.${padded.slice(-scale)}` : padded;
+}
+/** Exact notional comparison; never round financial authority through Number. */
+export function notionalWithin(qty, px, cap) {
+    const a = decimal(qty), b = decimal(px), c = decimal(cap);
+    return a.units * b.units * 10n ** BigInt(c.scale) <= c.units * 10n ** BigInt(a.scale + b.scale);
+}
+export function notionalAtLeast(qty, px, minimum) {
+    const a = decimal(qty), b = decimal(px), c = decimal(minimum);
+    return a.units * b.units * 10n ** BigInt(c.scale) >= c.units * 10n ** BigInt(a.scale + b.scale);
+}
+/** Exact product, with no rounding below a risk cap. */
+export function notional(qty, px) {
+    const a = decimal(qty), b = decimal(px);
+    return format(a.units * b.units, a.scale + b.scale);
+}
+/** Exact sum of plain decimal strings. */
+export function sumDecimals(values) {
+    const parsed = values.map(decimal);
+    const scale = Math.max(0, ...parsed.map((value) => value.scale));
+    const total = parsed.reduce((sum, value) => sum + value.units * 10n ** BigInt(scale - value.scale), 0n);
+    return format(total, scale);
+}
+/** Exact position size/sign; exchange positions may contain zero or a minus sign. */
+export function positionSize(value) {
+    if (typeof value !== "string" || value.trim() !== value || !/^-?(0|[1-9][0-9]*)(\.[0-9]+)?$/.test(value))
+        throw new HyperliquidError("Invalid exchange position size");
+    if (!/[1-9]/.test(value))
+        return { side: "flat", size: "0" };
+    return { side: value.startsWith("-") ? "short" : "long", size: decimal(value.replace(/^-/, "")).text };
+}
+/** Guarded IOC price: 0.5% for entries, 10% for market triggers, rounded inward. */
+export function guardPrice(reference, buy, sizeDecimals, bps = 50) {
+    const parsed = decimal(reference);
+    const numerator = parsed.units * BigInt(10_000 + (buy ? bps : -bps));
+    const denominator = 10n ** BigInt(parsed.scale) * 10000n;
+    const whole = numerator / denominator;
+    let magnitude = whole ? whole.toString().length - 1 : -1;
+    if (!whole) {
+        let scaled = numerator * 10n;
+        while (scaled < denominator) {
+            magnitude--;
+            scaled *= 10n;
+        }
+    }
+    const scale = Math.max(0, Math.min(6 - sizeDecimals, 4 - magnitude));
+    const scaledNumerator = numerator * 10n ** BigInt(scale);
+    const rounded = (scaledNumerator + (buy ? 0n : denominator - 1n)) / denominator;
+    return price(format(rounded, scale), sizeDecimals);
+}

package/dist/hyperliquid/orders/order-outcomes.js

@@ -0,0 +1,74 @@
+import { liveView } from "./order-prepare.js";
+import { compare, decimal } from "./order-math.js";
+function record(value) { return value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined; }
+export function unknownViews(views, message) {
+    return views.map((view) => ({ ...view, commandStatus: "unknown", orderStatus: "unknown", source: "transport", updatedAt: Date.now(), error: message }));
+}
+/** SDK throws for mixed-success batches; decode its raw response item by item. */
+export function responseViews(kind, response, views) {
+    const root = record(response);
+    if (root?.status === "err" && typeof root.response === "string") {
+        if (/nonce|duplicate|already/i.test(root.response))
+            return unknownViews(views, "Exchange reported a duplicate identity or nonce; reconcile before any new attempt.");
+        return views.map((view) => ({ ...view, commandStatus: "rejected", orderStatus: kind === "submit" ? "rejected" : view.orderStatus, error: root.response.slice(0, 1000), updatedAt: Date.now(), source: "exchange_response" }));
+    }
+    const body = record(root?.response);
+    const statuses = record(body?.data)?.statuses;
+    if (root?.status !== "ok" || body?.type !== (kind === "submit" ? "order" : "cancel") || !Array.isArray(statuses) || statuses.length !== views.length)
+        return unknownViews(views, "Exchange response shape/count is uncertain. Reconcile; do not resubmit.");
+    return views.map((view, index) => {
+        const item = statuses[index];
+        const result = { ...view, updatedAt: Date.now(), source: "exchange_response" };
+        if (kind === "cancel" && item === "success")
+            return { ...result, commandStatus: "accepted", orderStatus: "canceled", error: null };
+        const status = record(item);
+        if (typeof status?.error === "string") {
+            if (kind === "submit" && /duplicate|cloid/i.test(status.error))
+                return unknownViews([view], "Duplicate client order ID response; reconcile before retrying.")[0];
+            return { ...result, commandStatus: "rejected", orderStatus: kind === "submit" ? "rejected" : view.orderStatus, error: status.error.slice(0, 1000) };
+        }
+        if (kind === "submit") {
+            if (item === "waitingForFill" || item === "waitingForTrigger")
+                return { ...result, commandStatus: "accepted", orderStatus: item, error: null };
+            const resting = record(status?.resting), filled = record(status?.filled);
+            const oid = resting?.oid ?? filled?.oid;
+            if (typeof oid === "number" && Number.isSafeInteger(oid) && oid > 0 && (resting || filled)) {
+                if (filled) {
+                    try {
+                        decimal(filled.totalSz);
+                        decimal(filled.avgPx);
+                        if (view.size && compare(filled.totalSz, view.size) > 0)
+                            throw new Error("Overfilled receipt");
+                    }
+                    catch {
+                        return unknownViews([view], "Malformed fill receipt; reconciliation required.")[0];
+                    }
+                }
+                const responseCloid = resting?.cloid ?? filled?.cloid;
+                if (responseCloid && responseCloid !== view.cloid)
+                    return unknownViews([view], "Exchange receipt client order ID did not match intent.")[0];
+                return { ...result, commandStatus: "accepted", orderStatus: filled ? "filled" : "open", exchangeOid: String(oid),
+                    filledSize: filled ? filled.totalSz : null, averageFillPrice: filled ? filled.avgPx : null, error: null };
+            }
+        }
+        return unknownViews([view], "Unrecognized per-order outcome; reconciliation required.")[0];
+    });
+}
+/** A targeted not-found result never manufactures a rejection or cancellation. */
+export function reconciledView(view, response) {
+    if (response.status !== "order")
+        return { ...view, updatedAt: Date.now(), error: "Order not found in venue lookup; absence is not proof of rejection, fill, or cancellation." };
+    const report = response.order;
+    const remote = liveView(report.order, report.status, report.statusTimestamp);
+    if (remote.symbol !== view.symbol || (view.exchangeOid && remote.exchangeOid !== view.exchangeOid) || (view.cloid && remote.cloid && view.cloid !== remote.cloid)) {
+        return { ...view, updatedAt: Date.now(), error: "Exchange order identity did not match the recorded intent." };
+    }
+    if (view.venueTimestamp !== null && report.statusTimestamp < view.venueTimestamp)
+        return view;
+    // A pending cancel is not confirmed by seeing an order still open/triggered.
+    const terminal = !["open", "triggered"].includes(report.status);
+    return { ...view, exchangeOid: remote.exchangeOid, orderStatus: report.status, venueTimestamp: report.statusTimestamp,
+        commandStatus: view.kind === "cancel" && !terminal && view.commandStatus === "unknown" ? "unknown"
+            : view.commandStatus === "rejected" ? "rejected" : "reconciled",
+        updatedAt: Date.now(), source: "reconciliation", error: null };
+}

package/dist/hyperliquid/orders/order-prepare.js

@@ -0,0 +1,109 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { HyperliquidError } from "../errors.js";
+import { compare, guardPrice, price, size } from "./order-math.js";
+export function newView(requestId, symbol, kind) {
+    return { id: randomUUID(), requestId, symbol, side: "", kind, size: null, price: null, triggerPrice: null, reduceOnly: false, cloid: null, exchangeOid: null,
+        commandStatus: "not_sent", orderStatus: "not_sent", filledSize: null, averageFillPrice: null, updatedAt: Date.now(), venueTimestamp: null, source: "intent", error: null };
+}
+export function liveView(order, status = "open", timestamp = null) {
+    if (!Number.isSafeInteger(order.oid) || order.oid <= 0)
+        throw new HyperliquidError("Exchange returned an unsafe order ID.", 502);
+    return { ...newView("", order.coin, order.orderType), id: String(order.oid), requestId: null,
+        side: order.side === "B" ? "buy" : "sell", size: order.origSz ?? order.sz, price: order.limitPx, triggerPrice: order.isTrigger ? order.triggerPx : null,
+        reduceOnly: order.reduceOnly, cloid: order.cloid ?? null, exchangeOid: String(order.oid), commandStatus: "reconciled", orderStatus: status,
+        updatedAt: Date.now(), venueTimestamp: timestamp, source: "exchange" };
+}
+export function isPerpetual(coin) { return !coin.startsWith("@") && !coin.includes("/") && !coin.includes(":") && !coin.startsWith("+") && !/^o\d+$/.test(coin); }
+export function exchangeOid(oid) {
+    if (typeof oid !== "string" || !/^[1-9]\d{0,15}$/.test(oid))
+        throw new HyperliquidError("Use an exchange order ID as a decimal string.");
+    const number = Number(oid);
+    if (!Number.isSafeInteger(number))
+        throw new HyperliquidError("Exchange order ID exceeds safe integer range.");
+    return number;
+}
+export async function instruments(info, signal) {
+    const meta = await info.meta({ dex: "" }, signal);
+    return new Map(meta.universe.map((entry, asset) => [entry.name, { ...entry, asset }]));
+}
+export function instrument(meta, symbol) {
+    const entry = meta.get(symbol);
+    if (!entry || !isPerpetual(symbol) || entry.isDelisted || !Number.isInteger(entry.szDecimals) || entry.szDecimals < 0 || entry.szDecimals > 6)
+        throw new HyperliquidError(`Unknown, delisted, or unsupported main-DEX perpetual: ${symbol}`);
+    return entry;
+}
+export async function prepareSubmit(info, requestId, inputs, builder, signal) {
+    const meta = await instruments(info, signal);
+    const mids = inputs.some((input) => input.order_type === "market") ? await info.allMids({ dex: "" }, signal) : {};
+    return inputs.map((input) => {
+        const entry = instrument(meta, input.symbol);
+        const buy = input.side === "buy";
+        if (!["buy", "sell"].includes(input.side))
+            throw new HyperliquidError("Invalid order side.");
+        const amount = size(input.size, entry.szDecimals);
+        const attached = [...(input.take_profits ?? []), ...(input.stop_losses ?? [])];
+        if ((input.take_profits?.length ?? 0) > 1 || (input.stop_losses?.length ?? 0) > 1)
+            throw new HyperliquidError("Native parent TP/SL supports one take-profit and one stop-loss per entry.");
+        if (input.reduce_only && attached.length)
+            throw new HyperliquidError("Attach TP/SL only to an opening entry; use standalone reduce-only triggers to protect an existing position.");
+        const orders = [], items = [];
+        const add = (kind, side, qty, px, reduce, type, trigger = null) => {
+            const cloid = `0x${randomBytes(16).toString("hex")}`;
+            orders.push({ a: entry.asset, b: side, p: px, s: qty, r: reduce, t: type, c: cloid });
+            items.push({ ...newView(requestId, input.symbol, kind), side: side ? "buy" : "sell", size: qty, price: px, triggerPrice: trigger, reduceOnly: reduce, cloid });
+        };
+        if (input.order_type === "limit" || input.order_type === "market") {
+            if (input.trigger_price !== undefined)
+                throw new HyperliquidError("Use trigger_price only for standalone triggers.");
+            if (input.order_type === "market" && (input.price !== undefined || input.time_in_force !== undefined))
+                throw new HyperliquidError("Market entries use a 0.5% guarded IOC; omit price/time_in_force.");
+            const px = input.order_type === "market" ? guardPrice(mids[input.symbol] ?? "", buy, entry.szDecimals) : price(input.price ?? "", entry.szDecimals);
+            const tif = input.order_type === "market" ? "Ioc" : input.time_in_force === "ioc" ? "Ioc" : input.time_in_force === "alo" ? "Alo" : "Gtc";
+            add(input.order_type, buy, amount, px, input.reduce_only ?? false, { limit: { tif } });
+            const trigger = (leg, kind) => {
+                const triggerPx = price(leg.trigger_price, entry.szDecimals);
+                const qty = size(leg.size ?? amount, entry.szDecimals);
+                if (compare(qty, amount) > 0)
+                    throw new HyperliquidError("Attached trigger size cannot exceed entry size.");
+                const direction = compare(triggerPx, px);
+                if ((kind === "tp" ? buy ? direction <= 0 : direction >= 0 : buy ? direction >= 0 : direction <= 0))
+                    throw new HyperliquidError("Attached TP/SL trigger is on the wrong side of the entry price.");
+                if (kind === "sl" && leg.limit_price !== undefined)
+                    throw new HyperliquidError("Attached stop-loss is market-on-trigger; omit limit_price.");
+                const isMarket = leg.limit_price === undefined;
+                const limitPx = isMarket ? guardPrice(triggerPx, !buy, entry.szDecimals, 1000) : price(leg.limit_price, entry.szDecimals);
+                add(kind === "tp" ? "take_profit" : "stop_loss", !buy, qty, limitPx, true, { trigger: { triggerPx, isMarket, tpsl: kind } }, triggerPx);
+            };
+            for (const leg of input.take_profits ?? [])
+                trigger(leg, "tp");
+            for (const leg of input.stop_losses ?? [])
+                trigger(leg, "sl");
+        }
+        else if (input.order_type === "take_profit" || input.order_type === "stop_loss") {
+            if (attached.length || input.time_in_force !== undefined || input.reduce_only === false)
+                throw new HyperliquidError("Standalone TP/SL must be reduce-only, without attached legs or time_in_force.");
+            const triggerPx = price(input.trigger_price ?? "", entry.szDecimals);
+            const isMarket = input.price === undefined;
+            const px = isMarket ? guardPrice(triggerPx, buy, entry.szDecimals, 1000) : price(input.price, entry.szDecimals);
+            add(input.order_type, buy, amount, px, true, { trigger: { triggerPx, isMarket, tpsl: input.order_type === "take_profit" ? "tp" : "sl" } }, triggerPx);
+        }
+        else
+            throw new HyperliquidError("Unsupported order_type.");
+        return { payload: { kind: "submit", orders, grouping: attached.length ? "normalTpsl" : "na", builder }, items };
+    });
+}
+/** Reject numeric money before Durable's permissive schema coercion can stringify it. */
+export function assertStringAmounts(value) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            assertStringAmounts(item);
+        return;
+    }
+    if (!value || typeof value !== "object")
+        return;
+    for (const [key, item] of Object.entries(value)) {
+        if (["size", "price", "trigger_price", "limit_price", "take_profit_price", "stop_loss_price", "oid"].includes(key) && typeof item !== "string")
+            throw new HyperliquidError(`${key} must be an exact decimal string, not a JSON number.`);
+        assertStringAmounts(item);
+    }
+}