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
@@ -4,7 +4,7 @@
4
4
  * Price derivation, persistence, grid correction, and UI/interactive utilities.
5
5
  *
6
6
  * ===============================================================================
7
- * TABLE OF CONTENTS (43 exported functions + 11 structural view types)
7
+ * TABLE OF CONTENTS (52 exported functions + 12 structural view types)
8
8
  * ===============================================================================
9
9
  *
10
10
  * SECTION 1: PRICE DERIVATION (9 functions + 1 internal)
@@ -50,7 +50,20 @@
50
50
  * - resetLastFillPivot(manager) - Clear the pivot to cold state
51
51
  * - restoreLastFillPivot(manager) - Restore the persisted pivot into the manager
52
52
  *
53
- * SECTION 7: UI & INTERACTIVE UTILITIES (6 functions)
53
+ * SECTION 7: FILL PIPELINE & LAST-FILL GUARD (9 functions)
54
+ * - reanchorBoundaryFromLastFill(manager, ...) - Re-anchor a rebuilt boundary to the last fill
55
+ * - rearmLastFillPivotFromMarketFill(manager) - Re-arm the pivot from the last market fill
56
+ * - isLastFillGuardBlocked(price, type, lastPrice, lastType) - LAST-FILL-GUARD direction predicate
57
+ * - isLastFillBandSellExempt(manager, price) - Geometry territory for a SELL counter-order
58
+ * - evaluateLastFillGuard(manager, price, type, pivot, pivotType) - Shared placement verdict
59
+ * - isLastFillPlacementBlocked(manager, price, type) - Placement-side LAST-FILL-GUARD wrapper
60
+ * - readFillPipelineState(source) - Projection of the fill-pipeline state
61
+ * - resolveGridUpdateBlockers(source, options) - Blockers that forbid a grid update right now
62
+ * - noteGridUpdateBlockers(...) - Log/record the blockers for one decision
63
+ * - hasUnsettledFills(source) - Whether any fill is still unsettled (with a reason)
64
+ * - getPipelineInFlightAgeMs(source, nowMs) - Age of the oldest in-flight pipeline work
65
+ *
66
+ * SECTION 8: UI & INTERACTIVE UTILITIES (6 functions)
54
67
  * - ensureProfilesDirectory(profilesDir) - Ensure profiles directory exists
55
68
  * - sleep(ms) - Pause execution for specified duration
56
69
  * - readInput(prompt, options) - Read user input from stdin
@@ -59,7 +72,7 @@
59
72
  * - withBlockchainRetry(fn, label, options) - Blockchain op with timeout + retry + node failover
60
73
  * (withTimeout lives in ./timeout)
61
74
  *
62
- * SECTION 8: GENERAL UTILITIES (7 functions)
75
+ * SECTION 9: GENERAL UTILITIES (7 functions)
63
76
  * - resolveAccountRef(manager, account) - Resolve best account reference
64
77
  * - deepFreeze(obj) - Recursively freeze object for immutability
65
78
  * - cloneMap(map) - Create shallow clone of Map
@@ -70,8 +83,8 @@
70
83
  *
71
84
  * STRUCTURAL VIEW TYPES:
72
85
  * AssetMeta, PoolReserve, PoolEntry, BitSharesClient, AmaCenterSnapshot,
73
- * FeeCacheEntryData, SpreadCorrectionRefusalReason, SpreadCorrectionReadiness,
74
- * UnmatchedChainOrderLike, GridResizeResult, CowResult
86
+ * FeeCacheEntryData, SpreadCorrectionReadiness, GridUpdateBlockerCode,
87
+ * GridUpdateBlocker, FillPipelineState, GridResizeResult, CowResult
75
88
  *
76
89
  * ===============================================================================
77
90
  */
@@ -597,6 +610,94 @@ export declare function isLastFillGuardBlocked(price: number, type: unknown, las
597
610
  pivot: number | null;
598
611
  threshold?: number | null;
599
612
  };
