dexbot 1.2.5 → 1.2.7

package/dist/modules/order/sync_engine.js

@@ -40,25 +40,30 @@
  *      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
+ * FILL PROCESSING (2 methods)
+ *   5. syncFromFillHistory(fill) - Process single fill event synchronously
  *      Updates grid order state based on fill data
  *      Updates fund state and accounting
  *      Handles both maker and taker fills
  *
+ *   6. syncFromFillHistoryBatch(fills) - Process multiple fill events in batch
+ *      Acquires _gridLock once for all fills in block group
+ *      Batches drift refetch into one get_objects RPC call
+ *      Applies all grid mutations in a single applyGridUpdateBatch
+ *
  * FULL SYNCHRONIZATION (1 method - async)
- *   6. synchronizeWithChain(chainData, source) - Full sync (fetch + sync) (async)
+ *   7. 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)
+ *   8. 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)
+ *   9. initializeAssets() - Initialize asset metadata (async)
  *      Fetches asset precision and other metadata
  *      Sets manager.assets
  *      Called once at bot startup
@@ -91,28 +96,7 @@ const { blockchainToFloat, floatToBlockchainInt, hasValidAccountTotals, calculat
 const { parseChainOrder, findMatchingGridOrderByOpenOrder, applyChainSizeToGridOrder, convertToSpreadPlaceholder, virtualizeOrder, buildFillKey, isOrderPlaced, isOrderOnChain, hasOnChainId, isOrderVirtual, isPhantomOrder } = require('./utils/order');
 const { resolveProcessedFillPersistenceMode } = require('./processed_fill_store');
 const { lookupAsset } = require('./utils/system');
-/**
- * Compare two raw chain order objects for on-chain equivalence.
- * @param {Object|null} a - First chain order
- * @param {Object|null} b - Second chain order
- * @returns {boolean} True if orders are equivalent
- */
-function hasEquivalentRawOnChainOrder(a, b) {
-    if (!a && !b)
-        return true;
-    if (!a || !b)
-        return false;
-    const aBase = a.sell_price?.base || {};
-    const bBase = b.sell_price?.base || {};
-    const aQuote = a.sell_price?.quote || {};
-    const bQuote = b.sell_price?.quote || {};
-    return String(a.id ?? '') === String(b.id ?? '') &&
-        String(a.for_sale ?? '') === String(b.for_sale ?? '') &&
-        String(aBase.amount ?? '') === String(bBase.amount ?? '') &&
-        String(aBase.asset_id ?? '') === String(bBase.asset_id ?? '') &&
-        String(aQuote.amount ?? '') === String(bQuote.amount ?? '') &&
-        String(aQuote.asset_id ?? '') === String(bQuote.asset_id ?? '');
-}
+const chainOrders = require('../chain_orders');
 function describeNearestAdoptionCandidates(mgr, chainOrder, precision, calcTolerance, matchedGridOrderIds = null) {
     if (!mgr?.orders || !chainOrder || typeof precision !== 'number')
         return 'candidate diagnostics unavailable';
@@ -181,9 +165,6 @@ function describeNearestAdoptionCandidates(mgr, chainOrder, precision, calcToler
             ` reason=${reasons.join('|') || 'unknown'}`;
     }).join('; ');
 }
