@reefclaw/openclaw-plugin 0.1.0

package/simulator/fill-engine.d.ts

@@ -0,0 +1,53 @@
+import type { Order, Position, Wallet, Trade, OrderBookDepth, SimulationConfig, ExecutionQuality, PositionMetadata } from './types.js';
+/** Result of filling an order */
+export interface FillResult {
+    /** The filled order (status set to 'closed') */
+    order: Order;
+    /** Updated or new position (null if position was fully closed) */
+    position: Position | null;
+    /** Closed trade record (only when closing/reducing a position) */
+    trade: Trade | null;
+    /** Wallet balance changes: { currency: delta } */
+    walletDeltas: Record<string, number>;
+    /** Execution quality metrics (Phase 9a) */
+    executionQuality?: ExecutionQuality;
+}
+/**
+ * Compute simulated slippage for a market order (legacy mode).
+ * Returns basis points: random 0-2 bps, signed based on order side.
+ * BUY: positive slippage (pay more), SELL: negative slippage (receive less).
+ */
+export declare function computeSlippage(side: 'buy' | 'sell'): number;
+/**
+ * Apply slippage to a price.
+ * @param price Base price
+ * @param slippageBps Slippage in basis points (signed)
+ * @returns Adjusted price
+ */
+export declare function applySlippage(price: number, slippageBps: number): number;
+/**
+ * Parse the base and quote currencies from a symbol like "BTC/USDT".
+ */
+export declare function parseSymbol(symbol: string): {
+    base: string;
+    quote: string;
+};
+/** Options for realistic market fills (Phase 9a). */
+export interface RealisticFillOptions {
+    orderbook?: OrderBookDepth | null;
+    config?: SimulationConfig;
+    volFactor?: number;
+    /** Position metadata to attach on new position creation. */
+    metadata?: PositionMetadata;
+}
+/**
+ * Fill a market order immediately at the given price (plus slippage).
+ * When realistic options are provided, uses book-aware VWAP + latency + maker/taker fees.
+ * Otherwise falls back to legacy random slippage + flat fee.
+ */
+export declare function fillMarketOrder(order: Order, currentPrice: number, wallet: Wallet, existingPosition: Position | null, realistic?: RealisticFillOptions): FillResult;
+/**
+ * Fill a limit order (when price crosses the limit price).
+ * Limit orders fill at the limit price. When config is provided, uses maker fee rate.
+ */
+export declare function fillLimitOrder(order: Order, wallet: Wallet, existingPosition: Position | null, config?: SimulationConfig, decisionPrice?: number, metadata?: PositionMetadata): FillResult;

package/simulator/fill-engine.js

