dexbot 1.6.16 → 1.6.18

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 (124) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/analysis/README.md +10 -9
  3. package/analysis/ama_fitting/README.md +2 -2
  4. package/analysis/bot_fitting/README.md +3 -3
  5. package/analysis/tradingview/README.md +2 -2
  6. package/analysis/trend_detection/DYNAMIC_WEIGHT_RESEARCH.md +1 -1
  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/analyze_args.d.ts +2 -1
  12. package/dist/analysis/fills_source.d.ts +1 -8
  13. package/dist/analysis/fills_source.js +1 -1
  14. package/dist/analysis/grid_correction_check.d.ts +9 -6
  15. package/dist/analysis/grid_correction_check.js +56 -64
  16. package/dist/analysis/math_utils.d.ts +1 -1
  17. package/dist/analysis/trade_profitability.d.ts +1 -1
  18. package/dist/analysis/tradingview/grid_reset_sim.js +1 -1
  19. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +7 -7
  20. package/dist/analysis/trend_detection/backtest_ama_slope_huber.js +1 -1
  21. package/dist/analysis/trend_detection/huber_scale_variants.d.ts +4 -3
  22. package/dist/market_adapter/cli_args.d.ts +6 -1
  23. package/dist/market_adapter/cli_args.js +16 -2
  24. package/dist/market_adapter/core/kibana_candles.d.ts +5 -1
  25. package/dist/market_adapter/core/kibana_candles.js +3 -1
  26. package/dist/market_adapter/core/strategies/regime_gate.d.ts +7 -1
  27. package/dist/market_adapter/core/strategies/regime_gate.js +3 -1
  28. package/dist/market_adapter/inputs/cex_candle_parsing.d.ts +7 -2
  29. package/dist/market_adapter/inputs/cex_candle_parsing.js +3 -1
  30. package/dist/market_adapter/inputs/fetch_book_data.d.ts +7 -1
  31. package/dist/market_adapter/inputs/fetch_book_data.js +3 -1
  32. package/dist/market_adapter/inputs/fetch_cex_synthetic_data.js +2 -11
  33. package/dist/market_adapter/inputs/fetch_lp_data.d.ts +26 -1
  34. package/dist/market_adapter/inputs/fetch_lp_data.js +62 -52
  35. package/dist/market_adapter/inputs/kibana_feed_source.d.ts +14 -2
  36. package/dist/market_adapter/inputs/kibana_feed_source.js +14 -1
  37. package/dist/market_adapter/inputs/window_cache.d.ts +14 -3
  38. package/dist/market_adapter/inputs/window_cache.js +14 -1
  39. package/dist/market_adapter/lp_chart_runner.d.ts +12 -9
  40. package/dist/market_adapter/lp_chart_runner.js +3 -1
  41. package/dist/market_adapter/lp_chart_strategy_loader.d.ts +5 -1
  42. package/dist/market_adapter/lp_chart_strategy_loader.js +3 -1
  43. package/dist/market_adapter/market_adapter.d.ts +10 -2
  44. package/dist/market_adapter/market_adapter.js +10 -11
  45. package/dist/market_adapter/utils/chain.d.ts +2 -3
  46. package/dist/market_adapter/utils/file_json_cache.d.ts +5 -1
  47. package/dist/market_adapter/utils/file_json_cache.js +3 -1
  48. package/dist/market_adapter/utils/file_lock.js +1 -1
  49. package/dist/market_adapter/utils/native_history.d.ts +7 -3
  50. package/dist/market_adapter/utils/native_history.js +3 -1
  51. package/dist/market_adapter/utils/pair_orientation.d.ts +2 -2
  52. package/dist/modules/account_bots.d.ts +3 -0
  53. package/dist/modules/bots_file_lock.d.ts +2 -2
  54. package/dist/modules/bots_file_lock.js +2 -2
  55. package/dist/modules/chain_keys.d.ts +1 -1
  56. package/dist/modules/constants.d.ts +6 -0
  57. package/dist/modules/constants.js +37 -6
  58. package/dist/modules/credit_pricing.d.ts +20 -1
  59. package/dist/modules/credit_pricing.js +23 -1
  60. package/dist/modules/credit_runtime.js +33 -16
  61. package/dist/modules/dexbot_class.d.ts +11 -1
  62. package/dist/modules/dexbot_class.js +15 -2
  63. package/dist/modules/dexbot_cow_runtime.d.ts +90 -38
  64. package/dist/modules/dexbot_cow_runtime.js +507 -108
  65. package/dist/modules/dexbot_credential_client.d.ts +5 -0
  66. package/dist/modules/dexbot_maintenance_runtime.js +117 -12
  67. package/dist/modules/dexbot_startup_runtime.js +7 -1
  68. package/dist/modules/graceful_shutdown.d.ts +2 -2
  69. package/dist/modules/graceful_shutdown.js +2 -2
  70. package/dist/modules/launcher/credential_daemon.d.ts +14 -2
  71. package/dist/modules/launcher/credential_daemon.js +60 -26
  72. package/dist/modules/launcher/runtime_mode.d.ts +4 -3
  73. package/dist/modules/node_manager.d.ts +1 -1
  74. package/dist/modules/node_manager.js +1 -1
  75. package/dist/modules/order/accounting.js +2 -1
  76. package/dist/modules/order/export.d.ts +2 -2
  77. package/dist/modules/order/export.js +2 -2
  78. package/dist/modules/order/grid.d.ts +26 -14
  79. package/dist/modules/order/grid.js +416 -73
  80. package/dist/modules/order/grid_reconcile.js +5 -1
  81. package/dist/modules/order/grid_reconcile_internal.js +2 -1
  82. package/dist/modules/order/index.d.ts +22 -1
  83. package/dist/modules/order/manager.d.ts +40 -7
  84. package/dist/modules/order/manager.js +149 -23
  85. package/dist/modules/order/strategy.d.ts +5 -0
  86. package/dist/modules/order/strategy.js +44 -3
  87. package/dist/modules/order/sync_engine.d.ts +12 -1
  88. package/dist/modules/order/sync_engine.js +135 -20
  89. package/dist/modules/order/utils/math.d.ts +49 -10
  90. package/dist/modules/order/utils/math.js +71 -14
  91. package/dist/modules/order/utils/order.d.ts +65 -11
  92. package/dist/modules/order/utils/order.js +198 -28
  93. package/dist/modules/order/utils/system.d.ts +112 -2
  94. package/dist/modules/order/utils/system.js +338 -12
  95. package/dist/modules/order/utils/validate.d.ts +4 -1
  96. package/dist/modules/order/utils/validate.js +9 -2
  97. package/dist/modules/storage/index.d.ts +3 -2
  98. package/dist/modules/storage/index.js +3 -2
  99. package/dist/modules/types.d.ts +44 -2
  100. package/dist/scripts/analyze-credit.js +64 -23
  101. package/dist/scripts/bts_distribution.d.ts +66 -0
  102. package/dist/scripts/bts_distribution.js +2102 -0
  103. package/dist/scripts/token_distribution.d.ts +45 -0
  104. package/dist/scripts/token_distribution.js +1870 -0
  105. package/dist/unlock.js +42 -24
  106. package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -1
  107. package/docs/COW_INVARIANTS.md +24 -8
  108. package/docs/DEXBOT_COMPARISON.md +5 -5
  109. package/docs/EVOLUTION.md +10 -8
  110. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +13 -11
  111. package/docs/GRID_PRICE_INVARIANT.md +29 -3
  112. package/docs/GRID_RECALCULATION.md +3 -3
  113. package/docs/GRID_RECONCILE.md +5 -5
  114. package/docs/LIFECYCLE.md +11 -11
  115. package/docs/LOGGING.md +22 -0
  116. package/docs/MPA_CREDIT_USAGE.md +3 -2
  117. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +236 -32
  118. package/docs/README.md +1 -1
  119. package/docs/architecture.md +205 -6
  120. package/docs/developer_guide.md +12 -0
  121. package/market_adapter/README.md +11 -6
  122. package/modules/README.md +18 -14
  123. package/package.json +6 -3
  124. package/scripts/README.md +85 -148
