perp-cli 0.12.17 → 0.14.1

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

@@ -0,0 +1,43 @@
+/**
+ * Arb state (per network, src/arb/state.ts) of spot-perp pairs opened by a bot (spot-perp-arb,
+ * funding-arb). The bot records its entries like `arb exec` does, so `arb status` confirms the
+ * pair and `arb close <SYM>` finds it. The network is the spot adapter's own (the bot's -n).
+ * An entry is matched on symbol + spot venue + perp venue.
+ */
+import { type ArbPositionState } from "../../arb/state.js";
+import { type SpotAdapter } from "../../exchanges/spot-interface.js";
+/** A bot spot-perp pair: spot base symbol, spot venue, perp venue (bot adapter names). */
+export interface SpotPerpPair {
+    symbol: string;
+    spotExchange: string;
+    perpExchange: string;
+}
+/** Arb-state symbol of a spot base: the perp name (UBTC → BTC), as `arb status` matches it. */
+export declare function stateSymbol(base: string): string;
+/** This pair's spot-perp entry in the arb state (same symbol, spot venue and perp venue), or undefined. */
+export declare function stateEntryOf(spot: SpotAdapter, pos: SpotPerpPair): ArbPositionState | undefined;
+/** A failed state write never undoes the trade: logged (with `tag`, e.g. "[SPA]") with the manual close command. */
+export declare function stateWriteFailed(tag: string, what: string, pos: SpotPerpPair, err: unknown, log: (msg: string) => void): void;
+/** The opened pair's actual legs: sizes filled, the venue-reported fill prices (null = not reported). */
+export interface SpotPerpEntry extends SpotPerpPair {
+    id: string;
+    entryTime: number;
+    /** Annualized funding spread / rate at entry (%). */
+    entrySpread: number;
+    spotSize: number;
+    perpSize: number;
+    spotAvgPrice: number | null;
+    perpEntryPrice: number | null;
+}
+/**
+ * Record an opened pair as a spot-perp arb-state entry (a failed write is logged, never thrown —
+ * including the RISK_VIOLATION of an existing entry of the symbol on other venues / another
+ * mode, which is never overwritten).
+ */
+export declare function recordSpotPerpEntry(spot: SpotAdapter, e: SpotPerpEntry, tag: string, log: (msg: string) => void): void;
+/**
+ * Close recorded in the arb state: entry removed (remaining null) or its legs set to the
+ * still-hedged remainder. A pair the state does not hold for these venues (e.g. recovered from
+ * the venues) is left alone. A failed write is logged, never thrown.
+ */
+export declare function recordSpotPerpClose(spot: SpotAdapter, pos: SpotPerpPair, remaining: string | null, tag: string, log: (msg: string) => void): void;

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

