dexbot 1.6.13 → 1.6.15

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 (114) hide show
  1. package/CHANGELOG.md +66 -4
  2. package/README.md +2 -2
  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/AI_BOT_LIBRARY_API.md +1 -1
  7. package/claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md +4 -4
  8. package/claw/modules/claw_catalog.ts +8 -4
  9. package/claw/modules/dexbot_profiles.ts +59 -15
  10. package/claw/modules/types.ts +2 -1
  11. package/claw/package.json +1 -1
  12. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  13. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  14. package/claw/skills/margin-trading/SKILL.md +1 -1
  15. package/claw/skills/margin-trading/references/position-management.md +1 -1
  16. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +105 -31
  17. package/dist/analysis/trend_detection/dynamic_weight_chart_generator.js +36 -2
  18. package/dist/dexbot.js +23 -3
  19. package/dist/market_adapter/core/strategies/dynamic_weight_series.js +26 -11
  20. package/dist/modules/account_bots.d.ts +10 -6
  21. package/dist/modules/account_bots.js +13 -10
  22. package/dist/modules/account_orders.d.ts +36 -4
  23. package/dist/modules/account_orders.js +76 -5
  24. package/dist/modules/bitshares-native/crypto/ecc_core.d.ts +1 -2
  25. package/dist/modules/bitshares-native/crypto/ecc_core.js +1 -1
  26. package/dist/modules/bitshares-native/serial/chain_constants.d.ts +1 -2
  27. package/dist/modules/bitshares-native/serial/chain_constants.js +1 -2
  28. package/dist/modules/bitshares-native/subscriptions.js +1 -1
  29. package/dist/modules/bot_defaults.d.ts +29 -4
  30. package/dist/modules/bot_defaults.js +65 -10
  31. package/dist/modules/bot_settings.d.ts +4 -0
  32. package/dist/modules/bot_settings.js +58 -21
  33. package/dist/modules/config.js +6 -1
  34. package/dist/modules/constants.d.ts +13 -5
  35. package/dist/modules/constants.js +36 -5
  36. package/dist/modules/credit_runtime.d.ts +35 -5
  37. package/dist/modules/credit_runtime.js +219 -38
  38. package/dist/modules/dexbot_class.d.ts +23 -0
  39. package/dist/modules/dexbot_class.js +60 -17
  40. package/dist/modules/dexbot_cow_runtime.d.ts +62 -174
  41. package/dist/modules/dexbot_cow_runtime.js +350 -64
  42. package/dist/modules/dexbot_credential_client.d.ts +1 -16
  43. package/dist/modules/dexbot_credential_client.js +1 -1
  44. package/dist/modules/dexbot_fill_runtime.d.ts +2 -2
  45. package/dist/modules/dexbot_fill_runtime.js +16 -8
  46. package/dist/modules/dexbot_maintenance_runtime.d.ts +24 -81
  47. package/dist/modules/dexbot_maintenance_runtime.js +104 -70
  48. package/dist/modules/dexbot_startup_runtime.js +15 -2
  49. package/dist/modules/dexbot_state_recovery.js +17 -1
  50. package/dist/modules/key_store.d.ts +0 -5
  51. package/dist/modules/key_store.js +1 -1
  52. package/dist/modules/order/accounting.js +11 -11
  53. package/dist/modules/order/export.js +4 -4
  54. package/dist/modules/order/format.d.ts +15 -1
  55. package/dist/modules/order/format.js +19 -1
  56. package/dist/modules/order/genesis_policy.d.ts +1 -1
  57. package/dist/modules/order/genesis_policy.js +1 -1
  58. package/dist/modules/order/grid.d.ts +141 -12
  59. package/dist/modules/order/grid.js +666 -92
  60. package/dist/modules/order/grid_reconcile.d.ts +1 -1
  61. package/dist/modules/order/grid_reconcile.js +9 -8
  62. package/dist/modules/order/grid_reconcile_internal.js +61 -58
  63. package/dist/modules/order/index.d.ts +37 -9
  64. package/dist/modules/order/logger.js +2 -2
  65. package/dist/modules/order/manager.d.ts +10 -2
  66. package/dist/modules/order/manager.js +56 -31
  67. package/dist/modules/order/strategy.d.ts +2 -2
  68. package/dist/modules/order/strategy.js +51 -21
  69. package/dist/modules/order/sync_engine.js +22 -9
  70. package/dist/modules/order/utils/math.d.ts +101 -29
  71. package/dist/modules/order/utils/math.js +215 -84
  72. package/dist/modules/order/utils/order.d.ts +58 -58
  73. package/dist/modules/order/utils/order.js +135 -106
  74. package/dist/modules/order/utils/system.d.ts +193 -6
  75. package/dist/modules/order/utils/system.js +394 -31
  76. package/dist/modules/order/utils/validate.d.ts +1 -1
  77. package/dist/modules/order/utils/validate.js +71 -59
  78. package/dist/modules/runtime_settings.d.ts +1 -1
  79. package/dist/modules/runtime_settings.js +3 -3
  80. package/dist/modules/types.d.ts +55 -4
  81. package/dist/scripts/analyze-credit.js +44 -27
  82. package/dist/scripts/analyze-orders.d.ts +1 -1
  83. package/dist/scripts/analyze-orders.js +4 -4
  84. package/dist/scripts/diagnose-pool-history.js +35 -30
  85. package/dist/scripts/divergence-calc.js +6 -6
  86. package/dist/scripts/pnl.js +1 -1
  87. package/dist/scripts/rich_list.d.ts +18 -0
  88. package/dist/scripts/rich_list.js +461 -0
  89. package/dist/scripts/run-tests.js +80 -4
  90. package/dist/scripts/validate_bots.d.ts +1 -1
  91. package/dist/scripts/validate_bots.js +3 -3
  92. package/dist/unlock.d.ts +2 -1
  93. package/dist/unlock.js +11 -5
  94. package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -2
  95. package/docs/COW_INVARIANTS.md +12 -6
  96. package/docs/DEXBOT_COMPARISON.md +7 -7
  97. package/docs/EVOLUTION.md +10 -8
  98. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +8 -6
  99. package/docs/GRID_PRICE_INVARIANT.md +3 -3
  100. package/docs/GRID_RECALCULATION.md +4 -1
  101. package/docs/GRID_RECONCILE.md +4 -4
  102. package/docs/LIFECYCLE.md +11 -11
  103. package/docs/LOGGING.md +30 -1
  104. package/docs/MPA_CREDIT_USAGE.md +11 -6
  105. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +170 -12
  106. package/docs/README.md +3 -3
  107. package/docs/WORKFLOW.md +1 -0
  108. package/docs/architecture.md +62 -8
  109. package/docs/developer_guide.md +12 -3
  110. package/market_adapter/README.md +4 -4
  111. package/modules/README.md +1 -1
  112. package/package.json +2 -1
  113. package/scripts/README.md +59 -32
  114. package/tests/README.md +12 -3
