dexbot 1.7.0 → 1.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/CHANGELOG.md +70 -0
  2. package/README.md +3 -3
  3. package/analysis/README.md +33 -13
  4. package/claw/package.json +1 -1
  5. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  6. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  7. package/dist/analysis/account_resolver.js +5 -6
  8. package/dist/analysis/analyze_liquidity.js +15 -4
  9. package/dist/analysis/bot_key_utils.d.ts +44 -1
  10. package/dist/analysis/bot_key_utils.js +76 -7
  11. package/dist/analysis/fills_cache.js +2 -1
  12. package/dist/analysis/grid_correction_check.d.ts +1 -19
  13. package/dist/analysis/grid_correction_check.js +12 -30
  14. package/dist/analysis/liquidity/liquidity_chart_generator.js +190 -20
  15. package/dist/analysis/liquidity/liquidity_depth_model.d.ts +41 -16
  16. package/dist/analysis/liquidity/liquidity_depth_model.js +49 -21
  17. package/dist/analysis/liquidity/liquidity_view.d.ts +15 -0
  18. package/dist/analysis/liquidity/liquidity_view.js +11 -0
  19. package/dist/analysis/resolve_bot_accounts.js +7 -6
  20. package/dist/analysis/trade_profitability.js +2 -1
  21. package/dist/credential-daemon.js +13 -2
  22. package/dist/dexbot.js +4 -4
  23. package/dist/modules/account_bots.d.ts +12 -1
  24. package/dist/modules/account_bots.js +7 -5
  25. package/dist/modules/account_orders.d.ts +12 -0
  26. package/dist/modules/account_orders.js +30 -0
  27. package/dist/modules/bitshares-native/transport.js +24 -6
  28. package/dist/modules/bitshares_client.d.ts +24 -6
  29. package/dist/modules/bitshares_client.js +44 -7
  30. package/dist/modules/bot_settings.d.ts +2 -0
  31. package/dist/modules/constants.d.ts +28 -3
  32. package/dist/modules/constants.js +79 -10
  33. package/dist/modules/dexbot_class.d.ts +23 -6
  34. package/dist/modules/dexbot_class.js +44 -0
  35. package/dist/modules/dexbot_cow_runtime.d.ts +128 -8
  36. package/dist/modules/dexbot_cow_runtime.js +688 -188
  37. package/dist/modules/dexbot_fill_runtime.js +124 -35
  38. package/dist/modules/dexbot_maintenance_runtime.d.ts +1 -1
  39. package/dist/modules/dexbot_maintenance_runtime.js +259 -79
  40. package/dist/modules/dexbot_startup_runtime.js +32 -20
  41. package/dist/modules/dexbot_state_recovery.d.ts +33 -1
  42. package/dist/modules/dexbot_state_recovery.js +167 -5
  43. package/dist/modules/node_connect_policy.d.ts +8 -1
  44. package/dist/modules/node_connect_policy.js +18 -2
  45. package/dist/modules/node_flap_score.d.ts +87 -0
  46. package/dist/modules/node_flap_score.js +124 -0
  47. package/dist/modules/node_health_cache.d.ts +40 -3
  48. package/dist/modules/node_health_cache.js +66 -20
  49. package/dist/modules/node_manager.d.ts +101 -19
  50. package/dist/modules/node_manager.js +255 -65
  51. package/dist/modules/order/accounting.d.ts +9 -4
  52. package/dist/modules/order/accounting.js +131 -19
  53. package/dist/modules/order/async_lock.d.ts +7 -1
  54. package/dist/modules/order/async_lock.js +7 -1
  55. package/dist/modules/order/export.js +25 -18
  56. package/dist/modules/order/fill_ledger.d.ts +99 -0
  57. package/dist/modules/order/fill_ledger.js +103 -0
  58. package/dist/modules/order/format.d.ts +24 -10
  59. package/dist/modules/order/format.js +30 -10
  60. package/dist/modules/order/grid.d.ts +75 -18
  61. package/dist/modules/order/grid.js +289 -72
  62. package/dist/modules/order/grid_reconcile.d.ts +5 -1
  63. package/dist/modules/order/grid_reconcile.js +333 -210
  64. package/dist/modules/order/grid_reconcile_internal.d.ts +38 -2
  65. package/dist/modules/order/grid_reconcile_internal.js +223 -91
  66. package/dist/modules/order/index.d.ts +18 -5
  67. package/dist/modules/order/index.js +5 -5
  68. package/dist/modules/order/lifecycle.d.ts +353 -0
  69. package/dist/modules/order/lifecycle.js +1109 -0
  70. package/dist/modules/order/manager.d.ts +277 -20
  71. package/dist/modules/order/manager.js +680 -64
  72. package/dist/modules/order/placement_lock.d.ts +102 -0
  73. package/dist/modules/order/placement_lock.js +222 -0
  74. package/dist/modules/order/strategy.js +13 -1
  75. package/dist/modules/order/sync_engine.d.ts +74 -114
  76. package/dist/modules/order/sync_engine.js +254 -198
  77. package/dist/modules/order/utils/math.d.ts +29 -4
  78. package/dist/modules/order/utils/math.js +61 -4
  79. package/dist/modules/order/utils/order.d.ts +106 -37
  80. package/dist/modules/order/utils/order.js +256 -81
  81. package/dist/modules/order/utils/system.d.ts +99 -6
  82. package/dist/modules/order/utils/system.js +249 -35
  83. package/dist/modules/order/utils/validate.d.ts +7 -1
  84. package/dist/modules/order/utils/validate.js +48 -2
  85. package/dist/modules/outcome.d.ts +54 -0
  86. package/dist/modules/outcome.js +51 -0
  87. package/dist/modules/settings_merge.d.ts +4 -0
  88. package/dist/modules/settings_merge.js +9 -0
  89. package/dist/modules/timing_policy.d.ts +82 -0
  90. package/dist/modules/timing_policy.js +244 -0
  91. package/dist/modules/types.d.ts +149 -22
  92. package/dist/scripts/analyze-credit.js +54 -17
  93. package/dist/scripts/analyze-orders.d.ts +4 -2
  94. package/dist/scripts/analyze-orders.js +113 -34
  95. package/dist/scripts/chart_targets.js +11 -15
  96. package/dist/scripts/test-credit-renewal.js +12 -5
  97. package/docs/COW_INVARIANTS.md +71 -8
  98. package/docs/DEXBOT_COMPARISON.md +6 -6
  99. package/docs/EVOLUTION.md +10 -8
  100. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  101. package/docs/GRID_PRICE_INVARIANT.md +1 -1
  102. package/docs/GRID_RECONCILE.md +18 -13
  103. package/docs/LOGGING.md +25 -1
  104. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +183 -26
  105. package/docs/README.md +23 -2
  106. package/docs/WORKFLOW.md +9 -3
  107. package/docs/architecture.md +68 -13
  108. package/docs/developer_guide.md +25 -8
  109. package/modules/README.md +6 -0
  110. package/package.json +3 -3
  111. package/scripts/README.md +16 -0
  112. package/scripts/pdev.sh +14 -1
  113. package/scripts/pmain.sh +23 -8
  114. package/scripts/ptest.sh +7 -0
  115. package/tests/README.md +30 -1
