dexbot 1.7.0 → 1.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/CHANGELOG.md +70 -0
  2. package/README.md +3 -3
  3. package/analysis/README.md +33 -13
  4. package/claw/package.json +1 -1
  5. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  6. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  7. package/dist/analysis/account_resolver.js +5 -6
  8. package/dist/analysis/analyze_liquidity.js +15 -4
  9. package/dist/analysis/bot_key_utils.d.ts +44 -1
  10. package/dist/analysis/bot_key_utils.js +76 -7
  11. package/dist/analysis/fills_cache.js +2 -1
  12. package/dist/analysis/grid_correction_check.d.ts +1 -19
  13. package/dist/analysis/grid_correction_check.js +12 -30
  14. package/dist/analysis/liquidity/liquidity_chart_generator.js +190 -20
  15. package/dist/analysis/liquidity/liquidity_depth_model.d.ts +41 -16
  16. package/dist/analysis/liquidity/liquidity_depth_model.js +49 -21
  17. package/dist/analysis/liquidity/liquidity_view.d.ts +15 -0
  18. package/dist/analysis/liquidity/liquidity_view.js +11 -0
  19. package/dist/analysis/resolve_bot_accounts.js +7 -6
  20. package/dist/analysis/trade_profitability.js +2 -1
  21. package/dist/credential-daemon.js +13 -2
  22. package/dist/dexbot.js +4 -4
  23. package/dist/modules/account_bots.d.ts +12 -1
  24. package/dist/modules/account_bots.js +7 -5
  25. package/dist/modules/account_orders.d.ts +12 -0
  26. package/dist/modules/account_orders.js +30 -0
  27. package/dist/modules/bitshares-native/transport.js +24 -6
  28. package/dist/modules/bitshares_client.d.ts +24 -6
  29. package/dist/modules/bitshares_client.js +44 -7
  30. package/dist/modules/bot_settings.d.ts +2 -0
  31. package/dist/modules/constants.d.ts +28 -3
  32. package/dist/modules/constants.js +79 -10
  33. package/dist/modules/dexbot_class.d.ts +23 -6
  34. package/dist/modules/dexbot_class.js +44 -0
  35. package/dist/modules/dexbot_cow_runtime.d.ts +128 -8
  36. package/dist/modules/dexbot_cow_runtime.js +688 -188
  37. package/dist/modules/dexbot_fill_runtime.js +124 -35
  38. package/dist/modules/dexbot_maintenance_runtime.d.ts +1 -1
  39. package/dist/modules/dexbot_maintenance_runtime.js +259 -79
  40. package/dist/modules/dexbot_startup_runtime.js +32 -20
  41. package/dist/modules/dexbot_state_recovery.d.ts +33 -1
  42. package/dist/modules/dexbot_state_recovery.js +167 -5
  43. package/dist/modules/node_connect_policy.d.ts +8 -1
  44. package/dist/modules/node_connect_policy.js +18 -2
  45. package/dist/modules/node_flap_score.d.ts +87 -0
  46. package/dist/modules/node_flap_score.js +124 -0
  47. package/dist/modules/node_health_cache.d.ts +40 -3
  48. package/dist/modules/node_health_cache.js +66 -20
  49. package/dist/modules/node_manager.d.ts +101 -19
  50. package/dist/modules/node_manager.js +255 -65
  51. package/dist/modules/order/accounting.d.ts +9 -4
  52. package/dist/modules/order/accounting.js +131 -19
  53. package/dist/modules/order/async_lock.d.ts +7 -1
  54. package/dist/modules/order/async_lock.js +7 -1
  55. package/dist/modules/order/export.js +25 -18
  56. package/dist/modules/order/fill_ledger.d.ts +99 -0
  57. package/dist/modules/order/fill_ledger.js +103 -0
  58. package/dist/modules/order/format.d.ts +24 -10
  59. package/dist/modules/order/format.js +30 -10
  60. package/dist/modules/order/grid.d.ts +75 -18
  61. package/dist/modules/order/grid.js +289 -72
  62. package/dist/modules/order/grid_reconcile.d.ts +5 -1
  63. package/dist/modules/order/grid_reconcile.js +333 -210
  64. package/dist/modules/order/grid_reconcile_internal.d.ts +38 -2
  65. package/dist/modules/order/grid_reconcile_internal.js +223 -91
  66. package/dist/modules/order/index.d.ts +18 -5
  67. package/dist/modules/order/index.js +5 -5
  68. package/dist/modules/order/lifecycle.d.ts +353 -0
  69. package/dist/modules/order/lifecycle.js +1109 -0
  70. package/dist/modules/order/manager.d.ts +277 -20
  71. package/dist/modules/order/manager.js +680 -64
  72. package/dist/modules/order/placement_lock.d.ts +102 -0
  73. package/dist/modules/order/placement_lock.js +222 -0
  74. package/dist/modules/order/strategy.js +13 -1
  75. package/dist/modules/order/sync_engine.d.ts +74 -114
  76. package/dist/modules/order/sync_engine.js +254 -198
  77. package/dist/modules/order/utils/math.d.ts +29 -4
  78. package/dist/modules/order/utils/math.js +61 -4
  79. package/dist/modules/order/utils/order.d.ts +106 -37
  80. package/dist/modules/order/utils/order.js +256 -81
  81. package/dist/modules/order/utils/system.d.ts +99 -6
  82. package/dist/modules/order/utils/system.js +249 -35
  83. package/dist/modules/order/utils/validate.d.ts +7 -1
  84. package/dist/modules/order/utils/validate.js +48 -2
  85. package/dist/modules/outcome.d.ts +54 -0
  86. package/dist/modules/outcome.js +51 -0
  87. package/dist/modules/settings_merge.d.ts +4 -0
  88. package/dist/modules/settings_merge.js +9 -0
  89. package/dist/modules/timing_policy.d.ts +82 -0
  90. package/dist/modules/timing_policy.js +244 -0
  91. package/dist/modules/types.d.ts +149 -22
  92. package/dist/scripts/analyze-credit.js +54 -17
  93. package/dist/scripts/analyze-orders.d.ts +4 -2
  94. package/dist/scripts/analyze-orders.js +113 -34
  95. package/dist/scripts/chart_targets.js +11 -15
  96. package/dist/scripts/test-credit-renewal.js +12 -5
  97. package/docs/COW_INVARIANTS.md +71 -8
  98. package/docs/DEXBOT_COMPARISON.md +6 -6
  99. package/docs/EVOLUTION.md +10 -8
  100. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  101. package/docs/GRID_PRICE_INVARIANT.md +1 -1
  102. package/docs/GRID_RECONCILE.md +18 -13
  103. package/docs/LOGGING.md +25 -1
  104. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +183 -26
  105. package/docs/README.md +23 -2
  106. package/docs/WORKFLOW.md +9 -3
  107. package/docs/architecture.md +68 -13
  108. package/docs/developer_guide.md +25 -8
  109. package/modules/README.md +6 -0
  110. package/package.json +3 -3
  111. package/scripts/README.md +16 -0
  112. package/scripts/pdev.sh +14 -1
  113. package/scripts/pmain.sh +23 -8
  114. package/scripts/ptest.sh +7 -0
  115. package/tests/README.md +30 -1