@@ -484,11 +484,24 @@ The correction path is fund-only and never manufactures budget by shrinking a re
484
484
  it cannot move bestBuy/bestSell and cannot narrow the spread.
485
485
  4. Contiguous gap-slot promotion may extend the window while preserving
486
486
  MIN_SPREAD_ORDERS and the opposite placed rail.
487
- 5. If free funds cannot cover every target, place the affordable prefix, stop
488
- without shrinking inventory, and log the fund-constrained remainder.
487
+ 5. If free funds cannot cover every target, place the affordable prefix, then
488
+ **rotate a resting same-side order** into each unfunded promoted gap slot
489
+ (same booked size, never a new commitment). A fully allocated rail has ~0
490
+ free forever, so create-only repair can never close the spread; the rotation
491
+ is the repair path and is bounded by the same promotion, crossing, last-fill,
492
+ dedupe/duplicate-price and edge-order guards as a create. It never shrinks or
493
+ grows the moved order. Exactly-zero free on both sides is covered by a
494
+ rotation-only fallback around side selection (an unavailable market price is
495
+ still a hard skip: cross-asset comparison is unsafe).
489
496
  6. If neither side places an effective order, `checkSpreadCondition` reports a
490
497
  `stall` cause (`no-free-funds` / `unfunded` / `no-candidates` / `cold-book` /
491
- `unmatched-orders` / `readiness-gate` / `batch-not-executed` / `apply-error`).
498
+ `unmatched-orders` / `readiness-gate` / `last-fill-blocked` /
499
+ `batch-not-executed` / `apply-error`). `last-fill-blocked` is the geometry
500
+ bind: every tightening slot on that side is at/through the last fill, so a
501
+ sell slot below the last sale means the boundary/crawl is behind the fill —
502
+ placement cannot repair it and the re-center can, so it escalates on the
503
+ short geometry window (at most once per fill pivot: a re-center does not move
504
+ the pivot, so a repeat attempt would only churn the new generation).
492
505
  Every cause arms the targeted
