dexbot 1.6.14 → 1.6.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/CHANGELOG.md +34 -4
  2. package/analysis/README.md +6 -6
  3. package/analysis/tradingview/README.md +2 -1
  4. package/claw/README.md +7 -7
  5. package/claw/package.json +1 -1
  6. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  7. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  8. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +80 -6
  9. package/dist/analysis/trend_detection/dynamic_weight_chart_generator.js +36 -2
  10. package/dist/dexbot.js +23 -3
  11. package/dist/market_adapter/core/strategies/dynamic_weight_series.js +26 -11
  12. package/dist/modules/account_bots.d.ts +3 -0
  13. package/dist/modules/account_bots.js +3 -0
  14. package/dist/modules/bitshares-native/subscriptions.js +1 -1
  15. package/dist/modules/bot_defaults.d.ts +13 -2
  16. package/dist/modules/bot_defaults.js +31 -2
  17. package/dist/modules/bot_settings.js +3 -0
  18. package/dist/modules/constants.d.ts +6 -0
  19. package/dist/modules/constants.js +24 -0
  20. package/dist/modules/credit_runtime.d.ts +35 -5
  21. package/dist/modules/credit_runtime.js +219 -38
  22. package/dist/modules/dexbot_class.d.ts +19 -1
  23. package/dist/modules/dexbot_class.js +58 -20
  24. package/dist/modules/dexbot_cow_runtime.js +19 -18
  25. package/dist/modules/dexbot_fill_runtime.d.ts +1 -1
  26. package/dist/modules/dexbot_fill_runtime.js +4 -7
  27. package/dist/modules/dexbot_maintenance_runtime.d.ts +7 -2
  28. package/dist/modules/dexbot_maintenance_runtime.js +52 -7
  29. package/dist/modules/dexbot_startup_runtime.js +3 -2
  30. package/dist/modules/dexbot_state_recovery.js +1 -1
  31. package/dist/modules/order/export.js +2 -2
  32. package/dist/modules/order/grid.d.ts +118 -1
  33. package/dist/modules/order/grid.js +292 -50
  34. package/dist/modules/order/grid_reconcile.js +4 -3
  35. package/dist/modules/order/grid_reconcile_internal.js +13 -18
  36. package/dist/modules/order/index.d.ts +3 -1
  37. package/dist/modules/order/manager.d.ts +1 -0
  38. package/dist/modules/order/manager.js +5 -14
  39. package/dist/modules/order/sync_engine.js +18 -9
  40. package/dist/modules/order/utils/math.d.ts +98 -26
  41. package/dist/modules/order/utils/math.js +177 -57
  42. package/dist/modules/order/utils/order.js +16 -4
  43. package/dist/modules/order/utils/system.js +2 -2
  44. package/dist/modules/order/utils/validate.d.ts +1 -1
  45. package/dist/modules/order/utils/validate.js +48 -58
  46. package/dist/modules/types.d.ts +7 -0
  47. package/dist/scripts/analyze-credit.js +44 -27
  48. package/dist/scripts/diagnose-pool-history.js +35 -30
  49. package/dist/scripts/pnl.js +1 -1
  50. package/dist/scripts/rich_list.d.ts +18 -0
  51. package/dist/scripts/rich_list.js +461 -0
  52. package/dist/scripts/run-tests.js +80 -4
  53. package/dist/unlock.d.ts +2 -1
  54. package/dist/unlock.js +4 -3
  55. package/docs/COW_INVARIANTS.md +6 -0
  56. package/docs/DEXBOT_COMPARISON.md +6 -6
  57. package/docs/EVOLUTION.md +10 -9
  58. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  59. package/docs/LOGGING.md +16 -1
  60. package/docs/MPA_CREDIT_USAGE.md +10 -5
  61. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +159 -9
  62. package/docs/README.md +1 -1
  63. package/docs/WORKFLOW.md +1 -0
  64. package/docs/architecture.md +56 -2
  65. package/docs/developer_guide.md +5 -1
  66. package/market_adapter/README.md +4 -4
  67. package/modules/README.md +1 -1
  68. package/package.json +2 -1
  69. package/scripts/README.md +59 -32
  70. package/tests/README.md +11 -2
