dexbot 1.6.15 → 1.6.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/CHANGELOG.md +52 -0
  2. package/README.md +4 -4
  3. package/analysis/tradingview/README.md +2 -2
  4. package/analysis/trend_detection/DYNAMIC_WEIGHT_RESEARCH.md +1 -1
  5. package/claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md +3 -2
  6. package/claw/modules/chain_queries.ts +3 -3
  7. package/claw/package.json +1 -1
  8. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  9. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  10. package/dist/analysis/ama_fitting/analyze_lambda_vs_slow.js +5 -3
  11. package/dist/analysis/ama_fitting/fetch_lp_candles.js +8 -1
  12. package/dist/analysis/ama_fitting/optimizer_high_resolution.d.ts +50 -1
  13. package/dist/analysis/ama_fitting/optimizer_high_resolution.js +33 -7
  14. package/dist/analysis/bot_fitting/backtest_bot_fitting.d.ts +8 -6
  15. package/dist/analysis/bot_fitting/backtest_bot_fitting.js +8 -10
  16. package/dist/analysis/bot_key_utils.js +9 -7
  17. package/dist/analysis/chart_utils.d.ts +9 -2
  18. package/dist/analysis/chart_utils.js +51 -1
  19. package/dist/analysis/tradingview/grid_reset_sim.js +1 -1
  20. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.d.ts +2 -1
  21. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +23 -9
  22. package/dist/analysis/trend_detection/backtest_ama_slope_huber.js +1 -1
  23. package/dist/analysis/trend_detection/dynamic_weight_chart_generator.js +21 -2
  24. package/dist/analysis/trend_detection/kalman_chart_generator.js +1 -0
  25. package/dist/analysis/trend_detection/regime_chart_generator.js +1 -1
  26. package/dist/analysis/trend_detection/volatility_chart_generator.js +1 -0
  27. package/dist/dexbot.js +89 -138
  28. package/dist/market_adapter/inputs/fetch_book_data.js +36 -12
  29. package/dist/market_adapter/inputs/fetch_lp_data.d.ts +6 -0
  30. package/dist/market_adapter/inputs/fetch_lp_data.js +65 -19
  31. package/dist/market_adapter/inputs/kibana_feed_source.js +45 -12
  32. package/dist/market_adapter/inputs/window_cache.d.ts +14 -1
  33. package/dist/market_adapter/inputs/window_cache.js +53 -17
  34. package/dist/market_adapter/lp_chart_core.js +1 -0
  35. package/dist/market_adapter/utils/chain.js +4 -3
  36. package/dist/market_adapter/utils/pair_orientation.d.ts +60 -0
  37. package/dist/market_adapter/utils/pair_orientation.js +142 -0
  38. package/dist/modules/account_bots.d.ts +40 -3
  39. package/dist/modules/account_bots.js +77 -37
  40. package/dist/modules/account_orders.d.ts +4 -1
  41. package/dist/modules/account_orders.js +4 -1
  42. package/dist/modules/bitshares-native/resolvers.js +3 -3
  43. package/dist/modules/bitshares_client.d.ts +12 -10
  44. package/dist/modules/bitshares_client.js +12 -10
  45. package/dist/modules/bot_settings.js +3 -3
  46. package/dist/modules/chain_keys.d.ts +6 -2
  47. package/dist/modules/chain_keys.js +5 -1
  48. package/dist/modules/chain_orders.d.ts +6 -2
  49. package/dist/modules/chain_orders.js +6 -2
  50. package/dist/modules/constants.d.ts +11 -0
  51. package/dist/modules/constants.js +41 -7
  52. package/dist/modules/credit_pricing.d.ts +20 -1
  53. package/dist/modules/credit_pricing.js +23 -1
  54. package/dist/modules/credit_runtime.js +33 -16
  55. package/dist/modules/dexbot_class.d.ts +6 -2
  56. package/dist/modules/dexbot_class.js +8 -3
  57. package/dist/modules/dexbot_cow_runtime.d.ts +28 -37
  58. package/dist/modules/dexbot_cow_runtime.js +47 -66
  59. package/dist/modules/dexbot_maintenance_runtime.js +68 -10
  60. package/dist/modules/graceful_shutdown.d.ts +6 -2
  61. package/dist/modules/graceful_shutdown.js +6 -2
  62. package/dist/modules/launcher/bot_supervisor.js +4 -0
  63. package/dist/modules/launcher/credential_daemon.d.ts +14 -2
  64. package/dist/modules/launcher/credential_daemon.js +60 -26
  65. package/dist/modules/launcher/launch_modes.js +6 -3
  66. package/dist/modules/launcher/monolithic_runtime.d.ts +39 -1
  67. package/dist/modules/launcher/monolithic_runtime.js +60 -1
  68. package/dist/modules/launcher/runtime_mode.d.ts +79 -0
  69. package/dist/modules/launcher/runtime_mode.js +223 -0
  70. package/dist/modules/market_adapter_whitelist.d.ts +8 -0
  71. package/dist/modules/market_adapter_whitelist.js +8 -0
  72. package/dist/modules/order/accounting.d.ts +15 -1
  73. package/dist/modules/order/accounting.js +15 -1
  74. package/dist/modules/order/async_lock.d.ts +9 -3
  75. package/dist/modules/order/async_lock.js +9 -3
  76. package/dist/modules/order/export.d.ts +0 -5
  77. package/dist/modules/order/export.js +0 -5
  78. package/dist/modules/order/format.d.ts +6 -4
  79. package/dist/modules/order/format.js +6 -4
  80. package/dist/modules/order/grid.d.ts +36 -18
  81. package/dist/modules/order/grid.js +186 -33
  82. package/dist/modules/order/index.d.ts +16 -1
  83. package/dist/modules/order/index.js +1 -1
  84. package/dist/modules/order/logger_state.d.ts +1 -1
  85. package/dist/modules/order/logger_state.js +1 -1
  86. package/dist/modules/order/manager.d.ts +30 -7
  87. package/dist/modules/order/manager.js +108 -12
  88. package/dist/modules/order/strategy.d.ts +5 -0
  89. package/dist/modules/order/strategy.js +23 -2
  90. package/dist/modules/order/sync_engine.d.ts +26 -11
  91. package/dist/modules/order/sync_engine.js +26 -11
  92. package/dist/modules/order/utils/math.d.ts +100 -22
  93. package/dist/modules/order/utils/math.js +106 -22
  94. package/dist/modules/order/utils/order.d.ts +77 -20
  95. package/dist/modules/order/utils/order.js +125 -27
  96. package/dist/modules/order/utils/system.d.ts +107 -11
  97. package/dist/modules/order/utils/system.js +176 -11
  98. package/dist/modules/order/utils/validate.d.ts +8 -3
  99. package/dist/modules/order/utils/validate.js +10 -3
  100. package/dist/modules/types.d.ts +35 -2
  101. package/dist/modules/utils/asset_symbols.d.ts +5 -5
  102. package/dist/modules/utils/asset_symbols.js +5 -5
  103. package/dist/modules/utils/errors.d.ts +2 -1
  104. package/dist/modules/utils/errors.js +2 -1
  105. package/dist/scripts/analyze-credit.js +64 -23
  106. package/dist/scripts/bts_distribution.d.ts +66 -0
  107. package/dist/scripts/bts_distribution.js +2102 -0
  108. package/dist/scripts/rich_list.d.ts +32 -0
  109. package/dist/scripts/rich_list.js +16 -8
  110. package/dist/scripts/token_distribution.d.ts +45 -0
  111. package/dist/scripts/token_distribution.js +1870 -0
  112. package/dist/unlock.js +91 -42
  113. package/docs/BITSHARES_ONBOARDING.md +7 -0
  114. package/docs/COW_INVARIANTS.md +7 -1
  115. package/docs/DEXBOT_COMPARISON.md +5 -5
  116. package/docs/EVOLUTION.md +10 -8
  117. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +5 -3
  118. package/docs/GRID_PRICE_INVARIANT.md +6 -0
  119. package/docs/GRID_RECALCULATION.md +18 -6
  120. package/docs/LIFECYCLE.md +8 -8
  121. package/docs/LOGGING.md +9 -0
  122. package/docs/MPA_CREDIT_USAGE.md +3 -2
  123. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +121 -4
  124. package/docs/README.md +1 -1
  125. package/docs/WORKFLOW.md +5 -5
  126. package/docs/architecture.md +98 -1
  127. package/market_adapter/README.md +10 -3
  128. package/package.json +5 -1
  129. package/scripts/README.md +85 -148
  130. package/tests/README.md +29 -0
