@raintree-technology/perps 0.1.0

package/dist/lib/validate.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Input Validation Utilities
+ * Validates and sanitizes CLI inputs
+ */
+export declare class ValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate and parse a positive number
+ */
+export declare function parsePositiveNumber(value: string | undefined, name: string, defaultValue?: number): number;
+/**
+ * Validate and parse a positive integer
+ */
+export declare function parsePositiveInt(value: string | undefined, name: string, defaultValue?: number): number;
+/**
+ * Validate and parse a number within a range
+ */
+export declare function parseNumberInRange(value: string | undefined, name: string, min: number, max: number, defaultValue?: number): number;
+/**
+ * Validate asset symbol
+ */
+export declare function validateAsset(asset: string | undefined, defaultAsset?: string): string;
+/**
+ * Validate market symbol
+ */
+export declare function validateMarket(market: string | undefined, defaultMarket?: string): string;
+/**
+ * Parse comma-separated list of assets
+ */
+export declare function parseAssetList(value: string | undefined, defaultAssets: readonly string[]): string[];
+/**
+ * Validate exchange ID
+ */
+export declare function validateExchange(exchangeId: string, validExchanges: string[]): string;
+/**
+ * Validate USD size
+ */
+export declare function validateSize(value: string | undefined, defaultSize?: number): number;

package/dist/lib/validate.js

@@ -0,0 +1,108 @@
+/**
+ * Input Validation Utilities
+ * Validates and sanitizes CLI inputs
+ */
+export class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ValidationError";
+    }
+}
+/**
+ * Validate and parse a positive number
+ */
+export function parsePositiveNumber(value, name, defaultValue) {
+    if (value === undefined || value === "") {
+        if (defaultValue !== undefined)
+            return defaultValue;
+        throw new ValidationError(`${name} is required`);
+    }
+    const num = parseFloat(value);
+    if (isNaN(num)) {
+        throw new ValidationError(`${name} must be a valid number, got: ${value}`);
+    }
+    if (num <= 0) {
+        throw new ValidationError(`${name} must be positive, got: ${num}`);
+    }
+    return num;
+}
+/**
+ * Validate and parse a positive integer
+ */
+export function parsePositiveInt(value, name, defaultValue) {
+    const num = parsePositiveNumber(value, name, defaultValue);
+    if (!Number.isInteger(num)) {
+        throw new ValidationError(`${name} must be an integer, got: ${num}`);
+    }
+    return num;
+}
+/**
+ * Validate and parse a number within a range
+ */
+export function parseNumberInRange(value, name, min, max, defaultValue) {
+    const num = parsePositiveNumber(value, name, defaultValue);
+    if (num < min || num > max) {
+        throw new ValidationError(`${name} must be between ${min} and ${max}, got: ${num}`);
+    }
+    return num;
+}
+/**
+ * Validate asset symbol
+ */
+export function validateAsset(asset, defaultAsset = "BTC") {
+    if (!asset)
+        return defaultAsset;
+    const normalized = asset.toUpperCase().trim();
+    // Basic validation: 1-10 alphanumeric characters
+    if (!/^[A-Z0-9]{1,10}$/.test(normalized)) {
+        throw new ValidationError(`Invalid asset symbol: ${asset}`);
+    }
+    return normalized;
+}
+/**
+ * Validate market symbol
+ */
+export function validateMarket(market, defaultMarket = "BTC-PERP") {
+    if (!market)
+        return defaultMarket;
+    const normalized = market.toUpperCase().trim();
+    // Format: ASSET-PERP or ASSET-USD-PERP
+    if (!/^[A-Z0-9]{1,10}(-USD)?-PERP$/.test(normalized)) {
+        throw new ValidationError(`Invalid market symbol: ${market}. Expected format: ASSET-PERP`);
+    }
+    return normalized;
+}
+/**
+ * Parse comma-separated list of assets
+ */
+export function parseAssetList(value, defaultAssets) {
+    if (!value)
+        return [...defaultAssets];
+    return value
+        .split(",")
+        .map(a => validateAsset(a.trim()))
+        .filter((a, i, arr) => arr.indexOf(a) === i); // dedupe
+}
+/**
+ * Validate exchange ID
+ */
+export function validateExchange(exchangeId, validExchanges) {
+    const normalized = exchangeId.toLowerCase().trim();
+    if (!validExchanges.includes(normalized)) {
+        throw new ValidationError(`Invalid exchange: ${exchangeId}. Valid options: ${validExchanges.join(", ")}`);
+    }
+    return normalized;
+}
+/**
+ * Validate USD size
+ */
+export function validateSize(value, defaultSize = 1000) {
+    const size = parsePositiveNumber(value, "size", defaultSize);
+    if (size < 10) {
+        throw new ValidationError("Position size must be at least $10");
+    }
+    if (size > 10_000_000) {
+        throw new ValidationError("Position size cannot exceed $10M");
+    }
+    return size;
+}

