hypervibes 0.0.0-stage → 0.4.0

package/dist/hyperliquid/service.js

@@ -0,0 +1,529 @@
+import { SharedHyperliquidFeeds } from "./shared-feeds.js";
+import { MarketCharts } from "./market-charts.js";
+import { loadMarketSnapshot } from "./market-snapshot.js";
+import { hvWalletAddresses } from "../db/auth-schema.js";
+import { HttpTransport, InfoClient } from "@nktkas/hyperliquid";
+import { loadAccountStatus } from "./account-status.js";
+import { loadAgentDashboard } from "./agent-dashboard.js";
+import { LiveDashboards } from "./live-dashboard.js";
+import { agentId } from "../agents/agent-input.js";
+import { and, eq, isNotNull, isNull, sql } from "drizzle-orm";
+import { privateKeyToAccount } from "viem/accounts";
+import { hvAgents } from "../db/agent-schema.js";
+import { hvHyperliquidSettings } from "../db/exchange-schema.js";
+import { accountModeError, loadOwnedTradingAccounts, maxBuilderFee, } from "./account-info.js";
+import { addDecimals } from "./decimal.js";
+import { agentSubaccountName, API_WALLET_APPROVAL_MS, BUILDER_FEE_BPS_TO_TENTHS, BUILDER_RECIPIENT, DEFAULT_BUILDER_FEE_BPS, MAX_BUILDER_FEE_BPS, MAX_BUILDER_FEE_TENTHS_OF_BP, MIN_BUILDER_FEE_BPS, REVOKED_BUILDER_FEE_RATE, } from "./constants.js";
+import { decryptSecret, encryptSecret, generateWalletPrivateKey } from "./crypto.js";
+import { exchangeErrorMessage, exchangeSuccess, relaySignedAction, SubaccountCreator } from "./exchange.js";
+import { HyperliquidError } from "./errors.js";
+import { parseSignedAction, signatureMatches, validApproveAgentAction, validApproveBuilderFeeAction, } from "./signing.js";
+/** Owns every user's Hyperliquid settings and the shared exchange clients. */
+export class HyperliquidService {
+    db;
+    encryptionKey;
+    transport;
+    journal;
+    log;
+    creator;
+    live;
+    feeds;
+    charts;
+    started = false;
+    stopped = false;
+    reconcileChain = Promise.resolve();
+    reconcileTimer;
+    constructor(db, encryptionKey, transport = new HttpTransport(), feedFactory, journal, nonceManager, log, feeds = new SharedHyperliquidFeeds()) {
+        this.db = db;
+        this.encryptionKey = encryptionKey;
+        this.transport = transport;
+        this.journal = journal;
+        this.log = log;
+        this.feeds = feeds;
+        this.creator = new SubaccountCreator(transport, nonceManager);
+        this.live = new LiveDashboards(transport, feedFactory ?? feeds.account);
+        this.charts = new MarketCharts(transport, feeds.candle);
+    }
+    start() {
+        if (this.started || this.stopped)
+            return;
+        this.started = true;
+        this.log?.info("Starting Hyperliquid service");
+        void this.reconcileLinkedAccounts();
+    }
+    /** Reconciles journal and live feeds with the linked trading accounts.
+     * Called once at start and on every account-linking event; failures retry. */
+    reconcileLinkedAccounts(strict = false) {
+        const reconciliation = this.reconcileChain.then(async () => {
+            if (this.stopped)
+                return;
+            try {
+                const rows = await this.db.select({ address: hvAgents.tradingAccountAddress }).from(hvAgents)
+                    .where(and(isNotNull(hvAgents.tradingAccountAddress), sql `${hvAgents.state} NOT IN ('stopping', 'stopped')`)).all();
+                if (this.stopped)
+                    return;
+                const addresses = rows.flatMap((row) => row.address ? [row.address] : []);
+                await this.journal?.reconcile(addresses);
+                await this.live.reconcile(addresses);
+                this.log?.debug({ accounts: addresses.length }, "Reconciled linked Hyperliquid accounts");
+            }
+            catch (error) {
+                this.log?.error(error, "Unable to refresh linked Hyperliquid accounts; retrying");
+                if (!this.stopped) {
+                    this.reconcileTimer = setTimeout(() => { void this.reconcileLinkedAccounts(); }, 30_000);
+                    this.reconcileTimer.unref();
+                }
+                if (strict)
+                    throw error;
+            }
+        });
+        this.reconcileChain = reconciliation.catch(() => { });
+        return reconciliation;
+    }
+    async close() {
+        this.stopped = true;
+        clearTimeout(this.reconcileTimer);
+        await this.reconcileChain;
+        try {
+            await Promise.all([this.live.close(), this.charts.close()]);
+        }
+        finally {
+            await this.journal?.close();
+            this.feeds.close();
+        }
+    }
+    async dashboardAccount(userId, id) {
+        const agent = await this.db.select().from(hvAgents).where(and(eq(hvAgents.id, agentId(id)), eq(hvAgents.userId, userId))).get();
+        if (!agent)
+            throw new HyperliquidError("Agent not found", 404);
+        if (agent.state === "stopping" || agent.state === "stopped")
+            throw new HyperliquidError("Agent is being deleted", 409);
+        if (!agent.tradingAccountAddress)
+            throw new HyperliquidError("Agent is missing its required Hyperliquid account", 409);
+        return agent.tradingAccountAddress;
+    }
+    /** Internal Agent-bound research capability; no exchange mutation or signing. */
+    async catchUpJournal(id, end, signal) {
+        const agent = await this.db.select({ account: hvAgents.tradingAccountAddress }).from(hvAgents).where(and(eq(hvAgents.id, id), sql `${hvAgents.state} NOT IN ('stopping', 'stopped')`)).get();
+        if (!agent?.account)
+            throw new HyperliquidError("Agent has no trading account", 409);
+        return this.journal ? this.journal.ensureThrough(agent.account, end, signal) : { attempted: false, limitation: "Journal synchronization is unavailable" };
+    }
+    async agentTradingAccount(userId, id) {
+        if (this.stopped)
+            throw new HyperliquidError("Hyperliquid service is closed", 503);
+        return this.dashboardAccount(userId, id);
+    }
+    /** Signing authority is resolved by the host, never from tool arguments. */
+    async orderAuthority(userId, id, signal, needsBuilder) {
+        const account = (await this.agentTradingAccount(userId, id))?.toLowerCase();
+        if (!account)
+            throw new HyperliquidError("Assign a trading account first.", 409);
+        const wallets = await this.db.select().from(hvWalletAddresses).where(eq(hvWalletAddresses.userId, userId)).all();
+        const primary = wallets.filter((wallet) => wallet.isPrimary);
+        const wallet = primary.length === 1 ? primary[0] : wallets.length === 1 ? wallets[0] : undefined;
+        if (!wallet || !/^0x[0-9a-fA-F]{40}$/.test(wallet.address))
+            throw new HyperliquidError("A unique owner wallet is required for order signing.", 409);
+        const owner = wallet.address.toLowerCase();
+        const info = new InfoClient({ transport: this.transport });
+        const role = await info.userRole({ user: account }, signal);
+        if (!(account === owner && role.role === "user") && !(role.role === "subAccount" && role.data.master.toLowerCase() === owner))
+            throw new HyperliquidError("Assigned trading account ownership could not be verified.", 409);
+        const row = await this.settings(userId);
+        const privateKey = await this.decryptSigner(userId);
+        const signer = privateKeyToAccount(privateKey);
+        if (signer.address.toLowerCase() !== row?.apiWalletAddress?.toLowerCase())
+            throw new HyperliquidError("Stored signer identity does not match its configuration.", 409);
+        const signerRole = await info.userRole({ user: signer.address }, signal);
+        if (signerRole.role !== "agent" || signerRole.data.user.toLowerCase() !== owner)
+            throw new HyperliquidError("Trading signer approval could not be verified on the exchange.", 409);
+        const fee = row?.builderFeeTenthsOfBp ?? 0;
+        const remoteFee = needsBuilder ? await maxBuilderFee(this.transport, owner, BUILDER_RECIPIENT, signal) : 0;
+        if (needsBuilder && (!row?.builderFeeApprovedAt || !Number.isInteger(fee) || fee < 1 || fee > MAX_BUILDER_FEE_TENTHS_OF_BP || !Number.isSafeInteger(remoteFee) || remoteFee < fee))
+            throw new HyperliquidError("Builder fee approval is missing or insufficient.", 409);
+        return { account, privateKey, ...(account === owner ? {} : { vaultAddress: account }), builder: { b: BUILDER_RECIPIENT, f: needsBuilder ? fee : 0 } };
+    }
+    async marketSnapshot(instrument, signal) {
+        if (this.stopped)
+            throw new HyperliquidError("Hyperliquid service is closed", 503);
+        return loadMarketSnapshot(this.transport, instrument, signal);
+    }
+    async agentAccountStatus(userId, id, signal) {
+        if (this.stopped)
+            throw new HyperliquidError("Hyperliquid service is closed", 503);
+        const address = await this.dashboardAccount(userId, id);
+        const cached = this.started && address ? this.live.snapshot(address) : undefined;
+        return loadAccountStatus(this.transport, address, cached, signal);
+    }
+    async agentDashboard(userId, id) {
+        const address = await this.dashboardAccount(userId, id);
+        const [snapshot, balanceHistory] = await Promise.all([
+            this.started && address ? this.live.snapshot(address) : loadAgentDashboard(this.transport, address),
+            address && this.journal ? this.journal.balanceHistory(address) : null,
+        ]);
+        return { ...snapshot, balanceHistory };
+    }
+    async watchDashboard(userId, id, signal, publish) {
+        const address = await this.dashboardAccount(userId, id);
+        if (signal.aborted || this.stopped)
+            return;
+        if (!this.started || !address) {
+            const snapshot = await loadAgentDashboard(this.transport, null);
+            if (!signal.aborted && !this.stopped)
+                publish(snapshot);
+            return;
+        }
+        let balanceHistory = null;
+        let latest = this.live.snapshot(address);
+        let active = true;
+        let initialized = false;
+        let ready = () => { };
+        const initial = new Promise((resolve) => { ready = resolve; });
+        const unsubscribe = this.journal?.watchBalanceHistory(address, (history) => {
+            balanceHistory = history;
+            ready();
+            if (initialized && active && !signal.aborted && !this.stopped)
+                publish({ ...latest, balanceHistory });
+        });
+        // Also settle initialization if journal shutdown suppresses the first callback.
+        if (unsubscribe)
+            void unsubscribe.ready.then(ready, ready);
+        else
+            ready();
+        // Detach immediately on abort, rather than waiting for the live feed to settle.
+        const detach = () => { active = false; ready(); void unsubscribe?.(); };
+        signal.addEventListener("abort", detach, { once: true });
+        try {
+            await initial;
+            if (!active || signal.aborted || this.stopped)
+                return;
+            initialized = true;
+            await this.live.watch(address, signal, (snapshot) => {
+                latest = snapshot;
+                if (active && !signal.aborted && !this.stopped)
+                    publish({ ...latest, balanceHistory });
+            });
+        }
+        finally {
+            active = false;
+            signal.removeEventListener("abort", detach);
+            await unsubscribe?.();
+        }
+    }
+    async agentJournal(userId, id, view, page) {
+        const address = await this.dashboardAccount(userId, id);
+        if (!this.journal)
+            throw new HyperliquidError("Journal is unavailable", 503);
+        return this.journal.page(address, view, page);
+    }
+    async chartFills(userId, id, coin, range) {
+        const address = await this.dashboardAccount(userId, id);
+        if (!this.journal)
+            throw new HyperliquidError("Journal is unavailable", 503);
+        return this.journal.chartFills(address, coin, range);
+    }
+    async journalNotes(userId, id, target) {
+        const address = await this.dashboardAccount(userId, id);
+        if (!address || !this.journal)
+            throw new HyperliquidError("Journal entry not found", 404);
+        return this.journal.notes(address, target);
+    }
+    async addJournalNote(userId, id, target, body) {
+        const address = await this.dashboardAccount(userId, id);
+        if (!address || !this.journal)
+            throw new HyperliquidError("Journal entry not found", 404);
+        await this.journal.addNote(address, target, userId, body);
+    }
+    async settings(userId) {
+        return this.db.select().from(hvHyperliquidSettings).where(eq(hvHyperliquidSettings.userId, userId)).get();
+    }
+    async ensureSettings(userId) {
+        const now = Date.now();
+        await this.db.insert(hvHyperliquidSettings).values({ userId, createdAt: now, updatedAt: now })
+            .onConflictDoNothing({ target: hvHyperliquidSettings.userId }).run();
+        const row = await this.settings(userId);
+        if (!row)
+            throw new HyperliquidError("Unable to store Hyperliquid settings", 503);
+        return row;
+    }
+    /** True when the trading signer exists, is approved and not known-expired. */
+    apiWalletIsReady(row) {
+        if (!row?.apiWalletAddress || !row.privateKeyCiphertext || !row.privateKeyKeyId || !row.apiWalletApprovedAt)
+            return false;
+        const now = Date.now();
+        if (row.apiWalletExpiresAt && row.apiWalletExpiresAt <= now)
+            return false;
+        if (row.apiWalletExpiresAt && !row.apiWalletExpiryCheckedAt)
+            return false;
+        return true;
+    }
+    apiWalletView(row) {
+        if (!row?.apiWalletAddress)
+            return null;
+        const expired = row.apiWalletExpiresAt !== null && row.apiWalletExpiresAt <= Date.now();
+        const state = !row.apiWalletApprovedAt
+            ? "approval-required"
+            : expired || !this.apiWalletIsReady(row) ? "expired-or-unavailable" : "approved";
+        return {
+            address: row.apiWalletAddress,
+            state,
+            expiresAt: row.apiWalletExpiresAt,
+            showExpired: Boolean(row.apiWalletApprovedAt) && expired,
+        };
+    }
+    /** Generates or imports a trading signer and stores it encrypted. */
+    async storeApiWallet(userId, source, importedKey) {
+        if (!this.encryptionKey)
+            throw new HyperliquidError("Trading signer storage is not configured on the server", 503);
+        let privateKey;
+        if (source === "generate")
+            privateKey = generateWalletPrivateKey();
+        else if (source === "import" && importedKey.trim())
+            privateKey = importedKey.trim();
+        else if (source === "import")
+            throw new HyperliquidError("Private key is required.");
+        else
+            throw new HyperliquidError("Select an API wallet option.");
+        let address;
+        try {
+            address = privateKeyToAccount(privateKey).address.toLowerCase();
+        }
+        catch {
+            throw new HyperliquidError("Private key is invalid.");
+        }
+        const row = await this.ensureSettings(userId);
+        if (row.apiWalletAddress === address)
+            throw new HyperliquidError("Use a fresh trading signer address.");
+        const ciphertext = encryptSecret(this.encryptionKey, privateKey);
+        await this.db.update(hvHyperliquidSettings).set({
+            apiWalletAddress: address,
+            privateKeyCiphertext: Buffer.from(ciphertext),
+            privateKeyKeyId: this.encryptionKey.id,
+            apiWalletApprovedAt: null,
+            apiWalletExpiresAt: null,
+            apiWalletExpiryCheckedAt: null,
+            updatedAt: Date.now(),
+        }).where(eq(hvHyperliquidSettings.userId, userId)).run();
+        return address;
+    }
+    /** Relays a main-wallet-signed ApproveAgent action and records the approval. */
+    async approveApiWallet(user, request) {
+        const signed = parseSignedAction(request);
+        const row = await this.settings(user.id);
+        if (!row?.apiWalletAddress)
+            throw new HyperliquidError("Set up a trading signer first.");
+        if (!validApproveAgentAction(signed.action, row.apiWalletAddress)
+            || !(await signatureMatches(signed.action, signed.signature, user.walletAddress, "approveAgent"))) {
+            throw new HyperliquidError("Invalid trading signer approval.");
+        }
+        const exchange = await this.relay(signed);
+        if (!exchangeSuccess(exchange)) {
+            throw new HyperliquidError(exchangeErrorMessage(exchange), 502);
+        }
+        const now = Date.now();
+        await this.db.update(hvHyperliquidSettings).set({
+            apiWalletApprovedAt: now,
+            apiWalletExpiresAt: now + API_WALLET_APPROVAL_MS,
+            apiWalletExpiryCheckedAt: now,
+            updatedAt: now,
+        }).where(and(eq(hvHyperliquidSettings.userId, user.id), isNotNull(hvHyperliquidSettings.apiWalletAddress), isNotNull(hvHyperliquidSettings.privateKeyCiphertext), isNotNull(hvHyperliquidSettings.privateKeyKeyId))).run();
+        const approved = await this.settings(user.id);
+        if (!approved?.apiWalletApprovedAt)
+            throw new HyperliquidError("Trading signer approval conflict", 409);
+    }
+    /** Relays a main-wallet-signed ApproveBuilderFee action and stores the fee. */
+    async approveBuilderFee(user, request, feeBps) {
+        const maxFeeRate = `${(feeBps / 100).toFixed(2)}%`;
+        if (!Number.isSafeInteger(feeBps) || feeBps < MIN_BUILDER_FEE_BPS || feeBps > MAX_BUILDER_FEE_BPS) {
+            throw new HyperliquidError("Builder fee must be between 1 and 10 basis points.");
+        }
+        await this.relayBuilderFee(user, request, maxFeeRate);
+        await this.ensureSettings(user.id);
+        await this.db.update(hvHyperliquidSettings).set({
+            builderFeeTenthsOfBp: feeBps * BUILDER_FEE_BPS_TO_TENTHS,
+            builderFeeApprovedAt: Date.now(),
+            updatedAt: Date.now(),
+        }).where(eq(hvHyperliquidSettings.userId, user.id)).run();
+    }
+    /** Relays a main-wallet-signed builder-fee revocation. */
+    async cancelBuilderFee(user, request) {
+        await this.relayBuilderFee(user, request, REVOKED_BUILDER_FEE_RATE);
+        await this.db.update(hvHyperliquidSettings).set({ builderFeeApprovedAt: null, updatedAt: Date.now() })
+            .where(eq(hvHyperliquidSettings.userId, user.id)).run();
+    }
+    async relayBuilderFee(user, request, maxFeeRate) {
+        const signed = parseSignedAction(request);
+        if (!validApproveBuilderFeeAction(signed.action, maxFeeRate)
+            || !(await signatureMatches(signed.action, signed.signature, user.walletAddress, "approveBuilderFee"))) {
+            throw new HyperliquidError("Invalid builder fee approval.");
+        }
+        const exchange = await this.relay(signed);
+        if (!exchangeSuccess(exchange)) {
+            throw new HyperliquidError(exchangeErrorMessage(exchange), 502);
+        }
+    }
+    async relay(signed) {
+        try {
+            return await relaySignedAction(this.transport, signed.action, signed.signature);
+        }
+        catch {
+            throw new HyperliquidError("Hyperliquid exchange unavailable", 502);
+        }
+    }
+    /** Reconciles the stored builder fee with Hyperliquid's current maximum. */
+    async reconcileBuilderFee(user) {
+        const row = await this.settings(user.id);
+        const saved = row?.builderFeeTenthsOfBp ?? 0;
+        try {
+            const remote = await maxBuilderFee(this.transport, user.walletAddress, BUILDER_RECIPIENT);
+            const capped = Math.min(remote, MAX_BUILDER_FEE_TENTHS_OF_BP);
+            const tenths = capped > 0 && capped !== saved ? capped : saved;
+            // Coverage must be judged against the value synced from Hyperliquid,
+            // never against a stale pre-sync value: a first visit by a user who
+            // already approved the fee on Hyperliquid must show as approved.
+            const covered = tenths > 0 && remote >= tenths;
+            if (tenths !== saved) {
+                await this.ensureSettings(user.id);
+                await this.db.update(hvHyperliquidSettings).set({ builderFeeTenthsOfBp: tenths, updatedAt: Date.now() })
+                    .where(eq(hvHyperliquidSettings.userId, user.id)).run();
+            }
+            if (covered && !row?.builderFeeApprovedAt) {
+                await this.ensureSettings(user.id);
+                await this.db.update(hvHyperliquidSettings).set({ builderFeeApprovedAt: Date.now(), updatedAt: Date.now() })
+                    .where(and(eq(hvHyperliquidSettings.userId, user.id), isNull(hvHyperliquidSettings.builderFeeApprovedAt))).run();
+            }
+            else if (!covered && row?.builderFeeApprovedAt) {
+                await this.db.update(hvHyperliquidSettings).set({ builderFeeApprovedAt: null, updatedAt: Date.now() })
+                    .where(and(eq(hvHyperliquidSettings.userId, user.id), isNotNull(hvHyperliquidSettings.builderFeeApprovedAt))).run();
+            }
+            const feeBps = tenths > 0 && tenths % BUILDER_FEE_BPS_TO_TENTHS === 0
+                ? Math.min(Math.max(tenths / BUILDER_FEE_BPS_TO_TENTHS, MIN_BUILDER_FEE_BPS), MAX_BUILDER_FEE_BPS)
+                : DEFAULT_BUILDER_FEE_BPS;
+            return { feeBps, approved: covered };
+        }
+        catch {
+            // Keep the last known approval when the lookup fails.
+            return { feeBps: this.displayFeeBps(saved), approved: Boolean(row?.builderFeeApprovedAt) };
+        }
+    }
+    displayFeeBps(tenths) {
+        return tenths > 0 && tenths % BUILDER_FEE_BPS_TO_TENTHS === 0
+            ? Math.min(Math.max(tenths / BUILDER_FEE_BPS_TO_TENTHS, MIN_BUILDER_FEE_BPS), MAX_BUILDER_FEE_BPS)
+            : DEFAULT_BUILDER_FEE_BPS;
+    }
+    /** Assembles the full Account page view for a signed-in wallet. */
+    async accountView(user) {
+        const [row, accounts, builderFee] = await Promise.all([
+            this.settings(user.id),
+            loadOwnedTradingAccounts(this.transport, user.walletAddress, { includeCapacity: false }),
+            this.reconcileBuilderFee(user),
+        ]);
+        const assignments = await this.db.select({
+            address: hvAgents.tradingAccountAddress,
+            agentId: hvAgents.id,
+            agentName: hvAgents.name,
+        }).from(hvAgents).where(isNotNull(hvAgents.tradingAccountAddress)).all();
+        const assignmentFor = (address) => assignments
+            .find((assignment) => assignment.address?.toLowerCase() === address.toLowerCase());
+        const rows = [this.accountRow("Main Account", accounts.mainAddress, accounts.mainBalance, assignmentFor)];
+        for (const subaccount of accounts.subaccounts) {
+            rows.push(this.accountRow(subaccount.name ?? "Unnamed subaccount", subaccount.address, subaccount.balance, assignmentFor));
+        }
+        const total = rows.length > 1 ? this.totalBalance(accounts) : null;
+        return {
+            walletAddress: user.walletAddress,
+            accountMode: accounts.accountMode,
+            accountModeMessage: accountModeError(accounts.accountMode),
+            encryptionConfigured: Boolean(this.encryptionKey),
+            apiWallet: this.apiWalletView(row),
+            builderFee,
+            accounts: rows,
+            totalBalance: total,
+            lookupError: accounts.lookupError,
+        };
+    }
+    accountRow(name, address, balance, assignmentFor) {
+        const assignment = assignmentFor(address);
+        return {
+            name,
+            address,
+            agentId: assignment?.agentId ?? null,
+            agentName: assignment?.agentName ?? null,
+            balance,
+        };
+    }
+    totalBalance(accounts) {
+        let total = "0";
+        for (const balance of [accounts.mainBalance, ...accounts.subaccounts.map((subaccount) => subaccount.balance)]) {
+            if (!balance)
+                return null;
+            total = addDecimals(total, balance);
+            if (!total)
+                return null;
+        }
+        return total;
+    }
+    /** Account choices for the Create Agent page. */
+    async tradingAccountChoices(user) {
+        const [row, accounts] = await Promise.all([
+            this.settings(user.id),
+            loadOwnedTradingAccounts(this.transport, user.walletAddress, { includeCapacity: true }),
+        ]);
+        const assignments = await this.db.select({
+            address: hvAgents.tradingAccountAddress,
+            agentId: hvAgents.id,
+            agentName: hvAgents.name,
+        }).from(hvAgents).where(isNotNull(hvAgents.tradingAccountAddress)).all();
+        const assignmentFor = (address) => assignments
+            .find((assignment) => assignment.address?.toLowerCase() === address.toLowerCase());
+        const mainAssignment = assignmentFor(accounts.mainAddress);
+        return {
+            mainAddress: accounts.mainAddress,
+            mainBalance: accounts.mainBalance,
+            mainAssignedTo: mainAssignment?.agentName ?? null,
+            subaccounts: accounts.subaccounts.map((subaccount) => ({
+                name: subaccount.name,
+                address: subaccount.address,
+                balance: subaccount.balance,
+                assignedTo: assignmentFor(subaccount.address) ?? null,
+            })),
+            subaccountCapacity: accounts.subaccountCapacity,
+            lookupError: accounts.lookupError ?? accountModeError(accounts.accountMode),
+            accountModeSupported: accounts.accountMode === "unified",
+            apiWalletReady: this.apiWalletIsReady(row),
+        };
+    }
+    /** Creates a Hyperliquid sub-account for an agent using the trading signer. */
+    async createAgentSubaccount(user, displayName) {
+        const name = agentSubaccountName(displayName);
+        if (!name || name === "vt-")
+            throw new HyperliquidError("Enter an agent name first.");
+        const privateKey = await this.decryptSigner(user.id);
+        const result = await this.creator.create(user.walletAddress.toLowerCase(), name, privateKey);
+        if (!result.ok) {
+            throw new HyperliquidError(result.failure.kind === "rejected" ? result.failure.message
+                : result.failure.kind === "lookup-unavailable" ? "Hyperliquid account data is temporarily unavailable."
+                    : "Sub-Account creation could not be confirmed. Refresh the account list before retrying.", result.failure.kind === "rejected" ? 422 : 502);
+        }
+        return result.subaccount;
+    }
+    /** Loads the decrypted trading signer for exchange signing only. */
+    async decryptSigner(userId) {
+        if (!this.encryptionKey)
+            throw new HyperliquidError("Trading signer storage is not configured on the server", 503);
+        const row = await this.settings(userId);
+        if (!row || !this.apiWalletIsReady(row))
+            throw new HyperliquidError("Set up and approve a trading signer first.", 409);
+        if (!row.privateKeyCiphertext)
+            throw new HyperliquidError("The stored trading signer is incomplete.", 409);
+        if (row.privateKeyKeyId !== this.encryptionKey.id) {
+            throw new HyperliquidError("The stored trading signer uses an unknown encryption key.", 409);
+        }
+        try {
+            return decryptSecret(this.encryptionKey, new Uint8Array(row.privateKeyCiphertext));
+        }
+        catch {
+            throw new HyperliquidError("The stored trading signer could not be decrypted.", 409);
+        }
+    }
+}

