hypervibes 0.0.0-stage → 0.4.0

package/dist/hyperliquid/exchange.js

@@ -0,0 +1,118 @@
+import { ApiRequestError, ExchangeClient, HttpTransport, InfoClient } from "@nktkas/hyperliquid";
+import { privateKeyToAccount } from "viem/accounts";
+import { HYPERLIQUID_API_URL } from "./constants.js";
+/** Splits a 65-byte secp256k1 signature into Hyperliquid's `r`/`s`/`v` fields. */
+export function signatureParts(signature) {
+    const raw = signature.slice(2);
+    if (!/^[0-9a-fA-F]{130}$/.test(raw))
+        throw new Error("Invalid signature");
+    return {
+        r: `0x${raw.slice(0, 64)}`,
+        s: `0x${raw.slice(64, 128)}`,
+        v: Number.parseInt(raw.slice(128, 130), 16),
+    };
+}
+/** An exchange response succeeded only when Hyperliquid reports `status: "ok"`. */
+export function exchangeSuccess(response) {
+    return typeof response === "object" && response !== null
+        && response.status === "ok";
+}
+/** The message Hyperliquid attached to a rejected exchange response. */
+export function exchangeErrorMessage(response) {
+    if (typeof response !== "object" || response === null)
+        return "Hyperliquid rejected the request.";
+    const inner = response.response;
+    const nested = typeof inner === "object" && inner !== null ? inner.data?.status?.error : undefined;
+    const message = typeof nested === "string" ? nested
+        : typeof inner === "string" ? inner
+            : typeof response.message === "string" ? response.message
+                : undefined;
+    return message ?? "Hyperliquid rejected the request.";
+}
+/**
+ * Relays a browser-signed action to the exchange endpoint unchanged. The
+ * caller has already validated the action object and recovered its signer.
+ */
+export async function relaySignedAction(transport, action, signature) {
+    const nonce = action.nonce;
+    if (typeof nonce !== "number" || !Number.isSafeInteger(nonce))
+        throw new Error("Invalid action nonce");
+    const response = await fetch(`${HYPERLIQUID_API_URL}/exchange`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ action, nonce, signature: signatureParts(signature) }),
+    });
+    if (!response.ok)
+        throw new Error("Hyperliquid exchange unavailable");
+    return response.json();
+}
+/**
+ * Serializes creation for each owner and remembers uncertain submissions for
+ * the lifetime of the service. A cancelled request also remains uncertain.
+ */
+export class SubaccountCreator {
+    transport;
+    nonceManager;
+    owners = new Map();
+    constructor(transport, nonceManager) {
+        this.transport = transport;
+        this.nonceManager = nonceManager;
+    }
+    async discover(owner, name) {
+        const info = new InfoClient({ transport: this.transport });
+        const accounts = await info.subAccounts({ user: owner });
+        return accounts?.find((account) => account.master.toLowerCase() === owner && account.name === name)
+            ?.subAccountUser.toLowerCase() ?? null;
+    }
+    async create(owner, name, privateKey) {
+        const state = this.owners.get(owner) ?? { pending: new Set(), queue: Promise.resolve() };
+        this.owners.set(owner, state);
+        const attempt = state.queue.then(() => this.attempt(state, owner, name, privateKey));
+        state.queue = attempt.then(() => { }, () => { });
+        return attempt;
+    }
+    async attempt(state, owner, name, privateKey) {
+        let existing;
+        try {
+            existing = await this.discover(owner, name);
+        }
+        catch {
+            return state.pending.has(name)
+                ? { ok: false, failure: { kind: "unconfirmed" } }
+                : { ok: false, failure: { kind: "lookup-unavailable" } };
+        }
+        if (existing) {
+            state.pending.delete(name);
+            return { ok: true, subaccount: { address: existing, created: false } };
+        }
+        if (state.pending.has(name))
+            return { ok: false, failure: { kind: "unconfirmed" } };
+        // Record the name before awaiting submission so a cancelled request cannot
+        // enable another request to blindly submit the same creation.
+        state.pending.add(name);
+        try {
+            const wallet = privateKeyToAccount(privateKey);
+            const exchange = new ExchangeClient({ transport: this.transport, wallet, nonceManager: this.nonceManager });
+            const response = await exchange.createSubAccount({ name });
+            state.pending.delete(name);
+            const address = typeof response.response?.data === "string" ? response.response.data.toLowerCase() : null;
+            if (!address)
+                return { ok: false, failure: { kind: "unconfirmed" } };
+            return { ok: true, subaccount: { address, created: true } };
+        }
+        catch (error) {
+            if (error instanceof ApiRequestError) {
+                // An explicit exchange rejection definitively means nothing was created.
+                state.pending.delete(name);
+                return { ok: false, failure: { kind: "rejected", message: error.message } };
+            }
+            // Transport or unexpected failures are uncertain; reconcile by discovery.
+            const reconciled = await this.discover(owner, name).catch(() => null);
+            if (reconciled) {
+                state.pending.delete(name);
+                return { ok: true, subaccount: { address: reconciled, created: true } };
+            }
+            return { ok: false, failure: { kind: "unconfirmed" } };
+        }
+    }
+}

