dexbot 1.6.15 → 1.6.17

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 (130) hide show
  1. package/CHANGELOG.md +52 -0
  2. package/README.md +4 -4
  3. package/analysis/tradingview/README.md +2 -2
  4. package/analysis/trend_detection/DYNAMIC_WEIGHT_RESEARCH.md +1 -1
  5. package/claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md +3 -2
  6. package/claw/modules/chain_queries.ts +3 -3
  7. package/claw/package.json +1 -1
  8. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  9. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  10. package/dist/analysis/ama_fitting/analyze_lambda_vs_slow.js +5 -3
  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/grid_reset_sim.js +1 -1
  20. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.d.ts +2 -1
  21. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +23 -9
  22. package/dist/analysis/trend_detection/backtest_ama_slope_huber.js +1 -1
  23. package/dist/analysis/trend_detection/dynamic_weight_chart_generator.js +21 -2
  24. package/dist/analysis/trend_detection/kalman_chart_generator.js +1 -0
  25. package/dist/analysis/trend_detection/regime_chart_generator.js +1 -1
  26. package/dist/analysis/trend_detection/volatility_chart_generator.js +1 -0
  27. package/dist/dexbot.js +89 -138
  28. package/dist/market_adapter/inputs/fetch_book_data.js +36 -12
  29. package/dist/market_adapter/inputs/fetch_lp_data.d.ts +6 -0
  30. package/dist/market_adapter/inputs/fetch_lp_data.js +65 -19
  31. package/dist/market_adapter/inputs/kibana_feed_source.js +45 -12
  32. package/dist/market_adapter/inputs/window_cache.d.ts +14 -1
  33. package/dist/market_adapter/inputs/window_cache.js +53 -17
  34. package/dist/market_adapter/lp_chart_core.js +1 -0
  35. package/dist/market_adapter/utils/chain.js +4 -3
  36. package/dist/market_adapter/utils/pair_orientation.d.ts +60 -0
  37. package/dist/market_adapter/utils/pair_orientation.js +142 -0
  38. package/dist/modules/account_bots.d.ts +40 -3
  39. package/dist/modules/account_bots.js +77 -37
  40. package/dist/modules/account_orders.d.ts +4 -1
  41. package/dist/modules/account_orders.js +4 -1
  42. package/dist/modules/bitshares-native/resolvers.js +3 -3
  43. package/dist/modules/bitshares_client.d.ts +12 -10
  44. package/dist/modules/bitshares_client.js +12 -10
  45. package/dist/modules/bot_settings.js +3 -3
  46. package/dist/modules/chain_keys.d.ts +6 -2
  47. package/dist/modules/chain_keys.js +5 -1
  48. package/dist/modules/chain_orders.d.ts +6 -2
  49. package/dist/modules/chain_orders.js +6 -2
  50. package/dist/modules/constants.d.ts +11 -0
  51. package/dist/modules/constants.js +41 -7
  52. package/dist/modules/credit_pricing.d.ts +20 -1
  53. package/dist/modules/credit_pricing.js +23 -1
  54. package/dist/modules/credit_runtime.js +33 -16
  55. package/dist/modules/dexbot_class.d.ts +6 -2
  56. package/dist/modules/dexbot_class.js +8 -3
  57. package/dist/modules/dexbot_cow_runtime.d.ts +28 -37
  58. package/dist/modules/dexbot_cow_runtime.js +47 -66
  59. package/dist/modules/dexbot_maintenance_runtime.js +68 -10
  60. package/dist/modules/graceful_shutdown.d.ts +6 -2
  61. package/dist/modules/graceful_shutdown.js +6 -2
  62. package/dist/modules/launcher/bot_supervisor.js +4 -0
  63. package/dist/modules/launcher/credential_daemon.d.ts +14 -2
  64. package/dist/modules/launcher/credential_daemon.js +60 -26
  65. package/dist/modules/launcher/launch_modes.js +6 -3
  66. package/dist/modules/launcher/monolithic_runtime.d.ts +39 -1
  67. package/dist/modules/launcher/monolithic_runtime.js +60 -1
  68. package/dist/modules/launcher/runtime_mode.d.ts +79 -0
  69. package/dist/modules/launcher/runtime_mode.js +223 -0
  70. package/dist/modules/market_adapter_whitelist.d.ts +8 -0
  71. package/dist/modules/market_adapter_whitelist.js +8 -0
  72. package/dist/modules/order/accounting.d.ts +15 -1
  73. package/dist/modules/order/accounting.js +15 -1
  74. package/dist/modules/order/async_lock.d.ts +9 -3
  75. package/dist/modules/order/async_lock.js +9 -3
  76. package/dist/modules/order/export.d.ts +0 -5
  77. package/dist/modules/order/export.js +0 -5
  78. package/dist/modules/order/format.d.ts +6 -4
  79. package/dist/modules/order/format.js +6 -4
  80. package/dist/modules/order/grid.d.ts +36 -18
  81. package/dist/modules/order/grid.js +186 -33
  82. package/dist/modules/order/index.d.ts +16 -1
  83. package/dist/modules/order/index.js +1 -1
  84. package/dist/modules/order/logger_state.d.ts +1 -1
  85. package/dist/modules/order/logger_state.js +1 -1
  86. package/dist/modules/order/manager.d.ts +30 -7
  87. package/dist/modules/order/manager.js +108 -12
  88. package/dist/modules/order/strategy.d.ts +5 -0
  89. package/dist/modules/order/strategy.js +23 -2
  90. package/dist/modules/order/sync_engine.d.ts +26 -11
  91. package/dist/modules/order/sync_engine.js +26 -11
  92. package/dist/modules/order/utils/math.d.ts +100 -22
  93. package/dist/modules/order/utils/math.js +106 -22
  94. package/dist/modules/order/utils/order.d.ts +77 -20
  95. package/dist/modules/order/utils/order.js +125 -27
  96. package/dist/modules/order/utils/system.d.ts +107 -11
  97. package/dist/modules/order/utils/system.js +176 -11
  98. package/dist/modules/order/utils/validate.d.ts +8 -3
  99. package/dist/modules/order/utils/validate.js +10 -3
  100. package/dist/modules/types.d.ts +35 -2
  101. package/dist/modules/utils/asset_symbols.d.ts +5 -5
  102. package/dist/modules/utils/asset_symbols.js +5 -5
  103. package/dist/modules/utils/errors.d.ts +2 -1
  104. package/dist/modules/utils/errors.js +2 -1
  105. package/dist/scripts/analyze-credit.js +64 -23
  106. package/dist/scripts/bts_distribution.d.ts +66 -0
  107. package/dist/scripts/bts_distribution.js +2102 -0
  108. package/dist/scripts/rich_list.d.ts +32 -0
  109. package/dist/scripts/rich_list.js +16 -8
  110. package/dist/scripts/token_distribution.d.ts +45 -0
  111. package/dist/scripts/token_distribution.js +1870 -0
  112. package/dist/unlock.js +91 -42
  113. package/docs/BITSHARES_ONBOARDING.md +7 -0
  114. package/docs/COW_INVARIANTS.md +7 -1
  115. package/docs/DEXBOT_COMPARISON.md +5 -5
  116. package/docs/EVOLUTION.md +10 -8
  117. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +5 -3
  118. package/docs/GRID_PRICE_INVARIANT.md +6 -0
  119. package/docs/GRID_RECALCULATION.md +18 -6
  120. package/docs/LIFECYCLE.md +8 -8
  121. package/docs/LOGGING.md +9 -0
  122. package/docs/MPA_CREDIT_USAGE.md +3 -2
  123. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +121 -4
  124. package/docs/README.md +1 -1
  125. package/docs/WORKFLOW.md +5 -5
  126. package/docs/architecture.md +98 -1
  127. package/market_adapter/README.md +10 -3
  128. package/package.json +5 -1
  129. package/scripts/README.md +85 -148
  130. package/tests/README.md +29 -0
