dexbot 1.6.17 → 1.7.0

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 (156) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/README.md +24 -18
  3. package/analysis/README.md +105 -12
  4. package/analysis/ama_fitting/README.md +2 -2
  5. package/analysis/bot_fitting/README.md +3 -3
  6. package/claw/package.json +1 -1
  7. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  8. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  9. package/dist/analysis/analyze_args.d.ts +2 -1
  10. package/dist/analysis/analyze_dynamic_weight.js +2 -1
  11. package/dist/analysis/analyze_kalman.js +3 -2
  12. package/dist/analysis/analyze_liquidity.d.ts +17 -0
  13. package/dist/analysis/analyze_liquidity.js +325 -0
  14. package/dist/analysis/analyze_regime.js +3 -2
  15. package/dist/analysis/analyze_regime_windows.js +3 -2
  16. package/dist/analysis/analyze_volatility.js +3 -2
  17. package/dist/analysis/fills_source.d.ts +1 -8
  18. package/dist/analysis/fills_source.js +1 -1
  19. package/dist/analysis/grid_correction_check.d.ts +9 -6
  20. package/dist/analysis/grid_correction_check.js +56 -64
  21. package/dist/analysis/liquidity/liquidity_chain.d.ts +66 -0
  22. package/dist/analysis/liquidity/liquidity_chain.js +178 -0
  23. package/dist/analysis/liquidity/liquidity_chart_generator.d.ts +19 -0
  24. package/dist/analysis/liquidity/liquidity_chart_generator.js +523 -0
  25. package/dist/analysis/liquidity/liquidity_depth_model.d.ts +141 -0
  26. package/dist/analysis/liquidity/liquidity_depth_model.js +230 -0
  27. package/dist/analysis/liquidity/liquidity_view.d.ts +38 -0
  28. package/dist/analysis/liquidity/liquidity_view.js +55 -0
  29. package/dist/analysis/math_utils.d.ts +1 -1
  30. package/dist/analysis/trade_profitability.d.ts +1 -1
  31. package/dist/analysis/trade_profitability.js +2 -1
  32. package/dist/analysis/tradingview/analyze_tradingview.js +2 -1
  33. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +3 -3
  34. package/dist/analysis/trend_detection/huber_scale_variants.d.ts +4 -3
  35. package/dist/dexbot.js +74 -169
  36. package/dist/market_adapter/cli_args.d.ts +6 -1
  37. package/dist/market_adapter/cli_args.js +16 -2
  38. package/dist/market_adapter/core/kibana_candles.d.ts +5 -1
  39. package/dist/market_adapter/core/kibana_candles.js +3 -1
  40. package/dist/market_adapter/core/strategies/regime_gate.d.ts +7 -1
  41. package/dist/market_adapter/core/strategies/regime_gate.js +3 -1
  42. package/dist/market_adapter/inputs/cex_candle_parsing.d.ts +7 -2
  43. package/dist/market_adapter/inputs/cex_candle_parsing.js +3 -1
  44. package/dist/market_adapter/inputs/fetch_book_data.d.ts +7 -1
  45. package/dist/market_adapter/inputs/fetch_book_data.js +3 -1
  46. package/dist/market_adapter/inputs/fetch_cex_synthetic_data.js +2 -11
  47. package/dist/market_adapter/inputs/fetch_lp_data.d.ts +26 -1
  48. package/dist/market_adapter/inputs/fetch_lp_data.js +62 -52
  49. package/dist/market_adapter/inputs/kibana_feed_source.d.ts +14 -2
  50. package/dist/market_adapter/inputs/kibana_feed_source.js +14 -1
  51. package/dist/market_adapter/inputs/window_cache.d.ts +14 -3
  52. package/dist/market_adapter/inputs/window_cache.js +14 -1
  53. package/dist/market_adapter/lp_chart_runner.d.ts +12 -9
  54. package/dist/market_adapter/lp_chart_runner.js +3 -1
  55. package/dist/market_adapter/lp_chart_strategy_loader.d.ts +5 -1
  56. package/dist/market_adapter/lp_chart_strategy_loader.js +3 -1
  57. package/dist/market_adapter/market_adapter.d.ts +10 -2
  58. package/dist/market_adapter/market_adapter.js +10 -11
  59. package/dist/market_adapter/utils/chain.d.ts +2 -3
  60. package/dist/market_adapter/utils/file_json_cache.d.ts +5 -1
  61. package/dist/market_adapter/utils/file_json_cache.js +3 -1
  62. package/dist/market_adapter/utils/file_lock.js +1 -1
  63. package/dist/market_adapter/utils/native_history.d.ts +7 -3
  64. package/dist/market_adapter/utils/native_history.js +3 -1
  65. package/dist/market_adapter/utils/pair_orientation.d.ts +2 -2
  66. package/dist/modules/asset_lookup.d.ts +25 -0
  67. package/dist/modules/asset_lookup.js +75 -0
  68. package/dist/modules/bots_file_lock.d.ts +2 -2
  69. package/dist/modules/bots_file_lock.js +2 -2
  70. package/dist/modules/chain_scan.d.ts +64 -0
  71. package/dist/modules/chain_scan.js +80 -0
  72. package/dist/modules/cli_colors.d.ts +5 -0
  73. package/dist/modules/cli_colors.js +7 -0
  74. package/dist/modules/cli_progress.d.ts +51 -0
  75. package/dist/modules/cli_progress.js +113 -0
  76. package/dist/modules/constants.js +6 -3
  77. package/dist/modules/dexbot_class.d.ts +8 -0
  78. package/dist/modules/dexbot_class.js +10 -0
  79. package/dist/modules/dexbot_cow_runtime.d.ts +62 -1
  80. package/dist/modules/dexbot_cow_runtime.js +475 -47
  81. package/dist/modules/dexbot_credential_client.d.ts +5 -0
  82. package/dist/modules/dexbot_fill_runtime.js +20 -0
  83. package/dist/modules/dexbot_maintenance_runtime.js +71 -9
  84. package/dist/modules/dexbot_startup_runtime.js +7 -1
  85. package/dist/modules/graceful_shutdown.d.ts +2 -2
  86. package/dist/modules/graceful_shutdown.js +2 -2
  87. package/dist/modules/launcher/runtime_entry.d.ts +21 -1
  88. package/dist/modules/launcher/runtime_entry.js +36 -1
  89. package/dist/modules/launcher/runtime_mode.d.ts +4 -3
  90. package/dist/modules/liquidity_pool_ref.d.ts +32 -0
  91. package/dist/modules/liquidity_pool_ref.js +116 -0
  92. package/dist/modules/node_manager.d.ts +1 -1
  93. package/dist/modules/node_manager.js +1 -1
  94. package/dist/modules/order/accounting.js +2 -1
  95. package/dist/modules/order/export.d.ts +2 -2
  96. package/dist/modules/order/export.js +2 -2
  97. package/dist/modules/order/grid.d.ts +19 -14
  98. package/dist/modules/order/grid.js +269 -61
  99. package/dist/modules/order/grid_reconcile.js +27 -2
  100. package/dist/modules/order/grid_reconcile_internal.js +94 -15
  101. package/dist/modules/order/index.d.ts +24 -4
  102. package/dist/modules/order/manager.d.ts +12 -0
  103. package/dist/modules/order/manager.js +44 -11
  104. package/dist/modules/order/strategy.js +22 -2
  105. package/dist/modules/order/sync_engine.d.ts +32 -1
  106. package/dist/modules/order/sync_engine.js +209 -26
  107. package/dist/modules/order/utils/math.d.ts +26 -10
  108. package/dist/modules/order/utils/math.js +54 -14
  109. package/dist/modules/order/utils/order.d.ts +158 -11
  110. package/dist/modules/order/utils/order.js +434 -21
  111. package/dist/modules/order/utils/system.d.ts +136 -30
  112. package/dist/modules/order/utils/system.js +465 -63
  113. package/dist/modules/order/utils/validate.d.ts +1 -0
  114. package/dist/modules/order/utils/validate.js +37 -3
  115. package/dist/modules/storage/index.d.ts +3 -2
  116. package/dist/modules/storage/index.js +3 -2
  117. package/dist/modules/types.d.ts +14 -0
  118. package/dist/modules/utils/asset_symbols.d.ts +13 -2
  119. package/dist/modules/utils/asset_symbols.js +21 -2
  120. package/dist/scripts/analysis_runner.d.ts +10 -0
  121. package/dist/scripts/analysis_runner.js +33 -0
  122. package/dist/scripts/analyze-orders.js +2 -1
  123. package/dist/scripts/asset.d.ts +26 -0
  124. package/dist/scripts/asset.js +165 -0
  125. package/dist/scripts/bts_distribution.d.ts +1 -0
  126. package/dist/scripts/bts_distribution.js +194 -142
  127. package/dist/scripts/chart_command.d.ts +1 -1
  128. package/dist/scripts/chart_command.js +60 -86
  129. package/dist/scripts/chart_targets.d.ts +18 -0
  130. package/dist/scripts/chart_targets.js +52 -0
  131. package/dist/scripts/dw.js +1 -1
  132. package/dist/scripts/liquid.d.ts +24 -0
  133. package/dist/scripts/liquid.js +134 -0
  134. package/dist/scripts/rich_list.js +12 -16
  135. package/dist/scripts/token_distribution.d.ts +2 -0
  136. package/dist/scripts/token_distribution.js +132 -108
  137. package/dist/scripts/tv.js +1 -1
  138. package/dist/scripts/verify-browser-bundle.js +18 -0
  139. package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -1
  140. package/docs/COW_INVARIANTS.md +21 -11
  141. package/docs/DEXBOT_COMPARISON.md +6 -6
  142. package/docs/EVOLUTION.md +10 -8
  143. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +11 -11
  144. package/docs/GRID_PRICE_INVARIANT.md +28 -5
  145. package/docs/GRID_RECONCILE.md +25 -5
  146. package/docs/LIFECYCLE.md +11 -11
  147. package/docs/LOGGING.md +37 -2
  148. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +124 -36
  149. package/docs/README.md +1 -1
  150. package/docs/WORKFLOW.md +3 -1
  151. package/docs/architecture.md +115 -13
  152. package/docs/developer_guide.md +12 -0
  153. package/market_adapter/README.md +9 -4
  154. package/modules/README.md +23 -15
  155. package/package.json +6 -3
  156. package/scripts/README.md +23 -7
