perp-cli 0.12.17 → 0.14.0

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

package/dist/bot/engine.d.ts

@@ -1,5 +1,8 @@
 import type { ExchangeAdapter } from "../exchanges/index.js";
+import { filledOf } from "./fill-size.js";
 import type { BotConfig } from "./config.js";
+import type { StrategyAction } from "./strategy-types.js";
+import { type QuoteRules } from "./quote-rules.js";
 import "./strategies/grid-strategy.js";
 import "./strategies/dca-strategy.js";
 import "./strategies/funding-arb-strategy.js";
@@ -22,9 +25,65 @@ import "./strategies/funding-auto.js";
 import "./strategies/spot-perp-arb-strategy.js";
 export type BotLog = (msg: string) => void;
 export type BotOutputMode = "tui" | "json" | "headless";
-export declare function runBot(adapter: ExchangeAdapter, config: BotConfig, jobId?: string, log?: BotLog, extraAdapters?: Map<string, ExchangeAdapter>, // for funding-arb (multi-exchange)
-mode?: BotOutputMode): Promise<{
+/**
+ * Strategies that place/close orders themselves (multi-leg executors, spot legs) instead of
+ * returning StrategyActions — the engine cannot simulate them, so --dry-run is refused.
+ */
+export declare const NON_SIMULATABLE_STRATEGIES: ReadonlySet<string>;
+/**
+ * ExchangeAdapter methods a --dry-run bot may call: pure reads (plus resolveSymbol, a local
+ * lookup). Allowlist, not blocklist (review L4): any other method — every venue write, and any
+ * write added to an adapter later — throws, so a dry-run can never reach the venue's write path.
+ */
+export declare const ADAPTER_READ_METHODS: ReadonlySet<string>;
+/** Throw INVALID_PARAMS if `strategyType` cannot run under --dry-run (checked before any adapter call). */
+export declare function assertStrategySimulatable(strategyType: string): void;
+/** Wrap an adapter so only allowlisted reads run; every other method throws (defense in depth for --dry-run bots). */
+export declare function dryRunAdapter(adapter: ExchangeAdapter): ExchangeAdapter;
+export declare function runBot(adapter: ExchangeAdapter, config: BotConfig, jobId: string | undefined, log: BotLog, extraAdapters: Map<string, ExchangeAdapter> | undefined, // for funding-arb (multi-exchange)
+mode: BotOutputMode, 
+/** Global --dry-run: strategy actions are logged, never sent; non-simulatable strategies are refused. */
+isDryRun: boolean): Promise<{
     fills: number;
+    ordersPlaced: number;
     totalPnl: number;
     runtime: number;
 }>;
+/** Consecutive ticks with unknown equity after which the bot stops (an error, never a silent run). */
+export declare const UNKNOWN_EQUITY_STOP_TICKS = 10;
+/** Strategies that read the snapshot's orderbook / klines: a tick whose read failed is skipped. */
+export declare const MARKET_DATA_STRATEGIES: ReadonlySet<string>;
+/** Strategies that hold spot legs (spot-perp): their stop summary lists the spot holdings too. */
+export declare const SPOT_LEG_STRATEGIES: ReadonlySet<string>;
+/** A position left open at stop, with the command that closes it (a pair's legs share one command). */
+export interface OpenPositionAtStop {
+    exchange: string;
+    symbol: string;
+    side: string;
+    size: string;
+    close: string;
+}
+/**
+ * Open positions at stop (logged with the close command); a failed read is logged, never "none".
+ * `spotLegs` (a multi-venue spot-perp bot): the bot spot venues' holdings of the traded symbol(s)
+ * are listed too — a spot holding + a perp short of one symbol is closed as a pair
+ * (`arb close --spot-exch --perp-exch`), never the short alone (that leaves the spot unhedged).
+ */
+export declare function openPositionsAtStop(primary: ExchangeAdapter, symbol: string, extra: Map<string, ExchangeAdapter> | undefined, log: BotLog, spotLegs: boolean): Promise<OpenPositionAtStop[]>;
+/**
+ * Send strategy actions. Orders go out on the venue grid (quote-rules.ts): limit prices aligned
+ * passively to the tick (bid ↓, ask ↑), sizes floored to the lot, venue minimums refused before
+ * sending. `refPrice` = the tick's snapshot price (minimum order value of market orders).
+ * One order under the venue minimum (e.g. the inventory-skewed side of a market maker) is
+ * skipped for this tick with a log line — the other orders still go out; when EVERY order of
+ * the batch is under the minimum the last SIZE_TOO_SMALL is thrown (the tick fails: the
+ * strategy's base size itself is too small).
+ * Returns the orders sent (`placed`) and those the venue reported as (partly) filled (`filled`,
+ * filledOf) — an accepted resting limit order is a placement, not a fill. Under --dry-run every
+ * place_order is a simulated placement and nothing fills.
+ */
+export declare function executeActions(adapter: ExchangeAdapter, symbol: string, actions: StrategyAction[], log: BotLog, dryRun: boolean, rulesOf: () => Promise<QuoteRules>, refPrice: number): Promise<{
+    placed: number;
+    filled: number;
+}>;
+export { filledOf };