dexbot 1.6.15 → 1.6.17

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 (130) hide show
  1. package/CHANGELOG.md +52 -0
  2. package/README.md +4 -4
  3. package/analysis/tradingview/README.md +2 -2
  4. package/analysis/trend_detection/DYNAMIC_WEIGHT_RESEARCH.md +1 -1
  5. package/claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md +3 -2
  6. package/claw/modules/chain_queries.ts +3 -3
  7. package/claw/package.json +1 -1
  8. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  9. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  10. package/dist/analysis/ama_fitting/analyze_lambda_vs_slow.js +5 -3
  11. package/dist/analysis/ama_fitting/fetch_lp_candles.js +8 -1
  12. package/dist/analysis/ama_fitting/optimizer_high_resolution.d.ts +50 -1
  13. package/dist/analysis/ama_fitting/optimizer_high_resolution.js +33 -7
  14. package/dist/analysis/bot_fitting/backtest_bot_fitting.d.ts +8 -6
  15. package/dist/analysis/bot_fitting/backtest_bot_fitting.js +8 -10
  16. package/dist/analysis/bot_key_utils.js +9 -7
  17. package/dist/analysis/chart_utils.d.ts +9 -2
  18. package/dist/analysis/chart_utils.js +51 -1
  19. package/dist/analysis/tradingview/grid_reset_sim.js +1 -1
  20. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.d.ts +2 -1
  21. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +23 -9
  22. package/dist/analysis/trend_detection/backtest_ama_slope_huber.js +1 -1
  23. package/dist/analysis/trend_detection/dynamic_weight_chart_generator.js +21 -2
  24. package/dist/analysis/trend_detection/kalman_chart_generator.js +1 -0
  25. package/dist/analysis/trend_detection/regime_chart_generator.js +1 -1
  26. package/dist/analysis/trend_detection/volatility_chart_generator.js +1 -0
  27. package/dist/dexbot.js +89 -138
  28. package/dist/market_adapter/inputs/fetch_book_data.js +36 -12
  29. package/dist/market_adapter/inputs/fetch_lp_data.d.ts +6 -0
  30. package/dist/market_adapter/inputs/fetch_lp_data.js +65 -19
  31. package/dist/market_adapter/inputs/kibana_feed_source.js +45 -12
  32. package/dist/market_adapter/inputs/window_cache.d.ts +14 -1
  33. package/dist/market_adapter/inputs/window_cache.js +53 -17
  34. package/dist/market_adapter/lp_chart_core.js +1 -0
  35. package/dist/market_adapter/utils/chain.js +4 -3
  36. package/dist/market_adapter/utils/pair_orientation.d.ts +60 -0
  37. package/dist/market_adapter/utils/pair_orientation.js +142 -0
  38. package/dist/modules/account_bots.d.ts +40 -3
  39. package/dist/modules/account_bots.js +77 -37
  40. package/dist/modules/account_orders.d.ts +4 -1
  41. package/dist/modules/account_orders.js +4 -1
  42. package/dist/modules/bitshares-native/resolvers.js +3 -3
  43. package/dist/modules/bitshares_client.d.ts +12 -10
  44. package/dist/modules/bitshares_client.js +12 -10
  45. package/dist/modules/bot_settings.js +3 -3
  46. package/dist/modules/chain_keys.d.ts +6 -2
  47. package/dist/modules/chain_keys.js +5 -1
  48. package/dist/modules/chain_orders.d.ts +6 -2
  49. package/dist/modules/chain_orders.js +6 -2
  50. package/dist/modules/constants.d.ts +11 -0
  51. package/dist/modules/constants.js +41 -7
  52. package/dist/modules/credit_pricing.d.ts +20 -1
  53. package/dist/modules/credit_pricing.js +23 -1
  54. package/dist/modules/credit_runtime.js +33 -16
  55. package/dist/modules/dexbot_class.d.ts +6 -2
  56. package/dist/modules/dexbot_class.js +8 -3
  57. package/dist/modules/dexbot_cow_runtime.d.ts +28 -37
  58. package/dist/modules/dexbot_cow_runtime.js +47 -66
  59. package/dist/modules/dexbot_maintenance_runtime.js +68 -10
  60. package/dist/modules/graceful_shutdown.d.ts +6 -2
  61. package/dist/modules/graceful_shutdown.js +6 -2
  62. package/dist/modules/launcher/bot_supervisor.js +4 -0
  63. package/dist/modules/launcher/credential_daemon.d.ts +14 -2
  64. package/dist/modules/launcher/credential_daemon.js +60 -26
  65. package/dist/modules/launcher/launch_modes.js +6 -3
  66. package/dist/modules/launcher/monolithic_runtime.d.ts +39 -1
  67. package/dist/modules/launcher/monolithic_runtime.js +60 -1
  68. package/dist/modules/launcher/runtime_mode.d.ts +79 -0
  69. package/dist/modules/launcher/runtime_mode.js +223 -0
  70. package/dist/modules/market_adapter_whitelist.d.ts +8 -0
  71. package/dist/modules/market_adapter_whitelist.js +8 -0
  72. package/dist/modules/order/accounting.d.ts +15 -1
  73. package/dist/modules/order/accounting.js +15 -1
  74. package/dist/modules/order/async_lock.d.ts +9 -3
  75. package/dist/modules/order/async_lock.js +9 -3
  76. package/dist/modules/order/export.d.ts +0 -5
  77. package/dist/modules/order/export.js +0 -5
  78. package/dist/modules/order/format.d.ts +6 -4
  79. package/dist/modules/order/format.js +6 -4
  80. package/dist/modules/order/grid.d.ts +36 -18
  81. package/dist/modules/order/grid.js +186 -33
  82. package/dist/modules/order/index.d.ts +16 -1
  83. package/dist/modules/order/index.js +1 -1
  84. package/dist/modules/order/logger_state.d.ts +1 -1
  85. package/dist/modules/order/logger_state.js +1 -1
  86. package/dist/modules/order/manager.d.ts +30 -7
  87. package/dist/modules/order/manager.js +108 -12
  88. package/dist/modules/order/strategy.d.ts +5 -0
  89. package/dist/modules/order/strategy.js +23 -2
  90. package/dist/modules/order/sync_engine.d.ts +26 -11
  91. package/dist/modules/order/sync_engine.js +26 -11
  92. package/dist/modules/order/utils/math.d.ts +100 -22
  93. package/dist/modules/order/utils/math.js +106 -22
  94. package/dist/modules/order/utils/order.d.ts +77 -20
  95. package/dist/modules/order/utils/order.js +125 -27
  96. package/dist/modules/order/utils/system.d.ts +107 -11
  97. package/dist/modules/order/utils/system.js +176 -11
  98. package/dist/modules/order/utils/validate.d.ts +8 -3
  99. package/dist/modules/order/utils/validate.js +10 -3
  100. package/dist/modules/types.d.ts +35 -2
  101. package/dist/modules/utils/asset_symbols.d.ts +5 -5
  102. package/dist/modules/utils/asset_symbols.js +5 -5
  103. package/dist/modules/utils/errors.d.ts +2 -1
  104. package/dist/modules/utils/errors.js +2 -1
  105. package/dist/scripts/analyze-credit.js +64 -23
  106. package/dist/scripts/bts_distribution.d.ts +66 -0
  107. package/dist/scripts/bts_distribution.js +2102 -0
  108. package/dist/scripts/rich_list.d.ts +32 -0
  109. package/dist/scripts/rich_list.js +16 -8
  110. package/dist/scripts/token_distribution.d.ts +45 -0
  111. package/dist/scripts/token_distribution.js +1870 -0
  112. package/dist/unlock.js +91 -42
  113. package/docs/BITSHARES_ONBOARDING.md +7 -0
  114. package/docs/COW_INVARIANTS.md +7 -1
  115. package/docs/DEXBOT_COMPARISON.md +5 -5
  116. package/docs/EVOLUTION.md +10 -8
  117. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +5 -3
  118. package/docs/GRID_PRICE_INVARIANT.md +6 -0
  119. package/docs/GRID_RECALCULATION.md +18 -6
  120. package/docs/LIFECYCLE.md +8 -8
  121. package/docs/LOGGING.md +9 -0
  122. package/docs/MPA_CREDIT_USAGE.md +3 -2
  123. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +121 -4
  124. package/docs/README.md +1 -1
  125. package/docs/WORKFLOW.md +5 -5
  126. package/docs/architecture.md +98 -1
  127. package/market_adapter/README.md +10 -3
  128. package/package.json +5 -1
  129. package/scripts/README.md +85 -148
  130. package/tests/README.md +29 -0