package/dist/hyperliquid/journal-decimal.js

@@ -0,0 +1,48 @@
+/** Exact finite-decimal accounting. Division alone rounds half-even at 28 places.
+ * Split fees use subtraction for the remainder, preserving the source total. */
+export class Amount {
+    units;
+    scale;
+    constructor(units, scale) {
+        this.units = units;
+        this.scale = scale;
+    }
+    static from(value) {
+        if (value.length > 200 || !/^-?\d+(?:\.\d+)?$/.test(value))
+            throw new Error("Invalid journal decimal");
+        const [whole, fraction = ""] = value.split(".");
+        return new Amount(BigInt(`${whole}${fraction}`), fraction.length);
+    }
+    align(other) {
+        const scale = Math.max(this.scale, other.scale);
+        return { a: this.units * 10n ** BigInt(scale - this.scale), b: other.units * 10n ** BigInt(scale - other.scale), scale };
+    }
+    add(other) { const { a, b, scale } = this.align(other); return new Amount(a + b, scale); }
+    sub(other) { return this.add(other.neg()); }
+    neg() { return new Amount(-this.units, this.scale); }
+    abs() { return this.units < 0n ? this.neg() : this; }
+    mul(other) { return new Amount(this.units * other.units, this.scale + other.scale); }
+    div(other) {
+        if (other.units === 0n)
+            throw new Error("Division by zero");
+        const numerator = this.units * 10n ** BigInt(other.scale + 28);
+        const denominator = other.units * 10n ** BigInt(this.scale);
+        const negative = (numerator < 0n) !== (denominator < 0n);
+        const n = numerator < 0n ? -numerator : numerator;
+        const d = denominator < 0n ? -denominator : denominator;
+        let result = n / d;
+        const remainder = n % d;
+        if (remainder * 2n > d || (remainder * 2n === d && result % 2n !== 0n))
+            result++;
+        return new Amount(negative ? -result : result, 28);
+    }
+    cmp(other) { const { a, b } = this.align(other); return a < b ? -1 : a > b ? 1 : 0; }
+    get zero() { return this.units === 0n; }
+    get sign() { return this.units < 0n ? -1 : this.units > 0n ? 1 : 0; }
+    toString() {
+        const raw = (this.units < 0n ? -this.units : this.units).toString().padStart(this.scale + 1, "0");
+        const body = this.scale ? `${raw.slice(0, -this.scale)}.${raw.slice(-this.scale)}`.replace(/\.?0+$/, "") : raw;
+        return `${this.units < 0n ? "-" : ""}${body}`;
+    }
+}
+export const amount = Amount.from;

package/dist/hyperliquid/journal-model.js

