@raintree-technology/perps 0.1.0

package/dist/lib/execution/safety.js

@@ -0,0 +1,197 @@
+import { eventBus } from "../events/bus.js";
+import { createLogger } from "../logger.js";
+import { assertTradeAllowed } from "../trade-reputation.js";
+const log = createLogger("execution:safety");
+export async function executeOrderWithSafety(adapter, params, options = {}) {
+    assertTradeAllowed({
+        exchangeId: adapter.info.id,
+        market: params.market,
+        command: "order.execute",
+    });
+    let closedOppositePosition = false;
+    let orderParams = { ...params };
+    let pricing;
+    if (options.closeThenFlip && !params.reduceOnly) {
+        closedOppositePosition = await closeThenFlipIfNeeded(adapter, params.market, params.side);
+    }
+    if (options.spreadAwarePricing) {
+        const spreadAware = await resolveSpreadAwarePrice(adapter, params.market, params.side, options.spreadOffset ?? 0.3);
+        pricing = spreadAware;
+        // Decibel uses this pattern for safer marketable execution.
+        if (params.type === "market" && adapter.info.id === "decibel") {
+            orderParams = {
+                ...orderParams,
+                type: "limit",
+                price: spreadAware.referencePrice.toFixed(8),
+            };
+        }
+    }
+    const order = await adapter.placeOrder(orderParams);
+    eventBus.emit("order.filled", {
+        exchange: "",
+        market: orderParams.market,
+        orderId: order.id,
+        side: orderParams.side,
+        size: parseFloat(orderParams.size),
+        price: order.price ? parseFloat(order.price) : 0,
+        timestamp: Date.now(),
+    });
+    const tpSlOrderIds = [];
+    if (options.attachTpSl &&
+        options.tpSlConfig &&
+        !params.reduceOnly &&
+        params.side !== undefined) {
+        const entryPrice = parseFloat(order.price ?? "");
+        const fallbackPrice = pricing?.referencePrice;
+        const resolvedEntry = Number.isFinite(entryPrice) && entryPrice > 0 ? entryPrice : fallbackPrice;
+        if (resolvedEntry && resolvedEntry > 0) {
+            const ids = await attachTpSlForPosition(adapter, {
+                market: params.market,
+                side: params.side,
+                size: params.size,
+                entryPrice: resolvedEntry,
+            }, options.tpSlConfig);
+            tpSlOrderIds.push(...ids);
+        }
+    }
+    return {
+        order,
+        closedOppositePosition,
+        tpSlOrderIds,
+        pricing,
+    };
+}
+export async function closeThenFlipIfNeeded(adapter, market, desiredSide) {
+    let position = null;
+    try {
+        position = await adapter.getPosition(market);
+    }
+    catch {
+        return false;
+    }
+    if (!position) {
+        return false;
+    }
+    if (position.side === desiredSide) {
+        return false;
+    }
+    const closeSide = position.side === "long" ? "short" : "long";
+    const size = parseFloat(position.size);
+    if (!Number.isFinite(size) || size <= 0) {
+        return false;
+    }
+    log.info("Closing opposite position before flip", {
+        market,
+        existingSide: position.side,
+        desiredSide,
+        size: position.size,
+    });
+    await adapter.placeOrder({
+        market,
+        side: closeSide,
+        type: "market",
+        size: position.size,
+        reduceOnly: true,
+    });
+    eventBus.emit("position.closed", {
+        exchange: "",
+        market: position.market,
+        side: position.side,
+        size: Math.abs(parseFloat(position.size)),
+        entryPrice: parseFloat(position.entryPrice),
+        exitPrice: parseFloat(position.markPrice),
+        pnl: parseFloat(position.unrealizedPnl),
+        timestamp: Date.now(),
+    });
+    return true;
+}
+export async function attachTpSlForPosition(adapter, position, config) {
+    const ids = [];
+    if (!adapter.info.features.stopOrders && !adapter.info.features.takeProfitOrders) {
+        return ids;
+    }
+    const isLong = position.side === "long";
+    const tpTriggerPrice = isLong
+        ? position.entryPrice * (1 + config.takeProfitPct / 100)
+        : position.entryPrice * (1 - config.takeProfitPct / 100);
+    const slTriggerPrice = isLong
+        ? position.entryPrice * (1 - config.stopLossPct / 100)
+        : position.entryPrice * (1 + config.stopLossPct / 100);
+    const tpLimitPrice = isLong ? tpTriggerPrice * 0.999 : tpTriggerPrice * 1.001;
+    const slLimitPrice = isLong ? slTriggerPrice * 0.999 : slTriggerPrice * 1.001;
+    if (adapter.info.features.takeProfitOrders) {
+        try {
+            const tpOrder = await adapter.placeOrder({
+                market: position.market,
+                side: isLong ? "short" : "long",
+                type: "take_profit",
+                size: position.size,
+                reduceOnly: true,
+                triggerPrice: tpTriggerPrice.toFixed(8),
+                price: tpLimitPrice.toFixed(8),
+            });
+            ids.push(tpOrder.id);
+        }
+        catch (err) {
+            log.warn("Failed to attach take-profit", { market: position.market, err });
+        }
+    }
+    if (adapter.info.features.stopOrders) {
+        try {
+            const slOrder = await adapter.placeOrder({
+                market: position.market,
+                side: isLong ? "short" : "long",
+                type: "stop_limit",
+                size: position.size,
+                reduceOnly: true,
+                triggerPrice: slTriggerPrice.toFixed(8),
+                price: slLimitPrice.toFixed(8),
+            });
+            ids.push(slOrder.id);
+        }
+        catch (err) {
+            log.warn("Failed to attach stop-loss", { market: position.market, err });
+        }
+    }
+    return ids;
+}
+export async function resolveSpreadAwarePrice(adapter, market, side, spreadOffset = 0.3) {
+    try {
+        const book = await adapter.getOrderBook(market, 1);
+        const bestBid = parseFloat(book.bids[0]?.price ?? "");
+        const bestAsk = parseFloat(book.asks[0]?.price ?? "");
+        if (Number.isFinite(bestBid) && Number.isFinite(bestAsk) && bestBid > 0 && bestAsk > 0) {
+            const mid = (bestBid + bestAsk) / 2;
+            const spread = Math.max(0, bestAsk - bestBid);
+            const offset = spread * spreadOffset;
+            const rawPrice = side === "long" ? mid + offset : mid - offset;
+            const clampedPrice = clamp(rawPrice, bestBid, bestAsk);
+            return {
+                source: "orderbook",
+                referencePrice: clampedPrice,
+                spread,
+            };
+        }
+    }
+    catch {
+        // fallback below
+    }
+    const ticker = await adapter.getTicker(market);
+    const mark = parseFloat(ticker.markPrice);
+    const last = parseFloat(ticker.lastPrice);
+    const referencePrice = Number.isFinite(mark) && mark > 0 ? mark : last;
+    if (!Number.isFinite(referencePrice) || referencePrice <= 0) {
+        throw new Error(`Unable to resolve spread-aware price for ${market}`);
+    }
+    return {
+        source: "ticker",
+        referencePrice,
+    };
+}
+function clamp(value, min, max) {
+    if (value < min)
+        return min;
+    if (value > max)
+        return max;
+    return value;
+}

