dexbot 1.6.14 → 1.6.16

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 (134) hide show
  1. package/CHANGELOG.md +60 -4
  2. package/README.md +4 -4
  3. package/analysis/README.md +6 -6
  4. package/analysis/tradingview/README.md +2 -1
  5. package/claw/README.md +7 -7
  6. package/claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md +3 -2
  7. package/claw/modules/chain_queries.ts +3 -3
  8. package/claw/package.json +1 -1
  9. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  10. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  11. package/dist/analysis/ama_fitting/fetch_lp_candles.js +8 -1
  12. package/dist/analysis/ama_fitting/optimizer_high_resolution.d.ts +50 -1
  13. package/dist/analysis/ama_fitting/optimizer_high_resolution.js +33 -7
  14. package/dist/analysis/bot_fitting/backtest_bot_fitting.d.ts +8 -6
  15. package/dist/analysis/bot_fitting/backtest_bot_fitting.js +8 -10
  16. package/dist/analysis/bot_key_utils.js +9 -7
  17. package/dist/analysis/chart_utils.d.ts +9 -2
  18. package/dist/analysis/chart_utils.js +51 -1
  19. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.d.ts +2 -1
  20. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +99 -11
  21. package/dist/analysis/trend_detection/dynamic_weight_chart_generator.js +57 -4
  22. package/dist/analysis/trend_detection/kalman_chart_generator.js +1 -0
  23. package/dist/analysis/trend_detection/regime_chart_generator.js +1 -1
  24. package/dist/analysis/trend_detection/volatility_chart_generator.js +1 -0
  25. package/dist/dexbot.js +112 -141
  26. package/dist/market_adapter/core/strategies/dynamic_weight_series.js +26 -11
  27. package/dist/market_adapter/inputs/fetch_book_data.js +36 -12
  28. package/dist/market_adapter/inputs/fetch_lp_data.d.ts +6 -0
  29. package/dist/market_adapter/inputs/fetch_lp_data.js +65 -19
  30. package/dist/market_adapter/inputs/kibana_feed_source.js +45 -12
  31. package/dist/market_adapter/inputs/window_cache.d.ts +14 -1
  32. package/dist/market_adapter/inputs/window_cache.js +53 -17
  33. package/dist/market_adapter/lp_chart_core.js +1 -0
  34. package/dist/market_adapter/utils/chain.js +4 -3
  35. package/dist/market_adapter/utils/pair_orientation.d.ts +60 -0
  36. package/dist/market_adapter/utils/pair_orientation.js +142 -0
  37. package/dist/modules/account_bots.d.ts +40 -3
  38. package/dist/modules/account_bots.js +80 -37
  39. package/dist/modules/account_orders.d.ts +4 -1
  40. package/dist/modules/account_orders.js +4 -1
  41. package/dist/modules/bitshares-native/resolvers.js +3 -3
  42. package/dist/modules/bitshares-native/subscriptions.js +1 -1
  43. package/dist/modules/bitshares_client.d.ts +12 -10
  44. package/dist/modules/bitshares_client.js +12 -10
  45. package/dist/modules/bot_defaults.d.ts +13 -2
  46. package/dist/modules/bot_defaults.js +31 -2
  47. package/dist/modules/bot_settings.js +6 -3
  48. package/dist/modules/chain_keys.d.ts +5 -1
  49. package/dist/modules/chain_keys.js +5 -1
  50. package/dist/modules/chain_orders.d.ts +6 -2
  51. package/dist/modules/chain_orders.js +6 -2
  52. package/dist/modules/constants.d.ts +11 -0
  53. package/dist/modules/constants.js +31 -1
  54. package/dist/modules/credit_runtime.d.ts +35 -5
  55. package/dist/modules/credit_runtime.js +219 -38
  56. package/dist/modules/dexbot_class.d.ts +22 -2
  57. package/dist/modules/dexbot_class.js +61 -21
  58. package/dist/modules/dexbot_cow_runtime.js +19 -18
  59. package/dist/modules/dexbot_fill_runtime.d.ts +1 -1
  60. package/dist/modules/dexbot_fill_runtime.js +4 -7
  61. package/dist/modules/dexbot_maintenance_runtime.d.ts +7 -2
  62. package/dist/modules/dexbot_maintenance_runtime.js +52 -7
  63. package/dist/modules/dexbot_startup_runtime.js +3 -2
  64. package/dist/modules/dexbot_state_recovery.js +1 -1
  65. package/dist/modules/graceful_shutdown.d.ts +6 -2
  66. package/dist/modules/graceful_shutdown.js +6 -2
  67. package/dist/modules/launcher/bot_supervisor.js +4 -0
  68. package/dist/modules/launcher/launch_modes.js +6 -3
  69. package/dist/modules/launcher/monolithic_runtime.d.ts +39 -1
  70. package/dist/modules/launcher/monolithic_runtime.js +60 -1
  71. package/dist/modules/launcher/runtime_mode.d.ts +79 -0
  72. package/dist/modules/launcher/runtime_mode.js +223 -0
  73. package/dist/modules/market_adapter_whitelist.d.ts +8 -0
  74. package/dist/modules/market_adapter_whitelist.js +8 -0
  75. package/dist/modules/order/accounting.d.ts +15 -1
  76. package/dist/modules/order/accounting.js +15 -1
  77. package/dist/modules/order/async_lock.d.ts +9 -3
  78. package/dist/modules/order/async_lock.js +9 -3
  79. package/dist/modules/order/export.d.ts +0 -5
  80. package/dist/modules/order/export.js +2 -7
  81. package/dist/modules/order/format.d.ts +6 -4
  82. package/dist/modules/order/format.js +6 -4
  83. package/dist/modules/order/grid.d.ts +147 -19
  84. package/dist/modules/order/grid.js +321 -68
  85. package/dist/modules/order/grid_reconcile.js +4 -3
  86. package/dist/modules/order/grid_reconcile_internal.js +13 -18
  87. package/dist/modules/order/index.d.ts +4 -2
  88. package/dist/modules/order/index.js +1 -1
  89. package/dist/modules/order/logger_state.d.ts +1 -1
  90. package/dist/modules/order/logger_state.js +1 -1
  91. package/dist/modules/order/manager.d.ts +1 -0
  92. package/dist/modules/order/manager.js +5 -14
  93. package/dist/modules/order/sync_engine.d.ts +26 -11
  94. package/dist/modules/order/sync_engine.js +44 -20
  95. package/dist/modules/order/utils/math.d.ts +157 -47
  96. package/dist/modules/order/utils/math.js +236 -78
  97. package/dist/modules/order/utils/order.d.ts +64 -20
  98. package/dist/modules/order/utils/order.js +80 -24
  99. package/dist/modules/order/utils/system.d.ts +41 -11
  100. package/dist/modules/order/utils/system.js +43 -13
  101. package/dist/modules/order/utils/validate.d.ts +6 -3
  102. package/dist/modules/order/utils/validate.js +53 -60
  103. package/dist/modules/types.d.ts +7 -0
  104. package/dist/modules/utils/asset_symbols.d.ts +5 -5
  105. package/dist/modules/utils/asset_symbols.js +5 -5
  106. package/dist/modules/utils/errors.d.ts +2 -1
  107. package/dist/modules/utils/errors.js +2 -1
  108. package/dist/scripts/analyze-credit.js +44 -27
  109. package/dist/scripts/diagnose-pool-history.js +35 -30
  110. package/dist/scripts/pnl.js +1 -1
  111. package/dist/scripts/rich_list.d.ts +50 -0
  112. package/dist/scripts/rich_list.js +469 -0
  113. package/dist/scripts/run-tests.js +80 -4
  114. package/dist/unlock.d.ts +2 -1
  115. package/dist/unlock.js +53 -21
  116. package/docs/BITSHARES_ONBOARDING.md +7 -0
  117. package/docs/COW_INVARIANTS.md +7 -1
  118. package/docs/DEXBOT_COMPARISON.md +6 -6
  119. package/docs/EVOLUTION.md +11 -9
  120. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +3 -3
  121. package/docs/GRID_RECALCULATION.md +18 -6
  122. package/docs/LIFECYCLE.md +8 -8
  123. package/docs/LOGGING.md +16 -1
  124. package/docs/MPA_CREDIT_USAGE.md +10 -5
  125. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +163 -13
  126. package/docs/README.md +1 -1
  127. package/docs/WORKFLOW.md +6 -5
  128. package/docs/architecture.md +56 -2
  129. package/docs/developer_guide.md +5 -1
  130. package/market_adapter/README.md +14 -7
  131. package/modules/README.md +1 -1
  132. package/package.json +4 -1
  133. package/scripts/README.md +59 -32
  134. package/tests/README.md +40 -2
