dexbot 1.5.0 → 1.5.1

package/dist/modules/dexbot_cow_runtime.js

@@ -14,11 +14,41 @@ import { BroadcastUncertainError as BroadcastUncertainErrorBinding } from './dex
 const BroadcastUncertainError = BroadcastUncertainErrorBinding;
 import * as orderUtils from './order/utils/order.js';
 import { sleep } from './order/utils/system.js';
-const { buildCreateOrderArgs, buildCreateOpFingerprint, extractBatchOperationResults, formatUnmatchedChainOrder, convertToSpreadPlaceholder, buildOutsideInPairGroups, isOrderPlaced, } = orderUtils;
+const { buildCreateOrderArgs, buildCreateOpFingerprint, extractBatchOperationResults, formatUnmatchedChainOrder, convertToSpreadPlaceholder, toRailHolePlaceholder, buildOutsideInPairGroups, isOrderPlaced, } = orderUtils;
 import * as validate from './order/utils/validate.js';
-const { validateCreateTargetSlots, evaluateCommit, hasExecutableActions } = validate;
+const { validateCreateTargetSlots, evaluateCommit, hasExecutableActions, stampGapEvacuationRotation } = validate;
 import * as math from './order/utils/math.js';
-const { validateOrderSize, findCrossedOrder, priceSlotEqual } = math;
+const { validateOrderSize, findCrossedOrder, priceSlotEqual, isEvacuationRotationAllowed, getSellStartIdx, getPrecisionByOrderType, isSlotIndexInGapBand } = math;
+/**
+ * Re-verify a B-stamped gap-evacuation rotation against the LIVE committed
+ * geometry (boundaryIdx/_gapSlots at execution time). The stamp freezes
+ * plan-build geometry, but a boundary commit can land between plan-build and
+ * execution; when the live geometry is finite and the source is no longer
+ * in-band (or the dest no longer rail), the stamp is stale and the rotation
+ * must be re-proven by the unstamped live probe instead of bypassing the
+ * last-fill guard. Non-finite live geometry cannot disprove the stamp and
+ * keeps the plan-build authority (fail-open to the stamp, never to the guard).
+ */
+export function isEvacuationStampStillValid(liveBoundary, liveGapSlots, sourceId, destId, orderType) {
+    const b = Number(liveBoundary);
+    const g = Number(liveGapSlots);
+    if (orderType !== ORDER_TYPES.BUY && orderType !== ORDER_TYPES.SELL)
+        return false;
+    if (!Number.isFinite(b) || !Number.isFinite(g) || g < 0)
+        return true;
+    const srcIdx = parseSlotIndex(sourceId);
+    const dstIdx = parseSlotIndex(destId);
+    if (srcIdx === null || srcIdx === undefined || dstIdx === null || dstIdx === undefined)
+        return false;
+    if (!isSlotIndexInGapBand(srcIdx, b, g))
+        return false;
+    if (isSlotIndexInGapBand(dstIdx, b, g))
+        return false;
+    const sellStartIdx = getSellStartIdx(b, g);
+    const dstInRail = orderType === ORDER_TYPES.SELL ? Number(dstIdx) >= sellStartIdx : Number(dstIdx) <= b;
+    return dstInRail;
+}
+import { parseSlotIndex } from './order/utils/slot.js';
 function hasSlotPriceCollision(items, targetPrice, precision, excludeId, predicate) {
     for (const it of items) {
         if (predicate && !predicate(it))
@@ -1446,7 +1476,13 @@ function validateOrderSizeForExecution(bot, size, type, orderLike = null, fallba
  *  last fill @x with increment i: BUY < x*(1 - i/2/100), SELL > x*(1 + i/2/100)
  *  e.g. x=1000, i=0.5% => BUY < 997.5, SELL > 1002.5
  * Cold (pivot null or lastType null) => disabled. Spread-correction CREATES
- * bypass per-action (see broadcast sites); rotations never bypass.
+ * bypass per-action (see broadcast sites); gap-evacuation rotation UPDATEs
+ * bypass only via the violation-reducing allowance (origin='gap-evacuation',
+ * UPDATE-only, frozen B-stamp or live-proven isEvacuationRotationAllowed) —
+ * see the UPDATE rotation guard block.
+ * The pivot is the latest fill of either side and is never expired: it stays
+ * the durable mark (last sold level floors new sells; buy fills pull it down
+ * and re-open the sell side, buy-below-sell is never gated).
  * @param {number} price - Target order price
  * @param {number} size - Order size (unused, kept for compat)
  * @param {string} type - ORDER_TYPES.BUY/SELL
@@ -1612,7 +1648,49 @@ function buildActionsFromPlan(_bot, plan) {
     // inherit the spread-correction bypass. Actions built outside this helper
     // carry no origin and default to guarded (safe default).
     const planOrigin = normalizedPlan?.origin;
-    const withOrigin = (action) => (planOrigin ? { ...action, origin: planOrigin } : action);
+    // B-stamp inputs: the plan-level boundary + gap width frozen AT
+    // PLAN-BUILD TIME. The stamp carries this geometry so the execution
+    // guard can bypass on it — and re-verifies it against the LIVE
+    // committed geometry at execution time (isEvacuationStampStillValid),
+    // downgrading stale stamps to the live probe.
+    const frozenBoundaryRaw = Number(normalizedPlan?.boundaryIdx ?? _bot?.manager?.boundaryIdx);
+    const frozenGapRaw = Number(normalizedPlan?.gapSlots ?? _bot?.manager?._gapSlots);
+    const hasFrozenGeometry = Number.isFinite(frozenBoundaryRaw) && Number.isFinite(frozenGapRaw) && frozenGapRaw >= 0;
+    const withOrigin = (action, sourceMaster = null) => {
+        if (!planOrigin)
+            return action;
+        // Origin only rides UPDATEs (where the guard reads it). Gap-plan
+        // CREATEs carry a provably dead origin — the spread-correction
+        // CREATE check falls back to the batch origin, so dropping the
+        // per-action origin there is safe. Other plan origins keep riding
+        // non-UPDATE actions unchanged.
+        if (action?.type !== COW_ACTIONS.UPDATE) {
+            return planOrigin === 'gap-evacuation' ? { ...action } : { ...action, origin: planOrigin };
+        }
+        if (planOrigin !== 'gap-evacuation')
+            return { ...action, origin: planOrigin };
+        if (!hasFrozenGeometry)
+            return { ...action, origin: planOrigin };
+        // Route through the real stampler: geometry (source in-band, dest
+        // rail), bit-exact non-growing size (side precision) and outward
+        // repricing must all PROVE — a plan-level origin alone never grants
+        // the bypass. Without a source master the proof is impossible, so
+        // the action stays unstamped (the live probe at execution can still
+        // re-prove it from the master grid).
+        const base = { ...action, origin: planOrigin };
+        if (!sourceMaster)
+            return { ...base, origin: undefined };
+        // The stampler wants the ORDER type (SELL/BUY), which rides on
+        // action.order.type — action.type is the COW action kind ('update').
+        const rotOrderType = action?.order?.type ?? action?.type;
+        const proved = stampGapEvacuationRotation(base, sourceMaster, action.newPrice, action.newSize, rotOrderType, frozenBoundaryRaw, frozenGapRaw, _bot?.manager?.assets);
+        // Proof refused: strip the origin so the action is exactly an
+        // unstamped rotation (never an origin claim without a stamp).
+        if (!proved?.evacBoundary && !proved?.evacGapSlots) {
+            proved.origin = undefined;
+        }
+        return proved;
+    };
     const actions = [];
     for (const o of ordersToCancel) {
         if (o?.orderId) {
@@ -1646,7 +1724,7 @@ function buildActionsFromPlan(_bot, plan) {
                 price: newPrice,
                 size: newSize
             }
-        }));
+        }, oldOrder));
     }
     for (const o of ordersToUpdate) {
         const partialOrder = o?.partialOrder || o;
@@ -1697,12 +1775,31 @@ function buildCowResultFromPlan(bot, plan) {
         ? requestedBoundary
         : bot.manager.boundaryIdx;
     const actions = buildActionsFromPlan(bot, plan);
+    // Rail-aware hole projection (Phase 2): a cleared in-rail slot stays a
+    // rail-typed VIRTUAL hole with its booked size preserved (rotation
+    // sources keep the remainder the guard/plan must see); only true
+    // gap-band slots become side-neutral SPREAD holes.
+    const toWorkingHole = (slot) => {
+        try {
+            const idx = parseSlotIndex(slot?.id);
+            const b = Number(workingBoundary);
+            const gapSlots = Number(bot?.manager?._gapSlots);
+            if (idx !== null && idx !== undefined && Number.isFinite(b) && Number.isFinite(gapSlots) && gapSlots >= 0) {
+                if (Number(idx) <= b)
+                    return toRailHolePlaceholder(slot, ORDER_TYPES.BUY);
+                if (Number(idx) >= getSellStartIdx(b, gapSlots))
+                    return toRailHolePlaceholder(slot, ORDER_TYPES.SELL);
+            }
+        }
+        catch { /* fall through to SPREAD */ }
+        return convertToSpreadPlaceholder(slot);
+    };
     for (const action of actions) {
         if (action.type === COW_ACTIONS.CANCEL) {
             const current = workingGrid.get(action.id);
             if (!current)
                 continue;
-            workingGrid.set(action.id, convertToSpreadPlaceholder(current));
+            workingGrid.set(action.id, toWorkingHole(current));
         }
         else if (action.type === COW_ACTIONS.CREATE) {
             if (!action.id || !action.order)
@@ -1720,7 +1817,7 @@ function buildCowResultFromPlan(bot, plan) {
             if (action.newGridId && action.newGridId !== action.id) {
                 const current = workingGrid.get(action.id);
                 if (current) {
-                    workingGrid.set(action.id, convertToSpreadPlaceholder(current));
+                    workingGrid.set(action.id, toWorkingHole(current));
                 }
                 const targetId = action.newGridId;
                 const targetCurrent = workingGrid.get(targetId) || { id: targetId };
@@ -1781,7 +1878,11 @@ function applyRotationTransitionsToWorkingGrid(bot, workingGrid, executedContext
             continue;
         const { rotation } = ctx;
         const { oldOrder, newGridId, newPrice, newSize, type } = rotation;
-        // Source slot → VIRTUAL (if it's a different slot)
+        // Source slot → VIRTUAL (if it's a different slot). Phase 2: the
+        // source stays a RAIL-TYPED hole with its booked size preserved —
+        // only state/orderId/rawOnChain are cleared, never type or size
+        // (no SPREAD retype, no zeroing). In-rail sources must remain
+        // visible to candidate-selection and evacuation geometry.
         if (oldOrder?.id && oldOrder.id !== newGridId) {
             const sourceSlot = workingGrid.get(oldOrder.id);
             if (sourceSlot && sourceSlot.orderId) {
@@ -2712,35 +2813,125 @@ async function updateOrdersOnChainBatchCOW(bot, cowResult, options = {}) {
                                 `${crossedOrderLabel(crossedOrder)}; re-planned after its cancel confirms.`, 'warn');
                             continue;
                         }
-                        // LAST-FILL PRICE GUARD (UPDATE rotation): pivot ± halfIncrement — same as CREATE.
-                        // No origin bypass here, ever: a rotation reprices, so it always obeys the guard —
-                        // even if a future correction plan carries rotation entries (per-action scoping).
+                        // LAST-FILL PRICE GUARD (UPDATE rotation): pivot ± halfIncrement — same as CREATE,
+                        // plus the GAP-EVACUATION ALLOWANCE (violation-reducing): a rotation stamped
+                        // origin='gap-evacuation' at plan-build moves a live order OUT of the gap band
+                        // onto its rail with bit-exact non-growing size — it shrinks the violation
+                        // surface instead of adding exposure, so it bypasses the guard. The bypass
+                        // is UPDATE-only (CREATEs carry no source slot and can never qualify) and
+                        // honors the frozen B-stamp (evacBoundary/evacGapSlots captured when the
+                        // plan was built — never re-derived here, since plans can validate against
+                        // a later-committed boundary):
+                        // - B-stamped: plan-build geometry already proved the evacuation; bypass
+                        //   outright (logged + counted as bypassed).
+                        // - Unstamped gap-evacuation: prove it live from oldPrice/oldSize read
+                        //   off the MASTER grid above (bot.manager.orders.get, before rotation
+                        //   pre-application virtualizes sources — after that the lookup lies);
+                        //   fail closed (block) when unresolvable; otherwise run the pure
+                        //   isEvacuationRotationAllowed decision and bypass only on allow.
+                        // Everything else obeys the guard (per-action scoping: a rotation entry
+                        // merged into another plan inherits no bypass).
                         // The pivot is refreshed from still-queued fills first: fills detected mid-broadcast
                         // sit in _incomingFillQueue until the fill cycle ends, and without this the later
                         // chunks of a long broadcast would be checked against a stale pivot.
                         try {
-                            try {
-                                if (refreshLastFillPivotFromQueue(bot))
-                                    lastFillGuardPivotRefreshed = true;
+                            let bypassedEvacuation = false;
+                            const rotationOrigin = action?.origin;
+                            if (rotationOrigin === 'gap-evacuation') {
+                                const frozenB = Number(action?.evacBoundary);
+                                const frozenG = Number(action?.evacGapSlots);
+                                let stampUsable = Number.isFinite(frozenB) && Number.isFinite(frozenG);
+                                if (stampUsable) {
+                                    // Stale-stamp check: the stamp froze PLAN-BUILD
+                                    // geometry; if a boundary commit landed between
+                                    // plan-build and execution and the source is no
+                                    // longer in-band (or dest no longer rail) under
+                                    // the LIVE geometry, re-prove via the unstamped
+                                    // live probe below instead of bypassing outright.
+                                    const stampValid = isEvacuationStampStillValid(bot.manager?.boundaryIdx, bot.manager?._gapSlots, action.id, action.newGridId, orderType);
+                                    if (!stampValid) {
+                                        stampUsable = false;
+                                        bot.manager.logger.log(`[LAST-FILL-GUARD] Stamped evacuation for ${action.id} -> ${action.newGridId} is stale under live ` +
+                                            `boundary ${bot.manager?.boundaryIdx}/gap ${bot.manager?._gapSlots} — re-proving live`, 'warn');
+                                    }
+                                }
+                                if (stampUsable) {
+                                    bypassedEvacuation = true;
+                                    bot.manager.logger.log(`[LAST-FILL-GUARD] Allowing ${orderType} evacuation UPDATE for ${action.id} -> ${action.newGridId} at ${Format.formatPrice6(newPrice)}: ` +
+                                        `gap-evacuation stamped at plan-build (boundary ${frozenB}, gap ${frozenG})`, 'warn');
+                                }
+                                else {
+                                    // Unstamped: prove violation-reducing live. masterOrder was
+                                    // captured from the master grid before any rotation
+                                    // pre-application — it must NOT be re-read afterwards.
+                                    const oldPrice = Number(masterOrder?.price);
+                                    const oldSize = Number(masterOrder?.size);
+                                    if (!Number.isFinite(oldPrice) || !(oldPrice > 0) || !Number.isFinite(oldSize) || !(oldSize > 0)) {
+                                        lastFillGuardStats.checked++;
+                                        lastFillGuardStats.skipped++;
+                                        skippedUpdateCount++;
+                                        if (action.id)
+                                            skippedUpdateSlotIds.add(action.id);
+                                        if (action.newGridId)
+                                            skippedUpdateSlotIds.add(action.newGridId);
+                                        bot.manager.logger.log(`[LAST-FILL-GUARD] Skipping ${orderType} UPDATE for ${action.id} -> ${action.newGridId}: ` +
+                                            `gap-evacuation source unresolvable from master grid (fail-closed)`, 'warn');
+                                        continue;
+                                    }
+                                    let sidePrecision = null;
+                                    try {
+                                        sidePrecision = getPrecisionByOrderType(bot.manager.assets, orderType);
+                                    }
+                                    catch {
+                                        sidePrecision = null;
+                                    }
+                                    // Geometry re-proof under the LIVE boundary: if the
+                                    // source is no longer in-band (or dest no longer rail),
+                                    // this is not an evacuation anymore — fall through to
+                                    // the normal guard instead of bypassing via the probe.
+                                    // Non-finite live geometry cannot disprove; probe proceeds.
+                                    if (isEvacuationStampStillValid(bot.manager?.boundaryIdx, bot.manager?._gapSlots, action.id, action.newGridId, orderType)) {
+                                        const evacCheck = isEvacuationRotationAllowed(oldPrice, oldSize, newPrice, newSize, orderType, sidePrecision);
+                                        if (evacCheck.allowed) {
+                                            bypassedEvacuation = true;
+                                            bot.manager.logger.log(`[LAST-FILL-GUARD] Allowing ${orderType} evacuation UPDATE for ${action.id} -> ${action.newGridId} at ${Format.formatPrice6(newPrice)}: ` +
+                                                `${evacCheck.reason} (probed live: ${Format.formatPrice6(oldPrice)} -> ${Format.formatPrice6(newPrice)})`, 'warn');
+                                        }
+                                    }
+                                    else {
+                                        bot.manager.logger.log(`[LAST-FILL-GUARD] Unstamped evacuation probe for ${action.id} -> ${action.newGridId} rejected: ` +
+                                            `source/dest no longer evacuation geometry under live boundary ${bot.manager?.boundaryIdx}/gap ${bot.manager?._gapSlots} — normal guard applies`, 'warn');
+                                    }
+                                    // Not allowed: fall through to the normal guard below.
+                                }
                             }
-                            catch { /* best-effort */ }
-                            const lastPrice = bot.manager?._lastFilledPrice;
-                            const lastType = bot.manager?._lastFilledType;
-                            const inc = resolveLastFillGuardIncrement(bot);
-                            const check = isLastFillGuardBlocked(newPrice, newSize, orderType, lastPrice, lastType, inc);
-                            lastFillGuardStats.checked++;
-                            if (check.blocked) {
-                                lastFillGuardStats.skipped++;
-                                skippedUpdateCount++;
-                                if (action.id)
-                                    skippedUpdateSlotIds.add(action.id);
-                                if (action.newGridId)
-                                    skippedUpdateSlotIds.add(action.newGridId);
-                                const dir = orderType === ORDER_TYPES.BUY ? 'above' : 'below';
-                                bot.manager.logger.log(`[LAST-FILL-GUARD] Skipping ${orderType} UPDATE for ${action.id} -> ${action.newGridId} at ${Format.formatPrice6(newPrice)}: ${dir} last filled ${Format.formatPrice6(check.pivot)} (halfInc ${check.halfInc}% thr ${Format.formatPrice6(check.threshold)})`, 'warn');
-                                continue;
+                            if (bypassedEvacuation) {
+                                lastFillGuardStats.bypassed++;
+                            }
+                            else {
+                                try {
+                                    if (refreshLastFillPivotFromQueue(bot))
+                                        lastFillGuardPivotRefreshed = true;
+                                }
+                                catch { /* best-effort */ }
+                                const lastPrice = bot.manager?._lastFilledPrice;
+                                const lastType = bot.manager?._lastFilledType;
+                                const inc = resolveLastFillGuardIncrement(bot);
+                                const check = isLastFillGuardBlocked(newPrice, newSize, orderType, lastPrice, lastType, inc);
+                                lastFillGuardStats.checked++;
+                                if (check.blocked) {
+                                    lastFillGuardStats.skipped++;
+                                    skippedUpdateCount++;
+                                    if (action.id)
+                                        skippedUpdateSlotIds.add(action.id);
+                                    if (action.newGridId)
+                                        skippedUpdateSlotIds.add(action.newGridId);
+                                    const dir = orderType === ORDER_TYPES.BUY ? 'above' : 'below';
+                                    bot.manager.logger.log(`[LAST-FILL-GUARD] Skipping ${orderType} UPDATE for ${action.id} -> ${action.newGridId} at ${Format.formatPrice6(newPrice)}: ${dir} last filled ${Format.formatPrice6(check.pivot)} (halfInc ${check.halfInc}% thr ${Format.formatPrice6(check.threshold)})`, 'warn');
+                                    continue;
+                                }
+                                lastFillGuardStats.passed++;
                             }
-                            lastFillGuardStats.passed++;
                         }
                         catch (_e) { /* best-effort */ }
                         const { amountToSell, minToReceive } = buildCreateOrderArgs({ type: orderType, size: newSize, price: newPrice }, assetA, assetB);