613
+ /**
614
+ * REFUSED-LEVEL SAME-LEVEL RE-FILL BLOCK (§9.12/P2 amended, 2026-11-16).
615
+ *
616
+ * A fill the pivot-arming policy refused (wrong-side / too-far premium sweep)
617
+ * does not arm the direction pivot — deliberately, so the guard keeps trading
618
+ * around the live market instead of deadlocking the side for the pivot TTL.
619
+ * But the same-level re-fill refusal (§9.12/P2: "the exact pivot level remains
620
+ * blocked as a same-level re-fill") keys off the ARMED pivot, so the P1
621
+ * refusal silently suspended it: a spread-correction slot could be re-armed at
622
+ * the identical level and refill immediately, in a loop, for as long as a
623
+ * taker kept lifting it.
624
+ *
625
+ * This predicate closes that gap with a SEPARATE, minimal role: the refused
626
+ * fill's own level, same side only, within half a grid step (the same
627
+ * pricesWithinHalfStep test isLastFillPlacementBlocked uses), for a short
628
+ * in-memory TTL (GRID_LIMITS.LAST_FILL_REFUSED_LEVEL_TTL_MS). It vetoes exactly
629
+ * one price level — the just-filled one — and nothing else: the counter-side
630
+ * stays governed by the (older) direction pivot and spread correction can
631
+ * still trade around the live market, so the unquoted-side deadlock P1 was
632
+ * written against cannot re-open through it. Fail-open on anything unreadable.
633
+ *
634
+ * @param {Object} manager - OrderManager instance
635
+ * @param {number} price - Candidate placement price
636
+ * @param {string} type - ORDER_TYPES.BUY / ORDER_TYPES.SELL
637
+ * @returns {{blocked: boolean, level: number|null}} Verdict + the refused level
638
+ */
639
+ export declare function isRefusedLevelRefillBlocked(manager: OrderManagerLike | null | undefined, price: unknown, type: unknown): {
640
+ blocked: boolean;
641
+ level: number | null;
642
+ };
643
+ /**
644
+ * The direction rule PLUS the geometry-territory exemption — the verdict
645
+ * every COW-path guard shares (probe and final gate), so no site re-implements
646
+ * "may this op be placed against the last fill?".
647
+ *
648
+ * Also applies the REFUSED-LEVEL same-level re-fill block (§9.12/P2 amended):
649
+ * a placement on the same side within half a grid step of a fill whose
650
+ * pivot-arm was refused stays blocked even though the direction pivot itself
651
+ * stayed behind that fill. See isRefusedLevelRefillBlocked.
652
+ *
653
+ * @param {Object} manager - OrderManager instance (geometry for the exemption)
654
+ * @param {number} price - Target price
655
+ * @param {string} type - ORDER_TYPES.BUY/SELL
656
+ * @param {number|null} pivotPrice - Resolved pivot (already ladder-snapped by the caller)
657
+ * @param {string|null} pivotType - Pivot side; null keeps the guard cold
658
+ * @returns {{blocked: boolean, pivot: number|null, threshold?: number|null, bandExempt?: boolean, refusedLevel?: boolean}}
659
+ */
660
+ export declare function evaluateLastFillGuard(manager: OrderManagerLike | null | undefined, price: number, type: unknown, pivotPrice: number | null, pivotType: string | null): {
661
+ blocked: boolean;
662
+ pivot: number | null;
663
+ threshold?: number | null;
664
+ bandExempt?: boolean;
665
+ refusedLevel?: boolean;
666
+ };
667
+ /**
668
+ *
669
+ * The direction rule (isLastFillGuardBlocked) says "never sell at/below the last
670
+ * sale". That is right when the veto is evidence of a fault — retrospective
671
+ * §9.7/§9.9: "a sell slot below the last sale is evidence that the boundary/
672
+ * crawl is behind the fill". It is WRONG when the geometry is exactly where the
673
+ * fill re-anchor puts it: after a SELL fill at slot f the re-anchor rule is
674
+ * `boundary >= f - gapSlots`, so the gap band (boundary, boundary+gap] tops out
675
+ * AT the filled level and every band slot is `<= pivot` by construction. The
676
+ * pivot then vetoes 100% of the counter-order rungs it just derived.
677
+ *
678
+ * Live (2026-11-15): a sweep armed the pivot at the band's own top level; every
679
+ * sell slot in the band was refused as "at/through the last fill", no sell
680
+ * could be re-placed, and the spread stayed 3.0% (limit 1.65%) for 86 minutes
681
+ * until an operator-visible watchdog ran out of options.
682
+ *
683
+ * The exemption is a GEOMETRY fact, not a second direction rule: it applies
684
+ * - SELL only. The BUY mirror is deliberately absent — after a BUY fill the
685
+ * band sits ABOVE the fill, and buys above the last buy are the chase class
686
+ * the guard was introduced for (§9.7 "buying later at higher prices").
687
+ * - inside the band only (boundary < idx <= boundary + gap),
688
+ * - strictly below the pivot's own ladder level (the pivot level itself is
689
+ * always refused as a same-level re-fill),
690
+ * - only when the boundary already satisfies the fill anchor
691
+ * (`boundary >= pivotIdx - gapSlots`), i.e. the geometry is NOT behind the
692
+ * fill — the precise precondition §9.7 names for the refusal.
693
+ * Fail-closed on anything unprovable (no genesis, off-ladder price, unknown
694
+ * boundary/gap).
695
+ *
696
+ * @param {Object} manager - OrderManager instance (pivot + boundary + gap + genesis)
697
+ * @param {number} price - SELL placement price
698
+ * @returns {boolean} True when the pivot must NOT veto this placement
699
+ */
700
+ export declare function isLastFillBandSellExempt(manager: OrderManagerLike | null | undefined, price: unknown): boolean;
600
701
  /**
601
702
  * LAST-FILL PLACEMENT GUARD — the direction rule applied to a PLACEMENT.
602
703
  *
@@ -614,19 +715,87 @@ export declare function isLastFillGuardBlocked(price: number, type: unknown, las
614
715
  * prices" incident). Fail-open on a cold pivot (no fill yet) so a fresh grid
615
716
  * still builds.
616
717
  *
718
+ * The SELL band exemption (isLastFillBandSellExempt) is applied between the two
719
+ * rules: a re-place at the traded level stays blocked, a band counter-order is
720
+ * not.
721
+ *
617
722
  * @param {Object} manager - OrderManager instance (pivot + config.incrementPercent)
618
723
  * @param {number} price - Target placement price
619
724
  * @param {string} type - ORDER_TYPES.BUY / ORDER_TYPES.SELL
620
- * @returns {{blocked: boolean, pivot: number|null, reason?: 'direction'|'same-level'}}
725
+ * @returns {{blocked: boolean, pivot: number|null, reason?: 'direction'|'same-level'|'refused-level'}}
621
726
  */
