perp-cli 0.14.3 → 0.15.0

package/dist/bot/engine.js

@@ -1,3 +1,4 @@
+import { getVenue, requireRole, tryResolveVenueId } from "../exchanges/venue.js";
 import { assertCanClosePositions } from "../exchanges/trading-v2.js";
 import { resolveAdapterSlippage } from "../exchanges/slippage.js";
 import { filledOf } from "./fill-size.js";
@@ -100,6 +101,12 @@ export async function runBot(adapter, config, jobId, log, extraAdapters, // for
 mode, 
 /** Global --dry-run: strategy actions are logged, never sent; non-simulatable strategies are refused. */
 isDryRun) {
+    // A venue without the trading role (TxFlow, release-gated RISEx) runs no bot — dry-run included.
+    for (const a of [adapter, ...(extraAdapters?.values() ?? [])]) {
+        const venueId = tryResolveVenueId(a.name);
+        if (venueId !== null)
+            requireRole(getVenue(venueId), "trading", "automation");
+    }
     if (isDryRun) {
         assertStrategySimulatable(config.strategy.type);
         adapter = dryRunAdapter(adapter);
@@ -192,7 +199,7 @@ isDryRun) {
     if (mode === "tui") {
         try {
             const { startDashboard } = await import("./tui/index.js");
-            const initialTuiState = buildTuiState(state, config, { price: 0, volatility24h: 0, fundingRate: 0, volume24h: 0 }, [], [], strategyCtx);
+            const initialTuiState = buildTuiState(state, config, { price: 0, volatility24h: 0, fundingRate: 0, volume24h: 0, openInterest: null }, [], [], strategyCtx);
             const result = startDashboard({
                 initialState: initialTuiState,
                 onQuit: () => { running = false; state.phase = "stopped"; },
@@ -883,14 +890,14 @@ export { filledOf };
  * read): the empty arrays in `snapshot` then are NOT data — the engine skips the tick of a
  * strategy that reads them (MARKET_DATA_STRATEGIES).
  */
-async function getEnrichedSnapshot(adapter, symbol, log) {
+export async function getEnrichedSnapshot(adapter, symbol, log) {
     // Multi-symbol strategies use "ALL" — skip market-specific data
     if (symbol.toUpperCase() === "ALL") {
         return {
             snapshot: {
                 price: 0, high24h: 0, low24h: 0, volume24h: 0,
                 fundingRate: 0, volatility24h: 0, rsi: NaN, spreadPct: 0,
-                klines: [], orderbook: { bids: [], asks: [] }, openInterest: "0",
+                klines: [], orderbook: { bids: [], asks: [] }, openInterest: null,
             },
             unknown: null,
         };
@@ -903,7 +910,8 @@ async function getEnrichedSnapshot(adapter, symbol, log) {
         adapter.getKlines(symbol, "1h", Date.now() - 24 * 60 * 60 * 1000, Date.now()).catch(why("klines")),
     ]);
     return {
-        snapshot: { ...base, klines: klines ?? [], orderbook: orderbook ?? { bids: [], asks: [] }, openInterest: "0" },
+        // Open interest is not read for the bot snapshot: null (unknown), never a "0" stand-in.
+        snapshot: { ...base, klines: klines ?? [], orderbook: orderbook ?? { bids: [], asks: [] }, openInterest: null },
         unknown: failed.length > 0 ? failed.join("; ") : null,
     };
 }
@@ -982,7 +990,7 @@ export async function fetchExchangeBalances(primaryAdapter, extraAdapters) {
 }
 const _spotPriceWarned = new Set();
 async function fetchSpotPositions(adapter) {
-    // Bot scope (§12.4 #3): only separate/runtime spot venues with transfer.
+    // Bot scope: only separate/runtime spot venues with transfer.
     const { getBotSpotAdapter, isSpotQuoteAsset, spotMarketsForValuation, spotNetworkOf, spotTokenBase } = await import("../exchanges/spot-factory.js");
     const { getVenue } = await import("../exchanges/venue.js");
     let raw;
@@ -1100,7 +1108,7 @@ function buildTuiState(state, config, snapshot, positions, openOrders, strategyC
         exchange: config.exchange,
         price: snapshot.price,
         volume24h: snapshot.volume24h ?? 0,
-        openInterest: snapshot.openInterest ?? "0",
+        openInterest: snapshot.openInterest,
         fundingRate: snapshot.fundingRate,
         volatility24h: snapshot.volatility24h,
         positions,

package/dist/bot/indicators.d.ts

@@ -7,6 +7,13 @@ export declare function calculateEMA(prices: number[], period: number): number[]
 /** Calculate Simple Moving Average */
 export declare function calculateSMA(prices: number[], period: number): number[];
 /** Calculate Volume Weighted Average Price */
+/**
+ * Candle volumes as numbers, or null when ANY candle's volume is unknown — null (the venue does
+ * not publish it) or not a finite number ("", "undefined", NaN). Never a 0 stand-in.
+ */
+export declare function klineVolumes(klines: ReadonlyArray<{
+    volume: string | null;
+}>): number[] | null;
 export declare function calculateVWAP(candles: {
     close: number;
     volume: number;

package/dist/bot/indicators.js

@@ -33,6 +33,22 @@ export function calculateSMA(prices, period) {
     return sma;
 }
 /** Calculate Volume Weighted Average Price */
+/**
+ * Candle volumes as numbers, or null when ANY candle's volume is unknown — null (the venue does
+ * not publish it) or not a finite number ("", "undefined", NaN). Never a 0 stand-in.
+ */
+export function klineVolumes(klines) {
+    const out = [];
+    for (const k of klines) {
+        if (k.volume === null || k.volume.trim() === "")
+            return null;
+        const v = Number(k.volume);
+        if (!Number.isFinite(v))
+            return null;
+        out.push(v);
+    }
+    return out;
+}
 export function calculateVWAP(candles) {
     let cumVolPrice = 0;
     let cumVol = 0;

package/dist/bot/perp-order.d.ts

@@ -1,5 +1,5 @@
 /**
- * Verified perp market order for bot / arb legs (design §12.3).
+ * Verified perp market order for bot / arb legs.
  *
  * A resolved `marketOrder()` promise does not prove a fill: Lighter returns success
  * when its /tx poll times out ("assuming executed") or the IOC filled nothing, and a
@@ -22,7 +22,7 @@
  *    Likewise a plain (non-transport, non-5xx) "not a multiple of lot size N" rejection with
  *    the position measured unchanged → ORDER_REJECTED with details.lotSize (rejectedLotSize()).
  *
- * Venue-final IOC outcome (design §13.10 #4): when the adapter is IocOutcomeCapable and
+ * Venue-final IOC outcome: when the adapter is IocOutcomeCapable and
  * iocOutcomeOf(raw) reports the order's FINAL filled size, that report is authoritative
  * (no 80% rule) once cross-checked against the measured position delta (tolerance one lot
  * step, taken from the precision of the order size / reported fill):
@@ -61,7 +61,7 @@ export declare function rejectedLotSize(e: unknown): number | null;
 /** true when `e` says the order outcome is unknown (quarantine, never retry / roll back blindly). */
 export declare function isOutcomeUnknown(e: unknown): boolean;
 /**
- * Second-leg residual correction (design §12.3): the second leg is sized to the first
+ * Second-leg residual correction: the second leg is sized to the first
  * leg's VERIFIED fill but may itself fill less (≥ 80% measured, or any venue-final partial fill). Reduce the first leg by exactly
  * this trade's excess (firstFilled − secondFilled, floored to `decimals`) — reduce-only,
  * verified, never the venue's whole position. `firstSide` is the side the first leg
@@ -79,7 +79,7 @@ export interface PerpCloseResult {
     note: string | null;
 }
 /**
- * Verified reduce-only close of `size` with residual handling (design §12.3, §13.10 #4). placePerpVerified
+ * Verified reduce-only close of `size` with residual handling. placePerpVerified
  * accepts a ≥ 80% measured fill or any venue-final partial IOC fill (cross-checked); a close must
  * not leave the rest silently open, so:
  *  1. reduce-only close of `size` (opts.place, e.g. a smartOrder IOC, or a market order);

package/dist/bot/perp-order.js

@@ -1,5 +1,5 @@
 /**
- * Verified perp market order for bot / arb legs (design §12.3).
+ * Verified perp market order for bot / arb legs.
  *
  * A resolved `marketOrder()` promise does not prove a fill: Lighter returns success
  * when its /tx poll times out ("assuming executed") or the IOC filled nothing, and a
@@ -22,7 +22,7 @@
  *    Likewise a plain (non-transport, non-5xx) "not a multiple of lot size N" rejection with
  *    the position measured unchanged → ORDER_REJECTED with details.lotSize (rejectedLotSize()).
  *
- * Venue-final IOC outcome (design §13.10 #4): when the adapter is IocOutcomeCapable and
+ * Venue-final IOC outcome: when the adapter is IocOutcomeCapable and
  * iocOutcomeOf(raw) reports the order's FINAL filled size, that report is authoritative
  * (no 80% rule) once cross-checked against the measured position delta (tolerance one lot
  * step, taken from the precision of the order size / reported fill):
@@ -158,7 +158,7 @@ export async function placePerpVerified(adapter, venue, symbol, side, size, opts
         }
         throw orderOutcomeUnknown(venue, what, e, `Do NOT resubmit — the order may still execute. Check the ${venue} ${symbol} position`);
     }
-    // Venue-final IOC outcome (§13.10 #4): the venue reported what this order filled; nothing more can fill.
+    // Venue-final IOC outcome: the venue reported what this order filled; nothing more can fill.
     const outcome = isIocOutcomeCapable(adapter) ? adapter.iocOutcomeOf(raw) : null;
     if (outcome !== null) {
         const reported = Number(outcome.filledSize);
@@ -226,7 +226,7 @@ export function isOutcomeUnknown(e) {
     return e instanceof PerpError && e.structured.code === "ORDER_PENDING";
 }
 /**
- * Second-leg residual correction (design §12.3): the second leg is sized to the first
+ * Second-leg residual correction: the second leg is sized to the first
  * leg's VERIFIED fill but may itself fill less (≥ 80% measured, or any venue-final partial fill). Reduce the first leg by exactly
  * this trade's excess (firstFilled − secondFilled, floored to `decimals`) — reduce-only,
  * verified, never the venue's whole position. `firstSide` is the side the first leg
@@ -245,7 +245,7 @@ export async function trimFirstLegToHedge(adapter, venue, symbol, firstSide, fir
     return excess;
 }
 /**
- * Verified reduce-only close of `size` with residual handling (design §12.3, §13.10 #4). placePerpVerified
+ * Verified reduce-only close of `size` with residual handling. placePerpVerified
  * accepts a ≥ 80% measured fill or any venue-final partial IOC fill (cross-checked); a close must
  * not leave the rest silently open, so:
  *  1. reduce-only close of `size` (opts.place, e.g. a smartOrder IOC, or a market order);

package/dist/bot/quarantine.d.ts

@@ -1,5 +1,5 @@
 /**
- * Position quarantine (design §12.3) — GLOBAL per symbol.
+ * Position quarantine — GLOBAL per symbol.
  *
  * A spot leg whose outcome is unknown (ORDER_PENDING), a perp leg that could not be
  * confirmed, a close whose post-trade verification failed, or a position left unhedged

package/dist/bot/quarantine.js

@@ -1,5 +1,5 @@
 /**
- * Position quarantine (design §12.3) — GLOBAL per symbol.
+ * Position quarantine — GLOBAL per symbol.
  *
  * A spot leg whose outcome is unknown (ORDER_PENDING), a perp leg that could not be
  * confirmed, a close whose post-trade verification failed, or a position left unhedged

package/dist/bot/strategies/apex-strategy.js

@@ -85,11 +85,12 @@ export class ApexStrategy {
             this.slots.splice(idx, 1);
         }
         // ── Phase 2: Record pulse history ──
-        const currentOi = parseFloat(snapshot.openInterest);
+        // Unknown OI (null) is not recorded: a fake 0 in the history would read as an OI jump later.
         const currentVolume = snapshot.volume24h;
         const historyKey = ctx.symbol;
         const existing = this.pulseHistory.get(historyKey) ?? [];
-        existing.push({ oi: currentOi, volume: currentVolume });
+        if (snapshot.openInterest !== null)
+            existing.push({ oi: parseFloat(snapshot.openInterest), volume: currentVolume });
         // Keep last 10 entries
         if (existing.length > 10)
             existing.shift();

package/dist/bot/strategies/engine-mm.js

@@ -1,5 +1,5 @@
 import { registerStrategy } from "../strategy-registry.js";
-import { calculateEMA, calculateVWAP, calculateATR } from "../indicators.js";
+import { calculateEMA, calculateVWAP, calculateATR, klineVolumes } from "../indicators.js";
 export class EngineMmStrategy {
     name = "engine-mm";
     describe() {
@@ -92,11 +92,12 @@ export class EngineMmStrategy {
         const components = [];
         // Mid-price (always available)
         components.push(snapshot.price);
-        // VWAP from klines
-        if (snapshot.klines.length > 0) {
-            const candles = snapshot.klines.map(k => ({
+        // VWAP from klines — only when every candle volume is known (unknown is never weighted as 0)
+        const volumes = klineVolumes(snapshot.klines);
+        if (snapshot.klines.length > 0 && volumes !== null) {
+            const candles = snapshot.klines.map((k, i) => ({
                 close: parseFloat(k.close),
-                volume: parseFloat(k.volume),
+                volume: volumes[i],
             }));
             const vwap = calculateVWAP(candles);
             if (vwap > 0)

package/dist/bot/strategies/funding-arb-strategy.js

@@ -549,7 +549,7 @@ export class FundingArbStrategy {
                 const perpRates = ratesByExchange.get(name);
                 if (!perpRates)
                     continue;
-                // Same-venue spot↔perp: canonical symbol + price-deviation guard (§12.4 #6).
+                // Same-venue spot↔perp: canonical symbol + price-deviation guard.
                 const spotMarkets = await spotAdapter.getSpotMarkets();
                 const matched = await botSpotPerpMatches(name, spotMarkets, [name], perpMarketsCache, (msg) => ctx.log(`  [ARB] ${msg}`));
                 const spotSymbols = matched.get(name);
@@ -1099,7 +1099,7 @@ export class FundingArbStrategy {
             const transferAmt = Math.ceil(matched.notional * 1.02); // slight buffer for price movement
             if (await transferUsdcToSpot(spotAdapter, transferAmt))
                 ctx.log(`  [ARB] Transferred $${transferAmt} to spot`);
-            // Step 2: Buy spot — the hedge is sized to what actually filled (§12.4 #5).
+            // Step 2: Buy spot — the hedge is sized to what actually filled.
             let hedgeSize;
             let spotFill;
             try {

package/dist/bot/strategies/funding-arb-utils.d.ts

@@ -8,7 +8,7 @@ import type { SpotAdapter, SpotMarketInfo } from "../../exchanges/spot-interface
 import type { VenueMarket } from "../../exchanges/venue-types.js";
 import "../../exchanges/venues/index.js";
 /**
- * Funding strategies refuse a venue whose funding rate is unverified as a leg (design §14.12
+ * Funding strategies refuse a venue whose funding rate is unverified as a leg (
  * #6): every adapter of the run (primary + extraAdapters) is checked when the strategy starts.
  * Adapter names that are not registered venues (test doubles) are not venues and are skipped.
  */

package/dist/bot/strategies/funding-arb-utils.js

@@ -10,7 +10,7 @@ import { PerpError, extractErrorMessage } from "../../errors.js";
 import { assertFundingArbVenue, tryResolveVenueId } from "../../exchanges/venue.js";
 import "../../exchanges/venues/index.js";
 /**
- * Funding strategies refuse a venue whose funding rate is unverified as a leg (design §14.12
+ * Funding strategies refuse a venue whose funding rate is unverified as a leg (
  * #6): every adapter of the run (primary + extraAdapters) is checked when the strategy starts.
  * Adapter names that are not registered venues (test doubles) are not venues and are skipped.
  */
@@ -38,7 +38,7 @@ export function buildAdapterMap(ctx) {
     }
     return adapters;
 }
-// ── Transfer helpers (§12.4 #4) ──
+// ── Transfer helpers ──
 // Spot adapters come from the factory (src/exchanges/spot-factory.ts, getBotSpotAdapter).
 /**
  * Move the spot venue's quote asset (quoteAssets[0]) perp → spot. Returns false when
@@ -52,7 +52,7 @@ export async function transferUsdcToSpot(spotAdapter, amount) {
 export async function transferUsdcToPerp(spotAdapter, amount) {
     return transferQuoteToPerp(spotAdapter, amount);
 }
-// ── Spot ↔ perp matching (§12.4 #6) ──
+// ── Spot ↔ perp matching ──
 /**
  * Bot spot↔perp candidates: spot bases on `spotVenue` matched to each perp venue by
  * canonical symbol + price-deviation guard (`matchSpotPerp`). Bare-ticker equality is
@@ -172,7 +172,7 @@ function hasPerSymbolFundingHours(adapter) {
 /**
  * Funding basis (hours one quoted rate covers) for a market: the market's own
  * value when the venue publishes one per symbol, else the venue definition.
- * History timestamp spacing is settlement timing, never the basis (§10.13 #2).
+ * History timestamp spacing is settlement timing, never the basis.
  * @returns null when the venue publishes per-symbol values and this symbol has none
  */
 async function marketFundingHours(adapter, exchangeName, symbol) {
@@ -217,7 +217,7 @@ export async function scoreFunding(adapter, symbol, exchangeName, periods, cache
 export async function fetchRates(adapter, exchangeName) {
     const markets = await adapter.getMarkets();
     const withRates = markets.filter(m => m.fundingRate != null);
-    // fundingHours = basis (§10.13 #7): market value first, then the venue definition.
+    // fundingHours = basis: market value first, then the venue definition.
     // Per-symbol venues (Aster) load their whole table in one call; symbols it
     // does not list stay null and are skipped below.
     for (const m of withRates) {

package/dist/bot/strategies/funding-auto.js

@@ -5,7 +5,7 @@ import { closePerpVerified, isOutcomeUnknown, placePerpVerified, trimFirstLegToH
 import { fillSizeString, sizeDecimalsOf } from "../../exchanges/spot-result.js";
 import { PerpError } from "../../errors.js";
 import { assertFundingArbLegs } from "./funding-arb-utils.js";
-/** Market basis first (ExchangeMarketInfo.fundingHours), else the venue definition's basis (§10.1). */
+/** Market basis first (ExchangeMarketInfo.fundingHours), else the venue definition's basis. */
 function hourlyOf(info, exchange) {
     return info.fundingHours !== null ? info.rate / info.fundingHours : toHourlyRate(info.rate, exchange);
 }
@@ -177,7 +177,7 @@ class FundingAutoStrategy {
         const surviving = [];
         for (const pos of positions) {
             if (isQuarantined(pos.symbol, ctx.log)) {
-                // Unknown / unhedged outcome recorded by some bot or arb path: hands off (design §12.3).
+                // Unknown / unhedged outcome recorded by some bot or arb path: hands off.
                 surviving.push(pos);
                 continue;
             }

package/dist/bot/strategies/liquidation-mm.d.ts

@@ -19,6 +19,7 @@ export declare class LiquidationMmStrategy implements Strategy {
     };
     private get params();
     private _config;
+    private _oiUnknownLogged;
     init(ctx: StrategyContext, snapshot: EnrichedSnapshot): Promise<void>;
     onTick(ctx: StrategyContext, snapshot: EnrichedSnapshot): Promise<StrategyAction[]>;
     onStop(_ctx: StrategyContext): Promise<StrategyAction[]>;

package/dist/bot/strategies/liquidation-mm.js

@@ -17,9 +17,10 @@ export class LiquidationMmStrategy {
         return this._config;
     }
     _config = {};
+    _oiUnknownLogged = false;
     async init(ctx, snapshot) {
         this._config = ctx.config;
-        ctx.state.set("prevOi", parseFloat(snapshot.openInterest) || 0);
+        ctx.state.set("prevOi", snapshot.openInterest === null ? 0 : parseFloat(snapshot.openInterest) || 0);
         ctx.state.set("cascadeMode", false);
         ctx.state.set("cascadeTicks", 0);
         const p = this.params;
@@ -29,7 +30,12 @@ export class LiquidationMmStrategy {
         const params = this.params;
         const actions = [];
         actions.push({ type: "cancel_all" });
-        const currentOi = parseFloat(snapshot.openInterest) || 0;
+        // Unknown OI (null): cascade detection is off — said once per run, never computed on a fake 0.
+        if (snapshot.openInterest === null && !this._oiUnknownLogged) {
+            this._oiUnknownLogged = true;
+            ctx.log("  [LIQUIDATION-MM] open interest unknown — OI cascade detection is off");
+        }
+        const currentOi = snapshot.openInterest === null ? 0 : parseFloat(snapshot.openInterest) || 0;
         const prevOi = ctx.state.get("prevOi") ?? currentOi;
         let cascadeMode = ctx.state.get("cascadeMode") ?? false;
         let cascadeTicks = ctx.state.get("cascadeTicks") ?? 0;

package/dist/bot/strategies/momentum-breakout.d.ts

@@ -9,6 +9,7 @@ import type { Strategy, StrategyContext, StrategyAction, EnrichedSnapshot } from
 export declare class MomentumBreakoutStrategy implements Strategy {
     readonly name = "momentum-breakout";
     private _config;
+    private _noVolumeLogged;
     describe(): {
         description: string;
         params: ({

package/dist/bot/strategies/momentum-breakout.js

@@ -1,5 +1,5 @@
 import { registerStrategy } from "../strategy-registry.js";
-import { calculateATR, calculateSMA } from "../indicators.js";
+import { calculateATR, calculateSMA, klineVolumes } from "../indicators.js";
 /**
  * Momentum breakout strategy.
  * Entry: price breaks above N-period high (buy) or below N-period low (sell)
@@ -10,6 +10,7 @@ import { calculateATR, calculateSMA } from "../indicators.js";
 export class MomentumBreakoutStrategy {
     name = "momentum-breakout";
     _config = {};
+    _noVolumeLogged = false;
     describe() {
         return {
             description: "Momentum breakout with volume confirmation and ATR trailing stop",
@@ -42,7 +43,14 @@ export class MomentumBreakoutStrategy {
         const closes = klines.map(k => parseFloat(k.close));
         const highs = klines.map(k => parseFloat(k.high));
         const lows = klines.map(k => parseFloat(k.low));
-        const volumes = klines.map(k => parseFloat(k.volume));
+        // Unknown candle volume (null / non-numeric) cannot confirm a breakout: no entry, exits still run.
+        const known = klineVolumes(klines);
+        const volumeKnown = known !== null;
+        if (!volumeKnown && !this._noVolumeLogged) {
+            this._noVolumeLogged = true; // once per run, not every tick
+            ctx.log("  [BREAKOUT] no candle volume from the venue — volume confirmation unavailable, no new entries");
+        }
+        const volumes = known ?? klines.map(() => NaN);
         const price = snapshot.price;
         // Compute indicators
         const candles = klines.map(k => ({
@@ -61,7 +69,7 @@ export class MomentumBreakoutStrategy {
         const avgVolSma = calculateSMA(volumes, this.lookbackPeriod);
         const avgVolume = avgVolSma.length > 0 ? avgVolSma[avgVolSma.length - 1] : 0;
         const currentVolume = volumes[volumes.length - 1];
-        const volumeConfirmed = avgVolume > 0 && currentVolume > avgVolume * this.volumeMultiplier;
+        const volumeConfirmed = volumeKnown && avgVolume > 0 && currentVolume > avgVolume * this.volumeMultiplier;
         const position = ctx.state.get("position");
         // If no position, look for breakout entry
         if (!position) {

package/dist/bot/strategies/spot-perp-arb-strategy.js

@@ -285,7 +285,7 @@ export class SpotPerpArbStrategy {
             ctx.state.set("spaPositions", remaining);
             ctx.state.set("arbPositions", remaining.length);
         }
-        // ── Rotation check (only to perp venues that match the spot leg, §12.4 #6) ──
+        // ── Rotation check (only to perp venues that match the spot leg) ──
         const perpMarketsCache = new Map();
         const allowedBySpotVenue = new Map();
         const currentPositions = ctx.state.get("spaPositions");
@@ -375,7 +375,7 @@ export class SpotPerpArbStrategy {
                 const spotAdapter = await getBotSpotAdapter(spotExName, spotExAdapter);
                 if (!spotAdapter)
                     continue;
-                // Canonical symbol + price guard (§12.4 #6): base → perp venues it may hedge on.
+                // Canonical symbol + price guard: base → perp venues it may hedge on.
                 const allowedByBase = await this.spotPerpVenues(spotExName, await spotAdapter.getSpotMarkets(), adapters, perpMarketsCache, ctx);
                 for (const [base, allowed] of allowedByBase) {
                     // HL spot: skip tokens not in whitelist

package/dist/bot/strategies/spot-perp-executor.d.ts

@@ -26,7 +26,7 @@ export type ExecutionResult = {
 /**
  * closed = position fully closed; remainingSize = partially closed, this size is still open (hedged).
  * manual = the outcome is unknown / unverified or a leg is unhedged: the caller must quarantine
- * the position and never retry it automatically (design §12.3).
+ * the position and never retry it automatically.
  */
 export type CloseResult = {
     closed: true;

package/dist/bot/strategies/spot-perp-executor.js

@@ -140,7 +140,7 @@ export class SpotPerpExecutor {
                     await this.returnToPerp(spotAdapter, actualTransferred, spotExchange, log);
                 return { success: false, error: `pre-trade balance: ${msg}` };
             }
-            // Step 1: Buy spot — the hedge is sized to what actually filled (§12.4 #5)
+            // Step 1: Buy spot — the hedge is sized to what actually filled
             let fill;
             try {
                 fill = await spotMarketFill(spotAdapter, symbol, "buy", matched.size, spotStep);

package/dist/bot/strategy-types.d.ts

@@ -10,7 +10,8 @@ export interface EnrichedSnapshot extends MarketSnapshot {
         bids: [string, string][];
         asks: [string, string][];
     };
-    openInterest: string;
+    /** Base-asset open interest; null = not read / not published (never "0" as a stand-in). */
+    openInterest: string | null;
 }
 export type StrategyAction = {
     type: "place_order";

package/dist/bot/tui/BotDashboard.d.ts

@@ -28,7 +28,7 @@ export interface BotTuiState {
     exchange: string;
     price: number;
     volume24h: number;
-    openInterest: string;
+    openInterest: string | null;
     fundingRate: number;
     volatility24h: number;
     positions: Position[];

package/dist/bot/tui/BotDashboard.js

@@ -78,7 +78,7 @@ export function BotDashboard({ initialState, onQuit, onPause, subscribe }) {
     const askOrders = state.openOrders.filter((o) => o.side.toLowerCase() === "sell");
     const hasMultiExchange = (state.exchangeBalances?.length ?? 0) > 1;
     const isMultiSymbol = state.symbol.toUpperCase() === "ALL";
-    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { flexDirection: "row", justifyContent: "space-between", marginBottom: 1, children: [_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { bold: true, color: "cyan", children: [state.strategy, " | ", state.symbol, " | ", state.exchange] }), _jsxs(Text, { color: "gray", children: ["Runtime: ", formatDuration(state.runtime), " | Tick: ", state.tick] })] }), _jsx(Box, { children: _jsx(Text, { bold: true, color: phaseColor(state.phase), children: phaseIndicator(state.phase) }) })] }), isMultiSymbol ? (_jsxs(Box, { borderStyle: "single", borderColor: "gray", paddingX: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Text, { children: ["Exchanges: ", _jsx(Text, { bold: true, color: "white", children: state.exchangeBalances?.length ?? 1 })] }), _jsxs(Text, { color: "gray", children: ["Positions: ", _jsx(Text, { bold: true, color: state.positions.length > 0 ? "yellow" : "white", children: state.positions.length })] }), _jsxs(Text, { color: "gray", children: ["Total Equity: ", _jsx(Text, { bold: true, color: "white", children: usd(totalEquity) })] }), _jsxs(Text, { color: "gray", children: ["PnL: ", _jsxs(Text, { bold: true, color: state.totalPnl >= 0 ? "green" : "red", children: ["$", state.totalPnl.toFixed(2)] })] })] })) : (_jsxs(Box, { borderStyle: "single", borderColor: "gray", paddingX: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Text, { children: ["Price: ", _jsxs(Text, { bold: true, color: "white", children: ["$", state.price.toFixed(2)] })] }), _jsxs(Text, { color: "gray", children: ["Vol24h: ", _jsx(Text, { color: "white", children: Number.isFinite(state.volatility24h) ? `${state.volatility24h.toFixed(1)}%` : "unknown" })] }), _jsxs(Text, { color: "gray", children: ["FR: ", _jsxs(Text, { color: state.fundingRate >= 0 ? "green" : "red", children: [(state.fundingRate * 100).toFixed(4), "%"] })] }), _jsxs(Text, { color: "gray", children: ["OI: ", _jsx(Text, { color: "white", children: state.openInterest })] })] })), _jsxs(Box, { marginTop: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "cyan", bold: true, children: "Account" }), _jsxs(Text, { children: ["Equity: ", _jsx(Text, { bold: true, color: "white", children: usd(state.equity) }), _jsxs(Text, { color: "gray", children: [" (peak: ", usd(state.peakEquity), ")"] })] }), _jsxs(Text, { children: ["Daily P&L: ", _jsxs(Text, { bold: true, color: pnlColor(state.dailyPnl), children: ["$", state.dailyPnl.toFixed(2)] })] })] }), _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: " " }), _jsxs(Text, { children: ["Drawdown: ", _jsx(Text, { bold: true, color: drawdown === null ? "gray" : drawdown > 0 ? "red" : "green", children: drawdown === null ? "unknown" : `${usd(drawdown)} (${drawdownPct.toFixed(1)}%)` })] }), _jsxs(Text, { children: ["Orders: ", _jsx(Text, { bold: true, color: "white", children: state.ordersPlaced }), _jsx(Text, { color: "gray", children: " | Fills: " }), _jsx(Text, { bold: true, color: "white", children: state.fills }), _jsx(Text, { color: "gray", children: " | Total P&L: " }), _jsxs(Text, { bold: true, color: pnlColor(state.totalPnl), children: ["$", state.totalPnl.toFixed(2)] })] })] })] }), state.exchangeBalances && state.exchangeBalances.length > 1 && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: "cyan", bold: true, children: "Exchange Balances" }), _jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { color: "gray", children: pad("Exchange", 16) }), _jsx(Text, { color: "gray", children: pad("Equity", 14) }), _jsx(Text, { color: "gray", children: "Available" })] }), state.exchangeBalances.map((eb, i) => (_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { color: "white", children: pad(eb.exchange, 16) }), eb.equity === null ? (_jsxs(Text, { color: "red", children: ["unavailable", eb.error ? ` (${eb.error})` : ""] })) : (_jsxs(_Fragment, { children: [_jsx(Text, { color: "white", children: pad(`$${parseFloat(eb.equity).toFixed(2)}`, 14) }), _jsx(Text, { color: "gray", children: eb.available === null ? "unavailable" : `$${parseFloat(eb.available).toFixed(2)}` })] }))] }, i)))] })), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: "cyan", bold: true, children: "Positions" }), positionErrors.map((pe, i) => (_jsxs(Text, { color: "red", children: ["  ", pe.exchange, ": unavailable (", pe.error, ")"] }, `err-${i}`))), state.positions.length === 0 ? (positionErrors.length === 0 && _jsx(Text, { color: "gray", children: "  No open positions" })) : (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [hasMultiExchange && _jsx(Text, { color: "gray", children: pad("Exchange", 14) }), _jsx(Text, { color: "gray", children: pad("Symbol", 10) }), _jsx(Text, { color: "gray", children: pad("Side", 6) }), _jsx(Text, { color: "gray", children: pad("Size", 12) }), _jsx(Text, { color: "gray", children: pad("Entry", 12) }), _jsx(Text, { color: "gray", children: pad("Mark", 12) }), _jsx(Text, { color: "gray", children: "uPnL" })] }), state.positions.map((p, i) => {
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { flexDirection: "row", justifyContent: "space-between", marginBottom: 1, children: [_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { bold: true, color: "cyan", children: [state.strategy, " | ", state.symbol, " | ", state.exchange] }), _jsxs(Text, { color: "gray", children: ["Runtime: ", formatDuration(state.runtime), " | Tick: ", state.tick] })] }), _jsx(Box, { children: _jsx(Text, { bold: true, color: phaseColor(state.phase), children: phaseIndicator(state.phase) }) })] }), isMultiSymbol ? (_jsxs(Box, { borderStyle: "single", borderColor: "gray", paddingX: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Text, { children: ["Exchanges: ", _jsx(Text, { bold: true, color: "white", children: state.exchangeBalances?.length ?? 1 })] }), _jsxs(Text, { color: "gray", children: ["Positions: ", _jsx(Text, { bold: true, color: state.positions.length > 0 ? "yellow" : "white", children: state.positions.length })] }), _jsxs(Text, { color: "gray", children: ["Total Equity: ", _jsx(Text, { bold: true, color: "white", children: usd(totalEquity) })] }), _jsxs(Text, { color: "gray", children: ["PnL: ", _jsxs(Text, { bold: true, color: state.totalPnl >= 0 ? "green" : "red", children: ["$", state.totalPnl.toFixed(2)] })] })] })) : (_jsxs(Box, { borderStyle: "single", borderColor: "gray", paddingX: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Text, { children: ["Price: ", _jsxs(Text, { bold: true, color: "white", children: ["$", state.price.toFixed(2)] })] }), _jsxs(Text, { color: "gray", children: ["Vol24h: ", _jsx(Text, { color: "white", children: Number.isFinite(state.volatility24h) ? `${state.volatility24h.toFixed(1)}%` : "unknown" })] }), _jsxs(Text, { color: "gray", children: ["FR: ", _jsxs(Text, { color: state.fundingRate >= 0 ? "green" : "red", children: [(state.fundingRate * 100).toFixed(4), "%"] })] }), _jsxs(Text, { color: "gray", children: ["OI: ", _jsx(Text, { color: "white", children: state.openInterest ?? "-" })] })] })), _jsxs(Box, { marginTop: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "cyan", bold: true, children: "Account" }), _jsxs(Text, { children: ["Equity: ", _jsx(Text, { bold: true, color: "white", children: usd(state.equity) }), _jsxs(Text, { color: "gray", children: [" (peak: ", usd(state.peakEquity), ")"] })] }), _jsxs(Text, { children: ["Daily P&L: ", _jsxs(Text, { bold: true, color: pnlColor(state.dailyPnl), children: ["$", state.dailyPnl.toFixed(2)] })] })] }), _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: " " }), _jsxs(Text, { children: ["Drawdown: ", _jsx(Text, { bold: true, color: drawdown === null ? "gray" : drawdown > 0 ? "red" : "green", children: drawdown === null ? "unknown" : `${usd(drawdown)} (${drawdownPct.toFixed(1)}%)` })] }), _jsxs(Text, { children: ["Orders: ", _jsx(Text, { bold: true, color: "white", children: state.ordersPlaced }), _jsx(Text, { color: "gray", children: " | Fills: " }), _jsx(Text, { bold: true, color: "white", children: state.fills }), _jsx(Text, { color: "gray", children: " | Total P&L: " }), _jsxs(Text, { bold: true, color: pnlColor(state.totalPnl), children: ["$", state.totalPnl.toFixed(2)] })] })] })] }), state.exchangeBalances && state.exchangeBalances.length > 1 && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: "cyan", bold: true, children: "Exchange Balances" }), _jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { color: "gray", children: pad("Exchange", 16) }), _jsx(Text, { color: "gray", children: pad("Equity", 14) }), _jsx(Text, { color: "gray", children: "Available" })] }), state.exchangeBalances.map((eb, i) => (_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { color: "white", children: pad(eb.exchange, 16) }), eb.equity === null ? (_jsxs(Text, { color: "red", children: ["unavailable", eb.error ? ` (${eb.error})` : ""] })) : (_jsxs(_Fragment, { children: [_jsx(Text, { color: "white", children: pad(`$${parseFloat(eb.equity).toFixed(2)}`, 14) }), _jsx(Text, { color: "gray", children: eb.available === null ? "unavailable" : `$${parseFloat(eb.available).toFixed(2)}` })] }))] }, i)))] })), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: "cyan", bold: true, children: "Positions" }), positionErrors.map((pe, i) => (_jsxs(Text, { color: "red", children: ["  ", pe.exchange, ": unavailable (", pe.error, ")"] }, `err-${i}`))), state.positions.length === 0 ? (positionErrors.length === 0 && _jsx(Text, { color: "gray", children: "  No open positions" })) : (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [hasMultiExchange && _jsx(Text, { color: "gray", children: pad("Exchange", 14) }), _jsx(Text, { color: "gray", children: pad("Symbol", 10) }), _jsx(Text, { color: "gray", children: pad("Side", 6) }), _jsx(Text, { color: "gray", children: pad("Size", 12) }), _jsx(Text, { color: "gray", children: pad("Entry", 12) }), _jsx(Text, { color: "gray", children: pad("Mark", 12) }), _jsx(Text, { color: "gray", children: "uPnL" })] }), state.positions.map((p, i) => {
                                 const upnl = parseFloat(p.unrealizedPnl);
                                 return (_jsxs(Box, { flexDirection: "row", children: [hasMultiExchange && _jsx(Text, { color: "cyan", children: pad(p.exchange ?? "—", 14) }), _jsx(Text, { color: "white", children: pad(p.symbol, 10) }), _jsx(Text, { color: p.side.toLowerCase() === "long" ? "green" : "red", children: pad(p.side, 6) }), _jsx(Text, { color: "white", children: pad(p.size, 12) }), _jsx(Text, { color: "white", children: pad(p.entryPrice, 12) }), _jsx(Text, { color: "white", children: pad(p.markPrice, 12) }), _jsx(Text, { color: isNaN(upnl) ? "gray" : pnlColor(upnl), children: isNaN(upnl) ? "$—" : `$${upnl.toFixed(2)}` })] }, i));
                             })] }))] }), openOrdersError !== null ? (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", children: ["Open orders unavailable (", openOrdersError, ")"] }) })) : (_jsxs(Box, { marginTop: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Box, { flexDirection: "column", width: "50%", children: [_jsxs(Text, { color: "green", bold: true, children: ["Bids (", bidOrders.length, ")"] }), bidOrders.length === 0 ? (_jsx(Text, { color: "gray", children: "  --" })) : (bidOrders.slice(0, 8).map((o, i) => (_jsxs(Text, { color: "green", children: [pad(o.price, 12), " ", pad(o.size, 10), " ", o.type] }, i))))] }), _jsxs(Box, { flexDirection: "column", width: "50%", children: [_jsxs(Text, { color: "red", bold: true, children: ["Asks (", askOrders.length, ")"] }), askOrders.length === 0 ? (_jsx(Text, { color: "gray", children: "  --" })) : (askOrders.slice(0, 8).map((o, i) => (_jsxs(Text, { color: "red", children: [pad(o.price, 12), " ", pad(o.size, 10), " ", o.type] }, i))))] })] })), _jsx(Box, { marginTop: 1, flexDirection: "column", children: state.strategyState.fundingTotal !== undefined ? (_jsxs(_Fragment, { children: [_jsx(Text, { color: "cyan", bold: true, children: "Funding & Arb" }), _jsxs(Box, { flexDirection: "row", marginLeft: 2, children: [_jsx(Text, { color: "gray", children: "Funding Income: " }), _jsx(Text, { color: "white", children: String(state.strategyState.fundingTotal) }), _jsx(Text, { color: "gray", children: "        Positions: " }), _jsx(Text, { color: "white", children: String(state.strategyState.arbPositions ?? 0) })] }), Array.isArray(state.strategyState.arbPositionDetails) &&

package/dist/cache.js

@@ -7,6 +7,7 @@
 import { mkdirSync, readFileSync, writeFileSync, renameSync, readdirSync, unlinkSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
+import { randomBytes } from "crypto";
 const CACHE_DIR = join(tmpdir(), "perp-cli-cache");
 // TTL presets
 export const TTL_ACCOUNT = 15_000; // 15s — balance, positions, orders (ticks are 30s; 15s ensures same-tick dedup)
@@ -41,16 +42,21 @@ export function getCached(key) {
 }
 export function setCached(key, data, ttlMs) {
     ensureDir();
+    const file = join(CACHE_DIR, `${safeKey(key)}.json`);
+    // Unique per writer: concurrent processes writing the same key must not share one tmp file
+    // (a rename of another writer's half-written tmp would publish a partial entry).
+    const tmp = `${file}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
     try {
         const entry = { ts: Date.now(), ttl: ttlMs, data };
-        const content = JSON.stringify(entry);
-        const file = join(CACHE_DIR, `${safeKey(key)}.json`);
-        const tmp = file + ".tmp";
-        writeFileSync(tmp, content);
+        writeFileSync(tmp, JSON.stringify(entry));
         renameSync(tmp, file);
     }
     catch {
-        // cache write failure is non-fatal
+        // cache write failure is non-fatal; never leave this writer's tmp file behind
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* not written */ }
     }
 }
 /**
@@ -94,7 +100,7 @@ export function invalidateCache(keyPrefix) {
         const files = readdirSync(CACHE_DIR);
         for (const f of files) {
             if (!f.endsWith(".json"))
-                continue;
+                continue; // also skips in-flight "<key>.json.<pid>.<rand>.tmp" files
             if (!prefix || f.startsWith(prefix)) {
                 try {
                     unlinkSync(join(CACHE_DIR, f));

package/dist/cli-program.d.ts

@@ -28,8 +28,23 @@ export declare function landingData(program: Command, version: string): {
         name: string;
         description: string;
     }[];
+    venues: {
+        id: string;
+        displayName: string;
+        roles: string[];
+        apiStatus: "official" | "unofficial";
+        note: string | null;
+    }[];
 };
 export declare function buildProgram(opts: {
     defaultExchange: string;
     version: string;
 }): CliProgram;
+/**
+ * The trading-role gate at command resolution: `perp -e <venue> trade <write>`, every
+ * `perp trade multi <venue>:…` leg and `perp wallet agent approve|import|revoke|rotate <venue>`
+ * (revoke --force / --local-only excepted: local cleanup only) and every `strategy … --exchanges` leg refuse with roleUnsupported() (CAPABILITY_UNSUPPORTED) when the venue has no trading role. Runs
+ * before the dry-run guard and before any action, so a dry-run plan can never present a gated
+ * venue as tradable. Unknown venue names are left to the command's own UNKNOWN_VENUE handling.
+ */
+export declare function assertCommandVenueRole(actionCommand: Command, exchangeOpt: string): void;