@@ -111,7 +111,7 @@ class COWRebalanceEngine {
111
111
  fills,
112
112
  currentBoundaryIdx: boundaryIdx
113
113
  };
114
- const { targetGrid, boundaryIdx: targetBoundary } = this.strategy.calculateTargetGrid(strategyParams);
114
+ const { targetGrid, boundaryIdx: targetBoundary, consumedCrawlIds } = this.strategy.calculateTargetGrid(strategyParams);
115
115
  // P4 / unanchored plan: the strategy returns a null boundary paired
116
116
  // with an EMPTY target grid only when no numeric center exists to
117
117
  // recover from (e.g. GRID-LOAD rejected the persisted boundary AND
@@ -297,7 +297,8 @@ class COWRebalanceEngine {
297
297
  workingGrid,
298
298
  workingBoundary: targetBoundary,
299
299
  planningDuration: duration,
300
- refillSlotIds
300
+ refillSlotIds,
301
+ consumedCrawlIds
301
302
  }),
302
303
  evacReady
303
304
  };
@@ -1712,13 +1713,100 @@ class OrderManager {
1712
1713
  *
1713
1714
  * @param {string} reason - Log/debug label for the drop
1714
1715
  */
1715
- _clearPendingFillCrawls(reason = 'unspecified') {
1716
+ /**
1717
+ * Drop ALL owed fill-crawl records.
1718
+ *
1719
+ * This is the explicit allowed-loss path: the grid generation is being
1720
+ * discarded (rebuild, rejected snapshot, restart replay), so the relative
1721
+ * deltas no longer have a geometry to apply onto.
1722
+ */
1723
+ _clearPendingFillCrawls(reason = 'unspecified', detail = '') {
1716
1724
  if (!Array.isArray(this._pendingFillCrawls) || this._pendingFillCrawls.length === 0)
1717
1725
  return;
1718
- const count = this._pendingFillCrawls.length;
1726
+ const dropped = this._pendingFillCrawls;
1727
+ const count = dropped.length;
1728
+ // Side split + age are the two facts needed to tell "the derivation
1729
+ // folded and applied this crawl" from "the commit cleared a crawl the
1730
+ // derivation never consumed" after the fact: a same-sign, same-age run
1731
+ // that did NOT move the boundary accordingly is the second case (the
1732
+ // 2026-10-25 sweep: 7 fills, boundary 148 -> 146, 7 crawls dropped).
1733
+ let buys = 0;
1734
+ let sells = 0;
1735
+ let oldestTs = 0;
1736
+ for (const e of dropped) {
1737
+ if (!e)
1738
+ continue;
1739
+ if (e.side === ORDER_TYPES.BUY)
1740
+ buys++;
1741
+ else if (e.side === ORDER_TYPES.SELL)
1742
+ sells++;
1743
+ const ts = Number(e.ts);
1744
+ if (Number.isFinite(ts) && ts > 0 && (oldestTs === 0 || ts < oldestTs))
1745
+ oldestTs = ts;
1746
+ }
1747
+ const oldestAgeS = oldestTs > 0 ? Math.max(0, Math.round((Date.now() - oldestTs) / 1000)) : null;
1719
1748
  this._pendingFillCrawls = [];
1720
1749
  this._markGridDirty();
1721
- this.logger?.log?.(`[BOUNDARY] Dropped ${count} owed fill crawl(s) (${reason})`, 'debug');
1750
+ this.logger?.log?.(`[BOUNDARY] Dropped ${count} owed fill crawl(s) (${reason}): ` +
1751
+ `buy=${buys} sell=${sells} net=${sells - buys}` +
1752
+ `${oldestAgeS == null ? '' : ` oldest=${oldestAgeS}s`}` +
1753
+ `${detail ? ` ${detail}` : ''}`, 'debug');
1754
+ }
1755
+ /**
1756
+ * Consume the owed fill-crawl records a derivation actually folded.
1757
+ *
1758
+ * A boundary commit must never clear a record it could not apply: a
1759
+ * truncated cross-chunk shift, an edge-classified slot of an older
1760
+ * generation, or a record re-written for the same slot after the
1761
+ * derivation ran. Clearing all of them was the last way a fill's crawl
1762
+ * could be lost silently (2026-10-25: 7 fills swept slots 147-153, the
1763
+ * commits dropped every record and the boundary ended 7 levels behind).
1764
+ *
1765
+ * `consumed` is the derivation's `consumedCrawlIds`; absent/not-an-array
1766
+ * means the plan never derived a boundary (e.g. a create-only correction),
1767
+ * so NOTHING is consumed. Records are matched by `slotId` + `ts`, so a
1768
+ * newer record for the same slot survives a stale consumption.
1769
+ */
1770
+ _consumePendingFillCrawls(consumed, reason = 'boundary commit', detail = '') {
1771
+ if (!Array.isArray(this._pendingFillCrawls) || this._pendingFillCrawls.length === 0)
1772
+ return;
1773
+ const before = this._pendingFillCrawls;
1774
+ if (!Array.isArray(consumed)) {
1775
+ this.logger?.log?.(`[BOUNDARY] Kept ${before.length} owed fill crawl(s) unconsumed (${reason})` +
1776
+ `${detail ? `: ${detail}` : ''} — a later derivation still owes them`, 'debug');
1777
+ return;
1778
+ }
1779
+ const key = (e) => {
1780
+ const ts = Number(e?.ts);
1781
+ return `${String(e?.slotId ?? '')}|${Number.isFinite(ts) ? ts : '*'}`;
1782
+ };
1783
+ const consumedKeys = new Set(consumed
1784
+ .filter((e) => !!e
1785
+ && typeof e.slotId === 'string'
1786
+ && (e.slotId).length > 0)
1787
+ .map(key));
1788
+ const dropped = before.filter((e) => consumedKeys.has(key(e)));
1789
+ if (dropped.length === 0) {
1790
+ this.logger?.log?.(`[BOUNDARY] Kept ${before.length} owed fill crawl(s) unconsumed (${reason})` +
1791
+ `${detail ? `: ${detail}` : ''} — a later derivation still owes them`, 'debug');
1792
+ return;
1793
+ }
1794
+ const kept = before.filter((e) => !consumedKeys.has(key(e)));
1795
+ const buys = dropped.filter((e) => e?.side === ORDER_TYPES.BUY).length;
1796
+ const sells = dropped.filter((e) => e?.side === ORDER_TYPES.SELL).length;
1797
+ let oldestTs = 0;
1798
+ for (const e of dropped) {
1799
+ const ts = Number(e?.ts);
1800
+ if (Number.isFinite(ts) && ts > 0 && (oldestTs === 0 || ts < oldestTs))
1801
+ oldestTs = ts;
1802
+ }
1803
+ const oldestAgeS = oldestTs > 0 ? Math.max(0, Math.round((Date.now() - oldestTs) / 1000)) : null;
1804
+ this._pendingFillCrawls = kept;
1805
+ this._markGridDirty();
1806
+ this.logger?.log?.(`[BOUNDARY] Dropped ${dropped.length} owed fill crawl(s) (${reason}): ` +
1807
+ `buy=${buys} sell=${sells} net=${sells - buys}` +
1808
+ `${oldestAgeS == null ? '' : ` oldest=${oldestAgeS}s`} kept=${kept.length}` +
1809
+ `${detail ? ` ${detail}` : ''}`, 'debug');
1722
1810
  }
1723
1811
  /**
1724
1812
  * Observability (fix #4, docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md §2): emit the live
@@ -1803,12 +1891,12 @@ class OrderManager {
1803
1891
  }
1804
1892
  /**
1805
1893
  * Record last filled price for the single-pivot guard: when armed, BOTH
1806
- * sides are gated against the most recent fill price (BUY blocked above
1807
- * pivot*(1-halfInc), SELL blocked below pivot*(1+halfInc); see
1808
- * isLastFillGuardBlocked). Spread-correction bypasses. _lastFilledType is
1809
- * purely the cold/armed discriminator (null => disabled). The per-side
1810
- * fields are not read by the guard itself; they feed the book-seed
1811
- * cold-check and per-side seeding in seedLastFilledPricesFromBook.
1894
+ * sides are gated by the direction rule against the most recent fill price
1895
+ * (BUY blocked at/above the pivot, SELL blocked at/below it; see
1896
+ * isLastFillGuardBlocked). _lastFilledType is purely the cold/armed
1897
+ * discriminator (null => disabled). The per-side fields are not read by the
1898
+ * guard itself; they feed the book-seed cold-check and per-side seeding in
1899
+ * seedLastFilledPricesFromBook.
1812
1900
  * @param {Array} fills
1813
1901
  */
1814
1902
  recordLastFilledPrices(fills) {
@@ -2432,7 +2520,15 @@ class OrderManager {
2432
2520
  // left for the next derivation, holes refilled same-side).
2433
2521
  if (boundaryCheck.ok && commitBoundary !== null && commitBoundary !== undefined
2434
2522
  && boundaryHeld !== true) {
2435
- this._clearPendingFillCrawls('boundary commit');
2523
+ // Carry the boundary delta into the drop log: a crawl whose
2524
+ // net direction the commit did NOT honor is the ledger-leak
2525
+ // signature (see _clearPendingFillCrawls). Observability
2526
+ // only — the clear itself is unchanged pending that evidence.
2527
+ const prevBoundary = this.boundaryIdx;
2528
+ // Scope the drop to what the plan's derivation folded: a
2529
+ // record it could not apply (truncated shift, edge slot,
2530
+ // re-recorded slot) stays owed for the next derivation.
2531
+ this._consumePendingFillCrawls(options?.consumedCrawlIds, 'boundary commit', `boundary ${prevBoundary ?? 'null'} -> ${commitBoundary}`);
2436
2532
  }
2437
2533
  this._gridVersion++;
2438
2534
  committed = true;
@@ -156,6 +156,11 @@ declare class StrategyEngine {
156
156
  }): {
157
157
  targetGrid: Map<any, any>;
158
158
  boundaryIdx: number | null;
159
+ consumedCrawlIds?: undefined;
160
+ } | {
161
+ targetGrid: Map<string, ManagedOrder>;
162
+ boundaryIdx: number;
163
+ consumedCrawlIds: import("./utils/order.js").CrawlEntry[];
159
164
  };
160
165
  }
161
166
  export default StrategyEngine;
@@ -50,6 +50,7 @@ import { ORDER_TYPES, ORDER_STATES } from '../constants.js';
50
50
  import { calculateGapSlots } from './grid.js';
51
51
  import { isSlotInRail } from './utils/math.js';
52
52
  import { deriveTargetBoundary, getSideBudget, calculateBudgetedSizes, getCoreOrdersTotal, resolveEdgeCount, resolveLiveEdgeAnchorPrice, selectEdgeSlots, isShiftEligibleFill } from './utils/order.js';
53
+ import { reanchorBoundaryFromLastFill } from './utils/system.js';
53
54
  import { assignGridRoles } from './utils/order.js';
54
55
  import { convertToSpreadPlaceholder, toRailHolePlaceholder, geometryTypeForSlotIndex, parseSlotIndex, hasOnChainId, isOrderPlaced } from "./utils/order.js";
55
56
  class StrategyEngine {
@@ -259,10 +260,25 @@ class StrategyEngine {
259
260
  buy: resolveLiveEdgeAnchorPrice(this.manager, 'buy'),
260
261
  sell: resolveLiveEdgeAnchorPrice(this.manager, 'sell'),
261
262
  };
262
- const { boundaryIdx: newBoundaryIdx, remainingBudget } = deriveTargetBoundary(fills, currentBoundaryIdx, allSlots, boundaryConfig, gapSlots, crossChunkBudget, this.manager._pendingFillCrawls, edgeAnchors);
263
+ let { boundaryIdx: newBoundaryIdx, remainingBudget, consumedCrawlIds } = deriveTargetBoundary(fills, currentBoundaryIdx, allSlots, boundaryConfig, gapSlots, crossChunkBudget, this.manager._pendingFillCrawls, edgeAnchors);
263
264
  if (crossChunkBudget != null) {
264
265
  this.manager._boundaryShiftBudget = remainingBudget;
265
266
  }
267
+ // GEOMETRY RE-ANCHOR: the crawl is +-1 slot per committed fill, so a
268
+ // window that ended up BEHIND the newest real fill can never catch up —
269
+ // every tightening slot on that side is then at/through the fill and the
270
+ // last-fill guard refuses all of them while the funds sit in the resting
271
+ // inventory. The fill is the anchor: place it outside its own window.
272
+ // Validated like a boundary commit (strands no live in-band order), and
273
+ // only for an on-ladder fill price.
274
+ const reanchor = reanchorBoundaryFromLastFill(this.manager, newBoundaryIdx, allSlots, gapSlots);
275
+ if (reanchor.reanchored) {
276
+ newBoundaryIdx = reanchor.boundaryIdx;
277
+ try {
278
+ this.manager._markGridDirty?.();
279
+ }
280
+ catch { /* best-effort */ }
281
+ }
266
282
  // Unanchorable (null boundary, no numeric center anywhere): refuse to
267
283
  // plan rotations on fabricated geometry. The COW engine routes this
268
284
  // to a structural resync instead.
@@ -417,7 +433,12 @@ class StrategyEngine {
417
433
  });
418
434
  return {
419
435
  targetGrid: targetGrid,
420
- boundaryIdx: newBoundaryIdx
436
+ boundaryIdx: newBoundaryIdx,
437
+ // Records whose shift this derivation actually folded. The commit
438
+ // clears ONLY these, so a record it could not apply (truncated
439
+ // shift, edge classification, a newer record for the same slot)
440
+ // stays owed instead of vanishing with the commit.
441
+ consumedCrawlIds
421
442
  };
422
443
  }
423
444
  }
