perp-cli 0.12.15 → 0.14.0

package/dist/arb/state.js

@@ -1,8 +1,28 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "fs";
+import { copyFileSync, constants as fsConstants, existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "fs";
 import { resolve } from "path";
+import { PerpError } from "../errors.js";
+import { withFileLock } from "./file-lock.js";
+/**
+ * Arb daemon state is PER NETWORK (review N2): a testnet run must never read, close, or
+ * overwrite mainnet positions, and vice versa.
+ *
+ *   mainnet → ~/.perp/arb-state.json          (the pre-network path, unchanged)
+ *   testnet → ~/.perp/arb-state.testnet.json
+ *
+ * Every saved file carries `network`; a load whose tag does not match the requested
+ * network throws. Files written before this change have no tag. They are MAINNET by
+ * definition (mainnet was — and is — the documented default network, and the mainnet
+ * path is unchanged), so a mainnet load adopts an untagged file and tags it in place
+ * (atomic tmp+rename, after a one-time backup copy `arb-state.json.pre-network.bak`).
+ * The history does NOT prove an untagged file could only come from mainnet (`-n testnet`
+ * routed `arb exec/auto` to testnet adapters since 2026-03 and they wrote the same file),
+ * so a TESTNET load refuses while an untagged legacy file exists — the user decides
+ * (adopt as mainnet, or move it to the testnet path). Nothing is ever dropped or copied
+ * into both networks.
+ */
 const PERP_DIR = resolve(process.env.HOME || "~", ".perp");
 const STATE_FILE = resolve(PERP_DIR, "arb-state.json");
-// Allow overriding the state file path for testing
+// Allow overriding the (mainnet) state file path for testing; testnet derives from it.
 let stateFilePath = STATE_FILE;
 export function setStateFilePath(path) {
     stateFilePath = path;
@@ -10,13 +30,73 @@ export function setStateFilePath(path) {
 export function resetStateFilePath() {
     stateFilePath = STATE_FILE;
 }
-function ensureDir() {
-    const dir = resolve(stateFilePath, "..");
+/** Absolute state-file path for `network` (mainnet = the pre-network path). */
+export function arbStateFilePath(network) {
+    if (network === "mainnet")
+        return stateFilePath;
+    return stateFilePath.endsWith(".json") ? `${stateFilePath.slice(0, -5)}.testnet.json` : `${stateFilePath}.testnet`;
+}
+function ensureDir(path) {
+    const dir = resolve(path, "..");
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true, mode: 0o700 });
 }
-/** Load daemon state from disk. Falls back to .tmp if main file is corrupted. */
-export function loadArbState() {
+/** Parse a state file's tag without the .tmp recovery (used for the legacy-file guard). */
+function readTag(path) {
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (e) {
+        throw new PerpError("INVALID_PARAMS", `Arb state ${path} is not valid JSON (${e instanceof Error ? e.message : String(e)}) — refusing to guess its network`, {
+            remediation: `Inspect or restore ${path} (a .tmp / .pre-network.bak copy may exist next to it)`,
+        });
+    }
+    return { untagged: parsed.network === undefined };
+}
+/** Load the daemon state for `network`. Falls back to .tmp if main file is corrupted. */
+export function loadArbState(network, opts = { readOnly: false }) {
+    if (network === "testnet") {
+        const legacy = readTag(arbStateFilePath("mainnet"));
+        if (legacy?.untagged) {
+            const main = arbStateFilePath("mainnet");
+            throw new PerpError("INVALID_PARAMS", `Untagged arb state ${main} (written before per-network state) exists — refusing to guess its network on testnet`, {
+                remediation: `If it holds MAINNET positions (the default network), adopt it once with any mainnet arb read: perp -n mainnet arb status. `
+                    + `If it holds TESTNET positions, move it: mv ${main} ${arbStateFilePath("testnet")}`,
+            });
+        }
+    }
+    const state = loadArbStateFile(arbStateFilePath(network));
+    if (state === null)
+        return null;
+    if (state.network === undefined) {
+        // Only reachable for mainnet (testnet refused above / its path never held untagged data).
+        // A read-only (dry-run) load tags the copy in memory and leaves the file untouched.
+        if (opts.readOnly)
+            state.network = "mainnet";
+        else
+            adoptLegacyAsMainnet(state);
+        return state;
+    }
+    if (state.network !== network) {
+        throw new PerpError("INVALID_PARAMS", `Arb state ${arbStateFilePath(network)} is tagged ${state.network}, not ${network}`, {
+            remediation: `The file was moved or edited by hand. Restore it to ${arbStateFilePath(state.network)}`,
+        });
+    }
+    return state;
+}
+/** One-time adoption of a pre-network (untagged) state file as mainnet: backup copy, then atomic in-place tag. */
+function adoptLegacyAsMainnet(state) {
+    const path = arbStateFilePath("mainnet");
+    const backup = `${path}.pre-network.bak`;
+    if (!existsSync(backup))
+        copyFileSync(path, backup, fsConstants.COPYFILE_EXCL);
+    state.network = "mainnet";
+    writeStateAtomic(path, state);
+}
+function loadArbStateFile(stateFilePath) {
     const tmpPath = stateFilePath + ".tmp";
     // Try main file first
     if (existsSync(stateFilePath)) {
@@ -55,47 +135,110 @@ export function loadArbState() {
  * Writes to .tmp first, then renames to main file.
  * If crash occurs mid-write, .tmp is partial but main file is intact.
  */
-export function saveArbState(state) {
-    ensureDir();
-    const tmpPath = stateFilePath + ".tmp";
+export function saveArbState(network, state) {
+    if (state.network !== undefined && state.network !== network) {
+        throw new PerpError("INVALID_PARAMS", `Refusing to save ${state.network} arb state as ${network}`, {
+            remediation: "This is a bug — the state object was loaded for another network. Re-run the command.",
+        });
+    }
+    // Same network on the -n testnet path: never let a testnet save land while an untagged legacy file is unresolved.
+    if (network === "testnet")
+        loadArbState("testnet");
+    writeStateAtomic(arbStateFilePath(network), { ...state, network });
+}
+function writeStateAtomic(path, state) {
+    ensureDir(path);
+    const tmpPath = path + ".tmp";
     const json = JSON.stringify(state, null, 2);
     writeFileSync(tmpPath, json, { mode: 0o600 });
-    renameSync(tmpPath, stateFilePath);
-}
-/** Add a position to the persisted state. Auto-initializes state if missing. */
-export function addPosition(pos) {
-    let state = loadArbState();
-    if (!state) {
-        // State was lost — create minimal valid state to avoid losing position tracking
-        state = createInitialState({ minSpread: 0, closeSpread: 0, size: 0, holdDays: 0, bridgeCost: 0, maxPositions: 10, settleStrategy: "off" });
+    renameSync(tmpPath, path);
+}
+/** Identity of a state entry: symbol + long venue + short venue + mode (absent mode = perp-perp). */
+export function positionKey(p) {
+    return `${p.symbol.toUpperCase()}|${p.longExchange}|${p.shortExchange}|${p.mode ?? "perp-perp"}`;
+}
+/**
+ * Put `pos` into `positions`: an entry with the same key is replaced (a re-record of the same
+ * pair); an entry of the same symbol on OTHER venues / another mode is never overwritten —
+ * RISK_VIOLATION (the state tracks one pair per symbol; overwriting would drop a live pair).
+ */
+export function upsertPosition(positions, pos) {
+    const key = positionKey(pos);
+    const other = positions.find(p => p.symbol.toUpperCase() === pos.symbol.toUpperCase() && positionKey(p) !== key);
+    if (other !== undefined) {
+        throw new PerpError("RISK_VIOLATION", `Arb state already tracks ${other.symbol} as ${other.mode ?? "perp-perp"} long ${other.longExchange} / short ${other.shortExchange} — refusing to overwrite it with ${pos.mode ?? "perp-perp"} long ${pos.longExchange} / short ${pos.shortExchange}`, {
+            remediation: `Both pairs may be open: check ${pos.symbol} on ${[...new Set([other.longExchange, other.shortExchange, pos.longExchange, pos.shortExchange])].join(", ")} (perp arb status), close one by hand, then record / drop it (perp arb close ${pos.symbol} --state-only)`,
+        });
     }
-    // Avoid duplicates by symbol
-    state.positions = state.positions.filter(p => p.symbol !== pos.symbol);
-    state.positions.push(pos);
-    saveArbState(state);
-}
-/** Remove a position by symbol from the persisted state. */
-export function removePosition(symbol) {
-    const state = loadArbState();
-    if (!state)
-        return;
-    state.positions = state.positions.filter(p => p.symbol !== symbol);
-    saveArbState(state);
+    return [...positions.filter(p => positionKey(p) !== key), pos];
+}
+/** Load → modify → save of the state for `network` under the cross-process lock. */
+function withStateLock(network, fn) {
+    return withFileLock(arbStateFilePath(network), `Arb state (${network})`, fn);
+}
+/** Add a position to the persisted state for `network`. Auto-initializes state if missing. Throws RISK_VIOLATION for a conflicting entry (upsertPosition). */
+export function addPosition(network, pos) {
+    withStateLock(network, () => {
+        let state = loadArbState(network);
+        if (!state) {
+            // State was lost — create minimal valid state to avoid losing position tracking
+            state = createInitialState({ minSpread: 0, closeSpread: 0, size: 0, holdDays: 0, bridgeCost: 0, maxPositions: 10, settleStrategy: "off" });
+        }
+        state.positions = upsertPosition(state.positions, pos);
+        saveArbState(network, state);
+    });
+}
+/** Remove a position by symbol from the persisted state for `network` (one entry per symbol: upsertPosition). */
+export function removePosition(network, symbol) {
+    withStateLock(network, () => {
+        const state = loadArbState(network);
+        if (!state)
+            return;
+        state.positions = state.positions.filter(p => p.symbol !== symbol);
+        saveArbState(network, state);
+    });
+}
+/** Remove exactly the entry with `entry`'s key (symbol + venues + mode); another pair of the symbol is left alone. */
+export function removePositionEntry(network, entry) {
+    withStateLock(network, () => {
+        const state = loadArbState(network);
+        if (!state)
+            return;
+        const key = positionKey(entry);
+        state.positions = state.positions.filter(p => positionKey(p) !== key);
+        saveArbState(network, state);
+    });
 }
 /** Update a position by symbol with partial updates. */
-export function updatePosition(symbol, updates) {
-    const state = loadArbState();
-    if (!state)
-        return;
-    const idx = state.positions.findIndex(p => p.symbol === symbol);
-    if (idx === -1)
-        return;
-    state.positions[idx] = { ...state.positions[idx], ...updates };
-    saveArbState(state);
-}
-/** Get all persisted positions. */
-export function getPositions() {
-    const state = loadArbState();
+export function updatePosition(network, symbol, updates) {
+    withStateLock(network, () => {
+        const state = loadArbState(network);
+        if (!state)
+            return;
+        const idx = state.positions.findIndex(p => p.symbol === symbol);
+        if (idx === -1)
+            return;
+        state.positions[idx] = { ...state.positions[idx], ...updates };
+        saveArbState(network, state);
+    });
+}
+/** Update exactly the entry with `entry`'s key (symbol + venues + mode). */
+export function updatePositionEntry(network, entry, updates) {
+    withStateLock(network, () => {
+        const state = loadArbState(network);
+        if (!state)
+            return;
+        const key = positionKey(entry);
+        const idx = state.positions.findIndex(p => positionKey(p) === key);
+        if (idx === -1)
+            return;
+        state.positions[idx] = { ...state.positions[idx], ...updates };
+        saveArbState(network, state);
+    });
+}
+/** Get all persisted positions for `network`. */
+export function getPositions(network) {
+    const state = loadArbState(network);
     if (!state)
         return [];
     return state.positions;
@@ -111,3 +254,32 @@ export function createInitialState(config) {
         config,
     };
 }
+/**
+ * Live: the per-network state file. Dry-run (review N3): an in-memory copy seeded READ-ONLY
+ * from the real state — nothing is ever written to disk, so a simulated entry is never picked
+ * up by a live run and a simulated close never drops a real position from tracking.
+ */
+export function createDaemonStateStore(network, dryRun, config) {
+    if (!dryRun) {
+        return {
+            load: () => loadArbState(network),
+            save: (next) => saveArbState(network, next),
+            add: (pos) => addPosition(network, pos),
+            remove: (symbol) => removePosition(network, symbol),
+        };
+    }
+    let sim = structuredClone(loadArbState(network, { readOnly: true }));
+    return {
+        load: () => structuredClone(sim),
+        save: (next) => { sim = structuredClone(next); },
+        add: (pos) => {
+            const next = sim ?? createInitialState(config);
+            next.positions = upsertPosition(next.positions, structuredClone(pos));
+            sim = next;
+        },
+        remove: (symbol) => {
+            if (sim !== null)
+                sim.positions = sim.positions.filter(p => p.symbol !== symbol);
+        },
+    };
+}

package/dist/arb/utils.d.ts

@@ -1,24 +1,38 @@
 /**
  * Arb utilities: settlement timing strategy, basis risk monitoring, and webhook notifications.
  */
-/** Settlement schedules per exchange (UTC hours when settlement occurs) */
+/**
+ * Settlement schedules per venue (UTC hours when settlement occurs), generated
+ * from `VenueDefinition.settlementIntervalHours`, anchored at 00:00 UTC
+ * (design §10.1, §10.13 #1). Venues whose interval is per-market (Aster)
+ * have no entry — pass the market's interval to getLastSettlement().
+ */
 export declare const SETTLEMENT_SCHEDULES: Record<string, number[]>;
 export type SettleStrategy = "block" | "aggressive" | "off";
 /**
- * Get the most recent settlement time for an exchange.
- * @returns Date of the most recent past settlement
+ * Settlement interval in hours for a venue ref. `marketIntervalHours` (the
+ * market's `settlementIntervalHours`) takes precedence; it is required for
+ * per-market venues. Unknown venues throw UNKNOWN_VENUE.
+ */
+export declare function settlementIntervalHours(exchange: string, marketIntervalHours?: number | null): number;
+/**
+ * Get the most recent settlement time for an exchange (anchored at 00:00 UTC).
+ * @param marketIntervalHours market settlement interval; required for per-market venues
+ * @returns Date of the most recent past settlement (== now when exactly on a settlement)
  */
-export declare function getLastSettlement(exchange: string, now?: Date): Date;
+export declare function getLastSettlement(exchange: string, now?: Date, marketIntervalHours?: number | null): Date;
 /**
  * Get minutes since the most recent settlement for an exchange.
  */
-export declare function getMinutesSinceSettlement(exchange: string, now?: Date): number;
+export declare function getMinutesSinceSettlement(exchange: string, now?: Date, marketIntervalHours?: number | null): number;
 /**
  * Compute a score boost for aggressive settlement mode.
  * Returns a multiplier > 1.0 if within the post-settlement window, else 1.0.
  * The boost decays linearly from 1.5x (right after settlement) to 1.0x (at windowMinutes).
+ * `marketIntervalFor` returns the market's settlement interval per exchange;
+ * it must return a number for per-market venues (Aster).
  */
-export declare function aggressiveSettleBoost(longExchange: string, shortExchange: string, windowMinutes?: number, now?: Date): number;
+export declare function aggressiveSettleBoost(longExchange: string, shortExchange: string, windowMinutes?: number, now?: Date, marketIntervalFor?: (exchange: string) => number | null): number;
 /**
  * Estimate cumulative funding between now and the next settlement.
  *

package/dist/arb/utils.js

@@ -1,62 +1,66 @@
 /**
  * Arb utilities: settlement timing strategy, basis risk monitoring, and webhook notifications.
  */
+import { PerpError } from "../errors.js";
+import { listVenues, settlementIntervalOf } from "../exchanges/venue.js";
+import { ensureVenuesRegistered } from "../exchanges/venues/index.js";
 // ── Settlement Timing Strategy ──
-/** Settlement schedules per exchange (UTC hours when settlement occurs) */
-export const SETTLEMENT_SCHEDULES = {
-    hyperliquid: Array.from({ length: 24 }, (_, i) => i), // every hour
-    pacifica: Array.from({ length: 24 }, (_, i) => i), // every hour
-    lighter: Array.from({ length: 24 }, (_, i) => i), // every hour
-    aster: [0, 8, 16], // every 8 hours (Binance convention)
-};
+ensureVenuesRegistered();
 /**
- * Get the most recent settlement time for an exchange.
- * @returns Date of the most recent past settlement
+ * Settlement schedules per venue (UTC hours when settlement occurs), generated
+ * from `VenueDefinition.settlementIntervalHours`, anchored at 00:00 UTC
+ * (design §10.1, §10.13 #1). Venues whose interval is per-market (Aster)
+ * have no entry — pass the market's interval to getLastSettlement().
  */
-export function getLastSettlement(exchange, now = new Date()) {
-    const schedule = SETTLEMENT_SCHEDULES[exchange.toLowerCase()];
-    if (!schedule || schedule.length === 0) {
-        return getLastSettlement("pacifica", now);
+export const SETTLEMENT_SCHEDULES = Object.fromEntries(listVenues()
+    .filter(v => v.settlementIntervalHours !== "perMarket")
+    .map(v => [v.id, scheduleFor(v.settlementIntervalHours)]));
+function scheduleFor(intervalHours) {
+    if (!(intervalHours > 0) || 24 % intervalHours !== 0) {
+        throw new PerpError("INVALID_PARAMS", `Settlement interval ${intervalHours}h does not divide a UTC day`);
     }
-    const currentHour = now.getUTCHours();
-    const currentMinutes = now.getUTCMinutes();
-    const currentSeconds = now.getUTCSeconds();
-    // Find the most recent settlement hour at or before now
-    for (let i = schedule.length - 1; i >= 0; i--) {
-        const hour = schedule[i];
-        if (hour < currentHour || (hour === currentHour && (currentMinutes > 0 || currentSeconds > 0))) {
-            const last = new Date(now);
-            last.setUTCHours(hour, 0, 0, 0);
-            return last;
-        }
-        // Exactly at settlement time
-        if (hour === currentHour && currentMinutes === 0 && currentSeconds === 0) {
-            const last = new Date(now);
-            last.setUTCHours(hour, 0, 0, 0);
-            return last;
+    return Array.from({ length: 24 / intervalHours }, (_, i) => i * intervalHours);
+}
+/**
+ * Settlement interval in hours for a venue ref. `marketIntervalHours` (the
+ * market's `settlementIntervalHours`) takes precedence; it is required for
+ * per-market venues. Unknown venues throw UNKNOWN_VENUE.
+ */
+export function settlementIntervalHours(exchange, marketIntervalHours = null) {
+    if (marketIntervalHours !== null) {
+        if (!(marketIntervalHours > 0)) {
+            throw new PerpError("INVALID_PARAMS", `Invalid settlement interval ${marketIntervalHours}h for ${exchange}`);
         }
+        return marketIntervalHours;
     }
-    // Wrap to previous day's last settlement
-    const last = new Date(now);
-    last.setUTCDate(last.getUTCDate() - 1);
-    last.setUTCHours(schedule[schedule.length - 1], 0, 0, 0);
-    return last;
+    return settlementIntervalOf(exchange);
+}
+/**
+ * Get the most recent settlement time for an exchange (anchored at 00:00 UTC).
+ * @param marketIntervalHours market settlement interval; required for per-market venues
+ * @returns Date of the most recent past settlement (== now when exactly on a settlement)
+ */
+export function getLastSettlement(exchange, now = new Date(), marketIntervalHours = null) {
+    const intervalMs = settlementIntervalHours(exchange, marketIntervalHours) * 3_600_000;
+    return new Date(Math.floor(now.getTime() / intervalMs) * intervalMs);
 }
 /**
  * Get minutes since the most recent settlement for an exchange.
  */
-export function getMinutesSinceSettlement(exchange, now = new Date()) {
-    const lastSettle = getLastSettlement(exchange, now);
+export function getMinutesSinceSettlement(exchange, now = new Date(), marketIntervalHours = null) {
+    const lastSettle = getLastSettlement(exchange, now, marketIntervalHours);
     return (now.getTime() - lastSettle.getTime()) / (1000 * 60);
 }
 /**
  * Compute a score boost for aggressive settlement mode.
  * Returns a multiplier > 1.0 if within the post-settlement window, else 1.0.
  * The boost decays linearly from 1.5x (right after settlement) to 1.0x (at windowMinutes).
+ * `marketIntervalFor` returns the market's settlement interval per exchange;
+ * it must return a number for per-market venues (Aster).
  */
-export function aggressiveSettleBoost(longExchange, shortExchange, windowMinutes = 10, now = new Date()) {
-    const longMinutes = getMinutesSinceSettlement(longExchange, now);
-    const shortMinutes = getMinutesSinceSettlement(shortExchange, now);
+export function aggressiveSettleBoost(longExchange, shortExchange, windowMinutes = 10, now = new Date(), marketIntervalFor = () => null) {
+    const longMinutes = getMinutesSinceSettlement(longExchange, now, marketIntervalFor(longExchange));
+    const shortMinutes = getMinutesSinceSettlement(shortExchange, now, marketIntervalFor(shortExchange));
     // Use the minimum of the two — we want BOTH exchanges to have recently settled
     const minMinutes = Math.min(longMinutes, shortMinutes);
     if (minMinutes <= windowMinutes) {

package/dist/bot/conditions.d.ts

@@ -19,14 +19,14 @@ export interface MarketSnapshot {
 export declare function calculateRSI(closes: number[], period?: number): number;
 export declare function getMarketSnapshot(adapter: ExchangeAdapter, symbol: string): Promise<MarketSnapshot>;
 export declare function evaluateCondition(condition: Condition, snapshot: MarketSnapshot, context: {
-    equity: number;
+    equity: number | null;
     startTime: number;
-    peakEquity: number;
+    peakEquity: number | null;
     dailyPnl: number;
 }): boolean;
 export declare function evaluateAllConditions(conditions: Condition[], snapshot: MarketSnapshot, context: {
-    equity: number;
+    equity: number | null;
     startTime: number;
-    peakEquity: number;
+    peakEquity: number | null;
     dailyPnl: number;
 }, mode?: "all" | "any"): boolean;

package/dist/bot/conditions.js

@@ -1,3 +1,4 @@
+import { symbolMatch } from "../utils.js";
 // ── RSI Calculation (Wilder smoothing) ──
 /**
  * Calculate RSI from an array of closing prices using Wilder's smoothing method.
@@ -39,13 +40,16 @@ export function calculateRSI(closes, period = 14) {
 }
 export async function getMarketSnapshot(adapter, symbol) {
     const markets = await adapter.getMarkets();
-    const m = markets.find(mk => mk.symbol.toUpperCase() === symbol.toUpperCase());
+    const m = markets.find(mk => symbolMatch(mk.symbol, symbol));
     if (!m) {
         throw new Error(`Market "${symbol}" not found on ${adapter.name}`);
     }
     const price = parseFloat(m.markPrice);
-    const fundingRate = parseFloat(m.fundingRate ?? "0");
-    const volume24h = parseFloat(m.volume24h);
+    // Unknown funding (venue publishes none, e.g. QFEX) → NaN, never 0: a 0 would satisfy
+    // "funding below X" conditions on a rate nobody reported. NaN makes every comparison false.
+    const fundingRate = m.fundingRate === null ? NaN : parseFloat(m.fundingRate);
+    // Unknown volume → NaN, never 0: a 0 would read as "no liquidity" to volume conditions.
+    const volume24h = m.volume24h === null ? NaN : parseFloat(m.volume24h);
     // Try to get kline data for 24h high/low + RSI
     let high24h = price;
     let low24h = price;
@@ -113,10 +117,11 @@ export function evaluateCondition(condition, snapshot, context) {
             return !isNaN(snapshot.rsi) && snapshot.rsi > val;
         case "rsi_below":
             return !isNaN(snapshot.rsi) && snapshot.rsi < val;
+        // Unknown equity (null) never meets an equity condition — neither a fake stop nor a fake entry.
         case "balance_above":
-            return context.equity > val;
+            return context.equity !== null && context.equity > val;
         case "balance_below":
-            return context.equity < val;
+            return context.equity !== null && context.equity < val;
         case "spread_above":
             // Bid-ask spread percentage, pre-computed from orderbook in snapshot.
             return snapshot.spreadPct > val;
@@ -125,7 +130,7 @@ export function evaluateCondition(condition, snapshot, context) {
             return elapsed > val;
         }
         case "max_drawdown":
-            return (context.peakEquity - context.equity) > val;
+            return context.equity !== null && context.peakEquity !== null && (context.peakEquity - context.equity) > val;
         default:
             return false;
     }

package/dist/bot/config.d.ts

@@ -1,3 +1,4 @@
+import { type VenueId } from "../exchanges/venue.js";
 export type ConditionType = "price_above" | "price_below" | "volatility_above" | "volatility_below" | "funding_rate_above" | "funding_rate_below" | "spread_above" | "rsi_above" | "rsi_below" | "balance_above" | "balance_below" | "time_after" | "max_drawdown" | "always";
 export interface Condition {
     type: ConditionType;
@@ -59,7 +60,22 @@ export interface BotConfig {
     risk: RiskConfig;
     monitor_interval_sec: number;
 }
-export declare function loadBotConfig(pathOrInline: string): BotConfig;
+/**
+ * The venue selected on the command line: the root `-e` value (resolved id) and whether it was
+ * given explicitly (commander option source "cli") or is the CLI default.
+ */
+export interface CliVenueSelection {
+    id: VenueId;
+    explicit: boolean;
+}
+/**
+ * The venue a config runs on. `config.exchange` (alias resolved; unknown → UNKNOWN_VENUE) wins
+ * over the CLI default; an explicit root `-e` naming a different venue is a contradiction →
+ * INVALID_PARAMS (never one of them silently). No `exchange` in the config → the CLI selection.
+ */
+export declare function resolveConfigVenue(configExchange: string | null, cli: CliVenueSelection): VenueId;
+/** Load a bot config; its venue is resolved against the CLI selection (resolveConfigVenue). */
+export declare function loadBotConfig(pathOrInline: string, cli: CliVenueSelection): BotConfig;
 export declare function parseStrategy(type: string, raw: Record<string, unknown>): StrategyParams;
 export declare function quickGridConfig(opts: {
     exchange: string;

package/dist/bot/config.js

@@ -1,5 +1,7 @@
 import { readFileSync, existsSync } from "node:fs";
 import { parse as parseYaml } from "yaml";
+import { PerpError, extractErrorMessage } from "../errors.js";
+import { resolveVenueId } from "../exchanges/venue.js";
 // ── Defaults ──
 const DEFAULT_RISK = {
     max_position_usd: 1000,
@@ -8,27 +10,61 @@ const DEFAULT_RISK = {
     pause_after_loss_sec: 300,
     max_open_bots: 5,
 };
-// ── Loader ──
-export function loadBotConfig(pathOrInline) {
+/**
+ * The venue a config runs on. `config.exchange` (alias resolved; unknown → UNKNOWN_VENUE) wins
+ * over the CLI default; an explicit root `-e` naming a different venue is a contradiction →
+ * INVALID_PARAMS (never one of them silently). No `exchange` in the config → the CLI selection.
+ */
+export function resolveConfigVenue(configExchange, cli) {
+    if (configExchange === null)
+        return cli.id;
+    const id = resolveVenueId(configExchange);
+    if (cli.explicit && cli.id !== id) {
+        throw new PerpError("INVALID_PARAMS", `The config runs on "${configExchange}" (${id}) but -e selects ${cli.id}`, {
+            remediation: `Drop -e, or pass -e ${id}, or change "exchange" in the config`,
+        });
+    }
+    return id;
+}
+/** Load a bot config; its venue is resolved against the CLI selection (resolveConfigVenue). */
+export function loadBotConfig(pathOrInline, cli) {
     let raw;
+    const remediation = "Pass a readable YAML/JSON config file path (or inline JSON). See examples with: perp strategy example";
     if (existsSync(pathOrInline)) {
-        const content = readFileSync(pathOrInline, "utf-8");
-        if (pathOrInline.endsWith(".json")) {
-            raw = JSON.parse(content);
+        let content;
+        try {
+            content = readFileSync(pathOrInline, "utf-8");
+        }
+        catch (err) {
+            throw new PerpError("INVALID_PARAMS", `Cannot read bot config file '${pathOrInline}': ${extractErrorMessage(err)}`, { remediation });
+        }
+        try {
+            raw = pathOrInline.endsWith(".json") ? JSON.parse(content) : parseYaml(content);
         }
-        else {
-            raw = parseYaml(content);
+        catch (err) {
+            throw new PerpError("INVALID_PARAMS", `Bot config file '${pathOrInline}' is not valid ${pathOrInline.endsWith(".json") ? "JSON" : "YAML"}: ${extractErrorMessage(err)}`, { remediation });
+        }
+    }
+    else if (pathOrInline.trimStart().startsWith("{")) {
+        // Inline JSON config
+        try {
+            raw = JSON.parse(pathOrInline);
+        }
+        catch (err) {
+            throw new PerpError("INVALID_PARAMS", `Inline bot config is not valid JSON: ${extractErrorMessage(err)}`, { remediation });
         }
     }
     else {
-        // Try parsing as inline JSON
-        raw = JSON.parse(pathOrInline);
+        throw new PerpError("INVALID_PARAMS", `Bot config file not found: '${pathOrInline}'`, { remediation });
     }
-    return parseBotConfig(raw);
+    return parseBotConfig(raw, cli);
 }
-function parseBotConfig(raw) {
+function parseBotConfig(raw, cli) {
     const name = String(raw.name ?? `bot-${Date.now()}`);
-    const exchange = String(raw.exchange ?? "hyperliquid");
+    if (raw.exchange !== undefined && (typeof raw.exchange !== "string" || raw.exchange.trim() === "")) {
+        throw new PerpError("INVALID_PARAMS", `Bot config "exchange" must be a venue name (got ${JSON.stringify(raw.exchange)})`);
+    }
+    const exchange = resolveConfigVenue(typeof raw.exchange === "string" ? raw.exchange : null, cli);
     const symbol = String(raw.symbol ?? "ETH");
     const monitorInterval = Number(raw.monitor_interval_sec ?? raw.interval ?? 30);
     // Strategy