dexbot 1.6.14 → 1.6.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +34 -4
- package/analysis/README.md +6 -6
- package/analysis/tradingview/README.md +2 -1
- package/claw/README.md +7 -7
- package/claw/package.json +1 -1
- package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
- package/claw/runtimes/openclaw-plugin/package.json +1 -1
- package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +80 -6
- package/dist/analysis/trend_detection/dynamic_weight_chart_generator.js +36 -2
- package/dist/dexbot.js +23 -3
- package/dist/market_adapter/core/strategies/dynamic_weight_series.js +26 -11
- package/dist/modules/account_bots.d.ts +3 -0
- package/dist/modules/account_bots.js +3 -0
- package/dist/modules/bitshares-native/subscriptions.js +1 -1
- package/dist/modules/bot_defaults.d.ts +13 -2
- package/dist/modules/bot_defaults.js +31 -2
- package/dist/modules/bot_settings.js +3 -0
- package/dist/modules/constants.d.ts +6 -0
- package/dist/modules/constants.js +24 -0
- package/dist/modules/credit_runtime.d.ts +35 -5
- package/dist/modules/credit_runtime.js +219 -38
- package/dist/modules/dexbot_class.d.ts +19 -1
- package/dist/modules/dexbot_class.js +58 -20
- package/dist/modules/dexbot_cow_runtime.js +19 -18
- package/dist/modules/dexbot_fill_runtime.d.ts +1 -1
- package/dist/modules/dexbot_fill_runtime.js +4 -7
- package/dist/modules/dexbot_maintenance_runtime.d.ts +7 -2
- package/dist/modules/dexbot_maintenance_runtime.js +52 -7
- package/dist/modules/dexbot_startup_runtime.js +3 -2
- package/dist/modules/dexbot_state_recovery.js +1 -1
- package/dist/modules/order/export.js +2 -2
- package/dist/modules/order/grid.d.ts +118 -1
- package/dist/modules/order/grid.js +292 -50
- package/dist/modules/order/grid_reconcile.js +4 -3
- package/dist/modules/order/grid_reconcile_internal.js +13 -18
- package/dist/modules/order/index.d.ts +3 -1
- package/dist/modules/order/manager.d.ts +1 -0
- package/dist/modules/order/manager.js +5 -14
- package/dist/modules/order/sync_engine.js +18 -9
- package/dist/modules/order/utils/math.d.ts +98 -26
- package/dist/modules/order/utils/math.js +177 -57
- package/dist/modules/order/utils/order.js +16 -4
- package/dist/modules/order/utils/system.js +2 -2
- package/dist/modules/order/utils/validate.d.ts +1 -1
- package/dist/modules/order/utils/validate.js +48 -58
- package/dist/modules/types.d.ts +7 -0
- package/dist/scripts/analyze-credit.js +44 -27
- package/dist/scripts/diagnose-pool-history.js +35 -30
- package/dist/scripts/pnl.js +1 -1
- package/dist/scripts/rich_list.d.ts +18 -0
- package/dist/scripts/rich_list.js +461 -0
- package/dist/scripts/run-tests.js +80 -4
- package/dist/unlock.d.ts +2 -1
- package/dist/unlock.js +4 -3
- package/docs/COW_INVARIANTS.md +6 -0
- package/docs/DEXBOT_COMPARISON.md +6 -6
- package/docs/EVOLUTION.md +10 -9
- package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
- package/docs/LOGGING.md +16 -1
- package/docs/MPA_CREDIT_USAGE.md +10 -5
- package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +159 -9
- package/docs/README.md +1 -1
- package/docs/WORKFLOW.md +1 -0
- package/docs/architecture.md +56 -2
- package/docs/developer_guide.md +5 -1
- package/market_adapter/README.md +4 -4
- package/modules/README.md +1 -1
- package/package.json +2 -1
- package/scripts/README.md +59 -32
- package/tests/README.md +11 -2
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.
|
|
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,
|
|
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
|
|
12
|
-
- **Releases**:
|
|
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-
|
|
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,12 +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 |
|
|
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 |
|
|
175
176
|
|
|
176
177
|
---
|
|
177
178
|
|
|
178
179
|
**Report Originally Generated**: February 19, 2026
|
|
179
|
-
**Last Updated**: October
|
|
180
|
-
**Total Commits**: 2,
|
|
181
|
-
**Date Range**: December 2, 2025 – October
|
|
180
|
+
**Last Updated**: October 16, 2026
|
|
181
|
+
**Total Commits**: 2,411
|
|
182
|
+
**Date Range**: December 2, 2025 – October 16, 2026
|
|
182
183
|
**Repository**: DEXBot2 (BitShares DEX Trading Bot)
|
|
@@ -803,4 +803,4 @@ To prevent "Time-of-Check to Time-of-Use" errors:
|
|
|
803
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.
|
|
804
804
|
|
|
805
805
|
---
|
|
806
|
-
*Technical Reference for DEXBot2 v1.6.
|
|
806
|
+
*Technical Reference for DEXBot2 v1.6.15 release*
|
package/docs/LOGGING.md
CHANGED
|
@@ -248,7 +248,7 @@ 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` |
|
|
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` |
|
|
@@ -295,6 +295,21 @@ Counter-only signals (none gate placement) surfaced through `getMetrics()`: `ref
|
|
|
295
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
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
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
|
+
|
|
298
313
|
---
|
|
299
314
|
|
|
300
315
|
## Fill History Scan Profiling
|
package/docs/MPA_CREDIT_USAGE.md
CHANGED
|
@@ -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:**
|
|
@@ -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
|
|
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
|
|
@@ -4,14 +4,16 @@
|
|
|
4
4
|
> misbehaving (Part I) and the preserved **incident & fix ledger** (Part II), formerly
|
|
5
5
|
> `CONSOLIDATED_ORPHAN_FIX_SUMMARY.md`.
|
|
6
6
|
>
|
|
7
|
-
> **Sources:** `CHANGELOG.md` v1.0.0 → v1.6.
|
|
7
|
+
> **Sources:** `CHANGELOG.md` v1.0.0 → v1.6.14; `docs/GRID_PRICE_INVARIANT.md`;
|
|
8
8
|
> `docs/COW_INVARIANTS.md`. Generic terms only — no live markets, accounts, or order ids.
|
|
9
9
|
>
|
|
10
|
-
> **Scope / snapshot:** v1.0.0 → v1.6.
|
|
10
|
+
> **Scope / snapshot:** v1.0.0 → v1.6.14 (`f6c0df32`, 2026-10-12); the v1.6.4 → v1.6.14 arc
|
|
11
|
+
> is the §9 addendum below.
|
|
11
12
|
>
|
|
12
13
|
> **Section numbering:** Part II deliberately keeps its original `§0`–`§8` numbers because
|
|
13
|
-
> source-code comments and tests cite them (e.g. `… §2 fix #1`, `… §3 lineage`)
|
|
14
|
-
>
|
|
14
|
+
> source-code comments and tests cite them (e.g. `… §2 fix #1`, `… §3 lineage`); §9 is a
|
|
15
|
+
> later addendum (v1.6.4 → v1.6.14) that extends, and does not renumber, that range. Part I
|
|
16
|
+
> uses `R1`–`R5` so the two never collide. The closing appendix is unnumbered (`A`).
|
|
15
17
|
>
|
|
16
18
|
> **How to read:** start with **Part I** for the explanation; drop into **Part II** when you need
|
|
17
19
|
> the per-incident evidence, commit hashes, and verification targets.
|
|
@@ -41,6 +43,7 @@
|
|
|
41
43
|
- 6. Consolidated invariants
|
|
42
44
|
- 7. Consolidated verification — grid-correction check as regression gate
|
|
43
45
|
- 8. Provenance & supersession record
|
|
46
|
+
- 9. COW Broadcast, Resync & Geometry Safety (v1.6.4 → v1.6.14) — addendum
|
|
44
47
|
- A. Grid-Price Invariant — former failure trace (appendix)
|
|
45
48
|
|
|
46
49
|
---
|
|
@@ -102,6 +105,11 @@ notes; the grid-price invariant has its own doc — [GRID_PRICE_INVARIANT.md](GR
|
|
|
102
105
|
config, one authoritative set of counters.
|
|
103
106
|
- **Global last-fill guard + final pre-broadcast gate:** one pivot rule, enforced at the
|
|
104
107
|
last moment before broadcast, with fail-open semantics for unjudgeable ops.
|
|
108
|
+
- **Non-destructive recovery (v1.6.13+):** uncertain broadcasts and credential outages
|
|
109
|
+
*defer* instead of rebuilding the grid, so a reset stops being the reflex response to
|
|
110
|
+
ambiguity — see §9.1.
|
|
111
|
+
- **Fail-closed geometry (v1.6.14+):** an unknown boundary/gap is no longer coerced to a
|
|
112
|
+
valid-looking `0` — see §9.1.
|
|
105
113
|
|
|
106
114
|
The winning strategy was **removing writers and sources of truth**, not adding handlers.
|
|
107
115
|
|
|
@@ -115,6 +123,8 @@ The winning strategy was **removing writers and sources of truth**, not adding h
|
|
|
115
123
|
beats fail-closed alone.
|
|
116
124
|
5. Make deferred work **level-triggered** — never let a retry depend on a future event.
|
|
117
125
|
6. If a fix class keeps returning, the model is wrong, not the fix.
|
|
126
|
+
7. Treat **ambiguity as deferral, not destruction** — a reset that clears guard state is
|
|
127
|
+
another writer, and `Number(null) === 0` is how "unknown" becomes a confident `0`.
|
|
118
128
|
|
|
119
129
|
---
|
|
120
130
|
|
|
@@ -243,7 +253,7 @@ Falling market Aug 28 after ~17:00 UTC: bot **placed new SELLs below own live se
|
|
|
243
253
|
|
|
244
254
|
**Mode B — lag (stale boundary).** Aug 29 09:32 swept up through sell rail slots 147–158 → then `09:32:21 Placed sell slot-129 -> <order-1>` filled 250 ms later, `09:32:33 slot-131`, `09:32:42 slot-132` — 15–25 levels below rail; `ANCHOR-DIVERGENCE projected=138 bookkept=123 drift=15`. Boundary crawled down with falling-market buys, re-rolled slots 129–132 as SELL into rising market. One instant fill set `maxFilledSellPrice=1044.79`, guard caught later attempts `15:47` (1 slot below) and `17:27` (4+8 below 1099.37/1112.62). **What PRICE_FIRST Phase 2 fixes.**
|
|
245
255
|
|
|
246
|
-
**Mode C — COW commit geometry (separate).** Attribution corrected: `Batch transaction failed: Execution error: Order does not exist … cannot update` confirmed post-commit on bot-B: `<order-4>` `00:28:51 chunk1/3`, `<order-5>` `06:43:09 chunk5/9`, `<order-6>` `00:29:30` (`limit_order_update delta=-2341206 targets missing`). Broadcast refs missing orderId, aborts partial grid. `GAP-BAND VIOLATION after commit` = 0 in post-commit bot-A/B/C logs (evidence is bot-D `4` + D2 `11` dated Aug 26/28/29). Need: (a) COW rejects placement inside gap pre-broadcast; (b) pre-broadcast existence check off slot→orderId map. Gap case hardening independent.
|
|
256
|
+
**Mode C — COW commit geometry (separate).** Attribution corrected: `Batch transaction failed: Execution error: Order does not exist … cannot update` confirmed post-commit on bot-B: `<order-4>` `00:28:51 chunk1/3`, `<order-5>` `06:43:09 chunk5/9`, `<order-6>` `00:29:30` (`limit_order_update delta=-2341206 targets missing`). Broadcast refs missing orderId, aborts partial grid. `GAP-BAND VIOLATION after commit` = 0 in post-commit bot-A/B/C logs (evidence is bot-D `4` + D2 `11` dated Aug 26/28/29). Need: (a) COW rejects placement inside gap pre-broadcast; (b) pre-broadcast existence check off slot→orderId map. Gap case hardening independent. **Status: (b) LANDED `552b3ed7` (v1.6.14) as `UPDATE_TARGET_MISSING`; (a) deliberately shipped as a non-gating shadow (`gapBandPlacementShadowCount`) — see §9.2.**
|
|
247
257
|
|
|
248
258
|
**Mode D — boundary-evidence re-derivation not persisted (freeze).** `grid_reconcile.ts:359-502` re-derives corrected boundary via `manager._restoreBoundary (:380)` but didn't survive next resync; bot-A re-derived at *every* hourly resync: `117→118 (00:28:48)`, `118→119 (01:00)`, `118→115 (02:00)`, `118→114 (03:00,04:00)`, `118→115 (04:30,05:00)`, `122→119 (07:00)` — 8× identical `ERROR` in ~7h. Bot-C `NO_FEASIBLE_BOUNDARY` → adoption-only at `00:27:17, 00:31:12, 04:27:48`; after `04:27:48` placed **zero orders 04:27:48→07:15:27 (~2h48m)** — only fills + `[ORPHAN-FILL]`. Earlier freeze `00:31→00:54`. Resumed only via fill-driven rotation `07:15`. → Fix #5 (LANDED).
|
|
249
259
|
|
|
@@ -363,7 +373,12 @@ P2 additions (2026-10-11, counter-only — none gated behavior):
|
|
|
363
373
|
- `restampBuyAboveAnchorCount` — `recordRestampBuyAboveAnchor` counts a BUY emitted at/above the last filled BUY pivot (guard bypass or unjudgeable pivot), warned once per batch; it never blocks.
|
|
364
374
|
- `boundaryDriftExceedsWindowCount` — `calculateTargetGrid` counts a derived boundary that jumps more than the active window in one plan (the detached-boundary signal the removed ANCHOR-DIVERGENCE telemetry used to carry), rate-limited warn.
|
|
365
375
|
- `gapBandPlacementShadowCount` — the Mode C(a) shadow above.
|
|
366
|
-
|
|
376
|
+
|
|
377
|
+
Spread-correction additions (counter-only, written on `manager._metrics` by `order/grid.ts` because the planner has no bot reference):
|
|
378
|
+
- `spreadCorrectionRefusedCount` / `spreadCorrectionRefusalCauses` — every spread-correction batch that failed to land, plus the per-`SPREAD_CORRECTION_REFUSAL`-cause breakdown.
|
|
379
|
+
- `spreadCorrectionRetryCount` — bounded fresh-master re-plan retries after a transient refusal.
|
|
380
|
+
|
|
381
|
+
All eight surface through `getMetrics()`; the five baseline counters via the existing `...bot._metrics` spread, and the manager-owned set (`boundaryDriftExceedsWindowCount` plus the three spread counters) via the `managerOwnedCounters()` overlay in `dexbot_maintenance_runtime.ts`, because those engines write on the manager's metrics object and have no bot reference.
|
|
367
382
|
|
|
368
383
|
#### 3.4 Key code references (from source table)
|
|
369
384
|
|
|
@@ -444,7 +459,7 @@ Goal (Phase 2): I1–I6 property pass, full suite green, harness random, 48h per
|
|
|
444
459
|
4. **LADDER #2/#3** identity + update-first hardening. — *done (`4838bcb0`).*
|
|
445
460
|
5. **LADDER #5 / ORPHAN P0 recovery-by-ID** persistence (long freeze). — *done (`4838bcb0`, extended `a54863ca`; recovery-by-ID `1b27f6eb`).*
|
|
446
461
|
6. **ORPHAN P0 ID-based adoption** + **P1 atomicity** (stale-plan race). — *P0 done (`1b27f6eb`, retry `d808c052`); atomicity partial.*
|
|
447
|
-
7. **ORPHAN P1 rotation + P1 duplicate + GAP P3/P5 + Mode C guards + P2 guardrails** fast-follow. — *rotation + GAP P5 done; GAP P3 reverted `e7231534` (`validateBoundaryAgainstChainEvidence`/`placementsAllowed` removed);
|
|
462
|
+
7. **ORPHAN P1 rotation + P1 duplicate + GAP P3/P5 + Mode C guards + P2 guardrails** fast-follow. — *rotation + GAP P5 done; GAP P3 reverted `e7231534` (`validateBoundaryAgainstChainEvidence`/`placementsAllowed` removed); Mode C pre-broadcast UPDATE guard and P2 counters LANDED `552b3ed7` (§9.2); the in-gap reject ships as a shadow, not a block.*
|
|
448
463
|
8. **PRICE Phase 3/4** only after evidence (`grid_correction_check` see §7). If soak never clean, stop at Phase 2. — *Phase 3 moot; Phase 4 golden tests landed.*
|
|
449
464
|
|
|
450
465
|
---
|
|
@@ -474,7 +489,7 @@ Pairs-checked base excludes cross-pair unless flagged; strict sat-level detectio
|
|
|
474
489
|
- Shifted center → every live order adopted or immediate cancel (no silent unmanaged); startup reconcile replays: bot-A `<order-8>` 07:00 and `<order-9>` 6× loop must stay managed, no `ORPHAN-FILL`.
|
|
475
490
|
- Boundary re-derivation persists: bot-A `00:28–07:00` must not repeat `[BOUNDARY-EVIDENCE]` for unchanged chain.
|
|
476
491
|
- `NO_FEASIBLE_BOUNDARY` bot-C `04:27:48` resumes on next sync tick (bounded, not hours) with WARN.
|
|
477
|
-
- Post-broadcast read-back retry: bot-B `06:43` no `14` piled / forced resync mid-broadcast.
|
|
492
|
+
- Post-broadcast read-back retry: bot-B `06:43` no `14` piled / forced resync mid-broadcast. *(Addressed v1.6.13–1.6.14 by the resync-cascade break (`7eb65c8e`) and the fresh-placement cancel grace (`85a7e7f0`); see §9.)*
|
|
478
493
|
- COW commit never places inside gap; pre-broadcast existence check: bot-B `<order-4/5>` + bot-D/D2 `GAP-BAND` fixtures → `0`. *(Amended: the commit-time in-gap cancel sweep was reverted `e2898e51` — current expectation is adoption-after-chain-evidence-correction; `0` unmanaged in-gap orders remains the target.)*
|
|
479
494
|
- Aug 28 burst `17:09–17:16` (3 regs/6m, sells 1110–1176) → `0` orphans, `0` sells below asks.
|
|
480
495
|
- **Orphan regression over ~7h post-`cd690000` on bot-A/B/C:** distinct `Unmatched` `58/60/91 → ~0` (full `229/107/172 → ~0`), `Fund invariant violation` `0` (was `3077.07→3184.93` etc.), `ORPHAN-FILL` `0` (was `7/33/22`), repeated `[BOUNDARY-EVIDENCE]` `0`, deferred minutes `0`, `[MAINT] n/m failed` `0`.
|
|
@@ -490,7 +505,142 @@ Original doc regression excerpts preserved: GAP P6 A/B/C; LADDER §2.8 checks (1
|
|
|
490
505
|
- [x] No other doc/index lists the four (verified 2026-08-31); `analysis/README.md` documents the `grid_correction_check` tool.
|
|
491
506
|
- [x] Stale `*.md` filename references in code comments/tests updated to the consolidated doc (9 module files, 6 test files), then re-pointed to this hub when it absorbed the summary.
|
|
492
507
|
|
|
493
|
-
*Generated 2026-08-31 from the 4 test-only docs at their HEAD contents; statuses corrected against `test` HEAD `a54863ca` the same day, then refreshed against `1382f267` (2026-09-13). Landed/reverted/superseded annotations carry commit hashes where known; **line references in §§1-4 were re-verified at `a54863ca` and are subject to drift** — treat them as pointers, not assertions. The GRID-PRICE-INVARIANT guard is **BLOCKING** at all six emission sites (CREATE / UPDATE / CREATE-FALLBACK in `modules/dexbot_cow_runtime.ts`, RECONCILE-CREATE / RECONCILE-UPDATE / STARTUP-CREATE in `modules/order/grid_reconcile_internal.ts`): an off-grid emission is skipped, not merely counted, so a `violated>0` line means an emission was *prevented* rather than a writer merely *pinned*. Counters are still reported (`site=`, `checked=`, `violated=`, `unchecked=`) for observability — see `docs/GRID_PRICE_INVARIANT.md`.*
|
|
508
|
+
*Generated 2026-08-31 from the 4 test-only docs at their HEAD contents; statuses corrected against `test` HEAD `a54863ca` the same day, then refreshed against `1382f267` (2026-09-13) and extended through v1.6.14 at `f6c0df32` (2026-10-12; see §9). Landed/reverted/superseded annotations carry commit hashes where known; **line references in §§1-4 were re-verified at `a54863ca` and are subject to drift** — treat them as pointers, not assertions. The GRID-PRICE-INVARIANT guard is **BLOCKING** at all six emission sites (CREATE / UPDATE / CREATE-FALLBACK in `modules/dexbot_cow_runtime.ts`, RECONCILE-CREATE / RECONCILE-UPDATE / STARTUP-CREATE in `modules/order/grid_reconcile_internal.ts`): an off-grid emission is skipped, not merely counted, so a `violated>0` line means an emission was *prevented* rather than a writer merely *pinned*. Counters are still reported (`site=`, `checked=`, `violated=`, `unchecked=`) for observability — see `docs/GRID_PRICE_INVARIANT.md`.*
|
|
509
|
+
|
|
510
|
+
---
|
|
511
|
+
|
|
512
|
+
### 9. COW Broadcast, Resync & Geometry Safety (v1.6.4 → v1.6.14)
|
|
513
|
+
|
|
514
|
+
> **Source:** `CHANGELOG.md` v1.6.4 → v1.6.14 · **Snapshot:** `f6c0df32` (2026-10-12).
|
|
515
|
+
> Extends the §§1–8 ledger; the `§0`–`§8` numbers are unchanged (code and tests cite them).
|
|
516
|
+
|
|
517
|
+
Sections 1–4 end with the prevention sweeps reverted: a cancel sweep on ambiguous evidence
|
|
518
|
+
proved worse than the orphan it targets. The post-1.6.3 arc is the constructive inverse —
|
|
519
|
+
**stop the engine from destroying good state**, and **fail closed when geometry is unknown**.
|
|
520
|
+
|
|
521
|
+
#### 9.1 The synthesis: avoid the destructive resync
|
|
522
|
+
|
|
523
|
+
R4's fixes (genesis determinism, one writer, the last-fill guard) closed the *orphan* family.
|
|
524
|
+
The remaining harm was self-inflicted: **structural resyncs fired on evidence that did not
|
|
525
|
+
justify them**, and each reset clears the LAST-FILL-GUARD pivot and any gap-evacuation streak.
|
|
526
|
+
The engine now treats uncertainty as *defer, never rebuild*:
|
|
527
|
+
|
|
528
|
+
- **Uncertain-broadcast reconciliation is master-aware** (`7eb65c8e`, v1.6.13):
|
|
529
|
+
`resyncIfUnreconciled` treats a chain order as reconciled if master already tracks it
|
|
530
|
+
(`collectKnownOnChainOrderIds`), not merely if it appears in this batch's adopted set.
|
|
531
|
+
Before, a populated grid (`W` chain orders − `A` adopted ≫ 0) forced a full rebuild — and a
|
|
532
|
+
LAST-FILL pivot wipe — after *every* uncertain broadcast.
|
|
533
|
+
- **A suspended persistence is a deferral, not divergence** (`7eb65c8e`): a credential-daemon
|
|
534
|
+
outage (`persistGrid()` → `{skipped, suspended}`) marks the committed grid dirty for the
|
|
535
|
+
end-of-tick flush instead of escalating to a resync. The daemon watchdog also sets the
|
|
536
|
+
recovery flag that actually re-runs `resumeGridPersistence()` — previously a transient ping
|
|
537
|
+
timeout suspended persistence for hours and cascade-resynced the grid many times in one window.
|
|
538
|
+
- **Unknown geometry fails closed** (`5003b8ef`, `750386ac`, `dc87ce01`, `249016e4`, v1.6.14):
|
|
539
|
+
`Number(null) === 0` and `Number('') === 0` had made an unknown boundary/gap read as the
|
|
540
|
+
*valid* value `0`, casting real geometry around slot 0. `Format.toKnownNumber` keeps
|
|
541
|
+
`null`/`undefined`/`''` unknown (a genuine `0` stays `0`) across the gap-evacuation
|
|
542
|
+
candidates, `geometryTypeForSlotIndex`, evac stamping, `optimizeRebalanceActions`,
|
|
543
|
+
`planVacatedRailRefill`, `buildCowResultFromPlan`, the gap-band shadow and the guard
|
|
544
|
+
fallback; `validateBoundaryCommit` rejects every other non-numeric value (`'abc'`, `NaN`,
|
|
545
|
+
`Infinity`) as `non_integer_boundary` again (the 1.6.13 absent-aware rewrite had widened
|
|
546
|
+
"garbage" to "no proposal").
|
|
547
|
+
- **The LAST-FILL reference survives regeneration** (`09dbaad7`, `f1c331bd`, v1.6.14): a
|
|
548
|
+
bot-scoped last-market-fill row (price/type/fillsAt) is restored at startup under a 24h TTL,
|
|
549
|
+
so a `clearGrid()`/regeneration no longer wipes the anti-through-trade pivot.
|
|
550
|
+
`evaluateSpreadCorrectionReadiness()` is the single verdict (cold book = hard refuse; stale
|
|
551
|
+
snapshot/unmatched orders = plan-but-withhold-the-bypass), with the NEWER of a live
|
|
552
|
+
order-book/ticker read and the fill anchor as the crossing floor;
|
|
553
|
+
`SPREAD_CORRECTION_SYNC_FRESH_MS` is the one trust window.
|
|
554
|
+
|
|
555
|
+
#### 9.2 Pre-broadcast atomicity — Mode C now guarded (`552b3ed7`, v1.6.14)
|
|
556
|
+
|
|
557
|
+
Mode C (§2.3) is the `Order does not exist … cannot update` abort that leaves a partially
|
|
558
|
+
applied grid. Its pre-broadcast existence check — the second of Mode C's two "Need"s — is now
|
|
559
|
+
implemented in `runPreBroadcastGuards`: every UPDATE action's tracked `orderId` is re-read
|
|
560
|
+
(`batchReadOrders`), fail-open on a non-Map/errored read, then re-verified one by one
|
|
561
|
+
(`readSingleOrder`) so a lagging node cannot manufacture an absence. Any target still missing
|
|
562
|
+
aborts the whole batch (`UPDATE_TARGET_MISSING`), pops the working grid and requests a
|
|
563
|
+
structural resync — the divergence is refused *before* the wire, never half-applied.
|
|
564
|
+
|
|
565
|
+
Mode C's first "Need" (reject placement inside the gap band pre-broadcast) was deliberately
|
|
566
|
+
**not** implemented as a block: spread correction legitimately places into the band (that is
|
|
567
|
+
what the LAST-FILL-GUARD bypass is for), and a hard reject re-opens the P1 regression class.
|
|
568
|
+
It ships as an observability **shadow** (`gapBandPlacementShadowCount`, warned, never gating).
|
|
569
|
+
`COW_ORIGINS` (`eca90ce6`, v1.6.13) makes the bypass's `origin` keys a single frozen constant,
|
|
570
|
+
so a typo can no longer silently disable the spread-correction / gap-evacuation bypass.
|
|
571
|
+
|
|
572
|
+
#### 9.3 Don't churn orders the pipeline just placed
|
|
573
|
+
|
|
574
|
+
- **Fresh-placement cancel grace** (`85a7e7f0`, v1.6.12): `SURPLUS_CANCEL_GRACE_MS` (15 min)
|
|
575
|
+
timestamps placements (`_placedAt`) and surplus/cancel-only sweeps skip orders inside the
|
|
576
|
+
window (covering the batched and serial paths; `grid-load`/`grid-init` excluded so restarts
|
|
577
|
+
still sweep).
|
|
578
|
+
- **Spread correction repairs what it places** (`cd82cd8a`, v1.6.12): create-only, funded from
|
|
579
|
+
available balance; a distance-sorted windowed-rail ordering bridges contiguously from the
|
|
580
|
+
live window instead of leaving an interior hole. It tightens the spread rather than walking
|
|
581
|
+
to the rail edge (`67377d58`, v1.6.9) and is fund-driven (`589cb30e`, v1.6.4).
|
|
582
|
+
- **Committed-size drift resize** (`16308f72`, `d8a97f76`, v1.6.14): an external
|
|
583
|
+
deposit/withdrawal shifting a side's budget ≥3% resizes all of that side's on-chain orders
|
|
584
|
+
on the next pipeline-empty tick; the trigger is unified in `checkAndUpdateGridIfNeeded` so the
|
|
585
|
+
ratio legs cannot be consumed in isolation.
|
|
586
|
+
- **Orphan double-count pruned** (`1f272cee` v1.6.11, `073cceca` v1.6.12): slotless chain
|
|
587
|
+
orders are counted as committed funds, so adopting one *into* a slot must remove the stale
|
|
588
|
+
`_lastUnmatchedChainOrders` record; both success exits and the `createOrder` materialize
|
|
589
|
+
branch prune it by chain id.
|
|
590
|
+
|
|
591
|
+
#### 9.4 Removing writers — the genesis cleanup (`b2f4a65f`, v1.6.8)
|
|
592
|
+
|
|
593
|
+
Appendix A's writer chain is closed at the source: a persisted grid with no usable price
|
|
594
|
+
ladder is **refused** at load (`MissingGenesisError` before any mutation;
|
|
595
|
+
`MISSING_GENESIS_POLICY` `rebuild`/`halt`) instead of loading ladder-less and degrading every
|
|
596
|
+
slot-price consumer to a tolerance matcher. The legacy tolerance matcher,
|
|
597
|
+
`findMatchingGridOrderByOpenOrder`, the `price-drift-orphan` auto-cancel and the pass-1
|
|
598
|
+
price-equality / duplicate-swap tolerance fallbacks are deleted, and `syncFromOpenOrders` is
|
|
599
|
+
fail-closed behind `_assertGenesisInvariant`. This is R4's "removing writers and sources of
|
|
600
|
+
truth" carried to its end: the no-ladder state that Appendix A's `slot.price` corruption
|
|
601
|
+
required is no longer reachable at runtime.
|
|
602
|
+
|
|
603
|
+
#### 9.5 Ledger (order-engine commits, v1.6.4 → v1.6.14)
|
|
604
|
+
|
|
605
|
+
| Commit | Release | Change |
|
|
606
|
+
|---|---|---|
|
|
607
|
+
| `589cb30e` | 1.6.4 | Spread correction purely fund-driven with a balance refresh fallback |
|
|
608
|
+
| `1f2fd7ae` | 1.6.4 | Fill/broadcast batch cap raised to `gapSlots + 1` |
|
|
609
|
+
| `f90c4b6c` | 1.6.4 | Include VIRTUAL orders in RMS structural divergence |
|
|
610
|
+
| `224f92ee` | 1.6.6 | Harden stale cancellation guards |
|
|
611
|
+
| `b14a1fc8` | 1.6.7 | Persist/restore the LAST-FILL-GUARD pivot with the grid snapshot |
|
|
612
|
+
| `cd6c15fb` | 1.6.7 | Fill-channel watchdog recovery and accounting |
|
|
613
|
+
| `8c4baa69` | 1.6.7 | Recover dead-but-open sessions; stop stale COW re-broadcasts |
|
|
614
|
+
| `b2f4a65f` | 1.6.8 | Refuse persisted grids with no usable price ladder (genesis policy) |
|
|
615
|
+
| `dbd86cc8` | 1.6.8 | Bound the correction drain by wall-clock; surface long grid-lock holds |
|
|
616
|
+
| `67377d58` | 1.6.9 | Spread correction tightens the spread instead of walking to the rail edge |
|
|
617
|
+
| `1f272cee` | 1.6.11 | Five order-engine/lifecycle fixes (orphan accounting, double-count, grace, …) |
|
|
618
|
+
| `85a7e7f0` | 1.6.12 | Defer cancels of freshly placed orders in COW reconcile/divergence |
|
|
619
|
+
| `073cceca` | 1.6.12 | Prune the deferred-orphan record when createOrder linkage binds the slot |
|
|
620
|
+
| `cd82cd8a` | 1.6.12 | Keep spread correction funded by repairing what it places |
|
|
621
|
+
| `7eb65c8e` | 1.6.13 | Break resync cascades; suspended persistence is a deferral |
|
|
622
|
+
| `edb53176` | 1.6.13 | Report spread-correction stall causes |
|
|
623
|
+
| `6480923c` | 1.6.13 | Sync with the chain on every spread-correction stall |
|
|
624
|
+
| `eca90ce6` | 1.6.13 | Centralize COW plan-origin labels in `COW_ORIGINS` |
|
|
625
|
+
| `09dbaad7` | 1.6.14 | Never let spread correction trade through the last real fill |
|
|
626
|
+
| `f1c331bd` | 1.6.14 | Single readiness gate + live market floor |
|
|
627
|
+
| `16308f72` | 1.6.14 | Resize the full side when a deposit slips past the fund ratio |
|
|
628
|
+
| `d8a97f76` | 1.6.14 | Harden committed-size drift; unify the fund trigger |
|
|
629
|
+
| `552b3ed7` | 1.6.14 | COW pre-broadcast UPDATE-target guard + P2 counters |
|
|
630
|
+
| `5003b8ef` | 1.6.14 | Guard unknown boundary/gap across gap-evacuation and COW shadow paths |
|
|
631
|
+
| `750386ac` | 1.6.14 | Guard unknown boundary in the gap-band shadow |
|
|
632
|
+
| `dc87ce01` | 1.6.14 | Close missed 1.6.13 regressions in absent geometry and the rebuild guard |
|
|
633
|
+
| `249016e4` | 1.6.14 | Keep `validateBoundaryCommit` fail-closed for garbage boundaries |
|
|
634
|
+
|
|
635
|
+
#### 9.6 Invariants added
|
|
636
|
+
|
|
637
|
+
- **Uncertainty defers, it does not rebuild:** a resync requires a chain order unknown to
|
|
638
|
+
master, a non-suspension persist divergence, or a proven pre-broadcast UPDATE-target gap.
|
|
639
|
+
- **Unknown geometry is unknown:** no code path may coerce absent boundary/gap to `0`.
|
|
640
|
+
- **Atomic-or-refused:** a COW batch either applies wholly on chain or is refused before the
|
|
641
|
+
wire; no `limit_order_update` may abort a chunk.
|
|
642
|
+
- **Placed is not surplus:** an order inside `SURPLUS_CANCEL_GRACE_MS` is never cancelled by a
|
|
643
|
+
sweep running on a stale snapshot.
|
|
494
644
|
|
|
495
645
|
---
|
|
496
646
|
|
package/docs/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
This directory contains the comprehensive technical documentation for the DEXBot2 trading bot. It is designed to guide developers from high-level architecture down to the nuances of fund accounting and state management.
|
|
4
4
|
|
|
5
|
-
**Version context:** v1.6.
|
|
5
|
+
**Version context:** v1.6.15 (released).
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
package/docs/WORKFLOW.md
CHANGED
|
@@ -252,6 +252,7 @@ the canonical name is preferred in scripts and docs.
|
|
|
252
252
|
| `dexbot order` | `orders` | Analyze persisted order grids (spread, increment, funds); `--export` for HTML |
|
|
253
253
|
| `dexbot order [<bot>]` | — | Analyze only the specified bot's order grid |
|
|
254
254
|
| `dexbot credit` | — | Live summed MPA + borrowed-credit positions per asset per bot (`[<bot>]`) |
|
|
255
|
+
| `dexbot rich <asset...>` | — | Top holder(s) per asset via the chain asset-holders API (`--top N`, `--json`/`--csv`) |
|
|
255
256
|
| `dexbot tv <target>` | — | TradingView 1h chart for `<bot|pool-id|AssetA/AssetB>` over `--month N` (default 3) |
|
|
256
257
|
| `dexbot dw <target>` | — | Dynamic-weight research chart: same targets/flags as `tv` |
|
|
257
258
|
| `dexbot pnl <account>` | — | HTML PnL report for a bot/account over `--month N`, optional `--pair BASE/QUOTE` filter |
|
package/docs/architecture.md
CHANGED
|
@@ -487,8 +487,9 @@ The correction path is fund-only and never manufactures budget by shrinking a re
|
|
|
487
487
|
5. If free funds cannot cover every target, place the affordable prefix, stop
|
|
488
488
|
without shrinking inventory, and log the fund-constrained remainder.
|
|
489
489
|
6. If neither side places an effective order, `checkSpreadCondition` reports a
|
|
490
|
-
`stall` cause (`no-free-funds` / `unfunded` / `no-candidates` /
|
|
491
|
-
`batch-not-executed` / `apply-error`).
|
|
490
|
+
`stall` cause (`no-free-funds` / `unfunded` / `no-candidates` / `cold-book` /
|
|
491
|
+
`unmatched-orders` / `readiness-gate` / `batch-not-executed` / `apply-error`).
|
|
492
|
+
Every cause arms the targeted
|
|
492
493
|
balances + open-orders refresh: the local snapshot the check reasoned over
|
|
493
494
|
may be stale (`no-candidates` can mean a missed fill left an ACTIVE slot
|
|
494
495
|
occupying the window edge, so no tightening slot appears to exist), and only
|
|
@@ -525,6 +526,59 @@ const availableFund = Math.max(0, Math.min(
|
|
|
525
526
|
- ✅ Funds always respected (no forced allocation)
|
|
526
527
|
- ✅ Natural smoothing over multiple rebalance cycles
|
|
527
528
|
|
|
529
|
+
### Resilience: Atomic Broadcast, Plan-Time Dedupe, Bounded Re-Plan
|
|
530
|
+
|
|
531
|
+
A correction is planned under `_gridLock` but broadcast *after* the lock is
|
|
532
|
+
released, so a concurrent fill rebalance can invalidate it in that window. Left
|
|
533
|
+
alone, the batch is refused fail-closed and the grid waits for a fill it cannot
|
|
534
|
+
produce (an out-of-spread grid generates no fill) — the stale-grid pathology.
|
|
535
|
+
`checkSpreadCondition` wraps the plan/broadcast in a bounded, region-held
|
|
536
|
+
attempt loop so a stale plan heals in place:
|
|
537
|
+
|
|
538
|
+
1. **Region hold (atomicity).** The refcounted broadcast region
|
|
539
|
+
(`startBroadcasting` / `stopBroadcasting`, released in `finally`) is held for
|
|
540
|
+
the whole attempt loop, so a fill rebalance defers instead of committing a
|
|
541
|
+
master-version bump between the plan and its broadcast. This narrows the
|
|
542
|
+
race; the COW commit guard remains the backstop.
|
|
543
|
+
2. **Plan-time CREATE dedupe.** Before broadcasting, `getOccupiedCorrectionSlots`
|
|
544
|
+
checks whether a planned destination became a live order since planning, and
|
|
545
|
+
`resolveOccupiedCorrection` re-derives from fresh master or withholds the
|
|
546
|
+
colliding batch. A known-taken slot is never shipped (the COW build layer is
|
|
547
|
+
still authoritative against a false positive).
|
|
548
|
+
3. **Bounded fresh-master re-plan.** On a **transient** refusal (stale plan /
|
|
549
|
+
duplicate CREATE / unclassified non-execution) the cycle re-plans once from
|
|
550
|
+
fresh master (`replanSpreadCorrectionFromFreshMaster`) and retries —
|
|
551
|
+
`TIMING.SPREAD_CORRECTION_MAX_ATTEMPTS` (default 2 = initial + one retry).
|
|
552
|
+
A **non-transient** refusal (commit-refused, update-target-missing, unmatched
|
|
553
|
+
chain orders, shutdown) is not retried and counts toward grid staleness.
|
|
554
|
+
4. **Observability.** `spreadCorrectionRefusedCount`, per-cause
|
|
555
|
+
`spreadCorrectionRefusalCauses` (vocabulary `SPREAD_CORRECTION_REFUSAL`), and
|
|
556
|
+
`spreadCorrectionRetryCount`, surfaced through `getMetrics()` and the shutdown
|
|
557
|
+
line separately from the generic `refusedCommitCount`.
|
|
558
|
+
|
|
559
|
+
**Retry invariant:** an `uncertain: true` COW result is retry-safe only while the
|
|
560
|
+
COW layer adopts-or-defers-with-guard into master before returning. The
|
|
561
|
+
adopt/discard path persists first; the ambiguous-read path keeps pending-broadcast
|
|
562
|
+
protection (the existing orderId build guard is the fail-safe, not fail-fast).
|
|
563
|
+
|
|
564
|
+
### Out-of-Spread Watchdog
|
|
565
|
+
|
|
566
|
+
Independent of the in-cycle retry, the maintenance watchdog (`trackOutOfSpreadStaleness`)
|
|
567
|
+
tracks how long the grid has been continuously out of tolerance **without an
|
|
568
|
+
effective correction**:
|
|
569
|
+
|
|
570
|
+
- warns once past `TIMING.SPREAD_STALE_WARN_MS`;
|
|
571
|
+
- escalates to a structural re-center past `TIMING.SPREAD_STALE_ESCALATE_MS`
|
|
572
|
+
(cooldown `TIMING.SPREAD_STALE_RESYNC_COOLDOWN_MS`);
|
|
573
|
+
- tolerates up to `TIMING.SPREAD_STALE_TRANSIENT_GRACE` consecutive **transient**
|
|
574
|
+
refusals (which reset the stale clock) before they count toward escalation, so a
|
|
575
|
+
retryable refusal is not mistaken for a structural dead end — a persistent one
|
|
576
|
+
still re-centers.
|
|
577
|
+
|
|
578
|
+
These spread knobs (with `SPREAD_CORRECTION_SYNC_FRESH_MS`) are global `TIMING`
|
|
579
|
+
keys, overridable under `TIMING` in `profiles/general.settings.json`; they are not
|
|
580
|
+
per-bot settings.
|
|
581
|
+
|
|
528
582
|
---
|
|
529
583
|
|
|
530
584
|
## Periodic Market Price Refresh
|
package/docs/developer_guide.md
CHANGED
|
@@ -111,7 +111,7 @@ A **phantom order** is an order in ACTIVE/PARTIAL state WITHOUT a valid `orderId
|
|
|
111
111
|
| **WorkingGrid** | Mutable clone of the master grid used during planning. Created by `new WorkingGrid(masterGrid)`. Discarded on failure; committed on success. Lives in `modules/order/working_grid.ts`. |
|
|
112
112
|
| **COW Rebalance** | The full plan→broadcast→commit cycle: `_applySafeRebalanceCOW()` → `_updateOrdersOnChainBatchCOW()` → `_commitWorkingGrid()` |
|
|
113
113
|
| **Atomic Commit** | `_commitWorkingGrid(workingGrid, indexes, boundary, options = {})` swaps master to the working copy in a single operation, then increments `_gridVersion`. |
|
|
114
|
-
| **Staleness / Version Mismatch** | If a fill mutates the master grid while a rebalance is in progress, the working grid is marked stale. The commit guard rejects stale or version-mismatched working grids. |
|
|
114
|
+
| **Staleness / Version Mismatch** | If a fill mutates the master grid while a rebalance is in progress, the working grid is marked stale. The commit guard rejects stale or version-mismatched working grids. Spread correction additionally holds the broadcast region across a bounded fresh-master re-plan ([architecture.md](architecture.md) → Spread Correction → Resilience). |
|
|
115
115
|
| **`_gridVersion`** | Integer counter incremented on every master-grid mutation. Used by commit guards to detect concurrent master changes. |
|
|
116
116
|
| **`_gridLock`** | `AsyncLock` that serializes all master-grid mutations to prevent races. |
|
|
117
117
|
| **`syncFromMaster()`** | WorkingGrid method that selectively syncs one order from the master into the working copy during fills, avoiding a full abort. |
|
|
@@ -787,6 +787,10 @@ checkAndUpdateGridIfNeeded(manager)
|
|
|
787
787
|
// checkAndUpdateGridIfNeeded above
|
|
788
788
|
checkCommittedSizeDrift(manager)
|
|
789
789
|
|
|
790
|
+
// Spread correction: plan-time dedupe + bounded fresh-master re-plan retry,
|
|
791
|
+
// wrapped in a held broadcast region (see architecture.md → Resilience)
|
|
792
|
+
checkSpreadCondition(manager, BitShares, batchCb)
|
|
793
|
+
|
|
790
794
|
// Compare ideal vs. persisted grid
|
|
791
795
|
compareGrids(calculatedGrid, persistedGrid, manager)
|
|
792
796
|
```
|
package/market_adapter/README.md
CHANGED
|
@@ -489,7 +489,7 @@ Per cycle, per processed bot, the adapter can produce:
|
|
|
489
489
|
|
|
490
490
|
### Files
|
|
491
491
|
|
|
492
|
-
<details><summary>Config and state files (click to expand)</summary>
|
|
492
|
+
<details><summary><mark>Config and state files (click to expand)</mark></summary>
|
|
493
493
|
|
|
494
494
|
| File | Purpose |
|
|
495
495
|
|------|---------|
|
|
@@ -574,7 +574,7 @@ Typical fields:
|
|
|
574
574
|
|
|
575
575
|
### Module Map
|
|
576
576
|
|
|
577
|
-
<details><summary>Directory layout (click to expand)</summary>
|
|
577
|
+
<details><summary><mark>Directory layout (click to expand)</mark></summary>
|
|
578
578
|
|
|
579
579
|
```text
|
|
580
580
|
market_adapter/
|
|
@@ -798,7 +798,7 @@ snapshot.
|
|
|
798
798
|
|
|
799
799
|
Main override knobs live in `profiles/market_adapter_settings.json`:
|
|
800
800
|
|
|
801
|
-
<details><summary>Full settings table (click to expand)</summary>
|
|
801
|
+
<details><summary><mark>Full settings table (click to expand)</mark></summary>
|
|
802
802
|
|
|
803
803
|
| Setting | Meaning |
|
|
804
804
|
|---------|---------|
|
|
@@ -987,7 +987,7 @@ removed manually.
|
|
|
987
987
|
|
|
988
988
|
Important fields in `market_adapter/state/market_adapter_state.json`:
|
|
989
989
|
|
|
990
|
-
<details><summary>Field reference (click to expand)</summary>
|
|
990
|
+
<details><summary><mark>Field reference (click to expand)</mark></summary>
|
|
991
991
|
|
|
992
992
|
| Field | Meaning |
|
|
993
993
|
|-------|---------|
|
package/modules/README.md
CHANGED
|
@@ -88,7 +88,7 @@ modules/
|
|
|
88
88
|
│
|
|
89
89
|
├── order/ order lifecycle and grid management
|
|
90
90
|
│ ├── manager.ts OrderManager — central controller, COW rebalance
|
|
91
|
-
│ ├── grid.ts grid generation, sizing, health
|
|
91
|
+
│ ├── grid.ts grid generation, sizing, spread correction, health
|
|
92
92
|
│ ├── working_grid.ts COW grid wrapper for safe mutations
|
|
93
93
|
│ ├── strategy.ts grid rebalancing, consolidation, rotation
|
|
94
94
|
│ ├── accounting.ts fund tracking, fee accounting
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dexbot",
|
|
3
|
-
"version": "1.6.
|
|
3
|
+
"version": "1.6.15",
|
|
4
4
|
"description": "The first open source trading bot with zero runtime dependencies and a fully adaptive market making strategy.",
|
|
5
5
|
"main": "dist/modules/dexbot_class.js",
|
|
6
6
|
"exports": {
|
|
@@ -98,6 +98,7 @@
|
|
|
98
98
|
"analysis:trade-pnl": "npm run build && node dist/analysis/trade_profitability.js",
|
|
99
99
|
"analysis:grid-check": "npm run build && node dist/analysis/grid_correction_check.js",
|
|
100
100
|
"analysis:resolve-accounts": "npm run build && node dist/analysis/resolve_bot_accounts.js",
|
|
101
|
+
"richlist": "npm run build && node dist/scripts/rich_list.js",
|
|
101
102
|
"native:release-gates": "npm run build && npm run build:tests && node dist/scripts/native_release_gates.js",
|
|
102
103
|
"native:serial-snapshots": "npm run build && npm run build:tests && node dist/tests/test_native_serial_ops.js",
|
|
103
104
|
"native:ecc-invariants": "npm run build && npm run build:tests && node dist/tests/test_native_ecc.js",
|