@@ -15,12 +15,17 @@
15
15
  * Uses AsyncLock to prevent concurrent sync operations (defense-in-depth locking).
16
16
  *
17
17
  * ===============================================================================
18
- * TABLE OF CONTENTS - SyncEngine Class (8 methods) + 1 module-level helper
18
+ * TABLE OF CONTENTS - SyncEngine Class (12 methods) + module-level helpers
19
19
  * ===============================================================================
20
20
  *
21
- * MODULE-LEVEL HELPER (internal, not exported):
22
- * hasEquivalentRawOnChainOrder(a, b) - Compare two chain orders for equivalence
23
- * Used internally during sync to detect redundant/duplicate chain entries
21
+ * MODULE-LEVEL HELPERS (internal, not exported):
22
+ * readSingleOrderSeam / batchReadOrdersSeam - Chain-order read indirection seams
23
+ * confirmSuspectEmptyRead(mgr) - Re-read after a suspicious empty snapshot
24
+ * describeNearestAdoptionCandidates(mgr, chainOrder, precision, matchedIds) -
25
+ * Diagnostic candidates for nearest-slot adoption
26
+ * chainPriceOnSameLevel(...) - Chain price vs a grid level under precision rules
27
+ * adoptedSlotKeepsItsOwnPrice(mgr, adopted, chainOrderId, path) - Adoption guard
28
+ * adoptChainOrderIntoSlot(...) - Adopt an unmatched chain order into a free slot
24
29
  *
