@raintree-technology/perps 0.1.0

package/dist/lib/rate-limit.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Rate Limiting Utilities
+ * Prevents API abuse and handles concurrent requests
+ */
+/**
+ * Simple semaphore for limiting concurrent operations
+ */
+export declare class Semaphore {
+    private permits;
+    private queue;
+    constructor(permits: number);
+    acquire(): Promise<void>;
+    release(): void;
+}
+/**
+ * Run promises with concurrency limit
+ */
+export declare function pLimit<T>(tasks: Array<() => Promise<T>>, concurrency?: number): Promise<Array<PromiseSettledResult<T>>>;
+/**
+ * Run promises sequentially with delay between each
+ */
+export declare function pSequential<T>(tasks: Array<() => Promise<T>>, delayMs?: number): Promise<T[]>;
+/**
+ * Rate limiter with sliding window
+ */
+export declare class RateLimiter {
+    private timestamps;
+    private readonly maxRequests;
+    private readonly windowMs;
+    constructor(maxRequests: number, windowMs: number);
+    acquire(): Promise<void>;
+}

package/dist/lib/rate-limit.js

@@ -0,0 +1,88 @@
+/**
+ * Rate Limiting Utilities
+ * Prevents API abuse and handles concurrent requests
+ */
+/**
+ * Simple semaphore for limiting concurrent operations
+ */
+export class Semaphore {
+    permits;
+    queue = [];
+    constructor(permits) {
+        this.permits = permits;
+    }
+    async acquire() {
+        if (this.permits > 0) {
+            this.permits--;
+            return;
+        }
+        return new Promise(resolve => {
+            this.queue.push(resolve);
+        });
+    }
+    release() {
+        const next = this.queue.shift();
+        if (next) {
+            next();
+        }
+        else {
+            this.permits++;
+        }
+    }
+}
+/**
+ * Run promises with concurrency limit
+ */
+export async function pLimit(tasks, concurrency = 3) {
+    const semaphore = new Semaphore(concurrency);
+    const wrappedTasks = tasks.map(async (task) => {
+        await semaphore.acquire();
+        try {
+            return await task();
+        }
+        finally {
+            semaphore.release();
+        }
+    });
+    return Promise.allSettled(wrappedTasks);
+}
+/**
+ * Run promises sequentially with delay between each
+ */
+export async function pSequential(tasks, delayMs = 100) {
+    const results = [];
+    for (const task of tasks) {
+        results.push(await task());
+        if (delayMs > 0) {
+            await sleep(delayMs);
+        }
+    }
+    return results;
+}
+/**
+ * Rate limiter with sliding window
+ */
+export class RateLimiter {
+    timestamps = [];
+    maxRequests;
+    windowMs;
+    constructor(maxRequests, windowMs) {
+        this.maxRequests = maxRequests;
+        this.windowMs = windowMs;
+    }
+    async acquire() {
+        while (true) {
+            const now = Date.now();
+            this.timestamps = this.timestamps.filter(t => now - t < this.windowMs);
+            if (this.timestamps.length < this.maxRequests) {
+                this.timestamps.push(now);
+                return;
+            }
+            const waitTime = this.timestamps[0] + this.windowMs - now;
+            await sleep(Math.max(0, waitTime));
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

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

@@ -0,0 +1,39 @@
+export interface DenialSummary {
+    reason: string;
+    count: number;
+    lastSeen: number;
+    markets: string[];
+}
+export interface EvalWindow {
+    total: number;
+    allowed: number;
+    denied: number;
+    denialRate: number;
+    windowStartMs: number;
+    windowEndMs: number;
+}
+export interface AnomalyAlert {
+    type: "high_denial_rate" | "repeated_denial" | "exposure_spike";
+    severity: "warning" | "critical";
+    message: string;
+    data: Record<string, unknown>;
+    timestamp: number;
+}
+/**
+ * Get denials grouped by reason in the last N minutes.
+ */
+export declare function getDenialsByReason(minutes?: number): DenialSummary[];
+/**
+ * Get evaluation stats in sliding windows.
+ *
+ * Breaks the last `spanMinutes` into `windowMinutes`-sized buckets. For each
+ * bucket, counts total/allowed/denied and computes denial rate.
+ */
+export declare function getEvalWindows(windowMinutes?: number, spanMinutes?: number): EvalWindow[];
+/**
+ * Detect anomalies based on recent evaluation patterns.
+ */
+export declare function detectAnomalies(options?: {
+    denialRateThreshold?: number;
+    windowMinutes?: number;
+}): AnomalyAlert[];

package/dist/lib/risk/analytics.js

@@ -0,0 +1,98 @@
+import { getDb } from "../db/index.js";
+/**
+ * Get denials grouped by reason in the last N minutes.
+ */
+export function getDenialsByReason(minutes = 60) {
+    const db = getDb();
+    const cutoff = Date.now() - minutes * 60_000;
+    const rows = db
+        .prepare(`SELECT reason, COUNT(*) as count, MAX(created_at) as last_seen,
+              GROUP_CONCAT(DISTINCT market) as markets
+       FROM risk_evaluation_log
+       WHERE allowed = 0 AND created_at > ?
+       GROUP BY reason
+       ORDER BY count DESC`)
+        .all(cutoff);
+    return rows.map((r) => ({
+        reason: r.reason ?? "unknown",
+        count: r.count,
+        lastSeen: r.last_seen,
+        markets: r.markets ? r.markets.split(",").filter(Boolean) : [],
+    }));
+}
+/**
+ * Get evaluation stats in sliding windows.
+ *
+ * Breaks the last `spanMinutes` into `windowMinutes`-sized buckets. For each
+ * bucket, counts total/allowed/denied and computes denial rate.
+ */
+export function getEvalWindows(windowMinutes = 5, spanMinutes = 60) {
+    const db = getDb();
+    const bucketMs = windowMinutes * 60_000;
+    const cutoff = Date.now() - spanMinutes * 60_000;
+    const rows = db
+        .prepare(`SELECT
+         (created_at / ?) * ? as bucket,
+         COUNT(*) as total,
+         SUM(CASE WHEN allowed = 1 THEN 1 ELSE 0 END) as allowed,
+         SUM(CASE WHEN allowed = 0 THEN 1 ELSE 0 END) as denied
+       FROM risk_evaluation_log
+       WHERE created_at > ?
+       GROUP BY bucket
+       ORDER BY bucket`)
+        .all(bucketMs, bucketMs, cutoff);
+    return rows.map((r) => ({
+        total: r.total,
+        allowed: r.allowed,
+        denied: r.denied,
+        denialRate: r.total > 0 ? r.denied / r.total : 0,
+        windowStartMs: r.bucket,
+        windowEndMs: r.bucket + bucketMs,
+    }));
+}
+/**
+ * Detect anomalies based on recent evaluation patterns.
+ */
+export function detectAnomalies(options) {
+    const threshold = options?.denialRateThreshold ?? 0.5;
+    const windowMinutes = options?.windowMinutes ?? 5;
+    const alerts = [];
+    const now = Date.now();
+    // Check the most recent window for high denial rate
+    const windows = getEvalWindows(windowMinutes, windowMinutes);
+    if (windows.length > 0) {
+        const latest = windows[windows.length - 1];
+        if (latest.denialRate > threshold && latest.total > 3) {
+            alerts.push({
+                type: "high_denial_rate",
+                severity: latest.denialRate > 0.8 ? "critical" : "warning",
+                message: `Denial rate ${(latest.denialRate * 100).toFixed(0)}% (${latest.denied}/${latest.total}) in last ${windowMinutes} min`,
+                data: {
+                    denialRate: latest.denialRate,
+                    denied: latest.denied,
+                    total: latest.total,
+                    windowMinutes,
+                },
+                timestamp: now,
+            });
+        }
+    }
+    // Check for repeated denials by reason
+    const denials = getDenialsByReason(windowMinutes);
+    for (const d of denials) {
+        if (d.count > 5) {
+            alerts.push({
+                type: "repeated_denial",
+                severity: d.count > 10 ? "critical" : "warning",
+                message: `"${d.reason}" denied ${d.count} times in last ${windowMinutes} min`,
+                data: {
+                    reason: d.reason,
+                    count: d.count,
+                    markets: d.markets,
+                },
+                timestamp: now,
+            });
+        }
+    }
+    return alerts;
+}

package/dist/lib/risk/drawdown.d.ts

@@ -0,0 +1,18 @@
+export interface DrawdownState {
+    peakEquity: number;
+    halted: boolean;
+}
+export declare class DrawdownMonitor {
+    private peakEquity;
+    private readonly maxDrawdownPct;
+    private haltedState;
+    constructor(maxDrawdownPct: number, initialState?: Partial<DrawdownState>);
+    get halted(): boolean;
+    get peak(): number;
+    update(equity: number): {
+        drawdownPct: number;
+        halted: boolean;
+        peakEquity: number;
+    };
+    reset(): void;
+}

package/dist/lib/risk/drawdown.js

@@ -0,0 +1,49 @@
+import { eventBus } from "../events/bus.js";
+import { createLogger } from "../logger.js";
+const log = createLogger("risk:drawdown");
+export class DrawdownMonitor {
+    peakEquity = 0;
+    maxDrawdownPct;
+    haltedState = false;
+    constructor(maxDrawdownPct, initialState) {
+        this.maxDrawdownPct = maxDrawdownPct;
+        this.peakEquity = initialState?.peakEquity ?? 0;
+        this.haltedState = initialState?.halted ?? false;
+    }
+    get halted() {
+        return this.haltedState;
+    }
+    get peak() {
+        return this.peakEquity;
+    }
+    update(equity) {
+        if (equity > this.peakEquity) {
+            this.peakEquity = equity;
+        }
+        const drawdownPct = this.peakEquity > 0
+            ? ((this.peakEquity - equity) / this.peakEquity) * 100
+            : 0;
+        if (drawdownPct >= this.maxDrawdownPct && !this.haltedState) {
+            this.haltedState = true;
+            log.error("CIRCUIT BREAKER: max drawdown exceeded", {
+                drawdownPct: drawdownPct.toFixed(2),
+                maxAllowed: this.maxDrawdownPct,
+                equity,
+                peak: this.peakEquity,
+            });
+            eventBus.emit("risk.circuit_breaker.tripped", {
+                exchange: "",
+                drawdownPct,
+                peakEquity: this.peakEquity,
+                currentEquity: equity,
+                timestamp: Date.now(),
+            });
+        }
+        return { drawdownPct, halted: this.haltedState, peakEquity: this.peakEquity };
+    }
+    reset() {
+        this.haltedState = false;
+        this.peakEquity = 0;
+        log.info("Drawdown monitor reset");
+    }
+}

package/dist/lib/risk/evaluation-log.d.ts

@@ -0,0 +1,29 @@
+export interface RiskEvaluationInput {
+    traceId?: string;
+    exchange: string;
+    market?: string;
+    side?: string;
+    requestedSizeUsd: number;
+    equity: number;
+    exposureUsd: number;
+    confidence?: number;
+    allowed: boolean;
+    adjustedSizeUsd?: number;
+    drawdownPct?: number;
+    rulesEvaluated: string[];
+    rulesFired: string[];
+    reason: string | null;
+}
+export interface RiskEvaluationRecord extends RiskEvaluationInput {
+    id: number;
+    createdAt: number;
+}
+export interface RiskEvaluationQuery {
+    traceId?: string;
+    market?: string;
+    exchange?: string;
+    allowed?: boolean;
+    limit?: number;
+}
+export declare function logRiskEvaluation(input: RiskEvaluationInput): number;
+export declare function queryRiskEvaluations(query?: RiskEvaluationQuery): RiskEvaluationRecord[];

package/dist/lib/risk/evaluation-log.js

@@ -0,0 +1,61 @@
+import { getDb } from "../db/index.js";
+function rowToRecord(row) {
+    return {
+        id: row.id,
+        traceId: row.trace_id ?? undefined,
+        exchange: row.exchange,
+        market: row.market ?? undefined,
+        side: row.side ?? undefined,
+        requestedSizeUsd: row.requested_size_usd,
+        equity: row.equity,
+        exposureUsd: row.exposure_usd,
+        confidence: row.confidence ?? undefined,
+        allowed: row.allowed === 1,
+        adjustedSizeUsd: row.adjusted_size_usd ?? undefined,
+        drawdownPct: row.drawdown_pct ?? undefined,
+        rulesEvaluated: row.rules_evaluated
+            ? JSON.parse(row.rules_evaluated)
+            : [],
+        rulesFired: row.rules_fired
+            ? JSON.parse(row.rules_fired)
+            : [],
+        reason: row.reason,
+        createdAt: row.created_at,
+    };
+}
+export function logRiskEvaluation(input) {
+    const db = getDb();
+    const stmt = db.prepare(`INSERT INTO risk_evaluation_log
+       (trace_id, exchange, market, side, requested_size_usd, equity, exposure_usd,
+        confidence, allowed, adjusted_size_usd, drawdown_pct, rules_evaluated, rules_fired, reason)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const result = stmt.run(input.traceId ?? null, input.exchange, input.market ?? null, input.side ?? null, input.requestedSizeUsd, input.equity, input.exposureUsd, input.confidence ?? null, input.allowed ? 1 : 0, input.adjustedSizeUsd ?? null, input.drawdownPct ?? null, JSON.stringify(input.rulesEvaluated), JSON.stringify(input.rulesFired), input.reason);
+    return Number(result.lastInsertRowid);
+}
+export function queryRiskEvaluations(query = {}) {
+    const db = getDb();
+    const conditions = [];
+    const params = [];
+    if (query.traceId !== undefined) {
+        conditions.push("trace_id = ?");
+        params.push(query.traceId);
+    }
+    if (query.market !== undefined) {
+        conditions.push("market = ?");
+        params.push(query.market);
+    }
+    if (query.exchange !== undefined) {
+        conditions.push("exchange = ?");
+        params.push(query.exchange);
+    }
+    if (query.allowed !== undefined) {
+        conditions.push("allowed = ?");
+        params.push(query.allowed ? 1 : 0);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const limit = query.limit ?? 100;
+    const rows = db
+        .prepare(`SELECT * FROM risk_evaluation_log ${where} ORDER BY created_at DESC LIMIT ?`)
+        .all(...params, limit);
+    return rows.map(rowToRecord);
+}

package/dist/lib/risk/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./drawdown.js";
+export * from "./limits.js";
+export * from "./manager.js";
+export * from "./position-sizer.js";

package/dist/lib/risk/index.js

@@ -0,0 +1,4 @@
+export * from "./drawdown.js";
+export * from "./limits.js";
+export * from "./manager.js";
+export * from "./position-sizer.js";

package/dist/lib/risk/limits.d.ts

@@ -0,0 +1,23 @@
+export interface RiskLimitsConfig {
+    maxPositionSizeUsd: number;
+    maxTotalExposureUsd: number;
+    maxLeverage: number;
+    minSignalConfidence: number;
+}
+export interface RiskSignal {
+    market: string;
+    side: "long" | "short" | "close";
+    confidence: number;
+    reason?: string;
+    timestamp?: number;
+}
+export interface RiskCheck {
+    allowed: boolean;
+    reason?: string;
+    adjustedSizeUsd?: number;
+}
+export declare class RiskLimits {
+    private readonly config;
+    constructor(config: RiskLimitsConfig);
+    check(signal: RiskSignal, proposedSizeUsd: number, currentExposureUsd: number, equity: number): RiskCheck;
+}

package/dist/lib/risk/limits.js

@@ -0,0 +1,27 @@
+export class RiskLimits {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    check(signal, proposedSizeUsd, currentExposureUsd, equity) {
+        if (signal.confidence < this.config.minSignalConfidence) {
+            return {
+                allowed: false,
+                reason: `Confidence ${signal.confidence.toFixed(3)} below min ${this.config.minSignalConfidence}`,
+            };
+        }
+        if (proposedSizeUsd > this.config.maxPositionSizeUsd) {
+            proposedSizeUsd = this.config.maxPositionSizeUsd;
+        }
+        const newTotalExposure = currentExposureUsd + proposedSizeUsd;
+        const maxExposure = Math.min(this.config.maxTotalExposureUsd, equity * this.config.maxLeverage);
+        if (newTotalExposure > maxExposure) {
+            const available = maxExposure - currentExposureUsd;
+            if (available <= 0) {
+                return { allowed: false, reason: "Max exposure reached" };
+            }
+            proposedSizeUsd = available;
+        }
+        return { allowed: true, adjustedSizeUsd: proposedSizeUsd };
+    }
+}

package/dist/lib/risk/manager.d.ts

@@ -0,0 +1,32 @@
+import { type DrawdownState } from "./drawdown.js";
+import { type RiskLimitsConfig, type RiskSignal } from "./limits.js";
+import { type PositionSizerConfig } from "./position-sizer.js";
+export interface RiskManagerConfig {
+    positionSizer: PositionSizerConfig;
+    limits: RiskLimitsConfig;
+    maxDrawdownPct: number;
+    initialDrawdownState?: Partial<DrawdownState>;
+}
+export interface RiskEvaluation {
+    allowed: boolean;
+    sizeUsd: number;
+    reason?: string;
+    drawdownPct: number;
+    peakEquity: number;
+    halted: boolean;
+}
+export declare class RiskManager {
+    private readonly sizer;
+    private readonly drawdown;
+    private readonly limits;
+    constructor(config: RiskManagerConfig);
+    evaluate(signal: RiskSignal, equity: number, currentExposureUsd: number, proposedSizeUsd?: number): RiskEvaluation;
+    updateEquity(equity: number): {
+        drawdownPct: number;
+        halted: boolean;
+        peakEquity: number;
+    };
+    get isHalted(): boolean;
+    get drawdownState(): DrawdownState;
+    resetCircuitBreaker(): void;
+}

package/dist/lib/risk/manager.js

@@ -0,0 +1,85 @@
+import { createLogger } from "../logger.js";
+import { DrawdownMonitor } from "./drawdown.js";
+import { RiskLimits } from "./limits.js";
+import { PositionSizer } from "./position-sizer.js";
+const log = createLogger("risk:manager");
+export class RiskManager {
+    sizer;
+    drawdown;
+    limits;
+    constructor(config) {
+        this.sizer = new PositionSizer(config.positionSizer);
+        this.drawdown = new DrawdownMonitor(config.maxDrawdownPct, config.initialDrawdownState);
+        this.limits = new RiskLimits(config.limits);
+    }
+    evaluate(signal, equity, currentExposureUsd, proposedSizeUsd) {
+        const dd = this.drawdown.update(equity);
+        if (dd.halted) {
+            return {
+                allowed: false,
+                sizeUsd: 0,
+                reason: "Trading halted: max drawdown exceeded",
+                drawdownPct: dd.drawdownPct,
+                peakEquity: dd.peakEquity,
+                halted: dd.halted,
+            };
+        }
+        if (signal.side === "close") {
+            return {
+                allowed: true,
+                sizeUsd: 0,
+                drawdownPct: dd.drawdownPct,
+                peakEquity: dd.peakEquity,
+                halted: dd.halted,
+            };
+        }
+        const sizedByPolicy = this.sizer.calculate(equity, signal.confidence, currentExposureUsd);
+        const effectiveProposed = proposedSizeUsd !== undefined
+            ? Math.min(proposedSizeUsd, sizedByPolicy)
+            : sizedByPolicy;
+        if (effectiveProposed <= 0) {
+            return {
+                allowed: false,
+                sizeUsd: 0,
+                reason: "Position sizer returned 0",
+                drawdownPct: dd.drawdownPct,
+                peakEquity: dd.peakEquity,
+                halted: dd.halted,
+            };
+        }
+        const check = this.limits.check(signal, effectiveProposed, currentExposureUsd, equity);
+        if (!check.allowed) {
+            log.info("Risk rejected signal", { market: signal.market, reason: check.reason });
+            return {
+                allowed: false,
+                sizeUsd: 0,
+                reason: check.reason,
+                drawdownPct: dd.drawdownPct,
+                peakEquity: dd.peakEquity,
+                halted: dd.halted,
+            };
+        }
+        return {
+            allowed: true,
+            sizeUsd: check.adjustedSizeUsd ?? effectiveProposed,
+            drawdownPct: dd.drawdownPct,
+            peakEquity: dd.peakEquity,
+            halted: dd.halted,
+        };
+    }
+    updateEquity(equity) {
+        return this.drawdown.update(equity);
+    }
+    get isHalted() {
+        return this.drawdown.halted;
+    }
+    get drawdownState() {
+        return {
+            peakEquity: this.drawdown.peak,
+            halted: this.drawdown.halted,
+        };
+    }
+    resetCircuitBreaker() {
+        this.drawdown.reset();
+    }
+}

package/dist/lib/risk/policy-middleware.d.ts

@@ -0,0 +1,33 @@
+import type { PerpDEXAdapter } from "../../adapters/interface.js";
+import type { Config } from "../config.js";
+import type { RiskSignal } from "./limits.js";
+export interface RiskOrderInput {
+    market: string;
+    side: "long" | "short";
+    requestedSizeBase: number;
+    confidence?: number;
+    referencePriceUsd?: number;
+    reason?: string;
+}
+export interface RiskOrderDecision {
+    allowed: boolean;
+    adjustedSizeBase: number;
+    adjustedSizeUsd: number;
+    referencePriceUsd: number;
+    reason?: string;
+}
+export declare class RiskPolicyMiddleware {
+    private readonly config;
+    private readonly exchangeId;
+    private readonly manager;
+    constructor(config: Config, exchangeId: string);
+    evaluateUsdSignal(adapter: PerpDEXAdapter, signal: RiskSignal, proposedSizeUsd: number, traceId?: string): Promise<{
+        allowed: boolean;
+        sizeUsd: number;
+        reason?: string;
+    }>;
+    evaluateOrder(adapter: PerpDEXAdapter, input: RiskOrderInput, traceId?: string): Promise<RiskOrderDecision>;
+    private resolveReferencePrice;
+    private loadAccountMetrics;
+    private recordHeartbeat;
+}