dexbot 1.6.16 โ†’ 1.6.17

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 (60) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/analysis/tradingview/README.md +2 -2
  3. package/analysis/trend_detection/DYNAMIC_WEIGHT_RESEARCH.md +1 -1
  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/ama_fitting/analyze_lambda_vs_slow.js +5 -3
  8. package/dist/analysis/tradingview/grid_reset_sim.js +1 -1
  9. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +4 -4
  10. package/dist/analysis/trend_detection/backtest_ama_slope_huber.js +1 -1
  11. package/dist/modules/account_bots.d.ts +3 -0
  12. package/dist/modules/chain_keys.d.ts +1 -1
  13. package/dist/modules/constants.d.ts +6 -0
  14. package/dist/modules/constants.js +34 -6
  15. package/dist/modules/credit_pricing.d.ts +20 -1
  16. package/dist/modules/credit_pricing.js +23 -1
  17. package/dist/modules/credit_runtime.js +33 -16
  18. package/dist/modules/dexbot_class.d.ts +3 -1
  19. package/dist/modules/dexbot_class.js +5 -2
  20. package/dist/modules/dexbot_cow_runtime.d.ts +28 -37
  21. package/dist/modules/dexbot_cow_runtime.js +47 -66
  22. package/dist/modules/dexbot_maintenance_runtime.js +68 -10
  23. package/dist/modules/launcher/credential_daemon.d.ts +14 -2
  24. package/dist/modules/launcher/credential_daemon.js +60 -26
  25. package/dist/modules/order/grid.d.ts +7 -0
  26. package/dist/modules/order/grid.js +157 -15
  27. package/dist/modules/order/index.d.ts +15 -0
  28. package/dist/modules/order/manager.d.ts +30 -7
  29. package/dist/modules/order/manager.js +108 -12
  30. package/dist/modules/order/strategy.d.ts +5 -0
  31. package/dist/modules/order/strategy.js +23 -2
  32. package/dist/modules/order/utils/math.d.ts +41 -1
  33. package/dist/modules/order/utils/math.js +47 -1
  34. package/dist/modules/order/utils/order.d.ts +13 -0
  35. package/dist/modules/order/utils/order.js +61 -7
  36. package/dist/modules/order/utils/system.d.ts +66 -0
  37. package/dist/modules/order/utils/system.js +135 -0
  38. package/dist/modules/order/utils/validate.d.ts +3 -1
  39. package/dist/modules/order/utils/validate.js +5 -1
  40. package/dist/modules/types.d.ts +35 -2
  41. package/dist/scripts/analyze-credit.js +64 -23
  42. package/dist/scripts/bts_distribution.d.ts +66 -0
  43. package/dist/scripts/bts_distribution.js +2102 -0
  44. package/dist/scripts/token_distribution.d.ts +45 -0
  45. package/dist/scripts/token_distribution.js +1870 -0
  46. package/dist/unlock.js +42 -24
  47. package/docs/COW_INVARIANTS.md +6 -0
  48. package/docs/DEXBOT_COMPARISON.md +5 -5
  49. package/docs/EVOLUTION.md +9 -8
  50. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +3 -1
  51. package/docs/GRID_PRICE_INVARIANT.md +6 -0
  52. package/docs/GRID_RECALCULATION.md +3 -3
  53. package/docs/LOGGING.md +9 -0
  54. package/docs/MPA_CREDIT_USAGE.md +3 -2
  55. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +117 -0
  56. package/docs/README.md +1 -1
  57. package/docs/architecture.md +98 -1
  58. package/market_adapter/README.md +2 -2
  59. package/package.json +3 -1
  60. package/scripts/README.md +85 -148
package/scripts/README.md CHANGED
@@ -19,93 +19,34 @@ dexbot update
19
19
 
20
20
  ## ๐Ÿงน CLEANING & RESET (DANGER ZONE)
21
21
 