@@ -157,7 +157,7 @@ plans, `LANDED`/`REVERTED`/`SUPERSEDED` statuses, commit hashes, and verificatio
157
157
 
158
158
  ### 1. Gap-Band Orphan — Prevention Plan (P1–P6)
159
159
 
160
- > **Source:** `GAP_BAND_ORPHAN_PREVENTION_PLAN.md` · **Status:** implemented `f94d6ec4` (2026-08-29), with subsequent amendments — landing map below.
160
+ > **Source:** former `GAP_BAND_ORPHAN_PREVENTION_PLAN.md` (deleted 2026-08-31; merged here) · **Status:** implemented `f94d6ec4` (2026-08-29), with subsequent amendments — landing map below.
161
161
 
162
162
  **Landing map (corrected 2026-08-31):**
163
163
  - **P1** — landed `f94d6ec4` (same-batch CANCEL injection in `COWRebalanceEngine.execute` + `_assertGapBandIntactPostCommit` cancelOnly). **REVERTED `e2898e51`** ("remove placement guards that interfered with normal operation") — both sites removed; stranding is now handled by `calculateIdealBoundary` + `LAST-FILL-GUARD` + adoption path (P3 gate removed `e7231534`).
@@ -226,7 +226,7 @@ Sequence `Restored boundary index: 131` *then* `[SNAPSHOT-REJECT] Deleting corru
226
226
 
227
227
  ### 2. Ladder Recenter Orphan — Root Cause (Aug 26–30 2026)
228
228
 
229
- > **Source:** `LADDER_RECENTER_ORPHAN_ROOT_CAUSE.md` · **Status:** fixes #1–#7 landed 2026-08-30.
229
+ > **Source:** former `LADDER_RECENTER_ORPHAN_ROOT_CAUSE.md` (deleted 2026-08-31; merged here) · **Status:** fixes #1–#7 landed 2026-08-30.
230
230
 
231
231
  #### 2.1 Symptom
232
232
 
@@ -317,7 +317,7 @@ Throttle `Structural resync defer` to first/last per cap window (was 120/30s); l
317
317
 
318
318
  ### 3. Orphan-Fill & Fund-Invariant — Root Cause & Fix Plan
319
319
 
320
- > **Source:** `ORPHAN_FILL_INVARIANT_ROOT_CAUSE_AND_FIX.md` · **Status:** P0s + rotation landed `1b27f6eb`/`4838bcb0`/`d808c052`; P1 atomicity partial; duplicate-cancel hard-error and P2 counters still open.
320
+ > **Source:** former `ORPHAN_FILL_INVARIANT_ROOT_CAUSE_AND_FIX.md` (deleted 2026-08-31; merged here) · **Status:** P0s + rotation landed `1b27f6eb`/`4838bcb0`/`d808c052`; P1 atomicity partial; duplicate-cancel hard-error and P2 counters still open.
321
321
  > **Scope:** `dexbot_cow_runtime.ts`, `sync_engine.ts`, `chain_orders.ts`, `dexbot_state_recovery.ts`, `dexbot_maintenance_runtime.ts`, `strategy.ts`, `constants.ts` · **Evidence:** `profiles/logs/<bot>.log` Aug 28 17:40–17:57, Aug 29 15:13–15:19.
322
322
 
323
323
  #### 3.1 TL;DR — one cascade
@@ -388,7 +388,7 @@ All eight surface through `getMetrics()`; the five baseline counters via the exi
388
388
 
389
389
  ### 4. Price-First Alignment Plan
390
390
 
391
- > **Source:** `PRICE_FIRST_ALIGNMENT_PLAN.md` · **Status:** Phase 1 shipped and live as shadow telemetry; Phase 2 projection was enabled (`1bbf1a23`) then **removed** (`3713c496`) after a live-bot incident — the anchor veto overrode chain evidence and drove destructive gap-band cancels. The anchor is now observability-only; the boundary is chain-evidence-derived. Phase 3 is moot (no second write path to retire); boundary geometry is pinned by `tests/test_boundary_anchor_recovery.ts` (ANCHOR-001..004) and `tests/test_grid_price_slot_invariant.ts`.
391
+ > **Source:** former `PRICE_FIRST_ALIGNMENT_PLAN.md` (deleted 2026-08-31; merged here) · **Status:** Phase 1 shipped and live as shadow telemetry; Phase 2 projection was enabled (`1bbf1a23`) then **removed** (`3713c496`) after a live-bot incident — the anchor veto overrode chain evidence and drove destructive gap-band cancels. The anchor is now observability-only; the boundary is chain-evidence-derived. Phase 3 is moot (no second write path to retire); boundary geometry is pinned by `tests/test_boundary_anchor_recovery.ts` (ANCHOR-001..004) and `tests/test_grid_price_slot_invariant.ts`.
392
392
  > **Scope:** grid boundary state `modules/order/` · **Related:** three-layer crawl/anchor/guard fix.
393
393
 
394
394
  #### 4.1 Goal
@@ -642,6 +642,123 @@ required is no longer reachable at runtime.
642
642
  - **Placed is not surplus:** an order inside `SURPLUS_CANCEL_GRACE_MS` is never cancelled by a
643
643
  sweep running on a stale snapshot.
644
644
 
645
+ #### 9.7 The guard was a band, not an economic rule (`c86b4b0e`)
646
+
647
+ **Observed (2026-10-24/25, a live market-pair bot).** A dump swept the grid and the
648
+ market then held. Spread correction planned, the broadcast guard dropped the creates,
649
+ `SPREAD-STALE` reported **84 minutes with no correction placed**, and only a structural
650
+ re-center (grid rebuild) restored the spread. Two distinct guard defects, both from one
651
+ predicate:
652
+
653
+ 1. **The pivot band ignored the fill's side.** `isLastFillGuardBlocked` judged against
654
+ `pivot ± increment/2`:
655
+ ```ts
656
+ BUY blocked if price > pivot * (1 - inc/2/100)
657
+ SELL blocked if price < pivot * (1 + inc/2/100)
658
+ ```
659
+ The `lastType` argument was passed and never read. Consequences: a BUY **below** a SELL
660
+ fill was blocked (the doc claimed "buy-below-sell is never gated"; the code gated it),
661
+ and a SELL 0.2% **above** our cost was blocked after a BUY fill — exactly the spread
662
+ edge, which correction places tighter than a full increment by design. Repair therefore
663
+ depended on the `SPREAD_CORRECTION` bypass, which `09dbaad7` denies whenever a real fill
664
+ reference exists — so after any fill, tightening was structurally impossible.
665
+ 2. **Planner and guard disagreed.** `09dbaad7` intended a planner-side filter against the
666
+ fill reference, but the implementation used the readiness *crossing floor*, which
667
+ prefers a **fresh live market read** over the fill anchor. With a fresh read the planner
668
+ admitted what the guard would drop, producing the live sequence
669
+ `planned 2, placing 1 → Skipping sell CREATE … below last filled → Transient refusal 1/3
670
+ → batch was prepared but not executed` — a whole cycle spent on a guaranteed refusal.
671
+
672
+ **Fix.** Direction only, one predicate shared by both sides:
673
+
674
+ ```ts
675
+ BUY blocked if price >= pivot // never place a higher BUY
676
+ SELL blocked if price <= pivot // never place a lower SELL
677
+ ```
678
+
679
+ Equal price stays blocked (re-place at the filled level). The predicate lives in
680
+ `order/utils/system.ts` next to `resolveLastFillGuardReference`; `dexbot_cow_runtime`
681
+ re-exports it. The planner now filters every candidate pool (and boundary promotion) with
682
+ the **same** predicate before the quota slice, so a batch is never built out of ops the
683
+ guard will drop, and an unplaceable side reports it honestly.
684
+
685
+ **Deliberately not relaxed.** A lower SELL is still refused **when the last fill was a
686
+ SELL**: after a fill the sell window must move *up*, so a sell slot below the last sale is
687
+ evidence that the boundary/crawl is behind the fill — a geometry fault, not a placement
688
+ opportunity. The log confirms it: seven slots (147–153) filled in one sync, the boundary
689
+ then **moved down** to 146 (two commits each dropping owed crawls), leaving slots 151/152
690
+ as sell-zone holes below the last sale. A cost-basis rule (sell only above the last BUY)
691
+ would have *placed into* that corrupted geometry.
692
+
693
+ #### 9.8 Stalls that placement cannot repair get their own clocks
694
+
695
+ Three states were previously indistinguishable from patience and all waited for the
696
+ 30-minute structural window:
697
+
698
+ - **Rail oversubscribed** — `availableFund = chainFree − virtual` reads 0 when the empty
699
+ rail already reserves more than the account holds (live: free 454560.80 vs virtual
700
+ 456046.21, `planned 3, placing 0` for 84 minutes). Named in the log, flagged on the
701
+ manager, escalated on `SPREAD_STALE_FUND_ESCALATE_MS` (5 min).
702
+ - **Geometry bind (`last-fill-blocked`)** — every tightening slot is at/through the last
703
+ fill, i.e. the window is behind the fill. A distinct stall value, preserved through the
704
+ starvation-fallback merge (`mergeSpreadStalls`), escalated on
705
+ `SPREAD_STALE_GEOMETRY_ESCALATE_MS` (10 min).
706
+ - **Oscillating measurement** — one in-tolerance reading no longer clears the persistence
707
+ clock; tolerance must hold for `SPREAD_STALE_IN_TOLERANCE_RESET_MS` (10 min), and a
708
+ placed correction still clears it immediately. A single good glance between refusals was
709
+ what let 84 minutes pass.
710
+
711
+ **RESOLVED (crawl consumption is now scoped).** The clear was ledger-wide while
712
+ the derivation folded a subset. `deriveTargetBoundary` now returns
713
+ `consumedCrawlIds`, the plan carries it to the commit (`_consumePendingFillCrawls`),
714
+ and only the applied records are dropped — a capped fold consumes a same-side
715
+ prefix up to the applied magnitude, so the remainder stays owed exactly once.
716
+ A commit without the wire consumes nothing. The instrumentation below remains
717
+ (and now reports `kept=M`), and the historical leak record is kept for context:
718
+
719
+ **Original finding (leak #6): the crawl ledger dropped records it never applied.** A commit clears
720
+ **all** owed fill crawls whenever the plan's boundary is accepted and not held
721
+ (`_clearPendingFillCrawls('boundary commit')`), while the derivation folds only the subset
722
+ that passes its batch-dedupe, edge classification and `fallbackCap`. Any excluded entry is
723
+ lost — the same class `77e763f6` fixed for the held boundary, still open for the rest, and
724
+ the mechanism behind a multi-slot sweep leaving the boundary *behind* the fills.
725
+
726
+ #### 9.9 Two deadlocks that were bookkeeping, not market (`430dee6a` follow-up)
727
+
728
+ Both incidents in §9.7/§9.8 ended in a rebuild. Neither was a fund shortage and
729
+ neither needed a new guard — each was a self-referential calculation that could
730
+ only be broken from outside.
731
+
732
+ **The budget that vetoed its own placement.** `available = chainFree −
733
+ virtualReservation` is the right question for "how much room is left beyond the
734
+ projected rail", but the correction then spends it on *that same projection*:
735
+ when the rail was sized from a larger balance (or from inventory locked in
736
+ resting orders), the reservation exceeds chain free, `available` reads 0, no
737
+ placement can consume the reservation, and it can never shrink. Live: free
738
+ 454560.80 vs virtual 456046.21 — `planned 3, placing 0` every cycle for 84
739
+ minutes. The fix is arithmetic, not policy: for a known candidate set the budget
740
+ is `min(chainFree, min(virtualReservation, Σ candidate ideals))` when `available`
741
+ is 0 (`deriveChainTruthFundBudget`). Bound on both sides, and the chain rejects
742
+ an over-commit anyway.
743
+
744
+ **The crawl that could not catch up.** A boundary crawl is ±1 slot per committed
745
+ fill, so once a sweep leaves the window *behind* the fill, crawling is
746
+ arithmetically unable to recover: every tightening slot is then at/through the
747
+ fill, `passesLastFill` refuses all of them, and the funds sit in the stranded
748
+ resting inventory. The cheapest repair (rotate the stranded orders down) is
749
+ itself a lower sell, which the same guard forbids — three locks, no key. The fill
750
+ is the anchor: `SELL fill at f => boundary ≥ f − gapSlots`, `BUY fill at f =>
751
+ boundary ≤ f − 1` (`reanchorBoundaryFromLastFill`), subject to a real
752
+ fill-provenanced pivot, an on-ladder price and `validatePersistedBoundary`.
753
+
754
+ **Deliberately rejected: the pair ledger.** Making each fill mint its counter
755
+ order (reserve the exact proceeds) would prove per-trade funding and delete the
756
+ `fund-constrained prefix` logic — but it also turns the ladder into a set of
757
+ independent round trips, so sizes stop following the side budget. Spread repair
758
+ must stay fund-driven from the side pool: a SELL fill returns quote while the
759
+ same-side repair needs base, so no fill can ever fund its own side, and pairing
760
+ would hide that asymmetry instead of resolving it.
761
+
645
762
  ---
646
763
 
647
764
  ### A. Grid-Price Invariant — former failure trace
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.15 (released).
5
+ **Version context:** v1.6.17 (released).
6
6
 
7
7
  ---
8
8
 
package/docs/WORKFLOW.md CHANGED
@@ -257,12 +257,12 @@ the canonical name is preferred in scripts and docs.
257
257
  | `dexbot dw <target>` | — | Dynamic-weight research chart: same targets/flags as `tv` |
258
258
  | `dexbot pnl <account>` | — | HTML PnL report for a bot/account over `--month N`, optional `--pair BASE/QUOTE` filter |
259
259
  | `dexbot git` | — | Analyze repository git history and write an added/deleted-lines HTML chart (`repo-stats.html`; source checkouts only) |
260
- | `dexbot status` | `stat`, `stats` | Unified runtime health — daemon, adapter, bots |
260
+ | `dexbot status` | `stat`, `stats` | Unified runtime health — daemon, adapter, bots. Whole-runtime: an optional bot name is validated, then ignored |
261
261
  | `dexbot start` | `unlock` | Run credential daemon + bot (equivalent to running the `unlock` runtime, `dist/unlock.js`) |
262
- | `dexbot stop` | `stp`, `stopall` | Stop the monolithic runtime (unlock mode) |
263
- | `dexbot reload` | `reloadall` | Reload the monolithic runtime without touching the credential daemon (unlock mode) |
264
- | `dexbot restart` | `restartall` | Restart the monolithic runtime (unlock mode, re-unlocks credential daemon) |
265
- | `dexbot delete` | — | Shut down and clean up the monolithic runtime (unlock mode) |
262
+ | `dexbot stop [<bot>]` | `stp`, `stopall` | Stop the runtime. Monolithic: whole runtime (a bot argument folds into it with a notice); `--isolated`: just that bot |
263
+ | `dexbot reload [<bot>]` | `reloadall` | Reload without touching the credential daemon. Same per-bot target rules as `stop` |
264
+ | `dexbot restart [<bot>]` | `restartall` | Restart and re-unlock the credential daemon. Same per-bot target rules as `stop` |
265
+ | `dexbot delete` | — | Shut down and clean up the monolithic runtime. Whole-runtime only; rejects a bot argument |
266
266
  | `dexbot clear` | — | Delete `*.log`, rotated `*.log.*` and `*.jsonl*` from the logs directory (`<profiles>/logs`) |
267
267
  | `dexbot clear-orders` | — | Delete all persisted order files (`<profiles>/orders`); grids regenerate on next start |
268
268
  | `dexbot clear-market-adapter` | — | Delete market adapter data, state (incl. `market_adapter.lock`), and adapter logs |
@@ -488,7 +488,12 @@ The correction path is fund-only and never manufactures budget by shrinking a re
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
490
  `stall` cause (`no-free-funds` / `unfunded` / `no-candidates` / `cold-book` /
491
- `unmatched-orders` / `readiness-gate` / `batch-not-executed` / `apply-error`).
491
+ `unmatched-orders` / `readiness-gate` / `last-fill-blocked` /
492
+ `batch-not-executed` / `apply-error`). `last-fill-blocked` is the geometry
493
+ bind: every tightening slot on that side is at/through the last fill, so a
494
+ sell slot below the last sale means the boundary/crawl is behind the fill —
495
+ placement cannot repair it and the re-center can, so it escalates on the
496
+ short geometry window.
492
497
  Every cause arms the targeted
493
498
  balances + open-orders refresh: the local snapshot the check reasoned over
494
499
  may be stale (`no-candidates` can mean a missed fill left an ACTIVE slot
@@ -520,6 +525,88 @@ const availableFund = Math.max(0, Math.min(
520
525
  // No resting ACTIVE/PARTIAL order is shrunk to fund the correction.
521
526
  ```