@@ -12,7 +12,7 @@
12
12
  * - Detects and flags out-of-spread conditions
13
13
  *
14
14
  * ===============================================================================
15
- * TABLE OF CONTENTS - Grid Functions (23 exported functions)
15
+ * TABLE OF CONTENTS - Grid Functions (34 exports)
16
16
  * ===============================================================================
17
17
  *
18
18
  * CONFIGURATION & CALCULATION (2 functions)
@@ -37,36 +37,49 @@
37
37
  * GRID STATE CHECKING (2 functions)
38
38
  * 8. checkAndUpdateGridIfNeeded(manager) - Complete fund trigger: available-
39
39
  * funds ratio + over-allocation + on-chain committed-drift legs
40
- * 8b. checkCommittedSizeDrift(manager) - Async committed-drift-only accessor
40
+ * 9. checkCommittedSizeDrift(manager) - Async committed-drift-only accessor
41
41
  * (the drift core is folded into checkAndUpdateGridIfNeeded)
42
42
  *
43
43
  * BLOCKCHAIN SYNCHRONIZATION (2 functions - async)
44
- * 9. _recalculateGridOrderSizesFromBlockchain(manager, orderType, options) - Recalculate sizes from blockchain
45
- * 10. updateGridFromBlockchainSnapshot(manager, orderType, fromBlockchainTimer, overrideBoundaryIdx) - Update grid from blockchain
44
+ * 10. _recalculateGridOrderSizesFromBlockchain(manager, orderType, options) - Recalculate sizes from blockchain
45
+ * 11. updateGridFromBlockchainSnapshot(manager, orderType, fromBlockchainTimer, overrideBoundaryIdx) - Update grid from blockchain
46
46
  *
47
47
  * GRID COMPARISON (2 functions - async)
48
- * 11. compareGrids(calculatedGrid, persistedGrid, manager) - Compare two grids
48
+ * 12. compareGrids(calculatedGrid, persistedGrid, manager) - Compare two grids
49
49
  * Validates grid structure and reports divergence metrics
50
- * 12. monitorDivergence(manager, calculatedGrid, persistedGrid) - Unified divergence check
50
+ * 13. monitorDivergence(manager, calculatedGrid, persistedGrid) - Unified divergence check
51
51
  * Runs ratio-based + RMS-based checks and returns combined result
52
52
  *
53
53
  * SPREAD MANAGEMENT (2 functions)
54
- * 13. calculateCurrentSpread(manager) - Calculate current bid-ask spread
55
- * 14. checkSpreadCondition(manager, BitShares, updateOrdersOnChainBatch) - Check and flag spread condition
54
+ * 14. calculateCurrentSpread(manager) - Calculate current bid-ask spread
55
+ * 15. checkSpreadCondition(manager, BitShares, updateOrdersOnChainBatch) - Check and flag spread condition
56
56
  *
57
57
  * GRID HEALTH MONITORING (4 functions)
58
- * 15. checkGridHealth(manager, updateOrdersOnChainBatch) - Monitor grid health
59
- * 16. checkWindowDust(manager) - Dust check scoped to the active buy/sell window
60
- * 17. hasAnyDust(manager, partials, side) - Check for dust orders
61
- * 18. getDustOrders(manager, partials, side) - Get dust order IDs
58
+ * 16. checkGridHealth(manager, updateOrdersOnChainBatch) - Monitor grid health
59
+ * 17. checkWindowDust(manager) - Dust check scoped to the active buy/sell window
60
+ * 18. hasAnyDust(manager, partials, side) - Check for dust orders
61
+ * 19. getDustOrders(manager, partials, side) - Get dust order IDs
62
62
  *