package/dist/lib/validation.d.ts

@@ -0,0 +1,9 @@
+import type { Address, Hex } from "viem";
+export declare function validateAddress(value: string): Address;
+export declare function validateAptosLikeAddress(value: string): string;
+export declare function validateAddressForExchange(value: string, exchangeId: string): string;
+export declare function validatePrivateKey(value: string): Hex;
+export declare function validatePositiveNumber(value: string, name: string): number;
+export declare function validatePositiveInteger(value: string, name: string): number;
+export declare function validateSide(value: string): "buy" | "sell";
+export declare function validateTif(value: string): "Gtc" | "Ioc" | "Alo";

package/dist/lib/validation.js

@@ -0,0 +1,64 @@
+export function validateAddress(value) {
+    if (!/^0x[a-fA-F0-9]{40}$/.test(value)) {
+        throw new Error(`Invalid address: ${value}`);
+    }
+    return value;
+}
+export function validateAptosLikeAddress(value) {
+    if (!/^0x[a-fA-F0-9]{1,64}$/.test(value)) {
+        throw new Error(`Invalid address: ${value}`);
+    }
+    return value;
+}
+export function validateAddressForExchange(value, exchangeId) {
+    const normalized = exchangeId.trim().toLowerCase();
+    if (normalized === "decibel" || normalized === "paradex") {
+        return validateAptosLikeAddress(value);
+    }
+    if (normalized === "orderly") {
+        if (!value.trim()) {
+            throw new Error("Invalid account identifier: value cannot be empty");
+        }
+        return value.trim();
+    }
+    return validateAddress(value);
+}
+export function validatePrivateKey(value) {
+    if (!/^0x[a-fA-F0-9]{64}$/.test(value)) {
+        throw new Error("Invalid private key format");
+    }
+    return value;
+}
+export function validatePositiveNumber(value, name) {
+    const num = parseFloat(value);
+    if (isNaN(num) || num <= 0) {
+        throw new Error(`${name} must be a positive number`);
+    }
+    return num;
+}
+export function validatePositiveInteger(value, name) {
+    const num = parseInt(value, 10);
+    if (isNaN(num) || num <= 0) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return num;
+}
+export function validateSide(value) {
+    const lower = value.toLowerCase();
+    if (lower !== "buy" && lower !== "sell") {
+        throw new Error('Side must be "buy" or "sell"');
+    }
+    return lower;
+}
+export function validateTif(value) {
+    const mapping = {
+        gtc: "Gtc",
+        ioc: "Ioc",
+        alo: "Alo",
+    };
+    const result = mapping[value.toLowerCase()];
+    if (!result) {
+        throw new Error('Time-in-force must be "Gtc", "Ioc", or "Alo"');
+    }
+    return result;
+}

package/dist/server/cache.d.ts

@@ -0,0 +1,38 @@
+import { AllPerpMetasResponse, SpotMetaResponse } from "@nktkas/hyperliquid";
+import { AllDexsAssetCtxsEvent, SpotAssetCtxsEvent } from "@nktkas/hyperliquid/api/subscription";
+export interface CacheEntry<T> {
+    data: T;
+    updatedAt: number;
+}
+export interface AllMidsData {
+    [coin: string]: string;
+}
+export declare class ServerCache {
+    private allMids;
+    private allDexsAssetCtxs;
+    private allPerpMetas;
+    private spotMeta;
+    private spotAssetCtxs;
+    setAllMids(data: AllMidsData): void;
+    setAllDexsAssetCtxs(data: AllDexsAssetCtxsEvent): void;
+    setAllPerpMetas(data: AllPerpMetasResponse): void;
+    setSpotMeta(data: SpotMetaResponse): void;
+    setSpotAssetCtxs(data: SpotAssetCtxsEvent): void;
+    getAllMids(): CacheEntry<AllMidsData> | null;
+    getAllDexsAssetCtxs(): CacheEntry<AllDexsAssetCtxsEvent> | null;
+    getAllPerpMetas(): CacheEntry<AllPerpMetasResponse> | null;
+    getSpotMeta(): CacheEntry<SpotMetaResponse> | null;
+    getSpotAssetCtxs(): CacheEntry<SpotAssetCtxsEvent> | null;
+    getStatus(): {
+        hasMids: boolean;
+        hasAssetCtxs: boolean;
+        hasPerpMetas: boolean;
+        hasSpotMeta: boolean;
+        hasSpotAssetCtxs: boolean;
+        midsAge?: number;
+        assetCtxsAge?: number;
+        perpMetasAge?: number;
+        spotMetaAge?: number;
+        spotAssetCtxsAge?: number;
+    };
+}

