dexbot 1.1.10

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

@@ -0,0 +1,386 @@
+/**
+ * modules/order/sync_engine.ts - SyncEngine
+ *
+ * Blockchain synchronization and reconciliation engine.
+ * Exports a single SyncEngine class handling all blockchain state matching.
+ *
+ * Responsibilities:
+ * - Match blockchain open orders to grid orders
+ * - Detect and handle partial fills
+ * - Process fill history events
+ * - Update fund state based on blockchain
+ * - Fetch and cache account balances
+ * - Initialize asset metadata
+ *
+ * Uses AsyncLock to prevent concurrent sync operations (defense-in-depth locking).
+ *
+ * ===============================================================================
+ * TABLE OF CONTENTS - SyncEngine Class (8 methods) + 1 module-level helper
+ * ===============================================================================
+ *
+ * MODULE-LEVEL HELPER (internal, not exported):
+ *   hasEquivalentRawOnChainOrder(a, b) - Compare two chain orders for equivalence
+ *      Used internally during sync to detect redundant/duplicate chain entries
+ *
+ * INITIALIZATION (1 method)
+ *   1. constructor(manager) - Create new SyncEngine with manager reference
+ *
+ * BLOCKCHAIN SYNCHRONIZATION (3 methods - async)
+ *   2. syncFromOpenOrders(chainOrders, options) - Main sync entry point (async)
+ *      Reconciles grid against fresh blockchain snapshot
+ *      Uses AsyncLock to ensure only one sync at a time (defense-in-depth)
+ *      Performs two-pass reconciliation (grid→chain, then chain→grid)
+ *
+ *   3. _doSyncFromOpenOrders(chainOrders, options) - Execute sync with locking (async, internal)
+ *      Acquires _syncLock, validates chain orders, calls _performSyncFromOpenOrders
+ *
+ *   4. _performSyncFromOpenOrders(mgr, precA, precB, parsedChain, rawChain, options) - Core sync logic (internal)
+ *      Performs actual two-pass reconciliation without locking
+ *      Pass 1: Match grid orders to chain (known grid → chain, includes orphan cleanup)
+ *      Pass 2: Add missing chain orders (unknown chain → grid)
+ *
+ * FILL PROCESSING (1 method)
+ *   5. syncFromFillHistory(fill) - Process fill event synchronously
+ *      Updates grid order state based on fill data
+ *      Updates fund state and accounting
+ *      Handles both maker and taker fills
+ *
+ * FULL SYNCHRONIZATION (1 method - async)
+ *   6. synchronizeWithChain(chainData, source) - Full sync (fetch + sync) (async)
+ *      Fetches fresh account balances
+ *      Calls syncFromOpenOrders() with chain data
+ *      Source: event type that triggered sync (fill, poll, broadcast, etc.)
+ *
+ * ACCOUNT STATE (2 methods - async)
+ *   7. fetchAccountBalancesAndSetTotals(accountId) - Fetch account totals (async)
+ *      Retrieves BUY/SELL totals and free balances from blockchain
+ *      Sets manager.accountTotals
+ *      Triggers fund recalculation
+ *
+ *   8. initializeAssets() - Initialize asset metadata (async)
+ *      Fetches asset precision and other metadata
+ *      Sets manager.assets
+ *      Called once at bot startup
+ *
+ * ===============================================================================
+ *
+ * LOCK HIERARCHY:
+ * 1. _syncLock (AsyncLock): Ensures only one full-sync at a time
+ * 2. Per-order locks (shadowOrderIds): Protect specific orders during sync
+ * 3. Lock refresh mechanism: Prevents timeout during long reconciliation
+ *
+ * TWO-PASS RECONCILIATION:
+ * PASS 1: Grid → Chain
+ * - For each grid order with orderId, find matching chain order
+ * - Detect partial fills (chain size < grid size)
+ * - Update sizes and mark as filled if needed
+ * - Downgrade to VIRTUAL if not found on-chain
+ *
+ * PASS 2: Chain → Grid
+ * - For each chain order not matched to grid order
+ * - Create new grid order for unexpected chain order
+ * - Mark as ACTIVE with blockchain orderId
+ *
+ * ===============================================================================
+ */
+declare class SyncEngine {
+    private manager;
+    /**
+     * @param {Object} manager - OrderManager instance
+     */
+    constructor(manager: any);
+    /**
+     * Reconcile grid orders against fresh blockchain open orders snapshot.
+     * This is the MAIN SYNCHRONIZATION MECHANISM that corrects the grid state when
+     * the blockchain state diverges from our local expectations.
+     *
+     * CRITICAL: This method uses AsyncLock (defense-in-depth) to ensure only one
+     * full-sync operation runs at a time. WITHIN that lock, per-order locks prevent
+     * concurrent createOrder/cancelOrder races.
+     *
+     * LOCK HIERARCHY:
+     * 1. _syncLock (AsyncLock): Ensures only one full-sync at a time
+     * 2. Per-order locks (shadowOrderIds): Protect specific orders during sync
+     * 3. Lock refresh mechanism: Prevents timeout during long reconciliation
+     *
+     * RECONCILIATION FLOW:
+     * ========================================================================
+     * This method performs a two-pass reconciliation:
+     *
+     * PASS 1: Match grid orders to chain orders (known grid → chain lookup)
+     * - For each grid order with an orderId, find the matching chain order
+     * - Detect partial fills: if chain size < grid size, downgrade to PARTIAL state
+     * - Detect full fills: if order no longer exists on chain, convert to SPREAD
+     * - Detect price slippage: flag orders for price correction if needed
+     * - Update grid order sizes to match chain reality
+     *
+     * PASS 2: Orphan chain orders (chain → grid lookup)
+     * - For chain orders not matched in Pass 1, find best grid slot match
+     * - This handles cases where an order was placed but grid lost track (race condition)
+     * - Uses price tolerance and geometric proximity to find the best match
+     * - Once matched, retroactively assign orderId and synchronize state
+     *
+     * CRITICAL RULES:
+     * 1. ACTIVE orders can only stay ACTIVE if size matches chain exactly
+     *    If chain size < grid size → must transition to PARTIAL
+     * 2. If an ACTIVE order is not found on chain → it filled → convert to SPREAD
+     * 3. Precision matters: Use blockchain integer arithmetic to compare sizes
+     *    Floating point comparisons can give false positives for partial fills
+     * 4. Size updates are applied via applyChainSizeToGridOrder() which handles
+     *    precision conversion and may adjust sizes slightly for blockchain granularity
+     *
+      * PRICE TOLERANCE CALCULATION:
+      * calculatePriceTolerance() can return null in these cases:
+      *   1. assets parameter is null/missing
+      *   2. gridPrice is 0 or null (invalid price)
+      *   3. orderSize is 0 or null (invalid size - orders should not sync with 0 size)
+      *   4. assetA or assetB precision is undefined (asset metadata not loaded)
+      * When tolerance is null, we treat it as 0 (strict: any price difference flagged).
+      * This is safe because null signals a configuration/data issue, not a real order.
+      *
+      * RETURNS: { filledOrders, updatedOrders, ordersNeedingCorrection }
+      * - filledOrders: Orders that completed (now SPREAD placeholders)
+      * - updatedOrders: All orders modified during sync (state changes, size updates)
+      * - ordersNeedingCorrection: Orders with price slippage requiring correction
+     *
+     * EDGE CASES HANDLED:
+     * - Orphan chain orders (placed but grid lost track due to race condition)
+     * - Partial fills (size reduced on chain)
+     * - Full fills (order removed from chain completely)
+     * - Price tolerance (small slippage acceptable, large slippage flagged)
+     * - Precision mismatches (blockchain integer precision vs float grid)
+     * - Double spending prevention (each chain order matched to at most one grid order)
+     */
+    /**
+     * Synchronize grid orders with blockchain open orders snapshot.
+     * @param {Array|null} chainOrders - Array of blockchain order objects
+     * @param {Object} [options={}] - Sync options (e.g., { skipAccounting: true })
+     * @returns {Promise<Object>} Result with filledOrders, updatedOrders, ordersNeedingCorrection
+     */
+    syncFromOpenOrders(chainOrders: any[] | null, options?: Record<string, any>): Promise<any>;
+    /**
+     * Internal method that performs the actual sync logic within lock context.
+     *
+     * This is the core synchronization implementation that runs inside _syncLock
+     * to ensure exclusive access. It validates inputs, parses chain orders, and
+     * delegates to _performSyncFromOpenOrders for the actual reconciliation.
+     *
+     * VALIDATION CHECKS:
+     * - Manager must be initialized
+     * - Chain orders must be a valid array
+     * - Manager.orders must be initialized as Map
+     * - Asset precisions must be available
+     *
+     * PARSING:
+     * Converts raw blockchain order objects to normalized format using parseChainOrder()
+     * with appropriate asset precision.
+     *
+     * @param {Array<Object>|null} chainOrders - Array of raw blockchain order objects
+     *   Each object contains sell_price, for_sale, id, etc. from blockchain
+     * @param {Object} options - Sync options
+     *   - validateOnly {boolean}: If true, only validate without applying changes
+     *   - skipFundRecalc {boolean}: If true, skip fund recalculation after sync
+     * @returns {Promise<Object>} Sync result:
+     *   - filledOrders {Array}: Orders that were detected as filled
+     *   - updatedOrders {Array}: Orders that were updated during sync
+     *   - ordersNeedingCorrection {Array}: Orders flagged for price correction
+     * @async
+     * @private
+     */
+    _doSyncFromOpenOrders(chainOrders: any[] | null, options: Record<string, any>): Promise<{
+        filledOrders: any[];
+        updatedOrders: any[];
+        ordersNeedingCorrection: any[];
+        unmatchedChainOrders: any[];
+    }>;
+    /**
+     * Internal two-pass reconciliation with locks already held.
+     * @param {Object} mgr - OrderManager instance
+     * @param {number} assetAPrecision - Asset A precision
+     * @param {number} assetBPrecision - Asset B precision
+     * @param {Map<string, import('./types').ParsedChainOrder>} parsedChainOrders - Parsed chain orders by ID
+     * @param {Map<string, Object>} rawChainOrders - Raw blockchain order objects by ID
+     * @param {Set<string>} chainOrderIdsOnGrid - Output set: chain order IDs matched to grid
+     * @param {Set<string>} matchedGridOrderIds - Output set: grid order IDs matched to chain
+     * @param {Array<Object>} filledOrders - Output array: orders detected as filled
+     * @param {Array<Object>} updatedOrders - Output array: orders updated during sync
+     * @param {Array<Object>} ordersNeedingCorrection - Output array: orders flagged for price correction
+     * @param {Array<Object>} unmatchedChainOrders - Output array: open chain orders with no adoptable grid slot
+     * @param {Object} options - Sync options (skipAccounting, etc.)
+     * @returns {Promise<{filledOrders: Array, updatedOrders: Array, ordersNeedingCorrection: Array, unmatchedChainOrders: Array}>}
+     */
+    _performSyncFromOpenOrders(mgr: any, assetAPrecision: number, assetBPrecision: number, parsedChainOrders: Map<string, any>, rawChainOrders: Map<string, any>, chainOrderIdsOnGrid: Set<string>, matchedGridOrderIds: Set<string>, filledOrders: any[], updatedOrders: any[], ordersNeedingCorrection: any[], unmatchedChainOrders: any[], options: Record<string, any>): Promise<{
+        filledOrders: any[];
+        updatedOrders: any[];
+        ordersNeedingCorrection: any[];
+        unmatchedChainOrders: any[];
+    }>;
+    /**
+     * Process one incremental fill-history event.
+     * Returns `{ filledOrders, updatedOrders, partialFill, requiresOpenOrdersSync }`.
+     * @param {Object} fill - Fill history event object
+     * @param {Object} [options] - Persistence mode options
+     * @returns {Promise<Object>} { filledOrders, updatedOrders, partialFill, requiresOpenOrdersSync }
+     */
+    syncFromFillHistory(fill: any, options?: Record<string, any>): Promise<{
+        filledOrders: any[];
+        updatedOrders: any[];
+        partialFill: boolean;
+        requiresOpenOrdersSync: boolean;
+    } | {
+        filledOrders: any[];
+        updatedOrders: any[];
+        partialFill: boolean;
+        requiresOpenOrdersSync?: undefined;
+    }>;
+    /**
+     * High-level dispatcher for different blockchain synchronization sources.
+     * Routes to the appropriate sync strategy based on the data source.
+     *
+     * SOURCES AND STRATEGIES:
+     * ========================================================================
+     * source: 'createOrder'
+     *   Purpose: Grid order was successfully placed on-chain
+     *   Data: { gridOrderId, chainOrderId, isPartialPlacement, fee }
+     *   Action:
+     *     1. Look up grid order by gridOrderId
+     *     2. Assign the returned chainOrderId (so we can find it later)
+     *     3. Transition state based on isPartialPlacement:
+     *        - false → ACTIVE (full order placed)
+     *        - true → PARTIAL (placed as partial, likely due to insufficient funds)
+     *     4. Update optimistic chainFree balance (deduct fees if BTS pair)
+     *   Fund Impact: Funds transition from free → locked/committed
+     *
+     * source: 'cancelOrder'
+     *   Purpose: Grid order was successfully cancelled on-chain
+     *   Data: The chainOrderId to cancel
+     *   Action:
+     *     1. Find grid order by orderId (reverse lookup)
+     *     2. Transition to VIRTUAL (order no longer on-chain)
+     *     3. Clear orderId so it can be re-used
+     *     4. Update optimistic chainFree balance (add funds back as free)
+     *   Fund Impact: Funds transition from locked → free
+     *   Note: This is used for direct cancellations (not rotation/consolidation)
+     *
+     * source: 'readOpenOrders' or 'periodicBlockchainFetch'
+     *   Purpose: Full snapshot sync of all open orders from blockchain
+     *   Data: Array of chain orders from blockchain API
+     *   Action: Delegates to syncFromOpenOrders() for full reconciliation
+     *   Use Case: Periodic health check or startup initialization
+     *
+     * FUND TRACKING:
+     * Both 'createOrder' and 'cancelOrder' call updateOptimisticFreeBalance() to
+     * keep the optimistic chainFree balance in sync with actual on-chain state.
+     * This prevents fund leaks where placed orders weren't deducted or cancelled
+     * orders weren't released.
+     *
+     * RETURNS: { newOrders, ordersNeedingCorrection }
+     * Most callers use ordersNeedingCorrection to flag price corrections needed.
+     * Only syncFromOpenOrders() populates ordersNeedingCorrection.
+     *
+     * @param {Object} chainData - Chain event data
+     * @param {string} source - Source identifier ('createOrder', 'cancelOrder', 'readOpenOrders', etc.)
+     * @param {Object} [options] - Sync options forwarded to open-order reconciliation
+     * @returns {Promise<Object>} { newOrders, ordersNeedingCorrection }
+     */
+    synchronizeWithChain(chainData: any, source: string, options?: Record<string, any>): Promise<any>;
+    /**
+     * Fetch account balances from blockchain and update optimistic fund totals.
+     * This is a critical method for financial accuracy and must be called periodically.
+     *
+     * BALANCE FETCHING:
+     * ========================================================================
+     * This method queries the blockchain for the actual account balances in both
+     * assetA and assetB. It retrieves:
+     *   - total: Total balance (including locked amounts)
+     *   - free: Available balance (not locked in orders)
+     *
+     * These are stored in mgr.accountTotals as:
+     *   - sell: assetA total (what we can sell)
+     *   - sellFree: assetA available
+     *   - buy: assetB total (what we can buy with)
+     *   - buyFree: assetB available
+     *
+     * IMPORTANCE FOR FUND TRACKING:
+     * The grid maintains an "optimistic" free balance that tracks fund deductions
+     * as orders transition states. However, the blockchain is the source of truth.
+     * Periodically fetching actual balances allows us to:
+     *
+     * 1. RECONCILE: Detect if optimistic state diverged from reality
+     *    Example: If we think buyFree=1000 but blockchain says 950,
+     *    something was deducted (fee, slippage, etc.) that we didn't track.
+     *
+     * 2. RECOVER: Identify "orphaned" funds that got stuck somewhere
+     *    If actual > optimistic, we can reabsorb the extra into available pool.
+     *
+     * 3. PREVENT OVERSPEND: Use actual totals as the hard ceiling
+     *    Even if optimistic calc says we have X funds, we never exceed actual total.
+     *
+     * FUND FORMULA:
+     * At any time, this should hold:
+     *   chainTotal = chainFree + chainCommitted
+     * Where:
+     *   chainTotal = actual on-chain total from blockchain
+     *   chainFree = free balance (unallocated)
+     *   chainCommitted = sum of all ACTIVE/PARTIAL order sizes on-chain
+     *
+     * ASSET INITIALIZATION:
+     * First calls initializeAssets() to ensure assetA and assetB metadata is loaded.
+     * Without this, we can't convert between blockchain precision and float values.
+     *
+     * ERROR HANDLING:
+     * Gracefully handles lookup failures. If blockchain fetch fails, we don't crash
+     * but instead log a warning. The system continues with last-known balances.
+     *
+     * @returns {Promise<void>}
+     */
+    fetchAccountBalancesAndSetTotals(): Promise<void>;
+    /**
+     * Initialize asset metadata for assetA and assetB.
+     * This must be called before any blockchain operations, as asset metadata
+     * (ID, precision) is required for all conversions and lookups.
+     *
+     * WHY ASSET METADATA MATTERS:
+     * ========================================================================
+     * The blockchain and grid use different representations for amounts:
+     *
+     * Blockchain: Uses integers (atomic units based on asset precision)
+     *   - BTS: precision 5 → 1 BTS = 100000 satoshis
+     *   - USDT: precision 6 → 1 USDT = 1000000 satoshis
+     *   Storage on-chain is always integer to prevent floating-point errors
+     *
+     * Grid: Uses floats for all calculations
+     *   - Easier to work with for price/size calculations
+     *   - Must round-trip correctly through blockchain precision
+     *
+     * Asset Metadata Needed:
+     * 1. asset_id: Required to match orders on-chain
+     *    When we see an order selling assetA for assetB, we identify it by comparing
+     *    the asset_ids in the sell_price object.
+     *
+     * 2. precision: Required for float ↔ integer conversions
+     *    floatToBlockchainInt(1.5, precision=5) = 150000
+     *    blockchainToFloat(150000, precision=5) = 1.5
+     *
+     * Without precision, we can't:
+     * - Compare order sizes (float vs blockchain int)
+     * - Calculate fills (precision matters at extreme sizes)
+     * - Match chain orders to grid orders (need correct ID)
+     * - Convert fill amounts to grid sizes
+     *
+     * INITIALIZATION STRATEGY:
+     * Assets are looked up asynchronously via the BitShares API.
+     * The lookup is idempotent: if assets are already initialized, returns immediately.
+     * This allows safe calls from multiple places without redundant lookups.
+     *
+     * ERROR HANDLING:
+     * If asset lookup fails (asset doesn't exist, API error, etc.), the error
+     * is propagated (not caught). This is intentional - a missing asset is a
+     * configuration error that must be fixed before the bot can operate.
+     *
+     * @returns {Promise<void>}
+     */
+    initializeAssets(): Promise<void>;
+}
+export = SyncEngine;
+//# sourceMappingURL=sync_engine.d.ts.map

package/dist/modules/order/sync_engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync_engine.d.ts","sourceRoot":"","sources":["../../../modules/order/sync_engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAkLH,cAAM,UAAU;IACZ,OAAO,CAAC,OAAO,CAAM;IACrB;;OAEG;gBACS,OAAO,EAAE,GAAG;IAIxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6DG;IACH;;;;;OAKG;IACG,kBAAkB,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM;IAyErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,qBAAqB,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;;;;;IA6HnF;;;;;;;;;;;;;;;OAeG;IACG,0BAA0B,CAAC,GAAG,EAAE,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9J,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,GAAG,EAAE,EAAE,aAAa,EAAE,GAAG,EAAE,EAAE,uBAAuB,EAAE,GAAG,EAAE,EAAE,oBAAoB,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;;;;;IAoV5M;;;;;;OAMG;IACG,mBAAmB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM;;;;;;;;;;;IAwQtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACG,oBAAoB,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM;IA0K5F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACG,gCAAgC;IA0CtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACG,gBAAgB;CAgCzB;AAED,SAAS,UAAU,CAAC"}