perp-cli 0.3.3

package/dist/__tests__/exchanges/mock-adapter.js

@@ -0,0 +1,137 @@
+/**
+ * Mock adapter for unit testing. Records all calls and returns configurable responses.
+ */
+export class MockAdapter {
+    name;
+    calls = [];
+    // Configurable return values
+    marketsResponse = [];
+    orderbookResponse = { bids: [], asks: [] };
+    balanceResponse = { equity: "1000", available: "800", marginUsed: "200", unrealizedPnl: "50" };
+    positionsResponse = [];
+    ordersResponse = [];
+    orderResult = { status: "ok", orderId: "12345" };
+    constructor(name = "mock") {
+        this.name = name;
+    }
+    record(method, args) {
+        this.calls.push({ method, args });
+    }
+    getCallsFor(method) {
+        return this.calls.filter((c) => c.method === method);
+    }
+    reset() {
+        this.calls = [];
+    }
+    async getMarkets() {
+        this.record("getMarkets", []);
+        return this.marketsResponse;
+    }
+    async getOrderbook(symbol) {
+        this.record("getOrderbook", [symbol]);
+        return this.orderbookResponse;
+    }
+    async getBalance() {
+        this.record("getBalance", []);
+        return this.balanceResponse;
+    }
+    async getPositions() {
+        this.record("getPositions", []);
+        return this.positionsResponse;
+    }
+    async getOpenOrders() {
+        this.record("getOpenOrders", []);
+        return this.ordersResponse;
+    }
+    async marketOrder(symbol, side, size) {
+        this.record("marketOrder", [symbol, side, size]);
+        return this.orderResult;
+    }
+    async limitOrder(symbol, side, price, size) {
+        this.record("limitOrder", [symbol, side, price, size]);
+        return this.orderResult;
+    }
+    async editOrder(symbol, orderId, price, size) {
+        this.record("editOrder", [symbol, orderId, price, size]);
+        return this.orderResult;
+    }
+    async cancelOrder(symbol, orderId) {
+        this.record("cancelOrder", [symbol, orderId]);
+        return { status: "cancelled" };
+    }
+    async cancelAllOrders(symbol) {
+        this.record("cancelAllOrders", [symbol]);
+        return { status: "all_cancelled" };
+    }
+    async setLeverage(symbol, leverage, marginMode) {
+        this.record("setLeverage", [symbol, leverage, marginMode]);
+        return { symbol, leverage, marginMode };
+    }
+    async stopOrder(symbol, side, size, triggerPrice, opts) {
+        this.record("stopOrder", [symbol, side, size, triggerPrice, opts]);
+        return this.orderResult;
+    }
+    async getRecentTrades(symbol, limit) {
+        this.record("getRecentTrades", [symbol, limit]);
+        return [];
+    }
+    async getFundingHistory(symbol, limit) {
+        this.record("getFundingHistory", [symbol, limit]);
+        return [];
+    }
+    async getKlines(symbol, interval, startTime, endTime) {
+        this.record("getKlines", [symbol, interval, startTime, endTime]);
+        return [];
+    }
+    async getOrderHistory(limit) {
+        this.record("getOrderHistory", [limit]);
+        return this.ordersResponse;
+    }
+    async getTradeHistory(limit) {
+        this.record("getTradeHistory", [limit]);
+        return [];
+    }
+    async getFundingPayments(limit) {
+        this.record("getFundingPayments", [limit]);
+        return [];
+    }
+}
+/** Factory to create mock markets data */
+export function createMockMarkets(count = 3) {
+    const symbols = ["BTC", "ETH", "SOL", "DOGE", "ARB"];
+    return symbols.slice(0, count).map((symbol) => ({
+        symbol,
+        markPrice: String(symbol === "BTC" ? 100000 : symbol === "ETH" ? 3500 : 150),
+        indexPrice: String(symbol === "BTC" ? 99990 : symbol === "ETH" ? 3498 : 149.5),
+        fundingRate: "0.0001",
+        volume24h: "1000000",
+        openInterest: "500000",
+        maxLeverage: symbol === "BTC" ? 100 : 50,
+    }));
+}
+/** Factory to create mock positions */
+export function createMockPositions(count = 1) {
+    return Array.from({ length: count }, (_, i) => ({
+        symbol: i === 0 ? "BTC" : "ETH",
+        side: (i % 2 === 0 ? "long" : "short"),
+        size: "0.1",
+        entryPrice: "100000",
+        markPrice: "101000",
+        liquidationPrice: "90000",
+        unrealizedPnl: "100",
+        leverage: 10,
+    }));
+}
+/** Factory to create mock orders */
+export function createMockOrders(count = 2) {
+    return Array.from({ length: count }, (_, i) => ({
+        orderId: String(1000 + i),
+        symbol: "BTC",
+        side: (i % 2 === 0 ? "buy" : "sell"),
+        price: String(99000 + i * 1000),
+        size: "0.05",
+        filled: "0",
+        status: "open",
+        type: "limit",
+    }));
+}

