dexbot 1.6.18 → 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 (89) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +24 -18
  3. package/analysis/README.md +95 -3
  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/analyze_dynamic_weight.js +2 -1
  8. package/dist/analysis/analyze_kalman.js +3 -2
  9. package/dist/analysis/analyze_liquidity.d.ts +17 -0
  10. package/dist/analysis/analyze_liquidity.js +325 -0
  11. package/dist/analysis/analyze_regime.js +3 -2
  12. package/dist/analysis/analyze_regime_windows.js +3 -2
  13. package/dist/analysis/analyze_volatility.js +3 -2
  14. package/dist/analysis/liquidity/liquidity_chain.d.ts +66 -0
  15. package/dist/analysis/liquidity/liquidity_chain.js +178 -0
  16. package/dist/analysis/liquidity/liquidity_chart_generator.d.ts +19 -0
  17. package/dist/analysis/liquidity/liquidity_chart_generator.js +523 -0
  18. package/dist/analysis/liquidity/liquidity_depth_model.d.ts +141 -0
  19. package/dist/analysis/liquidity/liquidity_depth_model.js +230 -0
  20. package/dist/analysis/liquidity/liquidity_view.d.ts +38 -0
  21. package/dist/analysis/liquidity/liquidity_view.js +55 -0
  22. package/dist/analysis/trade_profitability.js +2 -1
  23. package/dist/analysis/tradingview/analyze_tradingview.js +2 -1
  24. package/dist/dexbot.js +74 -169
  25. package/dist/modules/asset_lookup.d.ts +25 -0
  26. package/dist/modules/asset_lookup.js +75 -0
  27. package/dist/modules/chain_scan.d.ts +64 -0
  28. package/dist/modules/chain_scan.js +80 -0
  29. package/dist/modules/cli_colors.d.ts +5 -0
  30. package/dist/modules/cli_colors.js +7 -0
  31. package/dist/modules/cli_progress.d.ts +51 -0
  32. package/dist/modules/cli_progress.js +113 -0
  33. package/dist/modules/dexbot_cow_runtime.js +14 -4
  34. package/dist/modules/dexbot_fill_runtime.js +20 -0
  35. package/dist/modules/dexbot_maintenance_runtime.js +16 -1
  36. package/dist/modules/launcher/runtime_entry.d.ts +21 -1
  37. package/dist/modules/launcher/runtime_entry.js +36 -1
  38. package/dist/modules/liquidity_pool_ref.d.ts +32 -0
  39. package/dist/modules/liquidity_pool_ref.js +116 -0
  40. package/dist/modules/order/grid.js +9 -2
  41. package/dist/modules/order/grid_reconcile.js +22 -1
  42. package/dist/modules/order/grid_reconcile_internal.js +92 -14
  43. package/dist/modules/order/index.d.ts +15 -1
  44. package/dist/modules/order/manager.d.ts +2 -0
  45. package/dist/modules/order/manager.js +3 -0
  46. package/dist/modules/order/sync_engine.d.ts +20 -0
  47. package/dist/modules/order/sync_engine.js +101 -33
  48. package/dist/modules/order/utils/math.d.ts +18 -1
  49. package/dist/modules/order/utils/math.js +30 -1
  50. package/dist/modules/order/utils/order.d.ts +107 -1
  51. package/dist/modules/order/utils/order.js +298 -1
  52. package/dist/modules/order/utils/system.d.ts +63 -1
  53. package/dist/modules/order/utils/system.js +247 -36
  54. package/dist/modules/order/utils/validate.js +33 -2
  55. package/dist/modules/types.d.ts +5 -0
  56. package/dist/modules/utils/asset_symbols.d.ts +13 -2
  57. package/dist/modules/utils/asset_symbols.js +21 -2
  58. package/dist/scripts/analysis_runner.d.ts +10 -0
  59. package/dist/scripts/analysis_runner.js +33 -0
  60. package/dist/scripts/analyze-orders.js +2 -1
  61. package/dist/scripts/asset.d.ts +26 -0
  62. package/dist/scripts/asset.js +165 -0
  63. package/dist/scripts/bts_distribution.d.ts +1 -0
  64. package/dist/scripts/bts_distribution.js +194 -142
  65. package/dist/scripts/chart_command.d.ts +1 -1
  66. package/dist/scripts/chart_command.js +60 -86
  67. package/dist/scripts/chart_targets.d.ts +18 -0
  68. package/dist/scripts/chart_targets.js +52 -0
  69. package/dist/scripts/dw.js +1 -1
  70. package/dist/scripts/liquid.d.ts +24 -0
  71. package/dist/scripts/liquid.js +134 -0
  72. package/dist/scripts/rich_list.js +12 -16
  73. package/dist/scripts/token_distribution.d.ts +2 -0
  74. package/dist/scripts/token_distribution.js +132 -108
  75. package/dist/scripts/tv.js +1 -1
  76. package/dist/scripts/verify-browser-bundle.js +18 -0
  77. package/docs/COW_INVARIANTS.md +2 -2
  78. package/docs/DEXBOT_COMPARISON.md +6 -6
  79. package/docs/EVOLUTION.md +9 -8
  80. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  81. package/docs/GRID_PRICE_INVARIANT.md +4 -1
  82. package/docs/GRID_RECONCILE.md +20 -0
  83. package/docs/LOGGING.md +25 -3
  84. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +2 -1
  85. package/docs/README.md +1 -1
  86. package/docs/WORKFLOW.md +3 -1
  87. package/modules/README.md +5 -1
  88. package/package.json +3 -1
  89. package/scripts/README.md +23 -7