522
527
 
528
+ `availableFund` is `chainFree − virtualReservation`, so it reads 0 when the
529
+ empty rail already reserves more than the chain holds. That state
530
+ (*rail oversubscribed*) is named explicitly in the log and flagged on the
531
+ manager; the out-of-spread watchdog then escalates on its short fund window
532
+ instead of waiting for a fill that cannot free existing inventory.
533
+
534
+ The budget the loop spends is **not** `availableFund`, because subtracting the
535
+ projection from the budget that funds that same projection is circular: a rail
536
+ sized from a larger balance (or from inventory locked in resting orders) reads 0
537
+ forever and no placement can ever shrink it. `deriveChainTruthFundBudget`
538
+ (`order/utils/math.ts`) re-derives it for a known candidate set:
539
+
540
+ ```text
541
+ budget = availableFund > 0 ? availableFund // healthy: accounting wins
542
+ : virtualReservation > chainFree ? min(chainFree, min(virtualReservation, Σ candidate ideals))
543
+ : availableFund // zero for fees/empty balance: honour it
544
+ ```
545
+
546
+ so the correction funds what the chain actually holds free (capped by what the
547
+ candidates need, and the chain stays the final arbiter). Live effect: the
548
+ `planned 3, placing 0` cycle that ran for 84 minutes now places the three holes.
549
+
550
+ ### Owed Fill Crawls: consume what was applied, keep the rest owed
551
+
552
+ Every shift-eligible fill records a relative boundary delta (`_pendingFillCrawls`)
553
+ because the batch that saw the fill may not commit a boundary (refused
554
+ broadcast, held boundary, restart). The derivation folds a *subset* — current-batch
555
+ slots are deduped (their shift comes from `fills`), edge slots never crawl, and
556
+ the cross-chunk budget caps how far one plan may move. So the commit must not
557
+ clear the whole ledger: `deriveTargetBoundary` returns `consumedCrawlIds`
558
+ (what it applied, plus what it deliberately never counts), the plan carries it
559
+ to `_consumePendingFillCrawls` via `buildSuccessResult` → `CowResult` →
560
+ `_commitWorkingGrid({ consumedCrawlIds })`, and only those records are dropped.
561
+ A capped fold consumes a same-side prefix up to the applied magnitude; the rest
562
+ stays owed and applies exactly once on a later derivation. `_clearPendingFillCrawls`
563
+ is the explicit allowed-loss path (rebuild, rejected snapshot, restart replay).
564
+
565
+ ### Boundary Re-Anchoring: the fill is the anchor
566
+
567
+ A boundary crawl is ±1 slot per committed fill, so a window that ends up
568
+ **behind** the newest real fill cannot catch up by crawling — every tightening
569
+ slot on that side is then at/through the fill and `passesLastFill` refuses all of
570
+ them while the funds sit in the resting (stranded) inventory. `reanchorBoundaryFromLastFill`
571
+ (`order/utils/system.ts`, called from `calculateTargetGrid` right after the
572
+ derivation) treats the fill as the anchor:
573
+
574
+ ```text
575
+ SELL fill at slot f -> boundary >= f - gapSlots (sellStart = f + 1)
576
+ BUY fill at slot f -> boundary <= f - 1 (buy window ends below f)
577
+ ```
578
+
579
+ Preconditions, all fail-closed: a real fill-provenanced pivot (a cold/book-seeded
580
+ pivot or a price without a recorded fill side never anchors), an on-ladder price
581
+ within one increment (`off-ladder-fill`), and the candidate must pass
582
+ `validatePersistedBoundary` — a re-anchor that would strand a live order inside
583
+ the re-typed band is refused (`unsafe: placed_order_in_band`). Every accepted
584
+ re-anchor is logged at warn with the fill slot, the pivot price and the boundary
585
+ move.
586
+
587
+ ### Candidate Selection: Spread Edge, Grid Slot, Last-Fill Consistent
588
+
589
+ The planner only ever emits the tightening edge on a real grid slot:
590
+
591
+ - `tightensSpread` — a SELL must improve (be below) the lowest live sell, a BUY
592
+ must improve the highest live buy;
593
+ - `sortCandidates` + `.slice(0, missingSlots)` — the nearest empty level to the
594
+ live edge, so no interior hole is created;
595
+ - `doesNotCrossMarket` — the absolute crossing floor (fresh live read, fill
596
+ reference as fallback);
597
+ - **`passesLastFill`** — the same direction rule the broadcast guard applies
598
+ (`SELL` above the last fill, `BUY` below it), evaluated on the same pivot.
599
+
600
+ The last filter is what keeps planner and guard from disagreeing: without it a
601
+ cycle could plan a candidate the guard was guaranteed to drop, and the whole
602
+ batch would be reported as "prepared but not executed" (observed live: the only
603
+ funded candidate sat at the fill price, both attempts were dropped, and the
604
+ correction spent its cycle on a refusal). With it, an unplaceable side reports
605
+ *no placeable slot — every tightening slot is at/through the last fill* and the
606
+ batch is never built. Only a fill arriving **during** the check can still change
607
+ the pivot under the batch; the final pre-broadcast gate remains the last line
608
+ for that race.
609
+
523
610
  **Benefits**:
524
611
  - ✅ No inventory recycling from stale-size snapshots
525
612
  - ✅ Constant, predictable spread width
@@ -570,6 +657,16 @@ effective correction**:
570
657
  - warns once past `TIMING.SPREAD_STALE_WARN_MS`;
571
658
  - escalates to a structural re-center past `TIMING.SPREAD_STALE_ESCALATE_MS`
572
659
  (cooldown `TIMING.SPREAD_STALE_RESYNC_COOLDOWN_MS`);
660
+ - clears the clock only after the spread has stayed in tolerance for
661
+ `TIMING.SPREAD_STALE_IN_TOLERANCE_RESET_MS` (or immediately on a placed
662
+ correction). A single in-tolerance reading does not clear it: the measured
663
+ spread oscillates around the tolerance edge, and resetting per good glance let
664
+ a live bot sit out of tolerance for 84 minutes while every cycle looked
665
+ recoverable;
666
+ - escalates on a **shorter** window (`TIMING.SPREAD_STALE_FUND_ESCALATE_MS`) when
667
+ the correction reports a rail-oversubscribed fund stall (`virtual` reservation
668
+ > chain free on the corrected side). That state cannot heal by waiting for a
669
+ fill — the rail must be re-sized from chain truth, which the re-center does;
573
670
  - tolerates up to `TIMING.SPREAD_STALE_TRANSIENT_GRACE` consecutive **transient**
