dexbot 1.6.18 → 1.7.1

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 (146) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/README.md +24 -18
  3. package/analysis/README.md +117 -5
  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_dynamic_weight.js +2 -1
  9. package/dist/analysis/analyze_kalman.js +3 -2
  10. package/dist/analysis/analyze_liquidity.d.ts +17 -0
  11. package/dist/analysis/analyze_liquidity.js +336 -0
  12. package/dist/analysis/analyze_regime.js +3 -2
  13. package/dist/analysis/analyze_regime_windows.js +3 -2
  14. package/dist/analysis/analyze_volatility.js +3 -2
  15. package/dist/analysis/bot_key_utils.d.ts +44 -1
  16. package/dist/analysis/bot_key_utils.js +76 -7
  17. package/dist/analysis/fills_cache.js +2 -1
  18. package/dist/analysis/grid_correction_check.d.ts +1 -19
  19. package/dist/analysis/grid_correction_check.js +12 -30
  20. package/dist/analysis/liquidity/liquidity_chain.d.ts +66 -0
  21. package/dist/analysis/liquidity/liquidity_chain.js +178 -0
  22. package/dist/analysis/liquidity/liquidity_chart_generator.d.ts +19 -0
  23. package/dist/analysis/liquidity/liquidity_chart_generator.js +693 -0
  24. package/dist/analysis/liquidity/liquidity_depth_model.d.ts +166 -0
  25. package/dist/analysis/liquidity/liquidity_depth_model.js +258 -0
  26. package/dist/analysis/liquidity/liquidity_view.d.ts +53 -0
  27. package/dist/analysis/liquidity/liquidity_view.js +66 -0
  28. package/dist/analysis/resolve_bot_accounts.js +7 -6
  29. package/dist/analysis/trade_profitability.js +4 -2
  30. package/dist/analysis/tradingview/analyze_tradingview.js +2 -1
  31. package/dist/credential-daemon.js +13 -2
  32. package/dist/dexbot.js +77 -172
  33. package/dist/modules/account_bots.d.ts +11 -1
  34. package/dist/modules/account_orders.d.ts +12 -0
  35. package/dist/modules/account_orders.js +30 -0
  36. package/dist/modules/asset_lookup.d.ts +25 -0
  37. package/dist/modules/asset_lookup.js +75 -0
  38. package/dist/modules/bitshares-native/transport.js +24 -6
  39. package/dist/modules/bitshares_client.d.ts +24 -6
  40. package/dist/modules/bitshares_client.js +44 -7
  41. package/dist/modules/bot_settings.d.ts +2 -0
  42. package/dist/modules/chain_scan.d.ts +64 -0
  43. package/dist/modules/chain_scan.js +80 -0
  44. package/dist/modules/cli_colors.d.ts +5 -0
  45. package/dist/modules/cli_colors.js +7 -0
  46. package/dist/modules/cli_progress.d.ts +51 -0
  47. package/dist/modules/cli_progress.js +113 -0
  48. package/dist/modules/constants.d.ts +26 -3
  49. package/dist/modules/constants.js +63 -8
  50. package/dist/modules/dexbot_class.d.ts +1 -6
  51. package/dist/modules/dexbot_class.js +14 -0
  52. package/dist/modules/dexbot_cow_runtime.d.ts +97 -7
  53. package/dist/modules/dexbot_cow_runtime.js +634 -136
  54. package/dist/modules/dexbot_fill_runtime.js +132 -23
  55. package/dist/modules/dexbot_maintenance_runtime.js +242 -74
  56. package/dist/modules/dexbot_startup_runtime.js +32 -20
  57. package/dist/modules/dexbot_state_recovery.d.ts +33 -1
  58. package/dist/modules/dexbot_state_recovery.js +167 -5
  59. package/dist/modules/launcher/runtime_entry.d.ts +21 -1
  60. package/dist/modules/launcher/runtime_entry.js +36 -1
  61. package/dist/modules/liquidity_pool_ref.d.ts +32 -0
  62. package/dist/modules/liquidity_pool_ref.js +116 -0
  63. package/dist/modules/node_connect_policy.d.ts +8 -1
  64. package/dist/modules/node_connect_policy.js +18 -2
  65. package/dist/modules/node_flap_score.d.ts +87 -0
  66. package/dist/modules/node_flap_score.js +124 -0
  67. package/dist/modules/node_health_cache.d.ts +40 -3
  68. package/dist/modules/node_health_cache.js +66 -20
  69. package/dist/modules/node_manager.d.ts +101 -19
  70. package/dist/modules/node_manager.js +255 -65
  71. package/dist/modules/order/accounting.js +56 -7
  72. package/dist/modules/order/format.d.ts +24 -10
  73. package/dist/modules/order/format.js +30 -10
  74. package/dist/modules/order/grid.js +91 -13
  75. package/dist/modules/order/grid_reconcile.d.ts +5 -1
  76. package/dist/modules/order/grid_reconcile.js +333 -189
  77. package/dist/modules/order/grid_reconcile_internal.d.ts +38 -2
  78. package/dist/modules/order/grid_reconcile_internal.js +298 -100
  79. package/dist/modules/order/index.d.ts +19 -1
  80. package/dist/modules/order/lifecycle.d.ts +353 -0
  81. package/dist/modules/order/lifecycle.js +1109 -0
  82. package/dist/modules/order/manager.d.ts +273 -5
  83. package/dist/modules/order/manager.js +654 -48
  84. package/dist/modules/order/placement_lock.d.ts +102 -0
  85. package/dist/modules/order/placement_lock.js +222 -0
  86. package/dist/modules/order/strategy.js +13 -1
  87. package/dist/modules/order/sync_engine.d.ts +33 -1
  88. package/dist/modules/order/sync_engine.js +241 -73
  89. package/dist/modules/order/utils/math.d.ts +39 -1
  90. package/dist/modules/order/utils/math.js +83 -1
  91. package/dist/modules/order/utils/order.d.ts +181 -5
  92. package/dist/modules/order/utils/order.js +455 -9
  93. package/dist/modules/order/utils/system.d.ts +81 -1
  94. package/dist/modules/order/utils/system.js +331 -44
  95. package/dist/modules/order/utils/validate.d.ts +7 -1
  96. package/dist/modules/order/utils/validate.js +80 -3
  97. package/dist/modules/outcome.d.ts +54 -0
  98. package/dist/modules/outcome.js +51 -0
  99. package/dist/modules/settings_merge.d.ts +4 -0
  100. package/dist/modules/settings_merge.js +9 -0
  101. package/dist/modules/timing_policy.d.ts +82 -0
  102. package/dist/modules/timing_policy.js +244 -0
  103. package/dist/modules/types.d.ts +137 -0
  104. package/dist/modules/utils/asset_symbols.d.ts +13 -2
  105. package/dist/modules/utils/asset_symbols.js +21 -2
  106. package/dist/scripts/analysis_runner.d.ts +10 -0
  107. package/dist/scripts/analysis_runner.js +33 -0
  108. package/dist/scripts/analyze-credit.js +54 -17
  109. package/dist/scripts/analyze-orders.d.ts +4 -2
  110. package/dist/scripts/analyze-orders.js +115 -35
  111. package/dist/scripts/asset.d.ts +26 -0
  112. package/dist/scripts/asset.js +165 -0
  113. package/dist/scripts/bts_distribution.d.ts +1 -0
  114. package/dist/scripts/bts_distribution.js +194 -142
  115. package/dist/scripts/chart_command.d.ts +1 -1
  116. package/dist/scripts/chart_command.js +60 -86
  117. package/dist/scripts/chart_targets.d.ts +18 -0
  118. package/dist/scripts/chart_targets.js +48 -0
  119. package/dist/scripts/dw.js +1 -1
  120. package/dist/scripts/liquid.d.ts +24 -0
  121. package/dist/scripts/liquid.js +134 -0
  122. package/dist/scripts/rich_list.js +12 -16
  123. package/dist/scripts/test-credit-renewal.js +12 -5
  124. package/dist/scripts/token_distribution.d.ts +2 -0
  125. package/dist/scripts/token_distribution.js +132 -108
  126. package/dist/scripts/tv.js +1 -1
  127. package/dist/scripts/verify-browser-bundle.js +18 -0
  128. package/docs/COW_INVARIANTS.md +69 -10
  129. package/docs/DEXBOT_COMPARISON.md +6 -6
  130. package/docs/EVOLUTION.md +10 -8
  131. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  132. package/docs/GRID_PRICE_INVARIANT.md +5 -2
  133. package/docs/GRID_RECONCILE.md +36 -11
  134. package/docs/LOGGING.md +50 -4
  135. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +177 -27
  136. package/docs/README.md +23 -2
  137. package/docs/WORKFLOW.md +12 -4
  138. package/docs/architecture.md +42 -5
  139. package/docs/developer_guide.md +25 -8
  140. package/modules/README.md +8 -1
  141. package/package.json +3 -1
  142. package/scripts/README.md +39 -7
  143. package/scripts/pdev.sh +14 -1
  144. package/scripts/pmain.sh +23 -8
  145. package/scripts/ptest.sh +7 -0
  146. package/tests/README.md +30 -1
