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
@@ -0,0 +1,124 @@
1
+ 'use strict';
2
+ /**
3
+ * modules/node_flap_score.ts - Time-decayed connection-churn (flapping) scoring
4
+ *
5
+ * Node selection used to rank nodes by raw RPC latency only, so the
6
+ * lowest-ping node won even when it dropped its socket every few hours. Live
7
+ * logs showed exactly that: three Cloudflare-fronted endpoints answered in
8
+ * 50-120ms and accounted for every abnormal close, while three
9
+ * 300-360ms endpoints never dropped once — and were never selected.
10
+ *
11
+ * This module turns transport drop *timestamps* into a ranking input:
12
+ *
13
+ * effectiveLatency = latencyMs + flapPenaltyMs
14
+ * flapScore = Σ 0.5 ^ (age_i / halfLife)
15
+ * flapPenaltyMs = min(flapScore * penaltyPerDrop, maxPenaltyMs)
16
+ *
17
+ * A node with no recent drops ranks on its ping alone. One drop costs
18
+ * `penaltyPerDrop` of effective latency and then fades with `halfLife`, so a
19
+ * node that flaps once and then behaves is re-admitted automatically, a node
20
+ * that keeps flapping stays at the back of the list, and nothing has to be
21
+ * "reset" by a lucky health probe (the old
22
+ * LIVE_FAILURE_HEALTH_SUCCESS_STREAK wipe-on-success counter).
23
+ *
24
+ * Everything here is pure: callers own persistence and logging. Drop history
25
+ * is bounded by the window (24h default) and capped by MAX_DROP_TIMES, so it
26
+ * is safe to persist in the shared health cache (see node_health_cache.ts).
27
+ */
28
+ /** Trailing window of drops that may influence selection. */
29
+ const DEFAULT_FLAP_WINDOW_MS = 24 * 60 * 60 * 1000;
30
+ /** Time for a drop's penalty weight to halve. */
31
+ const DEFAULT_FLAP_HALF_LIFE_MS = 12 * 60 * 60 * 1000;
32
+ /** Effective-latency cost of one *undecayed* drop. */
33
+ const DEFAULT_FLAP_PENALTY_MS_PER_DROP = 5_000;
34
+ /** Ceiling for the decayed penalty, so a badly degraded node stays usable as a last resort. */
35
+ const DEFAULT_FLAP_PENALTY_MAX_MS = 10 * 60 * 1000;
36
+ /** Hard cap on retained drop timestamps per node (bounded persistence). */
37
+ const MAX_DROP_TIMES = 64;
38
+ /** Trailing window used for the reported drops/hour counters. */
39
+ const DROP_RATE_WINDOW_MS = 60 * 60 * 1000;
40
+ function positiveOr(value, fallback) {
41
+ const n = Number(value);
42
+ return Number.isFinite(n) && n > 0 ? n : fallback;
43
+ }
44
+ /** Drop timestamps that are valid finite numbers, ascending. */
45
+ function normalizeDropTimes(dropTimes) {
46
+ if (!Array.isArray(dropTimes))
47
+ return [];
48
+ return dropTimes
49
+ .filter((t) => typeof t === 'number' && Number.isFinite(t) && t > 0)
50
+ .sort((a, b) => a - b);
51
+ }
52
+ /**
53
+ * Drop `dropTimes` down to the ones inside the trailing window and cap the
54
+ * retained history. Always returns a new array.
55
+ */
56
+ function pruneDropTimes(dropTimes, nowMs = Date.now(), windowMs = DEFAULT_FLAP_WINDOW_MS) {
57
+ const window = positiveOr(windowMs, DEFAULT_FLAP_WINDOW_MS);
58
+ const cutoff = nowMs - window;
59
+ const kept = normalizeDropTimes(dropTimes).filter((t) => t > cutoff && t <= nowMs);
60
+ return kept.length > MAX_DROP_TIMES ? kept.slice(kept.length - MAX_DROP_TIMES) : kept;
61
+ }
62
+ /**
63
+ * Append one drop and return the pruned history. The same millisecond is
64
+ * collapsed (a close + keep-alive trip for the same socket is one event).
65
+ */
66
+ function recordDrop(dropTimes, nowMs = Date.now(), windowMs = DEFAULT_FLAP_WINDOW_MS) {
67
+ const pruned = pruneDropTimes(dropTimes, nowMs, windowMs);
68
+ if (pruned.length > 0 && pruned[pruned.length - 1] === nowMs)
69
+ return pruned;
70
+ return pruneDropTimes([...pruned, nowMs], nowMs, windowMs);
71
+ }
72
+ /**
73
+ * Decayed drop weight: 1.0 for a drop that just happened, 0.5 after one
74
+ * half-life, ~0 after a few. Entries outside the window are ignored.
75
+ */
76
+ function flapScore(dropTimes, nowMs = Date.now(), halfLifeMs = DEFAULT_FLAP_HALF_LIFE_MS, windowMs = DEFAULT_FLAP_WINDOW_MS) {
77
+ const halfLife = positiveOr(halfLifeMs, DEFAULT_FLAP_HALF_LIFE_MS);
78
+ let score = 0;
79
+ for (const t of pruneDropTimes(dropTimes, nowMs, windowMs)) {
80
+ score += Math.pow(0.5, (nowMs - t) / halfLife);
81
+ }
82
+ return score;
83
+ }
84
+ /** Effective-latency penalty in ms for the node's recent drops. */
85
+ function flapPenaltyMs(dropTimes, options = {}) {
86
+ const nowMs = Number.isFinite(options.nowMs) ? options.nowMs : Date.now();
87
+ const score = flapScore(dropTimes, nowMs, options.halfLifeMs, options.windowMs);
88
+ if (score <= 0)
89
+ return 0;
90
+ const perDrop = positiveOr(options.penaltyMsPerDrop, DEFAULT_FLAP_PENALTY_MS_PER_DROP);
91
+ const maxPenalty = positiveOr(options.maxPenaltyMs, DEFAULT_FLAP_PENALTY_MAX_MS);
92
+ return Math.min(score * perDrop, maxPenalty);
93
+ }
94
+ /**
95
+ * Latency + decayed flap penalty, the value node selection sorts on.
96
+ * Unknown latency stays `Infinity` so it never outranks a measured node.
97
+ */
98
+ function effectiveLatencyMs(latencyMs, dropTimes, options = {}) {
99
+ if (typeof latencyMs !== 'number' || !Number.isFinite(latencyMs))
100
+ return Infinity;
101
+ return latencyMs + flapPenaltyMs(dropTimes, options);
102
+ }
103
+ /**
104
+ * Churn counters for logging/persistence: exact trailing-window counts plus
105
+ * the decayed score used for ranking.
106
+ */
107
+ function dropCounters(dropTimes, options = {}) {
108
+ const nowMs = Number.isFinite(options.nowMs) ? options.nowMs : Date.now();
109
+ const windowMs = positiveOr(options.windowMs, DEFAULT_FLAP_WINDOW_MS);
110
+ const pruned = pruneDropTimes(dropTimes, nowMs, windowMs);
111
+ const dropsLastHour = pruned.filter((t) => nowMs - t <= DROP_RATE_WINDOW_MS).length;
112
+ const score = flapScore(pruned, nowMs, options.halfLifeMs, windowMs);
113
+ return {
114
+ dropsLastHour,
115
+ drops24h: pruned.length,
116
+ // Round to 2 decimals: a 24h average is meaningless beyond that and the
117
+ // value is persisted in JSON.
118
+ dropsPerHour: Math.round((pruned.length / (windowMs / (60 * 60 * 1000))) * 100) / 100,
119
+ flapScore: Math.round(score * 1000) / 1000,
120
+ penaltyMs: Math.round(flapPenaltyMs(pruned, { ...options, nowMs })),
121
+ };
122
+ }
123
+ export { DEFAULT_FLAP_HALF_LIFE_MS, DEFAULT_FLAP_PENALTY_MAX_MS, DEFAULT_FLAP_PENALTY_MS_PER_DROP, DEFAULT_FLAP_WINDOW_MS, DROP_RATE_WINDOW_MS, MAX_DROP_TIMES, dropCounters, effectiveLatencyMs, flapPenaltyMs, flapScore, pruneDropTimes, recordDrop, };
124
+ //# sourceMappingURL=node_flap_score.js.map
@@ -3,18 +3,44 @@ interface HealthCacheOptions {
3
3
  stateDir?: string;
4
4
  now?: number;
5
5
  maxAgeMs?: number;
6
+ /**
7
+ * Flap-scoring tuning of the writer/reader. Defaults to
8
+ * modules/node_flap_score.ts values (which modules/constants.ts also reuses),
9
+ * so an operator who tuned `NODES.healthCheck.flap*` gets counters and
10
+ * ordering that match their bot's own ranking instead of the stock maths.
11
+ */
12
+ flap?: {
13
+ windowMs?: number;
14
+ halfLifeMs?: number;
15
+ penaltyMsPerDrop?: number;
16
+ maxPenaltyMs?: number;
17
+ };
6
18
  }
