@raintree-technology/perps 0.1.0

package/dist/lib/operator-state.d.ts

@@ -0,0 +1,25 @@
+export interface OperatorHeartbeatSnapshot {
+    exchange: string;
+    market?: string;
+    equity: number;
+    exposureUsd: number;
+    drawdownPct: number;
+    peakEquity: number;
+    halted: boolean;
+    haltReason?: string;
+    updatedAt: number;
+}
+export interface KillSwitchState {
+    enabled: boolean;
+    reason?: string;
+    updatedAt: number;
+}
+export interface OperatorState {
+    heartbeat: OperatorHeartbeatSnapshot | null;
+    killSwitch: KillSwitchState;
+}
+export declare function readOperatorState(): OperatorState;
+export declare function writeOperatorState(state: OperatorState): void;
+export declare function updateOperatorHeartbeat(heartbeat: OperatorHeartbeatSnapshot): OperatorState;
+export declare function setKillSwitch(enabled: boolean, reason?: string): OperatorState;
+export declare function resetOperatorState(): void;

package/dist/lib/operator-state.js

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { eventBus } from "./events/bus.js";
+import { HL_DIR, OPERATOR_STATE_PATH } from "./paths.js";
+import { ensurePrivateDir, hardenPrivateFile, PRIVATE_FILE_MODE } from "./fs-security.js";
+const DEFAULT_OPERATOR_STATE = {
+    heartbeat: null,
+    killSwitch: {
+        enabled: false,
+        updatedAt: 0,
+    },
+};
+function ensureOperatorStateDir() {
+    ensurePrivateDir(HL_DIR);
+}
+export function readOperatorState() {
+    ensureOperatorStateDir();
+    if (!existsSync(OPERATOR_STATE_PATH)) {
+        return { ...DEFAULT_OPERATOR_STATE };
+    }
+    try {
+        const raw = readFileSync(OPERATOR_STATE_PATH, "utf-8");
+        const parsed = JSON.parse(raw);
+        return {
+            heartbeat: parsed.heartbeat ?? null,
+            killSwitch: {
+                enabled: parsed.killSwitch?.enabled ?? false,
+                reason: parsed.killSwitch?.reason,
+                updatedAt: parsed.killSwitch?.updatedAt ?? 0,
+            },
+        };
+    }
+    catch {
+        return { ...DEFAULT_OPERATOR_STATE };
+    }
+}
+export function writeOperatorState(state) {
+    ensureOperatorStateDir();
+    writeFileSync(OPERATOR_STATE_PATH, `${JSON.stringify(state, null, 2)}\n`, {
+        encoding: "utf-8",
+        mode: PRIVATE_FILE_MODE,
+    });
+    hardenPrivateFile(OPERATOR_STATE_PATH);
+}
+export function updateOperatorHeartbeat(heartbeat) {
+    const state = readOperatorState();
+    const next = {
+        ...state,
+        heartbeat,
+    };
+    writeOperatorState(next);
+    return next;
+}
+export function setKillSwitch(enabled, reason) {
+    const state = readOperatorState();
+    const next = {
+        ...state,
+        killSwitch: {
+            enabled,
+            reason,
+            updatedAt: Date.now(),
+        },
+    };
+    writeOperatorState(next);
+    if (enabled) {
+        eventBus.emit("operator.halt", {
+            reason: reason ?? "Manual kill switch",
+            source: "manual",
+            timestamp: Date.now(),
+        });
+    }
+    else {
+        eventBus.emit("operator.resume", {
+            timestamp: Date.now(),
+        });
+    }
+    return next;
+}
+export function resetOperatorState() {
+    writeOperatorState({
+        ...DEFAULT_OPERATOR_STATE,
+    });
+}

package/dist/lib/orders-watcher.d.ts

