dexbot 1.6.16 → 1.6.17

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 (60) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/analysis/tradingview/README.md +2 -2
  3. package/analysis/trend_detection/DYNAMIC_WEIGHT_RESEARCH.md +1 -1
  4. package/claw/package.json +1 -1
  5. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  6. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  7. package/dist/analysis/ama_fitting/analyze_lambda_vs_slow.js +5 -3
  8. package/dist/analysis/tradingview/grid_reset_sim.js +1 -1
  9. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +4 -4
  10. package/dist/analysis/trend_detection/backtest_ama_slope_huber.js +1 -1
  11. package/dist/modules/account_bots.d.ts +3 -0
  12. package/dist/modules/chain_keys.d.ts +1 -1
  13. package/dist/modules/constants.d.ts +6 -0
  14. package/dist/modules/constants.js +34 -6
  15. package/dist/modules/credit_pricing.d.ts +20 -1
  16. package/dist/modules/credit_pricing.js +23 -1
  17. package/dist/modules/credit_runtime.js +33 -16
  18. package/dist/modules/dexbot_class.d.ts +3 -1
  19. package/dist/modules/dexbot_class.js +5 -2
  20. package/dist/modules/dexbot_cow_runtime.d.ts +28 -37
  21. package/dist/modules/dexbot_cow_runtime.js +47 -66
  22. package/dist/modules/dexbot_maintenance_runtime.js +68 -10
  23. package/dist/modules/launcher/credential_daemon.d.ts +14 -2
  24. package/dist/modules/launcher/credential_daemon.js +60 -26
  25. package/dist/modules/order/grid.d.ts +7 -0
  26. package/dist/modules/order/grid.js +157 -15
  27. package/dist/modules/order/index.d.ts +15 -0
  28. package/dist/modules/order/manager.d.ts +30 -7
  29. package/dist/modules/order/manager.js +108 -12
  30. package/dist/modules/order/strategy.d.ts +5 -0
  31. package/dist/modules/order/strategy.js +23 -2
  32. package/dist/modules/order/utils/math.d.ts +41 -1
  33. package/dist/modules/order/utils/math.js +47 -1
  34. package/dist/modules/order/utils/order.d.ts +13 -0
  35. package/dist/modules/order/utils/order.js +61 -7
  36. package/dist/modules/order/utils/system.d.ts +66 -0
  37. package/dist/modules/order/utils/system.js +135 -0
  38. package/dist/modules/order/utils/validate.d.ts +3 -1
  39. package/dist/modules/order/utils/validate.js +5 -1
  40. package/dist/modules/types.d.ts +35 -2
  41. package/dist/scripts/analyze-credit.js +64 -23
  42. package/dist/scripts/bts_distribution.d.ts +66 -0
  43. package/dist/scripts/bts_distribution.js +2102 -0
  44. package/dist/scripts/token_distribution.d.ts +45 -0
  45. package/dist/scripts/token_distribution.js +1870 -0
  46. package/dist/unlock.js +42 -24
  47. package/docs/COW_INVARIANTS.md +6 -0
  48. package/docs/DEXBOT_COMPARISON.md +5 -5
  49. package/docs/EVOLUTION.md +9 -8
  50. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +3 -1
  51. package/docs/GRID_PRICE_INVARIANT.md +6 -0
  52. package/docs/GRID_RECALCULATION.md +3 -3
  53. package/docs/LOGGING.md +9 -0
  54. package/docs/MPA_CREDIT_USAGE.md +3 -2
  55. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +117 -0
  56. package/docs/README.md +1 -1
  57. package/docs/architecture.md +98 -1
  58. package/market_adapter/README.md +2 -2
  59. package/package.json +3 -1
  60. package/scripts/README.md +85 -148
@@ -13,7 +13,7 @@ const { readOpenOrdersWithMetaSafe } = chainOrdersModule;
13
13
  import { BroadcastUncertainError as BroadcastUncertainErrorBinding } from './dexbot_credential_client.js';
14
14
  const BroadcastUncertainError = BroadcastUncertainErrorBinding;
15
15
  import * as orderUtils from './order/utils/order.js';
16
- import { sleep, setLastFillPivot, fireStructuralResync, evaluateSpreadCorrectionReadiness, resolveLastFillGuardReference } from './order/utils/system.js';
16
+ import { sleep, setLastFillPivot, fireStructuralResync, evaluateSpreadCorrectionReadiness, resolveLastFillGuardReference, isLastFillGuardBlocked } from './order/utils/system.js';
17
17
  const { buildCreateOrderArgs, buildCreateOpFingerprint, extractBatchOperationResults, formatUnmatchedChainOrder, convertToSpreadPlaceholder, toRailHolePlaceholder, buildOutsideInPairGroups, isOrderPlaced, chainOrderUnchangedFromCache, detectCrossedBookPlan, collectKnownOnChainOrderIds, } = orderUtils;
18
18
  import * as validate from './order/utils/validate.js';
19
19
  const { validateCreateTargetSlots, evaluateCommit, hasExecutableActions, stampGapEvacuationRotation } = validate;
