dexbot 1.6.12 → 1.6.13

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 (170) hide show
  1. package/CHANGELOG.md +33 -1
  2. package/analysis/README.md +9 -11
  3. package/analysis/ama_fitting/README.md +5 -3
  4. package/claw/README.md +1 -0
  5. package/claw/docs/AI_BOT_LIBRARY_API.md +2 -0
  6. package/claw/modules/claw_bridge.ts +0 -3
  7. package/claw/modules/claw_skill_md.ts +1 -0
  8. package/claw/package.json +3 -3
  9. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  10. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  11. package/claw/tsconfig.json +2 -2
  12. package/dist/analysis/ama_fitting/analyze_lambda_vs_slow.js +1 -14
  13. package/dist/analysis/ama_fitting/fetch_lp_candles.js +51 -41
  14. package/dist/analysis/ama_fitting/generate_unified_comparison_chart.d.ts +1 -24
  15. package/dist/analysis/ama_fitting/generate_unified_comparison_chart.js +36 -18
  16. package/dist/analysis/ama_fitting/optimizer_high_resolution.js +18 -66
  17. package/dist/analysis/analyze_args.d.ts +12 -0
  18. package/dist/analysis/analyze_args.js +20 -0
  19. package/dist/analysis/bot_fitting/backtest_ama_sweep.d.ts +1 -16
  20. package/dist/analysis/bot_fitting/backtest_ama_sweep.js +20 -101
  21. package/dist/analysis/bot_fitting/backtest_bot_fitting.js +26 -92
  22. package/dist/analysis/bot_fitting/backtest_lookback_drawdown.js +19 -34
  23. package/dist/analysis/bot_fitting/shared_utils.d.ts +71 -3
  24. package/dist/analysis/bot_fitting/shared_utils.js +124 -8
  25. package/dist/analysis/chart_ui.d.ts +30 -1
  26. package/dist/analysis/chart_ui.js +37 -1
  27. package/dist/analysis/fills_cache.d.ts +3 -23
  28. package/dist/analysis/fills_cache.js +3 -84
  29. package/dist/analysis/fills_source.d.ts +31 -1
  30. package/dist/analysis/fills_source.js +69 -1
  31. package/dist/analysis/grid_correction_check.d.ts +1 -23
  32. package/dist/analysis/grid_correction_check.js +15 -58
  33. package/dist/analysis/math_utils.d.ts +85 -1
  34. package/dist/analysis/math_utils.js +116 -1
  35. package/dist/analysis/price_sources.d.ts +22 -1
  36. package/dist/analysis/price_sources.js +23 -0
  37. package/dist/analysis/resolve_source.js +31 -10
  38. package/dist/analysis/trade_profitability.d.ts +6 -0
  39. package/dist/analysis/trade_profitability.js +23 -97
  40. package/dist/analysis/tradingview/analyze_tradingview.d.ts +1 -17
  41. package/dist/analysis/tradingview/analyze_tradingview.js +1 -1
  42. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +2 -15
  43. package/dist/analysis/trend_detection/backtest_ama_slope_huber.d.ts +1 -101
  44. package/dist/analysis/trend_detection/backtest_ama_slope_huber.js +22 -80
  45. package/dist/analysis/trend_detection/dynamic_weight_chart_generator.js +11 -37
  46. package/dist/analysis/trend_detection/volatility_chart_generator.js +9 -10
  47. package/dist/analysis/worker_pool.d.ts +38 -0
  48. package/dist/analysis/worker_pool.js +67 -0
  49. package/dist/dexbot.js +67 -48
  50. package/dist/market_adapter/ama_signal_runner.js +21 -54
  51. package/dist/market_adapter/candle_utils.d.ts +7 -1
  52. package/dist/market_adapter/candle_utils.js +11 -1
  53. package/dist/market_adapter/cli_args.d.ts +22 -0
  54. package/dist/market_adapter/cli_args.js +30 -0
  55. package/dist/market_adapter/core/config_normalizers.js +11 -6
  56. package/dist/market_adapter/core/kibana_candles.d.ts +3 -1
  57. package/dist/market_adapter/core/kibana_candles.js +3 -2
  58. package/dist/market_adapter/core/market_adapter_service.d.ts +85 -85
  59. package/dist/market_adapter/core/market_adapter_service.js +93 -158
  60. package/dist/market_adapter/core/signals/hurst_analyzer.d.ts +1 -6
  61. package/dist/market_adapter/core/signals/hurst_analyzer.js +1 -1
  62. package/dist/market_adapter/core/signals/permutation_entropy_analyzer.d.ts +1 -11
  63. package/dist/market_adapter/core/signals/permutation_entropy_analyzer.js +1 -1
  64. package/dist/market_adapter/inputs/fetch_book_data.js +0 -1
  65. package/dist/market_adapter/inputs/fetch_cex_synthetic_data.js +63 -107
  66. package/dist/market_adapter/inputs/fetch_lp_data.d.ts +8 -1
  67. package/dist/market_adapter/inputs/fetch_lp_data.js +25 -7
  68. package/dist/market_adapter/inputs/kibana_feed_source.js +4 -26
  69. package/dist/market_adapter/inputs/window_cache.d.ts +4 -72
  70. package/dist/market_adapter/inputs/window_cache.js +52 -177
  71. package/dist/market_adapter/interval_utils.d.ts +11 -1
  72. package/dist/market_adapter/interval_utils.js +16 -1
  73. package/dist/market_adapter/lp_chart_runner.d.ts +3 -0
  74. package/dist/market_adapter/lp_chart_runner.js +37 -19
  75. package/dist/market_adapter/market_adapter.js +27 -72
  76. package/dist/market_adapter/utils/data_discovery.d.ts +45 -1
  77. package/dist/market_adapter/utils/data_discovery.js +220 -27
  78. package/dist/market_adapter/utils/month_shards.d.ts +84 -0
  79. package/dist/market_adapter/utils/month_shards.js +237 -0
  80. package/dist/modules/account_bots.d.ts +1 -0
  81. package/dist/modules/account_bots.js +102 -121
  82. package/dist/modules/account_orders.d.ts +13 -0
  83. package/dist/modules/account_orders.js +38 -44
  84. package/dist/modules/bitshares-native/chain_client.d.ts +1 -1
  85. package/dist/modules/bitshares-native/chain_client.js +14 -13
  86. package/dist/modules/bitshares-native/resolvers.js +22 -25
  87. package/dist/modules/bitshares-native/serial/types.js +22 -50
  88. package/dist/modules/bitshares-native/signing_client.d.ts +1 -1
  89. package/dist/modules/bot_defaults.d.ts +2 -1
  90. package/dist/modules/bot_settings.d.ts +1 -1
  91. package/dist/modules/broadcast_failure.d.ts +2 -1
  92. package/dist/modules/chain_orders.d.ts +1 -1
  93. package/dist/modules/chain_orders.js +51 -96
  94. package/dist/modules/cli_start_onboarding.d.ts +2 -1
  95. package/dist/modules/constants.d.ts +7 -1
  96. package/dist/modules/constants.js +20 -1
  97. package/dist/modules/cr_planner.d.ts +1 -1
  98. package/dist/modules/cr_planner.js +1 -5
  99. package/dist/modules/credit_pricing.d.ts +2 -1
  100. package/dist/modules/credit_pricing.js +36 -40
  101. package/dist/modules/credit_runtime.d.ts +7 -0
  102. package/dist/modules/credit_runtime.js +45 -73
  103. package/dist/modules/daemon_node_health.d.ts +4 -3
  104. package/dist/modules/dexbot_class.d.ts +28 -17
  105. package/dist/modules/dexbot_class.js +105 -58
  106. package/dist/modules/dexbot_cow_runtime.d.ts +0 -7
  107. package/dist/modules/dexbot_cow_runtime.js +54 -28
  108. package/dist/modules/dexbot_credential_client.d.ts +0 -7
  109. package/dist/modules/dexbot_credential_client.js +1 -2
  110. package/dist/modules/dexbot_fill_runtime.d.ts +1 -2
  111. package/dist/modules/dexbot_fill_runtime.js +5 -6
  112. package/dist/modules/dexbot_maintenance_runtime.d.ts +20 -3
  113. package/dist/modules/dexbot_maintenance_runtime.js +84 -69
  114. package/dist/modules/dexbot_startup_runtime.d.ts +0 -1
  115. package/dist/modules/dexbot_startup_runtime.js +13 -14
  116. package/dist/modules/general_settings.d.ts +1 -1
  117. package/dist/modules/graceful_shutdown.js +17 -11
  118. package/dist/modules/key_store.js +0 -1
  119. package/dist/modules/lazy_shim.d.ts +11 -0
  120. package/dist/modules/lazy_shim.js +16 -0
  121. package/dist/modules/node_connect_policy.d.ts +3 -2
  122. package/dist/modules/node_failure_ledger.d.ts +6 -5
  123. package/dist/modules/order/format.d.ts +12 -3
  124. package/dist/modules/order/format.js +15 -3
  125. package/dist/modules/order/genesis_policy.d.ts +3 -3
  126. package/dist/modules/order/genesis_policy.js +5 -2
  127. package/dist/modules/order/grid.d.ts +4 -2
  128. package/dist/modules/order/grid.js +91 -35
  129. package/dist/modules/order/index.d.ts +1 -0
  130. package/dist/modules/order/logger.d.ts +1 -8
  131. package/dist/modules/order/logger.js +0 -9
  132. package/dist/modules/order/manager.d.ts +9 -13
  133. package/dist/modules/order/manager.js +33 -50
  134. package/dist/modules/order/utils/order.js +39 -35
  135. package/dist/modules/order/utils/system.d.ts +9 -29
  136. package/dist/modules/order/utils/system.js +17 -2
  137. package/dist/modules/order/utils/validate.js +2 -2
  138. package/dist/modules/order/utils/withPoolRef.d.ts +2 -1
  139. package/dist/modules/paths.js +32 -34
  140. package/dist/modules/runtime_settings.d.ts +2 -4
  141. package/dist/modules/settings_merge.d.ts +2 -2
  142. package/dist/modules/socket_json_client.d.ts +2 -1
  143. package/dist/modules/types.d.ts +42 -27
  144. package/dist/modules/utils/errors.js +1 -3
  145. package/dist/modules/version_notice.d.ts +11 -10
  146. package/dist/pm2.d.ts +0 -1
  147. package/dist/pm2.js +56 -35
  148. package/dist/scripts/analyze-git.js +2 -15
  149. package/dist/scripts/chart_command.js +2 -2
  150. package/dist/scripts/check_any.d.ts +4 -0
  151. package/dist/scripts/check_any.js +53 -21
  152. package/dist/scripts/diagnose-pool-history.js +1 -6
  153. package/dist/scripts/run-tests.js +0 -1
  154. package/dist/scripts/sync-version.js +0 -10
  155. package/docs/BITSHARES_ONBOARDING.md +8 -12
  156. package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -1
  157. package/docs/DEXBOT_COMPARISON.md +6 -6
  158. package/docs/EVOLUTION.md +9 -8
  159. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  160. package/docs/README.md +1 -1
  161. package/docs/WORKFLOW.md +1 -0
  162. package/docs/architecture.md +19 -10
  163. package/market_adapter/README.md +6 -4
  164. package/package.json +6 -9
  165. package/scripts/README.md +43 -38
  166. package/tests/README.md +25 -10
  167. package/dist/scripts/diagnose-kibana-candles.d.ts +0 -3
  168. package/dist/scripts/diagnose-kibana-candles.js +0 -82
  169. package/scripts/git-viewer.sh +0 -489
  170. package/scripts/postinstall.js +0 -16
