dexbot 1.6.17 → 1.7.0

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 (156) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/README.md +24 -18
  3. package/analysis/README.md +105 -12
  4. package/analysis/ama_fitting/README.md +2 -2
  5. package/analysis/bot_fitting/README.md +3 -3
  6. package/claw/package.json +1 -1
  7. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  8. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  9. package/dist/analysis/analyze_args.d.ts +2 -1
  10. package/dist/analysis/analyze_dynamic_weight.js +2 -1
  11. package/dist/analysis/analyze_kalman.js +3 -2
  12. package/dist/analysis/analyze_liquidity.d.ts +17 -0
  13. package/dist/analysis/analyze_liquidity.js +325 -0
  14. package/dist/analysis/analyze_regime.js +3 -2
  15. package/dist/analysis/analyze_regime_windows.js +3 -2
  16. package/dist/analysis/analyze_volatility.js +3 -2
  17. package/dist/analysis/fills_source.d.ts +1 -8
  18. package/dist/analysis/fills_source.js +1 -1
  19. package/dist/analysis/grid_correction_check.d.ts +9 -6
  20. package/dist/analysis/grid_correction_check.js +56 -64
  21. package/dist/analysis/liquidity/liquidity_chain.d.ts +66 -0
  22. package/dist/analysis/liquidity/liquidity_chain.js +178 -0
  23. package/dist/analysis/liquidity/liquidity_chart_generator.d.ts +19 -0
  24. package/dist/analysis/liquidity/liquidity_chart_generator.js +523 -0
  25. package/dist/analysis/liquidity/liquidity_depth_model.d.ts +141 -0
  26. package/dist/analysis/liquidity/liquidity_depth_model.js +230 -0
  27. package/dist/analysis/liquidity/liquidity_view.d.ts +38 -0
  28. package/dist/analysis/liquidity/liquidity_view.js +55 -0
  29. package/dist/analysis/math_utils.d.ts +1 -1
  30. package/dist/analysis/trade_profitability.d.ts +1 -1
  31. package/dist/analysis/trade_profitability.js +2 -1
  32. package/dist/analysis/tradingview/analyze_tradingview.js +2 -1
  33. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +3 -3
  34. package/dist/analysis/trend_detection/huber_scale_variants.d.ts +4 -3
  35. package/dist/dexbot.js +74 -169
  36. package/dist/market_adapter/cli_args.d.ts +6 -1
  37. package/dist/market_adapter/cli_args.js +16 -2
  38. package/dist/market_adapter/core/kibana_candles.d.ts +5 -1
  39. package/dist/market_adapter/core/kibana_candles.js +3 -1
  40. package/dist/market_adapter/core/strategies/regime_gate.d.ts +7 -1
  41. package/dist/market_adapter/core/strategies/regime_gate.js +3 -1
  42. package/dist/market_adapter/inputs/cex_candle_parsing.d.ts +7 -2
  43. package/dist/market_adapter/inputs/cex_candle_parsing.js +3 -1
  44. package/dist/market_adapter/inputs/fetch_book_data.d.ts +7 -1
  45. package/dist/market_adapter/inputs/fetch_book_data.js +3 -1
  46. package/dist/market_adapter/inputs/fetch_cex_synthetic_data.js +2 -11
  47. package/dist/market_adapter/inputs/fetch_lp_data.d.ts +26 -1
  48. package/dist/market_adapter/inputs/fetch_lp_data.js +62 -52
  49. package/dist/market_adapter/inputs/kibana_feed_source.d.ts +14 -2
  50. package/dist/market_adapter/inputs/kibana_feed_source.js +14 -1
  51. package/dist/market_adapter/inputs/window_cache.d.ts +14 -3
  52. package/dist/market_adapter/inputs/window_cache.js +14 -1
  53. package/dist/market_adapter/lp_chart_runner.d.ts +12 -9
  54. package/dist/market_adapter/lp_chart_runner.js +3 -1
  55. package/dist/market_adapter/lp_chart_strategy_loader.d.ts +5 -1
  56. package/dist/market_adapter/lp_chart_strategy_loader.js +3 -1
  57. package/dist/market_adapter/market_adapter.d.ts +10 -2
  58. package/dist/market_adapter/market_adapter.js +10 -11
  59. package/dist/market_adapter/utils/chain.d.ts +2 -3
  60. package/dist/market_adapter/utils/file_json_cache.d.ts +5 -1
  61. package/dist/market_adapter/utils/file_json_cache.js +3 -1
  62. package/dist/market_adapter/utils/file_lock.js +1 -1
  63. package/dist/market_adapter/utils/native_history.d.ts +7 -3
  64. package/dist/market_adapter/utils/native_history.js +3 -1
  65. package/dist/market_adapter/utils/pair_orientation.d.ts +2 -2
  66. package/dist/modules/asset_lookup.d.ts +25 -0
  67. package/dist/modules/asset_lookup.js +75 -0
  68. package/dist/modules/bots_file_lock.d.ts +2 -2
  69. package/dist/modules/bots_file_lock.js +2 -2
  70. package/dist/modules/chain_scan.d.ts +64 -0
  71. package/dist/modules/chain_scan.js +80 -0
  72. package/dist/modules/cli_colors.d.ts +5 -0
  73. package/dist/modules/cli_colors.js +7 -0
  74. package/dist/modules/cli_progress.d.ts +51 -0
  75. package/dist/modules/cli_progress.js +113 -0
  76. package/dist/modules/constants.js +6 -3
  77. package/dist/modules/dexbot_class.d.ts +8 -0
  78. package/dist/modules/dexbot_class.js +10 -0
  79. package/dist/modules/dexbot_cow_runtime.d.ts +62 -1
  80. package/dist/modules/dexbot_cow_runtime.js +475 -47
  81. package/dist/modules/dexbot_credential_client.d.ts +5 -0
  82. package/dist/modules/dexbot_fill_runtime.js +20 -0
  83. package/dist/modules/dexbot_maintenance_runtime.js +71 -9
  84. package/dist/modules/dexbot_startup_runtime.js +7 -1
  85. package/dist/modules/graceful_shutdown.d.ts +2 -2
  86. package/dist/modules/graceful_shutdown.js +2 -2
  87. package/dist/modules/launcher/runtime_entry.d.ts +21 -1
  88. package/dist/modules/launcher/runtime_entry.js +36 -1
  89. package/dist/modules/launcher/runtime_mode.d.ts +4 -3
  90. package/dist/modules/liquidity_pool_ref.d.ts +32 -0
  91. package/dist/modules/liquidity_pool_ref.js +116 -0
  92. package/dist/modules/node_manager.d.ts +1 -1
  93. package/dist/modules/node_manager.js +1 -1
  94. package/dist/modules/order/accounting.js +2 -1
  95. package/dist/modules/order/export.d.ts +2 -2
  96. package/dist/modules/order/export.js +2 -2
  97. package/dist/modules/order/grid.d.ts +19 -14
  98. package/dist/modules/order/grid.js +269 -61
  99. package/dist/modules/order/grid_reconcile.js +27 -2
  100. package/dist/modules/order/grid_reconcile_internal.js +94 -15
  101. package/dist/modules/order/index.d.ts +24 -4
  102. package/dist/modules/order/manager.d.ts +12 -0
  103. package/dist/modules/order/manager.js +44 -11
  104. package/dist/modules/order/strategy.js +22 -2
  105. package/dist/modules/order/sync_engine.d.ts +32 -1
  106. package/dist/modules/order/sync_engine.js +209 -26
  107. package/dist/modules/order/utils/math.d.ts +26 -10
  108. package/dist/modules/order/utils/math.js +54 -14
  109. package/dist/modules/order/utils/order.d.ts +158 -11
  110. package/dist/modules/order/utils/order.js +434 -21
  111. package/dist/modules/order/utils/system.d.ts +136 -30
  112. package/dist/modules/order/utils/system.js +465 -63
  113. package/dist/modules/order/utils/validate.d.ts +1 -0
  114. package/dist/modules/order/utils/validate.js +37 -3
  115. package/dist/modules/storage/index.d.ts +3 -2
  116. package/dist/modules/storage/index.js +3 -2
  117. package/dist/modules/types.d.ts +14 -0
  118. package/dist/modules/utils/asset_symbols.d.ts +13 -2
  119. package/dist/modules/utils/asset_symbols.js +21 -2
  120. package/dist/scripts/analysis_runner.d.ts +10 -0
  121. package/dist/scripts/analysis_runner.js +33 -0
  122. package/dist/scripts/analyze-orders.js +2 -1
  123. package/dist/scripts/asset.d.ts +26 -0
  124. package/dist/scripts/asset.js +165 -0
  125. package/dist/scripts/bts_distribution.d.ts +1 -0
  126. package/dist/scripts/bts_distribution.js +194 -142
  127. package/dist/scripts/chart_command.d.ts +1 -1
  128. package/dist/scripts/chart_command.js +60 -86
  129. package/dist/scripts/chart_targets.d.ts +18 -0
  130. package/dist/scripts/chart_targets.js +52 -0
  131. package/dist/scripts/dw.js +1 -1
  132. package/dist/scripts/liquid.d.ts +24 -0
  133. package/dist/scripts/liquid.js +134 -0
  134. package/dist/scripts/rich_list.js +12 -16
  135. package/dist/scripts/token_distribution.d.ts +2 -0
  136. package/dist/scripts/token_distribution.js +132 -108
  137. package/dist/scripts/tv.js +1 -1
  138. package/dist/scripts/verify-browser-bundle.js +18 -0
  139. package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -1
  140. package/docs/COW_INVARIANTS.md +21 -11
  141. package/docs/DEXBOT_COMPARISON.md +6 -6
  142. package/docs/EVOLUTION.md +10 -8
  143. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +11 -11
  144. package/docs/GRID_PRICE_INVARIANT.md +28 -5
  145. package/docs/GRID_RECONCILE.md +25 -5
  146. package/docs/LIFECYCLE.md +11 -11
  147. package/docs/LOGGING.md +37 -2
  148. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +124 -36
  149. package/docs/README.md +1 -1
  150. package/docs/WORKFLOW.md +3 -1
  151. package/docs/architecture.md +115 -13
  152. package/docs/developer_guide.md +12 -0
  153. package/market_adapter/README.md +9 -4
  154. package/modules/README.md +23 -15
  155. package/package.json +6 -3
  156. package/scripts/README.md +23 -7