@@ -0,0 +1,276 @@
+// Fill engine for simulated order execution (derivatives model).
+// All accounting in quote currency (USDT). Supports long and short positions.
+// Opening any direction: deduct notional + fee from USDT.
+// Closing: credit margin + PnL - fee to USDT.
+//
+// Phase 9a: Supports realistic fills (book-aware VWAP, latency, maker/taker fees)
+// when SimulationConfig and OrderBookDepth are provided. Falls back to legacy
+// behavior (0-2 bps random slippage, 0.1% flat fee) when not provided.
+import { FEE_RATE } from './types.js';
+import { computeRealisticMarketFill, computeLimitFillQuality, getFeeRate, } from './realistic-fills.js';
+/** On NEW-position creation only, freeze the at-fill stop into
+ *  `originalStopPrice` and seed `mfePeakPrice` to the entry price. Component C
+ *  uses these as immutable denominators / starting points for MFE tracking.
+ *  Scale-ins and partial closes preserve whatever was set on the first fill —
+ *  this helper is intentionally only called from the brand-new and flip code
+ *  paths, never from the scale-in path. */
+function seedMfeMetadata(metadata, fillPrice) {
+    const seeded = { ...(metadata ?? {}) };
+    if (seeded.originalEntryPrice === undefined) {
+        seeded.originalEntryPrice = fillPrice; // frozen R/MFE entry reference
+    }
+    if (seeded.originalStopPrice === undefined && seeded.stopPrice !== undefined) {
+        seeded.originalStopPrice = seeded.stopPrice;
+    }
+    if (seeded.mfePeakPrice === undefined) {
+        seeded.mfePeakPrice = fillPrice;
+    }
+    return seeded;
+}
+/**
+ * Compute simulated slippage for a market order (legacy mode).
+ * Returns basis points: random 0-2 bps, signed based on order side.
+ * BUY: positive slippage (pay more), SELL: negative slippage (receive less).
+ */
+export function computeSlippage(side) {
+    const bps = Math.random() * 2; // 0 to 2 bps
+    return side === 'buy' ? bps : -bps;
+}
+/**
+ * Apply slippage to a price.
+ * @param price Base price
+ * @param slippageBps Slippage in basis points (signed)
+ * @returns Adjusted price
+ */
+export function applySlippage(price, slippageBps) {
+    return price * (1 + slippageBps / 10_000);
+}
+/**
+ * Parse the base and quote currencies from a symbol like "BTC/USDT".
+ */
+export function parseSymbol(symbol) {
+    const parts = symbol.split('/');
+    if (parts.length !== 2) {
+        throw new Error(`Invalid symbol format: ${symbol}. Expected BASE/QUOTE`);
+    }
+    return { base: parts[0], quote: parts[1] };
+}
+/**
+ * Ensure a currency exists in the wallet with at least zero balance.
+ */
+function ensureCurrency(wallet, currency) {
+    if (!wallet[currency]) {
+        wallet[currency] = { total: 0, available: 0, locked: 0 };
+    }
+    return wallet[currency];
+}
+/**
+ * Fill a market order immediately at the given price (plus slippage).
+ * When realistic options are provided, uses book-aware VWAP + latency + maker/taker fees.
+ * Otherwise falls back to legacy random slippage + flat fee.
+ */
+export function fillMarketOrder(order, currentPrice, wallet, existingPosition, realistic) {
+    if (realistic?.config) {
+        // Phase 9a: Realistic fill path
+        const { fillPrice, executionQuality } = computeRealisticMarketFill(order.side, order.amount, currentPrice, realistic.orderbook ?? null, realistic.volFactor ?? 1.0, realistic.config);
+        const feeRate = getFeeRate('market', realistic.config);
+        return executeOrderFill(order, fillPrice, wallet, existingPosition, feeRate, executionQuality, realistic.metadata);
+    }
+    // Legacy path: random 0-2 bps slippage + flat 0.1% fee
+    const slippageBps = computeSlippage(order.side);
+    const fillPrice = applySlippage(currentPrice, slippageBps);
+    return executeOrderFill(order, fillPrice, wallet, existingPosition);
+}
+/**
+ * Fill a limit order (when price crosses the limit price).
+ * Limit orders fill at the limit price. When config is provided, uses maker fee rate.
+ */
+export function fillLimitOrder(order, wallet, existingPosition, config, decisionPrice, metadata) {
+    if (order.price === null) {
+        throw new Error('Limit order must have a price');
+    }
+    const feeRate = config ? getFeeRate('limit', config) : undefined;
+    const executionQuality = config && decisionPrice !== undefined
+        ? computeLimitFillQuality(order.side, order.amount, order.price, decisionPrice, config)
+        : undefined;
+    return executeOrderFill(order, order.price, wallet, existingPosition, feeRate, executionQuality, metadata);
+}
+/**
+ * Core fill logic (derivatives model).
+ * All accounting in quote currency. Both longs and shorts use USDT as collateral.
+ *
+ * Opening: deduct notional + fee from quote balance.
+ * Closing: credit (entry_notional + directional_PnL - fee) to quote balance.
+ * Flip: close existing + open opposite, fees split proportionally.
+ *
+ * Trade PnL is directional only (no fee deduction) — fees are tracked separately
+ * and already reflected in wallet balance changes.
+ *
+ * @param feeRateOverride When provided, overrides the legacy FEE_RATE (Phase 9a maker/taker)
+ * @param executionQuality When provided, attached to the Trade record (Phase 9a)
+ */
+function executeOrderFill(order, fillPrice, wallet, existingPosition, feeRateOverride, executionQuality, metadata) {
+    const { quote } = parseSymbol(order.symbol);
+    const activeFeeRate = feeRateOverride ?? FEE_RATE;
+    const notional = order.amount * fillPrice;
+    const fee = notional * activeFeeRate;
+    const now = new Date().toISOString();
+    const quoteBalance = ensureCurrency(wallet, quote);
+    let position = null;
+    let trade = null;
+    let totalWalletDelta = 0;
+    let totalFee = fee;
+    // Determine relationship to existing position
+    const isClosing = existingPosition && ((existingPosition.side === 'long' && order.side === 'sell') ||
+        (existingPosition.side === 'short' && order.side === 'buy'));
+    if (existingPosition && isClosing) {
+        // --- CLOSING / REDUCING / FLIPPING ---
+        const closeQty = Math.min(order.amount, existingPosition.quantity);
+        const closeNotional = closeQty * fillPrice;
+        const closeFee = closeNotional * activeFeeRate;
+        // Directional PnL (no fee — fee tracked separately in trade record)
+        const pnl = existingPosition.side === 'long'
+            ? (fillPrice - existingPosition.entryPrice) * closeQty
+            : (existingPosition.entryPrice - fillPrice) * closeQty;
+        // Open-side fee attributable to this close (proportional for partial closes).
+        // Older positions without `openFee` are treated as 0 (legacy roundtrip error).
+        const totalOpenFee = existingPosition.openFee ?? 0;
+        const openFeeShare = existingPosition.quantity > 0
+            ? totalOpenFee * (closeQty / existingPosition.quantity)
+            : 0;
+        // Credit: release original margin + PnL - close fee
+        const credit = existingPosition.entryPrice * closeQty + pnl - closeFee;
+        quoteBalance.available += credit;
+        quoteBalance.total += credit;
+        totalWalletDelta += credit;
+        trade = {
+            id: `trade-${order.id}`,
+            orderId: order.id,
+            symbol: order.symbol,
+            side: order.side,
+            entryPrice: existingPosition.entryPrice,
+            exitPrice: fillPrice,
+            quantity: closeQty,
+            realizedPnl: pnl,
+            fee: closeFee,
+            openFee: openFeeShare,
+            openedAt: existingPosition.openedAt,
+            closedAt: now,
+            executionQuality,
+            metadata: existingPosition.metadata,
+        };
+        const remaining = existingPosition.quantity - closeQty;
+        if (remaining > 0) {
+            // Partial close — position reduced, metadata preserved, remaining openFee proportional
+            position = {
+                ...existingPosition,
+                quantity: remaining,
+                openFee: totalOpenFee - openFeeShare,
+            };
+        }
+        else if (order.amount > existingPosition.quantity) {
+            // Flip: close existing + open opposite (must be atomic)
+            const flipQty = order.amount - existingPosition.quantity;
+            const flipNotional = flipQty * fillPrice;
+            const flipFee = flipNotional * activeFeeRate;
+            // Affordability check for the flip leg. The close credit was already
+            // applied to quoteBalance.available above, so `available` IS the true
+            // post-close figure — do NOT add `credit` again. Double-counting the
+            // released margin would pass an unaffordable flip and overdraw the
+            // wallet negative. On failure we roll the credit back below.
+            const projectedAvailable = quoteBalance.available;
+            if (projectedAvailable < flipNotional + flipFee) {
+                // Rollback the close credit already applied above
+                quoteBalance.available -= credit;
+                quoteBalance.total -= credit;
+                totalWalletDelta -= credit;
+                throw new Error(`Insufficient ${quote} balance for position flip. After closing, would have ${projectedAvailable.toFixed(2)} but need ${(flipNotional + flipFee).toFixed(2)}`);
+            }
+            quoteBalance.available -= flipNotional + flipFee;
+            quoteBalance.total -= flipNotional + flipFee;
+            totalWalletDelta -= flipNotional + flipFee;
+            // Accounting invariant: the affordability check above guarantees a
+            // non-negative balance. If this ever fires, the flip math regressed.
+            if (quoteBalance.available < -1e-6) {
+                throw new Error(`Wallet overdrawn during flip (available=${quoteBalance.available.toFixed(2)}) — accounting invariant violated`);
+            }
+            position = {
+                symbol: order.symbol,
+                side: order.side === 'buy' ? 'long' : 'short',
+                entryPrice: fillPrice,
+                quantity: flipQty,
+                openedAt: now,
+                metadata: seedMfeMetadata(metadata, fillPrice),
+                openFee: flipFee,
+            };
+            totalFee = closeFee + flipFee;
+        }
+        // else: fully closed, position remains null, totalFee = closeFee
+        else {
+            totalFee = closeFee;
+        }
+    }
+    else if (existingPosition && !isClosing) {
+        // --- ADDING TO EXISTING POSITION (same direction) ---
+        if (quoteBalance.available < notional + fee) {
+            throw new Error(`Insufficient ${quote} balance. Need ${(notional + fee).toFixed(2)}, have ${quoteBalance.available.toFixed(2)}`);
+        }
+        quoteBalance.available -= notional + fee;
+        quoteBalance.total -= notional + fee;
+        totalWalletDelta = -(notional + fee);
+        // Average entry price
+        const totalQty = existingPosition.quantity + order.amount;
+        const avgEntry = (existingPosition.entryPrice * existingPosition.quantity + fillPrice * order.amount) / totalQty;
+        // Scale-in: preserve frozen MFE state (originalStopPrice + the running
+        // peak) from the first fill, while letting the agent override mutable
+        // entry-context fields like updated stopPrice / thesis on this fill.
+        const baseMeta = existingPosition.metadata ?? {};
+        const incomingMeta = metadata ?? {};
+        const mergedMeta = {
+            ...baseMeta,
+            ...incomingMeta,
+            originalEntryPrice: baseMeta.originalEntryPrice ?? incomingMeta.originalEntryPrice,
+            originalStopPrice: baseMeta.originalStopPrice ?? incomingMeta.originalStopPrice,
+            mfePeakPrice: baseMeta.mfePeakPrice ?? incomingMeta.mfePeakPrice,
+        };
+        position = {
+            ...existingPosition,
+            entryPrice: avgEntry,
+            quantity: totalQty,
+            metadata: mergedMeta,
+            openFee: (existingPosition.openFee ?? 0) + fee,
+        };
+    }
+    else {
+        // --- NEW POSITION ---
+        if (quoteBalance.available < notional + fee) {
+            throw new Error(`Insufficient ${quote} balance. Need ${(notional + fee).toFixed(2)}, have ${quoteBalance.available.toFixed(2)}`);
+        }
+        quoteBalance.available -= notional + fee;
+        quoteBalance.total -= notional + fee;
+        totalWalletDelta = -(notional + fee);
+        position = {
+            symbol: order.symbol,
+            side: order.side === 'buy' ? 'long' : 'short',
+            entryPrice: fillPrice,
+            quantity: order.amount,
+            openedAt: now,
+            metadata: seedMfeMetadata(metadata, fillPrice),
+            openFee: fee,
+        };
+    }
+    // Build the filled order
+    const filledOrder = {
+        ...order,
+        status: 'closed',
+        filled: order.amount,
+        average: fillPrice,
+        cost: notional,
+        fee: { cost: totalFee, currency: quote },
+    };
+    const walletDeltas = {};
+    if (totalWalletDelta !== 0) {
+        walletDeltas[quote] = totalWalletDelta;
+    }
+    return { order: filledOrder, position, trade, walletDeltas, executionQuality };
+}