@@ -15,7 +15,7 @@
15
15
  * Uses AsyncLock to prevent concurrent sync operations (defense-in-depth locking).
16
16
  *
17
17
  * ===============================================================================
18
- * TABLE OF CONTENTS - SyncEngine Class (12 methods) + module-level helpers
18
+ * TABLE OF CONTENTS - SyncEngine Class (14 methods) + module-level helpers
19
19
  * ===============================================================================
20
20
  *
21
21
  * MODULE-LEVEL HELPERS (internal, not exported):
@@ -42,42 +42,46 @@
42
42
  * 4. _performSyncFromOpenOrders(mgr, precA, precB, parsedChain, rawChain, options) - Core sync logic (internal)
43
43
  * Performs actual two-pass reconciliation without locking
44
44
  * Pass 1: Match grid orders to chain (known grid → chain, includes orphan cleanup)
45
- * Pass 2: Add missing chain orders (unknown chain → grid)
45
+ * Pass 2: Bind unmatched chain orders to their genesis-ladder slot (chain → grid)
46
46
  *
47
- * FILL PROCESSING (5 methods)
47
+ * FILL PROCESSING (6 methods)
48
48
  * 5. _findMatchingGridOrder(mgr, orderId) - Look up the grid slot owning a chain order (internal)
49
49
  *
50
- * 6. _computeFillContext(mgr, matchedGridOrder, paysAssetId, paysAmountRaw) -
51
- * Resolve the asset/side context for a fill (internal)
50
+ * 6. _computeFillContext(mgr, matchedGridOrder, paysAssetId, paysAmountRaw,
51
+ * receivesAssetId, receivesAmountRaw) - Resolve the asset/side context for
52
+ * a fill (internal)
52
53
  *
53
54
  * 7. _computeFillTransitionResult(mgr, params) - Compute the post-fill slot
54
55
  * transition and fund deltas without mutating state (internal, async)
55
56
  *
56
- * 8. syncFromFillHistory(fill) - Process single fill event synchronously
57
+ * 8. _absorbUnmatchedFill(mgr, params) - Attribute a fill whose slot was
58
+ * already virtualised (thin wrapper over utils/order.ts) (internal, async)
59
+ *
60
+ * 9. syncFromFillHistory(fill) - Process single fill event synchronously
57
61
  * Updates grid order state based on fill data
58
62
  * Updates fund state and accounting
59
63
  * Handles both maker and taker fills
60
64
  *
61
- * 9. syncFromFillHistoryBatch(fills) - Process multiple fill events in batch
65
+ * 10. syncFromFillHistoryBatch(fills) - Process multiple fill events in batch
62
66
  * Acquires _gridLock once for all fills in block group
63
67
  * Batches drift refetch into one get_objects RPC call
64
68
  * Applies all grid mutations in a single applyGridUpdateBatch
65
69
  *
66
70
  * FULL SYNCHRONIZATION (2 methods - async)
67
- * 10. _assertGenesisInvariant(mgr) - Fail-closed check that a snapshot has a genesis ladder (internal)
71
+ * 11. _assertGenesisInvariant(mgr) - Fail-closed check that a snapshot has a genesis ladder (internal)
68
72
  *
69
- * 11. synchronizeWithChain(chainData, source) - Full sync (fetch + sync) (async)
73
+ * 12. synchronizeWithChain(chainData, source) - Full sync (fetch + sync) (async)
70
74
  * Fetches fresh account balances
71
75
  * Calls syncFromOpenOrders() with chain data
72
76
  * Source: event type that triggered sync (fill, poll, broadcast, etc.)
73
77
  *
74
78
  * ACCOUNT STATE (2 methods - async)
75
- * 12. fetchAccountBalancesAndSetTotals() - Fetch account totals (async)
79
+ * 13. fetchAccountBalancesAndSetTotals() - Fetch account totals (async)
76
80
  * Retrieves BUY/SELL totals and free balances from blockchain
77
81
  * Sets manager.accountTotals
78
82
  * Triggers fund recalculation
79
83
  *
80
- * 13. initializeAssets() - Initialize asset metadata (async)
84
+ * 14. initializeAssets() - Initialize asset metadata (async)
81
85
  * Fetches asset precision and other metadata
82
86
  * Sets manager.assets
83
87
  * Called once at bot startup
@@ -101,10 +105,16 @@
101
105
  * - Update sizes and mark as filled if needed
102
106
  * - Downgrade to VIRTUAL if not found on-chain
103
107
  *
104
- * PASS 2: Chain → Grid
105
- * - For each chain order not matched to grid order
106
- * - Create new grid order for unexpected chain order
107
- * - Mark as ACTIVE with blockchain orderId
108
+ * PASS 2: Chain → Grid (genesis-frozen nearest-slot adoption)
109
+ * - For each chain order not matched in pass 1, resolve its slot from the
110
+ * frozen price ladder (`slotIndexForPrice`) and adopt it there
111
+ * - No tolerance matcher remains: without a ladder the E2 gate refuses the
112
+ * sync, and a ladder-less grid defers every orphan instead of matching it
113
+ * - A price outside the grid range is HELD/deferred (nearest slot is only
114
+ * reported as a hint) — it is never adopted into a rail slot
115
+ * - An order whose price cannot be resolved to a slot is queued for a
116
+ * cancel-only correction; the deferred (no-ladder / out-of-grid) cases are
117
+ * logged and held, never dropped silently
108
118
  *
109
119
  * ===============================================================================
110
120
  */
