dexbot 1.6.13 → 1.6.14

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 (93) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/README.md +2 -2
  3. package/claw/docs/AI_BOT_LIBRARY_API.md +1 -1
  4. package/claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md +4 -4
  5. package/claw/modules/claw_catalog.ts +8 -4
  6. package/claw/modules/dexbot_profiles.ts +59 -15
  7. package/claw/modules/types.ts +2 -1
  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/claw/skills/margin-trading/SKILL.md +1 -1
  12. package/claw/skills/margin-trading/references/position-management.md +1 -1
  13. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +25 -25
  14. package/dist/modules/account_bots.d.ts +7 -6
  15. package/dist/modules/account_bots.js +10 -10
  16. package/dist/modules/account_orders.d.ts +36 -4
  17. package/dist/modules/account_orders.js +76 -5
  18. package/dist/modules/bitshares-native/crypto/ecc_core.d.ts +1 -2
  19. package/dist/modules/bitshares-native/crypto/ecc_core.js +1 -1
  20. package/dist/modules/bitshares-native/serial/chain_constants.d.ts +1 -2
  21. package/dist/modules/bitshares-native/serial/chain_constants.js +1 -2
  22. package/dist/modules/bot_defaults.d.ts +16 -2
  23. package/dist/modules/bot_defaults.js +34 -8
  24. package/dist/modules/bot_settings.d.ts +4 -0
  25. package/dist/modules/bot_settings.js +55 -21
  26. package/dist/modules/config.js +6 -1
  27. package/dist/modules/constants.d.ts +7 -5
  28. package/dist/modules/constants.js +12 -5
  29. package/dist/modules/dexbot_class.d.ts +5 -0
  30. package/dist/modules/dexbot_class.js +8 -3
  31. package/dist/modules/dexbot_cow_runtime.d.ts +62 -174
  32. package/dist/modules/dexbot_cow_runtime.js +331 -46
  33. package/dist/modules/dexbot_credential_client.d.ts +1 -16
  34. package/dist/modules/dexbot_credential_client.js +1 -1
  35. package/dist/modules/dexbot_fill_runtime.d.ts +1 -1
  36. package/dist/modules/dexbot_fill_runtime.js +12 -1
  37. package/dist/modules/dexbot_maintenance_runtime.d.ts +18 -80
  38. package/dist/modules/dexbot_maintenance_runtime.js +57 -68
  39. package/dist/modules/dexbot_startup_runtime.js +12 -0
  40. package/dist/modules/dexbot_state_recovery.js +16 -0
  41. package/dist/modules/key_store.d.ts +0 -5
  42. package/dist/modules/key_store.js +1 -1
  43. package/dist/modules/order/accounting.js +11 -11
  44. package/dist/modules/order/export.js +2 -2
  45. package/dist/modules/order/format.d.ts +15 -1
  46. package/dist/modules/order/format.js +19 -1
  47. package/dist/modules/order/genesis_policy.d.ts +1 -1
  48. package/dist/modules/order/genesis_policy.js +1 -1
  49. package/dist/modules/order/grid.d.ts +23 -11
  50. package/dist/modules/order/grid.js +383 -51
  51. package/dist/modules/order/grid_reconcile.d.ts +1 -1
  52. package/dist/modules/order/grid_reconcile.js +5 -5
  53. package/dist/modules/order/grid_reconcile_internal.js +48 -40
  54. package/dist/modules/order/index.d.ts +34 -8
  55. package/dist/modules/order/logger.js +2 -2
  56. package/dist/modules/order/manager.d.ts +9 -2
  57. package/dist/modules/order/manager.js +58 -24
  58. package/dist/modules/order/strategy.d.ts +2 -2
  59. package/dist/modules/order/strategy.js +51 -21
  60. package/dist/modules/order/sync_engine.js +4 -0
  61. package/dist/modules/order/utils/math.d.ts +3 -3
  62. package/dist/modules/order/utils/math.js +38 -27
  63. package/dist/modules/order/utils/order.d.ts +58 -58
  64. package/dist/modules/order/utils/order.js +119 -102
  65. package/dist/modules/order/utils/system.d.ts +193 -6
  66. package/dist/modules/order/utils/system.js +392 -29
  67. package/dist/modules/order/utils/validate.js +26 -4
  68. package/dist/modules/runtime_settings.d.ts +1 -1
  69. package/dist/modules/runtime_settings.js +3 -3
  70. package/dist/modules/types.d.ts +48 -4
  71. package/dist/scripts/analyze-orders.d.ts +1 -1
  72. package/dist/scripts/analyze-orders.js +4 -4
  73. package/dist/scripts/divergence-calc.js +6 -6
  74. package/dist/scripts/validate_bots.d.ts +1 -1
  75. package/dist/scripts/validate_bots.js +3 -3
  76. package/dist/unlock.js +7 -2
  77. package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -2
  78. package/docs/COW_INVARIANTS.md +6 -6
  79. package/docs/DEXBOT_COMPARISON.md +5 -5
  80. package/docs/EVOLUTION.md +8 -7
  81. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +8 -6
  82. package/docs/GRID_PRICE_INVARIANT.md +3 -3
  83. package/docs/GRID_RECALCULATION.md +4 -1
  84. package/docs/GRID_RECONCILE.md +4 -4
  85. package/docs/LIFECYCLE.md +11 -11
  86. package/docs/LOGGING.md +14 -0
  87. package/docs/MPA_CREDIT_USAGE.md +1 -1
  88. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +12 -4
  89. package/docs/README.md +3 -3
  90. package/docs/architecture.md +6 -6
  91. package/docs/developer_guide.md +7 -2
  92. package/package.json +1 -1
  93. package/tests/README.md +1 -1