25
30
  * INITIALIZATION (1 method)
26
31
  * 1. constructor(manager) - Create new SyncEngine with manager reference
@@ -39,30 +44,40 @@
39
44
  * Pass 1: Match grid orders to chain (known grid → chain, includes orphan cleanup)
40
45
  * Pass 2: Add missing chain orders (unknown chain → grid)
41
46
  *
42
- * FILL PROCESSING (2 methods)
43
- * 5. syncFromFillHistory(fill) - Process single fill event synchronously
47
+ * FILL PROCESSING (5 methods)
48
+ * 5. _findMatchingGridOrder(mgr, orderId) - Look up the grid slot owning a chain order (internal)
49
+ *
50
+ * 6. _computeFillContext(mgr, matchedGridOrder, paysAssetId, paysAmountRaw) -
51
+ * Resolve the asset/side context for a fill (internal)
52
+ *
53
+ * 7. _computeFillTransitionResult(mgr, params) - Compute the post-fill slot
54
+ * transition and fund deltas without mutating state (internal, async)
55
+ *
56
+ * 8. syncFromFillHistory(fill) - Process single fill event synchronously
44
57
  * Updates grid order state based on fill data
45
58
  * Updates fund state and accounting
46
59
  * Handles both maker and taker fills
47
60
  *
