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.
- package/CHANGELOG.md +58 -0
- package/analysis/README.md +10 -9
- package/analysis/ama_fitting/README.md +2 -2
- package/analysis/bot_fitting/README.md +3 -3
- package/analysis/tradingview/README.md +2 -2
- package/analysis/trend_detection/DYNAMIC_WEIGHT_RESEARCH.md +1 -1
- package/claw/package.json +1 -1
- package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
- package/claw/runtimes/openclaw-plugin/package.json +1 -1
- package/dist/analysis/ama_fitting/analyze_lambda_vs_slow.js +5 -3
- package/dist/analysis/analyze_args.d.ts +2 -1
- package/dist/analysis/fills_source.d.ts +1 -8
- package/dist/analysis/fills_source.js +1 -1
- package/dist/analysis/grid_correction_check.d.ts +9 -6
- package/dist/analysis/grid_correction_check.js +56 -64
- package/dist/analysis/math_utils.d.ts +1 -1
- package/dist/analysis/trade_profitability.d.ts +1 -1
- package/dist/analysis/tradingview/grid_reset_sim.js +1 -1
- package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +7 -7
- package/dist/analysis/trend_detection/backtest_ama_slope_huber.js +1 -1
- package/dist/analysis/trend_detection/huber_scale_variants.d.ts +4 -3
- package/dist/market_adapter/cli_args.d.ts +6 -1
- package/dist/market_adapter/cli_args.js +16 -2
- package/dist/market_adapter/core/kibana_candles.d.ts +5 -1
- package/dist/market_adapter/core/kibana_candles.js +3 -1
- package/dist/market_adapter/core/strategies/regime_gate.d.ts +7 -1
- package/dist/market_adapter/core/strategies/regime_gate.js +3 -1
- package/dist/market_adapter/inputs/cex_candle_parsing.d.ts +7 -2
- package/dist/market_adapter/inputs/cex_candle_parsing.js +3 -1
- package/dist/market_adapter/inputs/fetch_book_data.d.ts +7 -1
- package/dist/market_adapter/inputs/fetch_book_data.js +3 -1
- package/dist/market_adapter/inputs/fetch_cex_synthetic_data.js +2 -11
- package/dist/market_adapter/inputs/fetch_lp_data.d.ts +26 -1
- package/dist/market_adapter/inputs/fetch_lp_data.js +62 -52
- package/dist/market_adapter/inputs/kibana_feed_source.d.ts +14 -2
- package/dist/market_adapter/inputs/kibana_feed_source.js +14 -1
- package/dist/market_adapter/inputs/window_cache.d.ts +14 -3
- package/dist/market_adapter/inputs/window_cache.js +14 -1
- package/dist/market_adapter/lp_chart_runner.d.ts +12 -9
- package/dist/market_adapter/lp_chart_runner.js +3 -1
- package/dist/market_adapter/lp_chart_strategy_loader.d.ts +5 -1
- package/dist/market_adapter/lp_chart_strategy_loader.js +3 -1
- package/dist/market_adapter/market_adapter.d.ts +10 -2
- package/dist/market_adapter/market_adapter.js +10 -11
- package/dist/market_adapter/utils/chain.d.ts +2 -3
- package/dist/market_adapter/utils/file_json_cache.d.ts +5 -1
- package/dist/market_adapter/utils/file_json_cache.js +3 -1
- package/dist/market_adapter/utils/file_lock.js +1 -1
- package/dist/market_adapter/utils/native_history.d.ts +7 -3
- package/dist/market_adapter/utils/native_history.js +3 -1
- package/dist/market_adapter/utils/pair_orientation.d.ts +2 -2
- package/dist/modules/account_bots.d.ts +3 -0
- package/dist/modules/bots_file_lock.d.ts +2 -2
- package/dist/modules/bots_file_lock.js +2 -2
- package/dist/modules/chain_keys.d.ts +1 -1
- package/dist/modules/constants.d.ts +6 -0
- package/dist/modules/constants.js +37 -6
- package/dist/modules/credit_pricing.d.ts +20 -1
- package/dist/modules/credit_pricing.js +23 -1
- package/dist/modules/credit_runtime.js +33 -16
- package/dist/modules/dexbot_class.d.ts +11 -1
- package/dist/modules/dexbot_class.js +15 -2
- package/dist/modules/dexbot_cow_runtime.d.ts +90 -38
- package/dist/modules/dexbot_cow_runtime.js +507 -108
- package/dist/modules/dexbot_credential_client.d.ts +5 -0
- package/dist/modules/dexbot_maintenance_runtime.js +117 -12
- package/dist/modules/dexbot_startup_runtime.js +7 -1
- package/dist/modules/graceful_shutdown.d.ts +2 -2
- package/dist/modules/graceful_shutdown.js +2 -2
- package/dist/modules/launcher/credential_daemon.d.ts +14 -2
- package/dist/modules/launcher/credential_daemon.js +60 -26
- package/dist/modules/launcher/runtime_mode.d.ts +4 -3
- package/dist/modules/node_manager.d.ts +1 -1
- package/dist/modules/node_manager.js +1 -1
- package/dist/modules/order/accounting.js +2 -1
- package/dist/modules/order/export.d.ts +2 -2
- package/dist/modules/order/export.js +2 -2
- package/dist/modules/order/grid.d.ts +26 -14
- package/dist/modules/order/grid.js +416 -73
- package/dist/modules/order/grid_reconcile.js +5 -1
- package/dist/modules/order/grid_reconcile_internal.js +2 -1
- package/dist/modules/order/index.d.ts +22 -1
- package/dist/modules/order/manager.d.ts +40 -7
- package/dist/modules/order/manager.js +149 -23
- package/dist/modules/order/strategy.d.ts +5 -0
- package/dist/modules/order/strategy.js +44 -3
- package/dist/modules/order/sync_engine.d.ts +12 -1
- package/dist/modules/order/sync_engine.js +135 -20
- package/dist/modules/order/utils/math.d.ts +49 -10
- package/dist/modules/order/utils/math.js +71 -14
- package/dist/modules/order/utils/order.d.ts +65 -11
- package/dist/modules/order/utils/order.js +198 -28
- package/dist/modules/order/utils/system.d.ts +112 -2
- package/dist/modules/order/utils/system.js +338 -12
- package/dist/modules/order/utils/validate.d.ts +4 -1
- package/dist/modules/order/utils/validate.js +9 -2
- package/dist/modules/storage/index.d.ts +3 -2
- package/dist/modules/storage/index.js +3 -2
- package/dist/modules/types.d.ts +44 -2
- package/dist/scripts/analyze-credit.js +64 -23
- package/dist/scripts/bts_distribution.d.ts +66 -0
- package/dist/scripts/bts_distribution.js +2102 -0
- package/dist/scripts/token_distribution.d.ts +45 -0
- package/dist/scripts/token_distribution.js +1870 -0
- package/dist/unlock.js +42 -24
- package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -1
- package/docs/COW_INVARIANTS.md +24 -8
- package/docs/DEXBOT_COMPARISON.md +5 -5
- package/docs/EVOLUTION.md +10 -8
- package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +13 -11
- package/docs/GRID_PRICE_INVARIANT.md +29 -3
- package/docs/GRID_RECALCULATION.md +3 -3
- package/docs/GRID_RECONCILE.md +5 -5
- package/docs/LIFECYCLE.md +11 -11
- package/docs/LOGGING.md +22 -0
- package/docs/MPA_CREDIT_USAGE.md +3 -2
- package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +236 -32
- package/docs/README.md +1 -1
- package/docs/architecture.md +205 -6
- package/docs/developer_guide.md +12 -0
- package/market_adapter/README.md +11 -6
- package/modules/README.md +18 -14
- package/package.json +6 -3
- package/scripts/README.md +85 -148
package/docs/architecture.md
CHANGED
|
@@ -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,
|
|
488
|
-
|
|
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` / `
|
|
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
|
|
520
|
-
//
|
|
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 `
|
|
907
|
+
- Recovery called from `executeMaintenanceLogic()` during periodic maintenance checks
|
|
709
908
|
|
|
710
909
|
**Location**: `modules/order/manager.ts` (`isPipelineEmpty()` and `clearStalePipelineOperations()`)
|
|
711
910
|
|
package/docs/developer_guide.md
CHANGED
|
@@ -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`)
|
package/market_adapter/README.md
CHANGED
|
@@ -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":
|
|
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
|
|
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
|
|
449
|
-
updates wait for the next completed
|
|
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
|
|
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
|
|
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
|
|
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
|
|
66
|
-
├── daemon_node_health.ts daemon-side node
|
|
67
|
-
├── node_failure_ledger.ts node failure
|
|
68
|
-
├── node_health_cache.ts node
|
|
69
|
-
├── socket_json_client.ts JSON-
|
|
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
|
|
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
|
|
97
|
-
│ ├── grid_reconcile.ts startup grid reconciliation (
|
|
98
|
-
│ ├── grid_reconcile_internal.ts
|
|
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
|
|
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
|
|
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
|
|
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** —
|
|
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.
|
|
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",
|