63
63
  * SIDE SELECTION (1 function)
64
- * 19. determineOrderSideByFunds(manager, currentMarketPrice) - Determine priority side
64
+ * 20. determineOrderSideByFunds(manager, currentMarketPrice) - Determine priority side
65
+ *
66
+ * SPREAD CORRECTION PLANNING (11 exports)
67
+ * 21. SPREAD_CORRECTION_REFUSAL - Refusal-cause vocabulary constant
68
+ * 22. SpreadCorrectionRefusalCause - Refusal-cause union type
69
+ * 23. isTransientSpreadRefusal(cause) - Whether a refusal cause is retryable
70
+ * 24. classifySpreadRefusalCause(...) - Classify why a correction batch did not land
71
+ * 25. recordSpreadCorrectionRefusal(...) - Record a refusal on the manager
72
+ * 26. recordSpreadCorrectionRetry(...) - Count a bounded re-plan retry
73
+ * 27. getOccupiedCorrectionSlots(...) - Planned CREATE destinations already occupied
74
+ * 28. replanSpreadCorrectionFromFreshMaster(...) - Re-plan from the current master
75
+ * 29. OccupiedCorrectionResolution - Outcome of plan-time collision resolution
76
+ * 30. resolveOccupiedCorrection(...) - Resolve a correction whose destination was taken
77
+ * 31. prepareSpreadCorrectionOrders(...) - Prepare orders to correct a wide spread
65
78
  *
66
79
  * BLOAT STATUS (3 functions)
67
- * 20. isGridBloated(manager, orders) - Check whether the grid is bloated
68
- * 21. isGridBloatGraceActive(manager) - Check the bloat grace state
69
- * 22. clearGridBloatFlag(manager) - Clear the bloat state
80
+ * 32. isGridBloated(manager, orders) - Check whether the grid is bloated
81
+ * 33. isGridBloatGraceActive(manager) - Check the bloat grace state
82
+ * 34. clearGridBloatFlag(manager) - Clear the bloat state
70
83
  *
71
84
  * ===============================================================================
72
85
  *
@@ -102,6 +115,13 @@ interface SpreadCorrection {
102
115
  origin?: string;
103
116
  [key: string]: unknown;
104
117
  }
