dexbot 1.6.10 → 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 (76) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +1 -0
  3. package/analysis/README.md +49 -11
  4. package/analysis/bot_fitting/README.md +12 -0
  5. package/analysis/tradingview/README.md +2 -2
  6. package/analysis/trend_detection/DYNAMIC_WEIGHT_RESEARCH.md +10 -36
  7. package/analysis/trend_detection/README.md +31 -0
  8. package/claw/package.json +1 -1
  9. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  10. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  11. package/dist/analysis/account_resolver.js +13 -1
  12. package/dist/analysis/analyze_dynamic_weight.js +0 -3
  13. package/dist/analysis/bot_fitting/backtest_ama_sweep.js +51 -7
  14. package/dist/analysis/bot_fitting/backtest_bot_fitting.js +65 -7
  15. package/dist/analysis/bot_fitting/backtest_lookback_drawdown.d.ts +21 -0
  16. package/dist/analysis/bot_fitting/backtest_lookback_drawdown.js +315 -0
  17. package/dist/analysis/bot_key_utils.js +3 -13
  18. package/dist/analysis/fills_cache.d.ts +64 -0
  19. package/dist/analysis/fills_cache.js +254 -0
  20. package/dist/analysis/fills_source.js +5 -2
  21. package/dist/analysis/pnl_report.d.ts +39 -0
  22. package/dist/analysis/pnl_report.js +325 -0
  23. package/dist/analysis/resolve_source.d.ts +0 -1
  24. package/dist/analysis/trade_profitability.d.ts +11 -2
  25. package/dist/analysis/trade_profitability.js +187 -61
  26. package/dist/analysis/tradingview/analyze_tradingview.js +3 -5
  27. package/dist/analysis/tradingview/grid_reset_config.d.ts +2 -0
  28. package/dist/analysis/tradingview/grid_reset_config.js +18 -1
  29. package/dist/analysis/tradingview/grid_reset_sim.d.ts +1 -0
  30. package/dist/analysis/tradingview/grid_reset_sim.js +38 -2
  31. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +2 -1
  32. package/dist/analysis/trend_detection/backtest_ama_slope_huber.d.ts +102 -0
  33. package/dist/analysis/trend_detection/backtest_ama_slope_huber.js +725 -0
  34. package/dist/analysis/trend_detection/dynamic_weight_chart_generator.js +22 -108
  35. package/dist/analysis/trend_detection/huber_scale_variants.d.ts +34 -0
  36. package/dist/analysis/trend_detection/huber_scale_variants.js +176 -0
  37. package/dist/dexbot.js +6 -3
  38. package/dist/market_adapter/core/market_adapter_service.d.ts +15 -0
  39. package/dist/market_adapter/core/market_adapter_service.js +64 -5
  40. package/dist/market_adapter/core/strategies/ama.d.ts +1 -1
  41. package/dist/market_adapter/core/strategies/ama.js +5 -28
  42. package/dist/market_adapter/core/strategies/dynamic_weight_series.d.ts +2 -2
  43. package/dist/market_adapter/core/strategies/dynamic_weight_series.js +2 -2
  44. package/dist/market_adapter/inputs/fetch_cex_synthetic_data.js +1 -2
  45. package/dist/market_adapter/log_format.js +1 -2
  46. package/dist/market_adapter/market_adapter.d.ts +0 -1
  47. package/dist/market_adapter/market_adapter.js +2 -27
  48. package/dist/modules/constants.d.ts +3 -1
  49. package/dist/modules/constants.js +39 -15
  50. package/dist/modules/dexbot_maintenance_runtime.js +12 -0
  51. package/dist/modules/order/accounting.js +25 -0
  52. package/dist/modules/order/format.d.ts +35 -15
  53. package/dist/modules/order/format.js +62 -16
  54. package/dist/modules/order/manager.d.ts +1 -0
  55. package/dist/modules/order/manager.js +22 -1
  56. package/dist/modules/order/sync_engine.js +15 -1
  57. package/dist/modules/order/utils/order.d.ts +21 -1
  58. package/dist/modules/order/utils/order.js +80 -2
  59. package/dist/modules/paths.d.ts +2 -0
  60. package/dist/modules/paths.js +2 -0
  61. package/dist/modules/utils/time_range.d.ts +15 -0
  62. package/dist/modules/utils/time_range.js +18 -0
  63. package/dist/scripts/analyze-orders.js +1 -44
  64. package/dist/scripts/chart_command.js +3 -4
  65. package/dist/scripts/pnl.d.ts +3 -0
  66. package/dist/scripts/pnl.js +40 -0
  67. package/dist/unlock.js +34 -0
  68. package/docs/DEXBOT_COMPARISON.md +3 -3
  69. package/docs/EVOLUTION.md +10 -9
  70. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  71. package/docs/GRID_RECALCULATION.md +12 -15
  72. package/docs/README.md +2 -2
  73. package/docs/WORKFLOW.md +1 -0
  74. package/market_adapter/README.md +4 -26
  75. package/package.json +1 -1
  76. package/scripts/README.md +14 -0
