dexbot 1.6.13 → 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 (114) hide show
  1. package/CHANGELOG.md +66 -4
  2. package/README.md +2 -2
  3. package/analysis/README.md +6 -6
  4. package/analysis/tradingview/README.md +2 -1
  5. package/claw/README.md +7 -7
  6. package/claw/docs/AI_BOT_LIBRARY_API.md +1 -1
  7. package/claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md +4 -4
  8. package/claw/modules/claw_catalog.ts +8 -4
  9. package/claw/modules/dexbot_profiles.ts +59 -15
  10. package/claw/modules/types.ts +2 -1
  11. package/claw/package.json +1 -1
  12. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  13. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  14. package/claw/skills/margin-trading/SKILL.md +1 -1
  15. package/claw/skills/margin-trading/references/position-management.md +1 -1
  16. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +105 -31
  17. package/dist/analysis/trend_detection/dynamic_weight_chart_generator.js +36 -2
  18. package/dist/dexbot.js +23 -3
  19. package/dist/market_adapter/core/strategies/dynamic_weight_series.js +26 -11
  20. package/dist/modules/account_bots.d.ts +10 -6
  21. package/dist/modules/account_bots.js +13 -10
  22. package/dist/modules/account_orders.d.ts +36 -4
  23. package/dist/modules/account_orders.js +76 -5
  24. package/dist/modules/bitshares-native/crypto/ecc_core.d.ts +1 -2
  25. package/dist/modules/bitshares-native/crypto/ecc_core.js +1 -1
  26. package/dist/modules/bitshares-native/serial/chain_constants.d.ts +1 -2
  27. package/dist/modules/bitshares-native/serial/chain_constants.js +1 -2
  28. package/dist/modules/bitshares-native/subscriptions.js +1 -1
  29. package/dist/modules/bot_defaults.d.ts +29 -4
  30. package/dist/modules/bot_defaults.js +65 -10
  31. package/dist/modules/bot_settings.d.ts +4 -0
  32. package/dist/modules/bot_settings.js +58 -21
  33. package/dist/modules/config.js +6 -1
  34. package/dist/modules/constants.d.ts +13 -5
  35. package/dist/modules/constants.js +36 -5
  36. package/dist/modules/credit_runtime.d.ts +35 -5
  37. package/dist/modules/credit_runtime.js +219 -38
  38. package/dist/modules/dexbot_class.d.ts +23 -0
  39. package/dist/modules/dexbot_class.js +60 -17
  40. package/dist/modules/dexbot_cow_runtime.d.ts +62 -174
  41. package/dist/modules/dexbot_cow_runtime.js +350 -64
  42. package/dist/modules/dexbot_credential_client.d.ts +1 -16
  43. package/dist/modules/dexbot_credential_client.js +1 -1
  44. package/dist/modules/dexbot_fill_runtime.d.ts +2 -2
  45. package/dist/modules/dexbot_fill_runtime.js +16 -8
  46. package/dist/modules/dexbot_maintenance_runtime.d.ts +24 -81
  47. package/dist/modules/dexbot_maintenance_runtime.js +104 -70
  48. package/dist/modules/dexbot_startup_runtime.js +15 -2
  49. package/dist/modules/dexbot_state_recovery.js +17 -1
  50. package/dist/modules/key_store.d.ts +0 -5
  51. package/dist/modules/key_store.js +1 -1
  52. package/dist/modules/order/accounting.js +11 -11
  53. package/dist/modules/order/export.js +4 -4
  54. package/dist/modules/order/format.d.ts +15 -1
  55. package/dist/modules/order/format.js +19 -1
  56. package/dist/modules/order/genesis_policy.d.ts +1 -1
  57. package/dist/modules/order/genesis_policy.js +1 -1
  58. package/dist/modules/order/grid.d.ts +141 -12
  59. package/dist/modules/order/grid.js +666 -92
  60. package/dist/modules/order/grid_reconcile.d.ts +1 -1
  61. package/dist/modules/order/grid_reconcile.js +9 -8
  62. package/dist/modules/order/grid_reconcile_internal.js +61 -58
  63. package/dist/modules/order/index.d.ts +37 -9
  64. package/dist/modules/order/logger.js +2 -2
  65. package/dist/modules/order/manager.d.ts +10 -2
  66. package/dist/modules/order/manager.js +56 -31
  67. package/dist/modules/order/strategy.d.ts +2 -2
  68. package/dist/modules/order/strategy.js +51 -21
  69. package/dist/modules/order/sync_engine.js +22 -9
  70. package/dist/modules/order/utils/math.d.ts +101 -29
  71. package/dist/modules/order/utils/math.js +215 -84
  72. package/dist/modules/order/utils/order.d.ts +58 -58
  73. package/dist/modules/order/utils/order.js +135 -106
  74. package/dist/modules/order/utils/system.d.ts +193 -6
  75. package/dist/modules/order/utils/system.js +394 -31
  76. package/dist/modules/order/utils/validate.d.ts +1 -1
  77. package/dist/modules/order/utils/validate.js +71 -59
  78. package/dist/modules/runtime_settings.d.ts +1 -1
  79. package/dist/modules/runtime_settings.js +3 -3
  80. package/dist/modules/types.d.ts +55 -4
  81. package/dist/scripts/analyze-credit.js +44 -27
  82. package/dist/scripts/analyze-orders.d.ts +1 -1
  83. package/dist/scripts/analyze-orders.js +4 -4
  84. package/dist/scripts/diagnose-pool-history.js +35 -30
  85. package/dist/scripts/divergence-calc.js +6 -6
  86. package/dist/scripts/pnl.js +1 -1
  87. package/dist/scripts/rich_list.d.ts +18 -0
  88. package/dist/scripts/rich_list.js +461 -0
  89. package/dist/scripts/run-tests.js +80 -4
  90. package/dist/scripts/validate_bots.d.ts +1 -1
  91. package/dist/scripts/validate_bots.js +3 -3
  92. package/dist/unlock.d.ts +2 -1
  93. package/dist/unlock.js +11 -5
  94. package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -2
  95. package/docs/COW_INVARIANTS.md +12 -6
  96. package/docs/DEXBOT_COMPARISON.md +7 -7
  97. package/docs/EVOLUTION.md +10 -8
  98. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +8 -6
  99. package/docs/GRID_PRICE_INVARIANT.md +3 -3
  100. package/docs/GRID_RECALCULATION.md +4 -1
  101. package/docs/GRID_RECONCILE.md +4 -4
  102. package/docs/LIFECYCLE.md +11 -11
  103. package/docs/LOGGING.md +30 -1
  104. package/docs/MPA_CREDIT_USAGE.md +11 -6
  105. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +170 -12
  106. package/docs/README.md +3 -3
  107. package/docs/WORKFLOW.md +1 -0
  108. package/docs/architecture.md +62 -8
  109. package/docs/developer_guide.md +12 -3
  110. package/market_adapter/README.md +4 -4
  111. package/modules/README.md +1 -1
  112. package/package.json +2 -1
  113. package/scripts/README.md +59 -32
  114. package/tests/README.md +12 -3
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
@@ -56,8 +56,6 @@ import { buildRuntimeScriptArgs } from './modules/launcher/runtime_entry.js';
56
56
  import { sendControlCommand } from './modules/launcher/supervisor_control.js';
57
57
  import { registerCleanup, setupGracefulShutdown } from './modules/graceful_shutdown.js';
58
58
  import { normalizeBotEntry, resolveRawBotEntries, loadSettingsFile } from './modules/bot_settings.js';