48
- * 6. syncFromFillHistoryBatch(fills) - Process multiple fill events in batch
61
+ * 9. syncFromFillHistoryBatch(fills) - Process multiple fill events in batch
49
62
  * Acquires _gridLock once for all fills in block group
50
63
  * Batches drift refetch into one get_objects RPC call
51
64
  * Applies all grid mutations in a single applyGridUpdateBatch
52
65
  *
53
- * FULL SYNCHRONIZATION (1 method - async)
54
- * 7. synchronizeWithChain(chainData, source) - Full sync (fetch + sync) (async)
66
+ * FULL SYNCHRONIZATION (2 methods - async)
67
+ * 10. _assertGenesisInvariant(mgr) - Fail-closed check that a snapshot has a genesis ladder (internal)
68
+ *
69
+ * 11. synchronizeWithChain(chainData, source) - Full sync (fetch + sync) (async)
55
70
  * Fetches fresh account balances
56
71
  * Calls syncFromOpenOrders() with chain data
57
72
  * Source: event type that triggered sync (fill, poll, broadcast, etc.)
58
73
  *
59
74
  * ACCOUNT STATE (2 methods - async)
60
- * 8. fetchAccountBalancesAndSetTotals(accountId) - Fetch account totals (async)
75
+ * 12. fetchAccountBalancesAndSetTotals() - Fetch account totals (async)
61
76
  * Retrieves BUY/SELL totals and free balances from blockchain
62
77
  * Sets manager.accountTotals
63
78
  * Triggers fund recalculation
64
79
  *
65
- * 9. initializeAssets() - Initialize asset metadata (async)
80
+ * 13. initializeAssets() - Initialize asset metadata (async)
66
81
  * Fetches asset precision and other metadata
67
82
  * Sets manager.assets
68
83
  * Called once at bot startup
@@ -15,12 +15,17 @@
15
15
  * Uses AsyncLock to prevent concurrent sync operations (defense-in-depth locking).
16
16
  *
17
17
  * ===============================================================================
18
- * TABLE OF CONTENTS - SyncEngine Class (8 methods) + 1 module-level helper
18
+ * TABLE OF CONTENTS - SyncEngine Class (12 methods) + module-level helpers
19
19
  * ===============================================================================
20
20
  *
21
- * MODULE-LEVEL HELPER (internal, not exported):
22
- * hasEquivalentRawOnChainOrder(a, b) - Compare two chain orders for equivalence
23
- * Used internally during sync to detect redundant/duplicate chain entries
21
+ * MODULE-LEVEL HELPERS (internal, not exported):
22
+ * readSingleOrderSeam / batchReadOrdersSeam - Chain-order read indirection seams
23
+ * confirmSuspectEmptyRead(mgr) - Re-read after a suspicious empty snapshot
24
+ * describeNearestAdoptionCandidates(mgr, chainOrder, precision, matchedIds) -
25
+ * Diagnostic candidates for nearest-slot adoption
26
+ * chainPriceOnSameLevel(...) - Chain price vs a grid level under precision rules
27
+ * adoptedSlotKeepsItsOwnPrice(mgr, adopted, chainOrderId, path) - Adoption guard
28
+ * adoptChainOrderIntoSlot(...) - Adopt an unmatched chain order into a free slot
24
29
  *
25
30
  * INITIALIZATION (1 method)
26
31
  * 1. constructor(manager) - Create new SyncEngine with manager reference
@@ -39,30 +44,40 @@
39
44
  * Pass 1: Match grid orders to chain (known grid → chain, includes orphan cleanup)
40
45
  * Pass 2: Add missing chain orders (unknown chain → grid)
41
46
  *
42
- * FILL PROCESSING (2 methods)
43
- * 5. syncFromFillHistory(fill) - Process single fill event synchronously
47
+ * FILL PROCESSING (5 methods)
48
+ * 5. _findMatchingGridOrder(mgr, orderId) - Look up the grid slot owning a chain order (internal)
49
+ *
50
+ * 6. _computeFillContext(mgr, matchedGridOrder, paysAssetId, paysAmountRaw) -
51
+ * Resolve the asset/side context for a fill (internal)
52
+ *
53
+ * 7. _computeFillTransitionResult(mgr, params) - Compute the post-fill slot
54
+ * transition and fund deltas without mutating state (internal, async)
55
+ *
56
+ * 8. syncFromFillHistory(fill) - Process single fill event synchronously
44
57
  * Updates grid order state based on fill data
45
58
  * Updates fund state and accounting
46
59
  * Handles both maker and taker fills
47
60
  *
48
- * 6. syncFromFillHistoryBatch(fills) - Process multiple fill events in batch
61
+ * 9. syncFromFillHistoryBatch(fills) - Process multiple fill events in batch
49
62
  * Acquires _gridLock once for all fills in block group
50
63
  * Batches drift refetch into one get_objects RPC call
51
64
  * Applies all grid mutations in a single applyGridUpdateBatch
52
65
  *
53
- * FULL SYNCHRONIZATION (1 method - async)
54
- * 7. synchronizeWithChain(chainData, source) - Full sync (fetch + sync) (async)
66
+ * FULL SYNCHRONIZATION (2 methods - async)
67
+ * 10. _assertGenesisInvariant(mgr) - Fail-closed check that a snapshot has a genesis ladder (internal)
68
+ *
69
+ * 11. synchronizeWithChain(chainData, source) - Full sync (fetch + sync) (async)
55
70
  * Fetches fresh account balances
56
71
  * Calls syncFromOpenOrders() with chain data
57
72
  * Source: event type that triggered sync (fill, poll, broadcast, etc.)
58
73
  *
59
74
  * ACCOUNT STATE (2 methods - async)
60
- * 8. fetchAccountBalancesAndSetTotals(accountId) - Fetch account totals (async)
75
+ * 12. fetchAccountBalancesAndSetTotals() - Fetch account totals (async)
61
76
  * Retrieves BUY/SELL totals and free balances from blockchain
62
77
  * Sets manager.accountTotals
63
78
  * Triggers fund recalculation
