perp-cli 0.12.15 → 0.14.0

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 };