@raintree-technology/perps 0.1.0

package/dist/commands/order/shared.d.ts

@@ -0,0 +1,17 @@
+export type Side = "buy" | "sell";
+export type NormalizedSide = "long" | "short";
+export declare function normalizeMarket(symbol: string): string;
+export declare function normalizeSide(value: string): NormalizedSide;
+export declare function validateSideWithAliases(value: string): Side;
+export declare function getAssetIndex(publicClient: {
+    allPerpMetas: () => Promise<Array<{
+        universe: Array<{
+            name: string;
+        }>;
+    }>>;
+    spotMeta: () => Promise<{
+        universe: Array<{
+            name: string;
+        }>;
+    }>;
+}, coin: string): Promise<number>;

package/dist/commands/order/shared.js

@@ -0,0 +1,51 @@
+export function normalizeMarket(symbol) {
+    let market = symbol.toUpperCase();
+    if (!market.includes("-")) {
+        market = `${market}-PERP`;
+    }
+    return market;
+}
+export function normalizeSide(value) {
+    const side = value.trim().toLowerCase();
+    if (!["buy", "long", "sell", "short"].includes(side)) {
+        throw new Error('Side must be: buy, long, sell, or short');
+    }
+    return side === "buy" || side === "long" ? "long" : "short";
+}
+export function validateSideWithAliases(value) {
+    const lower = value.toLowerCase();
+    if (lower === "long" || lower === "buy") {
+        return "buy";
+    }
+    if (lower === "short" || lower === "sell") {
+        return "sell";
+    }
+    throw new Error('Side must be "buy", "sell", "long", or "short"');
+}
+export async function getAssetIndex(publicClient, coin) {
+    // Fetch all perp metas (includes main dex at index 0 and builder dexes at index 1+)
+    const allPerpMetas = await publicClient.allPerpMetas();
+    // Check all perp dexes (case-sensitive matching)
+    for (let dexIndex = 0; dexIndex < allPerpMetas.length; dexIndex++) {
+        const dex = allPerpMetas[dexIndex];
+        const marketIndex = dex.universe.findIndex((a) => a.name === coin);
+        if (marketIndex !== -1) {
+            if (dexIndex === 0) {
+                // Main perp: just the index
+                return marketIndex;
+            }
+            else {
+                // Builder-deployed perp: 100000 + perp_dex_index * 10000 + index_in_meta
+                return 100000 + dexIndex * 10000 + marketIndex;
+            }
+        }
+    }
+    // Then check spot markets (case-sensitive matching)
+    const spotMeta = await publicClient.spotMeta();
+    const spotIndex = spotMeta.universe.findIndex((a) => a.name === coin);
+    if (spotIndex !== -1) {
+        // Spot assets use 10000 + index per Hyperliquid API docs
+        return 10000 + spotIndex;
+    }
+    throw new Error(`Unknown coin: ${coin}`);
+}

package/dist/commands/order/trigger-simple.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Trigger order commands using the adapter interface.
+ */
+import { Command } from "commander";
+export declare function registerTriggerOrderSimpleCommands(order: Command): void;

package/dist/commands/order/trigger-simple.js