package/dist/server/cache.js

@@ -0,0 +1,56 @@
+// In-memory cache for real-time data from WebSocket subscriptions
+export class ServerCache {
+    allMids = null;
+    allDexsAssetCtxs = null;
+    allPerpMetas = null;
+    spotMeta = null;
+    spotAssetCtxs = null;
+    // Update methods - called from subscription handlers
+    setAllMids(data) {
+        this.allMids = { data, updatedAt: Date.now() };
+    }
+    setAllDexsAssetCtxs(data) {
+        this.allDexsAssetCtxs = { data, updatedAt: Date.now() };
+    }
+    setAllPerpMetas(data) {
+        this.allPerpMetas = { data, updatedAt: Date.now() };
+    }
+    setSpotMeta(data) {
+        this.spotMeta = { data, updatedAt: Date.now() };
+    }
+    setSpotAssetCtxs(data) {
+        this.spotAssetCtxs = { data, updatedAt: Date.now() };
+    }
+    // Get methods - return data with cache timestamp
+    getAllMids() {
+        return this.allMids;
+    }
+    getAllDexsAssetCtxs() {
+        return this.allDexsAssetCtxs;
+    }
+    getAllPerpMetas() {
+        return this.allPerpMetas;
+    }
+    getSpotMeta() {
+        return this.spotMeta;
+    }
+    getSpotAssetCtxs() {
+        return this.spotAssetCtxs;
+    }
+    // Get status info
+    getStatus() {
+        const now = Date.now();
+        return {
+            hasMids: this.allMids !== null,
+            hasAssetCtxs: this.allDexsAssetCtxs !== null,
+            hasPerpMetas: this.allPerpMetas !== null,
+            hasSpotMeta: this.spotMeta !== null,
+            hasSpotAssetCtxs: this.spotAssetCtxs !== null,
+            midsAge: this.allMids ? now - this.allMids.updatedAt : undefined,
+            assetCtxsAge: this.allDexsAssetCtxs ? now - this.allDexsAssetCtxs.updatedAt : undefined,
+            perpMetasAge: this.allPerpMetas ? now - this.allPerpMetas.updatedAt : undefined,
+            spotMetaAge: this.spotMeta ? now - this.spotMeta.updatedAt : undefined,
+            spotAssetCtxsAge: this.spotAssetCtxs ? now - this.spotAssetCtxs.updatedAt : undefined,
+        };
+    }
+}