@@ -0,0 +1,24 @@
+import type { Address } from "viem";
+export interface OrderData {
+    oid: number;
+    coin: string;
+    side: string;
+    sz: string;
+    limitPx: string;
+    timestamp: number;
+}
+export interface OrdersWatcher {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface OrdersWatcherConfig {
+    user: Address;
+    isTestnet: boolean;
+    onUpdate: (orders: OrderData[]) => void;
+    onError: (error: Error) => void;
+}
+/**
+ * Creates an orders watcher that subscribes to orderUpdates
+ * and polls open orders on each update
+ */
+export declare function createOrdersWatcher(config: OrdersWatcherConfig): OrdersWatcher;

package/dist/lib/orders-watcher.js

@@ -0,0 +1,74 @@
+import { WebSocketTransport, SubscriptionClient, HttpTransport, InfoClient, } from "@nktkas/hyperliquid";
+import WebSocket from "ws";
+/**
+ * Creates an orders watcher that subscribes to orderUpdates
+ * and polls open orders on each update
+ */
+export function createOrdersWatcher(config) {
+    let wsTransport = null;
+    let subscriptionClient = null;
+    let subscription = null;
+    let httpClient = null;
+    const fetchOrders = async () => {
+        if (!httpClient)
+            return [];
+        const orders = await httpClient.openOrders({ user: config.user, dex: "ALL_DEXS" });
+        return orders.map((o) => ({
+            oid: o.oid,
+            coin: o.coin,
+            side: o.side,
+            sz: o.sz,
+            limitPx: o.limitPx,
+            timestamp: o.timestamp,
+        }));
+    };
+    return {
+        async start() {
+            // Create HTTP client for polling open orders
+            const httpTransport = new HttpTransport({ isTestnet: config.isTestnet });
+            httpClient = new InfoClient({ transport: httpTransport });
+            // Fetch initial orders
+            const initialOrders = await fetchOrders();
+            config.onUpdate(initialOrders);
+            wsTransport = new WebSocketTransport({
+                isTestnet: config.isTestnet,
+                reconnect: { WebSocket: WebSocket },
+            });
+            subscriptionClient = new SubscriptionClient({ transport: wsTransport });
+            await wsTransport.ready();
+            // Subscribe to order updates
+            subscription = await subscriptionClient.orderUpdates({ user: config.user }, async () => {
+                // Re-fetch orders on any update
+                try {
+                    const orders = await fetchOrders();
+                    config.onUpdate(orders);
+                }
+                catch (err) {
+                    config.onError(err instanceof Error ? err : new Error(String(err)));
+                }
+            });
+        },
+        async stop() {
+            if (subscription) {
+                try {
+                    await subscription.unsubscribe();
+                }
+                catch {
+                    // Ignore errors during unsubscribe
+                }
+                subscription = null;
+            }
+            if (wsTransport) {
+                try {
+                    await wsTransport.close();
+                }
+                catch {
+                    // Ignore errors during close
+                }
+                wsTransport = null;
+            }
+            subscriptionClient = null;
+            httpClient = null;
+        },
+    };
+}

package/dist/lib/paths.d.ts

@@ -0,0 +1,20 @@
+export declare const PERP_DIR: string;
+export declare const LEGACY_HL_DIR: string;
+export declare const HL_DIR: string;
+export declare const SERVER_SOCKET_PATH: string;
+export declare const SERVER_PID_PATH: string;
+export declare const SERVER_LOG_PATH: string;
+export declare const SERVER_CONFIG_PATH: string;
+export declare const OPERATOR_STATE_PATH: string;
+export declare const TELEMETRY_PATH: string;
+export declare const CREDENTIAL_VAULT_PATH: string;
+export declare const ONBOARDING_STATE_DIR: string;
+export declare const AGENT_AUDIT_LOG_PATH: string;
+export declare const AGENT_METRICS_PATH: string;
+export declare const DB_PATH: string;
+export declare const LEGACY_DB_PATH: string;
+export declare const MASTER_KEY_PATH: string;
+export interface ServerConfig {
+    testnet: boolean;
+    startedAt: number;
+}

package/dist/lib/paths.js

@@ -0,0 +1,23 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+// Base directory for all perps runtime files
+export const PERP_DIR = join(homedir(), ".perp");
+// Legacy path retained for one-way migration helpers
+export const LEGACY_HL_DIR = join(homedir(), ".hl");
+// Backward-compatible alias for older imports
+export const HL_DIR = PERP_DIR;
+// Server files
+export const SERVER_SOCKET_PATH = join(PERP_DIR, "server.sock");
+export const SERVER_PID_PATH = join(PERP_DIR, "server.pid");
+export const SERVER_LOG_PATH = join(PERP_DIR, "server.log");
+export const SERVER_CONFIG_PATH = join(PERP_DIR, "server.json");
+export const OPERATOR_STATE_PATH = join(PERP_DIR, "operator-state.json");
+export const TELEMETRY_PATH = join(PERP_DIR, "telemetry.json");
+export const CREDENTIAL_VAULT_PATH = join(PERP_DIR, "credentials-vault.json");
+export const ONBOARDING_STATE_DIR = join(PERP_DIR, "onboarding");
+export const AGENT_AUDIT_LOG_PATH = join(PERP_DIR, "agent-audit.log");
+export const AGENT_METRICS_PATH = join(PERP_DIR, "agent-metrics.json");
+// Database files
+export const DB_PATH = join(PERP_DIR, "perp.db");
+export const LEGACY_DB_PATH = join(LEGACY_HL_DIR, "hl.db");
+export const MASTER_KEY_PATH = join(PERP_DIR, "master.key");

package/dist/lib/portfolio-watcher.d.ts

@@ -0,0 +1,33 @@
+import type { Address } from "viem";
+export interface PortfolioData {
+    positions: Array<{
+        coin: string;
+        size: string;
+        entryPx: string;
+        positionValue: string;
+        unrealizedPnl: string;
+        leverage: string;
+    }>;
+    spotBalances: Array<{
+        token: string;
+        total: string;
+        hold: string;
+    }>;
+    accountValue: string;
+    totalMarginUsed: string;
+}
+export interface PortfolioWatcher {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface PortfolioWatcherConfig {
+    user: Address;
+    isTestnet: boolean;
+    onUpdate: (data: PortfolioData) => void;
+    onError: (error: Error) => void;
+}
+/**
+ * Creates a portfolio watcher that subscribes to perp state updates
+ * and polls spot balances on each update
+ */
+export declare function createPortfolioWatcher(config: PortfolioWatcherConfig): PortfolioWatcher;

package/dist/lib/portfolio-watcher.js

@@ -0,0 +1,95 @@
+import { WebSocketTransport, SubscriptionClient, HttpTransport, InfoClient } from "@nktkas/hyperliquid";
+import WebSocket from "ws";
+/**
+ * Creates a portfolio watcher that subscribes to perp state updates
+ * and polls spot balances on each update
+ */
+export function createPortfolioWatcher(config) {
+    let wsTransport = null;
+    let subscriptionClient = null;
+    let perpSubscription = null;
+    let httpClient = null;
+    return {
+        async start() {
+            // Create HTTP client for spot balance polling
+            const httpTransport = new HttpTransport({ isTestnet: config.isTestnet });
+            httpClient = new InfoClient({ transport: httpTransport });
+            // Fetch initial spot state
+            const spotState = await httpClient.spotClearinghouseState({ user: config.user });
+            let currentSpotBalances = spotState.balances
+                .filter((b) => parseFloat(b.total) !== 0)
+                .map((b) => ({
+                token: b.coin,
+                total: b.total,
+                hold: b.hold,
+            }));
+            wsTransport = new WebSocketTransport({
+                isTestnet: config.isTestnet,
+                reconnect: { WebSocket: WebSocket },
+            });
+            subscriptionClient = new SubscriptionClient({ transport: wsTransport });
+            await wsTransport.ready();
+            // Subscribe to perp clearinghouse state
+            perpSubscription = await subscriptionClient.allDexsClearinghouseState({ user: config.user }, async (state) => {
+                const clearinghouseState = state.clearinghouseStates[0]?.[1];
+                const accountValue = clearinghouseState?.marginSummary.accountValue || "0";
+                const totalMarginUsed = clearinghouseState?.marginSummary.totalMarginUsed || "0";
+                const positions = state.clearinghouseStates
+                    .flatMap((c) => c[1].assetPositions)
+                    .filter((p) => parseFloat(p.position.szi) !== 0)
+                    .map((p) => ({
+                    coin: p.position.coin,
+                    size: p.position.szi,
+                    entryPx: p.position.entryPx,
+                    positionValue: p.position.positionValue,
+                    unrealizedPnl: p.position.unrealizedPnl,
+                    leverage: `${p.position.leverage.value}x ${p.position.leverage.type}`,
+                }));
+                // Refresh spot balances on each perp update
+                if (httpClient) {
+                    try {
+                        const freshSpotState = await httpClient.spotClearinghouseState({ user: config.user });
+                        currentSpotBalances = freshSpotState.balances
+                            .filter((b) => parseFloat(b.total) !== 0)
+                            .map((b) => ({
+                            token: b.coin,
+                            total: b.total,
+                            hold: b.hold,
+                        }));
+                    }
+                    catch {
+                        // Keep previous spot balances on error
+                    }
+                }
+                config.onUpdate({
+                    positions,
+                    spotBalances: currentSpotBalances,
+                    accountValue,
+                    totalMarginUsed,
+                });
+            });
+        },
+        async stop() {
+            if (perpSubscription) {
+                try {
+                    await perpSubscription.unsubscribe();
+                }
+                catch {
+                    // Ignore errors during unsubscribe
+                }
+                perpSubscription = null;
+            }
+            if (wsTransport) {
+                try {
+                    await wsTransport.close();
+                }
+                catch {
+                    // Ignore errors during close
+                }
+                wsTransport = null;
+            }
+            subscriptionClient = null;
+            httpClient = null;
+        },
+    };
+}

package/dist/lib/position-watcher.d.ts

@@ -0,0 +1,16 @@
+import type { Address } from "viem";
+import { AllDexsClearinghouseStateEvent } from "@nktkas/hyperliquid/api/subscription";
+export interface PositionWatcher {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface PositionWatcherConfig {
+    user: Address;
+    isTestnet: boolean;
+    onUpdate: (state: AllDexsClearinghouseStateEvent) => void;
+    onError: (error: Error) => void;
+}
+/**
+ * Creates a position watcher that subscribes to clearinghouseState updates via WebSocket
+ */
+export declare function createPositionWatcher(config: PositionWatcherConfig): PositionWatcher;

package/dist/lib/position-watcher.js

@@ -0,0 +1,44 @@
+import { WebSocketTransport, SubscriptionClient } from "@nktkas/hyperliquid";
+import WebSocket from "ws";
+/**
+ * Creates a position watcher that subscribes to clearinghouseState updates via WebSocket
+ */
+export function createPositionWatcher(config) {
+    let wsTransport = null;
+    let subscriptionClient = null;
+    let subscription = null;
+    return {
+        async start() {
+            wsTransport = new WebSocketTransport({
+                isTestnet: config.isTestnet,
+                reconnect: { WebSocket: WebSocket },
+            });
+            subscriptionClient = new SubscriptionClient({ transport: wsTransport });
+            await wsTransport.ready();
+            subscription = await subscriptionClient.allDexsClearinghouseState({ user: config.user }, (state) => {
+                config.onUpdate(state);
+            });
+        },
+        async stop() {
+            if (subscription) {
+                try {
+                    await subscription.unsubscribe();
+                }
+                catch {
+                    // Ignore errors during unsubscribe
+                }
+                subscription = null;
+            }
+            if (wsTransport) {
+                try {
+                    await wsTransport.close();
+                }
+                catch {
+                    // Ignore errors during close
+                }
+                wsTransport = null;
+            }
+            subscriptionClient = null;
+        },
+    };
+}

package/dist/lib/price-watcher.d.ts

@@ -0,0 +1,15 @@
+export interface PriceWatcher {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface PriceWatcherConfig {
+    coin: string;
+    isTestnet: boolean;
+    onUpdate: (price: string) => void;
+    onError: (error: Error) => void;
+}
+/**
+ * Creates a price watcher that uses server cache polling if available,
+ * otherwise falls back to direct WebSocket subscription
+ */
+export declare function createPriceWatcher(config: PriceWatcherConfig): PriceWatcher;

package/dist/lib/price-watcher.js

@@ -0,0 +1,84 @@
+import { tryConnectToServer } from "../client/index.js";
+import { WebSocketTransport, SubscriptionClient } from "@nktkas/hyperliquid";
+import WebSocket from "ws";
+/**
+ * Creates a price watcher that uses server cache polling if available,
+ * otherwise falls back to direct WebSocket subscription
+ */
+export function createPriceWatcher(config) {
+    let serverClient = null;
+    let pollInterval = null;
+    let wsTransport = null;
+    let subscription = null;
+    let stopped = false;
+    const pollServerPrice = async () => {
+        if (stopped || !serverClient)
+            return;
+        try {
+            const { data } = await serverClient.getPrices();
+            const price = data[config.coin];
+            if (price !== undefined) {
+                config.onUpdate(price);
+            }
+        }
+        catch (err) {
+            config.onError(err instanceof Error ? err : new Error(String(err)));
+        }
+    };
+    return {
+        async start() {
+            stopped = false;
+            // Try to use server cache first
+            serverClient = await tryConnectToServer();
+            if (serverClient) {
+                // Poll server every 500ms for price updates
+                await pollServerPrice();
+                pollInterval = setInterval(pollServerPrice, 500);
+            }
+            else {
+                // No server, use direct WebSocket subscription
+                wsTransport = new WebSocketTransport({
+                    isTestnet: config.isTestnet,
+                    reconnect: { WebSocket: WebSocket },
+                });
+                const subscriptionClient = new SubscriptionClient({ transport: wsTransport });
+                await wsTransport.ready();
+                subscription = await subscriptionClient.allMids({ dex: "ALL_DEXS" }, (event) => {
+                    const price = event.mids[config.coin];
+                    if (price !== undefined) {
+                        config.onUpdate(price);
+                    }
+                });
+            }
+        },
+        async stop() {
+            stopped = true;
+            if (pollInterval) {
+                clearInterval(pollInterval);
+                pollInterval = null;
+            }
+            if (serverClient) {
+                serverClient.close();
+                serverClient = null;
+            }
+            if (subscription) {
+                try {
+                    await subscription.unsubscribe();
+                }
+                catch {
+                    // Ignore errors during unsubscribe
+                }
+                subscription = null;
+            }
+            if (wsTransport) {
+                try {
+                    await wsTransport.close();
+                }
+                catch {
+                    // Ignore errors during close
+                }
+                wsTransport = null;
+            }
+        },
+    };
+}

package/dist/lib/prompts.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Prompt for text input
+ */
+export declare function prompt(question: string): Promise<string>;
+/**
+ * Prompt for selection from a list of options with arrow key navigation
+ */
+export declare function select<T extends string>(question: string, options: {
+    value: T;
+    label: string;
+    description?: string;
+}[]): Promise<T>;
+/**
+ * Prompt for multiple selections with checkboxes
+ */
+export declare function multiSelect<T extends string>(question: string, options: {
+    value: T;
+    label: string;
+    description?: string;
+}[]): Promise<T[]>;
+/**
+ * Prompt for yes/no confirmation
+ */
+export declare function confirm(question: string, defaultValue?: boolean): Promise<boolean>;
+/**
+ * Wait for user to press Enter
+ */
+export declare function waitForEnter(message?: string): Promise<void>;
+/**
+ * Wait for user to press Enter (returns true) or Escape (returns false)
+ */
+export declare function pressEnterOrEsc(message: string): Promise<boolean>;

package/dist/lib/prompts.js

@@ -0,0 +1,105 @@
+import { input, select as inquirerSelect, confirm as inquirerConfirm, checkbox, } from "@inquirer/prompts";
+import { inquirerTheme, highlighter } from "./ui-tokens.js";
+/**
+ * Prompt for text input
+ */
+export async function prompt(question) {
+    const answer = await input({
+        message: question,
+        theme: inquirerTheme,
+    });
+    return answer.trim();
+}
+/**
+ * Prompt for selection from a list of options with arrow key navigation
+ */
+export async function select(question, options) {
+    const result = await inquirerSelect({
+        message: question,
+        choices: options.map((opt) => ({
+            value: opt.value,
+            name: opt.label,
+            description: opt.description,
+        })),
+        theme: inquirerTheme,
+    });
+    return result;
+}
+/**
+ * Prompt for multiple selections with checkboxes
+ */
+export async function multiSelect(question, options) {
+    const results = await checkbox({
+        message: question,
+        choices: options.map((opt) => ({
+            value: opt.value,
+            name: opt.label,
+            description: opt.description,
+        })),
+        theme: inquirerTheme,
+    });
+    return results;
+}
+/**
+ * Prompt for yes/no confirmation
+ */
+export async function confirm(question, defaultValue = false) {
+    return inquirerConfirm({
+        message: question,
+        default: defaultValue,
+        theme: inquirerTheme,
+    });
+}
+/**
+ * Wait for user to press Enter
+ */
+export async function waitForEnter(message = "Press Enter to continue...") {
+    await input({
+        message,
+        theme: {
+            ...inquirerTheme,
+            prefix: {
+                idle: highlighter.warn("→"),
+                done: highlighter.success("✔"),
+            },
+        },
+    });
+}
+/**
+ * Wait for user to press Enter (returns true) or Escape (returns false)
+ */
+export async function pressEnterOrEsc(message) {
+    return new Promise((resolve) => {
+        console.log(`${highlighter.warn("→")} ${message}`);
+        const stdin = process.stdin;
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        const onData = (key) => {
+            const char = key.toString();
+            // Enter key
+            if (char === "\r" || char === "\n") {
+                cleanup();
+                console.log(`${highlighter.success("✔")} Opening browser...`);
+                resolve(true);
+            }
+            // Escape key
+            else if (char === "\x1b") {
+                cleanup();
+                console.log(`${highlighter.dimWhite("✔")} Skipped`);
+                resolve(false);
+            }
+            // Ctrl+C
+            else if (char === "\x03") {
+                cleanup();
+                process.exit(0);
+            }
+        };
+        const cleanup = () => {
+            stdin.removeListener("data", onData);
+            stdin.setRawMode(wasRaw);
+            stdin.pause();
+        };
+        stdin.on("data", onData);
+    });
+}