574
671
  refusals (which reset the stale clock) before they count toward escalation, so a
575
672
  retryable refusal is not mistaken for a structural dead end — a persistent one
@@ -240,13 +240,18 @@ Pair-specific AMA profiles live in `profiles/market_profiles.json`:
240
240
  "intervalSeconds": 3600,
241
241
  "defaultAma": "AMA1",
242
242
  "amas": {
243
- "AMA1": { "erPeriod": 200, "fastPeriod": 3, "slowPeriod": 80 },
244
- "AMA2": { "erPeriod": 500, "fastPeriod": 5, "slowPeriod": 120 }
243
+ "AMA1": { "erPeriod": 781, "fastPeriod": 5.2, "slowPeriod": 62.1 },
244
+ "AMA2": { "erPeriod": 781, "fastPeriod": 5.2, "slowPeriod": 71.5 }
245
245
  }
246
246
  }]
247
247
  }
248
248
  ```
249
249
 
250
+ > The `amas` periods above are the built-in presets (`MARKET_ADAPTER.AMAS`),
251
+ > shown here only to make the shape concrete. A real pair profile needs just the
252
+ > fields it changes — e.g. `"AMA3": { "slowPeriod": 90 }` keeps the built-in
253
+ > `erPeriod`/`fastPeriod` and overrides only `slowPeriod`.
254
+
250
255
  `profiles/market_adapter_settings.json` layers:
251
256
 
252
257
  ```json