@@ -138,9 +148,11 @@ function batchReadOrdersSeam(mgr, orderIds, timeoutMs) {
138
148
  const { BitShares } = client;
139
149
  import { NATIVE_CLIENT } from '../constants.js';
140
150
  const { toFiniteNumber } = Format;
141
- import { blockchainToFloat, floatToBlockchainInt, getAssetFees, getBtsSide, slotIndexForPrice, isChainPriceOutOfGrid, isSlotInRail, priceForSlot, priceSlotEqual, pricesOnSameLevel } from './utils/math.js';
151
+ import { blockchainToFloat, floatToBlockchainInt, getAssetFees, getBtsSide, slotIndexForPrice, isChainPriceOutOfGrid, isSlotInRail, resolveGapSlots, priceForSlot, priceSlotEqual, pricesOnSameLevel } from './utils/math.js';
142
152
  import { parseChainOrder, geometryTypeForSlotIndex, applyChainSizeToGridOrder, convertToSpreadPlaceholder, virtualizeOrder, buildFillKey, isOrderPlaced, hasOnChainId, isOrderVirtual, resolveSpreadOrderSide, duplicateOrphanLogInfo, _stampCorrectionProvenance, _filterUnmatchedChainOrders, attributeUnmatchedFillToGrid, reviveVirtualSlotFromChain, resolveExecutionPrice } from './utils/order.js';
143
153
  import { parseSlotIndex } from './utils/slot.js';
154
+ import { readSlotLifecycle } from './lifecycle.js';
155
+ import { resolveTradedSide } from './fill_ledger.js';
144
156
  import { resolveProcessedFillPersistenceMode } from './processed_fill_store.js';
145
157
  import { hasGenesisLadder } from './genesis_policy.js';
146
158
  import { getErrorMessage } from '../utils/errors.js';
@@ -497,6 +509,20 @@ async function adoptChainOrderIntoSlot(mgr, slot, chainOrder, chainOrderId, rawC
497
509
  matchedGridOrderIds.delete(bestMatch.id);
498
510
  return false;
499
511
  }
512
+ // ADOPTION IS CHAIN EVIDENCE: a chain order was matched into this slot by
513
+ // this very snapshot, so record it as such. The write funnel can only speak
514
+ // for the LOCAL slot state ('local'); without this the registry would claim a
515
+ // purely local basis for the strongest thing we know about the order, and
516
+ // `observedAt` ("when did the chain last tell us anything") would never
517
+ // advance for adoptions.
518
+ try {
519
+ mgr._lifecycle?.markLanded?.(chainOrderId, {
520
+ slotId: String(bestMatch.id),
521
+ evidence: 'adoption',
522
+ phase: bestMatch.state === ORDER_STATES.PARTIAL ? 'filling' : 'landed',
523
+ });
524
+ }
525
+ catch { /* lifecycle bookkeeping must never break adoption */ }
500
526
  updatedOrders.push(bestMatch);
501
527
  chainOrderIdsOnGrid.add(chainOrderId);
502
528
  // Adopted means matched: drop any deferred-orphan record so fund counting
@@ -516,72 +542,15 @@ class SyncEngine {
516
542
  this.manager = manager;
517
543
  }
518
544
  /**
519
- * Reconcile grid orders against fresh blockchain open orders snapshot.
520
- * This is the MAIN SYNCHRONIZATION MECHANISM that corrects the grid state when
521
- * the blockchain state diverges from our local expectations.
545
+ * Reconcile grid orders against a fresh blockchain open-orders snapshot.
546
+ * This is the MAIN SYNCHRONIZATION MECHANISM: it corrects the grid when the
547
+ * chain state diverges from local expectations. The two-pass structure, the
548
+ * lock hierarchy and the per-pass rules live in the module header; the
549
+ * fail-closed genesis gate (E2) runs before anything is touched.
522
550
  *
523
- * CRITICAL: This method uses AsyncLock (defense-in-depth) to ensure only one
524
- * full-sync operation runs at a time. WITHIN that lock, per-order locks prevent
525
- * concurrent createOrder/cancelOrder races.
526
- *
527
- * LOCK HIERARCHY:
528
- * 1. _syncLock (AsyncLock): Ensures only one full-sync at a time
529
- * 2. Per-order locks (shadowOrderIds): Protect specific orders during sync
530
- * 3. Lock refresh mechanism: Prevents timeout during long reconciliation
531
- *
532
- * RECONCILIATION FLOW:
533
- * ========================================================================
534
- * This method performs a two-pass reconciliation:
535
- *
536
- * PASS 1: Match grid orders to chain orders (known grid → chain lookup)
537
- * - For each grid order with an orderId, find the matching chain order
538
- * - Detect partial fills: if chain size < grid size, downgrade to PARTIAL state
539
- * - Detect full fills: if order no longer exists on chain, convert to SPREAD
540
- * - Detect price slippage: flag orders for price correction if needed
541
- * - Update grid order sizes to match chain reality
542
- *
543
- * PASS 2: Orphan chain orders (chain → grid lookup)
544
- * - For chain orders not matched in Pass 1, find best grid slot match
545
- * - This handles cases where an order was placed but grid lost track (race condition)
546
- * - Uses price tolerance and geometric proximity to find the best match
547
- * - Once matched, retroactively assign orderId and synchronize state
548
- *
549
- * CRITICAL RULES:
550
- * 1. ACTIVE orders can only stay ACTIVE if size matches chain exactly
551
- * If chain size < grid size → must transition to PARTIAL
552
- * 2. If an ACTIVE order is not found on chain → it filled → convert to SPREAD
553
- * 3. Precision matters: Use blockchain integer arithmetic to compare sizes
554
- * Floating point comparisons can give false positives for partial fills
555
- * 4. Size updates are applied via applyChainSizeToGridOrder() which handles
556
- * precision conversion and may adjust sizes slightly for blockchain granularity
557
- *
558
- * PRICE TOLERANCE CALCULATION:
559
- * calculatePriceTolerance() can return null in these cases:
560
- * 1. assets parameter is null/missing
561
- * 2. gridPrice is 0 or null (invalid price)
562
- * 3. orderSize is 0 or null (invalid size - orders should not sync with 0 size)
563
- * 4. assetA or assetB precision is undefined (asset metadata not loaded)
564
- * When tolerance is null, we treat it as 0 (strict: any price difference flagged).
565
- * This is safe because null signals a configuration/data issue, not a real order.
566
- *
567
- * RETURNS: { filledOrders, updatedOrders, ordersNeedingCorrection }
568
- * - filledOrders: Orders that completed (now SPREAD placeholders)
569
- * - updatedOrders: All orders modified during sync (state changes, size updates)
570
- * - ordersNeedingCorrection: Orders with price slippage requiring correction
571
- *
572
- * EDGE CASES HANDLED:
573
- * - Orphan chain orders (placed but grid lost track due to race condition)
574
- * - Partial fills (size reduced on chain)
575
- * - Full fills (order removed from chain completely)
576
- * - Price tolerance (small slippage acceptable, large slippage flagged)
577
- * - Precision mismatches (blockchain integer precision vs float grid)
578
- * - Double spending prevention (each chain order matched to at most one grid order)
579
- */
580
- /**
581
- * Synchronize grid orders with blockchain open orders snapshot.
582
551
  * @param {Array|null} chainOrders - Array of blockchain order objects
583
552
  * @param {Object} [options={}] - Sync options (e.g., { skipAccounting: true })
584
- * @returns {Promise<Object>} Result with filledOrders, updatedOrders, ordersNeedingCorrection
553
+ * @returns {Promise<SyncResult>} filledOrders, updatedOrders, ordersNeedingCorrection
585
554
  */
586
555
  async syncFromOpenOrders(chainOrders, options = {}) {
587
556
  const mgr = this.manager;
@@ -781,17 +750,30 @@ class SyncEngine {
781
750
  // This eliminates type confusion - each map has a single, clear purpose
782
751
  const parsedChainOrders = new Map();
783
752
  const rawChainOrders = new Map();
753
+ // Unparseable chain orders are UNKNOWN, not absent. A live order the
754
+ // node returned but we could not decode must never make its slot look
755
+ // empty: that virtualizes a real order and re-CREATEs on top of it.
756
+ // The id set is threaded into pass 1 so the absence decision can consult
757
+ // it (mirrors the accounting recovery sweep's `malformedOrderIds`).
758
+ const malformedChainOrderIds = new Set();
784
759
  for (const order of chainOrders) {
785
760
  try {
786
761
  const parsed = parseChainOrder(order, mgr.assets);
787
- if (!parsed)
762
+ if (!parsed) {
763
+ const rawId = order.id;
764
+ if (rawId != null)
765
+ malformedChainOrderIds.add(String(rawId));
788
766
  continue;
767
+ }
789
768
  // Store parsed (converted) data in parsedChainOrders
790
769
  parsedChainOrders.set(order.id, parsed);
791
770
  // Store raw blockchain data in separate map - clean separation of concerns
792
771
  rawChainOrders.set(order.id, order);
793
772
  }
794
773
  catch (e) {
774
+ const rawId = order.id;
775
+ if (rawId != null)
776
+ malformedChainOrderIds.add(String(rawId));
795
777
  mgr.logger?.log?.(`Warning: Error parsing chain order ${order.id}: ${getErrorMessage(e)}`, 'warn');
796
778
  continue;
797
779
  }
@@ -902,7 +884,7 @@ class SyncEngine {
902
884
  const runReconciliation = async () => {
903
885
  mgr.pauseFundRecalc();
904
886
  try {
905
- await this._performSyncFromOpenOrders(mgr, assetAPrecision, assetBPrecision, parsedChainOrders, rawChainOrders, chainOrderIdsOnGrid, matchedGridOrderIds, filledOrders, updatedOrders, ordersNeedingCorrection, unmatchedChainOrders, options);
887
+ await this._performSyncFromOpenOrders(mgr, assetAPrecision, assetBPrecision, parsedChainOrders, rawChainOrders, malformedChainOrderIds, chainOrderIdsOnGrid, matchedGridOrderIds, filledOrders, updatedOrders, ordersNeedingCorrection, unmatchedChainOrders, options);
906
888
  }
907
889
  finally {
908
890
  await mgr.resumeFundRecalc();
@@ -924,6 +906,7 @@ class SyncEngine {
924
906
  * @param {number} assetBPrecision - Asset B precision
925
907
  * @param {Map<string, any>} parsedChainOrders - Parsed chain orders by ID
926
908
  * @param {Map<string, Object>} rawChainOrders - Raw blockchain order objects by ID
909
+ * @param {Set<string>} malformedChainOrderIds - Chain order IDs that were returned but could not be parsed (UNKNOWN, not absent)
927
910
  * @param {Set<string>} chainOrderIdsOnGrid - Output set: chain order IDs matched to grid
928
911
  * @param {Set<string>} matchedGridOrderIds - Output set: grid order IDs matched to chain
929
912
  * @param {Array<Object>} filledOrders - Output array: orders detected as filled
@@ -933,7 +916,7 @@ class SyncEngine {
933
916
  * @param {Object} options - Sync options (skipAccounting, etc.)
934
917
  * @returns {Promise<any>}
935
918
  */
936
- async _performSyncFromOpenOrders(mgr, assetAPrecision, assetBPrecision, parsedChainOrders, rawChainOrders, chainOrderIdsOnGrid, matchedGridOrderIds, filledOrders, updatedOrders, ordersNeedingCorrection, unmatchedChainOrders, options) {
919
+ async _performSyncFromOpenOrders(mgr, assetAPrecision, assetBPrecision, parsedChainOrders, rawChainOrders, malformedChainOrderIds, chainOrderIdsOnGrid, matchedGridOrderIds, filledOrders, updatedOrders, ordersNeedingCorrection, unmatchedChainOrders, options) {
937
920
  const skipAccounting = (options?.skipAccounting ?? true);
938
921
  const queueCorrection = (entry) => {
939
922
  // Provenance: classify the detector so a stale replay at drain
@@ -972,6 +955,14 @@ class SyncEngine {
972
955
  continue;
973
956
  let updatedOrder = { ...gridOrder };
974
957
  chainOrderIdsOnGrid.add(gridOrder.orderId);
958
+ // A grid order matched against this snapshot IS a chain
959
+ // observation: record it with the only evidence kind that
960
+ // advances `observedAt` (when did the chain last tell us).
961
+ mgr._lifecycle?.markLanded?.(String(gridOrder.orderId), {
962
+ slotId: String(gridOrder.id),
963
+ evidence: 'chain-snapshot',
964
+ phase: gridOrder.state === ORDER_STATES.PARTIAL ? 'filling' : 'landed',
965
+ });
975
966
  // REVIVE BEFORE ANYTHING ELSE: this slot is not placed but its
976
967
  // chain order is still live. Leaving it VIRTUAL is the "dark
977
968
  // level" state — invisible to window accounting
@@ -1183,6 +1174,19 @@ class SyncEngine {
1183
1174
  // divergence re-detects on the next sync.
1184
1175
  mgr.logger?.log?.(`[SYNC] Partial-size update for ${gridOrder.id} rejected — slot keeps booked size ${gridOrder.size}`, 'warn');
1185
1176
  }
1177
+ else if (chainSizeInt < currentSizeInt && gridOrder.orderId) {
1178
+ // Mark the fill's size/fund delta as already absorbed:
1179
+ // the fill-history batch that follows must not shrink
1180
+ // (or credit) it a second time.
1181
+ mgr.noteChainSizeAppliedFill?.(String(gridOrder.orderId), currentSizeInt - chainSizeInt);
1182
+ // The marker is persisted with the grid snapshot
1183
+ // (debugInputs). Force the snapshot dirty AFTER
1184
+ // recording it: a flush already queued by
1185
+ // _applyOrderUpdate may have captured the grid
1186
+ // without the marker, and a crash in that window
1187
+ // would replay the fill as a second shrink.
1188
+ mgr._markGridDirty?.();
1189
+ }
1186
1190
  }
1187
1191
  else {
1188
1192
  const spreadOrder = convertToSpreadPlaceholder(gridOrder);
@@ -1216,59 +1220,68 @@ class SyncEngine {
1216
1220
  // genuine fill on the other side.
1217
1221
  // Don't virtualize orders placed by a successful COW commit.
1218
1222
  // The chain snapshot may lag behind confirmed transactions,
1219
- // causing correctly-placed orders to appear missing. _committedOrderIds
1220
- // is atomically rebuilt from every successful COW commit
1223
+ // causing correctly-placed orders to appear missing. The committed
1224
+ // snapshot is published by every successful COW commit
1221
1225
  // (manager.ts:_commitWorkingGrid) and is always active for all sync
1222
- // paths.
1223
- // filled/virtualized orders are absent from the next commit's
1224
- // finalMap, so their IDs drop out on the next atomic rebuild.
1225
- //
1226
- // SAFETY: _committedOrderIds is replaced atomically (reference swap)
1227
- // by _commitWorkingGrid. The sync reads has(gridOrder.orderId) against the
1228
- // current reference. If a concurrent COW commit replaces the set mid-sync,
1229
- // the new set is a superset (only adds entries for newly committed orders).
1230
- // An order in the superset was just committed, so it is genuinely on-chain
1231
- // and should not be virtualized. An order removed from the old set was
1232
- // filled/virtualized, which the sync will detect independently via the
1233
- // chain snapshot. Superset behavior is safe for this guard.
1226
+ // paths. Filled/virtualized orders are absent from the next commit's
1227
+ // finalMap, so their IDs drop out on the next atomic publish.
1234
1228
  //
1235
1229
  // ESCAPE HATCH 1 — Ghost orders (PARTIAL + size=0): These preserve the
1236
1230
  // original orderId only to block duplicate CREATEs after a full fill
1237
- // that the chain hasn't closed yet. The orderId is in _committedOrderIds
1238
- // because the original order was COW-placed, but the slot is already a
1239
- // known fill. Allow phantom detection to proceed so the ghost is cleaned
1240
- // up on the next sync cycle after the chain cancel succeeds.
1231
+ // that the chain hasn't closed yet. The orderId is in the committed
1232
+ // snapshot because the original order was COW-placed, but the slot is
1233
+ // already a known fill. Allow phantom detection to proceed so the ghost
1234
+ // is cleaned up on the next sync cycle after the chain cancel succeeds.
1235
+ //
1236
+ // ESCAPE HATCH 2 — Time-based: the lifecycle in-flight window is
1237
+ // bounded (2× the pending-broadcast TTL), so a permanently lagging
1238
+ // node cannot park cleanup forever; past it the committed-but-missing
1239
+ // order is presumed genuinely filled. This is what keeps a missed fill
1240
+ // event (reconnect gap, lossy subscription) from stalling the grid.
1241
1241
  //
1242
- // ESCAPE HATCH 2 — Time-based: If the most recent COW commit is older
1243
- // than SYNC_LOCK_TIMEOUT_MS, the committed-but-missing order is
1244
- // presumed genuinely filled. The chain should have confirmed or
1245
- // rejected the transaction within the sync timeout window (~7 blocks
1246
- // at 3s each). Prevents permanent stall when a fill event was missed
1247
- // (reconnect gap, lossy subscription) and the only detection path is
1248
- // this open-orders sync.
1249
- if (gridOrder.orderId != null && mgr._committedOrderIds?.has(gridOrder.orderId)) {
1250
- const commitAge = Date.now() - (mgr._committedOrderIdsBuiltAt || 0);
1242
+ // ONE GUARD: the absence decision asks `isInFlight()` — the single
1243
+ // definition of "absence is not trustworthy yet". This site used to
1244
+ // consult the committed window and the fresh-assignment window
1245
+ // separately, while the startup reconcile and the fund recalibration
1246
+ // sweep asked `isInFlight()`: same order, three different answers for
1247
+ // the `unknown`/`broadcasting` phases (an abandoned CREATE receipt, an
1248
+ // unreadable chain entry). Those phases are exactly what the guard is
1249
+ // for, so reading a subset here re-opened the bug class it exists to
1250
+ // close.
1251
+ if (gridOrder.orderId != null) {
1252
+ const slotLifecycle = readSlotLifecycle(mgr, gridOrder);
1251
1253
  const isGhost = gridOrder.size <= 0 && gridOrder.state === ORDER_STATES.PARTIAL;
1252
- if (!isGhost && commitAge < TIMING.SYNC_LOCK_TIMEOUT_MS) {
1254
+ // Guard 0: the order was returned but could not be decoded.
1255
+ // Absence is UNKNOWN — keep the id and let a later, readable
1256
+ // snapshot decide. Reading an unparseable entry as absent
1257
+ // virtualizes a live order and duplicates it on re-create.
1258
+ if (malformedChainOrderIds.has(String(gridOrder.orderId))) {
1259
+ mgr._lifecycle?.markUnknown?.(String(gridOrder.orderId), {
1260
+ slotId: String(gridOrder.id),
1261
+ evidence: 'chain-snapshot',
1262
+ });
1263
+ mgr.logger?.log?.(`[SYNC] ${gridOrder.id}: chain order ${gridOrder.orderId} is present but unparseable — ` +
1264
+ `absence is UNKNOWN (not virtualizing)`, 'warn');
1265
+ continue;
1266
+ }
1267
+ // Ghosts are known fills: they must pass so the cleanup runs.
1268
+ if (!isGhost && slotLifecycle.isInFlight()) {
1269
+ if (gridOrder.state === ORDER_STATES.ACTIVE || gridOrder.state === ORDER_STATES.PARTIAL) {
1270
+ mgr.logger?.log?.(`[SYNC] ${gridOrder.id}: chain order ${gridOrder.orderId} is absent from the snapshot but ` +
1271
+ `${slotLifecycle.isUnresolved
1272
+ ? 'its lifecycle phase is unresolved'
1273
+ : 'it was assigned/committed recently'} — absence not yet trustworthy`, 'debug');
1274
+ }
1275
+ else {
1276
+ mgr.logger?.log?.(`[SYNC] Stale-id check for ${gridOrder.id} deferred: chain id ${gridOrder.orderId} was ` +
1277
+ `assigned recently and is not in the snapshot — absence not yet trustworthy`, 'debug');
1278
+ }
1253
1279
  continue;
1254
1280
  }
1255
1281
  }
1256
1282
  const currentGridOrder = mgr.orders.get(gridOrder.id) || gridOrder;
1257
1283
  const hadOrderId = Boolean(currentGridOrder?.orderId);
1258
1284
  const wasPlaced = isOrderPlaced(currentGridOrder);
1259
- // A freshly assigned id on a NON-placed slot is not trustworthy
1260
- // evidence of absence yet (an in-flight create/cancel whose
1261
- // broadcast has not landed, or a lagging read). Mirrors the
1262
- // reconcile's _orderIdAssignedAt deferral: keep the id, re-check
1263
- // next sync. A PLACED slot keeps the existing behaviour.
1264
- if (!wasPlaced && hadOrderId) {
1265
- const assignedAt = Number(mgr._orderIdAssignedAt?.get(String(currentGridOrder.orderId)) || 0);
1266
- if (assignedAt > 0 && Date.now() - assignedAt < TIMING.SYNC_LOCK_TIMEOUT_MS) {
1267
- mgr.logger?.log?.(`[SYNC] Stale-id check for ${gridOrder.id} deferred: chain id ${currentGridOrder.orderId} was ` +
1268
- `assigned ${Date.now() - assignedAt}ms ago and is not in the snapshot — absence not yet trustworthy`, 'debug');
1269
- continue;
1270
- }
1271
- }
1272
1285
  const spreadOrder = convertToSpreadPlaceholder(currentGridOrder);
1273
1286
  const cleanupContext = wasPlaced ? 'sync-cleanup-phantom' : 'sync-clear-stale-id';
1274
1287
  const phantomApplied = await mgr._applyOrderUpdate(spreadOrder, cleanupContext, { skipAccounting: skipAccounting, fee: 0 });
@@ -1386,7 +1399,11 @@ class SyncEngine {
1386
1399
  continue;
1387
1400
  }
1388
1401
  }
1389
- const gapSlots = genesis?.gapSlots ?? mgr._gapSlots ?? 0;
1402
+ // Unknown geometry must NOT read as gap 0 (a 0-wide band turns the
1403
+ // slot just above the boundary into a SELL rail slot, so an in-band
1404
+ // orphan could be adopted onto the wrong rail). resolveGapSlots is
1405
+ // the single source of truth (_gapSlots ?? config-derived).
1406
+ const gapSlots = genesis?.gapSlots ?? resolveGapSlots(mgr);
1390
1407
  const boundaryIdx = mgr.boundaryIdx;
1391
1408
  // Pre-boundary sync: gap geometry is unknown, so adoption is
1392
1409
  // deferred entirely — touch nothing (no adopt, no cancelOnly).
@@ -1484,31 +1501,34 @@ class SyncEngine {
1484
1501
  const assets = mgr.assets;
1485
1502
  if (!assets?.assetA || !assets?.assetB)
1486
1503
  throw new Error('assets required for fill context');
1487
- // A SPREAD slot can carry an on-chain order (e.g. spread-correction
1488
- // activation). Resolve the real side from the fill's pays asset so the
1489
- // transition result is BUY/SELL — never SPREAD with an on-chain state,
1490
- // which validateOrder rejects as fatal ILLEGAL_SPREAD_STATE. When the
1491
- // pays asset matches neither side (malformed fill event), fall back to
1492
- // the price-vs-startPrice convention so the type can never leak SPREAD
1493
- // into a fill result (which would drop the boundary shift downstream).
1494
- let orderType = matchedGridOrder.type;
1495
- if (orderType === ORDER_TYPES.SPREAD) {
1496
- if (paysAssetId === assets.assetB.id)
1497
- orderType = ORDER_TYPES.BUY;
1498
- else if (paysAssetId === assets.assetA.id)
1499
- orderType = ORDER_TYPES.SELL;
1500
- else
1501
- orderType = resolveSpreadOrderSide(matchedGridOrder.price, mgr.config.startPrice);
1502
- }
1504
+ // The fill's paid asset is the ground truth for the order side. The
1505
+ // slot type is only a grid identity and can be retyped (BUY<->SELL)
1506
+ // before the resting chain order is corrected; trusting it classified
1507
+ // a real SELL fill as a BUY (filledAmount=0 because the paid asset did
1508
+ // not match the slot's expected quote side) and the phantom fill was
1509
+ // re-bought at the fill level. Resolving the side from `paysAssetId`
1510
+ // also selects the correct size asset (BUY sizes are quote, SELL
1511
+ // sizes are base), so `filledAmount`/`precision` stay dimensionally
1512
+ // consistent with the resting order's size.
1513
+ // One resolver for "which side did this trade" (order/fill_ledger.ts):
1514
+ // the paid asset is chain truth, the slot type is only the fallback.
1515
+ // A SPREAD slot carries no rail side, so it is resolved from the
1516
+ // price-vs-startPrice convention without leaking SPREAD into the
1517
+ // transition (validateOrder treats an on-chain SPREAD state as fatal
1518
+ // ILLEGAL_SPREAD_STATE).
1519
+ const fallbackSide = matchedGridOrder.type === ORDER_TYPES.SPREAD
1520
+ ? resolveSpreadOrderSide(matchedGridOrder.price, mgr.config.startPrice)
1521
+ : matchedGridOrder.type;
1522
+ const orderType = (resolveTradedSide(paysAssetId, assets, fallbackSide) ?? matchedGridOrder.type);
1503
1523
  const currentSize = toFiniteNumber(matchedGridOrder.size);
1504
1524
  const precision = (orderType === ORDER_TYPES.SELL) ? assets.assetA.precision : assets.assetB.precision;
1505
1525
  let filledAmount = 0;
1506
1526
  if (orderType === ORDER_TYPES.SELL) {
1507
- if (paysAssetId === assets.assetA.id)
1527
+ if (paysAssetId != null && paysAssetId === assets.assetA.id)
1508
1528
  filledAmount = blockchainToFloat(paysAmountRaw, precision);
1509
1529
  }
1510
1530
  else {
1511
- if (paysAssetId === assets.assetB.id)
1531
+ if (paysAssetId != null && paysAssetId === assets.assetB.id)
1512
1532
  filledAmount = blockchainToFloat(paysAmountRaw, precision);
1513
1533
  }
1514
1534
  const currentSizeIntFromGrid = floatToBlockchainInt(currentSize, precision);
@@ -1537,7 +1557,21 @@ class SyncEngine {
1537
1557
  const currentSizeInt = Number.isFinite(effectiveRawForSale)
1538
1558
  ? Math.max(0, Math.round(effectiveRawForSale))
1539
1559
  : currentSizeIntFromGrid;
1540
- const newSizeInt = Math.max(0, currentSizeInt - filledAmountInt);
1560
+ // `rawOnChain.for_sale` may already include the part of this fill that
1561
+ // sync pass 1 absorbed. Subtract only the NOT-yet-applied remainder;
1562
+ // subtracting the whole fill (or none of it) is the double-shrink /
1563
+ // growth pair from the 2026-11-03 incident.
1564
+ //
1565
+ // ONE channel: the applied AMOUNT. The pre-P2 `alreadyAppliedChainSize`
1566
+ // boolean is gone — it carried the same fact without a number, so it
1567
+ // could disagree with the amount, and the aggregated path read it off
1568
+ // the LAST group entry only (a group with one marked entry collapsed the
1569
+ // unapplied remainder of its siblings to 0). `processFillAccounting`
1570
+ // writes `__chainSizeAppliedInt` on every marker it consumes, so the
1571
+ // amount is total.
1572
+ const appliedInt = Math.max(0, Math.min(filledAmountInt, Math.round(Number(params.alreadyAppliedInt)) || 0));
1573
+ const remainingFillInt = Math.max(0, filledAmountInt - appliedInt);
1574
+ const newSizeInt = Math.max(0, currentSizeInt - remainingFillInt);
1541
1575
  const newSize = blockchainToFloat(newSizeInt, precision);
1542
1576
  if (Number.isFinite(effectiveRawForSale) && currentSizeInt !== currentSizeIntFromGrid) {
1543
1577
  mgr.logger.log(`[SYNC] Using rawOnChain.for_sale baseline for ${matchedGridOrder.orderId}: raw=${currentSizeInt}, grid=${currentSizeIntFromGrid}` +
@@ -1614,6 +1648,18 @@ class SyncEngine {
1614
1648
  }
1615
1649
  }
1616
1650
  }
1651
+ // ZERO-REMAINDER BRAKE: a fill that leaves nothing tradeable must never
1652
+ // produce a 0-size PARTIAL slot (invalid order state), even when the
1653
+ // quote-side rounding test above could not decide (a corrupt/zero slot
1654
+ // price makes `otherSize` non-finite, so `<= 0` is false). Deliberately
1655
+ // placed AFTER the residual verification: taking this brake earlier
1656
+ // skipped the explicit cancel of a real chain residual — the exact
1657
+ // stranding path `cancelResidualOrders` exists for.
1658
+ if (!isEffectivelyFull && newSizeInt <= 0) {
1659
+ isEffectivelyFull = true;
1660
+ mgr.logger.log(`[SYNC] Order ${matchedGridOrder.orderId} (slot ${matchedGridOrder.id}) leaves no tradeable remainder ` +
1661
+ `(filled=${filledAmountInt} baseline=${currentSizeInt} applied=${appliedInt}); treating as a full fill.`, 'debug');
1662
+ }
1617
1663
  let fullUpdate;
1618
1664
  let partialUpdate;
1619
1665
  let filledOrderResult;
@@ -1640,12 +1686,18 @@ class SyncEngine {
1640
1686
  isMaker
1641
1687
  };
1642
1688
  const { btsFeeState, ...matchedWithoutDeferredFee } = matchedGridOrder;
1689
+ // Store the TRADED side, not the slot's old label: `size` below is
1690
+ // in that side's units, and accounting/recalculateFunds resolve
1691
+ // dimensions from order.type. This does NOT launder a queued
1692
+ // typeMismatch cancel — its drain-time validator compares the
1693
+ // level's rail geometry, not just slot.type (see
1694
+ // _validatePriceCorrectionEntry).
1643
1695
  let updatedOrder = { ...matchedWithoutDeferredFee, type: orderType, state: ORDER_STATES.PARTIAL };
1644
1696
  if (updatedOrder.rawOnChain && updatedOrder.rawOnChain.for_sale !== undefined) {
1645
- const baselineForSale = (chainRefetched && Number.isFinite(effectiveRawForSale))
1646
- ? effectiveRawForSale
1647
- : toFiniteNumber(updatedOrder.rawOnChain.for_sale);
1648
- const nextForSaleInt = Math.max(0, Math.round(baselineForSale) - filledAmountInt);
1697
+ // The snapshot's for_sale is the authoritative remaining size
1698
+ // after the not-yet-applied portion was subtracted above; it is
1699
+ // never decremented a second time.
1700
+ const nextForSaleInt = newSizeInt;
1649
1701
  updatedOrder.rawOnChain = {
1650
1702
  ...updatedOrder.rawOnChain,
1651
1703
  for_sale: String(nextForSaleInt),
@@ -1784,7 +1836,8 @@ class SyncEngine {
1784
1836
  blockNum,
1785
1837
  historyId,
1786
1838
  isMaker,
1787
- fillPrice: ctx.fillPrice
1839
+ fillPrice: ctx.fillPrice,
1840
+ alreadyAppliedInt: Math.max(0, Math.round(Number(fillOp.__chainSizeAppliedInt) || 0)),
1788
1841
  });
1789
1842
  const filledOrders = [];
1790
1843
  const updatedOrders = [];
@@ -2044,8 +2097,10 @@ class SyncEngine {
2044
2097
  // Sum the integer filled amounts across this order's fills so
2045
2098
  // the single transition reflects the total consumption.
2046
2099
  let totalFilledAmountInt = 0;
2100
+ let totalAppliedInt = 0;
2047
2101
  for (const ctx of group) {
2048
2102
  totalFilledAmountInt += ctx.filledAmountInt;
2103
+ totalAppliedInt += Math.max(0, Math.round(Number(ctx.entry.fillOp.__chainSizeAppliedInt) || 0));
2049
2104
  }
2050
2105
  const totalFilledAmount = blockchainToFloat(totalFilledAmountInt, precision);
2051
2106
  if (group.length > 1) {
@@ -2069,7 +2124,8 @@ class SyncEngine {
2069
2124
  blockNum: lastCtx.entry.blockNum,
2070
2125
  historyId: lastCtx.entry.historyId,
2071
2126
  isMaker: lastCtx.entry.isMaker,
2072
- fillPrice: lastCtx.fillPrice
2127
+ fillPrice: lastCtx.fillPrice,
2128
+ alreadyAppliedInt: Math.min(totalFilledAmountInt, Math.max(0, totalAppliedInt)),
2073
2129
  });
2074
2130
  if (result.isFull) {
2075
2131
  mgr.logger.log(`[SYNC] Full fill for order ${orderId} (slot ${matchedGridOrder.id}).`, 'info');
@@ -2129,55 +2185,6 @@ class SyncEngine {
2129
2185
  mgr._fillBatchInFlight--;
2130
2186
  }
2131
2187
  }
2132
- /**
2133
- * High-level dispatcher for different blockchain synchronization sources.
2134
- * Routes to the appropriate sync strategy based on the data source.
2135
- *
2136
- * SOURCES AND STRATEGIES:
2137
- * ========================================================================
2138
- * source: 'createOrder'
2139
- * Purpose: Grid order was successfully placed on-chain
2140
- * Data: { gridOrderId, chainOrderId, isPartialPlacement, fee }
2141
- * Action:
2142
- * 1. Look up grid order by gridOrderId
2143
- * 2. Assign the returned chainOrderId (so we can find it later)
2144
- * 3. Transition state based on isPartialPlacement:
2145
- * - false → ACTIVE (full order placed)
2146
- * - true → PARTIAL (placed as partial, likely due to insufficient funds)
2147
- * 4. Update optimistic chainFree balance (deduct fees if BTS pair)
2148
- * Fund Impact: Funds transition from free → locked/committed
2149
- *
2150
- * source: 'cancelOrder'
2151
- * Purpose: Grid order was successfully cancelled on-chain
2152
- * Data: The chainOrderId to cancel
2153
- * Action:
2154
- * 1. Find grid order by orderId (reverse lookup)
2155
- * 2. Transition to VIRTUAL (order no longer on-chain)
2156
- * 3. Clear orderId so it can be re-used
2157
- * 4. Update optimistic chainFree balance (add funds back as free)
2158
- * Fund Impact: Funds transition from locked → free
2159
- * Note: This is used for direct cancellations (not rotation/consolidation)
2160
- *
2161
- * source: 'readOpenOrders' or 'periodicBlockchainFetch'
2162
- * Purpose: Full snapshot sync of all open orders from blockchain
2163
- * Data: Array of chain orders from blockchain API
2164
- * Action: Delegates to syncFromOpenOrders() for full reconciliation
2165
- * Use Case: Periodic health check or startup initialization
2166
- *
2167
- * FUND TRACKING:
2168
- * Both 'createOrder' and 'cancelOrder' call updateOptimisticFreeBalance() to
2169
- * keep the optimistic chainFree balance in sync with actual on-chain state.
2170
- * This prevents fund leaks where placed orders weren't deducted or cancelled
2171
- * orders weren't released.
2172
- *
2173
- * RETURNS: { newOrders, ordersNeedingCorrection }
2174
- * Most callers use ordersNeedingCorrection to flag price corrections needed.
2175
- * Only syncFromOpenOrders() populates ordersNeedingCorrection.
2176
- *
2177
- * @param {Object} chainData - Chain event data
2178
- * @param {string} source - Source identifier ('createOrder', 'cancelOrder', 'readOpenOrders', etc.)
2179
- * @returns {Promise<Object>} { newOrders, ordersNeedingCorrection }
2180
- */
2181
2188
  /**
2182
2189
  * E2 invariant assert: a manager holding grid slots but no price ladder is
2183
2190
  * in the undefined state the grid-price invariant forbids (INV-GRID-004).
@@ -2228,6 +2235,55 @@ class SyncEngine {
2228
2235
  return false;
2229
2236
  }
2230
2237
  }
2238
+ /**
2239
+ * High-level dispatcher for the different blockchain synchronization
2240
+ * sources. Routes each source to its strategy and returns a uniform result
2241
+ * shape.
2242
+ *
2243
+ * SOURCES AND STRATEGIES:
2244
+ * ========================================================================
2245
+ * source: 'createOrder'
2246
+ * Purpose: Grid order was successfully placed on-chain
2247
+ * Data: { gridOrderId, chainOrderId, isPartialPlacement, expectedType, fee, order? }
2248
+ * Action:
2249
+ * 1. Look up grid order by gridOrderId
2250
+ * 2. Assign the returned chainOrderId (so we can find it later)
2251
+ * 3. Transition state based on isPartialPlacement:
2252
+ * - false → ACTIVE (full order placed)
2253
+ * - true → PARTIAL (placed as partial, likely due to insufficient funds)
2254
+ * 4. Apply the transition through _applyOrderUpdate (skipAccounting:
2255
+ * false), which owns the optimistic chainFree update and the BTS fee
2256
+ * Fund Impact: Funds transition from free → locked/committed
2257
+ *
2258
+ * source: 'cancelOrder'
2259
+ * Purpose: Grid order was successfully cancelled on-chain
2260
+ * Data: The chainOrderId to cancel
2261
+ * Action:
2262
+ * 1. Find grid order by orderId (reverse lookup)
2263
+ * 2. Transition to VIRTUAL (order no longer on-chain)
2264
+ * 3. Clear orderId so it can be re-used
2265
+ * 4. Apply the transition through _applyOrderUpdate
2266
+ * Fund Impact: Funds transition from locked → free
2267
+ * Note: This is used for direct cancellations (not rotation/consolidation).
2268
+ * A cancel whose slot vanished still deducts its fee from the totals
2269
+ * via adjustTotalBalance, so the books cannot drift.
2270
+ *
2271
+ * source: 'readOpenOrders' or 'periodicBlockchainFetch'
2272
+ * Purpose: Full snapshot sync of all open orders from blockchain
2273
+ * Data: Array of chain orders from blockchain API
2274
+ * Action: Delegates to syncFromOpenOrders() for full reconciliation
2275
+ * Use Case: Periodic health check or startup initialization
2276
+ *
2277
+ * FUND TRACKING:
2278
+ * The two event sources move funds through _applyOrderUpdate (and, for an
2279
+ * unmatched cancel, adjustTotalBalance), so the optimistic chainFree balance
2280
+ * cannot be bypassed by an event path. This prevents fund leaks where placed
2281
+ * orders weren't deducted or cancelled orders weren't released.
2282
+ *
2283
+ * @param {Object} chainData - Chain event data
2284
+ * @param {string} source - Source identifier ('createOrder', 'cancelOrder', 'readOpenOrders', 'periodicBlockchainFetch')
2285
+ * @returns {Promise<Object>} { newOrders, filledOrders, updatedOrders, ordersNeedingCorrection }
2286
+ */
2231
2287
  async synchronizeWithChain(chainData, source) {
2232
2288
  const mgr = this.manager;
2233
2289
  if (!mgr.assets)