package/dist/__tests__/execution-log.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/execution-log.test.js

@@ -0,0 +1,106 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { logExecution, readExecutionLog, getExecutionStats } from "../execution-log.js";
+import { existsSync, unlinkSync, readFileSync, writeFileSync, renameSync } from "fs";
+import { resolve } from "path";
+const PERP_DIR = resolve(process.env.HOME || "~", ".perp");
+const LOG_FILE = resolve(PERP_DIR, "executions.jsonl");
+const BACKUP_FILE = resolve(PERP_DIR, "executions.jsonl.test-backup");
+describe("Execution Log", () => {
+    beforeEach(() => {
+        // Backup existing log if present
+        if (existsSync(LOG_FILE)) {
+            const content = readFileSync(LOG_FILE, "utf-8");
+            writeFileSync(BACKUP_FILE, content);
+        }
+        // Clear log for test
+        if (existsSync(LOG_FILE))
+            unlinkSync(LOG_FILE);
+    });
+    afterEach(() => {
+        // Restore original log
+        if (existsSync(LOG_FILE))
+            unlinkSync(LOG_FILE);
+        if (existsSync(BACKUP_FILE)) {
+            renameSync(BACKUP_FILE, LOG_FILE);
+        }
+    });
+    it("should log an execution record", () => {
+        const record = logExecution({
+            type: "market_order",
+            exchange: "hyperliquid",
+            symbol: "BTC",
+            side: "buy",
+            size: "0.1",
+            price: "100000",
+            notional: 10000,
+            status: "success",
+            dryRun: false,
+        });
+        expect(record.id).toBeTruthy();
+        expect(record.timestamp).toBeTruthy();
+        expect(record.exchange).toBe("hyperliquid");
+        expect(record.symbol).toBe("BTC");
+    });
+    it("should read back logged records", () => {
+        logExecution({ type: "market_order", exchange: "test", symbol: "BTC", side: "buy", size: "0.1", status: "success", dryRun: false });
+        logExecution({ type: "limit_order", exchange: "test", symbol: "ETH", side: "sell", size: "1.0", status: "success", dryRun: false });
+        const records = readExecutionLog();
+        expect(records).toHaveLength(2);
+    });
+    it("should filter by exchange", () => {
+        logExecution({ type: "market_order", exchange: "hl", symbol: "BTC", side: "buy", size: "0.1", status: "success", dryRun: false });
+        logExecution({ type: "market_order", exchange: "pac", symbol: "BTC", side: "buy", size: "0.1", status: "success", dryRun: false });
+        const records = readExecutionLog({ exchange: "hl" });
+        expect(records).toHaveLength(1);
+        expect(records[0].exchange).toBe("hl");
+    });
+    it("should filter by symbol", () => {
+        logExecution({ type: "market_order", exchange: "test", symbol: "BTC", side: "buy", size: "0.1", status: "success", dryRun: false });
+        logExecution({ type: "market_order", exchange: "test", symbol: "ETH", side: "sell", size: "1.0", status: "success", dryRun: false });
+        const records = readExecutionLog({ symbol: "ETH" });
+        expect(records).toHaveLength(1);
+        expect(records[0].symbol).toBe("ETH");
+    });
+    it("should mark dry-run executions", () => {
+        logExecution({ type: "market_order", exchange: "test", symbol: "BTC", side: "buy", size: "0.1", status: "simulated", dryRun: true });
+        logExecution({ type: "market_order", exchange: "test", symbol: "ETH", side: "sell", size: "1.0", status: "success", dryRun: false });
+        const dryRuns = readExecutionLog({ dryRunOnly: true });
+        expect(dryRuns).toHaveLength(1);
+        expect(dryRuns[0].dryRun).toBe(true);
+        expect(dryRuns[0].status).toBe("simulated");
+    });
+    it("should compute execution stats", () => {
+        logExecution({ type: "market_order", exchange: "hl", symbol: "BTC", side: "buy", size: "0.1", status: "success", dryRun: false });
+        logExecution({ type: "limit_order", exchange: "pac", symbol: "ETH", side: "sell", size: "1.0", status: "success", dryRun: false });
+        logExecution({ type: "market_order", exchange: "hl", symbol: "SOL", side: "buy", size: "10", status: "failed", error: "insufficient balance", dryRun: false });
+        const stats = getExecutionStats();
+        expect(stats.totalTrades).toBe(3);
+        expect(stats.successRate).toBeCloseTo(66.67, 0);
+        expect(stats.byExchange.hl).toBe(2);
+        expect(stats.byExchange.pac).toBe(1);
+        expect(stats.byType.market_order).toBe(2);
+        expect(stats.byType.limit_order).toBe(1);
+        expect(stats.recentErrors).toHaveLength(1);
+    });
+    it("should return empty stats when no log file", () => {
+        const stats = getExecutionStats();
+        expect(stats.totalTrades).toBe(0);
+        expect(stats.successRate).toBe(0);
+    });
+    it("should limit results", () => {
+        for (let i = 0; i < 10; i++) {
+            logExecution({ type: "market_order", exchange: "test", symbol: "BTC", side: "buy", size: "0.1", status: "success", dryRun: false });
+        }
+        const records = readExecutionLog({ limit: 3 });
+        expect(records).toHaveLength(3);
+    });
+    it("should sort newest first", async () => {
+        logExecution({ type: "market_order", exchange: "test", symbol: "FIRST", side: "buy", size: "0.1", status: "success", dryRun: false });
+        // Ensure distinct timestamps (Date.now resolution is 1ms)
+        await new Promise((r) => setTimeout(r, 5));
+        logExecution({ type: "market_order", exchange: "test", symbol: "SECOND", side: "buy", size: "0.1", status: "success", dryRun: false });
+        const records = readExecutionLog();
+        expect(records[0].symbol).toBe("SECOND");
+        expect(records[1].symbol).toBe("FIRST");
+    });
+});