@@ -12,7 +12,7 @@
12
12
  * - Detects and flags out-of-spread conditions
13
13
  *
14
14
  * ===============================================================================
15
- * TABLE OF CONTENTS - Grid Functions (22 exported functions)
15
+ * TABLE OF CONTENTS - Grid Functions (23 exported functions)
16
16
  * ===============================================================================
17
17
  *
18
18
  * CONFIGURATION & CALCULATION (2 functions)
@@ -34,8 +34,11 @@
34
34
  * GRID RECALCULATION (1 function - async)
35
35
  * 7. recalculateGrid(manager, opts) - Recalculate grid based on current state
36
36
  *
37
- * GRID STATE CHECKING (1 function)
38
- * 8. checkAndUpdateGridIfNeeded(manager) - Check if grid needs update
37
+ * GRID STATE CHECKING (2 functions)
38
+ * 8. checkAndUpdateGridIfNeeded(manager) - Complete fund trigger: available-
39
+ * funds ratio + over-allocation + on-chain committed-drift legs
40
+ * 8b. checkCommittedSizeDrift(manager) - Async committed-drift-only accessor
41
+ * (the drift core is folded into checkAndUpdateGridIfNeeded)
39
42
  *
40
43
  * BLOCKCHAIN SYNCHRONIZATION (2 functions - async)
41
44
  * 9. _recalculateGridOrderSizesFromBlockchain(manager, orderType, options) - Recalculate sizes from blockchain
@@ -94,11 +97,123 @@ interface SpreadCorrection {
94
97
  newSize: number;
95
98
  }>;
96
99
  plannedCount?: number;
97
- stallHint?: 'unfunded' | 'no-candidates';
100
+ stallHint?: SpreadCorrectionStall;
98
101
  boundaryIdx?: number;
99
102
  origin?: string;
100
103
  [key: string]: unknown;
101
104
  }