622
727
  export declare function isLastFillPlacementBlocked(manager: OrderManagerLike | null | undefined, price: unknown, type: unknown): {
623
728
  blocked: boolean;
624
729
  pivot: number | null;
625
- reason?: 'direction' | 'same-level';
730
+ reason?: 'direction' | 'same-level' | 'refused-level';
731
+ };
732
+ /**
733
+ * Why a grid update was refused this cycle.
734
+ *
735
+ * These are the ONLY reasons `resolveGridUpdateBlockers` may report. The list
736
+ * is closed on purpose: a new reason must be added here (and to
737
+ * `tests/test_grid_update_blockers.ts`), so "the grid did not update" can never
738
+ * be explained by an unprintable string again.
739
+ */
740
+ export type GridUpdateBlockerCode = 'fill-queued' | 'fill-deferred' | 'fill-in-flight' | 'crawl-owed' | 'broadcast-pending' | 'placement-held' | 'rebuild-active' | 'unknown-blocker';
741
+ export interface GridUpdateBlocker {
742
+ code: GridUpdateBlockerCode;
743
+ detail: string;
744
+ }
745
+ /** Pipeline state the fill blockers are derived from. `ok: false` means UNREADABLE, not settled. */
746
+ export interface FillPipelineState {
747
+ ok: boolean;
748
+ queued: number;
749
+ deferred: boolean;
750
+ inFlight: number;
751
+ owed: number;
752
+ error?: string;
753
+ }
754
+ /**
755
+ * Read the fill-pipeline counters ONCE, from a bot or a bare manager.
756
+ *
757
+ * This is the only place that peeks these fields. The previous projection
758
+ * (`hasUnsettledFills`) swallowed every read error and returned "settled",
759
+ * which is a fail-OPEN answer in a fail-closed system: an unreadable queue
760
+ * looked like an idle one and the grid was updated from a stale master.
761
+ * Unreadable is now a first-class state (`ok: false`), surfaced as
762
+ * `unknown-blocker`.
763
+ *
764
+ * These counters are pipeline bookkeeping, not lifecycle evidence: absence
765
+ * decisions still use the lifecycle registry (INV-LIFE-003), so this reader
766
+ * cannot become a second evidence set.
767
+ */
768
+ export declare function readFillPipelineState(source: unknown): FillPipelineState;
769
+ export declare function resolveGridUpdateBlockers(source: unknown, options?: {
770
+ now?: number;
771
+ }): GridUpdateBlocker[];
772
+ /**
773
+ * Count consecutive blocked cycles and decide whether the state is STUCK.
774
+ *
775
+ * Escalation is deliberately narrow: only `unknown-blocker` (unreadable
776
+ * pipeline state) escalates. A busy pipeline (`fill-in-flight`,
777
+ * `broadcast-pending`, a held region) is normal work and must not trigger a
778
+ * structural resync — the placement/broadcast watchdogs own those bounds. The
779
+ * counter is a cycle count, not a timing window: it is NOT a `TIMING` entry and
780
+ * must not be classified in `modules/timing_policy.ts`.
781
+ *
782
+ * @returns `{ cycles, escalate }`; `escalate` is true exactly when the state
783
+ * stayed unreadable for `FILL_PROCESSING.GRID_BLOCKED_ESCALATE_CYCLES`
784
+ * consecutive attempts.
785
+ */
786
+ export declare function noteGridUpdateBlockers(source: unknown, blockers: GridUpdateBlocker[] | null | undefined, options?: {
787
+ limit?: number;
788
+ }): {
789
+ cycles: number;
790
+ escalate: boolean;
626
791
  };
