dexbot 1.6.9 → 1.6.11

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 (96) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +1 -0
  3. package/analysis/README.md +50 -12
  4. package/analysis/bot_fitting/README.md +12 -0
  5. package/analysis/tradingview/README.md +15 -10
  6. package/analysis/trend_detection/DYNAMIC_WEIGHT_RESEARCH.md +10 -36
  7. package/analysis/trend_detection/README.md +31 -0
  8. package/claw/modules/chain_queries.ts +9 -4
  9. package/claw/modules/claw_bridge.ts +9 -9
  10. package/claw/package.json +1 -1
  11. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  12. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  13. package/dist/analysis/account_resolver.js +13 -1
  14. package/dist/analysis/ama_fitting/optimizer_high_resolution.js +2 -1
  15. package/dist/analysis/analyze_dynamic_weight.js +0 -3
  16. package/dist/analysis/bot_fitting/backtest_ama_sweep.js +52 -8
  17. package/dist/analysis/bot_fitting/backtest_bot_fitting.js +68 -10
  18. package/dist/analysis/bot_fitting/backtest_lookback_drawdown.d.ts +21 -0
  19. package/dist/analysis/bot_fitting/backtest_lookback_drawdown.js +315 -0
  20. package/dist/analysis/bot_key_utils.js +17 -17
  21. package/dist/analysis/fills_cache.d.ts +64 -0
  22. package/dist/analysis/fills_cache.js +254 -0
  23. package/dist/analysis/fills_source.js +5 -2
  24. package/dist/analysis/pnl_report.d.ts +39 -0
  25. package/dist/analysis/pnl_report.js +325 -0
  26. package/dist/analysis/resolve_source.d.ts +0 -1
  27. package/dist/analysis/trade_profitability.d.ts +11 -2
  28. package/dist/analysis/trade_profitability.js +187 -61
  29. package/dist/analysis/tradingview/analyze_tradingview.d.ts +0 -3
  30. package/dist/analysis/tradingview/analyze_tradingview.js +6 -19
  31. package/dist/analysis/tradingview/grid_reset_config.d.ts +2 -0
  32. package/dist/analysis/tradingview/grid_reset_config.js +18 -1
  33. package/dist/analysis/tradingview/grid_reset_sim.d.ts +12 -1
  34. package/dist/analysis/tradingview/grid_reset_sim.js +60 -11
  35. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +180 -33
  36. package/dist/analysis/trend_detection/backtest_ama_slope_huber.d.ts +102 -0
  37. package/dist/analysis/trend_detection/backtest_ama_slope_huber.js +725 -0
  38. package/dist/analysis/trend_detection/dynamic_weight_chart_generator.js +29 -110
  39. package/dist/analysis/trend_detection/huber_scale_variants.d.ts +34 -0
  40. package/dist/analysis/trend_detection/huber_scale_variants.js +176 -0
  41. package/dist/dexbot.js +19 -11
  42. package/dist/market_adapter/core/market_adapter_service.d.ts +15 -0
  43. package/dist/market_adapter/core/market_adapter_service.js +64 -5
  44. package/dist/market_adapter/core/strategies/ama.d.ts +1 -1
  45. package/dist/market_adapter/core/strategies/ama.js +5 -28
  46. package/dist/market_adapter/core/strategies/ama_slope_model.d.ts +2 -2
  47. package/dist/market_adapter/core/strategies/ama_slope_model.js +12 -10
  48. package/dist/market_adapter/core/strategies/dynamic_weight_series.d.ts +41 -14
  49. package/dist/market_adapter/core/strategies/dynamic_weight_series.js +138 -30
  50. package/dist/market_adapter/inputs/fetch_cex_synthetic_data.js +1 -2
  51. package/dist/market_adapter/log_format.js +1 -2
  52. package/dist/market_adapter/lp_chart_strategy_loader.js +2 -1
  53. package/dist/market_adapter/market_adapter.d.ts +0 -1
  54. package/dist/market_adapter/market_adapter.js +2 -27
  55. package/dist/market_adapter/utils/chain.d.ts +1 -1
  56. package/dist/market_adapter/utils/chain.js +8 -6
  57. package/dist/modules/account_bots.js +5 -4
  58. package/dist/modules/bitshares-native/resolvers.js +5 -0
  59. package/dist/modules/bot_settings.js +13 -1
  60. package/dist/modules/chain_orders.js +2 -1
  61. package/dist/modules/constants.d.ts +9 -1
  62. package/dist/modules/constants.js +55 -9
  63. package/dist/modules/credential_policy.js +4 -1
  64. package/dist/modules/credit_runtime.js +5 -1
  65. package/dist/modules/dexbot_maintenance_runtime.js +12 -0
  66. package/dist/modules/order/accounting.js +25 -0
  67. package/dist/modules/order/format.d.ts +35 -15
  68. package/dist/modules/order/format.js +62 -16
  69. package/dist/modules/order/manager.d.ts +1 -0
  70. package/dist/modules/order/manager.js +22 -1
  71. package/dist/modules/order/sync_engine.js +15 -1
  72. package/dist/modules/order/utils/order.d.ts +21 -1
  73. package/dist/modules/order/utils/order.js +80 -2
  74. package/dist/modules/order/utils/system.js +11 -1
  75. package/dist/modules/paths.d.ts +2 -0
  76. package/dist/modules/paths.js +2 -0
  77. package/dist/modules/utils/asset_symbols.d.ts +59 -0
  78. package/dist/modules/utils/asset_symbols.js +128 -0
  79. package/dist/modules/utils/time_range.d.ts +15 -0
  80. package/dist/modules/utils/time_range.js +18 -0
  81. package/dist/scripts/analyze-credit.js +10 -7
  82. package/dist/scripts/analyze-orders.js +1 -44
  83. package/dist/scripts/chart_command.js +15 -8
  84. package/dist/scripts/pnl.d.ts +3 -0
  85. package/dist/scripts/pnl.js +40 -0
  86. package/dist/scripts/verify-browser-bundle.js +8 -0
  87. package/dist/unlock.js +34 -0
  88. package/docs/DEXBOT_COMPARISON.md +3 -3
  89. package/docs/EVOLUTION.md +12 -10
  90. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  91. package/docs/GRID_RECALCULATION.md +33 -17
  92. package/docs/README.md +2 -2
  93. package/docs/WORKFLOW.md +1 -0
  94. package/market_adapter/README.md +6 -28
  95. package/package.json +1 -1
  96. package/scripts/README.md +14 -0
