dexbot 1.7.0 → 1.7.2

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 (115) hide show
  1. package/CHANGELOG.md +70 -0
  2. package/README.md +3 -3
  3. package/analysis/README.md +33 -13
  4. package/claw/package.json +1 -1
  5. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  6. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  7. package/dist/analysis/account_resolver.js +5 -6
  8. package/dist/analysis/analyze_liquidity.js +15 -4
  9. package/dist/analysis/bot_key_utils.d.ts +44 -1
  10. package/dist/analysis/bot_key_utils.js +76 -7
  11. package/dist/analysis/fills_cache.js +2 -1
  12. package/dist/analysis/grid_correction_check.d.ts +1 -19
  13. package/dist/analysis/grid_correction_check.js +12 -30
  14. package/dist/analysis/liquidity/liquidity_chart_generator.js +190 -20
  15. package/dist/analysis/liquidity/liquidity_depth_model.d.ts +41 -16
  16. package/dist/analysis/liquidity/liquidity_depth_model.js +49 -21
  17. package/dist/analysis/liquidity/liquidity_view.d.ts +15 -0
  18. package/dist/analysis/liquidity/liquidity_view.js +11 -0
  19. package/dist/analysis/resolve_bot_accounts.js +7 -6
  20. package/dist/analysis/trade_profitability.js +2 -1
  21. package/dist/credential-daemon.js +13 -2
  22. package/dist/dexbot.js +4 -4
  23. package/dist/modules/account_bots.d.ts +12 -1
  24. package/dist/modules/account_bots.js +7 -5
  25. package/dist/modules/account_orders.d.ts +12 -0
  26. package/dist/modules/account_orders.js +30 -0
  27. package/dist/modules/bitshares-native/transport.js +24 -6
  28. package/dist/modules/bitshares_client.d.ts +24 -6
  29. package/dist/modules/bitshares_client.js +44 -7
  30. package/dist/modules/bot_settings.d.ts +2 -0
  31. package/dist/modules/constants.d.ts +28 -3
  32. package/dist/modules/constants.js +79 -10
  33. package/dist/modules/dexbot_class.d.ts +23 -6
  34. package/dist/modules/dexbot_class.js +44 -0
  35. package/dist/modules/dexbot_cow_runtime.d.ts +128 -8
  36. package/dist/modules/dexbot_cow_runtime.js +688 -188
  37. package/dist/modules/dexbot_fill_runtime.js +124 -35
  38. package/dist/modules/dexbot_maintenance_runtime.d.ts +1 -1
  39. package/dist/modules/dexbot_maintenance_runtime.js +259 -79
  40. package/dist/modules/dexbot_startup_runtime.js +32 -20
  41. package/dist/modules/dexbot_state_recovery.d.ts +33 -1
  42. package/dist/modules/dexbot_state_recovery.js +167 -5
  43. package/dist/modules/node_connect_policy.d.ts +8 -1
  44. package/dist/modules/node_connect_policy.js +18 -2
  45. package/dist/modules/node_flap_score.d.ts +87 -0
  46. package/dist/modules/node_flap_score.js +124 -0
  47. package/dist/modules/node_health_cache.d.ts +40 -3
  48. package/dist/modules/node_health_cache.js +66 -20
  49. package/dist/modules/node_manager.d.ts +101 -19
  50. package/dist/modules/node_manager.js +255 -65
  51. package/dist/modules/order/accounting.d.ts +9 -4
  52. package/dist/modules/order/accounting.js +131 -19
  53. package/dist/modules/order/async_lock.d.ts +7 -1
  54. package/dist/modules/order/async_lock.js +7 -1
  55. package/dist/modules/order/export.js +25 -18
  56. package/dist/modules/order/fill_ledger.d.ts +99 -0
  57. package/dist/modules/order/fill_ledger.js +103 -0
  58. package/dist/modules/order/format.d.ts +24 -10
  59. package/dist/modules/order/format.js +30 -10
  60. package/dist/modules/order/grid.d.ts +75 -18
  61. package/dist/modules/order/grid.js +289 -72
  62. package/dist/modules/order/grid_reconcile.d.ts +5 -1
  63. package/dist/modules/order/grid_reconcile.js +333 -210
  64. package/dist/modules/order/grid_reconcile_internal.d.ts +38 -2
  65. package/dist/modules/order/grid_reconcile_internal.js +223 -91
  66. package/dist/modules/order/index.d.ts +18 -5
  67. package/dist/modules/order/index.js +5 -5
  68. package/dist/modules/order/lifecycle.d.ts +353 -0
  69. package/dist/modules/order/lifecycle.js +1109 -0
  70. package/dist/modules/order/manager.d.ts +277 -20
  71. package/dist/modules/order/manager.js +680 -64
  72. package/dist/modules/order/placement_lock.d.ts +102 -0
  73. package/dist/modules/order/placement_lock.js +222 -0
  74. package/dist/modules/order/strategy.js +13 -1
  75. package/dist/modules/order/sync_engine.d.ts +74 -114
  76. package/dist/modules/order/sync_engine.js +254 -198
  77. package/dist/modules/order/utils/math.d.ts +29 -4
  78. package/dist/modules/order/utils/math.js +61 -4
  79. package/dist/modules/order/utils/order.d.ts +106 -37
  80. package/dist/modules/order/utils/order.js +256 -81
  81. package/dist/modules/order/utils/system.d.ts +99 -6
  82. package/dist/modules/order/utils/system.js +249 -35
  83. package/dist/modules/order/utils/validate.d.ts +7 -1
  84. package/dist/modules/order/utils/validate.js +48 -2
  85. package/dist/modules/outcome.d.ts +54 -0
  86. package/dist/modules/outcome.js +51 -0
  87. package/dist/modules/settings_merge.d.ts +4 -0
  88. package/dist/modules/settings_merge.js +9 -0
  89. package/dist/modules/timing_policy.d.ts +82 -0
  90. package/dist/modules/timing_policy.js +244 -0
  91. package/dist/modules/types.d.ts +149 -22
  92. package/dist/scripts/analyze-credit.js +54 -17
  93. package/dist/scripts/analyze-orders.d.ts +4 -2
  94. package/dist/scripts/analyze-orders.js +113 -34
  95. package/dist/scripts/chart_targets.js +11 -15
  96. package/dist/scripts/test-credit-renewal.js +12 -5
  97. package/docs/COW_INVARIANTS.md +71 -8
  98. package/docs/DEXBOT_COMPARISON.md +6 -6
  99. package/docs/EVOLUTION.md +10 -8
  100. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  101. package/docs/GRID_PRICE_INVARIANT.md +1 -1
  102. package/docs/GRID_RECONCILE.md +18 -13
  103. package/docs/LOGGING.md +25 -1
  104. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +183 -26
  105. package/docs/README.md +23 -2
  106. package/docs/WORKFLOW.md +9 -3
  107. package/docs/architecture.md +68 -13
  108. package/docs/developer_guide.md +25 -8
  109. package/modules/README.md +6 -0
  110. package/package.json +3 -3
  111. package/scripts/README.md +16 -0
  112. package/scripts/pdev.sh +14 -1
  113. package/scripts/pmain.sh +23 -8
  114. package/scripts/ptest.sh +7 -0
  115. package/tests/README.md +30 -1
