dexbot 1.6.13 → 1.6.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +66 -4
- package/README.md +2 -2
- package/analysis/README.md +6 -6
- package/analysis/tradingview/README.md +2 -1
- package/claw/README.md +7 -7
- package/claw/docs/AI_BOT_LIBRARY_API.md +1 -1
- package/claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md +4 -4
- package/claw/modules/claw_catalog.ts +8 -4
- package/claw/modules/dexbot_profiles.ts +59 -15
- package/claw/modules/types.ts +2 -1
- 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/claw/skills/margin-trading/SKILL.md +1 -1
- package/claw/skills/margin-trading/references/position-management.md +1 -1
- package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +105 -31
- 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 +10 -6
- package/dist/modules/account_bots.js +13 -10
- package/dist/modules/account_orders.d.ts +36 -4
- package/dist/modules/account_orders.js +76 -5
- package/dist/modules/bitshares-native/crypto/ecc_core.d.ts +1 -2
- package/dist/modules/bitshares-native/crypto/ecc_core.js +1 -1
- package/dist/modules/bitshares-native/serial/chain_constants.d.ts +1 -2
- package/dist/modules/bitshares-native/serial/chain_constants.js +1 -2
- package/dist/modules/bitshares-native/subscriptions.js +1 -1
- package/dist/modules/bot_defaults.d.ts +29 -4
- package/dist/modules/bot_defaults.js +65 -10
- package/dist/modules/bot_settings.d.ts +4 -0
- package/dist/modules/bot_settings.js +58 -21
- package/dist/modules/config.js +6 -1
- package/dist/modules/constants.d.ts +13 -5
- package/dist/modules/constants.js +36 -5
- package/dist/modules/credit_runtime.d.ts +35 -5
- package/dist/modules/credit_runtime.js +219 -38
- package/dist/modules/dexbot_class.d.ts +23 -0
- package/dist/modules/dexbot_class.js +60 -17
- package/dist/modules/dexbot_cow_runtime.d.ts +62 -174
- package/dist/modules/dexbot_cow_runtime.js +350 -64
- package/dist/modules/dexbot_credential_client.d.ts +1 -16
- package/dist/modules/dexbot_credential_client.js +1 -1
- package/dist/modules/dexbot_fill_runtime.d.ts +2 -2
- package/dist/modules/dexbot_fill_runtime.js +16 -8
- package/dist/modules/dexbot_maintenance_runtime.d.ts +24 -81
- package/dist/modules/dexbot_maintenance_runtime.js +104 -70
- package/dist/modules/dexbot_startup_runtime.js +15 -2
- package/dist/modules/dexbot_state_recovery.js +17 -1
- package/dist/modules/key_store.d.ts +0 -5
- package/dist/modules/key_store.js +1 -1
- package/dist/modules/order/accounting.js +11 -11
- package/dist/modules/order/export.js +4 -4
- package/dist/modules/order/format.d.ts +15 -1
- package/dist/modules/order/format.js +19 -1
- package/dist/modules/order/genesis_policy.d.ts +1 -1
- package/dist/modules/order/genesis_policy.js +1 -1
- package/dist/modules/order/grid.d.ts +141 -12
- package/dist/modules/order/grid.js +666 -92
- package/dist/modules/order/grid_reconcile.d.ts +1 -1
- package/dist/modules/order/grid_reconcile.js +9 -8
- package/dist/modules/order/grid_reconcile_internal.js +61 -58
- package/dist/modules/order/index.d.ts +37 -9
- package/dist/modules/order/logger.js +2 -2
- package/dist/modules/order/manager.d.ts +10 -2
- package/dist/modules/order/manager.js +56 -31
- package/dist/modules/order/strategy.d.ts +2 -2
- package/dist/modules/order/strategy.js +51 -21
- package/dist/modules/order/sync_engine.js +22 -9
- package/dist/modules/order/utils/math.d.ts +101 -29
- package/dist/modules/order/utils/math.js +215 -84
- package/dist/modules/order/utils/order.d.ts +58 -58
- package/dist/modules/order/utils/order.js +135 -106
- package/dist/modules/order/utils/system.d.ts +193 -6
- package/dist/modules/order/utils/system.js +394 -31
- package/dist/modules/order/utils/validate.d.ts +1 -1
- package/dist/modules/order/utils/validate.js +71 -59
- package/dist/modules/runtime_settings.d.ts +1 -1
- package/dist/modules/runtime_settings.js +3 -3
- package/dist/modules/types.d.ts +55 -4
- package/dist/scripts/analyze-credit.js +44 -27
- package/dist/scripts/analyze-orders.d.ts +1 -1
- package/dist/scripts/analyze-orders.js +4 -4
- package/dist/scripts/diagnose-pool-history.js +35 -30
- package/dist/scripts/divergence-calc.js +6 -6
- 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/scripts/validate_bots.d.ts +1 -1
- package/dist/scripts/validate_bots.js +3 -3
- package/dist/unlock.d.ts +2 -1
- package/dist/unlock.js +11 -5
- package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -2
- package/docs/COW_INVARIANTS.md +12 -6
- package/docs/DEXBOT_COMPARISON.md +7 -7
- package/docs/EVOLUTION.md +10 -8
- package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +8 -6
- package/docs/GRID_PRICE_INVARIANT.md +3 -3
- package/docs/GRID_RECALCULATION.md +4 -1
- package/docs/GRID_RECONCILE.md +4 -4
- package/docs/LIFECYCLE.md +11 -11
- package/docs/LOGGING.md +30 -1
- package/docs/MPA_CREDIT_USAGE.md +11 -6
- package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +170 -12
- package/docs/README.md +3 -3
- package/docs/WORKFLOW.md +1 -0
- package/docs/architecture.md +62 -8
- package/docs/developer_guide.md +12 -3
- 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 +12 -3
|
@@ -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
|
---
|
|
@@ -72,10 +75,10 @@ local state.
|
|
|
72
75
|
| **Infinite loops** | grid-bloat → resync → bloat; plan→skip→restore holes; `NO_FEASIBLE_BOUNDARY` freeze | Cooldowns, grace windows, minimal cancel ladders |
|
|
73
76
|
| **Silent hangs** | Retries that depended on a future event that never came | Level-triggered scheduling with time-based watchdogs |
|
|
74
77
|
| **Stale queues** | Queued price corrections replayed onto a resynced grid, reverting good placements | Pre-broadcast validation against the live slot |
|
|
75
|
-
| **Shelf /
|
|
78
|
+
| **Shelf / edge orders** | Non-grid orders poisoning every "orders on grid" counter (issue #27) | Slot-N gating across all counters |
|
|
76
79
|
|
|
77
80
|
Families **not** detailed in Part II: silent hangs and stale correction queues are covered in
|
|
78
|
-
`CHANGELOG.md` (v1.6.1 and v1.6.3 respectively); shelf/
|
|
81
|
+
`CHANGELOG.md` (v1.6.1 and v1.6.3 respectively); shelf/edge orders in issue #27 and the v1.6.x
|
|
79
82
|
notes; the grid-price invariant has its own doc — [GRID_PRICE_INVARIANT.md](GRID_PRICE_INVARIANT.md).
|
|
80
83
|
|
|
81
84
|
### R3. Meta-patterns (the actual "madness")
|
|
@@ -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
|
|
|
@@ -295,7 +305,7 @@ Debug line: `[BOUNDARY] boundary=123 sellStart=128 spread=4 anchorProjected=138
|
|
|
295
305
|
**#7 Sync-lock/maintenance observability — LANDED.**
|
|
296
306
|
Throttle `Structural resync defer` to first/last per cap window (was 120/30s); log/retry `[MAINT] n/m failed` with orderId/reason.
|
|
297
307
|
|
|
298
|
-
**Mode C hardening —
|
|
308
|
+
**Mode C hardening — PARTIAL (2026-10-11).** (b) **LANDED** pre-broadcast UPDATE-target existence check off the slot→orderId map: `runPreBroadcastGuards` re-reads every UPDATE action's `orderId` via `chainOrders.batchReadOrders` and refuses the whole batch (`UPDATE_TARGET_MISSING`) + requests a structural resync when a tracked target is gone on chain, instead of letting a `limit_order_update` abort the chunk mid-broadcast. Fails open on a non-Map/errored read (chain rejection remains the backstop), and re-verifies each candidate missing id with a single `readSingleOrder` before declaring it gone so a node lagging behind a just-created order does not false-refuse. **Residual risk (accepted, safe direction):** if that second read also lags/returns null, the batch is refused — a skipped cycle + structural resync, never a half-applied grid. Unexplained `UPDATE_TARGET_MISSING` churn on a slow node is this mechanism. (No dedicated counter on this path, consistent with the other uncounted pre-broadcast refusals; it shows up in error logs.) (a) **SHADOW ONLY** gap-band placement check: non-spread-correction CREATE/UPDATE destinations inside the plan's gap band are counted (`_metrics.gapBandPlacementShadowCount`) and warned, never blocked — enforcement is deliberately withheld because spread correction legitimately places INTO the band and a hard reject would re-open the reverted P1/e2898e51 regression class. Note: the GAP-P1 same-batch cancel that covered commit-time in-gap placement was reverted `e2898e51`; **P3 gate removed `e7231534`** — commit-time in-gap placement is currently covered by `LAST-FILL-GUARD` + adoption (no chain-evidence veto).
|
|
299
309
|
|
|
300
310
|
#### 2.7 Relation to PRICE_FIRST draft
|
|
301
311
|
|
|
@@ -355,7 +365,20 @@ order of escalation forever — HOLD-010) and **not** from
|
|
|
355
365
|
`_lastUnmatchedChainOrdersAt` — the latter refreshes on every observing sync
|
|
356
366
|
and would make an age gate unfirable (HOLD-007).
|
|
357
367
|
|
|
358
|
-
Still open:
|
|
368
|
+
Still open: none of the listed counters — all four landed 2026-10-11 (see below). Deferred-hold observability is no longer open — the `[HOLD]` summary now names side/price/size/reason/off-grid distance and slow-re-warns on an unchanged hold (`modules/dexbot_maintenance_runtime.ts`, `docs/GRID_PRICE_INVARIANT.md`).
|
|
369
|
+
|
|
370
|
+
P2 additions (2026-10-11, counter-only — none gated behavior):
|
|
371
|
+
- `refusedCommitCount` — incremented once in `recoverRefusedCommit` (the single funnel for all refused/uncertain commit paths), and only for genuine refusals: the poll-confirmed **success** path also routes through this funnel (adoption + fee deduction) and passes `refusedCommit: false`, so it is not counted.
|
|
372
|
+
- `orphanFillCreditedCount` — incremented in `applyReplaySafeOrphanFillAccounting` on an `applied` result (a real proceeds credit; not `duplicate`/`error`/`missing_key`).
|
|
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.
|
|
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.
|
|
375
|
+
- `gapBandPlacementShadowCount` — the Mode C(a) shadow above.
|
|
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.
|
|
359
382
|
|
|
360
383
|
#### 3.4 Key code references (from source table)
|
|
361
384
|
|
|
@@ -436,7 +459,7 @@ Goal (Phase 2): I1–I6 property pass, full suite green, harness random, 48h per
|
|
|
436
459
|
4. **LADDER #2/#3** identity + update-first hardening. — *done (`4838bcb0`).*
|
|
437
460
|
5. **LADDER #5 / ORPHAN P0 recovery-by-ID** persistence (long freeze). — *done (`4838bcb0`, extended `a54863ca`; recovery-by-ID `1b27f6eb`).*
|
|
438
461
|
6. **ORPHAN P0 ID-based adoption** + **P1 atomicity** (stale-plan race). — *P0 done (`1b27f6eb`, retry `d808c052`); atomicity partial.*
|
|
439
|
-
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.*
|
|
440
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.*
|
|
441
464
|
|
|
442
465
|
---
|
|
@@ -466,7 +489,7 @@ Pairs-checked base excludes cross-pair unless flagged; strict sat-level detectio
|
|
|
466
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`.
|
|
467
490
|
- Boundary re-derivation persists: bot-A `00:28–07:00` must not repeat `[BOUNDARY-EVIDENCE]` for unchanged chain.
|
|
468
491
|
- `NO_FEASIBLE_BOUNDARY` bot-C `04:27:48` resumes on next sync tick (bounded, not hours) with WARN.
|
|
469
|
-
- 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.)*
|
|
470
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.)*
|
|
471
494
|
- Aug 28 burst `17:09–17:16` (3 regs/6m, sells 1110–1176) → `0` orphans, `0` sells below asks.
|
|
472
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`.
|
|
@@ -482,7 +505,142 @@ Original doc regression excerpts preserved: GAP P6 A/B/C; LADDER §2.8 checks (1
|
|
|
482
505
|
- [x] No other doc/index lists the four (verified 2026-08-31); `analysis/README.md` documents the `grid_correction_check` tool.
|
|
483
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.
|
|
484
507
|
|
|
485
|
-
*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.
|
|
486
644
|
|
|
487
645
|
---
|
|
488
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
|
|
|
@@ -45,7 +45,7 @@ This directory contains the comprehensive technical documentation for the DEXBot
|
|
|
45
45
|
- **API Boundary**: Responsibility split between the AI decision layer and the DEXBot2 execution substrate ([AI_BOT_LIBRARY_API.md](../claw/docs/AI_BOT_LIBRARY_API.md))
|
|
46
46
|
- **Tuning Reference**: Practical grid-tuning baselines ([DEXBOT2_TUNING_CHEAT_SHEET.md](../claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md))
|
|
47
47
|
- **Position Management**: Short-position tracking, position health monitoring (3-zone CR model), and shared CR planning via `cr_planner.ts`
|
|
48
|
-
- **Skills**: Presentation-only, concept-reference, and launcher-orchestration skill packs for bitshares-guide, margin-trading, launcher-ops, and shared references
|
|
48
|
+
- **Skills**: Presentation-only, concept-reference, and launcher-orchestration skill packs for bitshares-guide, margin-trading, launcher-ops, memu-memory, trend-detection, and shared references
|
|
49
49
|
|
|
50
50
|
## Operational & Security
|
|
51
51
|
|
|
@@ -58,7 +58,7 @@ This directory contains the comprehensive technical documentation for the DEXBot
|
|
|
58
58
|
|
|
59
59
|
### 📊 [Grid Recalculation](GRID_RECALCULATION.md)
|
|
60
60
|
*When and why the grid resets.*
|
|
61
|
-
- **Reset Sources**: Market-adapter bootstrap, AMA delta, AMA-slope range reset, RMS divergence correction, and
|
|
61
|
+
- **Reset Sources**: Market-adapter bootstrap, AMA delta, AMA-slope range reset, RMS divergence correction, and available-funds resize
|
|
62
62
|
- **Configuration**: Per-source thresholds, whitelist requirements, and defaults
|
|
63
63
|
- **Trigger Execution**: How `profiles/recalculate.<botKey>.trigger` is consumed under the fill-processing lock
|
|
64
64
|
|
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
|
|
@@ -620,12 +674,12 @@ mgr.outOfSpread = 3; // three slots beyond the target spread
|
|
|
620
674
|
### Calculation
|
|
621
675
|
|
|
622
676
|
```javascript
|
|
623
|
-
//
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
677
|
+
// Requested extra slots, derived from the live spread vs the target tolerance:
|
|
678
|
+
// calculateCurrentSpread(mgr) -> shouldFlagOutOfSpread(...) returns the slot count.
|
|
679
|
+
mgr.outOfSpread = shouldFlagOutOfSpread(
|
|
680
|
+
calculateCurrentSpread(mgr), nominalSpread, toleranceSteps, buyCount, sellCount, incrementPercent
|
|
681
|
+
);
|
|
682
|
+
// 0 = in spread, 3+ = out
|
|
629
683
|
```
|
|
630
684
|
|
|
631
685
|
---
|
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. |
|
|
@@ -141,7 +141,7 @@ A **phantom order** is an order in ACTIVE/PARTIAL state WITHOUT a valid `orderId
|
|
|
141
141
|
| **Crawl Candidate** | Furthest active order eligible for rotation |
|
|
142
142
|
| **Shortage** | Empty slot in the active window that needs an order |
|
|
143
143
|
| **Surplus** | Order outside the active window that can be rotated |
|
|
144
|
-
| **Hard Surplus** | Order beyond the configured window + reserve (`
|
|
144
|
+
| **Hard Surplus** | Order beyond the configured window + reserve (`coreOrders` + `edgeOrders`) count |
|
|
145
145
|
| **Reserve** | Edge-pinned live order outside the active window (buys at grid floor, sells at grid ceiling); never moves the boundary |
|
|
146
146
|
| **Dust** | Partial order < 5% of ideal size |
|
|
147
147
|
| **Dust Cancel** | Immediate on-chain cancel of dust partials on detection (no delay, no timer). Slot freed for a fresh counter-order. |
|
|
@@ -779,9 +779,18 @@ createOrderGrid(config)
|
|
|
779
779
|
// Initialize with blockchain balances
|
|
780
780
|
initializeGrid(manager)
|
|
781
781
|
|
|
782
|
-
//
|
|
782
|
+
// Complete fund trigger: available-funds ratio + over-allocation + the
|
|
783
|
+
// on-chain committed-drift leg (closes the virtual-reservation blind spot)
|
|
783
784
|
checkAndUpdateGridIfNeeded(manager)
|
|
784
785
|
|
|
786
|
+
// Drift-only async accessor (refreshes funds first); its core is folded into
|
|
787
|
+
// checkAndUpdateGridIfNeeded above
|
|
788
|
+
checkCommittedSizeDrift(manager)
|
|
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
|
+
|
|
785
794
|
// Compare ideal vs. persisted grid
|
|
786
795
|
compareGrids(calculatedGrid, persistedGrid, manager)
|
|
787
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",
|
package/scripts/README.md
CHANGED
|
@@ -111,27 +111,9 @@ bash scripts/reset-settings.sh
|
|
|
111
111
|
|
|
112
112
|
## 📊 DIAGNOSTICS & VALIDATION
|
|
113
113
|
|
|
114
|
-
###
|
|
115
|
-
**File:** `
|
|
116
|
-
**Purpose:**
|
|
117
|
-
```bash
|
|
118
|
-
# Validate the live bot configuration
|
|
119
|
-
node dist/scripts/validate_bots.js
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
### Grid Divergence Audit
|
|
123
|
-
**File:** `divergence-calc.ts`
|
|
124
|
-
**Purpose:** Measure the "drift" between in-memory grid and disk state using RMS divergence metric.
|
|
125
|
-
```bash
|
|
126
|
-
# Calculates RMS Error (hardcoded threshold: 1 promille ≈ 3.2% avg error)
|
|
127
|
-
# RMS quadratically penalizes large errors - see docs/GRID_RECALCULATION.md
|
|
128
|
-
node dist/scripts/divergence-calc.js
|
|
129
|
-
```
|
|
130
|
-
**Reference:** RMS threshold interpretation in [Grid Recalculation docs](../docs/GRID_RECALCULATION.md)
|
|
131
|
-
|
|
132
|
-
### Grid Trading Analysis
|
|
133
|
-
**File:** `analyze-orders.ts`
|
|
134
|
-
**Purpose:** Analyze grid trading metrics and order distribution patterns.
|
|
114
|
+
### Grid Order Analysis
|
|
115
|
+
**File:** `analyze-orders.ts` (CLI: `dexbot order`)
|
|
116
|
+
**Purpose:** Analyze grid order metrics and order distribution patterns.
|
|
135
117
|
```bash
|
|
136
118
|
# Analyzes spread accuracy, geometric consistency, and fund distribution
|
|
137
119
|
node dist/scripts/analyze-orders.js
|
|
@@ -155,24 +137,49 @@ node dist/scripts/analyze-credit.js <bot>
|
|
|
155
137
|
```
|
|
156
138
|
Credit deals report per-pair and average CR, but only for pairs whitelisted in `bots.json` (`debtPolicy.lending`) and listed on the current credit offer; everything else is shown as ignored/unpriced and excluded from the average. A borrow-now preview per configured pair shows today's rate.
|
|
157
139
|
|
|
158
|
-
###
|
|
159
|
-
**File:** `
|
|
160
|
-
**Purpose:**
|
|
140
|
+
### Asset Rich List / Top Holder
|
|
141
|
+
**File:** `rich_list.ts` (CLI: `dexbot rich`, npm: `npm run richlist`)
|
|
142
|
+
**Purpose:** Report the top holder(s) per asset using the chain's `asset_api`
|
|
143
|
+
(`get_asset_holders`). Holders come back balance-descending, so this is a live
|
|
144
|
+
rich list. Nodes must expose `asset_api` to anonymous logins; the script tries
|
|
145
|
+
`dex.iobanker.com` / `api.dex.trading` first and falls back through
|
|
146
|
+
`DEFAULT_NODES`.
|
|
161
147
|
```bash
|
|
162
|
-
#
|
|
163
|
-
|
|
148
|
+
# Rich list for one asset (default: node holder limit, usually 100)
|
|
149
|
+
dexbot rich <asset>
|
|
164
150
|
|
|
165
|
-
#
|
|
166
|
-
|
|
151
|
+
# Top 10 for several assets
|
|
152
|
+
dexbot rich <asset-a> <asset-b> <asset-c> --top 10
|
|
153
|
+
|
|
154
|
+
# Machine-readable
|
|
155
|
+
dexbot rich <asset-a> <asset-b> --json > rich.json
|
|
167
156
|
```
|
|
157
|
+
Balances reflect only liquid account balances, so they do not sum to total supply.
|
|
158
|
+
`--top` is clamped to the node's reported `api_limit_get_asset_holders` (shown
|
|
159
|
+
as a note when clamped). Legacy `bit*` MPA names were renamed on-chain without
|
|
160
|
+
the `bit` prefix; the script retries an unresolved `bit*` name stripped and notes
|
|
161
|
+
the rename. Note:
|
|
162
|
+
`get_asset_holders_count` is reported by the node as `distance(range) - 1`, so
|
|
163
|
+
the `holders=` figure can be off by one.
|
|
168
164
|
|
|
169
|
-
###
|
|
170
|
-
**File:** `
|
|
171
|
-
**Purpose:**
|
|
165
|
+
### Configuration Audit
|
|
166
|
+
**File:** `validate_bots.ts`
|
|
167
|
+
**Purpose:** Check `bots.json` for schema errors or missing required fields.
|
|
172
168
|
```bash
|
|
173
|
-
|
|
169
|
+
# Validate the live bot configuration
|
|
170
|
+
node dist/scripts/validate_bots.js
|
|
174
171
|
```
|
|
175
172
|
|
|
173
|
+
### Grid Divergence Audit
|
|
174
|
+
**File:** `divergence-calc.ts`
|
|
175
|
+
**Purpose:** Measure the "drift" between in-memory grid and disk state using RMS divergence metric.
|
|
176
|
+
```bash
|
|
177
|
+
# Calculates RMS Error (hardcoded threshold: 1 promille ≈ 3.2% avg error)
|
|
178
|
+
# RMS quadratically penalizes large errors - see docs/GRID_RECALCULATION.md
|
|
179
|
+
node dist/scripts/divergence-calc.js
|
|
180
|
+
```
|
|
181
|
+
**Reference:** RMS threshold interpretation in [Grid Recalculation docs](../docs/GRID_RECALCULATION.md)
|
|
182
|
+
|
|
176
183
|
### Grid Calculation Runner
|
|
177
184
|
**File:** `runner.ts`
|
|
178
185
|
**Purpose:** Standalone order grid calculation debugger — loads a bot config, initializes the grid, and simulates sync cycles.
|
|
@@ -186,6 +193,25 @@ LIVE_BOT_NAME=my-bot CALC_CYCLES=10 CALC_DELAY_MS=1000 node dist/scripts/runner.
|
|
|
186
193
|
Useful for verifying config produces the expected grid, testing price derivation, and debugging fund allocation.
|
|
187
194
|
Requires a live BitShares connection (asset metadata lookups and price derivation are on-chain).
|
|
188
195
|
|
|
196
|
+
### Print Grid Sample
|
|
197
|
+
**File:** `print_grid.ts`
|
|
198
|
+
**Purpose:** Demonstrate the grid structure — shows consecutive price levels with percentage differences between adjacent slots.
|
|
199
|
+
```bash
|
|
200
|
+
node dist/scripts/print_grid.js
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### Pool History Diagnostics
|
|
204
|
+
**File:** `diagnose-pool-history.ts`
|
|
205
|
+
**Purpose:** Inspect raw BitShares pool history API responses.
|
|
206
|
+
```bash
|
|
207
|
+
# Inspect pool history (default pool 1.19.133)
|
|
208
|
+
node dist/scripts/diagnose-pool-history.js
|
|
209
|
+
|
|
210
|
+
# Custom pool, limit, and time range
|
|
211
|
+
node dist/scripts/diagnose-pool-history.js --pool 1.19.133 --limit 100 --hours 48 --maxPages 5
|
|
212
|
+
```
|
|
213
|
+
`--pool` must be a concrete numeric liquidity-pool object ID (`1.19.N`). Placeholders such as `1.19.x` are rejected up front, because the node parses the instance part as a `uint64` and otherwise fails with `Parse Error: Couldn't parse uint64_t`.
|
|
214
|
+
|
|
189
215
|
### Native Release Gates
|
|
190
216
|
**File:** `native_release_gates.ts` (+ `generate_mainnet_corpus_report.ts`)
|
|
191
217
|
**Purpose:** Prove the native serialization layer matches the chain byte-for-byte before release.
|
|
@@ -374,6 +400,7 @@ The following scripts allow you to call `dexbot` commands directly from the `scr
|
|
|
374
400
|
| `npm run analysis:trade-pnl` | Trade PnL analysis from fill data |
|
|
375
401
|
| `npm run analysis:grid-check` | Last-fill-guard check (`grid_correction_check.ts`) |
|
|
376
402
|
| `npm run analysis:resolve-accounts` | Batch-resolve on-chain bot accounts (`resolve_bot_accounts.ts`) |
|
|
403
|
+
| `npm run richlist` | Per-asset rich list / top holder (`rich_list.ts`) |
|
|
377
404
|
| `npm run ama:chart:lp-local` | Generate local LP comparison chart |
|
|
378
405
|
| `npm run lp:chart` | Generate uPlot LP chart |
|
|
379
406
|
| `npm run test:credit-renewal` | Test credit offer renewal for a specific bot |
|