dexbot 1.6.17 → 1.6.18
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.
- package/CHANGELOG.md +32 -0
- package/analysis/README.md +10 -9
- package/analysis/ama_fitting/README.md +2 -2
- package/analysis/bot_fitting/README.md +3 -3
- package/claw/package.json +1 -1
- package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
- package/claw/runtimes/openclaw-plugin/package.json +1 -1
- package/dist/analysis/analyze_args.d.ts +2 -1
- package/dist/analysis/fills_source.d.ts +1 -8
- package/dist/analysis/fills_source.js +1 -1
- package/dist/analysis/grid_correction_check.d.ts +9 -6
- package/dist/analysis/grid_correction_check.js +56 -64
- package/dist/analysis/math_utils.d.ts +1 -1
- package/dist/analysis/trade_profitability.d.ts +1 -1
- package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +3 -3
- package/dist/analysis/trend_detection/huber_scale_variants.d.ts +4 -3
- package/dist/market_adapter/cli_args.d.ts +6 -1
- package/dist/market_adapter/cli_args.js +16 -2
- package/dist/market_adapter/core/kibana_candles.d.ts +5 -1
- package/dist/market_adapter/core/kibana_candles.js +3 -1
- package/dist/market_adapter/core/strategies/regime_gate.d.ts +7 -1
- package/dist/market_adapter/core/strategies/regime_gate.js +3 -1
- package/dist/market_adapter/inputs/cex_candle_parsing.d.ts +7 -2
- package/dist/market_adapter/inputs/cex_candle_parsing.js +3 -1
- package/dist/market_adapter/inputs/fetch_book_data.d.ts +7 -1
- package/dist/market_adapter/inputs/fetch_book_data.js +3 -1
- package/dist/market_adapter/inputs/fetch_cex_synthetic_data.js +2 -11
- package/dist/market_adapter/inputs/fetch_lp_data.d.ts +26 -1
- package/dist/market_adapter/inputs/fetch_lp_data.js +62 -52
- package/dist/market_adapter/inputs/kibana_feed_source.d.ts +14 -2
- package/dist/market_adapter/inputs/kibana_feed_source.js +14 -1
- package/dist/market_adapter/inputs/window_cache.d.ts +14 -3
- package/dist/market_adapter/inputs/window_cache.js +14 -1
- package/dist/market_adapter/lp_chart_runner.d.ts +12 -9
- package/dist/market_adapter/lp_chart_runner.js +3 -1
- package/dist/market_adapter/lp_chart_strategy_loader.d.ts +5 -1
- package/dist/market_adapter/lp_chart_strategy_loader.js +3 -1
- package/dist/market_adapter/market_adapter.d.ts +10 -2
- package/dist/market_adapter/market_adapter.js +10 -11
- package/dist/market_adapter/utils/chain.d.ts +2 -3
- package/dist/market_adapter/utils/file_json_cache.d.ts +5 -1
- package/dist/market_adapter/utils/file_json_cache.js +3 -1
- package/dist/market_adapter/utils/file_lock.js +1 -1
- package/dist/market_adapter/utils/native_history.d.ts +7 -3
- package/dist/market_adapter/utils/native_history.js +3 -1
- package/dist/market_adapter/utils/pair_orientation.d.ts +2 -2
- package/dist/modules/bots_file_lock.d.ts +2 -2
- package/dist/modules/bots_file_lock.js +2 -2
- package/dist/modules/constants.js +6 -3
- package/dist/modules/dexbot_class.d.ts +8 -0
- package/dist/modules/dexbot_class.js +10 -0
- package/dist/modules/dexbot_cow_runtime.d.ts +62 -1
- package/dist/modules/dexbot_cow_runtime.js +461 -43
- package/dist/modules/dexbot_credential_client.d.ts +5 -0
- package/dist/modules/dexbot_maintenance_runtime.js +56 -9
- package/dist/modules/dexbot_startup_runtime.js +7 -1
- package/dist/modules/graceful_shutdown.d.ts +2 -2
- package/dist/modules/graceful_shutdown.js +2 -2
- package/dist/modules/launcher/runtime_mode.d.ts +4 -3
- package/dist/modules/node_manager.d.ts +1 -1
- package/dist/modules/node_manager.js +1 -1
- package/dist/modules/order/accounting.js +2 -1
- package/dist/modules/order/export.d.ts +2 -2
- package/dist/modules/order/export.js +2 -2
- package/dist/modules/order/grid.d.ts +19 -14
- package/dist/modules/order/grid.js +262 -61
- package/dist/modules/order/grid_reconcile.js +5 -1
- package/dist/modules/order/grid_reconcile_internal.js +2 -1
- package/dist/modules/order/index.d.ts +9 -3
- package/dist/modules/order/manager.d.ts +10 -0
- package/dist/modules/order/manager.js +41 -11
- package/dist/modules/order/strategy.js +22 -2
- package/dist/modules/order/sync_engine.d.ts +12 -1
- package/dist/modules/order/sync_engine.js +135 -20
- package/dist/modules/order/utils/math.d.ts +8 -9
- package/dist/modules/order/utils/math.js +24 -13
- package/dist/modules/order/utils/order.d.ts +52 -11
- package/dist/modules/order/utils/order.js +137 -21
- package/dist/modules/order/utils/system.d.ts +73 -29
- package/dist/modules/order/utils/system.js +239 -48
- package/dist/modules/order/utils/validate.d.ts +1 -0
- package/dist/modules/order/utils/validate.js +4 -1
- package/dist/modules/storage/index.d.ts +3 -2
- package/dist/modules/storage/index.js +3 -2
- package/dist/modules/types.d.ts +9 -0
- package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -1
- package/docs/COW_INVARIANTS.md +20 -10
- package/docs/DEXBOT_COMPARISON.md +5 -5
- package/docs/EVOLUTION.md +9 -8
- package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +11 -11
- package/docs/GRID_PRICE_INVARIANT.md +24 -4
- package/docs/GRID_RECONCILE.md +5 -5
- package/docs/LIFECYCLE.md +11 -11
- package/docs/LOGGING.md +15 -2
- package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +123 -36
- package/docs/README.md +1 -1
- package/docs/architecture.md +115 -13
- package/docs/developer_guide.md +12 -0
- package/market_adapter/README.md +9 -4
- package/modules/README.md +18 -14
- package/package.json +4 -3
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,38 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## [1.6.18] - 2026-11-01 - Partial-Fill Re-Anchor Recovery, Rail-Derived Boundary & Live Fill Prices, Edge-Fill Pivot Exclusion, Guard Arity Pinning, CLI `--flag=value`, Export-Surface Cleanup
|
|
6
|
+
|
|
7
|
+
### 2026-11-01
|
|
8
|
+
|
|
9
|
+
- **Fix(spread)**: harden partial-fill re-anchor and recovery — a live market-pair bot stayed out of spread after a sell sweep even though the correction loop ran; four independent gaps combined. (1) A gap-evacuation plan built against an older boundary executed as a normal update once its live-geometry stamp went stale, moving valid in-rail buys off the bid edge and re-opening the spread: the build loop now skips a stale evacuation instead of falling through to the direction-only last-fill guard, and the final pre-broadcast gate drops a stamp whose live geometry went stale after op-building, including when the fill pivot itself did not change. (2) The fill anchor could not repair a window left behind a PARTIAL fill — the residual at the fill slot is inside the implied band by construction, so `validatePersistedBoundary` refused every re-anchor; the fill's own PARTIAL residual is now explicitly allow-listed (same side, same ladder level, exact anchor slot) while ACTIVE/foreign in-band orders still refuse, plus a post-clamp check that fails closed when the grid ceiling prevents the fill from leaving its window. (3) A re-anchor is absolute, but its plan carried only the derivation's consumed-crawl subset, so older owed deltas could be applied on top of the new boundary later: a successful re-anchor now snapshots and consumes the whole plan-time crawl ledger, and records recorded after plan build survive. (4) Create-only repair cannot close a fully allocated rail (free funds read 0 forever): when free funds cannot fund every promoted gap slot, a resting same-side ACTIVE order is rotated into the unfunded slot at its booked size (no new commitment, no growth/shrink; edge and PARTIAL sources excluded, crossing/last-fill/grid-price guards unchanged), rotation destinations come from the post-dedupe/post-duplicate-price candidate list so an already-occupied price cannot receive one, and rotation-only plans count as executable. Review hardening: startup and resume/reconcile load paths pass `tolerateTransientStranding` (the re-anchor deliberately leaves the fill's own PARTIAL residual in-band, so a strict load would rebuild the boundary away on the first restart); `reanchorBoundaryFromLastFill` requires `lastFillPivotSource === 'fill'`, because a one-sided book seed is a pricing hint for the guard, never an absolute geometry anchor (the bot-scoped last-market-fill row is the fallback); exactly-zero free funds now reach the rotation-only repair on the initial check, the TOCTOU re-plan and the fresh-master re-plan when the side decision carries the structured `no-free-funds` code (an unavailable market price stays a hard skip); and `plannedCount` includes rotation candidates so `checkSpreadCondition` reports the post-guard executed count rather than the plan count. Files: `order/grid_reconcile.ts`, `order/utils/system.ts`, `order/utils/math.ts`, `order/strategy.ts`, `order/grid.ts`, `dexbot_cow_runtime.ts`, `dexbot_startup_runtime.ts`; covered by `tests/test_stale_evac_build_skip.ts` and extended re-anchor, restore-validation, crawl-ledger, final-pivot-gate, spread-correction and pure-fund-driven tests.
|
|
10
|
+
|
|
11
|
+
- **Fix(order)**: keep the boundary on the placed rails and judge geometry by live fill prices — a sell sweep places counter BUYs on the promoted rail, but the refill hold kept the old committed boundary when the opposite-side refills were guard-skipped, so the next plan reclassified those counters as in-band and rotated SELLs onto their price, collapsing a 1.5% band to 0.3%; separately, a refused-commit adoption can leave a master slot keyed at an old generation price while its chain order trades elsewhere, and the fill pivot, GAP-EVAC and the crossing guard all trusted that stale price. `deriveRailBoundary` now clamps the committed boundary to the batch's resulting rails (`maxBuy <= boundary <= minSell-gap-1`, live master + kept op destinations) so counter orders win over empty refill holes, crossed or over-ceiling rails fail closed instead of self-legalizing, and `boundaryHeld` follows the value actually committed. Fill records now carry the chain execution price (history pays/receives, pass-1 chain price, pass-2 adoption, phantom cleanup) and the queued-fill pivot refresh prefers fill economics over the slot price without rewriting slot identity prices (GRID-PRICE-INVARIANT); `reanchorBoundaryFromLastFill` anchors on the fill batch's extremum for that side (max SELL/min BUY) rather than the mutable last-processed pivot, so a chunked sweep cannot leave its furthest counter in-band; new `resolveLiveOrderLadderPosition` maps the live chain price onto the ladder before falling back to the slot id for detection, drain-time validation and the eviction teeth, and a price mismatch whose live price is in-band queues a cancel-only `gapEvacuation` and drops any plain re-price for that chain order; the crossing candidate set uses the live chain price so an emission cannot print onto an opposite-side order adopted at a stale slot price. Risk: transient decisions follow the chain price while the grid slot identity stays frozen, and rail cross/ceiling failures keep the previous boundary and defer to GAP-EVAC. Covered by new `tests/test_rail_derived_boundary.ts` and `tests/test_live_geometry_provenance.ts` plus batch-extremum cases in `test_boundary_fill_reanchor`.
|
|
12
|
+
|
|
13
|
+
- **Fix(order)**: never arm the last-fill pivot from an edge-pinned fill — an edge order (grid floor/ceiling) is static fat-finger insurance, not market movement, yet `recordLastFilledPrices` armed the pivot on every fill and the pivot doubles as the absolute geometry anchor for `reanchorBoundaryFromLastFill`, so a wick that triggered a floor insurance BUY moved the window onto the grid edge (observed: boundary 29 -> 0 on a 60-slot ladder; mirrored at the ceiling). Eligibility now lives at the single pivot writer: fill ids are classified with `collectEdgePinnedFillIds` (`modules/order/utils/order.ts`), the same window/edge classifier the placement pickers use, so "edge" cannot mean two things; PARTIAL fills still arm the pivot (a partial at a far slot is a real trade and its residual is already allow-listed by the re-anchor). Behavioural impact: an edge fill no longer vetoes its own side of the book and can no longer drive an absolute boundary move — the guard and the anchor stay on the last WINDOW trade, so that side stays vetoed relative to it until a window fill or the 24h pivot TTL (the pre-fix alternative moved the whole window). The skip is logged (`[FILL-PIVOT] ... edge-skipped=K` plus a dedicated edge-only-batch line). Covered by new `tests/test_edge_fill_pivot.ts` and REANCHOR-18/19.
|
|
14
|
+
|
|
15
|
+
- **Fix(guard)**: pin the direction-only guard arity, re-arm the pivot explicitly, and stop self-legalizing the rail clamp — review follow-ups on the v1.6.12 -> v1.6.17 order-engine arc. `isLastFillGuardBlocked` still carried two dead parameters (`size`, `increment`) left over from the removed `pivot +/- increment/2` band, and keeping them made a band-rule reintroduction a compile-time non-event: the signature is now `(price, type, lastPrice, lastType)` at every call site (COW CREATE/rotation/fallback gates, planner predicate), and LFG-5 pins `.length === 4` plus "trailing arguments cannot resurrect a band". `initializeGrid` cleared the generation-bound pivot while its comment claimed the guard re-arms on the first real fill, and the read-time fallback silently kept an old-generation value, so after a rebuild in a market that had moved away one side read `last-fill-blocked` forever while the geometry clock rebuilt the generation every cooldown with no way to succeed: `rearmLastFillPivotFromMarketFill` now writes the re-arm explicitly through the one pivot writer (provenance `fill`, original fill timestamp, logged), and the geometry-bind escalation re-centers at most ONCE per pivot value (`_lastGeometryResyncPivotKey`) before reporting that only a fill or the 24h pivot TTL restores the side. `deriveRailBoundary` clamped onto EVERY live rail order, so one stray (refused-commit adoption, stranded hold, guard straggler) 18 slots off pulled the boundary 138 -> 115 and re-typed the whole window: rail membership is now the batch's own op destinations plus master orders on their own side of the planned boundary, strays are skipped and named in the log, rail indices come from the live chain price (`resolveLiveOrderLadderPosition`) instead of a possibly stale slot id, and the result passes the shared `validatePersistedBoundary` gate (cancel/rotation sources allow-listed, skipped on a sparse ladder whose array-derived ceiling would reject everything). Crossing CREATEs are observed rather than vetoed — a hard veto would re-open the counter-order deadlock after a gap — via `warnCrossingCreate`, logged once per batch from already-cached evidence (no chain call). Same pass: one pivot resolver (two verbatim copies merged), one boundary validator shared by the re-anchor and the rail clamp, and the batch-extremum logic extracted as the pure `resolveFillAnchorIndex`. Files: `order/utils/system.ts`, `order/utils/order.ts`, `order/grid.ts`, `order/grid_reconcile*.ts`, `dexbot_cow_runtime.ts`; covered by new `tests/test_last_fill_pivot_rearm.ts` plus RAIL-10..14, SLF-11/12 and arity updates in LFG-5, FG-9, GPI-WIRE-003 and SGP-1/4.
|
|
16
|
+
|
|
17
|
+
- **Fix(spread)**: count last-fill-excluded candidates per slot — the planner's "Excluded N candidate(s)" line counted pool visits, and a slot can legitimately appear in more than one candidate pool (an empty in-rail slot normalized to SPREAD satisfies both the SPREAD pool and the orphan pool, which the merge already dedupes), so every vetoed slot was reported twice and the over-count was worst exactly when the pools overlapped most. That number decides the `last-fill-blocked` stall and is the only signal for how much of a side the pivot blocked, so inflating it overstated the geometry bind. The counter now de-duplicates by slot id (an unidentified candidate still counts, since it cannot be matched); the plan itself is unchanged, the filter being a predicate and not a side effect. SLF-13 pins the overlap (`Excluded 2`, not `4`) and was verified failing on the pre-fix tree.
|
|
18
|
+
|
|
19
|
+
- **Refactor(analysis)**: judge fills by the direction-only guard — `analysis/grid_correction_check.ts` still implemented the old `pivot +/- increment/2` band while claiming to mirror `isLastFillGuardBlocked` 1:1, so it reported exactly the tightening placements the live guard allows. The predicate now matches the runtime rule (BUY < last fill, SELL > last fill, equal price blocked) with the same four arguments; the band fields are gone from the report header, violation table and JSON payload (per-row `halfInc` stays 0 so existing consumers keep their shape); `--increment` is documented as informational (default and configured value still reported); and the guard section of `analysis/README.md` documents the offline limits — edge-pinned fills cannot be reconstructed from the fill stream, so wick/insurance fills can appear as violations, and the spread-correction bypass is invisible per fill. Offline report only: no live behaviour change.
|
|
20
|
+
|
|
21
|
+
- **Feat(analysis)**: step SMA/VWMA period controls by 10 — the chart toolbar's period steppers moved one unit per click, making broad sweeps (e.g. 500 -> 600) tedious and hold-to-repeat slow. SMA and VWMA up/down buttons now step by 10 per click and per hold tick, the SMA arrow floor rises from 1 to 10 to match the 10-unit step, and the VWMA lower clamp/arrow floor drops from 24 to 10 so the 10-step sequence is reachable across the whole allowed range (manual entry unaffected apart from the lower clamp). AMA controls and chart rendering are unchanged.
|
|
22
|
+
|
|
23
|
+
- **Refactor(market_adapter)**: remove dead paths and narrow the test surface — the adapter still carried a native-history fallback that could never run (adapter_client exposes only db/history proxies, so `history.getMarketHistory` is always present and `BitShares.tradeHistory` never existed on the client shape), the CEX seeder's `typeof`/`||` guards re-checked helpers destructured from a `require` that would already have thrown, and seven types were exported although only used inside their defining modules. 41 test-only named exports became one explicit `__test` object per module: production callers keep the same public surface, tests still reach the internal seams, and future dead-export scans no longer need to special-case white-box helpers. The LP exporter CLI drift is fixed by routing it through the shared `walkCliArgs` walker (with `--help`, unknown flags rejected instead of silently ignored, and `--chunkMonths`, `--apiKey`, `--out` documented), the README no longer claims the adapter only handles 1h candles, and the file-lock default payload no longer writes an owner UUID into `pid` — it records `runtime.pid` while keeping the unique ownerId for release checks.
|
|
24
|
+
|
|
25
|
+
- **Fix(market_adapter)**: accept `--flag=value` and validate the LP export CLI — `walkCliArgs` rejected any value token starting with `--`, so a path or API key beginning with `--` could not be passed at all, and the LP exporter had drifted onto bare `parseInt`, silently storing `NaN` for `--chunkMonths abc`. The walker now understands `--flag=value` (the escape hatch for flag-shaped values), refuses an inline value on a flag/help that takes none, and reports an unknown token exactly as typed; the exporter routes its options through validating helpers (`--chunkMonths` an integer >= 1, `--precA`/`--precB` integers >= 0 with an empty inline value no longer read as 0, `--apiKey`/`--out` non-empty) and `--help` documents the `=` form. Behavioral impact for `fetch_lp_data`: unknown flags still fail, invalid numbers now fail naming the flag instead of producing `NaN`, and a flag-shaped value must use `--flag=value`. Covered by new `tests/test_cli_args_walker.ts` and extended `tests/test_fetch_lp_data_logic.ts`.
|
|
26
|
+
|
|
27
|
+
- **Fix(build)**: export the credential response type and pin the backtest slope test — the claw credential wrapper infers `Promise<CredentialDaemonResponse>` from the imported client, but declaration emit cannot name a module-private interface there, so `npm run build --prefix claw` failed with TS4058; the type is exported again (compile-time surface only, with a comment explaining why it must stay exported). `test_backtest_bot_fitting_logic` still hardcoded the old 0.09 AMA max-slope default and failed once the canonical constant moved to 0.1, so the full/half/sub-strength inputs are derived from `MARKET_ADAPTER.DYNAMIC_WEIGHT_AMA_MAX_SLOPE_PCT` and track the production knob instead of drifting on the next tune. Both restore a green `npm test` (331/331 files, 14 live tests skipped) and `build --prefix claw` on this branch.
|
|
28
|
+
|
|
29
|
+
- **Test(guards)**: enforce the `__test` seam and run the analysis typecheck in `npm test` — the `__test` convention replaced 41 named exports with one seam object per module, but nothing prevented production code from importing that object, so a future caller could quietly build on a test-only surface; and the standalone analysis tsconfig (stricter: `noUnusedLocals`/`noUnusedParameters`) was reachable only through `npm run typecheck:analysis`, so it could rot unnoticed. `tests/test_public_surface_guard.ts` scans every production `.ts` file (modules, market_adapter, analysis, scripts, claw and the root entrypoints) and fails if `__test` is referenced without defining a seam or if a seam is touched more than once inside its defining module, and `npm test` / `npm run test:live` now run `typecheck:analysis` before the suite.
|
|
30
|
+
|
|
31
|
+
- **Refactor(analysis)**: drop dead exports and correct stale docs — the analysis surface is aligned with its real callers and output locations: the README states that shared chart/bot-key helpers are imported by the production market adapter and that `--source market_adapter` prefers the bot candle cache before the centers file; the AMA optimizer/backtest docs point at `analysis/results/` (`PATHS.ANALYSIS.RESULTS_DIR`), not `analysis/ama_fitting/`; zero-consumer exports are narrowed back to internal types; the inert `analysis/.npmignore` is removed (the package `files` allowlist already ships only the analysis READMEs plus uplot); and `analysis/tsconfig.json` is wired into `typecheck:analysis` so the standalone config is actually used. **Removed CLI surface**: the deprecated `--tolerance` alias of `grid_correction_check` is gone — its band no longer exists and `--increment` already carries the report label.
|
|
32
|
+
|
|
33
|
+
- **Refactor(modules)**: remove dead exports, params and the slot-helper shim — an audit of `modules/` found no unreachable files or unused locals, but a layer of vestigial surface: ten symbols are de-exported (the remaining over-export candidates stay exported because declaration emit needs them named across modules, TS4023/TS4058), the `parseSlotIndex` forwarding wrapper and re-export in `order/utils/order.ts` are dropped so all callers import the canonical helper from `order/utils/slot.ts` and the two copies cannot drift again, the `calculateOrderCreationFees` JSDoc is corrected, and `lazy_shim.ts` / `launcher/runtime_mode.ts` are documented in `modules/README.md`. **Breaking for out-of-tree `dist/` consumers**: `allocateFundsByWeights`, `calculateOrderSizes` and `calculateRotationOrderSizes` lose their unused trailing `minSize`/`minSellSize`/`minBuySize` parameters (every in-repo caller passed 0, so behaviour is unchanged); in-tree call sites and tests are updated positionally.
|
|
34
|
+
|
|
35
|
+
- **Docs**: symbol-name citations and export-surface rules replace drifted line numbers, and the module map is corrected — 36 of 64 `file.ts:LINE` references in `docs/` no longer pointed at the code they described, so every one is now a symbol name plus filename, which also removed three outright-wrong claims (a deleted `computeOutOfToleranceDriftTag` listed as a live `priceForSlot` consumer, a non-existent `ANCHOR.PROJECTION_ENABLED` asserted dead three times, and a misnamed maintenance entry point); two documented symbols were corrected and deliberately removed ones keep only the filename. `modules/README.md` moves `runtime_mode.ts` into the `launcher/` block (it was the only tree entry resolving to nothing), fixes descriptions that sent readers to the wrong subsystem (`chain_keys` as the master-password vault plus signing-key retrieval, `credential_runtime` as socket/path helpers, `daemon_node_health` as a failure ledger with no health checking, `socket_json_client` as newline-delimited JSON rather than JSON-RPC, `storage/browser_adapter` as an IndexedDB-persisted Map), unwraps two markdown links that sat inside a fenced tree, names the real crypto split and fill wiring in the principles, and re-aligns three one-column-off rows; module-header usage snippets that used CommonJS `require()` in a `"type": "module"` package now use static imports with `.js` specifiers. `developer_guide` gains an "Export Surface & Test Seams" section (declaration emit is a real consumer, shipped `dist/` is a public API, test-only helpers live in one `__test` object enforced by `tests/test_public_surface_guard.ts`), and `ORDER_ENGINE_POST_1.0_RETROSPECTIVE` is reconciled with the code: §0/§6/§7 described the offline checker with old band semantics, §9.1/§9.7/§9.9 carried pre-fix statements, the header/TOC/snapshot/footer said v1.6.14, the §9.5 ledger gained rows for the whole 1.6.15/1.6.17 arc and the post-1.6.17 work, §9.6 gained four invariants (only a window trade may become the pivot, one boundary validator, a rail clamp cites only its own evidence, the pivot has a lifetime), and R2-R5 record the "one rule, several implementations" meta-pattern plus lessons 8-11. `COW_INVARIANTS`, `architecture`, `GRID_PRICE_INVARIANT` and `LOGGING` document the new rail-clamp membership, re-anchor eligibility, explicit re-arm, once-per-pivot re-center, `[COW-CROSS-GUARD]` line, capped re-center warning and the per-slot "Excluded N" count. Docs/comments only; `npm test` 331/331.
|
|
36
|
+
|
|
5
37
|
## [1.6.17] - 2026-10-30 - Last-Fill Direction Guard, Spread-Correction Stall Naming & Chain-Truth Funding, Owed-Crawl Consumption, Restart Auth-Before-Stop, Pool-Priced LP Collateral, Supply Distribution Analyzers
|
|
6
38
|
|
|
7
39
|
### 2026-10-30
|
package/analysis/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Analysis
|
|
2
2
|
|
|
3
|
-
Tools that inspect DEXBot trading behavior and the market data it operates on. Output is interactive HTML charts written to `charts/` (regenerated on each run, not committed)
|
|
3
|
+
Tools that inspect DEXBot trading behavior and the market data it operates on. Output is mostly interactive HTML charts written to `charts/` (regenerated on each run, not committed) and JSON results under `results/`; the trade analyzers can also export CSV/JSON to a caller-supplied path. The runners are research-only, but their shared chart and bot-key helpers are imported by the production market adapter.
|
|
4
4
|
|
|
5
5
|
## Contents
|
|
6
6
|
|
|
@@ -22,7 +22,7 @@ Tools that inspect DEXBot trading behavior and the market data it operates on. O
|
|
|
22
22
|
|------|----------------|------------------|
|
|
23
23
|
| [`trade_profitability.ts`](#trade-profitability-analyzer-trade_profitabilityts) | "Is my bot making money?" — PnL, R-multiples, drawdown | `npm run analysis:trade-pnl -- <account-id>` |
|
|
24
24
|
| [`dexbot pnl`](#pnl-html-report-dexbot-pnl) | "Give me a readable PnL report" — self-contained HTML with a lot table | `dexbot pnl <bot\|account> --month 3` |
|
|
25
|
-
| [`grid_correction_check.ts`](#last-fill-guard-check-grid_correction_checkts) | "Are fills respecting the
|
|
25
|
+
| [`grid_correction_check.ts`](#last-fill-guard-check-grid_correction_checkts) | "Are fills respecting the direction-only last-fill guard?" | `npm run analysis:grid-check -- --bot-key <bot-key>` |
|
|
26
26
|
| [`analyze_risk_profile.ts`](#risk-profile-analyzer-analyze_risk_profilets) | "How wide should my Safe Range clamps be?" | `node dist/analysis/analyze_risk_profile.js --bot-key <bot-key>` |
|
|
27
27
|
| [`analyze_trade_heatmap.ts`](#trade-heatmap-analyze_trade_heatmapts) | "Where did trade volume cluster vs the AMA?" | `node dist/analysis/analyze_trade_heatmap.js --bot-key <bot-key>` |
|
|
28
28
|
| [`tradingview/analyze_tradingview.ts`](#tradingview-chart-tradingviewanalyze_tradingviewts) | "Just give me a candle chart" | `dexbot tv <bot-key>` |
|
|
@@ -76,14 +76,14 @@ node dist/analysis/analyze_dynamic_weight.js --bot-key <bot-key>
|
|
|
76
76
|
npm run analysis:trade-pnl -- 1.2.123456 --hours 168
|
|
77
77
|
```
|
|
78
78
|
|
|
79
|
-
> The market adapter source
|
|
79
|
+
> The market adapter source prefers the bot's cached candle file and falls back to `market_adapter/state/market_adapter_centers.json` — run the bot first to populate state.
|
|
80
80
|
> Prefer the `npm run analysis:*` shortcuts; they wrap the compiled runners with the same flags (see [npm Script Shortcuts](#npm-script-shortcuts) for the full mapping).
|
|
81
81
|
|
|
82
82
|
## Data Prerequisites
|
|
83
83
|
|
|
84
84
|
Most runners expect candle data. Two paths to get it:
|
|
85
85
|
|
|
86
|
-
**Market adapter source** (default for most runners) —
|
|
86
|
+
**Market adapter source** (default for most runners) — resolves the bot's cached candle file first, then falls back to `market_adapter/state/market_adapter_centers.json`. No setup needed; just run the bot first to populate state.
|
|
87
87
|
|
|
88
88
|
**LP candle files** — for deeper analysis with full OHLC data:
|
|
89
89
|
|
|
@@ -258,9 +258,11 @@ All amounts use the shared 4-significant-figure formatter (compact `K`/`M`, sign
|
|
|
258
258
|
|
|
259
259
|
### LAST-FILL-GUARD Check (`grid_correction_check.ts`)
|
|
260
260
|
|
|
261
|
-
Validates LAST-FILL-GUARD discipline from the same Kibana fill pipeline as `trade_profitability.ts`.
|
|
261
|
+
Validates LAST-FILL-GUARD discipline from the same Kibana fill pipeline as `trade_profitability.ts`. The rule is **direction only** (v1.6.16+): with the previous fill at price `p`, the next order must satisfy `BUY < p` and `SELL > p` (equal price is blocked — a re-place at the just-filled level). There is no increment band: the older `pivot ± i/2` rule blocked a BUY below a SELL fill and a SELL one tick above our cost, i.e. it flagged the tightening placements the engine legitimately makes. A violation is a buy fill at/above its pivot or a sell fill at/below it.
|
|
262
262
|
|
|
263
|
-
**
|
|
263
|
+
**Offline limits:** the tool reconstructs pivots from consecutive fills, so it cannot see the runtime's edge-pinned-fill exclusion (no slot identity per fill) nor the spread-correction bypass — expect rare false positives on wick/insurance fills.
|
|
264
|
+
|
|
265
|
+
**Pipeline:** Kibana `fill_order` query (paginated `search_after`) → on-chain asset precision resolution → buy/sell classification → chronological sort → per-order/price-epoch aggregation (partial fills at one price collapsed to weighted-average; repriced order lifetimes kept separate) → consecutive direction comparison → violation report with daily histogram.
|
|
264
266
|
|
|
265
267
|
```bash
|
|
266
268
|
# Per-order aggregated check (default), last 7 days
|
|
@@ -272,7 +274,7 @@ npm run analysis:grid-check -- --bot-key <bot-key> --hours 720 --json out.json -
|
|
|
272
274
|
# Raw fill granularity instead of per-order aggregation
|
|
273
275
|
npm run analysis:grid-check -- --bot-key <bot-key> --per-fill --hours 168
|
|
274
276
|
|
|
275
|
-
# Override the bot's configured grid increment
|
|
277
|
+
# Override the bot's configured grid increment (informational: the guard has no band)
|
|
276
278
|
npm run analysis:grid-check -- --bot-key <bot-key> --hours 168 --increment 0.5
|
|
277
279
|
```
|
|
278
280
|
|
|
@@ -287,10 +289,9 @@ Exit code `0` = pass, `2` = violations found, `1` = fatal error. Bot keys resolv
|
|
|
287
289
|
| `--start <iso>` / `--end <iso>` | — | Absolute time window |
|
|
288
290
|
| `--account <id>` | bot `preferredAccount` | Override account ID or name |
|
|
289
291
|
| `--refresh-account` | off | Force re-resolution of `preferredAccount` and update the stored `accountId` when it changed |
|
|
290
|
-
| `--increment <pct>` | bot config / `0.5` | Grid increment
|
|
292
|
+
| `--increment <pct>` | bot config / `0.5` | Grid increment (informational only — the guard is direction-only and uses no band) |
|
|
291
293
|
| `--per-fill` | off | Check at fill granularity instead of per-order aggregated |
|
|
292
294
|
| `--include-cross-pair` | off | Also check consecutive fills across different pairs |
|
|
293
|
-
| `--tolerance <pct>` | — | Deprecated compatibility alias for `--increment`; its value is doubled and a warning is emitted |
|
|
294
295
|
| `--json <file>` / `--csv <file>` | — | Export violations |
|
|
295
296
|
| `--verbose` | off | Print the fetched trade sequence before checking |
|
|
296
297
|
| `--list-bots` | — | List available bot keys and exit |
|
|
@@ -10,7 +10,7 @@ parameters into `profiles/market_profiles.json` for the market adapter.
|
|
|
10
10
|
|
|
11
11
|
```
|
|
12
12
|
1. fetch_lp_candles.ts → market_adapter/data/lp/<pairFolder>/lp_pool_<poolShort>_<interval>.json
|
|
13
|
-
2. optimizer_high_resolution.ts → optimization_results_*.json
|
|
13
|
+
2. optimizer_high_resolution.ts → analysis/results/optimization_results_*.json
|
|
14
14
|
→ profiles/market_profiles.json (only with --write-profiles)
|
|
15
15
|
3. scripts/generate_lp_chart.ts → market chart + comparison chart (visual review)
|
|
16
16
|
- LP chart: `npm run lp:chart -- --data <lp-export.json>`
|
|
@@ -156,7 +156,7 @@ Source: pool 133 `IOB.XRP/BTS`, 1h candles, 2023-04-12 00:00 UTC through
|
|
|
156
156
|
2026-04-11 23:00 UTC (the working-tree dataset `analysis/ama_fitting/data/lp_pool_133_iob.xrp_bts_1h.json`, regenerated by a local `fetch_lp_candles.ts` run).
|
|
157
157
|
|
|
158
158
|
**Outputs:**
|
|
159
|
-
- `analysis/
|
|
159
|
+
- `analysis/results/optimization_results_<datafile>_w<λ1>_<λ2>_<λ3>_<λ4>.json` — full results (e.g. `_w0_0031_0_0025_0_00185_0_0013`)
|
|
160
160
|
- `analysis/charts/optimization_chart_<datafile>_w<λ1>_<λ2>_<λ3>_<λ4>.html` — interactive AMA overlay chart (auto-generated)
|
|
161
161
|
- `profiles/market_profiles.json` — updated with new AMA parameters per pair only when `--write-profiles` is used
|
|
162
162
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
## Bot Fitting Backtest
|
|
2
2
|
|
|
3
|
-
This folder contains parameter sweep backtests that simulate grid fills for the four AMA winners
|
|
3
|
+
This folder contains parameter sweep backtests that simulate grid fills for the four AMA winners produced by the optimizer in `analysis/ama_fitting/` (results land in `analysis/results/`).
|
|
4
4
|
|
|
5
5
|
### What it optimizes
|
|
6
6
|
|
|
@@ -74,7 +74,7 @@ microstructure, and no consolidation/dust-cancel/COW/collision mechanics.
|
|
|
74
74
|
Both scripts require:
|
|
75
75
|
|
|
76
76
|
- **LP candles JSON** (recommended 1h), from `market_adapter/data/lp/` — pass via `--data`
|
|
77
|
-
- **AMA optimization winners JSON**, from `analysis/
|
|
77
|
+
- **AMA optimization winners JSON**, from `analysis/results/` — for `backtest_ama_sweep.ts`, pass via `--results`
|
|
78
78
|
|
|
79
79
|
### Run
|
|
80
80
|
|
|
@@ -99,7 +99,7 @@ node dist/analysis/bot_fitting/backtest_lookback_drawdown.js \
|
|
|
99
99
|
> builds on it and reports the paired per-lookback deltas.
|
|
100
100
|
|
|
101
101
|
> `backtest_bot_fitting.ts` auto-derives `--results` from the `--data` filename
|
|
102
|
-
> (`analysis/
|
|
102
|
+
> (`analysis/results/optimization_results_<base>_w<λ1>_<λ2>_<λ3>_<λ4>.json`,
|
|
103
103
|
> newest `_w*` file matching the base name; falls back to the legacy
|
|
104
104
|
> `optimization_results_<base>.json`) when omitted.
|
|
105
105
|
> `backtest_ama_sweep.ts` requires `--results` explicitly.
|
package/claw/package.json
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
*/
|
|
9
9
|
import type { SourceConfig } from './resolve_source.js';
|
|
10
10
|
/** Fields every analysis CLI config shares. */
|
|
11
|
-
|
|
11
|
+
interface AnalysisBaseConfig {
|
|
12
12
|
source: {
|
|
13
13
|
type: string;
|
|
14
14
|
config: SourceConfig;
|
|
@@ -40,4 +40,5 @@ export declare function printHelpHeader(title: string, usagePath: string): void;
|
|
|
40
40
|
* `width` is per-tool so adopting this helper keeps the original column.
|
|
41
41
|
*/
|
|
42
42
|
export declare function helpRow(flag: string, description: string, width: number): string;
|
|
43
|
+
export {};
|
|
43
44
|
//# sourceMappingURL=analyze_args.d.ts.map
|
|
@@ -17,13 +17,6 @@ interface FillRecord {
|
|
|
17
17
|
}
|
|
18
18
|
declare function assetSymbol(id: string): string;
|
|
19
19
|
declare function assetPrec(id: string): number | undefined;
|
|
20
|
-
declare function toReal(amount: number, assetId: string): number;
|
|
21
|
-
/**
|
|
22
|
-
* A fill needs strictly positive, finite amounts on both legs. A zero base
|
|
23
|
-
* amount would produce an infinite price (quoteAmount / 0) that poisons
|
|
24
|
-
* downstream inventory lots and PnL aggregates.
|
|
25
|
-
*/
|
|
26
|
-
declare function isValidFillAmounts(baseAmount: number, quoteAmount: number): boolean;
|
|
27
20
|
/** Match a user-supplied pair leg against a chain asset id or its symbol. */
|
|
28
21
|
declare function matchesAssetRef(ref: string, assetId: string): boolean;
|
|
29
22
|
interface ClassifiedFill {
|
|
@@ -55,5 +48,5 @@ declare function classifyFill(f: FillRecord): ClassifiedFill | null;
|
|
|
55
48
|
declare function resolveAssetPrecisions(fills: FillRecord[]): Promise<void>;
|
|
56
49
|
/** Fetch every fill_order for an account in [gte, lte], paginated via search_after. */
|
|
57
50
|
declare function fetchAllFills(config: Record<string, unknown>, accountId: string, gte: string, lte: string): Promise<FillRecord[]>;
|
|
58
|
-
export { BTS_ID, assetSymbol, assetPrec,
|
|
51
|
+
export { BTS_ID, assetSymbol, assetPrec, matchesAssetRef, classifyFill, resolveAssetPrecisions, fetchAllFills, FillRecord, };
|
|
59
52
|
//# sourceMappingURL=fills_source.d.ts.map
|
|
@@ -255,5 +255,5 @@ async function fetchAllFills(config, accountId, gte, lte) {
|
|
|
255
255
|
}
|
|
256
256
|
return fills;
|
|
257
257
|
}
|
|
258
|
-
export { BTS_ID, assetSymbol, assetPrec,
|
|
258
|
+
export { BTS_ID, assetSymbol, assetPrec, matchesAssetRef, classifyFill, resolveAssetPrecisions, fetchAllFills, };
|
|
259
259
|
//# sourceMappingURL=fills_source.js.map
|
|
@@ -22,22 +22,25 @@ interface Violation {
|
|
|
22
22
|
priceDelta: number;
|
|
23
23
|
priceDeltaPct: number;
|
|
24
24
|
pivot: number;
|
|
25
|
+
/** Direction-only rule has no band; kept at 0 so the JSON/CSV shape is stable. */
|
|
25
26
|
halfInc: number;
|
|
27
|
+
/** The pivot itself (BUY must be below / SELL above it). */
|
|
26
28
|
threshold: number;
|
|
27
29
|
}
|
|
28
30
|
/**
|
|
29
|
-
* LAST-FILL-GUARD helper —
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
31
|
+
* LAST-FILL-GUARD helper — DIRECTION ONLY relative to the last fill price.
|
|
32
|
+
* BUY blocked if price >= pivot
|
|
33
|
+
* SELL blocked if price <= pivot
|
|
34
|
+
* e.g. pivot 1000 => BUY must be < 1000, SELL must be > 1000
|
|
35
|
+
* Cold (pivot null or lastType null) => disabled. Equal price stays blocked
|
|
36
|
+
* (a re-place at the just-filled level).
|
|
33
37
|
* @param {number} price - Target order price
|
|
34
38
|
* @param {string} type - buy/sell
|
|
35
39
|
* @param {number|null} lastPrice - Most recent fill price
|
|
36
40
|
* @param {string|null} lastType - Most recent fill side (buy/sell)
|
|
37
|
-
* @param {number|any} incrementPercent - Grid increment percent (e.g. 0.5). If not finite/<=0 falls back to DEFAULT_CONFIG.
|
|
38
41
|
* @returns {{blocked: boolean, pivot: number|null, halfInc: number, threshold: number|null}}
|
|
39
42
|
*/
|
|
40
|
-
declare function isLastFillGuardBlocked(price: unknown, type: unknown, lastPrice: unknown, lastType: unknown
|
|
43
|
+
declare function isLastFillGuardBlocked(price: unknown, type: unknown, lastPrice: unknown, lastType: unknown): {
|
|
41
44
|
blocked: boolean;
|
|
42
45
|
pivot: number | null;
|
|
43
46
|
halfInc?: number;
|
|
@@ -3,21 +3,31 @@
|
|
|
3
3
|
/**
|
|
4
4
|
* LAST-FILL-GUARD CHECK
|
|
5
5
|
*
|
|
6
|
-
* Validates LAST-FILL-GUARD discipline
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
6
|
+
* Validates LAST-FILL-GUARD discipline — DIRECTION ONLY, relative to the last
|
|
7
|
+
* fill price (v1.6.16+, retrospective §9.7):
|
|
8
|
+
* BUY blocked if price >= pivot
|
|
9
|
+
* SELL blocked if price <= pivot
|
|
10
|
+
* e.g. pivot 1000 => BUY must be < 1000, SELL must be > 1000.
|
|
10
11
|
* Cold start (no previous fill) is disabled.
|
|
11
|
-
*
|
|
12
|
+
*
|
|
13
|
+
* The older rule judged against `pivot ± increment/2` and ignored the fill
|
|
14
|
+
* side, which blocked a BUY below a SELL fill and a SELL one tick above our
|
|
15
|
+
* cost — i.e. it reported the tightening placements the current engine
|
|
16
|
+
* legitimately makes as violations. Do not reintroduce an increment term here.
|
|
17
|
+
*
|
|
18
|
+
* Intentional offline gaps (documented, acceptable):
|
|
12
19
|
* - Runtime pivots on _lastFilledPrice/_lastFilledType at decision time; tool
|
|
13
20
|
* checks consecutive fill pairs. For batch-placed orders (multiple orders
|
|
14
21
|
* guarded against the same pivot in one COW batch) this diverges — inherent
|
|
15
22
|
* offline approximation.
|
|
16
23
|
* - Spread-correction bypass (cowResult.origin === 'spread-correction') is
|
|
17
24
|
* not simulated — every consecutive pair is checked.
|
|
25
|
+
* - EDGE-pinned insurance fills no longer arm the runtime pivot
|
|
26
|
+
* (recordLastFilledPrices skips them); this reconstruction has no slot
|
|
27
|
+
* identity for a fill, so it cannot classify edge fills and will still
|
|
28
|
+
* judge the pair after one. Expect rare false positives on wick fills.
|
|
18
29
|
*
|
|
19
|
-
* Mirrors modules/
|
|
20
|
-
* modules/constants.ts:DEFAULT_CONFIG.incrementPercent fallback (0.5).
|
|
30
|
+
* Mirrors modules/order/utils/system.ts:isLastFillGuardBlocked 1:1.
|
|
21
31
|
*
|
|
22
32
|
* Fetches fill_order operations from Kibana (same pipeline as
|
|
23
33
|
* trade_profitability.ts) and checks for last-fill guard violations.
|
|
@@ -41,41 +51,32 @@ import { resolveBotAccount } from './account_resolver.js';
|
|
|
41
51
|
import { classifyFill, assetSymbol, fetchAllFills, resolveAssetPrecisions, } from './fills_source.js';
|
|
42
52
|
const { kibanaSearch, DEFAULT_CONFIG: BASE_CONFIG } = KC;
|
|
43
53
|
const OP_LIMIT_ORDER_UPDATE = 77;
|
|
44
|
-
// ─── LAST-FILL-GUARD helper (1:1 with
|
|
54
|
+
// ─── LAST-FILL-GUARD helper (1:1 with modules/order/utils/system.ts) ────────────
|
|
45
55
|
/**
|
|
46
|
-
* LAST-FILL-GUARD helper —
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
*
|
|
56
|
+
* LAST-FILL-GUARD helper — DIRECTION ONLY relative to the last fill price.
|
|
57
|
+
* BUY blocked if price >= pivot
|
|
58
|
+
* SELL blocked if price <= pivot
|
|
59
|
+
* e.g. pivot 1000 => BUY must be < 1000, SELL must be > 1000
|
|
60
|
+
* Cold (pivot null or lastType null) => disabled. Equal price stays blocked
|
|
61
|
+
* (a re-place at the just-filled level).
|
|
50
62
|
* @param {number} price - Target order price
|
|
51
63
|
* @param {string} type - buy/sell
|
|
52
64
|
* @param {number|null} lastPrice - Most recent fill price
|
|
53
65
|
* @param {string|null} lastType - Most recent fill side (buy/sell)
|
|
54
|
-
* @param {number|any} incrementPercent - Grid increment percent (e.g. 0.5). If not finite/<=0 falls back to DEFAULT_CONFIG.
|
|
55
66
|
* @returns {{blocked: boolean, pivot: number|null, halfInc: number, threshold: number|null}}
|
|
56
67
|
*/
|
|
57
|
-
function isLastFillGuardBlocked(price, type, lastPrice, lastType
|
|
68
|
+
function isLastFillGuardBlocked(price, type, lastPrice, lastType) {
|
|
58
69
|
const numPrice = Number(price);
|
|
59
70
|
if (!Number.isFinite(numPrice))
|
|
60
71
|
return { blocked: false, pivot: null };
|
|
61
72
|
if (lastPrice == null || !Number.isFinite(Number(lastPrice)) || lastType == null)
|
|
62
73
|
return { blocked: false, pivot: null };
|
|
63
74
|
const pivot = Number(lastPrice);
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
return { blocked: false, pivot: null };
|
|
70
|
-
const halfInc = inc / 2;
|
|
71
|
-
const halfPct = halfInc / 100;
|
|
72
|
-
const buyThreshold = pivot * (1 - halfPct);
|
|
73
|
-
const sellThreshold = pivot * (1 + halfPct);
|
|
74
|
-
if (type === 'buy' && numPrice > buyThreshold)
|
|
75
|
-
return { blocked: true, pivot, halfInc, threshold: buyThreshold };
|
|
76
|
-
if (type === 'sell' && numPrice < sellThreshold)
|
|
77
|
-
return { blocked: true, pivot, halfInc, threshold: sellThreshold };
|
|
78
|
-
return { blocked: false, pivot: null, halfInc, threshold: null };
|
|
75
|
+
if (type === 'buy' && numPrice >= pivot)
|
|
76
|
+
return { blocked: true, pivot, halfInc: 0, threshold: pivot };
|
|
77
|
+
if (type === 'sell' && numPrice <= pivot)
|
|
78
|
+
return { blocked: true, pivot, halfInc: 0, threshold: pivot };
|
|
79
|
+
return { blocked: false, pivot: null, halfInc: 0, threshold: null };
|
|
79
80
|
}
|
|
80
81
|
function resolveIncrementPercent(botMeta, override) {
|
|
81
82
|
if (override != null && Number.isFinite(override) && override > 0)
|
|
@@ -93,11 +94,11 @@ function printHelp() {
|
|
|
93
94
|
console.log(`\
|
|
94
95
|
Usage: node dist/analysis/grid_correction_check.js --bot-key <key> [options]
|
|
95
96
|
|
|
96
|
-
Validates LAST-FILL-GUARD discipline (
|
|
97
|
-
last fill
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
97
|
+
Validates LAST-FILL-GUARD discipline (DIRECTION ONLY relative to the last fill):
|
|
98
|
+
BUY must be < last fill price, SELL must be > last fill price.
|
|
99
|
+
Equal price counts as blocked (a re-place at the just-filled level).
|
|
100
|
+
Mirrors modules/order/utils/system:isLastFillGuardBlocked 1:1.
|
|
101
|
+
Cold start (no previous fill) is disabled.
|
|
101
102
|
|
|
102
103
|
Required:
|
|
103
104
|
--bot-key <key> Bot key (e.g. my-grid-bot) or bot name (use --list-bots)
|
|
@@ -112,8 +113,9 @@ Options:
|
|
|
112
113
|
--refresh-account Force re-resolution of preferredAccount and update the
|
|
113
114
|
stored accountId when it changed (default: reuse the
|
|
114
115
|
stored accountId with no chain lookup)
|
|
115
|
-
--increment <pct> Grid increment percent
|
|
116
|
-
|
|
116
|
+
--increment <pct> Grid increment percent, informational only — the
|
|
117
|
+
direction-only guard does not use a band
|
|
118
|
+
(default: from bot config or ${Number(C.DEFAULT_CONFIG?.incrementPercent ?? 0.5)})
|
|
117
119
|
--per-fill Check at fill granularity (default: per-order aggregated)
|
|
118
120
|
--include-cross-pair Check consecutive fills across different pairs (default: same pair only)
|
|
119
121
|
--json <file> Export violations as JSON
|
|
@@ -191,15 +193,6 @@ function parseArgs() {
|
|
|
191
193
|
case '--increment':
|
|
192
194
|
opts.incrementPercent = parseFloat(args[++i]);
|
|
193
195
|
break;
|
|
194
|
-
case '--tolerance': {
|
|
195
|
-
const v = parseFloat(args[++i]);
|
|
196
|
-
// Back-compat: old --tolerance was adverse pct before flagging; now map to increment if user still passes it
|
|
197
|
-
// Prefer explicit --increment; don't overwrite if already set
|
|
198
|
-
if (opts.incrementPercent == null)
|
|
199
|
-
opts.incrementPercent = v > 0 ? v * 2 : null; // heuristic: old tolerance ~ halfInc, so inc ~ 2*tolerance
|
|
200
|
-
console.warn(`[warn] --tolerance is deprecated, use --increment <pct> (e.g. --increment ${v > 0 ? (v * 2) : 0.5})`);
|
|
201
|
-
break;
|
|
202
|
-
}
|
|
203
196
|
case '--json':
|
|
204
197
|
opts.json = args[++i];
|
|
205
198
|
break;
|
|
@@ -416,7 +409,7 @@ function aggregateByOrder(trades, updates = []) {
|
|
|
416
409
|
return orders.sort((a, b) => a.sequence - b.sequence);
|
|
417
410
|
}
|
|
418
411
|
// ─── Violation detection (LAST-FILL-GUARD 1:1) ────────────────────────────────
|
|
419
|
-
function detectViolations(items, includeCrossPair
|
|
412
|
+
function detectViolations(items, includeCrossPair) {
|
|
420
413
|
const violations = [];
|
|
421
414
|
let checkedTransitions = 0;
|
|
422
415
|
// Helper for a single chronological sequence (already filtered to one pair or global)
|
|
@@ -428,7 +421,7 @@ function detectViolations(items, includeCrossPair, incrementPercent) {
|
|
|
428
421
|
if (prev.orderId && prev.orderId === curr.orderId)
|
|
429
422
|
continue;
|
|
430
423
|
checkedTransitions++;
|
|
431
|
-
const check = isLastFillGuardBlocked(curr.price, curr.direction, prev.price, prev.direction
|
|
424
|
+
const check = isLastFillGuardBlocked(curr.price, curr.direction, prev.price, prev.direction);
|
|
432
425
|
if (check.blocked) {
|
|
433
426
|
const delta = curr.price - prev.price;
|
|
434
427
|
const deltaPct = prev.price !== 0 ? (delta / prev.price) * 100 : 0;
|
|
@@ -437,13 +430,13 @@ function detectViolations(items, includeCrossPair, incrementPercent) {
|
|
|
437
430
|
index: i,
|
|
438
431
|
pair: `${curr.baseAsset}:${curr.quoteAsset}`,
|
|
439
432
|
direction: curr.direction,
|
|
440
|
-
expected: isSell ? `> ${check.threshold?.toFixed(6)} (
|
|
433
|
+
expected: isSell ? `> ${check.threshold?.toFixed(6)} (last fill ${check.pivot})` : `< ${check.threshold?.toFixed(6)} (last fill ${check.pivot})`,
|
|
441
434
|
prev: prev,
|
|
442
435
|
curr: curr,
|
|
443
436
|
priceDelta: delta,
|
|
444
437
|
priceDeltaPct: deltaPct,
|
|
445
438
|
pivot: check.pivot,
|
|
446
|
-
halfInc:
|
|
439
|
+
halfInc: 0,
|
|
447
440
|
threshold: check.threshold,
|
|
448
441
|
});
|
|
449
442
|
}
|
|
@@ -486,10 +479,11 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
|
|
|
486
479
|
pairGroups.set(k, []);
|
|
487
480
|
pairGroups.get(k).push(t);
|
|
488
481
|
}
|
|
489
|
-
|
|
482
|
+
// Direction-only guard: no band. The Violation row keeps halfInc = 0 so the
|
|
483
|
+
// JSON/CSV shape stays stable for existing consumers.
|
|
490
484
|
console.log('');
|
|
491
485
|
console.log('═══════════════════════════════════════════════════════════════════');
|
|
492
|
-
console.log(' LAST-FILL-GUARD CHECK (
|
|
486
|
+
console.log(' LAST-FILL-GUARD CHECK (direction only)');
|
|
493
487
|
console.log('═══════════════════════════════════════════════════════════════════');
|
|
494
488
|
console.log(` Bot key: ${botKey}${botMeta?.name ? ` (name: ${botMeta.name})` : ''}`);
|
|
495
489
|
if (botMeta)
|
|
@@ -497,8 +491,8 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
|
|
|
497
491
|
console.log(` Account: ${accountId}`);
|
|
498
492
|
console.log(` Range: ${rangeLabel}`);
|
|
499
493
|
console.log(` Mode: ${perFill ? 'per-fill' : 'per-order (aggregated)'}${includeCrossPair ? ', cross-pair enabled' : ', same-pair only'}`);
|
|
500
|
-
console.log(` Increment: ${incrementPercent}% (
|
|
501
|
-
console.log(
|
|
494
|
+
console.log(` Increment: ${incrementPercent}% (informational — the guard is direction-only)`);
|
|
495
|
+
console.log(' Guard: BUY < last fill / SELL > last fill — both sides, global pivot');
|
|
502
496
|
console.log('');
|
|
503
497
|
const buyCount = trades.filter(t => t.direction === 'buy').length;
|
|
504
498
|
const sellCount = trades.filter(t => t.direction === 'sell').length;
|
|
@@ -512,7 +506,7 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
|
|
|
512
506
|
console.log(` Violations: ${violations.length}${checkedTransitions > 0 ? ` (${((violations.length / checkedTransitions) * 100).toFixed(2)}%)` : ''}`);
|
|
513
507
|
console.log('');
|
|
514
508
|
if (violations.length === 0) {
|
|
515
|
-
console.log(' ✅ PASS — no LAST-FILL-GUARD violations detected (all BUY <
|
|
509
|
+
console.log(' ✅ PASS — no LAST-FILL-GUARD violations detected (all BUY < last fill, all SELL > last fill).');
|
|
516
510
|
console.log('');
|
|
517
511
|
if (checkedTransitions === 0) {
|
|
518
512
|
console.log(' Note: no consecutive transitions in range to check.');
|
|
@@ -526,7 +520,7 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
|
|
|
526
520
|
// Per-direction breakdown (blocked side = curr direction)
|
|
527
521
|
const buyV = violations.filter(v => v.direction === 'buy').length;
|
|
528
522
|
const sellV = violations.filter(v => v.direction === 'sell').length;
|
|
529
|
-
console.log(` Breakdown: sell violations: ${sellV} (SELL
|
|
523
|
+
console.log(` Breakdown: sell violations: ${sellV} (SELL <= last fill), buy violations: ${buyV} (BUY >= last fill)`);
|
|
530
524
|
console.log('');
|
|
531
525
|
// Timeline clustering by day
|
|
532
526
|
const dayBuckets = new Map();
|
|
@@ -556,9 +550,9 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
|
|
|
556
550
|
}
|
|
557
551
|
console.log('');
|
|
558
552
|
// Detailed violation table
|
|
559
|
-
console.log(' ── Violations (
|
|
553
|
+
console.log(' ── Violations (direction only) ──');
|
|
560
554
|
console.log('');
|
|
561
|
-
const hdr = ' # Pair Dir Prev Price Curr Price
|
|
555
|
+
const hdr = ' # Pair Dir Prev Price Curr Price Last Fill Δ% Prev Time Curr Time Prev Order Curr Order';
|
|
562
556
|
console.log(hdr);
|
|
563
557
|
console.log(' ' + '─'.repeat(hdr.length - 2));
|
|
564
558
|
for (let i = 0; i < violations.length; i++) {
|
|
@@ -570,24 +564,22 @@ function printReport(trades, orders, violations, checkedTransitions, skipped, ra
|
|
|
570
564
|
const thr = fmt(v.threshold, 6).padStart(12);
|
|
571
565
|
const delta = (v.priceDeltaPct >= 0 ? '+' : '') + v.priceDeltaPct.toFixed(4) + '%';
|
|
572
566
|
const deltaStr = delta.padStart(9);
|
|
573
|
-
const halfStr = (v.halfInc.toFixed(3) + '%').padStart(6);
|
|
574
567
|
const pTime = (v.prev.time || '').slice(0, 19).replace('T', ' ').padEnd(19);
|
|
575
568
|
const cTime = (v.curr.time || '').slice(0, 19).replace('T', ' ').padEnd(19);
|
|
576
569
|
const pOrd = (v.prev.orderId || '-').slice(0, 16).padEnd(16);
|
|
577
570
|
const cOrd = (v.curr.orderId || '-').slice(0, 16).padEnd(16);
|
|
578
571
|
const marker = v.direction === 'sell' ? `SELL < ${fmt(v.threshold, 4)}` : `BUY > ${fmt(v.threshold, 4)}`;
|
|
579
|
-
console.log(` ${(String(i + 1)).padStart(2)} ${pairLabel} ${dir} ${pPrice} ${cPrice} ${thr} ${deltaStr} ${
|
|
572
|
+
console.log(` ${(String(i + 1)).padStart(2)} ${pairLabel} ${dir} ${pPrice} ${cPrice} ${thr} ${deltaStr} ${pTime} ${cTime} ${pOrd} ${cOrd} ${marker}`);
|
|
580
573
|
}
|
|
581
574
|
console.log('');
|
|
582
|
-
console.log(
|
|
583
|
-
console.log(`
|
|
575
|
+
console.log(' Guard: BUY must be < the last fill price, SELL > it (equal price blocked) — mirrors bot.');
|
|
576
|
+
console.log(` No band: the grid increment (${incrementPercent}%) is reported for context only.`);
|
|
584
577
|
console.log('');
|
|
585
578
|
}
|
|
586
579
|
function exportJson(filePath, violations, trades, rangeLabel, botKey, accountId, incrementPercent) {
|
|
587
580
|
const payload = {
|
|
588
581
|
botKey, accountId, range: rangeLabel,
|
|
589
582
|
incrementPercent,
|
|
590
|
-
halfIncrement: incrementPercent / 2,
|
|
591
583
|
totalFills: trades.length,
|
|
592
584
|
violations: violations.map(v => ({
|
|
593
585
|
pair: `${assetSymbol(v.prev.baseAsset)}/${assetSymbol(v.prev.quoteAsset)}`,
|
|
@@ -638,7 +630,7 @@ async function main() {
|
|
|
638
630
|
const botMeta = resolvedAccount.botMeta;
|
|
639
631
|
console.log(`Account: ${accountId}${botMeta ? ` (${botMeta.assetA}/${botMeta.assetB})` : ''}`);
|
|
640
632
|
const incrementPercent = resolveIncrementPercent(botMeta, opts.incrementPercent);
|
|
641
|
-
console.log(`Increment: ${incrementPercent}% (
|
|
633
|
+
console.log(`Increment: ${incrementPercent}% (informational; the guard is direction-only)${opts.incrementPercent == null && botMeta?.incrementPercent != null ? ' — from bot config' : opts.incrementPercent != null ? ' — from --increment' : ' — default'}`);
|
|
642
634
|
console.log(`\nFetching fills and order updates from Kibana...`);
|
|
643
635
|
const [fills, orderUpdates] = await Promise.all([
|
|
644
636
|
fetchAllFills({}, accountId, gte, lte),
|
|
@@ -677,7 +669,7 @@ async function main() {
|
|
|
677
669
|
console.log(` Aggregated into ${orders.length} order epoch(s) (partial fills collapsed; repriced orders kept separate)`);
|
|
678
670
|
items = orders;
|
|
679
671
|
}
|
|
680
|
-
const { violations, checkedTransitions } = detectViolations(items, opts.includeCrossPair
|
|
672
|
+
const { violations, checkedTransitions } = detectViolations(items, opts.includeCrossPair);
|
|
681
673
|
const ordersForReport = opts.perFill ? null : items;
|
|
682
674
|
printReport(trades, ordersForReport, violations, checkedTransitions, skipped, label, String(opts.botKey), accountId, botMeta, opts.perFill, opts.includeCrossPair, incrementPercent, gte, lte);
|
|
683
675
|
if (opts.json)
|
|
@@ -72,7 +72,7 @@ declare function geometricRange(min: number, max: number, count: number, { decim
|
|
|
72
72
|
* Parse a candle JSON file with format detection:
|
|
73
73
|
* flat array → {candles: [...]} → {data: [...]}
|
|
74
74
|
*/
|
|
75
|
-
|
|
75
|
+
interface CandleFile {
|
|
76
76
|
candles: Record<string, unknown>[];
|
|
77
77
|
meta: Record<string, unknown> | null;
|
|
78
78
|
}
|
|
@@ -146,5 +146,5 @@ declare function computeMetrics(pair: PairAnalysis, window?: WindowRange): Tradi
|
|
|
146
146
|
/** Auto-named report file: bot/account + pair filter + requested range. */
|
|
147
147
|
declare function reportFileName(opts: TradeProfitabilityOptions, accountRef: string, botName: string | null): string;
|
|
148
148
|
declare function run(argv?: string[]): Promise<void>;
|
|
149
|
-
export { analyzePair, classifyFills, computeMetrics, parseArgs, run, reportFileName, TradeFill, FillRecord,
|
|
149
|
+
export { analyzePair, classifyFills, computeMetrics, parseArgs, run, reportFileName, TradeFill, FillRecord, PairAnalysis, TradingMetrics };
|
|
150
150
|
//# sourceMappingURL=trade_profitability.d.ts.map
|