dexbot 1.7.0 → 1.7.2
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 +70 -0
- package/README.md +3 -3
- package/analysis/README.md +33 -13
- 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/account_resolver.js +5 -6
- package/dist/analysis/analyze_liquidity.js +15 -4
- package/dist/analysis/bot_key_utils.d.ts +44 -1
- package/dist/analysis/bot_key_utils.js +76 -7
- package/dist/analysis/fills_cache.js +2 -1
- package/dist/analysis/grid_correction_check.d.ts +1 -19
- package/dist/analysis/grid_correction_check.js +12 -30
- package/dist/analysis/liquidity/liquidity_chart_generator.js +190 -20
- package/dist/analysis/liquidity/liquidity_depth_model.d.ts +41 -16
- package/dist/analysis/liquidity/liquidity_depth_model.js +49 -21
- package/dist/analysis/liquidity/liquidity_view.d.ts +15 -0
- package/dist/analysis/liquidity/liquidity_view.js +11 -0
- package/dist/analysis/resolve_bot_accounts.js +7 -6
- package/dist/analysis/trade_profitability.js +2 -1
- package/dist/credential-daemon.js +13 -2
- package/dist/dexbot.js +4 -4
- package/dist/modules/account_bots.d.ts +12 -1
- package/dist/modules/account_bots.js +7 -5
- package/dist/modules/account_orders.d.ts +12 -0
- package/dist/modules/account_orders.js +30 -0
- package/dist/modules/bitshares-native/transport.js +24 -6
- package/dist/modules/bitshares_client.d.ts +24 -6
- package/dist/modules/bitshares_client.js +44 -7
- package/dist/modules/bot_settings.d.ts +2 -0
- package/dist/modules/constants.d.ts +28 -3
- package/dist/modules/constants.js +79 -10
- package/dist/modules/dexbot_class.d.ts +23 -6
- package/dist/modules/dexbot_class.js +44 -0
- package/dist/modules/dexbot_cow_runtime.d.ts +128 -8
- package/dist/modules/dexbot_cow_runtime.js +688 -188
- package/dist/modules/dexbot_fill_runtime.js +124 -35
- package/dist/modules/dexbot_maintenance_runtime.d.ts +1 -1
- package/dist/modules/dexbot_maintenance_runtime.js +259 -79
- package/dist/modules/dexbot_startup_runtime.js +32 -20
- package/dist/modules/dexbot_state_recovery.d.ts +33 -1
- package/dist/modules/dexbot_state_recovery.js +167 -5
- package/dist/modules/node_connect_policy.d.ts +8 -1
- package/dist/modules/node_connect_policy.js +18 -2
- package/dist/modules/node_flap_score.d.ts +87 -0
- package/dist/modules/node_flap_score.js +124 -0
- package/dist/modules/node_health_cache.d.ts +40 -3
- package/dist/modules/node_health_cache.js +66 -20
- package/dist/modules/node_manager.d.ts +101 -19
- package/dist/modules/node_manager.js +255 -65
- package/dist/modules/order/accounting.d.ts +9 -4
- package/dist/modules/order/accounting.js +131 -19
- package/dist/modules/order/async_lock.d.ts +7 -1
- package/dist/modules/order/async_lock.js +7 -1
- package/dist/modules/order/export.js +25 -18
- package/dist/modules/order/fill_ledger.d.ts +99 -0
- package/dist/modules/order/fill_ledger.js +103 -0
- package/dist/modules/order/format.d.ts +24 -10
- package/dist/modules/order/format.js +30 -10
- package/dist/modules/order/grid.d.ts +75 -18
- package/dist/modules/order/grid.js +289 -72
- package/dist/modules/order/grid_reconcile.d.ts +5 -1
- package/dist/modules/order/grid_reconcile.js +333 -210
- package/dist/modules/order/grid_reconcile_internal.d.ts +38 -2
- package/dist/modules/order/grid_reconcile_internal.js +223 -91
- package/dist/modules/order/index.d.ts +18 -5
- package/dist/modules/order/index.js +5 -5
- package/dist/modules/order/lifecycle.d.ts +353 -0
- package/dist/modules/order/lifecycle.js +1109 -0
- package/dist/modules/order/manager.d.ts +277 -20
- package/dist/modules/order/manager.js +680 -64
- package/dist/modules/order/placement_lock.d.ts +102 -0
- package/dist/modules/order/placement_lock.js +222 -0
- package/dist/modules/order/strategy.js +13 -1
- package/dist/modules/order/sync_engine.d.ts +74 -114
- package/dist/modules/order/sync_engine.js +254 -198
- package/dist/modules/order/utils/math.d.ts +29 -4
- package/dist/modules/order/utils/math.js +61 -4
- package/dist/modules/order/utils/order.d.ts +106 -37
- package/dist/modules/order/utils/order.js +256 -81
- package/dist/modules/order/utils/system.d.ts +99 -6
- package/dist/modules/order/utils/system.js +249 -35
- package/dist/modules/order/utils/validate.d.ts +7 -1
- package/dist/modules/order/utils/validate.js +48 -2
- package/dist/modules/outcome.d.ts +54 -0
- package/dist/modules/outcome.js +51 -0
- package/dist/modules/settings_merge.d.ts +4 -0
- package/dist/modules/settings_merge.js +9 -0
- package/dist/modules/timing_policy.d.ts +82 -0
- package/dist/modules/timing_policy.js +244 -0
- package/dist/modules/types.d.ts +149 -22
- package/dist/scripts/analyze-credit.js +54 -17
- package/dist/scripts/analyze-orders.d.ts +4 -2
- package/dist/scripts/analyze-orders.js +113 -34
- package/dist/scripts/chart_targets.js +11 -15
- package/dist/scripts/test-credit-renewal.js +12 -5
- package/docs/COW_INVARIANTS.md +71 -8
- package/docs/DEXBOT_COMPARISON.md +6 -6
- package/docs/EVOLUTION.md +10 -8
- package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
- package/docs/GRID_PRICE_INVARIANT.md +1 -1
- package/docs/GRID_RECONCILE.md +18 -13
- package/docs/LOGGING.md +25 -1
- package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +183 -26
- package/docs/README.md +23 -2
- package/docs/WORKFLOW.md +9 -3
- package/docs/architecture.md +68 -13
- package/docs/developer_guide.md +25 -8
- package/modules/README.md +6 -0
- package/package.json +3 -3
- package/scripts/README.md +16 -0
- package/scripts/pdev.sh +14 -1
- package/scripts/pmain.sh +23 -8
- package/scripts/ptest.sh +7 -0
- package/tests/README.md +30 -1
|
@@ -4,23 +4,27 @@
|
|
|
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.
|
|
8
|
-
> `docs/COW_INVARIANTS.md
|
|
7
|
+
> **Sources:** `CHANGELOG.md` v1.0.0 → v1.7.1 (plus the post-1.7.1 arc);
|
|
8
|
+
> `docs/GRID_PRICE_INVARIANT.md`; `docs/COW_INVARIANTS.md`; `docs/ORDER_LIFECYCLE.md`.
|
|
9
|
+
> Generic terms only — no live markets, accounts, or order ids.
|
|
9
10
|
>
|
|
10
|
-
> **Scope / snapshot:** v1.0.0 → v1.
|
|
11
|
-
>
|
|
11
|
+
> **Scope / snapshot:** v1.0.0 → v1.7.1 (`2a85a501`, 2026-11-04), extended through the
|
|
12
|
+
> post-1.7.1 work at `bc20d574` (2026-11-04). §9 is the v1.6.4 → v1.6.17
|
|
13
|
+
> addendum; §9.10 closes the v1.6.18 review pass and §9.11 carries v1.6.18 → v1.7.1.
|
|
12
14
|
>
|
|
13
15
|
> **Section numbering:** Part II deliberately keeps its original `§0`–`§8` numbers because
|
|
14
16
|
> 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.
|
|
16
|
-
> uses `R1`–`R5` so the two never collide. The closing appendix
|
|
17
|
+
> later addendum (v1.6.4 → v1.6.17, with §9.10/§9.11 extending it) that adds to, and does not
|
|
18
|
+
> renumber, that range. Part I uses `R1`–`R5` so the two never collide. The closing appendix
|
|
19
|
+
> is unnumbered (`A`).
|
|
17
20
|
>
|
|
18
21
|
> **How to read:** start with **Part I** for the explanation; drop into **Part II** when you need
|
|
19
22
|
> the per-incident evidence, commit hashes, and verification targets.
|
|
20
23
|
>
|
|
21
24
|
> **See also:** [GRID_PRICE_INVARIANT.md](GRID_PRICE_INVARIANT.md) ·
|
|
22
25
|
> [COW_INVARIANTS.md](COW_INVARIANTS.md) · [GRID_RECONCILE.md](GRID_RECONCILE.md) ·
|
|
23
|
-
> [
|
|
26
|
+
> [ORDER_LIFECYCLE.md](ORDER_LIFECYCLE.md) · [EVOLUTION.md](EVOLUTION.md) ·
|
|
27
|
+
> [CHANGELOG.md](../CHANGELOG.md).
|
|
24
28
|
|
|
25
29
|
---
|
|
26
30
|
|
|
@@ -44,7 +48,8 @@
|
|
|
44
48
|
- 7. Consolidated verification — grid-correction check as regression gate
|
|
45
49
|
- 8. Provenance & supersession record
|
|
46
50
|
- 9. COW Broadcast, Resync & Geometry Safety (v1.6.4 → v1.6.17) — addendum
|
|
47
|
-
- 9.10 Review pass over v1.6.12 → v1.6.17 (findings P1–P5)
|
|
51
|
+
- 9.10 Review pass over v1.6.12 → v1.6.17 (findings P1–P5), released in v1.6.18
|
|
52
|
+
- 9.11 v1.6.18 → v1.7.1: fill identity, absence and the geometry budget
|
|
48
53
|
- A. Grid-Price Invariant — former failure trace (appendix)
|
|
49
54
|
|
|
50
55
|
---
|
|
@@ -77,6 +82,9 @@ local state.
|
|
|
77
82
|
| **Silent hangs** | Retries that depended on a future event that never came | Level-triggered scheduling with time-based watchdogs |
|
|
78
83
|
| **Stale queues** | Queued price corrections replayed onto a resynced grid, reverting good placements | Pre-broadcast validation against the live slot |
|
|
79
84
|
| **Shelf / edge orders** | Non-grid orders poisoning every "orders on grid" counter (issue #27) | Slot-N gating across all counters |
|
|
85
|
+
| **Stale window after a fill** | A fill is queued but not yet absorbed; the master still counts the filled slot ACTIVE, so a window top-up re-creates the expensive end of the rail and re-buys into a stale pivot | `hasUnsettledFills` defers the targeted reconcile and the window top-up (1:1 repairs still run) + attribution of the real execution price (§9.11.1) |
|
|
86
|
+
| **Fill identity by chain id** | `virtualizeOrder` nulls `orderId`, so a real fill matched no ACTIVE slot and was dropped *after* its accounting was booked; pivot and owed crawl stayed on a stale, higher price | `attributeUnmatchedFillToGrid` falls back to the genesis level of the execution price, refuses prices outside the frozen rail, and owes a crawl only for a hole the grid owns (§9.11.1) |
|
|
87
|
+
| **Chain-existence bookkeeping** | Seven structures with seven clocks; four read sites consulted four subsets and could give four answers for one order | `modules/order/lifecycle.ts`: one record per slot, `unknown` is a real phase, every absence decision asks the same time-bounded `isInFlight()` (§9.11.3) |
|
|
80
88
|
|
|
81
89
|
Families **not** detailed in Part II: silent hangs and stale correction queues are covered in
|
|
82
90
|
`CHANGELOG.md` (v1.6.1 and v1.6.3 respectively); shelf/edge orders in issue #27 and the v1.6.x
|
|
@@ -100,13 +108,16 @@ notes; the grid-price invariant has its own doc — [GRID_PRICE_INVARIANT.md](GR
|
|
|
100
108
|
the runtime guard, the spread-correction planner, the rail clamp and the offline checker.
|
|
101
109
|
Every copy drifted on its own schedule: the planner used the crossing floor, the checker
|
|
102
110
|
kept the old band, the rail clamp kept the old slot ids (§9.7, §9.10). The fix that
|
|
103
|
-
sticks is one exported predicate and callers that re-implement nothing.
|
|
111
|
+
sticks is one exported predicate and callers that re-implement nothing. The same shape
|
|
112
|
+
produced the existence bugs: seven local structures were seven policies for "does this
|
|
113
|
+
order exist?", and the first disagreement was the incident (§9.11.3).
|
|
104
114
|
|
|
105
115
|
### R4. What actually fixed it
|
|
106
116
|
|
|
107
117
|
- **Genesis-frozen price-slot determinism** (v1.4.25+): `slot-N` → exact ladder price
|
|
108
|
-
becomes the single source of truth
|
|
109
|
-
|
|
118
|
+
becomes the single source of truth. Grid-vs-grid identity is now exact; a CHAIN price is
|
|
119
|
+
compared by which ladder level it maps to (`pricesOnSameLevel`, bounded by asset precision),
|
|
120
|
+
never by a tuned band. Killed a whole family of orphan/duplicate bugs.
|
|
110
121
|
- **Single ownership:** one writer for the boundary, one owner for the adapter/market
|
|
111
122
|
config, one authoritative set of counters.
|
|
112
123
|
- **Global last-fill guard + final pre-broadcast gate:** one pivot rule, enforced at the
|
|
@@ -124,6 +135,16 @@ notes; the grid-price invariant has its own doc — [GRID_PRICE_INVARIANT.md](GR
|
|
|
124
135
|
each path carrying its own idea of "stranded".
|
|
125
136
|
- **Live identity over local keys (§9.10, `531edeb4`):** every rail/geometry decision maps the
|
|
126
137
|
order's LIVE chain price onto the ladder; a slot id is a hint, never the fact.
|
|
138
|
+
- **An id is not an identity (§9.11.1, `8705381b`):** a fill whose chain id was nulled by
|
|
139
|
+
virtualisation is resolved to the genesis level of its execution price, so attribution
|
|
140
|
+
cannot go blind exactly when the order is most interesting.
|
|
141
|
+
- **An unabsorbed fill blocks the geometry (§9.11.1, `a93f7eef`):** while fills are queued,
|
|
142
|
+
draining, in flight or owed a crawl, the targeted reconcile and the window top-up defer.
|
|
143
|
+
- **Repairs must reduce the violation (§9.11.3, `c493a604`):** a boundary move is accepted
|
|
144
|
+
only when it strands *strictly fewer* placed orders than the committed value, measured by
|
|
145
|
+
the validator's own count — never a second predicate.
|
|
146
|
+
- **One existence record (§9.11.3, `826d84a3`/`84b935d9`):** seven per-site structures
|
|
147
|
+
collapsed into `lifecycle.ts`; `unknown` is a phase, not an absence.
|
|
127
148
|
- **Observability instead of a veto (§9.10/P4):** where a hard guard would re-create a
|
|
128
149
|
deadlock (a counter order crossing the floor by construction), log it once and let the
|
|
129
150
|
chain price it as a taker fill.
|
|
@@ -157,6 +178,15 @@ The winning strategy was **removing writers and sources of truth**, not adding h
|
|
|
157
178
|
repair that can cite one stray order is not a repair.
|
|
158
179
|
11. **When a veto would deadlock, ship the observation.** A taker-fee risk earns a log line,
|
|
159
180
|
not a rule that re-creates the deadlock the previous fix removed (§9.10/P4).
|
|
181
|
+
12. **An id is not an identity.** Virtualising an order clears its chain id, so anything that
|
|
182
|
+
matches fills, occupancy or rails by id alone goes blind exactly when the order is most
|
|
183
|
+
interesting. Match the ladder level of the live price; keep the id as a hint (§9.11.1).
|
|
184
|
+
13. **A fill the geometry has not absorbed must block the geometry.** Deferring a repair for
|
|
185
|
+
one cycle is cheaper than a top-up built from a stale master, because a repair path that
|
|
186
|
+
runs on un-absorbed state is a way to re-create that state (§9.11.1).
|
|
187
|
+
14. **Absence needs one definition, one clock and one owner.** Seven local counters are seven
|
|
188
|
+
policies; if two sites can disagree about whether an order exists, the disagreement is
|
|
189
|
+
the bug, not either answer (§9.11.3).
|
|
160
190
|
|
|
161
191
|
---
|
|
162
192
|
|
|
@@ -183,7 +213,7 @@ plans, `LANDED`/`REVERTED`/`SUPERSEDED` statuses, commit hashes, and verificatio
|
|
|
183
213
|
|
|
184
214
|
**Grid terms:** `boundary` = discrete sell/buy split index; `gap band` = `SPREAD/virtual` slots around boundary; `sellStartIdx = splitIdx - floor(gap/2) - 1`; center-priced ladder `createOrderGrid` = `startPrice × step^(k+½)` (`modules/order/grid.ts`); `MarketAnchor` = fill-derived `lastFillPrice/maxFilledSellPrice/minFilledBuyPrice/lastFillSide`; tolerance helpers `calculatePriceTolerance = (1/satsA+1/satsB)×price` (`modules/order/utils/math.ts`), `GRID_LIMITS.PRICE_TOLERANCE_MAX_PERCENT 0.01` (`modules/constants.ts`).
|
|
185
215
|
|
|
186
|
-
**Validation tool:** `analysis/grid_correction_check.ts` (
|
|
216
|
+
**Validation tool:** `analysis/grid_correction_check.ts` (offline Node tool — it imports the runtime's own `isLastFillGuardBlocked`, so the verdict cannot drift; its Kibana query mirrors `analysis/trade_profitability.ts` (`https://kibana.bitshares.dev`, `bitshares-*`, `operation_type:4` `fill_order` only; `buildFillQuery`, paginated `search_after`, `_source` `block_data` fields). **Invariants:** `sell→sell` with no `buy` between must rise (`curr > prev`, **equal is a violation** — a re-place at the just-filled level), `buy→buy` must fall (`curr < prev`); `per-order` aggregated default (weighted avg collapses multi-fill `1.7.x`), `--per-fill` raw. Resolution via `bot_key_utils.ts` `loadBotMeta/computeBotKey`. Reports violations, `%`, daily histogram, time/range, table with price/Δ%/times/orderIds; `--json/--csv` export; exit `0` pass / `2` fail. Strict sat-level is ground truth — the verdict is **direction only** (equal price is a violation); `--increment` is **informational only** (the band the removed `--tolerance` flag used to express is gone, §9.10/P5). Used as regression gate below; pre-fix per-account baselines are intentionally omitted here — §7 states the targets (`0` violations).
|
|
187
217
|
|
|
188
218
|
---
|
|
189
219
|
|
|
@@ -538,15 +568,17 @@ Original doc regression excerpts preserved: GAP P6 A/B/C; LADDER §2.8 checks (1
|
|
|
538
568
|
- [x] No other doc/index lists the four (verified 2026-08-31); `analysis/README.md` documents the `grid_correction_check` tool.
|
|
539
569
|
- [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.
|
|
540
570
|
|
|
541
|
-
*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), extended through v1.6.14 at `f6c0df32` (2026-10-12), through v1.6.17 at `78ccbb8e`,
|
|
571
|
+
*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), extended through v1.6.14 at `f6c0df32` (2026-10-12), through v1.6.17 at `78ccbb8e`, through the v1.6.18 review pass (`§9.10`: `f4d6da8c`, `a2bf6ba5`, `56481b16`, `3d16f9e4`), and through v1.7.1 at `2a85a501` plus the post-1.7.1 arc (`§9.11`, HEAD `bc20d574`). 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`.*
|
|
542
572
|
|
|
543
573
|
---
|
|
544
574
|
|
|
545
575
|
### 9. COW Broadcast, Resync & Geometry Safety (v1.6.4 → v1.6.17)
|
|
546
576
|
|
|
547
|
-
> **Source:** `CHANGELOG.md` v1.6.4 → v1.6.17 · **Snapshot:** `78ccbb8e` (v1.6.17 tag)
|
|
577
|
+
> **Source:** `CHANGELOG.md` v1.6.4 → v1.6.17 · **Snapshot:** `78ccbb8e` (v1.6.17 tag);
|
|
578
|
+
> §9.10 and §9.11 extend past it — §9.10 released in v1.6.18; §9.11 released in v1.7.1,
|
|
579
|
+
> with the post-1.7.1 additions at HEAD `bc20d574`.
|
|
548
580
|
> Extends the §§1–8 ledger; the `§0`–`§8` numbers are unchanged (code and tests cite them).
|
|
549
|
-
>
|
|
581
|
+
> The ledger labels each row with its release; `post-1.7.1` means after the v1.7.1 tag.
|
|
550
582
|
|
|
551
583
|
Sections 1–4 end with the prevention sweeps reverted: a cancel sweep on ambiguous evidence
|
|
552
584
|
proved worse than the orphan it targets. The post-1.6.3 arc is the constructive inverse —
|
|
@@ -636,7 +668,7 @@ fail-closed behind `_assertGenesisInvariant`. This is R4's "removing writers and
|
|
|
636
668
|
truth" carried to its end: the no-ladder state that Appendix A's `slot.price` corruption
|
|
637
669
|
required is no longer reachable at runtime.
|
|
638
670
|
|
|
639
|
-
#### 9.5 Ledger (order-engine commits, v1.6.4 → v1.
|
|
671
|
+
#### 9.5 Ledger (order-engine commits, v1.6.4 → v1.7.1 + post-1.7.1)
|
|
640
672
|
|
|
641
673
|
| Commit | Release | Change |
|
|
642
674
|
|---|---|---|
|
|
@@ -672,11 +704,33 @@ required is no longer reachable at runtime.
|
|
|
672
704
|
| `62312e60` | 1.6.17 | Plan only placeable tightening slots; name the stall causes |
|
|
673
705
|
| `276cd504` | 1.6.17 | Fund from chain truth and re-anchor the boundary from the fill (§9.9) |
|
|
674
706
|
| `2e618197` | 1.6.17 | Consume only the owed fill crawls a derivation applied (§9.8) |
|
|
675
|
-
| `d99b8685` |
|
|
676
|
-
| `531edeb4` |
|
|
677
|
-
| `f4d6da8c` |
|
|
678
|
-
| `a2bf6ba5` |
|
|
679
|
-
| `56481b16` |
|
|
707
|
+
| `d99b8685` | 1.6.18 | Harden partial-fill re-anchor and recovery (residual allow-list, tolerant load) |
|
|
708
|
+
| `531edeb4` | 1.6.18 | Keep the boundary on the placed rails; use live fill prices for geometry |
|
|
709
|
+
| `f4d6da8c` | 1.6.18 | Edge-pinned fills never arm the pivot or the anchor (§9.10/P1) |
|
|
710
|
+
| `a2bf6ba5` | 1.6.18 | Guard arity, explicit pivot re-arm, stray-aware rail clamp, crossing observation (§9.10/P2-P4) |
|
|
711
|
+
| `56481b16` | 1.6.18 | Offline checker judges by the same direction-only predicate (§9.10/P5) |
|
|
712
|
+
| `ddc4b4a3` | 1.6.18 | Count last-fill-excluded candidates per slot, not per pool visit |
|
|
713
|
+
| `a93f7eef` | 1.7.0 | Stale-grid re-buys: unsettled-fill gate, attribution, same-level refusal (§9.11.1) |
|
|
714
|
+
| `8705381b` | 1.7.0 | Orphan-fill attribution by price; dark-level revive (§9.11.1) |
|
|
715
|
+
| `8aff50bb` | 1.7.0 | Anchor-aware residual allow-list, pivot clock provenance, read-time TTL (§9.11.2) |
|
|
716
|
+
| `c493a604` | 1.7.1 | Stranded-boundary repair without re-arming on replays (§9.11.3) |
|
|
717
|
+
| `ed52f9ef` | 1.7.1 | Exclusive placement region; no create-only re-plan after a rebuild (§9.11.3) |
|
|
718
|
+
| `970fedfd` | 1.7.1 | Remaining placement races; fill-accounting double-apply |
|
|
719
|
+
| `ad081e3d` | 1.7.1 | Placement lifecycle + fill-marker idempotency |
|
|
720
|
+
| `7a3571a4` | 1.7.1 | Follow-up gaps: one teardown, one lease check, one pending-broadcast policy |
|
|
721
|
+
| `94223d19` | 1.7.1 | Re-verify the placement lease before a region holder broadcasts |
|
|
722
|
+
| `8bab9881` | 1.7.1 | Unknown gap geometry is not gap 0 |
|
|
723
|
+
| `4d5e3d81` | 1.7.1 | Forced retreats evacuate, then re-plan the committed band |
|
|
724
|
+
| `7618f299` | 1.7.1 | Cancel teeth may not destroy the rotation that evacuates |
|
|
725
|
+
| `826d84a3` | 1.7.1 | Chain existence unified behind the lifecycle registry (§9.11.3) |
|
|
726
|
+
| `7252d7d3` | 1.7.1 | Broadcast uncertainty as a typed three-valued outcome (§9.11.3) |
|
|
727
|
+
| `84b935d9` | 1.7.1 | One writer per life-cycle clock, one guard per absence decision (§9.11.3) |
|
|
728
|
+
| `3edf8cb3` | post-1.7.1 | Release leaked broadcast regions; cancel wrong-side fills |
|
|
729
|
+
| `6afa0c4b` | post-1.7.1 | Fill side from the paid asset at every call site; backlog coalescing |
|
|
730
|
+
| `cb1041b6` | post-1.7.1 | Never park a chain-observed wrong-side cancel; the repair proof checks rail geometry |
|
|
731
|
+
| `b2f43d8a` | post-1.7.1 | One fill contract, fail-closed grid blockers, one fill identity (P0–P2) |
|
|
732
|
+
| `39675d8a` | post-1.7.1 | Claim the fill key at credit time; drop the duplicate amount channel (P2 tail) |
|
|
733
|
+
| `bc20d574` | post-1.7.1 | One grace-stamp writer, ledger side in export, single-winner fill claim |
|
|
680
734
|
|
|
681
735
|
#### 9.6 Invariants added
|
|
682
736
|
|
|
@@ -698,8 +752,18 @@ required is no longer reachable at runtime.
|
|
|
698
752
|
bounded by the same 24h TTL (enforced at restore and at read time, so a stale row can neither
|
|
699
753
|
arm the guard nor be re-armed), and a re-center is requested at most once per pivot because a
|
|
700
754
|
re-center cannot move it (§9.10/P2).
|
|
701
|
-
|
|
702
|
-
|
|
755
|
+
- **An unabsorbed fill blocks the geometry:** while fills are queued, draining, in flight or
|
|
756
|
+
owed a crawl, the targeted reconcile and the window top-up defer (1:1 repairs still run),
|
|
757
|
+
and a fill is attributed by the ladder level of its execution price, not by a chain id that
|
|
758
|
+
virtualisation has already nulled (§9.11.1).
|
|
759
|
+
- **A repair must reduce the violation:** a boundary move is accepted only when it strands
|
|
760
|
+
strictly fewer placed orders than the committed value, counted by `validatePersistedBoundary`
|
|
761
|
+
itself; an equal count is refused (§9.11.3).
|
|
762
|
+
- **Existence is a record, not a lookup:** one per-slot lifecycle record owns the phase, the
|
|
763
|
+
evidence rank and every clock; `unknown` is a phase that never reads as "gone", and every
|
|
764
|
+
absence decision asks the same time-bounded guard (§9.11.3).
|
|
765
|
+
|
|
766
|
+
#### 9.7 The guard was a band, not an economic rule (`8e5e1a3c`)
|
|
703
767
|
|
|
704
768
|
**Observed (2026-10-24/25, a live market-pair bot).** A dump swept the grid and the
|
|
705
769
|
market then held. Spread correction planned, the broadcast guard dropped the creates,
|
|
@@ -820,7 +884,7 @@ must stay fund-driven from the side pool: a SELL fill returns quote while the
|
|
|
820
884
|
same-side repair needs base, so no fill can ever fund its own side, and pairing
|
|
821
885
|
would hide that asymmetry instead of resolving it.
|
|
822
886
|
|
|
823
|
-
#### 9.10 Review pass over v1.6.12 → v1.6.17 (
|
|
887
|
+
#### 9.10 Review pass over v1.6.12 → v1.6.17 (released in v1.6.18)
|
|
824
888
|
|
|
825
889
|
A code review of the whole 1.6.12→1.6.17 order-engine arc (90 commits) against
|
|
826
890
|
the three stated goals — buy-low/sell-high counter orders, never trading through
|
|
@@ -844,8 +908,101 @@ extremum extracted as `resolveFillAnchorIndex` (pure, batch-only).
|
|
|
844
908
|
|
|
845
909
|
**Commits:** `f4d6da8c` (P1) · `a2bf6ba5` (P2–P4 plus the arity and the anchor
|
|
846
910
|
extraction) · `56481b16` (P5) · `3d16f9e4` (this document, the doc-level invariants
|
|
847
|
-
and the log rows it cites). **
|
|
848
|
-
|
|
911
|
+
and the log rows it cites). **Released in v1.6.18:** the review pass itself carried no
|
|
912
|
+
version bump, but every commit above is an ancestor of the `v1.6.18` tag (2026-11-01).
|
|
913
|
+
|
|
914
|
+
#### 9.11 v1.6.18 → v1.7.1: fill identity, absence and the geometry budget
|
|
915
|
+
|
|
916
|
+
The post-1.6.17 work stopped asking "which guard is missing?" and started asking
|
|
917
|
+
"which *identity* is the code using?". Three answers landed: a fill is identified
|
|
918
|
+
by its ladder level, existence by one lifecycle record, and a repair by the
|
|
919
|
+
amount of violation it removes.
|
|
920
|
+
|
|
921
|
+
##### 9.11.1 A fill the grid could not name (v1.7.0, `a93f7eef`/`8705381b`)
|
|
922
|
+
|
|
923
|
+
**Observed (2026-11-02, a live market-pair bot).** A multi-minute stale broadcast
|
|
924
|
+
region deferred the fill queue; the post-fill targeted reconcile then derived its
|
|
925
|
+
window from a master that still held the filled slots as ACTIVE and re-created
|
|
926
|
+
same-side orders at the top of the un-crawled rail. They filled within seconds:
|
|
927
|
+
9 buy-lower violations, 23.5% of the window's BTS.
|
|
928
|
+
|
|
929
|
+
**The root cause sat upstream of the reconcile.** A fill whose order id no longer
|
|
930
|
+
sat on an ACTIVE/PARTIAL slot was dropped ("order not found in active grid")
|
|
931
|
+
*after* its accounting was booked, so neither the pivot nor the owed crawl
|
|
932
|
+
learned the real execution price and every downstream gate compared against a
|
|
933
|
+
stale, higher price. `virtualizeOrder` nulls `orderId`, so the very fills the
|
|
934
|
+
attribution was written for could never match by id.
|
|
935
|
+
|
|
936
|
+
**Four gates, one direction:**
|
|
937
|
+
|
|
938
|
+
- `hasUnsettledFills` defers the targeted reconcile and the window top-up while
|
|
939
|
+
fills are queued, draining, in flight or owed a crawl. 1:1 repairs
|
|
940
|
+
(cancelled-slot replacement, vacated-rail refill) still run, so a rail is never
|
|
941
|
+
left un-repaired.
|
|
942
|
+
- `attributeUnmatchedFillToGrid` resolves the slot by chain id when a virtualised
|
|
943
|
+
slot still owns it, else by the **genesis level of the execution price**,
|
|
944
|
+
records pivot + owed crawl, and refuses a price outside the frozen rail so a
|
|
945
|
+
shelf/manual order can never arm the geometry.
|
|
946
|
+
- `isLastFillPlacementBlocked` (direction **plus** same grid level) gates every
|
|
947
|
+
reconcile placement, and `_pickVirtualSlotsToActivate` uses the same predicate,
|
|
948
|
+
so the pick budget rolls to the next level instead of being spent on a level
|
|
949
|
+
the create would refuse.
|
|
950
|
+
- A slot virtualised while its order stayed live on chain is revived in place
|
|
951
|
+
(`reviveVirtualSlotFromChain`, level-gated, master-only), a genuinely stale id
|
|
952
|
+
on a non-placed slot is cleared without booking a fill, and CREATE occupancy is
|
|
953
|
+
keyed on the id alone (any state) rather than on `isOrderOnChain()`.
|
|
954
|
+
|
|
955
|
+
##### 9.11.2 The pivot is a row, not a price (v1.6.18/v1.7.0, `d99b8685`/`8aff50bb`)
|
|
956
|
+
|
|
957
|
+
Three defects of the same shape:
|
|
958
|
+
|
|
959
|
+
- The in-band residual allow-list that lets a fill's own PARTIAL survive a re-anchor was
|
|
960
|
+
keyed on the last-processed pivot instead of the batch **extremum**, so for every chunked
|
|
961
|
+
sweep whose furthest fill was not the pivot the re-anchor was refused as
|
|
962
|
+
`unsafe: placed_order_in_band` — the exact shape the extremum resolution exists for.
|
|
963
|
+
- A market-row price could inherit a book-seed timestamp and then re-stamp it, refreshing the
|
|
964
|
+
24h lifetime on every rebuild until the row never expired.
|
|
965
|
+
- The TTL existed only at restore, so a long-lived process kept an expired pivot vetoing one
|
|
966
|
+
side forever while the geometry watchdog claimed a fill or the TTL would restore it.
|
|
967
|
+
|
|
968
|
+
Price, side and clock now travel as one row, and the TTL is enforced where the reference
|
|
969
|
+
is **read**; an unknown age never expires.
|
|
970
|
+
|
|
971
|
+
##### 9.11.3 Absence gets one record; repairs must reduce the violation (v1.7.1)
|
|
972
|
+
|
|
973
|
+
Chain existence used to be answered by seven structures with seven clocks
|
|
974
|
+
(`_pendingBroadcasts`, `createUncertain`, `_committedOrderIds`,
|
|
975
|
+
`_orderIdAssignedAt`, `_placedAt`, `_chainSizeAppliedFills`,
|
|
976
|
+
`_lastUnmatchedChainOrders`). Four read sites consulted four subsets and could
|
|
977
|
+
return four different answers for the same order, so each fix closed one site and
|
|
978
|
+
the bug reappeared at the next.
|
|
979
|
+
|
|
980
|
+
`modules/order/lifecycle.ts` (`826d84a3`, `7252d7d3`, `84b935d9`) now owns one
|
|
981
|
+
record per slot: a six-phase vocabulary in which `unknown` is a real state (a
|
|
982
|
+
lost receipt is *not* an absence), a monotonic evidence rank, and every existence
|
|
983
|
+
clock recorded once. The legacy maps survive as live views, so no call site had
|
|
984
|
+
to be rewritten to get one truth. The persisted `createUncertain` flag is still
|
|
985
|
+
read as evidence; `_lastUnmatchedChainOrders` remains a chain-diff cache for
|
|
986
|
+
orphan diagnostics, not an existence answer. Three rules fall out of it: one
|
|
987
|
+
absence guard (`isInFlight()`, time-bounded), one teardown authority for a hung
|
|
988
|
+
region (`_clearStalePlacementRegion`, `7a3571a4`), and one pending-broadcast
|
|
989
|
+
liveness policy (`getLivePendingBroadcasts`).
|
|
990
|
+
|
|
991
|
+
Geometry gained the matching rule. A boundary writer may move the boundary only
|
|
992
|
+
when the move strands **strictly fewer** placed orders than the committed value
|
|
993
|
+
(`boundaryMoveReducesStrands`, counted by `validatePersistedBoundary` itself); an
|
|
994
|
+
equal count stays refused, and a replayed fill no longer re-arms the pivot
|
|
995
|
+
(`c493a604`). The same arc put every chain-mutating path inside one exclusive
|
|
996
|
+
placement region (`modules/order/placement_lock.ts`, `ed52f9ef`/`970fedfd`) after
|
|
997
|
+
a trigger-file rebuild and a fill-driven rebalance interleaved into 25
|
|
998
|
+
duplicate-price orders; made a forced gap-evacuation retreat evacuate before
|
|
999
|
+
re-planning instead of letting its cancel teeth destroy the rotation (`7618f299`,
|
|
1000
|
+
`4d5e3d81`); and stopped an absent gap band from reading as a valid `0`
|
|
1001
|
+
(`8bab9881`).
|
|
1002
|
+
|
|
1003
|
+
**Why it belongs in this document:** R3.5's "one rule, several implementations"
|
|
1004
|
+
is not a style complaint. Every family above is that pattern applied to a
|
|
1005
|
+
different noun — price, fill, existence.
|
|
849
1006
|
|
|
850
1007
|
---
|
|
851
1008
|
|
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.7.
|
|
5
|
+
**Version context:** v1.7.2 (released).
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
@@ -131,9 +131,22 @@ This directory contains the comprehensive technical documentation for the DEXBot
|
|
|
131
131
|
### 🔒 [COW Invariants](COW_INVARIANTS.md)
|
|
132
132
|
*Stable theory contract for COW pipeline.*
|
|
133
133
|
- **Non-negotiable invariants**: Master immutability, commit atomicity, projection rules, accounting separation
|
|
134
|
-
- **Subsystem Scope**:
|
|
134
|
+
- **Subsystem Scope**: 15 `INV-*` prefix groups mapping each invariant to its runtime subsystem
|
|
135
135
|
- **Change Policy**: Required steps for an intentional invariant change — same-PR doc update, rationale, and regression tests
|
|
136
136
|
|
|
137
|
+
### 🧭 [Order Lifecycle Registry](ORDER_LIFECYCLE.md)
|
|
138
|
+
*How the engine answers one question from one record: does this order exist on chain, and how sure are we?*
|
|
139
|
+
- **The problem**: seven structures with seven clocks, four read sites consulting four different subsets of them
|
|
140
|
+
- **The model**: one record per slot, six phases, `unknown` as a real state that never reads as "gone"
|
|
141
|
+
- **The wiring**: legacy maps are live views onto the record; every mutation funnels through `_applyOrderUpdate`
|
|
142
|
+
- **Invariants**: `INV-LIFE-001…007` in [COW_INVARIANTS.md](COW_INVARIANTS.md#order-lifecycle-order_lifecyclemd)
|
|
143
|
+
|
|
144
|
+
### ⏱ [Timing Window Inventory](TIMING_INVENTORY.md)
|
|
145
|
+
*Every timing knob classified, with the self-healing ones marked as removal targets.*
|
|
146
|
+
- **The audit**: `external` / `bound` / `policy` / `self-healing`, each with a rationale
|
|
147
|
+
- **The gate**: `tests/test_timing_policy.ts` fails on an unclassified window, so the inventory can only shrink by decision
|
|
148
|
+
- **Removal targets**: the six windows that compensate for our own lost state, and the evidence that replaces each
|
|
149
|
+
|
|
137
150
|
### 📐 [Grid-Price Invariant](GRID_PRICE_INVARIANT.md)
|
|
138
151
|
*Why a slot's emitted price must equal its genesis level — and how that failed.*
|
|
139
152
|
- **The invariant**: `order.price === priceForSlot(idx, genesis)`, and why range guards cannot substitute for it
|
|
@@ -169,6 +182,14 @@ This directory contains the comprehensive technical documentation for the DEXBot
|
|
|
169
182
|
- **Practical How-Tos**: Adding features step by step, common pitfalls to avoid, and useful debugging commands.
|
|
170
183
|
- **Glossary**: Definitions of project-specific terminology (e.g., "VIRTUAL order state", "Rotation", "Pipeline Safety", "WorkingGrid", "Atomic Commit", "Dynamic Weight", "Regime Detection").
|
|
171
184
|
|
|
185
|
+
### 🌉 [Liquidity Mirror Design](LIQUIDITY_MIRROR_DESIGN.md)
|
|
186
|
+
*Design paper for a cross-venue liquidity mirror running alongside DEXBot2.*
|
|
187
|
+
- **Roles**: Chain host (TS, DEXBot2) owns identity, pool reads, and hedging; a separate venue daemon owns CEX credentials, the order book, and the rate-limit budget
|
|
188
|
+
- **Contract**: Intent-level, HMAC-authenticated NDJSON over a unix socket — desired book in, fills and positions out; no message whose retry can duplicate an order
|
|
189
|
+
- **Change surface**: Four new modules under `modules/venues/`, a `cex_mirror/` tree, and five mechanical edits; the grid, sync engine, accounting, and strategy engine are untouched
|
|
190
|
+
- **Guardrails**: Spread floor from pool fee plus impact, hedge batching trade-off, deadman cancellation, divergence breaker, and a split inventory-cap model
|
|
191
|
+
- **Rollout**: Milestones M0–M5 with acceptance gates, from protocol conformance vectors to capped live hedging
|
|
192
|
+
|
|
172
193
|
### 🔄 [Workflow](WORKFLOW.md)
|
|
173
194
|
*How we build and release.*
|
|
174
195
|
- **Branching Strategy**: Explanation of the `test` → `dev` → `main` lifecycle.
|
package/docs/WORKFLOW.md
CHANGED
|
@@ -250,8 +250,8 @@ the canonical name is preferred in scripts and docs.
|
|
|
250
250
|
| `dexbot update` | — | Update DEXBot2 from the repository and restart active bots |
|
|
251
251
|
| `dexbot export <bot>` | — | Export bot trades/settings to CSV/JSON for local analysis/ |
|
|
252
252
|
| `dexbot order` | `orders` | Analyze persisted order grids (spread, increment, funds); `--export` for HTML |
|
|
253
|
-
| `dexbot order [<bot>]` | — | Analyze only the specified bot's order grid |
|
|
254
|
-
| `dexbot credit` | — | Live summed MPA + borrowed-credit positions per asset per bot (`[<bot>]`) |
|
|
253
|
+
| `dexbot order [<bot|account>]` | — | Analyze only the specified bot's order grid — or every grid on that account (`<bot|account>`) |
|
|
254
|
+
| `dexbot credit` | — | Live summed MPA + borrowed-credit positions per asset per bot (`[<bot|account>]` — a bot name/key, or the account the bot trades from, name or `1.2.x` id) |
|
|
255
255
|
| `dexbot rich <asset...>` | — | Top holder(s) per asset via the chain asset-holders API (`--top N`, `--json`/`--csv`) |
|
|
256
256
|
| `dexbot tv <target>` | — | TradingView 1h chart for `<bot|pool|AssetA/AssetB>` over `--month N` (default 3); pool = id (133 / 1.19.133) or pool token (LP share-asset symbol) |
|
|
257
257
|
| `dexbot dw <target>` | — | Dynamic-weight research chart: same targets/flags as `tv` |
|
|
@@ -313,7 +313,13 @@ npm run pmain
|
|
|
313
313
|
|--------|---------|-------------|-----------|
|
|
314
314
|
| `npm run ptest` | Push test to origin | Checks out `test` (if not on it) and pushes local commits to `origin/test`. Does **not** touch `dev`/`main`. | Daily development; ensures `origin/test` is up-to-date |
|
|
315
315
|
| `npm run pdev` | Mirror test onto dev | Pushes `origin/test`, then `git push origin test:dev --force` and updates the local `dev` pointer. No merge commit. | When test is stable and you want `dev` to exactly equal `test` |
|
|
316
|
-
| `npm run pmain` | Mirror test onto dev and main | Pushes `origin/test`, then force-pushes `test` to both `dev` and `main` and updates local pointers. **No tagging.** | Full release where `test == dev == main` is intended. Tag manually afterward (see step 5) |
|
|
316
|
+
| `npm run pmain` | Mirror test onto dev and main | Pushes `origin/test`, then force-pushes `test` to both `dev` and `main` in one `--atomic` push and updates local pointers. **No tagging.** | Full release where `test == dev == main` is intended. Tag manually afterward (see step 5) |
|
|
317
|
+
|
|
318
|
+
All three scripts run a shared preflight before touching anything
|
|
319
|
+
(`scripts/lib/git_preflight.sh`): a read-only `git ls-remote` against `origin`.
|
|
320
|
+
An unreachable remote or a rejected SSH key now fails up front instead of
|
|
321
|
+
mid-script, and `pmain`'s `--atomic` push keeps `dev`/`main` together — a
|
|
322
|
+
refusal moves neither. Bypass the check with `DEXBOT_SKIP_GIT_PREFLIGHT=1`.
|
|
317
323
|
|
|
318
324
|
Note: `pmain` does **not** create a release tag. Run `git tag -a v0.X.Y -m "..."` manually after `pmain` if you need a tagged release point.
|
|
319
325
|
|
package/docs/architecture.md
CHANGED
|
@@ -275,8 +275,33 @@ The master grid (`this.orders`) is **immutable** - it can only be replaced atomi
|
|
|
275
275
|
| `deepFreeze()` | `manager.ts` | Individual order objects are deep-frozen |
|
|
276
276
|
| `_gridVersion` | `manager.ts` | Version counter for staleness detection |
|
|
277
277
|
| `_gridLock` | `manager.ts` | AsyncLock serializes grid mutations |
|
|
278
|
+
| `_placementLock` | `manager.ts` / `placement_lock.ts` | Exclusive placement region: serializes every chain-mutating path (COW broadcast, reconcile Phase 1+2, correction drain, dust/residual cancel, pool swap) |
|
|
278
279
|
| Encapsulation | `manager.ts` | Index Sets are private; mutations only via `_applyOrderUpdate()` |
|
|
279
280
|
|
|
281
|
+
### Exclusive Placement Region
|
|
282
|
+
|
|
283
|
+
`_gridVersion` protects the MASTER from a stale plan; it does not stop two paths
|
|
284
|
+
from broadcasting at the same time. That is the placement region
|
|
285
|
+
(`modules/order/placement_lock.ts`): a non-reentrant FIFO lease claimed once per
|
|
286
|
+
chain-mutating operation.
|
|
287
|
+
|
|
288
|
+
- Non-token holders use `manager.withPlacement(kind, fn)`, which owns the bounded
|
|
289
|
+
wait, the shutdown probe and the release. The two token-level holders are the
|
|
290
|
+
COW batch body and startup reconcile (they hold the lease across plan →
|
|
291
|
+
broadcast → commit).
|
|
292
|
+
- Nested work must NOT acquire again: it receives the holder's lease and verifies
|
|
293
|
+
it with `manager.isPlacementLeaseCurrent(lease)` — `isPlacementActive()` is true
|
|
294
|
+
for ANY holder, so it cannot prove ownership (a lease invalidated by
|
|
295
|
+
`forceRelease()` would still read as live).
|
|
296
|
+
- Anything that cannot get the region aborts or defers its batch instead of
|
|
297
|
+
broadcasting unprotected (`[PLACEMENT]`/`[DUST]`/`[RESIDUAL]`/`[MAINT]` deferral
|
|
298
|
+
lines).
|
|
299
|
+
- Leak protection: `_clearStalePlacementRegion()` force-releases a region held past
|
|
300
|
+
`TIMING.PLACEMENT_STALE_CLEAR_MS`, refuses while a bot-level pipeline counter
|
|
301
|
+
younger than that bound proves progress, and clears the hung region's stale
|
|
302
|
+
broadcast refcount in the same step. The broadcast-refcount watchdog mirrors the
|
|
303
|
+
rule in reverse (it refuses while a placement lease is held).
|
|
304
|
+
|
|
280
305
|
### Master Grid Update Pattern
|
|
281
306
|
|
|
282
307
|
All master grid updates follow clone-and-replace semantics:
|
|
@@ -483,16 +508,23 @@ The correction path is fund-only and never manufactures budget by shrinking a re
|
|
|
483
508
|
is never a correction target: a top-up grows an order at its current price, so
|
|
484
509
|
it cannot move bestBuy/bestSell and cannot narrow the spread.
|
|
485
510
|
4. Contiguous gap-slot promotion may extend the window while preserving
|
|
486
|
-
MIN_SPREAD_ORDERS and the opposite placed rail.
|
|
511
|
+
MIN_SPREAD_ORDERS and the opposite placed rail. A same-side order already
|
|
512
|
+
**placed inside the band** is absorbed by the slide (it becomes a legal rail
|
|
513
|
+
member); the walk steps over it and promotes only the next empty slot, so a
|
|
514
|
+
placed edge never becomes a duplicate CREATE target.
|
|
487
515
|
5. If free funds cannot cover every target, place the affordable prefix, then
|
|
488
|
-
**rotate a resting same-side order** into each unfunded
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
516
|
+
**rotate a resting same-side order** into each unfunded tightening slot —
|
|
517
|
+
whether it is a promoted gap slot or an orphaned rail slot left by a
|
|
518
|
+
fill-anchored boundary move (same booked size, never a new commitment). A
|
|
519
|
+
fully allocated rail has ~0 free forever, so create-only repair can never
|
|
520
|
+
close the spread. A virtual tail that reserves the whole free balance is not
|
|
521
|
+
a hard stop: moving a far resting order into the window edge frees no new
|
|
522
|
+
inventory but tightens the spread. The rotation is bounded by the same
|
|
523
|
+
promotion, crossing, last-fill, dedupe/duplicate-price and edge-order guards
|
|
524
|
+
as a create. It never shrinks or grows the moved order. Exactly-zero free on
|
|
525
|
+
both sides is covered by a rotation-only fallback around side selection (an
|
|
526
|
+
unavailable market price is still a hard skip: cross-asset comparison is
|
|
527
|
+
unsafe).
|
|
496
528
|
6. If neither side places an effective order, `checkSpreadCondition` reports a
|
|
497
529
|
`stall` cause (`no-free-funds` / `unfunded` / `no-candidates` / `cold-book` /
|
|
498
530
|
`unmatched-orders` / `readiness-gate` / `last-fill-blocked` /
|
|
@@ -605,9 +637,15 @@ rail-edge price would teleport the window to that edge (observed: boundary 29
|
|
|
605
637
|
anchor — a partial at a far slot is still a real trade, and its residual is the
|
|
606
638
|
allow-listed case below.
|
|
607
639
|
|
|
608
|
-
A
|
|
609
|
-
|
|
610
|
-
|
|
640
|
+
A move that strands **strictly fewer** placed orders than the committed boundary
|
|
641
|
+
is accepted as a violation-reducing repair; an equal count still refuses
|
|
642
|
+
(canonical statement: `INV-COW-006` in
|
|
643
|
+
[COW_INVARIANTS.md](COW_INVARIANTS.md#cow-pipeline) — this section is
|
|
644
|
+
its rationale, not a second definition). The
|
|
645
|
+
comparison uses `validatePersistedBoundary`'s own in-band count
|
|
646
|
+
(`boundaryMoveReducesStrands`), so the fill re-anchor and the rail clamp cannot
|
|
647
|
+
disagree about what "stranded" means. Within that bound, the fill's **own
|
|
648
|
+
PARTIAL residual** at the anchor slot (same side, same ladder level) is
|
|
611
649
|
allow-listed, because any boundary that puts the fill outside its window
|
|
612
650
|
necessarily puts that remainder inside the band. A partial fill therefore no
|
|
613
651
|
longer deadlocks the geometry; GAP-EVAC cleans the residual afterwards.
|
|
@@ -630,6 +668,20 @@ anchoring on it leaves the furthest fill's counter order inside the implied
|
|
|
630
668
|
band. `calculateTargetGrid` passes the batch into
|
|
631
669
|
`reanchorBoundaryFromLastFill`.
|
|
632
670
|
|
|
671
|
+
**Rebuild and load apply the same anchor.** A fresh generation derives its band
|
|
672
|
+
from the current market center, but the last fill is still geometry fact. If
|
|
673
|
+
that center puts the pivot inside the band, the startup picker correctly skips
|
|
674
|
+
the levels at/through the fill (LAST-FILL-GUARD), fills the same-side window
|
|
675
|
+
lower, and the first ask stays at the old `sellStart` — a realized spread two
|
|
676
|
+
steps wider than target with no fill reason for the extra width (live
|
|
677
|
+
2026‑11‑04: boundary 159 after a BUY at new-ladder slot 158, realized 2.123% vs
|
|
678
|
+
the 1.5% target). `initializeGrid` and `loadGrid` therefore call
|
|
679
|
+
`anchorRebuildBoundaryToLastFill` after the pivot is re-armed/restored and
|
|
680
|
+
before reconcile/re-type; `applyRebuildFillAnchor` moves the boundary and
|
|
681
|
+
re-types the rails atomically (`BUY fill at 158 => boundary 157`, counter SELL
|
|
682
|
+
at 162). A cold/off-ladder/unsafe fill keeps the derived boundary, so this is a
|
|
683
|
+
no-op on a healthy restart.
|
|
684
|
+
|
|
633
685
|
### Rail-Derived Commit Boundary (counter orders are the fact)
|
|
634
686
|
|
|
635
687
|
A plan built at a re-anchored boundary places **counter orders** on the promoted
|
|
@@ -668,7 +720,10 @@ GAP-EVAC / the next plan owns the offending order. The result is then passed
|
|
|
668
720
|
through the shared `validatePersistedBoundary` gate (skipped only for a sparse
|
|
669
721
|
ladder, whose array-length ceiling would reject everything), with the slots the
|
|
670
722
|
batch cancels or rotates away allow-listed — so the rail clamp and the re-anchor
|
|
671
|
-
cannot disagree about what "stranded in the band" means.
|
|
723
|
+
cannot disagree about what "stranded in the band" means. The gate accepts a
|
|
724
|
+
candidate that strands **strictly fewer** placed orders than the committed
|
|
725
|
+
boundary (the same violation-reducing rule the re-anchor uses), which is what
|
|
726
|
+
lets a fill-derived retreat land while GAP-EVAC is still draining older strands.
|
|
672
727
|
|
|
673
728
|
### Live-Price Provenance (fill, gap, crossing)
|
|
674
729
|
|
package/docs/developer_guide.md
CHANGED
|
@@ -907,18 +907,32 @@ _finishStartupSequence()
|
|
|
907
907
|
|
|
908
908
|
**Critical Rule: Always acquire locks in ascending level order**
|
|
909
909
|
|
|
910
|
-
The canonical
|
|
910
|
+
The canonical hierarchy (defined at `manager.ts`):
|
|
911
911
|
|
|
912
912
|
```
|
|
913
|
-
Level 0:
|
|
914
|
-
Level
|
|
915
|
-
Level
|
|
916
|
-
Level
|
|
917
|
-
Level
|
|
913
|
+
Level 0: _fillProcessingLock (fill processing — outermost)
|
|
914
|
+
Level 0.5: placement region (exclusive chain-mutation mutex — PlacementLock)
|
|
915
|
+
Level 1: _divergenceLock (divergence checks)
|
|
916
|
+
Level 2: _syncLock (sync operations — timeout-protected)
|
|
917
|
+
Level 3: _gridLock (grid mutations)
|
|
918
|
+
Level 4: _fundLock (fund operations — innermost)
|
|
918
919
|
```
|
|
919
920
|
|
|
920
|
-
All
|
|
921
|
-
|
|
921
|
+
All levels live on the `OrderManager` instance (the placement region is
|
|
922
|
+
`_placementLock`, see `modules/order/placement_lock.ts`). The `level` property
|
|
923
|
+
is a convention marker — AsyncLock does not enforce it at runtime, and
|
|
924
|
+
`PlacementLock` is not an AsyncLock (it is a FIFO, non-reentrant lease).
|
|
925
|
+
|
|
926
|
+
**Placement region (Level 0.5)** serializes every chain-mutating path: COW
|
|
927
|
+
broadcasts, reconcile Phase 1+2, correction drains, dust/residual cancels and
|
|
928
|
+
pool swaps. It is acquired **before** `_gridLock` and never while holding it,
|
|
929
|
+
and it is `NOT` reentrant — nested work receives the holder's lease instead of
|
|
930
|
+
acquiring again, and verifies it with `manager.isPlacementLeaseCurrent(lease)`
|
|
931
|
+
(`isPlacementActive()` is true for ANY holder and must not be used for that).
|
|
932
|
+
The canonical region order is:
|
|
933
|
+
`startBroadcasting → placement → gridLock → fundLock → release placement → stopBroadcasting`.
|
|
934
|
+
A leaked region is force-released by `_clearStalePlacementRegion()`, which also
|
|
935
|
+
drops the hung region's stale broadcast refcount in the same step.
|
|
922
936
|
|
|
923
937
|
**Why This Order?**
|
|
924
938
|
|
|
@@ -926,6 +940,9 @@ convention marker — AsyncLock does not enforce it at runtime.
|
|
|
926
940
|
- Divergence checks (Level 1) nest inside fill processing
|
|
927
941
|
- Sync operations (Level 2) are acquired before grid mutations — the timeout-protected lock is inner, so a stuck sync releases the outer lock
|
|
928
942
|
- Grid mutations (Level 3) and fund operations (Level 4) are innermost
|
|
943
|
+
- The placement region (Level 0.5) sits between fill processing and the grid
|
|
944
|
+
locks: it is broader than one grid mutation (it spans plan → broadcast →
|
|
945
|
+
commit) but must never be taken while a grid lock is held
|
|
929
946
|
- All paths follow the same order
|
|
930
947
|
|
|
931
948
|
**`adjustTotalBalance` Locking Contract** (v1.4.7):
|
package/modules/README.md
CHANGED
|
@@ -70,9 +70,12 @@ modules/
|
|
|
70
70
|
├── chain_keys.ts master-password vault + signing-key retrieval
|
|
71
71
|
├── daemon_node_health.ts daemon-side node failure ledger (shared rules)
|
|
72
72
|
├── node_failure_ledger.ts node failure counting shared by bot + daemon
|
|
73
|
+
├── node_flap_score.ts time-decayed connection-churn score used for node ranking
|
|
73
74
|
├── node_health_cache.ts shared node-health cache file I/O + ordering
|
|
74
75
|
├── socket_json_client.ts newline-delimited JSON Unix-socket client
|
|
75
76
|
├── market_adapter_whitelist.ts adapter whitelist I/O
|
|
77
|
+
├── outcome.ts three-valued Outcome construction (applied/rejected/unknown)
|
|
78
|
+
├── timing_policy.ts timing-window audit: EXTERNAL/BOUND/POLICY/SELF_HEALING classification
|
|
76
79
|
├── types.ts shared type definitions
|
|
77
80
|
│
|
|
78
81
|
├── crypto/ cross-environment crypto providers
|
|
@@ -98,9 +101,12 @@ modules/
|
|
|
98
101
|
│ ├── strategy.ts grid rebalancing, consolidation, rotation
|
|
99
102
|
│ ├── accounting.ts fund tracking, fee accounting
|
|
100
103
|
│ ├── sync_engine.ts blockchain sync, fill detection, reconciliation
|
|
104
|
+
│ ├── lifecycle.ts one record per slot: chain existence, phase, evidence, clocks (docs/ORDER_LIFECYCLE.md)
|
|
105
|
+
│ ├── fill_ledger.ts fill identity, traded-side resolution, booked membership (docs/FILL_PIPELINE.md)
|
|
101
106
|
│ ├── genesis_policy.ts missing-ladder refusal + rebuild policy (docs/GRID_PRICE_INVARIANT.md)
|
|
102
107
|
│ ├── grid_reconcile.ts startup grid reconciliation (docs/GRID_RECONCILE.md)
|
|
103
108
|
│ ├── grid_reconcile_internal.ts internal grid reconciliation helpers
|
|
109
|
+
│ ├── placement_lock.ts exclusive chain-mutating region: FIFO lease, non-reentrant, bounded wait
|
|
104
110
|
│ ├── index.ts barrel export
|
|
105
111
|
│ ├── logger.ts order-scoped logging
|
|
106
112
|
│ ├── logger_state.ts logger state management
|