@raintree-technology/perps 0.1.0

package/dist/commands/state/show.js

@@ -0,0 +1,105 @@
+import { getContext, getOutputOptions, getSelectedExchange } from "../../cli/program.js";
+import { output, outputError } from "../../cli/output.js";
+import { withJsonContract } from "../../lib/contracts.js";
+import { getExchangeAdapter } from "../../lib/exchange.js";
+import { getExchangeCredentials } from "../../lib/config.js";
+import { buildStateContext } from "../../lib/state-context.js";
+export function registerStateShowCommand(state) {
+    state
+        .command("show")
+        .description("Show current portfolio state context")
+        .action(async function () {
+        const ctx = getContext(this);
+        const outputOpts = getOutputOptions(this);
+        const exchangeId = getSelectedExchange(this);
+        const adapter = getExchangeAdapter();
+        let connected = false;
+        try {
+            const credentials = getExchangeCredentials(ctx.config, exchangeId, {
+                requireReadAccess: true,
+            });
+            await adapter.connect({
+                testnet: ctx.config.testnet,
+                rpcUrl: credentials.fullnodeUrl,
+                wsUrl: credentials.wsUrl,
+                credentials,
+            });
+            connected = true;
+            const stateCtx = await buildStateContext(adapter, exchangeId, ctx.config);
+            if (outputOpts.json) {
+                output(withJsonContract("state.context", stateCtx), outputOpts);
+                return;
+            }
+            // Human-readable output
+            console.log("\nPortfolio State:\n");
+            console.log(`  Exchange:      ${stateCtx.exchange}`);
+            console.log(`  Equity:        $${stateCtx.equity.toFixed(2)}`);
+            console.log(`  Available:     $${stateCtx.availableBalance.toFixed(2)}`);
+            console.log(`  Margin Used:   $${stateCtx.marginUsed.toFixed(2)}`);
+            console.log(`  Exposure:      $${stateCtx.totalExposureUsd.toFixed(2)}`);
+            console.log(`  Leverage:      ${stateCtx.leverageUsed.toFixed(2)}x`);
+            const pnlSign = stateCtx.netUnrealizedPnl >= 0 ? "+" : "";
+            console.log(`  Unrealized PnL: ${pnlSign}$${stateCtx.netUnrealizedPnl.toFixed(2)}`);
+            console.log(`  Drawdown:      ${stateCtx.drawdownFromPeakPct.toFixed(2)}%`);
+            console.log(`  Peak Equity:   $${stateCtx.peakEquity.toFixed(2)}`);
+            console.log(`  Halted:        ${stateCtx.halted ? "YES" : "NO"}`);
+            if (stateCtx.haltReason) {
+                console.log(`  Halt Reason:   ${stateCtx.haltReason}`);
+            }
+            // Positions
+            console.log(`\n  Positions (${stateCtx.positionCount}):\n`);
+            if (stateCtx.positions.length === 0) {
+                console.log("    No open positions.");
+            }
+            else {
+                for (const pos of stateCtx.positions) {
+                    const posPnlSign = pos.unrealizedPnl >= 0 ? "+" : "";
+                    console.log(`    ${pos.market} ${pos.side.toUpperCase()}`);
+                    console.log(`      Size:       ${pos.size} @ $${pos.entryPrice.toFixed(2)}`);
+                    console.log(`      Mark:       $${pos.markPrice.toFixed(2)}`);
+                    console.log(`      Notional:   $${pos.notionalUsd.toFixed(2)}`);
+                    console.log(`      PnL:        ${posPnlSign}$${pos.unrealizedPnl.toFixed(2)}`);
+                    console.log(`      Leverage:   ${pos.leverage}x (${pos.marginType})`);
+                    if (pos.liquidationPrice !== null) {
+                        console.log(`      Liq Price:  $${pos.liquidationPrice.toFixed(2)}`);
+                    }
+                    console.log("");
+                }
+            }
+            // Open orders
+            console.log(`  Open Orders (${stateCtx.openOrderCount}):\n`);
+            if (stateCtx.openOrders.length === 0) {
+                console.log("    No open orders.");
+            }
+            else {
+                for (const ord of stateCtx.openOrders) {
+                    console.log(`    ${ord.market} ${ord.side} ${ord.type} ${ord.size} @ ${ord.price ?? "market"}`);
+                }
+            }
+            // Errors
+            if (stateCtx.errors.length > 0) {
+                console.log(`\n  Errors (${stateCtx.errors.length}):\n`);
+                for (const err of stateCtx.errors) {
+                    console.log(`    - ${err}`);
+                }
+            }
+            // Risk limits
+            console.log("\n  Risk Limits:\n");
+            console.log(`    Max Position:  $${stateCtx.riskLimits.maxPositionSizeUsd.toFixed(2)}`);
+            console.log(`    Max Exposure:  $${stateCtx.riskLimits.maxTotalExposureUsd.toFixed(2)}`);
+            console.log(`    Max Leverage:  ${stateCtx.riskLimits.maxLeverage}x`);
+            console.log(`    Max Drawdown:  ${stateCtx.riskLimits.maxDrawdownPct}%`);
+            console.log(`    Min Confidence: ${stateCtx.riskLimits.minSignalConfidence}`);
+            console.log("");
+        }
+        catch (err) {
+            outputError(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+        }
+        finally {
+            if (connected) {
+                await adapter.disconnect().catch(() => undefined);
+            }
+        }
+    });
+}

package/dist/commands/strategy/index.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import "../../lib/strategy/funding-arb.js";
+import "../../lib/strategy/basis-trade.js";
+export declare function registerStrategyCommands(program: Command): void;

package/dist/commands/strategy/index.js

@@ -0,0 +1,73 @@
+import { getOutputOptions } from "../../cli/program.js";
+import { output, outputError } from "../../cli/output.js";
+import { withJsonContract } from "../../lib/contracts.js";
+import { listStrategies, getStrategy } from "../../lib/strategy/registry.js";
+import "../../lib/strategy/funding-arb.js";
+import "../../lib/strategy/basis-trade.js";
+export function registerStrategyCommands(program) {
+    const strategy = program.command("strategy").description("Strategy definitions and metadata");
+    strategy
+        .command("ls")
+        .description("List registered strategies")
+        .action(function () {
+        const outputOpts = getOutputOptions(this);
+        const strategies = listStrategies();
+        if (outputOpts.json) {
+            output(withJsonContract("strategy.list", { strategies }), outputOpts);
+            return;
+        }
+        const rows = strategies.map((s) => ({
+            id: s.id,
+            name: s.name,
+            shape: s.shape,
+            legs: String(s.legs),
+            exchanges: s.exchanges,
+        }));
+        output(rows, outputOpts);
+    });
+    strategy
+        .command("describe <id>")
+        .description("Describe a strategy in detail")
+        .action(function (id) {
+        const outputOpts = getOutputOptions(this);
+        const s = getStrategy(id);
+        if (!s) {
+            outputError(`Strategy "${id}" not found`);
+            process.exit(1);
+        }
+        if (outputOpts.json) {
+            output(withJsonContract("strategy.describe", s), outputOpts);
+            return;
+        }
+        console.log("");
+        console.log(`  Name:        ${s.name}`);
+        console.log(`  ID:          ${s.id}`);
+        console.log(`  Description: ${s.description}`);
+        console.log(`  Shape:       ${s.shape}`);
+        console.log(`  Legs:        ${s.legs}`);
+        console.log(`  Exchanges:   ${s.exchanges}`);
+        console.log("");
+        console.log(`  Entry Signal: ${s.entrySignal}`);
+        console.log(`  Exit Signal:  ${s.exitSignal}`);
+        console.log("");
+        if (s.parameters.length > 0) {
+            console.log("  Parameters:");
+            for (const p of s.parameters) {
+                const def = p.default !== undefined ? ` (default: ${p.default})` : "";
+                console.log(`    ${p.name} [${p.type}]${def} — ${p.description}`);
+            }
+            console.log("");
+        }
+        const rp = s.riskProfile;
+        if (rp.maxPositionSizeUsd || rp.maxLeverage || rp.maxDrawdownPct) {
+            console.log("  Risk Profile:");
+            if (rp.maxPositionSizeUsd)
+                console.log(`    Max Position Size: $${rp.maxPositionSizeUsd}`);
+            if (rp.maxLeverage)
+                console.log(`    Max Leverage:      ${rp.maxLeverage}x`);
+            if (rp.maxDrawdownPct)
+                console.log(`    Max Drawdown:      ${rp.maxDrawdownPct}%`);
+            console.log("");
+        }
+    });
+}

package/dist/commands/traces/index.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerTracesCommands(program: Command): void;

package/dist/commands/traces/index.js

@@ -0,0 +1,76 @@
+import { listTraces } from "../../lib/trace-queries.js";
+import { withJsonContract } from "../../lib/contracts.js";
+import { output } from "../../cli/output.js";
+import { getOutputOptions } from "../../cli/program.js";
+function formatTimestamp(ms) {
+    const d = new Date(ms);
+    const year = d.getFullYear();
+    const month = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    const hours = String(d.getHours()).padStart(2, "0");
+    const minutes = String(d.getMinutes()).padStart(2, "0");
+    return `${year}-${month}-${day} ${hours}:${minutes}`;
+}
+function truncateId(id, maxLen = 36) {
+    if (id.length <= maxLen)
+        return id;
+    return `${id.slice(0, maxLen - 3)}...`;
+}
+function formatStatus(journalStatus, riskDenials) {
+    if (riskDenials > 0)
+        return "denied";
+    return journalStatus ?? "-";
+}
+export function registerTracesCommands(program) {
+    const traces = program
+        .command("traces")
+        .description("Session and trace dashboard");
+    traces
+        .command("ls")
+        .description("List recent traces")
+        .option("--last <minutes>", "Time window in minutes", "60")
+        .option("--exchange <id>", "Filter by exchange")
+        .option("--market <symbol>", "Filter by market")
+        .option("--status <status>", "Filter by outcome (succeeded, failed, denied)")
+        .option("--limit <n>", "Max results", "50")
+        .action((opts, command) => {
+        const { json } = getOutputOptions(command);
+        const minutes = Number.parseInt(opts.last, 10);
+        const limit = Number.parseInt(opts.limit, 10);
+        const traces = listTraces({
+            minutes,
+            exchange: opts.exchange,
+            market: opts.market,
+            status: opts.status,
+            limit,
+        });
+        if (json) {
+            output(withJsonContract("traces.list", { traces, window: { minutes } }), { json });
+            return;
+        }
+        if (traces.length === 0) {
+            console.log(`\nNo traces found in the last ${minutes} minutes.\n`);
+            return;
+        }
+        console.log(`\nRecent Traces (last ${minutes} min):\n`);
+        const rows = traces.map((t) => ({
+            "Trace ID": truncateId(t.traceId),
+            Time: formatTimestamp(t.lastSeen),
+            Exchange: t.exchange,
+            Market: t.markets.join(", ") || "-",
+            Evals: String(t.riskEvaluations),
+            Denials: String(t.riskDenials),
+            Journal: String(t.journalEntries),
+            Status: formatStatus(t.journalStatus, t.riskDenials),
+        }));
+        output(rows, { json: false });
+        console.log(`\n${traces.length} trace${traces.length === 1 ? "" : "s"} found`);
+    });
+    traces
+        .command("show <trace-id>")
+        .description("Show trace details (alias for replay)")
+        .action((traceId) => {
+        console.log(`\nRun: perps replay ${traceId}\n`);
+        process.exitCode = 0;
+    });
+}

package/dist/commands/ui/demo.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from "commander";
+export interface UIDemoJsonPreview {
+    command: "ui demo";
+    intervalMs: number;
+    interactive: false;
+    note: string;
+}
+export declare function getUIDemoJsonPreview(intervalMs: number): UIDemoJsonPreview;
+export declare function registerUIDemoCommand(ui: Command): void;

package/dist/commands/ui/demo.js

@@ -0,0 +1,195 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useState } from "react";
+import { Box, Text, render, useApp, useInput } from "ink";
+import { getOutputOptions } from "../../cli/program.js";
+import { output, outputError } from "../../cli/output.js";
+import { AppShell, MetricStrip, Panel, Table, colors, toBar, toSparkline, } from "../../cli/ink/index.js";
+import { parsePositiveInt } from "../../lib/validate.js";
+const DEFAULT_INTERVAL_MS = 500;
+const MIN_INTERVAL_MS = 100;
+const INITIAL_EQUITY = 10_000;
+const HISTORY_LENGTH = 72;
+const MARKET_SEEDS = [
+    { market: "BTC-PERP", basePrice: 64_250, baseVolumeM: 86 },
+    { market: "ETH-PERP", basePrice: 3_410, baseVolumeM: 54 },
+    { market: "SOL-PERP", basePrice: 146, baseVolumeM: 37 },
+    { market: "BNB-PERP", basePrice: 612, baseVolumeM: 19 },
+    { market: "ARB-PERP", basePrice: 1.02, baseVolumeM: 8 },
+];
+export function getUIDemoJsonPreview(intervalMs) {
+    return {
+        command: "ui demo",
+        intervalMs,
+        interactive: false,
+        note: "Run without --json to launch the offline synthetic terminal preview.",
+    };
+}
+function formatCurrency(value, decimals = 2) {
+    return value.toLocaleString("en-US", {
+        minimumFractionDigits: decimals,
+        maximumFractionDigits: decimals,
+    });
+}
+function buildMarkets(tick) {
+    return MARKET_SEEDS.map((seed, index) => {
+        const momentum = Math.sin((tick + index * 2) / 7) * 2.2;
+        const meanReversion = Math.cos((tick + index) / 19) * 0.75;
+        const changePct = momentum + meanReversion;
+        const price = seed.basePrice * (1 + changePct / 100);
+        const fundingPct = Math.sin((tick + index * 5) / 13) * 0.035;
+        const volumeM = seed.baseVolumeM * (1 + Math.abs(Math.sin((tick + index * 3) / 4)) * 0.8);
+        let signal = "FLAT";
+        if (changePct > 1.1 && fundingPct < 0.02)
+            signal = "LONG";
+        if (changePct < -1.1 && fundingPct > -0.02)
+            signal = "SHORT";
+        return {
+            market: seed.market,
+            price,
+            changePct,
+            fundingPct,
+            volumeM,
+            signal,
+        };
+    });
+}
+function createInitialState() {
+    return {
+        tick: 0,
+        startedAt: Date.now(),
+        equity: INITIAL_EQUITY,
+        equityHistory: Array.from({ length: HISTORY_LENGTH }, () => INITIAL_EQUITY),
+        markets: buildMarkets(0),
+        latencyMs: 58,
+    };
+}
+function nextState(previous) {
+    const tick = previous.tick + 1;
+    const equityDelta = Math.sin(tick / 8) * 14 + Math.cos(tick / 3) * 7;
+    const equity = Math.max(5_000, previous.equity + equityDelta);
+    const equityHistory = [...previous.equityHistory.slice(-(HISTORY_LENGTH - 1)), equity];
+    const latencyMs = Math.round(45 + Math.abs(Math.sin(tick / 5)) * 95 + Math.abs(Math.cos(tick / 13)) * 20);
+    return {
+        tick,
+        startedAt: previous.startedAt,
+        equity,
+        equityHistory,
+        markets: buildMarkets(tick),
+        latencyMs,
+    };
+}
+function signalColor(signal) {
+    if (signal === "LONG")
+        return colors.profit;
+    if (signal === "SHORT")
+        return colors.loss;
+    return colors.muted;
+}
+function Dashboard({ intervalMs }) {
+    const [state, setState] = useState(createInitialState);
+    const { exit } = useApp();
+    useInput((input, key) => {
+        if (input.toLowerCase() === "q" || key.escape || (key.ctrl && input.toLowerCase() === "c")) {
+            exit();
+        }
+    });
+    useEffect(() => {
+        const timer = setInterval(() => {
+            setState((previous) => nextState(previous));
+        }, intervalMs);
+        return () => clearInterval(timer);
+    }, [intervalMs]);
+    const pnl = state.equity - INITIAL_EQUITY;
+    const pnlSign = pnl >= 0 ? "+" : "";
+    const uptimeSeconds = Math.floor((Date.now() - state.startedAt) / 1_000);
+    const liveSignals = state.markets.filter((row) => row.signal !== "FLAT").length;
+    const statusTone = state.latencyMs > 170 ? "danger" : state.latencyMs > 120 ? "warning" : "success";
+    const metrics = [
+        {
+            label: "Equity",
+            value: `$${formatCurrency(state.equity)}`,
+            delta: `${pnlSign}$${formatCurrency(pnl)}`,
+            tone: pnl >= 0 ? "success" : "danger",
+        },
+        { label: "Latency", value: `${state.latencyMs}ms`, tone: statusTone },
+        { label: "Signals", value: String(liveSignals), tone: liveSignals > 0 ? "info" : "neutral" },
+        { label: "Uptime", value: `${uptimeSeconds}s`, tone: "neutral" },
+    ];
+    const columns = useMemo(() => [
+        { key: "market", header: "Market" },
+        {
+            key: "price",
+            header: "Price",
+            align: "right",
+            render: (value) => _jsxs(Text, { children: ["$", formatCurrency(value)] }),
+        },
+        {
+            key: "changePct",
+            header: "24h %",
+            align: "right",
+            render: (value) => {
+                const change = value;
+                const sign = change >= 0 ? "+" : "";
+                return (_jsxs(Text, { color: change >= 0 ? colors.profit : colors.loss, children: [sign, change.toFixed(2), "%"] }));
+            },
+        },
+        {
+            key: "fundingPct",
+            header: "Funding",
+            align: "right",
+            render: (value) => {
+                const funding = value;
+                const sign = funding >= 0 ? "+" : "";
+                return (_jsxs(Text, { color: funding >= 0 ? colors.profit : colors.loss, children: [sign, funding.toFixed(4), "%"] }));
+            },
+        },
+        {
+            key: "volumeM",
+            header: "Vol(M)",
+            align: "right",
+            render: (value) => _jsx(Text, { children: formatCurrency(value, 1) }),
+        },
+        {
+            key: "signal",
+            header: "Signal",
+            align: "right",
+            render: (value) => _jsx(Text, { color: signalColor(value), children: value }),
+        },
+    ], []);
+    const strongest = [...state.markets]
+        .sort((left, right) => Math.abs(right.changePct) - Math.abs(left.changePct))
+        .slice(0, 3);
+    return (_jsxs(AppShell, { title: "Perps Terminal Preview", subtitle: "Synthetic stream for offline UI validation", status: [
+            { label: "LIVE", tone: "success" },
+            { label: `LAT ${state.latencyMs}ms`, tone: statusTone },
+        ], lastUpdated: new Date(), shortcuts: [
+            { key: "q", label: "quit" },
+            { key: "esc", label: "quit" },
+        ], children: [_jsx(MetricStrip, { metrics: metrics }), _jsx(Box, { flexDirection: "column", marginBottom: 1, children: _jsxs(Panel, { title: "Equity Curve", subtitle: "ASCII sparkline and momentum bars", tone: "info", children: [_jsx(Text, { children: toSparkline(state.equityHistory, 64) }), _jsx(Box, { marginTop: 1, flexDirection: "column", children: strongest.map((market) => (_jsxs(Box, { children: [_jsx(Text, { color: colors.muted, children: market.market.padEnd(8) }), _jsx(Text, { children: " " }), _jsx(Text, { children: toBar(Math.abs(market.changePct), 4, 20, market.changePct >= 0 ? "+" : "-", ".") }), _jsxs(Text, { color: market.changePct >= 0 ? colors.profit : colors.loss, children: [" ", market.changePct >= 0 ? "+" : "", market.changePct.toFixed(2), "%"] })] }, market.market))) })] }) }), _jsx(Panel, { title: "Market Tape", subtitle: "Reusable table component", tone: "neutral", children: _jsx(Table, { data: state.markets, columns: columns }) })] }));
+}
+export function registerUIDemoCommand(ui) {
+    ui
+        .command("demo")
+        .description("Run an offline synthetic dashboard preview")
+        .option("-i, --interval <ms>", "Refresh interval in milliseconds", String(DEFAULT_INTERVAL_MS))
+        .action(async function (options) {
+        const outputOpts = getOutputOptions(this);
+        try {
+            const intervalMs = parsePositiveInt(options.interval, "interval", DEFAULT_INTERVAL_MS);
+            if (intervalMs < MIN_INTERVAL_MS) {
+                throw new Error(`interval must be >= ${MIN_INTERVAL_MS}ms`);
+            }
+            if (outputOpts.json) {
+                output(getUIDemoJsonPreview(intervalMs), outputOpts);
+                return;
+            }
+            const { waitUntilExit, unmount } = render(_jsx(Dashboard, { intervalMs: intervalMs }));
+            await waitUntilExit();
+            unmount();
+        }
+        catch (err) {
+            outputError(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/ui/index.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerUICommands(program: Command): void;

package/dist/commands/ui/index.js

@@ -0,0 +1,7 @@
+import { registerUIDemoCommand } from "./demo.js";
+import { registerUITerminalCommand } from "./terminal.js";
+export function registerUICommands(program) {
+    const ui = program.command("ui").description("Terminal dashboards for live ops and diagnostics");
+    registerUITerminalCommand(ui);
+    registerUIDemoCommand(ui);
+}

package/dist/commands/ui/terminal.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerUITerminalCommand(ui: Command): void;