package/dist/hyperliquid/shared-feeds.js

@@ -0,0 +1,40 @@
+import { SubscriptionClient, WebSocketTransport } from "@nktkas/hyperliquid";
+import { openAccountFeed } from "./live-dashboard.js";
+import { openJournalFeed } from "./journal-service.js";
+/** A single lazy, app-owned exchange socket shared by account and candle feeds. */
+export class SharedHyperliquidFeeds {
+    transport;
+    stopped = false;
+    socket() {
+        if (this.stopped)
+            throw new Error("Exchange feeds are closed");
+        return this.transport ??= new WebSocketTransport();
+    }
+    account = (address, events) => openAccountFeed(address, events, this.socket());
+    journal = (address, events) => openJournalFeed(address, events, this.socket());
+    candle = (selection, events) => {
+        const transport = this.socket();
+        const abort = new AbortController();
+        const connected = () => events.connected();
+        const disconnected = () => events.disconnected();
+        transport.socket.addEventListener("open", connected);
+        transport.socket.addEventListener("close", disconnected);
+        if (transport.socket.readyState === 1)
+            queueMicrotask(() => { if (!abort.signal.aborted)
+                connected(); });
+        const task = new SubscriptionClient({ transport }).candle(selection, (candle) => { if (!abort.signal.aborted)
+            events.update(candle); }, { signal: abort.signal, onError: () => { if (!abort.signal.aborted)
+                events.failed(); } });
+        void task.catch(() => { if (!abort.signal.aborted)
+            events.failed(); });
+        return { async close() {
+                transport.socket.removeEventListener("open", connected);
+                transport.socket.removeEventListener("close", disconnected);
+                abort.abort();
+                const [result] = await Promise.allSettled([task]);
+                if (result?.status === "fulfilled")
+                    await result.value.unsubscribe().catch(() => { });
+            } };
+    };
+    close() { this.stopped = true; this.transport?.close(); }
+}