59
- import { main as runBotEditor } from './modules/account_bots.js';
60
- import { setSuppressConnectionLog, disconnectClient } from './modules/bitshares_client.js';
61
59
  import { selectStartOnboardingCommand } from './modules/cli_start_onboarding.js';
62
60
  import * as chainKeys from './modules/chain_keys.js';
63
61
  import * as credentialPolicy from './modules/credential_policy.js';
@@ -326,7 +324,7 @@ async function launchDetachedSupervisor({ botName = null, credentialDaemonPid =
326
324
  catch (_) { }
327
325
  }
328
326
  }
329
- 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 } = {}) {
330
328
  let supervisor;
331
329
  if (botName) {
332
330
  const bot = botEntry || resolveBotEntryForName(botName);
@@ -385,7 +383,7 @@ async function runIsolated({ botName, botEntry = null, stayResident = false, sta
385
383
  cleanupSignalHandlers();
386
384
  reject(err);
387
385
  }
388
- }, 1000);
386
+ }, isolatedPollIntervalMs);
389
387
  });
390
388
  }
391
389
  // ── Main entry point ───────────────────────────────────────────────
@@ -421,6 +419,13 @@ async function runStartOnboardingIfNeeded({ allowInteractive = true, nonInteract
421
419
  await chainKeys.main();
422
420
  return true;
423
421
  }
422
+ // The interactive bot editor drags in the heavyweight native chain client
423
+ // (~80 ms of module graph). It is only needed on this onboarding path, so
424
+ // load it lazily instead of eagerly on every `unlock`/`start` invocation.
425
+ const [{ main: runBotEditor }, { setSuppressConnectionLog, disconnectClient }] = await Promise.all([
426
+ import('./modules/account_bots.js'),
427
+ import('./modules/bitshares_client.js'),
428
+ ]);
424
429
  setSuppressConnectionLog(true);
425
430
  try {
426
431
  await runBotEditor();
@@ -435,7 +440,7 @@ async function runStartOnboardingIfNeeded({ allowInteractive = true, nonInteract
435
440
  }
436
441
  return true;
437
442
  }
438
- 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 } = {}) {
439
444
  if (typeof chainKeys.checkKeysFileSecurity === 'function')
440
445
  chainKeys.checkKeysFileSecurity();
441
446
  if (typeof credentialPolicy.checkPolicyFileSecurity === 'function')
@@ -629,6 +634,7 @@ async function main({ argv = process.argv, startupGraceMs = DEFAULT_STARTUP_GRAC
629
634
  botEntry: selectedBot,
630
635
  stayResident: isDetachedSupervisorChild,
631
636
  startupGraceMs,
637
+ isolatedPollIntervalMs,
632
638
  });
633
639
  return;
634
640
  }
@@ -95,7 +95,6 @@ boundary position and slot BUY/SELL roles during blockchain execution.
95
95
  ├─> Create WorkingGrid (clone master)
96
96
  ├─> Calculate target grid (from strategy)
97
97
  ├─> Reconcile against working copy
98
- ├─> Validate working grid funds
99
98
  └─> Return { workingGrid, actions, ... }
100
99
 
101
100
  2. updateOrdersOnChainBatch(result)
@@ -265,7 +264,7 @@ During Rebalance**.
265
264
 
266
265
  ## Safety Guardrails
267
266
 
268
- 1. **Accountant Dry-Run:** `Accountant.validateTargetGrid(targetMap)` verifies that the entire proposed grid fits within `Liquid + CurrentOrderValue` *before* broadcasting.
267
+ 1. **Planning-time budget feasibility:** order sizes are derived from `funds.allocated` via `getSideBudget` / `_getSizingContext`, so a proposed grid cannot exceed the side budget by construction. (The historical `Accountant.validateTargetGrid` dry-run was removed — it had no production caller.)
269
268
  2. **Atomic Transaction Semantics:** Large boundary shifts (>5 slots) are inherently safe because the COW pattern only commits after successful blockchain confirmation. If market volatility causes rapid shifts during planning, the plan is caught by the **pre-broadcast staleness guard** (`evaluateCommit` against `_gridVersion`): it re-plans ONCE from the fresh master with the same fills (`replanStaleBatch`, bounded by `STALE_PLAN_REPLAN_LIMIT`), then proceeds + structural resync if still stale — never a silent discard that drops the fill set. If the master changes *during* broadcast, the commit-time guard refuses the commit and the placed orders are adopted from chain so on-chain state never runs ahead of the grid.
270
269
  3. **Resync on Error:** If any blockchain action fails (e.g., "Insufficient funds"), the bot discards the working grid and triggers `grid_reconcile.ts` for a fresh blockchain sync ([GRID_RECONCILE.md](GRID_RECONCILE.md)).
271
270
 
@@ -61,15 +61,15 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
61
61
  - Funds drive order sizing/budget allocation only; `syncBoundaryToFunds`/`calculateFundDrivenBoundary` are deleted (1.5.3).
62
62
 
63
63
  - `INV-COW-007` Boundary hold on guard-skipped refills
64
- - When a slot on the plan's refill wire (`collectRefillSlotIds`: the plan's CREATE ids minus reserve-ladder edge ids) was guard-skipped at broadcast (`skippedUpdateSlotIds` ∪ `clampedUpdateSlotIds` ∪ `skippedCreateSlotIds`), `resolveRefillBoundaryHold` keeps the COMMITTED boundary instead of committing the plan's shifted one over the stranded rail hole; the grid still commits.
65
- - Reserve-ladder CREATEs are excluded because reserves are static edge insurance whose fills never crawl — a skipped reserve must not pin geometry.
64
+ - When a slot on the plan's refill wire (`collectRefillSlotIds`: the plan's CREATE ids minus edge-ladder edge ids) was guard-skipped at broadcast (`skippedUpdateSlotIds` ∪ `clampedUpdateSlotIds` ∪ `skippedCreateSlotIds`), `resolveRefillBoundaryHold` keeps the COMMITTED boundary instead of committing the plan's shifted one over the stranded rail hole; the grid still commits.
65
+ - Edge-ladder CREATEs are excluded because reserves are static edge insurance whose fills never crawl — a skipped reserve must not pin geometry.
66
66
  - The hold rides to the commit as `options.boundaryHeld`, which suppresses the pending-crawl clear.
67
67
  - `trackBoundaryHold` counts consecutive hold batches (`manager._consecutiveBoundaryHolds`, cleared on the first clean batch) with a last-hold snapshot (`manager._lastBoundaryHoldInfo`); runs of 3+ escalate visibly. It also records a hold signature (`manager._lastHeldPlanSignature`: committed boundary + guard pivot + `_lastFilledAt` + held wire) so a fill-less re-plan of an unchanged state defers instead of re-broadcasting the identical vetoed plan.
68
68
  - Fill-driven rebalances never sleep on `_broadcastingFlag` inside `_fillProcessingLock`: `performSafeRebalance({deferIfBroadcasting:true})` returns a `deferred` result and the region-end hook schedules one no-fill rebalance (`schedulePostRecoveryRebalance`). This prevents the 20s lock-acquisition-timeout cascade when a broadcast region outlives the 30s `_awaitBroadcastIdle` wait. The stale-flag watchdog (`_clearStaleBroadcastFlag`, 120s) fires the same region-end hook when it hard-clears a leaked flag, so deferred fills are woken even when the region never ends through `stopBroadcasting()`.
69
69
  - A hold run carrying fresh fills (>= `TIMING.BOUNDARY_HOLD_RESYNC_THRESHOLD`) requests a guard-aware structural re-center (`requestStructuralGridResync`, cooldown `TIMING.BOUNDARY_HOLD_RESYNC_COOLDOWN_MS`) instead of holding forever — the heal path when the grid is trailing the market.