package/dist/unlock.js CHANGED
@@ -977,6 +977,40 @@ async function handleControl({ cmd, target }) {
977
977
  }
978
978
  }
979
979
  }
980
+ // Worker drain: SIGTERM to the wrapper usually tears the
981
+ // supervisor tree down with it, but a dexbot worker can
982
+ // outlive the parent briefly — or keep running when the kill
983
+ // was swallowed. A `dexbot start` immediately after `stop`
984
+ // would then spawn a SECOND worker over the still-live orders
985
+ // (duplicate trades). Wait for every dexbot worker to actually
986
+ // die before returning.
987
+ if (monolithicExited) {
988
+ const workerPaths = candidateRuntimeScriptPaths(['dexbot']);
989
+ const drainDeadlineMs = 15000;
990
+ const drainStarted = Date.now();
991
+ let drained = false;
992
+ while (Date.now() - drainStarted < drainDeadlineMs) {
993
+ const aliveWorkers = [];
994
+ try {
995
+ for (const procEntry of fs.readdirSync('/proc')) {
996
+ const wpid = Number(procEntry);
997
+ if (!Number.isInteger(wpid) || wpid <= 0)
998
+ continue;
999
+ if (pidMatchesScriptCandidates(wpid, workerPaths))
1000
+ aliveWorkers.push(wpid);
1001
+ }
1002
+ }
1003
+ catch (_) { /* /proc scan is best-effort */ }
1004
+ if (aliveWorkers.length === 0) {
1005
+ drained = true;
1006
+ break;
1007
+ }
1008
+ await new Promise((res) => setTimeout(res, 250));
1009
+ }
1010
+ if (!drained) {
1011
+ console.warn(`dexbot stop: worker process(es) still alive after ${drainDeadlineMs}ms — not waiting longer (state kept; a start may report the running bot).`);
1012
+ }
1013
+ }
980
1014
  }
981
1015
  catch (err) {
982
1016
  if (err.code !== 'ESRCH')
@@ -1,7 +1,7 @@
1
1
  # DEXBot vs DEXBot2 — Detailed Comparison Report
2
2
 
3
3
  > **Date:** 2026-09-02 *(metrics refreshed against local source trees)*
4
- > **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.6.10).
4
+ > **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.6.11).
5
5
  > **Audience:** Developers, contributors, and operators evaluating or migrating between the two projects.
6
6
 
7
7
  ---
@@ -36,7 +36,7 @@
36
36
 
37
37
  | Attribute | DEXBot (original) | DEXBot2 |
38
38
  |---|---|---|
39
- | **Release Track** | 1.0.0 | v1.6.10 |
39
+ | **Release Track** | 1.0.0 | v1.6.11 |
40
40
  | **Language** | Python 3.6+ | TypeScript 5.x |