@@ -1861,65 +1861,24 @@ function collectGapBandPlacementShadowSlots(actions, boundary, gapSlots) {
1861
1861
  return [];
1862
1862
  }
1863
1863
  }
1864
- /**
1865
- * LAST-FILL-GUARD helper — pivot ± halfIncrement (replaces price-tolerance).
1866
- * last fill @x with increment i (blocked shapes): BUY > x*(1 - i/2/100),
1867
- * SELL < x*(1 + i/2/100)
1868
- * e.g. x=1000, i=0.5% => BUY > 997.5 and SELL < 1002.5 are blocked
1869
- * Cold (pivot null or lastType null) => disabled. Spread-correction CREATES
1870
- * bypass per-action (see broadcast sites); gap-evacuation rotation UPDATEs
1871
- * bypass only via the violation-reducing allowance (origin='gap-evacuation',
1872
- * UPDATE-only, frozen B-stamp or live-proven isEvacuationRotationAllowed) —
1873
- * see the UPDATE rotation guard block.
1874
- * The pivot is the latest fill of either side and is never expired: it stays
1875
- * the durable mark (last sold level floors new sells; buy fills pull it down
1876
- * and re-open the sell side, buy-below-sell is never gated).
1877
- * @param {number} price - Target order price
1878
- * @param {number} size - Order size (unused, kept for compat)
1879
- * @param {string} type - ORDER_TYPES.BUY/SELL
1880
- * @param {number|null} lastPrice - Most recent fill price
1881
- * @param {string|null} lastType - Most recent fill side (BUY/SELL)
1882
- * @param {number|any} incrementPercent - Grid increment percent (e.g. 0.5). If assets object passed, falls back to default.
1883
- * @returns {{blocked: boolean, pivot: number|null, halfInc: number, threshold: number|null}}
1884
- */
1885
- function isLastFillGuardBlocked(price, _size, type, lastPrice, lastType, incrementPercent) {
1886
- const numPrice = Number(price);
1887
- if (!Number.isFinite(numPrice))
1888
- return { blocked: false, pivot: null };
1889
- if (lastPrice == null || !Number.isFinite(Number(lastPrice)) || lastType == null)
1890
- return { blocked: false, pivot: null };
1891
- const pivot = Number(lastPrice);
1892
- // Resolve increment: fallback to default 0.5 (also covers legacy assets-object 6th arg)
1893
- let inc = Number(incrementPercent);
1894
- if (!Number.isFinite(inc) || inc <= 0) {
1895
- inc = Number(constantsModule?.DEFAULT_CONFIG?.incrementPercent ?? 0.5);
1896
- }
1897
- if (!Number.isFinite(inc) || inc <= 0)
1898
- return { blocked: false, pivot: null };
1899
- const halfInc = inc / 2;
1900
- const halfPct = halfInc / 100;
1901
- const buyThreshold = pivot * (1 - halfPct);
1902
- const sellThreshold = pivot * (1 + halfPct);
1903
- if (type === ORDER_TYPES.BUY && numPrice > buyThreshold)
1904
- return { blocked: true, pivot, halfInc, threshold: buyThreshold };
1905
- if (type === ORDER_TYPES.SELL && numPrice < sellThreshold)
1906
- return { blocked: true, pivot, halfInc, threshold: sellThreshold };
1907
- return { blocked: false, pivot: null, halfInc, threshold: null };
1908
- }
1909
1864
  /**
1910
1865
  * Whether a spread-correction CREATE may bypass the LAST-FILL-GUARD.
1911
1866
  *
1912
- * The bypass exists so gap repair can close even after a recent fill (the
1913
- * correction is tightening the spread, not chasing it). It must not become a
1914
- * licence to place THROUGH the market the bot last traded at:
1867
+ * Remaining purpose: the STARTUP BOOK SEED proxy. Before the first real fill a
1868
+ * single-sided book arms the guard on our own resting quote (max bid / min
1869
+ * ask) — a proxy that `b14a1fc8` deliberately keeps non-persistent ("a book
1870
+ * seed never fossilizes into the snapshot as market truth") because it goes
1871
+ * wrong whenever the book is not adjacent to the last fill. Blocking a
1872
+ * tightening placement against that proxy would be arbitrary, so the correction
1873
+ * is released from it while the local snapshot can be trusted.
1915
1874
  *
1916
- * 1. A real fill pivot (`lastFillPivotSource === 'fill'`) is always honored —
1917
- * no bypass. A sell below the last fill (or a buy above it) is the
1918
- * issue-#31 adverse fill.
1919
- * 2. A cold/book pivot is a heuristic (book seed) or absent, so the historical
1920
- * fail-open bypass is kept — but only while the LOCAL snapshot is fresh.
1921
- * A stale snapshot (known-unmatched chain orders, or an old sync) can hide
1922
- * the real window edge, so the bypass is withheld and the guard applies.
1875
+ * A real FILL reference always denies the bypass. Since the planner now filters
1876
+ * candidates with the SAME predicate the guard applies, planner-built
1877
+ * corrections never even propose an op that would need it — the bypass is a
1878
+ * proxy-case valve, not a licence to trade through the last real fill.
1879
+ *
1880
+ * Denied too when the snapshot is stale or has known-unmatched chain orders
1881
+ * (a stale edge can hide the real window edge), fail-closed on a gate throw.
1923
1882
  *
1924
1883
  * Exported for tests.
1925
1884
  * @param {Object} bot
@@ -2311,13 +2270,25 @@ function buildCowResultFromPlan(bot, plan) {
2311
2270
  const refillSlotIds = Array.isArray(plan?.refillSlotIds)
2312
2271
  ? plan.refillSlotIds.filter((id) => typeof id === 'string' && id.length > 0)
2313
2272
  : undefined;
2273
+ // Crawl-ledger wire: exactly which owed records this plan's derivation
2274
+ // folded (see CowResult.consumedCrawlIds). Absent/non-array => undefined,
2275
+ // which the commit reads as "clear nothing" rather than "clear all".
2276
+ const consumedCrawlIds = Array.isArray(plan?.consumedCrawlIds)
2277
+ ? plan.consumedCrawlIds
2278
+ .filter((e) => {
2279
+ const rec = e;
2280
+ return !!rec && typeof rec.slotId === 'string' && rec.slotId.length > 0
2281
+ && typeof rec.side === 'string' && rec.side.length > 0;
2282
+ })
2283
+ : undefined;
2314
2284
  return {
2315
2285
  workingGrid,
2316
2286
  workingIndexes: workingGrid.getIndexes(),
2317
2287
  workingBoundary: workingBoundary,
2318
2288
  actions,
2319
2289
  origin: plan.origin,
2320
- ...(refillSlotIds !== undefined ? { refillSlotIds } : {})
2290
+ ...(refillSlotIds !== undefined ? { refillSlotIds } : {}),
2291
+ ...(consumedCrawlIds !== undefined ? { consumedCrawlIds } : {})
2321
2292
  };
2322
2293
  }
2323
2294
  /**
@@ -3473,7 +3444,7 @@ async function updateOrdersOnChainBatchCOWBody(bot, cowResult, replanDepth, seam
3473
3444
  skippedCreateSlotIds.add(order.id);
3474
3445
  continue;
3475
3446
  }
3476
- // LAST-FILL PRICE GUARD: pivot ± halfIncrement (BUY < pivot*(1-half), SELL > pivot*(1+half)).
3447
+ // LAST-FILL PRICE GUARD: direction rule (BUY < pivot, SELL > pivot).
3477
3448
  // Bypass is per-action: only spread-correction CREATES skip so gap repair can close.
3478
3449
  // The batch-level origin is honored only for actions without their own origin stamp
3479
3450
  // (back-compat for plans that bypass buildActionsFromPlan). Cold (null) => disabled.
@@ -3490,7 +3461,7 @@ async function updateOrdersOnChainBatchCOWBody(bot, cowResult, replanDepth, seam
3490
3461
  if (check.blocked) {
3491
3462
  lastFillGuardStats.skipped++;
3492
3463
  const dir = order.type === ORDER_TYPES.BUY ? 'above' : 'below';
3493
- bot.manager.logger.log(`[LAST-FILL-GUARD] Skipping ${order.type} CREATE for ${order.id} at ${Format.formatPrice6(createPrice)}: ${dir} last filled ${Format.formatPrice6(Number(check.pivot))} (halfInc ${check.halfInc}% thr ${Format.formatPrice6(Number(check.threshold))}); re-planned after market moves`, 'debug');
3464
+ bot.manager.logger.log(`[LAST-FILL-GUARD] Skipping ${order.type} CREATE for ${order.id} at ${Format.formatPrice6(createPrice)}: ${dir} last filled ${Format.formatPrice6(Number(check.pivot))} (direction rule: BUY must be below / SELL above the last fill); re-planned after market moves`, 'debug');
3494
3465
  if (order.id)
3495
3466
  skippedCreateSlotIds.add(order.id);
3496
3467
  continue;
@@ -3630,7 +3601,7 @@ async function updateOrdersOnChainBatchCOWBody(bot, cowResult, replanDepth, seam
3630
3601
  `${crossedOrderLabel(crossedOrder)}; re-planned after its cancel confirms.`, 'warn');
3631
3602
  continue;
3632
3603
  }
3633
- // LAST-FILL PRICE GUARD (UPDATE rotation): pivot ± halfIncrement — same as CREATE,
3604
+ // LAST-FILL PRICE GUARD (UPDATE rotation): direction rule — same as CREATE,
3634
3605
  // plus the GAP-EVACUATION ALLOWANCE (violation-reducing): a rotation stamped
3635
3606
  // origin='gap-evacuation' at plan-build moves a live order OUT of the gap band
3636
3607
  // onto its rail with bit-exact non-growing size — it shrinks the violation
@@ -3765,7 +3736,7 @@ async function updateOrdersOnChainBatchCOWBody(bot, cowResult, replanDepth, seam
3765
3736
  if (action.newGridId)
3766
3737
  skippedUpdateSlotIds.add(action.newGridId);
3767
3738
  const dir = orderType === ORDER_TYPES.BUY ? 'above' : 'below';
3768
- bot.manager.logger.log(`[LAST-FILL-GUARD] Skipping ${orderType} UPDATE for ${action.id} -> ${action.newGridId} at ${Format.formatPrice6(newPrice)}: ${dir} last filled ${Format.formatPrice6(Number(check.pivot))} (halfInc ${check.halfInc}% thr ${Format.formatPrice6(Number(check.threshold))})`, 'debug');
3739
+ bot.manager.logger.log(`[LAST-FILL-GUARD] Skipping ${orderType} UPDATE for ${action.id} -> ${action.newGridId} at ${Format.formatPrice6(newPrice)}: ${dir} last filled ${Format.formatPrice6(Number(check.pivot))} (direction rule: BUY must be below / SELL above the last fill)`, 'debug');
3769
3740
  continue;
3770
3741
  }
3771
3742
  lastFillGuardStats.passed++;
@@ -3910,8 +3881,8 @@ async function updateOrdersOnChainBatchCOWBody(bot, cowResult, replanDepth, seam
3910
3881
  const fbDir = fbType === ORDER_TYPES.BUY ? 'above' : 'below';
3911
3882
  bot.manager.logger.log(`[LAST-FILL-GUARD] Skipping CREATE fallback for ${targetSlotId} at ` +
3912
3883
  `${Format.formatPrice6(fbPrice)}: ${fbDir} last filled ` +
3913
- `${Format.formatPrice6(Number(fbCheck.pivot))} (halfInc ${fbCheck.halfInc}% thr ` +
3914
- `${Format.formatPrice6(Number(fbCheck.threshold))}); re-planned after market moves`, 'debug');
3884
+ `${Format.formatPrice6(Number(fbCheck.pivot))} (direction rule: BUY must be ` +
3885
+ `below / SELL above the last fill); re-planned after market moves`, 'debug');
3915
3886
  continue;
3916
3887
  }
3917
3888
  lastFillGuardStats.passed++;
@@ -4327,7 +4298,12 @@ async function updateOrdersOnChainBatchCOWBody(bot, cowResult, replanDepth, seam
4327
4298
  // options.result, so a later throw in this frame (e.g.
4328
4299
  // processBatchResults after a successful commit) cannot pop a
4329
4300
  // second time for the same grid in the batch catch below.
4330
- const commitOk = await bot.manager._commitWorkingGrid(workingGrid, workingIndexes, effectiveBoundary, { skipRecalc: true, result: cowResult, boundaryHeld });
4301
+ const commitOk = await bot.manager._commitWorkingGrid(workingGrid, workingIndexes, effectiveBoundary, {
4302
+ skipRecalc: true,
4303
+ result: cowResult,
4304
+ boundaryHeld,
4305
+ consumedCrawlIds: cowResult?.consumedCrawlIds
4306
+ });
4331
4307
  if (!commitOk) {
4332
4308
  // Master changed during broadcast (e.g. a fill landed and was
4333
4309
  // processed concurrently) so the commit was refused. The batch
@@ -4440,7 +4416,12 @@ async function updateOrdersOnChainBatchCOWBody(bot, cowResult, replanDepth, seam
4440
4416
  // _commitWorkingGrid pops on every settle path and clears
4441
4417
  // the push marker via options.result, so a later throw here
4442
4418
  // must not pop again in the batch catch below.
4443
- const pollCommitOk = await bot.manager._commitWorkingGrid(workingGrid, workingIndexes, effectiveBoundary, { skipRecalc: true, result: cowResult, boundaryHeld });
4419
+ const pollCommitOk = await bot.manager._commitWorkingGrid(workingGrid, workingIndexes, effectiveBoundary, {
4420
+ skipRecalc: true,
4421
+ result: cowResult,
4422
+ boundaryHeld,
4423
+ consumedCrawlIds: cowResult?.consumedCrawlIds
4424
+ });
4444
4425
  if (!pollCommitOk) {
4445
4426
  // Master moved while polling — same recovery as the
4446
4427
  // refused-commit path: adopt from chain, keep pending
@@ -5171,7 +5152,7 @@ function runFinalPivotGate(bot, operations, opContexts, opts = {}) {
5171
5152
  try {
5172
5153
  bot.manager?.logger?.log?.(`[LAST-FILL-GUARD] Final gate dropping ${type} ${ctx.kind} for ${slotId ?? 'unknown'} at ` +
5173
5154
  `${Format.formatPrice6(price)}: ${dir} last filled ${check.pivot != null ? Format.formatPrice6(Number(check.pivot)) : 'n/a'} ` +
5174
- `(halfInc ${check.halfInc}% thr ${check.threshold != null ? Format.formatPrice6(Number(check.threshold)) : 'n/a'}); re-planned after market moves`, 'warn');
5155
+ `(direction rule: BUY must be below / SELL above the last fill); re-planned after market moves`, 'warn');
5175
5156
  }
5176
5157
  catch { /* logging is best-effort */ }