493
506
  balances + open-orders refresh: the local snapshot the check reasoned over
494
507
  may be stale (`no-candidates` can mean a missed fill left an ACTIVE slot
@@ -516,10 +529,186 @@ const availableFund = Math.max(0, Math.min(
516
529
  manager.accountTotals[side === 'buy' ? 'buyFree' : 'sellFree']
517
530
  ));
518
531
 
519
- // Each target is created or topped up only while remainingBudget covers it.
520
- // No resting ACTIVE/PARTIAL order is shrunk to fund the correction.
532
+ // Each target is created only while remainingBudget covers it.
533
+ // If the budget cannot fund a promoted gap slot, a resting same-side ACTIVE
534
+ // order is rotated into that slot at its booked size (no new commitment).
535
+ // No resting ACTIVE/PARTIAL order is shrunk or grown to fund the correction.
521
536
  ```
522
537
 
538
+ `availableFund` is `chainFree − virtualReservation`, so it reads 0 when the
539
+ empty rail already reserves more than the chain holds. That state
540
+ (*rail oversubscribed*) is named explicitly in the log and flagged on the
541
+ manager; the out-of-spread watchdog then escalates on its short fund window
542
+ instead of waiting for a fill that cannot free existing inventory.
543
+
544
+ The budget the loop spends is **not** `availableFund`, because subtracting the
545
+ projection from the budget that funds that same projection is circular: a rail
546
+ sized from a larger balance (or from inventory locked in resting orders) reads 0
547
+ forever and no placement can ever shrink it. `deriveChainTruthFundBudget`
548
+ (`order/utils/math.ts`) re-derives it for a known candidate set:
549
+
550
+ ```text
551
+ budget = availableFund > 0 ? availableFund // healthy: accounting wins
552
+ : virtualReservation > chainFree ? min(chainFree, min(virtualReservation, Σ candidate ideals))
553
+ : availableFund // zero for fees/empty balance: honour it
554
+ ```
555
+
556
+ so the correction funds what the chain actually holds free (capped by what the
557
+ candidates need, and the chain stays the final arbiter). Live effect: the
558
+ `planned 3, placing 0` cycle that ran for 84 minutes now places the three holes.
559
+
560
+ ### Owed Fill Crawls: consume what was applied, keep the rest owed
561
+
562
+ Every shift-eligible fill records a relative boundary delta (`_pendingFillCrawls`)
563
+ because the batch that saw the fill may not commit a boundary (refused
564
+ broadcast, held boundary, restart). The derivation folds a *subset* — current-batch
565
+ slots are deduped (their shift comes from `fills`), edge slots never crawl, and
566
+ the cross-chunk budget caps how far one plan may move. So the commit must not
567
+ clear the whole ledger: `deriveTargetBoundary` returns `consumedCrawlIds`
568
+ (what it applied, plus what it deliberately never counts), the plan carries it
569
+ to `_consumePendingFillCrawls` via `buildSuccessResult` → `CowResult` →
570
+ `_commitWorkingGrid({ consumedCrawlIds })`, and only those records are dropped.
571
+ A capped fold consumes a same-side prefix up to the applied magnitude; the rest
572
+ stays owed and applies exactly once on a later derivation. `_clearPendingFillCrawls`
573
+ is the explicit allowed-loss path (rebuild, rejected snapshot, restart replay).
574
+
575
+ ### Boundary Re-Anchoring: the fill is the anchor
576
+
577
+ A boundary crawl is ±1 slot per committed fill, so a window that ends up
578
+ **behind** the newest real fill cannot catch up by crawling — every tightening
579
+ slot on that side is then at/through the fill and `passesLastFill` refuses all of
580
+ them while the funds sit in the resting (stranded) inventory. `reanchorBoundaryFromLastFill`
581
+ (`order/utils/system.ts`, called from `calculateTargetGrid` right after the
582
+ derivation) treats the fill as the anchor:
583
+
584
+ ```text
585
+ SELL fill at slot f -> boundary >= f - gapSlots (sellStart = f + 1)
586
+ BUY fill at slot f -> boundary <= f - 1 (buy window ends below f)
587
+ ```
588
+
589
+ Preconditions, all fail-closed: a real fill-provenanced pivot (`lastFillPivotSource`
590
+ must be `fill`; a book-seeded max-bid/min-ask heuristic never anchors, and the
591
+ bot-scoped last-market-fill row is the fallback), an on-ladder price within one
592
+ increment (`off-ladder-fill`), a target that actually puts the fill outside the
593
+ window after the grid-ceiling clamp (`ceiling-clamped`), and the candidate must
594
+ pass `validatePersistedBoundary` — the SAME gate the restore and commit paths
595
+ use (`validatePersistedBoundary` is the disk-trust wrapper over
596
+ `validateBoundaryCommit`: in-band placement rejection plus an optional
597
+ allow-list), so every boundary writer ends in one validator.
598
+
599
+ **Eligibility is the crawl's eligibility.** EDGE-pinned insurance fills never
600
+ arm the pivot (`recordLastFilledPrices` skips them via
601
+ `collectEdgePinnedFillIds`) and therefore never anchor: an edge order is static
602
+ fat-finger insurance, not market movement, and an absolute anchor from a
603
+ rail-edge price would teleport the window to that edge (observed: boundary 29 →
604
+ 0 after a floor insurance BUY filled on a 60-slot ladder). PARTIAL fills DO
605
+ anchor — a partial at a far slot is still a real trade, and its residual is the
606
+ allow-listed case below.
607
+
608
+ A live order inside the re-typed band still refuses the re-anchor
609
+ (`unsafe: placed_order_in_band`) with one deliberate exception: the fill's
610
+ **own PARTIAL residual** at the anchor slot (same side, same ladder level) is
611
+ allow-listed, because any boundary that puts the fill outside its window
612
+ necessarily puts that remainder inside the band. A partial fill therefore no
613
+ longer deadlocks the geometry; GAP-EVAC cleans the residual afterwards.
614
+ Because that remainder is persisted in-band, the startup and recovery load
615
+ paths pass `tolerateTransientStranding` and keep the boundary
616
+ (warn + load) instead of rebuilding it away. Every accepted re-anchor is logged
617
+ at warn with the fill slot, the pivot price and the boundary move.
618
+
619
+ The re-anchor is an **absolute** anchor. Its accepted result subsumes every
620
+ pending crawl snapshot taken at plan time (`consumedCrawlIds` is replaced with
621
+ the whole snapshot in `calculateTargetGrid`), otherwise a later derivation could
622
+ apply those older deltas on top of the re-anchored boundary. Records recorded
623
+ after plan-build are not in the snapshot and stay owed for the next cycle.
624
+
625
+ The anchor slot is the current fill batch's **extremum** for that side (max slot
626
+ for SELL, min slot for BUY), resolved from each fill's real execution price with
627
+ the slot id only as a legacy fallback. The guard pivot is the *last-processed*
628
+ fill, which a chunked sweep overwrites per chunk (live: 1366 → 1349 → 1361);
629
+ anchoring on it leaves the furthest fill's counter order inside the implied
630
+ band. `calculateTargetGrid` passes the batch into
631
+ `reanchorBoundaryFromLastFill`.
632
+
633
+ ### Rail-Derived Commit Boundary (counter orders are the fact)
634
+
635
+ A plan built at a re-anchored boundary places **counter orders** on the promoted
636
+ rail (`SELL fill at s => counter BUY at s - gapSlots`). If the refill hold then
637
+ keeps the old committed boundary because the opposite-side refills were
638
+ guard-skipped, those counters are reclassified as in-band and the next plan
639
+ places sells on top of them (live 2026‑10‑30: counters at 1329.7–1345.7 were
640
+ held behind boundary 133, then sells were rotated onto 1345.728664 — the exact
641
+ price of the buy that had just filled; visible spread 1.5% → 0.3%).
642
+
643
+ `deriveRailBoundary` (`dexbot_cow_runtime.ts`, pre-broadcast) therefore clamps
644
+ the boundary to the batch's resulting rails — the batch's own op destinations
645
+ plus the master rail orders that sit on their own side of the planned boundary
646
+ (a BUY at/below it, a SELL at/above the implied sellStart):
647
+
648
+ ```text
649
+ maxBuyIdx <= boundary <= minSellIdx - gapSlots - 1
650
+ ```
651
+
652
+ Counter orders win over empty refill holes. When the batch placed nothing above
653
+ the committed boundary, the clamp is a no-op and the refill hold is unchanged.
654
+
655
+ **Strays do not clamp, and rail indices come from the live price.** A master
656
+ rail order parked on the wrong side of the planned boundary is a *stray* — a
657
+ refused-commit adoption at an old generation level, a SPREAD-GUARD straggler, a
658
+ stranded hold — and is skipped (counted in the log line), because letting it
659
+ clamp would SELF-LEGALIZE the corrupt state (live class: one live sell 18 slots
660
+ below clamped the boundary 138 → 115 and re-typed the whole window). Its rail
661
+ index is the order's LIVE chain price mapped onto the ladder
662
+ (`resolveLiveOrderLadderPosition`), not the slot id, for the same reason the
663
+ fill/gap/crossing paths are live-price: a stale slot id misplaces the order.
664
+
665
+ A crossed or over-ceiling rail fails closed (`rail-crossed` /
666
+ `rail-exceeds-grid`): keep the previous boundary, never legalize the overlap;
667
+ GAP-EVAC / the next plan owns the offending order. The result is then passed
668
+ through the shared `validatePersistedBoundary` gate (skipped only for a sparse
669
+ ladder, whose array-length ceiling would reject everything), with the slots the
670
+ 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.
672
+
673
+ ### Live-Price Provenance (fill, gap, crossing)
674
+
675
+ A refused-commit adoption can leave a master slot keyed at an old generation
676
+ price while its chain order rests elsewhere (slot-118 @1267 vs a trade at
677
+ 1345.73). The grid slot keeps that identity price (`GRID-PRICE-INVARIANT`); the
678
+ **transient decisions** use the live chain price:
679
+
680
+ - fill records pin the execution price from paid/received amounts (or the chain
681
+ order price), so the last-fill pivot and the re-anchor judge the real market;
682
+ - gap-evacuation geometry maps the live price onto the ladder
683
+ (`resolveLiveOrderLadderPosition`) before falling back to the slot index, and
684
+ a price mismatch whose live price is in-band queues a cancel-only evacuation
685
+ ahead of any plain re-price;
686
+ - the crossing-guard candidate set uses the live price, so an emission cannot
687
+ print onto a live opposite-side order that was adopted at a stale slot price.
688
+
689
+ ### Candidate Selection: Spread Edge, Grid Slot, Last-Fill Consistent
690
+
691
+ The planner only ever emits the tightening edge on a real grid slot:
692
+
693
+ - `tightensSpread` — a SELL must improve (be below) the lowest live sell, a BUY
694
+ must improve the highest live buy;
695
+ - `sortCandidates` + `.slice(0, missingSlots)` — the nearest empty level to the
696
+ live edge, so no interior hole is created;
697
+ - `doesNotCrossMarket` — the absolute crossing floor (fresh live read, fill
698
+ reference as fallback);
699
+ - **`passesLastFill`** — the same direction rule the broadcast guard applies
700
+ (`SELL` above the last fill, `BUY` below it), evaluated on the same pivot.
701
+
702
+ The last filter is what keeps planner and guard from disagreeing: without it a
703
+ cycle could plan a candidate the guard was guaranteed to drop, and the whole
704
+ batch would be reported as "prepared but not executed" (observed live: the only
705
+ funded candidate sat at the fill price, both attempts were dropped, and the
706
+ correction spent its cycle on a refusal). With it, an unplaceable side reports
707
+ *no placeable slot — every tightening slot is at/through the last fill* and the
708
+ batch is never built. Only a fill arriving **during** the check can still change
709
+ the pivot under the batch; the final pre-broadcast gate remains the last line
710
+ for that race.
711
+
523
712
  **Benefits**:
524
713
  - ✅ No inventory recycling from stale-size snapshots
525
714
  - ✅ Constant, predictable spread width
@@ -570,6 +759,16 @@ effective correction**:
570
759
  - warns once past `TIMING.SPREAD_STALE_WARN_MS`;
571
760
  - escalates to a structural re-center past `TIMING.SPREAD_STALE_ESCALATE_MS`
572
761
  (cooldown `TIMING.SPREAD_STALE_RESYNC_COOLDOWN_MS`);
762
+ - clears the clock only after the spread has stayed in tolerance for
763
+ `TIMING.SPREAD_STALE_IN_TOLERANCE_RESET_MS` (or immediately on a placed
764
+ correction). A single in-tolerance reading does not clear it: the measured
765
+ spread oscillates around the tolerance edge, and resetting per good glance let
766
+ a live bot sit out of tolerance for 84 minutes while every cycle looked
767
+ recoverable;
768
+ - escalates on a **shorter** window (`TIMING.SPREAD_STALE_FUND_ESCALATE_MS`) when
769
+ the correction reports a rail-oversubscribed fund stall (`virtual` reservation
770
+ > chain free on the corrected side). That state cannot heal by waiting for a
771
+ fill — the rail must be re-sized from chain truth, which the re-center does;
573
772
  - tolerates up to `TIMING.SPREAD_STALE_TRANSIENT_GRACE` consecutive **transient**
574
773
  refusals (which reset the stale clock) before they count toward escalation, so a
575
774
  retryable refusal is not mistaken for a structural dead end — a persistent one
@@ -705,7 +904,7 @@ PIPELINE_TIMING: {
705
904
  - `isPipelineEmpty()` tracks when pipeline operations started blocking via `_pipelineBlockedSince` timestamp
706
905
  - If blockage exceeds 5 minutes, `clearStalePipelineOperations()` is called
707
906
  - Non-destructive recovery: clears operation flags only, does NOT delete orders or modify grid state
708
- - Recovery called from `_executeMaintenanceLogic()` during periodic maintenance checks
907
+ - Recovery called from `executeMaintenanceLogic()` during periodic maintenance checks
709
908
 
710
909
  **Location**: `modules/order/manager.ts` (`isPipelineEmpty()` and `clearStalePipelineOperations()`)
711
910
 
@@ -279,6 +279,18 @@ const normalized = normalizeInt(currentSizeInt, assetPrecision);
279
279
 
280
280
  ---
281
281
 
282
+ ## Export Surface & Test Seams
283
+
284
+ Three rules keep the module surface honest once you start narrowing it.
285
+
286
+ **1. Declaration emit is a real consumer.** A type used only inside its own module can still be unnameable from a dependent package's `.d.ts`. The claw wrapper infers `Promise<CredentialDaemonResponse>` from `modules/dexbot_credential_client.ts`, so de-exporting that interface broke `npm run build --prefix claw` with `TS4058` even though nothing imports it by name. Before narrowing an export, run `npm run build --prefix claw` as well as `npm run typecheck`; when a type must stay exported purely for emit, say so in its JSDoc.
287
+
288
+ **2. The shipped `dist/` is a public API.** The package publishes compiled JS plus declarations, so dropping an optional positional parameter is breaking even when every in-repo caller is updated (for example `calculateOrderSizes`, `calculateRotationOrderSizes` and `allocateFundsByWeights` lost their unused `minSize` arguments). The changelog is written at release time, so call the break out in the next release entry instead of leaving it implicit.
289
+
290
+ **3. Test-only helpers live in one `__test` object.** White-box helpers that only tests call are grouped as `export const __test = { ... }` instead of individual named exports, so a dead-export scan does not have to special-case them. Nothing outside the defining module may reference `__test` — `tests/test_public_surface_guard.ts` fails the suite if production code imports the seam or if it is touched more than once in its own module.
291
+
292
+ ---
293
+
282
294
  ## Module Deep Dive
283
295
 
284
296
  ### OrderManager (`modules/order/manager.ts`)
@@ -241,13 +241,13 @@ Pair-specific AMA profiles live in `profiles/market_profiles.json`:
241
241
  "defaultAma": "AMA1",
242
242
  "amas": {
243
243
  "AMA1": { "erPeriod": 781, "fastPeriod": 5.2, "slowPeriod": 62.1 },
244
- "AMA2": { "erPeriod": 781, "fastPeriod": 5.2, "slowPeriod": 72.0 }
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 fitted built-in presets (`MARKET_ADAPTER.AMAS`),
250
+ > The `amas` periods above are the built-in presets (`MARKET_ADAPTER.AMAS`),
251
251
  > shown here only to make the shape concrete. A real pair profile needs just the
252
252
  > fields it changes — e.g. `"AMA3": { "slowPeriod": 90 }` keeps the built-in
253
253
  > `erPeriod`/`fastPeriod` and overrides only `slowPeriod`.
@@ -405,6 +405,10 @@ node dist/market_adapter/inputs/fetch_lp_data.js --pool <poolId> --precA <precA>
405
405
  npm run lp:chart -- --data market_adapter/data/lp/<pair>/lp_pool_<id>_<interval>.json
406
406
  ```
407
407
 
408
+ The LP exporter also accepts `--chunkMonths <n>` (fetch window size in months),
409
+ `--apiKey <key>` (Kibana API key when the endpoint requires auth), `--out <file>`
410
+ (explicit output path), and `--help`. Unknown flags are rejected.
411
+
408
412
  Research and calibration:
409
413
 
410
414
  ```bash
@@ -445,8 +449,9 @@ operation:
445
449
  node dist/market_adapter/market_adapter.js
446
450
  ```
447
451
 
448
- The adapter acts only on closed 1h candles. It can poll more often, but live
449
- updates wait for the next completed candle.
452
+ The adapter acts only on closed candles at the configured interval (default
453
+ 1h). It can poll more often, but live updates wait for the next completed
454
+ candle.
450
455
 
451
456
  ### Signal Pipeline
452
457
 
@@ -485,7 +490,7 @@ Per cycle, per processed bot, the adapter can produce:
485
490
  4. Read `startPrice` to choose the candle source: `pool`, `book`, or fixed.
486
491
  5. Sync candle data from Kibana or native BitShares data, using the selected source.
487
492
  6. Repair missing candle gaps: auto-fill gaps ≤24 candles directly (no Kibana), query Kibana only for gaps beyond that threshold. Kibana returning empty is treated as verified no-trade. Writes are suppressed while gaps remain unresolved.
488
- 7. Ignore still-forming 1h candles.
493
+ 7. Ignore still-forming candles at the configured interval.
489
494
  8. Compute AMA center, trend, ATR, weights, and collateral hint.
490
495
  9. Persist the first accepted center, compare center delta, and compare whitelisted range-scaling slope delta.
491
496
  10. Suppress live writes if the bot is not whitelisted or candle data is stale.
@@ -866,7 +871,7 @@ are merged in, or an empty response is treated as verified no-trade (all gaps
866
871
  in the queried window are synthesized). Gaps remaining after both steps
867
872
  suppress writes via `unresolved_candle_gaps` until repaired on a future cycle.
868
873
  The adapter prunes old candles to the required AMA window and acts only on
869
- closed 1h candles.
874
+ closed candles at the configured interval.
870
875
 
871
876
  #### Shared Month-Shard Cache and Fetch Robustness
872
877
 
package/modules/README.md CHANGED
@@ -38,7 +38,7 @@ modules/
38
38
  ├── cli_start_onboarding.ts first-run setup routing for `dexbot start`
39
39
  ├── cli_start_output.ts launcher notice formatting
40
40
  ├── cli_colors.ts shared CLI color helpers
41
- ├── credential_runtime.ts credential daemon lifecycle
41
+ ├── credential_runtime.ts daemon socket/path helpers + private-path security
42
42
  ├── credential_policy.ts signing policy validation
43
43
  ├── credential_session_cache.ts encrypted session cache
44
44
  ├── constants.ts central config and tuning params
@@ -46,6 +46,7 @@ modules/
46
46
  ├── config.ts load-time process.env snapshot
47
47
  ├── env.ts isBrowser/hasProcess detection
48
48
  ├── runtime.ts process abstraction singleton
49
+ ├── lazy_shim.ts lazy named-export passthrough (require-on-call)
49
50
  ├── runtime_settings.ts per-bot runtime settings resolver
50
51
  ├── paths.ts guarded path resolution
51
52
  ├── path_api.ts portable path abstraction for ESM/browser
@@ -62,11 +63,11 @@ modules/
62
63
  ├── bots_file_lock.ts profile write serialization
63
64
  ├── account_bots.ts bots.json read/write
64
65
  ├── broadcast_failure.ts broadcast failure classification
65
- ├── chain_keys.ts blockchain key helpers
66
- ├── daemon_node_health.ts daemon-side node health checks
67
- ├── node_failure_ledger.ts node failure tracking
68
- ├── node_health_cache.ts node health tracking
69
- ├── socket_json_client.ts JSON-RPC socket client
66
+ ├── chain_keys.ts master-password vault + signing-key retrieval
67
+ ├── daemon_node_health.ts daemon-side node failure ledger (shared rules)
68
+ ├── node_failure_ledger.ts node failure counting shared by bot + daemon
69
+ ├── node_health_cache.ts shared node-health cache file I/O + ordering
70
+ ├── socket_json_client.ts newline-delimited JSON Unix-socket client
70
71
  ├── market_adapter_whitelist.ts adapter whitelist I/O
71
72
  ├── types.ts shared type definitions
72
73
  │
@@ -83,7 +84,7 @@ modules/
83
84
  ├── storage/ portable storage abstraction
84
85
  │ ├── index.ts barrel export
85
86
  │ ├── types.ts storage adapter interface
86
- │ ├── browser_adapter.ts in-memory Map-based adapter
87
+ │ ├── browser_adapter.ts in-memory Map backed by IndexedDB
87
88
  │ └── node_adapter.ts fs.*Sync based adapter
88
89
  │
89
90
  ├── order/ order lifecycle and grid management
@@ -93,9 +94,9 @@ modules/
93
94
  │ ├── strategy.ts grid rebalancing, consolidation, rotation
94
95
  │ ├── accounting.ts fund tracking, fee accounting
95
96
  │ ├── sync_engine.ts blockchain sync, fill detection, reconciliation
96
- │ ├── genesis_policy.ts missing-ladder refusal + rebuild/halt policy ([doc](../docs/GRID_PRICE_INVARIANT.md))
97
- │ ├── grid_reconcile.ts startup grid reconciliation ([doc](../docs/GRID_RECONCILE.md))
98
- │ ├── grid_reconcile_internal.ts internal grid reconciliation helpers
97
+ │ ├── genesis_policy.ts missing-ladder refusal + rebuild policy (docs/GRID_PRICE_INVARIANT.md)
98
+ │ ├── grid_reconcile.ts startup grid reconciliation (docs/GRID_RECONCILE.md)
99
+ │ ├── grid_reconcile_internal.ts internal grid reconciliation helpers
99
100
  │ ├── index.ts barrel export
100
101
  │ ├── logger.ts order-scoped logging
101
102
  │ ├── logger_state.ts logger state management
@@ -126,6 +127,7 @@ modules/
126
127
  │ ├── market_adapter_watchdog.ts adapter process watchdog
127
128
  │ ├── monolithic_runtime.ts monolithic bot runtime
128
129
  │ ├── runtime_entry.ts bot process entry
130
+ │ ├── runtime_mode.ts runtime mode detection and status routing
129
131
  │ ├── status_reporting.ts process status reporter
130
132
  │ └── supervisor_control.ts supervisor orchestration
131
133
  │
@@ -142,14 +144,14 @@ modules/
142
144
  │ └── crypto/ cryptographic primitives
143
145
  │
144
146
  └── utils/
145
- ├── asset_symbols.ts asset symbol/object-id canonicalization helpers
147
+ ├── asset_symbols.ts asset symbol/object-id canonicalization helpers
146
148
  ├── base58check.ts Base58Check encoding
147
149
  ├── build_dir.ts BUILD_DIR constant helper
148
150
  ├── chain_logs.ts shared chain log helpers
149
151
  ├── errors.ts getErrorMessage helper
150
152
  ├── sanitize_key.ts shared sanitizeKey helper
151
153
  ├── text_width.ts display-width-aware text measurement (CJK/emoji tables)
152
- └── time_range.ts month→hour lookback conversion (analysis range flags)
154
+ └── time_range.ts month→hour lookback conversion (analysis range flags)
153
155
  ```
154
156
 
155
157
  ## Key Relationships
@@ -178,10 +180,10 @@ External consumers — other parts of DEXBot2 interact with modules through thes
178
180
 
179
181
  ## Design Principles
180
182
 
181
- - **Zero runtime dependencies** — no npm trading/blockchain libraries; the native client, crypto, and serialization are all in `bitshares-native/`. This eliminates supply-chain risk and keeps the bot fully self-contained.
183
+ - **Zero runtime dependencies** — no npm trading/blockchain libraries; the native client and serialization live in `bitshares-native/`, and the cross-environment crypto providers (Web Crypto / Node crypto plus pure-JS fallbacks) in `crypto/`. `package.json` declares no `dependencies`, which eliminates supply-chain risk and keeps the bot fully self-contained.
182
184
  - **Copy-on-write** — `order/working_grid.ts` provides isolated COW mutations; master grid is immutable during rebalance. The grid is never modified in-place; a working copy is built, mutated, and committed atomically only after blockchain operations succeed.
183
185
  - **Fund-driven sizing, fill-driven boundary** — available funds set order sizing and budget allocation, not the boundary position; no forced allocations. The boundary moves only through boundary crawl on fills or spread promotion onto orders placed in the same atomic batch.
184
- - **Replay-safe accounting** — fill processing in `dexbot_fill_runtime.ts` uses `processed_fill_store.ts` to prevent double-counting. If the bot restarts mid-fill, it can safely replay without creating duplicate orders.
186
+ - **Replay-safe accounting** — `dexbot_class.ts` constructs `order/processed_fill_store.ts`, `dexbot_fill_runtime.ts` configures it and hands it to the `OrderManager`, and `order/accounting.ts` consults it before counting a fill. If the bot restarts mid-fill, it can safely replay without creating duplicate orders.
185
187
  - **Daemon-backed signing** — the credential daemon holds decrypted keys; modules never handle raw private keys. If the main bot crashes, keys stay encrypted on disk — only the small daemon process sees them.
186
188
  - **Gap-slot batch processing** — each fill batch and broadcast is capped at the current grid's gap-slot count + 1. A queue at or below that depth is processed as one unified batch; deeper queues are chunked at the same deterministic cap.
187
189
 
@@ -194,5 +196,7 @@ External consumers — other parts of DEXBot2 interact with modules through thes
194
196
  - [Fund movement & accounting](../docs/FUND_MOVEMENT_AND_ACCOUNTING.md) — fund tracking algorithms and formulas
195
197
  - [Credential security](../docs/CREDENTIAL_SECURITY.md) — key handling and daemon-backed signing details
196
198
  - [Grid recalculation](../docs/GRID_RECALCULATION.md) — when and how the grid resets or regenerates
199
+ - [Grid price invariant](../docs/GRID_PRICE_INVARIANT.md) — genesis ladder as the only authoritative slot price
200
+ - [Grid reconcile](../docs/GRID_RECONCILE.md) — startup reconciliation of the persisted grid
197
201
  - [Market adapter](../market_adapter/README.md) — AMA pricing, dynamic weights, and signal pipeline
198
202
  - [Claw bridge](../claw/README.md) — AI layer integration and command dispatch
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dexbot",
3
- "version": "1.6.16",
3
+ "version": "1.6.18",
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",
@@ -107,14 +109,15 @@
107
109
  "version:sync": "npm run build && node dist/scripts/sync-version.js",
108
110
  "version:check": "npm run build && node dist/scripts/sync-version.js --check",
109
111
  "verify:browser-bundle": "npm run build && node dist/scripts/verify-browser-bundle.js",
110
- "test": "npm run build && npm run build:tests && npm run build --prefix claw && node dist/scripts/run-tests.js",
111
- "test:live": "RUN_LIVE_BITSHARES_TESTS=1 npm run build && npm run build:tests && npm run build --prefix claw && node dist/scripts/run-tests.js",
112
+ "test": "npm run build && npm run build:tests && npm run build --prefix claw && npm run typecheck:analysis && node dist/scripts/run-tests.js",
113
+ "test:live": "RUN_LIVE_BITSHARES_TESTS=1 npm run build && npm run build:tests && npm run build --prefix claw && npm run typecheck:analysis && node dist/scripts/run-tests.js",
112
114
  "test:playwright": "npm run build && NODE_PATH=\"$(npm root -g)\" playwright test --config tests/playwright/playwright.config.mjs",
113
115
  "clean": "node scripts/clean-dist.js",
114
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",
115
117
  "build:clean": "npm run clean && npm run build",
116
118
  "build:tests": "tsc -p tsconfig.tests.json && cp tests/package.json dist/tests/package.json && cp tests/helpers/esm_mock_hooks.mjs tests/helpers/esm_mock_loader.mjs dist/tests/helpers/",
117
119
  "typecheck": "tsc --noEmit",
120
+ "typecheck:analysis": "tsc -p analysis/tsconfig.json",
118
121
  "check:any": "npm run build && node dist/scripts/check_any.js",
119
122
  "check:any:update": "npm run build && node dist/scripts/check_any.js --update",
120
123
  "check:any:list": "npm run build && node dist/scripts/check_any.js --list",