41
41
  | **Status** | Released 1.0.0, unmaintained | Active development |
42
42
  | **Last Repo Activity** | May 23, 2020 | 2026-09-02 |
@@ -776,7 +776,7 @@ Where:
776
776
 
777
777
  | Metric | DEXBot | DEXBot2 |
778
778
  |---|---|---|
779
- | **Release Track** | 1.0.0 | v1.6.10 |
779
+ | **Release Track** | 1.0.0 | v1.6.11 |
780
780
  | **Active Since** | ~2018 | December 2025 |
781
781
  | **Last Commit** | May 23, 2020 | 2026-09-02 |
782
782
  | **Total Commits** | 2281 | 2,125 (v1.4.25) |
package/docs/EVOLUTION.md CHANGED
@@ -2,14 +2,14 @@
2
2
 
3
3
  ## Executive Summary
4
4
 
5
- DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.6.10 release.
5
+ DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.6.11 release.
6
6
 
7
7
  ### Key Milestones
8
8
  - **Project Inception**: December 2, 2025
9
- - **Growth Phase**: 2,315 commits over ~9 active months
9
+ - **Growth Phase**: 2,322 commits over ~9 active months
10
10
  - **Code Maturity**: Evolution from basic utilities to a ~100,000+ LoC intelligent TypeScript system
11
- - **Stability**: Progression from manual testing to a suite of 305 automated test files
12
- - **Releases**: 142 version entries in the changelog (v0.1.0 to v1.6.10)
11
+ - **Stability**: Progression from manual testing to a suite of 307 automated test files
12
+ - **Releases**: 143 version entries in the changelog (v0.1.0 to v1.6.11)
13
13
 
14
14
  > **Post-1.0.0 "why":** the thematic story behind the hardening releases — root cause, recurring
15
15
  > bug families, and lessons — lives in
