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
@@ -28,7 +28,7 @@
28
28
  * Price: startPrice, minPrice, maxPrice, incrementPercent, targetSpreadPercent
29
29
  * Control: active, dryRun
30
30
  * Trading pair: assetA, assetB
31
- * Allocation: weightDistribution, botFunds, activeOrders
31
+ * Allocation: weightDistribution, botFunds, coreOrders
32
32
  *
33
33
  * TIMING PARAMETERS:
34
34
  * 4. TIMING - Operational timing constants
@@ -173,11 +173,11 @@ declare let DEFAULT_CONFIG: {
173
173
  sell: string;
174
174
  buy: string;
175
175
  };
176
- activeOrders: {
176
+ coreOrders: {
177
177
  sell: number;
178
178
  buy: number;
179
179
  };
180
- reserveOrders: {
180
+ edgeOrders: {
181
181
  buy: number;
182
182
  sell: number;
183
183
  };
@@ -225,6 +225,9 @@ declare let TIMING: {
225
225
  FILL_TOTALS_RETRY_MAX_MS: number;
226
226
  SPREAD_STALE_WARN_MS: number;
227
227
  SPREAD_STALE_ESCALATE_MS: number;
228
+ SPREAD_CORRECTION_MAX_ATTEMPTS: number;
229
+ SPREAD_STALE_TRANSIENT_GRACE: number;
230
+ SPREAD_CORRECTION_SYNC_FRESH_MS: number;
228
231
  SPREAD_STALE_RESYNC_COOLDOWN_MS: number;
229
232
  BOUNDARY_HOLD_RESYNC_THRESHOLD: number;
230
233
  BOUNDARY_HOLD_RESYNC_COOLDOWN_MS: number;
@@ -331,6 +334,7 @@ declare let API_LIMITS: {
331
334
  declare let FILL_PROCESSING: {
332
335
  MODE: string;
333
336
  OPERATION_TYPE: number;
337
+ COALESCE_BACKLOG_REPLAY: boolean;
334
338
  MAX_CONSECUTIVE_CONSUMER_FAILURES: number;
335
339
  CONSUMER_BACKOFF_INITIAL_MS: number;
336
340
  CONSUMER_BACKOFF_MAX_MS: number;
@@ -764,6 +768,9 @@ declare function buildDefaultGeneralSettings(): {
764
768
  FILL_TOTALS_RETRY_MAX_MS: number;
765
769
  SPREAD_STALE_WARN_MS: number;
766
770
  SPREAD_STALE_ESCALATE_MS: number;
771
+ SPREAD_CORRECTION_MAX_ATTEMPTS: number;
772
+ SPREAD_STALE_TRANSIENT_GRACE: number;
773
+ SPREAD_CORRECTION_SYNC_FRESH_MS: number;
767
774
  SPREAD_STALE_RESYNC_COOLDOWN_MS: number;
768
775
  BOUNDARY_HOLD_RESYNC_THRESHOLD: number;
769
776
  BOUNDARY_HOLD_RESYNC_COOLDOWN_MS: number;
@@ -986,11 +993,11 @@ declare function buildDefaultGeneralSettings(): {
986
993
  sell: string;
987
994
  buy: string;
988
995
  };
989
- activeOrders: {
996
+ coreOrders: {
990
997
  sell: number;
991
998
  buy: number;
992
999
  };
993
- reserveOrders: {
1000
+ edgeOrders: {
994
1001
  buy: number;
995
1002
  sell: number;
996
1003
  };
@@ -999,6 +1006,7 @@ declare function buildDefaultGeneralSettings(): {
999
1006
  FILL_PROCESSING: {
1000
1007
  MODE: string;
1001
1008
  OPERATION_TYPE: number;
1009
+ COALESCE_BACKLOG_REPLAY: boolean;
1002
1010
  MAX_CONSECUTIVE_CONSUMER_FAILURES: number;
1003
1011
  CONSUMER_BACKOFF_INITIAL_MS: number;
1004
1012
  CONSUMER_BACKOFF_MAX_MS: number;
@@ -29,7 +29,7 @@
29
29
  * Price: startPrice, minPrice, maxPrice, incrementPercent, targetSpreadPercent
30
30
  * Control: active, dryRun
31
31
  * Trading pair: assetA, assetB
32
- * Allocation: weightDistribution, botFunds, activeOrders
32
+ * Allocation: weightDistribution, botFunds, coreOrders
33
33
  *
34
34
  * TIMING PARAMETERS:
35
35
  * 4. TIMING - Operational timing constants
@@ -196,10 +196,10 @@ let DEFAULT_CONFIG = {
196
196
  // Fund allocation
197
197
  weightDistribution: { sell: 1, buy: 1 }, // Geometric weight for order sizing (1 = ~1:2 center/outer split, 0.5 = linear)
198
198
  botFunds: { sell: "100%", buy: "100%" }, // Percentage of wallet balance to allocate ("100%" or numeric value)
199
- activeOrders: { sell: 20, buy: 20 }, // Number of orders to maintain closest to market on each side
200
- reserveOrders: { buy: 0, sell: 0 }, // Edge-pinned insurance orders resting live outside the window (buy: grid floor, sell: grid ceiling; 0 disables)
199
+ coreOrders: { sell: 20, buy: 20 }, // Number of window orders to maintain closest to market on each side
200
+ edgeOrders: { buy: 0, sell: 0 }, // Edge-pinned insurance orders resting live outside the window (buy: grid floor, sell: grid ceiling; 0 disables)
201
201
  // BTS fee management for non-BTS pairs
202
- min_BTS_value: null, // Minimum BTS balance to maintain (null = auto from activeOrders × fees × multiplier)
202
+ min_BTS_value: null, // Minimum BTS balance to maintain (null = auto from coreOrders × fees × multiplier)
203
203
  };
204
204
  // Range quality zones for price bounds (minPrice/maxPrice multipliers).
205
205
  // Used for pre-entry legend in the bot editor (mountain-style).
@@ -330,6 +330,27 @@ let TIMING = {
330
330
  // by moving the boundary). Time-based so it holds for any tick cadence.
331
331
  SPREAD_STALE_WARN_MS: 10 * 60 * 1000, // 10 minutes
332
332
  SPREAD_STALE_ESCALATE_MS: 30 * 60 * 1000, // 30 minutes
333
+ // SPREAD_CORRECTION_MAX_ATTEMPTS: bounded attempts for one spread-correction
334
+ // cycle (initial broadcast + fresh-master re-plan retries). Kept next to the
335
+ // other SPREAD_* tunables so the retry budget is centralized; a value < 1
336
+ // falls back to 2. Overridable per deployment under TIMING in
337
+ // profiles/general.settings.json (TIMING is a shallow-merged section).
338
+ SPREAD_CORRECTION_MAX_ATTEMPTS: 2,
339
+ // SPREAD_STALE_TRANSIENT_GRACE: consecutive TRANSIENT spread-correction
340
+ // refusals (stale plan / duplicate CREATE / unclassified non-execution)
341
+ // tolerated before the out-of-spread watchdog stops treating them as
342
+ // retryable and lets the persistent-stale clock escalate to a structural
343
+ // re-center. checkSpreadCondition's bounded re-plan heals most transient
344
+ // refusals in-cycle; the grace keeps a genuinely deadlocked transient from
345
+ // hiding behind the retry path forever.
346
+ SPREAD_STALE_TRANSIENT_GRACE: 3,
347
+ // SPREAD_CORRECTION_SYNC_FRESH_MS: how old the last completed open-orders
348
+ // sync may be before a spread-correction CREATE loses its LAST-FILL-GUARD
349
+ // bypass. A stale local snapshot (old sync or known-unmatched chain
350
+ // orders) can hide the real window edge, so the bypass is withheld and the
351
+ // guard applies instead of trusting the stale anchor. Fail-open when no
352
+ // sync timestamp exists yet.
353
+ SPREAD_CORRECTION_SYNC_FRESH_MS: 10 * 60 * 1000, // 10 minutes
333
354
  // Dedicated escalation cooldown for the spread-stale watchdog. Deliberately
334
355
  // separate from BOUNDARY_HOLD_RESYNC_COOLDOWN_MS so tuning boundary-hold
335
356
  // behavior never silently changes the spread watchdog cadence.
@@ -538,7 +559,7 @@ let GRID_LIMITS = {
538
559
  // to a price ladder ("no genesis" -- the genesis-less state analysed in
539
560
  // docs/GRID_PRICE_INVARIANT.md). A genesis-less grid is NOT repairable in
540
561
  // place: every consumer (nearest-slot adoption, the materialize
541
- // descriptor-price fallback, reserve-edge anchoring) has no authority for a
562
+ // descriptor-price fallback, edge anchoring) has no authority for a
542
563
  // slot's price, which is exactly how an off-grid price became grid evidence
543
564
  // and was re-emitted. The load and sync gates refuse that state outright —
544
565
  // no tolerance matcher remains.
@@ -856,6 +877,16 @@ let FILL_PROCESSING = {
856
877
  // NOTE: fill/broadcast batch sizing is derived from the grid gap-slot
857
878
  // count (DEXBot._getGapSlotBatchSize). There is deliberately no fixed
858
879
  // fill-batch or ops-per-broadcast constant here.
880
+ // COALESCE_BACKLOG_REPLAY: when true, a fill backlog larger than the
881
+ // gap-slot batch size is planned as ONE reconcile instead of the default
882
+ // chunked replay (each chunk mutating the boundary before broadcasting).
883
+ // Reuses the existing unified-plan path; the boundary-shift budget and
884
+ // _getMaxOpsPerBroadcast still bound the shift and split the broadcast
885
+ // into gapSlots+1-op transactions, so this only removes the intermediate
886
+ // plan/broadcast cycles (Stale-Restart #5). Default OFF: opt-in rollout
887
+ // for the live boundary engine, overridable per bot via
888
+ // `fillProcessing.COALESCE_BACKLOG_REPLAY` in general settings.
889
+ COALESCE_BACKLOG_REPLAY: false,
859
890
  // MAX_CONSECUTIVE_CONSUMER_FAILURES: Threshold for the _consumeFillQueue
860
891
  // watchdog. Below this count, the consumer re-schedules on every failure
861
892
  // via setImmediate. At or above this count, the consumer switches to
@@ -253,16 +253,46 @@ declare class CreditRuntime {
253
253
  */
254
254
  _getFreeDebtAssetBalance(debtAssetId: unknown, debtAsset: UnknownRecord | null): Promise<number | null>;
255
255
  /**
256
- * Raw collateral freed by a repay, used as the ceiling a reborrow can lock.
257
- * Precedence:
256
+ * Read the chain-free balance of a collateral asset. Mirrors
257
+ * `_getFreeDebtAssetBalance`; returns null when it cannot be determined.
258
+ */
259
+ _getFreeCollateralBalance(collateralAssetId: unknown, collateralAsset: UnknownRecord | null): Promise<number | null>;
260
+ /**
261
+ * Highest raw collateral this deal's position may hold, from the position's
262
+ * `assignedCollateralBudget`. The renewed deal is one member of the
263
+ * position, so its ceiling is the budget minus the collateral the position's
264
+ * other deals already hold. Returns null when no budget is known.
265
+ */
266
+ _positionCollateralCapInt(dealSummary: DealSummary | UnknownRecord | null, collateralAsset: UnknownRecord | null, releasedInt: number): number | null;
267
+ /**
268
+ * Raw collateral available to a reborrow, as `{ released, budget }`:
269
+ * - `released` — the portion freed by this repay (the collateral floor),
270
+ * - `budget` — the ceiling the new accept may lock: the released portion
271
+ * plus the borrower's free balance of the same asset (when
272
+ * `useFreeCollateral` is on, the default), bounded by the
273
+ * position's `assignedCollateralBudget`.
274
+ * Precedence for `released`:
258
275
  * 1. explicit raw `options.availableCollateralAmount` (collateral-switch flow),
259
276
  * 2. exact on-chain `floor(repay * collateral / debt)` when the deal's own
260
277
  * collateral asset is used,
261
278
  * 3. explicit `options.pendingReleaseCollateralAmount` (float) as a fallback.
262
- * Returns null when it cannot be determined, so the accept builder keeps the
263
- * legacy (unclamped) behaviour.
279
+ * Returns `{ released: null, budget: null }` when it cannot be determined, so
280
+ * the accept builder keeps the legacy (unclamped) behaviour.
281
+ */
282
+ _computeCollateralBudget(dealSummary: DealSummary | UnknownRecord | null, repayAmount: unknown, options: UnknownRecord): Promise<{
283
+ released: number | null;
284
+ budget: number | null;
285
+ }>;
286
+ /**
287
+ * Recompute a persisted pending reborrow's collateral budget from its stored
288
+ * released base, the current free balance, and the current position budget —
289
+ * not the snapshot taken when it was queued. If the free balance shrank after
290
+ * deferral the ceiling drops (no over-lock / on-chain failure); if it grew the
291
+ * ceiling rises (no unnecessary clamp). Entries without a released base —
292
+ * legacy ones and the collateral-switch flow, whose budget is the new asset's
293
+ * total balance, not freed collateral — keep their stored budget unchanged.
264
294
  */
265
- _computeReleasedCollateralInt(dealSummary: DealSummary | UnknownRecord | null, repayAmount: unknown, options: UnknownRecord): Promise<number | null>;
295
+ _refreshReborrowBudget(request: UnknownRecord | null): Promise<number | null>;
266
296
  /**
267
297
  * Decide how much of a maturing deal can actually be repaid and reborrowed
268
298
  * with the currently free debt-asset balance. The repay leg is funded from
@@ -145,6 +145,13 @@ function isPercentageAmountSpec(spec) {
145
145
  const normalized = normalizeAmountSpec(spec);
146
146
  return typeof normalized?.amount === 'string' && normalized.amount.trim().endsWith('%');
147
147
  }
148
+ /**
149
+ * Whether a credit-offer policy should top a renewal's collateral budget up from
150
+ * the borrower's free balance. Default `true`; only an explicit `false` opts out.
151
+ */
152
+ function resolveUseFreeCollateral(policy) {
153
+ return policy?.useFreeCollateral !== false;
154
+ }
148
155
  function getAccountRef(bot) {
149
156
  return bot?.accountId
150
157
  || bot?.account?.id
@@ -1601,8 +1608,16 @@ class CreditRuntime {
1601
1608
  requiredCollateralInt = collateralSpec?.amount !== null && collateralSpec?.amount !== undefined
1602
1609
  ? await this._resolveAmountToBlockchainInt(collateralSpec, collateralAsset, accountId, { balanceField: 'total', referenceAmount: collateralReferenceAmount, referenceLabel: 'total collateral balance' })
1603
1610
  : minimumCollateralInt;
1611
+ // An explicit collateral amount (e.g. the deal's old collateral on a
1612
+ // renewal) acts as a floor: when the offer price moved against the
1613
+ // collateral and the budget (released + free collateral) allows it,
1614
+ // top it up to what the borrow actually requires instead of failing
1615
+ // or under-borrowing.
1616
+ if (hasCollateralBudget && minimumCollateralInt != null && requiredCollateralInt != null && requiredCollateralInt < minimumCollateralInt) {
1617
+ requiredCollateralInt = minimumCollateralInt;
1618
+ }
1604
1619
  // An explicit collateral amount (e.g. a percentage spec) may still
1605
- // exceed the released budget; cap it so the op cannot over-lock. Do
1620
+ // exceed the budget; cap it so the op cannot over-lock. Do
1606
1621
  // NOT recompute the borrow here — it was already clamped above and
1607
1622
  // must never grow back past the requested amount.
1608
1623
  if (hasCollateralBudget && requiredCollateralInt != null && requiredCollateralInt > availableCollateralAmount) {
@@ -1826,14 +1841,29 @@ class CreditRuntime {
1826
1841
  let deferredReborrowRequest = null;
1827
1842
  let inlineReborrowPlanned = false;
1828
1843
  let availableReborrowCollateralInt = null;
1844
+ let releasedReborrowCollateralInt = null;
1829
1845
  // Snapshot the deals that already exist before this repay broadcasts.
1830
1846
  // A later pending reborrow can then distinguish a genuine replacement
1831
1847
  // (a deal that appeared after the repay) from a sibling deal that was
1832
1848
  // already present on the same offer and must not suppress the reborrow.
1833
1849
  const preRepayDealIds = this._collectActiveDealIds();
1834
1850
  if (shouldAutoReborrow) {
1835
- // Collateral this repay frees — the ceiling a reborrow may lock.
1836
- availableReborrowCollateralInt = await this._computeReleasedCollateralInt(dealSummary, repayAmount, options);
1851
+ // Collateral this repay frees — the baseline of the ceiling a
1852
+ // reborrow may lock. By default the borrower's free balance of the
1853
+ // same collateral is added to the budget so the reborrow can keep
1854
+ // the original principal when the offer's collateral price moved;
1855
+ // `useFreeCollateral: false` restores the released-only ceiling.
1856
+ const useFreeCollateral = options.useFreeCollateral !== undefined
1857
+ ? options.useFreeCollateral === true
1858
+ : resolveUseFreeCollateral(reborrowPolicy);
1859
+ const offer = await this._getOfferById(dealSummary.offerId);
1860
+ const collateralBudget = await this._computeCollateralBudget(dealSummary, repayAmount, {
1861
+ ...options,
1862
+ useFreeCollateral,
1863
+ offer,
1864
+ });
1865
+ availableReborrowCollateralInt = collateralBudget.budget;
1866
+ releasedReborrowCollateralInt = collateralBudget.released;
1837
1867
  const reborrowAmount = options.reborrowAmount !== undefined && options.reborrowAmount !== null
1838
1868
  ? options.reborrowAmount
1839
1869
  : repayAmount;
@@ -1869,7 +1899,6 @@ class CreditRuntime {
1869
1899
  const autoRepaySetting = (options.autoRepay !== undefined
1870
1900
  ? options.autoRepay
1871
1901
  : (policyHasAutoRepay ? reborrowPolicy.autoRepay : (dealSummary.autoRepay ?? false)));
1872
- const offer = await this._getOfferById(dealSummary.offerId);
1873
1902
  const selectFallbackReborrow = async (deferReason, selectionNote) => {
1874
1903
  const fallback = await this._selectFallbackCreditOffer({
1875
1904
  debtAssetId: dealSummary.debtAssetId,
@@ -1898,6 +1927,10 @@ class CreditRuntime {
1898
1927
  specificPolicy: reborrowPolicy,
1899
1928
  preRepayDealIds,
1900
1929
  availableCollateralAmount: availableReborrowCollateralInt,
1930
+ releasedCollateralAmount: releasedReborrowCollateralInt,
1931
+ useFreeCollateral,
1932
+ collateralAssetId: effectiveCollateralAssetId,
1933
+ debtAssetId: dealSummary.debtAssetId,
1901
1934
  pendingRepayAmount: repayAmount,
1902
1935
  pendingReleaseCollateralAmount: options.pendingReleaseCollateralAmount,
1903
1936
  requestedAt: nowIso(),
@@ -1934,6 +1967,10 @@ class CreditRuntime {
1934
1967
  await this.refreshState();
1935
1968
  if (shouldAutoReborrow && !inlineReborrowPlanned && !sourceDealStillActive) {
1936
1969
  const reborrowOffer = await this._getOfferById(dealSummary.offerId);
1970
+ const fallbackUseFreeCollateral = options.useFreeCollateral !== undefined
1971
+ ? options.useFreeCollateral === true
1972
+ : resolveUseFreeCollateral(reborrowPolicy);
1973
+ const fallbackCollateralAssetId = options.collateralAsset ?? dealSummary.collateralAssetId ?? null;
1937
1974
  const reborrowRequest = deferredReborrowRequest || {
1938
1975
  sourceDealId: dealSummary.id,
1939
1976
  offerId: dealSummary.offerId,
@@ -1949,6 +1986,10 @@ class CreditRuntime {
1949
1986
  specificPolicy: reborrowPolicy,
1950
1987
  preRepayDealIds,
1951
1988
  availableCollateralAmount: availableReborrowCollateralInt,
1989
+ releasedCollateralAmount: releasedReborrowCollateralInt,
1990
+ useFreeCollateral: fallbackUseFreeCollateral,
1991
+ collateralAssetId: fallbackCollateralAssetId,
1992
+ debtAssetId: dealSummary.debtAssetId,
1952
1993
  pendingRepayAmount: repayAmount,
1953
1994
  pendingReleaseCollateralAmount: options.pendingReleaseCollateralAmount,
1954
1995
  requestedAt: nowIso(),
@@ -2006,6 +2047,10 @@ class CreditRuntime {
2006
2047
  specificPolicy: request.specificPolicy || null,
2007
2048
  preRepayDealIds: Array.isArray(request.preRepayDealIds) ? request.preRepayDealIds.map((id) => String(id)) : null,
2008
2049
  availableCollateralAmount: request.availableCollateralAmount ?? null,
2050
+ releasedCollateralAmount: request.releasedCollateralAmount ?? null,
2051
+ useFreeCollateral: request.useFreeCollateral !== false,
2052
+ collateralAssetId: request.collateralAssetId ?? null,
2053
+ debtAssetId: request.debtAssetId ?? null,
2009
2054
  reborrowAttempts: Number(request.reborrowAttempts) || 0,
2010
2055
  pendingRepayAmount: request.pendingRepayAmount ?? null,
2011
2056
  pendingReleaseCollateralAmount: request.pendingReleaseCollateralAmount ?? null,
@@ -2066,55 +2111,183 @@ class CreditRuntime {
2066
2111
  }
2067
2112
  }
2068
2113
  /**
2069
- * Raw collateral freed by a repay, used as the ceiling a reborrow can lock.
2070
- * Precedence:
2114
+ * Read the chain-free balance of a collateral asset. Mirrors
2115
+ * `_getFreeDebtAssetBalance`; returns null when it cannot be determined.
2116
+ */
2117
+ async _getFreeCollateralBalance(collateralAssetId, collateralAsset) {
2118
+ const accountRef = getAccountRef(this.bot);
2119
+ if (!accountRef || !collateralAssetId)
2120
+ return null;
2121
+ try {
2122
+ const balances = await chainOrders.getOnChainAssetBalances(accountRef, [String(collateralAssetId)]);
2123
+ const entry = this._pickOnChainBalanceEntry(balances, collateralAssetId, collateralAsset);
2124
+ const free = toFiniteNumber(entry?.free, NaN);
2125
+ return Number.isFinite(free) ? free : null;
2126
+ }
2127
+ catch (err) {
2128
+ this.warn(`credit runtime: unable to read free collateral balance for ${String(collateralAssetId)}: ${getErrorMessage(err)}`);
2129
+ return null;
2130
+ }
2131
+ }
2132
+ /**
2133
+ * Highest raw collateral this deal's position may hold, from the position's
2134
+ * `assignedCollateralBudget`. The renewed deal is one member of the
2135
+ * position, so its ceiling is the budget minus the collateral the position's
2136
+ * other deals already hold. Returns null when no budget is known.
2137
+ */
2138
+ _positionCollateralCapInt(dealSummary, collateralAsset, releasedInt) {
2139
+ const collateralPrecision = getAssetPrecision(collateralAsset);
2140
+ if (collateralPrecision === null || !collateralAsset?.id)
2141
+ return null;
2142
+ const posKey = this._positionKey(dealSummary?.debtAssetId, collateralAsset.id);
2143
+ const posState = this.state?.positions?.[posKey];
2144
+ const assignedBudget = positiveOrNull(posState?.assignedCollateralBudget);
2145
+ if (assignedBudget === null)
2146
+ return null;
2147
+ const deals = Array.isArray(posState?.creditDeals) ? posState.creditDeals : [];
2148
+ const positionCollateral = deals.reduce((sum, d) => sum + (blockchainAmountToFloat(d?.collateralAmount, collateralAsset) || 0), 0);
2149
+ const releasedFloat = blockchainToFloat(releasedInt, collateralPrecision);
2150
+ const otherLocked = Math.max(0, positionCollateral - releasedFloat);
2151
+ const headroom = Math.max(releasedFloat, assignedBudget - otherLocked);
2152
+ const capInt = floatToBlockchainInt(headroom, collateralPrecision);
2153
+ return Number.isFinite(capInt) && capInt > 0 ? capInt : null;
2154
+ }
2155
+ /**
2156
+ * Raw collateral available to a reborrow, as `{ released, budget }`:
2157
+ * - `released` — the portion freed by this repay (the collateral floor),
2158
+ * - `budget` — the ceiling the new accept may lock: the released portion
2159
+ * plus the borrower's free balance of the same asset (when
2160
+ * `useFreeCollateral` is on, the default), bounded by the
2161
+ * position's `assignedCollateralBudget`.
2162
+ * Precedence for `released`:
2071
2163
  * 1. explicit raw `options.availableCollateralAmount` (collateral-switch flow),
2072
2164
  * 2. exact on-chain `floor(repay * collateral / debt)` when the deal's own
2073
2165
  * collateral asset is used,
2074
2166
  * 3. explicit `options.pendingReleaseCollateralAmount` (float) as a fallback.
2075
- * Returns null when it cannot be determined, so the accept builder keeps the
2076
- * legacy (unclamped) behaviour.
2167
+ * Returns `{ released: null, budget: null }` when it cannot be determined, so
2168
+ * the accept builder keeps the legacy (unclamped) behaviour.
2077
2169
  */
2078
- async _computeReleasedCollateralInt(dealSummary, repayAmount, options) {
2079
- // 1. Explicit raw budget (collateral-switch flow) wins.
2170
+ async _computeCollateralBudget(dealSummary, repayAmount, options) {
2171
+ // 1. Explicit raw budget (collateral-switch flow) wins. Return no
2172
+ // `released` base: this snapshot is the account's total balance of the
2173
+ // new collateral, not collateral freed by a repay, so a deferred retry
2174
+ // must not add the free balance on top (double count). With a null
2175
+ // base, `_refreshReborrowBudget` reuses the stored budget unchanged.
2080
2176
  const explicitRaw = toFiniteNumber(options?.availableCollateralAmount, null);
2081
- if (explicitRaw !== null && explicitRaw > 0)
2082
- return Math.floor(explicitRaw);
2177
+ if (explicitRaw !== null && explicitRaw > 0) {
2178
+ return { released: null, budget: Math.floor(explicitRaw) };
2179
+ }
2083
2180
  const effectiveCollateralAssetId = options?.collateralAsset ?? dealSummary?.collateralAssetId ?? null;
2084
2181
  const dealCollateralAssetId = dealSummary?.collateralAssetId ?? null;
2085
2182
  const sameCollateralAsset = !dealCollateralAssetId || !effectiveCollateralAssetId
2086
2183
  || String(dealCollateralAssetId) === String(effectiveCollateralAssetId);
2184
+ if (!sameCollateralAsset)
2185
+ return { released: null, budget: null };
2186
+ const collateralAsset = effectiveCollateralAssetId ? await this._resolveAsset(effectiveCollateralAssetId) : null;
2187
+ const collateralPrecision = getAssetPrecision(collateralAsset);
2188
+ const collateralAssetId = effectiveCollateralAssetId ?? dealCollateralAssetId;
2189
+ const debtAsset = await this._resolveAsset(dealSummary?.debtAssetId);
2190
+ const debtPrecision = getAssetPrecision(debtAsset);
2087
2191
  // 2. Exact on-chain release: floor(repay * collateral / debt), matching
2088
2192
  // credit_deal_repay_evaluator::do_apply. Preferred over the float
2089
2193
  // fallback so the budget never over-states the freed collateral.
2090
- if (sameCollateralAsset) {
2091
- const debtAsset = await this._resolveAsset(dealSummary?.debtAssetId);
2092
- const debtPrecision = getAssetPrecision(debtAsset);
2093
- if (debtPrecision !== null) {
2094
- const repayInt = floatToBlockchainInt(repayAmount, debtPrecision);
2095
- const debtInt = toFiniteNumber(dealSummary?.debtAmount, 0);
2096
- const collateralInt = toFiniteNumber(dealSummary?.collateralAmount, 0);
2097
- if (Number.isFinite(repayInt) && repayInt > 0 && debtInt > 0 && collateralInt > 0) {
2098
- const released = Math.floor(collateralInt * Math.min(repayInt, debtInt) / debtInt);
2099
- if (released > 0)
2100
- return released;
2194
+ let released = null;
2195
+ if (debtPrecision !== null) {
2196
+ const repayInt = floatToBlockchainInt(repayAmount, debtPrecision);
2197
+ const debtInt = toFiniteNumber(dealSummary?.debtAmount, 0);
2198
+ const collateralInt = toFiniteNumber(dealSummary?.collateralAmount, 0);
2199
+ if (Number.isFinite(repayInt) && repayInt > 0 && debtInt > 0 && collateralInt > 0) {
2200
+ const value = Math.floor(collateralInt * Math.min(repayInt, debtInt) / debtInt);
2201
+ if (value > 0)
2202
+ released = value;
2203
+ }
2204
+ }
2205
+ // 3. Fallback when raw deal amounts are unavailable: use an explicit
2206
+ // released float, floored at the collateral precision.
2207
+ if ((released === null || released <= 0) && collateralPrecision !== null
2208
+ && options?.pendingReleaseCollateralAmount !== null && options?.pendingReleaseCollateralAmount !== undefined) {
2209
+ const explicitFloat = toFiniteNumber(options.pendingReleaseCollateralAmount, null);
2210
+ if (explicitFloat !== null && explicitFloat > 0) {
2211
+ const value = floorToBlockchainInt(explicitFloat, collateralPrecision);
2212
+ if (Number.isFinite(value) && value > 0)
2213
+ released = value;
2214
+ }
2215
+ }
2216
+ if (released === null || released <= 0)
2217
+ return { released: null, budget: null };
2218
+ let budget = released;
2219
+ if (options?.useFreeCollateral !== false && collateralPrecision !== null) {
2220
+ // Skip the chain read when the released collateral already backs the
2221
+ // requested reborrow at the offer price (no price move against us).
2222
+ let needsFree = true;
2223
+ const offer = options?.offer;
2224
+ const repayFloat = toFiniteNumber(repayAmount, null);
2225
+ // Compare against the actual reborrow, not the repay: a caller may
2226
+ // request a larger reborrow than it repays.
2227
+ const reborrowFloat = toFiniteNumber(options?.reborrowAmount, null) ?? repayFloat;
2228
+ if (offer && reborrowFloat !== null) {
2229
+ const collateralMap = normalizeCollateralMap(offer.acceptable_collateral);
2230
+ const offerRate = this._extractRateFromCollateralMap(collateralMap, String(collateralAssetId), debtAsset, collateralAsset);
2231
+ const releasedFloat = blockchainToFloat(released, collateralPrecision);
2232
+ if (offerRate !== null && releasedFloat > 0 && offerRate >= reborrowFloat / releasedFloat) {
2233
+ needsFree = false;
2101
2234
  }
2102
2235
  }
2103
- // 3. Fallback when raw deal amounts are unavailable: use an explicit
2104
- // released float, floored at the collateral precision.
2105
- if (options?.pendingReleaseCollateralAmount !== null && options?.pendingReleaseCollateralAmount !== undefined) {
2106
- const collateralAsset = effectiveCollateralAssetId ? await this._resolveAsset(effectiveCollateralAssetId) : null;
2107
- const collateralPrecision = getAssetPrecision(collateralAsset);
2108
- if (collateralPrecision === null)
2109
- return null;
2110
- const explicitFloat = toFiniteNumber(options.pendingReleaseCollateralAmount, null);
2111
- if (explicitFloat === null || explicitFloat <= 0)
2112
- return null;
2113
- const explicit = floorToBlockchainInt(explicitFloat, collateralPrecision);
2114
- return Number.isFinite(explicit) && explicit > 0 ? explicit : null;
2236
+ if (needsFree) {
2237
+ const free = await this._getFreeCollateralBalance(collateralAssetId, collateralAsset);
2238
+ if (free !== null) {
2239
+ const freeInt = floatToBlockchainInt(free, collateralPrecision);
2240
+ if (Number.isFinite(freeInt) && freeInt > 0)
2241
+ budget = released + freeInt;
2242
+ }
2115
2243
  }
2116
2244
  }
2117
- return null;
2245
+ // Never top up past the position's assigned collateral budget.
2246
+ const capInt = this._positionCollateralCapInt(dealSummary, collateralAsset, released);
2247
+ if (capInt !== null)
2248
+ budget = Math.min(budget, capInt);
2249
+ return { released, budget };
2250
+ }
2251
+ /**
2252
+ * Recompute a persisted pending reborrow's collateral budget from its stored
2253
+ * released base, the current free balance, and the current position budget —
2254
+ * not the snapshot taken when it was queued. If the free balance shrank after
2255
+ * deferral the ceiling drops (no over-lock / on-chain failure); if it grew the
2256
+ * ceiling rises (no unnecessary clamp). Entries without a released base —
2257
+ * legacy ones and the collateral-switch flow, whose budget is the new asset's
2258
+ * total balance, not freed collateral — keep their stored budget unchanged.
2259
+ */
2260
+ async _refreshReborrowBudget(request) {
2261
+ const stored = toFiniteNumber(request?.availableCollateralAmount, null);
2262
+ const released = toFiniteNumber(request?.releasedCollateralAmount, null);
2263
+ if (released === null || released <= 0)
2264
+ return stored;
2265
+ const assetId = request?.collateralAssetId ?? null;
2266
+ const asset = assetId ? await this._resolveAsset(assetId) : null;
2267
+ const precision = getAssetPrecision(asset);
2268
+ if (precision === null || !assetId)
2269
+ return stored ?? released;
2270
+ let budget = released;
2271
+ if (request?.useFreeCollateral !== false) {
2272
+ const free = await this._getFreeCollateralBalance(assetId, asset);
2273
+ if (free !== null) {
2274
+ const freeInt = floatToBlockchainInt(free, precision);
2275
+ if (Number.isFinite(freeInt) && freeInt > 0)
2276
+ budget = released + freeInt;
2277
+ }
2278
+ }
2279
+ // Re-derive the position ceiling from current state rather than the
2280
+ // queue-time snapshot; `_positionCollateralCapInt` floors at `released`.
2281
+ const debtAssetId = request?.debtAssetId ?? null;
2282
+ if (debtAssetId) {
2283
+ const capInt = this._positionCollateralCapInt({ debtAssetId }, asset, released);
2284
+ if (capInt !== null)
2285
+ budget = Math.min(budget, capInt);
2286
+ }
2287
+ else if (stored !== null) {
2288
+ budget = Math.min(budget, stored);
2289
+ }
2290
+ return budget;
2118
2291
  }
2119
2292
  /**
2120
2293
  * Decide how much of a maturing deal can actually be repaid and reborrowed
@@ -2687,6 +2860,7 @@ class CreditRuntime {
2687
2860
  }
2688
2861
  if (!offer || offer.enabled === false) {
2689
2862
  const fallbackIds = await this._resolveFallbackAssetIds(requestPolicy, offer);
2863
+ const effectiveReborrowBudget = await this._refreshReborrowBudget(request);
2690
2864
  const fallback = fallbackIds.debtAssetId && fallbackIds.collateralAssetId
2691
2865
  ? await this._selectFallbackCreditOffer({
2692
2866
  debtAssetId: fallbackIds.debtAssetId,
@@ -2696,7 +2870,7 @@ class CreditRuntime {
2696
2870
  collateralAmount: effectiveCollateralAmount,
2697
2871
  autoRepay: (request.autoRepay ?? false),
2698
2872
  pendingReleaseCollateralAmount: request.pendingReleaseCollateralAmount,
2699
- availableCollateralAmount: request.availableCollateralAmount ?? null,
2873
+ availableCollateralAmount: effectiveReborrowBudget,
2700
2874
  excludeOfferId: request.offerId,
2701
2875
  })
2702
2876
  : null;
@@ -2717,6 +2891,7 @@ class CreditRuntime {
2717
2891
  continue;
2718
2892
  }
2719
2893
  try {
2894
+ const effectiveReborrowBudget = await this._refreshReborrowBudget(request);
2720
2895
  const acceptOp = await this.buildCreditOfferAcceptOperation({
2721
2896
  offer,
2722
2897
  borrowAmount: request.borrowAmount ?? null,
@@ -2724,7 +2899,7 @@ class CreditRuntime {
2724
2899
  autoRepay: (request.autoRepay ?? false),
2725
2900
  specificPolicy: (request.specificPolicy || requestPolicy),
2726
2901
  pendingReleaseCollateralAmount: request.pendingReleaseCollateralAmount,
2727
- availableCollateralAmount: request.availableCollateralAmount ?? null,
2902
+ availableCollateralAmount: effectiveReborrowBudget,
2728
2903
  });
2729
2904
  await this.executeOperations([acceptOp], 'credit reborrow');
2730
2905
  processed++;
@@ -2943,8 +3118,13 @@ class CreditRuntime {
2943
3118
  ? this.state.pendingReborrows.filter((r) => r.sourceDealId === String(deal.id))
2944
3119
  : [];
2945
3120
  const staleKeys = new Set(staleSnapshot.map((r) => `${r.sourceDealId}:${r.offerId}:${r.requestedAt}`));
3121
+ const useFreeCollateral = resolveUseFreeCollateral(lendingItem);
2946
3122
  await this.repayCreditDeal(deal, renewalAmount, {
2947
3123
  autoReborrow: true,
3124
+ // The deal's old collateral is the floor; free collateral
3125
+ // (added to the budget by useFreeCollateral, on by
3126
+ // default) lets the accept builder top it up to what the
3127
+ // borrow requires instead of scaling the principal down.
2948
3128
  collateralAmount: isCollateralMismatch || isPartialRenewal ? null : {
2949
3129
  amount: existingCollateralAmount,
2950
3130
  assetId: deal.collateralAssetId,
@@ -2952,6 +3132,7 @@ class CreditRuntime {
2952
3132
  collateralAsset: configuredCollateralAssetId,
2953
3133
  pendingReleaseCollateralAmount: renewalPendingReleaseCollateral,
2954
3134
  availableCollateralAmount: explicitAvailableCollateralInt,
3135
+ useFreeCollateral,
2955
3136
  specificPolicy: lendingItem,
2956
3137
  });
2957
3138
  // Prune only the stale entries that existed before the call
@@ -69,6 +69,20 @@ import type { ChainOrderLike, CowResult, OpPhase } from './dexbot_cow_runtime.js
69
69
  import { normalizeBotEntry } from './bot_settings.js';
70
70
  import type { FillOpLike, FillLike, ReplaySafeFillAccountingOptions } from './dexbot_fill_runtime.js';
71
71
  import type { BotLike, AssetPair, IncomingFill, UnknownRecord, GridConfig, OrderManagerLike, AccountOrdersLike, BotMetrics, ProcessedFillStoreLike, CreditRuntimeLike, FillBatchResult, SigningToken, SpreadCorrectionStall } from './types.js';
72
+ /**
73
+ * Resolve the COALESCE_BACKLOG_REPLAY opt-in.
74
+ *
75
+ * Reads the bot config override first, then the manager config, then the
76
+ * frozen FILL_PROCESSING default (mirrors order/utils readFillProcessingNumber
77
+ * precedence). Accepts the literal boolean true, the string 'true', or 1.
78
+ * Default OFF, so the live boundary engine is unchanged unless an operator
79
+ * opts a bot in via `fillProcessing.COALESCE_BACKLOG_REPLAY`.
80
+ *
81
+ * @param {unknown} config - DEXBot config
82
+ * @param {unknown} managerConfig - OrderManager config (may differ in tests)
83
+ * @returns {boolean}
84
+ */
85
+ export declare function shouldCoalesceBacklogReplay(config: unknown, managerConfig: unknown): boolean;
72
86
  declare class DEXBot implements BotLike {
73
87
  static normalizeBotEntry: typeof normalizeBotEntry;
74
88
  config: GridConfig;
@@ -172,6 +186,7 @@ declare class DEXBot implements BotLike {
172
186
  _marketAdapterWatchdogInFlight: boolean;
173
187
  _outOfSpreadSince: number;
174
188
  _outOfSpreadStaleWarned: boolean;
189
+ _outOfSpreadTransientCount: number;
175
190
  _postRecoveryRebalanceDefers: number;
176
191
  _skipEmptyReadConfirmDelay: boolean;
177
192
  _spreadFundsExhausted: boolean;
@@ -1001,6 +1016,14 @@ declare class DEXBot implements BotLike {
1001
1016
  maxQueueDepth: number;
1002
1017
  gridLockContention: number;
1003
1018
  fundRecalcCount: number;
1019
+ refusedCommitCount: number;
1020
+ orphanFillCreditedCount: number;
1021
+ restampBuyAboveAnchorCount: number;
1022
+ boundaryDriftExceedsWindowCount: number;
1023
+ gapBandPlacementShadowCount: number;
1024
+ spreadCorrectionRefusedCount: number;
1025
+ spreadCorrectionRefusalCauses: Record<string, number>;
1026
+ spreadCorrectionRetryCount: number;
1004
1027
  };
1005
1028
  /**
1006
1029
  * Execute grid maintenance checks in strict order with pipeline consensus.