dexbot 1.4.25 → 1.5.1

package/analysis/bot_usage/discover_bot_accounts.ts

@@ -18,12 +18,16 @@ const { writeJSON } = getStorage();
  *        Q1 — top 100 accounts by limit_order_create count
  *        Q2 — top 100 accounts by limit_order_cancel count
  *        Q3 — top 100 accounts by fill_order count
+ *        Q4 — top 200 accounts by limit_order_update count (op 77, DEXBot2 fingerprint)
  *   2. Merge & pre-filter:
  *        creates ≥ MIN_CREATES  (grid analysis determines DEXBot candidacy)
  *   3. Grid analysis (parallel, batches of 5):
  *        Fetch 200 raw orders per candidate → per-session geometric spacing test
  *   4. BitShares: resolve account IDs → names (batch db.get_objects call)
- *   5. Rank by DEX score and print table
+ *   5. Rank by DEX score and print table.
+ *        HIGH tier (80+) is split by op-77 usage:
+ *          updates ≥ 1 → DEXBot2 (native limit_order_update in-place re-price)
+ *          updates = 0 → DEXBot1-style (cancel-only, cancel + recreate)
  *
  * Usage:
  *   node dist/analysis/bot_usage/discover_bot_accounts.js
@@ -51,6 +55,7 @@ import {
     buildTopSellerAccountsQuery,
     buildTopCancellerAccountsQuery,
     buildTopFilledAccountsQuery,
+    buildTopUpdaterAccountsQuery,
     DEFAULT_CONFIG,
 } from './kibana_bot_queries.js';
 import { NODE_MANAGEMENT } from '../../modules/constants.js';