@@ -580,6 +585,7 @@ Typical fields:
580
585
  market_adapter/
581
586
  |-- market_adapter.ts main adapter daemon
582
587
  |-- ama_signal_runner.ts one-cycle JSON signal CLI
588
+ |-- cli_args.ts shared CLI argument walker
583
589
  |-- candle_utils.ts candle transforms, gap detection, pruning
584
590
  |-- interval_utils.ts shared interval label + chain-time helpers
585
591
  |-- lp_chart_core.ts chart HTML renderer
@@ -623,6 +629,7 @@ market_adapter/
623
629
  | |-- file_lock.ts single-instance file lock
624
630
  | |-- file_json_cache.ts write-through JSON read cache
625
631
  | |-- month_shards.ts calendar-month shard naming + coverage-span primitives (shared by candle and fills caches)
632
+ | |-- pair_orientation.ts canonical pair orientation + reciprocal inversion helpers
626
633
  | |-- data_discovery.ts data directory auto-discovery + shard-family assembly
627
634
  | |-- atomic_write.ts atomic file write utility
628
635
  | |-- dynamic_grid_snapshot.ts dynamic grid snapshot helpers
@@ -863,7 +870,7 @@ closed 1h candles.
863
870
 
864
871
  #### Shared Month-Shard Cache and Fetch Robustness
