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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dexbot",
3
- "version": "1.7.0",
3
+ "version": "1.7.2",
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": {
@@ -112,12 +112,12 @@
112
112
  "version:check": "npm run build && node dist/scripts/sync-version.js --check",
113
113
  "verify:browser-bundle": "npm run build && node dist/scripts/verify-browser-bundle.js",
114
114
  "test": "npm run build && npm run build:tests && npm run build --prefix claw && npm run typecheck:analysis && node dist/scripts/run-tests.js",
115
- "test:live": "RUN_LIVE_BITSHARES_TESTS=1 npm run build && npm run build:tests && npm run build --prefix claw && npm run typecheck:analysis && node dist/scripts/run-tests.js",
115
+ "test:live": "npm run build && npm run build:tests && npm run build --prefix claw && npm run typecheck:analysis && RUN_LIVE_BITSHARES_TESTS=1 node dist/scripts/run-tests.js",
116
116
  "test:playwright": "npm run build && NODE_PATH=\"$(npm root -g)\" playwright test --config tests/playwright/playwright.config.mjs",
117
117
  "clean": "node scripts/clean-dist.js",
118
118
  "build": "echo \"tsc is compiling ...\" && tsc && chmod +x dist/dexbot.js dist/bot.js dist/unlock.js dist/pm2.js dist/credential-daemon.js",
119
119
  "build:clean": "npm run clean && npm run build",
120
- "build:tests": "tsc -p tsconfig.tests.json && cp tests/package.json dist/tests/package.json && cp tests/helpers/esm_mock_hooks.mjs tests/helpers/esm_mock_loader.mjs dist/tests/helpers/",
120
+ "build:tests": "tsc -p tsconfig.tests.json && cp tests/package.json dist/tests/package.json && cp tests/helpers/esm_mock_hooks.mjs tests/helpers/esm_mock_loader.mjs tests/helpers/foreign_cred_stub.js dist/tests/helpers/",
121
121
  "typecheck": "tsc --noEmit",
122
122
  "typecheck:analysis": "tsc -p analysis/tsconfig.json",
123
123
  "check:any": "npm run build && node dist/scripts/check_any.js",
package/scripts/README.md CHANGED
@@ -67,8 +67,14 @@ All are irreversible and prompt for confirmation.
67
67
  ```bash
68
68
  # Analyzes spread accuracy, geometric consistency, and fund distribution
69
69
  node dist/scripts/analyze-orders.js
70
+
71
+ # One bot (name or key), or every grid on one account (name or 1.2.x id)
72
+ node dist/scripts/analyze-orders.js <bot|account>
70
73
  ```
71
74
 
75
+ Bot/account targets share one rule set with `dexbot credit`, `dexbot pnl` and
76
+ the chart commands (`analysis/bot_key_utils.ts`).
77
+
72
78
  For AMA bots (`gridPrice: ama`) the analyzer reads `<botKey>.dynamicgrid.json`
73
79
  and, when fresh (`2 × MARKET_ADAPTER.RUNTIME_DEFAULTS.pollSeconds`, default 2h),
74
80
  shows live weights with color: higher = red (losing), lower = green (winning),
@@ -84,6 +90,9 @@ node dist/scripts/analyze-credit.js
84
90
 
85
91
  # Single bot (name or key)
86
92
  node dist/scripts/analyze-credit.js <bot>