package/dist/lib/exit-codes.d.ts

@@ -0,0 +1,18 @@
+export declare const EXIT_CODES: {
+    readonly OK: 0;
+    readonly GENERAL_ERROR: 1;
+    readonly VALIDATION_ERROR: 2;
+    readonly CONFIG_ERROR: 3;
+    readonly AUTH_ERROR: 4;
+    readonly DATA_UNAVAILABLE: 5;
+    readonly NO_OPPORTUNITY: 6;
+    readonly EXECUTION_ERROR: 7;
+    readonly PARTIAL_EXECUTION: 8;
+    readonly CANCELLED: 9;
+};
+export type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
+export declare class CLIError extends Error {
+    readonly exitCode: ExitCode;
+    constructor(message: string, exitCode: ExitCode);
+}
+export declare function inferExitCode(err: unknown): ExitCode;

package/dist/lib/exit-codes.js

@@ -0,0 +1,60 @@
+export const EXIT_CODES = {
+    OK: 0,
+    GENERAL_ERROR: 1,
+    VALIDATION_ERROR: 2,
+    CONFIG_ERROR: 3,
+    AUTH_ERROR: 4,
+    DATA_UNAVAILABLE: 5,
+    NO_OPPORTUNITY: 6,
+    EXECUTION_ERROR: 7,
+    PARTIAL_EXECUTION: 8,
+    CANCELLED: 9,
+};
+export class CLIError extends Error {
+    exitCode;
+    constructor(message, exitCode) {
+        super(message);
+        this.name = "CLIError";
+        this.exitCode = exitCode;
+    }
+}
+export function inferExitCode(err) {
+    if (err instanceof CLIError) {
+        return err.exitCode;
+    }
+    const message = err instanceof Error ? err.message.toLowerCase() : String(err).toLowerCase();
+    if (message.includes("must be") ||
+        message.includes("invalid") ||
+        message.includes("use --yes with --json")) {
+        return EXIT_CODES.VALIDATION_ERROR;
+    }
+    if (message.includes("not configured") ||
+        message.includes("no account") ||
+        message.includes("credentials") ||
+        message.includes("read-only") ||
+        (message.includes("requires") &&
+            (message.includes("private_key") ||
+                message.includes("private key") ||
+                message.includes("api-wallet") ||
+                message.includes("api wallet")))) {
+        return EXIT_CODES.AUTH_ERROR;
+    }
+    if (message.includes("unknown exchange") ||
+        message.includes("config") ||
+        message.includes("failed to load")) {
+        return EXIT_CODES.CONFIG_ERROR;
+    }
+    if (message.includes("risk policy") ||
+        message.includes("reputation policy") ||
+        message.includes("idempotency key") ||
+        message.includes("execution failed") ||
+        message.includes("unable to fetch")) {
+        return EXIT_CODES.EXECUTION_ERROR;
+    }
+    if (message.includes("not enough exchange data") ||
+        message.includes("coin not found") ||
+        message.includes("not found")) {
+        return EXIT_CODES.DATA_UNAVAILABLE;
+    }
+    return EXIT_CODES.GENERAL_ERROR;
+}