@@ -0,0 +1,70 @@
+/**
+ * Arb state (per network, src/arb/state.ts) of spot-perp pairs opened by a bot (spot-perp-arb,
+ * funding-arb). The bot records its entries like `arb exec` does, so `arb status` confirms the
+ * pair and `arb close <SYM>` finds it. The network is the spot adapter's own (the bot's -n).
+ * An entry is matched on symbol + spot venue + perp venue.
+ */
+import { addPosition, getPositions, removePositionEntry, updatePositionEntry } from "../../arb/state.js";
+import { spotNetworkOf, spotPairSymbol } from "../../exchanges/spot-factory.js";
+import { SPOT_PERP_TOKEN_MAP } from "../../exchanges/spot-interface.js";
+import { getVenue } from "../../exchanges/venue.js";
+/** Arb-state symbol of a spot base: the perp name (UBTC → BTC), as `arb status` matches it. */
+export function stateSymbol(base) {
+    const upper = base.toUpperCase();
+    return SPOT_PERP_TOKEN_MAP[upper] ?? upper;
+}
+/** This pair's spot-perp entry in the arb state (same symbol, spot venue and perp venue), or undefined. */
+export function stateEntryOf(spot, pos) {
+    const sym = stateSymbol(pos.symbol);
+    const spotId = getVenue(pos.spotExchange).id;
+    const perpId = getVenue(pos.perpExchange).id;
+    return getPositions(spotNetworkOf(spot)).find(p => p.mode === "spot-perp" && p.symbol.toUpperCase() === sym
+        && (p.spotExchange ?? p.longExchange) === spotId && p.shortExchange === perpId);
+}
+/** A failed state write never undoes the trade: logged (with `tag`, e.g. "[SPA]") with the manual close command. */
+export function stateWriteFailed(tag, what, pos, err, log) {
+    log(`  ${tag} WARNING: arb state ${what} failed for ${pos.symbol} (${err instanceof Error ? err.message : String(err)}) — \`perp arb status\` may not confirm it; close with: perp arb close ${stateSymbol(pos.symbol)} --spot-exch ${pos.spotExchange} --perp-exch ${pos.perpExchange}`);
+}
+/**
+ * Record an opened pair as a spot-perp arb-state entry (a failed write is logged, never thrown —
+ * including the RISK_VIOLATION of an existing entry of the symbol on other venues / another
+ * mode, which is never overwritten).
+ */
+export function recordSpotPerpEntry(spot, e, tag, log) {
+    try {
+        const net = spotNetworkOf(spot);
+        const now = new Date(e.entryTime).toISOString();
+        addPosition(net, {
+            id: e.id, symbol: stateSymbol(e.symbol),
+            longExchange: getVenue(e.spotExchange).id, shortExchange: getVenue(e.perpExchange).id,
+            longSize: e.spotSize, shortSize: e.perpSize,
+            entryTime: now, entrySpread: e.entrySpread,
+            entryLongPrice: e.spotAvgPrice, entryShortPrice: e.perpEntryPrice,
+            accumulatedFunding: 0, lastCheckTime: now,
+            mode: "spot-perp", spotExchange: getVenue(e.spotExchange).id, spotSymbol: spotPairSymbol(getVenue(e.spotExchange), net, e.symbol),
+        });
+    }
+    catch (err) {
+        stateWriteFailed(tag, "entry", e, err, log);
+    }
+}
+/**
+ * Close recorded in the arb state: entry removed (remaining null) or its legs set to the
+ * still-hedged remainder. A pair the state does not hold for these venues (e.g. recovered from
+ * the venues) is left alone. A failed write is logged, never thrown.
+ */
+export function recordSpotPerpClose(spot, pos, remaining, tag, log) {
+    try {
+        const entry = stateEntryOf(spot, pos);
+        if (entry === undefined)
+            return;
+        // Keyed by symbol + venues + mode: never another pair of the same symbol.
+        if (remaining === null)
+            removePositionEntry(spotNetworkOf(spot), entry);
+        else
+            updatePositionEntry(spotNetworkOf(spot), entry, { longSize: Number(remaining), shortSize: Number(remaining) });
+    }
+    catch (err) {
+        stateWriteFailed(tag, remaining === null ? "removal" : "update", pos, err, log);
+    }
+}

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

@@ -61,4 +61,10 @@ export interface Strategy {
     init(ctx: StrategyContext, snapshot: EnrichedSnapshot): Promise<void>;
     onTick(ctx: StrategyContext, snapshot: EnrichedSnapshot): Promise<StrategyAction[]>;
     onStop(ctx: StrategyContext): Promise<StrategyAction[]>;
+    /**
+     * true once the strategy has nothing left to do (e.g. DCA placed its --orders total): the
+     * engine runs onStop and ENDS the bot (never returns to monitoring). Absent = runs until an
+     * exit condition / risk limit / signal.
+     */
+    isDone?(ctx: StrategyContext): boolean;
 }

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