22
- All clear/reset scripts resolve their directories via `scripts/lib/dexbot-paths.sh`,
23
- which mirrors `modules/paths.ts`. Defaults depend on the install type:
22
+ All clear/reset scripts resolve paths through `scripts/lib/dexbot-paths.sh`
23
+ (mirrors `modules/paths.ts`). Env overrides: `DEXBOT_PROFILE_ROOT`,
24
+ `DEXBOT_MARKET_ADAPTER_DATA_DIR`, `DEXBOT_MARKET_ADAPTER_STATE_DIR`,
25
+ `DEXBOT_CLAW_DATA_DIR`; the `dexbot` CLI passes the resolved dirs automatically.
24
26
 
25
27
  | Install | Profile root | Market adapter data/state | Claw data |
26
28
  |---------|--------------|---------------------------|-----------|
27
29
  | Source checkout | `<repo>/profiles` | `<repo>/market_adapter/{data,state}` | `<repo>/claw/data` |
28
30
  | Global npm (`npm i -g dexbot`) | `~/.config/dexbot2/profiles` | `<profiles>/market_adapter/{data,state}` | `<profiles>/claw/data` |
29
31
 
30
- Env overrides: `DEXBOT_PROFILE_ROOT`, `DEXBOT_MARKET_ADAPTER_DATA_DIR`,
31
- `DEXBOT_MARKET_ADAPTER_STATE_DIR`, `DEXBOT_CLAW_DATA_DIR`. When run through the
32
- `dexbot` CLI, the resolved runtime dirs are passed automatically, so the CLI
33
- always clears the same dirs the runtime uses.
34
-
35
- **Two behaviors are shared by all four `clear-*` scripts** (helpers in
36
- `scripts/lib/dexbot-paths.sh`):
37
-
38
- - **Advisory live-runtime warning.** Before the confirmation prompt, the scripts
39
- read `<profiles>/{monolithic,monolithic-bot,monolithic-cred}.pid` and โ€” only when
40
- the PM2 daemon is already up, so a cleanup script can never spawn one โ€” the
41
- online PM2 apps belonging to this install (`pm2 jlist`, filtered to
42
- `cwd`/`script_path` under the project or profiles root). If anything is found, a
43
- `YELLOW` warning is printed. It is **advisory**: the prompt still runs, the
44
- deletion still happens, and the exit code is unchanged. The reason it matters:
45
- a live bot re-persists its grid within seconds, a live adapter rewrites its
46
- state file *and* `market_adapter.lock` (a deleted lock lets a second adapter
47
- start), and open log FDs mean the disk space is only reclaimed on restart. Stop
48
- first with `dexbot stop` / `dexbot pm2 stop all`.
49
- - **One log predicate.** Every `find` over the logs directory goes through
50
- `log_files` (`*.log`, rotated `*.log.*`, `*.jsonl*`), so the preview, the count,
51
- the delete and the verification can never disagree. `*.jsonl*` also sweeps the
52
- credential audit trail `logs/daemon-audit.jsonl` **and** its rotated
53
- `daemon-audit.jsonl.1` siblings, which match no other pattern โ€” they used to
54
- survive a "clear" and leave a partial wipe. The audit trail is deleted with
55
- everything else, with no extra prompt and no opt-in flag; it is only named in
56
- the preview (`Includes the credential audit trail: daemon-audit.jsonl*`) so the
57
- deletion is never a surprise.
58
-
59
- ### Wipe Logs
60
- **File:** `clear-logs.sh`
61
- **Purpose:** Delete all bot `.log` and `.jsonl` files, including `profiles/logs/market_adapter.log`.
62
- ```bash
63
- # IRREVERSIBLE: Deletes all files in profiles/logs/*.log and *.jsonl, including market_adapter.log
64
- # (also the credential audit trail daemon-audit.jsonl and its rotated siblings)
65
- # Prompts for confirmation before deleting; warns first if a runtime is live.
66
- bash scripts/clear-logs.sh
67
- ```
68
-
69
- ### Wipe Orders
70
- **File:** `clear-orders.sh`
71
- **Purpose:** Delete all persistent order state files.
72
- ```bash
73
- # IRREVERSIBLE: Deletes all files in profiles/orders/*
74
- # Prompts for confirmation before deleting.
75
- bash scripts/clear-orders.sh
76
- ```
32
+ Shared behavior:
33
+ - **Advisory live-runtime warning.** Before the prompt the scripts check runtime
34
+ PIDs and this install's online PM2 apps. A live bot re-persists its grid and a
35
+ live adapter can recreate its state/lock, so stop first with `dexbot stop`.
36
+ The warning never blocks the deletion or changes the exit code.
37
+ - **One log predicate** (`*.log`, rotated `*.log.*`, `*.jsonl*`) so preview,
38
+ count, delete and verify always agree. It also removes the credential audit
39
+ trail `daemon-audit.jsonl*`, which is named in the preview.
77
40
 