@@ -12,7 +12,7 @@
12
12
  * - Detects and flags out-of-spread conditions
13
13
  *
14
14
  * ===============================================================================
15
- * TABLE OF CONTENTS - Grid Functions (23 exported functions)
15
+ * TABLE OF CONTENTS - Grid Functions (34 exports)
16
16
  * ===============================================================================
17
17
  *
18
18
  * CONFIGURATION & CALCULATION (2 functions)
@@ -37,36 +37,49 @@
37
37
  * GRID STATE CHECKING (2 functions)
38
38
  * 8. checkAndUpdateGridIfNeeded(manager) - Complete fund trigger: available-
39
39
  * funds ratio + over-allocation + on-chain committed-drift legs
40
- * 8b. checkCommittedSizeDrift(manager) - Async committed-drift-only accessor
40
+ * 9. checkCommittedSizeDrift(manager) - Async committed-drift-only accessor
41
41
  * (the drift core is folded into checkAndUpdateGridIfNeeded)
42
42
  *
43
43
  * BLOCKCHAIN SYNCHRONIZATION (2 functions - async)
44
- * 9. _recalculateGridOrderSizesFromBlockchain(manager, orderType, options) - Recalculate sizes from blockchain
45
- * 10. updateGridFromBlockchainSnapshot(manager, orderType, fromBlockchainTimer, overrideBoundaryIdx) - Update grid from blockchain
44
+ * 10. _recalculateGridOrderSizesFromBlockchain(manager, orderType, options) - Recalculate sizes from blockchain
45
+ * 11. updateGridFromBlockchainSnapshot(manager, orderType, fromBlockchainTimer, overrideBoundaryIdx) - Update grid from blockchain
46
46
  *
