perp-cli 0.12.17 → 0.14.0

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

@@ -7,12 +7,22 @@
  * Strategy layer handles ONLY decisions (opportunity scanning, scoring, close/rotation decisions).
  * Execution layer (SpotPerpExecutor) handles ALL exchange interactions.
  */
+import { requiredArbMargin } from "../../rebalance.js";
 import { registerStrategy } from "../strategy-registry.js";
 import { getFundingHours } from "../../funding.js";
 import { annualizeHourlyRate } from "../../funding/normalize.js";
 import { pruneExecutionLog } from "../../execution-log.js";
-import { buildAdapterMap, getSpotAdapter, getPerpSymbol, findRate, matchSymbol, fetchRates, scoreFunding, } from "./funding-arb-utils.js";
+import { buildAdapterMap, getPerpSymbol, findRate, matchSymbol, fetchRates, scoreFunding, botSpotPerpMatches, assertFundingArbLegs, cancelBotSymbols } from "./funding-arb-utils.js";
 import { SpotPerpExecutor } from "./spot-perp-executor.js";
+import { findSpotQuoteBalance, getBotSpotAdapter, nonQuoteSpotBalances, spotNetworkOf, spotSharesPerpMargin, spotTokenBase } from "../../exchanges/spot-factory.js";
+import { getVenue } from "../../exchanges/venue.js";
+import { updatePositionEntry } from "../../arb/state.js";
+import { recordSpotPerpClose, recordSpotPerpEntry, stateEntryOf, stateWriteFailed } from "./spot-perp-state.js";
+import { isQuarantined, quarantineSymbol } from "../quarantine.js";
+/** Consecutive failed closes before a position is quarantined (no sell→fail→re-hedge loop). */
+const MAX_CLOSE_FAILURES = 3;
+/** Spot leg buying power: notional plus 1% for the taker fee and the spot buy's slippage bound. */
+const SPOT_FEE_BUFFER = 1.01;
 let _posIdCounter = 0;
 function genPosId() { return `spa-${Date.now()}-${++_posIdCounter}`; }
 // ── Strategy ──
@@ -38,6 +48,12 @@ export class SpotPerpArbStrategy {
     }
     _config = {};
     _failCooldown = new Map();