64
79
  *
65
- * 9. initializeAssets() - Initialize asset metadata (async)
80
+ * 13. initializeAssets() - Initialize asset metadata (async)
66
81
  * Fetches asset precision and other metadata
67
82
  * Sets manager.assets
68
83
  * Called once at bot startup
@@ -4,56 +4,93 @@
4
4
  * Pure numeric calculations, blockchain conversions, fee math, and fund allocation.
5
5
  *
6
6
  * ===============================================================================
7
- * TABLE OF CONTENTS (44 exported functions)
7
+ * TABLE OF CONTENTS (78 exports)
8
8
  * ===============================================================================
9
9
  *
10
- * SECTION 1: PARSING & VALIDATION (6 functions)
10
+ * SECTION 1: GENESIS LADDER & RAIL GEOMETRY (28 items)
11
+ * - GridGenesis - Genesis ladder type: start price, increment, gap slots,
12
+ * price levels and their hash
13
+ * - priceLevelsForGenesis(genesis) - Extract the frozen price ladder from a genesis
14
+ * - buildGenesisFromPriceLevels(levels, config) - Build a genesis from precomputed levels
15
+ * - derivePriceLevels(startPrice, increment, minPrice, maxPrice) - Derive the
16
+ * geometric price ladder (the "rail") from a live config
17
+ * - hashPriceLevels(levels) - Deterministic hash of a price ladder
18
+ * - priceForSlot(idx, genesis) - Authoritative price for a slot index
19
+ * - slotIndexForPrice(price, genesis) - Resolve a price to its slot index
20
+ * - slotIdForPrice(price, genesis) - Resolve a price to its "slot-N" id
21
+ * - assertSlotPriceInvariant(...) - Reject a slot whose price disagrees with its index
22
+ * - priceSlotEqual(...) - Compare slot/price pairs under the genesis invariant
23
+ * - sameGridLevel(a, b) - Same ladder level, resolving each price against its genesis
24
+ * - sameGridPrice(a, b) - Same genesis-derived ladder level by precision
25
+ * - pricesOnSameLevel(a, b, ...) - Same order-book price LEVEL under precision
26
+ * - isChainPriceOutOfGrid(price, genesis, ...) - Whether a chain price is off the rail
27
+ * - getBtsSide(assets) - Which side of the pair holds BTS
28
+ * - getSellStartIdx(boundaryIdx, gapSlots) - Sell start index from boundary + gap
29
+ * - calculateGapSlots(incrementPercent, targetSpreadPercent) - Gap-slot count
30
+ * - resolveGapSlots(manager) - Configured gap-slot count for a manager
31
+ * - resolveGapBand(manager) - Gap-band geometry { start, end, gapSlots }
32
+ * - countGapBandSpread(manager) - Count SPREAD slots strictly inside the gap band
33
+ * - isSlotInRail(...) - Geometric rail-membership test for a slot
34
+ * - isSlotIndexInGapBand(idx, ...) - Whether a slot index sits inside the gap band
35
+ * - isEvacuationRotationAllowed(...) - Whether a gap-evacuation rotation is geometrically valid
36
+ * - isEvacuationSizeStillValid(...) - Re-proof a stamped evacuation size against live geometry
37
+ * - validateBoundaryCommit(...) - Validate a proposed boundary commit against geometry
38
+ * - validatePersistedBoundary(...) - Validate a boundary restored from disk
39
+ * - isTransientInBandRejection(reason) - Whether a persisted-boundary rejection is transient
40
+ * - BOUNDARY_REJECT_PLACED_IN_BAND - Rejection reason: target slot holds an in-band order
41
+ *
42
+ * SECTION 2: PARSING & VALIDATION (10 functions)
11
43
  * - isExplicitZeroAllocation(value) - Check if value is explicitly zero
12
44
  * - isPercentageString(v) - Check if value is percentage string
45
+ * - isPositiveNumber(value) - Check if value is a positive number
46
+ * - isPositiveNumberOrPercent(value) - Positive number or positive percentage string
47
+ * - isPositiveInt(value) - Check if value is a positive integer
13
48
  * - parsePercentageString(v) - Parse percentage string to decimal
49
+ * - toDecimal(value) - Convert number/percentage/numeric string to a decimal
14
50
  * - parseRelativeMultiplier(value) - Parse "3x" multiplier syntax to number
15
51
  * - resolveRelativePrice(value, startPrice, mode) - Resolve relative price values
16
52
  * - validateGridPriceBounds(min, max, center) - Reject bounds not bracketing center
17
53
  *
18
- * SECTION 2: FUND CALCULATIONS (4 functions)
54
+ * SECTION 3: FUND CALCULATIONS (8 functions)
19
55
  * - computeChainFundTotals(accountTotals, committedChain) - Compute total funds
20
56
  * - calculateAvailableFundsValue(side, accountTotals, funds, ...) - Calculate available funds
57
+ * - adjustBudgetForBtsFees(budget, btsFeeData, ...) - Reserve BTS fees from a side budget
58
+ * - getGridBestPrices(manager) - Best (highest) buy and best (lowest) sell price
21
59
  * - calculateSpreadFromOrders(activeBuys, activeSells) - Calculate spread percentage
22
60
  * - resolveConfigValue(value, total) - Resolve percentage or absolute config value
61
+ * - resolveConfigValueWithRegistry(value, total, registry) - Config value incl. shared-account funds
62
+ * - hasValidAccountTotals(accountTotals, checkFree) - Validate account totals structure
23
63
  *
24
- * SECTION 3: BLOCKCHAIN CONVERSIONS (5 functions)
64
+ * SECTION 4: BLOCKCHAIN CONVERSIONS (6 functions)
25
65
  * - blockchainToFloat(intValue, precision) - Convert blockchain int to float
26
66
  * - floatToBlockchainInt(floatValue, precision) - Convert float to blockchain int
67
+ * - floorToBlockchainInt(floatValue, precision) - Convert float to int by flooring
27
68
  * - quantizeFloat(value, precision) - Round float to blockchain precision
28
69
  * - normalizeInt(value, precision) - Normalize int within precision bounds