@@ -160,8 +160,7 @@ node dist/market_adapter/market_adapter.js --deltaPercent 2
160
160
  "ama": {
161
161
  "erPeriod": 10, // Efficiency Ratio lookback period (candles)
162
162
  "fastPeriod": 2, // Fast smoothing period for trending markets
163
- "slowPeriod": 30, // Slow smoothing period for choppy markets
164
- "erSmoothPeriod": 0 // Optional ER smoothing; 0 disables it
163
+ "slowPeriod": 30 // Slow smoothing period for choppy markets
165
164
  }
166
165
  }
167
166
  ```
@@ -199,23 +198,11 @@ The pool is fetched directly by ID, bypassing pool discovery. Useful when the tr
199
198
  - `slowPeriod`: Smoothing constant for choppy/sideways markets
200
199
  - Higher = more lag, filters noise
201
200
  - Built-in presets range from `AMA1` (fastest) to `AMA4` (slowest) — see `MARKET_ADAPTER.AMAS` in `modules/constants.ts` for the exact `slowPeriod` values
202
- - `erSmoothPeriod`: Optional DEXBot2 extension that smooths Kaufman's raw Efficiency Ratio before the AMA smoothing constant is calculated
203
- - `0`: Disabled, raw Kaufman ER is used directly
204
- - `1`: Effectively no extra smoothing
205
- - `3` to `5`: Light to moderate damping for faster AMAs that re-center too abruptly
206
- - Higher values: More stable ER, but delayed trend/chop recognition
207
- - Values between `0` and `1` are invalid and fall back to the configured default
208
201
 
209
202
  AMA parameters are resolved exclusively from **presets** (`AMA1`–`AMA4`): a matched
210
203
  pair profile in `profiles/market_profiles.json` wins, otherwise the built-in defaults
211
204
  (`MARKET_ADAPTER.AMAS` in `modules/constants.ts`, default key `AMA3`) are used.
212
205
 
213
- `erSmoothPeriod` is not part of canonical Kaufman AMA/KAMA. It is a bot-level
214
- stabilizer for cases where a faster AMA is useful but raw ER spikes cause false
215
- grid re-centering triggers. Market-profile presets still provide `erPeriod`,
216
- `fastPeriod`, and `slowPeriod`; an inline bot `ama.erSmoothPeriod` can be used
217
- with those presets.
218
-
219
206
  ### How It Works
220
207
 
221
208
  1. **Market Adapter** (`market_adapter/market_adapter.ts`) runs continuously
@@ -283,9 +270,38 @@ The snapshot fields involved are:
283
270
  `profiles/general.settings.json` and editable via `dexbot bot` → `1) Grid