+    /** Consecutive failed close attempts per symbol (quarantined at MAX_CLOSE_FAILURES). */
+    _closeFailures = new Map();
+    /** Venues whose positions could not be read during recovery: no entries there until re-read. */
+    _unrecovered = new Set();
+    /** Perp symbols this bot entered or tracked this run — the only symbols its stop cancels orders on. */
+    _traded = new Set();
     _fundingScoreCache = new Map();
     get params() {
         const c = this._config;
@@ -57,6 +73,7 @@ export class SpotPerpArbStrategy {
     }
     // ── init ──
     async init(ctx, _snapshot) {
+        assertFundingArbLegs(ctx);
         try {
             pruneExecutionLog(30);
         }
@@ -73,7 +90,8 @@ export class SpotPerpArbStrategy {
         ctx.log(`  [SPA] Exchanges: ${p.exchanges.join(", ")}`);
         try {
             const adapters = buildAdapterMap(ctx);
-            const recovered = await this.recoverPositions(adapters, ctx);
+            const { recovered, unreadable } = await this.recoverPositions(adapters, ctx);
+            this._unrecovered = unreadable;
             if (recovered.length > 0) {
                 ctx.state.set("spaPositions", recovered);
                 ctx.state.set("arbPositions", recovered.length);
@@ -105,6 +123,19 @@ export class SpotPerpArbStrategy {
         const p = this.params;
         const positions = ctx.state.get("spaPositions");
         const adapters = buildAdapterMap(ctx);
+        // Retry recovery on venues whose positions could not be read at init.
+        if (this._unrecovered.size > 0) {
+            const { recovered, unreadable } = await this.recoverPositions(adapters, ctx);
+            const tracked = new Set(positions.map(pos => pos.symbol.toUpperCase()));
+            for (const r of recovered) {
+                if (tracked.has(r.symbol.toUpperCase()))
+                    continue;
+                positions.push(r);
+                tracked.add(r.symbol.toUpperCase());
+            }
+            ctx.state.set("arbPositions", positions.length);
+            this._unrecovered = unreadable;
+        }
         const exchangeBalances = new Map();
         const availableAdapters = new Map();
         for (const [name, a] of adapters) {
@@ -115,7 +146,9 @@ export class SpotPerpArbStrategy {
                 const available = parseFloat(bal.available);
                 exchangeBalances.set(name, { equity, available, marginPct });
                 const cd = this._failCooldown.get(`${name}:exchange`) ?? 0;
-                if (Date.now() < cd)
+                if (this._unrecovered.has(name))
+                    ctx.log(`  [SPA] ${name} positions not recovered — no entries this tick`);
+                else if (Date.now() < cd)
                     ctx.log(`  [SPA] ${name} on cooldown`);
                 else if (available < 5)
                     ctx.log(`  [SPA] ${name} available $${available.toFixed(2)} too low`);
@@ -131,7 +164,15 @@ export class SpotPerpArbStrategy {
         }
         const ratesByExchange = new Map();
         for (const [name, a] of adapters) {
-            const rates = await fetchRates(a, name);
+            let rates;
+            try {
+                rates = await fetchRates(a, name);
+            }
+            catch (err) {
+                // Recorded per venue; this venue is left out of this cycle's rate map.
+                ctx.log(`  [SPA] fetchRates failed for ${name}: ${err instanceof Error ? err.message : String(err)}`);
+                continue;
+            }
             const map = new Map();
             for (const r of rates)
                 map.set(r.symbol.toUpperCase(), { rate: r.rate, price: r.price, sizeDecimals: r.sizeDecimals, maxLeverage: r.maxLeverage, fundingHours: r.fundingHours });
@@ -189,6 +230,10 @@ export class SpotPerpArbStrategy {
         for (const pos of positions) {
             if (!this.shouldClose(pos, ratesByExchange, p))
                 continue;
+            if (this.quarantined(pos.symbol, ctx)) {
+                ctx.log(`  [SPA] ${pos.symbol} is quarantined — not closing (perp strategy quarantine)`);
+                continue;
+            }
             const cd = this._failCooldown.get(`${pos.symbol}:close`) ?? 0;
             if (Date.now() < cd)
                 continue;
@@ -206,23 +251,67 @@ export class SpotPerpArbStrategy {
                 symbol: pos.symbol, spotExchange: pos.spotExchange, perpExchange: pos.perpExchange,
                 spotAdapter, perpAdapter, size: pos.size, log: ctx.log,
             });
-            if (closed)
+            if (closed.closed) {
                 toClose.push(pos);
-            else
+                this._closeFailures.delete(pos.symbol);
+                this.recordClose(spotAdapter, pos, null, ctx);
+            }
+            else if (closed.manual) {
+                this.quarantine(pos.symbol, closed.reason, pos.spotExchange, pos.perpExchange, ctx);
+            }
+            else if (closed.remainingSize !== null) {
+                pos.size = closed.remainingSize; // partial close: remainder still hedged
+                this.recordClose(spotAdapter, pos, closed.remainingSize, ctx);
+                this._closeFailures.delete(pos.symbol);
                 this._failCooldown.set(`${pos.symbol}:close`, Date.now() + 5 * 60 * 1000);
+            }
+            else {
+                // Each failed attempt may have traded (perp close → spot sell fail → re-hedge):
+                // stop after MAX_CLOSE_FAILURES instead of looping.
+                const n = (this._closeFailures.get(pos.symbol) ?? 0) + 1;
+                this._closeFailures.set(pos.symbol, n);
+                if (n >= MAX_CLOSE_FAILURES) {
+                    this.quarantine(pos.symbol, `close failed ${n} times in a row — stopping automatic close attempts`, pos.spotExchange, pos.perpExchange, ctx);
+                }
+                else {
+                    this._failCooldown.set(`${pos.symbol}:close`, Date.now() + 5 * 60 * 1000);
+                }
+            }
         }
         if (toClose.length > 0) {
             const remaining = positions.filter(pos => !toClose.some(c => c.id === pos.id));
             ctx.state.set("spaPositions", remaining);
             ctx.state.set("arbPositions", remaining.length);
         }
-        // ── Rotation check ──
+        // ── Rotation check (only to perp venues that match the spot leg, §12.4 #6) ──
+        const perpMarketsCache = new Map();
+        const allowedBySpotVenue = new Map();
         const currentPositions = ctx.state.get("spaPositions");
         for (const pos of currentPositions) {
+            if (this.quarantined(pos.symbol, ctx))
+                continue;
             const rcd = this._failCooldown.get(`${pos.id}:rotate`) ?? 0;
             if (Date.now() < rcd)
                 continue;
-            const candidates = await this.findPerpCandidates(pos.symbol, adapters, ratesByExchange);
+            let allowedByBase = allowedBySpotVenue.get(pos.spotExchange);
+            if (allowedByBase === undefined) {
+                const spotExAdapter = adapters.get(pos.spotExchange);
+                const rotSpot = spotExAdapter ? await getBotSpotAdapter(pos.spotExchange, spotExAdapter) : null;
+                if (rotSpot === null)
+                    continue;
+                try {
+                    allowedByBase = await this.spotPerpVenues(pos.spotExchange, await rotSpot.getSpotMarkets(), adapters, perpMarketsCache, ctx);
+                }
+                catch (e) {
+                    ctx.log(`  [SPA] ${pos.spotExchange} spot↔perp matching failed (rotation skipped): ${e instanceof Error ? e.message : String(e)}`);
+                    continue;
+                }
+                allowedBySpotVenue.set(pos.spotExchange, allowedByBase);
+            }
+            const allowed = allowedByBase.get(pos.symbol.toUpperCase());
+            if (allowed === undefined)
+                continue;
+            const candidates = await this.findPerpCandidates(pos.symbol, adapters, ratesByExchange, allowed);
             const best = candidates[0];
             if (!best || best.exchange === pos.perpExchange)
                 continue;
@@ -247,11 +336,26 @@ export class SpotPerpArbStrategy {
                 currentAdapter: oldAdapter, newAdapter,
                 size: pos.size, leverage: Math.min(p.leverage, newMaxLev), log: ctx.log,
             });
-            if (ok) {
+            if (ok.ok) {
+                // The spot leg is unchanged: the state entry follows the short to its new venue.
+                try {
+                    const spotExAdapter = adapters.get(pos.spotExchange);
+                    const rotSpot = spotExAdapter ? await this.executor.getSpotAdapter(pos.spotExchange, spotExAdapter) : null;
+                    const entry = rotSpot !== null ? stateEntryOf(rotSpot, pos) : undefined;
+                    if (rotSpot !== null && entry !== undefined)
+                        updatePositionEntry(spotNetworkOf(rotSpot), entry, { shortExchange: getVenue(best.exchange).id, entryShortPrice: ok.entryPrice });
+                }
+                catch (e) {
+                    stateWriteFailed("[SPA]", "update (rotation)", { ...pos, perpExchange: best.exchange }, e, ctx.log);
+                }
                 pos.perpExchange = best.exchange;
                 pos.fundingHistory = [];
                 pos.lastFundingCheck = 0;
             }
+            else if (ok.manual) {
+                // A leg is unknown / unhedged: a retry could double-short — quarantine, never cool down.
+                this.quarantine(pos.symbol, ok.reason, pos.spotExchange, `${pos.perpExchange}/${best.exchange}`, ctx);
+            }
             else {
                 this._failCooldown.set(`${pos.id}:rotate`, Date.now() + 10 * 60 * 1000);
             }
@@ -266,12 +370,12 @@ export class SpotPerpArbStrategy {
         const HL_SPOT_WHITELIST = new Set(["UBTC", "UETH", "USOL", "UFART", "UPUMP", "LINK0", "AVAX0", "AAVE0", "PURR", "HYPE"]);
         for (const [spotExName, spotExAdapter] of adapters) {
             try {
-                const spotAdapter = await getSpotAdapter(spotExName, spotExAdapter);
+                const spotAdapter = await getBotSpotAdapter(spotExName, spotExAdapter);
                 if (!spotAdapter)
                     continue;
-                const spotMarkets = await spotAdapter.getSpotMarkets();
-                for (const m of spotMarkets) {
-                    const base = m.baseToken.toUpperCase();
+                // Canonical symbol + price guard (§12.4 #6): 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
                     if (spotExName === "hyperliquid" && !HL_SPOT_WHITELIST.has(base))
                         continue;
@@ -279,7 +383,9 @@ export class SpotPerpArbStrategy {
                         continue;
                     if (Date.now() < (this._failCooldown.get(`${base}:entry`) ?? 0))
                         continue;
-                    const candidates = await this.findPerpCandidates(base, adapters, ratesByExchange);
+                    if (this.quarantined(base, ctx))
+                        continue;
+                    const candidates = await this.findPerpCandidates(base, adapters, ratesByExchange, allowed);
                     for (const cand of candidates) {
                         if (cand.score.annualized < p.min_rate || cand.score.consistency < p.min_consistency)
                             continue;
@@ -287,7 +393,9 @@ export class SpotPerpArbStrategy {
                     }
                 }
             }
-            catch { /* no spot */ }
+            catch (e) {
+                ctx.log(`  [SPA] ${spotExName} spot scan failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
         }
         scoredOpps.sort((a, b) => b.annualized - a.annualized);
         if (scoredOpps.length > 0 && numPos < p.max_positions) {
@@ -298,6 +406,8 @@ export class SpotPerpArbStrategy {
         for (const opp of scoredOpps) {
             if (ctx.state.get("spaPositions").length >= p.max_positions)
                 break;
+            if (this._unrecovered.has(opp.spotExchange) || this._unrecovered.has(opp.perpExchange))
+                continue;
             const opened = await this.tryOpenPosition(opp.spotExchange, opp.perpExchange, opp.symbol, opp.annualized, adapters, ctx, ratesByExchange, exchangeBalances);
             if (opened)
                 return [{ type: "noop" }];
@@ -311,9 +421,16 @@ export class SpotPerpArbStrategy {
     async onStop(ctx) {
         const positions = ctx.state.get("spaPositions");
         const adapters = buildAdapterMap(ctx);
+        for (const p of positions ?? [])
+            this._traded.add(getPerpSymbol(p.symbol, p.perpExchange).toUpperCase());
         if (positions && positions.length > 0) {
             const remaining = [];
             for (const pos of positions) {
+                if (this.quarantined(pos.symbol, ctx)) {
+                    ctx.log(`  [SPA] CRITICAL: ${pos.symbol} is quarantined — left open on stop; resolve manually (perp strategy quarantine)`);
+                    remaining.push(pos);
+                    continue;
+                }
                 const spotExAdapter = adapters.get(pos.spotExchange) ?? adapters.get(pos.perpExchange);
                 const perpAdapter = adapters.get(pos.perpExchange);
                 if (!perpAdapter || !spotExAdapter) {
@@ -331,33 +448,62 @@ export class SpotPerpArbStrategy {
                     symbol: pos.symbol, spotExchange: pos.spotExchange, perpExchange: pos.perpExchange,
                     spotAdapter, perpAdapter, size: pos.size, log: ctx.log,
                 });
-                if (!closed) {
-                    ctx.log(`  [SPA] CRITICAL: ${pos.symbol} could not be closed on stop`);
+                if (closed.closed)
+                    this.recordClose(spotAdapter, pos, null, ctx);
+                else {
+                    if (closed.manual)
+                        this.quarantine(pos.symbol, closed.reason, pos.spotExchange, pos.perpExchange, ctx);
+                    else if (closed.remainingSize !== null) {
+                        pos.size = closed.remainingSize; // partial close: remainder still hedged
+                        this.recordClose(spotAdapter, pos, closed.remainingSize, ctx);
+                    }
+                    ctx.log(`  [SPA] CRITICAL: ${pos.symbol} could not be (fully) closed on stop`);
                     remaining.push(pos);
                 }
             }
             ctx.state.set("spaPositions", remaining);
             ctx.state.set("arbPositions", remaining.length);
         }
-        const extra = ctx.state.get("extraAdapters");
-        if (extra) {
-            for (const [, a] of extra) {
-                try {
-                    await a.cancelAllOrders();
-                }
-                catch { /* best effort */ }
-            }
-        }
-        return [{ type: "cancel_all" }];
+        // Only the bot's own symbols, on each venue it used — never an account-wide cancel.
+        await cancelBotSymbols(adapters, this._traded, "[SPA]", ctx.log);
+        return [];
+    }
+    /** Close recorded in the arb state: entry removed (remaining null) or its legs set to the still-hedged remainder. */
+    recordClose(spot, pos, remaining, ctx) {
+        recordSpotPerpClose(spot, pos, remaining, "[SPA]", ctx.log);
+    }
+    quarantined(symbol, ctx) {
+        return isQuarantined(symbol, ctx.log);
+    }
+    /** Unknown / unhedged outcome (executor `manual`): stop touching this symbol until a human clears it. */
+    quarantine(symbol, reason, spotExchange, perpExchange, ctx) {
+        quarantineSymbol(this.name, symbol, reason, `Check ${spotExchange} spot (perp -e ${spotExchange} trade spot-balance, perp -e ${spotExchange} trade spot-orders) and the ${perpExchange} perp (perp -e ${perpExchange} positions); resolve by hand, then: perp strategy quarantine-clear ${symbol.toUpperCase()}`, ctx.log);
     }
     // ── Scoring (decision logic) ──
     scoreFundingLocal(adapter, symbol, exchangeName) {
         return scoreFunding(adapter, symbol, exchangeName, this.params.history_periods, this._fundingScoreCache);
     }
+    /** base (upper-case) → perp venues it may hedge on (canonical symbol + price guard, `botSpotPerpMatches`). */
+    async spotPerpVenues(spotExName, spotMarkets, adapters, perpMarketsCache, ctx) {
+        const byPerp = await botSpotPerpMatches(spotExName, spotMarkets, [...adapters.keys()], perpMarketsCache, (msg) => ctx.log(`  [SPA] ${msg}`));
+        const byBase = new Map();
+        for (const [perpVenue, bases] of byPerp) {
+            for (const b of bases) {
+                const set = byBase.get(b);
+                if (set)
+                    set.add(perpVenue);
+                else
+                    byBase.set(b, new Set([perpVenue]));
+            }
+        }
+        return byBase;
+    }
     /** Find all perp exchanges for a symbol, sorted by annualized rate (highest first). */
-    async findPerpCandidates(symbol, adapters, ratesByExchange) {
+    async findPerpCandidates(symbol, adapters, ratesByExchange, allowedPerpVenues) {
         const candidates = [];
         for (const [exName, adapter] of adapters) {
+            if (!allowedPerpVenues.has(exName))
+                continue;
             const perpSym = getPerpSymbol(symbol, exName);
             const ri = findRate(ratesByExchange, exName, perpSym) ?? findRate(ratesByExchange, exName, symbol);
             if (!ri || ri.rate <= 0)
@@ -403,6 +549,11 @@ export class SpotPerpArbStrategy {
     // ── Open position (decision + sizing, delegates execution) ──
     async tryOpenPosition(spotExchange, perpExchange, symbol, entryRate, adapters, ctx, ratesByExchange, exchangeBalances) {
         const p = this.params;
+        // Engine: equity unknown → no new entries (closes / rotations' closes still run).
+        if (ctx.state.get("equityUnknown") === true) {
+            ctx.log(`  [SPA] Skip ${symbol}: equity unknown — no new entries`);
+            return false;
+        }
         const spotExAdapter = adapters.get(spotExchange);
         const perpAdapter = adapters.get(perpExchange);
         if (!spotExAdapter || !perpAdapter) {
@@ -455,11 +606,12 @@ export class SpotPerpArbStrategy {
             if (sameExchange) {
                 const perpBal = await perpAdapter.getBalance();
                 const perpAvail = parseFloat(perpBal.available);
-                const totalNeeded = targetSizeUsd + targetSizeUsd / leverage;
-                if (perpAvail < totalNeeded) {
-                    const max = perpAvail * 0.8 / (1 + 1 / leverage);
+                // Spot leg: notional × SPOT_FEE_BUFFER; perp leg: requiredArbMargin (notional / leverage × ARB_MARGIN_BUFFER).
+                const need = (n) => n * SPOT_FEE_BUFFER + requiredArbMargin(n, leverage);
+                if (perpAvail < need(targetSizeUsd)) {
+                    const max = perpAvail / need(1);
                     if (max < 10) {
-                        ctx.log(`  [SPA] Skip ${symbol}: insufficient balance`);
+                        ctx.log(`  [SPA] Skip ${symbol}: insufficient balance — $${perpAvail.toFixed(2)} available, $${need(10).toFixed(2)} needed for the $10 minimum (spot + perp margin at ${leverage}x)`);
                         return false;
                     }
                     targetSizeUsd = Math.floor(max);
@@ -473,38 +625,45 @@ export class SpotPerpArbStrategy {
                     return false;
                 // Check spot USDC balance (only add if separate from perp — skip for unified accounts like HL)
                 let spotAvailable = sBal.available;
-                const isUnified = spotExAdapter?.isUnifiedAccount ?? false;
-                if (!isUnified) {
-                    try {
-                        const spotBals = await spotAdapter.getSpotBalances();
-                        const spotUsdc = spotBals.find(b => b.token.toUpperCase().startsWith("USDC"));
-                        if (spotUsdc)
-                            spotAvailable += parseFloat(spotUsdc.available);
-                    }
-                    catch { /* non-critical */ }
+                const spotDef = getVenue(spotExchange);
+                if (!spotSharesPerpMargin(spotDef, spotExAdapter)) {
+                    const spotQuote = findSpotQuoteBalance(spotDef, spotNetworkOf(spotAdapter), await spotAdapter.getSpotBalances());
+                    if (spotQuote)
+                        spotAvailable += parseFloat(spotQuote.available);
                 }
-                const maxNtl = Math.min(spotAvailable, pBal.available * leverage) * 0.8;
+                // Spot leg: notional × SPOT_FEE_BUFFER of spot buying power; perp leg: requiredArbMargin at the leverage.
+                const maxNtl = Math.min(spotAvailable / SPOT_FEE_BUFFER, pBal.available / requiredArbMargin(1, leverage));
                 if (maxNtl < targetSizeUsd) {
                     if (maxNtl < 10) {
-                        ctx.log(`  [SPA] Skip ${symbol}: insufficient balance (spot=$${spotAvailable.toFixed(2)}, perp=$${pBal.available.toFixed(2)})`);
+                        ctx.log(`  [SPA] Skip ${symbol}: insufficient balance for the $10 minimum — spot $${spotAvailable.toFixed(2)} (needs $${(10 * SPOT_FEE_BUFFER).toFixed(2)}), perp $${pBal.available.toFixed(2)} (needs $${requiredArbMargin(10, leverage).toFixed(2)} margin at ${leverage}x)`);
                         return false;
                     }
                     targetSizeUsd = Math.floor(maxNtl);
                 }
             }
             // Delegate to executor
+            this._traded.add(perpSymbol.toUpperCase());
             const result = await this.executor.openPosition({
                 symbol, perpSymbol, spotExchange, perpExchange,
                 spotAdapter, perpAdapter, sizeUsd: targetSizeUsd, leverage, log: ctx.log,
             });
             if (result.success) {
                 const cur = ctx.state.get("spaPositions");
-                cur.push({ id: genPosId(), symbol, spotExchange, perpExchange, size: result.size, entryTime: Date.now(), entryRate, fundingHistory: [], lastFundingCheck: 0 });
+                const pos = { id: genPosId(), symbol, spotExchange, perpExchange, size: result.size, entryTime: Date.now(), entryRate, fundingHistory: [], lastFundingCheck: 0 };
+                cur.push(pos);
+                recordSpotPerpEntry(spotAdapter, {
+                    id: pos.id, symbol, spotExchange, perpExchange, entryTime: pos.entryTime, entrySpread: entryRate,
+                    spotSize: result.spotSize, perpSize: Number(result.size), spotAvgPrice: result.spotAvgPrice, perpEntryPrice: result.perpEntryPrice,
+                }, "[SPA]", ctx.log);
                 ctx.state.set("spaPositions", cur);
                 ctx.state.set("arbPositions", cur.length);
                 ctx.log(`  [SPA] Opened! (${cur.length}/${p.max_positions})`);
                 return true;
             }
+            if (result.manual === true) {
+                this.quarantine(symbol, result.error ?? "entry outcome unknown", spotExchange, perpExchange, ctx);
+                return false;
+            }
             this._failCooldown.set(`${symbol}:entry`, Date.now() + 5 * 60 * 1000);
             return false;
         }
@@ -515,25 +674,30 @@ export class SpotPerpArbStrategy {
         }
     }
     // ── Position recovery ──
+    /** Rebuild positions from the venues; `unreadable` = venues whose positions / spot balances failed to load (never "none"). */
     async recoverPositions(adapters, ctx) {
         const recovered = [];
+        const unreadable = new Set();
         const perpByEx = new Map();
         for (const [name, a] of adapters) {
             try {
                 const pos = await a.getPositions();
                 perpByEx.set(name, pos.map(p => ({ symbol: p.symbol.toUpperCase(), side: p.side, size: p.size })));
             }
-            catch { /* skip */ }
+            catch (e) {
+                unreadable.add(name);
+                ctx.log(`  [SPA] ${name} positions unreadable during recovery (${e instanceof Error ? e.message : String(e)}) — no entries on ${name} until recovered`);
+            }
         }
         const used = new Set();
         for (const [spotExName, spotExAdapter] of adapters) {
             try {
-                const spotAdapter = await getSpotAdapter(spotExName, spotExAdapter);
+                const spotAdapter = await getBotSpotAdapter(spotExName, spotExAdapter);
                 if (!spotAdapter)
                     continue;
                 const bals = await spotAdapter.getSpotBalances();
-                for (const bal of bals.filter(b => Number(b.total) > 0 && !b.token.toUpperCase().startsWith("USDC"))) {
-                    const base = bal.token.toUpperCase().replace(/-SPOT$/, "");
+                for (const bal of nonQuoteSpotBalances(getVenue(spotExName), spotNetworkOf(spotAdapter), bals)) {
+                    const base = spotTokenBase(bal.token);
                     for (const [perpExName, perps] of perpByEx) {
                         for (const perp of perps) {
                             const key = `${perpExName}:${perp.symbol}`;
@@ -549,9 +713,12 @@ export class SpotPerpArbStrategy {
                     }
                 }
             }
-            catch { /* no spot */ }
+            catch (e) {
+                unreadable.add(spotExName);
+                ctx.log(`  [SPA] ${spotExName} spot recovery failed: ${e instanceof Error ? e.message : String(e)} — no entries on ${spotExName} until recovered`);
+            }
         }
-        return recovered;
+        return { recovered, unreadable };
     }
 }
 registerStrategy("spot-perp-arb", (_config) => new SpotPerpArbStrategy());

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

@@ -6,20 +6,63 @@
  */
 import type { ExchangeAdapter } from "../../exchanges/index.js";
 import type { SpotAdapter } from "../../exchanges/spot-interface.js";
-export interface ExecutionResult {
-    success: boolean;
-    size?: string;
-    notional?: number;
-    error?: string;
-}
+export type ExecutionResult = {
+    success: true;
+    /** Perp short size (= the hedged spot, on the perp lot grid). */
+    size: string;
+    notional: number;
+    /** Spot base units bought (the verified fill). */
+    spotSize: number;
+    /** The spot fill's average price; null = the venue reported none. */
+    spotAvgPrice: number | null;
+    /** The venue's entry price of the perp short after the hedge; null = not readable. */
+    perpEntryPrice: number | null;
+} | {
+    success: false;
+    error: string;
+    /** true = outcome unknown or a leg left unhedged: the caller must quarantine the symbol (no retry). */
+    manual?: boolean;
+};
+/**
+ * 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).
+ */
+export type CloseResult = {
+    closed: true;
+    remainingSize: null;
+    manual: false;
+} | {
+    closed: false;
+    remainingSize: string | null;
+    manual: false;
+} | {
+    closed: false;
+    remainingSize: null;
+    manual: true;
+    reason: string;
+};
+/** Rotation outcome (ok: the venue's entry price of the new short, null = not readable); manual = a leg's state is unknown or unhedged: the caller must quarantine. */
+export type RotationResult = {
+    ok: true;
+    entryPrice: number | null;
+} | {
+    ok: false;
+    manual: false;
+} | {
+    ok: false;
+    manual: true;
+    reason: string;
+};
 export declare class SpotPerpExecutor {
-    private _spotAdapterCache;
-    /** Get or create cached spot adapter. */
+    /** Spot adapter for a bot spot venue (factory-cached); null outside the bot spot scope. */
     getSpotAdapter(name: string, adapter: ExchangeAdapter): Promise<SpotAdapter | null>;
-    /** Transfer USDC: perp -> spot account. */
-    transferToSpot(spotAdapter: SpotAdapter, exchange: string, amount: number): Promise<void>;
-    /** Transfer USDC: spot -> perp account. */
-    transferToPerp(spotAdapter: SpotAdapter, exchange: string, amount: number): Promise<void>;
+    /** Transfer the spot quote asset perp -> spot. false = shared margin (nothing moved). */
+    transferToSpot(spotAdapter: SpotAdapter, amount: number): Promise<boolean>;
+    /** Transfer the spot quote asset spot -> perp. false = shared margin (nothing moved). */
+    transferToPerp(spotAdapter: SpotAdapter, amount: number): Promise<boolean>;
+    /** Rollback transfer spot → perp: failure is logged loudly (funds remain in spot), never swallowed. */
+    private returnToPerp;
     /**
      * Full spot-perp entry flow:
      * 1. Check liquidity
@@ -47,6 +90,11 @@ export declare class SpotPerpExecutor {
      * 1. Close perp short FIRST (reduceOnly) — hedge stays intact if this fails
      * 2. Sell spot
      * 3. Transfer USDC back to perp (always, not just same-exchange)
+     *
+     * Returns `manual: true` (caller quarantines, never retries) when the spot outcome is
+     * unknown (pending sell, failed post-trade verification) or spot is left unhedged.
+     * A perp short is re-opened only when THIS call closed it; if the perp was already
+     * gone and spot cannot be sold, nothing new is opened — the position is quarantined.
      */
     closePosition(params: {
         symbol: string;
@@ -56,14 +104,20 @@ export declare class SpotPerpExecutor {
         perpAdapter: ExchangeAdapter;
         size: string;
         log: (msg: string) => void;
-    }): Promise<boolean>;
+    }): Promise<CloseResult>;
+    /** Base-token balance (total), read UNCACHED; a token with no balance row holds 0. Errors propagate. */
+    private baseBalance;
+    private baseOf;
+    /** Spot quote total (0 when shared with perp margin — nothing to move, or no quote row). */
+    private quoteOf;
     /**
-     * Rotate perp short to better exchange:
+     * Rotate perp short to better exchange (spot stays unchanged):
      * 1. Set leverage on new exchange
-     * 2. Close current perp short (reduceOnly)
-     * 3. Open new perp short on new exchange
-     * 4. Rollback if new short fails
-     * Spot stays unchanged.
+     * 2. Close current perp short (reduceOnly, verified)
+     * 3. Open new perp short on new exchange (verified)
+     * 4. If the new short definitely failed: re-open the old short (verified)
+     * Any leg whose outcome is unknown, or a failed rollback, returns manual (quarantine):
+     * retrying could double-short or leave the spot unhedged.
      */
     rotateShort(params: {
         symbol: string;
@@ -75,5 +129,5 @@ export declare class SpotPerpExecutor {
         size: string;
         leverage: number;
         log: (msg: string) => void;
-    }): Promise<boolean>;
+    }): Promise<RotationResult>;
 }