78
- ### Clear Market Adapter State
79
- **File:** `clear-market-adapter.sh`
80
- **Purpose:** Delete all market adapter candle data, state files, and runtime logs.
81
- ```bash
82
- # IRREVERSIBLE: Removes market_adapter/{data,state}/ and profiles/logs/{market_adapter,dexbot-adapter,dexbot-adapter-error}.log
83
- # (paths relocate under the profiles dir for global npm installs)
84
- # Prompts for confirmation before deleting.
85
- bash scripts/clear-market-adapter.sh
86
- ```
87
-
88
- ### Wipe Orders + Logs + Market Adapter + Claw
89
- **File:** `clear-all.sh`
90
- **Purpose:** Delete order state files, log files, market adapter data/state, and claw data in one confirmed operation.
91
- ```bash
92
- # IRREVERSIBLE: Deletes profiles/orders/*, profiles/logs/*.{log,jsonl},
93
- # market_adapter/{data,state}/*, and claw data (positions.json, watcher-health.json, memu/) under
94
- # <profiles>/claw/data (or <repo>/claw/data for source checkouts).
95
- # Also deletes daemon-audit.jsonl and its rotated siblings.
96
- # Prompts for confirmation before deleting; warns first if a runtime is live.
97
- bash scripts/clear-all.sh
98
- ```
41
+ | Script | Deletes |
42
+ |:---|:---|
43
+ | `clear-logs.sh` | `<profiles>/logs/*.{log,jsonl}`, including market adapter logs and `daemon-audit.jsonl*` |
44
+ | `clear-orders.sh` | `<profiles>/orders/*` |
45
+ | `clear-market-adapter.sh` | market adapter `data/`, `state/`, and its runtime logs |
46
+ | `clear-all.sh` | orders + logs + market adapter data/state + claw data |
47
+ | `reset-settings.sh` | general, market and market-adapter settings files (defaults restored next run) |
99
48
 
100
- ### Reset Settings
101
- **File:** `reset-settings.sh`
102
- **Purpose:** Delete the three settings files and restore built-in defaults on next run.
103
- ```bash
104
- # IRREVERSIBLE: Deletes profiles/general.settings.json, profiles/market_profiles.json,
105
- # and profiles/market_adapter_settings.json
106
- # Prompts for confirmation before deleting.
107
- bash scripts/reset-settings.sh
108
- ```
49
+ All are irreversible and prompt for confirmation.
109
50
 
110
51
  ---
111
52
 
@@ -162,6 +103,45 @@ the rename. Note:
162
103
  `get_asset_holders_count` is reported by the node as `distance(range) - 1`, so
163
104
  the `holders=` figure can be off by one.
164
105
 