@@ -143,13 +143,13 @@ Evolved from a basic README to a comprehensive framework (50+ docs entries, 80%+
143
143
 
144
144
  ## Post-1.0.0 Status
145
145
 
146
- **Completed**: browser-safe core; credit/MPA runtime; storage-adapter I/O centralization; self-healing recovery; Kibana PnL analytics; credit-only mode; Docker support; npm package. For the grid order engine arc specifically (COW pipeline, orphan/self-trade/fill-guard hardening, invariants) see [ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md](ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md) §R4.
146
+ **Completed**: browser-safe core; credit/MPA runtime; storage-adapter I/O centralization; self-healing recovery; Kibana PnL analytics — terminal analyzer plus the self-contained HTML report behind `dexbot pnl` (`analysis/pnl_report.ts`), backed by a per-account month-shard fill cache (`analysis/fills_cache.ts`); credit-only mode; Docker support; npm package. For the grid order engine arc specifically (COW pipeline, orphan/self-trade/fill-guard hardening, invariants) see [ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md](ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md) §R4.
147
147
 
148
148
  **Planned**: backtesting engine (historical candle replay via exchange abstraction); injectable interfaces at call boundaries; SQLite persistence + Zod validation at the blockchain boundary; Telegram bot (**not yet implemented**) — owner-gated monitoring (`/status`, `/orders`, `/grid`, `/balance`) and opt-in+confirm gated control (`/start`, `/stop`, `/pause`); DEXBot is the only writer, private keys never reach the module (`TELEGRAM` block + `DEXBOT_TELEGRAM_TOKEN` env).
149
149
 
150
150
  ## Version History
151
151
 
152
- Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` over the current history (2026-10-01), so the column sums to 2,209 — the 106 commits before the `v0.1.0` tag are not attributed to an era (2,209 + 106 = 2,315). Per-release detail lives in [CHANGELOG.md](../CHANGELOG.md); the thematic post-1.0.0 story in [ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md](ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md).
152
+ Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` over the current history (2026-10-02), so the column sums to 2,215 — the 107 commits up to and including the `v0.1.0` tag are not attributed to an era (2,215 + 107 = 2,322). Per-release detail lives in [CHANGELOG.md](../CHANGELOG.md); the thematic post-1.0.0 story in [ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md](ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md).
153
153
 
154
154
  | Era | Commits | Theme |
155
155
  |-----|--------:|-------|
@@ -168,11 +168,12 @@ Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` o
168
168
  | v1.6.7 → v1.6.8 | 14 | Correction-drain budget + broadcast-deferral bounds, PM2 log capture + rotation, passive version notice, genesis-ladder refusal, reserve window exclusion, legacy tolerance-matcher removal, npm-tarball trim, TV grid-reset replay, bounded Kibana tail refresh, 1.4x range-threshold widening |
169
169
  | v1.6.8 → v1.6.9 | 6 | Market-adapter cycle-CPU cuts, candle-boundary off-hour idle, spread-correction spread-tightening guard |
170
170
  | v1.6.9 → v1.6.10 | 7 | Huber-robust AMA slope, asset-pair uppercase canonicalization, TradingView indicator ownership (auto opt-in, span bounds) and chart-view preservation |
171
+ | v1.6.10 → v1.6.11 | 6 | AMA-slope 3-bar persistence gate + 16h Huber lookback, EMA-smoothing removal, PnL HTML report + month-shard fill cache, five order-engine/lifecycle safety fixes |
171
172
 
172
173
  ---
173
174
 
174
175
  **Report Originally Generated**: February 19, 2026
175
- **Last Updated**: October 1, 2026
176
- **Total Commits**: 2,315
177
- **Date Range**: December 2, 2025 – October 1, 2026
176
+ **Last Updated**: October 2, 2026
177
+ **Total Commits**: 2,322
178
+ **Date Range**: December 2, 2025 – October 2, 2026
178
179
  **Repository**: DEXBot2 (BitShares DEX Trading Bot)
@@ -801,4 +801,4 @@ To prevent "Time-of-Check to Time-of-Use" errors:
801
801
  **TOCTOU protection in `processFillAccounting`.** `_buildBtsDeferredRefundAdjustment` reads `btsFeeState` from `mgr.orders` while the order lock is held — the lock is acquired before accounting runs, and the POST-RESET and BOOTSTRAP tracked-fill accounting paths follow the same locking pattern.
802
802
 
803
803
  ---
804
- *Technical Reference for DEXBot2 v1.6.10 release*
804
+ *Technical Reference for DEXBot2 v1.6.11 release*
@@ -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
@@ -286,9 +273,19 @@ Drift` (`AMA-Slope Δ`). An explicit `amaSlopeDeltaThresholdPercent` in
286
273
  directly as a percent-per-bar threshold (the same unit as the slope value
287
274
  described below — no averaging is implied by the unit).
288
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
+
289
286
  AMA slope values are stored and compared in percent per bar. The value itself
290
287
  is a **Huber-robust linear regression of `ln(AMA)` over the lookback window**
291
- (`computeHuberWindowSlopePct` in
288
+ (`DYNAMIC_WEIGHT_AMA_LOOKBACK_BARS`, default `16` bars; `computeHuberWindowSlopePct` in
292
289
  `core/strategies/dynamic_weight_series.ts`; its tuning lives in
293
290
  `MARKET_ADAPTER.DYNAMIC_WEIGHT_AMA_HUBER`) — a smooth, robust fit whose influence
294
291
  function is bounded, so one outlier bar cannot drag it, which is what a plain
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.10 (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:
@@ -806,7 +800,8 @@ Main override knobs live in `profiles/market_adapter_settings.json`:
806
800
  | `dw` | Kalman displacement weighting |
807
801
  | `gain` | Output amplitude |
808
802
  | `amaSlopePercentMode` | Slope override units: `perBar` for 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 |
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.10",
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.