@@ -5,10 +5,15 @@ export interface ExchangeBalance {
 }
 export interface BotTuiState {
     phase: string;
-    equity: number;
-    peakEquity: number;
+    /** null = unknown (see the bot log for the reason) — never shown as $0. */
+    equity: number | null;
+    /** null = no baseline yet. */
+    peakEquity: number | null;
     dailyPnl: number;
+    /** Orders the venue reported as (partly) filled. */
     fills: number;
+    /** Orders sent, filled or resting. */
+    ordersPlaced: number;
     totalPnl: number;
     runtime: number;
     strategy: string;

package/dist/bot/tui/BotDashboard.js

@@ -64,13 +64,16 @@ export function BotDashboard({ initialState, onQuit, onPause, subscribe }) {
             onPause();
         }
     });
-    const drawdown = state.peakEquity - state.equity;
-    const drawdownPct = state.peakEquity > 0 ? (drawdown / state.peakEquity) * 100 : 0;
+    // Unknown equity / baseline → drawdown unknown (shown as "unknown", never $0).
+    const drawdown = state.equity !== null && state.peakEquity !== null ? state.peakEquity - state.equity : null;
+    const drawdownPct = drawdown !== null && state.peakEquity !== null && state.peakEquity > 0 ? (drawdown / state.peakEquity) * 100 : 0;
+    const usd = (v) => v === null ? "unknown" : `$${v.toFixed(2)}`;
+    const totalEquity = state.exchangeBalances !== undefined ? state.exchangeBalances.reduce((s, e) => s + parseFloat(e.equity), 0) : state.equity;
     const bidOrders = state.openOrders.filter((o) => o.side.toLowerCase() === "buy");
     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: ", _jsxs(Text, { bold: true, color: "white", children: ["$", (state.exchangeBalances?.reduce((s, e) => s + parseFloat(e.equity), 0) ?? state.equity).toFixed(2)] })] }), _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: ", _jsxs(Text, { color: "white", children: [state.volatility24h.toFixed(1), "%"] })] }), _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: ", _jsxs(Text, { bold: true, color: "white", children: ["$", state.equity.toFixed(2)] }), _jsxs(Text, { color: "gray", children: [" (peak: $", state.peakEquity.toFixed(2), ")"] })] }), _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: ", _jsxs(Text, { bold: true, color: drawdown > 0 ? "red" : "green", children: ["$", drawdown.toFixed(2), " (", drawdownPct.toFixed(1), "%)"] })] }), _jsxs(Text, { 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) }), _jsx(Text, { color: "white", children: pad(`$${parseFloat(eb.equity).toFixed(2)}`, 14) }), _jsxs(Text, { color: "gray", children: ["$", parseFloat(eb.available).toFixed(2)] })] }, i)))] })), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: "cyan", bold: true, children: "Positions" }), state.positions.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: ", _jsxs(Text, { color: "white", children: [state.volatility24h.toFixed(1), "%"] })] }), _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) }), _jsx(Text, { color: "white", children: pad(`$${parseFloat(eb.equity).toFixed(2)}`, 14) }), _jsxs(Text, { color: "gray", children: ["$", parseFloat(eb.available).toFixed(2)] })] }, i)))] })), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: "cyan", bold: true, children: "Positions" }), state.positions.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));
                             })] }))] }), _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/bridge-engine.d.ts

@@ -9,6 +9,45 @@
  * Handles USDC bridging between Solana ↔ Arbitrum ↔ Base ↔ HyperCore
  * for cross-exchange rebalancing in funding arb.
  */