package/dist/lib/fetch.d.ts

@@ -0,0 +1,18 @@
+/**
+ * HTTP Fetch Utilities
+ * Provides fetch with timeout, retry, and error handling
+ */
+export interface FetchOptions extends RequestInit {
+    timeoutMs?: number;
+    retries?: number;
+    retryDelayMs?: number;
+}
+export declare class FetchError extends Error {
+    readonly status?: number | undefined;
+    readonly url?: string | undefined;
+    constructor(message: string, status?: number | undefined, url?: string | undefined);
+}
+/**
+ * Fetch with timeout, retry, and proper error handling
+ */
+export declare function fetchWithTimeout<T>(url: string, options?: FetchOptions): Promise<T>;

package/dist/lib/fetch.js

@@ -0,0 +1,66 @@
+/**
+ * HTTP Fetch Utilities
+ * Provides fetch with timeout, retry, and error handling
+ */
+export class FetchError extends Error {
+    status;
+    url;
+    constructor(message, status, url) {
+        super(message);
+        this.status = status;
+        this.url = url;
+        this.name = "FetchError";
+    }
+}
+import { DEFAULT_TIMEOUT_MS, DEFAULT_RETRIES, DEFAULT_RETRY_DELAY_MS } from "./constants.js";
+/**
+ * Fetch with timeout, retry, and proper error handling
+ */
+export async function fetchWithTimeout(url, options = {}) {
+    const { timeoutMs = DEFAULT_TIMEOUT_MS, retries = DEFAULT_RETRIES, retryDelayMs = DEFAULT_RETRY_DELAY_MS, ...fetchOptions } = options;
+    let lastError = null;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        let timeoutId = null;
+        try {
+            const controller = new AbortController();
+            timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+            const response = await fetch(url, {
+                ...fetchOptions,
+                signal: controller.signal,
+                headers: {
+                    "Content-Type": "application/json",
+                    ...fetchOptions.headers,
+                },
+            });
+            if (!response.ok) {
+                const text = await response.text().catch(() => "Unknown error");
+                throw new FetchError(`HTTP ${response.status}: ${text.slice(0, 200)}`, response.status, url);
+            }
+            return await response.json();
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            // Don't retry on client errors (4xx)
+            if (err instanceof FetchError && err.status && err.status >= 400 && err.status < 500) {
+                throw err;
+            }
+            // Don't retry on abort (timeout)
+            if (err instanceof Error && err.name === "AbortError") {
+                throw new FetchError(`Request timeout after ${timeoutMs}ms`, undefined, url);
+            }
+            // Retry on other errors
+            if (attempt < retries) {
+                await sleep(retryDelayMs * (attempt + 1)); // Exponential backoff
+            }
+        }
+        finally {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+        }
+    }
+    throw lastError || new FetchError("Request failed", undefined, url);
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