@@ -5,12 +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
+ import { attributeUnmatchedFillToGrid } from './order/utils/order.js';
9
10
  import { ORDER_STATES } from './constants.js';
10
11
  const buildFillKey = lazyShim('./order/utils/order', 'buildFillKey');
11
12
  const correctAllPriceMismatches = lazyShim('./order/utils/order', 'correctAllPriceMismatches');
12
13
  const parseChainOrder = lazyShim('./order/utils/order', 'parseChainOrder');
13
14
  const retryPersistenceIfNeeded = lazyShim('./order/utils/system', 'retryPersistenceIfNeeded');
15
+ const getPipelineInFlightAgeMs = lazyShim('./order/utils/system', 'getPipelineInFlightAgeMs');
14
16
  const { readOpenOrdersGuarded } = chainOrders;
15
17
  /**
16
18
  * Whether an unknown fill's order plausibly belongs to THIS bot's grid and
@@ -67,7 +69,10 @@ async function isUnknownFillOrderAdoptable(bot, fillOp) {
67
69
  if (!slot)
68
70
  return false;
69
71
  const boundaryIdx = bot.manager.boundaryIdx;
70
- 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);
71
76
  if (boundaryIdx != null && !isSlotInRail(boundaryIdx, gapSlots, parsed.type, { id: slotId }))
72
77
  return false;
73
78
  return slot.state === ORDER_STATES.VIRTUAL || !slot.orderId;
@@ -133,12 +138,43 @@ async function processSweepOrphanFill(bot, fill, fillOp, processedFillKeys, opts
133
138
  }
134
139
  return true;
135
140
  }
136
- (opts.logger ?? bot.manager.logger).log?.(`[${opts.label}] Processing funds for unknown order ${fillOp.order_id} (not in grid but crediting proceeds)`, 'warn');
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.
137
152
  const accountingResult = await bot._applyReplaySafeOrphanFillAccounting(fill, fillOp, {
138
153
  context: opts.context,
139
154
  logger: opts.logger,
140
155
  replayMessage: opts.replayMessage,
141
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');
166
+ try {
167
+ const pays = fillOp?.pays;
168
+ const receives = fillOp?.receives;
169
+ attributeUnmatchedFillToGrid(bot.manager, {
170
+ orderId: fillOp?.order_id != null ? String(fillOp.order_id) : null,
171
+ paysAssetId: pays?.asset_id ?? null,
172
+ paysAmountRaw: pays?.amount ?? null,
173
+ receivesAssetId: receives?.asset_id ?? null,
174
+ receivesAmountRaw: receives?.amount ?? null,
175
+ });
176
+ }
177
+ catch { /* attribution is best-effort: never block the credit */ }
142
178
  return accountingResult.status === 'missing_key';