package/dist/server/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server/index.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import { writeFileSync, appendFileSync, unlinkSync, existsSync } from "node:fs";
+import { HL_DIR, SERVER_PID_PATH, SERVER_LOG_PATH, SERVER_CONFIG_PATH, SERVER_SOCKET_PATH, } from "../lib/paths.js";
+import { ServerCache } from "./cache.js";
+import { SubscriptionManager } from "./subscriptions.js";
+import { IPCServer } from "./ipc.js";
+import { ensurePrivateDir, hardenPrivateFile, PRIVATE_FILE_MODE, } from "../lib/fs-security.js";
+// Parse command line args
+const args = process.argv.slice(2);
+const isTestnet = args.includes("--testnet");
+// Ensure runtime directory exists and remains owner-only.
+ensurePrivateDir(HL_DIR);
+// Logging
+function log(msg) {
+    const timestamp = new Date().toISOString();
+    const line = `[${timestamp}] ${msg}\n`;
+    appendFileSync(SERVER_LOG_PATH, line);
+    hardenPrivateFile(SERVER_LOG_PATH);
+}
+// Initialize
+const startedAt = Date.now();
+log(`Starting server (testnet: ${isTestnet}, pid: ${process.pid})`);
+// Write PID file
+writeFileSync(SERVER_PID_PATH, String(process.pid), { mode: PRIVATE_FILE_MODE });
+hardenPrivateFile(SERVER_PID_PATH);
+// Write config file
+const config = { testnet: isTestnet, startedAt };
+writeFileSync(SERVER_CONFIG_PATH, JSON.stringify(config, null, 2));
+hardenPrivateFile(SERVER_CONFIG_PATH);
+// Create cache and managers
+const cache = new ServerCache();
+const subscriptions = new SubscriptionManager(cache, isTestnet, log);
+let ipcServer = null;
+// Graceful shutdown
+async function shutdown(reason) {
+    log(`Shutting down: ${reason}`);
+    try {
+        // Stop IPC server first
+        if (ipcServer) {
+            await ipcServer.stop();
+        }
+        // Stop subscriptions
+        await subscriptions.stop();
+        // Clean up files
+        if (existsSync(SERVER_PID_PATH)) {
+            unlinkSync(SERVER_PID_PATH);
+        }
+        if (existsSync(SERVER_SOCKET_PATH)) {
+            unlinkSync(SERVER_SOCKET_PATH);
+        }
+        if (existsSync(SERVER_CONFIG_PATH)) {
+            unlinkSync(SERVER_CONFIG_PATH);
+        }
+        log("Shutdown complete");
+    }
+    catch (err) {
+        log(`Shutdown error: ${err}`);
+    }
+    process.exit(0);
+}
+// Signal handlers
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("uncaughtException", (err) => {
+    log(`Uncaught exception: ${err.message}`);
+    shutdown("uncaught exception").catch(() => process.exit(1));
+});
+process.on("unhandledRejection", (reason) => {
+    log(`Unhandled rejection: ${reason}`);
+    shutdown("unhandled rejection").catch(() => process.exit(1));
+});
+// Start server
+async function start() {
+    try {
+        // Start WebSocket subscriptions
+        await subscriptions.start();
+        // Start IPC server
+        ipcServer = new IPCServer(cache, subscriptions, isTestnet, startedAt, log, () => {
+            shutdown("shutdown request");
+        });
+        await ipcServer.start();
+        log("Server started successfully");
+    }
+    catch (err) {
+        log(`Failed to start server: ${err}`);
+        await shutdown("startup error");
+    }
+}
+start();

package/dist/server/ipc.d.ts

@@ -0,0 +1,18 @@
+import type { ServerCache } from "./cache.js";
+import type { SubscriptionManager } from "./subscriptions.js";
+export declare class IPCServer {
+    private server;
+    private cache;
+    private subscriptions;
+    private isTestnet;
+    private startedAt;
+    private log;
+    private onShutdown;
+    constructor(cache: ServerCache, subscriptions: SubscriptionManager, isTestnet: boolean, startedAt: number, log: (msg: string) => void, onShutdown: () => void);
+    start(): Promise<void>;
+    private handleConnection;
+    private handleMessage;
+    private handleRequest;
+    private sendResponse;
+    stop(): Promise<void>;
+}

package/dist/server/ipc.js