@@ -33,8 +33,9 @@ import fs from 'node:fs';
33
33
  import path from 'node:path';
34
34
  import { pathToFileURL } from 'node:url';
35
35
  import { calculateAMA, getAmaWarmupBars } from '../../market_adapter/core/strategies/ama.js';
36
- import { loadCandles } from '../trend_detection/backtest_ama_slope_huber.js';
37
36
  import { parseListOrRange } from './shared_utils.js';
37
+ import { printHelpHeader, helpRow } from '../analyze_args.js';
38
+ import { median, percentile, fmtNum as fmt, loadCandleSeries } from '../math_utils.js';
38
39
  import { simulatePersistentGrid, WEIGHT_PROFILES } from './backtest_ama_sweep.js';
39
40
  import { getStorage } from '../../modules/storage/index.js';
40
41
  import { PATHS } from '../../modules/paths.js';
@@ -157,23 +158,19 @@ function parseArgs() {
157
158
  return out;
158
159
  }
159
160
  function printHelp() {
160
- console.log('Lookback -> fill-model drawdown backtest (paired persistent-grid simulation)');
161
- console.log('');
162
- console.log('Usage: node dist/analysis/bot_fitting/backtest_lookback_drawdown.js [options]');
163
- console.log('');
164
- console.log('Options:');
165
- console.log(' --data <path> LP candle file or shard directory (required)');
166
- console.log(` --ama <AMA1..AMA4> Built-in AMA preset (default: ${MA.DEFAULT_AMA_KEY})`);
167
- console.log(` --lookbacks <spec> Lookbacks to compare: 12,14,16,20 (default: ${DEFAULT_LOOKBACKS.join(',')})`);
168
- console.log(` --spread <spec> Spread grid (default: ${DEFAULT_SPREADS.join(',')})`);
169
- console.log(` --increment <spec> Increment grid (default: ${DEFAULT_INCREMENTS.join(',')})`);
170
- console.log(` --ratio <spec> Max/min ratio grid (default: ${DEFAULT_RATIOS.join(',')})`);
171
- console.log(' --max-orders <n> Size cap per side (default: 20)');
172
- console.log(' --fee <pct> Round-trip fee % (default: 0.20)');
173
- console.log(' --capital <n> Notional capital per side (default: 10000)');
174
- console.log(` --reposition <pct> AMA drift % to re-center (default: ${MA.AMA_DELTA_THRESHOLD_PERCENT})`);
175
- console.log(' --no-asymmetric-bounds Disable trigger B + slope offset (default: enabled)');
176
- console.log(' --out <path> JSON output path');
161
+ printHelpHeader('Lookback -> fill-model drawdown backtest (paired persistent-grid simulation)', 'bot_fitting/backtest_lookback_drawdown.js');
162
+ console.log(helpRow('--data <path>', 'LP candle file or shard directory (required)', 25));
163
+ console.log(helpRow('--ama <AMA1..AMA4>', `Built-in AMA preset (default: ${MA.DEFAULT_AMA_KEY})`, 25));
164
+ console.log(helpRow('--lookbacks <spec>', `Lookbacks to compare: 12,14,16,20 (default: ${DEFAULT_LOOKBACKS.join(',')})`, 25));
165
+ console.log(helpRow('--spread <spec>', `Spread grid (default: ${DEFAULT_SPREADS.join(',')})`, 25));
166
+ console.log(helpRow('--increment <spec>', `Increment grid (default: ${DEFAULT_INCREMENTS.join(',')})`, 25));
167
+ console.log(helpRow('--ratio <spec>', `Max/min ratio grid (default: ${DEFAULT_RATIOS.join(',')})`, 25));
168
+ console.log(helpRow('--max-orders <n>', 'Size cap per side (default: 20)', 25));
169
+ console.log(helpRow('--fee <pct>', 'Round-trip fee % (default: 0.20)', 25));
170
+ console.log(helpRow('--capital <n>', 'Notional capital per side (default: 10000)', 25));
171
+ console.log(helpRow('--reposition <pct>', `AMA drift % to re-center (default: ${MA.AMA_DELTA_THRESHOLD_PERCENT})`, 25));
172
+ console.log(helpRow('--no-asymmetric-bounds', 'Disable trigger B + slope offset (default: enabled)', 25));
173
+ console.log(helpRow('--out <path>', 'JSON output path', 25));
177
174
  }