package/simulator/paper-market-feed.d.ts

@@ -0,0 +1,26 @@
+import type { CcxtTicker } from '../types.js';
+import type { ExchangeSimulator } from './exchange-simulator.js';
+export declare const DEFAULT_FEED_INTERVAL_MS = 5000;
+export declare const MAX_SYMBOLS_PER_TICK = 30;
+/** Narrow ticker source — only the method the feed needs. Lets tests inject a
+ *  fake without constructing a real CCXT client. */
+export interface TickerSource {
+    fetchTicker(symbol: string): Promise<CcxtTicker | null>;
+}
+export declare class PaperMarketFeed {
+    private readonly tickerSource;
+    private readonly simulator;
+    private readonly intervalMs;
+    private interval;
+    private ticking;
+    constructor(tickerSource: TickerSource, simulator: ExchangeSimulator, intervalMs?: number);
+    /** Idempotent — a second start() while running is a no-op. */
+    start(): void;
+    stop(): void;
+    isRunning(): boolean;
+    /** One refresh cycle. Exposed for tests (no setInterval). Never throws —
+     *  a fetch failure on one symbol is logged and skipped; state self-heals on
+     *  the next tick. Overlapping ticks are suppressed (a slow fetch round can
+     *  outlast the interval). */
+    tick(): Promise<void>;
+}