105
+ /**
106
+ * Spread-correction refusal causes — the single vocabulary shared by
107
+ * classifySpreadRefusalCause, the retry/transience decision and the
108
+ * spreadCorrectionRefusalCauses metric key. Keep every reader/writer keyed off
109
+ * this map so a new cause cannot leave classification and transience out of
110
+ * sync.
111
+ */
112
+ export declare const SPREAD_CORRECTION_REFUSAL: Readonly<{
113
+ /** Post-broadcast working-grid commit rejected (orders may already be on chain). */
114
+ readonly COMMIT_REFUSED: "commit-refused";
115
+ /** Plan went stale / skipped before broadcast (base-version mismatch). */
116
+ readonly VERSION_MISMATCH: "version-mismatch";
117
+ /** A tracked UPDATE target was gone on chain (COW pre-broadcast guard). */
118
+ readonly UPDATE_TARGET_MISSING: "update-target-missing";
119
+ /** Destination slot already held an active order (plan-time dedupe). */
120
+ readonly CREATE_COLLISION: "create-collision";
121
+ /** Unmatched chain orders blocked the CREATE batch. */
122
+ readonly UNMATCHED_CHAIN_ORDERS: "unmatched-chain-orders";
123
+ /** Shutdown began while the batch was in flight. */
124
+ readonly SHUTDOWN: "shutdown";
125
+ /** Unclassified non-execution (fallback). */
126
+ readonly BATCH_NOT_EXECUTED: "batch-not-executed";
127
+ }>;
128
+ export type SpreadCorrectionRefusalCause = (typeof SPREAD_CORRECTION_REFUSAL)[keyof typeof SPREAD_CORRECTION_REFUSAL];
129
+ /**
130
+ * Whether a refusal cause is retryable by the bounded spread-correction re-plan.
131
+ * @param {string} cause - A SPREAD_CORRECTION_REFUSAL value
132
+ * @returns {boolean}
133
+ */
134
+ export declare function isTransientSpreadRefusal(cause: SpreadCorrectionRefusalCause): boolean;
135
+ /**
136
+ * P0 observability: classify WHY a spread-correction batch did not land
137
+ * (executed !== true) from the COW batch result. Counter-only — never gates
138
+ * placement. Returns a SPREAD_CORRECTION_REFUSAL value so the metric key, the
139
+ * retry decision and the log all share one vocabulary.
140
+ * @param {Object|null} batchResult - The COW batch result
141
+ * @returns {string} A SPREAD_CORRECTION_REFUSAL value
142
+ */
143
+ export declare function classifySpreadRefusalCause(batchResult: unknown): SpreadCorrectionRefusalCause;
144
+ /**
145
+ * P0 observability: record a spread-correction refusal on the manager's
146
+ * metrics (the only object reachable from this planner; getMetrics overlays
147
+ * these onto the bot's counters). Counter-only; never throws, never gates.
148
+ * @param {Object} manager - OrderManager instance
149
+ * @param {string} cause - A SPREAD_CORRECTION_REFUSAL value
150
+ */
151
+ export declare function recordSpreadCorrectionRefusal(manager: OrderManagerLike, cause: SpreadCorrectionRefusalCause): void;
152
+ /**
153
+ * P5 observability: count a bounded spread-correction re-plan retry. Churn
154
+ * signal — a rising retry rate means concurrent commits are repeatedly
155
+ * invalidating corrections. Counter-only; never throws.
156
+ * @param {Object} manager - OrderManager instance
157
+ */
158
+ export declare function recordSpreadCorrectionRetry(manager: OrderManagerLike): void;
159
+ /**
160
+ * P2 plan-time dedupe: which of a correction's planned CREATE destinations are
161
+ * now occupied by a live (ACTIVE/PARTIAL) order with a chain id?
162
+ *
163
+ * The correction is planned under _gridLock, then broadcast after the lock is
164
+ * released. A concurrent fill rebalance can commit an order onto one of the
165
+ * planned slots in that window; the COW build layer then rejects the whole
166
+ * batch (`Rejecting CREATE … existing orderId`). Detecting it here turns that
167
+ * into a cheap plan-time re-derive (see the retry loop in checkSpreadCondition)
168
+ * instead of a mid-broadcast refusal and structural resync.
169
+ *
170
+ * Pure and never throws. A missing/non-Map orders store selects the empty set.
171
+ * @param {Object} manager - OrderManager instance
172
+ * @param {Object|null} correction - Prepared spread correction
173
+ * @returns {string[]} Occupied planned slot ids
174
+ */
175
+ export declare function getOccupiedCorrectionSlots(manager: OrderManagerLike, correction: SpreadCorrection | null | undefined): string[];
176
+ /**
177
+ * P1/P3 shared re-plan: derive a spread correction from the CURRENT master
178
+ * state (side chosen from fresh on-chain book, opposite-side starvation
179
+ * fallback). Used both for the plan-time collision dedupe and the bounded
180
+ * refusal retry. Read-only against the grid; no _gridLock needed (matches the
181
+ * existing TOCTOU fund re-plan contract).
182
+ * @param {Object} manager - OrderManager instance
183
+ * @returns {Promise<Object|null>} A correction with at least one create, or null
184
+ */
185
+ export declare function replanSpreadCorrectionFromFreshMaster(manager: OrderManagerLike): Promise<SpreadCorrection | null>;
186
+ /**
187
+ * Outcome of the P2 plan-time collision resolution.
188
+ * - 'broadcast': no occupied destination (or the final attempt) — ship the plan.
189
+ * - 'replanned': a destination was taken and a fresh correction was derived.
190
+ * - 'blocked': a destination was taken and no fresh correction exists — refuse.
191
+ */
192
+ export type OccupiedCorrectionResolution = {
193
+ action: 'broadcast';
194
+ } | {
195
+ action: 'replanned';
196
+ correction: SpreadCorrection;
197
+ occupied: string[];
198
+ } | {
199
+ action: 'blocked';
200
+ occupied: string[];
201
+ };
202
+ /**
203
+ * P2: resolve a planned correction whose CREATE destination(s) were taken after
204
+ * planning. Detects the collision, re-derives once from fresh master, and
205
+ * reports whether the caller should broadcast, swap in the re-plan, or refuse.
206
+ *
207
+ * Extracted from checkSpreadCondition so the branch is a real, production-called
208
+ * unit that tests can drive directly (no test-only hook in the production path).
209
+ *
210
+ * @param {Object} manager - OrderManager instance
211
+ * @param {Object|null} correction - The plan about to broadcast
212
+ * @param {number} attempt - 1-based attempt index
213
+ * @param {number} maxAttempts - Total attempts allowed
214
+ * @returns {Promise<OccupiedCorrectionResolution>}
215
+ */
216
+ export declare function resolveOccupiedCorrection(manager: OrderManagerLike, correction: SpreadCorrection | null | undefined, attempt: number, maxAttempts: number): Promise<OccupiedCorrectionResolution>;
102
217
  /**
103
218
  * Central resolution for the RMS structural-divergence threshold (percent).
104
219
  * Single source of truth: per-bot override wins, global GRID_COMPARISON default
@@ -152,13 +267,9 @@ export declare function isGridBloatGraceActive(manager: OrderManagerLike): {
152
267
  */