284
271
  Drift` (`AMA-Slope Δ`). An explicit `amaSlopeDeltaThresholdPercent` in
285
272
  `profiles/market_adapter_settings.json` bypasses the factor and is used
286
- directly as an average percent-per-bar threshold.
287
-
288
- AMA slope values are stored and compared as average percent per bar. Older
273
+ directly as a percent-per-bar threshold (the same unit as the slope value
274
+ described below — no averaging is implied by the unit).
275
+
276
+ **Persistence gate.** The slope-delta trigger is gated by default: it fires only
277
+ after `AMA_SLOPE_PERSIST_BARS` (default `3`) consecutive bars cross the threshold
278
+ in the same direction, so a 1–2 bar excursion is ignored. A sustained move is
279
+ confirmed K bars after onset — up to K−1 bars later than the ungated trigger;
280
+ the independent price/Drift trigger is unaffected.
281
+ `AMA_SLOPE_PERSIST_ENABLED` (default `true`) is the master switch; a
282
+ bot/market can override via `amaSlope.persistBars` or `amaSlope.persistEnabled`.
283
+ Versus the ungated path this cuts resets ~35% and whipsaws (~52%→~17%) with lag
284
+ and range tilt unchanged.
285
+
286
+ AMA slope values are stored and compared in percent per bar. The value itself
287
+ is a **Huber-robust linear regression of `ln(AMA)` over the lookback window**
288
+ (`DYNAMIC_WEIGHT_AMA_LOOKBACK_BARS`, default `16` bars; `computeHuberWindowSlopePct` in
289
+ `core/strategies/dynamic_weight_series.ts`; its tuning lives in
290
+ `MARKET_ADAPTER.DYNAMIC_WEIGHT_AMA_HUBER`) — a smooth, robust fit whose influence
291
+ function is bounded, so one outlier bar cannot drag it, which is what a plain
292
+ mean (and the older two-point endpoint difference it is equivalent to) would do.
293
+ Because the fit reports the log-return, a reading is ~`ln(1+r)` rather than the
294
+ arithmetic `r`: negligible at the sub-0.1 %/bar magnitudes the defaults use, but
295
+ ~3% lower at a 6%/bar saturation (`ln(1.06)*100 = 5.83`). A pre-existing user
296
+ override of `amaSlope.maxSlopePct` or `neutralZonePct` was tuned against the
297
+ arithmetic reading, so treat a saturated override as a hair tighter than before.
298
+
299
+ Changing the estimator changes the stored value: after a deploy, the first
300
+ cycle compares a new-algorithm reading against the baseline persisted by the
301
+ previous one (`botState.gridRangeScalingAmaSlope`). The magnitudes agree
302
+ closely, so the delta stays under the reset gate on ~98% of bars — a rare,
303
+ single extra recenter for whitelisted bots. No version marker is persisted to
304
+ suppress it. Older
289
305
  settings that used cumulative percent over the full lookback can either be
290
306
  divided by `amaSlope.lookbackBars`, or marked with
291
307
  `"amaSlopePercentMode": "window"` in `profiles/market_adapter_settings.json`
package/docs/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  This directory contains the comprehensive technical documentation for the DEXBot2 trading bot. It is designed to guide developers from high-level architecture down to the nuances of fund accounting and state management.
4
4
 
5
- **Version context:** v1.6.9 (released).
5
+ **Version context:** v1.6.11 (released).
6
6
 
7
7
  ---
8
8
 
@@ -36,7 +36,7 @@ This directory contains the comprehensive technical documentation for the DEXBot
36
36
  - **AMA Fitting**: Parameter fitting, comparison charts, and LP data workflows
37
37
  - **Bot Fitting**: Grid parameter sweep backtests for AMA winners
38
38
  - **TradingView Exports**: Chart export utilities for visual analysis
39
- - **Trade Profitability**: FIFO-based PnL analysis from Kibana fill data (`trade_profitability.ts`)
39
+ - **Trade Profitability**: FIFO-based PnL analysis from Kibana fill data (`trade_profitability.ts`), plus the self-contained HTML report behind `dexbot pnl` (`pnl_report.ts`) with a per-account month-shard fill cache (`fills_cache.ts`)
40
40
  - **Bot Usage Discovery**: On-chain bot account finder and Kibana query helpers (`bot_usage/`)
41
41
 
42
42
  ### 🦀 [Claw](../claw/README.md)
package/docs/WORKFLOW.md CHANGED
@@ -254,6 +254,7 @@ the canonical name is preferred in scripts and docs.
254
254
  | `dexbot credit` | — | Live summed MPA + borrowed-credit positions per asset per bot (`[<bot>]`) |
255
255
  | `dexbot tv <target>` | — | TradingView 1h chart for `<bot|pool-id|AssetA/AssetB>` over `--month N` (default 3) |
256
256
  | `dexbot dw <target>` | — | Dynamic-weight research chart: same targets/flags as `tv` |
257
+ | `dexbot pnl <account>` | — | HTML PnL report for a bot/account over `--month N`, optional `--pair BASE/QUOTE` filter |
257
258
  | `dexbot status` | `stat`, `stats` | Unified runtime health — daemon, adapter, bots |
258
259
  | `dexbot start` | `unlock` | Run credential daemon + bot (equivalent to running the `unlock` runtime, `dist/unlock.js`) |
259
260
  | `dexbot stop` | `stp`, `stopall` | Stop the monolithic runtime (unlock mode) |
@@ -95,12 +95,6 @@ the pair's `defaultAma` from
95
95
  `gridPrice: "ama4"` force a specific preset. If no pair profile matches, the
96
96
  bot's `ama` block is used as the fallback.
97
97
 
98
- Bots can optionally add `ama.erSmoothPeriod` to smooth Kaufman's raw Efficiency
99
- Ratio before it enters the AMA smoothing-constant formula. The default is `0`,
100
- which disables this DEXBot2 extension and preserves raw Kaufman behavior. Useful
101
- values start around `3` to `5` when a faster AMA is desired but raw ER spikes
102
- cause abrupt grid-center changes.
103
-
104
98
  ### Empirical Divergence Risk Management
105
99
 
106
100
  The adapter uses tiered clamping thresholds to manage inventory risk during extreme price divergence from the AMA trend center. These thresholds are derived from historical pool volatility and replace static 'fit cap' multipliers. The specific clamping limits and exit parameters are calculated per pair and preset using the AMA fitting toolchain:
@@ -688,7 +682,7 @@ This uses `dynamicWeights.trend`, `dynamicWeights.slopeOffset`, and
688
682
  weight shift. The whitelist flag is `asymmetricBounds`.
689
683
 
690
684
  ```