@@ -0,0 +1,461 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * BitShares per-asset rich list / top-holder reporter.
4
+ *
5
+ * Query one asset, or a list of assets, and print their top holders. Uses the
6
+ * chain's `asset_api` (`get_asset_holders`, `get_asset_holders_count`). Those
7
+ * endpoints are often restricted to allowlisted API users, so this script first
8
+ * tries candidate nodes that expose `asset_api` to anonymous logins.
9
+ *
10
+ * The returned holders are ordered by balance descending server-side (the
11
+ * account_balance_index `by_asset_balance` key sorts balance with
12
+ * `std::greater`), so page 0 is already the rich list.
13
+ *
14
+ * CLI: dexbot rich <ASSET> [ASSET...] [--top N]
15
+ * npm run richlist -- <ASSET> --top 10
16
+ */
17
+ const DB_API = 0; // database_api is always registered first
18
+ const LOGIN_API = 1; // login_api (registered second)
19
+ const FALLBACK_HOLDER_LIMIT = 100; // used when the node does not report api_limit_get_asset_holders
20
+ const LOOKUP_PAGE = 100; // chunk size for lookup_asset_symbols / get_objects
21
+ /** Nodes known to expose `asset_api` to anonymous logins come first. */
22
+ const DEFAULT_NODES = [
23
+ 'wss://dex.iobanker.com/ws',
24
+ 'wss://api.dex.trading/',
25
+ 'wss://api.bitshares.dev/ws',
26
+ 'wss://cloud.xbts.io/ws',
27
+ 'wss://node.xbts.io/ws',
28
+ 'wss://api.bts.mobi/ws',
29
+ ];
30
+ class UsageError extends Error {
31
+ }
32
+ // ---------------------------------------------------------------------------
33
+ // CLI parsing
34
+ // ---------------------------------------------------------------------------
35
+ function printHelp() {
36
+ console.log(`BitShares per-asset rich list.
37
+
38
+ Usage:
39
+ dexbot rich <ASSET> [ASSET...] [--top N]
40
+
41
+ Examples:
42
+ dexbot rich <asset>
43
+ dexbot rich <asset-a> <asset-b> <asset-c> --top 10
44
+ dexbot rich <asset-a> <asset-b> --json
45
+
46
+ Flags:
47
+ --top N Holders per asset (default: node holder limit, usually 100)
48
+ --concurrency N Parallel asset queries (default 8)
49
+ --node URL Pin websocket node (repeatable)
50
+ --json JSON output
51
+ --csv CSV output
52
+ -h, --help This help`);
53
+ }
54
+ function parseArgs(argv) {
55
+ const VALUE_FLAGS = new Set(['--top', '--concurrency', '--node']);
56
+ // Normalise `--flag=value` into `--flag value` for the value-taking flags.
57
+ const args = [];
58
+ for (const a of argv) {
59
+ const eq = a.indexOf('=');
60
+ if (a.startsWith('--') && eq > 0 && VALUE_FLAGS.has(a.slice(0, eq))) {
61
+ args.push(a.slice(0, eq), a.slice(eq + 1));
62
+ }
63
+ else {
64
+ args.push(a);
65
+ }
66
+ }
67
+ const opts = {
68
+ assets: [],
69
+ top: 0, // 0 = unset; resolved after the node holder limit is known
70
+ topSet: false,
71
+ concurrency: 8,
72
+ nodes: [],
73
+ json: false,
74
+ csv: false,
75
+ help: false,
76
+ };
77
+ for (let i = 0; i < args.length; i++) {
78
+ const a = args[i];
79
+ const next = () => {
80
+ const v = args[++i];
81
+ if (v === undefined)
82
+ throw new UsageError(`Missing value for ${a}`);
83
+ return v;
84
+ };
85
+ if (a === '--top') {
86
+ opts.top = Number(next());
87
+ opts.topSet = true;
88
+ }
89
+ else if (a === '--concurrency')
90
+ opts.concurrency = Number(next());
91
+ else if (a === '--node')
92
+ opts.nodes.push(next());
93
+ else if (a === '--json')
94
+ opts.json = true;
95
+ else if (a === '--csv')
96
+ opts.csv = true;
97
+ else if (a === '-h' || a === '--help')
98
+ opts.help = true;
99
+ else if (a.startsWith('-'))
100
+ throw new UsageError(`Unknown flag: ${a}`);
101
+ else
102
+ opts.assets.push(a);
103
+ }
104
+ if (opts.topSet && (!Number.isInteger(opts.top) || opts.top < 1)) {
105
+ throw new UsageError('--top must be a positive integer');
106
+ }
107
+ if (!Number.isInteger(opts.concurrency) || opts.concurrency < 1)
108
+ throw new UsageError('--concurrency must be >= 1');
109
+ if (opts.assets.length === 0 && !opts.help) {
110
+ throw new UsageError('Provide at least one ASSET (or an asset list).');
111
+ }
112
+ if (opts.json && opts.csv)
113
+ throw new UsageError('--json and --csv are mutually exclusive');
114
+ return opts;
115
+ }
116
+ class RpcClient {
117
+ url;
118
+ _id = 0;
119
+ _pending = new Map();
120
+ _closed = false;
121
+ _ws = null;
122
+ constructor(url) {
123
+ this.url = url;
124
+ }
125
+ connect(timeoutMs = 15000) {
126
+ return new Promise((resolve, reject) => {
127
+ let settled = false;
128
+ const ws = new WebSocket(this.url);
129
+ this._ws = ws;
130
+ const timer = setTimeout(() => {
131
+ if (settled)
132
+ return;
133
+ settled = true;
134
+ try {
135
+ ws.close();
136
+ }
137
+ catch { /* ignore */ }
138
+ reject(new Error(`connect timeout: ${this.url}`));
139
+ }, timeoutMs);
140
+ ws.onopen = () => {
141
+ if (settled)
142
+ return;
143
+ settled = true;
144
+ clearTimeout(timer);
145
+ resolve();
146
+ };
147
+ ws.onerror = () => {
148
+ if (settled)
149
+ return;
150
+ settled = true;
151
+ clearTimeout(timer);
152
+ reject(new Error(`connect error: ${this.url}`));
153
+ };
154
+ ws.onclose = () => {
155
+ this._closed = true;
156
+ for (const { reject: rj } of this._pending.values())
157
+ rj(new Error('connection closed'));
158
+ this._pending.clear();
159
+ };
160
+ ws.onmessage = (ev) => {
161
+ let msg;
162
+ try {
163
+ msg = JSON.parse(typeof ev.data === 'string' ? ev.data : String(ev.data));
164
+ }
165
+ catch {
166
+ return;
167
+ }
168
+ const p = this._pending.get(msg.id);
169
+ if (!p)
170
+ return;
171
+ this._pending.delete(msg.id);
172
+ if (msg.error)
173
+ p.reject(new Error(msg.error.message || JSON.stringify(msg.error)));
174
+ else
175
+ p.resolve(msg.result);
176
+ };
177
+ });
178
+ }
179
+ call(api, method, args, timeoutMs = 30000) {
180
+ if (this._closed)
181
+ return Promise.reject(new Error('connection closed'));
182
+ return new Promise((resolve, reject) => {
183
+ const id = ++this._id;
184
+ const timer = setTimeout(() => {
185
+ if (!this._pending.has(id))
186
+ return;
187
+ this._pending.delete(id);
188
+ reject(new Error(`rpc timeout: ${method}`));
189
+ }, timeoutMs);
190
+ this._pending.set(id, {
191
+ resolve: (v) => { clearTimeout(timer); resolve(v); },
192
+ reject: (e) => { clearTimeout(timer); reject(e); },
193
+ });
194
+ this._ws?.send(JSON.stringify({ jsonrpc: '2.0', id, method: 'call', params: [api, method, args] }));
195
+ });
196
+ }
197
+ close() {
198
+ try {
199
+ this._ws?.close();
200
+ }
201
+ catch { /* ignore */ }
202
+ }
203
+ }
204
+ // ---------------------------------------------------------------------------
205
+ // Asset API session
206
+ // ---------------------------------------------------------------------------
207
+ /** Connect to the first node that grants anonymous access to `asset_api`. */
208
+ async function openSession(nodes) {
209
+ const errors = [];
210
+ for (const url of nodes) {
211
+ const client = new RpcClient(url);
212
+ try {
213
+ await client.connect();
214
+ await client.call(LOGIN_API, 'login', [null, null]);
215
+ const assetApi = await client.call(LOGIN_API, 'asset', []);
216
+ if (typeof assetApi !== 'number')
217
+ throw new Error('asset() did not return an API id');
218
+ const holderLimit = await readHolderLimit(client);
219
+ return { client, assetApi, dbApi: DB_API, holderLimit };
220
+ }
221
+ catch (e) {
222
+ errors.push(`${url}: ${e.message}`);
223
+ client.close();
224
+ }
225
+ }
226
+ throw new Error(`No node exposes asset_api.\n ${errors.join('\n ')}`);
227
+ }
228
+ /** Read the node's configured get_asset_holders page cap, falling back to 100. */
229
+ async function readHolderLimit(client) {
230
+ try {
231
+ const cfg = await client.call(LOGIN_API, 'get_config', []);
232
+ const limit = cfg?.api_limit_get_asset_holders;
233
+ if (typeof limit === 'number' && limit > 0)
234
+ return limit;
235
+ }
236
+ catch { /* older nodes omit it */ }
237
+ return FALLBACK_HOLDER_LIMIT;
238
+ }
239
+ // ---------------------------------------------------------------------------
240
+ // Chain queries
241
+ // ---------------------------------------------------------------------------
242
+ async function lookupSymbols(session, symbolsOrIds) {
243
+ const out = [];
244
+ for (let i = 0; i < symbolsOrIds.length; i += LOOKUP_PAGE) {
245
+ const slice = symbolsOrIds.slice(i, i + LOOKUP_PAGE);
246
+ const res = await session.client.call(session.dbApi, 'lookup_asset_symbols', [slice]);
247
+ res.forEach((a, j) => out.push(a
248
+ ? { request: slice[j], found: true, id: a.id, symbol: a.symbol, precision: a.precision }
249
+ : { request: slice[j], found: false }));
250
+ }
251
+ return out;
252
+ }
253
+ /**
254
+ * Look up symbols/ids. Legacy `bit*` MPA names were renamed on-chain without the
255
+ * `bit` prefix, so unresolved `bit*` names are retried stripped and reported as
256
+ * an alias.
257
+ */
258
+ async function fetchAssets(session, symbolsOrIds) {
259
+ const out = await lookupSymbols(session, symbolsOrIds);
260
+ const retry = [];
261
+ out.forEach((a, i) => {
262
+ if (!a.found && /^bit./i.test(a.request) && a.request.length > 3)
263
+ retry.push(i);
264
+ });
265
+ if (retry.length > 0) {
266
+ const aliased = await lookupSymbols(session, retry.map((i) => out[i].request.slice(3)));
267
+ retry.forEach((i, j) => {
268
+ const a = aliased[j];
269
+ if (a.found)
270
+ out[i] = { ...a, request: out[i].request, alias: out[i].request };
271
+ });
272
+ }
273
+ return out;
274
+ }
275
+ async function fetchSupplies(session, assetIds) {
276
+ const map = new Map();
277
+ if (assetIds.length === 0)
278
+ return map;
279
+ // dynamic asset data id mirrors the asset instance: 1.3.N -> 2.3.N
280
+ const dynIds = assetIds.map((id) => `2.3.${id.split('.')[2]}`);
281
+ for (let i = 0; i < dynIds.length; i += LOOKUP_PAGE) {
282
+ const slice = dynIds.slice(i, i + LOOKUP_PAGE);
283
+ const objs = await session.client.call(session.dbApi, 'get_objects', [slice]);
284
+ slice.forEach((_, j) => {
285
+ const o = objs[j];
286
+ if (o)
287
+ map.set(assetIds[i + j], o.current_supply);
288
+ });
289
+ }
290
+ return map;
291
+ }
292
+ async function fetchTopHolders(session, asset, top) {
293
+ const holders = await session.client.call(session.assetApi, 'get_asset_holders', [asset.id, 0, top]);
294
+ const count = await session.client.call(session.assetApi, 'get_asset_holders_count', [asset.id]);
295
+ return { holders: holders || [], count };
296
+ }
297
+ /** Run `fn` over items with bounded concurrency, preserving order. */
298
+ async function mapPool(items, limit, fn) {
299
+ const results = new Array(items.length);
300
+ let next = 0;
301
+ async function worker() {
302
+ while (true) {
303
+ const i = next++;
304
+ if (i >= items.length)
305
+ return;
306
+ results[i] = await fn(items[i], i);
307
+ }
308
+ }
309
+ const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
310
+ await Promise.all(workers);
311
+ return results;
312
+ }
313
+ // ---------------------------------------------------------------------------
314
+ // Formatting
315
+ // ---------------------------------------------------------------------------
316
+ function formatAmount(raw, precision) {
317
+ const s = BigInt(raw).toString().padStart(precision + 1, '0');
318
+ const intPart = s.slice(0, s.length - precision);
319
+ let frac = precision > 0 ? s.slice(s.length - precision) : '';
320
+ frac = frac.replace(/0+$/, '');
321
+ return intPart + (frac ? `.${frac}` : '');
322
+ }
323
+ function pct(raw, supply) {
324
+ if (!supply || supply === '0')
325
+ return '';
326
+ const bp = (BigInt(raw) * 10000n) / BigInt(supply); // basis points
327
+ return `${bp / 100n}.${(bp % 100n).toString().padStart(2, '0')}%`;
328
+ }
329
+ const NAME_MAX_WIDTH = 30;
330
+ /** Pick a stable name column width for one asset, capped for readability. */
331
+ function nameColumnWidth(holders) {
332
+ const longest = holders.reduce((m, h) => Math.max(m, h.name.length), 0);
333
+ return Math.min(longest, NAME_MAX_WIDTH);
334
+ }
335
+ function padName(name, width) {
336
+ if (name.length <= width)
337
+ return name.padEnd(width);
338
+ return name.slice(0, width - 1) + '\u2026';
339
+ }
340
+ function widthOf(values) {
341
+ return values.reduce((m, v) => Math.max(m, v.length), 0);
342
+ }
343
+ function printTable(rows) {
344
+ for (const r of rows) {
345
+ if (!r.found) {
346
+ console.error(`?? ${r.request}: asset not found`);
347
+ continue;
348
+ }
349
+ const head = `${r.symbol} (${r.id}) precision=${r.precision}` +
350
+ (r.count != null ? ` holders=${r.count}` : '') +
351
+ (r.supply ? ` supply=${formatAmount(r.supply, r.precision ?? 0)}` : '');
352
+ console.log(`\n${head}`);
353
+ if (r.holders.length === 0) {
354
+ console.log(' (no holders)');
355
+ continue;
356
+ }
357
+ console.log(` ${r.holders.length > 1 ? `top ${r.holders.length}` : 'top holder'}:`);
358
+ const nameWidth = nameColumnWidth(r.holders);
359
+ const rankWidth = String(r.holders.length).length;
360
+ const amounts = r.holders.map((h) => formatAmount(h.amount, r.precision ?? 0));
361
+ const shares = r.holders.map((h) => pct(h.amount, r.supply));
362
+ const amountWidth = widthOf(amounts);
363
+ const shareWidth = widthOf(shares);
364
+ r.holders.forEach((h, i) => {
365
+ const share = shares[i];
366
+ console.log(` #${String(i + 1).padStart(rankWidth)} ${padName(h.name, nameWidth)} ${amounts[i].padStart(amountWidth)}` +
367
+ (share ? ` ${share.padStart(shareWidth)}` : '') + ` ${h.account_id}`);
368
+ });
369
+ }
370
+ }
371
+ function printCsv(rows) {
372
+ console.log('symbol,asset_id,rank,account,account_id,amount,percent');
373
+ for (const r of rows) {
374
+ if (!r.found)
375
+ continue;
376
+ r.holders.forEach((h, i) => {
377
+ console.log([r.symbol, r.id, i + 1, h.name, h.account_id,
378
+ formatAmount(h.amount, r.precision ?? 0), pct(h.amount, r.supply)].join(','));
379
+ });
380
+ }
381
+ }
382
+ // ---------------------------------------------------------------------------
383
+ // Main
384
+ // ---------------------------------------------------------------------------
385
+ async function collectRows(session, assets, opts) {
386
+ const showProgress = !opts.json && !opts.csv && assets.length > 10;
387
+ let done = 0;
388
+ const queried = await mapPool(assets, opts.concurrency, async (asset) => {
389
+ const { holders, count } = await fetchTopHolders(session, asset, opts.top);
390
+ if (showProgress) {
391
+ done++;
392
+ process.stderr.write(`\r queried ${done}/${assets.length} assets ...`);
393
+ }
394
+ return { ...asset, holders, count };
395
+ });
396
+ if (showProgress)
397
+ process.stderr.write('\r');
398
+ const supplies = await fetchSupplies(session, queried.map((r) => r.id));
399
+ return queried.map((r) => ({ ...r, supply: supplies.get(r.id) || null }));
400
+ }
401
+ async function main() {
402
+ let opts;
403
+ try {
404
+ opts = parseArgs(process.argv.slice(2));
405
+ }
406
+ catch (e) {
407
+ if (e instanceof UsageError) {
408
+ console.error(`Error: ${e.message}\n`);
409
+ printHelp();
410
+ process.exit(2);
411
+ }
412
+ throw e;
413
+ }
414
+ if (opts.help) {
415
+ printHelp();
416
+ return;
417
+ }
418
+ const nodes = opts.nodes.length > 0 ? opts.nodes : DEFAULT_NODES;
419
+ const session = await openSession(nodes);
420
+ // Resolve --top against the node's advertised cap now that we know it.
421
+ if (!opts.topSet)
422
+ opts.top = session.holderLimit;
423
+ if (opts.top > session.holderLimit) {
424
+ if (!opts.json && !opts.csv) {
425
+ console.error(`Note: --top ${opts.top} clamped to node limit ${session.holderLimit}.`);
426
+ }
427
+ opts.top = session.holderLimit;
428
+ }
429
+ try {
430
+ const looked = await fetchAssets(session, opts.assets);
431
+ const assets = looked.filter((a) => {
432
+ if (!a.found) {
433
+ console.error(`Warning: asset not found: ${a.request}`);
434
+ return false;
435
+ }
436
+ if (a.alias)
437
+ console.error(`Note: ${a.alias} was renamed; using ${a.symbol}.`);
438
+ return a.found;
439
+ });
440
+ if (assets.length === 0) {
441
+ console.error('No valid assets.');
442
+ process.exit(1);
443
+ }
444
+ const rows = await collectRows(session, assets, opts);
445
+ if (opts.json)
446
+ console.log(JSON.stringify(rows, null, 2));
447
+ else if (opts.csv)
448
+ printCsv(rows);
449
+ else
450
+ printTable(rows);
451
+ }
452
+ finally {
453
+ session.client.close();
454
+ }
455
+ }
456
+ main().catch((e) => {
457
+ console.error(`Error: ${e.message}`);
458
+ process.exit(1);
459
+ });
460
+ export {};
461
+ //# sourceMappingURL=rich_list.js.map
@@ -1,5 +1,6 @@
1
- import { globSync, mkdirSync, appendFileSync } from 'node:fs';
1
+ import { globSync, mkdirSync, appendFileSync, readFileSync, rmSync } from 'node:fs';
2
2
  import { spawn } from 'child_process';