@@ -0,0 +1,159 @@
+import { createServer } from "node:net";
+import { existsSync, unlinkSync } from "node:fs";
+import { SERVER_SOCKET_PATH } from "../lib/paths.js";
+export class IPCServer {
+    server = null;
+    cache;
+    subscriptions;
+    isTestnet;
+    startedAt;
+    log;
+    onShutdown;
+    constructor(cache, subscriptions, isTestnet, startedAt, log, onShutdown) {
+        this.cache = cache;
+        this.subscriptions = subscriptions;
+        this.isTestnet = isTestnet;
+        this.startedAt = startedAt;
+        this.log = log;
+        this.onShutdown = onShutdown;
+    }
+    async start() {
+        // Remove existing socket file if it exists
+        if (existsSync(SERVER_SOCKET_PATH)) {
+            unlinkSync(SERVER_SOCKET_PATH);
+        }
+        return new Promise((resolve, reject) => {
+            this.server = createServer((socket) => {
+                this.handleConnection(socket);
+            });
+            this.server.on("error", (err) => {
+                this.log(`IPC server error: ${err.message}`);
+                reject(err);
+            });
+            this.server.listen(SERVER_SOCKET_PATH, () => {
+                this.log(`IPC server listening on ${SERVER_SOCKET_PATH}`);
+                resolve();
+            });
+        });
+    }
+    handleConnection(socket) {
+        let buffer = "";
+        socket.on("data", (data) => {
+            buffer += data.toString();
+            // Process complete messages (newline-delimited)
+            const lines = buffer.split("\n");
+            buffer = lines.pop() || "";
+            for (const line of lines) {
+                if (line.trim()) {
+                    this.handleMessage(socket, line);
+                }
+            }
+        });
+        socket.on("error", (err) => {
+            this.log(`Socket error: ${err.message}`);
+        });
+    }
+    handleMessage(socket, message) {
+        let request;
+        try {
+            request = JSON.parse(message);
+        }
+        catch {
+            this.sendResponse(socket, { id: "0", error: "Invalid JSON" });
+            return;
+        }
+        const response = this.handleRequest(request);
+        this.sendResponse(socket, response);
+    }
+    handleRequest(request) {
+        const { id, method, params } = request;
+        switch (method) {
+            case "getPrices": {
+                const entry = this.cache.getAllMids();
+                if (!entry) {
+                    return { id, error: "No data available" };
+                }
+                const coin = params?.coin;
+                if (coin) {
+                    const normalizedCoin = coin.trim().toUpperCase();
+                    const price = entry.data[normalizedCoin];
+                    if (price === undefined) {
+                        return { id, error: `Coin not found: ${normalizedCoin}` };
+                    }
+                    return { id, result: { [normalizedCoin]: price }, cached_at: entry.updatedAt };
+                }
+                return { id, result: entry.data, cached_at: entry.updatedAt };
+            }
+            case "getAssetCtxs": {
+                const entry = this.cache.getAllDexsAssetCtxs();
+                if (!entry) {
+                    return { id, error: "No data available" };
+                }
+                return { id, result: entry.data, cached_at: entry.updatedAt };
+            }
+            case "getPerpMeta": {
+                const entry = this.cache.getAllPerpMetas();
+                if (!entry) {
+                    return { id, error: "No data available" };
+                }
+                return { id, result: entry.data, cached_at: entry.updatedAt };
+            }
+            case "getSpotMeta": {
+                const entry = this.cache.getSpotMeta();
+                if (!entry) {
+                    return { id, error: "No data available" };
+                }
+                return { id, result: entry.data, cached_at: entry.updatedAt };
+            }
+            case "getSpotAssetCtxs": {
+                const entry = this.cache.getSpotAssetCtxs();
+                if (!entry) {
+                    return { id, error: "No data available" };
+                }
+                return { id, result: entry.data, cached_at: entry.updatedAt };
+            }
+            case "getStatus": {
+                const cacheStatus = this.cache.getStatus();
+                return {
+                    id,
+                    result: {
+                        running: true,
+                        testnet: this.isTestnet,
+                        connected: this.subscriptions.isConnected(),
+                        startedAt: this.startedAt,
+                        uptime: Date.now() - this.startedAt,
+                        cache: cacheStatus,
+                    },
+                };
+            }
+            case "shutdown": {
+                // Respond first, then shutdown
+                setTimeout(() => this.onShutdown(), 100);
+                return { id, result: { ok: true } };
+            }
+            default:
+                return { id, error: `Unknown method: ${method}` };
+        }
+    }
+    sendResponse(socket, response) {
+        try {
+            socket.write(JSON.stringify(response) + "\n");
+        }
+        catch {
+            // Socket may have closed
+        }
+    }
+    async stop() {
+        return new Promise((resolve) => {
+            if (this.server) {
+                this.server.close(() => {
+                    this.log("IPC server stopped");
+                    resolve();
+                });
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+}

package/dist/server/subscriptions.d.ts

@@ -0,0 +1,18 @@
+import type { ServerCache } from "./cache.js";
+export declare class SubscriptionManager {
+    private wsTransport;
+    private subscriptionClient;
+    private infoClient;
+    private cache;
+    private subscriptions;
+    private perpMetaInterval;
+    private spotMetaInterval;
+    private isTestnet;
+    private log;
+    constructor(cache: ServerCache, isTestnet: boolean, log: (msg: string) => void);
+    start(): Promise<void>;
+    private fetchPerpMetas;
+    private fetchSpotMeta;
+    stop(): Promise<void>;
+    isConnected(): boolean;
+}