dexbot 1.6.16 → 1.6.18

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 (124) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/analysis/README.md +10 -9
  3. package/analysis/ama_fitting/README.md +2 -2
  4. package/analysis/bot_fitting/README.md +3 -3
  5. package/analysis/tradingview/README.md +2 -2
  6. package/analysis/trend_detection/DYNAMIC_WEIGHT_RESEARCH.md +1 -1
  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/analyze_args.d.ts +2 -1
  12. package/dist/analysis/fills_source.d.ts +1 -8
  13. package/dist/analysis/fills_source.js +1 -1
  14. package/dist/analysis/grid_correction_check.d.ts +9 -6
  15. package/dist/analysis/grid_correction_check.js +56 -64
  16. package/dist/analysis/math_utils.d.ts +1 -1
  17. package/dist/analysis/trade_profitability.d.ts +1 -1
  18. package/dist/analysis/tradingview/grid_reset_sim.js +1 -1
  19. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +7 -7
  20. package/dist/analysis/trend_detection/backtest_ama_slope_huber.js +1 -1
  21. package/dist/analysis/trend_detection/huber_scale_variants.d.ts +4 -3
  22. package/dist/market_adapter/cli_args.d.ts +6 -1
  23. package/dist/market_adapter/cli_args.js +16 -2
  24. package/dist/market_adapter/core/kibana_candles.d.ts +5 -1
  25. package/dist/market_adapter/core/kibana_candles.js +3 -1
  26. package/dist/market_adapter/core/strategies/regime_gate.d.ts +7 -1
  27. package/dist/market_adapter/core/strategies/regime_gate.js +3 -1
  28. package/dist/market_adapter/inputs/cex_candle_parsing.d.ts +7 -2
  29. package/dist/market_adapter/inputs/cex_candle_parsing.js +3 -1
  30. package/dist/market_adapter/inputs/fetch_book_data.d.ts +7 -1
  31. package/dist/market_adapter/inputs/fetch_book_data.js +3 -1
  32. package/dist/market_adapter/inputs/fetch_cex_synthetic_data.js +2 -11
  33. package/dist/market_adapter/inputs/fetch_lp_data.d.ts +26 -1
  34. package/dist/market_adapter/inputs/fetch_lp_data.js +62 -52
  35. package/dist/market_adapter/inputs/kibana_feed_source.d.ts +14 -2
  36. package/dist/market_adapter/inputs/kibana_feed_source.js +14 -1
  37. package/dist/market_adapter/inputs/window_cache.d.ts +14 -3
  38. package/dist/market_adapter/inputs/window_cache.js +14 -1
  39. package/dist/market_adapter/lp_chart_runner.d.ts +12 -9
  40. package/dist/market_adapter/lp_chart_runner.js +3 -1
  41. package/dist/market_adapter/lp_chart_strategy_loader.d.ts +5 -1
  42. package/dist/market_adapter/lp_chart_strategy_loader.js +3 -1
  43. package/dist/market_adapter/market_adapter.d.ts +10 -2
  44. package/dist/market_adapter/market_adapter.js +10 -11
  45. package/dist/market_adapter/utils/chain.d.ts +2 -3
  46. package/dist/market_adapter/utils/file_json_cache.d.ts +5 -1
  47. package/dist/market_adapter/utils/file_json_cache.js +3 -1
  48. package/dist/market_adapter/utils/file_lock.js +1 -1
  49. package/dist/market_adapter/utils/native_history.d.ts +7 -3
  50. package/dist/market_adapter/utils/native_history.js +3 -1
  51. package/dist/market_adapter/utils/pair_orientation.d.ts +2 -2
  52. package/dist/modules/account_bots.d.ts +3 -0
  53. package/dist/modules/bots_file_lock.d.ts +2 -2
  54. package/dist/modules/bots_file_lock.js +2 -2
  55. package/dist/modules/chain_keys.d.ts +1 -1
  56. package/dist/modules/constants.d.ts +6 -0
  57. package/dist/modules/constants.js +37 -6
  58. package/dist/modules/credit_pricing.d.ts +20 -1
  59. package/dist/modules/credit_pricing.js +23 -1
  60. package/dist/modules/credit_runtime.js +33 -16
  61. package/dist/modules/dexbot_class.d.ts +11 -1
  62. package/dist/modules/dexbot_class.js +15 -2
  63. package/dist/modules/dexbot_cow_runtime.d.ts +90 -38
  64. package/dist/modules/dexbot_cow_runtime.js +507 -108
  65. package/dist/modules/dexbot_credential_client.d.ts +5 -0
  66. package/dist/modules/dexbot_maintenance_runtime.js +117 -12
  67. package/dist/modules/dexbot_startup_runtime.js +7 -1
  68. package/dist/modules/graceful_shutdown.d.ts +2 -2
  69. package/dist/modules/graceful_shutdown.js +2 -2
  70. package/dist/modules/launcher/credential_daemon.d.ts +14 -2
  71. package/dist/modules/launcher/credential_daemon.js +60 -26
  72. package/dist/modules/launcher/runtime_mode.d.ts +4 -3
  73. package/dist/modules/node_manager.d.ts +1 -1
  74. package/dist/modules/node_manager.js +1 -1
  75. package/dist/modules/order/accounting.js +2 -1
  76. package/dist/modules/order/export.d.ts +2 -2
  77. package/dist/modules/order/export.js +2 -2
  78. package/dist/modules/order/grid.d.ts +26 -14
  79. package/dist/modules/order/grid.js +416 -73
  80. package/dist/modules/order/grid_reconcile.js +5 -1
  81. package/dist/modules/order/grid_reconcile_internal.js +2 -1
  82. package/dist/modules/order/index.d.ts +22 -1
  83. package/dist/modules/order/manager.d.ts +40 -7
  84. package/dist/modules/order/manager.js +149 -23
  85. package/dist/modules/order/strategy.d.ts +5 -0
  86. package/dist/modules/order/strategy.js +44 -3
  87. package/dist/modules/order/sync_engine.d.ts +12 -1
  88. package/dist/modules/order/sync_engine.js +135 -20
  89. package/dist/modules/order/utils/math.d.ts +49 -10
  90. package/dist/modules/order/utils/math.js +71 -14
  91. package/dist/modules/order/utils/order.d.ts +65 -11
  92. package/dist/modules/order/utils/order.js +198 -28
  93. package/dist/modules/order/utils/system.d.ts +112 -2
  94. package/dist/modules/order/utils/system.js +338 -12
  95. package/dist/modules/order/utils/validate.d.ts +4 -1
  96. package/dist/modules/order/utils/validate.js +9 -2
  97. package/dist/modules/storage/index.d.ts +3 -2
  98. package/dist/modules/storage/index.js +3 -2
  99. package/dist/modules/types.d.ts +44 -2
  100. package/dist/scripts/analyze-credit.js +64 -23
  101. package/dist/scripts/bts_distribution.d.ts +66 -0
  102. package/dist/scripts/bts_distribution.js +2102 -0
  103. package/dist/scripts/token_distribution.d.ts +45 -0
  104. package/dist/scripts/token_distribution.js +1870 -0
  105. package/dist/unlock.js +42 -24
  106. package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -1
  107. package/docs/COW_INVARIANTS.md +24 -8
  108. package/docs/DEXBOT_COMPARISON.md +5 -5
  109. package/docs/EVOLUTION.md +10 -8
  110. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +13 -11
  111. package/docs/GRID_PRICE_INVARIANT.md +29 -3
  112. package/docs/GRID_RECALCULATION.md +3 -3
  113. package/docs/GRID_RECONCILE.md +5 -5
  114. package/docs/LIFECYCLE.md +11 -11
  115. package/docs/LOGGING.md +22 -0
  116. package/docs/MPA_CREDIT_USAGE.md +3 -2
  117. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +236 -32
  118. package/docs/README.md +1 -1
  119. package/docs/architecture.md +205 -6
  120. package/docs/developer_guide.md +12 -0
  121. package/market_adapter/README.md +11 -6
  122. package/modules/README.md +18 -14
  123. package/package.json +6 -3
  124. package/scripts/README.md +85 -148