118
+ /**
119
+ * Merge two side stalls so the starvation fallback cannot mask a named cause.
120
+ * 'unfunded' stays top (a refresh may repair it); 'unmatched-orders' next (a
121
+ * sync repairs it); then the geometry bind; readiness causes; 'no-candidates'
122
+ * is the floor. Exported for tests.
123
+ */
124
+ export declare function mergeSpreadStalls(a: SpreadCorrectionStall | undefined, b: SpreadCorrectionStall | undefined): SpreadCorrectionStall;
105
125
  /**
106
126
  * Spread-correction refusal causes — the single vocabulary shared by
107
127
  * classifySpreadRefusalCause, the retry/transience decision and the
@@ -589,8 +609,6 @@ export declare function calculateCurrentSpread(manager: OrderManagerLike): numbe
589
609
  * - RACE CONDITION WINDOW: Between lock release and blockchain submission
590
610
  * - MITIGATION: Pre-flight fund verification before submission; comprehensive error handling
591
611
  *
592
- * See RACE_CONDITION_ANALYSIS.md for detailed vulnerability documentation.
593
- *
594
612
  * @param {import('./types').OrderManager} manager - Manager instance
595
613
  * @param {Object} BitShares - BitShares API client
596
614
  * @param {Function|null} [updateOrdersOnChainBatch=null] - Optional batch update function
@@ -12,7 +12,7 @@
12
12
  * - Detects and flags out-of-spread conditions
13
13
  *
14
14
  * ===============================================================================
15
- * TABLE OF CONTENTS - Grid Functions (23 exported functions)
15
+ * TABLE OF CONTENTS - Grid Functions (34 exports)
16
16
  * ===============================================================================
17
17
  *
18
18
  * CONFIGURATION & CALCULATION (2 functions)
@@ -37,36 +37,49 @@
37
37
  * GRID STATE CHECKING (2 functions)
38
38
  * 8. checkAndUpdateGridIfNeeded(manager) - Complete fund trigger: available-
39
39
  * funds ratio + over-allocation + on-chain committed-drift legs
40
- * 8b. checkCommittedSizeDrift(manager) - Async committed-drift-only accessor
40
+ * 9. checkCommittedSizeDrift(manager) - Async committed-drift-only accessor
41
41
  * (the drift core is folded into checkAndUpdateGridIfNeeded)
42
42
  *
43
43
  * BLOCKCHAIN SYNCHRONIZATION (2 functions - async)
44
- * 9. _recalculateGridOrderSizesFromBlockchain(manager, orderType, options) - Recalculate sizes from blockchain
45
- * 10. updateGridFromBlockchainSnapshot(manager, orderType, fromBlockchainTimer, overrideBoundaryIdx) - Update grid from blockchain
44
+ * 10. _recalculateGridOrderSizesFromBlockchain(manager, orderType, options) - Recalculate sizes from blockchain
45
+ * 11. updateGridFromBlockchainSnapshot(manager, orderType, fromBlockchainTimer, overrideBoundaryIdx) - Update grid from blockchain
46
46
  *
47
47
  * GRID COMPARISON (2 functions - async)
48
- * 11. compareGrids(calculatedGrid, persistedGrid, manager) - Compare two grids
48
+ * 12. compareGrids(calculatedGrid, persistedGrid, manager) - Compare two grids
49
49
  * Validates grid structure and reports divergence metrics
50
- * 12. monitorDivergence(manager, calculatedGrid, persistedGrid) - Unified divergence check
50
+ * 13. monitorDivergence(manager, calculatedGrid, persistedGrid) - Unified divergence check
51
51
  * Runs ratio-based + RMS-based checks and returns combined result
52
52
  *
53
53
  * SPREAD MANAGEMENT (2 functions)
54
- * 13. calculateCurrentSpread(manager) - Calculate current bid-ask spread
55
- * 14. checkSpreadCondition(manager, BitShares, updateOrdersOnChainBatch) - Check and flag spread condition
54
+ * 14. calculateCurrentSpread(manager) - Calculate current bid-ask spread
55
+ * 15. checkSpreadCondition(manager, BitShares, updateOrdersOnChainBatch) - Check and flag spread condition
56
56
  *
57
57
  * GRID HEALTH MONITORING (4 functions)
58
- * 15. checkGridHealth(manager, updateOrdersOnChainBatch) - Monitor grid health
59
- * 16. checkWindowDust(manager) - Dust check scoped to the active buy/sell window
60
- * 17. hasAnyDust(manager, partials, side) - Check for dust orders
61
- * 18. getDustOrders(manager, partials, side) - Get dust order IDs
58
+ * 16. checkGridHealth(manager, updateOrdersOnChainBatch) - Monitor grid health
59
+ * 17. checkWindowDust(manager) - Dust check scoped to the active buy/sell window
60
+ * 18. hasAnyDust(manager, partials, side) - Check for dust orders
61
+ * 19. getDustOrders(manager, partials, side) - Get dust order IDs
62
62
  *
63
63
  * SIDE SELECTION (1 function)
64
- * 19. determineOrderSideByFunds(manager, currentMarketPrice) - Determine priority side
64
+ * 20. determineOrderSideByFunds(manager, currentMarketPrice) - Determine priority side
65
+ *
66
+ * SPREAD CORRECTION PLANNING (11 exports)
67
+ * 21. SPREAD_CORRECTION_REFUSAL - Refusal-cause vocabulary constant
68
+ * 22. SpreadCorrectionRefusalCause - Refusal-cause union type
69
+ * 23. isTransientSpreadRefusal(cause) - Whether a refusal cause is retryable
70
+ * 24. classifySpreadRefusalCause(...) - Classify why a correction batch did not land
71
+ * 25. recordSpreadCorrectionRefusal(...) - Record a refusal on the manager
72
+ * 26. recordSpreadCorrectionRetry(...) - Count a bounded re-plan retry
73
+ * 27. getOccupiedCorrectionSlots(...) - Planned CREATE destinations already occupied
74
+ * 28. replanSpreadCorrectionFromFreshMaster(...) - Re-plan from the current master
75
+ * 29. OccupiedCorrectionResolution - Outcome of plan-time collision resolution
76
+ * 30. resolveOccupiedCorrection(...) - Resolve a correction whose destination was taken
77
+ * 31. prepareSpreadCorrectionOrders(...) - Prepare orders to correct a wide spread
65
78
  *
66
79
  * BLOAT STATUS (3 functions)
67
- * 20. isGridBloated(manager, orders) - Check whether the grid is bloated
68
- * 21. isGridBloatGraceActive(manager) - Check the bloat grace state
69
- * 22. clearGridBloatFlag(manager) - Clear the bloat state
80
+ * 32. isGridBloated(manager, orders) - Check whether the grid is bloated
81
+ * 33. isGridBloatGraceActive(manager) - Check the bloat grace state
82
+ * 34. clearGridBloatFlag(manager) - Clear the bloat state
70
83
  *
71
84
  * ===============================================================================
72
85
  *
@@ -115,12 +128,36 @@ function classifySpreadStall(c) {
115
128
  // the precedence is explicit so a future hint can never mask 'unfunded').
116
129
  if (Number(c?.plannedCount || 0) > 0 || hint === 'unfunded')
117
130
  return 'unfunded';
118
- // Preserve the readiness-gate causes verbatim; they are operationally
119
- // distinct and the targeted-sync reason states them literally.
120
- if (hint === 'cold-book' || hint === 'unmatched-orders' || hint === 'readiness-gate')
131
+ // Preserve the named causes verbatim; they are operationally distinct (one
132
+ // wants a sync, one wants a re-center) and the watchdog keys its escalation
133
+ // window off them.
134
+ if (hint === 'cold-book' || hint === 'unmatched-orders' || hint === 'readiness-gate'
135
+ || hint === 'last-fill-blocked')
121
136
  return hint;
122
137
  return 'no-candidates';
123
138
  }
139
+ /**
140
+ * Merge two side stalls so the starvation fallback cannot mask a named cause.
141
+ * 'unfunded' stays top (a refresh may repair it); 'unmatched-orders' next (a
142
+ * sync repairs it); then the geometry bind; readiness causes; 'no-candidates'
143
+ * is the floor. Exported for tests.
144
+ */
145
+ export function mergeSpreadStalls(a, b) {
146
+ const rank = {
147
+ 'unfunded': 5,
148
+ 'no-free-funds': 5,
149
+ 'unmatched-orders': 4,
150
+ 'last-fill-blocked': 3,
151
+ 'cold-book': 2,
152
+ 'readiness-gate': 2,
153
+ 'no-candidates': 1,
154
+ 'batch-not-executed': 1,
155
+ 'apply-error': 1
156
+ };
157
+ const ra = rank[String(a)] ?? 0;
158
+ const rb = rank[String(b)] ?? 0;
159
+ return (rb > ra ? String(b) : String(a));
160
+ }
124
161
  /**
125
162
  * Spread-correction refusal causes — the single vocabulary shared by
126
163
  * classifySpreadRefusalCause, the retry/transience decision and the
@@ -330,7 +367,7 @@ function _snapshotFundState(manager) {
330
367
  }
331
368
  import { floatToBlockchainInt, getPrecisionByOrderType, getPrecisionsForManager, calculateOrderCreationFees, calculateOrderSizes, calculateRotationOrderSizes, calculateAvailableFundsValue, calculateGridSideDivergenceMetric, getPrecisionSlack, getMinOrderSize, getSingleDustThreshold, getGridBestPrices, calculateSpreadFromOrders, allocateFundsByWeights, calculateGapSlots as _mathGapSlots, pricesOnSameLevel, sameGridLevel, getBtsSide, getSellStartIdx, resolveGapBand, countGapBandSpread, validatePersistedBoundary, isTransientInBandRejection, adjustBudgetForBtsFees, clamp, derivePriceLevels, buildGenesisFromPriceLevels, assertSlotPriceInvariant, priceForSlot, hashPriceLevels, } from './utils/math.js';
332
369
  import { filterOrdersByType, checkSizesBeforeMinimum, checkSizeThreshold, resolveConfiguredPriceBound, shouldFlagOutOfSpread, isOrderHealthy, isPhantomOrder, isSlotAvailable, isOrderOnChain, isOrderPlaced, hasOnChainId, isEmptyGridSlot, parseSlotIndex, calculateIdealBoundary, assignGridRoles, resolveOnChainRetypeType, resolveEdgeCount, edgeOrderIdSet, resolveLiveEdgeAnchorPrice, liveWindowIdSet, getOrderTypeFromUpdatedFlags } from './utils/order.js';
333
- import { loadAmaCenterPrice, loadAmaCenterSnapshot, withBlockchainRetry, restoreLastFillPivot, resetLastFillPivot, evaluateSpreadCorrectionReadiness, maybeRefreshLiveMarketPrice } from './utils/system.js';
370
+ import { loadAmaCenterPrice, loadAmaCenterSnapshot, withBlockchainRetry, restoreLastFillPivot, resetLastFillPivot, evaluateSpreadCorrectionReadiness, maybeRefreshLiveMarketPrice, resolveLastFillGuardReference, isLastFillGuardBlocked } from './utils/system.js';
334
371
  import * as MathUtils from './utils/math.js';
335
372
  import { derivePriceWithPoolRef, resolveStartPriceMode } from './utils/withPoolRef.js';
336
373
  import { getWhitelistFlags } from '../market_adapter_whitelist.js';
@@ -2378,8 +2415,6 @@ export function calculateCurrentSpread(manager) {
2378
2415
  * - RACE CONDITION WINDOW: Between lock release and blockchain submission
2379
2416
  * - MITIGATION: Pre-flight fund verification before submission; comprehensive error handling
2380
2417
  *
2381
- * See RACE_CONDITION_ANALYSIS.md for detailed vulnerability documentation.
2382
- *
2383
2418
  * @param {import('./types').OrderManager} manager - Manager instance
2384
2419
  * @param {Object} BitShares - BitShares API client
2385
2420
  * @param {Function|null} [updateOrdersOnChainBatch=null] - Optional batch update function
@@ -2551,9 +2586,10 @@ export async function checkSpreadCondition(manager, _BitShares, updateOrdersOnCh
2551
2586
  correction = oppositeCorrection;
2552
2587
  placeCount = oppositeCorrection.ordersToPlace?.length || 0;
2553
2588
  const oppositeStall = classifySpreadStall(oppositeCorrection);
2554
- sideStall = (sideStall === 'unfunded' || oppositeStall === 'unfunded')
2555
- ? 'unfunded'
2556
- : 'no-candidates';
2589
+ // Precedence merge (never overwrite): 'unfunded' > sync-repairable
2590
+ // > geometry bind > readiness > 'no-candidates'. The old collapse
2591
+ // to 'unfunded'/'no-candidates' dropped every named cause.
2592
+ sideStall = mergeSpreadStalls(sideStall, oppositeStall);
2557
2593
  }
2558
2594
  }
2559
2595
  // Capture fund snapshot under lock for pre-flight verification before broadcast
@@ -3095,6 +3131,41 @@ export async function prepareSpreadCorrectionOrders(manager, preferredSide, outO
3095
3131
  : 'no-candidates';
3096
3132
  const railType = preferredSide;
3097
3133
  const sideName = railType === ORDER_TYPES.BUY ? 'buy' : 'sell';
3134
+ // LAST-FILL FILTER (planner-side, same predicate as the broadcast guard).
3135
+ //
3136
+ // The guard drops any create at/through the last fill price, so a plan
3137
+ // built from such candidates can only end as "batch prepared but not
3138
+ // executed" (observed live: the only funded candidate was a SELL below
3139
+ // the 0.447640 fill, both attempts were dropped, and the correction
3140
+ // burned its cycle on a refusal). Filter here instead: the quota is then
3141
+ // filled from candidates the guard can accept, and an empty pool is an
3142
+ // honest "nothing to place" rather than a vetoed batch.
3143
+ //
3144
+ // Uses resolveLastFillGuardReference (the SAME effective pivot the guard
3145
+ // probes, including the persisted fallback that survives a rebuild) so
3146
+ // planner and guard cannot drift apart.
3147
+ const lastFillRef = resolveLastFillGuardReference(manager);
3148
+ const lastFillPivot = lastFillRef.price != null && Number.isFinite(Number(lastFillRef.price))
3149
+ ? Number(lastFillRef.price)
3150
+ : null;
3151
+ const lastFillSide = lastFillRef.type;
3152
+ const lastFillBlocks = (c) => {
3153
+ if (lastFillPivot == null || lastFillSide == null)
3154
+ return false;
3155
+ if (c?.price == null || !Number.isFinite(Number(c.price)))
3156
+ return false;
3157
+ return isLastFillGuardBlocked(Number(c.price), Number(c.size) || 0, railType, lastFillPivot, lastFillSide, manager.config?.incrementPercent).blocked === true;
3158
+ };
3159
+ let lastFillExcluded = 0;
3160
+ const passesLastFill = (c) => {
3161
+ if (!lastFillBlocks(c))
3162
+ return true;
3163
+ lastFillExcluded++;
3164
+ return false;
3165
+ };
3166
+ const lastFillRuleText = lastFillPivot == null
3167
+ ? ''
3168
+ : `${railType === ORDER_TYPES.BUY ? 'BUY must be below' : 'SELL must be above'} the last fill ${Format.formatPrice6(lastFillPivot)}`;
3098
3169
  const configuredMissingSlots = Number(outOfSpread || 0);
3099
3170
  const missingSlots = configuredMissingSlots > 0
3100
3171
  ? Math.floor(configuredMissingSlots)
@@ -3281,6 +3352,7 @@ export async function prepareSpreadCorrectionOrders(manager, preferredSide, outO
3281
3352
  .filter((o) => o.type === ORDER_TYPES.SPREAD
3282
3353
  && isSlotAvailable(o)
3283
3354
  && getSlotCorrectType(o) === railType)
3355
+ .filter(passesLastFill)
3284
3356
  .filter(tightensSpread)
3285
3357
  .filter(doesNotCrossMarket)
3286
3358
  .filter(doesNotCollideUnmatched)
@@ -3325,6 +3397,7 @@ export async function prepareSpreadCorrectionOrders(manager, preferredSide, outO
3325
3397
  && o.state === ORDER_STATES.VIRTUAL
3326
3398
  && !o.orderId
3327
3399
  && getSlotCorrectType(o) === railType)
3400
+ .filter(passesLastFill)
3328
3401
  .filter(tightensSpread)
3329
3402
  .filter(doesNotCrossMarket)
3330
3403
  .filter(doesNotCollideUnmatched)
@@ -3421,10 +3494,14 @@ export async function prepareSpreadCorrectionOrders(manager, preferredSide, outO
3421
3494
  // consume the whole quota without ever entering the gap.
3422
3495
  const remainingQuota = Math.max(0, missingSlots - orphanedVirtualCandidates.length);
3423
3496
  let spreadCandidates = [
3424
- ...promotedCandidates,
3497
+ ...promotedCandidates.filter(passesLastFill),
3425
3498
  ...typedSpreadCandidates.slice(0, remainingQuota),
3426
3499
  ...orphanedVirtualCandidates
3427
3500
  ];
3501
+ if (lastFillExcluded > 0) {
3502
+ manager.logger?.log?.(`[SPREAD-CORRECTION] Excluded ${lastFillExcluded} candidate(s) from ${sideName} planning: ` +
3503
+ `${lastFillRuleText} (the broadcast guard would drop them)`, 'debug');
3504
+ }
3428
3505
  // Dedupe by slot id: an empty in-rail slot typed SPREAD (normalized) now
3429
3506
  // qualifies for BOTH orphanedVirtualCandidates and typedSpreadCandidates
3430
3507
  // (both accept SPREAD type + rail geometry), so a single slot can be
@@ -3472,10 +3549,57 @@ export async function prepareSpreadCorrectionOrders(manager, preferredSide, outO
3472
3549
  manager.logger?.log?.(`[SPREAD-CORRECTION] Identified ${spreadCandidates.length}/${missingSlots} slot(s) for activation on ${sideName} (orphaned=${orphanedVirtualCandidates.length}, spread=${spreadCandidates.length - orphanedVirtualCandidates.length})`, 'debug');
3473
3550
  }
3474
3551
  if (spreadCandidates.length === 0) {
3475
- manager.logger?.log?.(bestLiveOnRail == null
3476
- ? `[SPREAD-CORRECTION] No orphaned virtual slots or spread slots found. Skipping.`
3477
- : `[SPREAD-CORRECTION] No spread-tightening slot on ${sideName} (best live ${bestLiveOnRail}); every remaining empty slot sits beyond the live window and cannot narrow the spread. Skipping.`, 'warn');
3478
- return { ordersToPlace: [], ordersToUpdate: [], plannedCount: 0, stallHint: refusalStallHint, origin: COW_ORIGINS.SPREAD_CORRECTION };
3552
+ manager.logger?.log?.(lastFillExcluded > 0 && lastFillPivot != null
3553
+ ? `[SPREAD-CORRECTION] No placeable ${sideName} slot: every tightening slot is at/through the last fill ` +
3554
+ `${Format.formatPrice6(lastFillPivot)} (${lastFillRuleText}). The spread cannot be tightened on this ` +
3555
+ `side; a boundary move or a fill must restore headroom.`
3556
+ : bestLiveOnRail == null
3557
+ ? `[SPREAD-CORRECTION] No orphaned virtual slots or spread slots found. Skipping.`
3558
+ : `[SPREAD-CORRECTION] No spread-tightening slot on ${sideName} (best live ${bestLiveOnRail}); every remaining empty slot sits beyond the live window and cannot narrow the spread. Skipping.`, 'warn');
3559
+ // Name the geometry bind: the window itself is wrong (a sell slot
3560
+ // below the last sale means the boundary/crawl is behind the fill),
3561
+ // so placement cannot repair the side and a re-center can.
3562
+ const emptyStall = (lastFillExcluded > 0 && lastFillPivot != null)
3563
+ ? 'last-fill-blocked'
3564
+ : refusalStallHint;
3565
+ return { ordersToPlace: [], ordersToUpdate: [], plannedCount: 0, stallHint: emptyStall, origin: COW_ORIGINS.SPREAD_CORRECTION };
3566
+ }
3567
+ // RAIL-OVERSUBSCRIBED: availableFund is chainFree − virtualReservation, so
3568
+ // it reads 0 whenever the empty rail already reserves more than the free
3569
+ // balance (observed live: free 454560.80 vs virtual 456046.21, a 1485 base
3570
+ // short, "planned 3, placing 0" every cycle for 84 minutes). That is not
3571
+ // "wait for a fill": the rail must be re-sized from chain truth, which a
3572
+ // re-center does. Detect it BEFORE the sizing-context gate (a zero budget
3573
+ // is the very symptom) and flag it so the persistence watchdog escalates
3574
+ // on its short fund window instead of the 30-minute structural one.
3575
+ {
3576
+ const sideChainFree = Math.max(0, Number(sideName === 'buy'
3577
+ ? manager.accountTotals?.buyFree
3578
+ : manager.accountTotals?.sellFree) || 0);
3579
+ const sideVirtual = Math.max(0, Number(sideName === 'buy'
3580
+ ? manager.funds?.virtual?.buy
3581
+ : manager.funds?.virtual?.sell) || 0);
3582
+ const sideAvailable = Math.max(0, Math.min(Number(manager.funds?.available?.[sideName] || 0), sideChainFree));
3583
+ const epsilon = 1e-8;
3584
+ if (sideAvailable <= epsilon && (sideVirtual - sideChainFree) > epsilon) {
3585
+ try {
3586
+ manager._spreadRailOversubscribed = {
3587
+ side: sideName, virtual: sideVirtual, free: sideChainFree, at: Date.now()
3588
+ };
3589
+ }
3590
+ catch { /* best-effort */ }
3591
+ manager.logger?.log?.(`[SPREAD-CORRECTION] ${sideName} rail is OVERSUBSCRIBED: virtual reservation ` +
3592
+ `${Format.formatAmount8(sideVirtual)} exceeds chain free ${Format.formatAmount8(sideChainFree)} ` +
3593
+ `by ${Format.formatAmount8(sideVirtual - sideChainFree)} — the projection is stale, so the ` +
3594
+ `correction funds what the chain actually holds free; a rail re-size (structural re-center) ` +
3595
+ `is still the durable repair`, 'warn');
3596
+ }
3597
+ else if (sideAvailable > epsilon) {
3598
+ try {
3599
+ manager._spreadRailOversubscribed = null;
3600
+ }
3601
+ catch { /* best-effort */ }
3602
+ }
3479
3603
  }