@@ -0,0 +1,167 @@
+import { createHash } from "node:crypto";
+import { amount } from "./journal-decimal.js";
+export function stableId(...parts) { return createHash("sha256").update(JSON.stringify(parts)).digest("hex"); }
+const decimal = (value) => value === undefined ? null : amount(value).toString();
+export function fillEvent(row) {
+    if (!Number.isSafeInteger(row.tid))
+        throw new Error("Exchange trade identity exceeds safe integer range");
+    const fee = row.feeToken?.toUpperCase() === "USDC" ? decimal(row.fee) : null;
+    const pnl = decimal(row.closedPnl);
+    // Spot principal and non-USDC fees must never masquerade as a USDC cash delta.
+    const perp = !row.coin.startsWith("@") && !row.coin.includes("/");
+    return { id: stableId("fill", row.hash, String(row.tid)), kind: "fill", time: row.time, symbol: row.coin,
+        type: `fill ${row.side}`, fee, pnl, delta: perp && pnl !== null && fee !== null ? amount(pnl).sub(amount(fee)).toString() : null,
+        fill: perp ? { hash: row.hash, tid: String(row.tid), side: row.side, size: amount(row.sz).toString(), price: amount(row.px).toString(), start: decimal(row.startPosition), feeToken: row.feeToken ?? null, rawFee: decimal(row.fee) } : null, raw: row };
+}
+export function fundingEvent(row) {
+    return { id: stableId("funding", row.delta.coin, String(row.time)), kind: "funding", time: row.time, symbol: row.delta.coin,
+        type: "funding", fee: null, pnl: null, delta: amount(row.delta.usdc).toString(), fill: null, raw: row };
+}
+/** WebSocket funding pushes carry a flat shape but must share HTTP event identities. */
+export function wsFundingEvent(row) {
+    return { id: stableId("funding", row.coin, String(row.time)), kind: "funding", time: row.time, symbol: row.coin,
+        type: "funding", fee: null, pnl: null, delta: amount(row.usdc).toString(), fill: null, raw: row };
+}
+export function ledgerEvent(account, row) {
+    const d = row.delta;
+    let delta = null;
+    let fee = null;
+    if (d.type === "deposit")
+        delta = amount(d.usdc).toString();
+    if (d.type === "withdraw")
+        delta = amount(d.usdc).neg().toString();
+    if (d.type === "send" && d.token.toUpperCase() === "USDC" && amount(d.amount).sign >= 0) {
+        const sender = d.user.toLowerCase() === account;
+        const recipient = d.destination.toLowerCase() === account;
+        if ((sender || recipient) && (amount(d.fee).zero || d.feeToken.toUpperCase() === "USDC")) {
+            fee = sender ? amount(d.fee).toString() : "0";
+            delta = (sender === recipient ? amount("0") : sender ? amount(d.amount).neg() : amount(d.amount)).sub(amount(fee)).toString();
+        }
+    }
+    return { id: stableId("ledger", row.hash, String(row.time), d.type), kind: "ledger", time: row.time,
+        symbol: "token" in d ? d.token : "usdc" in d ? "USDC" : null, type: d.type, fee, pnl: null, delta, fill: null, raw: row };
+}
+/** Exchange P&L, position-chain ordering, and flat-to-flat perps. */
+export function buildTrades(account, events) {
+    const result = [];
+    const instruments = new Map();
+    for (const event of events)
+        if (event.fill && event.symbol) {
+            const fills = instruments.get(event.symbol) ?? [];
+            fills.push(event);
+            instruments.set(event.symbol, fills);
+        }
+    for (const [symbol, fills] of instruments) {
+        fills.sort((a, b) => a.time - b.time || compareTid(a.fill.tid, b.fill.tid) || a.fill.hash.localeCompare(b.fill.hash));
+        let signed = amount("0");
+        let active;
+        const incomplete = (reason) => { if (active) {
+            active.status = "incomplete";
+            active.coverageReason = reason;
+        } };
+        const create = (event, segment, direction, partial) => ({
+            id: stableId(account, "live", symbol, direction, event.fill.hash, event.fill.tid, segment), symbol, direction,
+            status: partial ? "incomplete" : "open", openedAt: event.time, lastActivityAt: event.time, closedAt: null,
+            remainingSize: "0", entrySize: "0", exitSize: "0", entryNotional: "0", exitNotional: "0", grossPnl: "0", fees: "0", funding: null, net: null,
+            feeCoverage: true, coverageReason: partial ? "Position predates or disagrees with available fills" : null, parts: [],
+        });
+        const part = (trade, event, segment, quantity, fee, pnl) => {
+            const sizeKey = segment === "exit" ? "exitSize" : "entrySize";
+            const notionalKey = segment === "exit" ? "exitNotional" : "entryNotional";
+            trade[sizeKey] = amount(trade[sizeKey]).add(amount(quantity)).toString();
+            trade[notionalKey] = amount(trade[notionalKey]).add(amount(quantity).mul(amount(event.fill.price))).toString();
+            trade.grossPnl = amount(trade.grossPnl).add(amount(pnl)).toString();
+            if (fee !== null)
+                trade.fees = amount(trade.fees).add(amount(fee)).toString();
+            else {
+                trade.feeCoverage = false;
+                trade.coverageReason ??= "Fee is missing or not denominated in USDC";
+            }
+            trade.lastActivityAt = event.time;
+            trade.parts.push({ eventId: event.id, time: event.time, price: event.fill.price, side: event.fill.side, segment, quantity, fee, pnl });
+        };
+        let groupEnd = 0;
+        for (let index = 0; index < fills.length; index++) {
+            if (index === groupEnd) {
+                groupEnd = index + 1;
+                while (groupEnd < fills.length && fills[groupEnd].time === fills[index].time)
+                    groupEnd++;
+            }
+            const next = fills.slice(index, groupEnd).findIndex((f) => f.fill.start !== null && amount(f.fill.start).cmp(signed) === 0);
+            if (next > 0)
+                fills.splice(index, 0, ...fills.splice(index + next, 1));
+            const event = fills[index];
+            const fill = event.fill;
+            const size = amount(fill.size);
+            if (size.sign <= 0 || amount(fill.price).sign < 0)
+                throw new Error("Invalid journal fill size or price");
+            const sign = fill.side === "B" || fill.side === "buy" ? 1 : fill.side === "A" || fill.side === "sell" ? -1 : 0;
+            if (!sign) {
+                if (active) {
+                    incomplete("Unrecognized exchange side");
+                    result.push(active);
+                    active = undefined;
+                }
+                const unknown = create(event, "entry", "unknown", true);
+                unknown.coverageReason = "Unrecognized exchange side";
+                unknown.remainingSize = fill.size;
+                part(unknown, event, "entry", fill.size, null, "0");
+                result.push(unknown);
+                signed = amount("0");
+                continue;
+            }
+            if (fill.start !== null && amount(fill.start).cmp(signed) !== 0) {
+                if (active) {
+                    incomplete("Exchange startPosition disagrees with reconstructed size");
+                    result.push(active);
+                    active = undefined;
+                }
+                signed = amount(fill.start);
+                if (!signed.zero) {
+                    active = create(event, "entry", signed.sign > 0 ? "long" : "short", true);
+                    active.remainingSize = signed.abs().toString();
+                }
+            }
+            else if (fill.start === null)
+                incomplete("Exchange startPosition missing");
+            const closing = !signed.zero && signed.sign !== sign ? (signed.abs().cmp(size) < 0 ? signed.abs() : size) : amount("0");
+            const opening = size.sub(closing);
+            const closingFee = event.fee === null ? null : amount(event.fee).mul(closing).div(size).toString();
+            if (!closing.zero) {
+                if (!active)
+                    throw new Error("Missing active journal trade");
+                if (event.pnl === null)
+                    incomplete("Exchange closing P&L missing");
+                part(active, event, "exit", closing.toString(), closingFee, event.pnl ?? "0");
+                signed = signed.add(sign > 0 ? closing : closing.neg());
+                active.remainingSize = signed.abs().toString();
+                if (signed.zero) {
+                    active.closedAt = event.time;
+                    if (active.status === "open")
+                        active.status = "closed";
+                    result.push(active);
+                    active = undefined;
+                }
+            }
+            if (!opening.zero) {
+                const segment = closing.zero ? "entry" : "flip_entry";
+                active ??= create(event, segment, sign > 0 ? "long" : "short", fill.start === null);
+                signed = signed.add(sign > 0 ? opening : opening.neg());
+                active.remainingSize = signed.abs().toString();
+                part(active, event, segment, opening.toString(), event.fee === null ? null : amount(event.fee).sub(amount(closingFee)).toString(), "0");
+            }
+        }
+        if (active)
+            result.push(active);
+    }
+    for (const trade of result) {
+        if (trade.status !== "incomplete")
+            trade.funding = events.filter((e) => e.kind === "funding" && e.symbol === trade.symbol && e.time >= trade.openedAt && (trade.closedAt === null || e.time < trade.closedAt))
+                .reduce((sum, e) => sum.add(amount(e.delta)), amount("0")).toString();
+        if (trade.feeCoverage && trade.funding !== null)
+            trade.net = amount(trade.grossPnl).sub(amount(trade.fees)).add(amount(trade.funding)).toString();
+    }
+    return result;
+}
+function compareTid(a, b) { if (/^\d+$/.test(a) && /^\d+$/.test(b))
+    return BigInt(a) < BigInt(b) ? -1 : BigInt(a) > BigInt(b) ? 1 : 0; return a.localeCompare(b); }