dexbot 1.6.14 → 1.6.16
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 +60 -4
- package/README.md +4 -4
- package/analysis/README.md +6 -6
- package/analysis/tradingview/README.md +2 -1
- package/claw/README.md +7 -7
- package/claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md +3 -2
- package/claw/modules/chain_queries.ts +3 -3
- 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/ama_fitting/fetch_lp_candles.js +8 -1
- package/dist/analysis/ama_fitting/optimizer_high_resolution.d.ts +50 -1
- package/dist/analysis/ama_fitting/optimizer_high_resolution.js +33 -7
- package/dist/analysis/bot_fitting/backtest_bot_fitting.d.ts +8 -6
- package/dist/analysis/bot_fitting/backtest_bot_fitting.js +8 -10
- package/dist/analysis/bot_key_utils.js +9 -7
- package/dist/analysis/chart_utils.d.ts +9 -2
- package/dist/analysis/chart_utils.js +51 -1
- package/dist/analysis/tradingview/tradingview_uplot_chart_generator.d.ts +2 -1
- package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +99 -11
- package/dist/analysis/trend_detection/dynamic_weight_chart_generator.js +57 -4
- package/dist/analysis/trend_detection/kalman_chart_generator.js +1 -0
- package/dist/analysis/trend_detection/regime_chart_generator.js +1 -1
- package/dist/analysis/trend_detection/volatility_chart_generator.js +1 -0
- package/dist/dexbot.js +112 -141
- package/dist/market_adapter/core/strategies/dynamic_weight_series.js +26 -11
- package/dist/market_adapter/inputs/fetch_book_data.js +36 -12
- package/dist/market_adapter/inputs/fetch_lp_data.d.ts +6 -0
- package/dist/market_adapter/inputs/fetch_lp_data.js +65 -19
- package/dist/market_adapter/inputs/kibana_feed_source.js +45 -12
- package/dist/market_adapter/inputs/window_cache.d.ts +14 -1
- package/dist/market_adapter/inputs/window_cache.js +53 -17
- package/dist/market_adapter/lp_chart_core.js +1 -0
- package/dist/market_adapter/utils/chain.js +4 -3
- package/dist/market_adapter/utils/pair_orientation.d.ts +60 -0
- package/dist/market_adapter/utils/pair_orientation.js +142 -0
- package/dist/modules/account_bots.d.ts +40 -3
- package/dist/modules/account_bots.js +80 -37
- package/dist/modules/account_orders.d.ts +4 -1
- package/dist/modules/account_orders.js +4 -1
- package/dist/modules/bitshares-native/resolvers.js +3 -3
- package/dist/modules/bitshares-native/subscriptions.js +1 -1
- package/dist/modules/bitshares_client.d.ts +12 -10
- package/dist/modules/bitshares_client.js +12 -10
- package/dist/modules/bot_defaults.d.ts +13 -2
- package/dist/modules/bot_defaults.js +31 -2
- package/dist/modules/bot_settings.js +6 -3
- package/dist/modules/chain_keys.d.ts +5 -1
- package/dist/modules/chain_keys.js +5 -1
- package/dist/modules/chain_orders.d.ts +6 -2
- package/dist/modules/chain_orders.js +6 -2
- package/dist/modules/constants.d.ts +11 -0
- package/dist/modules/constants.js +31 -1
- package/dist/modules/credit_runtime.d.ts +35 -5
- package/dist/modules/credit_runtime.js +219 -38
- package/dist/modules/dexbot_class.d.ts +22 -2
- package/dist/modules/dexbot_class.js +61 -21
- 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/graceful_shutdown.d.ts +6 -2
- package/dist/modules/graceful_shutdown.js +6 -2
- package/dist/modules/launcher/bot_supervisor.js +4 -0
- package/dist/modules/launcher/launch_modes.js +6 -3
- package/dist/modules/launcher/monolithic_runtime.d.ts +39 -1
- package/dist/modules/launcher/monolithic_runtime.js +60 -1
- package/dist/modules/launcher/runtime_mode.d.ts +79 -0
- package/dist/modules/launcher/runtime_mode.js +223 -0
- package/dist/modules/market_adapter_whitelist.d.ts +8 -0
- package/dist/modules/market_adapter_whitelist.js +8 -0
- package/dist/modules/order/accounting.d.ts +15 -1
- package/dist/modules/order/accounting.js +15 -1
- package/dist/modules/order/async_lock.d.ts +9 -3
- package/dist/modules/order/async_lock.js +9 -3
- package/dist/modules/order/export.d.ts +0 -5
- package/dist/modules/order/export.js +2 -7
- package/dist/modules/order/format.d.ts +6 -4
- package/dist/modules/order/format.js +6 -4
- package/dist/modules/order/grid.d.ts +147 -19
- package/dist/modules/order/grid.js +321 -68
- 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 +4 -2
- package/dist/modules/order/index.js +1 -1
- package/dist/modules/order/logger_state.d.ts +1 -1
- package/dist/modules/order/logger_state.js +1 -1
- package/dist/modules/order/manager.d.ts +1 -0
- package/dist/modules/order/manager.js +5 -14
- package/dist/modules/order/sync_engine.d.ts +26 -11
- package/dist/modules/order/sync_engine.js +44 -20
- package/dist/modules/order/utils/math.d.ts +157 -47
- package/dist/modules/order/utils/math.js +236 -78
- package/dist/modules/order/utils/order.d.ts +64 -20
- package/dist/modules/order/utils/order.js +80 -24
- package/dist/modules/order/utils/system.d.ts +41 -11
- package/dist/modules/order/utils/system.js +43 -13
- package/dist/modules/order/utils/validate.d.ts +6 -3
- package/dist/modules/order/utils/validate.js +53 -60
- package/dist/modules/types.d.ts +7 -0
- package/dist/modules/utils/asset_symbols.d.ts +5 -5
- package/dist/modules/utils/asset_symbols.js +5 -5
- package/dist/modules/utils/errors.d.ts +2 -1
- package/dist/modules/utils/errors.js +2 -1
- 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 +50 -0
- package/dist/scripts/rich_list.js +469 -0
- package/dist/scripts/run-tests.js +80 -4
- package/dist/unlock.d.ts +2 -1
- package/dist/unlock.js +53 -21
- package/docs/BITSHARES_ONBOARDING.md +7 -0
- package/docs/COW_INVARIANTS.md +7 -1
- package/docs/DEXBOT_COMPARISON.md +6 -6
- package/docs/EVOLUTION.md +11 -9
- package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +3 -3
- package/docs/GRID_RECALCULATION.md +18 -6
- package/docs/LIFECYCLE.md +8 -8
- package/docs/LOGGING.md +16 -1
- package/docs/MPA_CREDIT_USAGE.md +10 -5
- package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +163 -13
- package/docs/README.md +1 -1
- package/docs/WORKFLOW.md +6 -5
- package/docs/architecture.md +56 -2
- package/docs/developer_guide.md +5 -1
- package/market_adapter/README.md +14 -7
- package/modules/README.md +1 -1
- package/package.json +4 -1
- package/scripts/README.md +59 -32
- package/tests/README.md +40 -2
|
@@ -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
|
|
|
@@ -147,7 +157,7 @@ plans, `LANDED`/`REVERTED`/`SUPERSEDED` statuses, commit hashes, and verificatio
|
|
|
147
157
|
|
|
148
158
|
### 1. Gap-Band Orphan — Prevention Plan (P1–P6)
|
|
149
159
|
|
|
150
|
-
> **Source:** `GAP_BAND_ORPHAN_PREVENTION_PLAN.md` · **Status:** implemented `f94d6ec4` (2026-08-29), with subsequent amendments — landing map below.
|
|
160
|
+
> **Source:** former `GAP_BAND_ORPHAN_PREVENTION_PLAN.md` (deleted 2026-08-31; merged here) · **Status:** implemented `f94d6ec4` (2026-08-29), with subsequent amendments — landing map below.
|
|
151
161
|
|
|
152
162
|
**Landing map (corrected 2026-08-31):**
|
|
153
163
|
- **P1** — landed `f94d6ec4` (same-batch CANCEL injection in `COWRebalanceEngine.execute` + `_assertGapBandIntactPostCommit` cancelOnly). **REVERTED `e2898e51`** ("remove placement guards that interfered with normal operation") — both sites removed; stranding is now handled by `calculateIdealBoundary` + `LAST-FILL-GUARD` + adoption path (P3 gate removed `e7231534`).
|
|
@@ -216,7 +226,7 @@ Sequence `Restored boundary index: 131` *then* `[SNAPSHOT-REJECT] Deleting corru
|
|
|
216
226
|
|
|
217
227
|
### 2. Ladder Recenter Orphan — Root Cause (Aug 26–30 2026)
|
|
218
228
|
|
|
219
|
-
> **Source:** `LADDER_RECENTER_ORPHAN_ROOT_CAUSE.md` · **Status:** fixes #1–#7 landed 2026-08-30.
|
|
229
|
+
> **Source:** former `LADDER_RECENTER_ORPHAN_ROOT_CAUSE.md` (deleted 2026-08-31; merged here) · **Status:** fixes #1–#7 landed 2026-08-30.
|
|
220
230
|
|
|
221
231
|
#### 2.1 Symptom
|
|
222
232
|
|
|
@@ -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
|
|
|
@@ -307,7 +317,7 @@ Throttle `Structural resync defer` to first/last per cap window (was 120/30s); l
|
|
|
307
317
|
|
|
308
318
|
### 3. Orphan-Fill & Fund-Invariant — Root Cause & Fix Plan
|
|
309
319
|
|
|
310
|
-
> **Source:** `ORPHAN_FILL_INVARIANT_ROOT_CAUSE_AND_FIX.md` · **Status:** P0s + rotation landed `1b27f6eb`/`4838bcb0`/`d808c052`; P1 atomicity partial; duplicate-cancel hard-error and P2 counters still open.
|
|
320
|
+
> **Source:** former `ORPHAN_FILL_INVARIANT_ROOT_CAUSE_AND_FIX.md` (deleted 2026-08-31; merged here) · **Status:** P0s + rotation landed `1b27f6eb`/`4838bcb0`/`d808c052`; P1 atomicity partial; duplicate-cancel hard-error and P2 counters still open.
|
|
311
321
|
> **Scope:** `dexbot_cow_runtime.ts`, `sync_engine.ts`, `chain_orders.ts`, `dexbot_state_recovery.ts`, `dexbot_maintenance_runtime.ts`, `strategy.ts`, `constants.ts` · **Evidence:** `profiles/logs/<bot>.log` Aug 28 17:40–17:57, Aug 29 15:13–15:19.
|
|
312
322
|
|
|
313
323
|
#### 3.1 TL;DR — one cascade
|
|
@@ -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
|
|
|
@@ -373,7 +388,7 @@ All five surface through `getMetrics()`; four via the existing `...bot._metrics`
|
|
|
373
388
|
|
|
374
389
|
### 4. Price-First Alignment Plan
|
|
375
390
|
|
|
376
|
-
> **Source:** `PRICE_FIRST_ALIGNMENT_PLAN.md` · **Status:** Phase 1 shipped and live as shadow telemetry; Phase 2 projection was enabled (`1bbf1a23`) then **removed** (`3713c496`) after a live-bot incident — the anchor veto overrode chain evidence and drove destructive gap-band cancels. The anchor is now observability-only; the boundary is chain-evidence-derived. Phase 3 is moot (no second write path to retire); boundary geometry is pinned by `tests/test_boundary_anchor_recovery.ts` (ANCHOR-001..004) and `tests/test_grid_price_slot_invariant.ts`.
|
|
391
|
+
> **Source:** former `PRICE_FIRST_ALIGNMENT_PLAN.md` (deleted 2026-08-31; merged here) · **Status:** Phase 1 shipped and live as shadow telemetry; Phase 2 projection was enabled (`1bbf1a23`) then **removed** (`3713c496`) after a live-bot incident — the anchor veto overrode chain evidence and drove destructive gap-band cancels. The anchor is now observability-only; the boundary is chain-evidence-derived. Phase 3 is moot (no second write path to retire); boundary geometry is pinned by `tests/test_boundary_anchor_recovery.ts` (ANCHOR-001..004) and `tests/test_grid_price_slot_invariant.ts`.
|
|
377
392
|
> **Scope:** grid boundary state `modules/order/` · **Related:** three-layer crawl/anchor/guard fix.
|
|
378
393
|
|
|
379
394
|
#### 4.1 Goal
|
|
@@ -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.16 (released).
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
package/docs/WORKFLOW.md
CHANGED
|
@@ -252,16 +252,17 @@ 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 |
|
|
258
259
|
| `dexbot git` | — | Analyze repository git history and write an added/deleted-lines HTML chart (`repo-stats.html`; source checkouts only) |
|
|
259
|
-
| `dexbot status` | `stat`, `stats` | Unified runtime health — daemon, adapter, bots |
|
|
260
|
+
| `dexbot status` | `stat`, `stats` | Unified runtime health — daemon, adapter, bots. Whole-runtime: an optional bot name is validated, then ignored |
|
|
260
261
|
| `dexbot start` | `unlock` | Run credential daemon + bot (equivalent to running the `unlock` runtime, `dist/unlock.js`) |
|
|
261
|
-
| `dexbot stop` | `stp`, `stopall` | Stop the
|
|
262
|
-
| `dexbot reload` | `reloadall` | Reload
|
|
263
|
-
| `dexbot restart` | `restartall` | Restart the
|
|
264
|
-
| `dexbot delete` | — | Shut down and clean up the monolithic runtime
|
|
262
|
+
| `dexbot stop [<bot>]` | `stp`, `stopall` | Stop the runtime. Monolithic: whole runtime (a bot argument folds into it with a notice); `--isolated`: just that bot |
|
|
263
|
+
| `dexbot reload [<bot>]` | `reloadall` | Reload without touching the credential daemon. Same per-bot target rules as `stop` |
|
|
264
|
+
| `dexbot restart [<bot>]` | `restartall` | Restart and re-unlock the credential daemon. Same per-bot target rules as `stop` |
|
|
265
|
+
| `dexbot delete` | — | Shut down and clean up the monolithic runtime. Whole-runtime only; rejects a bot argument |
|
|
265
266
|
| `dexbot clear` | — | Delete `*.log`, rotated `*.log.*` and `*.jsonl*` from the logs directory (`<profiles>/logs`) |
|
|
266
267
|
| `dexbot clear-orders` | — | Delete all persisted order files (`<profiles>/orders`); grids regenerate on next start |
|
|
267
268
|
| `dexbot clear-market-adapter` | — | Delete market adapter data, state (incl. `market_adapter.lock`), and adapter logs |
|
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
|
@@ -240,13 +240,18 @@ Pair-specific AMA profiles live in `profiles/market_profiles.json`:
|
|
|
240
240
|
"intervalSeconds": 3600,
|
|
241
241
|
"defaultAma": "AMA1",
|
|
242
242
|
"amas": {
|
|
243
|
-
"AMA1": { "erPeriod":
|
|
244
|
-
"AMA2": { "erPeriod":
|
|
243
|
+
"AMA1": { "erPeriod": 781, "fastPeriod": 5.2, "slowPeriod": 62.1 },
|
|
244
|
+
"AMA2": { "erPeriod": 781, "fastPeriod": 5.2, "slowPeriod": 72.0 }
|
|
245
245
|
}
|
|
246
246
|
}]
|
|
247
247
|
}
|
|
248
248
|
```
|
|
249
249
|
|
|
250
|
+
> The `amas` periods above are the fitted built-in presets (`MARKET_ADAPTER.AMAS`),
|
|
251
|
+
> shown here only to make the shape concrete. A real pair profile needs just the
|
|
252
|
+
> fields it changes — e.g. `"AMA3": { "slowPeriod": 90 }` keeps the built-in
|
|
253
|
+
> `erPeriod`/`fastPeriod` and overrides only `slowPeriod`.
|
|
254
|
+
|
|
250
255
|
`profiles/market_adapter_settings.json` layers:
|
|
251
256
|
|
|
252
257
|
```json
|
|
@@ -489,7 +494,7 @@ Per cycle, per processed bot, the adapter can produce:
|
|
|
489
494
|
|
|
490
495
|
### Files
|
|
491
496
|
|
|
492
|
-
<details><summary>Config and state files (click to expand)</summary>
|
|
497
|
+
<details><summary><mark>Config and state files (click to expand)</mark></summary>
|
|
493
498
|
|
|
494
499
|
| File | Purpose |
|
|
495
500
|
|------|---------|
|
|
@@ -574,12 +579,13 @@ Typical fields:
|
|
|
574
579
|
|
|
575
580
|
### Module Map
|
|
576
581
|
|
|
577
|
-
<details><summary>Directory layout (click to expand)</summary>
|
|
582
|
+
<details><summary><mark>Directory layout (click to expand)</mark></summary>
|
|
578
583
|
|
|
579
584
|
```text
|
|
580
585
|
market_adapter/
|
|
581
586
|
|-- market_adapter.ts main adapter daemon
|
|
582
587
|
|-- ama_signal_runner.ts one-cycle JSON signal CLI
|
|
588
|
+
|-- cli_args.ts shared CLI argument walker
|
|
583
589
|
|-- candle_utils.ts candle transforms, gap detection, pruning
|
|
584
590
|
|-- interval_utils.ts shared interval label + chain-time helpers
|
|
585
591
|
|-- lp_chart_core.ts chart HTML renderer
|
|
@@ -623,6 +629,7 @@ market_adapter/
|
|
|
623
629
|
| |-- file_lock.ts single-instance file lock
|
|
624
630
|
| |-- file_json_cache.ts write-through JSON read cache
|
|
625
631
|
| |-- month_shards.ts calendar-month shard naming + coverage-span primitives (shared by candle and fills caches)
|
|
632
|
+
| |-- pair_orientation.ts canonical pair orientation + reciprocal inversion helpers
|
|
626
633
|
| |-- data_discovery.ts data directory auto-discovery + shard-family assembly
|
|
627
634
|
| |-- atomic_write.ts atomic file write utility
|
|
628
635
|
| |-- dynamic_grid_snapshot.ts dynamic grid snapshot helpers
|
|
@@ -798,7 +805,7 @@ snapshot.
|
|
|
798
805
|
|
|
799
806
|
Main override knobs live in `profiles/market_adapter_settings.json`:
|
|
800
807
|
|
|
801
|
-
<details><summary>Full settings table (click to expand)</summary>
|
|
808
|
+
<details><summary><mark>Full settings table (click to expand)</mark></summary>
|
|
802
809
|
|
|
803
810
|
| Setting | Meaning |
|
|
804
811
|
|---------|---------|
|
|
@@ -863,7 +870,7 @@ closed 1h candles.
|
|
|
863
870
|
|
|
864
871
|
#### Shared Month-Shard Cache and Fetch Robustness
|
|
865
872
|
|
|
866
|
-
Pool, book, and feed candle fetches share one cache entry point (`runCachedWindows` in `market_adapter/inputs/window_cache.ts`): candles live in fixed calendar-month shards (`<base>.shard_YYYY-MM.json`, UTC) whose names never shift, so a run loads only the shards overlapping its requested range, queries only genuinely missing buckets plus a bounded tail refresh, and rewrites only shards that gained buckets or query coverage — pure-reuse runs perform zero writes and zero deletes. Shard metas record the ranges actually queried (`meta.queriedRanges`, monotonically unioned) together with `at`, the time each query ran; spans merge only when they assert the same verification time, so per-bucket freshness stays exact. A missing range is pruned only when recorded query coverage genuinely covers it — the absence of local buckets alone never certifies history as empty — and only once the range ended more than `GAP_SETTLE_HORIZON_MS` ago, judged per gap rather than per window (a month-old gap at the leading edge of the newest window is as settled as one in a fully past window). The tail window re-queries only buckets that no query has seen `TAIL_SETTLE_LAG_MS` after they closed (`settleCoverage`), so a rerun costs ~lag+elapsed hours instead of a fixed 48h, and the refresh never reaches back past `TAIL_REFRESH_HOURS` (an unsettled bucket must be refreshed because index lag is still open, but a coverage hole older than 48h is past any plausible lag and must not drag the boundary back weeks); caches without `at` fall back to that fixed window. Clusters of gaps within `GAP_MERGE_TOLERANCE_BUCKETS` collapse into one query, and the sub-range path is bounded by merged span hours rather than gap count, so one extra small hole can no longer escalate a run to a full-window fetch. Because spans merge only on an identical `at`, a shard gains one span per re-verifying run; the persisted list is capped at `MAX_COVERAGE_SPANS` by dropping the oldest spans, which can never invent emptiness (it can only make those buckets look unsettled, bounded by the same 48h ceiling). A run that re-verifies the tail therefore rewrites that shard even when the candles come back identical — the moved verification time is the news, and skipping the write would throw it away; pure-reuse runs still write nothing. Partial windows merge into the run output but are never persisted. Stable month shards are the only supported cache format; obsolete run-relative cache files are ignored. Every range fetch runs through `fetchRangeWithRetry` (per-range attempts + linear backoff + abort-signal timeout; the LP path keeps a 4-attempt budget), one-shot Kibana queries retry transient errors (3 attempts), paged fetchers cap at `kibanaMaxPages` (500), and bidirectional fetches tolerate a one-direction failure.
|
|
873
|
+
Pool, book, and feed candle fetches share one cache entry point (`runCachedWindows` in `market_adapter/inputs/window_cache.ts`): candles live in fixed calendar-month shards (`<base>.shard_YYYY-MM.json`, UTC) whose names never shift, so a run loads only the shards overlapping its requested range, queries only genuinely missing buckets plus a bounded tail refresh, and rewrites only shards that gained buckets or query coverage — pure-reuse runs perform zero writes and zero deletes. Shard metas record the ranges actually queried (`meta.queriedRanges`, monotonically unioned) together with `at`, the time each query ran; spans merge only when they assert the same verification time, so per-bucket freshness stays exact. A missing range is pruned only when recorded query coverage genuinely covers it — the absence of local buckets alone never certifies history as empty — and only once the range ended more than `GAP_SETTLE_HORIZON_MS` ago, judged per gap rather than per window (a month-old gap at the leading edge of the newest window is as settled as one in a fully past window). The tail window re-queries only buckets that no query has seen `TAIL_SETTLE_LAG_MS` after they closed (`settleCoverage`), so a rerun costs ~lag+elapsed hours instead of a fixed 48h, and the refresh never reaches back past `TAIL_REFRESH_HOURS` (an unsettled bucket must be refreshed because index lag is still open, but a coverage hole older than 48h is past any plausible lag and must not drag the boundary back weeks); caches without `at` fall back to that fixed window. Clusters of gaps within `GAP_MERGE_TOLERANCE_BUCKETS` collapse into one query, and the sub-range path is bounded by merged span hours rather than gap count, so one extra small hole can no longer escalate a run to a full-window fetch. Because spans merge only on an identical `at`, a shard gains one span per re-verifying run; the persisted list is capped at `MAX_COVERAGE_SPANS` by dropping the oldest spans, which can never invent emptiness (it can only make those buckets look unsettled, bounded by the same 48h ceiling). A run that re-verifies the tail therefore rewrites that shard even when the candles come back identical — the moved verification time is the news, and skipping the write would throw it away; pure-reuse runs still write nothing. Partial windows merge into the run output but are never persisted. Stable month shards are the only supported cache format; obsolete run-relative cache files are ignored. Pair orientation is canonicalized (the lower asset id is always leg A on disk), so `bts/iob.xrp` and `iob.xrp/bts` share one shard family: the fetch queries the canonical side and the result is inverted back for the requested side (inverse volume uses the same base×close approximation as the TV chart's inverse view). A legacy inverse-orientation family is read once as a migration source and folded into the canonical shards instead of being re-fetched. Every range fetch runs through `fetchRangeWithRetry` (per-range attempts + linear backoff + abort-signal timeout; the LP path keeps a 4-attempt budget), one-shot Kibana queries retry transient errors (3 attempts), paged fetchers cap at `kibanaMaxPages` (500), and bidirectional fetches tolerate a one-direction failure.
|
|
867
874
|
|
|
868
875
|
#### AMA Warmup Window — Why Candle Length Matters
|
|
869
876
|
|
|
@@ -987,7 +994,7 @@ removed manually.
|
|
|
987
994
|
|
|
988
995
|
Important fields in `market_adapter/state/market_adapter_state.json`:
|
|
989
996
|
|
|
990
|
-
<details><summary>Field reference (click to expand)</summary>
|
|
997
|
+
<details><summary><mark>Field reference (click to expand)</mark></summary>
|
|
991
998
|
|
|
992
999
|
| Field | Meaning |
|
|
993
1000
|
|-------|---------|
|
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.16",
|
|
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",
|
|
@@ -108,6 +109,7 @@
|
|
|
108
109
|
"verify:browser-bundle": "npm run build && node dist/scripts/verify-browser-bundle.js",
|
|
109
110
|
"test": "npm run build && npm run build:tests && npm run build --prefix claw && node dist/scripts/run-tests.js",
|
|
110
111
|
"test:live": "RUN_LIVE_BITSHARES_TESTS=1 npm run build && npm run build:tests && npm run build --prefix claw && node dist/scripts/run-tests.js",
|
|
112
|
+
"test:playwright": "npm run build && NODE_PATH=\"$(npm root -g)\" playwright test --config tests/playwright/playwright.config.mjs",
|
|
111
113
|
"clean": "node scripts/clean-dist.js",
|
|
112
114
|
"build": "echo \"tsc is compiling ...\" && tsc && chmod +x dist/dexbot.js dist/bot.js dist/unlock.js dist/pm2.js dist/credential-daemon.js",
|
|
113
115
|
"build:clean": "npm run clean && npm run build",
|
|
@@ -156,6 +158,7 @@
|
|
|
156
158
|
"./dist/modules/launcher/status_reporting.js": false,
|
|
157
159
|
"./dist/modules/launcher/supervisor_control.js": false,
|
|
158
160
|
"./dist/modules/launcher/monolithic_runtime.js": false,
|
|
161
|
+
"./dist/modules/launcher/runtime_mode.js": false,
|
|
159
162
|
"./dist/modules/launcher/market_adapter_runtime.js": false,
|
|
160
163
|
"./dist/modules/launcher/market_adapter_watchdog.js": false,
|
|
161
164
|
"./dist/modules/launcher/foreign_cred_daemon.js": false,
|