package/docs/LOGGING.md CHANGED
@@ -255,6 +255,9 @@ Prefix tags used in log messages to help operators identify event types. To find
255
255
  | `[GAP-EVAC]` | `order/utils/validate.ts`, `order/manager.ts`, `dexbot_startup_runtime.ts`, `dexbot_state_recovery.ts` | Stuck in-band (gap-band) order streak warnings, cancel-only evacuation teeth, persisted-streak restore counts |
256
256
  | `[GRID-TYPE-CORRECT]` | `order/grid.ts` | One-time backfill retype of legacy empty slots to rail-typed holes on load |
257
257
  | `[LAST-FILL-GUARD]` | `dexbot_cow_runtime.ts` | Last-fill-guard blocks plus gap-evacuation bypass allows/stale-stamp downgrades |
258
+ | `[RESTAMP-BUY]` | `dexbot_cow_runtime.ts` | BUY emitted at/above the last filled BUY pivot (guard bypass / unjudgeable pivot), counted not blocked (P2) |
259
+ | `[COW-GAP-BAND]` | `dexbot_cow_runtime.ts` | SHADOW: non-spread-correction placement inside the plan gap band, counted not blocked (Mode C(a)) |
260
+ | `[BOUNDARY-DRIFT]` | `order/strategy.ts` | Derived boundary jumped more than the active window in one plan (P2) |
258
261
  | `[TRANSPORT]` | `bitshares-native/transport.ts` | WebSocket keep-alive and reconnect |
259
262
 
260
263
  ## 1.4.8 Markers
@@ -281,6 +284,17 @@ New/updated operator-visible messages added by the uncertain-broadcast and COW h
281
284
  | `⚠ <node>… FAILED attempt N/3 (fill channel unrecoverable for <account>: …)` | **Node strike recorded.** Emitted only after N forced reconnects failed to clear the channel, i.e. the node itself is suspect. A forced reconnect on its own never costs a node a strike — a session-level wedge that clears on the first cycle leaves the strike ledger untouched. Three of these blacklist the node for 24h |
282
285
  | `Forcing reconnect on <node> (<reason>)` | Transport-level forced reconnect (stale api_id escalation or fill-channel watchdog); the node is reported failed so the reconnect prefers another node |
283
286
 
287
+ ### P2 observability + Mode C (2026-10-11)
288
+
289
+ Counter-only signals (none gate placement) surfaced through `getMetrics()`: `refusedCommitCount`, `orphanFillCreditedCount`, `restampBuyAboveAnchorCount`, `boundaryDriftExceedsWindowCount`, `gapBandPlacementShadowCount`.
290
+
291
+ | Message | Meaning |
292
+ |---------|---------|
293
+ | `[COW] Rejecting UPDATE batch pre-broadcast: N target(s) missing on chain (...); grid/chain existence divergence — structural resync required` | Mode C(b): a tracked UPDATE target is gone on chain; the batch aborts cleanly (`UPDATE_TARGET_MISSING`) instead of letting `limit_order_update` abort a chunk mid-broadcast. Followed by a structural resync request |
294
+ | `[RESTAMP-BUY] BUY emitted at ... at/above the last filled BUY ...` | A BUY at/above the last filled BUY pivot got past the LAST-FILL-GUARD (bypass or unjudgeable pivot). Counted, not blocked; warned once per batch |
295
+ | `[COW-GAP-BAND] shadow: N non-spread-correction placement(s) inside the plan's gap band (...)` | Mode C(a) shadow: an in-gap rail placement that is not spread correction / gap evacuation. Counted, never blocked; warned once per batch |
296
+ | `[BOUNDARY-DRIFT] committed boundary X -> planned Y (drift N slots) exceeds active window W; boundary is detached from the market anchor (observability only)` | A single plan moved the boundary more than the active window (absolute recovery anchor or geometry fault). Counted; rate-limited warn |
297
+
284
298
  ---
