dexbot 1.6.18 → 1.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +26 -0
- package/README.md +24 -18
- package/analysis/README.md +95 -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_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/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/trade_profitability.js +2 -1
- package/dist/analysis/tradingview/analyze_tradingview.js +2 -1
- package/dist/dexbot.js +74 -169
- package/dist/modules/asset_lookup.d.ts +25 -0
- package/dist/modules/asset_lookup.js +75 -0
- 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/dexbot_cow_runtime.js +14 -4
- package/dist/modules/dexbot_fill_runtime.js +20 -0
- package/dist/modules/dexbot_maintenance_runtime.js +16 -1
- package/dist/modules/launcher/runtime_entry.d.ts +21 -1
- package/dist/modules/launcher/runtime_entry.js +36 -1
- package/dist/modules/liquidity_pool_ref.d.ts +32 -0
- package/dist/modules/liquidity_pool_ref.js +116 -0
- package/dist/modules/order/grid.js +9 -2
- package/dist/modules/order/grid_reconcile.js +22 -1
- package/dist/modules/order/grid_reconcile_internal.js +92 -14
- package/dist/modules/order/index.d.ts +15 -1
- package/dist/modules/order/manager.d.ts +2 -0
- package/dist/modules/order/manager.js +3 -0
- package/dist/modules/order/sync_engine.d.ts +20 -0
- package/dist/modules/order/sync_engine.js +101 -33
- package/dist/modules/order/utils/math.d.ts +18 -1
- package/dist/modules/order/utils/math.js +30 -1
- package/dist/modules/order/utils/order.d.ts +107 -1
- package/dist/modules/order/utils/order.js +298 -1
- package/dist/modules/order/utils/system.d.ts +63 -1
- package/dist/modules/order/utils/system.js +247 -36
- package/dist/modules/order/utils/validate.js +33 -2
- package/dist/modules/types.d.ts +5 -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/COW_INVARIANTS.md +2 -2
- package/docs/DEXBOT_COMPARISON.md +6 -6
- package/docs/EVOLUTION.md +9 -8
- package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
- package/docs/GRID_PRICE_INVARIANT.md +4 -1
- package/docs/GRID_RECONCILE.md +20 -0
- package/docs/LOGGING.md +25 -3
- package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +2 -1
- package/docs/README.md +1 -1
- package/docs/WORKFLOW.md +3 -1
- package/modules/README.md +5 -1
- package/package.json +3 -1
- 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',
|
package/docs/COW_INVARIANTS.md
CHANGED
|
@@ -83,9 +83,9 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
|
|
|
83
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.
|
|
84
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.
|
|
85
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.
|
|
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). 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".
|
|
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
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 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
|
|
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
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.
|
|
90
90
|
|
|
91
91
|
- `INV-COW-010` Grid-layer spread-correction cycle is atomic and bounded
|
|
@@ -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-11-
|
|
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-11-
|
|
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
|
|-----|--------:|-------|
|
|
@@ -176,11 +176,12 @@ Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` o
|
|
|
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
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 |
|
|
179
180
|
|
|
180
181
|
---
|
|
181
182
|
|
|
182
183
|
**Report Originally Generated**: February 19, 2026
|
|
183
|
-
**Last Updated**: November
|
|
184
|
-
**Total Commits**: 2,
|
|
185
|
-
**Date Range**: December 2, 2025 – November
|
|
184
|
+
**Last Updated**: November 2, 2026
|
|
185
|
+
**Total Commits**: 2,468
|
|
186
|
+
**Date Range**: December 2, 2025 – November 2, 2026
|
|
186
187
|
**Repository**: DEXBot2 (BitShares DEX Trading Bot)
|
|
@@ -805,4 +805,4 @@ To prevent "Time-of-Check to Time-of-Use" errors:
|
|
|
805
805
|
**TOCTOU protection in `processFillAccounting`.** `_buildBtsDeferredRefundAdjustment` reads `btsFeeState` from `mgr.orders` while the order lock is held — the lock is acquired before accounting runs, and the POST-RESET and BOOTSTRAP tracked-fill accounting paths follow the same locking pattern.
|
|
806
806
|
|
|
807
807
|
---
|
|
808
|
-
*Technical Reference for DEXBot2 v1.
|
|
808
|
+
*Technical Reference for DEXBot2 v1.7.0 release*
|
|
@@ -202,7 +202,10 @@ Rules that keep the mirror honest:
|
|
|
202
202
|
genesis-mismatch verdicts erase the row through one shared drop path
|
|
203
203
|
(`AccountOrders.clearPersistedLastFillPivot`); an off-ladder row is a no-op
|
|
204
204
|
that falls back to the book seed. The snapped ladder level is restored, never
|
|
205
|
-
the raw float.
|
|
205
|
+
the raw float. The same TTL bounds the in-memory reference at READ time
|
|
206
|
+
(`resolveLastFillGuardReference` / `resolveFillProvenancedRow`), so the
|
|
207
|
+
geometry-bind "a fill or the TTL restores the side" contract does not need a
|
|
208
|
+
restart; a reference with no timestamp has an unknown age and never expires.
|
|
206
209
|
- **The generation wipes the pivot.** `initializeGrid` and
|
|
207
210
|
`rejectCorruptedGridSnapshot` call `resetLastFillPivot`, which clears the
|
|
208
211
|
full scalar family including the per-side mirrors (so the book seed's cold
|
package/docs/GRID_RECONCILE.md
CHANGED
|
@@ -225,6 +225,23 @@ Reconcile Phase 1 runs under `_gridLock` with no side effects on the frozen mast
|
|
|
225
225
|
|
|
226
226
|
Three of the six guarded emission sites are reconcile sites (`RECONCILE-CREATE`, `RECONCILE-UPDATE`, `STARTUP-CREATE` in `grid_reconcile_internal.ts`): every op reconcile emits is checked against the slot's genesis level and an off-grid emission is skipped, not broadcast — see [`GRID_PRICE_INVARIANT.md`](GRID_PRICE_INVARIANT.md). The coupling is bidirectional: the invariant guard's persistent-rejection escalation and the deferred-hold escalation both exit through the same structural resync (debounced reload → full reset) described here, and a full reset's update-first reconcile emits the rail's genesis level, so the guard does not block its own resolution.
|
|
227
227
|
|
|
228
|
+
### Fill Discipline (unsettled fills + last-fill placement)
|
|
229
|
+
|
|
230
|
+
Reconcile derives its window from the **master grid**, which is only as fresh as the last applied fill. Two gates keep a top-up from being derived from geometry that has not absorbed the latest trades (both added after the 2026-11-02 buy-higher incident: 9 buy-lower violations, 23.5% of the window's BTS):
|
|
231
|
+
|
|
232
|
+
- **Unsettled-fill gate** (`hasUnsettledFills`, `utils/system.ts`): while fills are queued (`_incomingFillQueue`), draining (`_deferredFillsPending`), in flight (`_fillBatchInFlight`) or owed a crawl (`_pendingFillCrawls`), `maybeRunTargetedDriftReconciliation` defers the targeted reconcile entirely and `_reconcileStartupSide` defers only the **window top-up** creates (1:1 repairs — cancelled-slot replacement, vacated-rail refill — still run). The master still counts filled slots as ACTIVE in that window, so a top-up would restore the expensive end of the rail.
|
|
233
|
+
- **Last-fill placement guard** (`isLastFillPlacementBlocked`, `utils/system.ts`): every reconcile placement (create in `_createOrderFromGrid` and the batch create path, plus the re-pricing relocation in `_prepareStartupUpdatePlan`) is refused when it sits on the wrong side of the last fill **or on the same grid level** (within half an increment — a slot level and its execution price differ by rounding). A same-price relocation is an adoption, not a placement, and is exempt. `_pickVirtualSlotsToActivate` applies the same predicate so the pick budget rolls to the next level down/up instead of being spent on a level the create would refuse — the filled level is never re-stamped same-side (the "rotate to bottom BUY / counter SELL" behaviour).
|
|
234
|
+
|
|
235
|
+
A fill whose order id no longer sits on an ACTIVE/PARTIAL slot is no longer dropped: `attributeUnmatchedFillToGrid` (shared by `SyncEngine._absorbUnmatchedFill` and the orphan-credit sweep in `dexbot_fill_runtime.ts`) records the **pivot + owed crawl from the real execution price**. It resolves the slot two ways — the chain id when a virtualised slot still owns it, otherwise the **genesis ladder level of the execution price** (the common case, because `virtualizeOrder` NULLS `orderId`; this is what the incident actually hit). A crawl is only owed by a HOLE, and a price outside the frozen rail is refused so a shelf order cannot arm the pivot. Without this the pivot stays on a stale, higher fill and the direction rule then permits re-buys above the market.
|
|
236
|
+
|
|
237
|
+
**The dark level it leaves behind is repaired too.** A slot virtualised while its order stayed live on chain reads as *not active* (`_countActiveOnGrid` needs ACTIVE/PARTIAL) while its order still counts in `chainCount`, so the side reports a shortfall it can never repair — and the planner sees a free level that already holds an order. Three pieces close that:
|
|
238
|
+
|
|
239
|
+
- `reviveVirtualSlotFromChain` re-materialises the slot **in place** (master-only, no broadcast) when the chain order is still live *and* rests at that slot's level. Wired into sync pass 1 (`sync-pass1-revive`) and reconcile Phase 1 (`startup-revive`). A rotation alias (chain order at another level) is never resurrected.
|
|
240
|
+
- Sync pass 1 also clears a **stale** id on a non-placed slot (`sync-clear-stale-id`) without booking a fill, so the level becomes a normal hole again.
|
|
241
|
+
- `validateCreateTargetSlots` treats *any* slot that still owns an `orderId` (any state) as `slot_occupied` (hard: the batch aborts), and a slot with a possibly-landed CREATE as the softer `slot_create_uncertain` (only that CREATE is withheld — an unknown outcome is not proof of a live order). `reconcileGrid` no longer treats a virtualised slot that owns an id as a hole. Together with the stale-id cleanup this blocks a **duplicate CREATE at a price that already holds an order** without stranding a level whose id was merely stale.
|
|
242
|
+
|
|
243
|
+
The spread-correction planner judges candidates with the same predicate as the placement guards (direction **plus same grid level**), so it no longer plans a create the broadcast guard will refuse; an unplaceable side reports the `last-fill-blocked` stall instead of burning a cycle. The COW build loop reaches the same verdict without a band term: it snaps the fill reference onto the ladder first (`resolveOnGridPivot`, tolerance one increment) and then applies the direction rule, so a target on the just-filled level equals the snapped pivot and is refused. A reference too far off-ladder to snap is judged raw (fail-open with a warning) rather than rewritten onto the grid — which is why the raw placement predicate is deliberately **not** wired into that lane (pinned by `tests/test_last_fill_guard.ts` PIVOT-004).
|
|
244
|
+
|
|
228
245
|
### Truncated-Read Ambiguity (since 1.4.8)
|
|
229
246
|
|
|
230
247
|
Every chain read feeding an absence/surplus decision goes through `readOpenOrdersGuarded`. A truncated snapshot is always unreadable. An empty snapshot is also unreadable at callers that set `deferEmpty: true`; the Phase-2 cancellation pre-read intentionally accepts a complete empty result, executes no plan, and leaves all remaining state for the normal reconcile paths:
|
|
@@ -287,6 +304,9 @@ Commit `e64db685` replaced 6 single-value boolean state fields with refcounts/st
|
|
|
287
304
|
| `tests/test_async_lock_force_release.ts` | Nested multi-lock re-entrancy |
|
|
288
305
|
| `tests/test_targeted_drift_reconcile.ts` | Active-order shortfall triggers sync |
|
|
289
306
|
| `tests/test_edge_orders.ts` | Reserve startup coverage: fully-placed matched-surplus cancels, orphan+matched ordering, at-target silence, plan/execute parity, shelf-order survival, reserve-deficit trigger (`buy reserves 0/2`) with filled/disabled/empty-budget silence, window-exclusion counting |
|
|
307
|
+
| `tests/test_grid_fill_discipline.ts` | Placement predicate (direction + same grid level), picker fall-through on both sides, create refusal before broadcast, window top-up deferral while fills are unsettled, slot revive (ACTIVE/PARTIAL + all refusals), CREATE occupancy gate, dark-level hole gate, spread planner/guard parity, orphan-sweep attribution |
|
|
308
|
+
| `tests/test_last_fill_pivot_rearm.ts` + `tests/test_last_fill_pivot_persistence.ts` | Re-arm on a new generation, timestamp provenance (the row that supplied the price also supplies the clock), and the pivot lifetime enforced at read time as well as at restore (expired rows neither arm nor re-arm; unknown age never expires) |
|
|
309
|
+
| `tests/test_fill_attribution_virtual_slot.ts` | Fill absorbed into a virtualised slot: pivot + owed crawl from the execution price (chain-id **and** ladder identity), unknown-order/no-stacking/dryRun cases, occupied-level and out-of-grid refusals, incident ladder refusals, `hasUnsettledFills` states |
|
|
290
310
|
| `tests/repro_phantom_orders.ts` | Phantom order prevention |
|
|
291
311
|
|
|
292
312
|
---
|
package/docs/LOGGING.md
CHANGED
|
@@ -316,11 +316,12 @@ re-plan retries). Kept separate from the generic `refusedCommitCount`.
|
|
|
316
316
|
| `[SPREAD-CORRECTION] <side> rail is OVERSUBSCRIBED: virtual reservation X exceeds chain free Y by Z — no correction can be funded until the rail is re-sized ...` | `availableFund` is `free − virtual`, so an oversubscribed rail reads 0 while the side still holds inventory. The watchdog escalates this on its short fund window |
|
|
317
317
|
| `[SPREAD-STALE] Spread out of tolerance for Nmin ... (outOfSpread=..., stall=...)` | Persistence warn with the last stall cause; the clock survives single in-tolerance readings and the terminal cases escalate early: `stall=last-fill-blocked` (sell window behind the last fill) on the 10-minute geometry window, a rail oversubscription on the 5-minute fund window |
|
|
318
318
|
| `[SPREAD-STALE] ... (sell window behind the last fill — re-centering)` | The `last-fill-blocked` geometry bind is escalating; placement cannot repair it, a re-center can |
|
|
319
|
-
| `[SPREAD-STALE] Still out of tolerance Nmin after re-centering on fill pivot P: the pivot is outside this generation's placeable side, so a re-center cannot clear it. A fill ... or pivot expiry restores the side; no further re-center will be requested for this pivot.` | Churn cap: a re-center does not move the pivot, so the same fill gets ONE re-center (`_lastGeometryResyncPivotKey`). Logged once per pivot; the same-side rail stays blocked until a fill or the 24h pivot TTL, by design |
|
|
320
|
-
| `[BOUNDARY] Re-anchored from the last fill: SELL filled at slot 153 (0.447640); boundary 146 -> 149 so the fill sits outside its own window` | The window was behind the fill and a ±1 crawl cannot catch up; the fill now anchors the geometry. The anchor is the current fill batch's extremum for that side (max SELL / min BUY), not the last-processed pivot. Refusals stay silent (cold/off-ladder/ceiling-clamped/unsafe preconditions); the fill's own PARTIAL residual is allow-listed, so a partial fill does not deadlock the repair |
|
|
319
|
+
| `[SPREAD-STALE] Still out of tolerance Nmin after re-centering on fill pivot P: the pivot is outside this generation's placeable side, so a re-center cannot clear it. A fill ... or pivot expiry restores the side; no further re-center will be requested for this pivot.` | Churn cap: a re-center does not move the pivot, so the same fill gets ONE re-center (`_lastGeometryResyncPivotKey`). Logged once per pivot; the same-side rail stays blocked until a fill or the read-time 24h pivot TTL, by design |
|
|
320
|
+
| `[BOUNDARY] Re-anchored from the last fill: SELL filled at slot 153 (0.447640); boundary 146 -> 149 so the fill sits outside its own window` | The window was behind the fill and a ±1 crawl cannot catch up; the fill now anchors the geometry. The anchor is the current fill batch's extremum for that side (max SELL / min BUY), not the last-processed pivot. Refusals stay silent (cold/off-ladder/ceiling-clamped/unsafe preconditions); the fill's own PARTIAL residual at the ANCHOR slot is allow-listed, so a partial fill does not deadlock the repair |
|
|
321
321
|
| `[FILL-PIVOT] pivot=... buy=... sell=... n=N src=full/direct` (+ `edge-skipped=K` when present) | One line per fill batch: the LAST-FILL-GUARD pivot after the batch. `edge-skipped=K` means K edge-pinned insurance fills were ignored — they never arm the pivot, so they can never drive the re-anchor |
|
|
322
322
|
| `[FILL-PIVOT] K edge-pinned fill(s) ignored — the guard pivot and the boundary anchor stay on the last window trade` | Edge-only batch: nothing armed, which is the point |
|
|
323
|
-
| `[LAST-FILL-GUARD] Re-armed on the new generation: 0.447640(SELL) from the last real fill (age Ns) — the guard survives a rebuild by design` | A grid rebuild dropped the generation-bound pivot and re-armed it explicitly from the bot-scoped last-market-fill row (`rearmLastFillPivotFromMarketFill`). Provenance stays `fill`; the timestamp is the original fill's |
|
|
323
|
+
| `[LAST-FILL-GUARD] Re-armed on the new generation: 0.447640(SELL) from the last real fill (age Ns) — the guard survives a rebuild by design` | A grid rebuild dropped the generation-bound pivot and re-armed it explicitly from the bot-scoped last-market-fill row (`rearmLastFillPivotFromMarketFill`). Provenance stays `fill`; the timestamp is the original fill's, taken from the SAME row that supplied the price (a book-seeded live pivot never lends its clock) |
|
|
324
|
+
| `[LAST-FILL-GUARD] Pivot expired (age Ns > TTL Ms) — guard re-arms on the next fill` | Read-time pivot lifetime: a fill reference older than `GRID_LIMITS.LAST_FILL_PIVOT_TTL_MS` no longer arms the guard, with or without a restart. Logged once per expired value, so the geometry-bind re-center cap cannot silently park a side forever |
|
|
324
325
|
| `[COW-CROSS-GUARD] CREATE SELL for slot-N at P sits on the crossing side of the floor F (the planner refuses these; a generic refill does not) — it executes at the best available price, so this is a taker-fee observation, not a veto. Once per batch.` | Planner/execution asymmetry made visible: `doesNotCrossMarket` is planner-only, so a reconcile/re-fill CREATE can be a taker fill. Never blocking by design (a hard veto would re-open the counter-order deadlock) |
|
|
325
326
|
| `[COW] Boundary rail-derived: planned X, held Y -> Z (maxBuy=..., minSell=...) — keeping placed counter orders on their rails` | The batch's own rails disagree with the boundary a refill hold would commit. `deriveRailBoundary` clamps to `maxBuy <= boundary <= minSell-gap-1`, so a fill's counter order carries the boundary instead of being stranded in the band. The refill hold still applies when nothing was placed above the committed boundary. The reason suffix `(N stray rail order(s) ignored)` names master orders parked on the wrong side (refused-commit adoption / stranded hold), and `window=K` reports the grid's claimed window size |
|
|
326
327
|
| `[COW] Boundary rail-derived: unusable (rail-crossed ... / rail-exceeds-grid ...); keeping Z` | The live/placed rails already overlap or cannot fit the gap band. Fail closed: keep the previous boundary and let GAP-EVAC / the next plan resolve the offending order (never self-legalize a crossed rail) |
|
|
@@ -334,6 +335,27 @@ re-plan retries). Kept separate from the generic `refusedCommitCount`.
|
|
|
334
335
|
|
|
335
336
|
---
|
|
336
337
|
|
|
338
|
+
## Fill discipline at the reconcile / placement sites
|
|
339
|
+
|
|
340
|
+
Added with the buy-higher fix (2026-11-02: 9 buy-lower violations, 23.5% of the
|
|
341
|
+
window's BTS). See `docs/GRID_RECONCILE.md#fill-discipline-unsettled-fills--last-fill-placement`.
|
|
342
|
+
|
|
343
|
+
| Message | Meaning |
|
|
344
|
+
|---------|---------|
|
|
345
|
+
| `[SYNC] Fill for order <id> attributed to <slot> via chain-id\|ladder (<side> @ P): pivot recorded + owed boundary crawl` (suffix `(slot still holds a live order: no crawl)` when applicable) | The fill's order id identified no ACTIVE/PARTIAL slot. `via=chain-id` means a virtualised slot still owned the id; `via=ladder` means the id was already cleared (every virtualisation NULLS it) and the **execution price** resolved the level through the genesis ladder. The pivot moves to that price unless the writer skips the fill as edge-pinned (a wick on the static floor/ceiling must never arm the guard — the line then reads `pivot NOT armed`); the crawl is only owed by a HOLE the grid owns, because an occupied level cannot be re-placed. A price outside the frozen rail is refused here, so a shelf/manual order can never arm the pivot. Previously this was a silent `ignored: order not found in active grid` at `debug` — the stale pivot it left behind is what let the reconciler re-buy above the market |
|
|
346
|
+
| `[SYNC] Revived virtualised slot <slot>: its chain order <id> is still live (<side> @ P, size S) while the slot was VIRTUAL — re-materialised in place (no broadcast), so window accounting counts it again` | The dark-level repair: a slot virtualised while its order stayed on chain (phantom cleanup on a truncated read, refused-commit adoption) is invisible to window accounting while its order still counts in `chainCount`. Master-only revive, only when the chain order rests at that slot's level — a rotation alias (different level) is never resurrected |
|
|
347
|
+
| `[SYNC] Revive of virtualised slot <slot> rejected — slot keeps its VIRTUAL state` | `_applyOrderUpdate` refused the revive; nothing is booked and the next sync re-detects |
|
|
348
|
+
| `[SYNC] Cleared stale chain id <id> on <slot> (slot was VIRTUAL): the order is gone from the chain read, so the level is a normal hole again — no fill booked` | A non-placed slot carried an id whose order is absent from a trusted read. The id is dropped WITHOUT booking a fill (inventing one would arm the pivot and crawl for a trade that never happened). This is what keeps the CREATE occupancy gate from stranding a level |
|
|
349
|
+
| (same `[SYNC] Revived virtualised slot ...` line) | Emitted by BOTH call sites: sync pass 1 (`sync-pass1-revive`) and reconcile Phase 1 (`startup-revive`, before the plan is derived so the side no longer reads a phantom shortfall) |
|
|
350
|
+
| `[TARGETED-SYNC] Deferring <context> reconciliation: <reason> — the rail must absorb the fills before it is topped up` | A targeted reconcile was requested while fills are queued/draining/in flight/owed a crawl. No cooldown is stamped, so it retries as soon as they settle |
|
|
351
|
+
| `Startup: Deferring N <side> window top-up create(s): <reason> — the rail must absorb the fills before it is refilled` | Same gate on the reconcile side. 1:1 repairs (cancelled-slot replacement, vacated-rail refill) are still planned; only the window top-up waits |
|
|
352
|
+
| `Startup: <side> pick skipped N slot(s) on the wrong side of the last fill (pivot P); picked X/Y` | The activation picker refused candidates the placement guard would block, so the pick rolls to the next level down (BUY) / up (SELL). `picked X/Y` below target means the rail had no legal level left this cycle |
|
|
353
|
+
| `[_createOrderFromGrid] SKIP (LAST-FILL-GUARD): Create for <slot> at P on the wrong side of the last fill F (<reason>); the rail must crawl before this level is refilled` | A reconcile create was refused before any broadcast. `reason` is `direction` (wrong side) or `same-level` (within half a grid step — a slot level and its execution price differ by rounding) |
|
|
354
|
+
| `Startup: Skip create <label> (LAST-FILL-GUARD) - price P ...` | Same refusal in the batch create path |
|
|
355
|
+
| `[STARTUP-LAST-FILL-GUARD] Skipping relocation update <orderId> -> <slot>: target ... is on the wrong side of the last fill F (<reason>); re-align on the next reconcile cycle` | A re-pricing relocation is a placement too. Same-price relocations are adoptions and are exempt |
|
|
356
|
+
|
|
357
|
+
---
|
|
358
|
+
|
|
337
359
|
## Fill History Scan Profiling
|
|
338
360
|
|
|
339
361
|
The `Subscriptions` logger emits `fetchFillHistoryEntries: maxPages (X) reached` at `debug` level when the fill-history scan reaches its configured page cap. On a busy account this is **normal** — the scan simply catches up over multiple polling cycles rather than in a single pass.
|