@@ -0,0 +1,246 @@
+/**
+ * Trigger order commands using the adapter interface.
+ */
+import { getContext, getOutputOptions, getSelectedExchange } from "../../cli/program.js";
+import { output, outputError, outputSuccess } from "../../cli/output.js";
+import { getExchangeAdapter } from "../../lib/exchange.js";
+import { getExchangeCredentials } from "../../lib/config.js";
+import { RiskPolicyMiddleware } from "../../lib/risk/policy-middleware.js";
+import { runWithExecutionJournal } from "../../lib/execution/journal.js";
+import { withJsonContract } from "../../lib/contracts.js";
+import { inferExitCode } from "../../lib/exit-codes.js";
+import { assertTradeAllowed } from "../../lib/trade-reputation.js";
+import { normalizeMarket, normalizeSide } from "./shared.js";
+function parsePositive(value, field) {
+    const parsed = Number.parseFloat(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${field} must be a positive number`);
+    }
+    return parsed;
+}
+function assertCapability(adapter, orderType) {
+    if (orderType === "take_profit" && !adapter.info.features.takeProfitOrders) {
+        throw new Error(`${adapter.info.name} does not support take-profit orders`);
+    }
+    if ((orderType === "stop" || orderType === "stop_limit") && !adapter.info.features.stopOrders) {
+        throw new Error(`${adapter.info.name} does not support stop orders`);
+    }
+}
+async function runTriggerOrder(args) {
+    const { command, commandName, orderType, side, symbol, size, triggerPrice, price, allowPostOnly } = args;
+    const ctx = getContext(command);
+    const outputOpts = getOutputOptions(command);
+    const exchangeId = getSelectedExchange(command);
+    const opts = command.opts();
+    try {
+        const market = normalizeMarket(symbol);
+        const normalizedSide = normalizeSide(side);
+        const requestedSize = parsePositive(size, "Size");
+        const trigger = parsePositive(triggerPrice, "Trigger price");
+        const limitPrice = price !== undefined ? parsePositive(price, "Price") : undefined;
+        const confidence = opts.confidence ? Number.parseFloat(opts.confidence) : 1;
+        if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1) {
+            throw new Error("Confidence must be a number between 0 and 1");
+        }
+        if (opts.postOnly && !allowPostOnly) {
+            throw new Error(`${commandName} does not support --post-only`);
+        }
+        const adapter = getExchangeAdapter();
+        const credentials = getExchangeCredentials(ctx.config, exchangeId, {
+            requireTrading: true,
+        });
+        await adapter.connect({
+            testnet: ctx.config.testnet,
+            rpcUrl: credentials.fullnodeUrl,
+            wsUrl: credentials.wsUrl,
+            credentials,
+        });
+        try {
+            assertCapability(adapter, orderType);
+            const referencePrice = limitPrice ?? trigger;
+            const riskPolicy = new RiskPolicyMiddleware(ctx.config, exchangeId);
+            const riskDecision = await riskPolicy.evaluateOrder(adapter, {
+                market,
+                side: normalizedSide,
+                requestedSizeBase: requestedSize,
+                referencePriceUsd: referencePrice,
+                confidence,
+                reason: `cli:order:${orderType}`,
+            });
+            if (!riskDecision.allowed || riskDecision.adjustedSizeBase <= 0) {
+                throw new Error(riskDecision.reason ?? "Order blocked by risk policy");
+            }
+            assertTradeAllowed({
+                exchangeId,
+                market,
+                command: `order.${commandName}`,
+            });
+            const finalSize = riskDecision.adjustedSizeBase;
+            const journaled = await runWithExecutionJournal({
+                idempotencyKey: opts.idempotencyKey,
+                metadata: {
+                    command: `order.${commandName}`,
+                    exchange: exchangeId,
+                    testnet: ctx.config.testnet,
+                    market,
+                    side: normalizedSide,
+                    orderType,
+                },
+                request: {
+                    market,
+                    side: normalizedSide,
+                    orderType,
+                    requestedSize: requestedSize.toFixed(8),
+                    triggerPrice: trigger.toFixed(8),
+                    price: limitPrice?.toFixed(8) ?? null,
+                    reduceOnly: opts.reduceOnly ?? false,
+                    postOnly: opts.postOnly ?? false,
+                    confidence,
+                },
+                execute: async () => {
+                    const order = await adapter.placeOrder({
+                        market,
+                        side: normalizedSide,
+                        type: orderType,
+                        size: finalSize.toFixed(8),
+                        triggerPrice: trigger.toFixed(8),
+                        price: limitPrice?.toFixed(8),
+                        reduceOnly: opts.reduceOnly,
+                        postOnly: opts.postOnly,
+                    });
+                    return {
+                        order,
+                        risk: {
+                            requestedSize,
+                            adjustedSize: finalSize,
+                            adjustedNotionalUsd: riskDecision.adjustedSizeUsd,
+                            referencePrice,
+                        },
+                        trigger: {
+                            triggerPrice: trigger,
+                            limitPrice: limitPrice ?? null,
+                        },
+                    };
+                },
+            });
+            const response = {
+                ...journaled.result.order,
+                risk: journaled.result.risk,
+                trigger: journaled.result.trigger,
+                idempotency: {
+                    key: journaled.idempotencyKey,
+                    replayed: journaled.replayed,
+                    autoGenerated: journaled.autoGeneratedKey,
+                    journalId: journaled.journalId,
+                },
+            };
+            if (outputOpts.json) {
+                output(withJsonContract("order.execution.result", {
+                    executionStatus: journaled.replayed ? "replayed" : "executed",
+                    ...response,
+                }), outputOpts);
+            }
+            else {
+                outputSuccess(journaled.replayed
+                    ? "Order replayed from idempotency journal!"
+                    : `${commandName} order placed!`);
+                console.log(`  Order ID:   ${response.id}`);
+                console.log(`  Market:     ${response.market}`);
+                console.log(`  Side:       ${response.side.toUpperCase()}`);
+                console.log(`  Type:       ${response.type}`);
+                console.log(`  Size:       ${response.size}`);
+                console.log(`  Trigger:    ${response.trigger.triggerPrice}`);
+                if (response.trigger.limitPrice !== null) {
+                    console.log(`  Limit:      ${response.trigger.limitPrice}`);
+                }
+                console.log(`  Status:     ${response.status}`);
+                if (Math.abs(response.risk.adjustedSize - response.risk.requestedSize) > 1e-12) {
+                    console.log(`  Risk Size:  adjusted from ${response.risk.requestedSize} to ${response.risk.adjustedSize.toFixed(8)}`);
+                }
+                console.log(`  Idempotency: ${response.idempotency.key}` +
+                    (response.idempotency.replayed ? " (replayed)" : ""));
+                console.log("");
+            }
+        }
+        finally {
+            await adapter.disconnect();
+        }
+    }
+    catch (err) {
+        const code = inferExitCode(err);
+        const message = err instanceof Error ? err.message : String(err);
+        if (outputOpts.json) {
+            output(withJsonContract("order.execution.result", {
+                status: "error",
+                error: {
+                    message,
+                    exitCode: code,
+                },
+            }), outputOpts);
+        }
+        else {
+            outputError(message);
+        }
+        process.exit(code);
+    }
+}
+export function registerTriggerOrderSimpleCommands(order) {
+    order
+        .command("stop <side> <symbol> <size> <triggerPrice>")
+        .description("Place a stop-market order (side: buy/long or sell/short)")
+        .option("--reduce-only", "Reduce-only order")
+        .option("--confidence <0-1>", "Signal confidence for risk policy (default: 1.0)")
+        .option("--idempotency-key <key>", "Idempotency key for safe retries")
+        .action(async function (side, symbol, size, triggerPrice) {
+        await runTriggerOrder({
+            command: this,
+            commandName: "stop",
+            orderType: "stop",
+            side,
+            symbol,
+            size,
+            triggerPrice,
+            allowPostOnly: false,
+        });
+    });
+    order
+        .command("stop-limit <side> <symbol> <size> <triggerPrice> <price>")
+        .description("Place a stop-limit order (side: buy/long or sell/short)")
+        .option("--reduce-only", "Reduce-only order")
+        .option("--post-only", "Post-only order")
+        .option("--confidence <0-1>", "Signal confidence for risk policy (default: 1.0)")
+        .option("--idempotency-key <key>", "Idempotency key for safe retries")
+        .action(async function (side, symbol, size, triggerPrice, price) {
+        await runTriggerOrder({
+            command: this,
+            commandName: "stop-limit",
+            orderType: "stop_limit",
+            side,
+            symbol,
+            size,
+            triggerPrice,
+            price,
+            allowPostOnly: true,
+        });
+    });
+    order
+        .command("take-profit <side> <symbol> <size> <triggerPrice> [price]")
+        .description("Place a take-profit order (side: buy/long or sell/short)")
+        .option("--reduce-only", "Reduce-only order")
+        .option("--post-only", "Post-only order")
+        .option("--confidence <0-1>", "Signal confidence for risk policy (default: 1.0)")
+        .option("--idempotency-key <key>", "Idempotency key for safe retries")
+        .action(async function (side, symbol, size, triggerPrice, price) {
+        await runTriggerOrder({
+            command: this,
+            commandName: "take-profit",
+            orderType: "take_profit",
+            side,
+            symbol,
+            size,
+            triggerPrice,
+            price,
+            allowPostOnly: true,
+        });
+    });
+}

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

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

package/dist/commands/referral/index.js

@@ -0,0 +1,7 @@
+import { registerSetCommand } from "./set.js";
+import { registerStatusCommand } from "./status.js";
+export function registerReferralCommands(program) {
+    const referral = program.command("referral").description("Referral management");
+    registerSetCommand(referral);
+    registerStatusCommand(referral);
+}

package/dist/commands/referral/set.d.ts

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

package/dist/commands/referral/set.js

@@ -0,0 +1,26 @@
+import { getContext, getOutputOptions } from "../../cli/program.js";
+import { output, outputError, outputSuccess } from "../../cli/output.js";
+export function registerSetCommand(referral) {
+    referral
+        .command("set")
+        .description("Set referral code (link to a referrer)")
+        .argument("<code>", "Referral code")
+        .action(async function (code) {
+        const ctx = getContext(this);
+        const outputOpts = getOutputOptions(this);
+        try {
+            const client = ctx.getWalletClient();
+            const result = await client.setReferrer({ code });
+            if (outputOpts.json) {
+                output(result, outputOpts);
+            }
+            else {
+                outputSuccess(`Referral code set: ${code}`);
+            }
+        }
+        catch (err) {
+            outputError(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/referral/status.d.ts

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

package/dist/commands/referral/status.js

@@ -0,0 +1,31 @@
+import { getContext, getOutputOptions } from "../../cli/program.js";
+import { output, outputError } from "../../cli/output.js";
+export function registerStatusCommand(referral) {
+    referral
+        .command("status")
+        .description("Get referral status")
+        .action(async function () {
+        const ctx = getContext(this);
+        const outputOpts = getOutputOptions(this);
+        try {
+            const client = ctx.getPublicClient();
+            const user = ctx.getWalletAddress();
+            const result = await client.referral({ user });
+            if (outputOpts.json) {
+                output(result, outputOpts);
+            }
+            else {
+                if (!result) {
+                    console.log("No referral information found");
+                }
+                else {
+                    output(result, outputOpts);
+                }
+            }
+        }
+        catch (err) {
+            outputError(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}

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

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

package/dist/commands/replay/index.js

@@ -0,0 +1,152 @@
+import { existsSync, readFileSync } from "node:fs";
+import { getDb } from "../../lib/db/index.js";
+import { AGENT_AUDIT_LOG_PATH } from "../../lib/paths.js";
+import { queryRiskEvaluations } from "../../lib/risk/evaluation-log.js";
+import { withJsonContract } from "../../lib/contracts.js";
+import { output } from "../../cli/output.js";
+import { getOutputOptions } from "../../cli/program.js";
+function readAuditEventsForTrace(traceId) {
+    if (!existsSync(AGENT_AUDIT_LOG_PATH))
+        return [];
+    const lines = readFileSync(AGENT_AUDIT_LOG_PATH, "utf-8")
+        .split("\n")
+        .filter(Boolean);
+    return lines
+        .map((line) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((event) => event?.traceId === traceId);
+}
+function formatCurrency(usd) {
+    return `$${usd.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+function formatHumanTimeline(traceId, events) {
+    const lines = [`Trace: ${traceId}`, ""];
+    for (let i = 0; i < events.length; i++) {
+        const event = events[i];
+        const ts = new Date(event.timestamp).toISOString();
+        const num = i + 1;
+        if (event.type === "risk_evaluation") {
+            const d = event.data;
+            lines.push(`${num}. [${ts}] Risk Evaluation`);
+            lines.push(`   Exchange: ${d.exchange} | Market: ${d.market ?? "N/A"} | Side: ${d.side ?? "N/A"}`);
+            lines.push(`   Requested: ${formatCurrency(d.requestedSizeUsd)} | Equity: ${formatCurrency(d.equity)} | Exposure: ${formatCurrency(d.exposureUsd)}`);
+            if (d.confidence !== undefined) {
+                lines.push(`   Confidence: ${d.confidence}`);
+            }
+            const rulesEvaluated = d.rulesEvaluated;
+            const rulesFired = d.rulesFired;
+            lines.push(`   Rules evaluated: ${rulesEvaluated.length > 0 ? rulesEvaluated.join(", ") : "(none)"}`);
+            lines.push(`   Rules fired: ${rulesFired.length > 0 ? rulesFired.join(", ") : "(none)"}`);
+            const result = d.allowed ? "ALLOWED" : "DENIED";
+            const adjustedPart = d.adjustedSizeUsd !== undefined
+                ? ` | Adjusted size: ${formatCurrency(d.adjustedSizeUsd)}`
+                : "";
+            lines.push(`   Result: ${result}${adjustedPart}`);
+        }
+        else if (event.type === "journal_entry") {
+            const d = event.data;
+            lines.push(`${num}. [${ts}] Execution Journal`);
+            lines.push(`   Key: ${d.idempotencyKey} | Command: ${d.command}`);
+            lines.push(`   Exchange: ${d.exchange} | Market: ${d.market ?? "N/A"}`);
+            lines.push(`   Status: ${d.status}`);
+        }
+        else if (event.type === "audit_event") {
+            const d = event.data;
+            lines.push(`${num}. [${ts}] Audit Event`);
+            lines.push(`   Action: ${d.action ?? "unknown"} | Status: ${d.status ?? "unknown"}`);
+            lines.push(`   Exchange: ${d.exchange ?? "N/A"} | Market: ${d.market ?? "N/A"}`);
+        }
+        if (i < events.length - 1) {
+            lines.push("");
+        }
+    }
+    return lines.join("\n");
+}
+export function registerReplayCommands(program) {
+    program
+        .command("replay <trace-id>")
+        .description("Reconstruct the full execution timeline for a trace ID")
+        .action(async (traceId, _opts, command) => {
+        const { json } = getOutputOptions(command);
+        const events = [];
+        // 1. Query risk evaluation log
+        const riskEvals = queryRiskEvaluations({ traceId });
+        for (const r of riskEvals) {
+            events.push({
+                type: "risk_evaluation",
+                timestamp: r.createdAt,
+                data: {
+                    exchange: r.exchange,
+                    market: r.market,
+                    side: r.side,
+                    requestedSizeUsd: r.requestedSizeUsd,
+                    equity: r.equity,
+                    exposureUsd: r.exposureUsd,
+                    confidence: r.confidence,
+                    rulesEvaluated: r.rulesEvaluated,
+                    rulesFired: r.rulesFired,
+                    allowed: r.allowed,
+                    adjustedSizeUsd: r.adjustedSizeUsd,
+                    reason: r.reason,
+                },
+            });
+        }
+        // 2. Query execution journal
+        const db = getDb();
+        const journalEntries = db
+            .prepare("SELECT * FROM execution_journal WHERE trace_id = ? ORDER BY created_at")
+            .all(traceId);
+        for (const j of journalEntries) {
+            events.push({
+                type: "journal_entry",
+                timestamp: j.created_at,
+                data: {
+                    idempotencyKey: j.idempotency_key,
+                    command: j.command,
+                    exchange: j.exchange,
+                    market: j.market,
+                    side: j.side,
+                    orderType: j.order_type,
+                    status: j.status,
+                    errorMessage: j.error_message,
+                },
+            });
+        }
+        // 3. Scan audit log
+        const auditEvents = readAuditEventsForTrace(traceId);
+        for (const a of auditEvents) {
+            events.push({
+                type: "audit_event",
+                timestamp: a.timestamp,
+                data: {
+                    action: a.action,
+                    status: a.status,
+                    exchange: a.exchange,
+                    market: a.market,
+                },
+            });
+        }
+        // Sort chronologically
+        events.sort((a, b) => a.timestamp - b.timestamp);
+        if (events.length === 0) {
+            output(json
+                ? withJsonContract("replay.timeline", { traceId, events: [] })
+                : `No events found for trace ID: ${traceId}`, { json });
+            return;
+        }
+        if (json) {
+            output(withJsonContract("replay.timeline", { traceId, events }), {
+                json,
+            });
+        }
+        else {
+            output(formatHumanTimeline(traceId, events), { json });
+        }
+    });
+}

package/dist/commands/risk/analytics.d.ts

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

package/dist/commands/risk/analytics.js

@@ -0,0 +1,64 @@
+import { getOutputOptions } from "../../cli/program.js";
+import { output } from "../../cli/output.js";
+import { withJsonContract } from "../../lib/contracts.js";
+import { getDenialsByReason, getEvalWindows, detectAnomalies, } from "../../lib/risk/analytics.js";
+export function registerRiskAnalyticsCommands(parent) {
+    parent
+        .command("patterns")
+        .description("Show denial patterns from risk evaluations")
+        .option("--minutes <n>", "Time window in minutes", Number.parseInt, 60)
+        .action(function () {
+        const outputOpts = getOutputOptions(this);
+        const opts = this.opts();
+        const denials = getDenialsByReason(opts.minutes);
+        const windows = getEvalWindows(5, opts.minutes);
+        if (outputOpts.json) {
+            output(withJsonContract("risk.patterns", { denials, windows }), outputOpts);
+            return;
+        }
+        if (denials.length === 0) {
+            console.log(`\nNo denials in the last ${opts.minutes} minutes.\n`);
+            return;
+        }
+        console.log(`\nDenial patterns (last ${opts.minutes} min):\n`);
+        for (const d of denials) {
+            const lastSeen = new Date(d.lastSeen).toISOString();
+            console.log(`  ${d.reason}`);
+            console.log(`    Count:     ${d.count}`);
+            console.log(`    Markets:   ${d.markets.join(", ") || "(none)"}`);
+            console.log(`    Last seen: ${lastSeen}`);
+            console.log("");
+        }
+    });
+    parent
+        .command("anomalies")
+        .description("Detect anomalies in recent risk evaluations")
+        .option("--threshold <0-1>", "Denial rate threshold", Number.parseFloat, 0.5)
+        .option("--window <minutes>", "Window size in minutes", Number.parseInt, 5)
+        .action(function () {
+        const outputOpts = getOutputOptions(this);
+        const opts = this.opts();
+        const alerts = detectAnomalies({
+            denialRateThreshold: opts.threshold,
+            windowMinutes: opts.window,
+        });
+        if (outputOpts.json) {
+            output(withJsonContract("risk.anomalies", {
+                alerts,
+                window: opts.window,
+            }), outputOpts);
+            return;
+        }
+        if (alerts.length === 0) {
+            console.log(`\nNo anomalies detected in the last ${opts.window} minutes.\n`);
+            return;
+        }
+        console.log(`\nAnomalies detected:\n`);
+        for (const a of alerts) {
+            const severity = a.severity === "critical" ? "CRITICAL" : "WARNING";
+            console.log(`  [${severity}] ${a.type}`);
+            console.log(`    ${a.message}`);
+            console.log("");
+        }
+    });
+}

package/dist/commands/risk/audit.d.ts

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