dexbot 1.1.13 → 1.2.0

package/dist/modules/order/grid.d.ts

@@ -2,7 +2,7 @@
  * modules/order/grid.ts - Grid Engine
  *
  * Order grid creation, synchronization, and health management.
- * Exports a single Grid class with static methods for grid operations.
+ * Exports plain functions for grid operations.
  *
  * Manages the complete lifecycle of the order grid:
  * - Creates geometric price grids with configurable spacing (increments)
@@ -12,7 +12,7 @@
  * - Detects and flags out-of-spread conditions
  *
  * ===============================================================================
- * TABLE OF CONTENTS - Grid Class (25 static methods)
+ * TABLE OF CONTENTS - Grid Functions (28 exported functions)
  * ===============================================================================
  *
  * CONFIGURATION & CALCULATION (2 methods)
@@ -94,456 +94,441 @@
  *
  * ===============================================================================
  */
-declare class Grid {
-    /**
-     * Calculate the spread gap size (number of empty slots between BUY and SELL rails).
-     * Delegates to utils/math for pure calculation logic.
-     *
-     * @param {number} incrementPercent
-     * @param {number} targetSpreadPercent
-     * @returns {number}
-     */
-    static calculateGapSlots(incrementPercent: any, targetSpreadPercent: any, gridLimitsOverride?: Record<string, any>): any;
-    /**
-     * Public wrapper for side sizing context.
-     * Keeps StrategyEngine decoupled from Grid private internals.
-     *
-     * @param {import('./types').OrderManager} manager
-     * @param {'buy'|'sell'} side
-     * @returns {Promise<import('./types').SizingContext|null>}
-     */
-    static getSizingContext(manager: any, side: any): Promise<{
-        budget: any;
-        precision: any;
-        config: any;
-    }>;
-    /**
-     * Unifies budget calculation and fee deduction for all grid sizing scenarios.
-     * Ensures consistent fund context (Allocated vs Total) across the bot.
-     *
-     * @param {import('./types').OrderManager} manager - OrderManager instance
-     * @param {string} side - 'buy' or 'sell'
-     * @returns {Promise<import('./types').SizingContext|null>}
-     * @private
-     */
-    static _getSizingContext(manager: any, side: any, { skipRecalc }?: {
-        skipRecalc?: boolean;
-    }): Promise<{
-        budget: any;
-        precision: any;
-        config: any;
-    }>;
-    /**
-     * Create the initial order grid structure based on configuration.
-     *
-     * ALGORITHM: Geometric Grid Creation with Fixed Spread Gap
-     * =========================================================
-     * This method generates a unified "Master Rail" of price levels with geometric spacing.
-     * The grid is centered around startPrice with a fixed-size spread gap.
-     *
-     * KEY CONCEPTS:
-     * - Geometric Spacing: Each price level is incrementPercent% away from neighbors
-     * - Master Rail: Single unified array (not separate buy/sell rails)
-     * - Spread Gap: Fixed-size buffer between best buy and best sell
-     * - Role Assignment: BUY / SPREAD / SELL based on position relative to startPrice
-     *
-     * SPREAD GAP FORMULA:
-     * ===================
-     * The spread gap size is calculated to match the target spread percentage:
-     *
-     * 1. Step Factor (s): s = 1 + (incrementPercent / 100)
-     *    Example: If incrementPercent = 0.5%, then s = 1.005
-     *
-     * 2. Minimum Spread: minSpread = incrementPercent × MIN_SPREAD_FACTOR
-     *    This ensures spread is at least 2× the increment (prevents too-narrow spread)
-     *
-     * 3. Target Steps (n): Number of price levels needed to achieve target spread
-     *    Formula: n = ceil(ln(1 + targetSpread/100) / ln(s))
-     *
-     *    Derivation: If we want price to grow by targetSpread% over n steps:
-     *    - Final price = startPrice × s^n
-     *    - Growth factor = (1 + targetSpread/100)
-     *    - Therefore: s^n = (1 + targetSpread/100)
-     *    - Taking ln: n × ln(s) = ln(1 + targetSpread/100)
-     *    - Solving: n = ln(1 + targetSpread/100) / ln(s)
-     *
-     * 4. Gap Slots (G): G = max(MIN_SPREAD_ORDERS, n)
-     *    Ensures at least MIN_SPREAD_ORDERS slots even if target spread is small
-     *
-     * EXAMPLE:
-     * --------
-     * incrementPercent = 0.5%, targetSpread = 2%
-     * - s = 1.005
-     * - minSpread = 0.5% × 2 = 1%
-     * - targetSpread = max(2%, 1%) = 2%
-     * - n = ceil(ln(1.02) / ln(1.005)) = ceil(3.98) = 4 steps
-     * - G = max(2, 4) = 4 slots
-     *
-     * @param {import('./types').GridConfig} config - Grid configuration
-     * @returns {import('./types').GridCreationResult}
-     */
-    static createOrderGrid(config: any): {
-        orders: any;
-        boundaryIdx: any;
-        initialSpreadCount: {
-            buy: number;
-            sell: number;
-        };
+export declare function calculateGapSlots(incrementPercent: any, targetSpreadPercent: any, gridLimitsOverride?: Record<string, any>): any;
+export declare function isGridBloated(manager: any, orders: any): {
+    bloated: boolean;
+    details?: undefined;
+} | {
+    bloated: boolean;
+    details: {
+        gridSize: any;
+        placedCount: number;
+        numBuyActive: number;
+        numSellActive: number;
+        gapSlots: any;
+        maxAllowed: any;
     };
-    /**
-     * Internal utility to clear all order-related manager caches.
-     * Prevents stale references during grid reinitialization.
-     * RC-2: Synchronized to prevent concurrent modifications during clear
-     *
-     * Note: Uses explicit assignment instead of .clear() to enforce COW semantics:
-     * - Replace the master grid atomically with a fresh Map instance
-     * - Avoid mutating any previously referenced Map object
-     * @param {import('./types').OrderManager} manager - OrderManager instance
-     * @private
-     */
-    static _clearOrderCachesLogic(manager: any): void;
-    /**
-     * Restore a persisted grid snapshot onto a manager instance.
-     * @param {import('./types').OrderManager} manager - The manager instance.
-     * @param {Array<import('./types').GridOrderSlot>} grid - The persisted grid array.
-     * @param {number|null} [boundaryIdx=null] - The master boundary index.
-     * @returns {Promise<void>}
-     */
-    static loadGrid(manager: any, grid: any, boundaryIdx?: any): Promise<any>;
-    /**
-     * Initialize the order grid with blockchain-aware sizing.
-     * @param {import('./types').OrderManager} manager - The manager instance.
-     * @returns {Promise<void>}
-     * @throws {Error} If initialization fails or account totals are missing.
-     */
-    static initializeGrid(manager: any): Promise<void>;
-    /**
-     * Full grid resynchronization from blockchain state.
-     * @param {import('./types').OrderManager} manager - The manager instance.
-     * @param {Object} opts - Options for resynchronization.
-     * @param {Function} opts.readOpenOrdersFn - Function to read open orders.
-     * @param {Object} opts.chainOrders - Chain orders module.
-     * @param {string} opts.account - Account name.
-     * @param {string} opts.privateKey - Private key.
-     * @returns {Promise<void>}
-     */
-    static recalculateGrid(manager: any, opts: any): Promise<void>;
-    /**
-     * Check for grid divergence and trigger update if threshold is met.
-     *
-     * @param {import('./types').OrderManager} manager - Manager instance with order state
-     * @returns {import('./types').SideUpdateFlags}
-     */
-    static checkAndUpdateGridIfNeeded(manager: any): {
-        buyUpdated: boolean;
-        sellUpdated: boolean;
+};
+/**
+ * Check whether the grid-bloat grace period is still active, i.e. a
+ * bloat detection happened recently enough that a structural resync
+ * has not had time to resolve it.
+ *
+ * Used by both Grid.loadGrid (to suppress redundant resync requests)
+ * and the maintenance runtime (to decide when to re-check after the
+ * grace window expires) so the two policies share one definition of
+ * the grace window.
+ *
+ * @param {Object} manager - OrderManager instance.
+ * @returns {{active: boolean, elapsed: number, graceMs: number}}
+ */
+export declare function isGridBloatGraceActive(manager: any): {
+    active: boolean;
+    elapsed: number;
+    graceMs: any;
+};
+/**
+ * Clear the grid-bloat detection timestamp once the grid size has
+ * returned to normal. Shared so both call sites use the same key.
+ * @param {Object} manager - OrderManager instance.
+ */
+export declare function clearGridBloatFlag(manager: any): void;
+/**
+ * Public wrapper for side sizing context.
+ * Keeps StrategyEngine decoupled from Grid private internals.
+ *
+ * @param {import('./types').OrderManager} manager
+ * @param {'buy'|'sell'} side
+ * @returns {Promise<import('./types').SizingContext|null>}
+ */
+export declare function getSizingContext(manager: any, side: any): Promise<{
+    budget: any;
+    precision: any;
+    config: any;
+}>;
+/**
+ * Unifies budget calculation and fee deduction for all grid sizing scenarios.
+ * Ensures consistent fund context (Allocated vs Total) across the bot.
+ *
+ * @param {import('./types').OrderManager} manager - OrderManager instance
+ * @param {string} side - 'buy' or 'sell'
+ * @returns {Promise<import('./types').SizingContext|null>}
+ * @private
+ */
+export declare function _getSizingContext(manager: any, side: any, { skipRecalc }?: {
+    skipRecalc?: boolean;
+}): Promise<{
+    budget: any;
+    precision: any;
+    config: any;
+}>;
+/**
+ * Create the initial order grid structure based on configuration.
+ *
+ * ALGORITHM: Geometric Grid Creation with Fixed Spread Gap
+ * =========================================================
+ * This method generates a unified "Master Rail" of price levels with geometric spacing.
+ * The grid is centered around startPrice with a fixed-size spread gap.
+ *
+ * KEY CONCEPTS:
+ * - Geometric Spacing: Each price level is incrementPercent% away from neighbors
+ * - Master Rail: Single unified array (not separate buy/sell rails)
+ * - Spread Gap: Fixed-size buffer between best buy and best sell
+ * - Role Assignment: BUY / SPREAD / SELL based on position relative to startPrice
+ *
+ * SPREAD GAP FORMULA:
+ * ===================
+ * The spread gap size is calculated to match the target spread percentage:
+ *
+ * 1. Step Factor (s): s = 1 + (incrementPercent / 100)
+ *    Example: If incrementPercent = 0.5%, then s = 1.005
+ *
+ * 2. Minimum Spread: minSpread = incrementPercent × MIN_SPREAD_FACTOR
+ *    This ensures spread is at least 2× the increment (prevents too-narrow spread)
+ *
+ * 3. Target Steps (n): Number of price levels needed to achieve target spread
+ *    Formula: n = ceil(ln(1 + targetSpread/100) / ln(s))
+ *
+ *    Derivation: If we want price to grow by targetSpread% over n steps:
+ *    - Final price = startPrice × s^n
+ *    - Growth factor = (1 + targetSpread/100)
+ *    - Therefore: s^n = (1 + targetSpread/100)
+ *    - Taking ln: n × ln(s) = ln(1 + targetSpread/100)
+ *    - Solving: n = ln(1 + targetSpread/100) / ln(s)
+ *
+ * 4. Gap Slots (G): G = max(MIN_SPREAD_ORDERS, n)
+ *    Ensures at least MIN_SPREAD_ORDERS slots even if target spread is small
+ *
+ * EXAMPLE:
+ * --------
+ * incrementPercent = 0.5%, targetSpread = 2%
+ * - s = 1.005
+ * - minSpread = 0.5% × 2 = 1%
+ * - targetSpread = max(2%, 1%) = 2%
+ * - n = ceil(ln(1.02) / ln(1.005)) = ceil(3.98) = 4 steps
+ * - G = max(2, 4) = 4 slots
+ *
+ * @param {import('./types').GridConfig} config - Grid configuration
+ * @returns {import('./types').GridCreationResult}
+ */
+export declare function createOrderGrid(config: any): {
+    orders: any;
+    boundaryIdx: any;
+    initialSpreadCount: {
+        buy: number;
+        sell: number;
     };
-    /**
-     * Standardize grid sizes using blockchain total context.
-     *
-     * FUND CAPPING STRATEGY:
-     * =====================
-     * During grid regeneration (e.g., after fills increase available funds),
-     * this method recalculates all order sizes using geometric weighting.
-     * However, ACTIVE/PARTIAL orders must not grow larger than currently available funds.
-     *
-     * Rationale for capping:
-     * 1. POST-FILL EXPANSION PREVENTION: After a large fill, funds become available.
-     *    A naive size recalculation might expand orders, consuming all new capital.
-     *    Capping prevents this "resize explosion" by limiting growth to available free balance.
-     * 2. VIRTUAL ORDER PROTECTION: Virtual orders (not yet placed) are uncapped,
-     *    allowing natural expansion when their slot comes up for placement.
-     * 3. BLOCKCHAIN-BACKED CONSTRAINT: sideFreeAvailable tracks exactly what we can spend,
-     *    decreasing as commitments grow (proportional to realized delta).
-     *
-     * Fund Capping Algorithm:
-     * ========================
-     * For each ACTIVE/PARTIAL order slot:
-     *   1. Calculate new size from geometric series
-     *   2. If delta > 0 (growth):
-     *      - affordableDelta = min(delta, sideFreeAvailable)
-     *      - Cap growth to what we actually have: newSize = currentSize + affordableDelta
-     *      - Deduct from sideFreeAvailable (this spending is now committed)
-     *   3. If delta < 0 (shrinkage):
-     *      - Release the freed capital back to sideFreeAvailable
-     *      - Allows later slots to grow into this freed capacity
-     *   4. For VIRTUAL orders (not on-chain):
-     *      - Apply new size directly (no capping)
-     *      - They will be constrained when actually placed
-     *
-     * Example (2 slots, buy side, budget=1000, simplify to linear):
-     * ========================================================
-     * Initial: slot[0]=400 (ACTIVE), slot[1]=0 (VIRTUAL), sideFree=600
-     * Recalc:  newSizes=[500, 500]
-     *
-     *   Process slot[0]:
-     *     - Type: ACTIVE, current=400, new=500, delta=+100
-     *     - affordableDelta = min(100, 600) = 100
-     *     - Apply: size=500 (full growth), sideFree=500
-     *
-     *   Process slot[1]:
-     *     - Type: VIRTUAL (not capped), current=0, new=500, delta=+500
-     *     - Apply: size=500 (no cap check)
-     *     - Result: slot[1] ready for placement, will consume from sideFree when placed
-     *
-     * @param {import('./types').OrderManager} manager - OrderManager instance
-     * @param {string} orderType - ORDER_TYPES.BUY or ORDER_TYPES.SELL
-     * @param {Object} [options] - Options object
-     * @param {import('./working_grid')} [options.workingGrid] - Working grid for COW pattern
-     * @returns {Promise<{actions: Array, changed: boolean}|undefined>} - COW result or undefined
-     * @private
-     */
-    static _recalculateGridOrderSizesFromBlockchain(manager: any, orderType: any, options?: {
-        workingGrid?: any;
-    }): Promise<{
-        actions: any[];
-        changed: boolean;
-    }>;
-    /**
-     * High-level entry for resizing grid from snapshot using COW pattern.
-     * Creates working grid, calculates new sizes, generates UPDATE actions.
-     * Master grid is only updated after successful blockchain confirmation.
-     *
-     * @param {import('./types').OrderManager} manager - Manager instance
-     * @param {string} orderType - 'buy', 'sell', or 'both' - which sides to update
-     * @param {boolean} [fromBlockchainTimer=false] - If true, skip refetch of account totals (already current)
-     * @param {number|null} [overrideBoundaryIdx=null] - Optional override for boundary index
-     * @returns {Promise<{actions: Array, workingGrid: import('./working_grid'), workingIndexes: Object, workingBoundary: number, hasWorkingChanges: boolean, aborted: boolean}|null>}
-     */
-    static updateGridFromBlockchainSnapshot(manager: any, orderType?: string, fromBlockchainTimer?: boolean, overrideBoundaryIdx?: any): Promise<{
-        actions: any[];
-        workingGrid: any;
-        workingIndexes: any;
-        workingBoundary: any;
-        hasWorkingChanges: boolean;
-        aborted: boolean;
-    }>;
-    /**
-     * Compare ideal grid vs persisted grid to detect divergence.
-     * INDEPENDENT SIDE CHECKING: Buy and sell sides are evaluated independently.
-     * Each side's RMS divergence is compared against its own threshold.
-     * Only sides exceeding the threshold are marked for update.
-     *
-     * PURPOSE: Detect if the calculated in-memory grid has diverged significantly from the
-     * persisted grid state. High divergence indicates that order fills/rotations have caused
-     * size distributions to deviate, potentially requiring grid size recalculation.
-     *
-     * METRIC: RMS (Root Mean Square) percentage of relative size differences
-     * Formula: RMS% = sqrt(mean((calculated - persisted) / persisted)²) × 100
-     * This measures the typical relative error across all orders on each side.
-     *
-     * SIDE INDEPENDENCE:
-     * - Buy side RMS is checked against GRID_COMPARISON.RMS_PERCENTAGE independently
-     * - Sell side RMS is checked against GRID_COMPARISON.RMS_PERCENTAGE independently
-     * - One side can diverge while the other remains stable (no update for stable side)
-     *
-     * RC-4: Atomic snapshot taking prevents stale data from concurrent fill operations
-     *   - Grids are snapshotted atomically before comparison
-     *   - Prevents mixing old and new grid state
-     *   - Ensures consistent RMS metrics across both sides
-     *
-     * @param {Array<import('./types').GridOrderSlot>} calculatedGrid - Ideal calculated grid
-     * @param {Array<import('./types').GridOrderSlot>} persistedGrid - Persisted grid state
-     * @param {import('./types').OrderManager|null} [manager=null] - Manager instance (for grid lock access)
-     * @returns {Promise<import('./types').GridComparisonResult>}
-     */
-    static compareGrids(calculatedGrid: any, persistedGrid: any, manager?: any): Promise<{
-        buy: {
-            metric: number;
-            updated: boolean;
-        };
-        sell: {
-            metric: number;
-            updated: boolean;
-        };
-        totalMetric?: undefined;
-    } | {
-        buy: {
-            metric: any;
-            updated: boolean;
-        };
-        sell: {
-            metric: any;
-            updated: boolean;
-        };
-        totalMetric: number;
-    }>;
-    /**
-     * Unified divergence monitoring.
-     * Performs both Ratio-based and RMS-based divergence checks.
-     *
-     * @param {import('./types').OrderManager} manager - Manager instance
-     * @param {Array<import('./types').GridOrderSlot>} calculatedGrid - Ideal/calculated grid
-     * @param {Array<import('./types').GridOrderSlot>} persistedGrid - Current/persisted grid
-     * @returns {Promise<import('./types').DivergenceResult>}
-     */
-    static monitorDivergence(manager: any, calculatedGrid: any, persistedGrid: any): Promise<{
-        needsUpdate: boolean;
-        buy: {
-            updated: boolean;
-            ratio: boolean;
-            rms: boolean;
-            metric: any;
-        };
-        sell: {
-            updated: boolean;
-            ratio: boolean;
-            rms: boolean;
-            metric: any;
-        };
-        orderType: any;
-    }>;
-    /**
-     * Collect on-chain buy and sell orders from the manager.
-     * Filters to orders with valid orderId and positive size.
-     * @param {import('./types').OrderManager} manager - The manager instance.
-     * @returns {{onChainBuys: Array<import('./types').Order>, onChainSells: Array<import('./types').Order>}}
-     */
-    static _getOnChainOrders(manager: any): {
-        onChainBuys: any[];
-        onChainSells: any[];
+};
+/**
+ * Restore a persisted grid snapshot onto a manager instance.
+ * @param {import('./types').OrderManager} manager - The manager instance.
+ * @param {Array<import('./types').GridOrderSlot>} grid - The persisted grid array.
+ * @param {number|null} [boundaryIdx=null] - The master boundary index.
+ * @returns {Promise<void>}
+ */
+export declare function loadGrid(manager: any, grid: any, boundaryIdx?: any): Promise<any>;
+/**
+ * Initialize the order grid with blockchain-aware sizing.
+ * @param {import('./types').OrderManager} manager - The manager instance.
+ * @returns {Promise<void>}
+ * @throws {Error} If initialization fails or account totals are missing.
+ */
+export declare function initializeGrid(manager: any): Promise<void>;
+/**
+ * Full grid resynchronization from blockchain state.
+ * @param {import('./types').OrderManager} manager - The manager instance.
+ * @param {Object} opts - Options for resynchronization.
+ * @param {Function} opts.readOpenOrdersFn - Function to read open orders.
+ * @param {Object} opts.chainOrders - Chain orders module.
+ * @param {string} opts.account - Account name.
+ * @param {string} opts.privateKey - Private key.
+ * @returns {Promise<void>}
+ */
+export declare function recalculateGrid(manager: any, opts: any): Promise<void>;
+/**
+ * Check for grid divergence and trigger update if threshold is met.
+ *
+ * @param {import('./types').OrderManager} manager - Manager instance with order state
+ * @returns {import('./types').SideUpdateFlags}
+ */
+export declare function checkAndUpdateGridIfNeeded(manager: any): {
+    buyUpdated: boolean;
+    sellUpdated: boolean;
+};
+/**
+ * Standardize grid sizes using blockchain total context.
+ *
+ * FUND CAPPING STRATEGY:
+ * =====================
+ * During grid regeneration (e.g., after fills increase available funds),
+ * this method recalculates all order sizes using geometric weighting.
+ * However, ACTIVE/PARTIAL orders must not grow larger than currently available funds.
+ *
+ * Rationale for capping:
+ * 1. POST-FILL EXPANSION PREVENTION: After a large fill, funds become available.
+ *    A naive size recalculation might expand orders, consuming all new capital.
+ *    Capping prevents this "resize explosion" by limiting growth to available free balance.
+ * 2. VIRTUAL ORDER PROTECTION: Virtual orders (not yet placed) are uncapped,
+ *    allowing natural expansion when their slot comes up for placement.
+ * 3. BLOCKCHAIN-BACKED CONSTRAINT: sideFreeAvailable tracks exactly what we can spend,
+ *    decreasing as commitments grow (proportional to realized delta).
+ *
+ * Fund Capping Algorithm:
+ * ========================
+ * For each ACTIVE/PARTIAL order slot:
+ *   1. Calculate new size from geometric series
+ *   2. If delta > 0 (growth):
+ *      - affordableDelta = min(delta, sideFreeAvailable)
+ *      - Cap growth to what we actually have: newSize = currentSize + affordableDelta
+ *      - Deduct from sideFreeAvailable (this spending is now committed)
+ *   3. If delta < 0 (shrinkage):
+ *      - Release the freed capital back to sideFreeAvailable
+ *      - Allows later slots to grow into this freed capacity
+ *   4. For VIRTUAL orders (not on-chain):
+ *      - Apply new size directly (no capping)
+ *      - They will be constrained when actually placed
+ *
+ * Example (2 slots, buy side, budget=1000, simplify to linear):
+ * ========================================================
+ * Initial: slot[0]=400 (ACTIVE), slot[1]=0 (VIRTUAL), sideFree=600
+ * Recalc:  newSizes=[500, 500]
+ *
+ *   Process slot[0]:
+ *     - Type: ACTIVE, current=400, new=500, delta=+100
+ *     - affordableDelta = min(100, 600) = 100
+ *     - Apply: size=500 (full growth), sideFree=500
+ *
+ *   Process slot[1]:
+ *     - Type: VIRTUAL (not capped), current=0, new=500, delta=+500
+ *     - Apply: size=500 (no cap check)
+ *     - Result: slot[1] ready for placement, will consume from sideFree when placed
+ *
+ * @param {import('./types').OrderManager} manager - OrderManager instance
+ * @param {string} orderType - ORDER_TYPES.BUY or ORDER_TYPES.SELL
+ * @param {Object} [options] - Options object
+ * @param {import('./working_grid')} [options.workingGrid] - Working grid for COW pattern
+ * @returns {Promise<{actions: Array, changed: boolean}|undefined>} - COW result or undefined
+ * @private
+ */
+export declare function _recalculateGridOrderSizesFromBlockchain(manager: any, orderType: any, options?: {
+    workingGrid?: any;
+}): Promise<{
+    actions: any[];
+    changed: boolean;
+}>;
+/**
+ * High-level entry for resizing grid from snapshot using COW pattern.
+ * Creates working grid, calculates new sizes, generates UPDATE actions.
+ * Master grid is only updated after successful blockchain confirmation.
+ *
+ * @param {import('./types').OrderManager} manager - Manager instance
+ * @param {string} orderType - 'buy', 'sell', or 'both' - which sides to update
+ * @param {boolean} [fromBlockchainTimer=false] - If true, skip refetch of account totals (already current)
+ * @param {number|null} [overrideBoundaryIdx=null] - Optional override for boundary index
+ * @returns {Promise<{actions: Array, workingGrid: import('./working_grid'), workingIndexes: Object, workingBoundary: number, hasWorkingChanges: boolean, aborted: boolean}|null>}
+ */
+export declare function updateGridFromBlockchainSnapshot(manager: any, orderType?: string, fromBlockchainTimer?: boolean, overrideBoundaryIdx?: any): Promise<{
+    actions: any[];
+    workingGrid: any;
+    workingIndexes: any;
+    workingBoundary: any;
+    hasWorkingChanges: boolean;
+    aborted: boolean;
+}>;
+/**
+ * Compare ideal grid vs persisted grid to detect divergence.
+ * INDEPENDENT SIDE CHECKING: Buy and sell sides are evaluated independently.
+ * Each side's RMS divergence is compared against its own threshold.
+ * Only sides exceeding the threshold are marked for update.
+ *
+ * PURPOSE: Detect if the calculated in-memory grid has diverged significantly from the
+ * persisted grid state. High divergence indicates that order fills/rotations have caused
+ * size distributions to deviate, potentially requiring grid size recalculation.
+ *
+ * METRIC: RMS (Root Mean Square) percentage of relative size differences
+ * Formula: RMS% = sqrt(mean((calculated - persisted) / persisted)²) × 100
+ * This measures the typical relative error across all orders on each side.
+ *
+ * SIDE INDEPENDENCE:
+ * - Buy side RMS is checked against GRID_COMPARISON.RMS_PERCENTAGE independently
+ * - Sell side RMS is checked against GRID_COMPARISON.RMS_PERCENTAGE independently
+ * - One side can diverge while the other remains stable (no update for stable side)
+ *
+ * RC-4: Atomic snapshot taking prevents stale data from concurrent fill operations
+ *   - Grids are snapshotted atomically before comparison
+ *   - Prevents mixing old and new grid state
+ *   - Ensures consistent RMS metrics across both sides
+ *
+ * @param {Array<import('./types').GridOrderSlot>} calculatedGrid - Ideal calculated grid
+ * @param {Array<import('./types').GridOrderSlot>} persistedGrid - Persisted grid state
+ * @param {import('./types').OrderManager|null} [manager=null] - Manager instance (for grid lock access)
+ * @returns {Promise<import('./types').GridComparisonResult>}
+ */
+export declare function compareGrids(calculatedGrid: any, persistedGrid: any, manager?: any): Promise<{
+    buy: {
+        metric: number;
+        updated: boolean;
+    };
+    sell: {
+        metric: number;
+        updated: boolean;
+    };
+    totalMetric?: undefined;
+} | {
+    buy: {
+        metric: any;
+        updated: boolean;
+    };
+    sell: {
+        metric: any;
+        updated: boolean;
     };
-    /**
-     * Calculate current market spread using on-chain orders.
-     * @param {import('./types').OrderManager} manager - The manager instance.
-     * @returns {number} The calculated spread percentage.
-     */
-    static calculateCurrentSpread(manager: any): any;
-    /**
-     * Proactive spread correction check.
-     *
-     * CRITICAL: Uses AsyncLock to prevent race conditions with fill processing.
-     * Without the lock, a TOCTOU (Time-Of-Check-To-Use) vulnerability exists where:
-     * - Fund snapshot is taken (check phase)
-     * - Fill processor modifies funds in another thread
-     * - Order is placed based on stale funds (use phase)
-     * Result: Orders placed beyond available liquidity, fund accounting errors
-     *
-     * DESIGN DECISION: Lock is released before blockchain operations for performance
-     * - Lock held: Fund verification and correction decision (synchronized)
-     * - Lock released: Blockchain submission (async, potentially slow)
-     * - RACE CONDITION WINDOW: Between lock release and blockchain submission
-     * - MITIGATION: Pre-flight fund verification before submission; comprehensive error handling
-     *
-     * See RACE_CONDITION_ANALYSIS.md for detailed vulnerability documentation.
-     *
-     * @param {import('./types').OrderManager} manager - Manager instance
-     * @param {Object} BitShares - BitShares API client
-     * @param {Function|null} [updateOrdersOnChainBatch=null] - Optional batch update function
-     * @returns {Promise<import('./types').SpreadCheckResult>}
-     */
-    static checkSpreadCondition(manager: any, BitShares: any, updateOrdersOnChainBatch?: any): Promise<{
-        ordersPlaced: any;
-        partialsMoved: any;
-    }>;
-    /**
-     * Grid health check for structural violations.
-     * Monitors for "Dust Partials" that are too small to be traded on-chain,
-     * scoped to the active buy/sell window.
-     *
-     * NOTE: Internal gaps (virtual slots between active ones) are no longer
-     * flagged as violations. The "Edge-First" placement strategy intentionally
-     * creates these gaps to maximize grid coverage during fund expansion.
-     *
-     * @param {import('./types').OrderManager} manager - The manager instance.
-     * @param {Function|null} [updateOrdersOnChainBatch=null] - Optional batch update function.
-     * @returns {Promise<import('./types').DustCheckResult>}
-     */
-    static checkGridHealth(manager: any, updateOrdersOnChainBatch?: any): Promise<{
-        buyDust: boolean;
-        sellDust: boolean;
-        buyDustOrders: any;
-        sellDustOrders: any;
-    }>;
-    /**
-     * Dust check covering all partial orders, with interior-only guard.
-     *
-     * The top-of-window partial (closest to market) is always eligible for dust
-     * detection since cancelling it is just the grid edge moving inward.
-     *
-     * Interior partials (further from market) are only eligible if they have a
-     * duplicate price level — another active order at essentially the same price.
-     * Cancelling such an interior partial won't leave a gap in the grid because
-     * the sibling active order already covers that price level.
-     *
-     * Returns boolean flags plus the actual dust order objects so callers can act
-     * on individual orders (e.g. DUST_CANCEL_DELAY_SEC auto-cancel).
-     *
-     * @param {import('./types').OrderManager} manager
-     * @returns {Promise<import('./types').DustCheckResult>}
-     */
-    static checkWindowDust(manager: any): Promise<{
-        buyDust: boolean;
-        sellDust: boolean;
-        buyDustOrders: any;
-        sellDustOrders: any;
-    }>;
-    /**
-     * Return the subset of partial orders that qualify as dust on a given side.
-     * Shares the same sizing context as _hasAnyDust but returns the actual order
-     * objects so callers can act on them (e.g. auto-cancel).
-     * @private
-     * @param {import('./types').OrderManager} manager
-     * @param {Array<import('./types').GridOrderSlot>} partials - Candidate partial orders to test.
-     * @param {string} type - ORDER_TYPES.BUY or ORDER_TYPES.SELL
-     * @returns {Promise<Array<import('./types').GridOrderSlot>>} Orders whose size is below the dust threshold.
-     */
-    static _getDustOrders(manager: any, partials: any, type: any): Promise<any>;
-    /**
-     * Check if any partial orders on a side represent "dust" that should be cleaned.
-     * @param {import('./types').OrderManager} manager - Manager instance
-     * @param {Array<import('./types').GridOrderSlot>} partials - Partial orders to check
-     * @param {string} type - ORDER_TYPES.BUY or ORDER_TYPES.SELL
-     * @returns {Promise<boolean>} true if dust partials exist
-     * @private
-     */
-    static _hasAnyDust(manager: any, partials: any, type: any): Promise<boolean>;
-    /**
-     * Public dust helper shared by StrategyEngine and Grid health checks.
-     * @param {import('./types').OrderManager} manager
-     * @param {Array<import('./types').GridOrderSlot>} partials
-     * @param {'buy'|'sell'} side
-     * @returns {Promise<boolean>}
-     */
-    static hasAnyDust(manager: any, partials: any, side: any): Promise<boolean>;
-    /**
-     * Public dust helper that returns the subset of candidate partials currently below
-     * the configured dust threshold for the requested side.
-     * @param {import('./types').OrderManager} manager
-     * @param {Array<import('./types').GridOrderSlot>} partials
-     * @param {'buy'|'sell'} side
-     * @returns {Promise<Array<import('./types').GridOrderSlot>>}
-     */
-    static getDustOrders(manager: any, partials: any, side: any): Promise<any>;
-    /**
-     * Determine which side has more available funds for spread correction.
-     * @param {import('./types').OrderManager} manager - The manager instance.
-     * @param {number} currentMarketPrice - Last traded price in B/A format (e.g. BTS/XRP), used to
-     *   normalize sell-side funds into buy-side units for a fair cross-asset comparison.
-     * @returns {{ side: import('./types').OrderType|null, reason: string }} The side to correct on, or null if insufficient funds.
-     */
-    static determineOrderSideByFunds(manager: any, currentMarketPrice: any): {
-        side: any;
-        reason: string;
+    totalMetric: number;
+}>;
+/**
+ * Unified divergence monitoring.
+ * Performs both Ratio-based and RMS-based divergence checks.
+ *
+ * @param {import('./types').OrderManager} manager - Manager instance
+ * @param {Array<import('./types').GridOrderSlot>} calculatedGrid - Ideal/calculated grid
+ * @param {Array<import('./types').GridOrderSlot>} persistedGrid - Current/persisted grid
+ * @returns {Promise<import('./types').DivergenceResult>}
+ */
+export declare function monitorDivergence(manager: any, calculatedGrid: any, persistedGrid: any): Promise<{
+    needsUpdate: boolean;
+    buy: {
+        updated: boolean;
+        ratio: boolean;
+        rms: boolean;
+        metric: any;
     };
-    /**
-     * Calculate the geometric ideal size for a new order being placed during spread correction.
-     * @param {import('./types').OrderManager} manager - The manager instance.
-     * @param {import('./types').OrderType} targetType - The type of order being placed (ORDER_TYPES.BUY or ORDER_TYPES.SELL).
-     * @returns {Promise<number|null>} The calculated geometric size.
-     */
-    static calculateGeometricSizeForSpreadCorrection(manager: any, targetType: any): Promise<any>;
-    /**
-     * Prepares one or more orders to correct a wide spread.
-     * @param {import('./types').OrderManager} manager - The OrderManager instance.
-     * @param {string} preferredSide - The side to place the correction on (ORDER_TYPES.BUY/SELL).
-     * @returns {Promise<import('./types').SpreadCorrectionResult>}
-     * @throws {Error} If preferredSide is invalid.
-     */
-    static prepareSpreadCorrectionOrders(manager: any, preferredSide: any): Promise<{
-        ordersToPlace: any[];
-        ordersToUpdate: any[];
-    }>;
-}
-export = Grid;
+    sell: {
+        updated: boolean;
+        ratio: boolean;
+        rms: boolean;
+        metric: any;
+    };
+    orderType: any;
+}>;
+/**
+ * Calculate current market spread using on-chain orders.
+ * @param {import('./types').OrderManager} manager - The manager instance.
+ * @returns {number} The calculated spread percentage.
+ */
+export declare function calculateCurrentSpread(manager: any): any;
+/**
+ * Proactive spread correction check.
+ *
+ * CRITICAL: Uses AsyncLock to prevent race conditions with fill processing.
+ * Without the lock, a TOCTOU (Time-Of-Check-To-Use) vulnerability exists where:
+ * - Fund snapshot is taken (check phase)
+ * - Fill processor modifies funds in another thread
+ * - Order is placed based on stale funds (use phase)
+ * Result: Orders placed beyond available liquidity, fund accounting errors
+ *
+ * DESIGN DECISION: Lock is released before blockchain operations for performance
+ * - Lock held: Fund verification and correction decision (synchronized)
+ * - Lock released: Blockchain submission (async, potentially slow)
+ * - RACE CONDITION WINDOW: Between lock release and blockchain submission
+ * - MITIGATION: Pre-flight fund verification before submission; comprehensive error handling
+ *
+ * See RACE_CONDITION_ANALYSIS.md for detailed vulnerability documentation.
+ *
+ * @param {import('./types').OrderManager} manager - Manager instance
+ * @param {Object} BitShares - BitShares API client
+ * @param {Function|null} [updateOrdersOnChainBatch=null] - Optional batch update function
+ * @returns {Promise<import('./types').SpreadCheckResult>}
+ */
+export declare function checkSpreadCondition(manager: any, BitShares: any, updateOrdersOnChainBatch?: any): Promise<{
+    ordersPlaced: any;
+    partialsMoved: any;
+}>;
+/**
+ * Grid health check for structural violations.
+ * Monitors for "Dust Partials" that are too small to be traded on-chain,
+ * scoped to the active buy/sell window.
+ *
+ * NOTE: Internal gaps (virtual slots between active ones) are no longer
+ * flagged as violations. The "Edge-First" placement strategy intentionally
+ * creates these gaps to maximize grid coverage during fund expansion.
+ *
+ * @param {import('./types').OrderManager} manager - The manager instance.
+ * @param {Function|null} [updateOrdersOnChainBatch=null] - Optional batch update function.
+ * @returns {Promise<import('./types').DustCheckResult>}
+ */
+export declare function checkGridHealth(manager: any, updateOrdersOnChainBatch?: any): Promise<{
+    buyDust: boolean;
+    sellDust: boolean;
+    buyDustOrders: any;
+    sellDustOrders: any;
+}>;
+/**
+ * Dust check covering all partial orders, with interior-only guard.
+ *
+ * The top-of-window partial (closest to market) is always eligible for dust
+ * detection since cancelling it is just the grid edge moving inward.
+ *
+ * Interior partials (further from market) are only eligible if they have a
+ * duplicate price level — another active order at essentially the same price.
+ * Cancelling such an interior partial won't leave a gap in the grid because
+ * the sibling active order already covers that price level.
+ *
+ * Returns boolean flags plus the actual dust order objects so callers can act
+ * on individual orders (e.g. DUST_CANCEL_DELAY_SEC auto-cancel).
+ *
+ * @param {import('./types').OrderManager} manager
+ * @returns {Promise<import('./types').DustCheckResult>}
+ */
+export declare function checkWindowDust(manager: any): Promise<{
+    buyDust: boolean;
+    sellDust: boolean;
+    buyDustOrders: any;
+    sellDustOrders: any;
+}>;
+/**
+ * Public dust helper shared by StrategyEngine and Grid health checks.
+ * @param {import('./types').OrderManager} manager
+ * @param {Array<import('./types').GridOrderSlot>} partials
+ * @param {'buy'|'sell'} side
+ * @returns {Promise<boolean>}
+ */
+export declare function hasAnyDust(manager: any, partials: any, side: any): Promise<boolean>;
+/**
+ * Public dust helper that returns the subset of candidate partials currently below
+ * the configured dust threshold for the requested side.
+ * @param {import('./types').OrderManager} manager
+ * @param {Array<import('./types').GridOrderSlot>} partials
+ * @param {'buy'|'sell'} side
+ * @returns {Promise<Array<import('./types').GridOrderSlot>>}
+ */
+export declare function getDustOrders(manager: any, partials: any, side: any): Promise<any>;
+/**
+ * Determine which side has more available funds for spread correction.
+ * @param {import('./types').OrderManager} manager - The manager instance.
+ * @param {number} currentMarketPrice - Last traded price in B/A format (e.g. BTS/XRP), used to
+ *   normalize sell-side funds into buy-side units for a fair cross-asset comparison.
+ * @returns {{ side: import('./types').OrderType|null, reason: string }} The side to correct on, or null if insufficient funds.
+ */
+export declare function determineOrderSideByFunds(manager: any, currentMarketPrice: any): {
+    side: any;
+    reason: string;
+};
+/**
+ * Calculate the geometric ideal size for a new order being placed during spread correction.
+ * @param {import('./types').OrderManager} manager - The manager instance.
+ * @param {import('./types').OrderType} targetType - The type of order being placed (ORDER_TYPES.BUY or ORDER_TYPES.SELL).
+ * @returns {Promise<number|null>} The calculated geometric size.
+ */
+export declare function calculateGeometricSizeForSpreadCorrection(manager: any, targetType: any): Promise<any>;
+/**
+ * Prepares one or more orders to correct a wide spread.
+ * @param {import('./types').OrderManager} manager - The OrderManager instance.
+ * @param {string} preferredSide - The side to place the correction on (ORDER_TYPES.BUY/SELL).
+ * @returns {Promise<import('./types').SpreadCorrectionResult>}
+ * @throws {Error} If preferredSide is invalid.
+ */
+export declare function prepareSpreadCorrectionOrders(manager: any, preferredSide: any): Promise<{
+    ordersToPlace: any[];
+    ordersToUpdate: any[];
+}>;
 //# sourceMappingURL=grid.d.ts.map