691
- slope = average AMA slope percent per bar over the lookback window
685
+ slope = Huber-robust regression of ln(AMA) over the lookback window, in percent per bar
692
686
  slopeOffset = slope normalized to the configured dynamic-weight slope cap
693
687
  asymmetry = min(|slopeOffset| / maxSlopeOffset, 1) × maxAsymmetryFactor
694
688
 
@@ -805,8 +799,9 @@ Main override knobs live in `profiles/market_adapter_settings.json`:
805
799
  | `alpha` | AMA vs Kalman blend |
806
800
  | `dw` | Kalman displacement weighting |
807
801
  | `gain` | Output amplitude |
808
- | `amaSlopePercentMode` | Slope override units: `perBar` for average percent per bar, or `window`/unset for legacy cumulative percent over the lookback |
809
- | `amaSlope.lookbackBars` | AMA slope lookback; slope is averaged per bar over this window |
802
+ | `amaSlopePercentMode` | Slope override units: `perBar` for percent per bar, or `window`/unset for legacy cumulative percent over the lookback |
803
+ | `amaSlope.lookbackBars` | AMA slope lookback; slope is averaged per bar over this window (default 16) |
804
+ | `amaSlope.persistBars` | Slope-delta persistence gate: consecutive confirming bars required before the slope reset fires (default 3; `1` = legacy fire-on-first-crossing). Values `< 1` fall through to the global default, so use `1` (or `persistEnabled: false`) to disable, not `0`. Global default in `MARKET_ADAPTER.AMA_SLOPE_PERSIST_*` |
810
805
  | `amaSlope.neutralZonePct` | Dead band around flat average AMA slope |
811
806
  | `amaSlope.maxSlopePct` | Average AMA slope saturation |
812
807
  | `amaSlopeDeltaThresholdPercent` | Average AMA slope delta threshold for slope-based resets |
@@ -876,28 +871,12 @@ bias_remaining(K) ≈ bias_initial × ∏ (1 − SC_i) for i = 1..K
876
871
  Kaufman's smoothing constant is the ER-scaled value, squared:
877
872
 