70
70
 
71
71
  - `INV-COW-008` Owed fill crawls survive unapplied commits
72
- - `order/strategy.ts` records a crawl per shift-eligible fill at intake (slot-level dedupe, capped at 500); `deriveTargetBoundary` folds still-owed `_pendingFillCrawls` into the next derivation, excluding the current batch's slots, reserve slots, and window members — a window that reaches the grid edge is not a reserve, using the same window exclusion every placement picker and `countLiveReserveOrders` apply.
72
+ - `order/strategy.ts` records a crawl per shift-eligible fill at intake (slot-level dedupe, capped at 500); `deriveTargetBoundary` folds still-owed `_pendingFillCrawls` into the next derivation, excluding the current batch's slots, edge slots, and window members — a window that reaches the grid edge is not an edge order, using the same window exclusion every placement picker and `countLiveEdgeOrders` apply.
73
73
  - `_commitWorkingGrid` clears them only when the plan's boundary was actually applied — a held boundary (`boundaryHeld`), a gate-rejected boundary, and a null boundary all leave them owed.
74
74
  - `consumePendingFillCrawls` applies them onto a restored finite boundary; `applyPersistedPendingCrawls` is the shared startup/recovery wrapper used before sync/reconcile; `_clearPendingFillCrawls` drops them when the boundary is re-anchored (grid rebuild via `initializeGrid`, rejected snapshot via `rejectCorruptedGridSnapshot`, persisted snapshot wipe via `AccountOrders.clearGrid`).
75
75
 
@@ -81,17 +81,23 @@ 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
 
87
93
  - `INV-PROJ-002` Preserve on-chain PARTIAL size in projection
88
94
  - If identity is retained (`keepOrderId=true`) and current state is `PARTIAL`, projected size must preserve current on-chain remaining size.
89
95
  - It must not be overwritten by ideal geometric `targetSize`.
90
- - Exception: a `PARTIAL` with a rotation/size-update action targeting its `orderId` does use `targetSize` (the explicit-UPDATE path at `modules/order/utils/validate.ts:1158`).
96
+ - Exception: a `PARTIAL` with a rotation/size-update action targeting its `orderId` does use `targetSize` (the explicit-UPDATE path at `modules/order/utils/validate.ts:1187`).
91
97
  - Preserve-path size must be normalized to finite, non-negative value.
92
98
 
93
99
  - `INV-PROJ-003` ACTIVE on-chain projection preserves current size (same as PARTIAL)
94
- - If identity is retained and state is `ACTIVE`, projection preserves current on-chain size via the same `shouldPreserveSize` path as `PARTIAL` (`validate.ts:1158`).
100
+ - If identity is retained and state is `ACTIVE`, projection preserves current on-chain size via the same `shouldPreserveSize` path as `PARTIAL` (`validate.ts:1187`).
95
101
  - An explicit UPDATE action targeting the `orderId` is required to apply `targetSize`.
96
102
 
97
103
  - `INV-ID-001` Order identity retention rule
@@ -191,7 +197,7 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
191
197
  - `INV-GRID-001` One-to-one order mapping
192
198
  - One grid slot = at most one on-chain order. No two chain orders may map to the same grid slot.
193
199
  - Sync engine tracks `matchedGridOrderIds` through both sync passes and skips already-matched slots.
194
- - Surplus orders (matched count above the per-side `activeOrders` + `reserveOrders` targets) are flagged for cancellation.
200
+ - Surplus orders (matched count above the per-side `coreOrders` + `edgeOrders` targets) are flagged for cancellation.
195
201
 
196
202
  - `INV-GRID-002` One order per price level
197
203
  - The active grid must have at most one on-chain order per (type, price) pair.
@@ -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.13).
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.13 |
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 |
@@ -347,7 +347,7 @@ workers:
347
347
  "targetSpreadPercent": 4,
348
348
  "weightDistribution": { "sell": 1, "buy": 1 },
349
349
  "botFunds": { "sell": "100%", "buy": "100%" },
350
- "activeOrders": { "sell": 5, "buy": 5 },
350
+ "coreOrders": { "sell": 5, "buy": 5 },
351
351
  "poolRef": "1.19.133" // optional: pin a specific pool for price derivation
352
352
  }
353
353
  ```
@@ -776,13 +776,13 @@ Where:
776
776
 
777
777
  | Metric | DEXBot | DEXBot2 |
778
778
  |---|---|---|
779
- | **Release Track** | 1.0.0 | v1.6.13 |
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,372 (current HEAD, v1.6.13 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) |
package/docs/EVOLUTION.md CHANGED
@@ -2,14 +2,14 @@
2
2
 
3
3
  ## Executive Summary
4
4
 
5
- DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.6.13 release.
5
+ DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.6.15 release.
6
6
 
7
7
  ### Key Milestones
8
8
  - **Project Inception**: December 2, 2025
9
- - **Growth Phase**: 2,372 commits over ~9 active months
9
+ - **Growth Phase**: 2,411 commits over ~9 active months
10
10
  - **Code Maturity**: Evolution from basic utilities to a ~100,000+ LoC intelligent TypeScript system
11
- - **Stability**: Progression from manual testing to a suite of 307 automated test files
12
- - **Releases**: 145 version entries in the changelog (v0.1.0 to v1.6.13)
11
+ - **Stability**: Progression from manual testing to a suite of 310 automated test files
12
+ - **Releases**: 147 version entries in the changelog (v0.1.0 to v1.6.15)
13
13
 
14
14
  > **Post-1.0.0 "why":** the thematic story behind the hardening releases — root cause, recurring
15
15
  > bug families, and lessons — lives in
@@ -149,7 +149,7 @@ Evolved from a basic README to a comprehensive framework (50+ docs entries, 80%+
149
149
 
150
150
  ## Version History
151
151
 
152
- Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` over the current history (2026-10-10), so the column sums to 2,265 — the 107 commits up to and including the `v0.1.0` tag are not attributed to an era (2,265 + 107 = 2,372). Per-release detail lives in [CHANGELOG.md](../CHANGELOG.md); the thematic post-1.0.0 story in [ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md](ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md).
152
+ Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` over the current history (2026-10-16). The 107 commits up to and including the `v0.1.0` tag are not attributed to an era, so the current totals are 2,304 (`v0.1.0..HEAD`) and 2,411 (`HEAD`); the `v1.4.x` era rows overlap slightly because `v1.4.13` is not an ancestor of `v1.4.25` in the current history. Per-release detail lives in [CHANGELOG.md](../CHANGELOG.md); the thematic post-1.0.0 story in [ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md](ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md).
153
153
 
154
154
  | Era | Commits | Theme |
155
155
  |-----|--------:|-------|
@@ -171,11 +171,13 @@ Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` o
171
171
  | v1.6.10 → v1.6.11 | 6 | AMA-slope 3-bar persistence gate + 16h Huber lookback, EMA-smoothing removal, PnL HTML report + month-shard fill cache, five order-engine/lifecycle safety fixes |
172
172
  | v1.6.11 → v1.6.12 | 27 | Explicit-`any` elimination + ratchet, shared ECC core & Firefox-safe pure-JS scrypt, worker-drain and fresh-placement cancel-grace safety fixes, funded spread correction, partial credit renewal, update install-layout classifier, AMA persistence-override fixes, test-suite speedup, dynamic-weight knob retune |