5177
5158
  }
@@ -673,7 +673,7 @@ function _hasBudgetForSide(manager, config, side) {
673
673
  */
674
674
  export function mirrorSpreadStall(bot, stall) {
675
675
  bot._spreadCorrectionStall = stall ?? null;
676
- bot._spreadFundsExhausted = stall != null;
676
+ bot._spreadStallArmed = stall != null;
677
677
  }
678
678
  function getTargetedSyncReason(bot) {
679
679
  if (!bot.manager || bot.config?.dryRun)
@@ -721,7 +721,7 @@ function getTargetedSyncReason(bot) {
721
721
  // structural stall from a stale one, so arm the refresh for every cause
722
722
  // instead of waiting up to SPREAD_STALE_ESCALATE_MS for the watchdog.
723
723
  // Never recycle resting inventory.
724
- if (bot._spreadFundsExhausted === true) {
724
+ if (bot._spreadStallArmed === true) {
725
725
  const cause = bot._spreadCorrectionStall || 'funds-exhausted';
726
726
  return { reason: `spread correction stalled (${cause})`, targetBuy, targetSell, liveBuy, liveSell, drift };
727
727
  }
@@ -763,8 +763,8 @@ async function maybeRunTargetedDriftReconciliation(bot, context) {
763
763
  // order shortfall. The spread check later this tick re-derives the flag
764
764
  // from fresh state, so a genuinely empty balance re-arms it for the next
765
765
  // tick (subject to the cooldown below).
766
- if (bot._spreadFundsExhausted === true)
767
- bot._spreadFundsExhausted = false;
766
+ if (bot._spreadStallArmed === true)
767
+ bot._spreadStallArmed = false;
768
768
  // Clear the companion cause with the flag so the two never drift apart
769
769
  // (a leftover cause would mislabel the next tick's reason).
770
770
  bot._spreadCorrectionStall = null;
@@ -2538,12 +2538,47 @@ async function executeMaintenanceLogic(bot, context) {
2538
2538
  */
2539
2539
  export function trackOutOfSpreadStaleness(bot, spreadChecked, ordersPlaced, transient = false) {
2540
2540
  const outOfSpread = Number(bot?.manager?.outOfSpread) || 0;
2541
- if (ordersPlaced > 0 || outOfSpread === 0) {
2541
+ const nowMs = Date.now();
2542
+ const inToleranceResetMs = Number(TIMING?.SPREAD_STALE_IN_TOLERANCE_RESET_MS) > 0
2543
+ ? Number(TIMING.SPREAD_STALE_IN_TOLERANCE_RESET_MS)
2544
+ : 10 * 60 * 1000;
2545
+ if (ordersPlaced > 0) {
2546
+ bot._outOfSpreadSince = 0;
2547
+ bot._outOfSpreadStaleWarned = false;
2548
+ bot._outOfSpreadTransientCount = 0;
2549
+ bot._outOfSpreadToleranceSince = 0;
2550
+ try {
2551
+ bot.manager._spreadRailOversubscribed = null;
2552
+ }
2553
+ catch { /* best-effort */ }
2554
+ return { staleMs: 0, escalated: false };
2555
+ }
2556
+ if (outOfSpread === 0) {
2557
+ // ONE good reading must not clear the clock. The measured spread
2558
+ // oscillates around the tolerance edge, so resetting on each
2559
+ // in-tolerance cycle let a live bot stay out of tolerance for 84
2560
+ // minutes while every individual glance looked recoverable (the
2561
+ // correction placed nothing in that whole window). Clear only after
2562
+ // tolerance has held for the reset window; a placement clears it
2563
+ // immediately (handled above).
2564
+ const toleranceSince = Number(bot._outOfSpreadToleranceSince) || 0;
2565
+ if (toleranceSince === 0) {
2566
+ bot._outOfSpreadToleranceSince = nowMs;
2567
+ return { staleMs: 0, escalated: false };
2568
+ }
2569
+ if (nowMs - toleranceSince < inToleranceResetMs)
2570
+ return { staleMs: 0, escalated: false };
2542
2571
  bot._outOfSpreadSince = 0;
2543
2572
  bot._outOfSpreadStaleWarned = false;
2544
2573
  bot._outOfSpreadTransientCount = 0;
2574
+ bot._outOfSpreadToleranceSince = 0;
2575
+ try {
2576
+ bot.manager._spreadRailOversubscribed = null;
2577
+ }
2578
+ catch { /* best-effort */ }
2545
2579
  return { staleMs: 0, escalated: false };
2546
2580
  }
2581
+ bot._outOfSpreadToleranceSince = 0;
2547
2582
  if (!spreadChecked) {
2548
2583
  const since = Number(bot._outOfSpreadSince) || 0;
2549
2584
  return { staleMs: since > 0 ? Date.now() - since : 0, escalated: false };
@@ -2579,13 +2614,33 @@ export function trackOutOfSpreadStaleness(bot, spreadChecked, ordersPlaced, tran
2579
2614
  const warnMs = Number(TIMING?.SPREAD_STALE_WARN_MS) > 0
2580
2615
  ? Number(TIMING.SPREAD_STALE_WARN_MS)
2581
2616
  : 10 * 60 * 1000;
2582
- const escalateMs = Number(TIMING?.SPREAD_STALE_ESCALATE_MS) > 0
2583
- ? Number(TIMING.SPREAD_STALE_ESCALATE_MS)
2584
- : 30 * 60 * 1000;
2617
+ // An oversubscribed rail is a fund-structure stall, not "wait for a fill":
2618
+ // escalate on the short fund window so the side is not dead for half an hour.
2619
+ const railOversubscribed = bot.manager?._spreadRailOversubscribed;
2620
+ const oversubscribedFresh = !!railOversubscribed && typeof railOversubscribed === 'object'
2621
+ && (now - Number(railOversubscribed.at || 0)) < 5 * 60 * 1000;
2622
+ const fundEscalateMs = Number(TIMING?.SPREAD_STALE_FUND_ESCALATE_MS) > 0
2623
+ ? Number(TIMING.SPREAD_STALE_FUND_ESCALATE_MS)
2624
+ : 5 * 60 * 1000;
2625
+ // The geometry bind has its own (longer than funds, shorter than structural)
2626
+ // window: the sell window is behind the last sale, which only a re-center
2627
+ // repairs.
2628
+ const geometryBlocked = bot._spreadCorrectionStall === 'last-fill-blocked';
2629
+ const geometryEscalateMs = Number(TIMING?.SPREAD_STALE_GEOMETRY_ESCALATE_MS) > 0
2630
+ ? Number(TIMING.SPREAD_STALE_GEOMETRY_ESCALATE_MS)
2631
+ : 10 * 60 * 1000;
2632
+ const escalateMs = oversubscribedFresh
2633
+ ? fundEscalateMs
2634
+ : geometryBlocked
2635
+ ? geometryEscalateMs
2636
+ : (Number(TIMING?.SPREAD_STALE_ESCALATE_MS) > 0
2637
+ ? Number(TIMING.SPREAD_STALE_ESCALATE_MS)
2638
+ : 30 * 60 * 1000);
2585
2639
  if (staleMs >= warnMs && !bot._outOfSpreadStaleWarned) {
2586
2640
  bot._outOfSpreadStaleWarned = true;
2641
+ const stall = bot._spreadCorrectionStall ? `, stall=${bot._spreadCorrectionStall}` : '';
2587
2642
  bot._log(`[SPREAD-STALE] Spread out of tolerance for ${staleMin}min with no correction placed ` +
2588
- `(outOfSpread=${outOfSpread}); structural re-center follows if unhealed`, 'warn');
2643
+ `(outOfSpread=${outOfSpread}${stall}); structural re-center follows if unhealed`, 'warn');
2589
2644
  }
2590
2645
  if (staleMs >= escalateMs && typeof bot.manager?.requestStructuralGridResync === 'function') {
2591
2646
  // Dedicated spread-stale cooldown (NOT BOUNDARY_HOLD_RESYNC_COOLDOWN_MS:
@@ -2600,7 +2655,10 @@ export function trackOutOfSpreadStaleness(bot, spreadChecked, ordersPlaced, tran
2600
2655
  const lastAt = Number(bot._lastSpreadStaleResyncAt) || 0;
2601
2656
  if (now - lastAt >= cooldownMs) {
2602
2657
  bot._lastSpreadStaleResyncAt = now;
2603
- bot._log(`[SPREAD-STALE] Spread out of tolerance for ${staleMin}min despite corrections; ` +
2658
+ bot._log(`[SPREAD-STALE] Spread out of tolerance for ${staleMin}min despite corrections` +
2659
+ `${oversubscribedFresh ? ' (rail oversubscribed — re-sizing from chain truth)' : ''}` +
2660
+ `${geometryBlocked ? ' (sell window behind the last fill — re-centering)' : ''}` +
2661
+ `${bot._spreadCorrectionStall ? ` (stall=${bot._spreadCorrectionStall})` : ''}; ` +
2604
2662
  `requesting structural re-center`, 'warn');
2605
2663
  fireStructuralResync(bot, 'spread-stale-persistent', {
2606
2664
  reason: `Spread out of tolerance for ${staleMin}min with no effective correction (outOfSpread=${outOfSpread})`
@@ -1,5 +1,12 @@
1
+ import type { VaultSecret } from '../chain_keys.js';
1
2
  import type { StdioOptions } from 'child_process';
2
3
  declare const DEFAULT_POLL_INTERVAL_MS = 1000;
4
+ /**
5
+ * Best-effort wipe of a derived vault secret held in memory.
6
+ * Vault secrets are plain objects with hex-string fields; V8 cannot zero an
7
+ * immutable string in place, so drop each value and let GC reclaim it.
8
+ */
9
+ declare function clearVaultSecret(secret: VaultSecret | null | undefined): void;
3
10
  declare function waitForExit(child: import('node:child_process').ChildProcess): Promise<number | null>;
4
11
  declare function createCredentialDaemonController({ root, codeRoot, socketPath, readyFilePath, pollIntervalMs, }?: {
5
12
  root?: string | undefined;
@@ -8,11 +15,16 @@ declare function createCredentialDaemonController({ root, codeRoot, socketPath,
8
15
  readyFilePath?: string | undefined;
9
16
  pollIntervalMs?: number | undefined;
10
17
  }): {
11
- ensureCredentialDaemon: ({ detached, stdio: stdioOption, headless, passwordFile }?: {
18
+ authenticateCredential: ({ headless, passwordFile }?: {
19
+ headless?: boolean;
20
+ passwordFile?: string | null;
21
+ }) => Promise<VaultSecret>;
22
+ ensureCredentialDaemon: ({ detached, stdio: stdioOption, headless, passwordFile, vaultSecret: preAuthenticatedSecret }?: {
12
23
  detached?: boolean;
13
24
  stdio?: StdioOptions;
14
25
  headless?: boolean;
15
26
  passwordFile?: string | null;
27
+ vaultSecret?: VaultSecret | null;
16
28
  }) => Promise<boolean>;
17
29
  forwardSignal: (signal: string) => void;
18
30
  getManagedDaemonPid: () => number | null;
@@ -21,5 +33,5 @@ declare function createCredentialDaemonController({ root, codeRoot, socketPath,
21
33
  stopManagedDaemon: () => Promise<void>;
22
34
  waitForManagedDaemon: () => Promise<number | null>;
23
35
  };
24
- export { createCredentialDaemonController, DEFAULT_POLL_INTERVAL_MS, waitForExit };
36
+ export { createCredentialDaemonController, clearVaultSecret, DEFAULT_POLL_INTERVAL_MS, waitForExit };
25
37
  //# sourceMappingURL=credential_daemon.d.ts.map
@@ -17,6 +17,22 @@ import { assertPrivatePathSecurity, ensureCredentialRuntimeDirSync, getCredentia
17
17
  import { buildRuntimeScriptArgs, SCRIPTS_ROOT as DEFAULT_CODE_ROOT } from './runtime_entry.js';
18
18
  import { getErrorMessage, getErrorCode } from '../utils/errors.js';
19
19
  const DEFAULT_POLL_INTERVAL_MS = 1000;
20
+ /**
21
+ * Best-effort wipe of a derived vault secret held in memory.
22
+ * Vault secrets are plain objects with hex-string fields; V8 cannot zero an
23
+ * immutable string in place, so drop each value and let GC reclaim it.
24
+ */
25
+ function clearVaultSecret(secret) {
26
+ if (!secret || typeof secret !== 'object')
27
+ return;
28
+ const record = secret;
29
+ for (const key of Object.keys(record)) {
30
+ const value = record[key];
31
+ if (Buffer.isBuffer(value))
32
+ value.fill(0);
33
+ record[key] = null;
34
+ }
35
+ }
20
36
  function waitForExit(child) {
21
37
  return new Promise((resolve, reject) => {
22
38
  child.on('error', reject);
@@ -63,37 +79,46 @@ function createCredentialDaemonController({ root = PATHS.PROJECT_ROOT, codeRoot
63
79
  throw err;
64
80
  }
65
81
  }
66
- async function ensureCredentialDaemon({ detached = false, stdio: stdioOption = undefined, headless = false, passwordFile = null } = {}) {
82
+ async function authenticateCredential({ headless = false, passwordFile = null } = {}) {
83
+ if (headless) {
84
+ return chainKeys.unlockWithPassword(readHeadlessPassword({ passwordFile }));
85
+ }
86
+ return chainKeys.authenticate();
87
+ }
88
+ /**
89
+ * Ensure a responsive credential daemon, starting one when needed.
90
+ * A caller-supplied `vaultSecret` is consumed: the launcher-side reference
91
+ * is cleared once the secret has been handed off (or startup fails), so
92
+ * callers must not reuse the object after this returns.
93
+ */
94
+ async function ensureCredentialDaemon({ detached = false, stdio: stdioOption = undefined, headless = false, passwordFile = null, vaultSecret: preAuthenticatedSecret = null } = {}) {
67
95
  if (await isDaemonReady()) {
68
96
  return false;
69
97
  }
70
98
  await removeStaleDaemonFiles();
71
99
  ensureCredentialRuntimeDirSync();
72
100
  credentialPolicy.ensurePolicyConfig(PATHS.PROFILES.DAEMON_POLICIES_JSON);
73
- let vaultSecret;
74
- if (headless) {
75
- vaultSecret = chainKeys.unlockWithPassword(readHeadlessPassword({ passwordFile }));
76
- }
77
- else {
78
- vaultSecret = await chainKeys.authenticate();
79
- }
80
- const bootstrap = await createPasswordBootstrapServer({ secret: vaultSecret });
81
- const daemonArgs = buildRuntimeScriptArgs({
82
- codeRoot,
83
- scriptSegments: ['credential-daemon'],
84
- });
85
- // Write the bootstrap socket path to a stable file in the runtime dir
86
- // so the credential daemon can find it via DEXBOT_CRED_BOOTSTRAP_PATH_FILE
87
- // instead of a PM2-persistable env var.
88
- const bootstrapPathFile = path.join(path.dirname(socketPath), '.dexbot-cred-bootstrap-path');
89
- try {
90
- storage.writeFile(bootstrapPathFile, bootstrap.socketPath, { mode: 0o600 });
91
- }
92
- catch (err) {
93
- bootstrap.close();
94
- throw new Error(`Cannot write bootstrap path file at ${bootstrapPathFile}: ${getErrorMessage(err)}`);
95
- }
101
+ // A caller that verified the master password up front can hand the
102
+ // secret in, so the daemon restart never has to re-prompt (and can
103
+ // never kill a healthy daemon before the password is known good).
104
+ const vaultSecret = preAuthenticatedSecret ?? await authenticateCredential({ headless, passwordFile });
105
+ let bootstrap = null;
96
106
  try {
107
+ bootstrap = await createPasswordBootstrapServer({ secret: vaultSecret });
108
+ const daemonArgs = buildRuntimeScriptArgs({
109
+ codeRoot,
110
+ scriptSegments: ['credential-daemon'],
111
+ });
112
+ // Write the bootstrap socket path to a stable file in the runtime dir
113
+ // so the credential daemon can find it via DEXBOT_CRED_BOOTSTRAP_PATH_FILE
114
+ // instead of a PM2-persistable env var.
115
+ const bootstrapPathFile = path.join(path.dirname(socketPath), '.dexbot-cred-bootstrap-path');
116
+ try {
117
+ storage.writeFile(bootstrapPathFile, bootstrap.socketPath, { mode: 0o600 });
118
+ }
119
+ catch (err) {
120
+ throw new Error(`Cannot write bootstrap path file at ${bootstrapPathFile}: ${getErrorMessage(err)}`);
121
+ }
97
122
  const childStdio = stdioOption ?? (detached ? 'ignore' : 'inherit');
98
123
  daemonProcess = spawn(Config.EXEC_PATH, daemonArgs, {
99
124
  cwd: root,
@@ -130,9 +155,17 @@ function createCredentialDaemonController({ root = PATHS.PROJECT_ROOT, codeRoot
130
155
  return true;
131
156
  }
132
157
  catch (error) {
133
- bootstrap.close();
158
+ bootstrap?.close();
134
159
  throw error;
135
160
  }
161
+ finally {
162
+ // The secret has been transferred over the one-shot bootstrap
163
+ // socket (or startup failed). Drop the launcher-side material as
164
+ // soon as it is no longer needed. Hex strings cannot be zeroed in
165
+ // place in V8, but clearing the properties lets the values be
166
+ // reclaimed with the object.
167
+ clearVaultSecret(vaultSecret);
168
+ }
136
169
  }
137
170
  function getManagedDaemonPid() {
138
171
  return daemonProcess && daemonProcess.pid ? daemonProcess.pid : null;
@@ -164,6 +197,7 @@ function createCredentialDaemonController({ root = PATHS.PROJECT_ROOT, codeRoot
164
197
  return 0;
165
198
  }
166
199
  return {
200
+ authenticateCredential,
167
201
  ensureCredentialDaemon,
168
202
  forwardSignal,
169
203
  getManagedDaemonPid,
@@ -173,5 +207,5 @@ function createCredentialDaemonController({ root = PATHS.PROJECT_ROOT, codeRoot
173
207
  waitForManagedDaemon,
174
208
  };
175
209
  }
176
- export { createCredentialDaemonController, DEFAULT_POLL_INTERVAL_MS, waitForExit };
210
+ export { createCredentialDaemonController, clearVaultSecret, DEFAULT_POLL_INTERVAL_MS, waitForExit };
177
211
  //# sourceMappingURL=credential_daemon.js.map
@@ -115,6 +115,13 @@ interface SpreadCorrection {
115
115
  origin?: string;
116
116
  [key: string]: unknown;
117
117
  }
118
+ /**
119
+ * Merge two side stalls so the starvation fallback cannot mask a named cause.
120
+ * 'unfunded' stays top (a refresh may repair it); 'unmatched-orders' next (a
121
+ * sync repairs it); then the geometry bind; readiness causes; 'no-candidates'
122
+ * is the floor. Exported for tests.
123
+ */
124
+ export declare function mergeSpreadStalls(a: SpreadCorrectionStall | undefined, b: SpreadCorrectionStall | undefined): SpreadCorrectionStall;
118
125
  /**
119
126
  * Spread-correction refusal causes — the single vocabulary shared by
120
127
  * classifySpreadRefusalCause, the retry/transience decision and the