106
+ ### BTS Supply Distribution
107
+ **File:** `bts_distribution.ts` (npm: `npm run distribution`)
108
+ **Purpose:** Live-chain breakdown of where BTS sits: call-order collateral, global/individual
109
+ settlement funds (plus force-settlement debt and parameters), governance tickets, vesting and
110
+ legacy balances, liquidity pools, SameT/credit funds, HTLC escrow and asset fee pools. The
111
+ remainder is reported as a derived liquid residual and compared with total supply and a derived
112
+ circulating float. Also writes a self-contained HTML donut report to
113
+ `analysis/charts/bts-distribution.html` (`--html PATH`, `--no-html`).
114
+ ```bash
115
+ npm run distribution # terminal + HTML
116
+ node dist/scripts/bts_distribution.js --json # JSON (HTML still written)
117
+ node dist/scripts/bts_distribution.js --circulating <reference-supply>
118
+ node dist/scripts/bts_distribution.js --holders all # full rich list (~5 min)
119
+ ```
120
+ Call-order collateral uses `api_helper_indexes` `total_in_collateral` (falls back to summing
121
+ `get_call_orders`). Top liquid holders come from `asset_api::get_asset_holders`, retrying on a
122
+ node that exposes it; exchange tags are name heuristics, not verified identities. `--holders all`
123
+ also splits the residual into account balances, blinded balances and order books, and adds
124
+ concentration plus balance bands. Read-only: no keys, no transactions.
125
+
126
+ ### Token Distribution
127
+ **File:** `token_distribution.ts` (npm: `npm run token-distribution`)
128
+ **Purpose:** Per-asset companion to BTS Supply Distribution. Buckets a token into free account
129
+ balances, limit orders, liquidity pools, vesting balances, P2P credit offers and deal collateral,
130
+ SameT funds, HTLC escrow, accumulated market fees and blinded supply, then reconciles the total
131
+ against `current_supply`. Liquidity is grouped by counterpart asset (token/BTS, token/USD, ...);
132
+ the HTML report adds a separate liquidity donut plus a 3% price-change liquidity table:
133
+ token sellable (price โˆ’3%) and buyable (+3%), orderbook + pool combined per market and expressed
134
+ as a share of total supply. Writes the report to
135
+ `analysis/charts/token-<SYMBOL>-distribution.html`.
136
+ ```bash
137
+ npm run token-distribution -- <token>
138
+ node dist/scripts/token_distribution.js <asset-id> --json
139
+ node dist/scripts/token_distribution.js <token> --no-orders # skip the ~6k order queries
140
+ ```
141
+ Limit orders have no by-asset index in bitshares-core, so the exact scan queries every listed
142
+ asset concurrently (~20s); vesting balances scan 1.13.x with a gap tolerance. Read-only: no keys,
143
+ no transactions. BTS itself is rejected; use `npm run distribution`.
144
+
165
145
  ### Configuration Audit
166
146
  **File:** `validate_bots.ts`
167
147
  **Purpose:** Check `bots.json` for schema errors or missing required fields.
@@ -301,35 +281,11 @@ npm run version:sync
301
281
  > global npm package installs (`npm install -g dexbot`). They are intended for
302
282
  > source checkout workflows only.
303
283
 
304
- ### Synchronize test โ†’ dev โ†’ main
305
- **File:** `pmain.sh` (also: `npm run pmain`)
306
- **Purpose:** Sync local test branch through dev to main remote.
307
- ```bash
308
- # Push test โ†’ dev โ†’ main
309
- bash scripts/pmain.sh
310
- # OR
311
- npm run pmain
312
- ```
313
-
314
- ### Synchronize test โ†’ dev
315
- **File:** `pdev.sh` (also: `npm run pdev`)
316
- **Purpose:** Sync local test branch to dev remote.
317
- ```bash
318
- # Push test โ†’ dev
319
- bash scripts/pdev.sh
320
- # OR
321
- npm run pdev
322
- ```
323
-
324
- ### Synchronize local test โ†’ origin/test
325
- **File:** `ptest.sh` (also: `npm run ptest`)
326
- **Purpose:** Push local test branch to remote.
327
- ```bash
328
- # Push test to origin/test
329
- bash scripts/ptest.sh
330
- # OR
331
- npm run ptest
332
- ```
284
+ | Script | npm | Action |
285
+ |:---|:---|:---|
286
+ | `ptest.sh` | `npm run ptest` | push local `test` โ†’ `origin/test` |
287
+ | `pdev.sh` | `npm run pdev` | sync `test` โ†’ `dev` |
288
+ | `pmain.sh` | `npm run pmain` | sync `test` โ†’ `dev` โ†’ `main` |
333
289
 
