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.
- package/CHANGELOG.md +58 -0
- package/README.md +24 -18
- package/analysis/README.md +105 -12
- package/analysis/ama_fitting/README.md +2 -2
- package/analysis/bot_fitting/README.md +3 -3
- package/claw/package.json +1 -1
- package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
- package/claw/runtimes/openclaw-plugin/package.json +1 -1
- package/dist/analysis/analyze_args.d.ts +2 -1
- package/dist/analysis/analyze_dynamic_weight.js +2 -1
- package/dist/analysis/analyze_kalman.js +3 -2
- package/dist/analysis/analyze_liquidity.d.ts +17 -0
- package/dist/analysis/analyze_liquidity.js +325 -0
- package/dist/analysis/analyze_regime.js +3 -2
- package/dist/analysis/analyze_regime_windows.js +3 -2
- package/dist/analysis/analyze_volatility.js +3 -2
- package/dist/analysis/fills_source.d.ts +1 -8
- package/dist/analysis/fills_source.js +1 -1
- package/dist/analysis/grid_correction_check.d.ts +9 -6
- package/dist/analysis/grid_correction_check.js +56 -64
- package/dist/analysis/liquidity/liquidity_chain.d.ts +66 -0
- package/dist/analysis/liquidity/liquidity_chain.js +178 -0
- package/dist/analysis/liquidity/liquidity_chart_generator.d.ts +19 -0
- package/dist/analysis/liquidity/liquidity_chart_generator.js +523 -0
- package/dist/analysis/liquidity/liquidity_depth_model.d.ts +141 -0
- package/dist/analysis/liquidity/liquidity_depth_model.js +230 -0
- package/dist/analysis/liquidity/liquidity_view.d.ts +38 -0
- package/dist/analysis/liquidity/liquidity_view.js +55 -0
- package/dist/analysis/math_utils.d.ts +1 -1
- package/dist/analysis/trade_profitability.d.ts +1 -1
- package/dist/analysis/trade_profitability.js +2 -1
- package/dist/analysis/tradingview/analyze_tradingview.js +2 -1
- package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +3 -3
- package/dist/analysis/trend_detection/huber_scale_variants.d.ts +4 -3
- package/dist/dexbot.js +74 -169
- package/dist/market_adapter/cli_args.d.ts +6 -1
- package/dist/market_adapter/cli_args.js +16 -2
- package/dist/market_adapter/core/kibana_candles.d.ts +5 -1
- package/dist/market_adapter/core/kibana_candles.js +3 -1
- package/dist/market_adapter/core/strategies/regime_gate.d.ts +7 -1
- package/dist/market_adapter/core/strategies/regime_gate.js +3 -1
- package/dist/market_adapter/inputs/cex_candle_parsing.d.ts +7 -2
- package/dist/market_adapter/inputs/cex_candle_parsing.js +3 -1
- package/dist/market_adapter/inputs/fetch_book_data.d.ts +7 -1
- package/dist/market_adapter/inputs/fetch_book_data.js +3 -1
- package/dist/market_adapter/inputs/fetch_cex_synthetic_data.js +2 -11
- package/dist/market_adapter/inputs/fetch_lp_data.d.ts +26 -1
- package/dist/market_adapter/inputs/fetch_lp_data.js +62 -52
- package/dist/market_adapter/inputs/kibana_feed_source.d.ts +14 -2
- package/dist/market_adapter/inputs/kibana_feed_source.js +14 -1
- package/dist/market_adapter/inputs/window_cache.d.ts +14 -3
- package/dist/market_adapter/inputs/window_cache.js +14 -1
- package/dist/market_adapter/lp_chart_runner.d.ts +12 -9
- package/dist/market_adapter/lp_chart_runner.js +3 -1
- package/dist/market_adapter/lp_chart_strategy_loader.d.ts +5 -1
- package/dist/market_adapter/lp_chart_strategy_loader.js +3 -1
- package/dist/market_adapter/market_adapter.d.ts +10 -2
- package/dist/market_adapter/market_adapter.js +10 -11
- package/dist/market_adapter/utils/chain.d.ts +2 -3
- package/dist/market_adapter/utils/file_json_cache.d.ts +5 -1
- package/dist/market_adapter/utils/file_json_cache.js +3 -1
- package/dist/market_adapter/utils/file_lock.js +1 -1
- package/dist/market_adapter/utils/native_history.d.ts +7 -3
- package/dist/market_adapter/utils/native_history.js +3 -1
- package/dist/market_adapter/utils/pair_orientation.d.ts +2 -2
- package/dist/modules/asset_lookup.d.ts +25 -0
- package/dist/modules/asset_lookup.js +75 -0
- package/dist/modules/bots_file_lock.d.ts +2 -2
- package/dist/modules/bots_file_lock.js +2 -2
- package/dist/modules/chain_scan.d.ts +64 -0
- package/dist/modules/chain_scan.js +80 -0
- package/dist/modules/cli_colors.d.ts +5 -0
- package/dist/modules/cli_colors.js +7 -0
- package/dist/modules/cli_progress.d.ts +51 -0
- package/dist/modules/cli_progress.js +113 -0
- package/dist/modules/constants.js +6 -3
- package/dist/modules/dexbot_class.d.ts +8 -0
- package/dist/modules/dexbot_class.js +10 -0
- package/dist/modules/dexbot_cow_runtime.d.ts +62 -1
- package/dist/modules/dexbot_cow_runtime.js +475 -47
- package/dist/modules/dexbot_credential_client.d.ts +5 -0
- package/dist/modules/dexbot_fill_runtime.js +20 -0
- package/dist/modules/dexbot_maintenance_runtime.js +71 -9
- package/dist/modules/dexbot_startup_runtime.js +7 -1
- package/dist/modules/graceful_shutdown.d.ts +2 -2
- package/dist/modules/graceful_shutdown.js +2 -2
- package/dist/modules/launcher/runtime_entry.d.ts +21 -1
- package/dist/modules/launcher/runtime_entry.js +36 -1
- package/dist/modules/launcher/runtime_mode.d.ts +4 -3
- package/dist/modules/liquidity_pool_ref.d.ts +32 -0
- package/dist/modules/liquidity_pool_ref.js +116 -0
- package/dist/modules/node_manager.d.ts +1 -1
- package/dist/modules/node_manager.js +1 -1
- package/dist/modules/order/accounting.js +2 -1
- package/dist/modules/order/export.d.ts +2 -2
- package/dist/modules/order/export.js +2 -2
- package/dist/modules/order/grid.d.ts +19 -14
- package/dist/modules/order/grid.js +269 -61
- package/dist/modules/order/grid_reconcile.js +27 -2
- package/dist/modules/order/grid_reconcile_internal.js +94 -15
- package/dist/modules/order/index.d.ts +24 -4
- package/dist/modules/order/manager.d.ts +12 -0
- package/dist/modules/order/manager.js +44 -11
- package/dist/modules/order/strategy.js +22 -2
- package/dist/modules/order/sync_engine.d.ts +32 -1
- package/dist/modules/order/sync_engine.js +209 -26
- package/dist/modules/order/utils/math.d.ts +26 -10
- package/dist/modules/order/utils/math.js +54 -14
- package/dist/modules/order/utils/order.d.ts +158 -11
- package/dist/modules/order/utils/order.js +434 -21
- package/dist/modules/order/utils/system.d.ts +136 -30
- package/dist/modules/order/utils/system.js +465 -63
- package/dist/modules/order/utils/validate.d.ts +1 -0
- package/dist/modules/order/utils/validate.js +37 -3
- package/dist/modules/storage/index.d.ts +3 -2
- package/dist/modules/storage/index.js +3 -2
- package/dist/modules/types.d.ts +14 -0
- package/dist/modules/utils/asset_symbols.d.ts +13 -2
- package/dist/modules/utils/asset_symbols.js +21 -2
- package/dist/scripts/analysis_runner.d.ts +10 -0
- package/dist/scripts/analysis_runner.js +33 -0
- package/dist/scripts/analyze-orders.js +2 -1
- package/dist/scripts/asset.d.ts +26 -0
- package/dist/scripts/asset.js +165 -0
- package/dist/scripts/bts_distribution.d.ts +1 -0
- package/dist/scripts/bts_distribution.js +194 -142
- package/dist/scripts/chart_command.d.ts +1 -1
- package/dist/scripts/chart_command.js +60 -86
- package/dist/scripts/chart_targets.d.ts +18 -0
- package/dist/scripts/chart_targets.js +52 -0
- package/dist/scripts/dw.js +1 -1
- package/dist/scripts/liquid.d.ts +24 -0
- package/dist/scripts/liquid.js +134 -0
- package/dist/scripts/rich_list.js +12 -16
- package/dist/scripts/token_distribution.d.ts +2 -0
- package/dist/scripts/token_distribution.js +132 -108
- package/dist/scripts/tv.js +1 -1
- package/dist/scripts/verify-browser-bundle.js +18 -0
- package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -1
- package/docs/COW_INVARIANTS.md +21 -11
- package/docs/DEXBOT_COMPARISON.md +6 -6
- package/docs/EVOLUTION.md +10 -8
- package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +11 -11
- package/docs/GRID_PRICE_INVARIANT.md +28 -5
- package/docs/GRID_RECONCILE.md +25 -5
- package/docs/LIFECYCLE.md +11 -11
- package/docs/LOGGING.md +37 -2
- package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +124 -36
- package/docs/README.md +1 -1
- package/docs/WORKFLOW.md +3 -1
- package/docs/architecture.md +115 -13
- package/docs/developer_guide.md +12 -0
- package/market_adapter/README.md +9 -4
- package/modules/README.md +23 -15
- package/package.json +6 -3
- package/scripts/README.md +23 -7
|
@@ -35,6 +35,8 @@
|
|
|
35
35
|
* no keys, no transactions. Chain source of truth: bitshares-core 7.0.x.
|
|
36
36
|
*
|
|
37
37
|
* Usage:
|
|
38
|
+
* dexbot asset <symbol|1.3.x> [options] # CLI shortcut
|
|
39
|
+
* dexbot a <symbol|1.3.x> [options] # shorthand for the line above
|
|
38
40
|
* node dist/scripts/token_distribution.js <symbol|1.3.x>
|
|
39
41
|
* node dist/scripts/token_distribution.js <token> --json
|
|
40
42
|
* node dist/scripts/token_distribution.js <asset-id> --no-html
|
|
@@ -47,6 +49,10 @@ import { pathToFileURL } from 'node:url';
|
|
|
47
49
|
import { NODE_MANAGEMENT } from '../modules/constants.js';
|
|
48
50
|
import { PATHS } from '../modules/paths.js';
|
|
49
51
|
import { CLI_COLORS as colors } from '../modules/cli_colors.js';
|
|
52
|
+
import { CLI_TAGS, clearProgressLine, loadingLine, savedLine, section, summaryLine, taggedProgress, warningsBlock, } from '../modules/cli_progress.js';
|
|
53
|
+
import { scanIdRange, DENSE_SPACE_GAP } from '../modules/chain_scan.js';
|
|
54
|
+
import { resolveAssetRef } from '../modules/asset_lookup.js';
|
|
55
|
+
import { toFileUrl } from '../analysis/chart_utils.js';
|
|
50
56
|
// ---------------------------------------------------------------------------
|
|
51
57
|
// Constants
|
|
52
58
|
// ---------------------------------------------------------------------------
|
|
@@ -58,8 +64,19 @@ const NAME_BATCH = 50;
|
|
|
58
64
|
const DEFAULT_DETAIL = 15;
|
|
59
65
|
const DEFAULT_VESTING_MAX = 200_000;
|
|
60
66
|
const DEFAULT_SCAN_GAP = 20_000;
|
|
61
|
-
|
|
67
|
+
// One get_limit_orders call per asset (core exposes no per-asset order index);
|
|
68
|
+
// 32 concurrent reads measured ~2x faster than 12 with an identical report.
|
|
69
|
+
const DEFAULT_CONCURRENCY = 32;
|
|
70
|
+
// Holder pages are offset-addressable (asset_api walks by_asset_balance by
|
|
71
|
+
// position), so the rich list is fetched in parallel pages. The asset_api nodes
|
|
72
|
+
// tolerate this well; 8 keeps ~800 holders in flight.
|
|
73
|
+
const HOLDER_PAGE_CONCURRENCY = 8;
|
|
62
74
|
const DEFAULT_HTML = path.join(PATHS.ANALYSIS.CHARTS_DIR, 'token-distribution.html');
|
|
75
|
+
// Console tag for status lines, matching the `[Liquidity]` style used by the
|
|
76
|
+
// other analysis entries.
|
|
77
|
+
const LOG_TAG = CLI_TAGS.assets;
|
|
78
|
+
const progress = taggedProgress(LOG_TAG);
|
|
79
|
+
const clearProgress = clearProgressLine;
|
|
63
80
|
// asset_api (get_asset_holders) is allowlisted on only a few public nodes; this
|
|
64
81
|
// mirrors scripts/rich_list.ts and scripts/bts_distribution.ts.
|
|
65
82
|
const HOLDER_NODES = [
|
|
@@ -78,13 +95,14 @@ class UsageError extends Error {
|
|
|
78
95
|
const HELP = `BitShares token distribution analyzer (read-only)
|
|
79
96
|
|
|
80
97
|
Usage:
|
|
98
|
+
dexbot asset <symbol|1.3.x> [options] (shorthand: dexbot a <symbol|1.3.x>)
|
|
81
99
|
node dist/scripts/token_distribution.js <symbol|1.3.x> [options]
|
|
82
100
|
|
|
83
101
|
Options:
|
|
84
102
|
--node URL BitShares node (repeatable; defaults to NODE_MANAGEMENT.DEFAULT_NODES)
|
|
85
103
|
--detail N Rows in top-holder / P2P / vesting tables (default ${DEFAULT_DETAIL})
|
|
86
|
-
--no-orders Skip the per-asset limit-order scan (saves ~
|
|
87
|
-
--concurrency N Concurrent get_limit_orders calls (default ${DEFAULT_CONCURRENCY})
|
|
104
|
+
--no-orders Skip the per-asset limit-order scan (~6.5k calls; saves ~15s)
|
|
105
|
+
--concurrency N Concurrent get_limit_orders calls (default ${DEFAULT_CONCURRENCY}, max 64)
|
|
88
106
|
--vesting-max N Highest 1.13.x object id to scan (default ${DEFAULT_VESTING_MAX})
|
|
89
107
|
--gap N Stop the 1.13.x scan after N consecutive missing ids (default ${DEFAULT_SCAN_GAP})
|
|
90
108
|
--html PATH HTML output path (default ${DEFAULT_HTML})
|
|
@@ -345,57 +363,6 @@ async function listPages(fetchPage, limit, maxPages = 10000) {
|
|
|
345
363
|
}
|
|
346
364
|
return out;
|
|
347
365
|
}
|
|
348
|
-
/** Enumerate every asset via list_assets (symbol-ordered, inclusive lower bound). */
|
|
349
|
-
async function listAllAssets(session) {
|
|
350
|
-
const limit = Math.max(1, Math.min(session.config.api_limit_get_assets ?? 100, 100));
|
|
351
|
-
const seen = new Set();
|
|
352
|
-
const out = [];
|
|
353
|
-
let lower = '';
|
|
354
|
-
for (let page = 0; page < 10000; page++) {
|
|
355
|
-
const rows = await callDb(session, 'list_assets', [lower, limit]);
|
|
356
|
-
if (!Array.isArray(rows) || rows.length === 0)
|
|
357
|
-
break;
|
|
358
|
-
let fresh = 0;
|
|
359
|
-
for (const row of rows) {
|
|
360
|
-
if (!row || seen.has(row.id))
|
|
361
|
-
continue;
|
|
362
|
-
seen.add(row.id);
|
|
363
|
-
out.push(row);
|
|
364
|
-
fresh++;
|
|
365
|
-
}
|
|
366
|
-
if (rows.length < limit || fresh === 0)
|
|
367
|
-
break;
|
|
368
|
-
const lastSymbol = rows[rows.length - 1]?.symbol;
|
|
369
|
-
if (typeof lastSymbol !== 'string')
|
|
370
|
-
break;
|
|
371
|
-
lower = lastSymbol;
|
|
372
|
-
}
|
|
373
|
-
return out;
|
|
374
|
-
}
|
|
375
|
-
/**
|
|
376
|
-
* Scan a dense-ish object id range with a gap tolerance. Used for 1.13.x
|
|
377
|
-
* vesting balances, which have no global by-asset index.
|
|
378
|
-
*/
|
|
379
|
-
async function scanIdRange(session, prefix, maxId, gap, onProgress) {
|
|
380
|
-
const objects = [];
|
|
381
|
-
let index = 0;
|
|
382
|
-
let lastSeen = -1;
|
|
383
|
-
while (index <= maxId && index - lastSeen <= gap) {
|
|
384
|
-
const count = Math.min(OBJECT_BATCH, maxId - index + 1);
|
|
385
|
-
const ids = Array.from({ length: count }, (_, i) => `${prefix}.${index + i}`);
|
|
386
|
-
const page = await callDb(session, 'get_objects', [ids]);
|
|
387
|
-
for (let j = 0; j < count; j++) {
|
|
388
|
-
const obj = page?.[j];
|
|
389
|
-
if (obj) {
|
|
390
|
-
lastSeen = index + j;
|
|
391
|
-
objects.push(obj);
|
|
392
|
-
}
|
|
393
|
-
}
|
|
394
|
-
index += count;
|
|
395
|
-
onProgress?.(index);
|
|
396
|
-
}
|
|
397
|
-
return { objects, scannedTo: index, hitLimit: index > maxId && index - lastSeen <= gap };
|
|
398
|
-
}
|
|
399
366
|
async function resolveAccountNames(session, ids) {
|
|
400
367
|
const names = new Map();
|
|
401
368
|
const unique = [...new Set(ids.filter(Boolean))];
|
|
@@ -414,31 +381,94 @@ async function resolveAccountNames(session, ids) {
|
|
|
414
381
|
return names;
|
|
415
382
|
}
|
|
416
383
|
async function resolveAsset(session, input) {
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
stub =
|
|
425
|
-
if (!stub && input.toLowerCase().startsWith('bit')) {
|
|
426
|
-
const retry = await callDb(session, 'lookup_asset_symbols', [[input.slice(3)]]);
|
|
427
|
-
stub = retry?.[0] ?? null;
|
|
428
|
-
}
|
|
384
|
+
// Shared case-insensitive lookup (modules/asset_lookup.ts), so a lowercase
|
|
385
|
+
// symbol such as `token.sym` resolves to the on-chain TOKEN.SYM. The legacy
|
|
386
|
+
// `bit*` MPA aliases were renamed on chain, so those are retried with the
|
|
387
|
+
// prefix stripped.
|
|
388
|
+
const read = (method, args) => callDb(session, method, args);
|
|
389
|
+
let stub = await resolveAssetRef(read, input);
|
|
390
|
+
if (!stub && input.toLowerCase().startsWith('bit')) {
|
|
391
|
+
stub = await resolveAssetRef(read, input.slice(3));
|
|
429
392
|
}
|
|
430
393
|
if (!stub)
|
|
431
394
|
throw new Error(`asset not found: ${input}`);
|
|
432
|
-
|
|
433
|
-
|
|
395
|
+
// The shared resolver fetches through get_assets, so this is already the
|
|
396
|
+
// extended object (float/dynamic ids included): no second round trip.
|
|
397
|
+
return stub;
|
|
434
398
|
}
|
|
435
399
|
async function fetchAssetHolders(session, assetId, onProgress) {
|
|
436
400
|
if (session.assetApi === null)
|
|
437
401
|
throw new Error('asset_api unavailable on this node');
|
|
438
402
|
const api = session.assetApi;
|
|
403
|
+
// The node caps holders per call (api_limit_get_asset_holders, commonly 100).
|
|
439
404
|
const pageSize = Math.max(1, Math.min(session.config.api_limit_get_asset_holders ?? 100, 100));
|
|
405
|
+
let totalCount = null;
|
|
406
|
+
try {
|
|
407
|
+
const count = await session.client.call(api, 'get_asset_holders_count', [assetId]);
|
|
408
|
+
if (typeof count === 'number' && count >= 0)
|
|
409
|
+
totalCount = count;
|
|
410
|
+
}
|
|
411
|
+
catch {
|
|
412
|
+
// optional: only used to plan the pages
|
|
413
|
+
}
|
|
440
414
|
const rows = [];
|
|
441
415
|
let complete = false;
|
|
416
|
+
// Reported while the pages are still in flight (rows is empty until the
|
|
417
|
+
// parallel fetch is reassembled), so count the rows themselves.
|
|
418
|
+
let fetchedRows = 0;
|
|
419
|
+
let fetchedPages = 0;
|
|
420
|
+
const report = (rowsInPage) => {
|
|
421
|
+
fetchedRows += rowsInPage;
|
|
422
|
+
fetchedPages += 1;
|
|
423
|
+
if (fetchedPages % 20 === 0)
|
|
424
|
+
onProgress?.(fetchedRows);
|
|
425
|
+
};
|
|
426
|
+
// `get_asset_holders(asset, start, limit)` walks the by_asset_balance index by
|
|
427
|
+
// *position*, so offsets are independent. With the holder count known the
|
|
428
|
+
// whole rich list is fetched as parallel pages instead of one blocking chain
|
|
429
|
+
// (15k holders = 153 sequential calls today).
|
|
430
|
+
if (totalCount !== null && totalCount > pageSize) {
|
|
431
|
+
const offsets = [];
|
|
432
|
+
for (let start = 0; start < totalCount; start += pageSize)
|
|
433
|
+
offsets.push(start);
|
|
434
|
+
// One sentinel page past the count: it absorbs a balance that appeared
|
|
435
|
+
// (or a rank that shifted) mid-scan, so a full last page cannot be
|
|
436
|
+
// mistaken for the whole list.
|
|
437
|
+
offsets.push(offsets[offsets.length - 1] + pageSize);
|
|
438
|
+
const pages = new Array(offsets.length);
|
|
439
|
+
let cursor = 0;
|
|
440
|
+
const worker = async () => {
|
|
441
|
+
for (;;) {
|
|
442
|
+
const index = cursor++;
|
|
443
|
+
if (index >= offsets.length)
|
|
444
|
+
return;
|
|
445
|
+
const page = await session.client.call(api, 'get_asset_holders', [assetId, offsets[index], pageSize]);
|
|
446
|
+
pages[index] = Array.isArray(page) ? page : [];
|
|
447
|
+
report(pages[index].length);
|
|
448
|
+
}
|
|
449
|
+
};
|
|
450
|
+
const workers = Math.min(HOLDER_PAGE_CONCURRENCY, offsets.length);
|
|
451
|
+
await Promise.all(Array.from({ length: workers }, () => worker()));
|
|
452
|
+
// Reassemble in rank order. A balance change mid-scan can shift ranks and
|
|
453
|
+
// repeat an account, so keep its highest-ranked occurrence only.
|
|
454
|
+
const seen = new Set();
|
|
455
|
+
let shortPage = false;
|
|
456
|
+
for (const page of pages) {
|
|
457
|
+
for (const holder of page) {
|
|
458
|
+
if (!holder?.account_id || seen.has(holder.account_id))
|
|
459
|
+
continue;
|
|
460
|
+
seen.add(holder.account_id);
|
|
461
|
+
rows.push(holder);
|
|
462
|
+
}
|
|
463
|
+
if (page.length < pageSize) {
|
|
464
|
+
shortPage = true;
|
|
465
|
+
break;
|
|
466
|
+
}
|
|
467
|
+
}
|
|
468
|
+
complete = shortPage ? true : rows.length >= totalCount;
|
|
469
|
+
onProgress?.(rows.length);
|
|
470
|
+
return { rows, totalCount, complete };
|
|
471
|
+
}
|
|
442
472
|
let nextProgress = 10000;
|
|
443
473
|
for (let start = 0; start < 2_000_000; start += pageSize) {
|
|
444
474
|
const page = await session.client.call(api, 'get_asset_holders', [assetId, start, pageSize]);
|
|
@@ -456,15 +486,6 @@ async function fetchAssetHolders(session, assetId, onProgress) {
|
|
|
456
486
|
break;
|
|
457
487
|
}
|
|
458
488
|
}
|
|
459
|
-
let totalCount = null;
|
|
460
|
-
try {
|
|
461
|
-
const count = await session.client.call(api, 'get_asset_holders_count', [assetId]);
|
|
462
|
-
if (typeof count === 'number')
|
|
463
|
-
totalCount = count;
|
|
464
|
-
}
|
|
465
|
-
catch {
|
|
466
|
-
// optional
|
|
467
|
-
}
|
|
468
489
|
return { rows, totalCount, complete };
|
|
469
490
|
}
|
|
470
491
|
// ---------------------------------------------------------------------------
|
|
@@ -581,19 +602,6 @@ function esc(text) {
|
|
|
581
602
|
}
|
|
582
603
|
});
|
|
583
604
|
}
|
|
584
|
-
// ---------------------------------------------------------------------------
|
|
585
|
-
// Collection
|
|
586
|
-
// ---------------------------------------------------------------------------
|
|
587
|
-
function progress(enabled, message) {
|
|
588
|
-
if (!enabled || !process.stderr.isTTY)
|
|
589
|
-
return;
|
|
590
|
-
process.stderr.write(`\r\x1b[2K ${message}`);
|
|
591
|
-
}
|
|
592
|
-
function clearProgress(enabled) {
|
|
593
|
-
if (!enabled || !process.stderr.isTTY)
|
|
594
|
-
return;
|
|
595
|
-
process.stderr.write('\r\x1b[2K');
|
|
596
|
-
}
|
|
597
605
|
async function scanLimitOrders(session, tokenId, assets, limit, concurrency, onProgress) {
|
|
598
606
|
const byCounterpart = new Map();
|
|
599
607
|
const depthByCounterpart = new Map();
|
|
@@ -737,8 +745,22 @@ async function collect(session, opts) {
|
|
|
737
745
|
const precision = asset.precision;
|
|
738
746
|
const money = (value) => formatUnits(value, precision);
|
|
739
747
|
// ---- Assets (symbols + order scan universe) -----------------------------
|
|
740
|
-
|
|
741
|
-
|
|
748
|
+
// Assets are enumerated by id instead of `list_assets` (100 assets per page):
|
|
749
|
+
// the 1.3.x space is dense and append-only, so a batched get_objects walk is
|
|
750
|
+
// the same payload with ~7 round trips instead of ~66. The object list also
|
|
751
|
+
// feeds the limit-order sweep below.
|
|
752
|
+
progress(showProgress, 'listing assets (1.3.x) ...');
|
|
753
|
+
const assetScan = await scanIdRange({
|
|
754
|
+
read: (method, args) => callDb(session, method, args),
|
|
755
|
+
prefix: '1.3',
|
|
756
|
+
maxId: 200_000,
|
|
757
|
+
gap: DENSE_SPACE_GAP,
|
|
758
|
+
onProgress: (n) => progress(showProgress, `listing assets (1.3.x) ... ${n} ids`),
|
|
759
|
+
});
|
|
760
|
+
const assets = assetScan.objects;
|
|
761
|
+
if (assetScan.hitLimit) {
|
|
762
|
+
warnings.push('Asset enumeration hit its 200,000-id limit; the limit-order scan may miss newer assets.');
|
|
763
|
+
}
|
|
742
764
|
const assetById = new Map(assets.map((row) => [row.id, row]));
|
|
743
765
|
assetById.set(asset.id, asset);
|
|
744
766
|
const symbolOf = (id) => assetById.get(id)?.symbol ?? id;
|
|
@@ -877,7 +899,13 @@ async function collect(session, opts) {
|
|
|
877
899
|
}
|
|
878
900
|
// ---- Vesting balances (1.13.x) ------------------------------------------
|
|
879
901
|
progress(showProgress, 'scanning vesting balances (1.13.x) ...');
|
|
880
|
-
const vestingScan = await scanIdRange(
|
|
902
|
+
const vestingScan = await scanIdRange({
|
|
903
|
+
read: (method, args) => callDb(session, method, args),
|
|
904
|
+
prefix: '1.13',
|
|
905
|
+
maxId: opts.vestingMax,
|
|
906
|
+
gap: opts.gap,
|
|
907
|
+
onProgress: (n) => progress(showProgress, `scanning vesting balances (1.13.x) ... ${n} ids`),
|
|
908
|
+
});
|
|
881
909
|
let vestingTotal = 0n;
|
|
882
910
|
let vestingCount = 0;
|
|
883
911
|
const vestingByType = new Map();
|
|
@@ -1299,11 +1327,8 @@ function renderTerminal(report, opts) {
|
|
|
1299
1327
|
if (report.locked > 0n && report.float > 0n) {
|
|
1300
1328
|
console.log(c(colors.gray, ` locked / float ${(Number(report.locked * 10000n / report.float) / 10_000).toFixed(2)}×`));
|
|
1301
1329
|
}
|
|
1302
|
-
const
|
|
1303
|
-
|
|
1304
|
-
console.log(c(colors.bold + colors.yellow, ` ── ${title} ${'─'.repeat(Math.max(0, 70 - title.length))}`));
|
|
1305
|
-
};
|
|
1306
|
-
section('Where the token sits');
|
|
1330
|
+
const heading = (title) => { console.log(section(title)); };
|
|
1331
|
+
heading('Where the token sits');
|
|
1307
1332
|
console.log(c(colors.gray, ` ${padEnd('Category', 26)} ${padStart(symbol, 18)} ${padStart('% supply', 10)} ${padStart('% float', 10)}`));
|
|
1308
1333
|
for (const bucket of report.buckets) {
|
|
1309
1334
|
console.log(` ${padEnd(bucket.label.slice(0, 26), 26)} ${padStart(money(bucket.amount), 18)} `
|
|
@@ -1408,13 +1433,10 @@ function renderTerminal(report, opts) {
|
|
|
1408
1433
|
console.log(` HTLC escrow ${money(report.htlcs.total)} in ${report.htlcs.count} HTLC(s)`);
|
|
1409
1434
|
}
|
|
1410
1435
|
}
|
|
1411
|
-
if (report.warnings.length > 0)
|
|
1412
|
-
|
|
1413
|
-
for (const warning of report.warnings)
|
|
1414
|
-
console.log(c(colors.sell, ` • ${warning}`));
|
|
1415
|
-
}
|
|
1436
|
+
if (report.warnings.length > 0)
|
|
1437
|
+
console.log(warningsBlock(report.warnings));
|
|
1416
1438
|
console.log();
|
|
1417
|
-
console.log(
|
|
1439
|
+
console.log(summaryLine(`reconcile: free ${money(report.free)} + locked ${money(report.locked)} `
|
|
1418
1440
|
+ `+ blinded ${money(report.supply.confidential)} + other ${money(report.residual)} = ${money(supply)}`));
|
|
1419
1441
|
}
|
|
1420
1442
|
function groupSlices(slices, total) {
|
|
@@ -1802,7 +1824,7 @@ ${warnings}
|
|
|
1802
1824
|
</div>
|
|
1803
1825
|
|
|
1804
1826
|
<footer>
|
|
1805
|
-
<p>Sources: bitshares-core 7.0.x database_api — <code>
|
|
1827
|
+
<p>Sources: bitshares-core 7.0.x database_api — <code>get_objects</code> (1.3.x assets, 1.13.x vesting), <code>get_limit_orders</code>, <code>get_liquidity_pools_by_one_asset</code>, <code>get_credit_offers_by_asset</code>, <code>get_credit_deals_by_collateral_asset</code>, <code>get_credit_deals_by_debt_asset</code>, <code>get_samet_funds_by_asset</code>, <code>list_htlcs</code>${report.holders.sourceNode ? ', <code>asset_api::get_asset_holders</code>' : ''}.</p>
|
|
1806
1828
|
<p>Read-only; no keys, no transactions. Limit-order totals are per market and capped by the node's per-side limit.</p>
|
|
1807
1829
|
</footer>
|
|
1808
1830
|
</body>
|
|
@@ -1826,7 +1848,7 @@ async function main() {
|
|
|
1826
1848
|
}
|
|
1827
1849
|
catch (e) {
|
|
1828
1850
|
if (e instanceof UsageError) {
|
|
1829
|
-
console.error(
|
|
1851
|
+
console.error(`${LOG_TAG} Error: ${e.message}\n`);
|
|
1830
1852
|
console.error(HELP);
|
|
1831
1853
|
process.exit(2);
|
|
1832
1854
|
}
|
|
@@ -1836,6 +1858,8 @@ async function main() {
|
|
|
1836
1858
|
console.log(HELP);
|
|
1837
1859
|
return;
|
|
1838
1860
|
}
|
|
1861
|
+
if (!opts.json)
|
|
1862
|
+
console.log(loadingLine(LOG_TAG, `Loading token distribution for ${opts.asset} from chain...`));
|
|
1839
1863
|
const nodes = opts.nodes.length > 0 ? opts.nodes : [...NODE_MANAGEMENT.DEFAULT_NODES];
|
|
1840
1864
|
const session = await openSession(nodes);
|
|
1841
1865
|
try {
|
|
@@ -1854,7 +1878,7 @@ async function main() {
|
|
|
1854
1878
|
else {
|
|
1855
1879
|
renderTerminal(report, opts);
|
|
1856
1880
|
if (htmlPath)
|
|
1857
|
-
console.log(
|
|
1881
|
+
console.log(savedLine(LOG_TAG, 'Report', toFileUrl(htmlPath)));
|
|
1858
1882
|
}
|
|
1859
1883
|
}
|
|
1860
1884
|
finally {
|
|
@@ -1863,7 +1887,7 @@ async function main() {
|
|
|
1863
1887
|
}
|
|
1864
1888
|
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
|
|
1865
1889
|
main().catch((e) => {
|
|
1866
|
-
console.error(`\
|
|
1890
|
+
console.error(`\n${LOG_TAG} Error: ${e.message}`);
|
|
1867
1891
|
process.exit(1);
|
|
1868
1892
|
});
|
|
1869
1893
|
}
|
package/dist/scripts/tv.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
'use strict';
|
|
3
3
|
/**
|
|
4
4
|
* Usage:
|
|
5
|
-
* dexbot tv <bot|pool
|
|
5
|
+
* dexbot tv <bot|pool|AssetA/AssetB> [--month N] [--chart <path>] [--feed|--pool|--book]
|
|
6
6
|
*
|
|
7
7
|
* Thin entry for the shared chart-command pipeline in scripts/chart_command.ts
|
|
8
8
|
* (identical fetch/target logic as `dexbot dw`). This command renders through
|
|
@@ -38,6 +38,24 @@ const TESTS = [
|
|
|
38
38
|
expectFail: false,
|
|
39
39
|
externalizeNodeBuiltins: true,
|
|
40
40
|
},
|
|
41
|
+
{
|
|
42
|
+
label: 'modules/liquidity_pool_ref.ts (browser-safe)',
|
|
43
|
+
entry: 'modules/liquidity_pool_ref.ts',
|
|
44
|
+
expectFail: false,
|
|
45
|
+
externalizeNodeBuiltins: true,
|
|
46
|
+
},
|
|
47
|
+
{
|
|
48
|
+
label: 'modules/chain_scan.ts (browser-safe)',
|
|
49
|
+
entry: 'modules/chain_scan.ts',
|
|
50
|
+
expectFail: false,
|
|
51
|
+
externalizeNodeBuiltins: true,
|
|
52
|
+
},
|
|
53
|
+
{
|
|
54
|
+
label: 'modules/asset_lookup.ts (browser-safe)',
|
|
55
|
+
entry: 'modules/asset_lookup.ts',
|
|
56
|
+
expectFail: false,
|
|
57
|
+
externalizeNodeBuiltins: true,
|
|
58
|
+
},
|
|
41
59
|
{
|
|
42
60
|
label: 'modules/crypto/index.ts (browser-safe)',
|
|
43
61
|
entry: 'modules/crypto/index.ts',
|
|
@@ -229,7 +229,7 @@ syncFromMaster(masterGrid, orderId, masterVersion?) {
|
|
|
229
229
|
|--------|-------------|
|
|
230
230
|
| `performSafeRebalance(fills, excludeIds)` | Entry point — delegates to COW |
|
|
231
231
|
| `_applySafeRebalanceCOW(fills, excludeIds)` | Creates working grid, runs planning |
|
|
232
|
-
| `WorkingGrid.buildDelta(masterGrid)` | Delta between master and working copy (`modules/order/working_grid.ts
|
|
232
|
+
| `WorkingGrid.buildDelta(masterGrid)` | Delta between master and working copy (`modules/order/working_grid.ts`, delegating to `utils/order.ts`) |
|
|
233
233
|
| `_commitWorkingGrid(workingGrid, indexes, boundary, options = {})` | Atomic swap to master |
|
|
234
234
|
| `_setRebalanceState(state)` | Track rebalance state |
|
|
235
235
|
| `_currentWorkingGridStack` | Stack of active working-grid references during rebalance for fill sync; peek the innermost via `_peekWorkingGrid()`, managed with `_pushWorkingGridRef`/`_popWorkingGridRef`/`_releaseWorkingGridRef`/`_clearWorkingGridRef` |
|
package/docs/COW_INVARIANTS.md
CHANGED
|
@@ -57,12 +57,14 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
|
|
|
57
57
|
- `_clearOrderCachesLogic` must bump `_gridVersion` so an in-flight COW plan (baseVersion from the pre-swap grid) is refused at commit instead of committing over a regenerated zero-slot grid.
|
|
58
58
|
|
|
59
59
|
- `INV-COW-006` Boundary moves only on fills and same-batch spread promotion
|
|
60
|
-
- Fund changes never move the boundary. Only boundary crawl (`deriveTargetBoundary`, `order/utils/order.ts`)
|
|
60
|
+
- Fund changes never move the boundary. Only boundary crawl (`deriveTargetBoundary`, `order/utils/order.ts`), spread promotion, and the fill-driven rail clamp move it, and promotion shifts it only onto orders placed in the same atomic batch (`prepareSpreadCorrectionOrders`).
|
|
61
61
|
- Funds drive order sizing/budget allocation only; `syncBoundaryToFunds`/`calculateFundDrivenBoundary` are deleted (1.5.3).
|
|
62
|
+
- `deriveRailBoundary` (`dexbot_cow_runtime.ts`, pre-broadcast) clamps the committed boundary to the batch's resulting rails: `maxBuyIdx <= boundary <= minSellIdx - gapSlots - 1`. A fill's counter order is the rail fact, so it decides the boundary; an empty refill hole never outvotes it. Rail membership = the batch's own op destinations + master rail orders on their own side of the planned boundary (BUY at/below, SELL at/above the implied sellStart); a master order parked on the wrong side is a STRAY (refused-commit adoption, SPREAD-GUARD straggler, stranded hold) and is skipped, because clamping onto it would self-legalize the corrupt state (live: one stray sell clamped 138 → 115). Rail indices are the orders' LIVE chain price (`resolveLiveOrderLadderPosition`), not stale slot ids. A crossed/over-ceiling rail fails closed (`rail-crossed` / `rail-exceeds-grid`) and keeps the previous value instead of legalizing it; the result then passes the shared `validatePersistedBoundary` gate (with cancel/rotation sources allow-listed), so the rail clamp and the fill re-anchor end in one validator.
|
|
62
63
|
|
|
63
64
|
- `INV-COW-007` Boundary hold on guard-skipped refills
|
|
64
65
|
- When a slot on the plan's refill wire (`collectRefillSlotIds`: the plan's CREATE ids minus edge-ladder edge ids) was guard-skipped at broadcast (`skippedUpdateSlotIds` ∪ `clampedUpdateSlotIds` ∪ `skippedCreateSlotIds`), `resolveRefillBoundaryHold` keeps the COMMITTED boundary instead of committing the plan's shifted one over the stranded rail hole; the grid still commits.
|
|
65
66
|
- Edge-ladder CREATEs are excluded because reserves are static edge insurance whose fills never crawl — a skipped reserve must not pin geometry.
|
|
67
|
+
- The hold is intersected with `deriveRailBoundary`: when the batch actually placed a counter order above the committed boundary, the rail clamp advances the boundary (the hold becomes a no-op and the counter stays live). The hold still applies when nothing was placed on the promoted rail. `boundaryHeld` is `effectiveBoundary !== workingBoundary`, so crawl consumption follows the value actually committed.
|
|
66
68
|
- The hold rides to the commit as `options.boundaryHeld`, which suppresses the pending-crawl clear.
|
|
67
69
|
- `trackBoundaryHold` counts consecutive hold batches (`manager._consecutiveBoundaryHolds`, cleared on the first clean batch) with a last-hold snapshot (`manager._lastBoundaryHoldInfo`); runs of 3+ escalate visibly. It also records a hold signature (`manager._lastHeldPlanSignature`: committed boundary + guard pivot + `_lastFilledAt` + held wire) so a fill-less re-plan of an unchanged state defers instead of re-broadcasting the identical vetoed plan.
|
|
68
70
|
- Fill-driven rebalances never sleep on `_broadcastingFlag` inside `_fillProcessingLock`: `performSafeRebalance({deferIfBroadcasting:true})` returns a `deferred` result and the region-end hook schedules one no-fill rebalance (`schedulePostRecoveryRebalance`). This prevents the 20s lock-acquisition-timeout cascade when a broadcast region outlives the 30s `_awaitBroadcastIdle` wait. The stale-flag watchdog (`_clearStaleBroadcastFlag`, 120s) fires the same region-end hook when it hard-clears a leaked flag, so deferred fills are woken even when the region never ends through `stopBroadcasting()`.
|
|
@@ -71,7 +73,7 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
|
|
|
71
73
|
- `INV-COW-008` Owed fill crawls survive unapplied commits
|
|
72
74
|
- `order/strategy.ts` records a crawl per shift-eligible fill at intake (slot-level dedupe, capped at 500); `deriveTargetBoundary` folds still-owed `_pendingFillCrawls` into the next derivation, excluding the current batch's slots, edge slots, and window members — a window that reaches the grid edge is not an edge order, using the same window exclusion every placement picker and `countLiveEdgeOrders` apply.
|
|
73
75
|
- `_commitWorkingGrid` clears them only when the plan's boundary was actually applied — a held boundary (`boundaryHeld`), a gate-rejected boundary, and a null boundary all leave them owed.
|
|
74
|
-
- A window that lands BEHIND the newest real fill is repaired by `reanchorBoundaryFromLastFill` (called from `calculateTargetGrid` right after the derivation): the fill anchors the geometry — `SELL fill at f => boundary ≥ f − gapSlots`, `BUY fill at f => boundary ≤ f − 1` — because a ±1 crawl can never catch up. Fail-closed preconditions:
|
|
76
|
+
- A window that lands BEHIND the newest real fill is repaired by `reanchorBoundaryFromLastFill` (called from `calculateTargetGrid` right after the derivation): the fill anchors the geometry — `SELL fill at f => boundary ≥ f − gapSlots`, `BUY fill at f => boundary ≤ f − 1` — because a ±1 crawl can never catch up. The anchor index is the current fill batch's EXTREMUM for the fill side (max slot for SELL, min slot for BUY), not the mutable last-processed pivot: a sweep processed in chunks overwrites the pivot per chunk (live: 1366 → 1349 → 1361), and anchoring on a non-extremum leaves the furthest fill's counter order in-band. Prices come from the fill record (the real execution price, `INV-COW-011`) with the slot id as a legacy fallback. Fail-closed preconditions: a pivot whose `lastFillPivotSource` is `fill` (a book seed never anchors; the bot-scoped last-market-fill row is the fallback), on-ladder price within one increment, a post-clamp target that actually puts the fill outside the window, and `validatePersistedBoundary` (a strand refuses the re-anchor). ELIGIBILITY matches the crawl: EDGE-pinned insurance fills never arm the pivot (`recordLastFilledPrices` skips them, shared classifier `collectEdgePinnedFillIds`) and so can never anchor — an edge order is static insurance, not market movement, and an absolute anchor at a rail-edge price would teleport the window there; PARTIAL fills still anchor (real trade) because the fill's OWN PARTIAL residual at the anchor slot is explicitly allow-listed (it is inside the band by construction). Startup/recovery load paths tolerate that pure in-band state (`tolerateTransientStranding`) so a restart does not rebuild the boundary before GAP-EVAC clears the residual. A successful re-anchor is absolute: it consumes the whole pending-crawl snapshot taken at plan time, so no older delta can be applied on top.
|
|
75
77
|
- Consumption is SCOPED to what the derivation applied: `deriveTargetBoundary` returns `consumedCrawlIds` (the owed records whose shift it folded, plus the records it deliberately never counts — current-batch slots, edge-classified slots, malformed records), the plan carries it (`buildSuccessResult` → `CowResult` → `_commitWorkingGrid` options), and `_consumePendingFillCrawls` drops exactly those, logging `Dropped N … kept=M`. A capped fold consumes only the entries it actually applied (same-side prefix up to the applied magnitude), so the remainder stays owed exactly once. `_clearPendingFillCrawls` remains the explicit allowed-loss path (rebuild, rejected snapshot, restart replay) and drops everything.
|
|
76
78
|
- A commit **without** the wire consumes nothing (a create-only plan never derived a boundary): clearing it would be the old silent-loss bug (2026-10-25: 7 slots 147–153 swept, every record dropped, boundary ending 7 levels behind).
|
|
77
79
|
- `consumePendingFillCrawls` applies them onto a restored finite boundary; `applyPersistedPendingCrawls` is the shared startup/recovery wrapper used before sync/reconcile; `_clearPendingFillCrawls` drops them when the boundary is re-anchored (grid rebuild via `initializeGrid`, rejected snapshot via `rejectCorruptedGridSnapshot`, persisted snapshot wipe via `AccountOrders.clearGrid`).
|
|
@@ -81,8 +83,10 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
|
|
|
81
83
|
- Provenance gate: only a pivot written through the shared `setLastFillPivot(type, price, 'fill')` writer is persist-eligible. A book-seeded pivot (`seedLastFilledPricesFromBook`, provenance `'book'`) is a heuristic — max resting buy / min resting sell is not market truth — and is never fossilized into the snapshot. The fill-batch and queued-fill refresh sites funnel through one implementation (free function in `utils/system.ts`; `OrderManager._setLastFillPivot` delegates to it), so value, timestamp, and provenance cannot drift apart; the queued-fill refresh and the restore path call the same free function directly, with the legacy-stub fallback built into the shared writer rather than copy-pasted. A single-sided book arms through the same writer with provenance `'book'`; the two-sided midpoint and per-side mirror seeds stay direct writes by design, because they carry no pivot provenance and must not be persist-eligible.
|
|
82
84
|
- The row carries `{price, type, fillsAt, genesisHash}` validated by one shared gate (`normalizeLastFillPivot`) used by BOTH the `storeMasterGrid` sanitizer and the loader — the two shape checks cannot drift. `null` from the payload builder always clears the stored row (consumed pivot / cold manager / no live genesis), `undefined` stays a legacy no-op for old callers, and a malformed shape also clears.
|
|
83
85
|
- Restore ordering: `grid.loadGrid` restores the pivot right after `_restoreBoundary` — with the persisted genesis applied and the grid re-typed, BEFORE the first reconcile/broadcast — so a restart cannot re-open the cold window where evacuation stamps get applied against a boundary still being rebuilt. All `loadGrid` callers (startup resume, price-match resume, recovery reload) inherit it; there is no second restore call site to drift.
|
|
84
|
-
- Validation chain (`restoreLastFillPivot`): TTL expiry (`GRID_LIMITS.LAST_FILL_PIVOT_TTL_MS`, 24h; the pivot is a "latest fill" fact, not a permanent ratchet; expired pivots hand over to the startup book seed) and genesis binding (mismatched hash = dead generation) erase the row through one shared drop path (`clearPersistedLastFillPivot` under the bot's persistence lock, best-effort). Off-grid refusal (`resolveOnGridPivot` — the runtime's own ladder validator, imported lazily from the restore site so ONE implementation serves both the per-probe live guard and the restore; the restorer can never accept a value the runtime would refuse per probe) is a no-op that falls back to the book seed and leaves the row for the next snapshot flush to clear (the cold in-memory pivot makes the payload builder return null). The snapped ladder level is restored, never the raw float, and the ORIGINAL `fillsAt` is preserved through `setLastFillPivot`'s `atMs` param so the TTL keeps meaning "age of the last fill", not "time since this restart".
|
|
85
|
-
- Generation invalidation mirrors the pending-crawl ledger: `initializeGrid` and `rejectCorruptedGridSnapshot` clear the in-memory pivot via `resetLastFillPivot` (exposed as `OrderManager._resetLastFillPivot`), which clears the FULL scalar family — per-side mirrors included — so `seedLastFilledPricesFromBook`'s cold gate cannot be silently suppressed by stale per-side values after a grid rebuild, and `AccountOrders.clearGrid` wipes the persisted row with the snapshot.
|
|
86
|
+
- Validation chain (`restoreLastFillPivot`): TTL expiry (`GRID_LIMITS.LAST_FILL_PIVOT_TTL_MS`, 24h; the pivot is a "latest fill" fact, not a permanent ratchet; expired pivots hand over to the startup book seed) and genesis binding (mismatched hash = dead generation) erase the row through one shared drop path (`clearPersistedLastFillPivot` under the bot's persistence lock, best-effort). The SAME TTL bounds the in-memory reference at READ time (`resolveLastFillGuardReference` / `resolveFillProvenancedRow`), because the geometry-bind watchdog re-centers at most once per pivot and reports that a fill or the TTL restores the side — that promise must not depend on a restart. Off-grid refusal (`resolveOnGridPivot` — the runtime's own ladder validator, imported lazily from the restore site so ONE implementation serves both the per-probe live guard and the restore; the restorer can never accept a value the runtime would refuse per probe) is a no-op that falls back to the book seed and leaves the row for the next snapshot flush to clear (the cold in-memory pivot makes the payload builder return null). The snapped ladder level is restored, never the raw float, and the ORIGINAL `fillsAt` is preserved through `setLastFillPivot`'s `atMs` param so the TTL keeps meaning "age of the last fill", not "time since this restart".
|
|
87
|
+
- Generation invalidation mirrors the pending-crawl ledger: `initializeGrid` and `rejectCorruptedGridSnapshot` clear the in-memory pivot via `resetLastFillPivot` (exposed as `OrderManager._resetLastFillPivot`), which clears the FULL scalar family — per-side mirrors included — so `seedLastFilledPricesFromBook`'s cold gate cannot be silently suppressed by stale per-side values after a grid rebuild, and `AccountOrders.clearGrid` wipes the persisted row with the snapshot.
|
|
88
|
+
- A rebuild then RE-ARMS explicitly (`rearmLastFillPivotFromMarketFill`) from the bot-scoped last-market-fill row, through the same writer, at the original timestamp (taken from the same row that supplied the price, so a book-seeded live pivot never lends its clock) and with provenance `'fill'`. The guard must not go cold while the account's last trade price is known (pre-1.6.14 behaviour: a rebuild let a fresh grid sell below the last sale), and the re-arm must be a logged, persisted write rather than an accident of the read-time fallback — the rebuild site's comment and the runtime behaviour were allowed to differ before this. Consequence, pinned by test: the pivot SURVIVES a rebuild, bounded by the same 24h TTL (enforced at restore AND at read time; an expired row is neither used as a fallback nor re-armed). If the market has moved away from that price, the same-side rail reads `last-fill-blocked` and only a fill (or TTL expiry) restores it; the geometry-bind watchdog therefore re-centers at most ONCE per pivot (`_lastGeometryResyncPivotKey`) — a re-center cannot move the pivot, so a second attempt would only churn the new generation — and then reports that fact instead of escalating.
|
|
89
|
+
- EDGE-PINNED fills never arm the pivot: `recordLastFilledPrices` skips the ids returned by `collectEdgePinnedFillIds` (the same window/edge classifier the placement pickers use). An edge order is static fat-finger insurance, not market movement; letting a wick on one arm the pivot at a rail-edge price would veto that whole side of the book AND, because the pivot doubles as the re-anchor's absolute geometry anchor, teleport the window to the edge.
|
|
86
90
|
|
|
87
91
|
- `INV-COW-010` Grid-layer spread-correction cycle is atomic and bounded
|
|
88
92
|
- `checkSpreadCondition` holds the refcounted broadcast region (`startBroadcasting` / `stopBroadcasting`, released in `finally`) across its whole attempt loop, so a fill-driven rebalance defers rather than committing a master-version bump between the initial plan and its broadcast. This narrows the race; the COW commit guard remains the backstop.
|
|
@@ -90,20 +94,26 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
|
|
|
90
94
|
- A transient refusal re-plans ONCE from fresh master (`replanSpreadCorrectionFromFreshMaster`, bounded by `TIMING.SPREAD_CORRECTION_MAX_ATTEMPTS`); a non-transient refusal (`commit-refused` / `update-target-missing` / `unmatched-chain-orders` / `shutdown`) is not retried and counts toward the out-of-spread stale clock.
|
|
91
95
|
- Candidates are tightening-edge-only on real grid slots (`tightensSpread` + distance-to-edge ordering + `doesNotCrossMarket`) AND last-fill consistent: the planner applies the guard's own direction rule (`passesLastFill`, same pivot, same predicate) before the quota slice, so a batch is never built from ops the broadcast guard would drop. An unplaceable side reports the geometry bind `last-fill-blocked` instead of a wasted "prepared but not executed" cycle.
|
|
92
96
|
- The budget spent by the loop is chain-truth for a known candidate set: `available = chainFree − virtualReservation` is circular when the reservation describes the very slots being funded, so an over-sized projection (rail sized from a larger balance or from inventory locked in resting orders) would read 0 forever (`planned 3, placing 0`, 84 minutes live). `deriveChainTruthFundBudget` re-derives it as `min(chainFree, min(virtualReservation, Σ candidate ideals))` when `available` is 0 **and** the reservation exceeds chain free (a zero caused by fees or an empty balance is a real constraint and is honoured); the chain stays the final arbiter.
|
|
93
|
-
- Terminal stalls are named and escalated on their own windows rather than the structural 30 minutes: rail oversubscription (`availableFund = chainFree − virtual` reads 0 while the side still holds inventory) on `SPREAD_STALE_FUND_ESCALATE_MS`, the `last-fill-blocked` geometry bind on `SPREAD_STALE_GEOMETRY_ESCALATE_MS
|
|
97
|
+
- Terminal stalls are named and escalated on their own windows rather than the structural 30 minutes: rail oversubscription (`availableFund = chainFree − virtual` reads 0 while the side still holds inventory) on `SPREAD_STALE_FUND_ESCALATE_MS`, the `last-fill-blocked` geometry bind on `SPREAD_STALE_GEOMETRY_ESCALATE_MS` (capped at ONE re-center per fill pivot — `_lastGeometryResyncPivotKey` — because a re-center cannot move the pivot, and the skip is explained once instead of rebuilt every cooldown), and the persistence clock clears only after sustained tolerance (`SPREAD_STALE_IN_TOLERANCE_RESET_MS`) or a placement.
|
|
94
98
|
- This is the grid layer's counterpart to `INV-COW-003` (COW-layer pre-broadcast re-plan) and to `INV-COW-007`'s broadcast-flag deferral contract.
|
|
95
99
|
|
|
100
|
+
- `INV-COW-011` Live-price provenance for fill, gap and crossing decisions
|
|
101
|
+
- A fill record carries the chain execution price (`sync_engine._computeFillTransitionResult` / pass-1 full-fill / pass-2 adoption), computed from paid/received amounts when only the history is available; the slot's generation price is a fallback, never the first choice. The queued-fill pivot refresh (`refreshLastFillPivotFromQueue`) likewise prefers fill economics over the slot price. The slot's identity price is NOT rewritten (`GRID-PRICE-INVARIANT`); only the transient fill/pivot fact uses the chain price.
|
|
102
|
+
- Gap-evacuation geometry maps an on-chain order's LIVE price onto the genesis ladder (`resolveLiveOrderLadderPosition`) before falling back to `parseSlotIndex(slot.id)`. Detection (`detectGapEvacuationCandidates`), the drain-time validation (`_validatePriceCorrectionEntry`), and the teeth (`_processGapEvacuationTeeth`) all use it, so a refused-commit adoption that leaves an order keyed at an in-rail slot cannot hide an in-band order.
|
|
103
|
+
- A price mismatch whose live chain price maps inside the gap band queues a cancel-only `gapEvacuation` correction and drops any opposite-kind (plain re-price) entry for the same chain order. Evacuation takes precedence over correcting the order back to a stale slot price.
|
|
104
|
+
- The crossing guard's candidate set (`buildCrossingCheckCandidates`) uses the live chain price for master and pending orders, so an emission cannot print onto a live opposite-side order that was adopted at a stale slot price.
|
|
105
|
+
|
|
96
106
|
- `INV-PROJ-001` New projected orders remain virtual
|
|
97
107
|
- Orders projected into empty slots must be `VIRTUAL` with no `orderId` until chain confirmation.
|
|
98
108
|
|
|
99
109
|
- `INV-PROJ-002` Preserve on-chain PARTIAL size in projection
|
|
100
110
|
- If identity is retained (`keepOrderId=true`) and current state is `PARTIAL`, projected size must preserve current on-chain remaining size.
|
|
101
111
|
- It must not be overwritten by ideal geometric `targetSize`.
|
|
102
|
-
- Exception: a `PARTIAL` with a rotation/size-update action targeting its `orderId` does use `targetSize` (the explicit-UPDATE path
|
|
112
|
+
- Exception: a `PARTIAL` with a rotation/size-update action targeting its `orderId` does use `targetSize` (the explicit-UPDATE path in `projectTargetToWorkingGrid`, `modules/order/utils/validate.ts`).
|
|
103
113
|
- Preserve-path size must be normalized to finite, non-negative value.
|
|
104
114
|
|
|
105
115
|
- `INV-PROJ-003` ACTIVE on-chain projection preserves current size (same as PARTIAL)
|
|
106
|
-
- If identity is retained and state is `ACTIVE`, projection preserves current on-chain size via the same `shouldPreserveSize` path as `PARTIAL` (`validate.ts
|
|
116
|
+
- If identity is retained and state is `ACTIVE`, projection preserves current on-chain size via the same `shouldPreserveSize` path as `PARTIAL` (`validate.ts`, `projectTargetToWorkingGrid`).
|
|
107
117
|
- An explicit UPDATE action targeting the `orderId` is required to apply `targetSize`.
|
|
108
118
|
|
|
109
119
|
- `INV-ID-001` Order identity retention rule
|
|
@@ -122,7 +132,7 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
|
|
|
122
132
|
- `INV-ACC-003` Cross-bot fund registry invariant (INVARIANT 3)
|
|
123
133
|
- Shared-account per-bot commitment must not exceed the bot's proportional share of chain balance.
|
|
124
134
|
- Checked with widened tolerance `max(PERCENT_TOLERANCE * 3, 0.15)`.
|
|
125
|
-
- Registry failure logs an error (`order/accounting.ts
|
|
135
|
+
- Registry failure logs an error (`order/accounting.ts`, cross-bot registry invariant block), not a silent skip.
|
|
126
136
|
|
|
127
137
|
---
|
|
128
138
|
|
|
@@ -263,7 +273,7 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
|
|
|
263
273
|
|
|
264
274
|
- `INV-BATCH-001` Illegal state batch abort
|
|
265
275
|
- `executeBatch` throws `ILLEGAL_SPREAD_STATE` on an illegal grid layout (emitted at `modules/order/utils/validate.ts`, propagated via `modules/order/manager.ts` `_throwOnIllegalState`).
|
|
266
|
-
- The `_handleBatchHardAbort` catch for `ILLEGAL_ORDER_STATE` (`dexbot_class.ts
|
|
276
|
+
- The `_handleBatchHardAbort` catch for `ILLEGAL_ORDER_STATE` (`dexbot_class.ts`) is a test-only dead branch — production never emits that code; only a test stub uses it.
|
|
267
277
|
- In production, recovery + cooldown are armed on the next maintenance tick via `_abortFlowIfIllegalState` (the `INV-MAINT-002` path), returning `abortedForIllegalState: true` to the caller. The caller does not need to return immediately; the maintenance tick handles recovery.
|
|
268
278
|
- Hard abort triggers one immediate recovery sync (`_triggerStateRecoverySync`) plus arms one maintenance cooldown cycle (`_maintenanceCooldownCycles = Math.max(current, 1)`).
|
|
269
279
|
|
|
@@ -282,7 +292,7 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
|
|
|
282
292
|
- NOT virtualize the slot.
|
|
283
293
|
- Preserve `orderId` until sync reconciles it.
|
|
284
294
|
- NOT mark the order as stale-cleaned.
|
|
285
|
-
- Fast path: if the batch result indicates `ORDER_SIZE_DRIFT_TARGETED` (`dexbot_state_recovery.ts
|
|
295
|
+
- Fast path: if the batch result indicates `ORDER_SIZE_DRIFT_TARGETED` (`dexbot_state_recovery.ts`), a targeted repair applies the correction directly and skips `_triggerStateRecoverySync`.
|
|
286
296
|
|
|
287
297
|
---
|
|
288
298
|
|
|
@@ -306,7 +316,7 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
|
|
|
306
316
|
- `INV-REG-001` Cross-bot allocation ≤ proportional share
|
|
307
317
|
- Per-bot committed amounts (sum of on-chain orders) must not exceed `totalChainBalance × allocatedPercent`.
|
|
308
318
|
- Violation triggers an error-level log entry (not silent), with tolerance `max(PERCENT_TOLERANCE * 3, 0.15)`.
|
|
309
|
-
- Registry registration is pre-flight + atomic; only shared-account bots register (`dexbot.ts
|
|
319
|
+
- Registry registration is pre-flight + atomic; only shared-account bots register (`dexbot.ts` derives `sharedAccounts` where `accountGroups[a].length > 1`), and registration completes before any shared-account bot starts.
|
|
310
320
|
- Release happens in `DEXBot.shutdown`.
|
|
311
321
|
|
|
312
322
|
- `INV-REG-002` Async-locked registry writes
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# DEXBot vs DEXBot2 — Detailed Comparison Report
|
|
2
2
|
|
|
3
3
|
> **Date:** 2026-09-02 *(metrics refreshed against local source trees)*
|
|
4
|
-
> **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.
|
|
4
|
+
> **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.7.0).
|
|
5
5
|
> **Audience:** Developers, contributors, and operators evaluating or migrating between the two projects.
|
|
6
6
|
|
|
7
7
|
---
|
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
|
|
37
37
|
| Attribute | DEXBot (original) | DEXBot2 |
|
|
38
38
|
|---|---|---|
|
|
39
|
-
| **Release Track** | 1.0.0 | v1.
|
|
39
|
+
| **Release Track** | 1.0.0 | v1.7.0 |
|
|
40
40
|
| **Language** | Python 3.6+ | TypeScript 5.x |
|
|
41
41
|
| **Status** | Released 1.0.0, unmaintained | Active development |
|
|
42
42
|
| **Last Repo Activity** | May 23, 2020 | 2026-09-02 |
|
|
@@ -776,13 +776,13 @@ Where:
|
|
|
776
776
|
|
|
777
777
|
| Metric | DEXBot | DEXBot2 |
|
|
778
778
|
|---|---|---|
|
|
779
|
-
| **Release Track** | 1.0.0 | v1.
|
|
779
|
+
| **Release Track** | 1.0.0 | v1.7.0 |
|
|
780
780
|
| **Active Since** | ~2018 | December 2025 |
|
|
781
|
-
| **Last Commit** | May 23, 2020 | 2026-
|
|
782
|
-
| **Total Commits** | 2281 | 2,
|
|
781
|
+
| **Last Commit** | May 23, 2020 | 2026-11-02 |
|
|
782
|
+
| **Total Commits** | 2281 | 2,468 (current HEAD, v1.7.0 line) |
|
|
783
783
|
| **Lines of Code** | ~10,846 Python LOC in `dexbot/` | Large TypeScript runtime + adapter + Claw + analysis + tests |
|
|
784
784
|
| **Source Files** | 72 Python files in `dexbot/` | ~656 TS files across the repo |
|
|
785
|
-
| **Test Files** | 16 Python test files |
|
|
785
|
+
| **Test Files** | 16 Python test files | 355 `test_*.ts` files (338 `tests/` + 17 `claw/tests/`, auto-discovered via `globSync`) |
|
|
786
786
|
| **Documentation** | Sphinx docs + README | 60+ Markdown docs plus Claw skills/references |
|
|
787
787
|
| **Strategies** | 3 + plugins | 1 |
|
|
788
788
|
| **Max Concurrent Bots** | Many (one process) | Many (one monolithic process by default; per-bot via `--isolated`/PM2) |
|
package/docs/EVOLUTION.md
CHANGED
|
@@ -2,14 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
## Executive Summary
|
|
4
4
|
|
|
5
|
-
DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.
|
|
5
|
+
DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.7.0 release.
|
|
6
6
|
|
|
7
7
|
### Key Milestones
|
|
8
8
|
- **Project Inception**: December 2, 2025
|
|
9
|
-
- **Growth Phase**: 2,
|
|
9
|
+
- **Growth Phase**: 2,468 commits over ~9 active months
|
|
10
10
|
- **Code Maturity**: Evolution from basic utilities to a ~100,000+ LoC intelligent TypeScript system
|
|
11
|
-
- **Stability**: Progression from manual testing to a suite of
|
|
12
|
-
- **Releases**:
|
|
11
|
+
- **Stability**: Progression from manual testing to a suite of 341 automated test files
|
|
12
|
+
- **Releases**: 151 version entries in the changelog (v0.1.0 to v1.7.0)
|
|
13
13
|
|
|
14
14
|
> **Post-1.0.0 "why":** the thematic story behind the hardening releases — root cause, recurring
|
|
15
15
|
> bug families, and lessons — lives in
|
|
@@ -149,7 +149,7 @@ Evolved from a basic README to a comprehensive framework (50+ docs entries, 80%+
|
|
|
149
149
|
|
|
150
150
|
## Version History
|
|
151
151
|
|
|
152
|
-
Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` over the current history (2026-
|
|
152
|
+
Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` over the current history (2026-11-02). The 107 commits up to and including the `v0.1.0` tag are not attributed to an era, so the current totals are 2,361 (`v0.1.0..HEAD`) and 2,468 (`HEAD`); the `v1.4.x` era rows overlap slightly because `v1.4.13` is not an ancestor of `v1.4.25` in the current history. Per-release detail lives in [CHANGELOG.md](../CHANGELOG.md); the thematic post-1.0.0 story in [ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md](ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md).
|
|
153
153
|
|
|
154
154
|
| Era | Commits | Theme |
|
|
155
155
|
|-----|--------:|-------|
|
|
@@ -175,11 +175,13 @@ Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` o
|
|
|
175
175
|
| v1.6.14 → v1.6.15 | 20 | Spread-correction resilience (atomic plan/retry, bounded re-plan, transient-refusal grace), price-vs-amount level identity for low-precision assets, credit-renewal free-collateral top-up, TradingView 1h/chart fixes & live data-age badge, per-asset `dexbot rich`, ~4x parallel test runner |
|
|
176
176
|
| v1.6.15 → v1.6.16 | 14 | Monolithic per-bot control routing, orientation-shared candle cache, market-profile orientation tolerance, chart log-axis hang fix + viewport-clipped draw hooks, Firefox Playwright chart suite, adapter-whitelist rename/copy sync, `dexbot rich` symbol canonicalization, doc reconciliation |
|
|
177
177
|
| v1.6.16 → v1.6.17 | 11 | Last-fill direction guard, placeable-slot spread planning with named stalls, chain-truth funding + fill-anchored boundary re-anchor, owed-crawl consumption, restart auth-before-stop with cleared vault secret, pool-priced LP-share collateral, AMA slowPeriod/slope retune, BTS & per-token supply distribution analyzers |
|
|
178
|
+
| v1.6.17 → v1.6.18 | 19 | Partial-fill re-anchor recovery (stale-evac skip, residual allow-list, crawl subsumption, rotation-only repair), rail-derived boundary + live fill/chain prices, edge-fill pivot exclusion, guard arity pinning with explicit re-arm, per-slot last-fill exclusion count, CLI `--flag=value` walker, `__test` seam guard, export-surface cleanup |
|
|
179
|
+
| v1.6.18 → v1.7.0 | 11 | Liquidity depth chart + `dexbot liquid`/`liq`/`liqu`, `dexbot asset` supply distribution shortcut, pool id/pool-token chart targets + shared spawn runner, case-insensitive asset lookup, asset-report chain-request cuts, shared CLI terminal output, orphan-fill attribution + dark-level revive, stale-grid re-buy discipline, pivot clock provenance & read-time TTL |
|
|
178
180
|
|
|
179
181
|
---
|
|
180
182
|
|
|
181
183
|
**Report Originally Generated**: February 19, 2026
|
|
182
|
-
**Last Updated**:
|
|
183
|
-
**Total Commits**: 2,
|
|
184
|
-
**Date Range**: December 2, 2025 –
|
|
184
|
+
**Last Updated**: November 2, 2026
|
|
185
|
+
**Total Commits**: 2,468
|
|
186
|
+
**Date Range**: December 2, 2025 – November 2, 2026
|
|
185
187
|
**Repository**: DEXBot2 (BitShares DEX Trading Bot)
|