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.
- package/CHANGELOG.md +52 -0
- 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/grid_correction_check.d.ts +60 -1
- package/dist/analysis/grid_correction_check.js +268 -18
- package/dist/analysis/pivot_timeline.d.ts +78 -0
- package/dist/analysis/pivot_timeline.js +360 -0
- package/dist/market_adapter/utils/file_lock.js +16 -4
- package/dist/modules/account_bots.d.ts +7 -0
- package/dist/modules/account_bots.js +7 -5
- package/dist/modules/bot_defaults.js +6 -1
- package/dist/modules/constants.d.ts +14 -0
- package/dist/modules/constants.js +82 -2
- package/dist/modules/dexbot_class.d.ts +39 -0
- package/dist/modules/dexbot_class.js +86 -1
- package/dist/modules/dexbot_cow_runtime.d.ts +31 -1
- package/dist/modules/dexbot_cow_runtime.js +299 -75
- package/dist/modules/dexbot_maintenance_runtime.d.ts +32 -2
- package/dist/modules/dexbot_maintenance_runtime.js +196 -16
- package/dist/modules/dexbot_state_recovery.js +15 -1
- package/dist/modules/launcher/instance_lock.d.ts +27 -0
- package/dist/modules/launcher/instance_lock.js +131 -0
- package/dist/modules/node_flap_score.d.ts +6 -6
- package/dist/modules/node_flap_score.js +6 -6
- package/dist/modules/order/accounting.d.ts +9 -4
- package/dist/modules/order/accounting.js +89 -26
- package/dist/modules/order/async_lock.d.ts +7 -1
- package/dist/modules/order/async_lock.js +7 -1
- package/dist/modules/order/export.js +25 -18
- package/dist/modules/order/fill_ledger.d.ts +99 -0
- package/dist/modules/order/fill_ledger.js +103 -0
- package/dist/modules/order/grid.d.ts +94 -18
- package/dist/modules/order/grid.js +247 -75
- package/dist/modules/order/grid_reconcile_internal.js +16 -4
- package/dist/modules/order/index.d.ts +29 -6
- package/dist/modules/order/index.js +5 -5
- package/dist/modules/order/lifecycle.js +3 -3
- package/dist/modules/order/manager.d.ts +36 -24
- package/dist/modules/order/manager.js +159 -39
- package/dist/modules/order/placement_lock.d.ts +30 -0
- package/dist/modules/order/placement_lock.js +48 -0
- package/dist/modules/order/sync_engine.d.ts +66 -118
- package/dist/modules/order/sync_engine.js +118 -162
- package/dist/modules/order/utils/math.d.ts +7 -3
- package/dist/modules/order/utils/math.js +7 -3
- package/dist/modules/order/utils/order.d.ts +79 -42
- package/dist/modules/order/utils/order.js +183 -86
- package/dist/modules/order/utils/system.d.ts +192 -8
- package/dist/modules/order/utils/system.js +534 -34
- package/dist/modules/paths.d.ts +1 -0
- package/dist/modules/paths.js +1 -0
- package/dist/modules/timing_policy.js +4 -2
- package/dist/modules/types.d.ts +49 -27
- package/dist/pm2.js +126 -0
- package/dist/unlock.js +26 -1
- package/docs/COW_INVARIANTS.md +5 -1
- package/docs/DEXBOT_COMPARISON.md +5 -5
- package/docs/EVOLUTION.md +10 -8
- package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
- package/docs/GRID_RECONCILE.md +3 -3
- package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +192 -31
- package/docs/README.md +1 -1
- package/docs/architecture.md +26 -8
- package/modules/README.md +4 -0
- 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 (
|
|
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:
|
|
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
|
|
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,
|
|
74
|
-
*
|
|
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}
|
|
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>}
|