93
+
94
+ # Every bot trading one account (preferredAccount name or 1.2.x id)
95
+ node dist/scripts/analyze-credit.js <account>
87
96
  ```
88
97
  Credit deals report per-pair and average CR, but only for pairs whitelisted in `bots.json` (`debtPolicy.lending`) and listed on the current credit offer; everything else is shown as ignored/unpriced and excluded from the average. A borrow-now preview per configured pair shows today's rate.
89
98
 
@@ -301,6 +310,13 @@ npm run version:sync
301
310
  | `pdev.sh` | `npm run pdev` | sync `test` → `dev` |
302
311
  | `pmain.sh` | `npm run pmain` | sync `test` → `dev` → `main` |
303
312
 
313
+ Before any push, all three scripts run a shared preflight
314
+ (`scripts/lib/git_preflight.sh`): one read-only `git ls-remote` against `origin`,
315
+ so an unreachable remote or a key the server no longer accepts fails **before** a
316
+ branch moves. `pmain.sh` mirrors `dev` and `main` in a single `--atomic` push —
317
+ either both move or neither does. Set `DEXBOT_SKIP_GIT_PREFLIGHT=1` to bypass
318
+ the preflight.
319
+
304
320
  ---
305
321
 
306
322
  ## ⚡ CONVENIENCE WRAPPERS
package/scripts/pdev.sh CHANGED
@@ -7,6 +7,13 @@ set -e
7
7
 
8
8
  echo "🔄 Starting safe branch synchronization (test -> dev)..."
9
9
 
10
+ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
11
+ # shellcheck source=scripts/lib/git_preflight.sh
12
+ source "$SCRIPT_DIR/lib/git_preflight.sh"
13
+
14
+ # 0. Fail fast when the remote cannot be read — before any branch is touched.
15
+ require_origin_access origin || exit 1
16
+
10
17
  # 1. Ensure we are on 'test'
11
18
  CURRENT=$(git rev-parse --abbrev-ref HEAD)
12
19
  if [ "$CURRENT" != "test" ]; then
@@ -31,8 +38,14 @@ echo "🚀 Synchronizing 'dev' with 'test' on origin..."
31
38
  git push origin test:dev --force
32
39
 
33
40
  # 5. Update local 'dev' branch pointer to match origin
41
+ # Best-effort: the push above already moved origin/dev, so a failure here is
42
+ # cosmetic (a stale local label) and self-heals on the next successful fetch.
34
43
  echo "📍 Updating local 'dev' branch pointer..."
35
- git fetch origin dev:dev --force
44
+ if ! git fetch origin dev:dev --force; then
45
+ echo "⚠️ Local 'dev' pointer was not refreshed — origin/dev is already synced."
46
+ echo " Re-run 'npm run pdev' once the remote is reachable again."
47
+ exit 1
48
+ fi
36
49
 
37
50
  echo "✅ Synchronization complete: test == dev"
38
51
  echo "✨ Your uncommitted changes on 'test' were never at risk."
package/scripts/pmain.sh CHANGED
@@ -8,6 +8,13 @@ set -e
8
8
 
9
9
  echo "🔄 Starting safe branch synchronization..."
10
10
 
11
+ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
12
+ # shellcheck source=scripts/lib/git_preflight.sh
13
+ source "$SCRIPT_DIR/lib/git_preflight.sh"
14
+
15
+ # 0. Fail fast when the remote cannot be read — before any branch is touched.
16
+ require_origin_access origin || exit 1
17
+
11
18
  # 1. Ensure we are on 'test'
12
19
  CURRENT=$(git rev-parse --abbrev-ref HEAD)
13
20
  if [ "$CURRENT" != "test" ]; then
@@ -28,17 +35,25 @@ if ! git push origin test; then
28
35
  exit 1
29
36
  fi
30
37
 
31
- # 4. Force update 'dev' and 'main' on origin (Zero-Checkout)
32
- # This updates the server branches directly from your local test branch
33
- echo "🚀 Synchronizing 'dev' and 'main' on origin..."
34
- git push origin test:dev --force
35
- git push origin test:main --force
38
+ # 4. Force update 'dev' and 'main' on origin in ONE atomic push (Zero-Checkout)
39
+ # --atomic makes the mirror all-or-nothing: either both branches move or neither
40
+ # does, so a refusal can never leave dev ahead of main.
41
+ echo "🚀 Synchronizing 'dev' and 'main' with 'test' on origin (atomic)..."
42
+ if ! git push --atomic origin test:dev test:main --force; then
43
+ echo "❌ Atomic push to dev/main failed — neither branch was moved."
44
+ echo "⚠️ Please check 'git status' or sync manually."
45
+ exit 1
46
+ fi
36
47
 
37
48
  # 5. Update local branch pointers to match origin
38
- # This makes your local 'dev' and 'main' labels match without switching to them
49
+ # Best-effort: the atomic push above already moved origin, so a failure here is
50
+ # cosmetic (a stale local label) and self-heals on the next successful fetch.
39
51
  echo "📍 Updating local branch pointers..."
40
- git fetch origin dev:dev --force
41
- git fetch origin main:main --force
52
+ if ! git fetch origin dev:dev main:main --force; then
53
+ echo "⚠️ Local 'dev'/'main' pointers were not refreshed — origin is already synced."
54
+ echo " Re-run 'npm run pmain' once the remote is reachable again."
55
+ exit 1
56
+ fi
42
57
 
43
58
  echo "✅ Everything is synchronized: test == dev == main"
44
59
  echo "✨ Your uncommitted changes on 'test' were never at risk."
package/scripts/ptest.sh CHANGED
@@ -7,6 +7,13 @@ set -e
7
7
 
8
8
  echo "🔄 Starting safe branch synchronization (test -> origin/test)..."
9
9
 
10
+ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
11
+ # shellcheck source=scripts/lib/git_preflight.sh
12
+ source "$SCRIPT_DIR/lib/git_preflight.sh"
13
+
14
+ # 0. Fail fast when the remote cannot be read — before any branch is touched.
15
+ require_origin_access origin || exit 1
16
+
10
17
  # 1. Ensure we are on 'test'
11
18
  CURRENT=$(git rev-parse --abbrev-ref HEAD)
12
19
  if [ "$CURRENT" != "test" ]; then
package/tests/README.md CHANGED
@@ -33,7 +33,7 @@ claw/tests/ # Claw integration tests (same conventions, run by npm test)
33
33
  - `bitshares_client_stub.ts` — mock blockchain client
34
34
  - `chain_orders_stub.ts` — order lifecycle test doubles
35
35
  - `fee_cache_init.ts` — fee cache seeding for tests
36
- - `order_test_helpers.ts` — order construction utilities
36
+ - `order_test_helpers.ts` — order construction utilities + genesis ladders (`ageChainIdAssignment` settles a fixture's fresh chain id so absence scenarios test the decision, not the in-flight guard)
37
37
  - `silent_logger.ts` — suppresses log output during tests
38
38
  - `module_cache_stub.ts` — isolates module state per test
39
39
  - `vault_fixture.ts` — chain-key vault fixtures
@@ -80,6 +80,10 @@ Research/analysis tools: chart generators, backtests, and the grid-reset replay
80
80
  Order lifecycle, fill processing, trade history, batch execution.
81
81
  *Examples:* `test_open_orders.ts`, `test_fills.ts`, `test_fill_batch_chunking.ts`, `test_fill_replay_guards.ts`, `test_uncertain_broadcast.ts`
82
82
 
83
+ ### Order Lifecycle Registry
84
+ The single answer to "does this order exist on chain, and how sure are we" ([ORDER_LIFECYCLE.md](../docs/ORDER_LIFECYCLE.md)): phases (`unknown ≠ gone`), evidence monotonicity, the unresolved bound, the write funnel (including the COW whole-map commit), and the unified absence guard the sync/reconcile/recovery sites share.
85
+ *Files:* `test_order_lifecycle.ts` (registry + manager integration), `recon_fuzz.ts` (interleaving fuzzer; `RECON_FUZZ_SCENARIOS`/`RECON_FUZZ_STEPS` scale it)
86
+
83
87
  ### Strategy & Grid Logic
84
88
  Grid generation, sizing, rotation, divergence detection, reconciliation.
85
89
  *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`