153
268
  export declare function clearGridBloatFlag(manager: OrderManagerLike): void;
154
269
  /**
155
- * Unifies budget calculation and fee deduction for all grid sizing scenarios.
156
- * Ensures consistent fund context (Allocated vs Total) across the bot.
157
- *
158
- * @param {import('./types').OrderManager} manager - OrderManager instance
159
- * @param {string} side - 'buy' or 'sell'
160
- * @returns {Promise<any|null>}
161
- * @private
270
+ * Async sizing-context accessor. Refreshes funds unless `skipRecalc`, then
271
+ * delegates to the sync core. Both divergence legs (ratio and committed
272
+ * drift) size through the sync core so they read one fund snapshot.
162
273
  */
163
274
  export declare function _getSizingContext(manager: OrderManagerLike, side: string, { skipRecalc }?: {
164
275
  skipRecalc?: boolean;
@@ -287,6 +398,19 @@ export declare function checkAndUpdateGridIfNeeded(manager: OrderManagerLike): {
287
398
  buyShrink: boolean;
288
399
  sellShrink: boolean;
289
400
  };
401
+ /**
402
+ * Async committed-drift accessor: refresh funds, then run the sync core.
403
+ * Public for callers/tests that want the drift-only result; the complete
404
+ * trigger is checkAndUpdateGridIfNeeded, which folds this core in.
405
+ * Naming mirrors the sizing pair: _computeCommittedSizeDriftSync is the
406
+ * private computation, checkCommittedSizeDrift the public accessor.
407
+ */
408
+ export declare function checkCommittedSizeDrift(manager: OrderManagerLike): Promise<{
409
+ buyUpdated: boolean;
410
+ sellUpdated: boolean;
411
+ buyShrink: boolean;
412
+ sellShrink: boolean;
413
+ }>;
290
414
  /**
291
415
  * Standardize grid sizes using blockchain total context.
292
416
  *
@@ -474,10 +598,15 @@ export declare function calculateCurrentSpread(manager: OrderManagerLike): numbe
474
598
  */
475
599
  export declare function checkSpreadCondition(manager: OrderManagerLike, _BitShares: unknown, updateOrdersOnChainBatch?: ((correction: SpreadCorrection) => Promise<{
476
600
  executed?: boolean;
477
- }>) | null): Promise<{
601
+ reason?: unknown;
602
+ commitRefused?: boolean;
603
+ skippedStalePlan?: boolean;
604
+ [key: string]: unknown;
605
+ } | null | undefined>) | null): Promise<{
478
606
  ordersPlaced: number;
479
607
  partialsMoved: number;
480
608
  stall?: SpreadCorrectionStall;
609
+ transient?: boolean;
481
610
  }>;
482
611
  /**
483
612
  * Grid health check for structural violations.