173
173
  | v1.6.12 → v1.6.13 | 21 | Spread-stall cause reporting + chain sync on every stall, resync-cascade guards (uncertain broadcast / suspended persistence), month-shard candle cache, dedup & dead-code purge, npm 12 install & PM2 fixes |
174
+ | v1.6.13 → v1.6.14 | 18 | Last-fill guard + live market floor for spread correction, committed-size drift resize, COW pre-broadcast guards & P2 counters, fail-closed unknown geometry, order-key rename, worker-thread test runner |
175
+ | v1.6.14 → v1.6.15 | 20 | Spread-correction resilience (atomic plan/retry, bounded re-plan, transient-refusal grace), price-vs-amount level identity for low-precision assets, credit-renewal free-collateral top-up, TradingView 1h/chart fixes & live data-age badge, per-asset `dexbot rich`, ~4x parallel test runner |
174
176
 
175
177
  ---
176
178
 
177
179
  **Report Originally Generated**: February 19, 2026
178
- **Last Updated**: October 10, 2026
179
- **Total Commits**: 2,372
180
- **Date Range**: December 2, 2025 – October 10, 2026
180
+ **Last Updated**: October 16, 2026
181
+ **Total Commits**: 2,411
182
+ **Date Range**: December 2, 2025 – October 16, 2026
181
183
  **Repository**: DEXBot2 (BitShares DEX Trading Bot)
@@ -52,7 +52,7 @@ funds.allocated → _getSizingContext() (budget for spread correction)
52
52
  **Key points:**
53
53
  - `botFunds` percentage applies to **total** capital (free + locked in orders), not just free. A bot at `"50%"` gets half of everything, not half of what's currently idle.
54
54
  - `funds.allocated` is the ceiling for each side. Existing orders already consume part of it; the remaining free portion is available for new placements.
55
- - The downstream `applyBotFundsAllocation()` (`manager.ts:1277`) also caps `funds.available` to `<= allocated` as a safety net, but the primary budget chokepoint is `getSideBudget` / `_getSizingContext` reading `allocated` directly (v1.2.6).
55
+ - The downstream `applyBotFundsAllocation()` (`manager.ts:1296`) also caps `funds.available` to `<= allocated` as a safety net, but the primary budget chokepoint is `getSideBudget` / `_getSizingContext` reading `allocated` directly (v1.2.6).
56
56
 
57
57
  ---
58
58
 