@@ -4,7 +4,7 @@
4
4
  * LAST-FILL-GUARD CHECK
5
5
  *
6
6
  * Validates LAST-FILL-GUARD discipline — DIRECTION ONLY, relative to the last
7
- * fill price (v1.6.16+, retrospective §9.7):
7
+ * fill price (v1.6.17+, retrospective §9.7):
8
8
  * BUY blocked if price >= pivot
9
9
  * SELL blocked if price <= pivot
10
10
  * e.g. pivot 1000 => BUY must be < 1000, SELL must be > 1000.
@@ -27,7 +27,8 @@
27
27
  * identity for a fill, so it cannot classify edge fills and will still
28
28
  * judge the pair after one. Expect rare false positives on wick fills.
29
29
  *
30
- * Mirrors modules/order/utils/system.ts:isLastFillGuardBlocked 1:1.
30
+ * Uses the runtime's own predicate (`modules/order/utils/system.ts:`
31
+ * `isLastFillGuardBlocked`); the checker never re-implements it.
31
32
  *
32
33
  * Fetches fill_order operations from Kibana (same pipeline as
33
34
  * trade_profitability.ts) and checks for last-fill guard violations.
@@ -42,6 +43,7 @@
42
43
  * node dist/analysis/grid_correction_check.js --list-bots
43
44
  */
44
45
  import { getErrorMessage, getErrorField } from '../modules/utils/errors.js';
46
+ import { isLastFillGuardBlocked } from '../modules/order/utils/system.js';
45
47
  import fs from 'node:fs';
46
48
  import { pathToFileURL } from 'node:url';
47
49
  import * as KC from '../market_adapter/core/kibana_client.js';
@@ -51,33 +53,13 @@ import { resolveBotAccount } from './account_resolver.js';
51
53
  import { classifyFill, assetSymbol, fetchAllFills, resolveAssetPrecisions, } from './fills_source.js';
52
54
  const { kibanaSearch, DEFAULT_CONFIG: BASE_CONFIG } = KC;
53
55
  const OP_LIMIT_ORDER_UPDATE = 77;