+import "./exchanges/venues/index.js";
+import type { Network } from "./exchanges/venue-types.js";
+import type { SolanaSigner } from "./signer/interface.js";
+import { type BridgeEvmSigner } from "./bridge-signers.js";
+/**
+ * What signs a bridge leg: a master-wallet signer (OWS vault signer or raw-key signer from
+ * bridge-signers.ts), or — for legacy callers — a raw private key string (EVM 0x hex, Solana
+ * base58 / JSON). An "ows:<name>" reference is not a key and is refused.
+ */
+export type BridgeSignerInput = string | BridgeEvmSigner | SolanaSigner;
+/**
+ * A USDC amount: preferably the user's decimal string (exact), or a number (legacy callers).
+ * Signed amounts are always derived from the exact decimal via usdcUnits() — never from float
+ * math. A number is read as its shortest round-trip decimal (String(n)); one with an exponent or
+ * more than 6 decimals is refused.
+ */
+export type UsdcAmount = string | number;
+/**
+ * Canonical USDC decimal string ("5", "5.25") of `amount`. INVALID_PARAMS for anything that is
+ * not a positive plain decimal with at most 6 decimals (USDC has 6).
+ */
+export declare function parseUsdcAmount(amount: UsdcAmount, what?: string): string;
+/** Exact USDC base units of `amount` (validated by parseUsdcAmount). */
+export declare function usdcUnits(amount: UsdcAmount, what?: string): bigint;
+/** Calldata of the exact USDC approval ensureUsdcAllowance sends (exported for tests). */
+export declare function usdcApproveData(spender: string, amount: bigint): string;
+/**
+ * Every route in this module is mainnet-only: the RPCs, USDC / CCTP contract
+ * addresses, Circle Iris, Relay and deBridge endpoints below are mainnet
+ * deployments with no testnet equivalent wired in. A testnet run must never
+ * sign or send through them (it would move real mainnet funds), so it throws
+ * NO_BRIDGE_ROUTE before any key is used.
+ */
+export declare function assertBridgeNetwork(network: Network): void;
+/**
+ * A bridge moves funds between two different chains. Same source and destination is a caller
+ * error, refused before any quote API is called or any key is used.
+ */
+export declare function assertDistinctBridgeChains(srcChain: string, dstChain: string): void;
 export declare const CHAIN_IDS: {
     readonly solana: 7565164;
     readonly arbitrum: 42161;
@@ -56,6 +95,15 @@ export interface BridgeQuote {
     estimatedTime: number;
     gasIncluded: boolean;
     gasNote?: string;
+    /**
+     * A fee paid in the source chain's NATIVE token on top of the USDC amount (deBridge `fixFee`,
+     * sent as the tx value). `usd` is null when no price was read. null = the provider charges none.
+     */
+    nativeFee?: {
+        amount: string;
+        symbol: string;
+        usd: number | null;
+    } | null;
     raw: unknown;
 }
 export interface BridgeResult {
@@ -67,16 +115,62 @@ export interface BridgeResult {
     amountOut: number;
     receiveTxHash?: string;
 }
+/**
+ * Solana-origin deBridge is refused: the create-tx answer is a full VersionedTransaction (lookup
+ * tables, several instructions) that this CLI cannot decode and check against the order it asked
+ * for, and SSOT forbids signing a payload blindly.
+ */
+export declare function assertDebridgeSourceSupported(srcChain: string): void;
+export interface DebridgeTxExpectation {
+    srcChain: string;
+    dstChain: string;
+    sender: string;
+    recipient: string;
+    /** USDC units that must leave the wallet (OrderCreation.giveAmount). */
+    giveAmount: bigint;
+    /** USDC units asked for on the destination (create-tx dstChainTokenOutAmount). */
+    takeAmount: bigint;
+    /** Quoted fixFee (native wei): tx.value may not exceed it. */
+    fixFee: bigint;
+    /** settings bridge.debridgeAffiliate fee, or null (then no affiliate fee may be attached). */
+    affiliate: {
+        feePercent: number;
+        feeRecipient: string;
+    } | null;
+}
+/**
+ * Verify a deBridge create-tx EVM transaction before anything is signed: pinned DlnSource target,
+ * createOrder / createSaltedOrder decoded, the give token / amount, take token / chain / amount,
+ * the receiver and destination order authority (the user's own address), source patch authority,
+ * no external call / permit / taker restriction, the affiliate fee, and value ≤ the quoted fixFee.
+ * Returns the verified { to, data, value }.
+ */
+export declare function verifyDebridgeEvmTx(tx: Record<string, unknown>, x: DebridgeTxExpectation): Promise<{
+    to: string;
+    data: string;
+    value: bigint;
+}>;
 /**
  * Get a bridge quote via deBridge DLN.
  */
-export declare function getDebridgeQuote(srcChain: string, dstChain: string, amountUsdc: number, senderAddress: string, recipientAddress: string): Promise<BridgeQuote>;
+export declare function getDebridgeQuote(srcChain: string, dstChain: string, amountUsdc: UsdcAmount, senderAddress: string, recipientAddress: string): Promise<BridgeQuote>;
 /**
- * Execute a deBridge bridge transaction.
- * Returns the TX hash after signing and submitting.
+ * Execute a deBridge bridge transaction (EVM origin only). The create-tx answer is verified
+ * against the request (verifyDebridgeEvmTx) before the exact USDC approval and the order are
+ * signed. Returns the TX hash after signing and submitting.
  */
-export declare function executeDebridgeBridge(bridgeQuote: BridgeQuote, signerKey: string): Promise<BridgeResult>;
+export declare function executeDebridgeBridge(network: Network, bridgeQuote: BridgeQuote, signerKey: BridgeSignerInput): Promise<BridgeResult>;
 export declare const CCTP_DOMAINS: Record<string, number>;
+/**
+ * HyperCore → Solana is refused. The sendToEvmWithData action built below is EVM-only: it sends
+ * the recipient with addressEncoding "hex" and signs with signatureChainId = the destination's
+ * chain id. Hyperliquid documents addressEncoding "hex" | "base58" and signatureChainId as "the id
+ * of the chain used when signing" (hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/
+ * exchange-endpoint, read 2026-10-13) — a base58 Solana recipient sent as "hex", signed for the
+ * deBridge pseudo chain id 7565164, would not be what HyperCore expects. The Solana encoding is
+ * not implemented against documentation, so the route is refused before anything is signed.
+ */
+export declare function assertCctpRouteSupported(srcChain: string, dstChain: string): void;
 /**
  * Get a CCTP V2 bridge quote. Supports EVM ↔ EVM, Solana ↔ EVM, and → HyperCore.
  *
@@ -87,15 +181,26 @@ export declare const CCTP_DOMAINS: Record<string, number>;
  * @param fast - If true, use fast finality (1000): ~1-2 min, $1-1.3 + $0.20 forwarding.
  *               If false (default), use standard finality (2000): ~2-5 min, ~$0.20 forwarding.
  */
-export declare function getCctpQuote(srcChain: string, dstChain: string, amountUsdc: number, fast?: boolean): Promise<BridgeQuote>;
+export declare function getCctpQuote(srcChain: string, dstChain: string, amount: UsdcAmount, fast?: boolean): Promise<BridgeQuote>;
 /**
  * Execute a CCTP V2 bridge. Routes to the appropriate implementation.
  *
  * @param fast - If true, use fast finality (1000): Circle auto-relays, no manual receiveMessage.
  *               If false (default), use standard finality (2000): cheaper but requires manual relay.
  */
-export declare function executeCctpBridge(srcChain: string, dstChain: string, amountUsdc: number, signerKey: string, recipientAddress: string, dstSignerKey?: string, // EVM key for receiveMessage (Solana→EVM) or Solana key for receiveMessage (EVM→Solana)
+export declare function executeCctpBridge(network: Network, srcChain: string, dstChain: string, amount: UsdcAmount, signerKey: BridgeSignerInput, recipientAddress: string, dstSignerKey?: BridgeSignerInput, // destination-chain signer for receiveMessage (EVM→Solana standard finality)
 fast?: boolean): Promise<BridgeResult>;
+/**
+ * After an EVM → Solana standard-finality burn: wait for Circle's attestation, then mint on
+ * Solana with receiveMessage. Returns the mint signature. Timeout or a failed / unconfirmed
+ * receiveMessage throws ORDER_PENDING carrying the burn tx hash and the Iris URL.
+ * `opts` exists for tests (poll count / interval, receiveMessage implementation).
+ */
+export declare function completeEvmToSolanaMint(srcDomain: number, burnTxHash: string, recipientAddress: string, payer: BridgeSignerInput, opts?: {
+    attempts: number;
+    intervalMs: number;
+    receive: typeof executeSolanaReceiveMessage;
+}): Promise<string>;
 /**
  * Call receiveMessage on Solana MessageTransmitter V2 to complete an EVM→Solana bridge.
  * This mints USDC on Solana after the attestation is ready.
@@ -103,28 +208,24 @@ fast?: boolean): Promise<BridgeResult>;
 export declare function executeSolanaReceiveMessage(messageHex: string, // "0x..." CCTP message from Iris API
 attestationHex: string, // "0x..." attestation from Iris API
 recipientAddress: string, // Solana wallet pubkey (base58)
-payerKey: string): Promise<string>;
-export declare function getRelayQuote(srcChain: string, dstChain: string, amountUsdc: number, senderAddress: string, recipientAddress: string): Promise<BridgeQuote>;
-export declare function executeRelayBridge(bridgeQuote: BridgeQuote, signerKey: string): Promise<BridgeResult>;
-/**
- * Get the best bridge quote. Strategy:
- * - CCTP primary ($0 fee) for all routes: Solana↔EVM, EVM↔EVM, →HyperCore
- * - Relay + deBridge DLN in parallel, pick cheapest
- */
+payerKey: BridgeSignerInput): Promise<string>;
+export declare function getRelayQuote(srcChain: string, dstChain: string, amount: UsdcAmount, senderAddress: string, recipientAddress: string): Promise<BridgeQuote>;
 /**
- * Get quotes from ALL available providers in parallel.
- * Returns sorted by amountOut (best first).
+ * Execute a verified Relay USDC quote with the master's EVM signer (OWS vault signer or a raw
+ * key). Only the verified approve (exact amount, pinned depository) + deposit are signed — never
+ * an unlimited approval, never an unchecked target.
  */
-export declare function getAllQuotes(srcChain: string, dstChain: string, amountUsdc: number, senderAddress: string, recipientAddress: string): Promise<BridgeQuote[]>;
+export declare function executeRelayBridge(network: Network, bridgeQuote: BridgeQuote, signerKey: BridgeSignerInput): Promise<BridgeResult>;
+export declare function getAllQuotes(srcChain: string, dstChain: string, amount: UsdcAmount, senderAddress: string, recipientAddress: string): Promise<BridgeQuote[]>;
 /**
  * Get the best quote across all providers.
  */
-export declare function getBestQuote(srcChain: string, dstChain: string, amountUsdc: number, senderAddress: string, recipientAddress: string): Promise<BridgeQuote>;
+export declare function getBestQuote(srcChain: string, dstChain: string, amount: UsdcAmount, senderAddress: string, recipientAddress: string): Promise<BridgeQuote>;
 /**
  * Execute a bridge using the specified or best available provider.
  * @param provider - Optional: force a specific provider ("cctp" | "relay" | "debridge")
  */
-export declare function executeBestBridge(srcChain: string, dstChain: string, amountUsdc: number, signerKey: string, senderAddress: string, recipientAddress: string, dstSignerKey?: string, // Optional EVM key for manual receiveMessage (standard finality)
+export declare function executeBestBridge(network: Network, srcChain: string, dstChain: string, amount: UsdcAmount, signerKey: BridgeSignerInput, senderAddress: string, recipientAddress: string, dstSignerKey?: BridgeSignerInput, // Optional destination-chain signer for manual receiveMessage (standard finality)
 provider?: "cctp" | "relay" | "debridge", fast?: boolean): Promise<BridgeResult>;
 /**
  * Check bridge order status via deBridge.