@@ -204,3 +208,28 @@ Shared utility functions, precision handling, chain helpers.
204
208
  ---
205
209
 
206
210
  **Note:** Interactive/diagnostic scripts (`connection_test.ts`, `diag_*`, `benchmark_cow.ts`, `sim_batching.ts`, `repro_phantom_orders.ts`) require network access or real state and are **not** run by `npm test` — the runner only globs `test_*.js`. Run these manually when debugging.
211
+
212
+ ## Harnesses (not run by `npm test`)
213
+
214
+ Two files are investigative harnesses rather than assertions about production
215
+ code, so they are deliberately *not* `test_*.ts`:
216
+
217
+ - `recon_fuzz.ts` — the interleaving fuzzer for the reconciliation engine. Drives
218
+ the real `SyncEngine` against a scripted chain (landed / vanished / partially
219
+ filled / orphaned / duplicated / lagging / unparseable reads), asserts
220
+ policy-free invariants after **every** event, and shrinks a failing sequence to
221
+ a seed + step count.
222
+
223
+ ```bash
224
+ npm run build:tests
225
+ node dist/tests/recon_fuzz.js # 40 scenarios × 25 steps
226
+ RECON_FUZZ_SCENARIOS=120 RECON_FUZZ_STEPS=40 node dist/tests/recon_fuzz.js
227
+ RECON_FUZZ_TRACE=1 RECON_FUZZ_DEBUG=1 node dist/tests/recon_fuzz.js
228
+ ```
229
+
230
+ `RECON_FUZZ_SEED=<n> RECON_FUZZ_STEPS=<n>` replays a reported failure. The run
231
+ fails if the scenarios are vacuous (coverage floors on placed-slot
232
+ observations and on un-adoptable orphans), so a green run means the engine was
233
+ actually exercised.
234
+
235
+ - `sim_batching.ts` — arithmetic mirror of the gap-slot batch sizing rule.