3480
3604
  const orphanedIds = new Set(orphanedVirtualCandidates.map((o) => o.id));
3481
3605
  const sideSlots = allOrders
@@ -3533,15 +3657,44 @@ export async function prepareSpreadCorrectionOrders(manager, preferredSide, outO
3533
3657
  if (prioritizedTargets.length === 0) {
3534
3658
  return { ordersToPlace: [], ordersToUpdate: [], plannedCount: 0, stallHint: 'no-candidates', origin: COW_ORIGINS.SPREAD_CORRECTION };
3535
3659
  }
3536
- let remainingBudget = availableFund;
3660
+ // Chain-truth budget (see deriveChainTruthFundBudget): `availableFund`
3661
+ // already had the virtual reservation subtracted, and that reservation
3662
+ // is the projection of THESE candidates — subtracting it from the
3663
+ // budget that funds them is circular. When the projection exceeds what
3664
+ // the chain holds free it reads 0 forever, so the holes can never be
3665
+ // filled and the projection can never shrink (live: `planned 3,
3666
+ // placing 0` for 84 minutes). Re-derive from chain truth, capped by
3667
+ // what the candidates need and by the real free balance.
3668
+ const candidateIdeals = prioritizedTargets.reduce((sum, t) => sum + Math.max(0, Number(t.ideal) || 0), 0);
3669
+ const chainFreeForSide = Math.max(0, Number(sideName === 'buy'
3670
+ ? manager.accountTotals?.buyFree
3671
+ : manager.accountTotals?.sellFree) || 0);
3672
+ const virtualIntentForSide = Math.max(0, Number(sideName === 'buy'
3673
+ ? manager.funds?.virtual?.buy
3674
+ : manager.funds?.virtual?.sell) || 0);
3675
+ const fundBudget = MathUtils.deriveChainTruthFundBudget({
3676
+ availableFund,
3677
+ virtualIntent: virtualIntentForSide,
3678
+ chainFree: chainFreeForSide,
3679
+ candidateIdeals,
3680
+ });
3681
+ if (fundBudget.eroded) {
3682
+ manager.logger?.log?.(`[SPREAD-CORRECTION] ${sideName} projection exceeds chain free by ` +
3683
+ `${Format.formatAmount8(fundBudget.oversubscribed)}; funding the candidates from chain truth ` +
3684
+ `(${Format.formatAmount8(fundBudget.budget)} for ${Format.formatAmount8(candidateIdeals)} of ideal ` +
3685
+ `size) instead of placing nothing`, 'warn');
3686
+ }
3687
+ let remainingBudget = fundBudget.budget;
3537
3688
  // FUNDING PROBE (diagnostic): one line per correction cycle showing the
3538
3689
  // quantities that decide whether candidates can be funded. availableFund
3539
3690
  // is min(funds.available[side], accountTotals[side]Free); when the
3540
3691
  // virtual rail has already reserved the free balance this reads ~0 even
3541
- // though the side still holds inventory — the state that makes the loop
3542
- // below place fewer orders than the plan's candidates.
3692
+ // though the side still holds inventory. `spendable` is what the loop
3693
+ // actually spends (chain truth when the projection is oversubscribed),
3694
+ // so the two never have to be inferred from each other.
3543
3695
  manager.logger?.log?.(`[SPREAD-CORRECTION] Funding probe side=${sideName}: ` +
3544
3696
  `availableFund=${Format.formatAmount8(availableFund)} ` +
3697
+ `spendable=${Format.formatAmount8(fundBudget.budget)} ` +
3545
3698
  `budget=${Format.formatAmount8(Number(ctx.budget || 0))} ` +
3546
3699
  `virtual=${Format.formatAmount8(Number(sideName === 'buy' ? manager.funds?.virtual?.buy : manager.funds?.virtual?.sell) || 0)} ` +
3547
3700
  `free=${Format.formatAmount8(Number(sideName === 'buy' ? manager.accountTotals?.buyFree : manager.accountTotals?.sellFree) || 0)} ` +
@@ -33,7 +33,7 @@
33
33
  * 1. manager.ts - OrderManager class (order lifecycle, fund tracking)
34
34
  * 2. grid.ts - Grid class (grid creation, synchronization, health)
35
35
  * 3. utils/math.ts, utils/order.ts, utils/system.ts - Helper functions by concern
36
- * 4. format.ts - Numeric formatting (18 functions for consistent display)
36
+ * 4. format.ts - Numeric formatting (17 functions for consistent display)
37
37
  * 5. accounting.ts - Accountant class (fund calculations and reconciliation)
38
38
  * 6. logger.ts - Logger class (structured, color-coded output)
39
39
  * 7. async_lock.ts - AsyncLock class (race condition prevention)
@@ -86,10 +86,24 @@ declare const utils: {
86
86
  } | null;
87
87
  }): system.SpreadCorrectionReadiness;
