dexbot 1.7.1 → 1.7.3

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 (66) hide show
  1. package/CHANGELOG.md +52 -0
  2. package/claw/package.json +1 -1
  3. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  4. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  5. package/dist/analysis/grid_correction_check.d.ts +60 -1
  6. package/dist/analysis/grid_correction_check.js +268 -18
  7. package/dist/analysis/pivot_timeline.d.ts +78 -0
  8. package/dist/analysis/pivot_timeline.js +360 -0
  9. package/dist/market_adapter/utils/file_lock.js +16 -4
  10. package/dist/modules/account_bots.d.ts +7 -0
  11. package/dist/modules/account_bots.js +7 -5
  12. package/dist/modules/bot_defaults.js +6 -1
  13. package/dist/modules/constants.d.ts +14 -0
  14. package/dist/modules/constants.js +82 -2
  15. package/dist/modules/dexbot_class.d.ts +39 -0
  16. package/dist/modules/dexbot_class.js +86 -1
  17. package/dist/modules/dexbot_cow_runtime.d.ts +31 -1
  18. package/dist/modules/dexbot_cow_runtime.js +299 -75
  19. package/dist/modules/dexbot_maintenance_runtime.d.ts +32 -2
  20. package/dist/modules/dexbot_maintenance_runtime.js +196 -16
  21. package/dist/modules/dexbot_state_recovery.js +15 -1
  22. package/dist/modules/launcher/instance_lock.d.ts +27 -0
  23. package/dist/modules/launcher/instance_lock.js +131 -0
  24. package/dist/modules/node_flap_score.d.ts +6 -6
  25. package/dist/modules/node_flap_score.js +6 -6
  26. package/dist/modules/order/accounting.d.ts +9 -4
  27. package/dist/modules/order/accounting.js +89 -26
  28. package/dist/modules/order/async_lock.d.ts +7 -1
  29. package/dist/modules/order/async_lock.js +7 -1
  30. package/dist/modules/order/export.js +25 -18
  31. package/dist/modules/order/fill_ledger.d.ts +99 -0
  32. package/dist/modules/order/fill_ledger.js +103 -0
  33. package/dist/modules/order/grid.d.ts +94 -18
  34. package/dist/modules/order/grid.js +247 -75
  35. package/dist/modules/order/grid_reconcile_internal.js +16 -4
  36. package/dist/modules/order/index.d.ts +29 -6
  37. package/dist/modules/order/index.js +5 -5
  38. package/dist/modules/order/lifecycle.js +3 -3
  39. package/dist/modules/order/manager.d.ts +36 -24
  40. package/dist/modules/order/manager.js +159 -39
  41. package/dist/modules/order/placement_lock.d.ts +30 -0
  42. package/dist/modules/order/placement_lock.js +48 -0
  43. package/dist/modules/order/sync_engine.d.ts +66 -118
  44. package/dist/modules/order/sync_engine.js +118 -162
  45. package/dist/modules/order/utils/math.d.ts +7 -3
  46. package/dist/modules/order/utils/math.js +7 -3
  47. package/dist/modules/order/utils/order.d.ts +79 -42
  48. package/dist/modules/order/utils/order.js +183 -86
  49. package/dist/modules/order/utils/system.d.ts +192 -8
  50. package/dist/modules/order/utils/system.js +534 -34
  51. package/dist/modules/paths.d.ts +1 -0
  52. package/dist/modules/paths.js +1 -0
  53. package/dist/modules/timing_policy.js +4 -2
  54. package/dist/modules/types.d.ts +49 -27
  55. package/dist/pm2.js +126 -0
  56. package/dist/unlock.js +26 -1
  57. package/docs/COW_INVARIANTS.md +5 -1
  58. package/docs/DEXBOT_COMPARISON.md +5 -5
  59. package/docs/EVOLUTION.md +10 -8
  60. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  61. package/docs/GRID_RECONCILE.md +3 -3
  62. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +192 -31
  63. package/docs/README.md +1 -1
  64. package/docs/architecture.md +26 -8
  65. package/modules/README.md +4 -0
  66. package/package.json +4 -3