285
299
 
286
300
  ## Fill History Scan Profiling
@@ -139,7 +139,7 @@ Set `creditOnly: true` on a bot entry to run only the credit runtime — no grid
139
139
  "preferredAccount": "my-account", "debtPolicy": { "lending": [...] } }
140
140
  ```
141
141
 
142
- No trading fields (`assetA`, `assetB`, `startPrice`, `incrementPercent`, `activeOrders`, `reserveOrders`, `botFunds`) are needed.
142
+ No trading fields (`assetA`, `assetB`, `startPrice`, `incrementPercent`, `coreOrders`, `edgeOrders`, `botFunds`) are needed.
143
143
 
144
144
  ```bash
145
145
  dexbot start credit # Background daemon — runs only the credit worker
@@ -72,10 +72,10 @@ local state.
72
72
  | **Infinite loops** | grid-bloat → resync → bloat; plan→skip→restore holes; `NO_FEASIBLE_BOUNDARY` freeze | Cooldowns, grace windows, minimal cancel ladders |
73
73
  | **Silent hangs** | Retries that depended on a future event that never came | Level-triggered scheduling with time-based watchdogs |
74
74
  | **Stale queues** | Queued price corrections replayed onto a resynced grid, reverting good placements | Pre-broadcast validation against the live slot |