29
- * - hasValidAccountTotals(accountTotals, checkFree) - Validate account totals structure
70
+ * - quantumForPrecision(precision) - Smallest representable unit for a precision
30
71
  *
31
- * SECTION 4: PRECISION & FORMATTING UTILITIES (8 functions)
32
- * - roundTo(value, factor) - Round to a factor
33
- * - fixedTo(value, decimals) - Format to fixed decimal string
34
- * - roundToDecimals(value, decimals) - Round to N decimal places
72
+ * SECTION 5: PRECISION UTILITIES (4 functions)
35
73
  * - getPrecision(assets, orderType) - Get precision for order type
36
74
  * - getPrecisionByOrderType(assets, orderType) - Alias for getPrecision
37
- * - getPrecisionForSide(assets, side) - Get precision by side (buy/sell)
38
75
  * - getPrecisionsForManager(manager) - Get both asset precisions
39
76
  * - getPrecisionSlack(precision) - Calculate tolerance for precision
40
77
  *
41
- * SECTION 5: ORDER SIZE VALIDATION (7 functions)
78
+ * SECTION 6: ORDER SIZE VALIDATION (8 functions)
42
79
  * - calculatePriceTolerance(price, size, type, assets) - Calculate price match tolerance
80
+ * - findCrossedOrder(...) - Find an opposite-side order a placement would CROSS
43
81
  * - validateOrderAmountsWithinLimits(amountToSell, minToReceive) - Validate order limits
44
- * - getMinOrderSize(assets, type) - Get minimum order size for type
82
+ * - getMinOrderSize(orderType, assets, factor) - Get minimum order size
45
83
  * - getDustThresholdFactor() - Get dust threshold multiplier
46
84
  * - getSingleDustThreshold(idealSize, dustThresholdPercent) - Get single dust threshold
47
85
  * - getDoubleDustThreshold(idealSize, dustThresholdPercent) - Get double dust threshold
48
- * - getMinOrderSize(orderType, assets, factor) - Get minimum order size
49
86
  * - validateOrderSize(manager, size, type, context) - Validate order size against minimums
50
87
  *
51
- * SECTION 6: FEE CALCULATIONS (2 functions + 2 internal)
88
+ * SECTION 7: FEE CALCULATIONS (3 functions)
52
89
  * - getAssetFees(assetSymbol, assetAmount, isMaker) - Get fee info for asset
90
+ * - getAssetFeesSafe(assetSymbol, assetAmount, isMaker) - Fee info without throwing
53
91
  * - _setFeeCache(cache) - Set internal fee cache (internal)
54
- * - _getFeeCache() - Get internal fee cache (internal)
55
92
  *
56
- * SECTION 7: FUND ALLOCATION (6 functions)
93
+ * SECTION 8: FUND ALLOCATION (6 functions)
57
94
  * - allocateFundsByWeights(available, targetCount) - Allocate funds by weight
58
95
  * - cloneWeightDistribution(weightDistribution, base) - Clone weight distribution safely
59
96
  * - calculateOrderSizes(manager, orderType) - Calculate order sizes for placement
@@ -61,13 +98,14 @@
61
98
  * - calculateGridSideDivergenceMetric(manager, orderType, threshold) - Calculate divergence
62
99
  * - clamp(value, min, max) - Clamp a value between min and max bounds
63
100
  *
64
- * SECTION 8: FEE DEDUCTION (3 functions)
101
+ * SECTION 9: FEE DEDUCTION (2 functions)
65
102
  * - calculateOrderCreationFees(count, btsFeeData) - Calculate total creation fees
66
- * - deductOrderFeesFromFunds(available, count, btsFeeData, btsSide) - Deduct fees from funds
67
103
  * - calculateSwapInAmount(targetReceive, poolReserveOut, poolReserveIn) - AMM swap math
68
104
  *
69
- * SECTION 9: GRID UTILITIES (1 function)
70
- * - calculateGapSlots(incrementPercent, targetSpreadPercent) - Calculate gap slots count
105
+ * SECTION 10: FORMATTING (3 functions)
106
+ * - roundTo(value, factor) - Round to a factor
107
+ * - fixedTo(value, decimals) - Format to fixed decimal string
108
+ * - roundToDecimals(value, decimals) - Round to N decimal places
71
109
  *
72
110
  * ===============================================================================
73
111
  */
@@ -404,6 +442,46 @@ declare function getAssetFeesSafe(assetSymbol: string, assetAmount?: number | nu
404
442
  feeAmount?: undefined;
405
443
  feePercent?: undefined;
406
444
  } | null;
445
+ /**
446
+ * Fund budget for placing a KNOWN set of pending slots (spread correction).
447
+ *
448
+ * `calculateAvailableFundsValue` computes `chainFree - virtual - fees`, where
449
+ * `virtual` is the projection of the side's not-yet-placed (VIRTUAL) slots.
450
+ * That is the right number for "how much room is left beyond the projected
451
+ * rail", but it is CIRCULAR when the caller is funding exactly those projected
452
+ * slots: if the projection is larger than the account holds free (a rail sized
453
+ * from a bigger balance, from inventory locked in resting orders, or from
454
+ * optimistic proceeds), `available` reads 0 while the chain clearly holds free
455
+ * funds, and the projection can never shrink because nothing gets placed.
456
+ * Live symptom: `planned 3, placing 0` every cycle for 84 minutes
457
+ * (`free 454560.80` vs `virtual 456046.21`).
458
+ *
459
+ * So for a known candidate set, re-derive the budget from chain truth: add the
460
+ * projection back, but never more than the candidates themselves need and never
461
+ * more than the chain actually holds free. The chain remains the final arbiter
462
+ * (an over-commit is rejected at broadcast), and the fee reservation stays
463
+ * inside `availableFund` for every healthy cycle.
464
+ *
465
+ * Only an OVERSUBSCRIPTION (projection > chain free) triggers the fallback. A
466
+ * zero caused by the fee reservation or by a genuinely empty balance is a real
467
+ * constraint: the projection fits, so honour it (and its fees) and place
468
+ * nothing.
469
+ *
470
+ * @param {{availableFund?: number, virtualIntent?: number, chainFree?: number, candidateIdeals?: number}} args
471
+ * @returns {{budget: number, oversubscribed: number, eroded: boolean}} budget to
472
+ * place with; projection excess over chain free (0 = healthy); whether the
473
+ * chain-truth re-derivation was needed
474
+ */
475
+ declare function deriveChainTruthFundBudget(args: {
476
+ availableFund?: number;
477
+ virtualIntent?: number;
478
+ chainFree?: number;
479
+ candidateIdeals?: number;
480
+ } | null | undefined): {
481
+ budget: number;
482
+ oversubscribed: number;
483
+ eroded: boolean;
484
+ };
407
485
  /**
408
486
  * Calculate available funds for a specific side (buy or sell).
409
487
  * Deducts virtual reservations, BTS fees owed, and BTS fee reservation from chain-free balance.
@@ -845,7 +923,7 @@ declare function calculateSwapInAmount(targetReceive: number, poolReserveOut: nu
845
923
  *
846
924
  * @param {number} incrementPercent - Grid increment percentage
847
925
  * @param {number} targetSpreadPercent - Target spread percentage
848
- * @param {Object} GRID_LIMITS - Grid limits constants (optional, uses defaults)
926
+ * @param {Object} [gridLimits] - Grid limits constants (optional, uses defaults)
849
927
  * @returns {number} Number of gap slots
850
928
  */
