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
@@ -5,13 +5,14 @@ import { PROCESSED_FILL_PERSISTENCE_MODES } from './order/processed_fill_store.j
5
5
  import { NATIVE_CLIENT, FILL_PROCESSING, TIMING, MAINTENANCE, ORDER_TYPES } from './constants.js';
6
6
  import { getErrorMessage, resolveSeamMsOrNull, getErrorField } from './utils/errors.js';
7
7
  import { isOrderDoesNotExistError } from './dexbot_maintenance_runtime.js';
8
- import { slotIndexForPrice, isChainPriceOutOfGrid, isSlotInRail } from './order/utils/math.js';
8
+ import { slotIndexForPrice, isChainPriceOutOfGrid, isSlotInRail, resolveGapSlots } from './order/utils/math.js';
9
9
  import { attributeUnmatchedFillToGrid } from './order/utils/order.js';
10
10
  import { ORDER_STATES } from './constants.js';
11
11
  const buildFillKey = lazyShim('./order/utils/order', 'buildFillKey');
12
12
  const correctAllPriceMismatches = lazyShim('./order/utils/order', 'correctAllPriceMismatches');
13
13
  const parseChainOrder = lazyShim('./order/utils/order', 'parseChainOrder');
14
14
  const retryPersistenceIfNeeded = lazyShim('./order/utils/system', 'retryPersistenceIfNeeded');
15
+ const getPipelineInFlightAgeMs = lazyShim('./order/utils/system', 'getPipelineInFlightAgeMs');
15
16
  const { readOpenOrdersGuarded } = chainOrders;
16
17
  /**
17
18
  * Whether an unknown fill's order plausibly belongs to THIS bot's grid and
@@ -68,7 +69,10 @@ async function isUnknownFillOrderAdoptable(bot, fillOp) {
68
69
  if (!slot)
69
70
  return false;
70
71
  const boundaryIdx = bot.manager.boundaryIdx;
71
- const gapSlots = genesis.gapSlots ?? bot.manager._gapSlots ?? 0;
72
+ // Gap 0 is not a valid geometry (it makes the slot above the
73
+ // boundary a SELL rail member); resolveGapSlots supplies the
74
+ // config-derived band width when neither source has one.
75
+ const gapSlots = genesis.gapSlots ?? resolveGapSlots(bot.manager);
72
76
  if (boundaryIdx != null && !isSlotInRail(boundaryIdx, gapSlots, parsed.type, { id: slotId }))
73
77
  return false;
74
78
  return slot.state === ORDER_STATES.VIRTUAL || !slot.orderId;
@@ -134,13 +138,31 @@ async function processSweepOrphanFill(bot, fill, fillOp, processedFillKeys, opts
134
138
  }
135
139
  return true;
136
140
  }
137
- // GEOMETRY FIRST, then money. The order is unknown to the grid, but the
138
- // fill still proves a trade at a price: attribute it (pivot + owed crawl)
139
- // BEFORE crediting the proceeds, so a fill that never reaches the strategy
140
- // cannot leave the LAST-FILL-GUARD pivot stale — the same split-brain the
141
- // unmatched-fill path closes for a virtualised slot. Attribution refuses a
142
- // price outside the frozen rail, so a shelf/manual order can never arm the
143
- // pivot at a level this grid does not trade.
141
+ // ACCOUNTING FIRST, then geometry. The processed-fill ledger is the single
142
+ // authority on whether this fill was already booked: a replayed fill comes
143
+ // back as `duplicate` and has ALREADY armed the pivot and the owed crawl on
144
+ // its first delivery. Re-attributing that replay re-arms geometry from a
145
+ // stale execution price (live incident: a 12-minute-old replay re-recorded
146
+ // four crawls and teleported the boundary 165 -> 169). Crediting first is
147
+ // still before the strategy batch, so a first-delivery fill cannot leave the
148
+ // LAST-FILL-GUARD pivot stale — the same split-brain the unmatched-fill path
149
+ // closes for a virtualised slot. Attribution refuses a price outside the
150
+ // frozen rail, so a shelf/manual order can never arm the pivot at a level
151
+ // this grid does not trade.
152
+ const accountingResult = await bot._applyReplaySafeOrphanFillAccounting(fill, fillOp, {
153
+ context: opts.context,
154
+ logger: opts.logger,
155
+ replayMessage: opts.replayMessage,
156
+ });
157
+ // A replay already armed the pivot and the owed crawl on its first delivery,
158
+ // so it must not be re-attributed (the replay message is already logged by
159
+ // the accounting wrapper). `applied`, `error` and `missing_key` are first
160
+ // deliveries (or deliveries whose money never booked), so they still prove
161
+ // the trade and must arm the geometry.
162
+ if (accountingResult.status === 'duplicate') {
163
+ return false;
164
+ }
165
+ (opts.logger ?? bot.manager.logger).log?.(`[${opts.label}] Processing funds for unknown order ${fillOp.order_id} (not in grid but crediting proceeds)`, 'warn');
144
166
  try {
145
167
  const pays = fillOp?.pays;
146
168
  const receives = fillOp?.receives;
@@ -153,12 +175,6 @@ async function processSweepOrphanFill(bot, fill, fillOp, processedFillKeys, opts
153
175
  });
154
176
  }
155
177
  catch { /* attribution is best-effort: never block the credit */ }