75
- | **Shelf / reserve orders** | Non-grid orders poisoning every "orders on grid" counter (issue #27) | Slot-N gating across all counters |
75
+ | **Shelf / edge orders** | Non-grid orders poisoning every "orders on grid" counter (issue #27) | Slot-N gating across all counters |
76
76
 
77
77
  Families **not** detailed in Part II: silent hangs and stale correction queues are covered in
78
- `CHANGELOG.md` (v1.6.1 and v1.6.3 respectively); shelf/reserve orders in issue #27 and the v1.6.x
78
+ `CHANGELOG.md` (v1.6.1 and v1.6.3 respectively); shelf/edge orders in issue #27 and the v1.6.x
79
79
  notes; the grid-price invariant has its own doc — [GRID_PRICE_INVARIANT.md](GRID_PRICE_INVARIANT.md).
80
80
 
81
81
  ### R3. Meta-patterns (the actual "madness")
@@ -295,7 +295,7 @@ Debug line: `[BOUNDARY] boundary=123 sellStart=128 spread=4 anchorProjected=138
295
295
  **#7 Sync-lock/maintenance observability — LANDED.**
296
296
  Throttle `Structural resync defer` to first/last per cap window (was 120/30s); log/retry `[MAINT] n/m failed` with orderId/reason.
297
297
 
298
- **Mode C hardening — OPEN.** (a) COW pre-broadcast gap-band reject; (b) order-existence check off slot→orderId map. Note: the GAP-P1 same-batch cancel that covered commit-time in-gap placement was reverted `e2898e51`; **P3 gate removed `e7231534`** — commit-time in-gap placement is currently covered by `LAST-FILL-GUARD` + adoption (no chain-evidence veto).
298
+ **Mode C hardening — PARTIAL (2026-10-11).** (b) **LANDED** pre-broadcast UPDATE-target existence check off the slot→orderId map: `runPreBroadcastGuards` re-reads every UPDATE action's `orderId` via `chainOrders.batchReadOrders` and refuses the whole batch (`UPDATE_TARGET_MISSING`) + requests a structural resync when a tracked target is gone on chain, instead of letting a `limit_order_update` abort the chunk mid-broadcast. Fails open on a non-Map/errored read (chain rejection remains the backstop), and re-verifies each candidate missing id with a single `readSingleOrder` before declaring it gone so a node lagging behind a just-created order does not false-refuse. **Residual risk (accepted, safe direction):** if that second read also lags/returns null, the batch is refused — a skipped cycle + structural resync, never a half-applied grid. Unexplained `UPDATE_TARGET_MISSING` churn on a slow node is this mechanism. (No dedicated counter on this path, consistent with the other uncounted pre-broadcast refusals; it shows up in error logs.) (a) **SHADOW ONLY** gap-band placement check: non-spread-correction CREATE/UPDATE destinations inside the plan's gap band are counted (`_metrics.gapBandPlacementShadowCount`) and warned, never blocked — enforcement is deliberately withheld because spread correction legitimately places INTO the band and a hard reject would re-open the reverted P1/e2898e51 regression class. Note: the GAP-P1 same-batch cancel that covered commit-time in-gap placement was reverted `e2898e51`; **P3 gate removed `e7231534`** — commit-time in-gap placement is currently covered by `LAST-FILL-GUARD` + adoption (no chain-evidence veto).
299
299
 
300
300
  #### 2.7 Relation to PRICE_FIRST draft
301
301
 
@@ -355,7 +355,15 @@ order of escalation forever — HOLD-010) and **not** from
355
355
  `_lastUnmatchedChainOrdersAt` — the latter refreshes on every observing sync
356
356
  and would make an age gate unfirable (HOLD-007).
357
357
 
358
- Still open: drift logging/alert >active window, re-stamp BUY above anchor metric, refused-commit and orphan-fill counters. Deferred-hold observability is no longer open — the `[HOLD]` summary now names side/price/size/reason/off-grid distance and slow-re-warns on an unchanged hold (`modules/dexbot_maintenance_runtime.ts`, `docs/GRID_PRICE_INVARIANT.md`).
358
+ Still open: none of the listed counters — all four landed 2026-10-11 (see below). Deferred-hold observability is no longer open — the `[HOLD]` summary now names side/price/size/reason/off-grid distance and slow-re-warns on an unchanged hold (`modules/dexbot_maintenance_runtime.ts`, `docs/GRID_PRICE_INVARIANT.md`).
359
+
360
+ P2 additions (2026-10-11, counter-only — none gated behavior):
361
+ - `refusedCommitCount` — incremented once in `recoverRefusedCommit` (the single funnel for all refused/uncertain commit paths), and only for genuine refusals: the poll-confirmed **success** path also routes through this funnel (adoption + fee deduction) and passes `refusedCommit: false`, so it is not counted.
362
+ - `orphanFillCreditedCount` — incremented in `applyReplaySafeOrphanFillAccounting` on an `applied` result (a real proceeds credit; not `duplicate`/`error`/`missing_key`).
363
+ - `restampBuyAboveAnchorCount` — `recordRestampBuyAboveAnchor` counts a BUY emitted at/above the last filled BUY pivot (guard bypass or unjudgeable pivot), warned once per batch; it never blocks.
364
+ - `boundaryDriftExceedsWindowCount` — `calculateTargetGrid` counts a derived boundary that jumps more than the active window in one plan (the detached-boundary signal the removed ANCHOR-DIVERGENCE telemetry used to carry), rate-limited warn.
365
+ - `gapBandPlacementShadowCount` — the Mode C(a) shadow above.
366
+ All five surface through `getMetrics()`; four via the existing `...bot._metrics` spread, and `boundaryDriftExceedsWindowCount` via an explicit overlay of `manager._metrics` (`getMetrics()`), because `calculateTargetGrid` writes it on the manager's metrics object and has no bot reference.
359
367
 
360
368
  #### 3.4 Key code references (from source table)
361
369
 
package/docs/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  This directory contains the comprehensive technical documentation for the DEXBot2 trading bot. It is designed to guide developers from high-level architecture down to the nuances of fund accounting and state management.
4
4
 
5
- **Version context:** v1.6.13 (released).
5
+ **Version context:** v1.6.14 (released).
6
6
 
7
7
  ---
8
8
 
@@ -45,7 +45,7 @@ This directory contains the comprehensive technical documentation for the DEXBot
45
45
  - **API Boundary**: Responsibility split between the AI decision layer and the DEXBot2 execution substrate ([AI_BOT_LIBRARY_API.md](../claw/docs/AI_BOT_LIBRARY_API.md))
46
46
  - **Tuning Reference**: Practical grid-tuning baselines ([DEXBOT2_TUNING_CHEAT_SHEET.md](../claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md))
47
47
  - **Position Management**: Short-position tracking, position health monitoring (3-zone CR model), and shared CR planning via `cr_planner.ts`
48
- - **Skills**: Presentation-only, concept-reference, and launcher-orchestration skill packs for bitshares-guide, margin-trading, launcher-ops, and shared references
48
+ - **Skills**: Presentation-only, concept-reference, and launcher-orchestration skill packs for bitshares-guide, margin-trading, launcher-ops, memu-memory, trend-detection, and shared references
49
49
 
50
50
  ## Operational & Security
51
51
 
@@ -58,7 +58,7 @@ This directory contains the comprehensive technical documentation for the DEXBot
58
58
 
59
59
  ### 📊 [Grid Recalculation](GRID_RECALCULATION.md)
60
60
  *When and why the grid resets.*
61
- - **Reset Sources**: Market-adapter bootstrap, AMA delta, AMA-slope range reset, RMS divergence correction, and fund regeneration
61
+ - **Reset Sources**: Market-adapter bootstrap, AMA delta, AMA-slope range reset, RMS divergence correction, and available-funds resize
62
62
  - **Configuration**: Per-source thresholds, whitelist requirements, and defaults
63
63
  - **Trigger Execution**: How `profiles/recalculate.<botKey>.trigger` is consumed under the fill-processing lock
64
64
 
@@ -620,12 +620,12 @@ mgr.outOfSpread = 3; // three slots beyond the target spread
620
620
  ### Calculation
621
621
 
622
622
  ```javascript
623
- // Calculate how many steps beyond target
624
- const currentSpreadSteps = calculateCurrentSpreadGap();
625
- const targetSpreadSteps = calculateTargetSpread();
626
- const outOfSpreadDistance = Math.max(0, currentSpreadSteps - targetSpreadSteps);
627
-
628
- mgr.outOfSpread = outOfSpreadDistance; // 0 = in spread, 3+ = out
623
+ // Requested extra slots, derived from the live spread vs the target tolerance:
624
+ // calculateCurrentSpread(mgr) -> shouldFlagOutOfSpread(...) returns the slot count.
625
+ mgr.outOfSpread = shouldFlagOutOfSpread(
626
+ calculateCurrentSpread(mgr), nominalSpread, toleranceSteps, buyCount, sellCount, incrementPercent
627
+ );
628
+ // 0 = in spread, 3+ = out
629
629
  ```
630
630
 
631
631
  ---
@@ -141,7 +141,7 @@ A **phantom order** is an order in ACTIVE/PARTIAL state WITHOUT a valid `orderId
141
141
  | **Crawl Candidate** | Furthest active order eligible for rotation |
142
142
  | **Shortage** | Empty slot in the active window that needs an order |
143
143
  | **Surplus** | Order outside the active window that can be rotated |
144
- | **Hard Surplus** | Order beyond the configured window + reserve (`activeOrders` + `reserveOrders`) count |
144
+ | **Hard Surplus** | Order beyond the configured window + reserve (`coreOrders` + `edgeOrders`) count |
145
145
  | **Reserve** | Edge-pinned live order outside the active window (buys at grid floor, sells at grid ceiling); never moves the boundary |
146
146
  | **Dust** | Partial order < 5% of ideal size |
147
147
  | **Dust Cancel** | Immediate on-chain cancel of dust partials on detection (no delay, no timer). Slot freed for a fresh counter-order. |
@@ -779,9 +779,14 @@ createOrderGrid(config)
779
779
  // Initialize with blockchain balances
780
780
  initializeGrid(manager)
781
781
 
782
- // Detect divergence and trigger updates
782
+ // Complete fund trigger: available-funds ratio + over-allocation + the
783
+ // on-chain committed-drift leg (closes the virtual-reservation blind spot)
783
784
  checkAndUpdateGridIfNeeded(manager)
784
785
 
786
+ // Drift-only async accessor (refreshes funds first); its core is folded into
787
+ // checkAndUpdateGridIfNeeded above
788
+ checkCommittedSizeDrift(manager)
789
+
785
790
  // Compare ideal vs. persisted grid
786
791
  compareGrids(calculatedGrid, persistedGrid, manager)
787
792
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dexbot",
3
- "version": "1.6.13",
3
+ "version": "1.6.14",
4
4
  "description": "The first open source trading bot with zero runtime dependencies and a fully adaptive market making strategy.",
5
5
  "main": "dist/modules/dexbot_class.js",
6
6
  "exports": {
package/tests/README.md CHANGED
@@ -82,7 +82,7 @@ Order lifecycle, fill processing, trade history, batch execution.
82
82
 
83
83
  ### Strategy & Grid Logic
84
84
  Grid generation, sizing, rotation, divergence detection, reconciliation.
85
- *Examples:* `test_order_grid.ts`, `test_strategy_logic.ts`, `test_grid_reconcile.ts`, `test_working_grid.ts`, `test_rotation_order_sizing.ts`, `test_strategy_edge_cases.ts`, `test_reserve_orders.ts`
85
+ *Examples:* `test_order_grid.ts`, `test_strategy_logic.ts`, `test_grid_reconcile.ts`, `test_working_grid.ts`, `test_rotation_order_sizing.ts`, `test_strategy_edge_cases.ts`, `test_edge_orders.ts`
86
86
 
87
87
  ### Copy-on-Write (COW) Rebalancing
88
88
  Concurrent-safe rebalancing with isolated working grids — dedicated test suite.