7
19
  interface NodeHealthStat {
8
20
  url?: string;
9
21
  status?: string;
10
22
  latencyMs?: number;
11
23
  lastCheckTime?: string | number | null;
24
+ /** Transport drop timestamps (see modules/node_flap_score.ts). */
25
+ dropTimes?: number[];
12
26
  }
13
27
  interface NodeHealthCacheEntry {
14
28
  url: string;
15
29
  status: string;
16
30
  latencyMs: number | null;
17
31
  lastCheckTime: string | number | null;
32
+ /**
33
+ * Connection churn, persisted so every consumer (bots, credential daemon)
34
+ * can see stability and not just ping. `dropTimes` is the source of truth
35
+ * for decay; the counters are derived for readers that only look at the
36
+ * JSON.
37
+ */
38
+ dropTimes: number[];
39
+ flapScore: number;
40
+ flapPenaltyMs: number;
41
+ dropsLastHour: number;
42
+ drops24h: number;
43
+ dropsPerHour: number;
18
44
  }
19
45
  interface NodeHealthCachePayload {
20
46
  version: number;
@@ -34,21 +60,32 @@ interface NodeSettings {
34
60
  }
35
61
  declare function resolveHealthCacheFile(config?: HealthCacheOptions): string;
36
62
  /**
37
- * Comparator for healthy/slow nodes: healthy first, then by ascending latency.
63
+ * Comparator for healthy/slow nodes: healthy first, then by *effective*
64
+ * latency (measured ping + decayed connection-churn penalty).
38
65
  * Shared by node_health_cache and node_manager.
39
66
  */
40
67
  declare function compareNodeHealth(a: {
41
68
  status: string;
42
69
  latencyMs?: number | null;
70
+ dropTimes?: number[];
71
+ flapPenaltyMs?: number;
43
72
  }, b: {
44
73
  status: string;
45
74
  latencyMs?: number | null;
46
- }): number;
75
+ dropTimes?: number[];
76
+ flapPenaltyMs?: number;
77
+ }, nowMs?: number, flap?: HealthCacheOptions['flap']): number;
78
+ /** Ranking latency: measured ping plus the churn penalty, Infinity when unknown. */
79
+ declare function nodeRankLatency(node: {
80
+ latencyMs?: number | null;
81
+ dropTimes?: number[];
82
+ flapPenaltyMs?: number;
83
+ }, nowMs: number, flap?: HealthCacheOptions['flap']): number;
47
84
  declare function writeHealthCache(stats: Iterable<NodeHealthStat> | ArrayLike<NodeHealthStat> | null | undefined, options?: HealthCacheOptions): NodeHealthCachePayload;