@@ -279,6 +279,18 @@ const normalized = normalizeInt(currentSizeInt, assetPrecision);
279
279
 
280
280
  ---
281
281
 
282
+ ## Export Surface & Test Seams
283
+
284
+ Three rules keep the module surface honest once you start narrowing it.
285
+
286
+ **1. Declaration emit is a real consumer.** A type used only inside its own module can still be unnameable from a dependent package's `.d.ts`. The claw wrapper infers `Promise<CredentialDaemonResponse>` from `modules/dexbot_credential_client.ts`, so de-exporting that interface broke `npm run build --prefix claw` with `TS4058` even though nothing imports it by name. Before narrowing an export, run `npm run build --prefix claw` as well as `npm run typecheck`; when a type must stay exported purely for emit, say so in its JSDoc.
287
+
288
+ **2. The shipped `dist/` is a public API.** The package publishes compiled JS plus declarations, so dropping an optional positional parameter is breaking even when every in-repo caller is updated (for example `calculateOrderSizes`, `calculateRotationOrderSizes` and `allocateFundsByWeights` lost their unused `minSize` arguments). The changelog is written at release time, so call the break out in the next release entry instead of leaving it implicit.
289
+
290
+ **3. Test-only helpers live in one `__test` object.** White-box helpers that only tests call are grouped as `export const __test = { ... }` instead of individual named exports, so a dead-export scan does not have to special-case them. Nothing outside the defining module may reference `__test` — `tests/test_public_surface_guard.ts` fails the suite if production code imports the seam or if it is touched more than once in its own module.
291
+
292
+ ---
293
+
282
294
  ## Module Deep Dive