-function _getDriftToleranceMultiplier(mgr) {
-    return mgr?.config?.gridLimits?.PRICE_DRIFT_TOLERANCE_MULTIPLIER;
-}
 /**
  * Find the closest same-side (or spread) candidate slot for a chain order and
  * return a "price-drift-orphan" tag if the slot's price diff is larger than the
@@ -235,7 +216,8 @@ function computeOutOfToleranceDriftTag(mgr, chainOrder, calcToleranceFn) {
         const tolerance = (calcToleranceFn ? (calcToleranceFn(slotPrice, effectiveSize, orderType) || 0) : 0);
         if (priceDiff <= tolerance)
             continue;
-        const driftBudget = tolerance * _getDriftToleranceMultiplier(mgr);
+        const driftMultiplier = mgr?.config?.gridLimits?.PRICE_DRIFT_TOLERANCE_MULTIPLIER;
+        const driftBudget = tolerance * driftMultiplier;
         if (driftBudget > 0 && priceDiff > driftBudget)
             continue;
         if (!bestDrift || priceDiff < bestDrift.priceDiff) {
@@ -963,6 +945,121 @@ class SyncEngine {
         }
         return { filledOrders, updatedOrders, ordersNeedingCorrection, unmatchedChainOrders };
     }
+    // ------------------------------------------------------------------
+    // Shared fill-processing helpers (used by syncFromFillHistory and
+    // syncFromFillHistoryBatch)
+    // ------------------------------------------------------------------
+    _findMatchingGridOrder(mgr, orderId) {
+        for (const gridOrder of mgr.orders.values()) {
+            if (gridOrder.orderId === orderId && (gridOrder.state === ORDER_STATES.ACTIVE || gridOrder.state === ORDER_STATES.PARTIAL)) {
+                return gridOrder;
+            }
+        }
+        return null;
+    }
+    _computeFillContext(mgr, matchedGridOrder, paysAssetId, paysAmountRaw) {
+        const orderType = matchedGridOrder.type;
+        const currentSize = toFiniteNumber(matchedGridOrder.size);
+        const precision = (orderType === ORDER_TYPES.SELL) ? mgr.assets.assetA.precision : mgr.assets.assetB.precision;
+        let filledAmount = 0;
+        if (orderType === ORDER_TYPES.SELL) {
+            if (paysAssetId === mgr.assets.assetA.id)
+                filledAmount = blockchainToFloat(paysAmountRaw, precision, true);
+        }
+        else {
+            if (paysAssetId === mgr.assets.assetB.id)
+                filledAmount = blockchainToFloat(paysAmountRaw, precision, true);
+        }
+        const currentSizeIntFromGrid = floatToBlockchainInt(currentSize, precision);
+        const rawForSaleInt = toFiniteNumber(matchedGridOrder?.rawOnChain?.for_sale, null);
+        const driftSignal = Number.isFinite(rawForSaleInt) && Math.round(rawForSaleInt) < currentSizeIntFromGrid;
+        return { orderType, currentSize, precision, filledAmount, currentSizeIntFromGrid, rawForSaleInt, driftSignal };
+    }
+    async _computeFillTransitionResult(mgr, params) {
+        const { matchedGridOrder, orderType, precision, filledAmount, filledAmountInt, currentSizeIntFromGrid, rawForSaleInt, chainRefetched, chainConfirmsEmpty, effectiveRawForSale, blockNum, historyId, isMaker } = params;
+        let resolvedChainConfirmsEmpty = chainConfirmsEmpty;
+        if (chainRefetched && Number.isFinite(effectiveRawForSale) && Math.round(effectiveRawForSale) <= 0) {
+            resolvedChainConfirmsEmpty = true;
+        }
+        const currentSizeInt = Number.isFinite(effectiveRawForSale)
+            ? Math.max(0, Math.round(effectiveRawForSale))
+            : currentSizeIntFromGrid;
+        const newSizeInt = Math.max(0, currentSizeInt - filledAmountInt);
+        const newSize = blockchainToFloat(newSizeInt, precision, true);
+        if (Number.isFinite(effectiveRawForSale) && currentSizeInt !== currentSizeIntFromGrid) {
+            mgr.logger.log(`[SYNC] Using rawOnChain.for_sale baseline for ${matchedGridOrder.orderId}: raw=${currentSizeInt}, grid=${currentSizeIntFromGrid}` +
+                (chainRefetched ? ' (refetched)' : ''), 'debug');
+        }
+        const gridAlsoEmpty = currentSizeIntFromGrid <= 0;
+        let isEffectivelyFull = resolvedChainConfirmsEmpty || gridAlsoEmpty;
+        let ghostOrderId;
+        if (!isEffectivelyFull) {
+            const otherPrecision = (orderType === ORDER_TYPES.SELL) ? mgr.assets.assetB.precision : mgr.assets.assetA.precision;
+            const price = matchedGridOrder.price;
+            const otherSize = (orderType === ORDER_TYPES.SELL) ? newSize * price : newSize / price;
+            if (floatToBlockchainInt(otherSize, otherPrecision) <= 0) {
+                mgr.logger.log(`[SYNC] Order ${matchedGridOrder.orderId} (slot ${matchedGridOrder.id}) other-side (${otherSize}) rounds to 0. Treating as full fill to trigger rotation.`, 'info');
+                isEffectivelyFull = true;
+                ghostOrderId = matchedGridOrder.orderId;
+            }
+        }
+        let fullUpdate;
+        let ghostUpdate;
+        let partialUpdate;
+        let filledOrderResult;
+        if (isEffectivelyFull) {
+            if (ghostOrderId) {
+                ghostUpdate = {
+                    ...matchedGridOrder,
+                    size: 0,
+                    state: ORDER_STATES.PARTIAL,
+                    orderId: ghostOrderId,
+                };
+            }
+            else {
+                fullUpdate = convertToSpreadPlaceholder(matchedGridOrder);
+            }
+            filledOrderResult = { ...matchedGridOrder, blockNum, historyId, isMaker };
+        }
+        else {
+            filledOrderResult = {
+                ...matchedGridOrder,
+                size: filledAmount,
+                isPartial: true,
+                blockNum,
+                historyId,
+                isMaker
+            };
+            const { btsFeeState, ...matchedWithoutDeferredFee } = matchedGridOrder;
+            let updatedOrder = { ...matchedWithoutDeferredFee, state: ORDER_STATES.PARTIAL };
+            if (updatedOrder.rawOnChain && updatedOrder.rawOnChain.for_sale !== undefined) {
+                const baselineForSale = (chainRefetched && Number.isFinite(effectiveRawForSale))
+                    ? effectiveRawForSale
+                    : toFiniteNumber(updatedOrder.rawOnChain.for_sale);
+                const nextForSaleInt = Math.max(0, Math.round(baselineForSale) - filledAmountInt);
+                updatedOrder.rawOnChain = {
+                    ...updatedOrder.rawOnChain,
+                    for_sale: String(nextForSaleInt),
+                    fetchedAt: Date.now()
+                };
+            }
+            const nextOrder = await applyChainSizeToGridOrder(mgr, updatedOrder, newSize);
+            if (nextOrder) {
+                updatedOrder = { ...updatedOrder, ...nextOrder };
+            }
+            partialUpdate = updatedOrder;
+        }
+        return {
+            isFull: isEffectivelyFull,
+            isGhost: !!ghostOrderId,
+            ghostOrderId,
+            filledOrder: filledOrderResult,
+            fullUpdate,
+            ghostUpdate,
+            partialUpdate,
+            newSize
+        };
+    }
     /**
      * Process one incremental fill-history event.
      * @param {Object} fill - Fill history event object
@@ -981,7 +1078,7 @@ class SyncEngine {
         if (fillOp.is_maker === undefined) {
             mgr.logger.log(`[SYNC] is_maker flag missing from fill data for order ${orderId}; defaulting to maker`, 'warn');
         }
-        const isMaker = fillOp.is_maker !== false; // Default missing flag to maker for consistency with accounting
+        const isMaker = fillOp.is_maker !== false;
         const fillKey = buildFillKey({ orderId, blockNum, historyId });
         const paysAmountRaw = toFiniteNumber(fillOp.pays?.amount);
         const paysAssetId = fillOp.pays ? fillOp.pays.asset_id : null;
@@ -992,231 +1089,96 @@ class SyncEngine {
             mgr.logger.log(`[SYNC] Missing replay-safe fill key for order ${orderId} block ${blockNum}; deferring to open-orders sync`, 'warn');
             return { filledOrders: [], updatedOrders: [], partialFill: false, requiresOpenOrdersSync: true };
         }
-        // Lock the order to prevent concurrent modifications from createOrder/cancelOrder/sync
-        // TOCTOU: lock before processFillAccounting so _buildBtsDeferredRefundAdjustment
-        // reads order state (btsFeeState) under the same lock as the state update below.
         const orderIdsToLock = new Set([orderId]);
         mgr.lockOrders([...orderIdsToLock]);
         try {
             mgr.pauseFundRecalc();
             try {
-                // Optimistically update account totals to reflect the fill.
-                // Under lock — btsFeeState on mgr.orders is stable for _buildBtsDeferredRefundAdjustment.
                 const appliedAccounting = await mgr.accountant.processFillAccounting(fillOp, fillKey, { persistenceMode });
                 if (!appliedAccounting) {
                     mgr.logger.log(`[SYNC] Replay detected for fill ${fillKey}; skipping duplicate order mutation`, 'debug');
                     return { filledOrders: [], updatedOrders: [], partialFill: false };
                 }
-                const paysAmount = paysAmountRaw;
                 const assetAPrecision = mgr.assets?.assetA?.precision;
                 const assetBPrecision = mgr.assets?.assetB?.precision;
                 if (assetAPrecision === undefined || assetBPrecision === undefined) {
                     mgr.logger?.log?.('Error: manager.assets precision missing in syncFromFillHistory', 'error');
                     return { filledOrders: [], updatedOrders: [], partialFill: false };
                 }
-                let matchedGridOrder = null;
-                for (const gridOrder of mgr.orders.values()) {
-                    if (gridOrder.orderId === orderId && (gridOrder.state === ORDER_STATES.ACTIVE || gridOrder.state === ORDER_STATES.PARTIAL)) {
-                        matchedGridOrder = gridOrder;
-                        break;
-                    }
-                }
+                const matchedGridOrder = this._findMatchingGridOrder(mgr, orderId);
                 if (!matchedGridOrder) {
                     mgr.logger.log(`[SYNC] Fill for order ${orderId} ignored: order not found in active grid.`, 'debug');
                     return { filledOrders: [], updatedOrders: [], partialFill: false };
                 }
-                const orderType = matchedGridOrder.type;
-                const currentSize = toFiniteNumber(matchedGridOrder.size);
-                // CRITICAL: Sells are sized in AssetA, Buys are sized in AssetB
-                const precision = (orderType === ORDER_TYPES.SELL) ? assetAPrecision : assetBPrecision;
-                let filledAmount = 0;
-                if (orderType === ORDER_TYPES.SELL) {
-                    if (paysAssetId === mgr.assets.assetA.id)
-                        filledAmount = blockchainToFloat(paysAmount, precision, true);
-                }
-                else {
-                    if (paysAssetId === mgr.assets.assetB.id)
-                        filledAmount = blockchainToFloat(paysAmount, precision, true);
-                }
-                mgr.logger.log(`[SYNC] Order ${orderId} (${orderType}) currentSize=${currentSize}, filledAmount=${filledAmount}`, 'debug');
-                const currentSizeIntFromGrid = floatToBlockchainInt(currentSize, precision);
-                const rawForSaleInt = toFiniteNumber(matchedGridOrder?.rawOnChain?.for_sale, null);
-                let effectiveRawForSale = rawForSaleInt;
+                const ctx = this._computeFillContext(mgr, matchedGridOrder, paysAssetId, paysAmountRaw);
+                mgr.logger.log(`[SYNC] Order ${orderId} (${ctx.orderType}) currentSize=${ctx.currentSize}, filledAmount=${ctx.filledAmount}`, 'debug');
+                let effectiveRawForSale = ctx.rawForSaleInt;
                 let chainConfirmsEmpty = false;
                 let chainRefetched = false;
-                // -----------------------------------------------------------------
-                // Drift-only refetch: the cache is self-correcting across
-                // sequential websocket fills, but if a fill was ever missed
-                // (reconnect, restart, reorg, external activity), the cache and
-                // the grid can disagree.
-                // The only signal we can detect from the in-memory state is a
-                // consistent drift: cached for_sale < grid size. Chain `for_sale`
-                // can only decrease, so a smaller cached value is an obvious
-                // inconsistency that warrants a targeted refetch.
-                //
-                // We do NOT refetch on a time-based TTL. A stale-but-consistent
-                // cache is still correct; a fresh-but-wrong cache is the actual
-                // bug we're guarding against, and the drift signal catches that.
-                // The refetch is best-effort: a network error falls back to the
-                // cache with a warning, and the open-orders sync is the ultimate
-                // recovery channel.
-                // -----------------------------------------------------------------
-                const driftSignal = Number.isFinite(rawForSaleInt)
-                    && Math.round(rawForSaleInt) < currentSizeIntFromGrid;
-                if (driftSignal) {
+                if (ctx.driftSignal) {
                     try {
-                        const { readSingleOrder } = require('../chain_orders');
-                        const fresh = await readSingleOrder(orderId, 3000);
+                        const fresh = await chainOrders.readSingleOrder(orderId, 3000);
                         if (fresh) {
                             const freshForSale = toFiniteNumber(fresh.for_sale, null);
                             if (Number.isFinite(freshForSale)) {
                                 effectiveRawForSale = freshForSale;
                                 chainRefetched = true;
-                                mgr.logger.log(`[SYNC] Drift detected for ${orderId} (cached=${rawForSaleInt} < grid=${currentSizeIntFromGrid}); ` +
+                                mgr.logger.log(`[SYNC] Drift detected for ${orderId} (cached=${ctx.rawForSaleInt} < grid=${ctx.currentSizeIntFromGrid}); ` +
                                     `refetched for_sale=${freshForSale}`, 'warn');
                             }
                         }
                         else {
-                            // Chain returned null — the order is genuinely absent.
-                            // This is the authoritative "chain confirms empty"
-                            // signal (vs. an RPC failure which would have thrown).
                             chainConfirmsEmpty = true;
                             mgr.logger.log(`[SYNC] Drift refetch for ${orderId} returned null; chain confirms empty`, 'info');
                         }
                     }
                     catch (refetchErr) {
-                        mgr.logger.log(`[SYNC] Drift refetch for ${orderId} failed; falling back to cache: ` +
-                            `${refetchErr?.message || refetchErr}`, 'warn');
-                    }
-                }
-                // Chain-confirmed-empty gate: only true when the drift refetch
-                // returned null (i.e., the chain is definitively saying the order
-                // is gone). We deliberately do not trust a cached 0 from a
-                // never-refetched source — that would misclassify a 0.003 XRP
-                // residual as a full fill.
-                if (chainRefetched
-                    && Number.isFinite(effectiveRawForSale)
-                    && Math.round(effectiveRawForSale) <= 0) {
-                    chainConfirmsEmpty = true;
-                }
-                const currentSizeInt = Number.isFinite(effectiveRawForSale)
-                    ? Math.max(0, Math.round(effectiveRawForSale))
-                    : currentSizeIntFromGrid;
-                const filledAmountInt = floatToBlockchainInt(filledAmount, precision);
-                const newSizeInt = Math.max(0, currentSizeInt - filledAmountInt);
-                const newSize = blockchainToFloat(newSizeInt, precision, true); // needed for partial fills
-                if (Number.isFinite(effectiveRawForSale) && currentSizeInt !== currentSizeIntFromGrid) {
-                    mgr.logger.log(`[SYNC] Using rawOnChain.for_sale baseline for ${orderId}: raw=${currentSizeInt}, grid=${currentSizeIntFromGrid}` +
-                        (chainRefetched ? ' (refetched)' : ''), 'debug');
-                }
-                // CRITICAL (v0.5.1 Robustness + chain-confirmed-empty gate):
-                // An order is "effectively" full if EITHER:
-                //   1. The chain has confirmed the order is gone (the drift
-                //      refetch above returned null), OR
-                //   2. The grid itself is at 0 (no drift between grid and chain), OR
-                //   3. The OTHER side rounds to 0 (the chain will close the order
-                //      regardless of the residual on the size side — see
-                //      test_ghost_order_fix.ts for the intended behaviour).
-                //
-                // We deliberately do NOT use `newSizeInt <= 0` as a fast-path
-                // full-fill signal: with a stale cached rawOnChain, that arithmetic
-                // can be wrong and misclassify a partial fill as full. The
-                // 30-satoshi residual that triggered the bot-stale incident is the
-                // motivating case.
-                const gridAlsoEmpty = currentSizeIntFromGrid <= 0;
-                let isEffectivelyFull = chainConfirmsEmpty || gridAlsoEmpty;
-                let ghostOrderId;
-                if (!isEffectivelyFull) {
-                    // Check the "other" side's precision. If the remaining amount to receive/pay
-                    // rounds to 0 on the blockchain, the order will be closed regardless of newSizeInt.
-                    const otherPrecision = (orderType === ORDER_TYPES.SELL) ? assetBPrecision : assetAPrecision;
-                    const price = matchedGridOrder.price;
-                    const otherSize = (orderType === ORDER_TYPES.SELL) ? newSize * price : newSize / price;
-                    if (floatToBlockchainInt(otherSize, otherPrecision) <= 0) {
-                        mgr.logger.log(`[SYNC] Order ${orderId} (slot ${matchedGridOrder.id}) other-side (${otherSize}) rounds to 0. Treating as full fill to trigger rotation.`, 'info');
-                        isEffectivelyFull = true;
-                        ghostOrderId = matchedGridOrder.orderId;
+                        mgr.logger.log(`[SYNC] Drift refetch for ${orderId} failed; falling back to cache: ${refetchErr?.message || refetchErr}`, 'warn');
                     }
                 }
+                const result = await this._computeFillTransitionResult(mgr, {
+                    matchedGridOrder,
+                    orderType: ctx.orderType,
+                    precision: ctx.precision,
+                    filledAmount: ctx.filledAmount,
+                    filledAmountInt: floatToBlockchainInt(ctx.filledAmount, ctx.precision),
+                    currentSizeIntFromGrid: ctx.currentSizeIntFromGrid,
+                    rawForSaleInt: ctx.rawForSaleInt,
+                    chainRefetched,
+                    chainConfirmsEmpty,
+                    effectiveRawForSale,
+                    blockNum,
+                    historyId,
+                    isMaker
+                });
                 const filledOrders = [];
                 const updatedOrders = [];
-                if (isEffectivelyFull) {
-                    const filledOrder = {
-                        ...matchedGridOrder,
-                        blockNum: blockNum,
-                        historyId: historyId,
-                        isMaker: isMaker // Preserve maker/taker flag for accurate fee calculation
-                    };
-                    if (ghostOrderId) {
-                        // Ghost order: the chain order still exists (other-side
-                        // rounding to 0) but the chain hasn't closed it yet.  Keep
-                        // the slot PARTIAL with its orderId so guards
-                        // (validateCreateTargetSlots, reconcileGrid) see the slot
-                        // as occupied and will NOT generate a duplicate CREATE.
-                        // The best-effort cancel in dexbot_class cleans up the
-                        // chain order; the next sync cycle virtualizes the
-                        // confirmed-free slot.
-                        mgr.logger.log(`[SYNC] Ghost full fill for order ${orderId} (slot ${matchedGridOrder.id}): ` +
-                            `preserving orderId ${ghostOrderId} as PARTIAL to block duplicate CREATE.`, 'info');
-                        const ghostOrder = {
-                            ...matchedGridOrder,
-                            size: 0,
-                            state: ORDER_STATES.PARTIAL,
-                            orderId: ghostOrderId,
-                        };
-                        const ghostOk = await mgr._updateOrder(ghostOrder, 'handle-fill-ghost', { skipAccounting: false, fee: 0 });
+                if (result.isFull) {
+                    if (result.isGhost) {
+                        mgr.logger.log(`[SYNC] Ghost full fill for order ${orderId} (slot ${matchedGridOrder.id}): preserving orderId ${result.ghostOrderId} as PARTIAL to block duplicate CREATE.`, 'info');
+                        const ghostOk = await mgr._updateOrder(result.ghostUpdate, 'handle-fill-ghost', { skipAccounting: false, fee: 0 });
                         if (ghostOk === false) {
                             mgr.logger.log(`[SYNC] Failed to apply ghost fill state for order ${orderId}`, 'warn');
                         }
-                        filledOrders.push(filledOrder);
-                        return { filledOrders, updatedOrders, partialFill: false, ghostOrderId };
+                        filledOrders.push(result.filledOrder);
+                        return { filledOrders, updatedOrders, partialFill: false, ghostOrderId: result.ghostOrderId };
                     }
                     mgr.logger.log(`[SYNC] Full fill for order ${orderId} (slot ${matchedGridOrder.id}).`, 'info');
-                    const spreadOrder = convertToSpreadPlaceholder(matchedGridOrder);
-                    const fullOk = await mgr._updateOrder(spreadOrder, 'handle-fill-full', { skipAccounting: false, fee: 0 });
+                    const fullOk = await mgr._updateOrder(result.fullUpdate, 'handle-fill-full', { skipAccounting: false, fee: 0 });
                     if (fullOk === false) {
                         mgr.logger.log(`[SYNC] Failed to convert filled order ${orderId} to spread placeholder`, 'warn');
                     }
-                    filledOrders.push(filledOrder);
+                    filledOrders.push(result.filledOrder);
                     return { filledOrders, updatedOrders, partialFill: false };
                 }
                 else {
-                    mgr.logger.log(`[SYNC] Partial fill for order ${orderId} (slot ${matchedGridOrder.id}): newSize=${newSize}`, 'info');
-                    const filledPortion = {
-                        ...matchedGridOrder,
-                        size: filledAmount,
-                        isPartial: true,
-                        blockNum: blockNum,
-                        historyId: historyId,
-                        isMaker: isMaker // Preserve maker/taker flag for accurate fee calculation
-                    };
-                    const { btsFeeState, ...matchedWithoutDeferredFee } = matchedGridOrder;
-                    let updatedOrder = { ...matchedWithoutDeferredFee, state: ORDER_STATES.PARTIAL };
-                    // Update cached raw order integer instead of deleting it.
-                    // If the drift refetch above pulled a fresh chain value, use
-                    // it as the new baseline (subtracting this fill) and stamp
-                    // fetchedAt so the cache is consistent for the next fill.
-                    if (updatedOrder.rawOnChain && updatedOrder.rawOnChain.for_sale !== undefined) {
-                        const baselineForSale = (chainRefetched && Number.isFinite(effectiveRawForSale))
-                            ? effectiveRawForSale
-                            : toFiniteNumber(updatedOrder.rawOnChain.for_sale);
-                        const nextForSaleInt = Math.max(0, Math.round(baselineForSale) - filledAmountInt);
-                        updatedOrder.rawOnChain = {
-                            ...updatedOrder.rawOnChain,
-                            for_sale: String(nextForSaleInt),
-                            fetchedAt: Date.now()
-                        };
-                    }
-                    const nextOrder = await applyChainSizeToGridOrder(mgr, updatedOrder, newSize);
-                    if (nextOrder) {
-                        updatedOrder = { ...updatedOrder, ...nextOrder };
-                    }
-                    const partialOk = await mgr._updateOrder(updatedOrder, 'handle-fill-partial', { skipAccounting: false, fee: 0 });
+                    mgr.logger.log(`[SYNC] Partial fill for order ${orderId} (slot ${matchedGridOrder.id}): newSize=${result.newSize}`, 'info');
+                    const partialOk = await mgr._updateOrder(result.partialUpdate, 'handle-fill-partial', { skipAccounting: false, fee: 0 });
                     if (partialOk === false) {
                         mgr.logger.log(`[SYNC] Failed to update partially filled order ${orderId}`, 'warn');
                     }
-                    updatedOrders.push(updatedOrder);
-                    filledOrders.push(filledPortion);
+                    updatedOrders.push(result.partialUpdate);
+                    filledOrders.push(result.filledOrder);
                     return { filledOrders, updatedOrders, partialFill: true };
                 }
             }
@@ -1228,6 +1190,225 @@ class SyncEngine {
             mgr.unlockOrders([...orderIdsToLock]);
         }
     }
+    /**
+     * Process multiple fill-history events in a batch, acquiring _gridLock once.
+     *
+     * Locking: all order IDs locked once up-front; fund recalc paused once.
+     *
+     * @param {Array} fills - Array of fill history event objects (same block group)
+     * @param {Object} [options] - Persistence mode options
+     * @returns {Promise<import('./types').BatchSyncResult>}
+     */
+    async syncFromFillHistoryBatch(fills, options = {}) {
+        const mgr = this.manager;
+        const persistenceMode = resolveProcessedFillPersistenceMode(options);
+        if (!Array.isArray(fills) || fills.length === 0) {
+            return { filledOrders: [], updatedOrders: [], partialFill: false, ghostOrderIds: [] };
+        }
+        // Phase 1: Extract & validate fill data
+        const fillEntries = [];
+        let anyRequiresSync = false;
+        for (const fill of fills) {
+            if (!fill || !fill.op || !fill.op[1])
+                continue;
+            const fillOp = fill.op[1];
+            const blockNum = fill.block_num;
+            const historyId = fill.id;
+            const orderId = fillOp.order_id;
+            if (fillOp.is_maker === undefined) {
+                mgr.logger.log(`[SYNC] is_maker flag missing from fill data for order ${orderId}; defaulting to maker`, 'warn');
+            }
+            const isMaker = fillOp.is_maker !== false;
+            const fillKey = buildFillKey({ orderId, blockNum, historyId });
+            if (!fillKey) {
+                mgr.logger.log(`[SYNC] Missing replay-safe fill key for order ${orderId} block ${blockNum}; deferring to open-orders sync`, 'warn');
+                anyRequiresSync = true;
+                continue;
+            }
+            const paysAmountRaw = toFiniteNumber(fillOp.pays?.amount);
+            const paysAssetId = fillOp.pays ? fillOp.pays.asset_id : null;
+            const receivesAmountRaw = toFiniteNumber(fillOp.receives?.amount);
+            const receivesAssetId = fillOp.receives ? fillOp.receives.asset_id : null;
+            mgr.logger.log(`[SYNC] Processing fill ${historyId} at block ${blockNum} for order ${orderId} (maker=${isMaker}). Pays=${paysAmountRaw}@${paysAssetId}, Receives=${receivesAmountRaw}@${receivesAssetId}`, 'debug');
+            fillEntries.push({
+                fill, fillOp, blockNum, historyId, orderId, fillKey,
+                isMaker, paysAmountRaw, paysAssetId, receivesAmountRaw, receivesAssetId
+            });
+        }
+        if (fillEntries.length === 0) {
+            return { filledOrders: [], updatedOrders: [], partialFill: false, ghostOrderIds: [], requiresOpenOrdersSync: anyRequiresSync };
+        }
+        // Phase 2: Lock all unique order IDs once
+        const allOrderIds = [...new Set(fillEntries.map(e => e.orderId))];
+        mgr.lockOrders(allOrderIds);
+        try {
+            mgr.pauseFundRecalc();
+            try {
+                // Phase 3: Process accounting for each fill
+                const validEntries = [];
+                for (const entry of fillEntries) {
+                    try {
+                        const appliedAccounting = await mgr.accountant.processFillAccounting(entry.fillOp, entry.fillKey, { persistenceMode });
+                        if (!appliedAccounting) {
+                            mgr.logger.log(`[SYNC] Replay detected for fill ${entry.fillKey}; skipping duplicate order mutation`, 'debug');
+                            continue;
+                        }
+                        validEntries.push(entry);
+                    }
+                    catch (acctErr) {
+                        mgr.logger.log(`[SYNC] Accounting error for fill ${entry.fillKey}: ${acctErr.message}`, 'error');
+                        continue;
+                    }
+                }
+                if (validEntries.length === 0) {
+                    return { filledOrders: [], updatedOrders: [], partialFill: false, ghostOrderIds: [], requiresOpenOrdersSync: anyRequiresSync };
+                }
+                // Phase 4: Build per-fill context + identify drift candidates
+                const entryContexts = [];
+                const driftOrderIds = new Set();
+                const assetAPrecision = mgr.assets?.assetA?.precision;
+                const assetBPrecision = mgr.assets?.assetB?.precision;
+                if (assetAPrecision === undefined || assetBPrecision === undefined) {
+                    mgr.logger?.log?.('Error: manager.assets precision missing in syncFromFillHistoryBatch', 'error');
+                    return { filledOrders: [], updatedOrders: [], partialFill: false, ghostOrderIds: [], requiresOpenOrdersSync: anyRequiresSync };
+                }
+                for (const entry of validEntries) {
+                    const { orderId, paysAmountRaw, paysAssetId } = entry;
+                    const matchedGridOrder = this._findMatchingGridOrder(mgr, orderId);
+                    if (!matchedGridOrder) {
+                        mgr.logger.log(`[SYNC] Fill for order ${orderId} ignored: order not found in active grid.`, 'debug');
+                        anyRequiresSync = true;
+                        continue;
+                    }
+                    const ctx = this._computeFillContext(mgr, matchedGridOrder, paysAssetId, paysAmountRaw);
+                    mgr.logger.log(`[SYNC] Order ${orderId} (${ctx.orderType}) currentSize=${ctx.currentSize}, filledAmount=${ctx.filledAmount}`, 'debug');
+                    if (ctx.driftSignal) {
+                        driftOrderIds.add(orderId);
+                    }
+                    entryContexts.push({
+                        entry, matchedGridOrder,
+                        orderType: ctx.orderType,
+                        precision: ctx.precision,
+                        filledAmount: ctx.filledAmount,
+                        filledAmountInt: floatToBlockchainInt(ctx.filledAmount, ctx.precision),
+                        currentSizeIntFromGrid: ctx.currentSizeIntFromGrid,
+                        rawForSaleInt: ctx.rawForSaleInt
+                    });
+                }
+                // Phase 5: Batch drift refetch — one get_objects call for all order IDs
+                const refetchMap = new Map();
+                if (driftOrderIds.size > 0) {
+                    try {
+                        const batchResults = await chainOrders.batchReadOrders([...driftOrderIds], 3000);
+                        for (const [orderId, freshOrder] of batchResults) {
+                            if (freshOrder) {
+                                const freshForSale = toFiniteNumber(freshOrder.for_sale, null);
+                                if (Number.isFinite(freshForSale)) {
+                                    refetchMap.set(orderId, {
+                                        chainConfirmsEmpty: Math.round(freshForSale) <= 0,
+                                        chainRefetched: true,
+                                        effectiveRawForSale: freshForSale
+                                    });
+                                }
+                                else {
+                                    refetchMap.set(orderId, {
+                                        chainConfirmsEmpty: false,
+                                        chainRefetched: true,
+                                        effectiveRawForSale: null
+                                    });
+                                }
+                            }
+                            else {
+                                refetchMap.set(orderId, {
+                                    chainConfirmsEmpty: true,
+                                    chainRefetched: true,
+                                    effectiveRawForSale: null
+                                });
+                            }
+                        }
+                        for (const [orderId, { chainRefetched, chainConfirmsEmpty, effectiveRawForSale }] of refetchMap) {
+                            if (chainRefetched && effectiveRawForSale != null) {
+                                mgr.logger.log(`[SYNC] Drift detected for ${orderId}; batch-refetched for_sale=${effectiveRawForSale}`, 'warn');
+                            }
+                            else if (chainConfirmsEmpty) {
+                                mgr.logger.log(`[SYNC] Drift refetch for ${orderId} returned null; chain confirms empty`, 'info');
+                            }
+                        }
+                    }
+                    catch (refetchErr) {
+                        mgr.logger.log(`[SYNC] Batch drift refetch failed for ${driftOrderIds.size} orders; falling back to cache: ${refetchErr?.message || refetchErr}`, 'warn');
+                    }
+                }
+                // Phase 6: Compute state transitions and collect grid updates
+                const gridUpdates = [];
+                const filledOrders = [];
+                const updatedOrders = [];
+                const ghostOrderIds = [];
+                let anyPartialFill = false;
+                for (const ctx of entryContexts) {
+                    const { entry, matchedGridOrder, orderType, precision, filledAmount, filledAmountInt, currentSizeIntFromGrid, rawForSaleInt } = ctx;
+                    const { orderId, blockNum, historyId, isMaker } = entry;
+                    const refetchInfo = refetchMap.get(orderId);
+                    const chainRefetched = refetchInfo?.chainRefetched || false;
+                    const chainConfirmsEmpty = refetchInfo?.chainConfirmsEmpty || false;
+                    const effectiveRawForSale = refetchInfo?.effectiveRawForSale != null ? refetchInfo.effectiveRawForSale : rawForSaleInt;
+                    const result = await this._computeFillTransitionResult(mgr, {
+                        matchedGridOrder,
+                        orderType,
+                        precision,
+                        filledAmount,
+                        filledAmountInt,
+                        currentSizeIntFromGrid,
+                        rawForSaleInt,
+                        chainRefetched,
+                        chainConfirmsEmpty,
+                        effectiveRawForSale,
+                        blockNum,
+                        historyId,
+                        isMaker
+                    });
+                    if (result.isFull) {
+                        if (result.isGhost) {
+                            mgr.logger.log(`[SYNC] Ghost full fill for order ${orderId} (slot ${matchedGridOrder.id}): ` +
+                                `preserving orderId ${result.ghostOrderId} as PARTIAL to block duplicate CREATE.`, 'info');
+                            gridUpdates.push({ id: matchedGridOrder.id, ...result.ghostUpdate, context: 'handle-fill-ghost' });
+                            ghostOrderIds.push(result.ghostOrderId);
+                        }
+                        else {
+                            mgr.logger.log(`[SYNC] Full fill for order ${orderId} (slot ${matchedGridOrder.id}).`, 'info');
+                            gridUpdates.push({ id: matchedGridOrder.id, ...result.fullUpdate, context: 'handle-fill-full' });
+                        }
+                        filledOrders.push(result.filledOrder);
+                    }
+                    else {
+                        mgr.logger.log(`[SYNC] Partial fill for order ${orderId} (slot ${matchedGridOrder.id}): newSize=${result.newSize}`, 'info');
+                        gridUpdates.push({ id: matchedGridOrder.id, ...result.partialUpdate, context: 'handle-fill-partial' });
+                        updatedOrders.push(result.partialUpdate);
+                        filledOrders.push(result.filledOrder);
+                        anyPartialFill = true;
+                    }
+                }
+                // Phase 7: Single grid batch update — acquires _gridLock once
+                if (gridUpdates.length > 0) {
+                    const updateObjects = gridUpdates.map(u => {
+                        const { context, ...orderData } = u;
+                        return orderData;
+                    });
+                    const batchOk = await mgr.applyGridUpdateBatch(updateObjects, 'handle-fill-batch', { skipAccounting: false, fee: 0 });
+                    if (batchOk === false) {
+                        mgr.logger.log('[SYNC] Batch grid update failed for some fills; next sync cycle will reconcile', 'warn');
+                    }
+                }
+                return { filledOrders, updatedOrders, partialFill: anyPartialFill, ghostOrderIds, requiresOpenOrdersSync: anyRequiresSync };
+            }
+            finally {
+                await mgr.resumeFundRecalc();
+            }
+        }
+        finally {
+            mgr.unlockOrders(allOrderIds);
+        }
+    }
     /**
      * High-level dispatcher for different blockchain synchronization sources.
      * Routes to the appropriate sync strategy based on the data source.
@@ -1513,14 +1694,13 @@ class SyncEngine {
             const assetBId = mgr.assets?.assetB?.id;
             if (!assetAId || !assetBId)
                 return;
-            const { getOnChainAssetBalances } = require('../chain_orders');
             const { NATIVE_CLIENT } = require('../constants');
             const assetList = [assetAId, assetBId];
             // For non-BTS pairs, also fetch core asset (BTS) balance for fee management
             if (mgr.config.assetA !== 'BTS' && mgr.config.assetB !== 'BTS') {
                 assetList.push(NATIVE_CLIENT.CHAIN.CORE_ASSET_ID);
             }
-            const lookup = await getOnChainAssetBalances(accountIdOrName, assetList);
+            const lookup = await chainOrders.getOnChainAssetBalances(accountIdOrName, assetList);
             const aInfo = lookup?.[assetAId] || lookup?.[mgr.config.assetA];
             const bInfo = lookup?.[assetBId] || lookup?.[mgr.config.assetB];
             if (aInfo && bInfo) {