@@ -25,6 +25,11 @@ interface CredentialClientOptions {
25
25
  */
26
26
  onNodeFailed?: (nodeUrl: string) => void;
27
27
  }
28
+ /**
29
+ * Typed daemon reply. Exported because downstream wrapper modules infer it as
30
+ * the return type of `executeOperationsViaCredentialDaemon`; declaration emit
31
+ * cannot name a module-private type there (TS4058).
32
+ */
28
33
  export interface CredentialDaemonResponse {
29
34
  success?: boolean;
30
35
  error?: string;
@@ -8,7 +8,7 @@ const require = createRequire(import.meta.url);
8
8
  import { lazyShim } from './lazy_shim.js';
9
9
  import fs from 'node:fs';
10
10
  import { spawn } from 'node:child_process';
11
- import { nowIso, fireStructuralResync } from './order/utils/system.js';
11
+ import { nowIso, fireStructuralResync, resolveLastFillGuardReference } from './order/utils/system.js';
12
12
  import { path } from './path_api.js';
13
13
  import * as chainOrders from './chain_orders.js';
14
14
  import * as grid from './order/grid.js';
@@ -72,7 +72,7 @@ function getCoreOrdersTotal(config) { return require('./order/utils/order').getC
72
72
  const correctAllPriceMismatches = lazyShim('./order/utils/order', 'correctAllPriceMismatches');
73
73
  const isOrderOnChain = lazyShim('./order/utils/order', 'isOrderOnChain');
74
74
  const parseChainOrder = lazyShim('./order/utils/order', 'parseChainOrder');
75
- const parseSlotIndex = lazyShim('./order/utils/order', 'parseSlotIndex');
75
+ const parseSlotIndex = lazyShim('./order/utils/slot', 'parseSlotIndex');
76
76
  const CODE_ROOT = path.join(__dirname, '..');
77
77
  const PROFILES_DIR = PATHS.PROFILES_DIR;
78
78
  const PROFILES_BOTS_FILE = PATHS.PROFILES.BOTS_JSON;
@@ -673,7 +673,7 @@ function _hasBudgetForSide(manager, config, side) {
673
673
  */
674
674
  export function mirrorSpreadStall(bot, stall) {
675
675
  bot._spreadCorrectionStall = stall ?? null;
676
- bot._spreadFundsExhausted = stall != null;
676
+ bot._spreadStallArmed = stall != null;
677
677
  }
678
678
  function getTargetedSyncReason(bot) {
679
679
  if (!bot.manager || bot.config?.dryRun)
@@ -721,7 +721,7 @@ function getTargetedSyncReason(bot) {
721
721
  // structural stall from a stale one, so arm the refresh for every cause
722
722
  // instead of waiting up to SPREAD_STALE_ESCALATE_MS for the watchdog.
723
723
  // Never recycle resting inventory.
724
- if (bot._spreadFundsExhausted === true) {
724
+ if (bot._spreadStallArmed === true) {
725
725
  const cause = bot._spreadCorrectionStall || 'funds-exhausted';
726
726
  return { reason: `spread correction stalled (${cause})`, targetBuy, targetSell, liveBuy, liveSell, drift };
727
727
  }
@@ -763,8 +763,8 @@ async function maybeRunTargetedDriftReconciliation(bot, context) {
763
763
  // order shortfall. The spread check later this tick re-derives the flag
764
764
  // from fresh state, so a genuinely empty balance re-arms it for the next
765
765
  // tick (subject to the cooldown below).
766
- if (bot._spreadFundsExhausted === true)
767
- bot._spreadFundsExhausted = false;
766
+ if (bot._spreadStallArmed === true)
767
+ bot._spreadStallArmed = false;
768
768
  // Clear the companion cause with the flag so the two never drift apart
769
769
  // (a leftover cause would mislabel the next tick's reason).
770
770
  bot._spreadCorrectionStall = null;
@@ -2516,6 +2516,19 @@ async function executeMaintenanceLogic(bot, context) {
2516
2516
  }
2517
2517
  }
2518
2518
  }
2519
+ /**
2520
+ * Clear the geometry-bind re-center memory (one re-center per fill pivot).
2521
+ * Called whenever the spread actually heals — a placement or a sustained
2522
+ * in-tolerance run — so a later geometry bind on a *different* pivot starts
2523
+ * with a fresh budget.
2524
+ * @param {Object} bot - DEXBot instance
2525
+ */
2526
+ function clearGeometryResyncMemory(bot) {
2527
+ if (!bot)
2528
+ return;
2529
+ bot._lastGeometryResyncPivotKey = '';
2530
+ bot._geometryResyncWarnedPivotKey = '';
2531
+ }
2519
2532
  /**
2520
2533
  * Out-of-spread persistence watchdog: the never-run-stale backstop.
2521
2534
  *
@@ -2538,12 +2551,49 @@ async function executeMaintenanceLogic(bot, context) {
2538
2551
  */
2539
2552
  export function trackOutOfSpreadStaleness(bot, spreadChecked, ordersPlaced, transient = false) {
2540
2553
  const outOfSpread = Number(bot?.manager?.outOfSpread) || 0;
2541
- if (ordersPlaced > 0 || outOfSpread === 0) {
2554
+ const nowMs = Date.now();
2555
+ const inToleranceResetMs = Number(TIMING?.SPREAD_STALE_IN_TOLERANCE_RESET_MS) > 0
2556
+ ? Number(TIMING.SPREAD_STALE_IN_TOLERANCE_RESET_MS)
2557
+ : 10 * 60 * 1000;
2558
+ if (ordersPlaced > 0) {
2559
+ bot._outOfSpreadSince = 0;
2560
+ bot._outOfSpreadStaleWarned = false;
2561
+ bot._outOfSpreadTransientCount = 0;
2562
+ bot._outOfSpreadToleranceSince = 0;
2563
+ clearGeometryResyncMemory(bot);
2564
+ try {
2565
+ bot.manager._spreadRailOversubscribed = null;
2566
+ }
2567
+ catch { /* best-effort */ }
2568
+ return { staleMs: 0, escalated: false };
2569
+ }
2570
+ if (outOfSpread === 0) {
2571
+ // ONE good reading must not clear the clock. The measured spread
2572
+ // oscillates around the tolerance edge, so resetting on each
2573
+ // in-tolerance cycle let a live bot stay out of tolerance for 84
2574
+ // minutes while every individual glance looked recoverable (the
2575
+ // correction placed nothing in that whole window). Clear only after
2576
+ // tolerance has held for the reset window; a placement clears it
2577
+ // immediately (handled above).
2578
+ const toleranceSince = Number(bot._outOfSpreadToleranceSince) || 0;
2579
+ if (toleranceSince === 0) {
2580
+ bot._outOfSpreadToleranceSince = nowMs;
2581
+ return { staleMs: 0, escalated: false };
2582
+ }
2583
+ if (nowMs - toleranceSince < inToleranceResetMs)
2584
+ return { staleMs: 0, escalated: false };
2542
2585
  bot._outOfSpreadSince = 0;
2543
2586
  bot._outOfSpreadStaleWarned = false;
2544
2587
  bot._outOfSpreadTransientCount = 0;
2588
+ bot._outOfSpreadToleranceSince = 0;
2589
+ clearGeometryResyncMemory(bot);
2590
+ try {
2591
+ bot.manager._spreadRailOversubscribed = null;
2592
+ }
2593
+ catch { /* best-effort */ }
2545
2594
  return { staleMs: 0, escalated: false };
2546
2595
  }
2596
+ bot._outOfSpreadToleranceSince = 0;
2547
2597
  if (!spreadChecked) {
2548
2598
  const since = Number(bot._outOfSpreadSince) || 0;
2549
2599
  return { staleMs: since > 0 ? Date.now() - since : 0, escalated: false };
@@ -2579,13 +2629,63 @@ export function trackOutOfSpreadStaleness(bot, spreadChecked, ordersPlaced, tran
2579
2629
  const warnMs = Number(TIMING?.SPREAD_STALE_WARN_MS) > 0
2580
2630
  ? Number(TIMING.SPREAD_STALE_WARN_MS)
2581
2631
  : 10 * 60 * 1000;
2582
- const escalateMs = Number(TIMING?.SPREAD_STALE_ESCALATE_MS) > 0
2583
- ? Number(TIMING.SPREAD_STALE_ESCALATE_MS)
2584
- : 30 * 60 * 1000;
2632
+ // An oversubscribed rail is a fund-structure stall, not "wait for a fill":
2633
+ // escalate on the short fund window so the side is not dead for half an hour.
2634
+ const railOversubscribed = bot.manager?._spreadRailOversubscribed;
2635
+ const oversubscribedFresh = !!railOversubscribed && typeof railOversubscribed === 'object'
2636
+ && (now - Number(railOversubscribed.at || 0)) < 5 * 60 * 1000;
2637
+ const fundEscalateMs = Number(TIMING?.SPREAD_STALE_FUND_ESCALATE_MS) > 0
2638
+ ? Number(TIMING.SPREAD_STALE_FUND_ESCALATE_MS)
2639
+ : 5 * 60 * 1000;
2640
+ // The geometry bind has its own (longer than funds, shorter than structural)
2641
+ // window: the window is behind the last fill, which a re-center repairs by
2642
+ // re-deriving the center AROUND that same fill. Capped at ONE re-center per
2643
+ // pivot value: the re-center does not move the pivot, so a second attempt on
2644
+ // the same fill re-derives the same veto (the pivot can sit outside the new
2645
+ // grid's placeable side when the market has moved far away) and would only
2646
+ // cancel/re-place the new generation every cooldown. Until a fill refreshes
2647
+ // the pivot (or it expires), the honest repair is a fill — so report once
2648
+ // and stop.
2649
+ const geometryBlocked = bot._spreadCorrectionStall === 'last-fill-blocked';
2650
+ let geometryPivotKey = '';
2651
+ if (geometryBlocked) {
2652
+ try {
2653
+ const ref = resolveLastFillGuardReference(bot.manager);
2654
+ if (ref?.price != null && Number.isFinite(Number(ref.price)))
2655
+ geometryPivotKey = `${Number(ref.price)}|${String(ref.type ?? '')}`;
2656
+ }
2657
+ catch {
2658
+ geometryPivotKey = '';
2659
+ }
2660
+ }
2661
+ const geometryAlreadyRecentered = geometryBlocked && !!geometryPivotKey
2662
+ && bot._lastGeometryResyncPivotKey === geometryPivotKey;
2663
+ const geometryEscalateMs = Number(TIMING?.SPREAD_STALE_GEOMETRY_ESCALATE_MS) > 0
2664
+ ? Number(TIMING.SPREAD_STALE_GEOMETRY_ESCALATE_MS)
2665
+ : 10 * 60 * 1000;
2666
+ const escalateMs = oversubscribedFresh
2667
+ ? fundEscalateMs
2668
+ : geometryAlreadyRecentered
2669
+ // Do not re-center again for the same fill. Out of the escalation
2670
+ // ladder entirely: a fill (or the pivot TTL) is the only heal.
2671
+ ? Number.POSITIVE_INFINITY
2672
+ : geometryBlocked
2673
+ ? geometryEscalateMs
2674
+ : (Number(TIMING?.SPREAD_STALE_ESCALATE_MS) > 0
2675
+ ? Number(TIMING.SPREAD_STALE_ESCALATE_MS)
2676
+ : 30 * 60 * 1000);
2677
+ if (geometryAlreadyRecentered && staleMs >= warnMs && bot._geometryResyncWarnedPivotKey !== geometryPivotKey) {
2678
+ bot._geometryResyncWarnedPivotKey = geometryPivotKey;
2679
+ bot._log(`[SPREAD-STALE] Still out of tolerance ${staleMin}min after re-centering on fill pivot ` +
2680
+ `${geometryPivotKey.split('|')[0]}: the pivot is outside this generation's placeable side, so a re-center ` +
2681
+ `cannot clear it. A fill (buy back below / sell above the pivot) or pivot expiry restores the side; ` +
2682
+ `no further re-center will be requested for this pivot.`, 'warn');
2683
+ }
2585
2684
  if (staleMs >= warnMs && !bot._outOfSpreadStaleWarned) {
2586
2685
  bot._outOfSpreadStaleWarned = true;
2686
+ const stall = bot._spreadCorrectionStall ? `, stall=${bot._spreadCorrectionStall}` : '';
2587
2687
  bot._log(`[SPREAD-STALE] Spread out of tolerance for ${staleMin}min with no correction placed ` +
2588
- `(outOfSpread=${outOfSpread}); structural re-center follows if unhealed`, 'warn');
2688
+ `(outOfSpread=${outOfSpread}${stall}); structural re-center follows if unhealed`, 'warn');
2589
2689
  }
2590
2690
  if (staleMs >= escalateMs && typeof bot.manager?.requestStructuralGridResync === 'function') {
2591
2691
  // Dedicated spread-stale cooldown (NOT BOUNDARY_HOLD_RESYNC_COOLDOWN_MS:
@@ -2600,7 +2700,12 @@ export function trackOutOfSpreadStaleness(bot, spreadChecked, ordersPlaced, tran
2600
2700
  const lastAt = Number(bot._lastSpreadStaleResyncAt) || 0;
2601
2701
  if (now - lastAt >= cooldownMs) {
2602
2702
  bot._lastSpreadStaleResyncAt = now;
2603
- bot._log(`[SPREAD-STALE] Spread out of tolerance for ${staleMin}min despite corrections; ` +
2703
+ if (geometryBlocked && geometryPivotKey)
2704
+ bot._lastGeometryResyncPivotKey = geometryPivotKey;
2705
+ bot._log(`[SPREAD-STALE] Spread out of tolerance for ${staleMin}min despite corrections` +
2706
+ `${oversubscribedFresh ? ' (rail oversubscribed — re-sizing from chain truth)' : ''}` +
2707
+ `${geometryBlocked ? ' (sell window behind the last fill — re-centering)' : ''}` +
2708
+ `${bot._spreadCorrectionStall ? ` (stall=${bot._spreadCorrectionStall})` : ''}; ` +
2604
2709
  `requesting structural re-center`, 'warn');
2605
2710
  fireStructuralResync(bot, 'spread-stale-persistent', {
2606
2711
  reason: `Spread out of tolerance for ${staleMin}min with no effective correction (outOfSpread=${outOfSpread})`
@@ -616,7 +616,13 @@ async function finishStartupSequence(bot, startupState) {
616
616
  }
617
617
  else {
618
618
  bot._log('Found active session. Loading and syncing existing grid.');
619
- await botGridModule(bot).loadGrid(bot.manager, persistedGrid, persistedBoundaryIdx, persistedGenesis);
619
+ // Pure in-band stranding is the transient SPREAD-GUARD /
620
+ // partial-fill-anchor state, not snapshot poison: the
621
+ // re-anchor deliberately leaves the fill's own PARTIAL
622
+ // residual inside the band until GAP-EVAC clears it.
623
+ // Keep the persisted boundary (warn + load) exactly like
624
+ // the recovery path; a rebuild here would undo the repair.
625
+ await botGridModule(bot).loadGrid(bot.manager, persistedGrid, persistedBoundaryIdx, persistedGenesis, { tolerateTransientStranding: true });
620
626
  // Phase 3 restart resilience: restore persisted gap-evacuation
621
627
  // streaks (pruned to surviving slots) so an order stranded
622
628
  // in-band across frequent restarts still reaches the cancel
@@ -40,8 +40,8 @@
40
40
  * 6. Log shutdown status
41
41
  * 7. Exit process
42
42
  *
43
- * USAGE:
44
- * const { registerCleanup } = require('./modules/graceful_shutdown');
43
+ * USAGE (from the repo root):
44
+ * import { registerCleanup } from './modules/graceful_shutdown.js';
45
45
  *
46
46
  * // Register cleanups (executed in reverse order on shutdown)
47
47
  * registerCleanup('Database', async () => db.close());
@@ -40,8 +40,8 @@
40
40
  * 6. Log shutdown status
41
41
  * 7. Exit process
42
42
  *
43
- * USAGE:
44
- * const { registerCleanup } = require('./modules/graceful_shutdown');
43
+ * USAGE (from the repo root):
44
+ * import { registerCleanup } from './modules/graceful_shutdown.js';
45
45
  *
46
46
  * // Register cleanups (executed in reverse order on shutdown)
47
47
  * registerCleanup('Database', async () => db.close());
@@ -1,5 +1,12 @@
1
+ import type { VaultSecret } from '../chain_keys.js';
1
2
  import type { StdioOptions } from 'child_process';
2
3
  declare const DEFAULT_POLL_INTERVAL_MS = 1000;
4
+ /**
5
+ * Best-effort wipe of a derived vault secret held in memory.
6
+ * Vault secrets are plain objects with hex-string fields; V8 cannot zero an
7
+ * immutable string in place, so drop each value and let GC reclaim it.
8
+ */
9
+ declare function clearVaultSecret(secret: VaultSecret | null | undefined): void;
3
10
  declare function waitForExit(child: import('node:child_process').ChildProcess): Promise<number | null>;
4
11
  declare function createCredentialDaemonController({ root, codeRoot, socketPath, readyFilePath, pollIntervalMs, }?: {
5
12
  root?: string | undefined;
@@ -8,11 +15,16 @@ declare function createCredentialDaemonController({ root, codeRoot, socketPath,
8
15
  readyFilePath?: string | undefined;
9
16
  pollIntervalMs?: number | undefined;
10
17
  }): {
11
- ensureCredentialDaemon: ({ detached, stdio: stdioOption, headless, passwordFile }?: {
18
+ authenticateCredential: ({ headless, passwordFile }?: {
19
+ headless?: boolean;
20
+ passwordFile?: string | null;
21
+ }) => Promise<VaultSecret>;
22
+ ensureCredentialDaemon: ({ detached, stdio: stdioOption, headless, passwordFile, vaultSecret: preAuthenticatedSecret }?: {
12
23
  detached?: boolean;
13
24
  stdio?: StdioOptions;
14
25
  headless?: boolean;
15
26
  passwordFile?: string | null;
27
+ vaultSecret?: VaultSecret | null;
16
28
  }) => Promise<boolean>;
17
29
  forwardSignal: (signal: string) => void;
18
30
  getManagedDaemonPid: () => number | null;
@@ -21,5 +33,5 @@ declare function createCredentialDaemonController({ root, codeRoot, socketPath,
21
33
  stopManagedDaemon: () => Promise<void>;
22
34
  waitForManagedDaemon: () => Promise<number | null>;
23
35
  };
24
- export { createCredentialDaemonController, DEFAULT_POLL_INTERVAL_MS, waitForExit };
36
+ export { createCredentialDaemonController, clearVaultSecret, DEFAULT_POLL_INTERVAL_MS, waitForExit };
25
37
  //# sourceMappingURL=credential_daemon.d.ts.map
@@ -17,6 +17,22 @@ import { assertPrivatePathSecurity, ensureCredentialRuntimeDirSync, getCredentia
17
17
  import { buildRuntimeScriptArgs, SCRIPTS_ROOT as DEFAULT_CODE_ROOT } from './runtime_entry.js';
18
18
  import { getErrorMessage, getErrorCode } from '../utils/errors.js';
19
19
  const DEFAULT_POLL_INTERVAL_MS = 1000;
20
+ /**
21
+ * Best-effort wipe of a derived vault secret held in memory.
22
+ * Vault secrets are plain objects with hex-string fields; V8 cannot zero an
23
+ * immutable string in place, so drop each value and let GC reclaim it.
24
+ */
25
+ function clearVaultSecret(secret) {
26
+ if (!secret || typeof secret !== 'object')
27
+ return;
28
+ const record = secret;
29
+ for (const key of Object.keys(record)) {
30
+ const value = record[key];
31
+ if (Buffer.isBuffer(value))
32
+ value.fill(0);
33
+ record[key] = null;
34
+ }
35
+ }
20
36
  function waitForExit(child) {
21
37
  return new Promise((resolve, reject) => {
22
38
  child.on('error', reject);
@@ -63,37 +79,46 @@ function createCredentialDaemonController({ root = PATHS.PROJECT_ROOT, codeRoot
63
79
  throw err;
64
80
  }
65
81
  }
66
- async function ensureCredentialDaemon({ detached = false, stdio: stdioOption = undefined, headless = false, passwordFile = null } = {}) {
82
+ async function authenticateCredential({ headless = false, passwordFile = null } = {}) {
83
+ if (headless) {
84
+ return chainKeys.unlockWithPassword(readHeadlessPassword({ passwordFile }));
85
+ }
86
+ return chainKeys.authenticate();
87
+ }
88
+ /**
89
+ * Ensure a responsive credential daemon, starting one when needed.
90
+ * A caller-supplied `vaultSecret` is consumed: the launcher-side reference
91
+ * is cleared once the secret has been handed off (or startup fails), so
92
+ * callers must not reuse the object after this returns.
93
+ */
94
+ async function ensureCredentialDaemon({ detached = false, stdio: stdioOption = undefined, headless = false, passwordFile = null, vaultSecret: preAuthenticatedSecret = null } = {}) {
67
95
  if (await isDaemonReady()) {
68
96
  return false;
69
97
  }
70
98
  await removeStaleDaemonFiles();
71
99
  ensureCredentialRuntimeDirSync();
72
100
  credentialPolicy.ensurePolicyConfig(PATHS.PROFILES.DAEMON_POLICIES_JSON);
73
- let vaultSecret;
74
- if (headless) {
75
- vaultSecret = chainKeys.unlockWithPassword(readHeadlessPassword({ passwordFile }));
76
- }
77
- else {
78
- vaultSecret = await chainKeys.authenticate();
79
- }
80
- const bootstrap = await createPasswordBootstrapServer({ secret: vaultSecret });
81
- const daemonArgs = buildRuntimeScriptArgs({
82
- codeRoot,
83
- scriptSegments: ['credential-daemon'],
84
- });
85
- // Write the bootstrap socket path to a stable file in the runtime dir
86
- // so the credential daemon can find it via DEXBOT_CRED_BOOTSTRAP_PATH_FILE
87
- // instead of a PM2-persistable env var.
88
- const bootstrapPathFile = path.join(path.dirname(socketPath), '.dexbot-cred-bootstrap-path');
89
- try {
90
- storage.writeFile(bootstrapPathFile, bootstrap.socketPath, { mode: 0o600 });
91
- }
92
- catch (err) {
93
- bootstrap.close();
94
- throw new Error(`Cannot write bootstrap path file at ${bootstrapPathFile}: ${getErrorMessage(err)}`);
95
- }
101
+ // A caller that verified the master password up front can hand the
102
+ // secret in, so the daemon restart never has to re-prompt (and can
103
+ // never kill a healthy daemon before the password is known good).
104
+ const vaultSecret = preAuthenticatedSecret ?? await authenticateCredential({ headless, passwordFile });
105
+ let bootstrap = null;
96
106
  try {
107
+ bootstrap = await createPasswordBootstrapServer({ secret: vaultSecret });
108
+ const daemonArgs = buildRuntimeScriptArgs({
109
+ codeRoot,
110
+ scriptSegments: ['credential-daemon'],
111
+ });
112
+ // Write the bootstrap socket path to a stable file in the runtime dir
113
+ // so the credential daemon can find it via DEXBOT_CRED_BOOTSTRAP_PATH_FILE
114
+ // instead of a PM2-persistable env var.
115
+ const bootstrapPathFile = path.join(path.dirname(socketPath), '.dexbot-cred-bootstrap-path');
116
+ try {
117
+ storage.writeFile(bootstrapPathFile, bootstrap.socketPath, { mode: 0o600 });
118
+ }
119
+ catch (err) {
120
+ throw new Error(`Cannot write bootstrap path file at ${bootstrapPathFile}: ${getErrorMessage(err)}`);
121
+ }
97
122
  const childStdio = stdioOption ?? (detached ? 'ignore' : 'inherit');
98
123
  daemonProcess = spawn(Config.EXEC_PATH, daemonArgs, {
99
124
  cwd: root,
@@ -130,9 +155,17 @@ function createCredentialDaemonController({ root = PATHS.PROJECT_ROOT, codeRoot
130
155
  return true;
131
156
  }
132
157
  catch (error) {
133
- bootstrap.close();
158
+ bootstrap?.close();
134
159
  throw error;
135
160
  }
161
+ finally {
162
+ // The secret has been transferred over the one-shot bootstrap
163
+ // socket (or startup failed). Drop the launcher-side material as
164
+ // soon as it is no longer needed. Hex strings cannot be zeroed in
165
+ // place in V8, but clearing the properties lets the values be
166
+ // reclaimed with the object.
167
+ clearVaultSecret(vaultSecret);
168
+ }
136
169
  }
137
170
  function getManagedDaemonPid() {
138
171
  return daemonProcess && daemonProcess.pid ? daemonProcess.pid : null;
@@ -164,6 +197,7 @@ function createCredentialDaemonController({ root = PATHS.PROJECT_ROOT, codeRoot
164
197
  return 0;
165
198
  }
166
199
  return {
200
+ authenticateCredential,
167
201
  ensureCredentialDaemon,
168
202
  forwardSignal,
169
203
  getManagedDaemonPid,
@@ -173,5 +207,5 @@ function createCredentialDaemonController({ root = PATHS.PROJECT_ROOT, codeRoot
173
207
  waitForManagedDaemon,
174
208
  };
175
209
  }
176
- export { createCredentialDaemonController, DEFAULT_POLL_INTERVAL_MS, waitForExit };
210
+ export { createCredentialDaemonController, clearVaultSecret, DEFAULT_POLL_INTERVAL_MS, waitForExit };
177
211
  //# sourceMappingURL=credential_daemon.js.map
@@ -1,4 +1,4 @@
1
- export type RuntimeMode = 'monolithic' | 'isolated' | 'pm2' | 'none';
1
+ type RuntimeMode = 'monolithic' | 'isolated' | 'pm2' | 'none';
2
2
  export interface Pm2Proc {
3
3
  pid?: number | string;
4
4
  name?: string;
@@ -28,7 +28,7 @@ export interface RuntimeInfo {
28
28
  }
29
29
  /** True when `name` matches a configured bot (case-insensitive). */
30
30
  export declare function isConfiguredBotName(name: string): boolean;
31
- export interface StatusTargetCheck {
31
+ interface StatusTargetCheck {
32
32
  error: string | null;
33
33
  notice: string | null;
34
34
  }
@@ -38,7 +38,7 @@ export interface StatusTargetCheck {
38
38
  * one is rejected — the same contract the unlock control path applies.
39
39
  */
40
40
  export declare function checkStatusTarget(target?: string | null): StatusTargetCheck;
41
- export type StatusRoute = 'unlock' | 'pm2' | 'empty';
41
+ type StatusRoute = 'unlock' | 'pm2' | 'empty';
42
42
  /**
43
43
  * Which branch `dexbot status` takes. PM2 wins when PM2 bots are running (even
44
44
  * if a stray credential daemon lingers) so the report and the help banner name
@@ -76,4 +76,5 @@ export interface RuntimeHelpEntry {
76
76
  * so the reference is always complete before anything is running.
77
77
  */
78
78
  export declare function runtimeControlHelp(mode: RuntimeMode): RuntimeHelpEntry[];
79
+ export {};
79
80
  //# sourceMappingURL=runtime_mode.d.ts.map
@@ -30,7 +30,7 @@
30
30
  *
31
31
  * In bitshares_client.ts:
32
32
  *
33
- * const NodeManager = require('./node_manager').default;
33
+ * import NodeManager from './node_manager.js';
34
34
  * const nodeManager = new NodeManager(config);
35
35
  * await nodeManager.checkAllNodes();
36
36
  * const bestNode = nodeManager.getBestNode();
@@ -30,7 +30,7 @@
30
30
  *
31
31
  * In bitshares_client.ts:
32
32
  *
33
- * const NodeManager = require('./node_manager').default;
33
+ * import NodeManager from './node_manager.js';
34
34
  * const nodeManager = new NodeManager(config);
35
35
  * await nodeManager.checkAllNodes();
36
36
  * const bestNode = nodeManager.getBestNode();
@@ -88,7 +88,8 @@ import { createRequire } from 'node:module';
88
88
  const require = createRequire(import.meta.url);
89
89
  import { ORDER_TYPES, ORDER_STATES, PIPELINE_TIMING, TIMING, FEE_PARAMETERS, GRID_LIMITS } from '../constants.js';
90
90
  import { resolveAccountRef } from './utils/system.js';
91
- import { resolveSpreadOrderSide, parseSlotIndex, parseChainOrder, applyChainSizeToGridOrder, convertToSpreadPlaceholder, resolveEdgeCount } from './utils/order.js';
91
+ import { resolveSpreadOrderSide, parseChainOrder, applyChainSizeToGridOrder, convertToSpreadPlaceholder, resolveEdgeCount } from './utils/order.js';
92
+ import { parseSlotIndex } from './utils/slot.js';
92
93
  import { isSlotInRail, floatToBlockchainInt } from './utils/math.js';
93
94
  import * as Format from './format.js';
94
95
  import * as fundRegistry from '../fund_registry.js';
@@ -4,8 +4,8 @@
4
4
  * Trading history extraction and CSV export engine.
5
5
  * Parses PM2 log files to extract trading fills and exports to standardized format.
6
6
  *
7
- * Usage:
8
- * const exporter = require('./order/export');
7
+ * Usage (from the repo root):
8
+ * import * as exporter from './modules/order/export.js';
9
9
  * const result = await exporter.exportBotTrades(botKey, botConfig, outputDir);
10
10
  *
11
11
  * Output Format:
@@ -4,8 +4,8 @@
4
4
  * Trading history extraction and CSV export engine.
5
5
  * Parses PM2 log files to extract trading fills and exports to standardized format.
6
6
  *
7
- * Usage:
8
- * const exporter = require('./order/export');
7
+ * Usage (from the repo root):
8
+ * import * as exporter from './modules/order/export.js';
9
9
  * const result = await exporter.exportBotTrades(botKey, botConfig, outputDir);
10
10
  *
11
11
  * Output Format:
@@ -103,18 +103,35 @@
103
103
  *
104
104
  * ===============================================================================
105
105
  */
106
+ interface SpreadCorrectionRotation {
107
+ id: string;
108
+ orderId: string;
109
+ oldOrder: ManagedOrder;
110
+ newGridId: string;
111
+ newPrice: number;
112
+ newSize: number;
113
+ type: OrderType;
114
+ }
106
115
  interface SpreadCorrection {
107
116
  ordersToPlace: ManagedOrder[];
108
117
  ordersToUpdate: Array<{
109
118
  partialOrder: ManagedOrder;
110
119
  newSize: number;
111
120
  }>;
121
+ ordersToRotate?: SpreadCorrectionRotation[];
112
122
  plannedCount?: number;
113
123
  stallHint?: SpreadCorrectionStall;
114
124
  boundaryIdx?: number;
115
125
  origin?: string;
116
126
  [key: string]: unknown;
117
127
  }
128
+ /**
129
+ * Merge two side stalls so the starvation fallback cannot mask a named cause.
130
+ * 'unfunded' stays top (a refresh may repair it); 'unmatched-orders' next (a
131
+ * sync repairs it); then the geometry bind; readiness causes; 'no-candidates'
132
+ * is the floor. Exported for tests.
133
+ */
134
+ export declare function mergeSpreadStalls(a: SpreadCorrectionStall | undefined, b: SpreadCorrectionStall | undefined): SpreadCorrectionStall;
118
135
  /**
119
136
  * Spread-correction refusal causes — the single vocabulary shared by
120
137
  * classifySpreadRefusalCause, the retry/transience decision and the
@@ -138,7 +155,7 @@ export declare const SPREAD_CORRECTION_REFUSAL: Readonly<{
138
155
  /** Unclassified non-execution (fallback). */
139
156
  readonly BATCH_NOT_EXECUTED: "batch-not-executed";
140
157
  }>;
141
- export type SpreadCorrectionRefusalCause = (typeof SPREAD_CORRECTION_REFUSAL)[keyof typeof SPREAD_CORRECTION_REFUSAL];
158
+ type SpreadCorrectionRefusalCause = (typeof SPREAD_CORRECTION_REFUSAL)[keyof typeof SPREAD_CORRECTION_REFUSAL];
142
159
  /**
143
160
  * Whether a refusal cause is retryable by the bounded spread-correction re-plan.
144
161
  * @param {string} cause - A SPREAD_CORRECTION_REFUSAL value
@@ -162,13 +179,6 @@ export declare function classifySpreadRefusalCause(batchResult: unknown): Spread
162
179
  * @param {string} cause - A SPREAD_CORRECTION_REFUSAL value
163
180
  */
164
181
  export declare function recordSpreadCorrectionRefusal(manager: OrderManagerLike, cause: SpreadCorrectionRefusalCause): void;
165
- /**
166
- * P5 observability: count a bounded spread-correction re-plan retry. Churn
167
- * signal — a rising retry rate means concurrent commits are repeatedly
168
- * invalidating corrections. Counter-only; never throws.
169
- * @param {Object} manager - OrderManager instance
170
- */
171
- export declare function recordSpreadCorrectionRetry(manager: OrderManagerLike): void;
172
182
  /**
173
183
  * P2 plan-time dedupe: which of a correction's planned CREATE destinations are
174
184
  * now occupied by a live (ACTIVE/PARTIAL) order with a chain id?
@@ -189,11 +199,12 @@ export declare function getOccupiedCorrectionSlots(manager: OrderManagerLike, co
189
199
  /**
190
200
  * P1/P3 shared re-plan: derive a spread correction from the CURRENT master
191
201
  * state (side chosen from fresh on-chain book, opposite-side starvation
192
- * fallback). Used both for the plan-time collision dedupe and the bounded
193
- * refusal retry. Read-only against the grid; no _gridLock needed (matches the
194
- * existing TOCTOU fund re-plan contract).
202
+ * fallback). A zero-free decision still tries the rotation-only fallback.
203
+ * Used both for the plan-time collision dedupe and the bounded refusal retry.
204
+ * Read-only against the grid; no _gridLock needed (matches the existing TOCTOU
205
+ * fund re-plan contract).
195
206
  * @param {Object} manager - OrderManager instance
196
- * @returns {Promise<Object|null>} A correction with at least one create, or null
207
+ * @returns {Promise<Object|null>} A correction with at least one executable action, or null
197
208
  */
198
209
  export declare function replanSpreadCorrectionFromFreshMaster(manager: OrderManagerLike): Promise<SpreadCorrection | null>;
199
210
  /**
@@ -202,7 +213,7 @@ export declare function replanSpreadCorrectionFromFreshMaster(manager: OrderMana
202
213
  * - 'replanned': a destination was taken and a fresh correction was derived.
203
214
  * - 'blocked': a destination was taken and no fresh correction exists — refuse.
204
215
  */
205
- export type OccupiedCorrectionResolution = {
216
+ type OccupiedCorrectionResolution = {
206
217
  action: 'broadcast';
207
218
  } | {
208
219
  action: 'replanned';
@@ -689,11 +700,12 @@ export declare function getDustOrders(manager: OrderManagerLike, partials: Manag
689
700
  * @param {import('./types').OrderManager} manager - The manager instance.
690
701
  * @param {number} currentMarketPrice - Last traded price in B/A format (e.g. BTS/XRP), used to
691
702
  * normalize sell-side funds into buy-side units for a fair cross-asset comparison.
692
- * @returns {{ side: import('./types').OrderType|null, reason: string }} The side to correct on, or null if insufficient funds.
703
+ * @returns {{ side: import('./types').OrderType|null, reason: string, code?: 'market-price-unavailable'|'no-free-funds' }} The side to correct on, or null with a structured cause.
693
704
  */
694
705
  export declare function determineOrderSideByFunds(manager: OrderManagerLike, currentMarketPrice: number): {
695
706
  side: OrderType | null;
696
707
  reason: string;
708
+ code?: 'market-price-unavailable' | 'no-free-funds';
697
709
  };
698
710
  /**
699
711
  * Prepares one or more orders to correct a wide spread.