@@ -61,6 +66,7 @@ interface AccountCounts {
     creates: number;
     cancels: number;
     fills: number;
+    updates: number;
 }
 
 interface CandidateInfo {
@@ -68,6 +74,8 @@ interface CandidateInfo {
     creates: number;
     cancels: number;
     fills: number;
+    updates: number;
+    flavor: 'DEXBot2' | 'DEXBot1' | '';
     cancelRatio: number;
     fillRate: number;
     gridScore: number;
@@ -323,18 +331,21 @@ async function run() {
 
     console.log('Phase 1: Querying Kibana for top active accounts...');
 
-    const [createRes, cancelRes, fillRes]: any[] = await Promise.all([
+    const [createRes, cancelRes, fillRes, updateRes]: any[] = await Promise.all([
         withRetry(() => kibanaSearch(KIBANA_CFG, buildTopSellerAccountsQuery(lookbackH, 200, opts.minCreates)),
             'top-seller query'),
         withRetry(() => kibanaSearch(KIBANA_CFG, buildTopCancellerAccountsQuery(lookbackH, 200, 5)),
             'top-canceller query'),
         withRetry(() => kibanaSearch(KIBANA_CFG, buildTopFilledAccountsQuery(lookbackH, 200, 3)),
             'top-fills query'),
+        withRetry(() => kibanaSearch(KIBANA_CFG, buildTopUpdaterAccountsQuery(lookbackH, 200, 1)),
+            'top-updater query'),
     ]);
 
     const createBuckets = createRes?.aggregations?.by_account?.buckets ?? [];
     const cancelBuckets = cancelRes?.aggregations?.by_account?.buckets ?? [];
     const fillBuckets   = fillRes?.aggregations?.by_account?.buckets   ?? [];
+    const updateBuckets = updateRes?.aggregations?.by_account?.buckets ?? [];
 
     if (opts.verbose) {
         console.log(`  [verbose] createRes keys: ${Object.keys(createRes ?? {}).join(', ')}`);
@@ -344,6 +355,7 @@ async function run() {
     console.log(`  Creates: ${createBuckets.length} accounts with ≥${opts.minCreates} creates`);
     console.log(`  Cancels: ${cancelBuckets.length} accounts with ≥5 cancels`);
     console.log(`  Fills:   ${fillBuckets.length} accounts with ≥3 fills`);
+    console.log(`  Updates: ${updateBuckets.length} accounts with ≥1 limit_order_update (op 77)`);
 
     if (createBuckets.length === 0) {
         console.log('');
@@ -360,17 +372,23 @@ async function run() {
     console.log('\nPhase 2: Merging and filtering candidates...');
 
     const accounts: Record<string, AccountCounts> = {};
-    for (const b of createBuckets) accounts[b.key] = { creates: b.doc_count, cancels: 0, fills: 0 };
+    for (const b of createBuckets) accounts[b.key] = { creates: b.doc_count, cancels: 0, fills: 0, updates: 0 };
     for (const b of cancelBuckets) {
-        if (!accounts[b.key]) accounts[b.key] = { creates: 0, cancels: 0, fills: 0 };
+        if (!accounts[b.key]) accounts[b.key] = { creates: 0, cancels: 0, fills: 0, updates: 0 };
         accounts[b.key].cancels = b.doc_count;
     }
     for (const b of fillBuckets) {
-        if (!accounts[b.key]) accounts[b.key] = { creates: 0, cancels: 0, fills: 0 };
+        if (!accounts[b.key]) accounts[b.key] = { creates: 0, cancels: 0, fills: 0, updates: 0 };
         accounts[b.key].fills = b.doc_count;
     }
+    for (const b of updateBuckets) {
+        if (!accounts[b.key]) accounts[b.key] = { creates: 0, cancels: 0, fills: 0, updates: 0 };
+        accounts[b.key].updates = b.doc_count;
+    }
 
     // Pre-filter: must have creates ≥ minCreates (grid analysis determines DEXBot candidacy)
+    // Flavor: any limit_order_update (op 77) in-window → DEXBot2 (native in-place
+    // re-price); zero updates → DEXBot1-style (cancel-only: cancel + recreate).
     const candidates: CandidateInfo[] = (Object.entries(accounts) as [string, AccountCounts][])
         .filter(([, s]) => s.creates >= opts.minCreates)
         .map(([id, s]) => ({
@@ -378,6 +396,8 @@ async function run() {
             creates: s.creates,
             cancels: s.cancels,
             fills:   s.fills,
+            updates: s.updates,
+            flavor: (s.updates >= 1 ? 'DEXBot2' : 'DEXBot1') as 'DEXBot2' | 'DEXBot1',
             cancelRatio: s.cancels / Math.max(s.creates, 1),
             fillRate:    s.creates > 0 ? (s.fills / s.creates * 100) : 0,
         } as CandidateInfo))
@@ -492,9 +512,41 @@ async function run() {
     console.log('════════════════════════════════════════════════════════════════════════════════════');
     console.log('');
 
-    // Print by DEX score tier
+    // Print by DEX score tier. HIGH tier (80+) splits by update-order usage:
+    //   DEXBot2      — broadcast limit_order_update (op 77) in-window (in-place re-price)
+    //   DEXBot1-style — cancel-only, no op 77 (cancel + recreate)
+    const highV2 = results.filter(r => r.dexScore >= 80 && r.updates >= 1);
+    const highV1 = results.filter(r => r.dexScore >= 80 && r.updates < 1);
+
+    const hdrHigh = ' #   Name                  ID              Creates  Fills  Cancel  Fill%  C/C   MaxBatch  Incr%  Grid  DEX  Updates';
+    function printHighGroup(label: string, rows: CandidateInfo[]) {
+        if (!rows.length) return;
+        console.log(` ── ${label}`);
+        console.log('');
+        console.log(hdrHigh);
+        console.log(' ' + '─'.repeat(hdrHigh.length - 1));
+        for (const r of rows) {
+            const rank    = String(results.indexOf(r) + 1).padStart(2);
+            const name    = r.name.padEnd(22).slice(0, 22);
+            const id      = r.id.padEnd(14);
+            const creates = String(r.creates).padStart(7);
+            const fills   = String(r.fills).padStart(6);
+            const cancels = String(r.cancels).padStart(7);
+            const fr      = (r.fillRate.toFixed(1) + '%').padStart(5);
+            const cr      = r.cancelRatio.toFixed(2).padStart(4);
+            const batch   = String(r.maxBatch || '-').padStart(9);
+            const inc     = (r.impliedInc != null ? r.impliedInc.toFixed(2) + '%' : 'n/a').padStart(6);
+            const grid    = String(r.gridScore).padStart(5);
+            const dex     = String(r.dexScore).padStart(4);
+            const upd     = String(r.updates).padStart(7);
+            console.log(` ${rank}  ${name}  ${id}  ${creates}  ${fills}  ${cancels}  ${fr}  ${cr}  ${batch}  ${inc}  ${grid}  ${dex}  ${upd}`);
+        }
+        console.log('');
+    }
+    printHighGroup('HIGH confidence — DEXBot2 (80+, uses limit_order_update op 77)', highV2);
+    printHighGroup('HIGH confidence — DEXBot1-style (80+, cancel-only, no op 77)', highV1);
+
     const tiers = [
-        { label: 'HIGH confidence (80+) — almost certainly DEXBot/DEXBot2', min: 80, max: 101 },
         { label: 'MEDIUM confidence (50–79) — likely a grid bot',           min: 50, max:  80 },
         { label: 'LOW confidence (25–49) — some automation detected',       min: 25, max:  50 },
         { label: 'WEAK signal (<25) — create/cancel pattern, no grid',     min:  0, max:  25 },
@@ -531,13 +583,13 @@ async function run() {
 
     // ── Summary ───────────────────────────────────────────────────────────────
 
-    const high   = results.filter(r => r.dexScore >= 80).length;
+    const high   = highV2.length + highV1.length;
     const medium = results.filter(r => r.dexScore >= 50 && r.dexScore < 80).length;
     const low    = results.filter(r => r.dexScore >= 25 && r.dexScore < 50).length;
 
     console.log('════════════════════════════════════════════════════════════════════════════════════');
     console.log(` Total candidates scanned:  ${results.length}`);
-    console.log(` HIGH (80+):   ${high}  accounts — almost certainly DEXBot/DEXBot2`);
+    console.log(` HIGH (80+):   ${high}  accounts — DEXBot2: ${highV2.length} (op 77 updates) / DEXBot1-style: ${highV1.length} (cancel-only)`);
     console.log(` MEDIUM (50+): ${medium}  accounts — likely grid bots`);
     console.log(` LOW (25+):    ${low}  accounts — weak signal`);
     console.log('');
@@ -545,6 +597,7 @@ async function run() {
     console.log('   C/C = cancel/create ratio  (grid bots: ~1.0)');
     console.log('   Incr% = implied grid increment from price spacing');
     console.log('   Grid = grid quality 0-100  |  DEX = DEXBot confidence 0-100');
+    console.log('   Updates = limit_order_update (op 77) count — DEXBot2 only; 0 = cancel-only (DEXBot1-style)');
     console.log('');
 
     // ── Export JSON ────────────────────────────────────────────────────────────
@@ -553,9 +606,11 @@ async function run() {
         const exportData = results.map(r => ({
             id:          r.id,
             name:        r.name,
+            flavor:      r.flavor,
             creates:     r.creates,
             fills:       r.fills,
             cancels:     r.cancels,
+            updates:     r.updates,
             fillPct:     r.fillRate,
             cancelRatio: r.cancelRatio,
             maxBatch:    r.maxBatch,

package/analysis/bot_usage/kibana_bot_queries.ts

@@ -32,6 +32,10 @@
  *   limit_order_cancel:
  *     op_object.fee_paying_account        — account that cancelled
  *     op_object.order                     — the order ID cancelled
+ *
+ *   limit_order_update (op 77, DEXBot2-only — native in-place re-price):
+ *     op_object.seller                    — account that updated the order
+ *     op_object.order                     — the limit order ID updated
  */
 
 
@@ -42,6 +46,11 @@ import { kibanaSearch, DEFAULT_CONFIG as BASE_CONFIG } from '../../market_adapte
 const OP_LIMIT_ORDER_CREATE = 1;
 const OP_LIMIT_ORDER_CANCEL = 2;
 const OP_FILL_ORDER         = 4;
+// Native in-place order re-price. Only DEXBot2 broadcasts this (COW UPDATE
+// actions via buildUpdateOrderOp); DEXBot1 (Python staggered_orders) predates
+// it and can only cancel + recreate. Presence of op 77 on an account is the
+// DEXBot2 fingerprint; absence means cancel-only (DEXBot1-style).
+const OP_LIMIT_ORDER_UPDATE = 77;
 
 const DEFAULT_CONFIG = {
     ...BASE_CONFIG,
@@ -166,7 +175,37 @@ function buildTopFilledAccountsQuery(lookbackHours: number, topN: number = 100,
     };
 }
 
+/**
+ * Top N accounts by limit_order_update count (seller field, op 77).
+ * DEXBot2 fingerprint: only DEXBot2 broadcasts native in-place re-prices
+ * (COW UPDATE actions). DEXBot1-style bots never emit op 77 — they cancel
+ * (op 2) and recreate (op 1) instead.
+ */
+function buildTopUpdaterAccountsQuery(lookbackHours: number, topN: number = 200, minUpdates: number = 1) {
+    return {
+        size: 0,
+        query: {
+            bool: {
+                filter: [
+                    { term:  { operation_type: OP_LIMIT_ORDER_UPDATE } },
+                    { range: { 'block_data.block_time': { gte: `now-${lookbackHours}h`, lte: 'now' } } },
+                ],
+            },
+        },
+        aggs: {
+            by_account: {
+                terms: {
+                    field:         'operation_history.op_object.seller.keyword',
+                    size:          topN,
+                    min_doc_count: minUpdates,
+                    order:         { _count: 'desc' },
+                },
+            },
+        },
+    };
+}
+
 // ─── Exports ──────────────────────────────────────────────────────────────────
 
-export { DEFAULT_CONFIG, kibanaSearch, buildOrderPriceQuery, buildTopSellerAccountsQuery, buildTopCancellerAccountsQuery, buildTopFilledAccountsQuery }
+export { DEFAULT_CONFIG, kibanaSearch, buildOrderPriceQuery, buildTopSellerAccountsQuery, buildTopCancellerAccountsQuery, buildTopFilledAccountsQuery, buildTopUpdaterAccountsQuery, OP_LIMIT_ORDER_UPDATE }
 

package/analysis/chart_utils.ts

@@ -54,8 +54,11 @@ function toEpochSeconds(ts: any, fallbackIdx: any) {
     return fallbackIdx * 3600;
 }
 
-function writeChartFile(filePath: any, html: any) {
-    const chartDir = path.dirname(filePath);
+function toFileUrl(filePath: any): string {
+    return `file://${path.resolve(String(filePath))}`;
+}
+
+function writeChartFile(filePath: any, html: any) {    const chartDir = path.dirname(filePath);
     if (!fs.existsSync(chartDir)) ensureDir(chartDir);
     ensureSiblingUplotAssets(chartDir);
     // Atomic write (tmp + rename, matching the production storage adapter
@@ -190,5 +193,5 @@ function bindPan(chart) {
 }
 `;
 
-export { escapeHtml, serializeJsonForScript, toEpochSeconds, writeChartFile, embedFunctionSources, UPLOT_SHARED_SCRIPT }
+export { escapeHtml, serializeJsonForScript, toEpochSeconds, writeChartFile, toFileUrl, embedFunctionSources, UPLOT_SHARED_SCRIPT }
 

package/analysis/grid_correction_check.ts

@@ -37,7 +37,7 @@ import fs from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import * as KC from '../market_adapter/core/kibana_client.js';
 import * as C from '../modules/constants.js';
-import { loadBotMeta, loadBotSettings, computeBotKey } from './bot_key_utils.js';
+import { loadBotMeta, loadBotSettings, computeBotKey, persistBotAccountId } from './bot_key_utils.js';
 
 const { kibanaSearch, DEFAULT_CONFIG: BASE_CONFIG } = KC;
 
@@ -221,8 +221,11 @@ Time range (one of):
 
 Options:
   --account <id>         Override account ID (default: from bot preferredAccount)
-  --lookup               Resolve account name to ID via BitShares node
-  --node <url>           BitShares node URL for --lookup / precision resolution
+  --lookup               Legacy: account names always resolve via BitShares node
+  --refresh-account      Force re-resolution of preferredAccount and update the
+                         stored accountId when it changed (default: reuse the
+                         stored accountId with no chain lookup)
+  --node <url>           BitShares node URL for account / precision resolution
   --increment <pct>      Grid increment percent (default: from bot config or ${Number((C as any)?.DEFAULT_CONFIG?.incrementPercent ?? 0.5)})
   --tolerance <pct>      Deprecated alias for --increment (kept for compat, prefer --increment)
   --per-fill             Check at fill granularity (default: per-order aggregated)
@@ -262,6 +265,7 @@ function parseArgs() {
         end: null,
         account: null,
         lookup: false,
+        refreshAccount: false,
         node: C.NODE_MANAGEMENT.DEFAULT_NODES[0],
         perFill: false,
         includeCrossPair: false,
@@ -279,6 +283,7 @@ function parseArgs() {
             case '--end': opts.end = args[++i]; break;
             case '--account': opts.account = args[++i]; break;
             case '--lookup': opts.lookup = true; break;
+            case '--refresh-account': opts.refreshAccount = true; break;
             case '--node': opts.node = args[++i]; break;
             case '--per-fill': opts.perFill = true; break;
             case '--include-cross-pair': opts.includeCrossPair = true; break;
@@ -356,32 +361,63 @@ async function resolveAccountId(name: string, nodeUrl: string): Promise<string |
     }
 }
 
-async function resolveAccountForBot(botKey: string, overrideAccount: string | null, nodeUrl: string, doLookup: boolean): Promise<{ accountId: string; botMeta: any }> {
+async function resolveAccountForBot(botKey: string, overrideAccount: string | null, nodeUrl: string, doRefresh: boolean): Promise<{ accountId: string; botMeta: any }> {
     const botMeta = loadBotMeta(botKey);
     if (!botMeta && !overrideAccount) {
         console.error(`Error: bot key '${botKey}' not found in profiles/bots.json and no --account provided.`);
         console.error(`Use --list-bots to see available keys, or pass --account <1.2.x> explicitly.`);
         process.exit(1);
     }
-    let accountId = overrideAccount ?? botMeta?.preferredAccount ?? null;
-    if (!accountId) {
+    // An explicit --account always wins and is never persisted.
+    if (overrideAccount) {
+        if (/^1\.2\.\d+$/.test(String(overrideAccount))) {
+            return { accountId: String(overrideAccount), botMeta };
+        }
+        console.log(`  Resolving account name '${overrideAccount}'...`);
+        const resolvedOverride = await resolveAccountId(String(overrideAccount), nodeUrl);
+        if (!resolvedOverride) {
+            console.error(`Error: failed to resolve --account '${overrideAccount}' to 1.2.x`);
+            process.exit(1);
+        }
+        console.log(`  → ${resolvedOverride}`);
+        return { accountId: String(resolvedOverride), botMeta };
+    }
+    const prefRaw = botMeta?.preferredAccount != null ? String(botMeta.preferredAccount) : null;
+    const prefIsId = !!prefRaw && /^1\.2\.\d+$/.test(prefRaw);
+    const storedId = /^1\.2\.\d+$/.test(String(botMeta?.accountId ?? '')) ? String(botMeta.accountId) : null;
+    // An explicit 1.2.x preferredAccount is authoritative: the stored accountId
+    // is a derived cache and must never override it. Self-heal the cache.
+    if (prefIsId) {
+        if (storedId && storedId !== prefRaw && persistBotAccountId(botKey, prefRaw as string)) {
+            console.log(`  Updated stale stored accountId ${storedId} → ${prefRaw} from preferredAccount`);
+        }
+        return { accountId: prefRaw as string, botMeta };
+    }
+    if (!prefRaw) {
         console.error(`Error: bot '${botKey}' has no preferredAccount and no --account provided.`);
         process.exit(1);
     }
-    // If account looks like a name, resolve it
-    if (!/^1\.2\.\d+$/.test(String(accountId))) {
-        if (doLookup || !String(accountId).startsWith('1.2.')) {
-            console.log(`  Resolving account name '${accountId}'...`);
-            const resolved = await resolveAccountId(String(accountId), nodeUrl);
-            if (!resolved) {
-                console.error(`Error: failed to resolve account name '${accountId}' to 1.2.x`);
-                process.exit(1);
-            }
-            console.log(`  → ${resolved}`);
-            accountId = resolved;
-        }
+    // Name + fresh-enough cache + no refresh requested: offline-friendly fast path.
+    if (storedId && !doRefresh) {
+        console.log(`  Using stored accountId ${storedId} from profiles/bots.json (no lookup needed; pass --refresh-account to re-verify)`);
+        return { accountId: storedId, botMeta };
+    }
+    // No cache, or --refresh-account: resolve the name on-chain.
+    console.log(`  Resolving account name '${prefRaw}'...`);
+    const resolved = await resolveAccountId(prefRaw, nodeUrl);
+    if (!resolved) {
+        console.error(`Error: failed to resolve account name '${prefRaw}' to 1.2.x`);
+        process.exit(1);
+    }
+    console.log(`  → ${resolved}`);
+    if (!storedId && persistBotAccountId(botKey, resolved)) {
+        console.log(`  Stored accountId ${resolved} in profiles/bots.json for '${botKey}'`);
+    } else if (storedId && storedId !== resolved && persistBotAccountId(botKey, resolved)) {
+        console.log(`  Updated stored accountId ${storedId} → ${resolved} in profiles/bots.json for '${botKey}'`);
+    } else if (storedId === resolved) {
+        console.log(`  Stored accountId ${resolved} confirmed up to date`);
     }
-    return { accountId: String(accountId), botMeta };
+    return { accountId: String(resolved), botMeta };
 }
 
 // ─── Asset precision resolution ───────────────────────────────────────────────
@@ -829,7 +865,7 @@ async function main() {
     console.log(`\nGrid correction check — bot-key: ${opts.botKey}`);
     console.log(`Range: ${label}`);
 
-    const { accountId, botMeta } = await resolveAccountForBot(opts.botKey, opts.account, opts.node, opts.lookup);
+    const { accountId, botMeta } = await resolveAccountForBot(opts.botKey, opts.account, opts.node, opts.refreshAccount);
     console.log(`Account: ${accountId}${botMeta ? `  (${botMeta.assetA}/${botMeta.assetB})` : ''}`);
     const incrementPercent = resolveIncrementPercent(botMeta, opts.incrementPercent);
     console.log(`Increment: ${incrementPercent}% (halfInc ${incrementPercent/2}%)${opts.incrementPercent == null && botMeta?.incrementPercent != null ? ' — from bot config' : opts.incrementPercent != null ? ' — from --increment' : ' — default'}`);

package/analysis/resolve_bot_accounts.ts

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * BOT ACCOUNT-ID BACKFILL
+ *
+ * Resolves every bot's preferredAccount name to its chain account ID and
+ * stamps `accountId` next to `preferredAccount` in profiles/bots.json, so
+ * analysis tools and scripts can skip the chain lookup on later runs.
+ * Nothing is ever written by hand — all IDs in the file come from this
+ * script, the bot editor, or the analysis tools themselves.
+ *
+ * Usage:
+ *   node dist/analysis/resolve_bot_accounts.js [--bot-key <key>] [--refresh]
+ *       [--timeout-ms <n>] [--dry-run] [--json]
+ *
+ * Exit code 0 = all bot accounts resolved (or nothing to do),
+ *           1 = one or more resolutions failed.
+ *
+ * Short-lived batch tool: suppresses chain INFO logging and disconnects the
+ * shared client on exit. Run standalone only — never import/call from a
+ * long-running process holding a live connection.
+ */
+
+import { loadBotSettings, computeBotKey, persistBotAccountId } from './bot_key_utils.js';
+import { setGlobalConsoleLevel, getGlobalConsoleLevel } from '../modules/order/logger.js';
+import { sleep } from '../modules/order/utils/system.js';
+import { getErrorMessage } from '../modules/utils/errors.js';
+
+const DEFAULT_TIMEOUT_MS = 20000;
+
+function printHelp() {
+    console.log(`\
+Usage: node dist/analysis/resolve_bot_accounts.js [options]
+
+Resolve bot preferredAccount names to chain IDs and store them as accountId
+in profiles/bots.json (byte-preserving; comments and formatting survive).
+
+Options:
+  --bot-key <key>    Only process this bot key or bot name (default: all bots)
+  --refresh          Re-resolve even when a stored accountId exists
+  --timeout-ms <n>   Per-account chain lookup timeout (default: ${DEFAULT_TIMEOUT_MS})
+  --dry-run          Report what would change without writing anything
+  --json             Append a machine-readable summary
+  --help, -h         Show this help
+`);
+}
+
+function parseArgs() {
+    const args = process.argv.slice(2);
+    if (args.includes('--help') || args.includes('-h')) { printHelp(); process.exit(0); }
+    const opts: any = {
+        botKey: null,
+        refresh: false,
+        timeoutMs: DEFAULT_TIMEOUT_MS,
+        dryRun: false,
+        json: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        switch (args[i]) {
+            case '--bot-key': opts.botKey = args[++i]; break;
+            case '--refresh': opts.refresh = true; break;
+            case '--timeout-ms': opts.timeoutMs = parseInt(args[++i], 10); break;
+            case '--dry-run': opts.dryRun = true; break;
+            case '--json': opts.json = true; break;
+            default:
+                console.error(`Unknown option: ${args[i]}`);
+                process.exit(1);
+        }
+    }
+    if (!Number.isFinite(opts.timeoutMs) || opts.timeoutMs <= 0) {
+        console.error('Error: --timeout-ms must be a positive number.');
+        process.exit(1);
+    }
+    return opts;
+}
+
+async function resolveWithTimeout(chainOrders: any, ref: string, timeoutMs: number): Promise<{ id: string | null; reason: string }> {
+    const timeoutErr: any = new Error(`lookup timed out after ${timeoutMs}ms`);
+    timeoutErr.code = 'ACCOUNT_LOOKUP_TIMEOUT';
+    try {
+        const id = await Promise.race([
+            chainOrders.resolveAccountId(ref),
+            sleep(timeoutMs).then(() => { throw timeoutErr; }),
+        ]);
+        if (id && /^1\.2\.\d+$/.test(String(id))) return { id: String(id), reason: 'resolved' };
+        return { id: null, reason: 'not-found' };
+    } catch (err: any) {
+        return { id: null, reason: err && err.code === 'ACCOUNT_LOOKUP_TIMEOUT' ? 'timeout' : 'error' };
+    }
+}
+
+async function main() {
+    const opts = parseArgs();
+    const settings = loadBotSettings();
+    const entries = Array.isArray(settings?.bots) ? settings.bots : [];
+    if (!entries.length) {
+        console.log('No bots in profiles/bots.json — nothing to do.');
+        process.exit(0);
+    }
+
+    let targets = entries.map((bot: any, index: number) => ({ bot, index, key: computeBotKey(bot, index) }));
+    if (opts.botKey) {
+        const want = String(opts.botKey).toLowerCase();
+        targets = targets.filter((t: any) => t.key === want || String(t.bot?.name ?? '').toLowerCase() === want);
+        if (!targets.length) {
+            console.error(`Error: bot '${opts.botKey}' not found in profiles/bots.json.`);
+            process.exit(1);
+        }
+    }
+
+    // Suppress chain INFO spam for the whole batch; restored in finally.
+    // (setSuppressConnectionLog is read lazily so this file never drags the
+    // chain stack in when it cannot be loaded.)
+    let chainClient: any = null;
+    let prevSuppress = false;
+    let prevGlobalLevel: string | null = null;
+    let suppressionArmed = false;
+    let chainOrders: any = null;
+    try {
+        chainClient = await import('../modules/bitshares_client.js');
+        prevSuppress = chainClient.isSuppressConnectionLog();
+        prevGlobalLevel = getGlobalConsoleLevel();
+        suppressionArmed = true;
+        chainClient.setSuppressConnectionLog(true);
+        setGlobalConsoleLevel('warn');
+        chainOrders = await import('../modules/chain_orders.js');
+    } catch (err: any) {
+        console.error(`Error: could not load the chain stack (${getErrorMessage(err)}).`);
+        process.exit(1);
+    }
+
+    const results: any[] = [];
+    try {
+        for (const t of targets) {
+            const name = t.bot?.name ?? t.key;
+            const prefRaw = t.bot?.preferredAccount != null ? String(t.bot.preferredAccount) : '';
+            const stored = /^1\.2\.\d+$/.test(String(t.bot?.accountId ?? '')) ? String(t.bot.accountId) : null;
+            if (!prefRaw) {
+                results.push({ key: t.key, name, status: 'skipped', detail: 'no preferredAccount' });
+                console.log(`- ${t.key}: skipped (no preferredAccount)`);
+                continue;
+            }
+            if (/^1\.2\.\d+$/.test(prefRaw)) {
+                if (stored !== prefRaw) {
+                    const wrote = opts.dryRun ? true : persistBotAccountId(t.key, prefRaw);
+                    const status = !wrote ? 'failed' : (opts.dryRun ? 'would-update' : 'updated');
+                    results.push({ key: t.key, name, status, detail: wrote ? `preferredAccount is authoritative (${prefRaw})` : 'could not write profiles/bots.json' });
+                    console.log(`- ${t.key}: ${!wrote ? 'FAILED to write' : (opts.dryRun ? 'would update' : 'updated')} stored accountId → ${prefRaw} (preferredAccount is authoritative)`);
+                } else {
+                    results.push({ key: t.key, name, status: 'cached', detail: prefRaw });
+                    console.log(`- ${t.key}: cached (${prefRaw})`);
+                }
+                continue;
+            }
+            if (stored && !opts.refresh) {
+                results.push({ key: t.key, name, status: 'cached', detail: stored });
+                console.log(`- ${t.key}: cached (${stored})`);
+                continue;
+            }
+            const r = await resolveWithTimeout(chainOrders, prefRaw, opts.timeoutMs);
+            if (r.id) {
+                const changed = stored !== r.id;
+                const wrote = !changed || opts.dryRun ? true : persistBotAccountId(t.key, r.id);
+                const status = !wrote ? 'failed' : (opts.dryRun ? (changed ? 'would-update' : 'unchanged') : (changed ? (stored ? 'updated' : 'stored') : 'unchanged'));
+                results.push({ key: t.key, name, status, detail: wrote ? r.id : 'could not write profiles/bots.json' });
+                console.log(`- ${t.key}: '${prefRaw}' → ${r.id}${!wrote ? ' (FAILED to store)' : (changed ? (opts.dryRun ? ' (would store)' : (stored ? ' (updated)' : ' (stored)')) : ' (unchanged)')}`);
+            } else {
+                const why = r.reason === 'timeout' ? `nodes unreachable (timed out after ${opts.timeoutMs}ms)` : 'not found on the blockchain';
+                results.push({ key: t.key, name, status: 'failed', detail: why });
+                console.log(`- ${t.key}: FAILED to resolve '${prefRaw}' (${why})`);
+            }
+        }
+    } finally {
+        if (chainClient) {
+            try { await chainClient.disconnectClient(); } catch (_) { /* best-effort cleanup */ }
+            if (suppressionArmed) {
+                try { chainClient.setSuppressConnectionLog(prevSuppress); } catch (_) { /* restore-only */ }
+            }
+        }
+        if (suppressionArmed) {
+            try { setGlobalConsoleLevel(prevGlobalLevel); } catch (_) { /* restore-only */ }
+        }
+    }
+
+    const failed = results.filter((r: any) => r.status === 'failed');
+    const skipped = results.filter((r: any) => r.status === 'skipped').length;
+    const ok = results.length - failed.length - skipped;
+    console.log(`\nDone: ${ok} resolved, ${skipped} skipped, ${failed.length} failed${opts.dryRun ? ' (dry run, nothing written)' : ''}.`);
+    if (opts.json) {
+        console.log(JSON.stringify({ dryRun: opts.dryRun, results }, null, 2));
+    }
+    process.exit(failed.length ? 1 : 0);
+}
+
+main().catch((err: any) => {
+    console.error('Fatal:', getErrorMessage(err));
+    process.exit(1);
+});