dexbot 1.7.0 → 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 +70 -0
- package/README.md +3 -3
- package/analysis/README.md +33 -13
- 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/account_resolver.js +5 -6
- package/dist/analysis/analyze_liquidity.js +15 -4
- package/dist/analysis/bot_key_utils.d.ts +44 -1
- package/dist/analysis/bot_key_utils.js +76 -7
- package/dist/analysis/fills_cache.js +2 -1
- package/dist/analysis/grid_correction_check.d.ts +1 -19
- package/dist/analysis/grid_correction_check.js +12 -30
- package/dist/analysis/liquidity/liquidity_chart_generator.js +190 -20
- package/dist/analysis/liquidity/liquidity_depth_model.d.ts +41 -16
- package/dist/analysis/liquidity/liquidity_depth_model.js +49 -21
- package/dist/analysis/liquidity/liquidity_view.d.ts +15 -0
- package/dist/analysis/liquidity/liquidity_view.js +11 -0
- package/dist/analysis/resolve_bot_accounts.js +7 -6
- package/dist/analysis/trade_profitability.js +2 -1
- package/dist/credential-daemon.js +13 -2
- package/dist/dexbot.js +4 -4
- package/dist/modules/account_bots.d.ts +12 -1
- package/dist/modules/account_bots.js +7 -5
- package/dist/modules/account_orders.d.ts +12 -0
- package/dist/modules/account_orders.js +30 -0
- package/dist/modules/bitshares-native/transport.js +24 -6
- package/dist/modules/bitshares_client.d.ts +24 -6
- package/dist/modules/bitshares_client.js +44 -7
- package/dist/modules/bot_settings.d.ts +2 -0
- package/dist/modules/constants.d.ts +28 -3
- package/dist/modules/constants.js +79 -10
- package/dist/modules/dexbot_class.d.ts +23 -6
- package/dist/modules/dexbot_class.js +44 -0
- package/dist/modules/dexbot_cow_runtime.d.ts +128 -8
- package/dist/modules/dexbot_cow_runtime.js +688 -188
- package/dist/modules/dexbot_fill_runtime.js +124 -35
- package/dist/modules/dexbot_maintenance_runtime.d.ts +1 -1
- package/dist/modules/dexbot_maintenance_runtime.js +259 -79
- package/dist/modules/dexbot_startup_runtime.js +32 -20
- package/dist/modules/dexbot_state_recovery.d.ts +33 -1
- package/dist/modules/dexbot_state_recovery.js +167 -5
- package/dist/modules/node_connect_policy.d.ts +8 -1
- package/dist/modules/node_connect_policy.js +18 -2
- package/dist/modules/node_flap_score.d.ts +87 -0
- package/dist/modules/node_flap_score.js +124 -0
- package/dist/modules/node_health_cache.d.ts +40 -3
- package/dist/modules/node_health_cache.js +66 -20
- package/dist/modules/node_manager.d.ts +101 -19
- package/dist/modules/node_manager.js +255 -65
- package/dist/modules/order/accounting.d.ts +9 -4
- package/dist/modules/order/accounting.js +131 -19
- 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/format.d.ts +24 -10
- package/dist/modules/order/format.js +30 -10
- package/dist/modules/order/grid.d.ts +75 -18
- package/dist/modules/order/grid.js +289 -72
- package/dist/modules/order/grid_reconcile.d.ts +5 -1
- package/dist/modules/order/grid_reconcile.js +333 -210
- package/dist/modules/order/grid_reconcile_internal.d.ts +38 -2
- package/dist/modules/order/grid_reconcile_internal.js +223 -91
- package/dist/modules/order/index.d.ts +18 -5
- package/dist/modules/order/index.js +5 -5
- package/dist/modules/order/lifecycle.d.ts +353 -0
- package/dist/modules/order/lifecycle.js +1109 -0
- package/dist/modules/order/manager.d.ts +277 -20
- package/dist/modules/order/manager.js +680 -64
- package/dist/modules/order/placement_lock.d.ts +102 -0
- package/dist/modules/order/placement_lock.js +222 -0
- package/dist/modules/order/strategy.js +13 -1
- package/dist/modules/order/sync_engine.d.ts +74 -114
- package/dist/modules/order/sync_engine.js +254 -198
- package/dist/modules/order/utils/math.d.ts +29 -4
- package/dist/modules/order/utils/math.js +61 -4
- package/dist/modules/order/utils/order.d.ts +106 -37
- package/dist/modules/order/utils/order.js +256 -81
- package/dist/modules/order/utils/system.d.ts +99 -6
- package/dist/modules/order/utils/system.js +249 -35
- package/dist/modules/order/utils/validate.d.ts +7 -1
- package/dist/modules/order/utils/validate.js +48 -2
- package/dist/modules/outcome.d.ts +54 -0
- package/dist/modules/outcome.js +51 -0
- package/dist/modules/settings_merge.d.ts +4 -0
- package/dist/modules/settings_merge.js +9 -0
- package/dist/modules/timing_policy.d.ts +82 -0
- package/dist/modules/timing_policy.js +244 -0
- package/dist/modules/types.d.ts +149 -22
- package/dist/scripts/analyze-credit.js +54 -17
- package/dist/scripts/analyze-orders.d.ts +4 -2
- package/dist/scripts/analyze-orders.js +113 -34
- package/dist/scripts/chart_targets.js +11 -15
- package/dist/scripts/test-credit-renewal.js +12 -5
- package/docs/COW_INVARIANTS.md +71 -8
- package/docs/DEXBOT_COMPARISON.md +6 -6
- package/docs/EVOLUTION.md +10 -8
- package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
- package/docs/GRID_PRICE_INVARIANT.md +1 -1
- package/docs/GRID_RECONCILE.md +18 -13
- package/docs/LOGGING.md +25 -1
- package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +183 -26
- package/docs/README.md +23 -2
- package/docs/WORKFLOW.md +9 -3
- package/docs/architecture.md +68 -13
- package/docs/developer_guide.md +25 -8
- package/modules/README.md +6 -0
- package/package.json +3 -3
- package/scripts/README.md +16 -0
- package/scripts/pdev.sh +14 -1
- package/scripts/pmain.sh +23 -8
- package/scripts/ptest.sh +7 -0
- package/tests/README.md +30 -1
|
@@ -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';
|
|
@@ -18,6 +18,10 @@ import Logger from './logger.js';
|
|
|
18
18
|
import Accountant from './accounting.js';
|
|
19
19
|
import StrategyEngine from './strategy.js';
|
|
20
20
|
import SyncEngine from './sync_engine.js';
|
|
21
|
+
import { LifecycleRegistry } from './lifecycle.js';
|
|
22
|
+
import type { LifecycleView } from './lifecycle.js';
|
|
23
|
+
import PlacementLock from './placement_lock.js';
|
|
24
|
+
import type { PlacementLease } from './placement_lock.js';
|
|
21
25
|
import type { GridGenesis } from './utils/math.js';
|
|
22
26
|
import type { OrderManagerLike, ManagedOrder, GridConfig, AssetPair, AccountTotals, ManagerFunds, PendingPriceCorrection, ProcessedFillStoreLike, PendingBroadcast, ManagerLock, IllegalStateSignal, AccountingFailureSignal, BotMetrics, AccountOrdersLike, CowAction, RebalanceResult, ProjectedFunds, SyncResult, FillHistorySyncResult, FundDriftCheck, ChainFundsSnapshot, OrderType, OrderState, UnknownRecord } from '../types.js';
|
|
23
27
|
/**
|
|
@@ -107,6 +111,10 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
107
111
|
sync: SyncEngine;
|
|
108
112
|
_rebalanceState: string;
|
|
109
113
|
_bootstrapping: number;
|
|
114
|
+
_structuralRebuildDepth: number;
|
|
115
|
+
_structuralRebuildStartedAt: number;
|
|
116
|
+
_structuralRebuildDeferWarnAt: number;
|
|
117
|
+
_structuralRebuildReason: string | null;
|
|
110
118
|
_endOfBootstrapValidationDone: boolean;
|
|
111
119
|
_broadcastingFlag: number;
|
|
112
120
|
_broadcastingStartedAt: number;
|
|
@@ -157,6 +165,13 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
157
165
|
private _getOrderIdIndex;
|
|
158
166
|
initialSpreadCount: number;
|
|
159
167
|
currentSpreadCount: number;
|
|
168
|
+
/**
|
|
169
|
+
* True once a grid has been loaded/created and the spread metric measured.
|
|
170
|
+
* Before that both counters are 0, which is indistinguishable from a
|
|
171
|
+
* genuinely empty band — telemetry must print "unknown" instead of "0"
|
|
172
|
+
* (the restore line otherwise claims the spread band is gone).
|
|
173
|
+
*/
|
|
174
|
+
_spreadCountKnown: boolean;
|
|
160
175
|
outOfSpread: number;
|
|
161
176
|
assets: AssetPair;
|
|
162
177
|
accountId: string | null;
|
|
@@ -172,6 +187,7 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
172
187
|
processedFillStore: ProcessedFillStoreLike | null;
|
|
173
188
|
_syncLock: ManagerLock;
|
|
174
189
|
_fillProcessingLock: ManagerLock;
|
|
190
|
+
_placementLock: PlacementLock;
|
|
175
191
|
_divergenceLock: ManagerLock;
|
|
176
192
|
_gridLock: ManagerLock;
|
|
177
193
|
_fundLock: ManagerLock;
|
|
@@ -179,6 +195,7 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
179
195
|
_pauseFundRecalc: number;
|
|
180
196
|
_pauseFundRecalcWatchdog: ReturnType<typeof setTimeout> | null;
|
|
181
197
|
_fillBatchInFlight: number;
|
|
198
|
+
_gridUpdateBlockedCycles: number;
|
|
182
199
|
_pauseRecalcLogging: boolean;
|
|
183
200
|
_pauseRecalcLoggingWatchdog: ReturnType<typeof setTimeout> | null;
|
|
184
201
|
_throwOnIllegalState: boolean;
|
|
@@ -187,11 +204,22 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
187
204
|
_syncGeneration: number;
|
|
188
205
|
_gridVersion: number;
|
|
189
206
|
_gridPersistenceSuspendedReason: string | null;
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
207
|
+
/**
|
|
208
|
+
* Single owner of "does this order exist on chain, and how sure are we".
|
|
209
|
+
* The legacy maps below are live views onto it — see modules/order/lifecycle.ts.
|
|
210
|
+
*/
|
|
211
|
+
readonly _lifecycle: LifecycleRegistry;
|
|
212
|
+
/** Live view onto `_lifecycle`. Assigned as a whole by the COW commit path. */
|
|
213
|
+
get _committedOrderIds(): Set<string>;
|
|
214
|
+
set _committedOrderIds(value: Iterable<string>);
|
|
215
|
+
get _committedOrderIdsBuiltAt(): number;
|
|
216
|
+
set _committedOrderIdsBuiltAt(value: number);
|
|
217
|
+
get _orderIdAssignedAt(): Map<string, number>;
|
|
218
|
+
set _orderIdAssignedAt(value: Map<string, number>);
|
|
219
|
+
get _placedAt(): Map<string, number>;
|
|
220
|
+
set _placedAt(value: Map<string, number>);
|
|
221
|
+
get _pendingBroadcasts(): Map<string, PendingBroadcast>;
|
|
222
|
+
set _pendingBroadcasts(value: Map<string, PendingBroadcast>);
|
|
195
223
|
_gapSlots: number;
|
|
196
224
|
_genesis: GridGenesis | null;
|
|
197
225
|
_missingGenesis: unknown;
|
|
@@ -213,6 +241,20 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
213
241
|
side: string;
|
|
214
242
|
ts: number;
|
|
215
243
|
}[];
|
|
244
|
+
/**
|
|
245
|
+
* Chain-size resizes already absorbed by sync pass 1 (partial fill seen in
|
|
246
|
+
* an open-orders snapshot). The fill-history batch that follows the same
|
|
247
|
+
* fill must not subtract / credit the same amount a second time.
|
|
248
|
+
* Live view onto `_lifecycle`; key = chain orderId.
|
|
249
|
+
*/
|
|
250
|
+
get _chainSizeAppliedFills(): Map<string, {
|
|
251
|
+
filledInt: number;
|
|
252
|
+
at: number;
|
|
253
|
+
}>;
|
|
254
|
+
set _chainSizeAppliedFills(value: Map<string, {
|
|
255
|
+
filledInt: number;
|
|
256
|
+
at: number;
|
|
257
|
+
}>);
|
|
216
258
|
_recentFillKeysSnapshot: Record<string, number> | null;
|
|
217
259
|
_lastFilledBuyPrice: number | null;
|
|
218
260
|
_lastFilledSellPrice: number | null;
|
|
@@ -296,16 +338,180 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
296
338
|
* @returns {boolean}
|
|
297
339
|
*/
|
|
298
340
|
isBootstrapping(): boolean;
|
|
341
|
+
/**
|
|
342
|
+
* Mark a structural grid rebuild (trigger-file resync, startup regenerate)
|
|
343
|
+
* as in progress. While active, fill-driven COW rebalances DEFER: they would
|
|
344
|
+
* otherwise re-plan against the freshly rebuilt, order-id-less master and
|
|
345
|
+
* emit a create-only batch while the reconcile re-prices the live orders
|
|
346
|
+
* onto the same levels (duplicate-price orphan incident 2026-11-03).
|
|
347
|
+
* This is deliberately narrower than isBootstrapping(): the constructor's
|
|
348
|
+
* initial bootstrap is not a rebuild and fills may still rebalance there.
|
|
349
|
+
* @param {string} reason - Diagnostic label (e.g. 'trigger-file resync')
|
|
350
|
+
*/
|
|
351
|
+
beginStructuralRebuild(reason?: string): void;
|
|
352
|
+
/** End a structural rebuild region (balanced with beginStructuralRebuild). */
|
|
353
|
+
endStructuralRebuild(): void;
|
|
354
|
+
/** Whether a structural rebuild currently owns placement. */
|
|
355
|
+
isStructuralRebuildInProgress(): boolean;
|
|
356
|
+
/** Diagnostic label of the active structural rebuild, or null. */
|
|
357
|
+
structuralRebuildReason(): string | null;
|
|
358
|
+
/**
|
|
359
|
+
* Run a chain-mutating placement path inside the exclusive region.
|
|
360
|
+
*
|
|
361
|
+
* SINGLE SOURCE OF TRUTH: every caller that can broadcast (COW, startup
|
|
362
|
+
* reconcile Phase 2, correction drain, dust/residual cancels, pool swaps)
|
|
363
|
+
* must go through this helper. It is NOT reentrant: a nested caller must not
|
|
364
|
+
* call it again — the COW body hands its lease to the pre-batch drain
|
|
365
|
+
* (`correctAllPriceMismatches({ placementLease })`), which verifies it with
|
|
366
|
+
* `isPlacementLeaseCurrent()` before mutating.
|
|
367
|
+
*
|
|
368
|
+
* Lock hierarchy: acquire placement BEFORE `_gridLock`; never acquire it
|
|
369
|
+
* while holding `_gridLock` (Level 0.5 — see the constructor's canonical
|
|
370
|
+
* lock-hierarchy block in this file).
|
|
371
|
+
*
|
|
372
|
+
* @returns `null` when the region could not be acquired; the caller must
|
|
373
|
+
* defer/abort its broadcast.
|
|
374
|
+
*/
|
|
375
|
+
withPlacement<T>(kind: string, fn: (lease: PlacementLease) => Promise<T>, options?: {
|
|
376
|
+
timeoutMs?: number;
|
|
377
|
+
isShuttingDown?: () => boolean;
|
|
378
|
+
}): Promise<T | null>;
|
|
379
|
+
/**
|
|
380
|
+
* Acquire the exclusive placement region (see placement_lock.ts).
|
|
381
|
+
* Callers MUST release the lease in a finally block before returning.
|
|
382
|
+
* @param {string} kind - Owner label for diagnostics (e.g. 'cow-broadcast')
|
|
383
|
+
* @param {Object} [options] - Wait bound + shutdown probe
|
|
384
|
+
* @returns {Promise<Object|null>} Lease, or null on timeout/shutdown
|
|
385
|
+
*/
|
|
386
|
+
acquirePlacement(kind: string, options?: {
|
|
387
|
+
timeoutMs?: number;
|
|
388
|
+
isShuttingDown?: () => boolean;
|
|
389
|
+
}): Promise<PlacementLease | null>;
|
|
390
|
+
/**
|
|
391
|
+
* Non-blocking placement acquire for paths that must defer rather than queue.
|
|
392
|
+
* @param {string} kind - Owner label
|
|
393
|
+
* @returns {Object|null} Lease when free, otherwise null
|
|
394
|
+
*/
|
|
395
|
+
tryAcquirePlacement(kind: string): PlacementLease | null;
|
|
396
|
+
/** Whether another placement path currently holds the exclusive region. */
|
|
397
|
+
isPlacementActive(): boolean;
|
|
398
|
+
/**
|
|
399
|
+
* Whether the given lease is STILL the one that owns the region.
|
|
400
|
+
*
|
|
401
|
+
* The authoritative nesting predicate: a nested caller (the COW pre-batch
|
|
402
|
+
* drain) must verify its inherited lease with this before mutating.
|
|
403
|
+
* `isPlacementActive()` cannot answer it — it is true for any holder, so a
|
|
404
|
+
* lease invalidated by `forceRelease()` would still read as "live".
|
|
405
|
+
* @param {Object|null|undefined} lease - Lease to verify
|
|
406
|
+
* @returns {boolean}
|
|
407
|
+
*/
|
|
408
|
+
isPlacementLeaseCurrent(lease: PlacementLease | null | undefined): boolean;
|
|
409
|
+
/** Owner label of the active placement region, or null. */
|
|
410
|
+
placementKind(): string | null;
|
|
411
|
+
/** Milliseconds the current placement region has been held (0 when free). */
|
|
412
|
+
placementHeldForMs(): number;
|
|
413
|
+
/**
|
|
414
|
+
* True when the given staleness reason means the master grid was
|
|
415
|
+
* structurally rebuilt while a plan was in flight. Such a plan must NOT be
|
|
416
|
+
* re-planned from the fresh (order-id-less) master: a create-only re-plan
|
|
417
|
+
* duplicates every live chain order the reconcile is about to update.
|
|
418
|
+
*/
|
|
419
|
+
isStructuralRebuildStale(reason: unknown): boolean;
|
|
299
420
|
/**
|
|
300
421
|
* Whether a broadcast is currently active (no side-effects).
|
|
301
422
|
* @returns {boolean}
|
|
302
423
|
*/
|
|
303
424
|
isBroadcastingActive(): boolean;
|
|
425
|
+
/**
|
|
426
|
+
* Record that sync pass 1 already applied a chain-size reduction (a
|
|
427
|
+
* partial fill) for this order. The following fill-history batch checks it
|
|
428
|
+
* to stay idempotent: subtracting/crediting the same fill again shrinks the
|
|
429
|
+
* order twice and over-credits free balance (2026-11-03 log: 3.6604 ->
|
|
430
|
+
* 3.3046 by pass 1, then 3.3046 -> 2.9488 by the fill batch).
|
|
431
|
+
*
|
|
432
|
+
* Markers ACCUMULATE: two pass-1 detections before the fill queue drains
|
|
433
|
+
* (or one aggregated fill-history entry covering both) must add up, not
|
|
434
|
+
* overwrite — an overwritten marker makes the batch total unmatchable and
|
|
435
|
+
* re-opens the double-shrink. The map is mirrored into the persisted grid
|
|
436
|
+
* snapshot (debugInputs) so a restart between pass 1 and fill processing
|
|
437
|
+
* does not lose the evidence.
|
|
438
|
+
* @param {string} orderId - Chain order id
|
|
439
|
+
* @param {number} filledInt - Base-amount delta in chain integer units
|
|
440
|
+
* @returns {void}
|
|
441
|
+
*/
|
|
442
|
+
noteChainSizeAppliedFill(orderId: string, filledInt: number, maxAgeMs?: number): void;
|
|
443
|
+
/**
|
|
444
|
+
* Consume a pass-1 chain-size marker for a fill without requiring an exact
|
|
445
|
+
* total match. Returns the number of chain-size units this fill may treat
|
|
446
|
+
* as ALREADY reflected in `rawOnChain` (0 when there is no marker).
|
|
447
|
+
*
|
|
448
|
+
* Partial consumption is the split-batch case: pass 1 absorbed A+B, the
|
|
449
|
+
* fill queue drains A first (marker keeps B), then B. The old all-or-nothing
|
|
450
|
+
* match rejected both and double-shrunk the slot twice.
|
|
451
|
+
* @param {string} orderId - Chain order id
|
|
452
|
+
* @param {number} filledInt - Base-amount delta in chain integer units
|
|
453
|
+
* @param {number} [maxAgeMs] - Marker freshness bound
|
|
454
|
+
* @returns {number} Applied (already-in-snapshot) amount, 0..filledInt
|
|
455
|
+
*/
|
|
456
|
+
consumeChainSizeAppliedFillAmount(orderId: string, filledInt: number, maxAgeMs?: number): number;
|
|
457
|
+
/**
|
|
458
|
+
* Merge persisted pass-1 markers into the in-memory set (recovery reload).
|
|
459
|
+
* Live markers win on conflict: they may already be partially consumed,
|
|
460
|
+
* and replacing them with the older persisted total would double-count.
|
|
461
|
+
* Entries are sanitized and the clock is freshened (see below).
|
|
462
|
+
* @param {unknown} payload - `{ [orderId]: { filledInt, at } }`
|
|
463
|
+
* @returns {void}
|
|
464
|
+
*/
|
|
465
|
+
restoreChainSizeAppliedFills(payload: unknown): void;
|
|
466
|
+
/** Snapshot the live pass-1 markers for persistence (empty when none). */
|
|
467
|
+
snapshotChainSizeAppliedFills(): Record<string, {
|
|
468
|
+
filledInt: number;
|
|
469
|
+
at: number;
|
|
470
|
+
}>;
|
|
471
|
+
/**
|
|
472
|
+
* Wake the tasks that deferred on isPlacementActive() when the region ends.
|
|
473
|
+
* The broadcast-region-end listener reschedules a deferred rebalance and
|
|
474
|
+
* drains queued fills; without this a fill deferred because a correction
|
|
475
|
+
* drain/COW held placement would only retry on the next unrelated event.
|
|
476
|
+
* Skipped while a broadcast region is still active (stopBroadcasting will
|
|
477
|
+
* fire the same listeners when it ends).
|
|
478
|
+
* @returns {void}
|
|
479
|
+
*/
|
|
480
|
+
_handlePlacementRegionEnd(): void;
|
|
304
481
|
/**
|
|
305
482
|
* @param {boolean} value
|
|
306
483
|
* @returns {void}
|
|
307
484
|
*/
|
|
308
485
|
setShuttingDown(value: boolean): void;
|
|
486
|
+
/**
|
|
487
|
+
* Auto-clears a stale placement region after
|
|
488
|
+
* TIMING.PLACEMENT_STALE_CLEAR_MS so a hung chain call / missed release
|
|
489
|
+
* cannot park fills and rebalances forever. The holder's lease becomes a
|
|
490
|
+
* no-op on release (token guard), so a late finally cannot release a
|
|
491
|
+
* successor.
|
|
492
|
+
*
|
|
493
|
+
* TWO GUARDS, ONE TEARDOWN:
|
|
494
|
+
* - A bot-level batch/recovery still in flight and YOUNGER than the bound is
|
|
495
|
+
* evidence of progress, so the region is not torn down (a long create-group
|
|
496
|
+
* reconcile must survive). Only a batch older than the same bound is
|
|
497
|
+
* treated as part of the hung region.
|
|
498
|
+
* - When the teardown does happen it also clears a broadcast refcount that
|
|
499
|
+
* is itself past its bound, atomically. A refcount raised by a placement
|
|
500
|
+
* holder belongs to the same region (the COW body and the reconcile call
|
|
501
|
+
* startBroadcasting() INSIDE it), so clearing both in one place stops the
|
|
502
|
+
* maintenance tick from tearing down placement first and the refcount
|
|
503
|
+
* second (two authorities, one hung region). A refcount raised OUTSIDE any
|
|
504
|
+
* region (the spread-correction pre-broadcast hold in `order/grid.ts`) is
|
|
505
|
+
* not this region's and is left to `_clearStaleBroadcastFlag`, which still
|
|
506
|
+
* refuses to act on its own while a placement lease is held.
|
|
507
|
+
* @param {number} [maxAgeMs] - Override for tests
|
|
508
|
+
* @param {Object} [options] - `batchInFlightMs`: age of the LAST raised
|
|
509
|
+
* bot-level pipeline counter (0/undefined when none).
|
|
510
|
+
* @returns {boolean} true when a stale region was force-released
|
|
511
|
+
*/
|
|
512
|
+
_clearStalePlacementRegion(maxAgeMs?: number, options?: {
|
|
513
|
+
batchInFlightMs?: number;
|
|
514
|
+
}): boolean;
|
|
309
515
|
/**
|
|
310
516
|
* Auto-clears a stale broadcast flag after 120s so a hung
|
|
311
517
|
* broadcast cannot permanently block rebalancing.
|
|
@@ -497,7 +703,7 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
497
703
|
*/
|
|
498
704
|
resumeRecalcLogging(): void;
|
|
499
705
|
/**
|
|
500
|
-
* @param {Array<import('
|
|
706
|
+
* @param {Array<import('../types.js').Order>} orders
|
|
501
707
|
* @param {Object} info
|
|
502
708
|
* @returns {Promise<any>}
|
|
503
709
|
*/
|
|
@@ -547,6 +753,32 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
547
753
|
*/
|
|
548
754
|
getActiveShadowLockCount(): number;
|
|
549
755
|
_cleanExpiredLocks(): void;
|
|
756
|
+
/**
|
|
757
|
+
* The single answer to "does this order exist on chain, and how sure are we".
|
|
758
|
+
*
|
|
759
|
+
* Every consumer that used to infer this from one of the legacy maps must
|
|
760
|
+
* read it here instead — that is the whole point of the lifecycle registry:
|
|
761
|
+
* four sites consulting four different structures is how the engine ended up
|
|
762
|
+
* with four different answers for the same order.
|
|
763
|
+
*
|
|
764
|
+
* A `createUncertain` slot flag (persisted across restarts) is folded into
|
|
765
|
+
* `phase === 'unknown'` here, so no caller has to remember to check it.
|
|
766
|
+
*
|
|
767
|
+
* @param identity - Slot id, chain order id, or pending-broadcast fingerprint
|
|
768
|
+
* @returns {LifecycleView} Unified read surface (never null)
|
|
769
|
+
*/
|
|
770
|
+
getLifecycle(identity: string | null | undefined): LifecycleView;
|
|
771
|
+
/**
|
|
772
|
+
* Lifecycle view for a slot, folding in the slot's own persisted flags.
|
|
773
|
+
* Prefer this over `getLifecycle(slotId)` wherever a slot object is at hand.
|
|
774
|
+
* @param slot - Grid slot (ManagedOrder) or null
|
|
775
|
+
* @returns {LifecycleView}
|
|
776
|
+
*/
|
|
777
|
+
getSlotLifecycle(slot: {
|
|
778
|
+
id?: string;
|
|
779
|
+
orderId?: string | null;
|
|
780
|
+
createUncertain?: boolean;
|
|
781
|
+
} | null | undefined): LifecycleView;
|
|
550
782
|
_normalizeOrderUpdateOptions(options?: UnknownRecord): {
|
|
551
783
|
skipAccounting: boolean;
|
|
552
784
|
fee: number;
|
|
@@ -557,10 +789,38 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
557
789
|
};
|
|
558
790
|
_updateOrder(order: ManagedOrder, context?: string, options?: UnknownRecord): Promise<boolean>;
|
|
559
791
|
_applyOrderUpdate(order: ManagedOrder, context?: string, options?: UnknownRecord): Promise<boolean>;
|
|
792
|
+
/**
|
|
793
|
+
* Project one order mutation into the lifecycle registry.
|
|
794
|
+
*
|
|
795
|
+
* This is the single write funnel for chain existence: every mutation goes
|
|
796
|
+
* through `_applyOrderUpdate`, so no call site has to remember which of the
|
|
797
|
+
* seven legacy structures to touch. A slot is the record's identity, so a
|
|
798
|
+
* chain-id change (rotation / re-place) updates the same record instead of
|
|
799
|
+
* starting a parallel one.
|
|
800
|
+
*
|
|
801
|
+
* @param previous - Slot before the mutation (absent on create)
|
|
802
|
+
* @param next - Slot after the mutation
|
|
803
|
+
* @param context - Mutation context label
|
|
804
|
+
* @returns {void}
|
|
805
|
+
*/
|
|
806
|
+
_syncLifecycleFromMutation(previous: ManagedOrder | null | undefined, next: ManagedOrder, context: string): void;
|
|
807
|
+
/**
|
|
808
|
+
* Abandon an unresolved pending CREATE (TTL sweep / give-up).
|
|
809
|
+
*
|
|
810
|
+
* Distinct from `_pendingBroadcasts.delete()`: dropping an entry because the
|
|
811
|
+
* create RESOLVED leaves the slot free, while dropping it because we ran out
|
|
812
|
+
* of patience means the order may still be live. Collapsing both into one
|
|
813
|
+
* delete is how a lost receipt turned into a clean hole that got re-CREATEd.
|
|
814
|
+
*
|
|
815
|
+
* @param fingerprint - Pending-broadcast fingerprint being abandoned
|
|
816
|
+
* @param entry - The abandoned entry (carries the slot id)
|
|
817
|
+
* @returns {void}
|
|
818
|
+
*/
|
|
819
|
+
_expirePendingBroadcast(fingerprint: string, entry: PendingBroadcast | null | undefined): void;
|
|
560
820
|
_peekWorkingGrid(): WorkingGrid | null;
|
|
561
821
|
_syncWorkingGridFromMasterMutation(orderId: string, context: string): void;
|
|
562
822
|
/**
|
|
563
|
-
* @param {Array<import('
|
|
823
|
+
* @param {Array<import('../types.js').Order>} updates - Order updates to apply
|
|
564
824
|
* @param {string} [context] - Update context label
|
|
565
825
|
* @param {unknown} [options]
|
|
566
826
|
* @returns {Promise<boolean>}
|
|
@@ -617,14 +877,14 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
617
877
|
reason: string;
|
|
618
878
|
}>;
|
|
619
879
|
/**
|
|
620
|
-
* @param {Array<import('
|
|
880
|
+
* @param {Array<import('../types.js').Order>} orders - Filled orders
|
|
621
881
|
* @param {Set<string>} [excl] - Order IDs to exclude
|
|
622
882
|
* @param {Object} [options]
|
|
623
883
|
* @returns {Promise<any>}
|
|
624
884
|
*/
|
|
625
885
|
processFilledOrders(orders: COWFillLike[], excl: Set<string>, options?: UnknownRecord): Promise<RebalanceResult>;
|
|
626
886
|
/**
|
|
627
|
-
* @returns {Array<import('
|
|
887
|
+
* @returns {Array<import('../types.js').Order>}
|
|
628
888
|
*/
|
|
629
889
|
getInitialOrdersToActivate(): ManagedOrder[];
|
|
630
890
|
/**
|
|
@@ -667,19 +927,16 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
667
927
|
* Also used when the boundary is (re)anchored outside the fill path (grid
|
|
668
928
|
* reset / recenter / rejected-snapshot rebuild): those records belong to
|
|
669
929
|
* the previous generation, and applying their relative deltas onto a fresh
|
|
670
|
-
* 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.
|
|
671
934
|
*
|
|
672
935
|
* Marks the grid dirty so the cleared array reaches disk even on paths
|
|
673
936
|
* that do not otherwise persist.
|
|
674
937
|
*
|
|
675
938
|
* @param {string} reason - Log/debug label for the drop
|
|
676
|
-
|
|
677
|
-
/**
|
|
678
|
-
* Drop ALL owed fill-crawl records.
|
|
679
|
-
*
|
|
680
|
-
* This is the explicit allowed-loss path: the grid generation is being
|
|
681
|
-
* discarded (rebuild, rejected snapshot, restart replay), so the relative
|
|
682
|
-
* deltas no longer have a geometry to apply onto.
|
|
939
|
+
* @param {string} detail - Extra context appended to the drop log line
|
|
683
940
|
*/
|
|
684
941
|
_clearPendingFillCrawls(reason?: string, detail?: string): void;
|
|
685
942
|
/**
|
|
@@ -855,7 +1112,7 @@ declare class OrderManager implements OrderManagerLike {
|
|
|
855
1112
|
*/
|
|
856
1113
|
clearStalePipelineOperations(): boolean;
|
|
857
1114
|
/**
|
|
858
|
-
* @param {Map<string, import('
|
|
1115
|
+
* @param {Map<string, import('../types.js').Order>} targetGrid
|
|
859
1116
|
* @param {number} targetBoundary
|
|
860
1117
|
* @returns {Object}
|
|
861
1118
|
*/
|