283
295
 
284
296
  ### OrderManager (`modules/order/manager.ts`)
@@ -405,6 +405,10 @@ node dist/market_adapter/inputs/fetch_lp_data.js --pool <poolId> --precA <precA>
405
405
  npm run lp:chart -- --data market_adapter/data/lp/<pair>/lp_pool_<id>_<interval>.json
406
406
  ```
407
407
 
408
+ The LP exporter also accepts `--chunkMonths <n>` (fetch window size in months),
409
+ `--apiKey <key>` (Kibana API key when the endpoint requires auth), `--out <file>`
410
+ (explicit output path), and `--help`. Unknown flags are rejected.
411
+
408
412
  Research and calibration:
409
413
 
410
414
  ```bash
@@ -445,8 +449,9 @@ operation:
445
449
  node dist/market_adapter/market_adapter.js
446
450
  ```
447
451
 
448
- The adapter acts only on closed 1h candles. It can poll more often, but live
449
- updates wait for the next completed candle.
452
+ The adapter acts only on closed candles at the configured interval (default
453
+ 1h). It can poll more often, but live updates wait for the next completed
454
+ candle.
450
455
 
451
456
  ### Signal Pipeline
452
457
 
@@ -485,7 +490,7 @@ Per cycle, per processed bot, the adapter can produce:
485
490
  4. Read `startPrice` to choose the candle source: `pool`, `book`, or fixed.
486
491
  5. Sync candle data from Kibana or native BitShares data, using the selected source.
487
492
  6. Repair missing candle gaps: auto-fill gaps ≤24 candles directly (no Kibana), query Kibana only for gaps beyond that threshold. Kibana returning empty is treated as verified no-trade. Writes are suppressed while gaps remain unresolved.
488
- 7. Ignore still-forming 1h candles.
493
+ 7. Ignore still-forming candles at the configured interval.
489
494
  8. Compute AMA center, trend, ATR, weights, and collateral hint.
490
495
  9. Persist the first accepted center, compare center delta, and compare whitelisted range-scaling slope delta.
491
496
  10. Suppress live writes if the bot is not whitelisted or candle data is stale.
@@ -866,7 +871,7 @@ are merged in, or an empty response is treated as verified no-trade (all gaps
866
871
  in the queried window are synthesized). Gaps remaining after both steps
867
872
  suppress writes via `unresolved_candle_gaps` until repaired on a future cycle.
868
873
  The adapter prunes old candles to the required AMA window and acts only on
869
- closed 1h candles.
874
+ closed candles at the configured interval.
870
875
 
871
876
  #### Shared Month-Shard Cache and Fetch Robustness
872
877
 
package/modules/README.md CHANGED
@@ -37,8 +37,12 @@ modules/
37
37
  ├── version_notice.ts passive npm-registry version check + status line
38
38
  ├── cli_start_onboarding.ts first-run setup routing for `dexbot start`
39
39
  ├── cli_start_output.ts launcher notice formatting
40
- ├── cli_colors.ts shared CLI color helpers
41
- ├── credential_runtime.ts credential daemon lifecycle
40
+ ├── cli_colors.ts shared CLI color palette + `colorize()`
41
+ ├── cli_progress.ts shared `[Tag]` lines: progress, section, warnings, summary, saved link
42
+ ├── liquidity_pool_ref.ts pool id / pool token resolution (shared by liq/tv/dw)
43
+ ├── chain_scan.ts batched object-id walk for list-less types (1.13/1.15)
44
+ ├── asset_lookup.ts case-insensitive asset refs (symbol/id) for every CLI
45
+ ├── credential_runtime.ts daemon socket/path helpers + private-path security
42
46
  ├── credential_policy.ts signing policy validation
43
47
  ├── credential_session_cache.ts encrypted session cache
44
48
  ├── constants.ts central config and tuning params
@@ -46,6 +50,7 @@ modules/
46
50
  ├── config.ts load-time process.env snapshot
47
51
  ├── env.ts isBrowser/hasProcess detection
48
52
  ├── runtime.ts process abstraction singleton
53
+ ├── lazy_shim.ts lazy named-export passthrough (require-on-call)
49
54
  ├── runtime_settings.ts per-bot runtime settings resolver
50
55
  ├── paths.ts guarded path resolution
51
56
  ├── path_api.ts portable path abstraction for ESM/browser
@@ -62,11 +67,11 @@ modules/
62
67
  ├── bots_file_lock.ts profile write serialization
63
68
  ├── account_bots.ts bots.json read/write
64
69
  ├── broadcast_failure.ts broadcast failure classification
65
- ├── chain_keys.ts blockchain key helpers
66
- ├── daemon_node_health.ts daemon-side node health checks
67
- ├── node_failure_ledger.ts node failure tracking
68
- ├── node_health_cache.ts node health tracking
69
- ├── socket_json_client.ts JSON-RPC socket client
70
+ ├── chain_keys.ts master-password vault + signing-key retrieval
71
+ ├── daemon_node_health.ts daemon-side node failure ledger (shared rules)
72
+ ├── node_failure_ledger.ts node failure counting shared by bot + daemon
73
+ ├── node_health_cache.ts shared node-health cache file I/O + ordering
74
+ ├── socket_json_client.ts newline-delimited JSON Unix-socket client
70
75
  ├── market_adapter_whitelist.ts adapter whitelist I/O
71
76
  ├── types.ts shared type definitions
72
77
  │
@@ -83,7 +88,7 @@ modules/
83
88
  ├── storage/ portable storage abstraction
84
89
  │ ├── index.ts barrel export
85
90
  │ ├── types.ts storage adapter interface
86
- │ ├── browser_adapter.ts in-memory Map-based adapter
91
+ │ ├── browser_adapter.ts in-memory Map backed by IndexedDB
87
92
  │ └── node_adapter.ts fs.*Sync based adapter
88
93
  │
89
94
  ├── order/ order lifecycle and grid management
@@ -93,9 +98,9 @@ modules/
93
98
  │ ├── strategy.ts grid rebalancing, consolidation, rotation
94
99
  │ ├── accounting.ts fund tracking, fee accounting
95
100
  │ ├── sync_engine.ts blockchain sync, fill detection, reconciliation
96
- │ ├── genesis_policy.ts missing-ladder refusal + rebuild/halt policy ([doc](../docs/GRID_PRICE_INVARIANT.md))
97
- │ ├── grid_reconcile.ts startup grid reconciliation ([doc](../docs/GRID_RECONCILE.md))
98
- │ ├── grid_reconcile_internal.ts internal grid reconciliation helpers
101
+ │ ├── genesis_policy.ts missing-ladder refusal + rebuild policy (docs/GRID_PRICE_INVARIANT.md)
102
+ │ ├── grid_reconcile.ts startup grid reconciliation (docs/GRID_RECONCILE.md)
103
+ │ ├── grid_reconcile_internal.ts internal grid reconciliation helpers
99
104
  │ ├── index.ts barrel export
100
105
  │ ├── logger.ts order-scoped logging
101
106
  │ ├── logger_state.ts logger state management
@@ -126,6 +131,7 @@ modules/
126
131
  │ ├── market_adapter_watchdog.ts adapter process watchdog
127
132
  │ ├── monolithic_runtime.ts monolithic bot runtime
128
133
  │ ├── runtime_entry.ts bot process entry
134
+ │ ├── runtime_mode.ts runtime mode detection and status routing
129
135
  │ ├── status_reporting.ts process status reporter
130
136
  │ └── supervisor_control.ts supervisor orchestration
131
137
  │
@@ -142,14 +148,14 @@ modules/
142
148
  │ └── crypto/ cryptographic primitives
143
149
  │
144
150
  └── utils/
145
- ├── asset_symbols.ts asset symbol/object-id canonicalization helpers
151
+ ├── asset_symbols.ts asset symbol/object-id canonicalization helpers
146
152
  ├── base58check.ts Base58Check encoding
147
153
  ├── build_dir.ts BUILD_DIR constant helper
148
154
  ├── chain_logs.ts shared chain log helpers
149
155
  ├── errors.ts getErrorMessage helper
150
156
  ├── sanitize_key.ts shared sanitizeKey helper
151
157
  ├── text_width.ts display-width-aware text measurement (CJK/emoji tables)
152
- └── time_range.ts month→hour lookback conversion (analysis range flags)
158
+ └── time_range.ts month→hour lookback conversion (analysis range flags)
153
159
  ```