178
175
  function resolveAma(name) {
179
176
  const presets = MA.AMAS;
@@ -182,22 +179,10 @@ function resolveAma(name) {
182
179
  throw new Error(`Unknown AMA preset '${name}' (expected ${Object.keys(presets).join(', ')})`);
183
180
  return { name, er: preset.erPeriod, fast: preset.fastPeriod, slow: preset.slowPeriod };
184
181
  }
185
- function median(values) {
186
- const s = values.slice().sort((a, b) => a - b);
187
- const mid = s.length >> 1;
188
- return s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
189
- }
190
- function percentile(values, pct) {
191
- const s = values.slice().sort((a, b) => a - b);
192
- return s[Math.min(s.length - 1, Math.max(0, Math.floor((pct / 100) * (s.length - 1))))];
193
- }
194
- function fmt(x, d = 2) {
195
- return Number.isFinite(Number(x)) ? Number(x).toFixed(d) : 'n/a';
196
- }
197
182
  function run() {
198
183
  const cfg = parseArgs();
199
184
  const amaDef = resolveAma(cfg.amaName);
200
- const { candles, files } = loadCandles(cfg.dataPath);
185
+ const { candles, files } = loadCandleSeries(cfg.dataPath);
201
186
  const closes = candles.map((c) => c.close);
202
187
  const amaValues = calculateAMA(closes, { erPeriod: amaDef.er, fastPeriod: amaDef.fast, slowPeriod: amaDef.slow });
203
188
  const warmupBars = getAmaWarmupBars(amaDef.er, amaDef.slow, 0, amaDef.fast);
@@ -260,7 +245,7 @@ function run() {
260
245
  for (const [label, field, mul, d] of fields) {
261
246
  let row = ` ${label.padEnd(20).slice(0, 20)} |`;
262
247
  for (const lb of cfg.lookbacks) {
263
- row += fmt(median(keys.map((k) => byLookback[lb][k][field] * mul)), d).padStart(12);
248
+ row += fmt(median(keys.map((k) => byLookback[lb][k][field] * mul)) ?? Number.NaN, d).padStart(12);
264
249
  }
265
250
  console.log(row);
266
251
  }
@@ -272,8 +257,8 @@ function run() {
272
257
  const deltas = keys.map((k) => byLookback[lb][k].maxDrawdownPct - ref[k].maxDrawdownPct);
273
258
  const lower = deltas.filter((d) => d < 0).length;
274
259
  console.log(` ${String(lb).padStart(2)} | ` +
275
- `${fmt(median(deltas)).padStart(12)} | ` +
276
- `${fmt(percentile(deltas, 25))} .. ${fmt(percentile(deltas, 75))} | ` +
260
+ `${fmt(median(deltas) ?? Number.NaN).padStart(12)} | ` +
261
+ `${fmt(percentile(deltas, 25, { interpolation: 'nearest', rounding: 'floor', empty: Number.NaN }))} .. ${fmt(percentile(deltas, 75, { interpolation: 'nearest', rounding: 'floor', empty: Number.NaN }))} | ` +
277
262
  `${lower}/${deltas.length} (${fmt((100 * lower) / deltas.length, 0)}%)`);
278
263
  }
279
264
  console.log('\n Reminder: the sign is pool-dependent and the absolute level is model-shaped');
@@ -1,3 +1,45 @@
1
+ /**
2
+ * Shared utilities for bot-fitting scripts.
3
+ *
4
+ * Also owns the backtest defaults/fee model shared by backtest_ama_sweep and
5
+ * backtest_bot_fitting, which previously declared byte-identical local copies.
6
+ */
7
+ declare const DEFAULT_FEE_ROUNDTRIP_PCT = 0.2;
8
+ declare const DEFAULT_MIN_SPREAD_FACTOR: number;
9
+ declare const DEFAULT_BTS_CREATE_FEE = 0.4826;
10
+ declare const DEFAULT_BTS_CANCEL_FEE = 0.00482;
11
+ declare const DEFAULT_BTS_MAKER_CREATE_FACTOR = 0.1;
12
+ declare const DEFAULT_TX_FEE_PRICE = 1;
13
+ declare const DEFAULT_REPOSITION_PCT: number;
14
+ declare const SLOPE_TRIGGER_FACTOR: number;
15
+ declare const SLOPE_MAX_PCT: number;
16
+ declare const SLOPE_LOOKBACK_BARS: number;
17
+ /** Slope-reset threshold in percent: (trigger factor/100) * max slope pct. */
18
+ declare function slopeResetThresholdPct(): number;
19
+ interface AmaStrategy {
20
+ id: string;
21
+ name: string;
22
+ er: number;
23
+ fast: number;
24
+ slow: number;
25
+ }
26
+ interface LoadAmaStrategiesOptions {
27
+ /** Require `fast` and `slow` to be finite too (default: only `er`). */
28
+ requireAllFields?: boolean;
29
+ /** Throw unless exactly this many strategies parse (default: no exact check). */
30
+ exactCount?: number | null;
31
+ /** Sort by `id` ascending. */
32
+ sort?: boolean;
33
+ /** Display-name lookup; when omitted use the entry's `label` field. */
34
+ labels?: Record<string, string> | null;
35
+ }
36
+ /**
37
+ * Read the `meta.amas` preset table from an optimization results file and map
38
+ * it to strategy descriptors. Single home for the loader previously copied into
39
+ * backtest_bot_fitting and backtest_ama_sweep; the options preserve each
40
+ * caller's validation and naming rules.
41
+ */
42
+ declare function loadAmaStrategies(resultsPath: string, options?: LoadAmaStrategiesOptions): AmaStrategy[];
1
43
  declare function parseListOrRange(spec: string | null | undefined, fallback: number[]): number[];
2
44
  declare function loadLpData(filePath: string): {
3
45
  candles: {
@@ -8,8 +50,34 @@ declare function loadLpData(filePath: string): {
8
50
  close: number;
9
51
  volume: number;
10
52
  }[];
11
- meta: {} | null;
53
+ meta: Record<string, unknown> | null;
12
54
  };
13
- declare function fmt(x: number, d?: number): string;
14
- export { parseListOrRange, loadLpData, fmt };
55
+ declare const fmt: (x: number, d?: number) => string;
56
+ interface BacktestArgTarget {
57
+ dataPath?: string | null;
58
+ resultsPath?: string | null;
59
+ spreadValues?: number[];
60
+ incrementValues?: number[];
61
+ ratioValues?: number[];
62
+ feeRoundtripPct?: number;
63
+ minSpreadFactor?: number;
64
+ repositionPct?: number;
65
+ btsCreateFee?: number;
66
+ btsCancelFee?: number;
67
+ makerCreateFactor?: number;
68
+ txFeePrice?: number;
69
+ }
70
+ interface BacktestListDefaults {
71
+ spreadValues: number[];
72
+ incrementValues: number[];
73
+ ratioValues: number[];
74
+ }
75
+ /**
76
+ * Consume one flag shared by backtest_ama_sweep and backtest_bot_fitting.
77
+ * Returns true when `arg` was handled, so the caller advances past its value.
78
+ * Both `--reposition` and `--reposition-pct` spellings are accepted so the two
79
+ * tools converge without breaking either CLI.
80
+ */
81
+ declare function consumeBacktestArg(arg: string, val: string, out: BacktestArgTarget, defaults: BacktestListDefaults): boolean;
82
+ export { parseListOrRange, loadLpData, fmt, loadAmaStrategies, consumeBacktestArg, slopeResetThresholdPct, DEFAULT_FEE_ROUNDTRIP_PCT, DEFAULT_MIN_SPREAD_FACTOR, DEFAULT_BTS_CREATE_FEE, DEFAULT_BTS_CANCEL_FEE, DEFAULT_BTS_MAKER_CREATE_FACTOR, DEFAULT_TX_FEE_PRICE, DEFAULT_REPOSITION_PCT, SLOPE_TRIGGER_FACTOR, SLOPE_MAX_PCT, SLOPE_LOOKBACK_BARS, };
15
83
  //# sourceMappingURL=shared_utils.d.ts.map
@@ -1,10 +1,68 @@
1
1
  'use strict';
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
2
4
  import { getStorage } from '../../modules/storage/index.js';
3
5
  const { readJSON } = getStorage();
4
- import { normalizeCandle } from '../math_utils.js';
6
+ import { normalizeCandle, fmtNum, loadCandleFile } from '../math_utils.js';
7
+ import { GRID_LIMITS, MARKET_ADAPTER } from '../../modules/constants.js';
5
8
  /**
6
9
  * Shared utilities for bot-fitting scripts.
10
+ *
11
+ * Also owns the backtest defaults/fee model shared by backtest_ama_sweep and
12
+ * backtest_bot_fitting, which previously declared byte-identical local copies.
7
13
  */
14
+ // Transaction / fee model shared by the two bot-fitting backtests.
15
+ const DEFAULT_FEE_ROUNDTRIP_PCT = 0.20;
16
+ const DEFAULT_MIN_SPREAD_FACTOR = GRID_LIMITS.MIN_SPREAD_FACTOR;
17
+ const DEFAULT_BTS_CREATE_FEE = 0.48260;
18
+ const DEFAULT_BTS_CANCEL_FEE = 0.00482;
19
+ const DEFAULT_BTS_MAKER_CREATE_FACTOR = 0.10;
20
+ const DEFAULT_TX_FEE_PRICE = 1.0;
21
+ // AMA reset trigger shared by both backtests.
22
+ const DEFAULT_REPOSITION_PCT = MARKET_ADAPTER.AMA_DELTA_THRESHOLD_PERCENT;
23
+ const SLOPE_TRIGGER_FACTOR = MARKET_ADAPTER.AMA_SLOPE_DELTA_THRESHOLD_PERCENT;
24
+ const SLOPE_MAX_PCT = MARKET_ADAPTER.DYNAMIC_WEIGHT_AMA_MAX_SLOPE_PCT;
25
+ const SLOPE_LOOKBACK_BARS = MARKET_ADAPTER.DYNAMIC_WEIGHT_AMA_LOOKBACK_BARS;
26
+ /** Slope-reset threshold in percent: (trigger factor/100) * max slope pct. */
27
+ function slopeResetThresholdPct() {
28
+ return (SLOPE_TRIGGER_FACTOR / 100) * SLOPE_MAX_PCT;
29
+ }
30
+ /**
31
+ * Read the `meta.amas` preset table from an optimization results file and map
32
+ * it to strategy descriptors. Single home for the loader previously copied into
33
+ * backtest_bot_fitting and backtest_ama_sweep; the options preserve each
34
+ * caller's validation and naming rules.
35
+ */
36
+ function loadAmaStrategies(resultsPath, options = {}) {
37
+ const { requireAllFields = false, exactCount = null, sort = false, labels = null } = options;
38
+ const json = readJSON(resultsPath);
39
+ const amas = json.meta?.amas;
40
+ if (!amas)
41
+ throw new Error('No meta.amas found in results file.');
42
+ const out = [];
43
+ for (const [key, val] of Object.entries(amas)) {
44
+ const v = val;
45
+ if (!v || !Number.isFinite(Number(v.er)))
46
+ continue;
47
+ if (requireAllFields && (!Number.isFinite(Number(v.fast)) || !Number.isFinite(Number(v.slow))))
48
+ continue;
49
+ out.push({
50
+ id: key,
51
+ name: labels ? (labels[key] ?? key) : String(v.label || key),
52
+ er: Number(v.er),
53
+ fast: Number(v.fast),
54
+ slow: Number(v.slow),
55
+ });
56
+ }
57
+ if (sort)
58
+ out.sort((a, b) => a.id.localeCompare(b.id));
59
+ if (exactCount != null && out.length !== exactCount) {
60
+ throw new Error(`Expected ${exactCount} AMA strategies in results meta.amas, found ${out.length}`);
61
+ }
62
+ if (out.length === 0)
63
+ throw new Error('No valid AMA strategies found');
64
+ return out;
65
+ }
8
66
  function toCandles(arr) {
9
67
  // Canonical accessor transform (market_adapter/candle_utils via math_utils)
10
68
  // instead of hand-rolled array indexing.
@@ -36,13 +94,71 @@ function parseListOrRange(spec, fallback) {
36
94
  return vals.length ? vals : fallback;
37
95
  }
38
96
  function loadLpData(filePath) {
39
- const json = readJSON(filePath);
40
- return { candles: toCandles((json.candles ?? json)), meta: json.meta ?? null };
97
+ // Shape detection (flat / {candles} / {data}) lives in math_utils.loadCandleFile.
98
+ // loadCandleFile returns an empty list for a missing file; keep the historical
99
+ // readJSON hard failure so a typo'd --data path is not silently treated as empty.
100
+ //
101
+ // Two intentional deltas vs the old inline readJSON+toCandles version:
102
+ // (a) a `{candles:[...]}` file without `meta` now yields the whole file object
103
+ // as `meta` (loadCandleFile's fallback). Both backtest consumers ignore
104
+ // `meta`, so this is inert today.
105
+ // (b) `{data:[...]}` files now load instead of crashing in toCandles (which
106
+ // called `.map` on the non-array object).
107
+ if (!filePath || !fs.existsSync(filePath))
108
+ throw new Error(`Data file not found: ${filePath}`);
109
+ const { candles, meta } = loadCandleFile(filePath);
110
+ return { candles: toCandles(candles), meta };
41
111
  }
42
- function fmt(x, d = 2) {
43
- if (!Number.isFinite(x))
44
- return ' n/a';
45
- return Number(x).toFixed(d);
112
+ // Strict (no Number() coercion) and padded fallback, matching the historical
113
+ // shared_utils output contract; formatting itself lives in math_utils.fmtNum.
114
+ const fmt = (x, d = 2) => fmtNum(x, d, { fallback: ' n/a', strict: true });
115
+ /**
116
+ * Consume one flag shared by backtest_ama_sweep and backtest_bot_fitting.
117
+ * Returns true when `arg` was handled, so the caller advances past its value.
118
+ * Both `--reposition` and `--reposition-pct` spellings are accepted so the two
119
+ * tools converge without breaking either CLI.
120
+ */
121
+ function consumeBacktestArg(arg, val, out, defaults) {
122
+ switch (arg) {
123
+ case '--data':
124
+ out.dataPath = path.resolve(val);
125
+ return true;
126
+ case '--results':
127
+ out.resultsPath = path.resolve(val);
128
+ return true;
129
+ case '--spread':
130
+ out.spreadValues = parseListOrRange(val, defaults.spreadValues);
131
+ return true;
132
+ case '--increment':
133
+ out.incrementValues = parseListOrRange(val, defaults.incrementValues);
134
+ return true;
135
+ case '--ratio':
136
+ out.ratioValues = parseListOrRange(val, defaults.ratioValues);
137
+ return true;
138
+ case '--fee':
139
+ out.feeRoundtripPct = Number(val);
140
+ return true;
141
+ case '--min-spread-factor':
142
+ out.minSpreadFactor = Number(val);
143
+ return true;
144
+ case '--reposition':
145
+ case '--reposition-pct':
146
+ out.repositionPct = Number(val);
147
+ return true;
148
+ case '--bts-create-fee':
149
+ out.btsCreateFee = Number(val);
150
+ return true;
151
+ case '--bts-cancel-fee':
152
+ out.btsCancelFee = Number(val);
153
+ return true;
154
+ case '--maker-create-factor':
155
+ out.makerCreateFactor = Number(val);
156
+ return true;
157
+ case '--tx-fee-price':
158
+ out.txFeePrice = Number(val);
159
+ return true;
160
+ default: return false;
161
+ }
46
162
  }
47
- export { parseListOrRange, loadLpData, fmt };
163
+ export { parseListOrRange, loadLpData, fmt, loadAmaStrategies, consumeBacktestArg, slopeResetThresholdPct, DEFAULT_FEE_ROUNDTRIP_PCT, DEFAULT_MIN_SPREAD_FACTOR, DEFAULT_BTS_CREATE_FEE, DEFAULT_BTS_CANCEL_FEE, DEFAULT_BTS_MAKER_CREATE_FACTOR, DEFAULT_TX_FEE_PRICE, DEFAULT_REPOSITION_PCT, SLOPE_TRIGGER_FACTOR, SLOPE_MAX_PCT, SLOPE_LOOKBACK_BARS, };
48
164
  //# sourceMappingURL=shared_utils.js.map
@@ -44,5 +44,34 @@ declare function zoomResetScript(): string;
44
44
  * e.g. `[['priceChart', 'price-panel'], ['kalmanChart', 'kalman-panel']]`
45
45
  */
46
46
  declare function sizeChartsFn(pairs: Array<[string, string]>): string;
47
- export { Y_AXIS_SIZE, makeCursorConfig, bindHoverStateFn, fmtDateFn, wireChartEvents, zoomResetScript, sizeChartsFn };
47
+ interface TimeLabelOptions {
48
+ /** Separator between the date and the HH:MM part in the sub-14d branch. */
49
+ dateTimeSep?: string;
50
+ /** Zero-pad the day-of-month (tradingview) vs leave it bare (dynamic weight). */
51
+ padDay?: boolean;
52
+ }
53
+ /**
54
+ * Return a self-contained `formatTimeLabel(tsSec, spanSec)` browser helper that
55
+ * chooses a label granularity from the visible span (year / month / day /
56
+ * minute). Single home for the near-identical copies in
57
+ * dynamic_weight_chart_generator and tradingview_uplot_chart_generator; the
58
+ * options preserve each chart's exact text (bare vs padded day, comma).
59
+ */
60
+ declare function formatTimeLabelFn({ dateTimeSep, padDay }?: TimeLabelOptions): string;
61
+ interface RefreshZoomOptions {
62
+ /** JS expression for the chart whose current x-scale is preserved. */
63
+ anchor: string;
64
+ /** Statements that re-populate the chart data (one per chart). */
65
+ reload: string[];
66
+ /** JS expression for the array of charts receiving the restored x-scale. */
67
+ charts: string;
68
+ }
69
+ /**
70
+ * Return a `refreshChartsPreservingZoom()` browser helper: snapshot the anchor
71
+ * chart's current x-range, re-run `reload`, then re-apply the saved range in one
72
+ * batched `setScale` per chart. Single home for the copies in
73
+ * dynamic_weight_chart_generator and volatility_chart_generator.
74
+ */
75
+ declare function refreshChartsPreservingZoomFn({ anchor, reload, charts }: RefreshZoomOptions): string;
76
+ export { Y_AXIS_SIZE, makeCursorConfig, bindHoverStateFn, fmtDateFn, wireChartEvents, zoomResetScript, sizeChartsFn, formatTimeLabelFn, refreshChartsPreservingZoomFn };
48
77
  //# sourceMappingURL=chart_ui.d.ts.map
@@ -96,5 +96,41 @@ function sizeChartsFn(pairs) {
96
96
  });
97
97
  }`;
98
98
  }
99
- export { Y_AXIS_SIZE, makeCursorConfig, bindHoverStateFn, fmtDateFn, wireChartEvents, zoomResetScript, sizeChartsFn };
99
+ /**
100
+ * Return a self-contained `formatTimeLabel(tsSec, spanSec)` browser helper that
101
+ * chooses a label granularity from the visible span (year / month / day /
102
+ * minute). Single home for the near-identical copies in
103
+ * dynamic_weight_chart_generator and tradingview_uplot_chart_generator; the
104
+ * options preserve each chart's exact text (bare vs padded day, comma).
105
+ */
106
+ function formatTimeLabelFn({ dateTimeSep = ' ', padDay = false } = {}) {
107
+ const dayExpr = padDay ? 'pad2(d.getUTCDate())' : 'd.getUTCDate()';
108
+ return `function formatTimeLabel(tsSec, spanSec) {
109
+ const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
110
+ const pad2 = (n) => String(n).padStart(2, '0');
111
+ const d = new Date(tsSec * 1000);
112
+ if (!Number.isFinite(spanSec)) spanSec = 0;
113
+ if (spanSec >= 365 * 24 * 3600 * 2) return String(d.getUTCFullYear());
114
+ if (spanSec >= 90 * 24 * 3600) return MONTHS[d.getUTCMonth()] + ' ' + d.getUTCFullYear();
115
+ if (spanSec >= 14 * 24 * 3600) return MONTHS[d.getUTCMonth()] + ' ' + ${dayExpr};
116
+ return MONTHS[d.getUTCMonth()] + ' ' + ${dayExpr} + '${dateTimeSep}' + pad2(d.getUTCHours()) + ':' + pad2(d.getUTCMinutes());
117
+ }`;
118
+ }
119
+ /**
120
+ * Return a `refreshChartsPreservingZoom()` browser helper: snapshot the anchor
121
+ * chart's current x-range, re-run `reload`, then re-apply the saved range in one
122
+ * batched `setScale` per chart. Single home for the copies in
123
+ * dynamic_weight_chart_generator and volatility_chart_generator.
124
+ */
125
+ function refreshChartsPreservingZoomFn({ anchor, reload, charts }) {
126
+ return `function refreshChartsPreservingZoom() {
127
+ const xs = ${anchor};
128
+ const savedX = xs ? { min: Number.isFinite(xs.min) ? xs.min : xMin, max: Number.isFinite(xs.max) ? xs.max : xMax } : null;
129
+ ${reload.join('\n ')}
130
+ if (savedX) {
131
+ ${charts}.forEach((c) => c.batch(() => c.setScale('x', savedX)));
132
+ }
133
+ }`;
134
+ }
135
+ export { Y_AXIS_SIZE, makeCursorConfig, bindHoverStateFn, fmtDateFn, wireChartEvents, zoomResetScript, sizeChartsFn, formatTimeLabelFn, refreshChartsPreservingZoomFn };
100
136
  //# sourceMappingURL=chart_ui.js.map
@@ -1,17 +1,10 @@
1
+ import { shardKeyForTimestamp, shardBoundsForKey, shardKeysForRange, shardPathFor, subtractRanges } from '../market_adapter/utils/month_shards.js';
2
+ import type { QueriedRange, Span } from '../market_adapter/utils/month_shards.js';
1
3
  import { FillRecord } from './fills_source.js';
2
4
  /** How long after a query its trailing fills may still be late-indexed. */
3
5
  declare const TAIL_SETTLE_LAG_MS: number;
4
6
  /** Upper bound on spans persisted per shard (keeps coverage bookkeeping small). */
5
7
  declare const MAX_COVERAGE_SPANS = 64;
6
- interface QueriedRange {
7
- gte: number;
8
- lte: number;
9
- at: number | null;
10
- }
11
- interface Span {
12
- gte: number;
13
- lte: number;
14
- }
15
8
  interface FillsShard {
16
9
  meta: {
17
10
  accountId: string;
@@ -31,25 +24,12 @@ interface FetchFillsOptions {
31
24
  fetchRange?: (gteIso: string, lteIso: string) => Promise<FillRecord[]>;
32
25
  quiet?: boolean;
33
26
  }
34
- declare function shardKeyForTimestamp(tsMs: number): string;
35
- declare function shardBoundsForKey(key: string): {
36
- start: number;
37
- end: number;
38
- };
39
- declare function shardKeysForRange(gteMs: number, lteMs: number): string[];
40
27
  declare function basePathFor(cacheDir: string, accountId: string): string;
41
- declare function shardPathFor(basePath: string, shardKey: string): string;
42
- /** Sort, merge overlapping/adjacent same-`at` spans, cap the list length. */
43
- declare function normalizeQueried(ranges: QueriedRange[]): QueriedRange[];
44
- /** Record a freshly queried span, dropping older spans it fully supersedes. */
45
- declare function addCoverage(queried: QueriedRange[], span: Span, atMs: number): QueriedRange[];
46
28
  /**
47
29
  * Portions of queried spans that are safe to reuse: the part up to
48
30
  * `at - TAIL_SETTLE_LAG_MS`. A span with an unknown `at` certifies nothing.
49
31
  */
50
32
  declare function trustedSegments(queried: QueriedRange[], nowMs: number): Span[];
51
- /** `span` minus the union of `covered` (both as inclusive ms ranges). */
52
- declare function subtractRanges(span: Span, covered: Span[]): Span[];
53
33
  declare function fillKey(f: FillRecord): string;
54
34
  /** Union two fill lists, deduped by the unique operation identity. */
55
35
  declare function mergeFills(existing: FillRecord[], incoming: FillRecord[]): FillRecord[];
@@ -59,6 +39,6 @@ declare function mergeFills(existing: FillRecord[], incoming: FillRecord[]): Fil
59
39
  * fetch when the range is malformed.
60
40
  */
61
41
  declare function fetchFillsCached(config: Record<string, unknown>, accountId: string, gteIso: string, lteIso: string, options?: FetchFillsOptions): Promise<FillRecord[]>;
62
- export { fetchFillsCached, shardKeyForTimestamp, shardBoundsForKey, shardKeysForRange, basePathFor, shardPathFor, normalizeQueried, addCoverage, trustedSegments, subtractRanges, mergeFills, fillKey, TAIL_SETTLE_LAG_MS, MAX_COVERAGE_SPANS, };
42
+ export { fetchFillsCached, shardKeyForTimestamp, shardBoundsForKey, shardKeysForRange, basePathFor, shardPathFor, trustedSegments, subtractRanges, mergeFills, fillKey, TAIL_SETTLE_LAG_MS, MAX_COVERAGE_SPANS, };
63
43
  export type { QueriedRange, FillsShard, FetchFillsOptions };
64
44
  //# sourceMappingURL=fills_cache.d.ts.map
@@ -27,6 +27,7 @@ import path from 'node:path';
27
27
  import { getStorage } from '../modules/storage/index.js';
28
28
  import { PATHS } from '../modules/paths.js';
29
29
  import { writeJsonAtomic } from '../market_adapter/utils/atomic_write.js';
30
+ import { shardKeyForTimestamp, shardBoundsForKey, shardKeysForRange, shardPathFor, unionQueriedRanges, compactCoverage, mergeSpans, subtractRanges, } from '../market_adapter/utils/month_shards.js';
30
31
  import { fetchAllFills } from './fills_source.js';
31
32
  const storage = getStorage();
32
33
  const { readJSON } = storage;
@@ -35,27 +36,6 @@ const TAIL_SETTLE_LAG_MS = 6 * 3600 * 1000;
35
36
  /** Upper bound on spans persisted per shard (keeps coverage bookkeeping small). */
36
37
  const MAX_COVERAGE_SPANS = 64;
37
38
  const SHARD_EXT = '.json';
38
- const SHARD_MARKER = '.shard_';
39
- function shardKeyForTimestamp(tsMs) {
40
- const d = new Date(Number(tsMs));
41
- return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`;
42
- }
43
- function shardBoundsForKey(key) {
44
- const parts = String(key).split('-').map(Number);
45
- const start = Date.UTC(parts[0], parts[1] - 1, 1);
46
- const end = parts[1] === 12 ? Date.UTC(parts[0] + 1, 0, 1) : Date.UTC(parts[0], parts[1], 1);
47
- return { start, end };
48
- }
49
- function shardKeysForRange(gteMs, lteMs) {
50
- const keys = [];
51
- const cursor = new Date(Date.UTC(new Date(gteMs).getUTCFullYear(), new Date(gteMs).getUTCMonth(), 1));
52
- const last = new Date(lteMs);
53
- while (cursor <= last) {
54
- keys.push(shardKeyForTimestamp(cursor.getTime()));
55
- cursor.setUTCMonth(cursor.getUTCMonth() + 1);
56
- }
57
- return keys;
58
- }
59
39
  function accountFileBase(accountId) {
60
40
  const s = String(accountId ?? '').trim();
61
41
  if (/^1\.2\.\d+$/.test(s))
@@ -65,10 +45,6 @@ function accountFileBase(accountId) {
65
45
  function basePathFor(cacheDir, accountId) {
66
46
  return path.join(cacheDir, 'fills', `${accountFileBase(accountId)}${SHARD_EXT}`);
67
47
  }
68
- function shardPathFor(basePath, shardKey) {
69
- const parsed = path.parse(basePath);
70
- return path.join(parsed.dir, `${parsed.name}${SHARD_MARKER}${shardKey}${parsed.ext}`);
71
- }
72
48
  function readShard(shardFile, accountId) {
73
49
  try {
74
50
  const parsed = readJSON(shardFile);
@@ -91,49 +67,13 @@ function readShard(shardFile, accountId) {
91
67
  }
92
68
  /** Sort, merge overlapping/adjacent same-`at` spans, cap the list length. */
93
69
  function normalizeQueried(ranges) {
94
- const clean = (ranges || [])
95
- .filter((q) => q && Number.isFinite(Number(q.gte)) && Number.isFinite(Number(q.lte)) && Number(q.lte) >= Number(q.gte))
96
- .map((q) => ({
97
- gte: Number(q.gte),
98
- lte: Number(q.lte),
99
- at: Number.isFinite(Number(q.at)) ? Number(q.at) : null,
100
- }))
101
- .sort((a, b) => a.gte - b.gte || a.lte - b.lte);
102
- const merged = [];
103
- for (const q of clean) {
104
- const top = merged[merged.length - 1];
105
- if (top && q.gte <= top.lte + 1 && top.at === q.at) {
106
- if (q.lte > top.lte)
107
- top.lte = q.lte;
108
- }
109
- else {
110
- merged.push({ ...q });
111
- }
112
- }
113
- if (merged.length > MAX_COVERAGE_SPANS)
114
- merged.splice(0, merged.length - MAX_COVERAGE_SPANS);
115
- return merged;
70
+ return compactCoverage(unionQueriedRanges(ranges || [], 1), MAX_COVERAGE_SPANS);
116
71
  }
117
72
  /** Record a freshly queried span, dropping older spans it fully supersedes. */
118
73
  function addCoverage(queried, span, atMs) {
119
74
  const kept = queried.filter((q) => !(q.gte >= span.gte && q.lte <= span.lte));
120
75
  return normalizeQueried([...kept, { gte: span.gte, lte: span.lte, at: atMs }]);
121
76
  }
122
- function mergeSpans(spans) {
123
- const sorted = [...spans].sort((a, b) => a.gte - b.gte || a.lte - b.lte);
124
- const merged = [];
125
- for (const s of sorted) {
126
- const top = merged[merged.length - 1];
127
- if (top && s.gte <= top.lte + 1) {
128
- if (s.lte > top.lte)
129
- top.lte = s.lte;
130
- }
131
- else {
132
- merged.push({ ...s });
133
- }
134
- }
135
- return merged;
136
- }
137
77
  /**
138
78
  * Portions of queried spans that are safe to reuse: the part up to
139
79
  * `at - TAIL_SETTLE_LAG_MS`. A span with an unknown `at` certifies nothing.
@@ -149,27 +89,6 @@ function trustedSegments(queried, nowMs) {
149
89
  }
150
90
  return mergeSpans(segs);
151
91
  }
152
- /** `span` minus the union of `covered` (both as inclusive ms ranges). */
153
- function subtractRanges(span, covered) {
154
- let parts = [{ ...span }];
155
- for (const c of mergeSpans(covered)) {
156
- const next = [];
157
- for (const p of parts) {
158
- if (c.lte < p.gte || c.gte > p.lte) {
159
- next.push(p);
160
- continue;
161
- }
162
- if (c.gte > p.gte)
163
- next.push({ gte: p.gte, lte: Math.min(p.lte, c.gte - 1) });
164
- if (c.lte < p.lte)
165
- next.push({ gte: Math.max(p.gte, c.lte + 1), lte: p.lte });
166
- }
167
- parts = next.filter(p => p.lte >= p.gte);
168
- if (parts.length === 0)
169
- break;
170
- }
171
- return parts;
172
- }
173
92
  function fillKey(f) {
174
93
  return `${f.blockNum}:${f.opNum}`;
175
94
  }
@@ -250,5 +169,5 @@ async function fetchFillsCached(config, accountId, gteIso, lteIso, options = {})
250
169
  }
251
170
  return [...collected.values()].sort(compareFills);
252
171
  }
253
- export { fetchFillsCached, shardKeyForTimestamp, shardBoundsForKey, shardKeysForRange, basePathFor, shardPathFor, normalizeQueried, addCoverage, trustedSegments, subtractRanges, mergeFills, fillKey, TAIL_SETTLE_LAG_MS, MAX_COVERAGE_SPANS, };
172
+ export { fetchFillsCached, shardKeyForTimestamp, shardBoundsForKey, shardKeysForRange, basePathFor, shardPathFor, trustedSegments, subtractRanges, mergeFills, fillKey, TAIL_SETTLE_LAG_MS, MAX_COVERAGE_SPANS, };
254
173
  //# sourceMappingURL=fills_cache.js.map
@@ -18,6 +18,36 @@ interface FillRecord {
18
18
  declare function assetSymbol(id: string): string;
19
19
  declare function assetPrec(id: string): number | undefined;
20
20
  declare function toReal(amount: number, assetId: string): number;
21
+ /**
22
+ * A fill needs strictly positive, finite amounts on both legs. A zero base
23
+ * amount would produce an infinite price (quoteAmount / 0) that poisons
24
+ * downstream inventory lots and PnL aggregates.
25
+ */
26
+ declare function isValidFillAmounts(baseAmount: number, quoteAmount: number): boolean;
27
+ /** Match a user-supplied pair leg against a chain asset id or its symbol. */
28
+ declare function matchesAssetRef(ref: string, assetId: string): boolean;
29
+ interface ClassifiedFill {
30
+ direction: 'buy' | 'sell';
31
+ baseAsset: string;
32
+ quoteAsset: string;
33
+ baseAmount: number;
34
+ quoteAmount: number;
35
+ price: number;
36
+ }
37
+ /**
38
+ * Resolve a raw fill's buy/sell direction, base/quote assets and real amounts.
39
+ *
40
+ * Direction/base/quote rules (single home for trade_profitability and
41
+ * grid_correction_check, which previously carried verbatim copies):
42
+ * - BTS on the pays side → buy the received asset, quote = BTS.
43
+ * - BTS on the receives side → sell the paid asset, quote = BTS.
44
+ * - any other cross-pair → lower asset id is the base; sell when pays < receives.
45
+ *
46
+ * Returns `null` when an asset precision is unknown or either real amount is
47
+ * not strictly positive/finite. Callers own the skip counting and any extra
48
+ * validation (e.g. the market-fee asset check in trade_profitability).
49
+ */
50
+ declare function classifyFill(f: FillRecord): ClassifiedFill | null;
21
51
  /**
22
52
  * Collect all unique non-BTS asset IDs from fills, resolve unknown precisions
23
53
  * from the blockchain, and populate the runtime cache.
@@ -25,5 +55,5 @@ declare function toReal(amount: number, assetId: string): number;
25
55
  declare function resolveAssetPrecisions(fills: FillRecord[]): Promise<void>;
26
56
  /** Fetch every fill_order for an account in [gte, lte], paginated via search_after. */
27
57
  declare function fetchAllFills(config: Record<string, unknown>, accountId: string, gte: string, lte: string): Promise<FillRecord[]>;
28
- export { BTS_ID, assetSymbol, assetPrec, toReal, resolveAssetPrecisions, fetchAllFills, FillRecord, };
58
+ export { BTS_ID, assetSymbol, assetPrec, toReal, isValidFillAmounts, matchesAssetRef, classifyFill, resolveAssetPrecisions, fetchAllFills, FillRecord, ClassifiedFill, };
29
59
  //# sourceMappingURL=fills_source.d.ts.map