88
88
  resolveSpreadMarketReference(manager: import("../types.js").OrderManagerLike): number | null;
89
+ reanchorBoundaryFromLastFill(manager: import("../types.js").OrderManagerLike, boundaryIdx: number | null | undefined, slots: import("../types.js").ManagedOrder[] | null | undefined, gapSlots: number): {
90
+ boundaryIdx: number | null;
91
+ reanchored: boolean;
92
+ from?: number | null;
93
+ to?: number;
94
+ side?: string;
95
+ fillSlot?: number;
96
+ reason?: string;
97
+ };
89
98
  resolveLastFillGuardReference(manager: import("../types.js").OrderManagerLike): {
90
99
  price: number | null;
91
100
  type: string | null;
92
101
  };
102
+ isLastFillGuardBlocked(price: number, _size: number, type: unknown, lastPrice: number | null, lastType: string | null, _incrementPercent?: number): {
103
+ blocked: boolean;
104
+ pivot: number | null;
105
+ threshold?: number | null;
106
+ };
93
107
  restoreLastMarketFill(manager: import("../types.js").OrderManagerLike, persisted: unknown, options?: {
94
108
  now?: number;
95
109
  }): boolean;
@@ -278,6 +292,7 @@ declare const utils: {
278
292
  getPrecision: typeof math.getPrecision;
279
293
  computeChainFundTotals: typeof math.computeChainFundTotals;
280
294
  calculateAvailableFundsValue: typeof math.calculateAvailableFundsValue;
295
+ deriveChainTruthFundBudget: typeof math.deriveChainTruthFundBudget;
281
296
  adjustBudgetForBtsFees: typeof math.adjustBudgetForBtsFees;
282
297
  getGridBestPrices: typeof math.getGridBestPrices;
283
298
  calculateSpreadFromOrders: typeof math.calculateSpreadFromOrders;
@@ -33,7 +33,7 @@
33
33
  * 1. manager.ts - OrderManager class (order lifecycle, fund tracking)
34
34
  * 2. grid.ts - Grid class (grid creation, synchronization, health)
35
35
  * 3. utils/math.ts, utils/order.ts, utils/system.ts - Helper functions by concern
36
- * 4. format.ts - Numeric formatting (18 functions for consistent display)
36
+ * 4. format.ts - Numeric formatting (17 functions for consistent display)
37
37
  * 5. accounting.ts - Accountant class (fund calculations and reconciliation)
38
38
  * 6. logger.ts - Logger class (structured, color-coded output)
39
39
  * 7. async_lock.ts - AsyncLock class (race condition prevention)
@@ -16,7 +16,7 @@
16
16
  * - Maintain audit trail for debugging
17
17
  *
18
18
  * ===============================================================================
19
- * TABLE OF CONTENTS - LoggerState Class (2 methods)
19
+ * TABLE OF CONTENTS - LoggerState Class (3 methods)
20
20
  * ===============================================================================
21
21
  *
22
22
  * INITIALIZATION (1 method)
@@ -17,7 +17,7 @@
17
17
  * - Maintain audit trail for debugging
18
18
  *
19
19
  * ===============================================================================
20
- * TABLE OF CONTENTS - LoggerState Class (2 methods)
20
+ * TABLE OF CONTENTS - LoggerState Class (3 methods)
21
21
  * ===============================================================================
22
22
  *
23
23
  * INITIALIZATION (1 method)
@@ -672,7 +672,30 @@ declare class OrderManager implements OrderManagerLike {
672
672
  *
673
673
  * @param {string} reason - Log/debug label for the drop
674
674
  */
675
- _clearPendingFillCrawls(reason?: string): void;
675
+ /**
676
+ * Drop ALL owed fill-crawl records.
677
+ *
678
+ * This is the explicit allowed-loss path: the grid generation is being
679
+ * discarded (rebuild, rejected snapshot, restart replay), so the relative
680
+ * deltas no longer have a geometry to apply onto.
681
+ */
682
+ _clearPendingFillCrawls(reason?: string, detail?: string): void;
683
+ /**
684
+ * Consume the owed fill-crawl records a derivation actually folded.
685
+ *
686
+ * A boundary commit must never clear a record it could not apply: a
687
+ * truncated cross-chunk shift, an edge-classified slot of an older
688
+ * generation, or a record re-written for the same slot after the
689
+ * derivation ran. Clearing all of them was the last way a fill's crawl
690
+ * could be lost silently (2026-10-25: 7 fills swept slots 147-153, the
691
+ * commits dropped every record and the boundary ended 7 levels behind).
692
+ *
693
+ * `consumed` is the derivation's `consumedCrawlIds`; absent/not-an-array
694
+ * means the plan never derived a boundary (e.g. a create-only correction),
695
+ * so NOTHING is consumed. Records are matched by `slotId` + `ts`, so a
696
+ * newer record for the same slot survives a stale consumption.
697
+ */
698
+ _consumePendingFillCrawls(consumed: unknown, reason?: string, detail?: string): void;
676
699
  /**
677
700
  * Observability (fix #4, docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md §2): emit the live
678
701
  * boundary whenever roles are (re)assigned, so a silent boundary crawl that
@@ -730,12 +753,12 @@ declare class OrderManager implements OrderManagerLike {
730
753
  _resetLastFillPivot(reason?: string): boolean;
731
754
  /**
732
755
  * Record last filled price for the single-pivot guard: when armed, BOTH
733
- * sides are gated against the most recent fill price (BUY blocked above
734
- * pivot*(1-halfInc), SELL blocked below pivot*(1+halfInc); see
735
- * isLastFillGuardBlocked). Spread-correction bypasses. _lastFilledType is
736
- * purely the cold/armed discriminator (null => disabled). The per-side
737
- * fields are not read by the guard itself; they feed the book-seed
738
- * cold-check and per-side seeding in seedLastFilledPricesFromBook.
756
+ * sides are gated by the direction rule against the most recent fill price
757
+ * (BUY blocked at/above the pivot, SELL blocked at/below it; see
758
+ * isLastFillGuardBlocked). _lastFilledType is purely the cold/armed
759
+ * discriminator (null => disabled). The per-side fields are not read by the
760
+ * guard itself; they feed the book-seed cold-check and per-side seeding in
761
+ * seedLastFilledPricesFromBook.
739
762
  * @param {Array} fills
740
763
  */
741
764
  recordLastFilledPrices(fills: COWFillLike[]): void;