@@ -3,21 +3,31 @@
3
3
  /**
4
4
  * LAST-FILL-GUARD CHECK
5
5
  *
6
- * Validates LAST-FILL-GUARD discipline: pivot ± halfIncrement
7
- * Last fill @x with increment i (half=i/2) gates BOTH sides regardless of
8
- * last side — BUY must be < x*(1-half/100), SELL > x*(1+half/100).
9
- * e.g. x=1000, i=0.5% => BUY < 997.5 / SELL > 1002.5.
6
+ * Validates LAST-FILL-GUARD discipline — DIRECTION ONLY, relative to the last
7
+ * fill price (v1.6.16+, retrospective §9.7):
8
+ * BUY blocked if price >= pivot
9
+ * SELL blocked if price <= pivot
10
+ * e.g. pivot 1000 => BUY must be < 1000, SELL must be > 1000.
10
11
  * Cold start (no previous fill) is disabled.
11
- * Intentional offline gaps (documented, acceptable):
12
+ *
13
+ * The older rule judged against `pivot ± increment/2` and ignored the fill
14
+ * side, which blocked a BUY below a SELL fill and a SELL one tick above our
15
+ * cost — i.e. it reported the tightening placements the current engine
16
+ * legitimately makes as violations. Do not reintroduce an increment term here.
17
+ *
18
+ * Intentional offline gaps (documented, acceptable):
12
19
  * - Runtime pivots on _lastFilledPrice/_lastFilledType at decision time; tool
13
20
  * checks consecutive fill pairs. For batch-placed orders (multiple orders
14
21
  * guarded against the same pivot in one COW batch) this diverges — inherent
15
22
  * offline approximation.
16
23
  * - Spread-correction bypass (cowResult.origin === 'spread-correction') is
17
24
  * not simulated — every consecutive pair is checked.
25
+ * - EDGE-pinned insurance fills no longer arm the runtime pivot
26
+ * (recordLastFilledPrices skips them); this reconstruction has no slot
27
+ * identity for a fill, so it cannot classify edge fills and will still
28
+ * judge the pair after one. Expect rare false positives on wick fills.
18
29
  *
19
- * Mirrors modules/dexbot_cow_runtime.ts:isLastFillGuardBlocked 1:1 and
20
- * modules/constants.ts:DEFAULT_CONFIG.incrementPercent fallback (0.5).
30
+ * Mirrors modules/order/utils/system.ts:isLastFillGuardBlocked 1:1.
21
31
  *
22
32
  * Fetches fill_order operations from Kibana (same pipeline as
23
33
  * trade_profitability.ts) and checks for last-fill guard violations.
@@ -41,41 +51,32 @@ import { resolveBotAccount } from './account_resolver.js';
41
51
  import { classifyFill, assetSymbol, fetchAllFills, resolveAssetPrecisions, } from './fills_source.js';
42
52
  const { kibanaSearch, DEFAULT_CONFIG: BASE_CONFIG } = KC;
43
53
  const OP_LIMIT_ORDER_UPDATE = 77;
44
- // ─── LAST-FILL-GUARD helper (1:1 with dexbot_cow_runtime.ts) ─────────────────
54
+ // ─── LAST-FILL-GUARD helper (1:1 with modules/order/utils/system.ts) ────────────
45
55
  /**
46
- * LAST-FILL-GUARD helper — pivot ± halfIncrement (replaces price-tolerance).
47
- * last fill @x with increment i: BUY < x*(1 - i/2/100), SELL > x*(1 + i/2/100)
48
- * e.g. x=1000, i=0.5% => BUY < 997.5, SELL > 1002.5
49
- * Cold (pivot null or lastType null) => disabled.
56
+ * LAST-FILL-GUARD helper — DIRECTION ONLY relative to the last fill price.
57
+ * BUY blocked if price >= pivot
58
+ * SELL blocked if price <= pivot
59
+ * e.g. pivot 1000 => BUY must be < 1000, SELL must be > 1000
60
+ * Cold (pivot null or lastType null) => disabled. Equal price stays blocked
61
+ * (a re-place at the just-filled level).
50
62
  * @param {number} price - Target order price
51
63
  * @param {string} type - buy/sell
52
64
  * @param {number|null} lastPrice - Most recent fill price
53
65
  * @param {string|null} lastType - Most recent fill side (buy/sell)
54
- * @param {number|any} incrementPercent - Grid increment percent (e.g. 0.5). If not finite/<=0 falls back to DEFAULT_CONFIG.
55
66
  * @returns {{blocked: boolean, pivot: number|null, halfInc: number, threshold: number|null}}
56
67
  */