package/simulator/paper-market-feed.js

@@ -0,0 +1,104 @@
+// Paper-mode background market-data feed.
+//
+// WHY: in paper mode the simulator's per-symbol lastTicker map is the SOLE
+// source of mark price, unrealized PnL, NAV, MFE, the stop-watcher breach
+// check, AND the resting-limit fill trigger. Nothing else refreshes it on a
+// timer — updateTicker fires only when the agent happens to call a price tool.
+// The skill gateway poller refreshes only the ONE dashboard symbol, so every
+// other symbol the agent trades (routine — it scans/trades many pairs) had its
+// mark FROZEN at entry until the next heartbeat: the stop-watcher compared a
+// stale mark and never fired, NAV/uPnL went stale, and resting limits missed.
+//
+// This poller closes that gap: every `intervalMs` it collects the symbols with
+// an open position OR an open order and refreshes each via the simulator's
+// updateTicker (which also runs MFE + the pending-limit-fill check). It is
+// paper-only and skips entirely when the book is flat, so it adds zero Binance
+// weight when there is nothing to track.
+//
+// Weight: it reuses the single-symbol, ban-gated BinancePublicApi.fetchTicker
+// (Binance GET /fapi/v1/ticker/24hr with a symbol = weight 1) one symbol at a
+// time. For a realistic paper book (a handful of open symbols) this is lighter
+// than CCXT fetchTickers(), which hits the all-symbols endpoint (weight 40).
+import { logger, formatError } from '../logger.js';
+const TAG = 'paper-market-feed';
+// 5s: well inside the 10s stop-watcher interval (so a breach is seen with a
+// fresh mark on the next watcher tick) and trivial weight for a small book.
+export const DEFAULT_FEED_INTERVAL_MS = 5_000;
+// Defensive upper bound on symbols refreshed per tick, so a pathological book
+// can't issue an unbounded burst of reads. A real paper book is far smaller;
+// if we ever hit the cap we log it (no silent truncation).
+export const MAX_SYMBOLS_PER_TICK = 30;
+export class PaperMarketFeed {
+    tickerSource;
+    simulator;
+    intervalMs;
+    interval = null;
+    ticking = false;
+    constructor(tickerSource, simulator, intervalMs = DEFAULT_FEED_INTERVAL_MS) {
+        this.tickerSource = tickerSource;
+        this.simulator = simulator;
+        this.intervalMs = intervalMs;
+    }
+    /** Idempotent — a second start() while running is a no-op. */
+    start() {
+        if (this.interval)
+            return;
+        logger.info(TAG, `Starting paper market feed (interval: ${this.intervalMs}ms)`);
+        this.interval = setInterval(() => {
+            void this.tick();
+        }, this.intervalMs);
+    }
+    stop() {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+    }
+    isRunning() {
+        return this.interval !== null;
+    }
+    /** One refresh cycle. Exposed for tests (no setInterval). Never throws —
+     *  a fetch failure on one symbol is logged and skipped; state self-heals on
+     *  the next tick. Overlapping ticks are suppressed (a slow fetch round can
+     *  outlast the interval). */
+    async tick() {
+        if (this.ticking)
+            return;
+        this.ticking = true;
+        try {
+            const state = this.simulator.getState();
+            const symbols = new Set();
+            for (const p of state.positions)
+                symbols.add(p.symbol);
+            for (const o of state.openOrders)
+                symbols.add(o.symbol);
+            if (symbols.size === 0)
+                return; // flat — no work, no Binance weight
+            let list = Array.from(symbols);
+            if (list.length > MAX_SYMBOLS_PER_TICK) {
+                logger.warn(TAG, `Open-symbol count ${list.length} exceeds per-tick cap ${MAX_SYMBOLS_PER_TICK} — refreshing the first ${MAX_SYMBOLS_PER_TICK}; the rest refresh next tick`);
+                list = list.slice(0, MAX_SYMBOLS_PER_TICK);
+            }
+            for (const symbol of list) {
+                let ticker;
+                try {
+                    ticker = await this.tickerSource.fetchTicker(symbol);
+                }
+                catch (err) {
+                    // fetchTicker already swallows + returns null, but guard the
+                    // weight-pacer throw path too so one symbol never aborts the loop.
+                    logger.warn(TAG, `fetchTicker(${symbol}) threw: ${formatError(err)}`);
+                    continue;
+                }
+                // Reject garbage marks (a null/0 last would poison NAV / open a
+                // 0-priced fill — mirrors the simulator's own mark > 0 guard).
+                if (ticker && Number.isFinite(ticker.last) && ticker.last > 0) {
+                    this.simulator.updateTicker(ticker);
+                }
+            }
+        }
+        finally {
+            this.ticking = false;
+        }
+    }
+}