package/dist/hyperliquid/signing.js

@@ -0,0 +1,89 @@
+import { isAddress, recoverTypedDataAddress } from "viem";
+import { BUILDER_RECIPIENT, SIGNATURE_CHAIN_ID, USER_API_WALLET_NAME, } from "./constants.js";
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+const FIELD_SETS = {
+    approveAgent: ["type", "hyperliquidChain", "signatureChainId", "agentAddress", "agentName", "nonce"],
+    approveBuilderFee: ["type", "hyperliquidChain", "signatureChainId", "maxFeeRate", "builder", "nonce"],
+};
+/** Narrow, validate and sanitize a client request body into a SignedAction. */
+export function parseSignedAction(value) {
+    if (typeof value !== "object" || value === null)
+        throw new Error("Invalid request");
+    const action = Reflect.get(value, "action");
+    const signature = Reflect.get(value, "signature");
+    if (typeof action !== "object" || action === null || Array.isArray(action))
+        throw new Error("Invalid request");
+    if (typeof signature !== "string" || !/^0x[0-9a-fA-F]{130}$/.test(signature))
+        throw new Error("Invalid request");
+    return { action: { ...action }, signature };
+}
+function hasExactFields(action, kind) {
+    const expected = FIELD_SETS[kind];
+    const keys = Object.keys(action);
+    return keys.length === expected.length && expected.every((field) => field in action);
+}
+function validCommon(action) {
+    const nonce = action.nonce;
+    return action.hyperliquidChain === "Mainnet"
+        && action.signatureChainId === "0xa4b1"
+        && typeof nonce === "number" && Number.isSafeInteger(nonce) && nonce > 0;
+}
+function isLowercaseAddress(value) {
+    return typeof value === "string" && isAddress(value) && value === value.toLowerCase();
+}
+/** The action must approve exactly this server-generated trading signer. */
+export function validApproveAgentAction(action, expectedAddress) {
+    return hasExactFields(action, "approveAgent")
+        && validCommon(action)
+        && action.type === "approveAgent"
+        && action.agentName === USER_API_WALLET_NAME
+        && isLowercaseAddress(action.agentAddress)
+        && action.agentAddress === expectedAddress;
+}
+/** The action must approve or revoke exactly this server's builder at the expected rate. */
+export function validApproveBuilderFeeAction(action, maxFeeRate) {
+    return hasExactFields(action, "approveBuilderFee")
+        && validCommon(action)
+        && action.type === "approveBuilderFee"
+        && action.builder === BUILDER_RECIPIENT
+        && action.maxFeeRate === maxFeeRate;
+}
+/**
+ * Recovers the signing address from an EIP-712 Hyperliquid action signature and
+ * compares it with the expected address. Invalid structures never match.
+ */
+export async function signatureMatches(action, signature, expectedAddress, kind) {
+    const primaryType = kind === "approveAgent"
+        ? "HyperliquidTransaction:ApproveAgent"
+        : "HyperliquidTransaction:ApproveBuilderFee";
+    try {
+        const recovered = await recoverTypedDataAddress({
+            domain: {
+                name: "HyperliquidSignTransaction",
+                version: "1",
+                chainId: SIGNATURE_CHAIN_ID,
+                verifyingContract: ZERO_ADDRESS,
+            },
+            types: kind === "approveAgent"
+                ? { [primaryType]: [
+                        { name: "hyperliquidChain", type: "string" },
+                        { name: "agentAddress", type: "address" },
+                        { name: "agentName", type: "string" },
+                        { name: "nonce", type: "uint64" },
+                    ] }
+                : { [primaryType]: [
+                        { name: "hyperliquidChain", type: "string" },
+                        { name: "maxFeeRate", type: "string" },
+                        { name: "builder", type: "address" },
+                        { name: "nonce", type: "uint64" },
+                    ] },
+            primaryType,
+            message: action,
+            signature: signature,
+        });
+        return recovered.toLowerCase() === expectedAddress.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}