627
792
  /**
628
793
  * Are fills still UNSETTLED (arrived but not yet absorbed by the grid)?
629
794
  *
795
+ * Projection over `resolveGridUpdateBlockers` so the prose reason and the code
796
+ * cannot disagree. Kept as a boolean for its existing callers; new callers
797
+ * should ask for the codes.
798
+ *
630
799
  * While this returns true the master grid still holds filled slots as ACTIVE
631
800
  * and the boundary has not crawled for them, so any geometry-derived plan
632
801
  * (window top-up, startup-style reconcile) is built on the PREVIOUS book. The
@@ -781,6 +950,21 @@ export declare function setLastFillPivot(manager: OrderManagerLike, type: string
781
950
  * @returns {boolean} True when an armed pivot was cleared
782
951
  */
783
952
  export declare function resetLastFillPivot(manager: OrderManagerLike, reason?: string): boolean;
953
+ /**
954
+ * Drop the ENTIRE last-fill guard state — the pivot scalar family AND the
955
+ * bot-scoped last-market-fill reference, live and persisted — after the
956
+ * spread watchdog concluded the pivot can never heal the grid (geometry
957
+ * re-center already tried and failed; SPREAD_STALE_PIVOT_EXPIRE_MS elapsed).
958
+ *
959
+ * Mirrors restoreLastMarketFill's dead-row contract: persisted rows are
960
+ * erased too, so a restart/rebuild cannot re-arm the same veto via
961
+ * rearmLastFillPivotFromMarketFill. Both references re-arm on the next real
962
+ * fill.
963
+ *
964
+ * @param {Object} manager - OrderManager instance
965
+ * @param {string} reason - Log/debug label for the expiry
966
+ */
967
+ export declare function expireLastFillGuardReferences(manager: OrderManagerLike, reason?: string): void;
784
968
  /**
785
969
  * Restore the persisted LAST-FILL-GUARD pivot into the manager.
786
970
  *
@@ -851,7 +1035,7 @@ export declare function retryPersistenceIfNeeded(manager: OrderManagerLike): Pro
851
1035
  *
852
1036
  * @param {Object} manager - OrderManager instance
853
1037
  * @param {Object} accountOrders - AccountOrders data accessor
854
- * @param {string} botKey - Bot identifier for persistence
1038
+ * @param {string} _botKey - Unused; persistence is keyed off the manager.
855
1039
  * @param {Function} updateOrdersOnChainBatchFn - Batch update function for blockchain operations
856
1040
  * @param {Function} updateGridFromBlockchainSnapshotFn - Grid resize function (injected to avoid circular dependency with grid.ts)
857
1041
  * @returns {Promise<void>}