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
@@ -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
@@ -45,7 +45,9 @@
45
45
  * ===============================================================================
46
46
  *
47
47
  * HELPER FUNCTIONS (module-level):
48
- * - normalizeBotEntry() - Normalize bot configuration object
48
+ * - shouldCoalesceBacklogReplay(config, managerConfig) - Decide whether a
49
+ * startup backlog should be drained as one coalesced batch
50
+ * (bot-entry normalization lives in bot_settings.ts: normalizeBotEntry)
49
51
  *
50
52
  * ===============================================================================
51
53
  *
@@ -69,6 +71,20 @@ import type { ChainOrderLike, CowResult, OpPhase } from './dexbot_cow_runtime.js
69
71
  import { normalizeBotEntry } from './bot_settings.js';
70
72
  import type { FillOpLike, FillLike, ReplaySafeFillAccountingOptions } from './dexbot_fill_runtime.js';
71
73
  import type { BotLike, AssetPair, IncomingFill, UnknownRecord, GridConfig, OrderManagerLike, AccountOrdersLike, BotMetrics, ProcessedFillStoreLike, CreditRuntimeLike, FillBatchResult, SigningToken, SpreadCorrectionStall } from './types.js';
74
+ /**
75
+ * Resolve the COALESCE_BACKLOG_REPLAY opt-in.
76
+ *
77
+ * Reads the bot config override first, then the manager config, then the
78
+ * frozen FILL_PROCESSING default (mirrors order/utils readFillProcessingNumber
79
+ * precedence). Accepts the literal boolean true, the string 'true', or 1.
80
+ * Default OFF, so the live boundary engine is unchanged unless an operator
81
+ * opts a bot in via `fillProcessing.COALESCE_BACKLOG_REPLAY`.
82
+ *
83
+ * @param {unknown} config - DEXBot config
84
+ * @param {unknown} managerConfig - OrderManager config (may differ in tests)
85
+ * @returns {boolean}
86
+ */
87
+ export declare function shouldCoalesceBacklogReplay(config: unknown, managerConfig: unknown): boolean;
72
88
  declare class DEXBot implements BotLike {
73
89
  static normalizeBotEntry: typeof normalizeBotEntry;
74
90
  config: GridConfig;
@@ -172,6 +188,7 @@ declare class DEXBot implements BotLike {
172
188
  _marketAdapterWatchdogInFlight: boolean;
173
189
  _outOfSpreadSince: number;
174
190
  _outOfSpreadStaleWarned: boolean;
191
+ _outOfSpreadTransientCount: number;
175
192
  _postRecoveryRebalanceDefers: number;
176
193
  _skipEmptyReadConfirmDelay: boolean;
177
194
  _spreadFundsExhausted: boolean;
@@ -985,7 +1002,6 @@ declare class DEXBot implements BotLike {
985
1002
  * @returns {Object} Metrics snapshot
986
1003
  */
987
1004
  getMetrics(): {
988
- boundaryDriftExceedsWindowCount: number;
989
1005
  queueDepth: number;
990
1006
  fillProcessingLockActive: boolean;
991
1007
  divergenceLockActive: boolean;
@@ -1005,7 +1021,11 @@ declare class DEXBot implements BotLike {
1005
1021
  refusedCommitCount: number;
1006
1022
  orphanFillCreditedCount: number;
1007
1023
  restampBuyAboveAnchorCount: number;
1024
+ boundaryDriftExceedsWindowCount: number;
1008
1025
  gapBandPlacementShadowCount: number;
1026
+ spreadCorrectionRefusedCount: number;
1027
+ spreadCorrectionRefusalCauses: Record<string, number>;
1028
+ spreadCorrectionRetryCount: number;
1009
1029
  };
1010
1030
  /**
1011
1031
  * Execute grid maintenance checks in strict order with pipeline consensus.
@@ -45,7 +45,9 @@
45
45
  * ===============================================================================
46
46
  *
47
47
  * HELPER FUNCTIONS (module-level):
48
- * - normalizeBotEntry() - Normalize bot configuration object
48
+ * - shouldCoalesceBacklogReplay(config, managerConfig) - Decide whether a
49
+ * startup backlog should be drained as one coalesced batch
50
+ * (bot-entry normalization lives in bot_settings.ts: normalizeBotEntry)
49
51
  *
50
52
  * ===============================================================================
51
53
  *
@@ -81,8 +83,9 @@ import { path } from './path_api.js';
81
83
  import * as Format from './order/format.js';
82
84
  import cowRuntime from './dexbot_cow_runtime.js';
83
85
  import { ProcessedFillStore } from './order/processed_fill_store.js';
84
- import { TIMING, DAEMON_CODES, } from './constants.js';
86
+ import { TIMING, DAEMON_CODES, FILL_PROCESSING, } from './constants.js';
85
87
  import { normalizeBotEntry } from './bot_settings.js';
88
+ import { createDefaultBotMetrics } from './bot_defaults.js';
86
89
  import { getErrorMessage, getErrorCode } from './utils/errors.js';
87
90
  const waitForConnected = lazyShim('./bitshares_client', 'waitForConnected');
88
91
  const getKeyStore = lazyShim('./key_store', 'getKeyStore');
@@ -90,6 +93,26 @@ const hasExecutableActions = lazyShim('./order/utils/validate', 'hasExecutableAc
90
93
  const getRecalculateTriggerFile = lazyShim('./paths', 'getRecalculateTriggerFile');
91
94
  const cloneWeightDistribution = lazyShim('./order/utils/math', 'cloneWeightDistribution');
92
95
  const resolveBotRuntimeSettings = lazyShim('./runtime_settings', 'resolveBotRuntimeSettings');
96
+ /**
97
+ * Resolve the COALESCE_BACKLOG_REPLAY opt-in.
98
+ *
99
+ * Reads the bot config override first, then the manager config, then the
100
+ * frozen FILL_PROCESSING default (mirrors order/utils readFillProcessingNumber
101
+ * precedence). Accepts the literal boolean true, the string 'true', or 1.
102
+ * Default OFF, so the live boundary engine is unchanged unless an operator
103
+ * opts a bot in via `fillProcessing.COALESCE_BACKLOG_REPLAY`.
104
+ *
105
+ * @param {unknown} config - DEXBot config
106
+ * @param {unknown} managerConfig - OrderManager config (may differ in tests)
107
+ * @returns {boolean}
108
+ */
109
+ export function shouldCoalesceBacklogReplay(config, managerConfig) {
110
+ const pick = (c) => c?.fillProcessing?.COALESCE_BACKLOG_REPLAY;
111
+ const raw = pick(config)
112
+ ?? pick(managerConfig)
113
+ ?? FILL_PROCESSING?.COALESCE_BACKLOG_REPLAY;
114
+ return raw === true || raw === 'true' || raw === 1;
115
+ }
93
116
  class DEXBot {
94
117
  static normalizeBotEntry;
95
118
  config;
@@ -193,6 +216,7 @@ class DEXBot {
193
216
  _marketAdapterWatchdogInFlight;
194
217
  _outOfSpreadSince;
195
218
  _outOfSpreadStaleWarned;
219
+ _outOfSpreadTransientCount;
196
220
  _postRecoveryRebalanceDefers;
197
221
  _skipEmptyReadConfirmDelay;
198
222
  _spreadFundsExhausted;
@@ -247,6 +271,14 @@ class DEXBot {
247
271
  this._recentlyProcessedFills = this._processedFillStore.tracker;
248
272
  this._pendingProcessedFillWrites = this._processedFillStore.pendingWrites;
249
273
  this._incomingFillQueue = [];
274
+ // Out-of-spread persistence watchdog state (declared with `!` above):
275
+ // initialize explicitly so a fresh bot never reads `undefined` before
276
+ // the first maintenance tick. Values mirror the lazy fallbacks in
277
+ // trackOutOfSpreadStaleness.
278
+ this._lastSpreadStaleResyncAt = 0;
279
+ this._outOfSpreadSince = 0;
280
+ this._outOfSpreadStaleWarned = false;
281
+ this._outOfSpreadTransientCount = 0;
250
282
  this.logPrefix = options.logPrefix || '';
251
283
  this._credentialDaemonWatchdogInterval = null;
252
284
  this._credentialDaemonDown = false;
@@ -259,21 +291,9 @@ class DEXBot {
259
291
  // window, we skip the credit to avoid double-counting freed capital.
260
292
  this._staleCleanedOrderIds = new Map();
261
293
  this._staleCleanupRetentionMs = Math.max(this._fillDedupeWindowMs || 0, 5 * 60 * 1000);
262
- // Metrics for monitoring lock contention and fill processing
263
- this._metrics = {
264
- fillsProcessed: 0,
265
- fillProcessingTimeMs: 0,
266
- batchesExecuted: 0,
267
- lockContentionEvents: 0,
268
- gridLockContention: 0,
269
- fundRecalcCount: 0,
270
- maxQueueDepth: 0,
271
- refusedCommitCount: 0,
272
- orphanFillCreditedCount: 0,
273
- restampBuyAboveAnchorCount: 0,
274
- boundaryDriftExceedsWindowCount: 0,
275
- gapBandPlacementShadowCount: 0
276
- };
294
+ // Metrics for monitoring lock contention and fill processing. Shared
295
+ // counters come from the central factory; the bot adds none of its own.
296
+ this._metrics = createDefaultBotMetrics();
277
297
  // Shutdown state
278
298
  this._shuttingDown = false;
279
299
  this._shutdownPromise = null;
@@ -1063,8 +1083,14 @@ class DEXBot {
1063
1083
  const managerLog = this.manager?.logger?.log?.bind(this.manager.logger) || (() => { });
1064
1084
  const maxBatch = this._getMaxFillBatchSize();
1065
1085
  const totalFills = fillList.length;
1066
- const useUnifiedPlan = totalFills <= maxBatch;
1067
- const modeLabel = useUnifiedPlan ? 'unified' : 'chunked';
1086
+ // P5 (Stale-Restart #5): optionally coalesce a backlog into a single
1087
+ // reconcile instead of a chunked replay that mutates the boundary
1088
+ // between broadcasts. Default OFF (opt-in) — see
1089
+ // shouldCoalesceBacklogReplay for the override precedence.
1090
+ const coalesceBacklog = totalFills > maxBatch
1091
+ && shouldCoalesceBacklogReplay(this.config, this.manager?.config);
1092
+ const useUnifiedPlan = totalFills <= maxBatch || coalesceBacklog;
1093
+ const modeLabel = coalesceBacklog ? 'coalesced' : (useUnifiedPlan ? 'unified' : 'chunked');
1068
1094
  managerLog(`Processing ${totalFills} filled orders (${modeLabel}, baseBatch=${useUnifiedPlan ? totalFills : maxBatch})...`, 'info');
1069
1095
  // NOTE: the LAST-FILL guard pivot is recorded per chunk inside the loop
1070
1096
  // below (not once per cycle): a multi-fill cycle broadcasts chunks
@@ -2072,12 +2098,26 @@ class DEXBot {
2072
2098
  }
2073
2099
  }
2074
2100
  }
2075
- // Log final metrics
2101
+ // Log final metrics. Spread-correction refusals are surfaced
2102
+ // separately from refusedCommitCount (the generic post-broadcast commit
2103
+ // refusals) so an operator can tell a commit-guard rejection apart from
2104
+ // a stale-plan / collision / update-target-missing refusal. Only shown
2105
+ // when any occurred, to keep the common-case line short.
2076
2106
  const metrics = this.getMetrics();
2107
+ const spreadRefusals = Number(metrics.spreadCorrectionRefusedCount) || 0;
2108
+ const refusalBreakdown = Object.entries(metrics.spreadCorrectionRefusalCauses || {})
2109
+ .map(([cause, count]) => `${cause}=${count}`)
2110
+ .join(', ');
2111
+ const refusalSuffix = spreadRefusals > 0
2112
+ ? `, spreadCorrectionRefusals=${spreadRefusals}` +
2113
+ (refusalBreakdown ? ` [${refusalBreakdown}]` : '') +
2114
+ `, spreadCorrectionRetries=${Number(metrics.spreadCorrectionRetryCount) || 0}`
2115
+ : '';
2077
2116
  this._log(`Shutdown complete. Final metrics: fills=${metrics.fillsProcessed}, batches=${metrics.batchesExecuted}, ` +
2078
2117
  `avgProcessingTime=${metrics.fillsProcessed > 0 ? Format.formatMetric2(metrics.fillProcessingTimeMs / metrics.fillsProcessed) : 0}ms, ` +
2079
2118
  `lockContentions=${metrics.lockContentionEvents}, maxQueueDepth=${metrics.maxQueueDepth}, ` +
2080
- `heldChainOrders=${metrics.heldChainOrders ?? 0}, blockingChainOrders=${metrics.blockingChainOrders ?? 0}`);
2119
+ `heldChainOrders=${metrics.heldChainOrders ?? 0}, blockingChainOrders=${metrics.blockingChainOrders ?? 0}` +
2120
+ refusalSuffix);
2081
2121
  await this.manager?.logger?.flush?.();
2082
2122
  }
2083
2123
  }