package/dist/__tests__/funding-calc.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/funding-calc.test.js

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import { annualizeRate, computeAnnualSpread, toHourlyRate, estimateHourlyFunding } from "../funding.js";
+describe("Funding Rate Normalization", () => {
+    describe("toHourlyRate", () => {
+        it("should return HL rate as-is (already hourly)", () => {
+            expect(toHourlyRate(0.001, "hyperliquid")).toBeCloseTo(0.001);
+        });
+        it("should return Pacifica rate as-is (already hourly)", () => {
+            expect(toHourlyRate(0.001, "pacifica")).toBeCloseTo(0.001);
+        });
+        it("should return Lighter rate as-is (already hourly)", () => {
+            expect(toHourlyRate(0.001, "lighter")).toBeCloseTo(0.001);
+        });
+    });
+    describe("annualizeRate", () => {
+        it("should annualize HL hourly rate correctly", () => {
+            // 0.01% per hour * 8760 hours = 87.6%
+            const result = annualizeRate(0.0001, "hyperliquid");
+            expect(result).toBeCloseTo(87.6, 0);
+        });
+        it("should annualize Pacifica hourly rate correctly", () => {
+            // 0.01% per hour * 8760 = 87.6%
+            const result = annualizeRate(0.0001, "pacifica");
+            expect(result).toBeCloseTo(87.6, 0);
+        });
+        it("should handle zero rate", () => {
+            expect(annualizeRate(0, "hyperliquid")).toBe(0);
+        });
+        it("should handle negative rates", () => {
+            expect(annualizeRate(-0.0001, "hyperliquid")).toBeLessThan(0);
+        });
+    });
+    describe("computeAnnualSpread", () => {
+        it("should compute spread between different exchanges", () => {
+            // HL: 0.01% hourly, PAC: 0.001% hourly
+            // Spread = |0.0001 - 0.00001| * 8760 * 100 = ~78.84%
+            const spread = computeAnnualSpread(0.0001, "hyperliquid", 0.00001, "pacifica");
+            expect(spread).toBeGreaterThan(0);
+        });
+        it("should return positive spread when rates are ordered correctly", () => {
+            const spread = computeAnnualSpread(0.001, "hyperliquid", 0.0001, "hyperliquid");
+            expect(spread).toBeGreaterThan(0);
+        });
+        it("should handle same exchange same rate (zero spread)", () => {
+            const spread = computeAnnualSpread(0.0001, "hyperliquid", 0.0001, "hyperliquid");
+            expect(spread).toBeCloseTo(0, 1);
+        });
+        it("should compute zero spread for identical hourly rates", () => {
+            // Same hourly rate on both exchanges
+            const spread = computeAnnualSpread(0.001, "hyperliquid", 0.001, "pacifica");
+            expect(Math.abs(spread)).toBeLessThan(1); // should be ~0
+        });
+    });
+    describe("estimateHourlyFunding", () => {
+        it("should estimate funding cost for long position (positive rate = longs pay)", () => {
+            // Positive rate, long position = pay funding (positive return means you pay)
+            const result = estimateHourlyFunding(0.0001, "hyperliquid", 10000, "long");
+            expect(result).toBeGreaterThan(0); // longs pay when rate is positive
+        });
+        it("should estimate funding income for short position (positive rate = shorts receive)", () => {
+            // Positive rate, short position = receive funding (negative return means you receive)
+            const result = estimateHourlyFunding(0.0001, "hyperliquid", 10000, "short");
+            expect(result).toBeLessThan(0); // shorts receive when rate is positive
+        });
+        it("should scale with position size", () => {
+            const small = estimateHourlyFunding(0.0001, "hyperliquid", 1000, "long");
+            const big = estimateHourlyFunding(0.0001, "hyperliquid", 10000, "long");
+            expect(Math.abs(big)).toBeCloseTo(Math.abs(small) * 10, 2);
+        });
+    });
+});

