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
@@ -454,6 +454,15 @@ function reconcileGrid(masterGrid, targetGrid, targetBoundary, options = {}) {
454
454
  for (const [id, targetOrder] of targetGrid) {
455
455
  const masterOrder = masterGrid.get(id);
456
456
  if (!masterOrder || masterOrder.state === ORDER_STATES.VIRTUAL) {
457
+ // A VIRTUAL slot that still OWNS a chain order id is not a hole: the
458
+ // level already holds a live order (the dark-level state owned by the
459
+ // sync/startup revive path). Planning a CREATE here would place a
460
+ // second order at the same price. A genuinely stale id is cleared by
461
+ // sync pass 1 (`sync-clear-stale-id`), which makes the slot a plain
462
+ // hole again on the next cycle.
463
+ if (masterOrder && masterOrder.state === ORDER_STATES.VIRTUAL && masterOrder.orderId) {
464
+ continue;
465
+ }
457
466
  // Slot is empty or virtual - check if we need to fill it
458
467
  if (targetOrder.size > 0 && targetOrder.state === ORDER_STATES.ACTIVE) {
459
468
  // This is a hole that needs filling
@@ -573,7 +582,10 @@ function reconcileGrid(masterGrid, targetGrid, targetBoundary, options = {}) {
573
582
  let evacReady = [];
574
583
  try {
575
584
  if (options?.evacStreaks instanceof Map && hasPlanGeometry) {
576
- const candidates = detectGapEvacuationCandidates(masterGrid, validatedBoundary, planGapSlots);
585
+ const candidates = detectGapEvacuationCandidates(masterGrid, validatedBoundary, planGapSlots, {
586
+ assets: evacAssets,
587
+ genesis: options?.genesis ?? null
588
+ });
577
589
  const tick = updateGapEvacuationStreaks(options.evacStreaks, candidates);
578
590
  evacReady = tick.ready;
579
591
  if (evacReady.length > 0 && logger) {
@@ -764,8 +776,17 @@ function validateCreateTargetSlots(actions, orders, _assets = null, chainOrderCa
764
776
  if (!targetId || releasedSlotIds.has(targetId))
765
777
  continue;
766
778
  const current = orderMap.get(targetId);
767
- // isOrderOnChain already checks orderId is truthy
768
- if (current && isOrderOnChain(current)) {
779
+ // OCCUPANCY = the slot still owns a chain order ID, in ANY state.
780
+ // isOrderOnChain() (ACTIVE/PARTIAL only) was too narrow: a slot
781
+ // virtualised while its order was still live (phantom cleanup on a
782
+ // truncated read, refused-commit adoption) kept its orderId but read as
783
+ // "empty", so a CREATE could be planned onto a level that already held a
784
+ // live order (duplicate price level). A genuinely STALE id is cleared by
785
+ // sync pass 1 (`sync-clear-stale-id`), which turns the slot back into a
786
+ // plain hole on the next cycle — so this gate cannot strand a level.
787
+ const currentOwnsChainId = Boolean(current?.orderId);
788
+ const currentCreateUncertain = current?.createUncertain === true;
789
+ if (current && (isOrderOnChain(current) || currentOwnsChainId)) {
769
790
  violations.push({
770
791
  targetId,
771
792
  currentOrderId: current.orderId,
@@ -774,6 +795,19 @@ function validateCreateTargetSlots(actions, orders, _assets = null, chainOrderCa
774
795
  reason: 'slot_occupied'
775
796
  });
776
797
  }
798
+ else if (current && currentCreateUncertain) {
799
+ // A CREATE whose broadcast outcome is unknown. Unlike slot_occupied
800
+ // this is NOT proof of a live order, so it must not abort the whole
801
+ // batch (runPreBroadcastGuards only hard-aborts on slot_occupied) —
802
+ // it only withholds this CREATE until the uncertainty resolves.
803
+ violations.push({
804
+ targetId,
805
+ currentOrderId: current.orderId,
806
+ currentType: current.type,
807
+ currentState: current.state,
808
+ reason: 'slot_create_uncertain'
809
+ });
810
+ }
777
811
  if (action.order?.price != null && action.order?.type != null) {
778
812
  // Key on the BROADCAST price (action.order.price — the price
779
813
  // actually placed on chain), never the live slot price: layer-5
@@ -3,8 +3,9 @@
3
3
  *
4
4
  * Provides a unified IStorageAdapter interface for all filesystem operations.
5
5
  *
6
- * Usage:
7
- * const storage = require('./modules/storage').getStorage();
6
+ * Usage (from the repo root):
7
+ * import { getStorage } from './modules/storage/index.js';
8
+ * const storage = getStorage();
8
9
  * const data = storage.readJSON('/path/to/file.json');
9
10
  * storage.writeJSON('/path/to/file.json', { hello: 'world' });
10
11
  * if (storage.exists('/path/to/file.json')) { ... }
@@ -3,8 +3,9 @@
3
3
  *
4
4
  * Provides a unified IStorageAdapter interface for all filesystem operations.
5
5
  *
6
- * Usage:
7
- * const storage = require('./modules/storage').getStorage();
6
+ * Usage (from the repo root):
7
+ * import { getStorage } from './modules/storage/index.js';
8
+ * const storage = getStorage();
8
9
  * const data = storage.readJSON('/path/to/file.json');
9
10
  * storage.writeJSON('/path/to/file.json', { hello: 'world' });
10
11
  * if (storage.exists('/path/to/file.json')) { ... }
@@ -227,6 +227,15 @@ export interface BotLike {
227
227
  _lastDeferredHoldResyncAt: number;
228
228
  _lastGridPriceInvariantResyncAt: number;
229
229
  _lastSpreadStaleResyncAt: number;
230
+ /**
231
+ * Fill pivot (`price|type`) the geometry-bind (`last-fill-blocked`) escalation
232
+ * already re-centered for. A re-center does not move the pivot, so a second
233
+ * request on the same fill only churns the new generation; cleared whenever
234
+ * the spread heals.
235
+ */
236
+ _lastGeometryResyncPivotKey: string;
237
+ /** Pivot key the "re-center cannot clear this pivot" warning was logged for. */
238
+ _geometryResyncWarnedPivotKey: string;
230
239
  _gridLockHoldWarnAt: number;
231
240
  _outOfSpreadSince: number;
232
241
  _outOfSpreadStaleWarned: boolean;
@@ -1090,6 +1099,11 @@ export interface OrderManagerLike {
1090
1099
  _lastFilledPrice: number | null;
1091
1100
  _lastFilledType: string | null;
1092
1101
  _lastFilledAt: number | null;
1102
+ /**
1103
+ * Timestamp of the fill reference whose expiry was already logged, so the
1104
+ * read-time pivot TTL reports once per expired value instead of per probe.
1105
+ */
1106
+ _lastFillPivotExpiryLoggedAt?: number | null;
1093
1107
  lastFillPivotSource: 'fill' | 'book' | null;
1094
1108
  _lastMarketFillPrice?: number | null;
1095
1109
  _lastMarketFillType?: string | null;
@@ -3,8 +3,9 @@
3
3
  *
4
4
  * BitShares stores asset symbols canonically UPPERCASE, so the assetA and
5
5
  * assetB symbols of a bot pair are always UPPERCASE on chain.
6
- * `lookup_asset_symbols` is case-sensitive: a lowercase symbol resolves to
7
- * null (not an error), so a lowercase input silently drops the asset. Casing
6
+ * The chain's asset lookups (`get_assets` / `lookup_asset_symbols`) are
7
+ * case-sensitive: a lowercase symbol resolves to null (not an error), so a
8
+ * lowercase input silently drops the asset. Casing
8
9
  * also leaks into everything built from a resolved symbol: the `symbol` field
9
10
  * we attach to assets, chart titles, cache-file names, Kibana query terms, and
10
11
  * strict in-process comparisons such as `assetA === 'CORE'`. That is a
@@ -35,6 +36,16 @@ export declare function normalizeAssetSymbol(value: unknown): string;
35
36
  * mixed "id or symbol" reference (credit runtime, credential policy, pools).
36
37
  */
37
38
  export declare function normalizeAssetRef(value: unknown): string;
39
+ /**
40
+ * Both spellings of a human-typed asset reference: the reference as typed
41
+ * (trimmed) and its canonical UPPERCASE form. Resolvers query the canonical form
42
+ * first and retry the as-typed spelling only when that misses (see
43
+ * modules/asset_lookup.ts), because `get_assets` is case-sensitive and a node
44
+ * may still hold a non-canonical symbol. Object ids collapse to one entry.
45
+ *
46
+ * @returns [] for empty input, otherwise 1-2 distinct spellings.
47
+ */
48
+ export declare function assetSymbolCandidates(value: unknown): string[];
38
49
  /** Case- and whitespace-insensitive asset-symbol equality. */
39
50
  export declare function isSameAssetSymbol(a: unknown, b: unknown): boolean;
40
51
  /**
@@ -3,8 +3,9 @@
3
3
  *
4
4
  * BitShares stores asset symbols canonically UPPERCASE, so the assetA and
5
5
  * assetB symbols of a bot pair are always UPPERCASE on chain.
6
- * `lookup_asset_symbols` is case-sensitive: a lowercase symbol resolves to
7
- * null (not an error), so a lowercase input silently drops the asset. Casing
6
+ * The chain's asset lookups (`get_assets` / `lookup_asset_symbols`) are
7
+ * case-sensitive: a lowercase symbol resolves to null (not an error), so a
8
+ * lowercase input silently drops the asset. Casing
8
9
  * also leaks into everything built from a resolved symbol: the `symbol` field
9
10
  * we attach to assets, chart titles, cache-file names, Kibana query terms, and
10
11
  * strict in-process comparisons such as `assetA === 'CORE'`. That is a
@@ -50,6 +51,24 @@ export function normalizeAssetSymbol(value) {
50
51
  export function normalizeAssetRef(value) {
51
52
  return normalizeAssetSymbol(value);
52
53
  }
54
+ /**
55
+ * Both spellings of a human-typed asset reference: the reference as typed
56
+ * (trimmed) and its canonical UPPERCASE form. Resolvers query the canonical form
57
+ * first and retry the as-typed spelling only when that misses (see
58
+ * modules/asset_lookup.ts), because `get_assets` is case-sensitive and a node
59
+ * may still hold a non-canonical symbol. Object ids collapse to one entry.
60
+ *
61
+ * @returns [] for empty input, otherwise 1-2 distinct spellings.
62
+ */
63
+ export function assetSymbolCandidates(value) {
64
+ if (value === null || value === undefined)
65
+ return [];
66
+ const typed = String(value).trim();
67
+ if (!typed)
68
+ return [];
69
+ const canonical = normalizeAssetSymbol(typed);
70
+ return typed === canonical ? [canonical] : [typed, canonical];
71
+ }
53
72
  /** Case- and whitespace-insensitive asset-symbol equality. */
54
73
  export function isSameAssetSymbol(a, b) {
55
74
  const na = normalizeAssetSymbol(a);
@@ -0,0 +1,10 @@
1
+ /** Absolute path to an analysis script, e.g. ['tradingview','analyze_tradingview.js']. */
2
+ declare function analysisScriptPath(segments: string[]): string;
3
+ /**
4
+ * Resolve, run and validate an analysis script.
5
+ * Throws with a command-specific `label` when the build is missing or the
6
+ * renderer exits non-zero; child stdio is inherited.
7
+ */
8
+ declare function runAnalysisScript(segments: string[], args: string[], label: string): void;
9
+ export { analysisScriptPath, runAnalysisScript };
10
+ //# sourceMappingURL=analysis_runner.d.ts.map
@@ -0,0 +1,33 @@
1
+ 'use strict';
2
+ /**
3
+ * Spawn an analysis entry point (compiled `dist/analysis/**\/*.js`).
4
+ *
5
+ * Chart-style commands (`tv`, `dw`, `liquid`) all render through a separate
6
+ * analysis binary. This helper centralises the path resolution, existence
7
+ * check, project-root cwd, and exit-status handling so a missing build or a
8
+ * crashed renderer reports the same way everywhere.
9
+ */
10
+ import path from 'node:path';
11
+ import { fileURLToPath } from 'node:url';
12
+ const __filename = fileURLToPath(import.meta.url);
13
+ const __dirname = path.dirname(__filename);
14
+ import { PATHS } from '../modules/paths.js';
15
+ import { runRuntimeScript } from '../modules/launcher/runtime_entry.js';
16
+ /** Absolute path to an analysis script, e.g. ['tradingview','analyze_tradingview.js']. */
17
+ function analysisScriptPath(segments) {
18
+ return path.join(__dirname, '..', 'analysis', ...segments);
19
+ }
20
+ /**
21
+ * Resolve, run and validate an analysis script.
22
+ * Throws with a command-specific `label` when the build is missing or the
23
+ * renderer exits non-zero; child stdio is inherited.
24
+ */
25
+ function runAnalysisScript(segments, args, label) {
26
+ runRuntimeScript(analysisScriptPath(segments), args, {
27
+ label,
28
+ cwd: PATHS.PROJECT_ROOT,
29
+ nonZero: 'throw',
30
+ });
31
+ }
32
+ export { analysisScriptPath, runAnalysisScript };
33
+ //# sourceMappingURL=analysis_runner.js.map
@@ -25,6 +25,7 @@ import { getStorage } from '../modules/storage/index.js';
25
25
  const { readJSON } = getStorage();
26
26
  import { getErrorMessage } from '../modules/utils/errors.js';
27
27
  import { toFileUrl } from '../analysis/chart_utils.js';
28
+ import { CLI_TAGS, savedLine } from '../modules/cli_progress.js';
28
29
  import { isSameBotName, sanitizeKey } from '../modules/utils/sanitize_key.js';
29
30
  import { CLI_COLORS as colors } from '../modules/cli_colors.js';
30
31
  import { pathToFileURL } from 'node:url';
@@ -1420,7 +1421,7 @@ function generateHtmlReport(analyses) {
1420
1421
  const outPath = path.join(PATHS.ANALYSIS.CHARTS_DIR, 'order-analysis.html');
1421
1422
  fs.mkdirSync(PATHS.ANALYSIS.CHARTS_DIR, { recursive: true });
1422
1423
  fs.writeFileSync(outPath, html, 'utf-8');
1423
- console.log(`\n📄 Order Analysis saved. Open report: (${toFileUrl(outPath)})`);
1424
+ console.log(savedLine(CLI_TAGS.orders, 'Order Analysis', toFileUrl(outPath), 'report'));
1424
1425
  }
1425
1426
  function main() {
1426
1427
  const rawArgs = process.argv.slice(2);
@@ -0,0 +1,26 @@
1
+ #!/usr/bin/env node
2
+ type AssetKind = 'bts' | 'token';
3
+ interface AssetConfig {
4
+ /** Distribution analyzer to run, or null when no target was given. */
5
+ kind: AssetKind | null;
6
+ /** Token symbol or asset id (token kind only). */
7
+ asset: string | null;
8
+ /** Flags forwarded verbatim to the analyzer. */
9
+ scriptArgs: string[];
10
+ help: boolean;
11
+ }
12
+ declare const CORE_ASSET_ID = "1.3.0";
13
+ declare const ANALYZERS: Record<AssetKind, {
14
+ script: string;
15
+ label: string;
16
+ }>;
17
+ /**
18
+ * Split `<target> <flags...>` into the analyzer identity plus the untouched
19
+ * flag list. `bts` (and the core asset id) route to the core-asset analyzer;
20
+ * anything else is an issued-asset symbol/id. Flags are validated per target so
21
+ * a `bts`-only option cannot be silently accepted (and ignored) by the token
22
+ * analyzer, or vice versa.
23
+ */
24
+ declare function parseArgs(argv: string[]): AssetConfig;
25
+ export { parseArgs, ANALYZERS, CORE_ASSET_ID };
26
+ //# sourceMappingURL=asset.d.ts.map
@@ -0,0 +1,165 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+ /**
4
+ * Usage:
5
+ * dexbot a bts [options] # shorthand for `dexbot asset bts`
6
+ * dexbot a <symbol|1.3.x> [options] # shorthand for an issued asset
7
+ * dexbot asset bts [options]
8
+ * dexbot asset <symbol|1.3.x> [options]
9
+ *
10
+ * Thin router behind the two live-chain supply distribution analyzers:
11
+ * bts -> scripts/bts_distribution.js (core asset 1.3.0)
12
+ * <symbol|1.3.x> -> scripts/token_distribution.js (any issued UIA/MPA)
13
+ *
14
+ * The analyzers own the chain scan, the terminal report and the HTML output;
15
+ * this entry only picks the target script, validates that the forwarded flags
16
+ * belong to it, and keeps the option order untouched. Per-target flag reference
17
+ * stays in the analyzers: `node dist/scripts/bts_distribution.js --help`,
18
+ * `node dist/scripts/token_distribution.js --help`.
19
+ */
20
+ import path from 'node:path';
21
+ import { dirname as _esmDirname } from 'node:path';
22
+ import { fileURLToPath, pathToFileURL } from 'node:url';
23
+ import { PATHS } from '../modules/paths.js';
24
+ import { getErrorMessage } from '../modules/utils/errors.js';
25
+ import { runRuntimeScript } from '../modules/launcher/runtime_entry.js';
26
+ const __filename = fileURLToPath(import.meta.url);
27
+ const __dirname = _esmDirname(__filename);
28
+ /** Shared by both analyzers. */
29
+ const COMMON_VALUE_FLAGS = ['--node', '--detail', '--vesting-max', '--gap', '--html'];
30
+ const COMMON_BOOLEAN_FLAGS = ['--json', '--no-html'];
31
+ /** Core-asset (BTS) analyzer only. */
32
+ const BTS_VALUE_FLAGS = ['--holders', '--circulating'];
33
+ /** Issued-asset (token) analyzer only. */
34
+ const TOKEN_VALUE_FLAGS = ['--concurrency'];
35
+ const TOKEN_BOOLEAN_FLAGS = ['--no-orders'];
36
+ const CORE_SYMBOL = 'BTS';
37
+ const CORE_ASSET_ID = '1.3.0';
38
+ const ANALYZERS = {
39
+ bts: { script: 'bts_distribution.js', label: 'BTS distribution analyzer' },
40
+ token: { script: 'token_distribution.js', label: 'Token distribution analyzer' },
41
+ };
42
+ const USAGE_SUFFIX = 'Usage: dexbot asset <bts|symbol|1.3.x> [options]';
43
+ function printUsage() {
44
+ console.log(USAGE_SUFFIX);
45
+ console.log('Live-chain supply distribution: where an asset sits across accounts, collateral,');
46
+ console.log('pools, orders, vesting and governance locks. Read-only (no keys, no transactions).');
47
+ console.log('Shorthand: dexbot a <bts|symbol|1.3.x>.');
48
+ console.log('');
49
+ console.log(' bts Core-asset supply distribution (BTS, 1.3.0)');
50
+ console.log(' <symbol|1.3.x> Issued-asset distribution (UIA/MPA) by symbol or object id');
51
+ console.log('');
52
+ console.log('Options (both targets):');
53
+ console.log(' --node URL Pin a WebSocket node (repeatable; default built-in pool)');
54
+ console.log(' --detail N Rows in detail tables');
55
+ console.log(' --vesting-max N Highest 1.13.x object id to probe');
56
+ console.log(' --gap N Stop id scans after N consecutive missing ids');
57
+ console.log(' --html PATH Report path');
58
+ console.log(' --no-html Do not write an HTML report');
59
+ console.log(' --json Print JSON instead of the terminal report (HTML still written)');
60
+ console.log(' --help Show this help');
61
+ console.log('');
62
+ console.log('bts only:');
63
+ console.log(' --holders N|all Liquid holders from asset_api (all = full rich list)');
64
+ console.log(' --circulating N Reference circulating supply to compare the derived float');
65
+ console.log('');
66
+ console.log('Issued asset only:');
67
+ console.log(' --no-orders Skip the per-asset limit-order scan (~20s on mainnet)');
68
+ console.log(' --concurrency N Concurrent get_limit_orders calls');
69
+ console.log('');
70
+ console.log('Output: analysis/charts/bts-distribution.html, analysis/charts/token-<SYMBOL>-distribution.html');
71
+ console.log('Full flag docs: node dist/scripts/bts_distribution.js --help');
72
+ console.log(' node dist/scripts/token_distribution.js --help');
73
+ }
74
+ /**
75
+ * Split `<target> <flags...>` into the analyzer identity plus the untouched
76
+ * flag list. `bts` (and the core asset id) route to the core-asset analyzer;
77
+ * anything else is an issued-asset symbol/id. Flags are validated per target so
78
+ * a `bts`-only option cannot be silently accepted (and ignored) by the token
79
+ * analyzer, or vice versa.
80
+ */
81
+ function parseArgs(argv) {
82
+ if (argv.some((arg) => arg === '--help' || arg === '-h')) {
83
+ return { kind: null, asset: null, scriptArgs: [], help: true };
84
+ }
85
+ const [first, ...args] = argv;
86
+ if (first === undefined)
87
+ return { kind: null, asset: null, scriptArgs: [], help: false };
88
+ if (first.startsWith('-')) {
89
+ throw new Error(`Expected a target (bts or an asset symbol/id). ${USAGE_SUFFIX}`);
90
+ }
91
+ const isCore = first.toLowerCase() === CORE_SYMBOL.toLowerCase() || first === CORE_ASSET_ID;
92
+ const kind = isCore ? 'bts' : 'token';
93
+ const asset = isCore ? null : first;
94
+ // `token` is not a word in this grammar — a target is either `bts` or the
95
+ // symbol itself. Catch the near-miss instead of looking up a symbol called
96
+ // "token" and reporting it as unknown.
97
+ if (asset !== null && asset.toLowerCase() === 'token' && args.length > 0 && !args[0].startsWith('-')) {
98
+ throw new Error('`token` is not a subcommand: pass the symbol directly (dexbot asset <symbol|1.3.x>).');
99
+ }
100
+ const valueFlags = new Set([...COMMON_VALUE_FLAGS, ...(kind === 'bts' ? BTS_VALUE_FLAGS : TOKEN_VALUE_FLAGS)]);
101
+ const booleanFlags = new Set([...COMMON_BOOLEAN_FLAGS, ...(kind === 'token' ? TOKEN_BOOLEAN_FLAGS : [])]);
102
+ const scriptArgs = [];
103
+ for (let i = 0; i < args.length; i++) {
104
+ const arg = args[i];
105
+ if (arg === '-h' || arg === '--help')
106
+ continue;
107
+ const eq = arg.startsWith('--') ? arg.indexOf('=') : -1;
108
+ if (eq > 0) {
109
+ const flag = arg.slice(0, eq);
110
+ if (!valueFlags.has(flag))
111
+ throw new Error(`${unknownFlagMessage(flag, kind)} ${USAGE_SUFFIX}`);
112
+ scriptArgs.push(arg);
113
+ continue;
114
+ }
115
+ if (booleanFlags.has(arg)) {
116
+ scriptArgs.push(arg);
117
+ continue;
118
+ }
119
+ if (valueFlags.has(arg)) {
120
+ const value = args[++i];
121
+ if (value === undefined)
122
+ throw new Error(`Missing value for ${arg}`);
123
+ scriptArgs.push(arg, value);
124
+ continue;
125
+ }
126
+ throw new Error(`${unknownFlagMessage(arg, kind)} ${USAGE_SUFFIX}`);
127
+ }
128
+ return { kind, asset, scriptArgs, help: false };
129
+ }
130
+ function unknownFlagMessage(flag, kind) {
131
+ if (!flag.startsWith('-'))
132
+ return `Unexpected argument "${flag}".`;
133
+ if (kind === 'bts' && (TOKEN_VALUE_FLAGS.includes(flag) || TOKEN_BOOLEAN_FLAGS.includes(flag))) {
134
+ return `${flag} applies to issued assets only; the core asset uses --holders and --circulating.`;
135
+ }
136
+ return `Unknown flag "${flag}".`;
137
+ }
138
+ /** Spawn the analyzer with inherited stdio and mirror its exit status. */
139
+ function runAnalyzer(kind, scriptArgs, asset) {
140
+ const { script, label } = ANALYZERS[kind];
141
+ const args = asset ? [asset, ...scriptArgs] : scriptArgs;
142
+ process.exitCode = runRuntimeScript(path.join(__dirname, script), args, {
143
+ label,
144
+ cwd: PATHS.PROJECT_ROOT,
145
+ });
146
+ }
147
+ async function run() {
148
+ const config = parseArgs(process.argv.slice(2));
149
+ if (config.help || !config.kind) {
150
+ printUsage();
151
+ if (!config.help)
152
+ process.exitCode = 1;
153
+ return;
154
+ }
155
+ runAnalyzer(config.kind, config.scriptArgs, config.asset);
156
+ }
157
+ const invoked = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
158
+ if (invoked) {
159
+ run().catch((err) => {
160
+ console.error(`[Assets] Error: ${getErrorMessage(err)}`);
161
+ process.exit(1);
162
+ });
163
+ }
164
+ export { parseArgs, ANALYZERS, CORE_ASSET_ID };
165
+ //# sourceMappingURL=asset.js.map
@@ -54,6 +54,7 @@
54
54
  * never touches a running bot's connection) and has no runtime dependencies.
55
55
  *
56
56
  * Usage:
57
+ * dexbot asset bts [options] # CLI shortcut (also: dexbot a bts)
57
58
  * node dist/scripts/bts_distribution.js # terminal + HTML
58
59
  * node dist/scripts/bts_distribution.js --json # JSON + HTML
59
60
  * node dist/scripts/bts_distribution.js --no-html # terminal only