47
47
  * GRID COMPARISON (2 functions - async)
48
- * 11. compareGrids(calculatedGrid, persistedGrid, manager) - Compare two grids
48
+ * 12. compareGrids(calculatedGrid, persistedGrid, manager) - Compare two grids
49
49
  * Validates grid structure and reports divergence metrics
50
- * 12. monitorDivergence(manager, calculatedGrid, persistedGrid) - Unified divergence check
50
+ * 13. monitorDivergence(manager, calculatedGrid, persistedGrid) - Unified divergence check
51
51
  * Runs ratio-based + RMS-based checks and returns combined result
52
52
  *
53
53
  * SPREAD MANAGEMENT (2 functions)
54
- * 13. calculateCurrentSpread(manager) - Calculate current bid-ask spread
55
- * 14. checkSpreadCondition(manager, BitShares, updateOrdersOnChainBatch) - Check and flag spread condition
54
+ * 14. calculateCurrentSpread(manager) - Calculate current bid-ask spread
55
+ * 15. checkSpreadCondition(manager, BitShares, updateOrdersOnChainBatch) - Check and flag spread condition
56
56
  *
57
57
  * GRID HEALTH MONITORING (4 functions)
58
- * 15. checkGridHealth(manager, updateOrdersOnChainBatch) - Monitor grid health
59
- * 16. checkWindowDust(manager) - Dust check scoped to the active buy/sell window
60
- * 17. hasAnyDust(manager, partials, side) - Check for dust orders
61
- * 18. getDustOrders(manager, partials, side) - Get dust order IDs
58
+ * 16. checkGridHealth(manager, updateOrdersOnChainBatch) - Monitor grid health
59
+ * 17. checkWindowDust(manager) - Dust check scoped to the active buy/sell window
60
+ * 18. hasAnyDust(manager, partials, side) - Check for dust orders
61
+ * 19. getDustOrders(manager, partials, side) - Get dust order IDs
62
62
  *