154
160
 
155
161
  ## Key Relationships
@@ -178,10 +184,10 @@ External consumers — other parts of DEXBot2 interact with modules through thes
178
184
 
179
185
  ## Design Principles
180
186
 
181
- - **Zero runtime dependencies** — no npm trading/blockchain libraries; the native client, crypto, and serialization are all in `bitshares-native/`. This eliminates supply-chain risk and keeps the bot fully self-contained.
187
+ - **Zero runtime dependencies** — no npm trading/blockchain libraries; the native client and serialization live in `bitshares-native/`, and the cross-environment crypto providers (Web Crypto / Node crypto plus pure-JS fallbacks) in `crypto/`. `package.json` declares no `dependencies`, which eliminates supply-chain risk and keeps the bot fully self-contained.
182
188
  - **Copy-on-write** — `order/working_grid.ts` provides isolated COW mutations; master grid is immutable during rebalance. The grid is never modified in-place; a working copy is built, mutated, and committed atomically only after blockchain operations succeed.
183
189
  - **Fund-driven sizing, fill-driven boundary** — available funds set order sizing and budget allocation, not the boundary position; no forced allocations. The boundary moves only through boundary crawl on fills or spread promotion onto orders placed in the same atomic batch.
184
- - **Replay-safe accounting** — fill processing in `dexbot_fill_runtime.ts` uses `processed_fill_store.ts` to prevent double-counting. If the bot restarts mid-fill, it can safely replay without creating duplicate orders.
190
+ - **Replay-safe accounting** — `dexbot_class.ts` constructs `order/processed_fill_store.ts`, `dexbot_fill_runtime.ts` configures it and hands it to the `OrderManager`, and `order/accounting.ts` consults it before counting a fill. If the bot restarts mid-fill, it can safely replay without creating duplicate orders.
185
191
  - **Daemon-backed signing** — the credential daemon holds decrypted keys; modules never handle raw private keys. If the main bot crashes, keys stay encrypted on disk — only the small daemon process sees them.