48
85
  declare function readHealthCache(options?: HealthCacheOptions): NodeHealthCachePayload | null;
49
86
  declare function removeNodesFromHealthCache(urls: string | string[], options?: HealthCacheOptions): NodeHealthCachePayload | null;
50
87
  declare function orderNodesFromHealthCache(configuredNodes: unknown, options?: HealthCacheOptions): string[];
51
88
  declare function resolveConfiguredNodes(settings: NodeSettings): string[];
52
89
  declare function orderNodesForSettings(settings: NodeSettings, options?: HealthCacheOptions): string[];
53
- export { compareNodeHealth, orderNodesFromHealthCache, orderNodesForSettings, readHealthCache, removeNodesFromHealthCache, resolveConfiguredNodes, resolveHealthCacheFile, writeHealthCache };
90
+ export { compareNodeHealth, nodeRankLatency, orderNodesFromHealthCache, orderNodesForSettings, readHealthCache, removeNodesFromHealthCache, resolveConfiguredNodes, resolveHealthCacheFile, writeHealthCache };
54
91
  //# sourceMappingURL=node_health_cache.d.ts.map
@@ -1,6 +1,7 @@
1
1
  import { NODE_MANAGEMENT } from './constants.js';
2
2
  import { getNodeHealthCacheFile } from './paths.js';