143
179
  }
144
180
  function wireProcessedFillTracking(bot) {
@@ -163,22 +199,37 @@ function wireProcessedFillTracking(bot) {
163
199
  async function cancelResidualOrders(bot, residualCancels) {
164
200
  if (!residualCancels || residualCancels.length === 0)
165
201
  return;
166
- for (const rc of residualCancels) {
167
- if (!rc || !rc.orderId)
168
- continue;
169
- try {
170
- await chainOrders.cancelOrder(bot.account, bot.privateKey, rc.orderId);
171
- bot.manager.logger.log(`[RESIDUAL] Cancelled residual order ${rc.orderId}${rc.id ? ` (slot ${rc.id})` : ''} left on chain after sub-dust fill`, 'warn');
172
- }
173
- catch (err) {
174
- const errMsg = getErrorMessage(err) || '';
175
- if (isOrderDoesNotExistError(errMsg, rc.orderId)) {
176
- 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');
177
209
  }
178
- else {
179
- 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
+ }
180
218
  }
181
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');
182
233
  }
183
234
  }
184
235
  /**
@@ -452,8 +503,34 @@ export function consumeDeferredDrainMarker(bot) {
452
503
  function shouldDeferFillForBroadcast(bot, nowMs) {
453
504
  const now = Number.isFinite(Number(nowMs)) ? Number(nowMs) : Date.now();
454
505
  let active = false;
506
+ let regionStartedAt = 0;
507
+ let viaPlacement = false;
455
508
  try {
456
- 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
+ }
457
534
  }
458
535
  catch {
459
536
  active = false;
@@ -469,16 +546,30 @@ function shouldDeferFillForBroadcast(bot, nowMs) {
469
546
  // Region-change detection: startBroadcasting() refreshes
470
547
  // _broadcastingStartedAt on every increment, so an advancing timestamp
471
548
  // proves the region is live and re-arms the bound. A frozen flag does
472
- // not advance it and still falls through at the bound.
473
- 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.
474
551
  const lastRegionAt = Number(bot?._fillBroadcastDeferRegionAt) || 0;
475
552
  if (regionStartedAt && regionStartedAt !== lastRegionAt) {
476
553
  bot._fillBroadcastDeferRegionAt = regionStartedAt;
477
554
  bot._fillBroadcastDeferSince = now;
478
555
  }
479
- const deferMaxMs = Number(TIMING?.FILL_BROADCAST_DEFER_MAX_MS) > 0
480
- ? Number(TIMING.FILL_BROADCAST_DEFER_MAX_MS)
481
- : 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);
482
573
  const since = Number(bot?._fillBroadcastDeferSince) || 0;
483
574
  if (!since)
484
575
  bot._fillBroadcastDeferSince = now;
@@ -906,6 +997,16 @@ async function consumeFillQueue(bot, chainOrders) {
906
997
  if (typeof bot.manager?._clearStaleBroadcastFlag === 'function') {
907
998
  bot.manager._clearStaleBroadcastFlag();
908
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
+ }
909
1010
  }
910
1011
  catch { /* watchdog must never break fill consumption */ }
911
1012
  if (bot._batchInFlight || bot._recoverySyncInFlight) {
@@ -1203,8 +1304,16 @@ async function consumeFillQueue(bot, chainOrders) {
1203
1304
  }
1204
1305
  if (ordersNeedingCorrection.length > 0) {
1205
1306
  const correctionResult = await correctAllPriceMismatches(bot.manager, bot.account, bot.privateKey, chainOrders);
1206
- 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) {
1207
1315
  bot.manager.logger.log(`${correctionResult.failed} corrections failed`, 'error');
1316
+ }
1208
1317
  }
1209
1318
  }
1210
1319
  finally {