package/dist/lib/fs-security.d.ts

@@ -0,0 +1,10 @@
+export declare const PRIVATE_DIR_MODE = 448;
+export declare const PRIVATE_FILE_MODE = 384;
+/**
+ * Ensure a runtime directory is owner-only where supported.
+ */
+export declare function ensurePrivateDir(path: string): void;
+/**
+ * Enforce owner-only permissions after writes.
+ */
+export declare function hardenPrivateFile(path: string): void;

package/dist/lib/fs-security.js

@@ -0,0 +1,26 @@
+import { chmodSync, mkdirSync } from "node:fs";
+export const PRIVATE_DIR_MODE = 0o700;
+export const PRIVATE_FILE_MODE = 0o600;
+/**
+ * Ensure a runtime directory is owner-only where supported.
+ */
+export function ensurePrivateDir(path) {
+    mkdirSync(path, { recursive: true, mode: PRIVATE_DIR_MODE });
+    try {
+        chmodSync(path, PRIVATE_DIR_MODE);
+    }
+    catch {
+        // Best effort on non-POSIX filesystems.
+    }
+}
+/**
+ * Enforce owner-only permissions after writes.
+ */
+export function hardenPrivateFile(path) {
+    try {
+        chmodSync(path, PRIVATE_FILE_MODE);
+    }
+    catch {
+        // Best effort on non-POSIX filesystems.
+    }
+}

package/dist/lib/funding-tracker.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Funding Rate Tracker
+ * Polls funding rates across exchanges and stores history
+ */
+import { type FundingRecord } from "./db/funding-history.js";
+interface TrackerOptions {
+    assets: string[];
+    exchanges?: string[];
+    testnet?: boolean;
+    intervalMs?: number;
+    onUpdate?: (records: FundingRecord[]) => void;
+    onError?: (error: Error, exchange: string) => void;
+}
+interface TrackerState {
+    running: boolean;
+    lastPoll: number;
+    recordCount: number;
+    errors: Map<string, string>;
+}
+/**
+ * Poll funding rates for all assets across all exchanges
+ */
+export declare function pollFundingRates(assets: string[], exchanges?: string[], onError?: (error: Error, exchange: string) => void, testnet?: boolean): Promise<FundingRecord[]>;
+/**
+ * Start the funding tracker
+ */
+export declare function startTracker(options: TrackerOptions): void;
+/**
+ * Stop the funding tracker
+ */
+export declare function stopTracker(): void;
+/**
+ * Get tracker status
+ */
+export declare function getTrackerState(): TrackerState;
+/**
+ * Check if tracker is running
+ */
+export declare function isTrackerRunning(): boolean;
+export {};