3
3
  import { writeJsonFileAtomic } from './bots_file_lock.js';
4
+ import { dropCounters, flapPenaltyMs, pruneDropTimes, } from './node_flap_score.js';
4
5
  import { getStorage } from './storage/index.js';
5
6
  const storage = getStorage();
6
7
  const { readJSON } = storage;
@@ -19,24 +20,63 @@ function normalizeNodeList(nodes) {
19
20
  : [];
20
21
  }
21
22
  /**
22
- * Comparator for healthy/slow nodes: healthy first, then by ascending latency.
23
+ * Comparator for healthy/slow nodes: healthy first, then by *effective*
24
+ * latency (measured ping + decayed connection-churn penalty).
23
25
  * Shared by node_health_cache and node_manager.
24
26
  */
25
- function compareNodeHealth(a, b) {
27
+ function compareNodeHealth(a, b, nowMs = Date.now(), flap) {
26
28
  if (a.status !== b.status)
27
29
  return a.status === 'healthy' ? -1 : 1;
28
- return (a.latencyMs ?? Infinity) - (b.latencyMs ?? Infinity);
30
+ // Compare without subtracting: two unknown latencies are both Infinity,
31
+ // and Infinity - Infinity is NaN (an unstable sort comparator).
32
+ const aRank = nodeRankLatency(a, nowMs, flap);
33
+ const bRank = nodeRankLatency(b, nowMs, flap);
34
+ if (aRank === bRank)
35
+ return 0;
36
+ return aRank < bRank ? -1 : 1;
29
37
  }
30
- function buildHealthCachePayload(stats, now = Date.now()) {
38
+ /** Ranking latency: measured ping plus the churn penalty, Infinity when unknown. */
39
+ function nodeRankLatency(node, nowMs, flap) {
40
+ if (typeof node.latencyMs !== 'number' || !Number.isFinite(node.latencyMs))
41
+ return Infinity;
42
+ // Prefer the penalty the writer persisted: recomputing from dropTimes here
43
+ // would silently apply *this* reader's tuning (or the stock defaults) over
44
+ // the one the cache was ordered with.
45
+ if (typeof node.flapPenaltyMs === 'number' && Number.isFinite(node.flapPenaltyMs)) {
46
+ return node.latencyMs + node.flapPenaltyMs;
47
+ }
48
+ const penalty = Array.isArray(node.dropTimes)
49
+ ? flapPenaltyMs(node.dropTimes, { nowMs, ...flap })
50
+ : 0;
51
+ return node.latencyMs + penalty;
52
+ }
53
+ function buildHealthCachePayload(stats, now = Date.now(), flap = undefined) {
54
+ const flapOptions = {
55
+ nowMs: now,
56
+ windowMs: flap?.windowMs ?? NODE_MANAGEMENT.FLAP_WINDOW_MS,
57
+ halfLifeMs: flap?.halfLifeMs ?? NODE_MANAGEMENT.FLAP_HALF_LIFE_MS,
58
+ penaltyMsPerDrop: flap?.penaltyMsPerDrop ?? NODE_MANAGEMENT.FLAP_PENALTY_MS_PER_DROP,
59
+ maxPenaltyMs: flap?.maxPenaltyMs ?? NODE_MANAGEMENT.FLAP_PENALTY_MAX_MS,
60
+ };
31
61
  const nodes = Array.from(stats || [])
32
62
  .filter((stat) => !!stat && (stat.status === 'healthy' || stat.status === 'slow') && typeof stat.url === 'string' && stat.url.trim() !== '')
33
- .map((stat) => ({
34
- url: stat.url,
35
- status: stat.status,
36
- latencyMs: Number.isFinite(stat.latencyMs) ? (stat.latencyMs ?? null) : null,
37
- lastCheckTime: stat.lastCheckTime || null,
38
- }));
39
- nodes.sort(compareNodeHealth);
63
+ .map((stat) => {
64
+ const dropTimes = pruneDropTimes(stat.dropTimes, now, flapOptions.windowMs);
65
+ const counters = dropCounters(dropTimes, flapOptions);
66
+ return {
67
+ url: stat.url,
68
+ status: stat.status,
69
+ latencyMs: Number.isFinite(stat.latencyMs) ? (stat.latencyMs ?? null) : null,
70
+ lastCheckTime: stat.lastCheckTime || null,
71
+ dropTimes,
72
+ flapScore: counters.flapScore,
73
+ flapPenaltyMs: counters.penaltyMs,
74
+ dropsLastHour: counters.dropsLastHour,
75
+ drops24h: counters.drops24h,
76
+ dropsPerHour: counters.dropsPerHour,
77
+ };
78
+ });
79
+ nodes.sort((a, b) => compareNodeHealth(a, b, now, flap));
40
80
  return {
41
81
  version: 1,
42
82
  updatedAt: new Date(now).toISOString(),
@@ -47,7 +87,7 @@ function buildHealthCachePayload(stats, now = Date.now()) {
47
87
  function writeHealthCache(stats, options = {}) {
48
88
  const file = resolveHealthCacheFile(options);
49
89
  const now = Number.isFinite(options.now) ? options.now : Date.now();
50
- const payload = buildHealthCachePayload(stats, now);
90
+ const payload = buildHealthCachePayload(stats, now, options.flap);
51
91
  // Atomic write: see writeJsonFileAtomic in bots_file_lock.ts. A torn
52
92
  // health cache would either lose all health history or fail to parse.
53
93
  writeJsonFileAtomic(file, payload);
@@ -69,7 +109,11 @@ function readHealthCache(options = {}) {
69
109
  return null;
70
110
  const nodes = payload.nodes
71
111
  .filter((node) => !!node && (node.status === 'healthy' || node.status === 'slow') && typeof node.url === 'string' && node.url.trim() !== '')
72
- .sort(compareNodeHealth);
112
+ .map((node) => ({
113
+ ...node,
114
+ dropTimes: pruneDropTimes(node.dropTimes, now, options.flap?.windowMs ?? NODE_MANAGEMENT.FLAP_WINDOW_MS),
115
+ }))
116
+ .sort((a, b) => compareNodeHealth(a, b, now, options.flap));
73
117
  return {
74
118
  ...payload,
75
119
  nodes,
@@ -95,12 +139,14 @@ function removeNodesFromHealthCache(urls, options = {}) {
95
139
  return null;
96
140
  const remaining = cache.nodes
97
141
  .filter((n) => !n || !n.url || !toRemove.has(n.url))
98
- .map((n) => ({
99
- url: n.url,
100
- status: n.status,
101
- latencyMs: n.latencyMs ?? undefined,
102
- lastCheckTime: n.lastCheckTime,
103
- }));
142
+ // Spread, not a field whitelist: dropping a node must not erase the
143
+ // churn history (dropTimes) of the nodes that stay.
144
+ .map((n) => ({ ...n, latencyMs: n.latencyMs ?? undefined, lastCheckTime: n.lastCheckTime }));
145
+ // The rewrite re-derives the drops/h counters from `dropTimes` using the
146
+ // caller's tuning (stock defaults when the caller has no bot config, e.g.
147
+ // the credential daemon). A bot that tuned NODES.healthCheck.flap* restores
148
+ // its own numbers on its next health sweep; until then the ordering can be
149
+ // computed with defaults, which is the best a tuning-less process can do.
104
150
  return writeHealthCache(remaining, { ...options, now: Date.now() });
105
151
  }
106
152
  function orderNodesFromHealthCache(configuredNodes, options = {}) {
@@ -145,5 +191,5 @@ function orderNodesForSettings(settings, options = {}) {
145
191
  : resolveHealthCacheMaxAgeMs(settings),
146
192
  });
147
193
  }
148
- export { compareNodeHealth, orderNodesFromHealthCache, orderNodesForSettings, readHealthCache, removeNodesFromHealthCache, resolveConfiguredNodes, resolveHealthCacheFile, writeHealthCache };
194
+ export { compareNodeHealth, nodeRankLatency, orderNodesFromHealthCache, orderNodesForSettings, readHealthCache, removeNodesFromHealthCache, resolveConfiguredNodes, resolveHealthCacheFile, writeHealthCache };
149
195
  //# sourceMappingURL=node_health_cache.js.map
@@ -15,7 +15,9 @@
15
15
  * - Automatic blacklisting of failed nodes
16
16
  *
17
17
  * 2. Intelligent Node Selection
18
- * - Selects lowest-latency healthy node
18
+ * - Ranks nodes by measured latency plus a time-decayed connection-churn
19
+ * penalty (see modules/node_flap_score.ts), so a fast node that keeps
20
+ * dropping its socket loses to a stable slightly-slower one
19
21
  * - Falls back to slow nodes if no healthy ones available
20
22
  * - Respects user-preferred node if healthy
21
23
  *
@@ -50,7 +52,14 @@ interface NodeManagerConfig {
50
52
  timeoutMs?: number;
51
53
  maxPingMs?: number;
52
54
  blacklistThreshold?: number;
53
- liveFailureSuccessStreak?: number;
55
+ /** Strikes live this long without a new failure before being forgiven. */
56
+ strikeDecayMs?: number;
57
+ /** Time for a connection drop's selection penalty to halve. */
58
+ flapHalfLifeMs?: number;
59
+ /** Effective-latency cost of one fresh (undecayed) drop. */
60
+ flapPenaltyMsPerDrop?: number;
61
+ /** Ceiling for the decayed penalty, so a degraded node stays usable. */
62
+ flapPenaltyMaxMs?: number;
54
63
  enabled?: boolean;
55
64
  };
56
65
  selection?: {
@@ -70,8 +79,14 @@ interface NodeStat {
70
79
  lastErrorMessage: string | null;
71
80
  chainId: string | null;
72
81
  blacklistedAt: number | null;
73
- healthCheckSuccessStreak: number;
74
- lastFailureSource: string | null;
82
+ /** When the most recent strike was recorded (drives strike decay). */
83
+ lastFailureAtMs: number | null;
84
+ /**
85
+ * Timestamps of live-transport drops inside the flap window. This is the
86
+ * stability signal node selection ranks on (see modules/node_flap_score.ts)
87
+ * and the value persisted into the shared health cache as drops/h.
88
+ */
89
+ dropTimes: number[];
75
90
  }
76
91
  interface ResolvedNodeManagerConfig {
77
92
  list: string[];
@@ -80,7 +95,10 @@ interface ResolvedNodeManagerConfig {
80
95
  timeoutMs: number;
81
96
  maxPingMs: number;
82
97
  blacklistThreshold: number;
83
- liveFailureSuccessStreak: number;
98
+ strikeDecayMs: number;
99
+ flapHalfLifeMs: number;
100
+ flapPenaltyMsPerDrop: number;
101
+ flapPenaltyMaxMs: number;
84
102
  enabled: boolean;
85
103
  };
86
104
  selection: {
@@ -91,6 +109,10 @@ interface ResolvedNodeManagerConfig {
91
109
  /**
92
110
  * NodeManager - Manages health checking and selection of BitShares nodes
93
111
  *
112
+ * Selection ranks healthy nodes on `latency + decayed churn penalty`, keeps a
113
+ * time-decaying strike count for blacklisting, and exposes per-node churn
114
+ * counters (drops/h) for logging and the shared health cache.
115
+ *
94
116
  * @class
95
117
  * @param {Object} config - Configuration object
96
118
  * @param {string[]} config.list - List of node URLs to monitor (e.g., wss://dex.iobanker.com/ws)
@@ -99,8 +121,12 @@ interface ResolvedNodeManagerConfig {
99
121
  * @param {number} [config.healthCheck.timeoutMs=5000] - Timeout for each health check
100
122
  * @param {number} [config.healthCheck.maxPingMs=3000] - Max acceptable latency
101
123
  * @param {number} [config.healthCheck.blacklistThreshold=3] - Failures before blacklist
124
+ * @param {number} [config.healthCheck.strikeDecayMs] - Lifetime of a strike without a new failure
125
+ * @param {number} [config.healthCheck.flapHalfLifeMs] - Half-life of a connection-drop penalty
126
+ * @param {number} [config.healthCheck.flapPenaltyMsPerDrop] - Effective-latency cost per fresh drop
127
+ * @param {number} [config.healthCheck.flapPenaltyMaxMs] - Cap on the decayed churn penalty
102
128
  * @param {Object} [config.selection] - Node selection settings
103
- * @param {string} [config.selection.strategy="latency"] - Selection strategy
129
+ * @param {string} [config.selection.strategy="latency"] - Selection strategy (latency + churn penalty)
104
130
  * @param {string} [config.selection.preferredNode] - Optional preferred node (if healthy)
105
131
  */
106
132
  declare class NodeManager {
@@ -133,6 +159,17 @@ declare class NodeManager {
133
159
  * @private
134
160
  */
135
161
  private saveBlacklistState;
162
+ /**
163
+ * Seed the in-memory drop history from the shared health cache.
164
+ *
165
+ * Churn has to survive process restarts: a bot that is restarted every few
166
+ * hours would otherwise start every node at zero drops and re-select the
167
+ * flapping endpoint immediately. The cache is written by whichever process
168
+ * last ran a health sweep, so treat it as advisory (any parse/age problem
169
+ * just means "no history yet").
170
+ * @private
171
+ */
172
+ private loadChurnHistory;
136
173
  /**
137
174
  * Persist the latest healthy/slow node ordering for lightweight consumers
138
175
  * such as the credential daemon.
@@ -170,17 +207,30 @@ declare class NodeManager {
170
207
  error: string | null;
171
208
  }>;
172
209
  /**
173
- * Record a successful health-probe result: set status/latency and decide
174
- * whether to clear the failure ledger.
210
+ * Remaining (decayed) strikes for a node at `nowMs`.
175
211
  *
176
- * A single successful probe must not erase strikes that came from the live
177
- * transport. Require `liveFailureSuccessStreak` consecutive successes before
178
- * clearing those, so a genuinely flapping node keeps accumulating toward
179
- * BLACKLIST_THRESHOLD while a recovered node is still re-admitted (status is
180
- * set either way). Strikes whose last source was a health check clear on the
181
- * first success, preserving normal probe recovery.
212
+ * A strike is worth 1.0 when recorded and falls linearly to 0 across
213
+ * `strikeDecayMs`. Linear decay (not exponential) keeps the threshold
214
+ * meaningful: three strikes on the same day still blacklist, while a node
215
+ * that failed once three days ago starts from 0 again. The remainder is
216
+ * rounded *up*, so a fresh single strike is not silently discounted to 0
217
+ * within minutes by the rounding step.
218
+ */
219
+ _decayedStrikeCount(stats: NodeStat, nowMs?: number): number;
220
+ /**
221
+ * Record a successful health-probe result: set status/latency and let the
222
+ * strike count decay.
182
223
  *
183
- * @returns {{ recovered: boolean, failureCount: number }}
224
+ * This deliberately no longer *resets* strikes: the old
225
+ * liveFailureSuccessStreak rule cleared a live-transport strike after two
226
+ * successful probes, and with a 4h probe interval that forgave a
227
+ * once-a-day flapper twice a day — every failure logged "attempt 1/3" and
228
+ * the node was never blacklisted. Strikes now age out on their own
229
+ * (`strikeDecayMs`), so probe success can re-admit a node's *status*
230
+ * without erasing the evidence that it drops connections.
231
+ *
232
+ * @returns {{ recovered: boolean, failureCount: number }} whether every
233
+ * strike has aged out, and the remaining count.
184
234
  */
185
235
  _recordHealthCheckSuccess(nodeUrl: string, status: string, latencyMs: number | null, chainId: string | null): {
186
236
  recovered: boolean;
@@ -215,12 +265,37 @@ declare class NodeManager {
215
265
  */
216
266
  rpcCall(ws: WebSocketLike, method: string, params: unknown[], timeoutMs: number): Promise<unknown>;
217
267
  /**
218
- * Get list of healthy nodes sorted by latency (best first)
268
+ * Flap-scoring options built from this manager's configuration.
269
+ * Single place that maps config -> the pure ranking maths, so the ranking,
270
+ * the logged counters and the persisted health cache always agree.
271
+ * @private
272
+ */
273
+ private _flapOptions;
274
+ /**
275
+ * Get list of healthy nodes, best first.
276
+ *
277
+ * Ranking is `measured latency + decayed connection-churn penalty`, so a
278
+ * 50ms node that drops its socket daily loses to a stable 350ms node. See
279
+ * modules/node_flap_score.ts for the penalty maths.
219
280
  * @returns {string[]} Array of node URLs
220
281
  */
221
282
  getHealthyNodes(): string[];
222
283
  /**
223
- * Get the single best (lowest latency) healthy node
284
+ * Connection-churn counters for one node (drops/h, decayed score, penalty).
285
+ * Used for logging and for the shared health cache.
286
+ * @param {string} nodeUrl - Node URL
287
+ * @returns {Object|null} Churn counters or null for an unknown node
288
+ */
289
+ getNodeChurn(nodeUrl: string, nowMs?: number): {
290
+ dropTimes: number[];
291
+ flapScore: number;
292
+ penaltyMs: number;
293
+ dropsLastHour: number;
294
+ drops24h: number;
295
+ dropsPerHour: number;
296
+ } | null;
297
+ /**
298
+ * Get the single best-ranked healthy node (latency + churn penalty)
224
299
  * @returns {string|null} Best node URL or null if none available
225
300
  */
226
301
  getBestNode(): string | null;
@@ -246,9 +321,12 @@ declare class NodeManager {
246
321
  * failure ledger — the same rules the credential daemon applies.
247
322
  * @param {string} nodeUrl - Node URL that failed
248
323
  * @param {string} [errorMessage] - Optional error description
249
- * @param {string} [source] - Failure source ('health-check' or 'broadcast'); controls log level
324
+ * @param {string} [source] - Failure source ('health-check', 'broadcast',
325
+ * 'connection', 'keep-alive'); controls log level and churn accounting
326
+ * @param {number} [nowMs] - Timestamp for the strike/drop (defaults to now;
327
+ * injectable so tests do not need to sleep past the report cooldown)
250
328
  */
251
- reportNodeFailure(nodeUrl: string, errorMessage?: string, source?: string): void;
329
+ reportNodeFailure(nodeUrl: string, errorMessage?: string, source?: string, nowMs?: number): void;
252
330
  /**
253
331
  * Manually blacklist a node (e.g., when it causes a connection failure)
254
332
  * @param {string} nodeUrl - Node URL to blacklist
@@ -274,6 +352,9 @@ declare class NodeManager {
274
352
  failureCount: number;
275
353
  lastCheckTime: string | null;
276
354
  lastErrorMessage: string | null;
355
+ drops24h: number;
356
+ dropsPerHour: number;
357
+ flapPenaltyMs: number;
277
358
  }>;
278
359
  /**
279
360
  * Get summary statistics
@@ -284,6 +365,7 @@ declare class NodeManager {
284
365
  counts: Record<string, number>;
285
366
  bestNode: string | null;
286
367
  avgLatency: number | null;
368
+ totalDrops24h: number;
287
369
  };
288
370
  }
289
371
  export default NodeManager;