186
192
  - **Gap-slot batch processing** — each fill batch and broadcast is capped at the current grid's gap-slot count + 1. A queue at or below that depth is processed as one unified batch; deeper queues are chunked at the same deterministic cap.
187
193
 
@@ -194,5 +200,7 @@ External consumers — other parts of DEXBot2 interact with modules through thes
194
200
  - [Fund movement & accounting](../docs/FUND_MOVEMENT_AND_ACCOUNTING.md) — fund tracking algorithms and formulas
195
201
  - [Credential security](../docs/CREDENTIAL_SECURITY.md) — key handling and daemon-backed signing details
196
202
  - [Grid recalculation](../docs/GRID_RECALCULATION.md) — when and how the grid resets or regenerates
203
+ - [Grid price invariant](../docs/GRID_PRICE_INVARIANT.md) — genesis ladder as the only authoritative slot price
204
+ - [Grid reconcile](../docs/GRID_RECONCILE.md) — startup reconciliation of the persisted grid
197
205
  - [Market adapter](../market_adapter/README.md) — AMA pricing, dynamic weights, and signal pipeline
198
206
  - [Claw bridge](../claw/README.md) — AI layer integration and command dispatch
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dexbot",
3
- "version": "1.6.17",
3
+ "version": "1.7.0",
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": {
@@ -97,10 +97,12 @@
97
97
  "ama:chart:lp-local": "npm run build && node dist/analysis/ama_fitting/generate_unified_comparison_chart.js",