63
63
  * SIDE SELECTION (1 function)
64
- * 19. determineOrderSideByFunds(manager, currentMarketPrice) - Determine priority side
64
+ * 20. determineOrderSideByFunds(manager, currentMarketPrice) - Determine priority side
65
+ *
66
+ * SPREAD CORRECTION PLANNING (11 exports)
67
+ * 21. SPREAD_CORRECTION_REFUSAL - Refusal-cause vocabulary constant
68
+ * 22. SpreadCorrectionRefusalCause - Refusal-cause union type
69
+ * 23. isTransientSpreadRefusal(cause) - Whether a refusal cause is retryable
70
+ * 24. classifySpreadRefusalCause(...) - Classify why a correction batch did not land
71
+ * 25. recordSpreadCorrectionRefusal(...) - Record a refusal on the manager
72
+ * 26. recordSpreadCorrectionRetry(...) - Count a bounded re-plan retry
73
+ * 27. getOccupiedCorrectionSlots(...) - Planned CREATE destinations already occupied
74
+ * 28. replanSpreadCorrectionFromFreshMaster(...) - Re-plan from the current master
75
+ * 29. OccupiedCorrectionResolution - Outcome of plan-time collision resolution
76
+ * 30. resolveOccupiedCorrection(...) - Resolve a correction whose destination was taken
77
+ * 31. prepareSpreadCorrectionOrders(...) - Prepare orders to correct a wide spread
65
78
  *
66
79
  * BLOAT STATUS (3 functions)
67
- * 20. isGridBloated(manager, orders) - Check whether the grid is bloated
68
- * 21. isGridBloatGraceActive(manager) - Check the bloat grace state
69
- * 22. clearGridBloatFlag(manager) - Clear the bloat state
80
+ * 32. isGridBloated(manager, orders) - Check whether the grid is bloated
81
+ * 33. isGridBloatGraceActive(manager) - Check the bloat grace state
82
+ * 34. clearGridBloatFlag(manager) - Clear the bloat state
70
83
  *
71
84
  * ===============================================================================
72
85
  *
@@ -102,6 +115,118 @@ interface SpreadCorrection {
102
115
  origin?: string;
103
116
  [key: string]: unknown;
104
117
  }