334
290
  ---
335
291
 
@@ -379,13 +335,6 @@ The following scripts allow you to call `dexbot` commands directly from the `scr
379
335
  | `npm run pm2:start` | Unlock + start bots via PM2 (alias of `pm2:unlock`) |
380
336
  | `npm run pm2:stop` | Stop all dexbot PM2 processes via the launcher |
381
337
 
382
- ### Branch Sync *(git checkout only)*
383
- | Command | Purpose |
384
- |:---|:---|
385
- | `npm run ptest` | Push local test โ†’ origin/test |
386
- | `npm run pdev` | Sync local test โ†’ dev |
387
- | `npm run pmain` | Sync local test โ†’ dev โ†’ main |
388
-
389
338
  ### Version
390
339
  | Command | Purpose |
391
340
  |:---|:---|
@@ -401,6 +350,8 @@ The following scripts allow you to call `dexbot` commands directly from the `scr
401
350
  | `npm run analysis:grid-check` | Last-fill-guard check (`grid_correction_check.ts`) |
402
351
  | `npm run analysis:resolve-accounts` | Batch-resolve on-chain bot accounts (`resolve_bot_accounts.ts`) |
403
352
  | `npm run richlist` | Per-asset rich list / top holder (`rich_list.ts`) |
353
+ | `npm run distribution` | BTS supply distribution + HTML donut report (`bts_distribution.ts`) |
354
+ | `npm run token-distribution` | Per-token supply distribution + HTML report (`token_distribution.ts`) |
404
355
  | `npm run ama:chart:lp-local` | Generate local LP comparison chart |
405
356
  | `npm run lp:chart` | Generate uPlot LP chart |
406
357
  | `npm run test:credit-renewal` | Test credit offer renewal for a specific bot |
@@ -418,36 +369,35 @@ The following scripts allow you to call `dexbot` commands directly from the `scr
418
369
 
419
370
  ## ๐Ÿ“ˆ CHART GENERATION
420
371
 
421
- `dexbot tv` and `dexbot dw` share ONE fetch pipeline ([`chart_command.ts`](chart_command.ts)): identical target resolution, source routing, cached candle chunks, and temp-file handoff โ€” only the renderer registration (`RENDERERS` table) differs.
372
+ `dexbot tv` and `dexbot dw` share the `chart_command.ts` pipeline (target
373
+ resolution, source routing, cached monthly candle chunks); only the renderer
374
+ differs. Both write to `analysis/charts/` and support `--month`, `--feed`,
375
+ `--pool`, `--book` and `--chart`.
422
376
 
423
377
  ### TradingView (`dexbot tv`)
424
- **File:** `tv.ts` (thin entry; shared pipeline: `chart_command.ts`)
425
- **Purpose:** One-step TradingView-style 1h chart for a bot (with AMA + order overlay), pool, or pair. Fetches candles in monthly Kibana chunks (pool-first with order-book fallback; `--feed` for MPA price-feed history), then renders via `analysis/tradingview/`. Bot charts pick up the order overlay from `profiles/orders/<botKey>.json` automatically.
426
- **Output:** `analysis/charts/tv_<bot|pool_<id>|<a>_<b>>_1h_<N>m.html` (`_feed` suffix for feed charts)
378
+ **File:** `tv.ts`
379
+ One-step 1h chart for a bot, pool or pair, with AMA + order overlay. Bot charts
380
+ load `profiles/orders/<botKey>.json` automatically.
381
+ **Output:** `tv_<bot|pool_<id>|<a>_<b>>_1h_<N>m.html` (`_feed` for feed charts)
427
382
  ```bash