98
98
  "analysis:trade-pnl": "npm run build && node dist/analysis/trade_profitability.js",
99
99
  "analysis:grid-check": "npm run build && node dist/analysis/grid_correction_check.js",
100
+ "analysis:liquidity": "npm run build && node dist/analysis/analyze_liquidity.js",
100
101
  "analysis:resolve-accounts": "npm run build && node dist/analysis/resolve_bot_accounts.js",
101
102
  "richlist": "npm run build && node dist/scripts/rich_list.js",
102
103
  "distribution": "npm run build && node dist/scripts/bts_distribution.js",
103
104
  "token-distribution": "npm run build && node dist/scripts/token_distribution.js",
105
+ "asset": "npm run build && node dist/scripts/asset.js",
104
106
  "native:release-gates": "npm run build && npm run build:tests && node dist/scripts/native_release_gates.js",
105
107
  "native:serial-snapshots": "npm run build && npm run build:tests && node dist/tests/test_native_serial_ops.js",
106
108
  "native:ecc-invariants": "npm run build && npm run build:tests && node dist/tests/test_native_ecc.js",
@@ -109,14 +111,15 @@
109
111
  "version:sync": "npm run build && node dist/scripts/sync-version.js",
110
112
  "version:check": "npm run build && node dist/scripts/sync-version.js --check",