156
- (opts.logger ?? bot.manager.logger).log?.(`[${opts.label}] Processing funds for unknown order ${fillOp.order_id} (not in grid but crediting proceeds)`, 'warn');
157
- const accountingResult = await bot._applyReplaySafeOrphanFillAccounting(fill, fillOp, {
158
- context: opts.context,
159
- logger: opts.logger,
160
- replayMessage: opts.replayMessage,
161
- });
162
178
  return accountingResult.status === 'missing_key';
163
179
  }
164
180
  function wireProcessedFillTracking(bot) {
@@ -183,22 +199,37 @@ function wireProcessedFillTracking(bot) {
183
199
  async function cancelResidualOrders(bot, residualCancels) {
184
200
  if (!residualCancels || residualCancels.length === 0)
185
201
  return;
186
- for (const rc of residualCancels) {
187
- if (!rc || !rc.orderId)
188
- continue;
189
- try {
190
- await chainOrders.cancelOrder(bot.account, bot.privateKey, rc.orderId);
191
- bot.manager.logger.log(`[RESIDUAL] Cancelled residual order ${rc.orderId}${rc.id ? ` (slot ${rc.id})` : ''} left on chain after sub-dust fill`, 'warn');
192
- }
193
- catch (err) {
194
- const errMsg = getErrorMessage(err) || '';
195
- if (isOrderDoesNotExistError(errMsg, rc.orderId)) {
196
- bot.manager.logger.log(`[RESIDUAL] Residual order ${rc.orderId} already gone from chain; nothing to cancel`, 'debug');
202
+ const run = async () => {
203
+ for (const rc of residualCancels) {
204
+ if (!rc || !rc.orderId)
205
+ continue;
206
+ try {
207
+ await chainOrders.cancelOrder(bot.account, bot.privateKey, rc.orderId);
208
+ bot.manager.logger.log(`[RESIDUAL] Cancelled residual order ${rc.orderId}${rc.id ? ` (slot ${rc.id})` : ''} left on chain after sub-dust fill`, 'warn');
197
209
  }
198
- else {
199
- bot.manager.logger.log(`[RESIDUAL] Failed to cancel residual order ${rc.orderId}: ${errMsg}`, 'warn');
210
+ catch (err) {
211
+ const errMsg = getErrorMessage(err) || '';
212
+ if (isOrderDoesNotExistError(errMsg, rc.orderId)) {
213
+ bot.manager.logger.log(`[RESIDUAL] Residual order ${rc.orderId} already gone from chain; nothing to cancel`, 'debug');
214
+ }
215
+ else {
216
+ bot.manager.logger.log(`[RESIDUAL] Failed to cancel residual order ${rc.orderId}: ${errMsg}`, 'warn');
217
+ }
200
218
  }
201
219
  }
220
+ return true;
221
+ };
222
+ // Residual cancels are chain mutations: serialize them with every other
223
+ // placement path. On a busy/shutting-down region leave the residuals for
224
+ // the next sync/reconcile rather than racing a live batch.
225
+ const placementOk = typeof bot.manager.withPlacement === 'function'
226
+ ? await bot.manager.withPlacement('fill-residual-cancel', run, {
227
+ timeoutMs: 10000,
228
+ isShuttingDown: () => bot._shuttingDown === true,
229
+ })
230
+ : await run();
231
+ if (placementOk !== true) {
232
+ bot.manager.logger.log(`[RESIDUAL] Deferring ${residualCancels.length} residual cancel(s): exclusive placement region busy or shutting down`, 'warn');
202
233
  }
203
234
  }
204
235
  /**
@@ -472,8 +503,34 @@ export function consumeDeferredDrainMarker(bot) {
472
503
  function shouldDeferFillForBroadcast(bot, nowMs) {
473
504
  const now = Number.isFinite(Number(nowMs)) ? Number(nowMs) : Date.now();
474
505
  let active = false;
506
+ let regionStartedAt = 0;
507
+ let viaPlacement = false;
475
508
  try {
476
- active = bot?.manager?.isBroadcastingActive?.() === true;
509
+ const broadcastingActive = bot?.manager?.isBroadcastingActive?.() === true;
510
+ const placementActive = bot?.manager?.isPlacementActive?.() === true;
511
+ // Placement is the authoritative mutex AND the lease that owns the
512
+ // region's lifetime. A reconcile/COW holds BOTH (startBroadcasting is
513
+ // called inside the placement region), so `viaPlacement` must win even
514
+ // when the broadcast refcount is also active: only the placement
515
+ // watchdog can end a legitimate 8-minute reconcile, and the broadcast
516
+ // deferral bound (150s) would otherwise drop fills into the region.
517
+ active = broadcastingActive || placementActive;
518
+ viaPlacement = placementActive;
519
+ if (broadcastingActive) {
520
+ regionStartedAt = Number(bot?.manager?._broadcastingStartedAt) || 0;
521
+ }
522
+ else if (placementActive) {
523
+ // Placement is the authoritative mutex; the broadcast refcount is
524
+ // only advisory. A correction drain / reconcile Phase 2 / dust
525
+ // cancel holds placement WITHOUT startBroadcasting(), so gating on
526
+ // the refcount alone lets fills book accounting while that path
527
+ // broadcasts. Treat the placement hold as a live region.
528
+ const heldMs = Number(bot?.manager?.placementHeldForMs?.()) || 0;
529
+ // Round to a second: placementHeldForMs() grows between calls, and
530
+ // raw millisecond jitter would look like an advancing region and
531
+ // re-arm the deferral bound forever (defeating its purpose).
532
+ regionStartedAt = heldMs > 0 ? Math.round((now - heldMs) / 1000) * 1000 : now;
533
+ }
477
534
  }
478
535
  catch {
479
536
  active = false;
@@ -489,16 +546,30 @@ function shouldDeferFillForBroadcast(bot, nowMs) {
489
546
  // Region-change detection: startBroadcasting() refreshes
490
547
  // _broadcastingStartedAt on every increment, so an advancing timestamp
491
548
  // proves the region is live and re-arms the bound. A frozen flag does
492
- // not advance it and still falls through at the bound.
493
- const regionStartedAt = Number(bot?.manager?._broadcastingStartedAt) || 0;
549
+ // not advance it and still falls through at the bound. A placement hold
550
+ // derives its start from placementHeldForMs() for the same reason.
494
551
  const lastRegionAt = Number(bot?._fillBroadcastDeferRegionAt) || 0;
495
552
  if (regionStartedAt && regionStartedAt !== lastRegionAt) {
496
553
  bot._fillBroadcastDeferRegionAt = regionStartedAt;
497
554
  bot._fillBroadcastDeferSince = now;
498
555
  }
499
- const deferMaxMs = Number(TIMING?.FILL_BROADCAST_DEFER_MAX_MS) > 0
500
- ? Number(TIMING.FILL_BROADCAST_DEFER_MAX_MS)
501
- : 60000;
556
+ // Placement holds are cleared by the placement watchdog
557
+ // (_clearStalePlacementRegion), NOT by falling through into a broadcast:
558
+ // a legitimate long reconcile (the 2026-11 live run had ~8-minute
559
+ // windows) must keep fills deferred, while a leaked lease is force-
560
+ // released by the watchdog this consumer invokes. The fallback bound here
561
+ // is therefore only a last-resort valve sized past that watchdog.
562
+ const placementStaleMs = Number(TIMING?.PLACEMENT_STALE_CLEAR_MS) > 0
563
+ ? Number(TIMING.PLACEMENT_STALE_CLEAR_MS)
564
+ : 15 * 60 * 1000;
565
+ const placementSafetyMs = Number(TIMING?.BROADCAST_DEFER_SAFETY_MARGIN_MS) > 0
566
+ ? Number(TIMING.BROADCAST_DEFER_SAFETY_MARGIN_MS)
567
+ : 30000;
568
+ const deferMaxMs = viaPlacement
569
+ ? placementStaleMs + placementSafetyMs
570
+ : (Number(TIMING?.FILL_BROADCAST_DEFER_MAX_MS) > 0
571
+ ? Number(TIMING.FILL_BROADCAST_DEFER_MAX_MS)
572
+ : 60000);
502
573
  const since = Number(bot?._fillBroadcastDeferSince) || 0;
503
574
  if (!since)
504
575
  bot._fillBroadcastDeferSince = now;
@@ -926,6 +997,16 @@ async function consumeFillQueue(bot, chainOrders) {
926
997
  if (typeof bot.manager?._clearStaleBroadcastFlag === 'function') {
927
998
  bot.manager._clearStaleBroadcastFlag();
928
999
  }
1000
+ // Placement watchdog: a leaked/hung lease parks this queue; the
1001
+ // consumer is the one place guaranteed to run while the queue is
1002
+ // non-empty (maintenance may be idle-gated by the same queue). The
1003
+ // pipeline age lets the watchdog refuse a teardown while a live batch
1004
+ // is still making progress.
1005
+ if (typeof bot.manager?._clearStalePlacementRegion === 'function') {
1006
+ bot.manager._clearStalePlacementRegion(undefined, {
1007
+ batchInFlightMs: getPipelineInFlightAgeMs(bot),
1008
+ });
1009
+ }
929
1010
  }
930
1011
  catch { /* watchdog must never break fill consumption */ }
931
1012
  if (bot._batchInFlight || bot._recoverySyncInFlight) {
@@ -1223,8 +1304,16 @@ async function consumeFillQueue(bot, chainOrders) {
1223
1304
  }
1224
1305
  if (ordersNeedingCorrection.length > 0) {
1225
1306
  const correctionResult = await correctAllPriceMismatches(bot.manager, bot.account, bot.privateKey, chainOrders);
1226
- if (correctionResult.failed > 0)
1307
+ // The drain takes the exclusive placement region; a busy
1308
+ // region defers it (queued entries stay and the next
1309
+ // maintenance tick retries). Log it like the maintenance
1310
+ // path does, or the deferral is silently invisible.
1311
+ if (correctionResult?.deferred === true) {
1312
+ bot.manager.logger.log(`[FILL-QUEUE] Deferring price-correction drain: ${correctionResult.reason || 'placement region busy'}`, 'info');
1313
+ }
1314
+ else if (correctionResult.failed > 0) {
1227
1315
  bot.manager.logger.log(`${correctionResult.failed} corrections failed`, 'error');
1316
+ }
1228
1317
  }
1229
1318
  }
1230
1319
  finally {
@@ -265,7 +265,7 @@ declare function stopBotsConfigPollInterval(bot: BotLike): void;
265
265
  /**
266
266
  * Release the market adapter runtime for a bot.
267
267
  * In PM2 mode this is a no-op; in direct mode it calls the shared runtime's releaseBot.
268
- * @param {import('./dexbot_class.js').DEXBot} bot
268
+ * @param {unknown} _bot - Unused; release is keyed by botId.
269
269
  * @param {string} botId - Bot identifier
270
270
  * @param {string} [context='shutdown'] - Context label for logging
271
271
  * @returns {Promise<any>}