package/dist/__tests__/funding-history.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/funding-history.test.js

@@ -0,0 +1,343 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+// Use vi.hoisted so TEST_DIR is available when vi.mock runs (hoisted)
+const { TEST_DIR } = vi.hoisted(() => {
+    const { tmpdir } = require("node:os");
+    const { join } = require("node:path");
+    return {
+        TEST_DIR: join(tmpdir(), `perp-funding-test-${Date.now()}-${Math.random().toString(36).slice(2)}`),
+    };
+});
+// Mock the homedir to redirect storage to our test directory
+vi.mock("node:os", async () => {
+    const actual = await vi.importActual("node:os");
+    return {
+        ...actual,
+        homedir: () => join(TEST_DIR, "home"),
+    };
+});
+import { saveFundingSnapshot, getAvgFundingRate, getHistoricalRates, getHistoricalAverages, getCompoundedAnnualReturn, getExchangeCompoundingHours, cleanupOldFiles, _resetCleanupFlag, } from "../funding-history.js";
+const DATA_DIR = join(TEST_DIR, "home", ".perp", "funding-rates");
+function makeRate(overrides = {}) {
+    return {
+        exchange: "hyperliquid",
+        symbol: "BTC",
+        fundingRate: 0.0001,
+        hourlyRate: 0.0001,
+        annualizedPct: 87.6,
+        markPrice: 50000,
+        ...overrides,
+    };
+}
+function readJsonl(filePath) {
+    if (!existsSync(filePath))
+        return [];
+    const content = readFileSync(filePath, "utf-8");
+    return content
+        .split("\n")
+        .filter(l => l.trim())
+        .map(l => JSON.parse(l));
+}
+function getMonthKey(date) {
+    const y = date.getFullYear();
+    const m = String(date.getMonth() + 1).padStart(2, "0");
+    return `${y}-${m}`;
+}
+describe("funding-history", () => {
+    beforeEach(() => {
+        _resetCleanupFlag();
+        mkdirSync(DATA_DIR, { recursive: true });
+    });
+    afterEach(() => {
+        try {
+            rmSync(TEST_DIR, { recursive: true, force: true });
+        }
+        catch {
+            // ignore cleanup errors
+        }
+    });
+    // ──────────────────────────────────────────────
+    // saveFundingSnapshot
+    // ──────────────────────────────────────────────
+    describe("saveFundingSnapshot", () => {
+        it("writes JSONL correctly", () => {
+            const rates = [
+                makeRate({ exchange: "hyperliquid", symbol: "BTC", fundingRate: 0.0001, hourlyRate: 0.0001 }),
+                makeRate({ exchange: "pacifica", symbol: "ETH", fundingRate: 0.0008, hourlyRate: 0.0001 }),
+            ];
+            saveFundingSnapshot(rates);
+            const monthKey = getMonthKey(new Date());
+            const filePath = join(DATA_DIR, `${monthKey}.jsonl`);
+            expect(existsSync(filePath)).toBe(true);
+            const entries = readJsonl(filePath);
+            expect(entries).toHaveLength(2);
+            expect(entries[0].symbol).toBe("BTC");
+            expect(entries[0].exchange).toBe("hyperliquid");
+            expect(entries[0].rate).toBe(0.0001);
+            expect(entries[0].hourlyRate).toBe(0.0001);
+            expect(entries[0].ts).toBeDefined();
+            expect(entries[1].symbol).toBe("ETH");
+            expect(entries[1].exchange).toBe("pacifica");
+        });
+        it("deduplicates entries within 5 minutes", () => {
+            const rates = [makeRate({ symbol: "BTC", exchange: "hyperliquid" })];
+            // Save twice in quick succession
+            saveFundingSnapshot(rates);
+            saveFundingSnapshot(rates);
+            const monthKey = getMonthKey(new Date());
+            const filePath = join(DATA_DIR, `${monthKey}.jsonl`);
+            const entries = readJsonl(filePath);
+            // Should only have 1 entry due to dedup
+            expect(entries).toHaveLength(1);
+        });
+        it("allows entries after 5 minute gap", () => {
+            const rates = [makeRate({ symbol: "BTC", exchange: "hyperliquid" })];
+            // Write an entry with a timestamp 6 minutes ago
+            const monthKey = getMonthKey(new Date());
+            const filePath = join(DATA_DIR, `${monthKey}.jsonl`);
+            const oldTs = new Date(Date.now() - 6 * 60 * 1000).toISOString();
+            const oldEntry = {
+                ts: oldTs,
+                symbol: "BTC",
+                exchange: "hyperliquid",
+                rate: 0.0001,
+                hourlyRate: 0.0001,
+            };
+            writeFileSync(filePath, JSON.stringify(oldEntry) + "\n");
+            // Now save new snapshot
+            saveFundingSnapshot(rates);
+            const entries = readJsonl(filePath);
+            expect(entries).toHaveLength(2);
+        });
+        it("uppercases symbol names", () => {
+            const rates = [makeRate({ symbol: "btc" })];
+            saveFundingSnapshot(rates);
+            const monthKey = getMonthKey(new Date());
+            const filePath = join(DATA_DIR, `${monthKey}.jsonl`);
+            const entries = readJsonl(filePath);
+            expect(entries[0].symbol).toBe("BTC");
+        });
+        it("skips entries with empty symbol", () => {
+            const rates = [makeRate({ symbol: "" })];
+            saveFundingSnapshot(rates);
+            const monthKey = getMonthKey(new Date());
+            const filePath = join(DATA_DIR, `${monthKey}.jsonl`);
+            // File may or may not exist; if it does, it should be empty
+            if (existsSync(filePath)) {
+                const entries = readJsonl(filePath);
+                expect(entries).toHaveLength(0);
+            }
+        });
+    });
+    // ──────────────────────────────────────────────
+    // getAvgFundingRate
+    // ──────────────────────────────────────────────
+    describe("getAvgFundingRate", () => {
+        it("returns correct average", () => {
+            const monthKey = getMonthKey(new Date());
+            const filePath = join(DATA_DIR, `${monthKey}.jsonl`);
+            // Write 3 entries with different hourly rates at recent times
+            const entries = [
+                { ts: new Date(Date.now() - 30 * 60 * 1000).toISOString(), symbol: "BTC", exchange: "hyperliquid", rate: 0.0001, hourlyRate: 0.0001 },
+                { ts: new Date(Date.now() - 20 * 60 * 1000).toISOString(), symbol: "BTC", exchange: "hyperliquid", rate: 0.0002, hourlyRate: 0.0002 },
+                { ts: new Date(Date.now() - 10 * 60 * 1000).toISOString(), symbol: "BTC", exchange: "hyperliquid", rate: 0.0003, hourlyRate: 0.0003 },
+            ];
+            writeFileSync(filePath, entries.map(e => JSON.stringify(e)).join("\n") + "\n");
+            const avg = getAvgFundingRate("BTC", "hyperliquid", 1);
+            expect(avg).toBeCloseTo(0.0002); // (0.0001 + 0.0002 + 0.0003) / 3
+        });
+        it("returns null when no data available", () => {
+            const avg = getAvgFundingRate("NOEXIST", "hyperliquid", 24);
+            expect(avg).toBeNull();
+        });
+        it("filters by symbol and exchange correctly", () => {
+            const monthKey = getMonthKey(new Date());
+            const filePath = join(DATA_DIR, `${monthKey}.jsonl`);
+            const entries = [
+                { ts: new Date(Date.now() - 10 * 60 * 1000).toISOString(), symbol: "BTC", exchange: "hyperliquid", rate: 0.0001, hourlyRate: 0.0001 },
+                { ts: new Date(Date.now() - 10 * 60 * 1000).toISOString(), symbol: "ETH", exchange: "hyperliquid", rate: 0.0005, hourlyRate: 0.0005 },
+                { ts: new Date(Date.now() - 10 * 60 * 1000).toISOString(), symbol: "BTC", exchange: "pacifica", rate: 0.0008, hourlyRate: 0.0001 },
+            ];
+            writeFileSync(filePath, entries.map(e => JSON.stringify(e)).join("\n") + "\n");
+            const avgBtcHL = getAvgFundingRate("BTC", "hyperliquid", 1);
+            expect(avgBtcHL).toBeCloseTo(0.0001);
+            const avgEthHL = getAvgFundingRate("ETH", "hyperliquid", 1);
+            expect(avgEthHL).toBeCloseTo(0.0005);
+            const avgBtcPac = getAvgFundingRate("BTC", "pacifica", 1);
+            expect(avgBtcPac).toBeCloseTo(0.0001);
+        });
+        it("only includes entries within the time window", () => {
+            const monthKey = getMonthKey(new Date());
+            const filePath = join(DATA_DIR, `${monthKey}.jsonl`);
+            const entries = [
+                { ts: new Date(Date.now() - 3 * 60 * 60 * 1000).toISOString(), symbol: "BTC", exchange: "hyperliquid", rate: 0.001, hourlyRate: 0.001 },
+                { ts: new Date(Date.now() - 10 * 60 * 1000).toISOString(), symbol: "BTC", exchange: "hyperliquid", rate: 0.0001, hourlyRate: 0.0001 },
+            ];
+            writeFileSync(filePath, entries.map(e => JSON.stringify(e)).join("\n") + "\n");
+            // Only 1h window should exclude the 3h-old entry
+            const avg1h = getAvgFundingRate("BTC", "hyperliquid", 1);
+            expect(avg1h).toBeCloseTo(0.0001);
+            // 4h window should include both
+            const avg4h = getAvgFundingRate("BTC", "hyperliquid", 4);
+            expect(avg4h).toBeCloseTo(0.00055); // (0.001 + 0.0001) / 2
+        });
+    });
+    // ──────────────────────────────────────────────
+    // getHistoricalRates
+    // ──────────────────────────────────────────────
+    describe("getHistoricalRates", () => {
+        it("returns sorted entries in time range", () => {
+            const monthKey = getMonthKey(new Date());
+            const filePath = join(DATA_DIR, `${monthKey}.jsonl`);
+            const t1 = new Date(Date.now() - 30 * 60 * 1000);
+            const t2 = new Date(Date.now() - 20 * 60 * 1000);
+            const t3 = new Date(Date.now() - 10 * 60 * 1000);
+            const entries = [
+                { ts: t3.toISOString(), symbol: "BTC", exchange: "hyperliquid", rate: 0.0003, hourlyRate: 0.0003 },
+                { ts: t1.toISOString(), symbol: "BTC", exchange: "hyperliquid", rate: 0.0001, hourlyRate: 0.0001 },
+                { ts: t2.toISOString(), symbol: "BTC", exchange: "hyperliquid", rate: 0.0002, hourlyRate: 0.0002 },
+            ];
+            writeFileSync(filePath, entries.map(e => JSON.stringify(e)).join("\n") + "\n");
+            const startTime = new Date(Date.now() - 60 * 60 * 1000);
+            const endTime = new Date();
+            const result = getHistoricalRates("BTC", "hyperliquid", startTime, endTime);
+            expect(result).toHaveLength(3);
+            // Should be sorted by time ascending
+            expect(result[0].rate).toBe(0.0001);
+            expect(result[1].rate).toBe(0.0002);
+            expect(result[2].rate).toBe(0.0003);
+        });
+    });
+    // ──────────────────────────────────────────────
+    // getHistoricalAverages
+    // ──────────────────────────────────────────────
+    describe("getHistoricalAverages", () => {
+        it("handles missing data (returns null)", () => {
+            const result = getHistoricalAverages(["BTC"], ["hyperliquid"]);
+            const avgs = result.get("BTC:hyperliquid");
+            expect(avgs).toBeDefined();
+            expect(avgs.avg1h).toBeNull();
+            expect(avgs.avg8h).toBeNull();
+            expect(avgs.avg24h).toBeNull();
+            expect(avgs.avg7d).toBeNull();
+        });
+        it("computes averages for different time windows", () => {
+            const monthKey = getMonthKey(new Date());
+            const filePath = join(DATA_DIR, `${monthKey}.jsonl`);
+            const entries = [
+                // Within 1h
+                { ts: new Date(Date.now() - 30 * 60 * 1000).toISOString(), symbol: "BTC", exchange: "hyperliquid", rate: 0.0002, hourlyRate: 0.0002 },
+                // Within 8h but not 1h
+                { ts: new Date(Date.now() - 4 * 60 * 60 * 1000).toISOString(), symbol: "BTC", exchange: "hyperliquid", rate: 0.0004, hourlyRate: 0.0004 },
+            ];
+            writeFileSync(filePath, entries.map(e => JSON.stringify(e)).join("\n") + "\n");
+            const result = getHistoricalAverages(["BTC"], ["hyperliquid"]);
+            const avgs = result.get("BTC:hyperliquid");
+            expect(avgs).toBeDefined();
+            expect(avgs.avg1h).toBeCloseTo(0.0002); // only the 30-min-old entry
+            expect(avgs.avg8h).toBeCloseTo(0.0003); // both entries: (0.0002 + 0.0004) / 2
+            expect(avgs.avg24h).toBeCloseTo(0.0003); // both entries
+            expect(avgs.avg7d).toBeCloseTo(0.0003); // both entries
+        });
+        it("generates correct keys for multiple symbols and exchanges", () => {
+            const result = getHistoricalAverages(["BTC", "ETH"], ["hyperliquid", "pacifica"]);
+            expect(result.has("BTC:hyperliquid")).toBe(true);
+            expect(result.has("BTC:pacifica")).toBe(true);
+            expect(result.has("ETH:hyperliquid")).toBe(true);
+            expect(result.has("ETH:pacifica")).toBe(true);
+        });
+    });
+    // ──────────────────────────────────────────────
+    // cleanupOldFiles
+    // ──────────────────────────────────────────────
+    describe("cleanupOldFiles", () => {
+        it("removes files older than 30 days", () => {
+            // Create a file from 3 months ago
+            const oldDate = new Date();
+            oldDate.setMonth(oldDate.getMonth() - 3);
+            const oldKey = getMonthKey(oldDate);
+            const oldFilePath = join(DATA_DIR, `${oldKey}.jsonl`);
+            writeFileSync(oldFilePath, '{"ts":"old","symbol":"BTC","exchange":"hl","rate":0.01,"hourlyRate":0.01}\n');
+            // Create a current month file
+            const curKey = getMonthKey(new Date());
+            const curFilePath = join(DATA_DIR, `${curKey}.jsonl`);
+            writeFileSync(curFilePath, '{"ts":"now","symbol":"BTC","exchange":"hl","rate":0.01,"hourlyRate":0.01}\n');
+            _resetCleanupFlag();
+            cleanupOldFiles();
+            expect(existsSync(oldFilePath)).toBe(false);
+            expect(existsSync(curFilePath)).toBe(true);
+        });
+        it("keeps recent files", () => {
+            const curKey = getMonthKey(new Date());
+            const curFilePath = join(DATA_DIR, `${curKey}.jsonl`);
+            writeFileSync(curFilePath, '{"ts":"now","symbol":"BTC","exchange":"hl","rate":0.01,"hourlyRate":0.01}\n');
+            _resetCleanupFlag();
+            cleanupOldFiles();
+            expect(existsSync(curFilePath)).toBe(true);
+        });
+    });
+    // ──────────────────────────────────────────────
+    // getCompoundedAnnualReturn
+    // ──────────────────────────────────────────────
+    describe("getCompoundedAnnualReturn", () => {
+        it("calculates correct compounded return for HL (1h compounding)", () => {
+            // hourlyRate = 0.01% = 0.0001
+            // periodRate = 0.0001 * 1 = 0.0001
+            // periodsPerYear = 8760/1 = 8760
+            // (1 + 0.0001)^8760 - 1
+            const result = getCompoundedAnnualReturn(0.0001, 1);
+            // Expected: (1.0001)^8760 - 1 = ~1.3964 (139.64%)
+            expect(result).toBeCloseTo(Math.pow(1.0001, 8760) - 1, 2);
+            expect(result).toBeGreaterThan(0.876); // Should be > simple rate of 87.6%
+        });
+        it("calculates correct compounded return for PAC/LT (1h compounding, same as HL)", () => {
+            // hourlyRate = 0.0001
+            // periodRate = 0.0001 * 1 = 0.0001
+            // periodsPerYear = 8760/1 = 8760
+            // (1 + 0.0001)^8760 - 1
+            const result = getCompoundedAnnualReturn(0.0001, 1);
+            expect(result).toBeCloseTo(Math.pow(1.0001, 8760) - 1, 2);
+        });
+        it("returns 0 for zero rate", () => {
+            expect(getCompoundedAnnualReturn(0, 1)).toBe(0);
+        });
+        it("handles negative rates", () => {
+            const result = getCompoundedAnnualReturn(-0.0001, 1);
+            // (1 - 0.0001)^8760 - 1 should be negative
+            expect(result).toBeLessThan(0);
+            expect(result).toBeCloseTo(Math.pow(1 - 0.0001, 8760) - 1, 2);
+        });
+        it("all exchanges compound at the same frequency (1h)", () => {
+            const hourlyRate = 0.0001;
+            const hl = getCompoundedAnnualReturn(hourlyRate, 1); // compound every 1h
+            const pac = getCompoundedAnnualReturn(hourlyRate, 1); // compound every 1h (same as HL)
+            // Same compounding frequency, same effective annual return
+            expect(hl).toBeCloseTo(pac, 10);
+        });
+        it("simple rate sanity check: small rate, compounded vs simple", () => {
+            const hourlyRate = 0.0001;
+            const simpleAnnual = hourlyRate * 8760; // 0.876
+            const compoundedAnnual = getCompoundedAnnualReturn(hourlyRate, 1);
+            // Compounded should always be greater than simple for positive rates
+            expect(compoundedAnnual).toBeGreaterThan(simpleAnnual);
+        });
+    });
+    // ──────────────────────────────────────────────
+    // getExchangeCompoundingHours
+    // ──────────────────────────────────────────────
+    describe("getExchangeCompoundingHours", () => {
+        it("returns 1 for hyperliquid", () => {
+            expect(getExchangeCompoundingHours("hyperliquid")).toBe(1);
+        });
+        it("returns 1 for pacifica", () => {
+            expect(getExchangeCompoundingHours("pacifica")).toBe(1);
+        });
+        it("returns 1 for lighter", () => {
+            expect(getExchangeCompoundingHours("lighter")).toBe(1);
+        });
+        it("returns 1 for unknown exchanges", () => {
+            expect(getExchangeCompoundingHours("binance")).toBe(1);
+        });
+    });
+});