111
113
  "verify:browser-bundle": "npm run build && node dist/scripts/verify-browser-bundle.js",
112
- "test": "npm run build && npm run build:tests && npm run build --prefix claw && node dist/scripts/run-tests.js",
113
- "test:live": "RUN_LIVE_BITSHARES_TESTS=1 npm run build && npm run build:tests && npm run build --prefix claw && node dist/scripts/run-tests.js",
114
+ "test": "npm run build && npm run build:tests && npm run build --prefix claw && npm run typecheck:analysis && node dist/scripts/run-tests.js",
115
+ "test:live": "RUN_LIVE_BITSHARES_TESTS=1 npm run build && npm run build:tests && npm run build --prefix claw && npm run typecheck:analysis && node dist/scripts/run-tests.js",
114
116
  "test:playwright": "npm run build && NODE_PATH=\"$(npm root -g)\" playwright test --config tests/playwright/playwright.config.mjs",
115
117
  "clean": "node scripts/clean-dist.js",
116
118
  "build": "echo \"tsc is compiling ...\" && tsc && chmod +x dist/dexbot.js dist/bot.js dist/unlock.js dist/pm2.js dist/credential-daemon.js",
117
119
  "build:clean": "npm run clean && npm run build",
118
120
  "build:tests": "tsc -p tsconfig.tests.json && cp tests/package.json dist/tests/package.json && cp tests/helpers/esm_mock_hooks.mjs tests/helpers/esm_mock_loader.mjs dist/tests/helpers/",
119
121
  "typecheck": "tsc --noEmit",
122
+ "typecheck:analysis": "tsc -p analysis/tsconfig.json",
120
123
  "check:any": "npm run build && node dist/scripts/check_any.js",
121
124
  "check:any:update": "npm run build && node dist/scripts/check_any.js --update",
122
125
  "check:any:list": "npm run build && node dist/scripts/check_any.js --list",
package/scripts/README.md CHANGED
@@ -2,6 +2,15 @@
2
2
 
3
3
  This guide provides a terminal-focused reference for the maintenance and diagnostic utilities available in the `scripts/` directory.
4
4
 
5
+ Every command that writes a file prints the same trailer
6
+ (`[Tag] ✓ <kind> saved. Open <kind>: (file://…)`) plus the shared section/warning/summary
7
+ blocks, all from `modules/cli_progress.ts` (`savedLine`, `section`, `warningsBlock`, `summaryLine`).
8
+
9
+ Asset symbols are case-insensitive wherever a command takes one (`dexbot asset token.sym`,
10
+ `dexbot rich token.sym`, `dexbot liq A/B`, `dexbot tv <pool-token>`, `--base`/`--quote`): every
11
+ path resolves through `modules/asset_lookup.ts`, which looks the symbol up in its canonical UPPERCASE
12
+ form and keeps `1.3.x` ids untouched.
13
+
5
14
  ---
6
15
 
7
16
  ## 🛠️ CORE MAINTENANCE
@@ -104,7 +113,7 @@ the rename. Note:
104
113
  the `holders=` figure can be off by one.
105
114
 
106
115
  ### BTS Supply Distribution
107
- **File:** `bts_distribution.ts` (npm: `npm run distribution`)
116
+ **File:** `bts_distribution.ts` (CLI: `dexbot asset bts`; npm: `npm run distribution`)
108
117
  **Purpose:** Live-chain breakdown of where BTS sits: call-order collateral, global/individual
109
118
  settlement funds (plus force-settlement debt and parameters), governance tickets, vesting and
110
119
  legacy balances, liquidity pools, SameT/credit funds, HTLC escrow and asset fee pools. The
@@ -112,11 +121,17 @@ remainder is reported as a derived liquid residual and compared with total suppl
112
121
  circulating float. Also writes a self-contained HTML donut report to