118
+ /**
119
+ * Spread-correction refusal causes — the single vocabulary shared by
120
+ * classifySpreadRefusalCause, the retry/transience decision and the
121
+ * spreadCorrectionRefusalCauses metric key. Keep every reader/writer keyed off
122
+ * this map so a new cause cannot leave classification and transience out of
123
+ * sync.
124
+ */
125
+ export declare const SPREAD_CORRECTION_REFUSAL: Readonly<{
126
+ /** Post-broadcast working-grid commit rejected (orders may already be on chain). */
127
+ readonly COMMIT_REFUSED: "commit-refused";
128
+ /** Plan went stale / skipped before broadcast (base-version mismatch). */
129
+ readonly VERSION_MISMATCH: "version-mismatch";
130
+ /** A tracked UPDATE target was gone on chain (COW pre-broadcast guard). */
131
+ readonly UPDATE_TARGET_MISSING: "update-target-missing";
132
+ /** Destination slot already held an active order (plan-time dedupe). */
133
+ readonly CREATE_COLLISION: "create-collision";
134
+ /** Unmatched chain orders blocked the CREATE batch. */
135
+ readonly UNMATCHED_CHAIN_ORDERS: "unmatched-chain-orders";
136
+ /** Shutdown began while the batch was in flight. */
137
+ readonly SHUTDOWN: "shutdown";
138
+ /** Unclassified non-execution (fallback). */
139
+ readonly BATCH_NOT_EXECUTED: "batch-not-executed";
140
+ }>;
141
+ export type SpreadCorrectionRefusalCause = (typeof SPREAD_CORRECTION_REFUSAL)[keyof typeof SPREAD_CORRECTION_REFUSAL];
142
+ /**
143
+ * Whether a refusal cause is retryable by the bounded spread-correction re-plan.
144
+ * @param {string} cause - A SPREAD_CORRECTION_REFUSAL value
145
+ * @returns {boolean}
146
+ */
147
+ export declare function isTransientSpreadRefusal(cause: SpreadCorrectionRefusalCause): boolean;
148
+ /**
149
+ * P0 observability: classify WHY a spread-correction batch did not land
150
+ * (executed !== true) from the COW batch result. Counter-only — never gates
151
+ * placement. Returns a SPREAD_CORRECTION_REFUSAL value so the metric key, the
152
+ * retry decision and the log all share one vocabulary.
153
+ * @param {Object|null} batchResult - The COW batch result
154
+ * @returns {string} A SPREAD_CORRECTION_REFUSAL value
155
+ */
156
+ export declare function classifySpreadRefusalCause(batchResult: unknown): SpreadCorrectionRefusalCause;
157
+ /**
158
+ * P0 observability: record a spread-correction refusal on the manager's
159
+ * metrics (the only object reachable from this planner; getMetrics overlays
160
+ * these onto the bot's counters). Counter-only; never throws, never gates.
161
+ * @param {Object} manager - OrderManager instance
162
+ * @param {string} cause - A SPREAD_CORRECTION_REFUSAL value
163
+ */
164
+ export declare function recordSpreadCorrectionRefusal(manager: OrderManagerLike, cause: SpreadCorrectionRefusalCause): void;
165
+ /**
166
+ * P5 observability: count a bounded spread-correction re-plan retry. Churn
167
+ * signal — a rising retry rate means concurrent commits are repeatedly
168
+ * invalidating corrections. Counter-only; never throws.
169
+ * @param {Object} manager - OrderManager instance
170
+ */
171
+ export declare function recordSpreadCorrectionRetry(manager: OrderManagerLike): void;
172
+ /**
173
+ * P2 plan-time dedupe: which of a correction's planned CREATE destinations are
174
+ * now occupied by a live (ACTIVE/PARTIAL) order with a chain id?
175
+ *
176
+ * The correction is planned under _gridLock, then broadcast after the lock is
177
+ * released. A concurrent fill rebalance can commit an order onto one of the
178
+ * planned slots in that window; the COW build layer then rejects the whole
179
+ * batch (`Rejecting CREATE … existing orderId`). Detecting it here turns that
180
+ * into a cheap plan-time re-derive (see the retry loop in checkSpreadCondition)
181
+ * instead of a mid-broadcast refusal and structural resync.
182
+ *
183
+ * Pure and never throws. A missing/non-Map orders store selects the empty set.
184
+ * @param {Object} manager - OrderManager instance
185
+ * @param {Object|null} correction - Prepared spread correction
186
+ * @returns {string[]} Occupied planned slot ids
187
+ */
188
+ export declare function getOccupiedCorrectionSlots(manager: OrderManagerLike, correction: SpreadCorrection | null | undefined): string[];
189
+ /**
190
+ * P1/P3 shared re-plan: derive a spread correction from the CURRENT master
191
+ * state (side chosen from fresh on-chain book, opposite-side starvation
192
+ * fallback). Used both for the plan-time collision dedupe and the bounded
193
+ * refusal retry. Read-only against the grid; no _gridLock needed (matches the
194
+ * existing TOCTOU fund re-plan contract).
195
+ * @param {Object} manager - OrderManager instance
196
+ * @returns {Promise<Object|null>} A correction with at least one create, or null
197
+ */
198
+ export declare function replanSpreadCorrectionFromFreshMaster(manager: OrderManagerLike): Promise<SpreadCorrection | null>;
199
+ /**
200
+ * Outcome of the P2 plan-time collision resolution.
201
+ * - 'broadcast': no occupied destination (or the final attempt) — ship the plan.
202
+ * - 'replanned': a destination was taken and a fresh correction was derived.
203
+ * - 'blocked': a destination was taken and no fresh correction exists — refuse.
204
+ */
205
+ export type OccupiedCorrectionResolution = {
206
+ action: 'broadcast';
207
+ } | {
208
+ action: 'replanned';
209
+ correction: SpreadCorrection;
210
+ occupied: string[];
211
+ } | {
212
+ action: 'blocked';
213
+ occupied: string[];
214
+ };
215
+ /**
216
+ * P2: resolve a planned correction whose CREATE destination(s) were taken after
217
+ * planning. Detects the collision, re-derives once from fresh master, and
218
+ * reports whether the caller should broadcast, swap in the re-plan, or refuse.
219
+ *
220
+ * Extracted from checkSpreadCondition so the branch is a real, production-called
221
+ * unit that tests can drive directly (no test-only hook in the production path).
222
+ *
223
+ * @param {Object} manager - OrderManager instance
224
+ * @param {Object|null} correction - The plan about to broadcast
225
+ * @param {number} attempt - 1-based attempt index
226
+ * @param {number} maxAttempts - Total attempts allowed
227
+ * @returns {Promise<OccupiedCorrectionResolution>}
228
+ */
229
+ export declare function resolveOccupiedCorrection(manager: OrderManagerLike, correction: SpreadCorrection | null | undefined, attempt: number, maxAttempts: number): Promise<OccupiedCorrectionResolution>;
105
230
  /**
106
231
  * Central resolution for the RMS structural-divergence threshold (percent).
107
232
  * Single source of truth: per-bot override wins, global GRID_COMPARISON default
@@ -477,8 +602,6 @@ export declare function calculateCurrentSpread(manager: OrderManagerLike): numbe
477
602
  * - RACE CONDITION WINDOW: Between lock release and blockchain submission
478
603
  * - MITIGATION: Pre-flight fund verification before submission; comprehensive error handling
479
604
  *
480
- * See RACE_CONDITION_ANALYSIS.md for detailed vulnerability documentation.
481
- *
482
605
  * @param {import('./types').OrderManager} manager - Manager instance
483
606
  * @param {Object} BitShares - BitShares API client
484
607
  * @param {Function|null} [updateOrdersOnChainBatch=null] - Optional batch update function
@@ -486,10 +609,15 @@ export declare function calculateCurrentSpread(manager: OrderManagerLike): numbe
486
609
  */
487
610
  export declare function checkSpreadCondition(manager: OrderManagerLike, _BitShares: unknown, updateOrdersOnChainBatch?: ((correction: SpreadCorrection) => Promise<{
488
611
  executed?: boolean;
489
- }>) | null): Promise<{
612
+ reason?: unknown;
613
+ commitRefused?: boolean;
614
+ skippedStalePlan?: boolean;
615
+ [key: string]: unknown;
616
+ } | null | undefined>) | null): Promise<{
490
617
  ordersPlaced: number;
491
618
  partialsMoved: number;
492
619
  stall?: SpreadCorrectionStall;
620
+ transient?: boolean;
493
621
  }>;
494
622
  /**
495
623
  * Grid health check for structural violations.