865
872
 
866
- Pool, book, and feed candle fetches share one cache entry point (`runCachedWindows` in `market_adapter/inputs/window_cache.ts`): candles live in fixed calendar-month shards (`<base>.shard_YYYY-MM.json`, UTC) whose names never shift, so a run loads only the shards overlapping its requested range, queries only genuinely missing buckets plus a bounded tail refresh, and rewrites only shards that gained buckets or query coverage — pure-reuse runs perform zero writes and zero deletes. Shard metas record the ranges actually queried (`meta.queriedRanges`, monotonically unioned) together with `at`, the time each query ran; spans merge only when they assert the same verification time, so per-bucket freshness stays exact. A missing range is pruned only when recorded query coverage genuinely covers it — the absence of local buckets alone never certifies history as empty — and only once the range ended more than `GAP_SETTLE_HORIZON_MS` ago, judged per gap rather than per window (a month-old gap at the leading edge of the newest window is as settled as one in a fully past window). The tail window re-queries only buckets that no query has seen `TAIL_SETTLE_LAG_MS` after they closed (`settleCoverage`), so a rerun costs ~lag+elapsed hours instead of a fixed 48h, and the refresh never reaches back past `TAIL_REFRESH_HOURS` (an unsettled bucket must be refreshed because index lag is still open, but a coverage hole older than 48h is past any plausible lag and must not drag the boundary back weeks); caches without `at` fall back to that fixed window. Clusters of gaps within `GAP_MERGE_TOLERANCE_BUCKETS` collapse into one query, and the sub-range path is bounded by merged span hours rather than gap count, so one extra small hole can no longer escalate a run to a full-window fetch. Because spans merge only on an identical `at`, a shard gains one span per re-verifying run; the persisted list is capped at `MAX_COVERAGE_SPANS` by dropping the oldest spans, which can never invent emptiness (it can only make those buckets look unsettled, bounded by the same 48h ceiling). A run that re-verifies the tail therefore rewrites that shard even when the candles come back identical — the moved verification time is the news, and skipping the write would throw it away; pure-reuse runs still write nothing. Partial windows merge into the run output but are never persisted. Stable month shards are the only supported cache format; obsolete run-relative cache files are ignored. Every range fetch runs through `fetchRangeWithRetry` (per-range attempts + linear backoff + abort-signal timeout; the LP path keeps a 4-attempt budget), one-shot Kibana queries retry transient errors (3 attempts), paged fetchers cap at `kibanaMaxPages` (500), and bidirectional fetches tolerate a one-direction failure.
873
+ Pool, book, and feed candle fetches share one cache entry point (`runCachedWindows` in `market_adapter/inputs/window_cache.ts`): candles live in fixed calendar-month shards (`<base>.shard_YYYY-MM.json`, UTC) whose names never shift, so a run loads only the shards overlapping its requested range, queries only genuinely missing buckets plus a bounded tail refresh, and rewrites only shards that gained buckets or query coverage — pure-reuse runs perform zero writes and zero deletes. Shard metas record the ranges actually queried (`meta.queriedRanges`, monotonically unioned) together with `at`, the time each query ran; spans merge only when they assert the same verification time, so per-bucket freshness stays exact. A missing range is pruned only when recorded query coverage genuinely covers it — the absence of local buckets alone never certifies history as empty — and only once the range ended more than `GAP_SETTLE_HORIZON_MS` ago, judged per gap rather than per window (a month-old gap at the leading edge of the newest window is as settled as one in a fully past window). The tail window re-queries only buckets that no query has seen `TAIL_SETTLE_LAG_MS` after they closed (`settleCoverage`), so a rerun costs ~lag+elapsed hours instead of a fixed 48h, and the refresh never reaches back past `TAIL_REFRESH_HOURS` (an unsettled bucket must be refreshed because index lag is still open, but a coverage hole older than 48h is past any plausible lag and must not drag the boundary back weeks); caches without `at` fall back to that fixed window. Clusters of gaps within `GAP_MERGE_TOLERANCE_BUCKETS` collapse into one query, and the sub-range path is bounded by merged span hours rather than gap count, so one extra small hole can no longer escalate a run to a full-window fetch. Because spans merge only on an identical `at`, a shard gains one span per re-verifying run; the persisted list is capped at `MAX_COVERAGE_SPANS` by dropping the oldest spans, which can never invent emptiness (it can only make those buckets look unsettled, bounded by the same 48h ceiling). A run that re-verifies the tail therefore rewrites that shard even when the candles come back identical — the moved verification time is the news, and skipping the write would throw it away; pure-reuse runs still write nothing. Partial windows merge into the run output but are never persisted. Stable month shards are the only supported cache format; obsolete run-relative cache files are ignored. Pair orientation is canonicalized (the lower asset id is always leg A on disk), so `bts/iob.xrp` and `iob.xrp/bts` share one shard family: the fetch queries the canonical side and the result is inverted back for the requested side (inverse volume uses the same base×close approximation as the TV chart's inverse view). A legacy inverse-orientation family is read once as a migration source and folded into the canonical shards instead of being re-fetched. Every range fetch runs through `fetchRangeWithRetry` (per-range attempts + linear backoff + abort-signal timeout; the LP path keeps a 4-attempt budget), one-shot Kibana queries retry transient errors (3 attempts), paged fetchers cap at `kibanaMaxPages` (500), and bidirectional fetches tolerate a one-direction failure.
867
874
 
868
875
  #### AMA Warmup Window — Why Candle Length Matters
869
876
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dexbot",
3
- "version": "1.6.15",
3
+ "version": "1.6.17",
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": {
@@ -99,6 +99,8 @@
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
101
  "richlist": "npm run build && node dist/scripts/rich_list.js",
102
+ "distribution": "npm run build && node dist/scripts/bts_distribution.js",
103
+ "token-distribution": "npm run build && node dist/scripts/token_distribution.js",
102
104
  "native:release-gates": "npm run build && npm run build:tests && node dist/scripts/native_release_gates.js",
103
105
  "native:serial-snapshots": "npm run build && npm run build:tests && node dist/tests/test_native_serial_ops.js",
104
106
  "native:ecc-invariants": "npm run build && npm run build:tests && node dist/tests/test_native_ecc.js",
@@ -109,6 +111,7 @@
109
111
  "verify:browser-bundle": "npm run build && node dist/scripts/verify-browser-bundle.js",
110
112
  "test": "npm run build && npm run build:tests && npm run build --prefix claw && node dist/scripts/run-tests.js",
111
113
  "test:live": "RUN_LIVE_BITSHARES_TESTS=1 npm run build && npm run build:tests && npm run build --prefix claw && node dist/scripts/run-tests.js",
114
+ "test:playwright": "npm run build && NODE_PATH=\"$(npm root -g)\" playwright test --config tests/playwright/playwright.config.mjs",
112
115
  "clean": "node scripts/clean-dist.js",
113
116
  "build": "echo \"tsc is compiling ...\" && tsc && chmod +x dist/dexbot.js dist/bot.js dist/unlock.js dist/pm2.js dist/credential-daemon.js",
114
117
  "build:clean": "npm run clean && npm run build",
@@ -157,6 +160,7 @@
157
160
  "./dist/modules/launcher/status_reporting.js": false,
158
161
  "./dist/modules/launcher/supervisor_control.js": false,
159
162
  "./dist/modules/launcher/monolithic_runtime.js": false,
163
+ "./dist/modules/launcher/runtime_mode.js": false,
160
164
  "./dist/modules/launcher/market_adapter_runtime.js": false,
161
165
  "./dist/modules/launcher/market_adapter_watchdog.js": false,
162
166
  "./dist/modules/launcher/foreign_cred_daemon.js": false,