113
122
  `analysis/charts/bts-distribution.html` (`--html PATH`, `--no-html`).
114
123
  ```bash
115
- npm run distribution # terminal + HTML
124
+ dexbot asset bts # terminal + HTML (shorthand: dexbot a bts)
125
+ npm run distribution # same, via npm
116
126
  node dist/scripts/bts_distribution.js --json # JSON (HTML still written)
117
127
  node dist/scripts/bts_distribution.js --circulating <reference-supply>
118
128
  node dist/scripts/bts_distribution.js --holders all # full rich list (~5 min)
119
129
  ```
130
+ Vesting (1.13.x) and legacy (1.15.x) objects have no list API, so both are enumerated by probing
131
+ ids with `get_objects` in 1000-id batches (`modules/chain_scan.ts`, halving on nodes that refuse
132
+ big batches) and filtered to BTS client-side — the walk covers every asset the node stores there,
133
+ because the chain exposes no per-asset index. `--gap N` controls how far past the last live object
134
+ the walk continues (default 20000); `--vesting-max` caps the 1.13.x probe.
120
135
  Call-order collateral uses `api_helper_indexes` `total_in_collateral` (falls back to summing
121
136
  `get_call_orders`). Top liquid holders come from `asset_api::get_asset_holders`, retrying on a
122
137
  node that exposes it; exchange tags are name heuristics, not verified identities. `--holders all`
@@ -124,7 +139,7 @@ also splits the residual into account balances, blinded balances and order books
124
139
  concentration plus balance bands. Read-only: no keys, no transactions.
125
140
 
126
141
  ### Token Distribution
127
- **File:** `token_distribution.ts` (npm: `npm run token-distribution`)
142
+ **File:** `token_distribution.ts` (CLI: `dexbot asset <symbol|1.3.x>`; npm: `npm run token-distribution`)
128
143
  **Purpose:** Per-asset companion to BTS Supply Distribution. Buckets a token into free account
129
144
  balances, limit orders, liquidity pools, vesting balances, P2P credit offers and deal collateral,
130
145
  SameT funds, HTLC escrow, accumulated market fees and blinded supply, then reconciles the total
@@ -134,13 +149,12 @@ token sellable (price −3%) and buyable (+3%), orderbook + pool combined per ma
134
149
  as a share of total supply. Writes the report to
135
150
  `analysis/charts/token-<SYMBOL>-distribution.html`.
136
151
  ```bash
152
+ dexbot asset <token> # terminal + HTML (shorthand: dexbot a <token>)
137
153
  npm run token-distribution -- <token>
138
154
  node dist/scripts/token_distribution.js <asset-id> --json
139
155
  node dist/scripts/token_distribution.js <token> --no-orders # skip the ~6k order queries
140
156
  ```
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`.
157
+ Read-only: no keys, no transactions. BTS itself is rejected; use `npm run distribution`.
144
158
 
145
159
  ### Configuration Audit
146
160
  **File:** `validate_bots.ts`
@@ -381,7 +395,8 @@ load `profiles/orders/<botKey>.json` automatically.
381
395
  **Output:** `tv_<bot|pool_<id>|<a>_<b>>_1h_<N>m.html` (`_feed` for feed charts)
382
396
  ```bash
383
397
  dexbot tv <bot> # bot, 3 months
384
- dexbot tv 133 --month 6 # pool
398
+ dexbot tv 133 --month 6 # pool by id
399
+ dexbot tv <pool-token-symbol> --month 6 # pool by its LP share-asset symbol
385
400
  dexbot tv TOKENA/TOKENB --month 1 --chart analysis/charts/custom.html
386
401
  dexbot tv TOKENA/BTS --feed --month 1 # MPA price feed
387
402
  ```
@@ -395,6 +410,7 @@ Same pipeline and flags as `tv`; renders the dynamic-weight research chart
395
410
  ```bash
396
411
  dexbot dw <bot>
397
412
  dexbot dw 133 --month 6
413
+ dexbot dw <pool-token-symbol> --month 6
398
414
  dexbot dw TOKENA/TOKENB --month 1 --chart analysis/charts/custom.html
399
415
  dexbot dw TOKENA/BTS --feed --month 1
400
416
  ```