3
+ import os from 'node:os';
3
4
  import path from 'node:path';
4
5
  // ── Intentionally uses process.env directly, NOT Config ───────────
5
6
  // This script runs BEFORE any module is loaded — Config's startup
@@ -67,13 +68,76 @@ const diagHits = [];
67
68
  // Per-test watchdog: a test that neither exits nor errors would otherwise
68
69
  // stall the whole sequential run. Override with DEXBOT_TEST_TIMEOUT_MS.
69
70
  const TEST_TIMEOUT_MS = Number(process.env.DEXBOT_TEST_TIMEOUT_MS || 240000);
71
+ // ── ESM-mock preload ──────────────────────────────────────────────
72
+ // Tests that call esmMockEntry() re-exec themselves with --import loader hooks
73
+ // when the hooks are not yet active. The runner can install those hooks up
74
+ // front, letting the test run in the process it was already spawned into and
75
+ // skipping one full node startup + module-graph load per file. Stage-based
76
+ // tests with multiple stages are excluded: their stages need per-stage worker
77
+ // isolation and the preload would defeat it. Single-stage runEsmMockStages()
78
+ // files are eligible, though: with the hooks already active the helper's
79
+ // in-process branch runs its one stage directly instead of spawning a worker.
80
+ const ESM_HOOKS_FILE = path.join(process.cwd(), 'dist', 'tests', 'helpers', 'esm_mock_hooks.mjs');
81
+ const ESM_ENV_ACTIVE = 'DEXBOT_ESM_MOCKS_ACTIVE';
82
+ const ESM_ENV_MANIFEST = 'DEXBOT_ESM_MOCK_MANIFEST';
83
+ const esmPreloadCache = new Map();
84
+ // Matches runEsmMockStages(['only-stage'], ...) — a single string literal in the
85
+ // stage array. Multi-stage calls (comma-separated literals,
86
+ // Object.keys(STAGES), a stage-list variable, or runEsmMockStagesGrouped/Shared)
87
+ // do not match, so only unambiguously single-stage files opt in.
88
+ const SINGLE_STAGE_CALL_RE = /runEsmMockStages\(\s*\[\s*(['"])[^'"]+\1\s*\]\s*,/g;
89
+ const STAGE_CALL_RE = /runEsmMockStages\(/g;
90
+ function isSingleStageTest(src) {
91
+ if (!src.includes('runEsmMockStages('))
92
+ return false;
93
+ const calls = src.match(STAGE_CALL_RE) || [];
94
+ const single = src.match(SINGLE_STAGE_CALL_RE) || [];
95
+ return calls.length > 0 && single.length === calls.length;
96
+ }
97
+ function needsEsmPreload(testFile) {
98
+ const cached = esmPreloadCache.get(testFile);
99
+ if (cached !== undefined)
100
+ return cached;
101
+ let needed = false;
102
+ try {
103
+ const src = readFileSync(testFile, 'utf8');
104
+ needed = (src.includes('esmMockEntry(') && !src.includes('runEsmMockStages'))
105
+ || isSingleStageTest(src);
106
+ }
107
+ catch {
108
+ needed = false;
109
+ }
110
+ esmPreloadCache.set(testFile, needed);
111
+ return needed;
112
+ }
70
113
  function runOne(testFile) {
71
114
  return new Promise((resolve) => {
72
115
  const start = performance.now();
73
- const child = spawn(process.execPath, [testFile], {
116
+ const preload = needsEsmPreload(testFile);
117
+ let manifestPath = null;
118
+ let childArgs = [testFile];
119
+ let childEnv = process.env;
120
+ if (preload) {
121
+ const manifestDir = path.join(logDir, 'esm-mock-manifests');
122
+ mkdirSync(manifestDir, { recursive: true });
123
+ const stamp = path.basename(testFile).replace(/\W+/g, '_');
124
+ manifestPath = path.join(manifestDir, `${stamp}-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`);
125
+ childArgs = ['--import', ESM_HOOKS_FILE, testFile];
126
+ childEnv = { ...process.env, [ESM_ENV_ACTIVE]: '1', [ESM_ENV_MANIFEST]: manifestPath };
127
+ }
128
+ const cleanupManifest = () => {
129
+ if (!manifestPath)
130
+ return;
131
+ try {
132
+ rmSync(manifestPath, { force: true });
133
+ }
134
+ catch { /* best effort */ }
135
+ manifestPath = null;
136
+ };
137
+ const child = spawn(process.execPath, childArgs, {
74
138
  stdio: ['inherit', 'pipe', 'pipe'],
75
139
  cwd: process.cwd(),
76
- env: process.env,
140
+ env: childEnv,
77
141
  });
78
142
  let timedOut = false;
79
143
  const killTimer = setTimeout(() => {
@@ -99,6 +163,7 @@ function runOne(testFile) {
99
163
  child.stderr.on('data', accumulate);
100
164
  child.on('close', (code, signal) => {
101
165
  clearTimeout(killTimer);
166
+ cleanupManifest();
102
167
  // Slice the buffered output into lines and scan for diagnostics.
103
168
  const seenForTest = new Set();
104
169
  for (const line of buffer.split(/\r?\n/)) {
@@ -126,6 +191,7 @@ function runOne(testFile) {
126
191
  });
127
192
  child.on('error', (err) => {
128
193
  clearTimeout(killTimer);
194
+ cleanupManifest();
129
195
  resolve({
130
196
  test: testFile,
131
197
  elapsedMs: performance.now() - start,
@@ -145,7 +211,17 @@ async function main() {
145
211
  let startTotal = performance.now();
146
212
  const concurrency = (() => {
147
213
  const raw = Number(process.env.DEXBOT_TEST_CONCURRENCY);
148
- return Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : 1;
214
+ if (Number.isFinite(raw) && raw >= 1)
215
+ return Math.floor(raw);
216
+ // Default to a small parallel fan-out. With one node process per test,
217
+ // sequential runs spend most of their wall time in per-process startup
218
+ // and module-graph evaluation. Files are isolated (per-PID tests/tmp),
219
+ // so bounded parallelism is safe. Set DEXBOT_TEST_CONCURRENCY=1 to force
220
+ // the old sequential behavior.
221
+ const cores = typeof os.availableParallelism === 'function'
222
+ ? os.availableParallelism()
223
+ : os.cpus().length;
224
+ return Math.max(1, Math.min(cores, 4));
149
225
  })();
150
226
  const toRun = [];
151
227
  for (const testFile of testFiles) {
package/dist/unlock.d.ts CHANGED
@@ -18,9 +18,10 @@ declare function runStartOnboardingIfNeeded({ allowInteractive, nonInteractiveFl
18
18
  allowInteractive?: boolean;
19
19
  nonInteractiveFlag?: string;
20
20
  }): Promise<boolean>;
21
- declare function main({ argv, startupGraceMs, exitAfterOnboarding, onboard }?: {
21
+ declare function main({ argv, startupGraceMs, isolatedPollIntervalMs, exitAfterOnboarding, onboard }?: {
22
22
  argv?: string[];
23
23
  startupGraceMs?: number;
24
+ isolatedPollIntervalMs?: number;
24
25
  exitAfterOnboarding?: boolean;
25
26
  onboard?: boolean;
26
27
  }): Promise<void>;
package/dist/unlock.js CHANGED
@@ -324,7 +324,7 @@ async function launchDetachedSupervisor({ botName = null, credentialDaemonPid =
324
324
  catch (_) { }
325
325
  }
326
326
  }
327
- async function runIsolated({ botName, botEntry = null, stayResident = false, startupGraceMs = DEFAULT_STARTUP_GRACE_MS } = {}) {
327
+ async function runIsolated({ botName, botEntry = null, stayResident = false, startupGraceMs = DEFAULT_STARTUP_GRACE_MS, isolatedPollIntervalMs = 1000 } = {}) {
328
328
  let supervisor;
329
329
  if (botName) {
330
330
  const bot = botEntry || resolveBotEntryForName(botName);
@@ -383,7 +383,7 @@ async function runIsolated({ botName, botEntry = null, stayResident = false, sta
383
383
  cleanupSignalHandlers();
384
384
  reject(err);
385
385
  }
386
- }, 1000);
386
+ }, isolatedPollIntervalMs);
387
387
  });
388
388
  }
389
389
  // ── Main entry point ───────────────────────────────────────────────
@@ -440,7 +440,7 @@ async function runStartOnboardingIfNeeded({ allowInteractive = true, nonInteract
440
440
  }
441
441
  return true;
442
442
  }
443
- async function main({ argv = process.argv, startupGraceMs = DEFAULT_STARTUP_GRACE_MS, exitAfterOnboarding = false, onboard = false } = {}) {
443
+ async function main({ argv = process.argv, startupGraceMs = DEFAULT_STARTUP_GRACE_MS, isolatedPollIntervalMs = 1000, exitAfterOnboarding = false, onboard = false } = {}) {
444
444
  if (typeof chainKeys.checkKeysFileSecurity === 'function')
445
445
  chainKeys.checkKeysFileSecurity();
446
446
  if (typeof credentialPolicy.checkPolicyFileSecurity === 'function')
@@ -634,6 +634,7 @@ async function main({ argv = process.argv, startupGraceMs = DEFAULT_STARTUP_GRAC
634
634
  botEntry: selectedBot,
635
635
  stayResident: isDetachedSupervisorChild,
636
636
  startupGraceMs,
637
+ isolatedPollIntervalMs,
637
638
  });
638
639
  return;
639
640
  }
@@ -81,6 +81,12 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
81
81
  - 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".
82
82
  - 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. The guard re-arms on the first real fill of the new generation.
83
83
 
84
+ - `INV-COW-010` Grid-layer spread-correction cycle is atomic and bounded
85
+ - `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.
86
+ - Before broadcasting, `resolveOccupiedCorrection` re-derives a plan whose CREATE destination became a live order since planning (`getOccupiedCorrectionSlots`), or withholds it — a known-taken slot is never shipped. The COW build layer stays authoritative against a detector false positive.
87
+ - 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.
88
+ - 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.
89
+
84
90
  - `INV-PROJ-001` New projected orders remain virtual
85
91
  - Orders projected into empty slots must be `VIRTUAL` with no `orderId` until chain confirmation.
86
92
 
@@ -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.6.14).
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.6.15).
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.6.14 |
39
+ | **Release Track** | 1.0.0 | v1.6.15 |
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.6.14 |
779
+ | **Release Track** | 1.0.0 | v1.6.15 |
780
780
  | **Active Since** | ~2018 | December 2025 |
781
- | **Last Commit** | May 23, 2020 | 2026-10-10 |
782
- | **Total Commits** | 2281 | 2,390 (current HEAD, v1.6.14 line) |
781
+ | **Last Commit** | May 23, 2020 | 2026-10-16 |
782
+ | **Total Commits** | 2281 | 2,411 (current HEAD, v1.6.15 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 | 324 `test_*.ts` files (307 `tests/` + 17 `claw/tests/`, auto-discovered via `globSync`) |
785
+ | **Test Files** | 16 Python test files | 327 `test_*.ts` files (310 `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) |