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.
- package/CHANGELOG.md +28 -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/modules/account_bots.d.ts +1 -0
- package/dist/modules/account_bots.js +7 -5
- package/dist/modules/constants.d.ts +2 -0
- package/dist/modules/constants.js +16 -2
- package/dist/modules/dexbot_class.d.ts +22 -0
- package/dist/modules/dexbot_class.js +30 -0
- package/dist/modules/dexbot_cow_runtime.d.ts +31 -1
- package/dist/modules/dexbot_cow_runtime.js +68 -56
- package/dist/modules/dexbot_maintenance_runtime.d.ts +1 -1
- package/dist/modules/dexbot_maintenance_runtime.js +33 -6
- 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 +75 -18
- package/dist/modules/order/grid.js +207 -61
- package/dist/modules/order/grid_reconcile_internal.js +16 -4
- package/dist/modules/order/index.d.ts +14 -5
- package/dist/modules/order/index.js +5 -5
- package/dist/modules/order/lifecycle.js +3 -3
- package/dist/modules/order/manager.d.ts +15 -24
- package/dist/modules/order/manager.js +40 -27
- 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 +40 -41
- package/dist/modules/order/utils/order.js +110 -84
- package/dist/modules/order/utils/system.d.ts +81 -6
- package/dist/modules/order/utils/system.js +167 -29
- package/dist/modules/timing_policy.js +2 -2
- package/dist/modules/types.d.ts +22 -27
- package/docs/COW_INVARIANTS.md +5 -1
- package/docs/DEXBOT_COMPARISON.md +4 -4
- package/docs/EVOLUTION.md +6 -5
- 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 +38 -30
- package/docs/README.md +1 -1
- package/docs/architecture.md +26 -8
- package/modules/README.md +3 -0
- package/package.json +3 -3
|
@@ -31,22 +31,22 @@
|
|
|
31
31
|
*
|
|
32
32
|
* SUBSYSTEM MODULES:
|
|
33
33
|
* 1. manager.ts - OrderManager class (order lifecycle, fund tracking)
|
|
34
|
-
* 2. grid.ts - Grid
|
|
34
|
+
* 2. grid.ts - Grid engine (grid creation, synchronization, health)
|
|
35
35
|
* 3. utils/math.ts, utils/order.ts, utils/system.ts - Helper functions by concern
|
|
36
|
-
* 4. format.ts - Numeric formatting (
|
|
36
|
+
* 4. format.ts - Numeric formatting (18 functions for consistent display)
|
|
37
37
|
* 5. accounting.ts - Accountant class (fund calculations and reconciliation)
|
|
38
38
|
* 6. logger.ts - Logger class (structured, color-coded output)
|
|
39
39
|
* 7. async_lock.ts - AsyncLock class (race condition prevention)
|
|
40
40
|
* 8. working_grid.ts - WorkingGrid class (copy-on-write grid state)
|
|
41
41
|
* 9. export.ts - Trade history extraction and CSV export
|
|
42
42
|
* 10. grid_reconcile.ts - Grid reconciliation against chain (startup + maintenance)
|
|
43
|
-
* 11. strategy.ts -
|
|
43
|
+
* 11. strategy.ts - StrategyEngine class (boundary-crawl rebalancing, target grid)
|
|
44
44
|
* 12. sync_engine.ts - Real-time blockchain synchronization
|
|
45
45
|
*
|
|
46
46
|
* ===============================================================================
|
|
47
47
|
*/
|
|
48
|
-
//
|
|
49
|
-
//
|
|
48
|
+
// The logger is required lazily: it pulls in console/formatting setup that small
|
|
49
|
+
// unit tests do not need, and `logger` is exposed as a lazy getter below.
|
|
50
50
|
import { createRequire } from 'node:module';
|
|
51
51
|
const require = createRequire(import.meta.url);
|
|
52
52
|
import { OrderManager } from './manager.js';
|
|
@@ -884,9 +884,9 @@ export class LifecycleRegistry {
|
|
|
884
884
|
record.revision += 1;
|
|
885
885
|
// Dropping a pending entry means the CREATE resolved. If the record
|
|
886
886
|
// still reads `broadcasting`, nothing was observed afterwards, so the
|
|
887
|
-
// slot is a clean intent again. (
|
|
888
|
-
//
|
|
889
|
-
// not collapse into one.)
|
|
887
|
+
// slot is a clean intent again. (A pending entry that expires in the
|
|
888
|
+
// manager's TTL sweep goes through `_expirePendingBroadcast`, which
|
|
889
|
+
// leaves `unknown` instead — the two cases must not collapse into one.)
|
|
890
890
|
if (record.phase === 'broadcasting')
|
|
891
891
|
record.phase = 'intent';
|
|
892
892
|
if (!record.orderId && !record.slotId)
|
|
@@ -9,8 +9,8 @@
|
|
|
9
9
|
* ===============================================================================
|
|
10
10
|
*
|
|
11
11
|
* SECTION 1: EXTERNAL DEPENDENCIES
|
|
12
|
-
* SECTION 2: COW REBALANCE ENGINE
|
|
13
|
-
* SECTION 3: ORDER MANAGER CLASS
|
|
12
|
+
* SECTION 2: COW REBALANCE ENGINE - COWRebalanceEngine class (exported)
|
|
13
|
+
* SECTION 3: ORDER MANAGER CLASS - OrderManager class (exported)
|
|
14
14
|
* ===============================================================================
|
|
15
15
|
*/
|
|
16
16
|
import { WorkingGrid } from './working_grid.js';
|
|
@@ -195,6 +195,7 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
195
195
|
_pauseFundRecalc: number;
|
|
196
196
|
_pauseFundRecalcWatchdog: ReturnType<typeof setTimeout> | null;
|
|
197
197
|
_fillBatchInFlight: number;
|
|
198
|
+
_gridUpdateBlockedCycles: number;
|
|
198
199
|
_pauseRecalcLogging: boolean;
|
|
199
200
|
_pauseRecalcLoggingWatchdog: ReturnType<typeof setTimeout> | null;
|
|
200
201
|
_throwOnIllegalState: boolean;
|
|
@@ -365,7 +366,8 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
365
366
|
* `isPlacementLeaseCurrent()` before mutating.
|
|
366
367
|
*
|
|
367
368
|
* Lock hierarchy: acquire placement BEFORE `_gridLock`; never acquire it
|
|
368
|
-
* while holding `_gridLock` (Level 0.5 — see
|
|
369
|
+
* while holding `_gridLock` (Level 0.5 — see the constructor's canonical
|
|
370
|
+
* lock-hierarchy block in this file).
|
|
369
371
|
*
|
|
370
372
|
* @returns `null` when the region could not be acquired; the caller must
|
|
371
373
|
* defer/abort its broadcast.
|
|
@@ -452,14 +454,6 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
452
454
|
* @returns {number} Applied (already-in-snapshot) amount, 0..filledInt
|
|
453
455
|
*/
|
|
454
456
|
consumeChainSizeAppliedFillAmount(orderId: string, filledInt: number, maxAgeMs?: number): number;
|
|
455
|
-
/**
|
|
456
|
-
* Boolean compatibility wrapper for {@link consumeChainSizeAppliedFillAmount}.
|
|
457
|
-
* @param {string} orderId - Chain order id
|
|
458
|
-
* @param {number} filledInt - Base-amount delta in chain integer units
|
|
459
|
-
* @param {number} [maxAgeMs] - Marker freshness bound
|
|
460
|
-
* @returns {boolean} true when any part of the fill was already applied
|
|
461
|
-
*/
|
|
462
|
-
consumeChainSizeAppliedFill(orderId: string, filledInt: number, maxAgeMs?: number): boolean;
|
|
463
457
|
/**
|
|
464
458
|
* Merge persisted pass-1 markers into the in-memory set (recovery reload).
|
|
465
459
|
* Live markers win on conflict: they may already be partially consumed,
|
|
@@ -709,7 +703,7 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
709
703
|
*/
|
|
710
704
|
resumeRecalcLogging(): void;
|
|
711
705
|
/**
|
|
712
|
-
* @param {Array<import('
|
|
706
|
+
* @param {Array<import('../types.js').Order>} orders
|
|
713
707
|
* @param {Object} info
|
|
714
708
|
* @returns {Promise<any>}
|
|
715
709
|
*/
|
|
@@ -826,7 +820,7 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
826
820
|
_peekWorkingGrid(): WorkingGrid | null;
|
|
827
821
|
_syncWorkingGridFromMasterMutation(orderId: string, context: string): void;
|
|
828
822
|
/**
|
|
829
|
-
* @param {Array<import('
|
|
823
|
+
* @param {Array<import('../types.js').Order>} updates - Order updates to apply
|
|
830
824
|
* @param {string} [context] - Update context label
|
|
831
825
|
* @param {unknown} [options]
|
|
832
826
|
* @returns {Promise<boolean>}
|
|
@@ -883,14 +877,14 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
883
877
|
reason: string;
|
|
884
878
|
}>;
|
|
885
879
|
/**
|
|
886
|
-
* @param {Array<import('
|
|
880
|
+
* @param {Array<import('../types.js').Order>} orders - Filled orders
|
|
887
881
|
* @param {Set<string>} [excl] - Order IDs to exclude
|
|
888
882
|
* @param {Object} [options]
|
|
889
883
|
* @returns {Promise<any>}
|
|
890
884
|
*/
|
|
891
885
|
processFilledOrders(orders: COWFillLike[], excl: Set<string>, options?: UnknownRecord): Promise<RebalanceResult>;
|
|
892
886
|
/**
|
|
893
|
-
* @returns {Array<import('
|
|
887
|
+
* @returns {Array<import('../types.js').Order>}
|
|
894
888
|
*/
|
|
895
889
|
getInitialOrdersToActivate(): ManagedOrder[];
|
|
896
890
|
/**
|
|
@@ -933,19 +927,16 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
933
927
|
* Also used when the boundary is (re)anchored outside the fill path (grid
|
|
934
928
|
* reset / recenter / rejected-snapshot rebuild): those records belong to
|
|
935
929
|
* the previous generation, and applying their relative deltas onto a fresh
|
|
936
|
-
* anchor would double-count movement the anchor already contains.
|
|
930
|
+
* anchor would double-count movement the anchor already contains. That is
|
|
931
|
+
* the explicit allowed-loss path: the grid generation is being discarded
|
|
932
|
+
* (rebuild, rejected snapshot, restart replay), so the relative deltas no
|
|
933
|
+
* longer have a geometry to apply onto.
|
|
937
934
|
*
|
|
938
935
|
* Marks the grid dirty so the cleared array reaches disk even on paths
|
|
939
936
|
* that do not otherwise persist.
|
|
940
937
|
*
|
|
941
938
|
* @param {string} reason - Log/debug label for the drop
|
|
942
|
-
|
|
943
|
-
/**
|
|
944
|
-
* Drop ALL owed fill-crawl records.
|
|
945
|
-
*
|
|
946
|
-
* This is the explicit allowed-loss path: the grid generation is being
|
|
947
|
-
* discarded (rebuild, rejected snapshot, restart replay), so the relative
|
|
948
|
-
* deltas no longer have a geometry to apply onto.
|
|
939
|
+
* @param {string} detail - Extra context appended to the drop log line
|
|
949
940
|
*/
|
|
950
941
|
_clearPendingFillCrawls(reason?: string, detail?: string): void;
|
|
951
942
|
/**
|
|
@@ -1121,7 +1112,7 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
1121
1112
|
*/
|
|
1122
1113
|
clearStalePipelineOperations(): boolean;
|
|
1123
1114
|
/**
|
|
1124
|
-
* @param {Map<string, import('
|
|
1115
|
+
* @param {Map<string, import('../types.js').Order>} targetGrid
|
|
1125
1116
|
* @param {number} targetBoundary
|
|
1126
1117
|
* @returns {Object}
|
|
1127
1118
|
*/
|
|
@@ -9,8 +9,8 @@
|
|
|
9
9
|
* ===============================================================================
|
|
10
10
|
*
|
|
11
11
|
* SECTION 1: EXTERNAL DEPENDENCIES
|
|
12
|
-
* SECTION 2: COW REBALANCE ENGINE
|
|
13
|
-
* SECTION 3: ORDER MANAGER CLASS
|
|
12
|
+
* SECTION 2: COW REBALANCE ENGINE - COWRebalanceEngine class (exported)
|
|
13
|
+
* SECTION 3: ORDER MANAGER CLASS - OrderManager class (exported)
|
|
14
14
|
* ===============================================================================
|
|
15
15
|
*/
|
|
16
16
|
// ===============================================================================
|
|
@@ -163,10 +163,29 @@ class COWRebalanceEngine {
|
|
|
163
163
|
// the whole slot's action group (a type-mismatch CANCEL is paired with
|
|
164
164
|
// a CREATE on the same id) for the grace window. The surplus is
|
|
165
165
|
// re-derived next cycle once the order has had time to prove itself.
|
|
166
|
+
//
|
|
167
|
+
// EXEMPT: a chain-observed wrong-side order. Only the correction
|
|
168
|
+
// queue's `typeMismatch` entry proves the CHAIN side is wrong; a
|
|
169
|
+
// plan-shaped CANCEL with reason 'type-mismatch' only proves
|
|
170
|
+
// master !== target, which is exactly the stale-target lag this
|
|
171
|
+
// grace exists for and must keep waiting. The pre-batch drain
|
|
172
|
+
// (correctAllPriceMismatches) normally cancels the mismatch first;
|
|
173
|
+
// when it deferred (active region) or failed, the entry is still
|
|
174
|
+
// queued — parking this action would add a second, 15-minute wait.
|
|
175
|
+
const knownWrongSide = new Set();
|
|
176
|
+
if (manager && Array.isArray(manager.ordersNeedingPriceCorrection)) {
|
|
177
|
+
for (const correction of manager.ordersNeedingPriceCorrection) {
|
|
178
|
+
if (correction?.typeMismatch === true && correction.chainOrderId) {
|
|
179
|
+
knownWrongSide.add(String(correction.chainOrderId));
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
}
|
|
166
183
|
const deferredFreshCancelSlots = new Set();
|
|
167
184
|
for (const action of reconcileResult.actions) {
|
|
168
185
|
if (action.type !== COW_ACTIONS.CANCEL || !action.orderId)
|
|
169
186
|
continue;
|
|
187
|
+
if (knownWrongSide.has(String(action.orderId)))
|
|
188
|
+
continue;
|
|
170
189
|
if (!manager || !isFreshlyPlacedOrder(manager, action.orderId))
|
|
171
190
|
continue;
|
|
172
191
|
const slotId = String(action.id);
|
|
@@ -420,6 +439,11 @@ class OrderManager {
|
|
|
420
439
|
_pauseFundRecalc;
|
|
421
440
|
_pauseFundRecalcWatchdog;
|
|
422
441
|
_fillBatchInFlight;
|
|
442
|
+
// Consecutive blocked-cycle counter for the grid-update gate
|
|
443
|
+
// (`noteGridUpdateBlockers` in order/utils/system.ts is its only writer and
|
|
444
|
+
// reader). Cleared when the gate is evaluated healthy or not evaluated at
|
|
445
|
+
// all; a cycle count, never a timing window.
|
|
446
|
+
_gridUpdateBlockedCycles;
|
|
423
447
|
_pauseRecalcLogging;
|
|
424
448
|
_pauseRecalcLoggingWatchdog;
|
|
425
449
|
_throwOnIllegalState;
|
|
@@ -631,6 +655,7 @@ class OrderManager {
|
|
|
631
655
|
// window would report a spurious Total != Free + Committed by exactly the
|
|
632
656
|
// fills' size. The check runs once the batch settles instead.
|
|
633
657
|
this._fillBatchInFlight = 0;
|
|
658
|
+
this._gridUpdateBlockedCycles = 0;
|
|
634
659
|
this._pauseRecalcLogging = false;
|
|
635
660
|
this._pauseRecalcLoggingWatchdog = null;
|
|
636
661
|
this._throwOnIllegalState = false;
|
|
@@ -644,7 +669,7 @@ class OrderManager {
|
|
|
644
669
|
this._committedOrderIdsBuiltAt = 0;
|
|
645
670
|
this._orderIdAssignedAt = new Map();
|
|
646
671
|
// Fresh-placement timestamps (chainOrderId -> Date.now) for the
|
|
647
|
-
// surplus-cancel grace window.
|
|
672
|
+
// surplus-cancel grace window. Written by this lifecycle funnel only.
|
|
648
673
|
this._placedAt = new Map();
|
|
649
674
|
this._gapSlots = 0;
|
|
650
675
|
// Genesis (price-ladder) state. `_genesis` is established by
|
|
@@ -842,7 +867,8 @@ class OrderManager {
|
|
|
842
867
|
* `isPlacementLeaseCurrent()` before mutating.
|
|
843
868
|
*
|
|
844
869
|
* Lock hierarchy: acquire placement BEFORE `_gridLock`; never acquire it
|
|
845
|
-
* while holding `_gridLock` (Level 0.5 — see
|
|
870
|
+
* while holding `_gridLock` (Level 0.5 — see the constructor's canonical
|
|
871
|
+
* lock-hierarchy block in this file).
|
|
846
872
|
*
|
|
847
873
|
* @returns `null` when the region could not be acquired; the caller must
|
|
848
874
|
* defer/abort its broadcast.
|
|
@@ -993,16 +1019,6 @@ class OrderManager {
|
|
|
993
1019
|
}
|
|
994
1020
|
return applied;
|
|
995
1021
|
}
|
|
996
|
-
/**
|
|
997
|
-
* Boolean compatibility wrapper for {@link consumeChainSizeAppliedFillAmount}.
|
|
998
|
-
* @param {string} orderId - Chain order id
|
|
999
|
-
* @param {number} filledInt - Base-amount delta in chain integer units
|
|
1000
|
-
* @param {number} [maxAgeMs] - Marker freshness bound
|
|
1001
|
-
* @returns {boolean} true when any part of the fill was already applied
|
|
1002
|
-
*/
|
|
1003
|
-
consumeChainSizeAppliedFill(orderId, filledInt, maxAgeMs = TIMING.CHAIN_SIZE_APPLIED_MARKER_TTL_MS) {
|
|
1004
|
-
return this.consumeChainSizeAppliedFillAmount(orderId, filledInt, maxAgeMs) > 0;
|
|
1005
|
-
}
|
|
1006
1022
|
/**
|
|
1007
1023
|
* Merge persisted pass-1 markers into the in-memory set (recovery reload).
|
|
1008
1024
|
* Live markers win on conflict: they may already be partially consumed,
|
|
@@ -1608,7 +1624,7 @@ class OrderManager {
|
|
|
1608
1624
|
}
|
|
1609
1625
|
}
|
|
1610
1626
|
/**
|
|
1611
|
-
* @param {Array<import('
|
|
1627
|
+
* @param {Array<import('../types.js').Order>} orders
|
|
1612
1628
|
* @param {Object} info
|
|
1613
1629
|
* @returns {Promise<any>}
|
|
1614
1630
|
*/
|
|
@@ -1956,7 +1972,7 @@ class OrderManager {
|
|
|
1956
1972
|
}
|
|
1957
1973
|
}
|
|
1958
1974
|
/**
|
|
1959
|
-
* @param {Array<import('
|
|
1975
|
+
* @param {Array<import('../types.js').Order>} updates - Order updates to apply
|
|
1960
1976
|
* @param {string} [context] - Update context label
|
|
1961
1977
|
* @param {unknown} [options]
|
|
1962
1978
|
* @returns {Promise<boolean>}
|
|
@@ -2045,7 +2061,7 @@ class OrderManager {
|
|
|
2045
2061
|
return result || { isValid: true };
|
|
2046
2062
|
}
|
|
2047
2063
|
/**
|
|
2048
|
-
* @param {Array<import('
|
|
2064
|
+
* @param {Array<import('../types.js').Order>} orders - Filled orders
|
|
2049
2065
|
* @param {Set<string>} [excl] - Order IDs to exclude
|
|
2050
2066
|
* @param {Object} [options]
|
|
2051
2067
|
* @returns {Promise<any>}
|
|
@@ -2094,7 +2110,7 @@ class OrderManager {
|
|
|
2094
2110
|
};
|
|
2095
2111
|
}
|
|
2096
2112
|
/**
|
|
2097
|
-
* @returns {Array<import('
|
|
2113
|
+
* @returns {Array<import('../types.js').Order>}
|
|
2098
2114
|
*/
|
|
2099
2115
|
getInitialOrdersToActivate() {
|
|
2100
2116
|
// Apply coreOrders limit from config
|
|
@@ -2247,19 +2263,16 @@ class OrderManager {
|
|
|
2247
2263
|
* Also used when the boundary is (re)anchored outside the fill path (grid
|
|
2248
2264
|
* reset / recenter / rejected-snapshot rebuild): those records belong to
|
|
2249
2265
|
* the previous generation, and applying their relative deltas onto a fresh
|
|
2250
|
-
* anchor would double-count movement the anchor already contains.
|
|
2266
|
+
* anchor would double-count movement the anchor already contains. That is
|
|
2267
|
+
* the explicit allowed-loss path: the grid generation is being discarded
|
|
2268
|
+
* (rebuild, rejected snapshot, restart replay), so the relative deltas no
|
|
2269
|
+
* longer have a geometry to apply onto.
|
|
2251
2270
|
*
|
|
2252
2271
|
* Marks the grid dirty so the cleared array reaches disk even on paths
|
|
2253
2272
|
* that do not otherwise persist.
|
|
2254
2273
|
*
|
|
2255
2274
|
* @param {string} reason - Log/debug label for the drop
|
|
2256
|
-
|
|
2257
|
-
/**
|
|
2258
|
-
* Drop ALL owed fill-crawl records.
|
|
2259
|
-
*
|
|
2260
|
-
* This is the explicit allowed-loss path: the grid generation is being
|
|
2261
|
-
* discarded (rebuild, rejected snapshot, restart replay), so the relative
|
|
2262
|
-
* deltas no longer have a geometry to apply onto.
|
|
2275
|
+
* @param {string} detail - Extra context appended to the drop log line
|
|
2263
2276
|
*/
|
|
2264
2277
|
_clearPendingFillCrawls(reason = 'unspecified', detail = '') {
|
|
2265
2278
|
if (!Array.isArray(this._pendingFillCrawls) || this._pendingFillCrawls.length === 0)
|
|
@@ -2710,7 +2723,7 @@ class OrderManager {
|
|
|
2710
2723
|
return true;
|
|
2711
2724
|
}
|
|
2712
2725
|
/**
|
|
2713
|
-
* @param {Map<string, import('
|
|
2726
|
+
* @param {Map<string, import('../types.js').Order>} targetGrid
|
|
2714
2727
|
* @param {number} targetBoundary
|
|
2715
2728
|
* @returns {Object}
|
|
2716
2729
|
*/
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
* Uses AsyncLock to prevent concurrent sync operations (defense-in-depth locking).
|
|
16
16
|
*
|
|
17
17
|
* ===============================================================================
|
|
18
|
-
* TABLE OF CONTENTS - SyncEngine Class (
|
|
18
|
+
* TABLE OF CONTENTS - SyncEngine Class (14 methods) + module-level helpers
|
|
19
19
|
* ===============================================================================
|
|
20
20
|
*
|
|
21
21
|
* MODULE-LEVEL HELPERS (internal, not exported):
|
|
@@ -42,42 +42,46 @@
|
|
|
42
42
|
* 4. _performSyncFromOpenOrders(mgr, precA, precB, parsedChain, rawChain, options) - Core sync logic (internal)
|
|
43
43
|
* Performs actual two-pass reconciliation without locking
|
|
44
44
|
* Pass 1: Match grid orders to chain (known grid → chain, includes orphan cleanup)
|
|
45
|
-
* Pass 2:
|
|
45
|
+
* Pass 2: Bind unmatched chain orders to their genesis-ladder slot (chain → grid)
|
|
46
46
|
*
|
|
47
|
-
* FILL PROCESSING (
|
|
47
|
+
* FILL PROCESSING (6 methods)
|
|
48
48
|
* 5. _findMatchingGridOrder(mgr, orderId) - Look up the grid slot owning a chain order (internal)
|
|
49
49
|
*
|
|
50
|
-
* 6. _computeFillContext(mgr, matchedGridOrder, paysAssetId, paysAmountRaw
|
|
51
|
-
* Resolve the asset/side context for
|
|
50
|
+
* 6. _computeFillContext(mgr, matchedGridOrder, paysAssetId, paysAmountRaw,
|
|
51
|
+
* receivesAssetId, receivesAmountRaw) - Resolve the asset/side context for
|
|
52
|
+
* a fill (internal)
|
|
52
53
|
*
|
|
53
54
|
* 7. _computeFillTransitionResult(mgr, params) - Compute the post-fill slot
|
|
54
55
|
* transition and fund deltas without mutating state (internal, async)
|
|
55
56
|
*
|
|
56
|
-
* 8.
|
|
57
|
+
* 8. _absorbUnmatchedFill(mgr, params) - Attribute a fill whose slot was
|
|
58
|
+
* already virtualised (thin wrapper over utils/order.ts) (internal, async)
|
|
59
|
+
*
|
|
60
|
+
* 9. syncFromFillHistory(fill) - Process single fill event synchronously
|
|
57
61
|
* Updates grid order state based on fill data
|
|
58
62
|
* Updates fund state and accounting
|
|
59
63
|
* Handles both maker and taker fills
|
|
60
64
|
*
|
|
61
|
-
*
|
|
65
|
+
* 10. syncFromFillHistoryBatch(fills) - Process multiple fill events in batch
|
|
62
66
|
* Acquires _gridLock once for all fills in block group
|
|
63
67
|
* Batches drift refetch into one get_objects RPC call
|
|
64
68
|
* Applies all grid mutations in a single applyGridUpdateBatch
|
|
65
69
|
*
|
|
66
70
|
* FULL SYNCHRONIZATION (2 methods - async)
|
|
67
|
-
*
|
|
71
|
+
* 11. _assertGenesisInvariant(mgr) - Fail-closed check that a snapshot has a genesis ladder (internal)
|
|
68
72
|
*
|
|
69
|
-
*
|
|
73
|
+
* 12. synchronizeWithChain(chainData, source) - Full sync (fetch + sync) (async)
|
|
70
74
|
* Fetches fresh account balances
|
|
71
75
|
* Calls syncFromOpenOrders() with chain data
|
|
72
76
|
* Source: event type that triggered sync (fill, poll, broadcast, etc.)
|
|
73
77
|
*
|
|
74
78
|
* ACCOUNT STATE (2 methods - async)
|
|
75
|
-
*
|
|
79
|
+
* 13. fetchAccountBalancesAndSetTotals() - Fetch account totals (async)
|
|
76
80
|
* Retrieves BUY/SELL totals and free balances from blockchain
|
|
77
81
|
* Sets manager.accountTotals
|
|
78
82
|
* Triggers fund recalculation
|
|
79
83
|
*
|
|
80
|
-
*
|
|
84
|
+
* 14. initializeAssets() - Initialize asset metadata (async)
|
|
81
85
|
* Fetches asset precision and other metadata
|
|
82
86
|
* Sets manager.assets
|
|
83
87
|
* Called once at bot startup
|
|
@@ -101,10 +105,16 @@
|
|
|
101
105
|
* - Update sizes and mark as filled if needed
|
|
102
106
|
* - Downgrade to VIRTUAL if not found on-chain
|
|
103
107
|
*
|
|
104
|
-
* PASS 2: Chain → Grid
|
|
105
|
-
* - For each chain order not matched
|
|
106
|
-
*
|
|
107
|
-
* -
|
|
108
|
+
* PASS 2: Chain → Grid (genesis-frozen nearest-slot adoption)
|
|
109
|
+
* - For each chain order not matched in pass 1, resolve its slot from the
|
|
110
|
+
* frozen price ladder (`slotIndexForPrice`) and adopt it there
|
|
111
|
+
* - No tolerance matcher remains: without a ladder the E2 gate refuses the
|
|
112
|
+
* sync, and a ladder-less grid defers every orphan instead of matching it
|
|
113
|
+
* - A price outside the grid range is HELD/deferred (nearest slot is only
|
|
114
|
+
* reported as a hint) — it is never adopted into a rail slot
|
|
115
|
+
* - An order whose price cannot be resolved to a slot is queued for a
|
|
116
|
+
* cancel-only correction; the deferred (no-ladder / out-of-grid) cases are
|
|
117
|
+
* logged and held, never dropped silently
|
|
108
118
|
*
|
|
109
119
|
* ===============================================================================
|
|
110
120
|
*/
|
|
@@ -157,11 +167,6 @@ interface FillTransitionParams {
|
|
|
157
167
|
* alreadyAppliedInt`; a partial value handles split/aggregated fills.
|
|
158
168
|
*/
|
|
159
169
|
alreadyAppliedInt?: number;
|
|
160
|
-
/**
|
|
161
|
-
* Backward-compatible boolean form: true means the whole fill was already
|
|
162
|
-
* applied (equivalent to alreadyAppliedInt = filledAmountInt).
|
|
163
|
-
*/
|
|
164
|
-
alreadyAppliedChainSize?: boolean;
|
|
165
170
|
}
|
|
166
171
|
interface SyncChainData {
|
|
167
172
|
gridOrderId?: string;
|
|
@@ -187,72 +192,15 @@ declare class SyncEngine {
|
|
|
187
192
|
*/
|
|
188
193
|
constructor(manager: OrderManagerLike);
|
|
189
194
|
/**
|
|
190
|
-
* Reconcile grid orders against fresh blockchain open
|
|
191
|
-
* This is the MAIN SYNCHRONIZATION MECHANISM
|
|
192
|
-
*
|
|
195
|
+
* Reconcile grid orders against a fresh blockchain open-orders snapshot.
|
|
196
|
+
* This is the MAIN SYNCHRONIZATION MECHANISM: it corrects the grid when the
|
|
197
|
+
* chain state diverges from local expectations. The two-pass structure, the
|
|
198
|
+
* lock hierarchy and the per-pass rules live in the module header; the
|
|
199
|
+
* fail-closed genesis gate (E2) runs before anything is touched.
|
|
193
200
|
*
|
|
194
|
-
* CRITICAL: This method uses AsyncLock (defense-in-depth) to ensure only one
|
|
195
|
-
* full-sync operation runs at a time. WITHIN that lock, per-order locks prevent
|
|
196
|
-
* concurrent createOrder/cancelOrder races.
|
|
197
|
-
*
|
|
198
|
-
* LOCK HIERARCHY:
|
|
199
|
-
* 1. _syncLock (AsyncLock): Ensures only one full-sync at a time
|
|
200
|
-
* 2. Per-order locks (shadowOrderIds): Protect specific orders during sync
|
|
201
|
-
* 3. Lock refresh mechanism: Prevents timeout during long reconciliation
|
|
202
|
-
*
|
|
203
|
-
* RECONCILIATION FLOW:
|
|
204
|
-
* ========================================================================
|
|
205
|
-
* This method performs a two-pass reconciliation:
|
|
206
|
-
*
|
|
207
|
-
* PASS 1: Match grid orders to chain orders (known grid → chain lookup)
|
|
208
|
-
* - For each grid order with an orderId, find the matching chain order
|
|
209
|
-
* - Detect partial fills: if chain size < grid size, downgrade to PARTIAL state
|
|
210
|
-
* - Detect full fills: if order no longer exists on chain, convert to SPREAD
|
|
211
|
-
* - Detect price slippage: flag orders for price correction if needed
|
|
212
|
-
* - Update grid order sizes to match chain reality
|
|
213
|
-
*
|
|
214
|
-
* PASS 2: Orphan chain orders (chain → grid lookup)
|
|
215
|
-
* - For chain orders not matched in Pass 1, find best grid slot match
|
|
216
|
-
* - This handles cases where an order was placed but grid lost track (race condition)
|
|
217
|
-
* - Uses price tolerance and geometric proximity to find the best match
|
|
218
|
-
* - Once matched, retroactively assign orderId and synchronize state
|
|
219
|
-
*
|
|
220
|
-
* CRITICAL RULES:
|
|
221
|
-
* 1. ACTIVE orders can only stay ACTIVE if size matches chain exactly
|
|
222
|
-
* If chain size < grid size → must transition to PARTIAL
|
|
223
|
-
* 2. If an ACTIVE order is not found on chain → it filled → convert to SPREAD
|
|
224
|
-
* 3. Precision matters: Use blockchain integer arithmetic to compare sizes
|
|
225
|
-
* Floating point comparisons can give false positives for partial fills
|
|
226
|
-
* 4. Size updates are applied via applyChainSizeToGridOrder() which handles
|
|
227
|
-
* precision conversion and may adjust sizes slightly for blockchain granularity
|
|
228
|
-
*
|
|
229
|
-
* PRICE TOLERANCE CALCULATION:
|
|
230
|
-
* calculatePriceTolerance() can return null in these cases:
|
|
231
|
-
* 1. assets parameter is null/missing
|
|
232
|
-
* 2. gridPrice is 0 or null (invalid price)
|
|
233
|
-
* 3. orderSize is 0 or null (invalid size - orders should not sync with 0 size)
|
|
234
|
-
* 4. assetA or assetB precision is undefined (asset metadata not loaded)
|
|
235
|
-
* When tolerance is null, we treat it as 0 (strict: any price difference flagged).
|
|
236
|
-
* This is safe because null signals a configuration/data issue, not a real order.
|
|
237
|
-
*
|
|
238
|
-
* RETURNS: { filledOrders, updatedOrders, ordersNeedingCorrection }
|
|
239
|
-
* - filledOrders: Orders that completed (now SPREAD placeholders)
|
|
240
|
-
* - updatedOrders: All orders modified during sync (state changes, size updates)
|
|
241
|
-
* - ordersNeedingCorrection: Orders with price slippage requiring correction
|
|
242
|
-
*
|
|
243
|
-
* EDGE CASES HANDLED:
|
|
244
|
-
* - Orphan chain orders (placed but grid lost track due to race condition)
|
|
245
|
-
* - Partial fills (size reduced on chain)
|
|
246
|
-
* - Full fills (order removed from chain completely)
|
|
247
|
-
* - Price tolerance (small slippage acceptable, large slippage flagged)
|
|
248
|
-
* - Precision mismatches (blockchain integer precision vs float grid)
|
|
249
|
-
* - Double spending prevention (each chain order matched to at most one grid order)
|
|
250
|
-
*/
|
|
251
|
-
/**
|
|
252
|
-
* Synchronize grid orders with blockchain open orders snapshot.
|
|
253
201
|
* @param {Array|null} chainOrders - Array of blockchain order objects
|
|
254
202
|
* @param {Object} [options={}] - Sync options (e.g., { skipAccounting: true })
|
|
255
|
-
* @returns {Promise<
|
|
203
|
+
* @returns {Promise<SyncResult>} filledOrders, updatedOrders, ordersNeedingCorrection
|
|
256
204
|
*/
|
|
257
205
|
syncFromOpenOrders(chainOrders: unknown[] | null, options?: Record<string, unknown>): Promise<SyncResult>;
|
|
258
206
|
/**
|
|
@@ -437,21 +385,42 @@ declare class SyncEngine {
|
|
|
437
385
|
deferred?: undefined;
|
|
438
386
|
}>;
|
|
439
387
|
/**
|
|
440
|
-
*
|
|
441
|
-
*
|
|
388
|
+
* E2 invariant assert: a manager holding grid slots but no price ladder is
|
|
389
|
+
* in the undefined state the grid-price invariant forbids (INV-GRID-004).
|
|
390
|
+
*
|
|
391
|
+
* Reports once per grid generation (latched on the manager, counted in
|
|
392
|
+
* `_genesisInvariantViolations`) and, when the bot wired the structural
|
|
393
|
+
* resync, requests one so the ladder is re-derived. Returns FALSE so the
|
|
394
|
+
* caller ABORTS the sync untouched: with no ladder there is no authority for
|
|
395
|
+
* a slot's price, and the legacy tolerance matcher that used to cover this
|
|
396
|
+
* state is gone — continuing would let an off-grid chain price be adopted
|
|
397
|
+
* into a slot.
|
|
398
|
+
*
|
|
399
|
+
* Non-throwing on purpose: the load-side gates (E1/E3) own the fail-closed
|
|
400
|
+
* decision, this one makes a bypass loud without stranding a live manager.
|
|
401
|
+
* @param {unknown} mgr - OrderManager instance
|
|
402
|
+
* @returns {boolean} true when the grid may be synced (no slots, or a usable
|
|
403
|
+
* ladder is present); false when the sync must not run.
|
|
404
|
+
*/
|
|
405
|
+
_assertGenesisInvariant(mgr: OrderManagerLike): boolean;
|
|
406
|
+
/**
|
|
407
|
+
* High-level dispatcher for the different blockchain synchronization
|
|
408
|
+
* sources. Routes each source to its strategy and returns a uniform result
|
|
409
|
+
* shape.
|
|
442
410
|
*
|
|
443
411
|
* SOURCES AND STRATEGIES:
|
|
444
412
|
* ========================================================================
|
|
445
413
|
* source: 'createOrder'
|
|
446
414
|
* Purpose: Grid order was successfully placed on-chain
|
|
447
|
-
* Data: { gridOrderId, chainOrderId, isPartialPlacement, fee }
|
|
415
|
+
* Data: { gridOrderId, chainOrderId, isPartialPlacement, expectedType, fee, order? }
|
|
448
416
|
* Action:
|
|
449
417
|
* 1. Look up grid order by gridOrderId
|
|
450
418
|
* 2. Assign the returned chainOrderId (so we can find it later)
|
|
451
419
|
* 3. Transition state based on isPartialPlacement:
|
|
452
420
|
* - false → ACTIVE (full order placed)
|
|
453
421
|
* - true → PARTIAL (placed as partial, likely due to insufficient funds)
|
|
454
|
-
* 4.
|
|
422
|
+
* 4. Apply the transition through _applyOrderUpdate (skipAccounting:
|
|
423
|
+
* false), which owns the optimistic chainFree update and the BTS fee
|
|
455
424
|
* Fund Impact: Funds transition from free → locked/committed
|
|
456
425
|
*
|
|
457
426
|
* source: 'cancelOrder'
|
|
@@ -461,9 +430,11 @@ declare class SyncEngine {
|
|
|
461
430
|
* 1. Find grid order by orderId (reverse lookup)
|
|
462
431
|
* 2. Transition to VIRTUAL (order no longer on-chain)
|
|
463
432
|
* 3. Clear orderId so it can be re-used
|
|
464
|
-
* 4.
|
|
433
|
+
* 4. Apply the transition through _applyOrderUpdate
|
|
465
434
|
* Fund Impact: Funds transition from locked → free
|
|
466
|
-
* Note: This is used for direct cancellations (not rotation/consolidation)
|
|
435
|
+
* Note: This is used for direct cancellations (not rotation/consolidation).
|
|
436
|
+
* A cancel whose slot vanished still deducts its fee from the totals
|
|
437
|
+
* via adjustTotalBalance, so the books cannot drift.
|
|
467
438
|
*
|
|
468
439
|
* source: 'readOpenOrders' or 'periodicBlockchainFetch'
|
|
469
440
|
* Purpose: Full snapshot sync of all open orders from blockchain
|
|
@@ -472,38 +443,15 @@ declare class SyncEngine {
|
|
|
472
443
|
* Use Case: Periodic health check or startup initialization
|
|
473
444
|
*
|
|
474
445
|
* FUND TRACKING:
|
|
475
|
-
*
|
|
476
|
-
*
|
|
477
|
-
* This prevents fund leaks where placed
|
|
478
|
-
* orders weren't released.
|
|
479
|
-
*
|
|
480
|
-
* RETURNS: { newOrders, ordersNeedingCorrection }
|
|
481
|
-
* Most callers use ordersNeedingCorrection to flag price corrections needed.
|
|
482
|
-
* Only syncFromOpenOrders() populates ordersNeedingCorrection.
|
|
446
|
+
* The two event sources move funds through _applyOrderUpdate (and, for an
|
|
447
|
+
* unmatched cancel, adjustTotalBalance), so the optimistic chainFree balance
|
|
448
|
+
* cannot be bypassed by an event path. This prevents fund leaks where placed
|
|
449
|
+
* orders weren't deducted or cancelled orders weren't released.
|
|
483
450
|
*
|
|
484
451
|
* @param {Object} chainData - Chain event data
|
|
485
|
-
* @param {string} source - Source identifier ('createOrder', 'cancelOrder', 'readOpenOrders',
|
|
486
|
-
* @returns {Promise<Object>} { newOrders, ordersNeedingCorrection }
|
|
452
|
+
* @param {string} source - Source identifier ('createOrder', 'cancelOrder', 'readOpenOrders', 'periodicBlockchainFetch')
|
|
453
|
+
* @returns {Promise<Object>} { newOrders, filledOrders, updatedOrders, ordersNeedingCorrection }
|
|
487
454
|
*/
|
|
488
|
-
/**
|
|
489
|
-
* E2 invariant assert: a manager holding grid slots but no price ladder is
|
|
490
|
-
* in the undefined state the grid-price invariant forbids (INV-GRID-004).
|
|
491
|
-
*
|
|
492
|
-
* Reports once per grid generation (latched on the manager, counted in
|
|
493
|
-
* `_genesisInvariantViolations`) and, when the bot wired the structural
|
|
494
|
-
* resync, requests one so the ladder is re-derived. Returns FALSE so the
|
|
495
|
-
* caller ABORTS the sync untouched: with no ladder there is no authority for
|
|
496
|
-
* a slot's price, and the legacy tolerance matcher that used to cover this
|
|
497
|
-
* state is gone — continuing would let an off-grid chain price be adopted
|
|
498
|
-
* into a slot.
|
|
499
|
-
*
|
|
500
|
-
* Non-throwing on purpose: the load-side gates (E1/E3) own the fail-closed
|
|
501
|
-
* decision, this one makes a bypass loud without stranding a live manager.
|
|
502
|
-
* @param {unknown} mgr - OrderManager instance
|
|
503
|
-
* @returns {boolean} true when the grid may be synced (no slots, or a usable
|
|
504
|
-
* ladder is present); false when the sync must not run.
|
|
505
|
-
*/
|
|
506
|
-
_assertGenesisInvariant(mgr: OrderManagerLike): boolean;
|
|
507
455
|
synchronizeWithChain(chainData: SyncChainData, source: string): Promise<SyncResult>;
|
|
508
456
|
/**
|
|
509
457
|
* Fetch account balances from blockchain and update optimistic fund totals.
|