851
929
  declare function calculateGapSlots(incrementPercent: number | undefined, targetSpreadPercent: number | undefined, gridLimits?: GridLimitsLike): number;
@@ -1178,7 +1256,7 @@ declare function priceSlotEqual(a: number, b: number, precision: number): boolea
1178
1256
  declare function derivePriceLevels(startPrice: number, minPrice: number, maxPrice: number, incrementPercent: number): number[];
1179
1257
  declare function buildGenesisFromPriceLevels(startPrice: number, incrementPercent: number, gapSlots: number, priceLevels: number[]): GridGenesis;
1180
1258
  export type { FeeCacheEntry };
1181
- export { getBtsSide, getSellStartIdx, resolveGapBand, countGapBandSpread, calculateGapSlots, isSlotInRail, isSlotIndexInGapBand, isEvacuationRotationAllowed, isEvacuationSizeStillValid, validateBoundaryCommit, validatePersistedBoundary, isTransientInBandRejection, BOUNDARY_REJECT_PLACED_IN_BAND, resolveGapSlots, isPercentageString, isPositiveNumber, isPositiveNumberOrPercent, isPositiveInt, parsePercentageString, toDecimal, resolveRelativePrice, parseRelativeMultiplier, validateGridPriceBounds, isExplicitZeroAllocation, getPrecision, computeChainFundTotals, calculateAvailableFundsValue, adjustBudgetForBtsFees, getGridBestPrices, calculateSpreadFromOrders, resolveConfigValue, resolveConfigValueWithRegistry, hasValidAccountTotals, blockchainToFloat, floatToBlockchainInt, floorToBlockchainInt, quantizeFloat, normalizeInt, getPrecisionByOrderType, getPrecisionsForManager, getPrecisionSlack, quantumForPrecision, calculatePriceTolerance, findCrossedOrder, pricesOnSameLevel, sameGridPrice, validateOrderAmountsWithinLimits, getMinOrderSize, getDustThresholdFactor, getSingleDustThreshold, getDoubleDustThreshold, validateOrderSize, getAssetFees, getAssetFeesSafe, allocateFundsByWeights, calculateOrderSizes, calculateRotationOrderSizes, calculateGridSideDivergenceMetric, calculateOrderCreationFees, calculateSwapInAmount, _setFeeCache, cloneWeightDistribution, clamp, roundTo, fixedTo, roundToDecimals, priceLevelsForGenesis, priceForSlot, slotIndexForPrice, slotIdForPrice, assertSlotPriceInvariant, priceSlotEqual, derivePriceLevels, sameGridLevel, buildGenesisFromPriceLevels, hashPriceLevels, isChainPriceOutOfGrid };
1259
+ export { getBtsSide, getSellStartIdx, resolveGapBand, countGapBandSpread, calculateGapSlots, isSlotInRail, isSlotIndexInGapBand, isEvacuationRotationAllowed, isEvacuationSizeStillValid, validateBoundaryCommit, validatePersistedBoundary, isTransientInBandRejection, BOUNDARY_REJECT_PLACED_IN_BAND, resolveGapSlots, isPercentageString, isPositiveNumber, isPositiveNumberOrPercent, isPositiveInt, parsePercentageString, toDecimal, resolveRelativePrice, parseRelativeMultiplier, validateGridPriceBounds, isExplicitZeroAllocation, getPrecision, computeChainFundTotals, calculateAvailableFundsValue, deriveChainTruthFundBudget, adjustBudgetForBtsFees, getGridBestPrices, calculateSpreadFromOrders, resolveConfigValue, resolveConfigValueWithRegistry, hasValidAccountTotals, blockchainToFloat, floatToBlockchainInt, floorToBlockchainInt, quantizeFloat, normalizeInt, getPrecisionByOrderType, getPrecisionsForManager, getPrecisionSlack, quantumForPrecision, calculatePriceTolerance, findCrossedOrder, pricesOnSameLevel, sameGridPrice, validateOrderAmountsWithinLimits, getMinOrderSize, getDustThresholdFactor, getSingleDustThreshold, getDoubleDustThreshold, validateOrderSize, getAssetFees, getAssetFeesSafe, allocateFundsByWeights, calculateOrderSizes, calculateRotationOrderSizes, calculateGridSideDivergenceMetric, calculateOrderCreationFees, calculateSwapInAmount, _setFeeCache, cloneWeightDistribution, clamp, roundTo, fixedTo, roundToDecimals, priceLevelsForGenesis, priceForSlot, slotIndexForPrice, slotIdForPrice, assertSlotPriceInvariant, priceSlotEqual, derivePriceLevels, sameGridLevel, buildGenesisFromPriceLevels, hashPriceLevels, isChainPriceOutOfGrid };
1182
1260
  /**
1183
1261
  * Round a value to a given factor.
1184
1262
  * @param {number} value - Value to round