package/dist/lib/funding-tracker.js

@@ -0,0 +1,118 @@
+/**
+ * Funding Rate Tracker
+ * Polls funding rates across exchanges and stores history
+ */
+import { getExchangeAdapterById, getAvailableExchanges } from "./exchange.js";
+import { FUNDING_INTERVAL_HOURS } from "./constants.js";
+import { storeFundingRates } from "./db/funding-history.js";
+const PERIODS_PER_YEAR = (24 / FUNDING_INTERVAL_HOURS) * 365;
+let trackerInterval = null;
+let trackerState = {
+    running: false,
+    lastPoll: 0,
+    recordCount: 0,
+    errors: new Map(),
+};
+/**
+ * Poll funding rates for all assets across all exchanges
+ */
+export async function pollFundingRates(assets, exchanges, onError, testnet = false) {
+    const exchangeIds = exchanges || getAvailableExchanges();
+    const records = [];
+    const now = Date.now();
+    for (const exchangeId of exchangeIds) {
+        const adapter = getExchangeAdapterById(exchangeId);
+        let connected = false;
+        try {
+            await adapter.connect({ testnet });
+            connected = true;
+            for (const asset of assets) {
+                try {
+                    const symbol = `${asset}-PERP`;
+                    const funding = await adapter.getFundingRate(symbol);
+                    const rate = parseFloat(funding.rate);
+                    records.push({
+                        exchange: adapter.info.name,
+                        market: `${asset}-PERP`,
+                        rate,
+                        annualized: rate * PERIODS_PER_YEAR * 100,
+                        nextFunding: funding.nextFundingTime,
+                        recordedAt: now,
+                    });
+                    trackerState.errors.delete(`${exchangeId}:${asset}`);
+                }
+                catch (err) {
+                    const key = `${exchangeId}:${asset}`;
+                    trackerState.errors.set(key, err instanceof Error ? err.message : "Unknown error");
+                }
+            }
+        }
+        catch (err) {
+            trackerState.errors.set(exchangeId, err instanceof Error ? err.message : "Unknown error");
+            onError?.(err instanceof Error ? err : new Error(String(err)), exchangeId);
+        }
+        finally {
+            if (connected) {
+                await adapter.disconnect().catch(() => undefined);
+            }
+        }
+    }
+    // Store in database
+    if (records.length > 0) {
+        storeFundingRates(records);
+        trackerState.recordCount += records.length;
+    }
+    trackerState.lastPoll = now;
+    return records;
+}
+/**
+ * Start the funding tracker
+ */
+export function startTracker(options) {
+    if (trackerInterval) {
+        throw new Error("Tracker already running");
+    }
+    const intervalMs = options.intervalMs || 5 * 60 * 1000; // 5 minutes
+    trackerState = {
+        running: true,
+        lastPoll: 0,
+        recordCount: 0,
+        errors: new Map(),
+    };
+    // Poll immediately
+    pollFundingRates(options.assets, options.exchanges, options.onError, options.testnet ?? false)
+        .then(records => options.onUpdate?.(records))
+        .catch(err => console.error("Initial poll failed:", err));
+    // Then poll on interval
+    trackerInterval = setInterval(async () => {
+        try {
+            const records = await pollFundingRates(options.assets, options.exchanges, options.onError, options.testnet ?? false);
+            options.onUpdate?.(records);
+        }
+        catch (err) {
+            console.error("Poll failed:", err);
+        }
+    }, intervalMs);
+}
+/**
+ * Stop the funding tracker
+ */
+export function stopTracker() {
+    if (trackerInterval) {
+        clearInterval(trackerInterval);
+        trackerInterval = null;
+    }
+    trackerState.running = false;
+}
+/**
+ * Get tracker status
+ */
+export function getTrackerState() {
+    return { ...trackerState, errors: new Map(trackerState.errors) };
+}
+/**
+ * Check if tracker is running
+ */
+export function isTrackerRunning() {
+    return trackerState.running;
+}