878
873
  ```
879
- SC_i = [ER_effective_i × (fastSC − slowSC) + slowSC]²
874
+ SC_i = [ER_i × (fastSC − slowSC) + slowSC]²
880
875
 
881
876
  where fastSC = 2 / (fastPeriod + 1)
882
877
  slowSC = 2 / (slowPeriod + 1)
883
878
  ```
884
879
 
885
- By default, `ER_effective_i` is Kaufman's raw `ER_i`. If `ama.erSmoothPeriod`
886
- or `MARKET_ADAPTER.AMA_ER_SMOOTH_FAST_PERIOD` is set to `1` or higher, DEXBot2
887
- first applies EMA smoothing to the ER stream:
888
-
889
- ```
890
- ER_effective_i = ER_effective_(i-1) + erSmoothAlpha × (ER_i − ER_effective_(i-1))
891
-
892
- where erSmoothAlpha = 2 / (erSmoothPeriod + 1)
893
- ```
894
-
895
- This ER smoothing is not part of canonical Kaufman AMA/KAMA. It is an optional
896
- DEXBot2 stabilizer for fast AMAs: it can reduce false or jerky re-centering
897
- caused by one-window ER spikes, at the cost of slower recognition when the
898
- market genuinely changes regime. `erSmoothPeriod = 0` disables it; `1` is
899
- effectively no extra smoothing; `3` to `5` are typical light/moderate values.
900
-
901
880
  Because `ER_i` varies bar-by-bar, a **typical-market ER** (`ER_avg`) is used to
902
881
  estimate an average decay rate:
903
882
 
@@ -915,14 +894,13 @@ The adapter keeps the **full warmup window** in candle history so the AMA seed
915
894
  and convergence bias are retained for downstream calculations:
916
895
 
917
896
  ```
918
- amaWarmupBars = erPeriod + convergenceBars + erSmoothConvergenceBars + lookbackBars
897
+ amaWarmupBars = erPeriod + convergenceBars + lookbackBars
919
898
  ```
920
899
 
921
900
  | Component | Role |
922
901
  |-----------|------|
923
902
  | `erPeriod` | Bars for the first Efficiency Ratio value to become available |
924
903
  | `convergenceBars` | Bars to decay 99 % of the cold-start initialisation bias |
925
- | `erSmoothConvergenceBars` | Extra ER EMA convergence bars when `erSmoothPeriod >= 1`; `0` when ER smoothing is disabled |
926
904
  | `lookbackBars` | Extra lookback for slope/trend analysis (AMA slope, ATR) |
927
905
 
928
906
  For **AMA slope readiness and percentile clipping**, the earlier gate is:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dexbot",
3
- "version": "1.6.9",
3
+ "version": "1.6.11",
4
4
  "description": "The first open source trading bot with zero runtime dependencies and a fully adaptive market making strategy.",
5
5
  "main": "dist/modules/dexbot_class.js",
6
6
  "exports": {
package/scripts/README.md CHANGED
@@ -417,6 +417,20 @@ dexbot dw BTS/HONEST.USD --feed --month 1
417
417
  ```
418
418
  Research knobs (`--alpha`, `--gain`, `--dw`, `--lb`, `--clip`) stay on the analyzer itself — call `node dist/analysis/analyze_dynamic_weight.js` directly for parameter sweeps (see `analysis/README.md`).
419
419
 
420
+ ### PnL Report (`dexbot pnl`)
421
+ **File:** `pnl.ts` (thin entry; analyzer + HTML renderer: `analysis/trade_profitability.ts` + `analysis/pnl_report.ts`)
422
+ **Purpose:** Resolve a bot profile (local-first), account name, or `1.2.x` id, fetch the account's fills for the requested window, and write a self-contained HTML PnL report (summary cards, performance metrics, realized-lot table). Terminal tables stay available by running the analyzer directly.
423
+ **Output:** `analysis/charts/pnl_<bot|account>[_<pair>]_<range>.html`
424
+ **Cache:** per-account fill shards under `analysis/cache/fills/` (settled months are reused; the unsettled tail is re-queried). `--refresh-account` bypasses it.
425
+ ```bash
426
+ # HTML PnL report for a local bot, last 3 months
427
+ dexbot pnl <bot> --month 3
428
+ # Filter a multi-pair account to one pair
429
+ dexbot pnl 1.2.123456 --month 6 --pair TOKENA/BTS
430
+ # Custom output path
431
+ dexbot pnl <bot> --month 1 --report analysis/charts/custom-pnl.html
432
+ ```
433
+
420
434
  ### LP Chart
421
435
  **File:** `generate_lp_chart.ts`
422
436
  **Purpose:** Generate the standard uPlot LP chart output.