@@ -12,7 +12,7 @@
12
12
  * - Detects and flags out-of-spread conditions
13
13
  *
14
14
  * ===============================================================================
15
- * TABLE OF CONTENTS - Grid Functions (34 exports)
15
+ * TABLE OF CONTENTS - Grid Functions (34 exports + internal helpers)
16
16
  * ===============================================================================
17
17
  *
18
18
  * CONFIGURATION & CALCULATION (2 functions)
@@ -81,6 +81,13 @@
81
81
  * 33. isGridBloatGraceActive(manager) - Check the bloat grace state
82
82
  * 34. clearGridBloatFlag(manager) - Clear the bloat state
83
83
  *
84
+ * SPREAD STALL MERGING (1 function)
85
+ * 35. mergeSpreadStalls(...) - Merge two side stalls so starvation cannot mask a cause
86
+ *
87
+ * REBUILD FILL ANCHOR (2 functions)
88
+ * 36. anchorRebuildBoundaryToLastFill(...) - Anchor a rebuilt boundary to the last fill
89
+ * 37. applyRebuildFillAnchor(...) - Apply the anchor and re-type the rails for it
90
+ *
84
91
  * ===============================================================================
85
92
  *
86
93
  * GRID STRUCTURE:
@@ -378,7 +385,7 @@ export declare function createOrderGrid(config: GridConfig): {
378
385
  * the creation-time value instead of recomputing from live config
379
386
  * - Sanitizes phantom orders (ACTIVE/PARTIAL without orderId → VIRTUAL)
380
387
  *
381
- * @param {import('./types').OrderManager} manager - The manager instance.
388
+ * @param {import('../types.js').OrderManagerLike} manager - The manager instance.
382
389
  * @param {Array<any>} grid - The persisted grid array.
383
390
  * @param {number|null} [boundaryIdx=null] - The master boundary index.
384
391
  * @returns {Promise<void>}
@@ -386,6 +393,56 @@ export declare function createOrderGrid(config: GridConfig): {
386
393
  export declare function loadGrid(manager: OrderManagerLike, grid: ManagedOrder[], boundaryIdx?: number | null, genesisInput?: GridGenesis | null, options?: {
387
394
  tolerateTransientStranding?: boolean;
388
395
  }): Promise<void>;
396
+ /**
397
+ * Anchor a rebuilt or reloaded boundary to the last real fill.
398
+ *
399
+ * A fresh grid generation derives its band from the current market center, but
400
+ * the last execution is the geometry fact the fill cycle already honors:
401
+ *
402
+ * BUY fill at slot f -> boundary <= f - 1 (buy window ends below the fill)
403
+ * SELL fill at slot f -> boundary >= f - gapSlots (sell window starts above it)
404
+ *
405
+ * Without this clamp, a generation centered ABOVE the pivot leaves the top
406
+ * buy levels at/through the fill. The startup picker then correctly skips them
407
+ * (the LAST-FILL-GUARD refuses the re-placement), fills the buy window lower,
408
+ * and the first ask stays at the old sellStart — a realized spread two grid
409
+ * steps wider than target with no order-fill reason for the extra width.
410
+ *
411
+ * The decision is delegated to `reanchorBoundaryFromLastFill` (single source:
412
+ * fill-provenanced pivot, on-ladder price, TTL, shared boundary validator), so
413
+ * this helper only fixes the array indexing (price-sorted ladder) and keeps a
414
+ * refusal fail-closed. Returns the original boundary when no safe anchor
415
+ * applies (cold pivot, already outside, off-ladder, unsafe geometry).
416
+ *
417
+ * @param manager - OrderManager holding the new generation + re-armed pivot
418
+ * @param boundaryIdx - Derived/restored boundary for that generation
419
+ * @param slots - Generation slots (any order; sorted by price here)
420
+ * @param gapSlots - Generation gap width
421
+ * @returns The fill-anchored boundary, or the original when no safe move exists
422
+ */
423
+ export declare function anchorRebuildBoundaryToLastFill(manager: OrderManagerLike, boundaryIdx: number | null, slots: Iterable<ManagedOrder> | null | undefined, gapSlots: number | null | undefined): number | null;
424
+ /**
425
+ * Apply the rebuild fill anchor AND re-type the rails for the anchored
426
+ * boundary.
427
+ *
428
+ * The split matters: `anchorRebuildBoundaryToLastFill` moves the band, but the
429
+ * slot roles still belong to createOrderGrid's structural boundary. Persisting
430
+ * those roles with the anchored boundary would leave the two counter levels
431
+ * typed as the old side (slot-158/159 BUY and 162/163 SPREAD for the incident)
432
+ * while every geometry consumer reads boundary 157. This helper keeps the
433
+ * boundary and the role assignment atomic, using the same `assignGridRoles`
434
+ * pass as a fresh build.
435
+ *
436
+ * @param manager - OrderManager holding the new generation + re-armed pivot
437
+ * @param boundaryIdx - Structural boundary from createOrderGrid
438
+ * @param slots - Slots from createOrderGrid
439
+ * @param gapSlots - Generation gap width
440
+ * @returns Anchored boundary and slots re-typed for it
441
+ */
442
+ export declare function applyRebuildFillAnchor(manager: OrderManagerLike, boundaryIdx: number | null, slots: Iterable<ManagedOrder> | null | undefined, gapSlots: number | null | undefined): {
443
+ boundaryIdx: number | null;
444
+ slots: ManagedOrder[];
445
+ };
389
446
  /**
390
447
  * Initialize and orchestrate the order grid.
391
448
  *
@@ -395,7 +452,7 @@ export declare function loadGrid(manager: OrderManagerLike, grid: ManagedOrder[]
395
452
  export declare function initializeGrid(manager: OrderManagerLike): Promise<void>;
396
453
  /**
397
454
  * Full grid resynchronization from blockchain state.
398
- * @param {import('./types').OrderManager} manager - The manager instance.
455
+ * @param {import('../types.js').OrderManagerLike} manager - The manager instance.
399
456
  * @param {Object} opts - Options for resynchronization.
400
457
  * @param {Function} opts.readOpenOrdersFn - Function to read open orders.
401
458
  * @param {Object} opts.chainOrders - Chain orders module.
@@ -413,7 +470,7 @@ export declare function recalculateGrid(manager: OrderManagerLike, opts: {
413
470
  /**
414
471
  * Check for grid divergence and trigger update if threshold is met.
415
472
  *
416
- * @param {import('./types').OrderManager} manager - Manager instance with order state
473
+ * @param {import('../types.js').OrderManagerLike} manager - Manager instance with order state
417
474
  * @returns {unknown}
418
475
  */
419
476
  export declare function checkAndUpdateGridIfNeeded(manager: OrderManagerLike): {
@@ -483,7 +540,7 @@ export declare function checkCommittedSizeDrift(manager: OrderManagerLike): Prom
483
540
  * - Apply: size=500 (no cap check)
484
541
  * - Result: slot[1] ready for placement, will consume from sideFree when placed
485
542
  *
486
- * @param {import('./types').OrderManager} manager - OrderManager instance
543
+ * @param {import('../types.js').OrderManagerLike} manager - OrderManager instance
487
544
  * @param {string} orderType - ORDER_TYPES.BUY or ORDER_TYPES.SELL
488
545
  * @param {Object} [options] - Options object
489
546
  * @param {import('./working_grid.js')} [options.workingGrid] - Working grid for COW pattern
@@ -501,7 +558,7 @@ export declare function _recalculateGridOrderSizesFromBlockchain(manager: OrderM
501
558
  * Creates working grid, calculates new sizes, generates UPDATE actions.
502
559
  * Master grid is only updated after successful blockchain confirmation.
503
560
  *
504
- * @param {import('./types').OrderManager} manager - Manager instance
561
+ * @param {import('../types.js').OrderManagerLike} manager - Manager instance
505
562
  * @param {string} orderType - 'buy', 'sell', or 'both' - which sides to update
506
563
  * @param {boolean} [fromBlockchainTimer=false] - If true, skip refetch of account totals (already current)
507
564
  * @param {number|null} [overrideBoundaryIdx=null] - Optional override for boundary index
@@ -548,7 +605,7 @@ export declare function updateGridFromBlockchainSnapshot(manager: OrderManagerLi
548
605
  *
549
606
  * @param {Array<any>} calculatedGrid - Ideal calculated grid
550
607
  * @param {Array<any>} persistedGrid - Persisted grid state
551
- * @param {import('./types').OrderManager|null} [manager=null] - Manager instance (for grid lock access)
608
+ * @param {import('../types.js').OrderManagerLike|null} [manager=null] - Manager instance (for grid lock access)
552
609
  * @returns {Promise<any>}
553
610
  */
554
611
  export declare function compareGrids(calculatedGrid: unknown[], persistedGrid: unknown[], manager?: OrderManagerLike | null): Promise<{
@@ -567,7 +624,7 @@ export declare function compareGrids(calculatedGrid: unknown[], persistedGrid: u
567
624
  * Unified divergence monitoring.
568
625
  * Performs both Ratio-based and RMS-based divergence checks.
569
626
  *
570
- * @param {import('./types').OrderManager} manager - Manager instance
627
+ * @param {import('../types.js').OrderManagerLike} manager - Manager instance
571
628
  * @param {Array<any>} calculatedGrid - Ideal/calculated grid
572
629
  * @param {Array<any>} persistedGrid - Current/persisted grid
573
630
  * @returns {Promise<any>}
@@ -593,10 +650,28 @@ export declare function monitorDivergence(manager: OrderManagerLike, calculatedG
593
650
  }>;
594
651
  /**
595
652
  * Calculate current market spread using on-chain orders.
596
- * @param {import('./types').OrderManager} manager - The manager instance.
653
+ * @param {import('../types.js').OrderManagerLike} manager - The manager instance.
597
654
  * @returns {number} The calculated spread percentage.
598
655
  */
599
656
  export declare function calculateCurrentSpread(manager: OrderManagerLike): number;
657
+ /**
658
+ * Measure the current out-of-spread violation in grid steps, from the live
659
+ * on-chain window only. ONE implementation for the entry reading and the
660
+ * post-placement reading, so "did the repair reduce the violation?" is the
661
+ * same arithmetic as "is the spread wide?" (retrospective §9.11.3: a repair
662
+ * must reduce the violation; the watchdog otherwise counted any placement
663
+ * as progress).
664
+ *
665
+ * @param {import('../types.js').OrderManagerLike} manager - Manager instance
666
+ * @returns {{ currentSpread: number, nominalSpread: number, excess: number, buyCount: number, sellCount: number }}
667
+ */
668
+ export declare function measureSpreadExcess(manager: OrderManagerLike): {
669
+ currentSpread: number;
670
+ nominalSpread: number;
671
+ excess: number;
672
+ buyCount: number;
673
+ sellCount: number;
674
+ };
600
675
  /**
601
676
  * Proactive spread correction check.
602
677
  *
@@ -613,8 +688,8 @@ export declare function calculateCurrentSpread(manager: OrderManagerLike): numbe
613
688
  * - RACE CONDITION WINDOW: Between lock release and blockchain submission
614
689
  * - MITIGATION: Pre-flight fund verification before submission; comprehensive error handling
615
690
  *
616
- * @param {import('./types').OrderManager} manager - Manager instance
617
- * @param {Object} BitShares - BitShares API client
691
+ * @param {import('../types.js').OrderManagerLike} manager - Manager instance
692
+ * @param {unknown} _BitShares - BitShares client, forwarded to the live-market-price refresh.
618
693
  * @param {Function|null} [updateOrdersOnChainBatch=null] - Optional batch update function
619
694
  * @returns {Promise<any>}
620
695
  */
@@ -629,6 +704,7 @@ export declare function checkSpreadCondition(manager: OrderManagerLike, _BitShar
629
704
  partialsMoved: number;
630
705
  stall?: SpreadCorrectionStall;
631
706
  transient?: boolean;
707
+ excessAfter?: number;
632
708
  }>;
633
709
  /**
634
710
  * Grid health check for structural violations.
@@ -639,7 +715,7 @@ export declare function checkSpreadCondition(manager: OrderManagerLike, _BitShar
639
715
  * flagged as violations. The "Edge-First" placement strategy intentionally
640
716
  * creates these gaps to maximize grid coverage during fund expansion.
641
717
  *
642
- * @param {import('./types').OrderManager} manager - The manager instance.
718
+ * @param {import('../types.js').OrderManagerLike} manager - The manager instance.
643
719
  * @param {Function|null} [updateOrdersOnChainBatch=null] - Optional batch update function.
644
720
  * @returns {Promise<any>}
645
721
  */
@@ -669,7 +745,7 @@ export declare function checkGridHealth(manager: OrderManagerLike, _updateOrders
669
745
  * Returns boolean flags plus the actual dust order objects so callers can act
670
746
  * on individual orders (dust is cancelled immediately on detection).
671
747
  *
672
- * @param {import('./types').OrderManager} manager
748
+ * @param {import('../types.js').OrderManagerLike} manager
673
749
  * @returns {Promise<any>}
674
750
  */
675
751
  export declare function checkWindowDust(manager: OrderManagerLike): Promise<{
@@ -680,7 +756,7 @@ export declare function checkWindowDust(manager: OrderManagerLike): Promise<{
680
756
  }>;
681
757
  /**
682
758
  * Public dust helper shared by StrategyEngine and Grid health checks.
683
- * @param {import('./types').OrderManager} manager
759
+ * @param {import('../types.js').OrderManagerLike} manager
684
760
  * @param {Array<any>} partials
685
761
  * @param {'buy'|'sell'} side
686
762
  * @returns {Promise<boolean>}
@@ -689,7 +765,7 @@ export declare function hasAnyDust(manager: OrderManagerLike, partials: ManagedO
689
765
  /**
690
766
  * Public dust helper that returns the subset of candidate partials currently below
691
767
  * the configured dust threshold for the requested side.
692
- * @param {import('./types').OrderManager} manager
768
+ * @param {import('../types.js').OrderManagerLike} manager
693
769
  * @param {Array<any>} partials
694
770
  * @param {'buy'|'sell'} side
695
771
  * @returns {Promise<Array<any>>}
@@ -697,10 +773,10 @@ export declare function hasAnyDust(manager: OrderManagerLike, partials: ManagedO
697
773
  export declare function getDustOrders(manager: OrderManagerLike, partials: ManagedOrder[], side: string): Promise<ManagedOrder[]>;
698
774
  /**
699
775
  * Determine which side has more available funds for spread correction.
700
- * @param {import('./types').OrderManager} manager - The manager instance.
776
+ * @param {import('../types.js').OrderManagerLike} manager - The manager instance.
701
777
  * @param {number} currentMarketPrice - Last traded price in B/A format (e.g. BTS/XRP), used to
702
778
  * normalize sell-side funds into buy-side units for a fair cross-asset comparison.
703
- * @returns {{ side: import('./types').OrderType|null, reason: string, code?: 'market-price-unavailable'|'no-free-funds' }} The side to correct on, or null with a structured cause.
779
+ * @returns {{ side: import('../types.js').OrderType|null, reason: string, code?: 'market-price-unavailable'|'no-free-funds' }} The side to correct on, or null with a structured cause.
704
780
  */
705
781
  export declare function determineOrderSideByFunds(manager: OrderManagerLike, currentMarketPrice: number): {
706
782
  side: OrderType | null;
@@ -709,7 +785,7 @@ export declare function determineOrderSideByFunds(manager: OrderManagerLike, cur
709
785
  };
710
786
  /**
711
787
  * Prepares one or more orders to correct a wide spread.
712
- * @param {import('./types').OrderManager} manager - The OrderManager instance.
788
+ * @param {import('../types.js').OrderManagerLike} manager - The OrderManager instance.
713
789
  * @param {string} preferredSide - The side to place the correction on (ORDER_TYPES.BUY/SELL).
714
790
  * @returns {Promise<any>}
715
791
  * @throws {Error} If preferredSide is invalid.