package/CHANGELOG.md CHANGED
@@ -2,6 +2,32 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [1.7.0] - 2026-11-02 - Liquidity Depth Chart & `dexbot liquid`, Asset Distribution Shortcut, Pool-Ref Chart Targets, Case-Insensitive Asset Lookup, Orphan-Fill Attribution & Stale-Grid Re-Buy Discipline
6
+
7
+ ### 2026-11-02
8
+
9
+ - **Feat(liquidity)**: add a cumulative liquidity depth chart and the `dexbot liquid` command — a read-only analyzer (`analysis/analyze_liquidity.ts`, `analysis/liquidity/*`) blends a pair's live order book with its constant-product AMM pool using the vendored uPlot runtime. The curves stay separate rather than summed, support depth-asset switching and price inversion via axis clicks, reuse the shared 4-digit formatters, and keep the market centre centred when inverted. Depth is fetched through `get_limit_orders` (up to ~300 levels per side) with a `get_order_book` fallback, because the latter is commonly capped at 50 and silently truncated the curves; transport chatter is suppressed for the generator. Exposed as `dexbot liquid <bot|AssetA/AssetB>` with the same clickable `file://` trailer as `dexbot tv`, and the bot-target resolution plus analysis-script spawning is now shared between `tv`, `dw` and `liquid` instead of duplicated. Covered by new `tests/test_liquidity_depth.ts` and `tests/test_liquid_cli.ts` (pool invariant math, order-book side mapping, limit-order decoding and fallback, view inversion, HTML payload/formatting, offline CLI parsing).
10
+
11
+ - **Feat(cli)**: add `liq` and `liqu` as shortcuts for the liquidity depth chart — the command was only reachable as `liquid`/`liquidity`, which is cumbersome for something used repeatedly during research. Both aliases forward `--help` to the liquid script (alias resolution runs before the help-owning command check), and `--help`, `--cli-examples`, the README cheat sheet and the analysis/WORKFLOW docs all show `liq` while naming `liquid` canonical. Covered by new `tests/test_cli_aliases.ts`, which spawns the entrypoint to assert every spelling and the help listing.
12
+
13
+ - **Feat(cli)**: add `dexbot asset <bts|symbol>` (shorthand `a`) for supply distribution — the two analyzers were only reachable through `dist/scripts/*.js` or npm scripts, which sat awkwardly beside the other analysis commands. The router sends `bts` (or the core asset id) to the BTS report and any other symbol/id to the token report, with no `token` keyword: `asset token X` fails with a hint instead of a chain lookup. Forwarded flags are validated against the chosen analyzer (core asset: `--holders`/`--circulating`; issued asset: `--no-orders`/`--concurrency`) while the analyzers stay the single flag reference, and `asset` is help-owning so `--help` works offline. Both analyzers now log in the `[Liquidity]` style (`[Assets] Loading`, tagged transient progress, `Report saved` link, `[Assets] Error:`), and the `asset` npm script plus README/scripts README/WORKFLOW docs are added. Covered by new `tests/test_asset_cli.ts`.
14
+
15
+ - **Feat(cli)**: accept a pool id or pool token wherever `liq`/`tv`/`dw` take a target — `dexbot liq` resolved only bots and `AssetA/AssetB` pairs, and the shared chart pipeline behind `tv`/`dw` accepted numeric pool ids only. All three now take the same three target kinds (bot, pool, pair), where a pool is either its object id (`133` / `1.19.133`) or its pool token (the LP-share asset symbol, the same value a bot names in its `pool` setting). Parsing lives once in `modules/liquidity_pool_ref.ts` (`normalizePoolRef`, `isPoolIdRef`/`isPoolRefLike`, `poolAssetIds`, `resolvePoolRef`) with the chain read injected, so the module stays browser-safe and the commands cannot drift. `analysis/analyze_liquidity.ts --pool` accepts the same spellings and derives both legs when `--base`/`--quote` are omitted; a half-given pair beside `--pool`, a pool target combined with `--pool`, a valueless `--pool` and a pool/pair mismatch are all rejected with specific messages instead of silently charting something else, and a bare `--help` now prints usage rather than failing target validation. The CLI's child-process plumbing is centralized in `modules/launcher/runtime_entry.runRuntimeScript` (one `SCRIPT_COMMANDS` map, replacing nine copy-pasted spawn blocks plus the router copies in `scripts/analysis_runner.ts` and `scripts/asset.ts`), and `modules/cli_progress.ts` owns the `[Tag] …` progress/saved-line style. Behavioral impact: new accepted targets on read-only chart commands; existing targets, flags, reports and exit codes are unchanged, except a missing build or failed spawn now reports through the shared runner and `status` exits 1 rather than 0 when the unlock probe cannot be spawned. Covered by `tests/test_liquidity_pool_ref.ts`, `tests/test_cli_progress.ts` and the extended liquid/liquidity suites.
16
+
17
+ - **Fix(cli)**: resolve asset symbols case-insensitively through one lookup — every command that takes an asset from a human (`dexbot asset <symbol>`, `dexbot rich <asset...>`, `dexbot liq`/`tv`/`dw` pairs and pool tokens, `--base`/`--quote`) failed on any spelling that was not exactly the on-chain UPPERCASE symbol, because `get_assets`/`lookup_asset_symbols` are case-sensitive and a lowercase symbol resolved to null. `modules/asset_lookup.ts` is now the single resolver: refs are canonicalised with `normalizeAssetSymbol` (1.3.x ids pass through untouched), resolved in one batched `get_assets` call, and only an unresolved ref is retried once with the spelling as typed so a node holding a genuinely non-canonical symbol still resolves. The reader is injected, keeping the module browser-safe, and `assetSymbolCandidates` is the only place that decides the two spellings. Wired through `scripts/token_distribution.ts`, `scripts/rich_list.ts` (which keeps the caller's spelling in result rows and still applies the legacy `bit*` alias retry) and `analysis/liquidity/liquidity_chain.ts` (dropping its private id regex); `modules/liquidity_pool_ref.ts` resolves pool tokens through the same resolver. Behavioral impact: lowercase/mixed-case symbols now resolve instead of failing; `asset not found` still echoes the typed spelling, and already-correct input is unchanged. Covered by new `tests/test_asset_lookup.ts` plus reworked `test_liquidity_pool_ref` and `test_rich_list_symbol_normalization`.
18
+
19
+ - **Perf(cli)**: cut the asset reports' chain requests by an order of magnitude — both supply distribution commands only need per-asset metadata but asked the node for far more. The BTS report listed every asset (100 per page over thousands of assets) just to find the smart assets and sum fee pools, then fetched dynamic/bitasset data by id; it now derives smart assets from a dense walk of the 2.4.x implementation space plus one `get_assets` call (extended objects, so `total_in_collateral` stays available), sums fee pools from a 2.3.x walk, looks up symbols only for printed rows, uses the asset-scoped SameT/credit calls with `list_*` fallbacks on older nodes, and uses `list_htlcs` instead of probing the 1.16.0..1.16.99,999 range. The token report enumerates assets through the same dense 1.3.x walk (9 calls instead of 67 `list_assets` pages), fetches rich-list pages in parallel (with one sentinel page so a mid-scan rank shift cannot truncate the list), and raises the per-asset `get_limit_orders` sweep concurrency from 12 to 32 while keeping `--no-orders` as the fast path. The shared walks live in new `modules/chain_scan.ts`, which batches 1000 ids per call, halves the batch on nodes that refuse it, and defines `--gap` as exactly "gap consecutive missing ids" so results no longer depend on batch size; scans that hit their id limit now warn instead of silently shortening a bucket. Measured on mainnet: BTS ~92s → ~20s and token full runs ~50s → ~19s (~29s → ~12s with `--no-orders`), with outputs unchanged apart from chain drift. Covered by new `tests/test_chain_scan.ts` and pinned browser-safe in `scripts/verify-browser-bundle.ts`.
20
+
21
+ - **Refactor(cli)**: centralize report terminal output — the file-writing commands each re-implemented the same furniture: the section header (two copies), a warning block (`! ` in one report, `• ` in the other), the muted trailing summary, the `[Tag] Loading …` opener, and a saved-file trailer that had drifted into four spellings. `modules/cli_progress.ts` now owns all of them (`loadingLine`, `section`, `warningLines`/`warningsBlock`, `summaryLine`, `savedLine` with an optional `kind` so a mixed-case label still reads "Open report"), and `modules/cli_colors.ts` exports `colorize()`, the local `c(color, text)` wrapper scripts kept redeclaring; `CLI_TAGS` covers the remaining tags. Behavioral impact: every command that writes a file ends with the same clickable `file://` trailer (the research analyzers now get a link too), warnings render identically everywhere, and the BTS report no longer prints a duplicate plain `HTML report: <path>` plus `Collateral:` source line (provenance moved into the HTML footer). `--quiet`, `--json` and `--no-html` keep their behavior: no trailer when no file is written. Covered by the extended `tests/test_cli_progress.ts`.
22
+
23
+ - **Fix(order)**: stop stale-grid re-buys after a fill — a live incident had the bot buying at successively higher prices: a multi-minute stale broadcast region deferred the fill queue, then the post-fill targeted reconcile derived its window from a master that still held the filled slots as ACTIVE and re-created same-side orders at the top of the un-crawled rail, which filled within seconds. The root cause was upstream: fills whose order id no longer sat on an ACTIVE/PARTIAL slot were dropped ("order not found in active grid") after their accounting was booked, so neither the last-fill pivot nor the owed boundary crawl learned the real execution price, and every downstream geometry gate compared against a stale, higher pivot. Four gates now close it: (1) `hasUnsettledFills` defers the targeted reconcile and the window top-up while fills are queued, draining, in flight or owed a crawl, while 1:1 repairs (cancelled-slot replacement, vacated-rail refill) still run so a rail is never left un-repaired; (2) `SyncEngine._absorbUnmatchedFill` attributes such a fill to the slot that still owns the chain id and records the pivot plus owed crawl from the real execution price, without mutating the slot or already-booked accounting, and dry runs never grow the crawl ledger; (3) `isLastFillPlacementBlocked` applies the direction rule plus a same-grid-level refusal to every reconcile placement (both create paths and the re-pricing relocation), keeping a same-price relocation exempt as an adoption; (4) `_pickVirtualSlotsToActivate` uses the same predicate so the pick budget rolls to the next level instead of being spent on a level the create would refuse, restoring the documented rotate-to-bottom/counter-SELL behaviour. Behavioral impact: fail-closed during an unsettled fill window (a top-up waits one cycle, and a level on the wrong side of the last fill waits for the crawl); no new orders, sizes or boundary semantics. Docs: `GRID_RECONCILE` (fill discipline) and `LOGGING`. Covered by new `tests/test_grid_fill_discipline.ts` and `tests/test_fill_attribution_virtual_slot.ts`.
24
+
25
+ - **Fix(order)**: attribute orphan fills by price and repair dark levels — a follow-up audit of the stale-grid fix found six gaps of the same class, the first in the fix itself. Fill attribution looked the slot up by chain order id, but `virtualizeOrder()` nulls `orderId` on every virtualisation path, so the absorption never fired for the very fills it was written for (the re-delivered fills logged "order not found in active grid" and the reconcile re-created their levels); attribution now falls back to the genesis ladder level of the execution price (the same authority pass 2 uses for adoption), refuses prices outside the frozen rail so a shelf/manual order can never arm the pivot, and only owes a crawl for a hole the grid owns. A slot virtualised while its order stayed live on chain counted as inactive for window accounting while its order still counted in `chainCount`, so the side reported a shortfall it could never repair and the planner saw a free level that already held an order; `reviveVirtualSlotFromChain` now re-materialises such a slot in place (master-only, no broadcast) when the chain order rests at that slot's own level, wired into sync pass 1 and reconcile Phase 1, so a rotation alias whose cancel has not landed is never resurrected. Duplicate CREATEs are closed by keying slot occupancy on the id alone (any state) instead of `isOrderOnChain()`, with a soft reason that withholds only a possibly-landed CREATE rather than aborting the batch, and sync pass 1 clears a genuinely stale id on a non-placed slot without booking a fill (freshly assigned ids are deferred). The orphan-credit sweep now attributes before crediting through the same shared helper, the spread-correction planner uses the same ladder-snapped predicate as the broadcast guards instead of planning same-level creates that were refused, and the re-stamp leak counter uses the same same-level comparison its comment claims to detect. Behavioral impact: no new orders, sizes or boundary semantics; attribution and the revive are master-side only, the revive is level-gated, and everything stays fail-closed for one cycle while fills are unsettled. Docs: `GRID_RECONCILE` (identities, revive, occupancy) and `LOGGING`. Covered by extended fill-attribution, revive, occupancy, hole-gate and planner/guard-parity tests.
26
+
27
+ - **Fix(order)**: anchor-aware residual allow-list, pivot clock provenance and read-time TTL — three defects of the same shape (1) `reanchorBoundaryFromLastFill` derives the boundary from the fill batch's extremum, but the in-band allow-list that lets the fill's own PARTIAL residual survive was keyed on the last-processed pivot, so for every chunked sweep whose furthest fill was not the pivot the list matched nothing and the re-anchor was refused as `unsafe: placed_order_in_band` — exactly the shape the extremum resolution exists for; the list is now keyed on the anchor and stays narrow (one explicit slot, same side, same ladder level; REANCHOR-21 pins that a foreign in-band order still refuses). (2) `rearmLastFillPivotFromMarketFill` read `_lastFilledAt || _lastMarketFillAt` while the price came from the market-row resolver, so a market-row price could inherit a fresh book-seed timestamp and then re-stamp `_lastMarketFillAt` with it, refreshing the 24h lifetime on every rebuild until the row never expired; price, side and clock now travel as one row. (3) The pivot lifetime only existed at restore, so a long-lived process kept a >24h fill vetoing one side forever even though the geometry-bind watchdog reports that a fill or the pivot TTL restores the side; the TTL is now enforced where the reference is read, in both entry points, so that line is true with or without a restart, while an unknown age (legacy managers, the ambiguous two-sided book seed) never expires. `recordRestampBuyAboveAnchor` reads the same reference the guard does. Centralisation: one TTL reader and expiry predicate for all four sites (both restores and both read paths), one row reader with live/market adapters replacing four near-copies, and expiry logged once per expired value rather than per probe. Deliberately unchanged: the COW build lane keeps judging a ladder-snapped pivot (`resolveOnGridPivot`, tolerance one increment) rather than the raw placement predicate, pinned by PIVOT-004 and a `GRID_RECONCILE` note. Behavioral impact: a chunked sweep can now complete its re-anchor instead of stalling, and a side whose last fill is older than 24h is placeable again (the documented lifetime, already true across a restart); no new orders, sizes or boundary semantics, and no persistence-contract change. Docs: `COW_INVARIANTS`, `GRID_PRICE_INVARIANT`, `GRID_RECONCILE`, `LOGGING`, `ORDER_ENGINE_POST_1.0_RETROSPECTIVE`. Tests: REANCHOR-20/21, REARM-6/7/8, LFP-10, PIVOT-004, plus two fixtures corrected because they hard-coded a fill date.
28
+
29
+ - **Docs**: align the CLI reference and document the shared lookup, scan and trailer — `dexbot help` and the README "Bot Management" block disagreed on both order and naming: the block opened with the runtime-only `status` (spelled as its `stat` alias), taught the `liq` alias while the help called `liquid` canonical, and never listed `dw` or `rich`, so a reader could not know that `tv`/`dw` take the same targets or that `rich` exists. Both surfaces now use one investigation-order sequence (grid state and its data export, then market research, then accounting/chain context, then maintenance); the README moves `status` into the runtime block above and regroups the rest into those clusters, lists `liquid` instead of `liq`, corrects `asset <bts/token>` to `<bts|symbol>`, and the help Analysis group is reordered to match with `liq`/`liqu`/`liquidity` moved into the `liquid` description; `CLI_EXAMPLES` drops its alias-first snippet. `modules/README.md` lists the two new browser-safe modules (`asset_lookup`, `chain_scan`) and the widened `cli_colors`/`cli_progress` responsibilities, and `scripts/README.md` states the two cross-cutting rules (case-insensitive asset symbols through `modules/asset_lookup.ts`, one terminal trailer through `modules/cli_progress.ts`) and records how 1.13.x/1.15.x objects are enumerated now that no per-asset index exists. Docs and help text only: nothing is renamed, added or removed — `stat`, `liq`, `liqu`, `liquidity` and `a` still resolve. The CLI alias test's help-shape assertions are updated to match the new layout (`liquid` row plus `aliases: liq, liqu, liquidity`), since the previous `liq <target>` expectation no longer described the documented output. Full suite: 341/341 files (`npm test`, 14 live tests skipped); `typecheck`, `check:any`, `typecheck:analysis` and `verify:browser-bundle` clean.
30
+
5
31
  ## [1.6.18] - 2026-11-01 - Partial-Fill Re-Anchor Recovery, Rail-Derived Boundary & Live Fill Prices, Edge-Fill Pivot Exclusion, Guard Arity Pinning, CLI `--flag=value`, Export-Surface Cleanup
6
32
 
7
33
  ### 2026-11-01
package/README.md CHANGED
@@ -317,6 +317,7 @@ Defaults in [`modules/constants.ts`](modules/constants.ts) are overridable at gl
317
317
  `dexbot start` is the recommended production runtime (global install). Repo-root users can run `./unlock` instead. It runs the selected bot set as one monolithic bot process, with the credential daemon and market adapter in separate helper processes. Monolithic start/stop/reload/restart controls apply to the whole runtime, not to individual bots: a bot argument (e.g. `dexbot reload <bot>`) is validated and then folds into the whole-runtime action with a notice. Per-bot control needs `--isolated` (one supervisor process per bot, then `stop`/`reload`/`restart <bot>` acts on just that bot). `delete` and `status` are whole-runtime only. `dexbot help` detects which runtime is up (monolithic, isolated, or PM2) and lists the controls for that mode.
318
318
 
319
319
  ```bash
320
+ dexbot status # Runtime health: credential daemon, adapter, bots
320
321
  dexbot start/stop # Stop/start the monolithic runtime
321
322
  dexbot start --dryrun # Dry-run (no transactions broadcast)
322
323
  dexbot reload [<bot>] # Reload (monolithic: whole runtime; isolated: one bot)
@@ -329,24 +330,29 @@ First-run details and common mistakes are covered in the [BitShares Onboarding T
329
330
  ## 🛠️ Bot Management
330
331
 
331
332
  ```bash
332
- dexbot key # Master password/keyring
333
- dexbot bot # Interactive bot configurator
334
-
335
- dexbot reset {all|<bot>} # Regenerate grid
336
- dexbot disable {all|<bot>} # Disable bot in config
337
- dexbot enable {all|<bot>} # Enable bot in config
338
-
339
- dexbot stat # Runtime status (unlock or PM2)
340
- dexbot order [<bot>] # Analyze order grids (--export → HTML to analysis/charts/)
341
- dexbot tv <bot|pool|A/B> # TradingView 1h chart with AMA overlay (default: 3 months)
342
- dexbot pnl <bot|account> # HTML PnL report (--month N, optional --pair A/B)
343
- dexbot credit [<bot>] # Live summed MPA + borrowed-credit positions
344
- dexbot export <bot> # Export trades + settings (CSV/JSON) for analysis/
345
-
346
- dexbot update # Update DEXBot2
347
- dexbot clear # Delete log files in <profiles>/logs
348
- dexbot default # Reset settings to defaults
349
- dexbot help # Grouped command reference
333
+ dexbot key # Master password/keyring
334
+ dexbot bot # Interactive bot configurator
335
+
336
+ dexbot reset {all|<bot>} # Regenerate grid
337
+ dexbot disable {all|<bot>} # Disable bot in config
338
+ dexbot enable {all|<bot>} # Enable bot in config
339
+
340
+ dexbot order [<bot>] # Grid state: spread, increment, funds (--export → HTML)
341
+ dexbot export <bot> # Trades + settings → CSV/JSON for analysis/
342
+
343
+ dexbot tv <bot|pool|A/B> # TradingView 1h chart with AMA overlay (default: 3 months)
344
+ dexbot dw <bot|pool|A/B> # Dynamic-weight research chart (same targets/flags as tv)
345
+ dexbot liquid <bot|pool|A/B> # Liquidity depth: order book + AMM pool (aliases: liq, liqu)
346
+
347
+ dexbot pnl <bot|account> # HTML PnL report (--month N, optional --pair A/B)
348
+ dexbot credit [<bot>] # Live summed MPA + borrowed-credit positions
349
+ dexbot asset <bts|symbol> # Supply distribution + HTML report (short: dexbot a bts)
350
+ dexbot rich <asset...> # Top holders per asset
351
+
352
+ dexbot update # Update DEXBot2
353
+ dexbot clear # Delete log files in <profiles>/logs
354
+ dexbot default # Reset settings to defaults
355
+ dexbot help # Grouped command reference (runtime, trading, config, analysis, files)
350
356
  ```
351
357
 
352
358
  ## 🎯 PM2 Process Management
@@ -26,6 +26,7 @@ Tools that inspect DEXBot trading behavior and the market data it operates on. O
26
26
  | [`analyze_risk_profile.ts`](#risk-profile-analyzer-analyze_risk_profilets) | "How wide should my Safe Range clamps be?" | `node dist/analysis/analyze_risk_profile.js --bot-key <bot-key>` |
27
27
  | [`analyze_trade_heatmap.ts`](#trade-heatmap-analyze_trade_heatmapts) | "Where did trade volume cluster vs the AMA?" | `node dist/analysis/analyze_trade_heatmap.js --bot-key <bot-key>` |
28
28
  | [`tradingview/analyze_tradingview.ts`](#tradingview-chart-tradingviewanalyze_tradingviewts) | "Just give me a candle chart" | `dexbot tv <bot-key>` |
29
+ | [`analyze_liquidity.ts`](#liquidity-depth-chart-analyze_liquidityts) | "Where is the pair's real liquidity — order book, AMM pool, or both?" | `npm run analysis:liquidity -- --pair TOKENA/TOKENB` |
29
30
  | [`analyze_dynamic_weight.ts`](#dynamic-weight-research-analyze_dynamic_weightts) | "Are buy/sell weights tuned for this regime?" | `dexbot dw <bot-key>` |
30
31
  | [`analyze_volatility.ts`](#volatility-analyze_volatilityts) | "Both weights clipped too hard / not enough?" | `node dist/analysis/analyze_volatility.js --bot-key <bot-key>` |
31
32
  | [`analyze_regime.ts`](#supporting-sub-signals) | "Is the trend/chaos gate too aggressive?" | `node dist/analysis/analyze_regime.js --bot-key <bot-key>` |
@@ -302,6 +303,91 @@ Exit code `0` = pass, `2` = violations found, `1` = fatal error. Bot keys resolv
302
303
 
303
304
  ## Charts & Visualization
304
305
 
306
+ ### Liquidity Depth Chart (`analyze_liquidity.ts`)
307
+
308
+ Blends one pair's live limit-order book with its constant-product AMM pool into a
309
+ single cumulative-depth chart (the PoolTool depth view, rebuilt with the vendored
310
+ uPlot runtime). The chart plots **both** liquidity sources side by side as
311
+ independent curves — they are deliberately **not summed**, because an on-chain
312
+ order and an AMM reserve are different claims on liquidity. You can see which
313
+ source supplies the depth at a given price, where the pool price sits relative
314
+ to the book mid, and how far the two diverge.
315
+
316
+ - **Price axis**: quote per base (B/A), e.g. `QUOTE per BASE`
317
+ - **Depth axis**: cumulative quote liquidity (e.g. BTS) at or better than that price;
318
+ click the right y-axis to toggle the same curves into cumulative base units
319
+ (e.g. BASE) — both are precomputed server-side
320
+ - **Click the x-axis to invert price** (`1/p`, e.g. `BASE per QUOTE`). Inversion
321
+ also swaps bid/ask roles and flips the depth asset to the new quote, so the
322
+ chart stays a valid book view rather than a mirrored picture with the wrong sides
323
+ - **Bids**: order-book bids (`quote` of every bid at price >= p) drawn next to
324
+ the pool's `quoteReserve * (1 - sqrt(p / p0))` curve
325
+ - **Asks**: order-book asks (`quote` of every ask at price <= p) drawn next to
326
+ the pool's `quoteReserve * (sqrt(p / p0) - 1)` curve
327
+
328
+ The window is symmetric around the pool price (book mid when there is no pool),
329
+ so the whole `0.5x .. 1.5x` range is visible by default. The chain's
330
+ `get_order_book` side convention is handled by the tool. Pool depth is the exact
331
+ constant-product solution (verified against the `x*y = k` swap invariant); the
332
+ AMM taker fee is **not** applied to the curve — matching PoolTool — and is shown
333
+ in the header as metadata only. PoolTool's `depthchart.py` plots the same curves
334
+ with the reciprocal price convention (`amount_y * (sqrt(p_pool/p) - 1)` for buys
335
+ and `amount_y * (1 - sqrt(p_pool/p))` for sells).
336
+
337
+ Order-book depth prefers `get_limit_orders` (up to ~300 levels per side) over
338
+ `get_order_book`, which many nodes cap at 50 — otherwise thin far levels are
339
+ silently missing from the curves. If the wider call is unavailable the tool
340
+ falls back to the classic 50-level endpoint.
341
+
342
+ All displayed numbers use DEXBot's existing 4-active-digit formatters —
343
+ `formatCurrency` for prices/percentages and `formatFundsValue` for amounts
344
+ (`modules/order/format.ts`) — embedded into the generated page so it renders
345
+ identically offline.
346
+
347
+ ```bash
348
+ # Default example pair
349
+ npm run analysis:liquidity -- --pair TOKENA/TOKENB
350
+
351
+ # CLI wrapper: resolves a bot key, a pool (id or pool token) or a pair
352
+ dexbot liq TOKENA/TOKENB --range 0.25
353
+ dexbot liq <bot-key>
354
+ dexbot liq 1.19.123 # pool by id
355
+ dexbot liq <pool-token-symbol> # pool by its LP share-asset symbol
356
+ # Aliases: liqu, liquidity (canonical command: liquid)
357
+
358
+ # Tighter window, deeper book, explicit pool
359
+ node dist/analysis/analyze_liquidity.js \
360
+ --pair TOKENA/TOKENB --range 0.25 --depth 50 --pool 1.19.123 --json liquidity.json
361
+
362
+ # Any pair by symbol or asset id
363
+ node dist/analysis/analyze_liquidity.js --base 1.3.123 --quote TOKENB --chart /tmp/lp.html
364
+
365
+ # One pool by id or pool token (legs derived from the pool)
366
+ node dist/analysis/analyze_liquidity.js --pool 1.19.123 --chart /tmp/pool.html
367
+ node dist/analysis/analyze_liquidity.js --pool <pool-token-symbol> --json pool.json
368
+ ```
369
+
370
+ <details><summary><mark>Options (click to expand)</mark></summary>
371
+
372
+ | Flag | Default | Description |
373
+ |------|---------|-------------|
374
+ | `--base` / `--quote` | — | Assets by symbol or `1.3.x` id (required via `--pair` or `--base` + `--quote`) |
375
+ | `--pair <base>/<quote>` | — | Shorthand for `--base` + `--quote` (also accepts `:`) |
376
+ | `--pool` | deepest pool | One pool: id (`133` / `1.19.133`) or its pool token (LP share-asset symbol). With no `--base`/`--quote`, both legs come from the pool |
377
+ | `--depth` | `300` | Order-book levels per side; fetched via `get_limit_orders` (commonly capped at 300) with a `get_order_book` fallback |
378
+ | `--range` | `0.5` | Window half-width as a fraction of the center price |
379
+ | `--steps` | `400` | Price samples across the window (exact book levels are always added) |
380
+ | `--chart` | `analysis/charts/liquidity_<base>_<quote>.html` | HTML output path |
381
+ | `--json` | — | Optional JSON dump of the sampled series and summary |
382
+ | `--quiet` | off | Suppress the console summary |
383
+
384
+ </details>
385
+
386
+ Generation is read-only and uses an ephemeral chain connection (`analysis/chain_pool.ts`),
387
+ so it never disturbs a running bot. The output is a single self-contained HTML file
388
+ (uPlot inlined, no CDN or sibling assets); hovering shows book/pool depth at
389
+ the cursor price, scroll zooms, drag pans, double-click resets.
390
+
305
391
  ### Trade Heatmap (`analyze_trade_heatmap.ts`)
306
392
 
307
393
  Generates a 2D heatmap + summed histogram showing where trade volume concentrates relative to AMA deviation. Time-slice rows show how the distribution evolved; the bottom histogram shows the aggregate bell-curve shape with threshold annotations.
@@ -347,9 +433,10 @@ Generates a standalone TradingView-style HTML chart with candle OHLC, SMA, AMA,
347
433
 
348
434
  # Recommended one-step: bot, pool, or pair (fetches candles + renders, default 3 months)
349
435
  dexbot tv <bot-key>
350
- dexbot tv 133
436
+ dexbot tv 133 # pool by id
437
+ dexbot tv <pool-token-symbol> # pool by its LP share-asset symbol
351
438
  dexbot tv TOKENA/TOKENB
352
- dexbot tv BTS/HONEST.USD --feed # opt-in: MPA price-feed history instead of market candles
439
+ dexbot tv BTS/HONEST.USD --feed # opt-in: MPA price-feed history instead of market candles
353
440
  # Manual: bot-key (auto-resolves candle file and AMA settings)
354
441
  npm run analysis:tradingview -- --source market_adapter --bot-key <bot-key>
355
442
 
@@ -374,7 +461,8 @@ Interactive 4-panel chart for the asymmetric path: AMA slope plus Kalman confirm
374
461
  # Recommended one-step (advanced): bot, pool, or pair — fetches candles and renders,
375
462
  # same pipeline as `dexbot tv`, default 3 months
376
463
  dexbot dw <bot-key>
377
- dexbot dw 133 --month 6
464
+ dexbot dw 133 --month 6 # pool by id
465
+ dexbot dw <pool-token-symbol> --month 6
378
466
  dexbot dw TOKENA/TOKENB --month 1
379
467
 
380
468
  # Direct analyzer (own candle files, research knobs --alpha/--gain/--dw/--lb/--clip)
@@ -543,6 +631,7 @@ These npm scripts wrap common analysis runners:
543
631
  | `npm run analysis:tradingview` | `node dist/analysis/tradingview/analyze_tradingview.js` |
544
632
  | `npm run analysis:trade-pnl` | `node dist/analysis/trade_profitability.js` |
545
633
  | `npm run analysis:grid-check` | `node dist/analysis/grid_correction_check.js` |
634
+ | `npm run analysis:liquidity` | `node dist/analysis/analyze_liquidity.js` |
546
635
  | `npm run ama:chart:lp-local` | `node dist/analysis/ama_fitting/generate_unified_comparison_chart.js` (chart also auto-generated by optimizer) |
547
636
 
548
637
  All accept `--` forwarded flags.
@@ -554,6 +643,9 @@ npm run analysis:tradingview -- --source market_adapter --bot-key <bot-key>
554
643
  # Trade PnL
555
644
  npm run analysis:trade-pnl -- 1.2.123456 --hours 720
556
645
 
646
+ # Liquidity depth (order book + AMM pool)
647
+ npm run analysis:liquidity -- --pair TOKENA/TOKENB --range 0.5
648
+
557
649
  # LAST-FILL-GUARD check
558
650
  npm run analysis:grid-check -- --bot-key <bot-key> --hours 168
559
651
 
package/claw/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dexbot2-claw",
3
- "version": "1.6.18",
3
+ "version": "1.7.0",
4
4
  "private": true,
5
5
  "description": "Claw bridge and runtime integration layer for BitShares and DEXBot2.",
6
6
  "type": "module",
@@ -2,7 +2,7 @@
2
2
  "id": "bitshares-claw",
3
3
  "name": "BitShares Claw",
4
4
  "description": "Native BitShares and DEXBot2 tools from the DEXBot2 claw integration",
5
- "version": "1.6.18",
5
+ "version": "1.7.0",
6
6
  "skills": [
7
7
  "skills"
8
8
  ],
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "bitshares-claw-openclaw-plugin",
3
3
  "private": true,
4
- "version": "1.6.18",
4
+ "version": "1.7.0",
5
5
  "type": "module",
6
6
  "main": "index.js"
7
7
  }
@@ -22,6 +22,7 @@ import { computeAmaSlopeWeights, createAmaSlopeClipTracker } from '../market_ada
22
22
  import { MARKET_ADAPTER } from '../modules/constants.js';
23
23
  import { PATHS } from '../modules/paths.js';
24
24
  import { writeChartFile, toFileUrl } from './chart_utils.js';
25
+ import { CLI_TAGS, savedLine } from '../modules/cli_progress.js';
25
26
  import { getCandleClose } from './math_utils.js';
26
27
  import { resolveSource, listAvailableBots } from './resolve_source.js';
27
28
  import { baseAnalysisConfig, consumeCommonAnalysisArg } from './analyze_args.js';
@@ -195,7 +196,7 @@ async function main() {
195
196
  }, config.title || 'Dynamic Weight Research Tool');
196
197
  writeChartFile(config.chartFile, html);
197
198
  if (!config.quiet)
198
- console.log(`\n[DynamicWeight] ✓ Chart saved. Open chart: (${toFileUrl(config.chartFile)})`);
199
+ console.log(savedLine(CLI_TAGS.dynamicWeight, 'Chart', toFileUrl(config.chartFile)));
199
200
  }
200
201
  catch (err) {
201
202
  console.error(`[DynamicWeight] Error: ${getErrorMessage(err)}`);
@@ -18,7 +18,8 @@ import { calculateAMA } from '../market_adapter/core/strategies/ama.js';
18
18
  import { computeAmaSlopeWeights, createAmaSlopeClipTracker } from '../market_adapter/core/strategies/ama_slope_model.js';
19
19
  import { MARKET_ADAPTER } from '../modules/constants.js';
20
20
  import { getCandleClose } from './math_utils.js';
21
- import { writeChartFile } from './chart_utils.js';
21
+ import { writeChartFile, toFileUrl } from './chart_utils.js';
22
+ import { CLI_TAGS, savedLine } from '../modules/cli_progress.js';
22
23
  import { PATHS } from '../modules/paths.js';
23
24
  import { resolveSource, listAvailableBots } from './resolve_source.js';
24
25
  import { baseAnalysisConfig, consumeCommonAnalysisArg } from './analyze_args.js';
@@ -124,7 +125,7 @@ async function main() {
124
125
  const html = generateHTML({ allResults, amaConfig, clipPct: MARKET_ADAPTER.DYNAMIC_WEIGHT_CLIP_PERCENTILE }, 'Kalman Trend Analysis');
125
126
  writeChartFile(config.chartFile, html);
126
127
  if (!config.quiet)
127
- console.log(`[Kalman] ✓ Chart saved to ${config.chartFile}`);
128
+ console.log(savedLine(CLI_TAGS.kalman, 'Chart', toFileUrl(config.chartFile)));
128
129
  }
129
130
  catch (err) {
130
131
  console.error(`[Kalman] Error: ${getErrorMessage(err)}`);
@@ -0,0 +1,17 @@
1
+ #!/usr/bin/env node
2
+ interface LiquidityConfig {
3
+ base: string;
4
+ quote: string;
5
+ poolId: string | null;
6
+ depth: number;
7
+ range: number;
8
+ steps: number;
9
+ chartFile: string | null;
10
+ jsonFile: string | null;
11
+ quiet: boolean;
12
+ help: boolean;
13
+ }
14
+ declare function parseArgs(argv: string[]): LiquidityConfig;
15
+ export { parseArgs };
16
+ export type { LiquidityConfig };
17
+ //# sourceMappingURL=analyze_liquidity.d.ts.map