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
@@ -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 (12 methods) + module-level helpers
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: Add missing chain orders (unknown chain → grid)
45
+ * Pass 2: Bind unmatched chain orders to their genesis-ladder slot (chain → grid)
46
46
  *
47
- * FILL PROCESSING (5 methods)
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 a fill (internal)
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. syncFromFillHistory(fill) - Process single fill event synchronously
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
- * 9. syncFromFillHistoryBatch(fills) - Process multiple fill events in batch
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
- * 10. _assertGenesisInvariant(mgr) - Fail-closed check that a snapshot has a genesis ladder (internal)
71
+ * 11. _assertGenesisInvariant(mgr) - Fail-closed check that a snapshot has a genesis ladder (internal)
68
72
  *
69
- * 11. synchronizeWithChain(chainData, source) - Full sync (fetch + sync) (async)
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
- * 12. fetchAccountBalancesAndSetTotals() - Fetch account totals (async)
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
- * 13. initializeAssets() - Initialize asset metadata (async)
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 to grid order
106
- * - Create new grid order for unexpected chain order
107
- * - Mark as ACTIVE with blockchain orderId
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 orders snapshot.
191
- * This is the MAIN SYNCHRONIZATION MECHANISM that corrects the grid state when
192
- * the blockchain state diverges from our local expectations.
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<Object>} Result with filledOrders, updatedOrders, ordersNeedingCorrection
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
- * High-level dispatcher for different blockchain synchronization sources.
441
- * Routes to the appropriate sync strategy based on the data source.
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. Update optimistic chainFree balance (deduct fees if BTS pair)
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. Update optimistic chainFree balance (add funds back as free)
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
- * Both 'createOrder' and 'cancelOrder' call updateOptimisticFreeBalance() to
476
- * keep the optimistic chainFree balance in sync with actual on-chain state.
477
- * This prevents fund leaks where placed orders weren't deducted or cancelled
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', etc.)
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.