@@ -6,7 +6,7 @@
6
6
  * Exports a single Accountant class that manages all fund accounting operations.
7
7
  *
8
8
  * ===============================================================================
9
- * TABLE OF CONTENTS - Accountant Class (26 methods)
9
+ * TABLE OF CONTENTS - Accountant Class (27 methods)
10
10
  * ===============================================================================
11
11
  *
12
12
  * CORE INITIALIZATION & RECALCULATION (2 methods)
@@ -56,6 +56,7 @@
56
56
  * 25. _recalibrateTrackedFundsFromChain(mgr, openOrders) - Recalibrate tracked funds
57
57
  * from a fresh chain snapshot
58
58
  * 26. _tryTrustChainFreeHeal(mgr, driftValidation) - Attempt a trust-chain-free heal
59
+ * 27. _getBtsFeeSchedule() - Resolve the BTS fee schedule (create/update/cancel + maker refund %)
59
60
  *
60
61
  * ===============================================================================
61
62
  * FUND STRUCTURE (managed by Accountant)
@@ -90,7 +91,8 @@ import { ORDER_TYPES, ORDER_STATES, PIPELINE_TIMING, TIMING, FEE_PARAMETERS, GRI
90
91
  import { resolveAccountRef } from './utils/system.js';
91
92
  import { resolveSpreadOrderSide, parseChainOrder, applyChainSizeToGridOrder, convertToSpreadPlaceholder, resolveEdgeCount } from './utils/order.js';
92
93
  import { parseSlotIndex } from './utils/slot.js';
93
- import { isSlotInRail, floatToBlockchainInt } from './utils/math.js';
94
+ import { readSlotLifecycle } from './lifecycle.js';
95
+ import { isSlotInRail, resolveGapSlots, floatToBlockchainInt } from './utils/math.js';
94
96
  import * as Format from './format.js';
95
97
  import * as fundRegistry from '../fund_registry.js';
96
98
  import * as chainOrders from '../chain_orders.js';
@@ -143,13 +145,30 @@ class Accountant {
143
145
  return false;
144
146
  }
145
147
  /**
146
- * Apply a list of balance adjustments.
147
- * @param {Array<{orderType: string, delta: number, operation: string}>} balanceAdjustments
148
- * @returns {void}
148
+ * Apply balance adjustments ALL-OR-NOTHING.
149
+ *
150
+ * A throw from the middle of the list used to leave the earlier deltas
151
+ * applied. Since P2 releases the dedup claim on failure (so the fill can be
152
+ * retried), a partial application would then be applied twice on the retry.
153
+ * The credit is now atomic: an applied prefix is reversed before the error
154
+ * propagates, so "not credited" is true whenever the claim was released.
149
155
  */
150
156
  async _applyBalanceAdjustments(balanceAdjustments) {
151
- for (const adjustment of balanceAdjustments) {
152
- await this.adjustTotalBalance(adjustment.orderType, adjustment.delta, adjustment.operation);
157
+ const applied = [];
158
+ try {
159
+ for (const adjustment of balanceAdjustments) {
160
+ await this.adjustTotalBalance(adjustment.orderType, adjustment.delta, adjustment.operation);
161
+ applied.push(adjustment);
162
+ }
163
+ }
164
+ catch (err) {
165
+ for (const adjustment of applied.reverse()) {
166
+ try {
167
+ await this.adjustTotalBalance(adjustment.orderType, -adjustment.delta, 'rollback-' + adjustment.operation);
168
+ }
169
+ catch { /* keep the original failure */ }
170
+ }
171
+ throw err;
153
172
  }
154
173
  }
155
174
  _getBtsOrderType() {
@@ -372,7 +391,11 @@ class Accountant {
372
391
  // * price >= startPrice → SELL side (higher prices are asks)
373
392
  const genesis = mgr._genesis;
374
393
  const boundaryIdx = mgr.boundaryIdx;
375
- const gapSlots = genesis?.gapSlots ?? mgr._gapSlots ?? 0;
394
+ // Never fall back to gap 0: a 0-wide band classifies the slot just
395
+ // above the boundary as a SELL rail slot and would book a SPREAD
396
+ // placeholder's size on the wrong side. resolveGapSlots keeps the
397
+ // config-derived geometry as the fallback.
398
+ const gapSlots = genesis?.gapSlots ?? resolveGapSlots(mgr);
376
399
  let spreadSide = null;
377
400
  if (order.type === ORDER_TYPES.SPREAD && genesis && boundaryIdx != null && Number.isFinite(Number(boundaryIdx))) {
378
401
  if (isSlotInRail(boundaryIdx, gapSlots, ORDER_TYPES.BUY, order))
@@ -931,11 +954,12 @@ class Accountant {
931
954
  mgr.logger?.log?.(`[RECOVERY] Skipping recalibration for ${gridOrder.id}: live order ${gridOrder.orderId} is unparseable (unknown, not absent)`, 'debug');
932
955
  continue;
933
956
  }
934
- const commitAge = Date.now() - (mgr._committedOrderIdsBuiltAt || 0);
935
- const recentCommit = mgr._committedOrderIds?.has?.(gridOrder.orderId) && commitAge < TIMING.SYNC_LOCK_TIMEOUT_MS;
936
- const assignedAt = mgr._orderIdAssignedAt?.get?.(gridOrder.orderId) || 0;
937
- const recentAssign = assignedAt > 0 && (Date.now() - assignedAt) < TIMING.SYNC_LOCK_TIMEOUT_MS;
938
- if (recentCommit || recentAssign)
957
+ // Single in-flight guard (modules/order/lifecycle.ts).
958
+ // This site used to OR together `_committedOrderIds` and
959
+ // `_orderIdAssignedAt` while the startup reconcile OR'd
960
+ // neither-or-one; same order, different answer. Read through the
961
+ // SLOT so the persisted create-uncertain marker participates.
962
+ if (readSlotLifecycle(mgr, gridOrder).isInFlight())
939
963
  continue;
940
964
  result.attempted++;
941
965
  const spreadOrder = convertToSpreadPlaceholder(gridOrder);
@@ -1642,6 +1666,20 @@ class Accountant {
1642
1666
  const assetBPrecision = mgr.assets?.assetB?.precision;
1643
1667
  if (assetAPrecision === undefined || assetBPrecision === undefined)
1644
1668
  return false;
1669
+ // Idempotency with sync pass 1: an open-orders pass may already have
1670
+ // resized the slot from the same post-fill chain snapshot (and
1671
+ // released that commitment into free). The fill transition must not
1672
+ // shrink/release the same base units a second time (3.6604 -> 3.3046
1673
+ // -> 2.9488). The trade's pays/receives are still applied here — pass
1674
+ // 1 never books them. A limit-order fill always PAYS the order's base
1675
+ // asset (assetA for a SELL, assetB for a BUY); the order's `size` and
1676
+ // the pass-1 delta are in that same base unit. `receives` is the
1677
+ // quote side and must not be used for the marker.
1678
+ const filledBaseInt = Number(pays.amount);
1679
+ // The marker is consumed LATER, just before the adjustments are
1680
+ // applied: a duplicate fill key or a failed dedup-key persist must not
1681
+ // eat marker units a following split fill of the same order needs.
1682
+ let appliedInt = 0;
1645
1683
  // Derive all numeric effects before recording the fill key.
1646
1684
  // This keeps retries safe if a later computation unexpectedly fails.
1647
1685
  const balanceAdjustments = [];
@@ -1669,6 +1707,13 @@ class Accountant {
1669
1707
  if (btsRefundAdjustment) {
1670
1708
  balanceAdjustments.push(btsRefundAdjustment);
1671
1709
  }
1710
+ // IMPORTANT: do NOT clear `balanceAdjustments` when pass 1 already
1711
+ // resized the slot. Pass 1's updateOptimisticFreeBalance only RELEASES
1712
+ // the commitment into free; it never applies the trade's pays/receives.
1713
+ // The duplicate the marker protects against is the second SIZE release
1714
+ // in the fill transition, which is handled by __chainSizeAppliedInt
1715
+ // (subtract only the remainder). Zeroing this list dropped the actual
1716
+ // trade until the post-batch reanchor happened to repair it.
1672
1717
  let processedAt = null;
1673
1718
  const tracker = this.manager.processedFillTracker;
1674
1719
  if (fillKey) {
@@ -1680,6 +1725,15 @@ class Accountant {
1680
1725
  }
1681
1726
  }
1682
1727
  const processedFillStore = this.manager.processedFillStore;
1728
+ // The claim, the duplicate gate and the rollback must all touch ONE map.
1729
+ // In a wired bot `processedFillTracker` IS `processedFillStore.tracker`
1730
+ // (dexbot_fill_runtime assigns the store map to the manager), but a
1731
+ // split fixture or a host that wiring never reached would otherwise
1732
+ // claim a key the ingest check cannot see. Prefer the store's map when
1733
+ // it exists; the in-memory tracker is the fallback.
1734
+ const claimTracker = processedFillStore?.tracker instanceof Map
1735
+ ? processedFillStore.tracker
1736
+ : tracker;
1683
1737
  // Queue the dedup key before applying balance adjustments. This ensures
1684
1738
  // persist failures are caught before any balance mutation. The queue entry
1685
1739
  // is flushed only after balance adjustments succeed below.
@@ -1693,7 +1747,59 @@ class Accountant {
1693
1747
  return false;
1694
1748
  }
1695
1749
  }
1696
- await this._applyBalanceAdjustments(balanceAdjustments);
1750
+ // CLAIM THE KEY AT CREDIT TIME (docs/FILL_PIPELINE.md stage 2).
1751
+ // The store is the dedupe authority, so the key must be visible to the
1752
+ // duplicate check before any balance moves — not after the flush. Without
1753
+ // this, a second fill with the same key can pass the check while the
1754
+ // first is still in flight and reach the transition a second time; the
1755
+ // claim lease in the bot only covers that when its window has not
1756
+ // expired. Rolled back on every failure path below, so the invariant is
1757
+ // "booked ⇒ tracker has the key" with no half-claimed keys.
1758
+ //
1759
+ // The check and the set are ONE synchronous step: the duplicate check
1760
+ // above happens before `persist()` awaits, so two concurrent callers can
1761
+ // both pass it and then both credit. Re-checking here (no await in
1762
+ // between) makes the claim the actual single-winner gate. The loser must
1763
+ // NOT discard the queued write: the pending entry is keyed by fill key
1764
+ // and belongs to the winner's booking.
1765
+ if (fillKey) {
1766
+ if (claimTracker.has(fillKey))
1767
+ return false;
1768
+ claimTracker.set(fillKey, processedAt || Date.now());
1769
+ }
1770
+ try {
1771
+ // Consume the pass-1 marker only now that this fill is not a
1772
+ // duplicate and its dedup key is queued. Partial consumption: pass 1
1773
+ // may have absorbed only part of this fill (A+B observed, fill A
1774
+ // drained now); the transition subtracts only the remainder.
1775
+ // Inside the try: the claim above must be released if the marker
1776
+ // accessor throws, or the fill could never be retried.
1777
+ const consumeApplied = mgr.consumeChainSizeAppliedFillAmount;
1778
+ if (Number.isFinite(filledBaseInt) && typeof consumeApplied === 'function') {
1779
+ appliedInt = Math.max(0, Math.min(Math.round(Number(consumeApplied.call(mgr, String(fillOp.order_id), filledBaseInt)) || 0), Math.round(filledBaseInt)));
1780
+ }
1781
+ if (appliedInt > 0) {
1782
+ fillOp.__chainSizeAppliedInt = appliedInt;
1783
+ mgr?.logger?.log?.(`[FILL-DEDUP] Fill ${fillKey || fillOp.order_id}: ${appliedInt}/${Math.round(filledBaseInt)} base units already absorbed by sync pass 1; the transition will not shrink them again`, 'debug');
1784
+ }
1785
+ else {
1786
+ delete fillOp.__chainSizeAppliedInt;
1787
+ }
1788
+ await this._applyBalanceAdjustments(balanceAdjustments);
1789
+ }
1790
+ catch (err) {
1791
+ // The claim was ours (the duplicate check above returned early for an
1792
+ // existing key) and no credit was committed, so release it — otherwise
1793
+ // the fill could never be retried.
1794
+ if (fillKey) {
1795
+ claimTracker.delete(fillKey);
1796
+ processedFillStore?.discard(fillKey, processedAt || Date.now());
1797
+ }
1798
+ if (appliedInt > 0 && typeof mgr.noteChainSizeAppliedFill === 'function') {
1799
+ mgr.noteChainSizeAppliedFill(String(fillOp.order_id), appliedInt);
1800
+ }
1801
+ throw err;
1802
+ }
1697
1803
  // Flush the queued dedup key now that balance adjustments succeeded.
1698
1804
  // For IMMEDIATE mode, this persists durably. For BATCHED mode, the
1699
1805
  // key remains queued for the caller's batch flush.
@@ -1710,17 +1816,23 @@ class Accountant {
1710
1816
  await this.adjustTotalBalance(adj.orderType, -adj.delta, 'rollback-' + adj.operation);
1711
1817
  }
1712
1818
  processedFillStore.discard(fillKey, processedAt || Date.now());
1819
+ claimTracker.delete(fillKey);
1820
+ // The marker was consumed for this attempt; the rolled-back
1821
+ // fill must be able to skip the pass-1 size release on retry.
1822
+ if (appliedInt > 0 && typeof mgr.noteChainSizeAppliedFill === 'function') {
1823
+ mgr.noteChainSizeAppliedFill(String(fillOp.order_id), appliedInt);
1824
+ }
1713
1825
  throw err;
1714
1826
  }
1715
1827
  }
1716
1828
  if (fillKey) {
1717
- tracker.set(fillKey, processedAt || Date.now());
1718
- // Prune entries beyond the retention horizon to prevent unbounded growth.
1719
- if (tracker.size > 500) {
1829
+ // Already claimed before the credit; prune beyond the retention
1830
+ // horizon so the tracker cannot grow without bound.
1831
+ if (claimTracker.size > 500) {
1720
1832
  const cutoff = (processedAt || Date.now()) - TIMING.FILL_RECORD_RETENTION_MS;
1721
- for (const [k, ts] of tracker) {
1833
+ for (const [k, ts] of claimTracker) {
1722
1834
  if (ts < cutoff)
1723
- tracker.delete(k);
1835
+ claimTracker.delete(k);
1724
1836
  }
1725
1837
  }
1726
1838
  }
@@ -2,7 +2,9 @@
2
2
  * modules/order/async_lock.ts - AsyncLock Engine
3
3
  *
4
4
  * Distributed mutual exclusion for async operations.
5
- * Exports a single AsyncLock class that prevents concurrent execution of critical sections.
5
+ * Exports the AsyncLock class (the lock itself) plus the `acquireIfNotHeld()`
6
+ * re-entrancy guard that call sites delegate through instead of inlining the
7
+ * `isReentrant()` check-and-acquire.
6
8
  *
7
9
  * Solves the Time-of-Check vs Time-of-Use (TOCTOU) race condition
8
10
  * where checking a flag and setting it are not atomic operations.
@@ -47,6 +49,10 @@
47
49
  * 8. forceRelease() - Force-release the lock, rejecting every queued waiter
48
50
  * (used by shutdown/cleanup paths; returns whether it was held)
49
51
  *
52
+ * MODULE-LEVEL EXPORT:
53
+ * acquireIfNotHeld(lock, fn) - Run `fn` under `lock` unless the current async
54
+ * context already holds it (canonical re-entrancy guard)
55
+ *
50
56
  * ===============================================================================
51
57
  *
52
58
  * RACE CONDITION PREVENTION:
@@ -2,7 +2,9 @@
2
2
  * modules/order/async_lock.ts - AsyncLock Engine
3
3
  *
4
4
  * Distributed mutual exclusion for async operations.
5
- * Exports a single AsyncLock class that prevents concurrent execution of critical sections.
5
+ * Exports the AsyncLock class (the lock itself) plus the `acquireIfNotHeld()`
6
+ * re-entrancy guard that call sites delegate through instead of inlining the
7
+ * `isReentrant()` check-and-acquire.
6
8
  *
7
9
  * Solves the Time-of-Check vs Time-of-Use (TOCTOU) race condition
8
10
  * where checking a flag and setting it are not atomic operations.
@@ -47,6 +49,10 @@
47
49
  * 8. forceRelease() - Force-release the lock, rejecting every queued waiter
48
50
  * (used by shutdown/cleanup paths; returns whether it was held)
49
51
  *
52
+ * MODULE-LEVEL EXPORT:
53
+ * acquireIfNotHeld(lock, fn) - Run `fn` under `lock` unless the current async
54
+ * context already holds it (canonical re-entrancy guard)
55
+ *
50
56
  * ===============================================================================
51
57
  *
52
58
  * RACE CONDITION PREVENTION:
@@ -74,11 +74,12 @@ import { getStorage } from '../storage/index.js';
74
74
  import { createRequire } from 'node:module';
75
75
  import { path } from '../path_api.js';
76
76
  import * as Format from './format.js';
77
- import { TIMING, DEFAULT_CONFIG } from '../constants.js';
77
+ import { TIMING, DEFAULT_CONFIG, ORDER_TYPES } from '../constants.js';
78
78
  import { PATHS } from '../paths.js';
79
79
  import Logger from '../order/logger.js';
80
80
  import { getErrorMessage } from '../utils/errors.js';
81
81
  import { nowIso } from './utils/system.js';
82
+ import { resolveTradedSide } from './fill_ledger.js';
82
83
  const _require = createRequire(import.meta.url);
83
84
  const storage = getStorage();
84
85
  let _readline = null;
@@ -181,30 +182,36 @@ function deriveTradeFromFillBlock(block, ctx) {
181
182
  if (block.paysRaw == null || block.receivesRaw == null)
182
183
  return null;
183
184
  let hypothesis = null;
185
+ const isOwnAsset = (id) => id === ctx.assetA.id || id === ctx.assetB.id;
184
186
  if (block.paysAssetId && block.receivesAssetId) {
185
- const sellOrientation = block.paysAssetId === ctx.assetA.id && block.receivesAssetId === ctx.assetB.id;
186
- const buyOrientation = block.paysAssetId === ctx.assetB.id && block.receivesAssetId === ctx.assetA.id;
187
- if (!sellOrientation && !buyOrientation)
188
- return null; // foreign-market fill, not ours
189
- hypothesis = buildOrientationHypothesis(block.paysRaw, block.receivesRaw, sellOrientation, ctx);
187
+ // Both sides must be this pair: a block that paid our asset and received
188
+ // a third one is a foreign-market fill, not ours.
189
+ if (!isOwnAsset(block.paysAssetId) || !isOwnAsset(block.receivesAssetId))
190
+ return null;
191
+ if (block.paysAssetId === block.receivesAssetId)
192
+ return null;
193
+ // Side comes from the ledger's one mapping (paid asset => side), never a
194
+ // local copy of it.
195
+ const tradedSide = resolveTradedSide(block.paysAssetId, ctx, null);
196
+ if (tradedSide == null)
197
+ return null;
198
+ hypothesis = buildOrientationHypothesis(block.paysRaw, block.receivesRaw, tradedSide === ORDER_TYPES.SELL, ctx);
190
199
  }
191
200
  else if (block.paysAssetId || block.receivesAssetId) {
192
201
  // Half-present block (truncated log line): exactly one side survived.
193
202
  // Pays present orients directly; receives present inverts
194
203
  // (receives A => pays B => BUY; receives B => pays A => SELL).
195
204
  // A present side matching neither local asset is a foreign-market fill.
196
- let paysIsA;
197
- if (block.paysAssetId) {
198
- if (block.paysAssetId !== ctx.assetA.id && block.paysAssetId !== ctx.assetB.id)
199
- return null;
200
- paysIsA = block.paysAssetId === ctx.assetA.id;
201
- }
202
- else {
203
- if (block.receivesAssetId !== ctx.assetA.id && block.receivesAssetId !== ctx.assetB.id)
204
- return null;
205
- paysIsA = block.receivesAssetId === ctx.assetB.id;
206
- }
207
- hypothesis = buildOrientationHypothesis(block.paysRaw, block.receivesRaw, paysIsA, ctx);
205
+ const present = block.paysAssetId || block.receivesAssetId;
206
+ if (!isOwnAsset(present))
207
+ return null;
208
+ const paidAssetId = block.paysAssetId
209
+ ? block.paysAssetId
210
+ : (block.receivesAssetId === ctx.assetA.id ? ctx.assetB.id : ctx.assetA.id);
211
+ const tradedSide = resolveTradedSide(paidAssetId, ctx, null);
212
+ if (tradedSide == null)
213
+ return null;
214
+ hypothesis = buildOrientationHypothesis(block.paysRaw, block.receivesRaw, tradedSide === ORDER_TYPES.SELL, ctx);
208
215
  }
209
216
  else {
210
217
  // Bare pre-#22 block: no asset orientation logged.
@@ -0,0 +1,99 @@
1
+ /**
2
+ * modules/order/fill_ledger.ts
3
+ *
4
+ * Fill identity, traded-side resolution and booked-fill membership.
5
+ *
6
+ * WHY THIS MODULE EXISTS
7
+ * ----------------------
8
+ * A fill used to be identified, sided and de-duplicated in three places:
9
+ * - `buildFillKey` / `buildOrphanFillFallbackKey` in `dexbot_fill_runtime.ts`,
10
+ * - the pays-asset side mapping copied into `SyncEngine._computeFillContext`,
11
+ * `attributeUnmatchedFillToGrid` (`order/utils/order.ts`) and the queued
12
+ * pivot refresh (`dexbot_cow_runtime.ts`),
13
+ * - the booked-fill check split between `_isNewFillKey` (bot level) and
14
+ * `OrderManager.processedFillStore` (the persisted authority).
15
+ *
16
+ * The copies drifted: `6afa0c4b` had to patch the same "undefined pays asset"
17
+ * collision in three sites at once, and `cb1041b6` had to fix a side that the
18
+ * slot label had laundered. This module is the single owner of the two pure
19
+ * questions ("which fill is this?" and "which side did it trade?") so a fourth
20
+ * copy is a review failure rather than a silent divergence.
21
+ *
22
+ * WHAT IT DOES NOT OWN
23
+ * --------------------
24
+ * - Duplicate *booking* stays with `OrderManager.processedFillStore`; this
25
+ * module only exposes its membership test (`isFillBooked`).
26
+ * - The SPREAD price fallback policy stays with the caller that has the
27
+ * genesis price (`resolveSpreadOrderSide`); `resolveTradedSide` takes the
28
+ * already-resolved fallback side as an argument instead of re-deriving it.
29
+ * - Rails: `slot.type` is the ACCOUNTING side after a partial fill retags it
30
+ * (`sync_engine` PARTIAL transition, see docs/COW_INVARIANTS.md INV-SYNC-008
31
+ * and `cb1041b6`). Rail identity is geometry and is never derived here.
32
+ *
33
+ * Browser-safe: no imports beyond the constants, no `process`/`fs` usage.
34
+ */
35
+ /** Minimal shape the key builder reads (a chain fill op, a history row, or a queue entry). */
36
+ export interface FillKeySource {
37
+ op?: unknown[];
38
+ orderId?: string;
39
+ block_num?: number;
40
+ blockNum?: number;
41
+ id?: string;
42
+ historyId?: string;
43
+ }
44
+ /** Minimal asset-pair shape needed to map a paid asset onto a side. */
45
+ export interface FillSideAssets {
46
+ assetA?: {
47
+ id?: unknown;
48
+ } | null;
49
+ assetB?: {
50
+ id?: unknown;
51
+ } | null;
52
+ }
53
+ /** Persisted dedupe store shape (`OrderManager.processedFillStore`). */
54
+ export interface FillBookedStore {
55
+ tracker?: Map<string, number> | null;
56
+ }
57
+ /**
58
+ * The chain identity of a fill: `orderId:blockNum:historyId`.
59
+ *
60
+ * All three parts are required. A fill without them cannot be de-duplicated
61
+ * across restarts, so callers treat `null` as "no identity" (the fill runtime
62
+ * then tries its orphan fallback key) rather than inventing one.
63
+ */
64
+ declare function fillKeyOf(fillOrParts: FillKeySource | null | undefined): string | null;
65
+ /**
66
+ * The side a fill actually traded, resolved from the asset that was PAID.
67
+ *
68
+ * Paying the quote asset (assetB) buys the base; paying the base (assetA)
69
+ * sells it. This is chain truth and must not be replaced by the slot label:
70
+ * a slot can be retyped (BUY<->SELL) before its resting order is corrected,
71
+ * and the slot type is the ACCOUNTING side after a partial fill (`6afa0c4b`,
72
+ * `cb1041b6`).
73
+ *
74
+ * `fallbackType` is used only when the fill event carries no usable pays
75
+ * asset (legacy/malformed fill). The caller supplies it — the matched slot's
76
+ * type, or a SPREAD slot's price-vs-startPrice resolution
77
+ * (`resolveSpreadOrderSide`) — so the SPREAD policy stays with the site that
78
+ * has the price ladder. A fallback that is not BUY/SELL yields `null`: the
79
+ * side is never guessed from a price here.
80
+ *
81
+ * @param paysAssetId - Asset the fill paid (chain `pays.asset_id`)
82
+ * @param assets - Asset pair (ids only; precisions are not needed)
83
+ * @param fallbackType - Side to use when no pays asset identifies one
84
+ * @returns 'buy' | 'sell' | null
85
+ */
86
+ declare function resolveTradedSide(paysAssetId: unknown, assets: FillSideAssets | null | undefined, fallbackType?: unknown): string | null;
87
+ /**
88
+ * Is this fill already booked?
89
+ *
90
+ * Reads the persisted dedupe authority (`ProcessedFillStore.tracker`) without
91
+ * mutating it. `_isNewFillKey` (bot level) still owns the *claim* — this is
92
+ * the membership question the accounting path asks before it books a credit.
93
+ * An unreadable store is reported as `false` (not booked) deliberately: the
94
+ * caller keeps its existing claim path, and a missing tracker cannot be turned
95
+ * into a silent double credit by this helper.
96
+ */
97
+ declare function isFillBooked(store: FillBookedStore | null | undefined, fillKey: string | null | undefined): boolean;
98
+ export { fillKeyOf, resolveTradedSide, isFillBooked };
99
+ //# sourceMappingURL=fill_ledger.d.ts.map
@@ -0,0 +1,103 @@
1
+ /**
2
+ * modules/order/fill_ledger.ts
3
+ *
4
+ * Fill identity, traded-side resolution and booked-fill membership.
5
+ *
6
+ * WHY THIS MODULE EXISTS
7
+ * ----------------------
8
+ * A fill used to be identified, sided and de-duplicated in three places:
9
+ * - `buildFillKey` / `buildOrphanFillFallbackKey` in `dexbot_fill_runtime.ts`,
10
+ * - the pays-asset side mapping copied into `SyncEngine._computeFillContext`,
11
+ * `attributeUnmatchedFillToGrid` (`order/utils/order.ts`) and the queued
12
+ * pivot refresh (`dexbot_cow_runtime.ts`),
13
+ * - the booked-fill check split between `_isNewFillKey` (bot level) and
14
+ * `OrderManager.processedFillStore` (the persisted authority).
15
+ *
16
+ * The copies drifted: `6afa0c4b` had to patch the same "undefined pays asset"
17
+ * collision in three sites at once, and `cb1041b6` had to fix a side that the
18
+ * slot label had laundered. This module is the single owner of the two pure
19
+ * questions ("which fill is this?" and "which side did it trade?") so a fourth
20
+ * copy is a review failure rather than a silent divergence.
21
+ *
22
+ * WHAT IT DOES NOT OWN
23
+ * --------------------
24
+ * - Duplicate *booking* stays with `OrderManager.processedFillStore`; this
25
+ * module only exposes its membership test (`isFillBooked`).
26
+ * - The SPREAD price fallback policy stays with the caller that has the
27
+ * genesis price (`resolveSpreadOrderSide`); `resolveTradedSide` takes the
28
+ * already-resolved fallback side as an argument instead of re-deriving it.
29
+ * - Rails: `slot.type` is the ACCOUNTING side after a partial fill retags it
30
+ * (`sync_engine` PARTIAL transition, see docs/COW_INVARIANTS.md INV-SYNC-008
31
+ * and `cb1041b6`). Rail identity is geometry and is never derived here.
32
+ *
33
+ * Browser-safe: no imports beyond the constants, no `process`/`fs` usage.
34
+ */
35
+ import { ORDER_TYPES } from '../constants.js';
36
+ /**
37
+ * The chain identity of a fill: `orderId:blockNum:historyId`.
38
+ *
39
+ * All three parts are required. A fill without them cannot be de-duplicated
40
+ * across restarts, so callers treat `null` as "no identity" (the fill runtime
41
+ * then tries its orphan fallback key) rather than inventing one.
42
+ */
43
+ function fillKeyOf(fillOrParts) {
44
+ const fillOp = fillOrParts?.op?.[1];
45
+ const orderId = fillOp?.order_id ?? fillOrParts?.orderId;
46
+ const blockNum = fillOrParts?.block_num ?? fillOrParts?.blockNum;
47
+ const historyId = fillOrParts?.id ?? fillOrParts?.historyId;
48
+ if (!orderId || blockNum == null || !historyId)
49
+ return null;
50
+ return `${orderId}:${blockNum}:${historyId}`;
51
+ }
52
+ /**
53
+ * The side a fill actually traded, resolved from the asset that was PAID.
54
+ *
55
+ * Paying the quote asset (assetB) buys the base; paying the base (assetA)
56
+ * sells it. This is chain truth and must not be replaced by the slot label:
57
+ * a slot can be retyped (BUY<->SELL) before its resting order is corrected,
58
+ * and the slot type is the ACCOUNTING side after a partial fill (`6afa0c4b`,
59
+ * `cb1041b6`).
60
+ *
61
+ * `fallbackType` is used only when the fill event carries no usable pays
62
+ * asset (legacy/malformed fill). The caller supplies it — the matched slot's
63
+ * type, or a SPREAD slot's price-vs-startPrice resolution
64
+ * (`resolveSpreadOrderSide`) — so the SPREAD policy stays with the site that
65
+ * has the price ladder. A fallback that is not BUY/SELL yields `null`: the
66
+ * side is never guessed from a price here.
67
+ *
68
+ * @param paysAssetId - Asset the fill paid (chain `pays.asset_id`)
69
+ * @param assets - Asset pair (ids only; precisions are not needed)
70
+ * @param fallbackType - Side to use when no pays asset identifies one
71
+ * @returns 'buy' | 'sell' | null
72
+ */
73
+ function resolveTradedSide(paysAssetId, assets, fallbackType) {
74
+ const a = assets?.assetA?.id;
75
+ const b = assets?.assetB?.id;
76
+ if (paysAssetId != null && b != null && paysAssetId === b)
77
+ return ORDER_TYPES.BUY;
78
+ if (paysAssetId != null && a != null && paysAssetId === a)
79
+ return ORDER_TYPES.SELL;
80
+ if (fallbackType === ORDER_TYPES.BUY || fallbackType === ORDER_TYPES.SELL)
81
+ return fallbackType;
82
+ return null;
83
+ }
84
+ /**
85
+ * Is this fill already booked?
86
+ *
87
+ * Reads the persisted dedupe authority (`ProcessedFillStore.tracker`) without
88
+ * mutating it. `_isNewFillKey` (bot level) still owns the *claim* — this is
89
+ * the membership question the accounting path asks before it books a credit.
90
+ * An unreadable store is reported as `false` (not booked) deliberately: the
91
+ * caller keeps its existing claim path, and a missing tracker cannot be turned
92
+ * into a silent double credit by this helper.
93
+ */
94
+ function isFillBooked(store, fillKey) {
95
+ if (!fillKey)
96
+ return false;
97
+ const tracker = store?.tracker;
98
+ if (!(tracker instanceof Map))
99
+ return false;
100
+ return tracker.has(fillKey);
101
+ }
102
+ export { fillKeyOf, resolveTradedSide, isFillBooked };
103
+ //# sourceMappingURL=fill_ledger.js.map
@@ -10,12 +10,12 @@
10
10
  *
11
11
  * Asset Amounts: 8 decimals - blockchain native precision
12
12
  * Prices: 6-8 decimals - price precision varies by pair
13
- * Percentages: 1-4 decimals - display precision
13
+ * Percentages: 0-2 decimals - display precision (formatPercentLabel)
14
14
  * Ratios/Metrics: 2-5 decimals - context dependent
15
15
  * Time/Performance (ms, %): 1-2 decimals - readable metrics
16
16
  *
17
17
  * ===============================================================================
18
- * TABLE OF CONTENTS (17 exported functions)
18
+ * TABLE OF CONTENTS (18 exported functions)
19
19
  * ===============================================================================
20
20
  *
21
21
  * SECTION 1: ASSET FORMATTING (4 functions)
@@ -31,20 +31,22 @@
31
31
  * 8. formatCurrency(value, digits) - Grouped thousands with SI micro-suffixes
32
32
  * 9. formatFundsValue(value) - Compact K/M, 4 significant figures (keeps trailing zeros)
33
33
  *
34
- * SECTION 3: PERCENTAGE FORMATTING (2 functions)
34
+ * SECTION 3: PERCENTAGE FORMATTING (3 functions)
35
35
  * 10. formatPercent2(value) - Format to 2 decimals (spread %, ratios)
36
36
  * 11. formatPercent(value, decimals) - Format with custom decimal places
37
+ * 12. formatPercentLabel(value) - Percentage with unit: 2 decimals below 100%,
38
+ * 1 from 100%, 0 from 1000% (fixed-point, never SI-suffixed)
37
39
  *
38
40
  * SECTION 4: RATIO/METRIC FORMATTING (1 function)
39
- * 12. formatMetric2(value) - Format to 2 decimals (timing, performance)
41
+ * 13. formatMetric2(value) - Format to 2 decimals (timing, performance)
40
42
  *
41
43
  * SECTION 5: HELPER UTILITIES (5 functions)
42
- * 13. isValidNumber(value) - Check if value is defined and finite
43
- * 14. toFiniteNumber(value, defaultValue) - Convert to finite number with fallback
44
- * 15. toKnownNumber(value, absentValue) - Convert to finite number, treating an
44
+ * 14. isValidNumber(value) - Check if value is defined and finite
45
+ * 15. toFiniteNumber(value, defaultValue) - Convert to finite number with fallback
46
+ * 16. toKnownNumber(value, absentValue) - Convert to finite number, treating an
45
47
  * explicitly absent value (null/undefined/empty) as the absent sentinel
46
- * 16. positiveOrNull(value) - Convert to a strictly-positive number, else null
47
- * 17. safeFormat(value, decimals, fallback) - Safely format with fallback
48
+ * 17. positiveOrNull(value) - Convert to a strictly-positive number, else null
49
+ * 18. safeFormat(value, decimals, fallback) - Safely format with fallback
48
50
  *
49
51
  * ===============================================================================
50
52
  */
@@ -138,6 +140,18 @@ declare function formatFundsValue(value: number): string;
138
140
  */
139
141
  declare function formatPercent2(value: number): string;
140
142
  declare function formatPercent(value: number, decimals?: number): string;
143
+ /**
144
+ * Percentage including its unit, at display precision.
145
+ *
146
+ * 2 decimals below 100% ("2.27%", "0.40%", "18.18%"), 1 from 100% ("100.0%")
147
+ * and none from 1000% ("1235%"), so a percentage never carries more than four
148
+ * significant digits or a noisy trailing digit on a spread. Fixed-point, so the
149
+ * milli/micro suffixes `formatCurrency` produces for small values ("0.05" ->
150
+ * "50m") can never leak into a percentage.
151
+ *
152
+ * Dependency-free (Math/Number only) so chart exporters can embed it verbatim.
153
+ */
154
+ declare function formatPercentLabel(value: number | null | undefined): string;
141
155
  /**
142
156
  * Format metric to 2 decimal places
143
157
  *
@@ -190,5 +204,5 @@ declare function toKnownNumber(value: unknown): number;
190
204
  * @returns {string} Formatted value or fallback string
191
205
  */
192
206
  declare function safeFormat(value: unknown, decimals: number, fallback?: string): string;
193
- export { formatAmount8, formatAmount, formatAmountByPrecision, formatSizeByOrderType, formatPrice, formatPrice6, formatPrice4, formatCurrency, formatFundsValue, formatPercent2, formatPercent, formatMetric2, isValidNumber, toFiniteNumber, toKnownNumber, positiveOrNull, safeFormat };
207
+ export { formatAmount8, formatAmount, formatAmountByPrecision, formatSizeByOrderType, formatPrice, formatPrice6, formatPrice4, formatCurrency, formatFundsValue, formatPercent2, formatPercent, formatPercentLabel, formatMetric2, isValidNumber, toFiniteNumber, toKnownNumber, positiveOrNull, safeFormat };
194
208
  //# sourceMappingURL=format.d.ts.map