54
- // ─── LAST-FILL-GUARD helper (1:1 with modules/order/utils/system.ts) ────────────
55
- /**
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).
62
- * @param {number} price - Target order price
63
- * @param {string} type - buy/sell
64
- * @param {number|null} lastPrice - Most recent fill price
65
- * @param {string|null} lastType - Most recent fill side (buy/sell)
66
- * @returns {{blocked: boolean, pivot: number|null, halfInc: number, threshold: number|null}}
67
- */
68
- function isLastFillGuardBlocked(price, type, lastPrice, lastType) {
69
- const numPrice = Number(price);
70
- if (!Number.isFinite(numPrice))
71
- return { blocked: false, pivot: null };
72
- if (lastPrice == null || !Number.isFinite(Number(lastPrice)) || lastType == null)
73
- return { blocked: false, pivot: null };
74
- const pivot = Number(lastPrice);
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 };
80
- }
56
+ // ─── LAST-FILL-GUARD (the runtime's own predicate) ──────────────────────────────
57
+ //
58
+ // `isLastFillGuardBlocked` is IMPORTED from modules/order/utils/system.ts, not
59
+ // re-implemented. The old local copy was labelled "mirrors 1:1" and had already
60
+ // kept the removed band term; a copy of a rule is a second rule waiting to drift
61
+ // (retrospective R3.5 / §9.10/P5). The module returns `{blocked, pivot, threshold}`
62
+ // — there is no `halfInc`, because the increment no longer participates.
81
63
  function resolveIncrementPercent(botMeta, override) {
82
64
  if (override != null && Number.isFinite(override) && override > 0)
83
65
  return override;
@@ -97,7 +79,7 @@ Usage: node dist/analysis/grid_correction_check.js --bot-key <key> [options]
97
79
  Validates LAST-FILL-GUARD discipline (DIRECTION ONLY relative to the last fill):
98
80
  BUY must be < last fill price, SELL must be > last fill price.
99
81
  Equal price counts as blocked (a re-place at the just-filled level).
100
- Mirrors modules/order/utils/system:isLastFillGuardBlocked 1:1.
82
+ Uses the runtime's own predicate (isLastFillGuardBlocked); not a copy.
101
83
  Cold start (no previous fill) is disabled.
102
84
 
103
85
  Required:
@@ -6,6 +6,8 @@
6
6
  * constant-product AMM pool curve, overlaid side by side on the same price
7
7
  * axis. The two sources are shown as independent curves (never summed), so the
8
8
  * trader can see which one actually supplies the depth at a given price. The
9
+ * pool curve is fee-adjusted: each side terminates at its effective edge and
10
+ * the shaded band between them is the AMM spread a taker has to cross. The
9
11
  * visual model follows PoolTool's depth chart, rebuilt with the vendored uPlot
10
12
  * runtime used by every other DEXBot2 chart exporter.
11
13
  *
@@ -14,13 +16,23 @@
14
16
  */
15
17
  import { embedFunctionSources, escapeHtml, serializeJsonForScript, uplotInlineTags } from '../chart_utils.js';
16
18
  import { sharedChartCSS } from '../chart_css.js';
17
- import { formatCurrency, formatFundsValue, isValidNumber, safeFormat } from '../../modules/order/format.js';
19
+ import { formatCurrency, formatFundsValue, formatPercentLabel, isValidNumber, safeFormat } from '../../modules/order/format.js';
18
20
  import { buildDepthView } from './liquidity_view.js';
19
21
  const COLORS = {
20
22
  bidBook: '#3fb950',
21
23
  askBook: '#f85149',
22
24
  bidPool: '#58a6ff',
23
25
  askPool: '#d2a8ff',
26
+ // Spread bands: book = best bid..best ask, pool = the fee band between the
27
+ // fee-adjusted pool edges. Distinct hues so both can be compared at once;
28
+ // the fill fades downward so a band wider than the viewport reads as a
29
+ // highlight strip instead of tinting the whole chart.
30
+ bookSpreadFillTop: 'rgba(210,153,34,0.20)',
31
+ bookSpreadFillBottom: 'rgba(210,153,34,0.02)',
32
+ bookSpreadEdge: 'rgba(227,179,65,0.5)',
33
+ poolSpreadFillTop: 'rgba(210,168,255,0.24)',
34
+ poolSpreadFillBottom: 'rgba(210,168,255,0.03)',
35
+ poolSpreadEdge: 'rgba(210,168,255,0.65)',
24
36
  };
25
37
  function generateLiquidityHTML(input, title) {
26
38
  const { base, quote, pool, book, series, window } = input;
@@ -70,13 +82,23 @@ function generateLiquidityHTML(input, title) {
70
82
  ? `<span class="badge badge-pool">POOL ${escapeHtml(pool.id ?? 'unknown')}</span>
71
83
  <span class="badge" id="badge-pool-price">${escapeHtml(formatCurrency(poolPrice))} ${escapeHtml(priceLabel)}</span>`
72
84
  : `<span class="badge badge-muted">NO AMM POOL</span>`;
85
+ // The pool draws two curves that stop at their fee-adjusted edges, so the
86
+ // header states the fee and the spread it opens between them.
87
+ const poolBidEdge = series.poolBidPrice;
88
+ const poolAskEdge = series.poolAskPrice;
89
+ const poolSpreadPercent = poolBidEdge != null && poolAskEdge != null && poolAskEdge > 0
90
+ ? ((poolAskEdge - poolBidEdge) / poolAskEdge) * 100
91
+ : null;
92
+ const feeBadge = pool && pool.feePercent != null
93
+ ? `<span class="badge badge-pool" title="AMM taker fee (charged on the output side)">FEE ${escapeHtml(formatPercentLabel(pool.feePercent))}${poolSpreadPercent != null ? ` &middot; POOL SPREAD ${escapeHtml(formatPercentLabel(poolSpreadPercent))}` : ''}</span>`
94
+ : '';
73
95
  const midBadge = book.mid != null
74
96
  ? `<span class="badge" id="badge-mid">BOOK MID ${escapeHtml(formatCurrency(book.mid))}</span>`
75
97
  : `<span class="badge badge-muted">ONE-SIDED BOOK</span>`;
76
98
  const spreadBadge = book.spreadPercent != null
77
- ? `<span class="badge">SPREAD ${escapeHtml(formatCurrency(book.spreadPercent))}%</span>`
99
+ ? `<span class="badge badge-book">BOOK SPREAD ${escapeHtml(formatPercentLabel(book.spreadPercent))}</span>`
78
100
  : '';
79
- const windowBadge = `<span class="badge badge-muted">&plusmn;${escapeHtml(formatCurrency(((window.max - window.min) / (2 * (poolPrice ?? book.mid ?? window.min))) * 100))}% WINDOW</span>`;
101
+ const windowBadge = `<span class="badge badge-muted">&plusmn;${escapeHtml(formatPercentLabel(((window.max - window.min) / (2 * (poolPrice ?? book.mid ?? window.min))) * 100))} WINDOW</span>`;
80
102
  return `<!DOCTYPE html>
81
103
  <html lang="en">
82
104
  <head>
@@ -89,9 +111,10 @@ function generateLiquidityHTML(input, title) {
89
111
  #panels { height: calc(100vh - 64px); }
90
112
  #liquidity-panel { flex: 1 1 auto; min-height: 0; position: relative; }
91
113
  #liquidity-chart { position: absolute; inset: 0; }
92
- .badge { display: inline-block; padding: 2px 8px; border-radius: 3px; font-size: 10px; font-weight: 600;
114
+ .badge { display: inline-block; padding: 3px 9px; border-radius: 3px; font-size: 11px; font-weight: 600;
93
115
  letter-spacing: 0.4px; background: rgba(110,118,129,0.16); color: #adbac7; white-space: nowrap; }
94
116
  .badge-pool { background: rgba(88,166,255,0.18); color: #79c0ff; }
117
+ .badge-book { background: rgba(210,153,34,0.18); color: #e3b341; }
95
118
  .badge-muted { color: #6e7681; }
96
119
  .readout { position: absolute; top: 10px; left: 12px; z-index: 10; pointer-events: none;
97
120
  background: rgba(11,14,20,0.82); border: 1px solid #21262d; border-radius: 6px;
@@ -104,6 +127,16 @@ function generateLiquidityHTML(input, title) {
104
127
  .readout td { padding: 0 10px 0 0; text-align: right; }
105
128
  .readout td.side-bid { color: ${COLORS.bidBook}; text-align: left; }
106
129
  .readout td.side-ask { color: ${COLORS.askBook}; text-align: left; }
130
+ .spread-block { margin-top: 5px; padding-top: 5px; border-top: 1px solid #21262d; }
131
+ .spread-row { display: flex; align-items: baseline; gap: 7px; line-height: 1.5; }
132
+ .spread-row .swatch { width: 9px; height: 9px; border-radius: 2px; align-self: center; flex: 0 0 auto; }
133
+ .spread-key { width: 30px; color: #6e7681; font-size: 11px; font-weight: 700; letter-spacing: 0.5px; }
134
+ .spread-pct { color: #adbac7; font-size: 14px; font-weight: 600; }
135
+ .spread-row.is-tighter .spread-pct { color: #7ee787; }
136
+ .spread-tag { display: none; font-size: 9px; letter-spacing: 0.4px; color: #3fb950; border: 1px solid rgba(63,185,80,0.5);
137
+ border-radius: 3px; padding: 0 4px; }
138
+ .spread-row.is-tighter .spread-tag { display: inline-block; }
139
+ .spread-range { color: #8b949e; font-size: 11px; }
107
140
  .hint { font-size: 12px; color: #8b949e; white-space: nowrap; }
108
141
  .legend-swatch { display: inline-block; width: 9px; height: 9px; border-radius: 2px; margin-right: 5px; vertical-align: middle; }
109
142
  .legend-item { display: inline-flex; align-items: center; gap: 5px; margin-left: 8px; vertical-align: middle; }
@@ -115,6 +148,7 @@ function generateLiquidityHTML(input, title) {
115
148
  <div style="font-weight:bold;color:#fff;font-size:13px;">${escapeHtml(pageTitle)}</div>
116
149
  <div style="display:flex;gap:6px;align-items:center;flex-wrap:wrap;">
117
150
  ${poolBadge}
151
+ ${feeBadge}
118
152
  ${midBadge}
119
153
  ${spreadBadge}
120
154
  ${windowBadge}
@@ -151,7 +185,24 @@ function generateLiquidityHTML(input, title) {
151
185
  </tr>
152
186
  </tbody>
153
187
  </table>
154
- <div style="color:#6e7681;font-size:11px;margin-top:2px;">depth in <span id="r-depth-unit">${escapeHtml(depthLabel)}</span> &middot; click axes: y=depth asset, x=invert price</div>
188
+ <div class="spread-block">
189
+ <div class="spread-row" id="spread-book">
190
+ <span class="swatch" style="background:${COLORS.bookSpreadEdge};"></span>
191
+ <span class="spread-key">BOOK</span>
192
+ <span class="spread-pct" id="r-book-spread">-</span>
193
+ <span class="spread-tag">tighter</span>
194
+ <span class="spread-range" id="r-book-spread-range"></span>
195
+ </div>
196
+ <div class="spread-row" id="spread-pool">
197
+ <span class="swatch" style="background:${COLORS.poolSpreadEdge};"></span>
198
+ <span class="spread-key">POOL</span>
199
+ <span class="spread-pct" id="r-pool-spread">-</span>
200
+ <span class="spread-tag">tighter</span>
201
+ <span class="spread-range" id="r-pool-spread-range"></span>
202
+ </div>
203
+ </div>
204
+ <div style="color:#8b949e;font-size:11px;margin-top:3px;">depth in <span id="r-depth-unit">${escapeHtml(depthLabel)}</span> &middot; shaded bands = spreads to cross</div>
205
+ <div style="color:#8b949e;font-size:11px;">click axes: y = depth asset &middot; x = invert price</div>
155
206
  </div>
156
207
  <div id="liquidity-chart"></div>
157
208
  </div>
@@ -162,7 +213,7 @@ function generateLiquidityHTML(input, title) {
162
213
  <script>
163
214
  (function () {
164
215
  const data = JSON.parse(document.getElementById('payload').textContent);
165
- ${embedFunctionSources([buildDepthView, isValidNumber, safeFormat, formatCurrency, formatFundsValue])}
216
+ ${embedFunctionSources([buildDepthView, formatPercentLabel, isValidNumber, safeFormat, formatCurrency, formatFundsValue])}
166
217
  const fmtPrice = formatCurrency;
167
218
  const fmtDepth = formatFundsValue;
168
219
  const colors = data.colors;
@@ -197,6 +248,8 @@ function generateLiquidityHTML(input, title) {
197
248
  poolPrice: data.pool ? data.pool.price : null,
198
249
  mid: data.book.mid,
199
250
  window: data.window,
251
+ bookBestBid: data.book.bestBid,
252
+ bookBestAsk: data.book.bestAsk,
200
253
  });
201
254
  }
202
255
  function currentChartData() {
@@ -205,10 +258,10 @@ function generateLiquidityHTML(input, title) {
205
258
  function rebuildGuides() {
206
259
  guides.length = 0;
207
260
  if (view.poolPrice != null) {
208
- guides.push({ price: view.poolPrice, color: 'rgba(230,237,243,0.55)', dash: [6, 4], label: 'POOL' });
261
+ guides.push({ price: view.poolPrice, color: 'rgba(230,237,243,0.85)', dash: [6, 4], label: 'POOL' });
209
262
  }
210
263
  if (view.mid != null) {
211
- guides.push({ price: view.mid, color: 'rgba(139,148,158,0.65)', dash: [2, 4], label: 'BOOK MID' });
264
+ guides.push({ price: view.mid, color: 'rgba(196,205,216,0.9)', dash: [2, 4], label: 'BOOK MID' });
212
265
  }
213
266
  }
214
267
  view = buildView();
@@ -256,35 +309,117 @@ function generateLiquidityHTML(input, title) {
256
309
  });
257
310
  }
258
311
 
259
- // ── guide-line draw hook (pool price + book mid) ────────────────────
312
+ // ── guide lines + label block ───────────────────────────────────────
260
313
  function drawGuides(u) {
261
314
  const { ctx, bbox } = u;
262
315
  const xScale = u.scales.x;
263
316
  if (!xScale || !Number.isFinite(xScale.min) || !Number.isFinite(xScale.max)) return;
317
+ // uPlot leaves this context unscaled, so every coordinate here is a
318
+ // DEVICE pixel. Text sizes and paddings must be multiplied by the
319
+ // device pixel ratio or the labels render at half size on a HiDPI
320
+ // display while uPlot's own axis text stays correct.
321
+ const canvas = ctx.canvas;
322
+ const pr = canvas.width && canvas.clientWidth ? canvas.width / canvas.clientWidth : 1;
323
+ const px = (value) => value * pr;
264
324
  ctx.save();
265
325
  ctx.beginPath();
266
326
  ctx.rect(bbox.left, bbox.top, bbox.width, bbox.height);
267
327
  ctx.clip();
328
+ // Spread bands, book first then the (usually much narrower) pool fee
329
+ // band on top. Each band is filled and bounded by two edge lines so
330
+ // it stays readable when zoomed in, and the pool curves terminate at
331
+ // exactly the pool band edges (inverted view swaps the sides).
332
+ function paintBand(lo, hi, fillTop, fillBottom, edge) {
333
+ if (lo == null || hi == null || !Number.isFinite(lo) || !Number.isFinite(hi) || !(hi > lo)) return;
334
+ const x0 = u.valToPos(Math.max(lo, xScale.min), 'x', true);
335
+ const x1 = u.valToPos(Math.min(hi, xScale.max), 'x', true);
336
+ if (!(x1 > x0)) return;
337
+ const fill = ctx.createLinearGradient(0, bbox.top, 0, bbox.top + bbox.height);
338
+ fill.addColorStop(0, fillTop);
339
+ // Fade out by half height: a band wider than the viewport then
340
+ // reads as a highlight strip instead of a full-chart tint.
341
+ fill.addColorStop(0.5, fillBottom);
342
+ ctx.fillStyle = fill;
343
+ ctx.fillRect(x0, bbox.top, x1 - x0, bbox.height);
344
+ ctx.strokeStyle = edge;
345
+ ctx.lineWidth = Math.max(1, px(1));
346
+ ctx.setLineDash([px(3), px(3)]);
347
+ ctx.beginPath();
348
+ ctx.moveTo(x0, bbox.top);
349
+ ctx.lineTo(x0, bbox.top + bbox.height);
350
+ ctx.moveTo(x1, bbox.top);
351
+ ctx.lineTo(x1, bbox.top + bbox.height);
352
+ ctx.stroke();
353
+ ctx.setLineDash([]);
354
+ }
355
+ paintBand(view.bookBidPrice, view.bookAskPrice, colors.bookSpreadFillTop, colors.bookSpreadFillBottom, colors.bookSpreadEdge);
356
+ paintBand(view.poolBidPrice, view.poolAskPrice, colors.poolSpreadFillTop, colors.poolSpreadFillBottom, colors.poolSpreadEdge);
268
357
  for (let i = 0; i < guides.length; i++) {
269
358
  const guide = guides[i];
270
359
  if (guide.price < xScale.min || guide.price > xScale.max) continue;
271
360
  const x = u.valToPos(guide.price, 'x', true);
272
361
  ctx.strokeStyle = guide.color;
273
- ctx.lineWidth = 1;
274
- ctx.setLineDash(guide.dash);
362
+ ctx.lineWidth = Math.max(1, px(1));
363
+ ctx.setLineDash(guide.dash.map(px));
275
364
  ctx.beginPath();
276
365
  ctx.moveTo(x, bbox.top);
277
366
  ctx.lineTo(x, bbox.top + bbox.height);
278
367
  ctx.stroke();
279
368
  ctx.setLineDash([]);
280
- const alignRight = x > bbox.left + bbox.width / 2;
281
- // Stagger labels vertically so near-identical guide prices
282
- // (pool vs book mid) never overprint each other.
283
- const labelY = bbox.top + 14 + (i % 2) * 13;
284
- ctx.fillStyle = guide.color;
285
- ctx.font = '11px ui-monospace, SFMono-Regular, Menlo, monospace';
286
- ctx.textAlign = alignRight ? 'right' : 'left';
287
- ctx.fillText(guide.label + ' ' + fmtPrice(guide.price), x + (alignRight ? -6 : 6), labelY);
369
+ }
370
+ // One aligned label block, parked beside the pool fee band instead
371
+ // of on top of it, so neither the band nor the curves hide the text.
372
+ if (guides.length > 0) {
373
+ ctx.font = '600 ' + px(15) + 'px ui-monospace, SFMono-Regular, Menlo, monospace';
374
+ ctx.textAlign = 'left';
375
+ const entries = guides.map((guide) => ({
376
+ color: guide.color,
377
+ dash: guide.dash,
378
+ text: guide.label + ' ' + fmtPrice(guide.price),
379
+ }));
380
+ const swatchW = px(14);
381
+ const gap = px(9);
382
+ const pad = px(9);
383
+ const lineH = px(20);
384
+ const textW = Math.max.apply(null, entries.map((entry) => ctx.measureText(entry.text).width));
385
+ const blockW = Math.min(pad + swatchW + gap + textW + pad, bbox.width - px(12));
386
+ const blockH = pad * 2 + (entries.length - 1) * lineH + px(15);
387
+ const minLeft = bbox.left + px(6);
388
+ const maxLeft = bbox.left + bbox.width - blockW - px(6);
389
+ let left;
390
+ const bandLo = view.poolBidPrice;
391
+ const bandHi = view.poolAskPrice;
392
+ if (bandLo != null && bandHi != null && bandHi > bandLo) {
393
+ const bandLeft = Math.max(bbox.left, Math.min(u.valToPos(bandLo, 'x', true), bbox.left + bbox.width));
394
+ const bandRight = Math.max(bbox.left, Math.min(u.valToPos(bandHi, 'x', true), bbox.left + bbox.width));
395
+ left = bbox.left + bbox.width - bandRight >= blockW + px(16)
396
+ ? bandRight + px(12)
397
+ : bandLeft - px(12) - blockW;
398
+ } else {
399
+ left = maxLeft;
400
+ }
401
+ left = Math.max(minLeft, Math.min(left, maxLeft));
402
+ const top = bbox.top + px(8);
403
+ ctx.fillStyle = 'rgba(11,14,20,0.84)';
404
+ ctx.strokeStyle = 'rgba(48,54,61,0.95)';
405
+ ctx.lineWidth = Math.max(1, px(1));
406
+ ctx.beginPath();
407
+ ctx.rect(left, top, blockW, blockH);
408
+ ctx.fill();
409
+ ctx.stroke();
410
+ for (let i = 0; i < entries.length; i++) {
411
+ const baseY = top + pad + px(11) + i * lineH;
412
+ ctx.strokeStyle = entries[i].color;
413
+ ctx.lineWidth = Math.max(1, px(1));
414
+ ctx.setLineDash(entries[i].dash.map(px));
415
+ ctx.beginPath();
416
+ ctx.moveTo(left + pad, baseY - px(5));
417
+ ctx.lineTo(left + pad + swatchW, baseY - px(5));
418
+ ctx.stroke();
419
+ ctx.setLineDash([]);
420
+ ctx.fillStyle = entries[i].color;
421
+ ctx.fillText(entries[i].text, left + pad + swatchW + gap, baseY);
422
+ }
288
423
  }
289
424
  ctx.restore();
290
425
  }
@@ -363,9 +498,42 @@ function generateLiquidityHTML(input, title) {
363
498
  const el = document.getElementById(id);
364
499
  if (el) el.textContent = value;
365
500
  }
501
+
502
+ // Spread comparison: the book's own bid/ask gap next to the pool fee
503
+ // band, so the cheaper entry is obvious without reading two badges.
504
+ function updateSpreads() {
505
+ const rows = [
506
+ { row: 'spread-book', pct: 'r-book-spread', range: 'r-book-spread-range',
507
+ lo: view.bookBidPrice, hi: view.bookAskPrice, value: null },
508
+ { row: 'spread-pool', pct: 'r-pool-spread', range: 'r-pool-spread-range',
509
+ lo: view.poolBidPrice, hi: view.poolAskPrice, value: null },
510
+ ];
511
+ for (const r of rows) {
512
+ r.value = r.lo != null && r.hi != null && r.lo > 0 && r.hi > r.lo
513
+ ? ((r.hi - r.lo) / r.hi) * 100
514
+ : null;
515
+ }
516
+ // Only call one of them "tighter" when both are measurable.
517
+ const comparable = rows.every((r) => r.value != null);
518
+ const tightest = comparable ? Math.min(rows[0].value, rows[1].value) : null;
519
+ for (const r of rows) {
520
+ setText(r.pct, r.value != null ? formatPercentLabel(r.value) : '—');
521
+ setText(r.range, r.lo != null && r.hi != null && r.hi > r.lo
522
+ ? fmtPrice(r.lo) + ' – ' + fmtPrice(r.hi)
523
+ : '');
524
+ const rowEl = document.getElementById(r.row);
525
+ if (rowEl) rowEl.classList.toggle('is-tighter', tightest != null && r.value <= tightest + 1e-12);
526
+ }
527
+ }
366
528
  function updateReadout(idx) {
367
529
  if (idx == null || idx < 0 || idx >= view.prices.length) {
368
- const anchor = view.poolPrice != null ? view.poolPrice : (view.mid != null ? view.mid : view.min);
530
+ // Park the readout on the best bid (top-of-book depth) rather
531
+ // than the pool price: the pool price sits inside the fee band,
532
+ // where both pool sides are legitimately zero, which reads as an
533
+ // empty readout on first paint.
534
+ const anchor = view.bookBidPrice != null
535
+ ? view.bookBidPrice
536
+ : (view.poolPrice != null ? view.poolPrice : (view.mid != null ? view.mid : view.min));
369
537
  idx = nearestIndex(anchor);
370
538
  }
371
539
  setText('r-price', fmtPrice(view.prices[idx]));
@@ -412,6 +580,7 @@ function generateLiquidityHTML(input, title) {
412
580
  setText('r-unit', currentPriceUnit());
413
581
  setText('r-depth-unit', currentDepthUnit());
414
582
  updateHeaderPrices();
583
+ updateSpreads();
415
584
  updateReadout(null);
416
585
  }
417
586
  // Axis clicks toggle, but a drag that starts on an axis gutter must not
@@ -431,6 +600,7 @@ function generateLiquidityHTML(input, title) {
431
600
  }
432
601
  });
433
602
  updateHeaderPrices();
603
+ updateSpreads();
434
604
 
435
605
  let leavePending = null;
436
606
  chart.over.addEventListener('mousemove', () => {
@@ -25,17 +25,29 @@
25
25
  * `normalizeOrderBook` performs that side flip, so the rest of this module
26
26
  * (and the chart) speaks plain real bid/ask.
27
27
  *
28
- * Pool depth is the exact constant-product solution for moving the pool price
29
- * from p0 to p:
30
- * - below p0 (selling base into the pool):
31
- * quote received = quoteReserve * (1 - sqrt(p / p0))
32
- * - above p0 (buying base from the pool):
33
- * quote paid = quoteReserve * (sqrt(p / p0) - 1)
34
- * which is the same curve PoolTool plots as `amount_y * (1 - sqrt(p_pool/p))`
35
- * and `amount_y * (sqrt(p_pool/p) - 1)` (there p_pool/p is inverted because
36
- * PoolTool's price is base-per-quote). The closed forms preserve x*y = k and
37
- * move the implied pool price to exactly p; the taker fee is not applied,
38
- * matching PoolTool's depth chart.
28
+ * Pool depth is the exact constant-product solution, net of the AMM taker fee
29
+ * f (`taker_fee_percent / 100`). The fee comes off the output side and stays in
30
+ * the pool (the on-chain liquidity_pool_exchange evaluator), so a swap that
31
+ * moves the reserve price p0 -> p pays:
32
+ * - selling base into the pool (p < p0):
33
+ * gross quote out = quoteReserve * (1 - sqrt(p / p0))
34
+ * taker gets = (1 - f) * gross
35
+ * - buying base from the pool (p > p0):
36
+ * gross quote in = quoteReserve * (sqrt(p / p0) - 1)
37
+ * taker gets = (1 - f) * gross base
38
+ * The marginal price of such a trade is p * (1 - f) when selling and
39
+ * p / (1 - f) when buying, so the curve is parameterized by that EFFECTIVE
40
+ * price P instead of the reserve price. That keeps the local slope of the
41
+ * cumulative curve equal to P at every sample (the same property the fee-free
42
+ * closed forms have), and it opens a fee band between the two sides:
43
+ * bid (P < (1 - f) * p0) = (1 - f) * quoteReserve * (1 - sqrt(P / ((1 - f) * p0)))
44
+ * ask (P > p0 / (1 - f)) = quoteReserve * (sqrt(P * (1 - f) / p0) - 1)
45
+ * i.e. the AMM's own spread `[(1 - f) * p0, p0 / (1 - f)]` (~2f wide) that a
46
+ * taker has to cross. With f = 0 both sides collapse onto p0 and reduce to the
47
+ * curve PoolTool plots (`amount_y * (1 - sqrt(p_pool/p))` and
48
+ * `amount_y * (sqrt(p_pool/p) - 1)`; its price is base-per-quote, so the same
49
+ * curves appear with the reciprocal price). The closed forms preserve
50
+ * x * y = k and move the implied pool price to exactly p.
39
51
  */
40
52
  interface RawBookOrder {
41
53
  price?: string | number;
@@ -72,6 +84,10 @@ interface PoolState {
72
84
  }
73
85
  interface DepthSeries {
74
86
  prices: number[];
87
+ /** Effective pool bid edge (fee-adjusted); null without a pool. */
88
+ poolBidPrice: number | null;
89
+ /** Effective pool ask edge (fee-adjusted); null without a pool. */
90
+ poolAskPrice: number | null;
75
91
  /** Cumulative quote (B) depth. */
76
92
  bookBid: number[];
77
93
  poolBid: number[];
@@ -123,10 +139,19 @@ declare function computeBookStats(sides: BookSides): BookStats;
123
139
  * no pool), e.g. range 0.5 => [0.5 * center, 1.5 * center].
124
140
  */
125
141
  declare function resolvePriceWindow(center: number | null, range: number): PriceWindow;
126
- declare function poolBidDepth(price: number, poolPrice: number, quoteReserve: number): number;
127
- declare function poolAskDepth(price: number, poolPrice: number, quoteReserve: number): number;
128
- declare function poolBidBaseDepth(price: number, poolPrice: number, baseReserve: number): number;
129
- declare function poolAskBaseDepth(price: number, poolPrice: number, baseReserve: number): number;
142
+ /**
143
+ * AMM taker fee as a fraction (0.2% => 0.002). Unknown/negative fees are 0 and
144
+ * the value is capped below 1 so the effective ask edge stays finite.
145
+ */
146
+ declare function poolFeeFraction(pool: PoolState | null | undefined): number;
147
+ /** Effective pool bid edge: the highest price a pool seller can realize. */
148
+ declare function poolBidPrice(poolPrice: number, fee?: number): number;
149
+ /** Effective pool ask edge: the lowest price a pool buyer can realize. */
150
+ declare function poolAskPrice(poolPrice: number, fee?: number): number;
151
+ declare function poolBidDepth(price: number, poolPrice: number, quoteReserve: number, fee?: number): number;
152
+ declare function poolAskDepth(price: number, poolPrice: number, quoteReserve: number, fee?: number): number;
153
+ declare function poolBidBaseDepth(price: number, poolPrice: number, baseReserve: number, fee?: number): number;
154
+ declare function poolAskBaseDepth(price: number, poolPrice: number, baseReserve: number, fee?: number): number;
130
155
  /**
131
156
  * Sample the two liquidity sources independently over a price window. The
132
157
  * returned arrays are all the same length and share the `prices` axis.
@@ -136,6 +161,6 @@ declare function poolAskBaseDepth(price: number, poolPrice: number, baseReserve:
136
161
  * side by side at each price instead of collapsing them into one stacked total.
137
162
  */
138
163
  declare function buildDepthSeries(input: DepthBuildInput): DepthBuildResult;
139
- export { DEFAULT_STEPS, normalizeOrderBook, computePoolPrice, computeBookStats, resolvePriceWindow, buildDepthSeries, poolBidDepth, poolAskDepth, poolBidBaseDepth, poolAskBaseDepth, };
164
+ export { DEFAULT_STEPS, normalizeOrderBook, computePoolPrice, computeBookStats, resolvePriceWindow, buildDepthSeries, poolFeeFraction, poolBidPrice, poolAskPrice, poolBidDepth, poolAskDepth, poolBidBaseDepth, poolAskBaseDepth, };
140
165
  export type { RawBookOrder, RawOrderBook, BookOrder, BookSides, PoolState, DepthSeries, DepthBuildInput, DepthBuildResult, PriceWindow, BookStats, };
141
166
  //# sourceMappingURL=liquidity_depth_model.d.ts.map
@@ -96,7 +96,7 @@ function upperBound(values, target) {
96
96
  }
97
97
  return lo;
98
98
  }
99
- function buildPriceGrid(input, poolPrice) {
99
+ function buildPriceGrid(input, poolPrice, poolFee) {
100
100
  const { window } = input;
101
101
  const steps = Math.max(2, Math.floor(input.steps ?? DEFAULT_STEPS));
102
102
  const span = window.max - window.min;
@@ -115,8 +115,11 @@ function buildPriceGrid(input, poolPrice) {
115
115
  for (const order of input.asks) {
116
116
  values.push(order.price, order.price - eps);
117
117
  }
118
- if (poolPrice != null)
119
- values.push(poolPrice);
118
+ if (poolPrice != null) {
119
+ // Reserve price plus both fee-adjusted edges, so the band corners are
120
+ // sampled sharply instead of being smeared across a step interval.
121
+ values.push(poolPrice, poolBidPrice(poolPrice, poolFee), poolAskPrice(poolPrice, poolFee));
122
+ }
120
123
  const inWindow = values.filter((v) => Number.isFinite(v) && v > 0 && v >= window.min && v <= window.max);
121
124
  inWindow.sort((a, b) => a - b);
122
125
  const deduped = [];
@@ -150,25 +153,47 @@ function buildBookLookups(sides) {
150
153
  }
151
154
  return { bidPrices, bidSuffix, bidSuffixBase, askPrices, askPrefix, askPrefixBase };
152
155
  }
153
- function poolBidDepth(price, poolPrice, quoteReserve) {
154
- if (!(price < poolPrice))
156
+ /**
157
+ * AMM taker fee as a fraction (0.2% => 0.002). Unknown/negative fees are 0 and
158
+ * the value is capped below 1 so the effective ask edge stays finite.
159
+ */
160
+ function poolFeeFraction(pool) {
161
+ const percent = pool?.feePercent;
162
+ if (typeof percent !== 'number' || !Number.isFinite(percent) || percent <= 0)
163
+ return 0;
164
+ return Math.min(percent, 99) / 100;
165
+ }
166
+ /** Effective pool bid edge: the highest price a pool seller can realize. */
167
+ function poolBidPrice(poolPrice, fee = 0) {
168
+ return poolPrice * (1 - fee);
169
+ }
170
+ /** Effective pool ask edge: the lowest price a pool buyer can realize. */
171
+ function poolAskPrice(poolPrice, fee = 0) {
172
+ return poolPrice / (1 - fee);
173
+ }
174
+ function poolBidDepth(price, poolPrice, quoteReserve, fee = 0) {
175
+ const edge = poolBidPrice(poolPrice, fee);
176
+ if (!(price < edge))
155
177
  return 0;
156
- return quoteReserve * (1 - Math.sqrt(price / poolPrice));
178
+ return (1 - fee) * quoteReserve * (1 - Math.sqrt(price / edge));
157
179
  }
158
- function poolAskDepth(price, poolPrice, quoteReserve) {
159
- if (!(price > poolPrice))
180
+ function poolAskDepth(price, poolPrice, quoteReserve, fee = 0) {
181
+ const edge = poolAskPrice(poolPrice, fee);
182
+ if (!(price > edge))
160
183
  return 0;
161
- return quoteReserve * (Math.sqrt(price / poolPrice) - 1);
184
+ return quoteReserve * (Math.sqrt((price * (1 - fee)) / poolPrice) - 1);
162
185
  }
163
- function poolBidBaseDepth(price, poolPrice, baseReserve) {
164
- if (!(price < poolPrice))
186
+ function poolBidBaseDepth(price, poolPrice, baseReserve, fee = 0) {
187
+ const edge = poolBidPrice(poolPrice, fee);
188
+ if (!(price < edge))
165
189
  return 0;
166
- return baseReserve * (Math.sqrt(poolPrice / price) - 1);
190
+ return baseReserve * (Math.sqrt(((1 - fee) * poolPrice) / price) - 1);
167
191
  }
168
- function poolAskBaseDepth(price, poolPrice, baseReserve) {
169
- if (!(price > poolPrice))
192
+ function poolAskBaseDepth(price, poolPrice, baseReserve, fee = 0) {
193
+ const edge = poolAskPrice(poolPrice, fee);
194
+ if (!(price > edge))
170
195
  return 0;
171
- return baseReserve * (1 - Math.sqrt(poolPrice / price));
196
+ return (1 - fee) * baseReserve * (1 - Math.sqrt(poolPrice / (price * (1 - fee))));
172
197
  }
173
198
  /**
174
199
  * Sample the two liquidity sources independently over a price window. The
@@ -184,8 +209,9 @@ function buildDepthSeries(input) {
184
209
  throw new Error('buildDepthSeries: window must be positive with max > min');
185
210
  }
186
211
  const poolPrice = computePoolPrice(input.pool);
212
+ const fee = poolFeeFraction(input.pool);
187
213
  const quoteReserve = poolPrice != null && input.pool ? input.pool.quoteReserve : 0;
188
- const prices = buildPriceGrid(input, poolPrice);
214
+ const prices = buildPriceGrid(input, poolPrice, fee);
189
215
  if (prices.length === 0)
190
216
  throw new Error('buildDepthSeries: empty price grid');
191
217
  const { bidPrices, bidSuffix, bidSuffixBase, askPrices, askPrefix, askPrefixBase } = buildBookLookups({
@@ -195,6 +221,8 @@ function buildDepthSeries(input) {
195
221
  const baseReserve = poolPrice != null && input.pool ? input.pool.baseReserve : 0;
196
222
  const series = {
197
223
  prices,
224
+ poolBidPrice: poolPrice != null ? poolBidPrice(poolPrice, fee) : null,
225
+ poolAskPrice: poolPrice != null ? poolAskPrice(poolPrice, fee) : null,
198
226
  bookBid: [],
199
227
  poolBid: [],
200
228
  bookAsk: [],
@@ -211,10 +239,10 @@ function buildDepthSeries(input) {
211
239
  const bookAsk = askPrefix[upperBound(askPrices, price)] ?? 0;
212
240
  const bookBidBase = bidSuffixBase[lowerBound(bidPrices, price)] ?? 0;
213
241
  const bookAskBase = askPrefixBase[upperBound(askPrices, price)] ?? 0;
214
- const poolBid = poolPrice != null ? poolBidDepth(price, poolPrice, quoteReserve) : 0;
215
- const poolAsk = poolPrice != null ? poolAskDepth(price, poolPrice, quoteReserve) : 0;
216
- const poolBidBase = poolPrice != null ? poolBidBaseDepth(price, poolPrice, baseReserve) : 0;
217
- const poolAskBase = poolPrice != null ? poolAskBaseDepth(price, poolPrice, baseReserve) : 0;
242
+ const poolBid = poolPrice != null ? poolBidDepth(price, poolPrice, quoteReserve, fee) : 0;
243
+ const poolAsk = poolPrice != null ? poolAskDepth(price, poolPrice, quoteReserve, fee) : 0;
244
+ const poolBidBase = poolPrice != null ? poolBidBaseDepth(price, poolPrice, baseReserve, fee) : 0;
245
+ const poolAskBase = poolPrice != null ? poolAskBaseDepth(price, poolPrice, baseReserve, fee) : 0;
218
246
  series.bookBid.push(bookBid);
219
247
  series.poolBid.push(poolBid);
220
248
  series.bookAsk.push(bookAsk);
@@ -226,5 +254,5 @@ function buildDepthSeries(input) {
226
254
  }
227
255
  return series;
228
256
  }
229
- export { DEFAULT_STEPS, normalizeOrderBook, computePoolPrice, computeBookStats, resolvePriceWindow, buildDepthSeries, poolBidDepth, poolAskDepth, poolBidBaseDepth, poolAskBaseDepth, };
257
+ export { DEFAULT_STEPS, normalizeOrderBook, computePoolPrice, computeBookStats, resolvePriceWindow, buildDepthSeries, poolFeeFraction, poolBidPrice, poolAskPrice, poolBidDepth, poolAskDepth, poolBidBaseDepth, poolAskBaseDepth, };
230
258
  //# sourceMappingURL=liquidity_depth_model.js.map