package/dist/lib/logger.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Logger Utility
+ * Centralized logging with levels and formatting
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+interface LoggerOptions {
+    level?: LogLevel;
+    prefix?: string;
+    timestamps?: boolean;
+}
+declare class Logger {
+    private level;
+    private prefix;
+    private timestamps;
+    constructor(options?: LoggerOptions);
+    private shouldLog;
+    private format;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    child(prefix: string): Logger;
+    setLevel(level: LogLevel): void;
+}
+export declare const logger: Logger;
+export declare function createLogger(name: string, options?: LoggerOptions): Logger;
+export default logger;

package/dist/lib/logger.js

@@ -0,0 +1,82 @@
+/**
+ * Logger Utility
+ * Centralized logging with levels and formatting
+ */
+const LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+const LEVEL_COLORS = {
+    debug: "\x1b[90m", // gray
+    info: "\x1b[36m", // cyan
+    warn: "\x1b[33m", // yellow
+    error: "\x1b[31m", // red
+};
+const RESET = "\x1b[0m";
+class Logger {
+    level;
+    prefix;
+    timestamps;
+    constructor(options = {}) {
+        this.level = options.level || (process.env.DEBUG ? "debug" : "info");
+        this.prefix = options.prefix || "";
+        this.timestamps = options.timestamps ?? false;
+    }
+    shouldLog(level) {
+        return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[this.level];
+    }
+    format(level, message, ...args) {
+        const parts = [];
+        if (this.timestamps) {
+            parts.push(`[${new Date().toISOString()}]`);
+        }
+        parts.push(`${LEVEL_COLORS[level]}[${level.toUpperCase()}]${RESET}`);
+        if (this.prefix) {
+            parts.push(`[${this.prefix}]`);
+        }
+        parts.push(message);
+        if (args.length > 0) {
+            parts.push(...args.map(a => typeof a === "object" ? JSON.stringify(a) : String(a)));
+        }
+        return parts.join(" ");
+    }
+    debug(message, ...args) {
+        if (this.shouldLog("debug")) {
+            console.debug(this.format("debug", message, ...args));
+        }
+    }
+    info(message, ...args) {
+        if (this.shouldLog("info")) {
+            console.info(this.format("info", message, ...args));
+        }
+    }
+    warn(message, ...args) {
+        if (this.shouldLog("warn")) {
+            console.warn(this.format("warn", message, ...args));
+        }
+    }
+    error(message, ...args) {
+        if (this.shouldLog("error")) {
+            console.error(this.format("error", message, ...args));
+        }
+    }
+    child(prefix) {
+        return new Logger({
+            level: this.level,
+            prefix: this.prefix ? `${this.prefix}:${prefix}` : prefix,
+            timestamps: this.timestamps,
+        });
+    }
+    setLevel(level) {
+        this.level = level;
+    }
+}
+// Default logger instance
+export const logger = new Logger();
+// Factory for creating named loggers
+export function createLogger(name, options) {
+    return new Logger({ ...options, prefix: name });
+}
+export default logger;

package/dist/lib/network-model.d.ts

@@ -0,0 +1,13 @@
+export type CommandIntent = "execution" | "data" | "neutral";
+export type DeploymentNetwork = "mainnet" | "testnet";
+export interface NetworkDecisionInput {
+    intent: CommandIntent;
+    cliOverride?: DeploymentNetwork;
+    exchangeOverride?: DeploymentNetwork;
+    fallbackNetwork?: DeploymentNetwork;
+}
+export interface NetworkDecision {
+    network: DeploymentNetwork;
+    source: "cli-override" | "exchange-override" | "intent-default" | "fallback";
+}
+export declare function resolveNetworkDecision(input: NetworkDecisionInput): NetworkDecision;