@@ -112,7 +112,7 @@ See [developer_guide.md#order-state-helper-functions](developer_guide.md#order-s
112
112
 
113
113
  #### Gap-Slot Batch Fill Processing
114
114
 
115
- **Mechanism**: Fill events arrive via `modules/dexbot_fill_runtime.ts` (the fill-runtime module), which pushes them into `bot._incomingFillQueue` (declared in `modules/dexbot_class.ts`). The drain loop in `dexbot_fill_runtime.ts` then chunks the queue into capped batches and calls `modules/order/manager.ts::processFilledOrders` (line 1438) once per chunk to run the full rebalance pipeline.
115
+ **Mechanism**: Fill events arrive via `modules/dexbot_fill_runtime.ts` (the fill-runtime module), which pushes them into `bot._incomingFillQueue` (declared in `modules/dexbot_class.ts`). The drain loop in `dexbot_fill_runtime.ts` then chunks the queue into capped batches and calls `modules/order/manager.ts::processFilledOrders` (line 1811) once per chunk to run the full rebalance pipeline.
116
116
 
117
117
  **Batch Sizing Algorithm**: Batch size is derived from the grid gap-slot count + 1 (`DEXBot._getGapSlotBatchSize`): a queue depth at or below gapSlots+1 is processed as one unified batch; deeper queues are chunked into repeated batches of gapSlots+1 (the last chunk may be smaller). The same gapSlots+1 size caps order operations per broadcast transaction (oversized op batches are split into sequential broadcasts).
118
118
 
@@ -123,7 +123,7 @@ See [developer_guide.md#order-state-helper-functions](developer_guide.md#order-s
123
123
  **Per-Batch Execution**:
124
124
 
125
125
  1. **Peek & Pop**: Check `_incomingFillQueue`, pop up to N fills (batch size)
126
- 2. **Replay-safe Accounting Pass**: Each fill is accounted individually via `processFillAccounting(fillOp, fillKey)` with replay-safe dedup (`applyReplaySafeFillAccounting`, `dexbot_fill_runtime.ts:305`)
126
+ 2. **Replay-safe Accounting Pass**: Each fill is accounted individually via `processFillAccounting(fillOp, fillKey)` with replay-safe dedup (`applyReplaySafeFillAccounting`, `dexbot_fill_runtime.ts:303`)
127
127
  - Proceeds credited directly to `chainFree` (via `adjustTotalBalance`)
128
128
  - Same-order fill batching (sync_engine Phase 6 cumulative transition) aggregates multiple fill transitions on one order before a single rebalance
129
129
  - All proceeds immediately available to next rebalance cycle (not split across cycles)
@@ -137,7 +137,7 @@ See [developer_guide.md#order-state-helper-functions](developer_guide.md#order-s
137
137
 
138
138
  **Result**: 29 fills now processed in ~8 broadcasts (~24s) instead of 29 broadcasts (~90s).
139
139
 
140
- **Residual Dust Cancellation** (post-1.4.12): After a sub-dust fill leaves a residual order on chain (e.g. the quote-side value truncates to 0 on `bitshares-core` `maybe_cull_small_order`), the fill runtime explicitly cancels those residuals via `cancelResidualOrders()` (`dexbot_fill_runtime.ts:193`, `[RESIDUAL]` tag) so a leftover of ≥1 base unit cannot be re-adopted into a grid slot by maintenance.
140
+ **Residual Dust Cancellation** (post-1.4.12): After a sub-dust fill leaves a residual order on chain (e.g. the quote-side value truncates to 0 on `bitshares-core` `maybe_cull_small_order`), the fill runtime explicitly cancels those residuals via `cancelResidualOrders()` (`dexbot_fill_runtime.ts:191`, `[RESIDUAL]` tag) so a leftover of ≥1 base unit cannot be re-adopted into a grid slot by maintenance.
141
141
 
142
142
  #### Grid Regeneration Trigger (Available Funds Ratio — bidirectional)
143
143
 
@@ -156,6 +156,8 @@ SHRINK: overAlloc = (gridTracked - allocatedCapital) / allocatedCapital * 100
156
156
 
157
157
  Deliberately no per-side chain-total-drop leg: a normal fill moves value across sides (pays one asset, receives the other — see `processFillAccounting`), so one side's total routinely drops ≥3% on ordinary fills, and the fill pipeline already re-sizes from the post-fill budget.
158
158
 
159
+ **Committed-Size Drift leg**: the available-funds ratio above is measured as `chainFree − virtual`. The fill/rotation sizing pipeline re-derives VIRTUAL slot sizes from the live budget, so an external deposit (or withdrawal) is folded into the virtual reservation on the first rotation after it lands — `chainFree` and `virtual` move together, the ratio stays pinned at the unallocated remainder, and the on-chain (ACTIVE/PARTIAL) orders can stay at their pre-deposit sizes with no trigger. The committed-drift leg (folded into `checkAndUpdateGridIfNeeded`, exposed drift-only as `checkCommittedSizeDrift`) closes that gap: it computes the geometric ideal for each side from the current budget and compares it against the sizes actually committed on-chain (replaying the resize path's free-balance growth cap). A side whose committed orders would change by ≥ `GRID_REGENERATION_PERCENTAGE` of its **committed size** is flagged on the same ratio leg, so the full side is resized rather than only the fill-generated replacement orders. The denominator is the committed total, not the whole allocation: the on-chain window is a small slice of the plan (the far rail holds most of it), so an allocation-relative fraction would understate a genuine full-side undersize.
160
+
159
161
  **How It Works (grow)**:
160
162
  1. Fill occurs → proceeds added to `chainFree`
161
163
  2. `calculateAvailableFundsValue()` computes true spending power (chainFree minus reservations)
@@ -525,7 +527,7 @@ BitShares charges fees for `limit_order_create` and `limit_order_cancel`.
525
527
 
526
528
  - **Reservation** (`BTS_RESERVATION_MULTIPLIER` in `constants.ts::FEE_PARAMETERS`):
527
529
  $$Reserve = N_{active} \times BTS\_RESERVATION\_MULTIPLIER$$
528
- *(Default: 5× per order — covers create, rotate (cancel+place), update, and cancel over the order's lifetime. $N_{active}$ counts window orders plus the `reserveOrders` edge ladder — reserves rest live on-chain and pay fees like window orders)*
530
+ *(Default: 5× per order — covers create, rotate (cancel+place), update, and cancel over the order's lifetime. $N_{active}$ counts window orders plus the `edgeOrders` edge ladder — reserves rest live on-chain and pay fees like window orders)*
529
531
 
530
532
  - **Settlement (`deductBtsFees`):**
531
533
  1. Check `Funds.btsFeesOwed`.
@@ -801,4 +803,4 @@ To prevent "Time-of-Check to Time-of-Use" errors:
801
803
  **TOCTOU protection in `processFillAccounting`.** `_buildBtsDeferredRefundAdjustment` reads `btsFeeState` from `mgr.orders` while the order lock is held — the lock is acquired before accounting runs, and the POST-RESET and BOOTSTRAP tracked-fill accounting paths follow the same locking pattern.
802
804
 
803
805
  ---
804
- *Technical Reference for DEXBot2 v1.6.13 release*
806
+ *Technical Reference for DEXBot2 v1.6.15 release*
@@ -1,7 +1,7 @@
1
1
  # The Grid-Price Invariant
2
2
 
3
3
  Status: **implemented; the emission check is BLOCKING**
4
- Last code-reviewed against the v1.6.7 release baseline `d4e0ce0b` (2026-09-26).
4
+ Last code-reviewed against the v1.6.13 release baseline `1a1ae60c` (2026-10-11).
5
5
 
6
6
  ## The invariant
7
7
 
@@ -413,7 +413,7 @@ is divergence telemetry built on `calculateGridSideDivergenceMetric`.
413
413
  **A grid with no price ladder is not a degraded grid — it is an undefined one.**
414
414
  Every consumer of the invariant reads `priceForSlot(idx, genesis)`, and each one
415
415
  silently degrades without it: nearest-slot adoption, `computeOutOfToleranceDriftTag`,
416
- the materialize descriptor-price fallback, `resolveLiveReserveEdgeAnchorPrice`
416
+ the materialize descriptor-price fallback, `resolveLiveEdgeAnchorPrice`
417
417
  tiers 3/4, and the `isSlotInRail` fail-open. That degradation is the tolerance
418
418
  matcher, which is exactly the path on which an off-grid price becomes grid
419
419
  evidence. So the ladder is treated as a **required** part of a snapshot, not a
@@ -489,7 +489,7 @@ degrade *into*:
489
489
  | correction-queue staleness matched by tolerance | `priceSlotEqual` against the slot's own level, and a ladder-less entry is dropped |
490
490
  | `computeOutOfToleranceDriftTag` + `price-drift-orphan` auto-cancel (`PRICE_DRIFT_TOLERANCE_MULTIPLIER`) | removed — an off-grid order is HELD (`out-of-grid-deferred`) and resolved structurally, never cancelled off a fuzzy price diff |
491
491
  | `findMatchingGridOrderByOpenOrder` | removed (its last production caller was the pass-2 legacy block; the cancelOrder linkage matches by `orderId`) |
492
- | `resolveLiveReserveEdgeAnchorPrice` tiers 2/3 (live slot extreme, config bound) | ladder extreme only; a ladder-less manager returns `null` (the live resolver no longer computes a config bound — consumers that want one, e.g. `reserveEdgeIdSet`, resolve it themselves) |
492
+ | `resolveLiveEdgeAnchorPrice` tiers 2/3 (live slot extreme, config bound) | ladder extreme only; a ladder-less manager returns `null` (the live resolver no longer computes a config bound — consumers that want one, e.g. `edgeOrderIdSet`, resolve it themselves) |
493
493
  | materialize descriptor-price fallback for a `slot-N` id | kept only for an unparseable id; a `slot-N` id with no ladder logs `error` and requests a structural resync |
494
494
 
495
495
  **E2 is fail-closed.** `syncFromOpenOrders` calls `_assertGenesisInvariant`
@@ -457,16 +457,19 @@ GRID_LIMITS: {
457
457
  **Parameters:**
458
458
  - `GRID_REGENERATION_PERCENTAGE`: Bidirectional threshold for size recalculation (default: `3%`)
459
459
  - Grow: free funds accumulate to ≥3% of allocated capital (e.g. availableFunds ≥ 60 BTS on a 2000 BTS grid)
460
+ - Grow (committed drift): the on-chain (ACTIVE/PARTIAL) orders lag their geometric ideal by ≥3% of the committed size — catches an external deposit that the fill/rotation pipeline already folded into `virtual`, which blinds the `availableFunds = chainFree − virtual` ratio
460
461
  - Shrink: grid-tracked size (ACTIVE + PARTIAL + VIRTUAL) exceeds allocation by ≥3% (external fund removal resizes affected orders down; per-side chain totals are not used — fills move value across sides)
462
+ - Shrink (committed drift): the on-chain orders exceed their geometric ideal by ≥3% of the committed size (external withdrawal)
461
463
 
462
464
  ### How It Works
463
465
 
464
466
  1. **OrderManager** tracks available funds per side (BUY and SELL separately)
465
467
  2. Allocated capital = number of active orders × size per order
466
- 3. When `availableFunds / allocatedCapital × 100 >= GRID_REGENERATION_PERCENTAGE`:
468
+ 3. When `availableFunds / allocatedCapital × 100 >= GRID_REGENERATION_PERCENTAGE`, OR the committed-drift leg flags the side (on-chain orders ≥threshold off their geometric ideal):
467
469
  - Triggers `Grid.recalculateGrid()` on that side only
468
470
  - Recalculates order sizes to incorporate freed capital
469
471
  - Maintains asymmetric fills (BUY fills don't trigger SELL resize)
472
+ - The committed-drift leg is what keeps a deposit that was absorbed into the VIRTUAL reservation from silently leaving the on-chain side un-resized
470
473
  4. After the resize, available funds are re-allocated into active orders
471
474
  5. Mirror (shrink): when `(gridTracked - allocated) / allocated × 100 >= threshold` (external fund removal), the same path resizes affected orders down
472
475
 
@@ -26,7 +26,7 @@ Phase 1 does all reasoning in memory under `_gridLock` (fast); Phases 2 and 3 ex
26
26
 
27
27
  Phase 2 and 3 both respect the `dryRun` flag: when true, no on-chain mutations are attempted — plans are logged but not executed.
28
28
 
29
- `targetCount` (per side, `targetSell`/`targetBuy`) is sourced from bot config (`activeOrders` window plus `reserveOrders` edge ladder) and determines how many live orders each side should maintain. The internal `planOnly` flag controls whether `_reconcileStartupSide` records plans for Phase 2 or executes inline — Phase 1 always calls with `planOnly=true`.
29
+ `targetCount` (per side, `targetSell`/`targetBuy`) is sourced from bot config (`coreOrders` window plus `edgeOrders` edge ladder) and determines how many live orders each side should maintain. The internal `planOnly` flag controls whether `_reconcileStartupSide` records plans for Phase 2 or executes inline — Phase 1 always calls with `planOnly=true`.
30
30
 
31
31
  ```
32
32
  Grid generated
@@ -93,7 +93,7 @@ Phase 2 and 3 both respect the `dryRun` flag: when true, no on-chain mutations a
93
93
  - Match sorted unmatched chain orders to virtual slots → `plannedUpdates`
94
94
  - Detect grid-edge lock and plan a largest-order cancel
95
95
  - Plan creates for remaining slots
96
- - Plan excess cancellations (guarded by `matchedOnGrid > 0`): orphans first, then **matched surplus** (`chainCount - targetCount`, reserve edge slots last) — the matched-excess selection is shared by the planOnly and execute branches so planning can never drift from execution; planOnly omits `releaseUntrackedFunds` for matched slots (their funds are tracked on the grid slot)
96
+ - Plan excess cancellations (guarded by `matchedOnGrid > 0`): orphans first, then **matched surplus** (`chainCount - targetCount`, edge slots last) — the matched-excess selection is shared by the planOnly and execute branches so planning can never drift from execution; planOnly omits `releaseUntrackedFunds` for matched slots (their funds are tracked on the grid slot)
97
97
  - Fork-kept **shelf orders** (live non-slot-N ids below the rail, e.g. `deep-*`) are never cancel candidates or reserve members — see [Shelf Orders](#shelf-orders-fork-kept-manual-orders)
98
98
  - **Vacated-rail refill**: each PROCEEDING update whose vacated price exactly matches (`priceSlotEqual`) an empty, sized, in-rail slot of the same side queues a refill CREATE in the same plan (`source startupVacatedRailRefill`) — skipped updates, ghost prices (lattice moved), in-band slots, and already-desired slots never refill; refill targets require VIRTUAL state with no `orderId`
99
99
 
@@ -213,7 +213,7 @@ Reconcile's role in the defense-in-depth: during Phase 1, any ACTIVE/PARTIAL ord
213
213
 
214
214
  Live on-chain orders with non-slot-N ids below the rail (e.g. `deep-*` manuals kept across a fork) are **shelf orders**: they sit outside the grid contract and must survive every startup path untouched. Three gates enforce this (all no-ops on grids that only mint slot-N ids):
215
215
 
216
- - **Reserve classification/placement** (`order.ts`, `grid_reconcile_internal.ts`, `manager.ts`): `reserveEdgeIdSet`, the Tier-2 live-anchor scan, `_pickEdgeReserveSlots`, and `pickEdgeReserves` all gate to `parseSlotIndex(id) !== null`, so a shelf can never count as the reserve edge (which would mask a real reserve deficit) nor be activated as a reserve it would never be counted as. The live-reserve count additionally excludes window members via `liveWindowIdSet`, so an edge-reaching window cannot masquerade as dedicated reserves.
216
+ - **Reserve classification/placement** (`order.ts`, `grid_reconcile_internal.ts`, `manager.ts`): `edgeOrderIdSet`, the Tier-2 live-anchor scan, `_pickEdgeSlots`, and `pickEdgeSlots` all gate to `parseSlotIndex(id) !== null`, so a shelf can never count as the edge (which would mask a real edge deficit) nor be activated as an edge order it would never be counted as. The live-edge count additionally excludes window members via `liveWindowIdSet`, so an edge-reaching window cannot masquerade as dedicated edge orders.
217
217
  - **Startup excess cancels** (`grid_reconcile_internal.ts`): the matched-excess selection filters to slot-N ids in both planOnly and execute branches — the cheapest-first sort would otherwise wipe the shelf on the next boot.
218
218
  - **Geometric size recalc** (`grid.ts`): `_recalculateGridOrderSizesFromBlockchain` skips non-slot-N slots in the per-slot loop, so divergence-triggered resizing never overwrites manual shelf sizes on-chain (the shelf stays in the budget denominator, so allocation math is unchanged).
219
219
 
@@ -286,7 +286,7 @@ Commit `e64db685` replaced 6 single-value boolean state fields with refcounts/st
286
286
  | `tests/test_race_condition_fixes_batch1.ts` | ABBA deadlock (RC-1B) |
287
287
  | `tests/test_async_lock_force_release.ts` | Nested multi-lock re-entrancy |
288
288
  | `tests/test_targeted_drift_reconcile.ts` | Active-order shortfall triggers sync |
289
- | `tests/test_reserve_orders.ts` | Reserve startup coverage: fully-placed matched-surplus cancels, orphan+matched ordering, at-target silence, plan/execute parity, shelf-order survival, reserve-deficit trigger (`buy reserves 0/2`) with filled/disabled/empty-budget silence, window-exclusion counting |
289
+ | `tests/test_edge_orders.ts` | Reserve startup coverage: fully-placed matched-surplus cancels, orphan+matched ordering, at-target silence, plan/execute parity, shelf-order survival, reserve-deficit trigger (`buy reserves 0/2`) with filled/disabled/empty-budget silence, window-exclusion counting |
290
290
  | `tests/repro_phantom_orders.ts` | Phantom order prevention |
291
291
 
292
292
  ---
package/docs/LIFECYCLE.md CHANGED
@@ -90,7 +90,7 @@ sequenceDiagram
90
90
  participant CO as chain_orders (broadcast)
91
91
  participant STORE as Storage
92
92
 
93
- CH->>Q: enqueue fill(s) (dexbot_fill_runtime.ts:458)
93
+ CH->>Q: enqueue fill(s) (dexbot_fill_runtime.ts:466)
94
94
  FR->>FR: drain queue -> _processFillsWithBatching
95
95
  FR->>OM: processFilledOrders() (manager.ts)
96
96
  OM->>AC: processFillAccounting() (single call, batch)
@@ -134,10 +134,10 @@ sequenceDiagram
134
134
  participant STORE as Storage
135
135
 
136
136
  MA->>CL: AMA center snapshot updated
137
- CL->>CL: _performPeriodicGridChecks() (dexbot_class.ts:1685)
138
- CL->>RT: performPeriodicGridChecks() (dexbot_maintenance_runtime.ts:1645)
139
- RT->>RT: runGridMaintenance(bot,'periodic') (dexbot_maintenance_runtime.ts:2944)
140
- RT->>RT: executeMaintenanceLogic() (dexbot_maintenance_runtime.ts:2443)
137
+ CL->>CL: _performPeriodicGridChecks() (dexbot_class.ts:1720)
138
+ CL->>RT: performPeriodicGridChecks() (dexbot_maintenance_runtime.ts:1677)
139
+ RT->>RT: runGridMaintenance(bot,'periodic') (dexbot_maintenance_runtime.ts:2953)
140
+ RT->>RT: executeMaintenanceLogic() (dexbot_maintenance_runtime.ts:2462)
141
141
  RT->>AC: recalculate funds from balances
142
142
  RT->>GD: promote AMA center -> grid center
143
143
  RT->>GD: recalculateGrid() (grid.ts)
@@ -157,13 +157,13 @@ The AMA signal stack (AMA/Kalman/Hurst/PE) is *research-tuned* in `analysis/` an
157
157
  the parameters.
158
158
 
159
159
  > Note: `runMaintenance()` is a **different** subsystem — the credit/MPA debt
160
- > runtime (`modules/credit_runtime.ts:3468`, reached via
161
- > `_runCreditRuntimeMaintenance` at `dexbot_class.ts:1802`). The grid maintenance
160
+ > runtime (`modules/credit_runtime.ts:3441`, reached via
161
+ > `_runCreditRuntimeMaintenance` at `dexbot_class.ts:1837`). The grid maintenance
162
162
  > chain above is the one that matters for order/price upkeep.
163
163
 
164
- References: `modules/dexbot_class.ts:1685` (`_performPeriodicGridChecks`) →
165
- `modules/dexbot_maintenance_runtime.ts:1645` (`performPeriodicGridChecks`) →
166
- `:2944` (`runGridMaintenance`) → `:2443` (`executeMaintenanceLogic`),
164
+ References: `modules/dexbot_class.ts:1720` (`_performPeriodicGridChecks`) →
165
+ `modules/dexbot_maintenance_runtime.ts:1677` (`performPeriodicGridChecks`) →
166
+ `:2953` (`runGridMaintenance`) → `:2462` (`executeMaintenanceLogic`),
167
167
  `docs/GRID_RECALCULATION.md`, `docs/GRID_RECONCILE.md`.
168
168
 
169
169
  ---
@@ -192,7 +192,7 @@ enforced*, not compiler-enforced — learn them or you will introduce fund bugs.
192
192
  | How a fill becomes orders | `modules/dexbot_fill_runtime.ts` → `modules/order/manager.ts` |
193
193
  | Grid math / recalculation | `modules/order/grid.ts`, `docs/GRID_RECALCULATION.md` |
194
194
  | Funds & accounting | `modules/order/accounting.ts`, `docs/FUND_MOVEMENT_AND_ACCOUNTING.md` |
195
- | Periodic loop & AMA hook | `modules/dexbot_maintenance_runtime.ts`, `modules/dexbot_class.ts:1685` |
195
+ | Periodic loop & AMA hook | `modules/dexbot_maintenance_runtime.ts`, `modules/dexbot_class.ts:1720` |
196
196
  | Market signal source | `market_adapter/market_adapter.ts`, `analysis/README.md` |
197
197
  | Startup & orchestration | `modules/dexbot_class.ts`, `docs/developer_guide.md` §"Startup Sequence" |
198
198
  | Why COW exists | `docs/architecture.md` §"Copy-on-Write (COW) Grid Pattern", `docs/COW_INVARIANTS.md` |
package/docs/LOGGING.md CHANGED
@@ -248,13 +248,16 @@ Prefix tags used in log messages to help operators identify event types. To find
248
248
  | `[TARGETED-SYNC]` | `dexbot_maintenance_runtime.ts` | Targeted drift synchronization deferral |
249
249
  | `[MULTI-BOT]` | `chain_orders.ts` | Multi-bot shared-account coordination |
250
250
  | `[BTS-FEE]` | `order/accounting.ts` | BTS fee deferred accounting |
251
- | `[SPREAD-CORRECTION]` | `order/grid.ts` | Partial order spread correction |
251
+ | `[SPREAD-CORRECTION]` | `order/grid.ts` | Spread correction, plan-time CREATE dedupe, and bounded fresh-master re-plan |
252
252
  | `[STRATEGY]` | `order/strategy.ts` | Fee event cache and strategy decisions |
253
253
  | `[RECONCILE]` | `order/utils/validate.ts` | Grid reconciliation ([GRID_RECONCILE.md](GRID_RECONCILE.md)) |
254
254
  | `[RMS]` | `order/grid.ts`, `dexbot_maintenance_runtime.ts` | RMS structural-divergence checks: per-side `metric vs threshold → TRIGGER-RESYNC/no trigger` at `debug` (plus a `checks disabled` variant when the threshold is 0), reset line with threshold + breaching sides at `info` |
255
255
  | `[GAP-EVAC]` | `order/utils/validate.ts`, `order/manager.ts`, `dexbot_startup_runtime.ts`, `dexbot_state_recovery.ts` | Stuck in-band (gap-band) order streak warnings, cancel-only evacuation teeth, persisted-streak restore counts |
256
256
  | `[GRID-TYPE-CORRECT]` | `order/grid.ts` | One-time backfill retype of legacy empty slots to rail-typed holes on load |
257
257
  | `[LAST-FILL-GUARD]` | `dexbot_cow_runtime.ts` | Last-fill-guard blocks plus gap-evacuation bypass allows/stale-stamp downgrades |
258
+ | `[RESTAMP-BUY]` | `dexbot_cow_runtime.ts` | BUY emitted at/above the last filled BUY pivot (guard bypass / unjudgeable pivot), counted not blocked (P2) |
259
+ | `[COW-GAP-BAND]` | `dexbot_cow_runtime.ts` | SHADOW: non-spread-correction placement inside the plan gap band, counted not blocked (Mode C(a)) |
260
+ | `[BOUNDARY-DRIFT]` | `order/strategy.ts` | Derived boundary jumped more than the active window in one plan (P2) |
258
261
  | `[TRANSPORT]` | `bitshares-native/transport.ts` | WebSocket keep-alive and reconnect |
259
262
 
260
263
  ## 1.4.8 Markers
@@ -281,6 +284,32 @@ New/updated operator-visible messages added by the uncertain-broadcast and COW h
281
284
  | `⚠ <node>… FAILED attempt N/3 (fill channel unrecoverable for <account>: …)` | **Node strike recorded.** Emitted only after N forced reconnects failed to clear the channel, i.e. the node itself is suspect. A forced reconnect on its own never costs a node a strike — a session-level wedge that clears on the first cycle leaves the strike ledger untouched. Three of these blacklist the node for 24h |
282
285
  | `Forcing reconnect on <node> (<reason>)` | Transport-level forced reconnect (stale api_id escalation or fill-channel watchdog); the node is reported failed so the reconnect prefers another node |
283
286
 
287
+ ### P2 observability + Mode C (2026-10-11)
288
+
289
+ Counter-only signals (none gate placement) surfaced through `getMetrics()`: `refusedCommitCount`, `orphanFillCreditedCount`, `restampBuyAboveAnchorCount`, `boundaryDriftExceedsWindowCount`, `gapBandPlacementShadowCount`.
290
+
291
+ | Message | Meaning |
292
+ |---------|---------|
293
+ | `[COW] Rejecting UPDATE batch pre-broadcast: N target(s) missing on chain (...); grid/chain existence divergence — structural resync required` | Mode C(b): a tracked UPDATE target is gone on chain; the batch aborts cleanly (`UPDATE_TARGET_MISSING`) instead of letting `limit_order_update` abort a chunk mid-broadcast. Followed by a structural resync request |
294
+ | `[RESTAMP-BUY] BUY emitted at ... at/above the last filled BUY ...` | A BUY at/above the last filled BUY pivot got past the LAST-FILL-GUARD (bypass or unjudgeable pivot). Counted, not blocked; warned once per batch |
295
+ | `[COW-GAP-BAND] shadow: N non-spread-correction placement(s) inside the plan's gap band (...)` | Mode C(a) shadow: an in-gap rail placement that is not spread correction / gap evacuation. Counted, never blocked; warned once per batch |
296
+ | `[BOUNDARY-DRIFT] committed boundary X -> planned Y (drift N slots) exceeds active window W; boundary is detached from the market anchor (observability only)` | A single plan moved the boundary more than the active window (absolute recovery anchor or geometry fault). Counted; rate-limited warn |
297
+
298
+ ### Spread-correction resilience
299
+
300
+ Counter-only signals (none gate placement) surfaced through `getMetrics()`:
301
+ `spreadCorrectionRefusedCount` (all refusals), `spreadCorrectionRefusalCauses`
302
+ (per-`SPREAD_CORRECTION_REFUSAL` cause), and `spreadCorrectionRetryCount` (bounded
303
+ re-plan retries). Kept separate from the generic `refusedCommitCount`.
304
+
305
+ | Message | Meaning |
306
+ |---------|---------|
307
+ | `[SPREAD-CORRECTION] Plan-time dedupe: N planned slot(s) occupied since planning (...); re-planning from fresh master` | A planned CREATE destination was taken after planning; the plan is re-derived from fresh master |
308
+ | `[SPREAD-CORRECTION] Plan-time dedupe: ...; no re-plan candidate — refusing this cycle` | Collision detected but no fresh candidate exists; the colliding plan is withheld (never broadcast) |
309
+ | `[SPREAD-CORRECTION] Batch refused (cause); re-planning from fresh master (attempt 2/2)` | Transient refusal; the bounded fresh-master re-plan is in progress |
310
+ | `Spread correction batch was prepared but not executed. Keeping local state unchanged. (cause=...)` | Terminal refusal; `cause` is the classified `SPREAD_CORRECTION_REFUSAL` value |
311
+ | `Shutdown complete. Final metrics: ... spreadCorrectionRefusals=N [cause=count, ...], spreadCorrectionRetries=M` | Refusal breakdown on shutdown; the suffix appears only when at least one refusal occurred |
312
+
284
313
  ---
285
314
 
286
315
  ## Fill History Scan Profiling
@@ -73,7 +73,7 @@ Add `debtPolicy` to a bot entry in `profiles/bots.json`:
73
73
 
74
74
  ### Field Reference
75
75
 
76
- <details><summary>All config fields (click to expand)</summary>
76
+ <details><summary><mark>All config fields (click to expand)</mark></summary>
77
77
 
78
78
  **Required Fields:**
79
79
 
@@ -118,6 +118,7 @@ Add `debtPolicy` to a bot entry in `profiles/bots.json`:
118
118
  | `allowedOfferIds` | `string[]` | No | Whitelist of credit offer object IDs (1.21.x) the bot may accept. |
119
119
  | `disallowedDealIds` | `string[]` | No | Denylist of credit deal object IDs (1.22.x) the bot must not reborrow from. Repay is unaffected — the bot can still repay deals in this list. |
120
120
  | `renewOnly` | `boolean` | No | If `true`, the bot only reborrows existing deals — standalone credit borrows are refused. Default `false`. |
121
+ | `useFreeCollateral` | `boolean` | No | Defaults to `true`: a renewal locks the borrower's free balance of the collateral asset in addition to the collateral the repay released, so the reborrow can keep the original principal when the offer's collateral price moved. Set to `false` to opt out and cap each reborrow to the released collateral only. |
121
122
  | `minDurationSeconds` | `number` | No | Minimum acceptable offer duration in seconds. Offers with `duration_seconds` below this value are skipped. |
122
123
 
123
124
  **Global Fields:**
@@ -139,7 +140,7 @@ Set `creditOnly: true` on a bot entry to run only the credit runtime — no grid
139
140
  "preferredAccount": "my-account", "debtPolicy": { "lending": [...] } }
140
141
  ```
141
142
 
142
- No trading fields (`assetA`, `assetB`, `startPrice`, `incrementPercent`, `activeOrders`, `reserveOrders`, `botFunds`) are needed.
143
+ No trading fields (`assetA`, `assetB`, `startPrice`, `incrementPercent`, `coreOrders`, `edgeOrders`, `botFunds`) are needed.
143
144
 
144
145
  ```bash
145
146
  dexbot start credit # Background daemon — runs only the credit worker
@@ -277,11 +278,15 @@ The repay leg is funded from the borrower's *free* debt-asset balance before the
277
278
 
278
279
  The reborrow snapshots the pre-repay deal IDs, so the stale-entry guard only drops a request when a deal *appeared after* the repay on the same offer — sibling deals no longer block a legitimate reborrow.
279
280
 
280
- #### Collateral Shortfall Scaling
281
+ #### Collateral Top-Up and Shortfall Scaling
281
282
 
282
- A reborrow can only lock the collateral the repay just released. If the market moved against the collateral, the full debt needs more than the deal holds, so the runtime clamps the borrow to the released collateral rather than emit an op that fails the collateral check:
283
+ A reborrow starts from the collateral the repay just released. If the offer's collateral price moved, the full debt may need more collateral than the deal holds. By default (`useFreeCollateral: true`) the runtime adds the borrower's free balance of the same collateral asset to that budget, so the reborrow re-locks the original principal instead of shrinking. Set `useFreeCollateral: false` on the lending item to keep the legacy released-collateral-only ceiling and let the position deleverage on a price move.
284
+
285
+ The top-up stays within the position's `assignedCollateralBudget`, so it cannot take collateral allocated to sibling positions on a shared account. If the collateral asset is also a grid asset (for example BTS), the top-up locks funds the grid would otherwise have free — that is the intended trade-off of the feature.
283
286
 
284
287
  - `buildCreditOfferAcceptOperation` takes an optional raw `availableCollateralAmount` budget and shrinks the borrow to the maximum that budget can back at the offer price (`capBorrowToCollateral`). It lives in the shared builder, so original, fallback, and deferred reborrows all get it.
288
+ - With `useFreeCollateral: false`, only `floor(repay * collateral / debt)` from the repaid deal is available, so a price move against the collateral scales the borrow down. The free-balance read is skipped when the released collateral already backs the borrow at the current offer price.
289
+ - A deferred reborrow re-reads the current free balance and position budget on each retry, so its ceiling tracks the live state rather than a queue-time snapshot. The collateral-switch flow is the exception: its budget is the new asset's total balance, not freed collateral, so a retry reuses the stored value instead of adding the free balance again.
285
290
  - A clamped borrow below `min_deal_amount` is deferred and retried (up to `TIMING.CREDIT_REBORROW_MAX_ATTEMPTS`, default `6`) so a price recovery can revive it; after the limit it is dropped. The repay still proceeds, so the position deleverages.
286
291
  - The collateral-switch flow passes the new asset's balance as the budget.
287
292
  - Each accept records `requestedBorrowAmount` vs `borrowAmount` and `clampedByCollateral` in `lastBorrowRequest`.
@@ -300,7 +305,7 @@ You can switch a credit deal's collateral to a different asset on its next renew
300
305
 
301
306
  On each maintenance cycle, the runtime compares each deal's on-chain `auto_repay` against the policy's `autoRepay` value. If they differ, a `credit_deal_update` operation is broadcast. After a successful update, the local deal state is updated to prevent redundant broadcasts on the next cycle.
302
307
 
303
- <details><summary>BitShares auto-repay modes (click to expand)</summary>
308
+ <details><summary><mark>BitShares auto-repay modes (click to expand)</mark></summary>
304
309
 
305
310
  BitShares core 7.0.2 defines three auto-repay modes:
306
311
 
@@ -359,7 +364,7 @@ Treat this file as runtime state, not primary configuration. The source of truth
359
364
 
360
365
  ## Related Files
361
366
 
362
- <details><summary>Source files and tests (click to expand)</summary>
367
+ <details><summary><mark>Source files and tests (click to expand)</mark></summary>
363
368
 
364
369
  - `modules/credit_runtime.ts`: debt workflow executor (Phase 0 oversized-deal splitter lives here)
365
370
  - `modules/credit_pricing.ts`: canonical credit-pricing math (offer orientation, conversion rates, CR, fees) shared by runtime and analyzer