428
- # Bot chart (default: 3 months)
429
- dexbot tv <bot>
430
- # Pool or pair, custom window
431
- dexbot tv 133 --month 6
383
+ dexbot tv <bot> # bot, 3 months
384
+ dexbot tv 133 --month 6 # pool
432
385
  dexbot tv TOKENA/TOKENB --month 1 --chart analysis/charts/custom.html
433
- # MPA price-feed history instead of market candles (opt-in)
434
- dexbot tv BTS/HONEST.USD --feed --month 1
386
+ dexbot tv TOKENA/BTS --feed --month 1 # MPA price feed
435
387
  ```
436
388
 
437
- ### Dynamic Weight (`dexbot dw`) โ€” advanced
438
- **File:** `dw.ts` (thin entry; shared pipeline: `chart_command.ts`)
439
- **Purpose:** Identical one-step pipeline to `dexbot tv` (same targets, `--month`, `--feed/--pool/--book`, same cached monthly candle chunks) โ€” the only difference is the renderer: it writes the dynamic-weight research chart via `analysis/analyze_dynamic_weight.ts` (AMA slope + Kalman blend, Hurst/PE regime gate) instead of a TradingView chart. For weight-tuning research, not general charting.
440
- **Output:** `analysis/charts/dw_<bot|pool_<id>|<a>_<b>>_1h_<N>m.html` (`_feed` suffix for feed charts)
389
+ ### Dynamic Weight (`dexbot dw`)
390
+ **File:** `dw.ts`
391
+ Same pipeline and flags as `tv`; renders the dynamic-weight research chart
392
+ (AMA slope + Kalman blend, Hurst/PE regime gate). Research knobs (`--alpha`,
393
+ `--gain`, `--dw`, `--lb`, `--clip`) live on `analysis/analyze_dynamic_weight.js`.
394
+ **Output:** `dw_<bot|pool_<id>|<a>_<b>>_1h_<N>m.html` (`_feed` for feed charts)
441
395
  ```bash
442
- # Bot chart (default: 3 months)
443
396
  dexbot dw <bot>
444
- # Pool or pair, custom window
445
397
  dexbot dw 133 --month 6
446
398
  dexbot dw TOKENA/TOKENB --month 1 --chart analysis/charts/custom.html
447
- # MPA price-feed history instead of market candles (opt-in)
448
- dexbot dw BTS/HONEST.USD --feed --month 1
399
+ dexbot dw TOKENA/BTS --feed --month 1
449
400
  ```
450
- 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`).
451
401
 
452
402
  ### PnL Report (`dexbot pnl`)
453
403
  **File:** `pnl.ts` (thin entry; analyzer + HTML renderer: `analysis/trade_profitability.ts` + `analysis/pnl_report.ts`)
@@ -504,20 +454,7 @@ alias dbr='bash scripts/clear-orders.sh'
504
454
  alias dba='bash scripts/clear-all.sh'
505
455
  alias dbv='node dist/scripts/validate_bots.js'
506
456
  alias dbd='node dist/scripts/divergence-calc.js'
507
- ```
508
-
509
- ---
510
-
511
- ## ๐Ÿ’ก PRO-TIPS FOR TERMINAL USERS
512
457
 
513
- **Monitor live updates while running a script:**
514
- ```bash
515
- # Tail the update log in a separate pane
458
+ # Tail the updater log in a separate pane
516
459
  tail -f <profiles>/logs/dexbot-update.log
517
460
  ```
518
-
519
- **Run a specific bot dry-run from the CLI:**
520
- ```bash
521
- # Force a clean start for 'my-bot'
522
- bash scripts/clear-orders.sh && BOT_NAME=my-bot dexbot test
523
- ```