dexbot 1.7.1 → 1.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/CHANGELOG.md +28 -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/modules/account_bots.d.ts +1 -0
  6. package/dist/modules/account_bots.js +7 -5
  7. package/dist/modules/constants.d.ts +2 -0
  8. package/dist/modules/constants.js +16 -2
  9. package/dist/modules/dexbot_class.d.ts +22 -0
  10. package/dist/modules/dexbot_class.js +30 -0
  11. package/dist/modules/dexbot_cow_runtime.d.ts +31 -1
  12. package/dist/modules/dexbot_cow_runtime.js +68 -56
  13. package/dist/modules/dexbot_maintenance_runtime.d.ts +1 -1
  14. package/dist/modules/dexbot_maintenance_runtime.js +33 -6
  15. package/dist/modules/node_flap_score.d.ts +6 -6
  16. package/dist/modules/node_flap_score.js +6 -6
  17. package/dist/modules/order/accounting.d.ts +9 -4
  18. package/dist/modules/order/accounting.js +89 -26
  19. package/dist/modules/order/async_lock.d.ts +7 -1
  20. package/dist/modules/order/async_lock.js +7 -1
  21. package/dist/modules/order/export.js +25 -18
  22. package/dist/modules/order/fill_ledger.d.ts +99 -0
  23. package/dist/modules/order/fill_ledger.js +103 -0
  24. package/dist/modules/order/grid.d.ts +75 -18
  25. package/dist/modules/order/grid.js +207 -61
  26. package/dist/modules/order/grid_reconcile_internal.js +16 -4
  27. package/dist/modules/order/index.d.ts +14 -5
  28. package/dist/modules/order/index.js +5 -5
  29. package/dist/modules/order/lifecycle.js +3 -3
  30. package/dist/modules/order/manager.d.ts +15 -24
  31. package/dist/modules/order/manager.js +40 -27
  32. package/dist/modules/order/sync_engine.d.ts +66 -118
  33. package/dist/modules/order/sync_engine.js +118 -162
  34. package/dist/modules/order/utils/math.d.ts +7 -3
  35. package/dist/modules/order/utils/math.js +7 -3
  36. package/dist/modules/order/utils/order.d.ts +40 -41
  37. package/dist/modules/order/utils/order.js +110 -84
  38. package/dist/modules/order/utils/system.d.ts +81 -6
  39. package/dist/modules/order/utils/system.js +167 -29
  40. package/dist/modules/timing_policy.js +2 -2
  41. package/dist/modules/types.d.ts +22 -27
  42. package/docs/COW_INVARIANTS.md +5 -1
  43. package/docs/DEXBOT_COMPARISON.md +4 -4
  44. package/docs/EVOLUTION.md +6 -5
  45. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  46. package/docs/GRID_RECONCILE.md +3 -3
  47. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +38 -30
  48. package/docs/README.md +1 -1
  49. package/docs/architecture.md +26 -8
  50. package/modules/README.md +3 -0
  51. package/package.json +3 -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,7 +650,7 @@ 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;
@@ -613,8 +670,8 @@ export declare function calculateCurrentSpread(manager: OrderManagerLike): numbe
613
670
  * - RACE CONDITION WINDOW: Between lock release and blockchain submission
614
671
  * - MITIGATION: Pre-flight fund verification before submission; comprehensive error handling
615
672
  *
616
- * @param {import('./types').OrderManager} manager - Manager instance
617
- * @param {Object} BitShares - BitShares API client
673
+ * @param {import('../types.js').OrderManagerLike} manager - Manager instance
674
+ * @param {unknown} _BitShares - BitShares client, forwarded to the live-market-price refresh.
618
675
  * @param {Function|null} [updateOrdersOnChainBatch=null] - Optional batch update function
619
676
  * @returns {Promise<any>}
620
677
  */
@@ -639,7 +696,7 @@ export declare function checkSpreadCondition(manager: OrderManagerLike, _BitShar
639
696
  * flagged as violations. The "Edge-First" placement strategy intentionally
640
697
  * creates these gaps to maximize grid coverage during fund expansion.
641
698
  *
642
- * @param {import('./types').OrderManager} manager - The manager instance.
699
+ * @param {import('../types.js').OrderManagerLike} manager - The manager instance.
643
700
  * @param {Function|null} [updateOrdersOnChainBatch=null] - Optional batch update function.
644
701
  * @returns {Promise<any>}
645
702
  */
@@ -669,7 +726,7 @@ export declare function checkGridHealth(manager: OrderManagerLike, _updateOrders
669
726
  * Returns boolean flags plus the actual dust order objects so callers can act
670
727
  * on individual orders (dust is cancelled immediately on detection).
671
728
  *
672
- * @param {import('./types').OrderManager} manager
729
+ * @param {import('../types.js').OrderManagerLike} manager
673
730
  * @returns {Promise<any>}
674
731
  */
675
732
  export declare function checkWindowDust(manager: OrderManagerLike): Promise<{
@@ -680,7 +737,7 @@ export declare function checkWindowDust(manager: OrderManagerLike): Promise<{
680
737
  }>;
681
738
  /**
682
739
  * Public dust helper shared by StrategyEngine and Grid health checks.
683
- * @param {import('./types').OrderManager} manager
740
+ * @param {import('../types.js').OrderManagerLike} manager
684
741
  * @param {Array<any>} partials
685
742
  * @param {'buy'|'sell'} side
686
743
  * @returns {Promise<boolean>}
@@ -689,7 +746,7 @@ export declare function hasAnyDust(manager: OrderManagerLike, partials: ManagedO
689
746
  /**
690
747
  * Public dust helper that returns the subset of candidate partials currently below
691
748
  * the configured dust threshold for the requested side.
692
- * @param {import('./types').OrderManager} manager
749
+ * @param {import('../types.js').OrderManagerLike} manager
693
750
  * @param {Array<any>} partials
694
751
  * @param {'buy'|'sell'} side
695
752
  * @returns {Promise<Array<any>>}
@@ -697,10 +754,10 @@ export declare function hasAnyDust(manager: OrderManagerLike, partials: ManagedO
697
754
  export declare function getDustOrders(manager: OrderManagerLike, partials: ManagedOrder[], side: string): Promise<ManagedOrder[]>;
698
755
  /**
699
756
  * Determine which side has more available funds for spread correction.
700
- * @param {import('./types').OrderManager} manager - The manager instance.
757
+ * @param {import('../types.js').OrderManagerLike} manager - The manager instance.
701
758
  * @param {number} currentMarketPrice - Last traded price in B/A format (e.g. BTS/XRP), used to
702
759
  * 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.
760
+ * @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
761
  */
705
762
  export declare function determineOrderSideByFunds(manager: OrderManagerLike, currentMarketPrice: number): {
706
763
  side: OrderType | null;
@@ -709,7 +766,7 @@ export declare function determineOrderSideByFunds(manager: OrderManagerLike, cur
709
766
  };
710
767
  /**
711
768
  * Prepares one or more orders to correct a wide spread.
712
- * @param {import('./types').OrderManager} manager - The OrderManager instance.
769
+ * @param {import('../types.js').OrderManagerLike} manager - The OrderManager instance.
713
770
  * @param {string} preferredSide - The side to place the correction on (ORDER_TYPES.BUY/SELL).
714
771
  * @returns {Promise<any>}
715
772
  * @throws {Error} If preferredSide is invalid.