57
- function isLastFillGuardBlocked(price, type, lastPrice, lastType, incrementPercent) {
68
+ function isLastFillGuardBlocked(price, type, lastPrice, lastType) {
58
69
  const numPrice = Number(price);
59
70
  if (!Number.isFinite(numPrice))
60
71
  return { blocked: false, pivot: null };
61
72
  if (lastPrice == null || !Number.isFinite(Number(lastPrice)) || lastType == null)
62
73
  return { blocked: false, pivot: null };
63
74
  const pivot = Number(lastPrice);
64
- let inc = Number(incrementPercent);
65
- if (!Number.isFinite(inc) || inc <= 0) {
66
- inc = Number(C.DEFAULT_CONFIG?.incrementPercent ?? 0.5);
67
- }
68
- if (!Number.isFinite(inc) || inc <= 0)
69
- return { blocked: false, pivot: null };
70
- const halfInc = inc / 2;
71
- const halfPct = halfInc / 100;
72
- const buyThreshold = pivot * (1 - halfPct);
73
- const sellThreshold = pivot * (1 + halfPct);
74
- if (type === 'buy' && numPrice > buyThreshold)
75
- return { blocked: true, pivot, halfInc, threshold: buyThreshold };
76
- if (type === 'sell' && numPrice < sellThreshold)
77
- return { blocked: true, pivot, halfInc, threshold: sellThreshold };
78
- return { blocked: false, pivot: null, halfInc, threshold: null };
75
+ if (type === 'buy' && numPrice >= pivot)
76
+ return { blocked: true, pivot, halfInc: 0, threshold: pivot };
77
+ if (type === 'sell' && numPrice <= pivot)
78
+ return { blocked: true, pivot, halfInc: 0, threshold: pivot };
79
+ return { blocked: false, pivot: null, halfInc: 0, threshold: null };
79
80
  }
80
81
  function resolveIncrementPercent(botMeta, override) {
81
82
  if (override != null && Number.isFinite(override) && override > 0)
@@ -93,11 +94,11 @@ function printHelp() {
93
94
  console.log(`\
94
95
  Usage: node dist/analysis/grid_correction_check.js --bot-key <key> [options]
95
96
 
96
- Validates LAST-FILL-GUARD discipline (pivot ± halfIncrement):
97
- last fill @x with increment i (half=i/2) gates both sides —
98
- BUY must be < x*(1-half/100), SELL > x*(1+half/100).
99
- e.g. x=1000, i=0.5% => BUY < 997.5 / SELL > 1002.5.
100
- Mirrors dexbot_cow_runtime:isLastFillGuardBlocked 1:1.
97
+ Validates LAST-FILL-GUARD discipline (DIRECTION ONLY relative to the last fill):
98
+ BUY must be < last fill price, SELL must be > last fill price.
99
+ Equal price counts as blocked (a re-place at the just-filled level).
100
+ Mirrors modules/order/utils/system:isLastFillGuardBlocked 1:1.
101
+ Cold start (no previous fill) is disabled.
101
102
 
102
103
  Required:
103
104
  --bot-key <key> Bot key (e.g. my-grid-bot) or bot name (use --list-bots)
@@ -112,8 +113,9 @@ Options:
112
113
  --refresh-account Force re-resolution of preferredAccount and update the
113
114
  stored accountId when it changed (default: reuse the
114
115
  stored accountId with no chain lookup)
115
- --increment <pct> Grid increment percent (default: from bot config or ${Number(C.DEFAULT_CONFIG?.incrementPercent ?? 0.5)})
116
- --tolerance <pct> Deprecated alias for --increment (kept for compat, prefer --increment)
116
+ --increment <pct> Grid increment percent, informational only — the
117
+ direction-only guard does not use a band
118
+ (default: from bot config or ${Number(C.DEFAULT_CONFIG?.incrementPercent ?? 0.5)})
117
119
  --per-fill Check at fill granularity (default: per-order aggregated)
118
120
  --include-cross-pair Check consecutive fills across different pairs (default: same pair only)
119
121
  --json <file> Export violations as JSON
@@ -191,15 +193,6 @@ function parseArgs() {
191
193
  case '--increment':
192
194
  opts.incrementPercent = parseFloat(args[++i]);
193
195
  break;
194
- case '--tolerance': {
195
- const v = parseFloat(args[++i]);
196
- // Back-compat: old --tolerance was adverse pct before flagging; now map to increment if user still passes it
197
- // Prefer explicit --increment; don't overwrite if already set
198
- if (opts.incrementPercent == null)
199
- opts.incrementPercent = v > 0 ? v * 2 : null; // heuristic: old tolerance ~ halfInc, so inc ~ 2*tolerance
200
- console.warn(`[warn] --tolerance is deprecated, use --increment <pct> (e.g. --increment ${v > 0 ? (v * 2) : 0.5})`);
201
- break;
202
- }
203
196
  case '--json':
204
197
  opts.json = args[++i];
205
198
  break;
@@ -416,7 +409,7 @@ function aggregateByOrder(trades, updates = []) {
416
409
  return orders.sort((a, b) => a.sequence - b.sequence);
417
410
  }
418
411
  // ─── Violation detection (LAST-FILL-GUARD 1:1) ────────────────────────────────
419
- function detectViolations(items, includeCrossPair, incrementPercent) {
412
+ function detectViolations(items, includeCrossPair) {
420
413
  const violations = [];
421
414
  let checkedTransitions = 0;
422
415
  // Helper for a single chronological sequence (already filtered to one pair or global)
@@ -428,7 +421,7 @@ function detectViolations(items, includeCrossPair, incrementPercent) {
428
421
  if (prev.orderId && prev.orderId === curr.orderId)
429
422
  continue;
430
423
  checkedTransitions++;
431
- const check = isLastFillGuardBlocked(curr.price, curr.direction, prev.price, prev.direction, incrementPercent);
424
+ const check = isLastFillGuardBlocked(curr.price, curr.direction, prev.price, prev.direction);
432
425
  if (check.blocked) {
433
426
  const delta = curr.price - prev.price;
434
427
  const deltaPct = prev.price !== 0 ? (delta / prev.price) * 100 : 0;
@@ -437,13 +430,13 @@ function detectViolations(items, includeCrossPair, incrementPercent) {
437
430
  index: i,
438
431
  pair: `${curr.baseAsset}:${curr.quoteAsset}`,
439
432
  direction: curr.direction,
440
- expected: isSell ? `> ${check.threshold?.toFixed(6)} (pivot ${check.pivot} +${check.halfInc}%)` : `< ${check.threshold?.toFixed(6)} (pivot ${check.pivot} -${check.halfInc}%)`,
433
+ expected: isSell ? `> ${check.threshold?.toFixed(6)} (last fill ${check.pivot})` : `< ${check.threshold?.toFixed(6)} (last fill ${check.pivot})`,
441
434
  prev: prev,
442
435
  curr: curr,
443
436
  priceDelta: delta,
444
437
  priceDeltaPct: deltaPct,
445
438
  pivot: check.pivot,
446
- halfInc: check.halfInc,
439
+ halfInc: 0,
447
440
  threshold: check.threshold,
448
441
  });
449
442
  }
@@ -486,10 +479,11 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
486
479
  pairGroups.set(k, []);
487
480
  pairGroups.get(k).push(t);
488
481
  }
489
- const halfInc = incrementPercent / 2;
482
+ // Direction-only guard: no band. The Violation row keeps halfInc = 0 so the
483
+ // JSON/CSV shape stays stable for existing consumers.
490
484
  console.log('');
491
485
  console.log('═══════════════════════════════════════════════════════════════════');
492
- console.log(' LAST-FILL-GUARD CHECK (pivot ± halfIncrement)');
486
+ console.log(' LAST-FILL-GUARD CHECK (direction only)');
493
487
  console.log('═══════════════════════════════════════════════════════════════════');
494
488
  console.log(` Bot key: ${botKey}${botMeta?.name ? ` (name: ${botMeta.name})` : ''}`);
495
489
  if (botMeta)
@@ -497,8 +491,8 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
497
491
  console.log(` Account: ${accountId}`);
498
492
  console.log(` Range: ${rangeLabel}`);
499
493
  console.log(` Mode: ${perFill ? 'per-fill' : 'per-order (aggregated)'}${includeCrossPair ? ', cross-pair enabled' : ', same-pair only'}`);
500
- console.log(` Increment: ${incrementPercent}% (halfInc ${halfInc}%)`);
501
- console.log(` Guard: BUY < pivot*(1-${halfInc}%) / SELL > pivot*(1+${halfInc}%) — both sides, global pivot`);
494
+ console.log(` Increment: ${incrementPercent}% (informational — the guard is direction-only)`);
495
+ console.log(' Guard: BUY < last fill / SELL > last fill — both sides, global pivot');
502
496
  console.log('');
503
497
  const buyCount = trades.filter(t => t.direction === 'buy').length;
504
498
  const sellCount = trades.filter(t => t.direction === 'sell').length;
@@ -512,7 +506,7 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
512
506
  console.log(` Violations: ${violations.length}${checkedTransitions > 0 ? ` (${((violations.length / checkedTransitions) * 100).toFixed(2)}%)` : ''}`);
513
507
  console.log('');
514
508
  if (violations.length === 0) {
515
- console.log(' ✅ PASS — no LAST-FILL-GUARD violations detected (all BUY < pivot-half, SELL > pivot+half).');
509
+ console.log(' ✅ PASS — no LAST-FILL-GUARD violations detected (all BUY < last fill, all SELL > last fill).');
516
510
  console.log('');
517
511
  if (checkedTransitions === 0) {
518
512
  console.log(' Note: no consecutive transitions in range to check.');
@@ -526,7 +520,7 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
526
520
  // Per-direction breakdown (blocked side = curr direction)
527
521
  const buyV = violations.filter(v => v.direction === 'buy').length;
528
522
  const sellV = violations.filter(v => v.direction === 'sell').length;
529
- console.log(` Breakdown: sell violations: ${sellV} (SELL < pivot+half), buy violations: ${buyV} (BUY > pivot-half)`);
523
+ console.log(` Breakdown: sell violations: ${sellV} (SELL <= last fill), buy violations: ${buyV} (BUY >= last fill)`);
530
524
  console.log('');
531
525
  // Timeline clustering by day
532
526
  const dayBuckets = new Map();
@@ -556,9 +550,9 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
556
550
  }
557
551
  console.log('');
558
552
  // Detailed violation table
559
- console.log(' ── Violations (pivot ± halfIncrement) ──');
553
+ console.log(' ── Violations (direction only) ──');
560
554
  console.log('');
561
- const hdr = ' # Pair Dir Prev Price Curr Price Thr Δ% Half% Prev Time Curr Time Prev Order Curr Order';
555
+ const hdr = ' # Pair Dir Prev Price Curr Price Last Fill Δ% Prev Time Curr Time Prev Order Curr Order';
562
556
  console.log(hdr);
563
557
  console.log(' ' + '─'.repeat(hdr.length - 2));
564
558
  for (let i = 0; i < violations.length; i++) {
@@ -570,24 +564,22 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
570
564
  const thr = fmt(v.threshold, 6).padStart(12);
571
565
  const delta = (v.priceDeltaPct >= 0 ? '+' : '') + v.priceDeltaPct.toFixed(4) + '%';
572
566
  const deltaStr = delta.padStart(9);
573
- const halfStr = (v.halfInc.toFixed(3) + '%').padStart(6);
574
567
  const pTime = (v.prev.time || '').slice(0, 19).replace('T', ' ').padEnd(19);
575
568
  const cTime = (v.curr.time || '').slice(0, 19).replace('T', ' ').padEnd(19);
576
569
  const pOrd = (v.prev.orderId || '-').slice(0, 16).padEnd(16);
577
570
  const cOrd = (v.curr.orderId || '-').slice(0, 16).padEnd(16);
578
571
  const marker = v.direction === 'sell' ? `SELL < ${fmt(v.threshold, 4)}` : `BUY > ${fmt(v.threshold, 4)}`;
579
- console.log(` ${(String(i + 1)).padStart(2)} ${pairLabel} ${dir} ${pPrice} ${cPrice} ${thr} ${deltaStr} ${halfStr} ${pTime} ${cTime} ${pOrd} ${cOrd} ${marker}`);
572
+ console.log(` ${(String(i + 1)).padStart(2)} ${pairLabel} ${dir} ${pPrice} ${cPrice} ${thr} ${deltaStr} ${pTime} ${cTime} ${pOrd} ${cOrd} ${marker}`);
580
573
  }
581
574
  console.log('');
582
- console.log(` Guard: BUY must be < pivot*(1-${halfInc}%), SELL > pivot*(1+${halfInc}%) — blocked if violated (mirrors bot).`);
583
- console.log(` Increment ${incrementPercent}% => halfInc ${halfInc}% — e.g. pivot 1000 => BUY thr ${(1000 * (1 - halfInc / 100)).toFixed(4)}, SELL thr ${(1000 * (1 + halfInc / 100)).toFixed(4)}`);
575
+ console.log(' Guard: BUY must be < the last fill price, SELL > it (equal price blocked) — mirrors bot.');
576
+ console.log(` No band: the grid increment (${incrementPercent}%) is reported for context only.`);
584
577
  console.log('');
585
578
  }
586
579
  function exportJson(filePath, violations, trades, rangeLabel, botKey, accountId, incrementPercent) {
587
580
  const payload = {
588
581
  botKey, accountId, range: rangeLabel,
589
582
  incrementPercent,
590
- halfIncrement: incrementPercent / 2,
591
583
  totalFills: trades.length,
592
584
  violations: violations.map(v => ({
593
585
  pair: `${assetSymbol(v.prev.baseAsset)}/${assetSymbol(v.prev.quoteAsset)}`,
@@ -638,7 +630,7 @@ async function main() {
638
630
  const botMeta = resolvedAccount.botMeta;
639
631
  console.log(`Account: ${accountId}${botMeta ? ` (${botMeta.assetA}/${botMeta.assetB})` : ''}`);
640
632
  const incrementPercent = resolveIncrementPercent(botMeta, opts.incrementPercent);
641
- console.log(`Increment: ${incrementPercent}% (halfInc ${incrementPercent / 2}%)${opts.incrementPercent == null && botMeta?.incrementPercent != null ? ' — from bot config' : opts.incrementPercent != null ? ' — from --increment' : ' — default'}`);
633
+ console.log(`Increment: ${incrementPercent}% (informational; the guard is direction-only)${opts.incrementPercent == null && botMeta?.incrementPercent != null ? ' — from bot config' : opts.incrementPercent != null ? ' — from --increment' : ' — default'}`);
642
634
  console.log(`\nFetching fills and order updates from Kibana...`);
643
635
  const [fills, orderUpdates] = await Promise.all([
644
636
  fetchAllFills({}, accountId, gte, lte),
@@ -677,7 +669,7 @@ async function main() {
677
669
  console.log(` Aggregated into ${orders.length} order epoch(s) (partial fills collapsed; repriced orders kept separate)`);
678
670
  items = orders;
679
671
  }
680
- const { violations, checkedTransitions } = detectViolations(items, opts.includeCrossPair, incrementPercent);
672
+ const { violations, checkedTransitions } = detectViolations(items, opts.includeCrossPair);
681
673
  const ordersForReport = opts.perFill ? null : items;
682
674
  printReport(trades, ordersForReport, violations, checkedTransitions, skipped, label, String(opts.botKey), accountId, botMeta, opts.perFill, opts.includeCrossPair, incrementPercent, gte, lte);
683
675
  if (opts.json)
@@ -0,0 +1,66 @@
1
+ import type { BookSides, PoolState } from './liquidity_depth_model.js';
2
+ interface ChainDbClient {
3
+ db(method: string, args?: unknown[]): Promise<unknown>;
4
+ }
5
+ interface ChainAsset {
6
+ id: string;
7
+ symbol: string;
8
+ precision: number;
9
+ }
10
+ interface RawLimitOrder {
11
+ id?: string;
12
+ for_sale?: string | number;
13
+ sell_price?: {
14
+ base?: {
15
+ amount?: string | number;
16
+ asset_id?: string;
17
+ };
18
+ quote?: {
19
+ amount?: string | number;
20
+ asset_id?: string;
21
+ };
22
+ };
23
+ }
24
+ interface RawPool {
25
+ id?: string;
26
+ asset_a?: string;
27
+ asset_b?: string;
28
+ asset_ids?: string[];
29
+ balance_a?: string | number;
30
+ balance_b?: string | number;
31
+ share_asset?: string;
32
+ taker_fee_percent?: number;
33
+ }
34
+ declare function resolveAsset(client: ChainDbClient, ref: string): Promise<ChainAsset>;
35
+ /**
36
+ * Decode raw limit orders into real bid/ask sides with display prices
37
+ * (quote per base) and quote/base amounts.
38
+ *
39
+ * `get_order_book` and `get_limit_orders` share the same side convention: an
40
+ * order whose `sell_price.base` is the requested base SELLS the base (real
41
+ * ask); the other side sells the quote (real bid).
42
+ */
43
+ declare function normalizeLimitOrders(orders: unknown, base: ChainAsset, quote: ChainAsset): BookSides;
44
+ /**
45
+ * Fetch the order book, preferring `get_limit_orders` because nodes usually
46
+ * cap `get_order_book` at 50 levels while `get_limit_orders` allows up to
47
+ * ~300 per side. Falls back to `get_order_book` when the wider API is not
48
+ * available. `depth` is per side.
49
+ */
50
+ declare function fetchOrderBook(client: ChainDbClient, base: ChainAsset, quote: ChainAsset, depth: number): Promise<BookSides>;
51
+ declare function fetchPools(client: ChainDbClient, baseId: string, quoteId: string): Promise<RawPool[]>;
52
+ /**
53
+ * Resolve a pool by id (`133` / `1.19.133`) or by its pool token (LP share-asset
54
+ * symbol). Shared with `dexbot tv`/`dw` and the liquidity analyzer's `--pool`.
55
+ */
56
+ declare function resolvePool(client: ChainDbClient, ref: string): Promise<RawPool>;
57
+ /** Decode one raw pool into display reserves (base = asset A, quote = asset B). */
58
+ declare function decodePool(pool: RawPool | null | undefined, base: ChainAsset, quote: ChainAsset): PoolState | null;
59
+ /**
60
+ * Decode and select a pool. With `poolId`, only that pool is considered;
61
+ * otherwise the deepest pool (largest quote reserve) wins.
62
+ */
63
+ declare function selectPool(pools: RawPool[], base: ChainAsset, quote: ChainAsset, poolId?: string | null): PoolState | null;
64
+ export { resolveAsset, fetchOrderBook, normalizeLimitOrders, fetchPools, resolvePool, decodePool, selectPool };
65
+ export type { ChainDbClient, ChainAsset, RawLimitOrder, RawPool };
66
+ //# sourceMappingURL=liquidity_chain.d.ts.map
@@ -0,0 +1,178 @@
1
+ 'use strict';
2
+ /**
3
+ * CHAIN READ HELPERS for the liquidity depth chart.
4
+ *
5
+ * Thin, dependency-injected wrappers over the read-only chain client so the
6
+ * order-book/pool decoding can be unit-tested with a stub `db()` function.
7
+ * Analysis connections never use the production singleton client (see
8
+ * analysis/chain_pool.ts).
9
+ *
10
+ * Pool references (id or pool token) are resolved by the shared helper in
11
+ * modules/liquidity_pool_ref.ts, so `dexbot liq`, `dexbot tv`/`dw` and this
12
+ * analyzer accept the same spellings.
13
+ */
14
+ import { blockchainToFloat } from '../../modules/order/utils/math.js';
15
+ import { poolAssetIds, resolvePoolRef } from '../../modules/liquidity_pool_ref.js';
16
+ import { resolveAssetRef } from '../../modules/asset_lookup.js';
17
+ import { normalizeOrderBook } from './liquidity_depth_model.js';
18
+ async function resolveAsset(client, ref) {
19
+ const probe = String(ref || '').trim();
20
+ if (!probe)
21
+ throw new Error('Asset reference is empty');
22
+ // Shared case-insensitive lookup (modules/asset_lookup.ts): "token.sym",
23
+ // "TOKEN.SYM" and "1.3.x" all reach the same asset object.
24
+ const asset = await resolveAssetRef((method, args) => client.db(method, args), probe);
25
+ if (!asset?.id || !asset.symbol || typeof asset.precision !== 'number') {
26
+ throw new Error(`Cannot resolve asset '${probe}' on chain`);
27
+ }
28
+ return { id: asset.id, symbol: asset.symbol, precision: asset.precision };
29
+ }
30
+ /**
31
+ * Decode raw limit orders into real bid/ask sides with display prices
32
+ * (quote per base) and quote/base amounts.
33
+ *
34
+ * `get_order_book` and `get_limit_orders` share the same side convention: an
35
+ * order whose `sell_price.base` is the requested base SELLS the base (real
36
+ * ask); the other side sells the quote (real bid).
37
+ */
38
+ function normalizeLimitOrders(orders, base, quote) {
39
+ const bids = [];
40
+ const asks = [];
41
+ if (!Array.isArray(orders))
42
+ return { bids, asks };
43
+ for (const entry of orders) {
44
+ const sellAsset = entry?.sell_price?.base?.asset_id;
45
+ const baseRaw = Number(entry?.sell_price?.base?.amount);
46
+ const quoteRaw = Number(entry?.sell_price?.quote?.amount);
47
+ const forSale = Number(entry?.for_sale ?? baseRaw);
48
+ if (!(baseRaw > 0) || !(quoteRaw > 0) || !(forSale > 0))
49
+ continue;
50
+ const sellsBase = sellAsset === base.id;
51
+ const sellsQuote = sellAsset === quote.id;
52
+ if (!sellsBase && !sellsQuote)
53
+ continue;
54
+ // `received` is the amount of the other asset the seller gets for the
55
+ // whole order; scaling by for_sale/baseRaw handles reduced fractions.
56
+ const receivedRaw = forSale * (quoteRaw / baseRaw);
57
+ if (sellsBase) {
58
+ const soldBase = blockchainToFloat(forSale, base.precision);
59
+ const receivedQuote = blockchainToFloat(receivedRaw, quote.precision);
60
+ if (soldBase > 0 && receivedQuote > 0) {
61
+ asks.push({ price: receivedQuote / soldBase, quote: receivedQuote, base: soldBase });
62
+ }
63
+ }
64
+ else {
65
+ const soldQuote = blockchainToFloat(forSale, quote.precision);
66
+ const receivedBase = blockchainToFloat(receivedRaw, base.precision);
67
+ if (soldQuote > 0 && receivedBase > 0) {
68
+ bids.push({ price: soldQuote / receivedBase, quote: soldQuote, base: receivedBase });
69
+ }
70
+ }
71
+ }
72
+ bids.sort((a, b) => b.price - a.price);
73
+ asks.sort((a, b) => a.price - b.price);
74
+ return { bids, asks };
75
+ }
76
+ /**
77
+ * Fetch the order book, preferring `get_limit_orders` because nodes usually
78
+ * cap `get_order_book` at 50 levels while `get_limit_orders` allows up to
79
+ * ~300 per side. Falls back to `get_order_book` when the wider API is not
80
+ * available. `depth` is per side.
81
+ */
82
+ async function fetchOrderBook(client, base, quote, depth) {
83
+ const requested = Math.max(1, Math.floor(depth));
84
+ const limits = [];
85
+ for (const candidate of [requested, 300, 100, 50]) {
86
+ if (candidate <= requested && !limits.includes(candidate))
87
+ limits.push(candidate);
88
+ }
89
+ for (const limit of limits) {
90
+ try {
91
+ const orders = await client.db('get_limit_orders', [base.id, quote.id, limit]);
92
+ if (Array.isArray(orders))
93
+ return normalizeLimitOrders(orders, base, quote);
94
+ }
95
+ catch (err) {
96
+ const message = String(err?.message ?? err);
97
+ if (!/limit|configured_limit|unknown|not found|method/i.test(message))
98
+ throw err;
99
+ }
100
+ }
101
+ // Conservative fallback: the classic order-book API (commonly capped at 50).
102
+ for (const limit of limits) {
103
+ if (limit > 50)
104
+ continue;
105
+ try {
106
+ const raw = await client.db('get_order_book', [base.id, quote.id, limit]);
107
+ return normalizeOrderBook(raw);
108
+ }
109
+ catch (err) {
110
+ const message = String(err?.message ?? err);
111
+ if (!/limit|configured_limit/i.test(message))
112
+ throw err;
113
+ }
114
+ }
115
+ const raw = await client.db('get_order_book', [base.id, quote.id, 50]);
116
+ return normalizeOrderBook(raw);
117
+ }
118
+ async function fetchPools(client, baseId, quoteId) {
119
+ const raw = await client.db('get_liquidity_pools_by_both_assets', [baseId, quoteId]);
120
+ return Array.isArray(raw) ? raw : [];
121
+ }
122
+ /**
123
+ * Resolve a pool by id (`133` / `1.19.133`) or by its pool token (LP share-asset
124
+ * symbol). Shared with `dexbot tv`/`dw` and the liquidity analyzer's `--pool`.
125
+ */
126
+ async function resolvePool(client, ref) {
127
+ return await resolvePoolRef((method, args) => client.db(method, args), ref);
128
+ }
129
+ /** Decode one raw pool into display reserves (base = asset A, quote = asset B). */
130
+ function decodePool(pool, base, quote) {
131
+ if (!pool)
132
+ return null;
133
+ const [assetA, assetB] = poolAssetIds(pool);
134
+ const aIsBase = assetA === base.id;
135
+ const aIsQuote = assetA === quote.id;
136
+ if (!aIsBase && !aIsQuote)
137
+ return null;
138
+ if (aIsBase && assetB !== quote.id)
139
+ return null;
140
+ if (aIsQuote && assetB !== base.id)
141
+ return null;
142
+ const baseRaw = aIsBase ? pool.balance_a : pool.balance_b;
143
+ const quoteRaw = aIsBase ? pool.balance_b : pool.balance_a;
144
+ if (baseRaw == null || quoteRaw == null)
145
+ return null;
146
+ const baseReserve = blockchainToFloat(baseRaw, base.precision);
147
+ const quoteReserve = blockchainToFloat(quoteRaw, quote.precision);
148
+ if (!(baseReserve > 0) || !(quoteReserve > 0))
149
+ return null;
150
+ // Chain stores the taker fee in 1/10000 units (50 => 0.5%).
151
+ const feePercent = typeof pool.taker_fee_percent === 'number'
152
+ ? pool.taker_fee_percent / 100
153
+ : null;
154
+ return {
155
+ id: pool.id,
156
+ shareAsset: pool.share_asset,
157
+ baseReserve,
158
+ quoteReserve,
159
+ feePercent,
160
+ };
161
+ }
162
+ /**
163
+ * Decode and select a pool. With `poolId`, only that pool is considered;
164
+ * otherwise the deepest pool (largest quote reserve) wins.
165
+ */
166
+ function selectPool(pools, base, quote, poolId) {
167
+ const wanted = poolId ? String(poolId).trim() : null;
168
+ const decoded = pools
169
+ .filter((p) => !wanted || p.id === wanted)
170
+ .map((p) => decodePool(p, base, quote))
171
+ .filter((p) => p != null);
172
+ if (decoded.length === 0)
173
+ return null;
174
+ decoded.sort((a, b) => b.quoteReserve - a.quoteReserve);
175
+ return decoded[0];
176
+ }
177
+ export { resolveAsset, fetchOrderBook, normalizeLimitOrders, fetchPools, resolvePool, decodePool, selectPool };
178
+ //# sourceMappingURL=liquidity_chain.js.map
@@ -0,0 +1,19 @@
1
+ import type { BookStats, DepthBuildResult, PoolState, PriceWindow } from './liquidity_depth_model.js';
2
+ interface ChartAsset {
3
+ symbol: string;
4
+ id?: string;
5
+ precision?: number;
6
+ }
7
+ interface LiquidityChartInput {
8
+ base: ChartAsset;
9
+ quote: ChartAsset;
10
+ pool: PoolState | null;
11
+ book: BookStats;
12
+ series: DepthBuildResult;
13
+ window: PriceWindow;
14
+ generatedAt?: string;
15
+ }
16
+ declare function generateLiquidityHTML(input: LiquidityChartInput, title?: string): string;
17
+ export { generateLiquidityHTML };
18
+ export type { LiquidityChartInput, ChartAsset };
19
+ //# sourceMappingURL=liquidity_chart_generator.d.ts.map