package/simulator/realistic-fills.d.ts

@@ -0,0 +1,59 @@
+import type { OrderBookDepth, SimulationConfig, ExecutionQuality } from './types.js';
+/**
+ * Walk the order book to compute a volume-weighted average fill price.
+ *
+ * For BUY: walks asks (sellers) from best ask upward.
+ * For SELL: walks bids (buyers) from best bid downward.
+ *
+ * If the order exceeds available depth, the remainder fills at the worst
+ * available price + 10 bps penalty (simulating thin-book impact).
+ *
+ * @returns { vwap, levelsConsumed, fillRatio } where fillRatio < 1 only
+ * if we want to model partial fills (currently always fills completely).
+ */
+export declare function computeBookAwareFillPrice(side: 'buy' | 'sell', amount: number, orderbook: OrderBookDepth): {
+    vwap: number;
+    levelsConsumed: number;
+};
+/**
+ * Simulate latency-induced price drift.
+ *
+ * During the latency window, the price can move against the trader.
+ * The drift is proportional to latency duration and current volatility.
+ *
+ * @param basePrice The VWAP price before latency adjustment
+ * @param side Order side (buy drift is positive, sell drift is negative)
+ * @param latencyMs Simulated latency in milliseconds
+ * @param volFactor Current volatility factor (1.0 = normal, >1 = elevated)
+ * @returns { adjustedPrice, latencyImpactBps }
+ */
+export declare function applyLatencyDrift(basePrice: number, side: 'buy' | 'sell', latencyMs: number, volFactor: number): {
+    adjustedPrice: number;
+    latencyImpactBps: number;
+};
+/**
+ * Generate a random simulated latency within the configured range.
+ */
+export declare function generateLatency(config: SimulationConfig): number;
+/**
+ * Compute the fee rate based on order type (maker vs taker).
+ * Market orders = taker. Limit orders = maker.
+ */
+export declare function getFeeRate(orderType: 'market' | 'limit', config: SimulationConfig): number;
+/**
+ * Compute a complete realistic fill for a market order.
+ *
+ * Combines: orderbook VWAP + latency drift + appropriate fee rate.
+ * Falls back to simple random slippage if no orderbook is available.
+ *
+ * @returns fillPrice and ExecutionQuality metrics
+ */
+export declare function computeRealisticMarketFill(side: 'buy' | 'sell', amount: number, decisionPrice: number, orderbook: OrderBookDepth | null, volFactor: number, config?: SimulationConfig): {
+    fillPrice: number;
+    executionQuality: ExecutionQuality;
+};
+/**
+ * Compute execution quality metrics for a limit order fill.
+ * Limit orders fill at the limit price (maker) with no market impact.
+ */
+export declare function computeLimitFillQuality(side: 'buy' | 'sell', amount: number, limitPrice: number, decisionPrice: number, config?: SimulationConfig): ExecutionQuality;