Spec: BTC residual-momentum cross-sectional market-neutral strategy

[Vzstar]

Problem Statement

QuantDinger can run single-strategy signals and backtests, but it does not currently provide a reproducible, point-in-time research and signal path for a crypto Cross-Sectional Market-Neutral Strategy. The existing Strategy API V2 OHLCV path is best-effort, stores only a narrow rounded OHLCV snapshot, has no historical perpetual-universe or funding semantics, and emits independent order-shaped signals rather than an atomic Target Portfolio.

A researcher therefore cannot determine whether BTC Residual Momentum produces robust net returns after realistic funding and trading costs without look-ahead bias. Even if the research passes, a Signal Deployment cannot durably emit one complete, idempotent Rebalance Group without accidentally implying positions, fills, cash, PnL, or live-order authority.

Solution

Add a research-first Cross-Sectional Market-Neutral Strategy for Binance USDT Linear Perpetuals.

Phase 1 builds an immutable, content-identified Research Dataset and performs a preregistered three-year hourly Walk-Forward Evaluation of BTC Residual Momentum. It constructs portfolios subject to hard Dollar Neutrality, BTC Beta Neutrality, concentration, liquidity, participation, holding, and cost-coverage constraints. A Research Run can promote only when every statistical, economic, ablation, data-integrity, and accounting gate passes.

Phase 2 is permitted only after promotion. It integrates the Registered Strategy Version with the existing Strategy API V2 signal execution mode and emits complete Target Portfolio snapshots as atomic Rebalance Groups. It remains credential-free and signal-only, has no Shadow subsystem, never submits exchange orders, never simulates fills or PnL, and is rejected by live deployment.

User Stories

1. As a quantitative researcher, I want the initial strategy hypothesis preregistered, so that failed research cannot be silently rescued through untracked parameter changes.
2. As a quantitative researcher, I want every formal parameter change to create a new Registered Strategy Version and Research Run, so that results remain attributable.
3. As a quantitative researcher, I want three years of hourly Binance perpetual history, so that the strategy is evaluated across multiple market regimes.
4. As a data steward, I want historical point-in-time contract membership, so that delisted or newly listed instruments are not evaluated with current-universe hindsight.
5. As a data steward, I want historical contract specifications and validity intervals, so that research does not apply current exchange metadata to the past.
6. As a data steward, I want full-precision Canonical Market Bars, so that upstream display rounding cannot alter ranks, returns, or PnL.
7. As a data steward, I want quote volume, trade count, taker flow, and funding data preserved, so that liquidity, capacity, and funding attribution are evidence-based.
8. As a data steward, I want every Research Dataset content-identified and immutable, so that a Research Run can be reproduced from exact inputs.
9. As a data steward, I want per-partition hashes and a canonical manifest, so that missing, changed, or corrupted data fails loudly.
10. As a data steward, I want dataset publication to be atomic, so that a partial download cannot masquerade as a complete Research Dataset.
11. As a risk reviewer, I want unknown instrument classifications excluded, so that ambiguous products do not silently enter the Eligible Universe.
12. As a risk reviewer, I want stablecoins, wrapped assets, staking receipts, leveraged tokens, baskets, synthetics, and fiat or commodity mappings excluded, so that the cross-section represents comparable crypto risk.
13. As a researcher, I want the BTC Benchmark excluded from alpha ranking, so that it remains a market explanatory variable rather than a portfolio candidate.
14. As a researcher, I want instruments to have at least 180 days of continuous trading history, so that immature listings do not dominate the factor.
15. As a researcher, I want at least 30 eligible candidates, so that long and short selections remain meaningfully cross-sectional.
16. As a researcher, I want explicit hourly coverage and maximum-gap gates, so that sparse histories cannot create artificial momentum.
17. As a researcher, I want incomplete BTC or funding history to invalidate the Decision Time, so that global inputs are never silently approximated.
18. As a researcher, I want hourly logarithmic Research Returns, so that regression and aggregation use one declared return convention.
19. As a researcher, I want a trailing 60-day OLS Residual Model with an intercept, so that each instrument's BTC exposure is estimated consistently.
20. As a researcher, I want regression inputs clipped only within their estimation window, so that outliers do not dominate beta while realized PnL remains unaltered.
21. As a researcher, I want the fitted Residual Model held fixed when accumulating the trailing 20-day Residual Momentum, so that the signal has one unambiguous definition.
22. As a researcher, I want cross-sectional clipping and z-scoring applied consistently, so that Alpha Scores are comparable at each Decision Time.
23. As a researcher, I want a trailing Expected Return Map built only from matured non-overlapping 72-hour cohorts, so that no future label leaks into a decision.
24. As a risk reviewer, I want Alpha declared valid only with sufficient positive cohort evidence, so that weak or unstable estimates produce a Flat Target.
25. As a portfolio researcher, I want inverse Residual Volatility scaling, so that volatile instruments do not dominate initial portfolio risk.
26. As a portfolio researcher, I want long and short Gross Exposure fixed at 50 percent per side, so that the strategy has a declared one-times gross profile.
27. As a risk reviewer, I want Dollar Neutrality enforced within 0.1 percent of NAV, so that signed quote exposure remains bounded.
28. As a risk reviewer, I want absolute portfolio BTC beta bounded at 0.02, so that dollar neutrality is not mistaken for market neutrality.
29. As a risk reviewer, I want every instrument weight capped at 10 percent of NAV, so that the strategy cannot concentrate in a small number of names.
30. As a risk reviewer, I want the optimizer to fail closed and be independently validated, so that solver success never silently relaxes constraints.
31. As a portfolio researcher, I want each side selected from 20 percent cross-sectional tails with explicit breadth limits, so that portfolio breadth is stable.
32. As a portfolio researcher, I want a Rank Buffer, so that small rank changes do not force excessive turnover.
33. As a portfolio researcher, I want a 24-hour Minimum Holding Period for ordinary alpha replacements, so that the hourly Decision Cycle does not imply hourly churn.
34. As a risk reviewer, I want risk exits exempt from the Minimum Holding Period, so that stale data or neutrality breaches can remove exposure immediately.
35. As a portfolio researcher, I want a Material Target Change threshold, so that immaterial weight noise does not emit a new target.
36. As a portfolio researcher, I want expected 72-hour improvement to cover at least twice incremental cost, so that rebalancing is economically justified.
37. As a capacity reviewer, I want a 100,000 USDT Capacity Reference, so that participation and cost assumptions have a declared scale.
38. As a capacity reviewer, I want each proposed trade capped at 0.5 percent of trailing median hourly quote volume, so that research does not assume implausible capacity.
39. As a performance reviewer, I want separate Base and Stress cost scenarios, so that results are not dependent on one optimistic estimate.
40. As a performance reviewer, I want all base research trades treated as taker executions, so that maker fills are only a sensitivity.
41. As a performance reviewer, I want funding booked at actual timestamps from pre-settlement positions and point-in-time rates, so that perpetual carry is correct.
42. As a performance reviewer, I want every PnL component reported separately, so that strategy economics are explainable.
43. As a validation reviewer, I want the first 12 months used only for initialization and the following 24 months evaluated walk-forward, so that performance is out of sample.
44. As a validation reviewer, I want cash, ordinary momentum, residual-momentum-only, dual-neutral, and randomized-ranking ablations, so that complexity must add value.
45. As a validation reviewer, I want block-bootstrap and randomized-null evidence, so that promotion does not rely on a point Sharpe estimate.
46. As a validation reviewer, I want Base and Stress performance gates, so that the strategy remains economically viable under adverse costs.
47. As a validation reviewer, I want zero silent skips, invalid-input targets, constraint violations, participation violations, and unexplained accounting differences, so that integrity failures cannot be averaged away.
48. As a validation reviewer, I want at least 90 percent valid Decision Times, so that strong metrics cannot hide unusable data coverage.
49. As a strategy operator, I want failed promotion to stop at Research, so that rejected evidence cannot auto-tune or emit signals.
50. As a strategy operator, I want a promoted strategy to run only as a Signal Deployment, so that research approval does not grant trading authority.
51. As a strategy operator, I want nonzero credential identifiers and live mode rejected, so that signal-only operation cannot accidentally bind an account or place orders.
52. As a signal consumer, I want one complete Target Portfolio per Decision Time, so that independent legs cannot be mistaken for independent trades.
53. As a signal consumer, I want removed instruments represented by explicit zero weights, so that exits are unambiguous.
54. As a signal consumer, I want the Rebalance Group committed atomically, so that a partial portfolio is never authoritative.
55. As a signal consumer, I want deterministic group and leg identities with complete-target hash checks, so that retries cannot create duplicates or conflicts.
56. As a strategy operator, I want Signal Continuity only across unchanged strategy versions, so that holding history survives restarts without crossing version boundaries.
57. As a strategy operator, I want invalid global input to record a failure without emitting a group, so that stale data is never reused.
58. As a strategy operator, I want a Neutrality Breach to emit a Flat Target, so that current hard-constraint violations remove risk.
59. As a strategy operator, I want runtime state to be cache-only, so that process restarts cannot change target authority.
60. As a strategy operator, I want notification attempted only after commit and unable to roll back the target, so that messaging availability cannot change authority.
61. As an auditor, I want Signal Deployments to report no virtual positions, fills, cash, or PnL, so that signals are not misrepresented as execution.
62. As a maintainer, I want research workflows isolated in a focused feature service, so that Strategy API V2 remains a runtime framework.
63. As a maintainer, I want the Binance research adapter separated from strategy decisions, so that venue data and portfolio logic have distinct ownership.
64. As a maintainer, I want canonical and incremental migrations, so that fresh installs and existing deployments receive the same schema.
65. As a maintainer, I want deterministic replay assertions and explicit tolerances, so that reproducibility is measurable rather than subjective.

Implementation Decisions

• Delivery has a mandatory Research phase and a gated Signal phase. Signal work begins only after the Research Promotion Gate passes.
• The initial Research Venue is Binance USDT Linear Perpetuals. The BTC Benchmark is the Binance BTC/USDT USDT Linear Perpetual and is benchmark-only.
• The Research Dataset uses version-locked PyArrow and partitioned Parquet beneath a configurable root. A canonical JSON manifest records schema/version metadata, partition hashes, source provenance, coverage, classifications, and Contract Specification History. Dataset identity is derived from canonical manifest content and publication is atomic.
• A dedicated full-precision Binance research adapter collects point-in-time membership, contract specifications, Funding Rate Panel data, and complete hourly market fields. The existing Strategy API V2 OHLCV snapshot is not research authority.
• Instrument classification is controlled by a versioned, human-approved Classification Registry. Unknown Classification fails closed.
• Eligibility requires the declared product type, 180 days of continuous tradability, successful classification, data-quality gates, and liquidity/participation eligibility.
• A Complete Decision Input requires complete BTC and funding inputs. Each candidate's 60-day window requires at least 99.5 percent coverage and no gap longer than two hours.
• Portfolio Breadth requires at least 30 candidates. Each side selects 20 percent, with a minimum of six and maximum of ten instruments.
• Research Return is hourly log return. Each instrument is regressed on the BTC Benchmark over 60 completed days using OLS with an intercept.
• Instrument and BTC regression inputs are clipped to trailing 0.5 and 99.5 percentiles for fitting and residual application only. Realized PnL remains unclipped.
• The fitted coefficients accumulate residuals over 20 days. Residual Momentum is clipped cross-sectionally at 1 and 99 percent and standardized with population standard deviation.
• The Forecast Horizon is 72 hours. The Expected Return Map uses the median cross-sectional slope from 180 days of fully matured, non-overlapping 72-hour cohorts. Valid Alpha requires at least 40 cohorts, a positive median, and at least 55 percent positive slopes.
• Raw weights use inverse 20-day Residual Volatility. A version-locked SciPy bounded optimizer enforces one-times gross exposure, 50 percent per side, 10 percent maximum instrument weight, Dollar Neutrality within 0.1 percent of NAV, and absolute BTC Beta within 0.02.
• Solver output is independently validated. Constraints are never relaxed. An Infeasible Target does not replace the authoritative target; a current Neutrality Breach produces a Flat Target.
• Entry uses top and bottom 20 percent tails. The Rank Buffer retains longs until they leave the top 30 percent and shorts until they leave the bottom 30 percent.
• Ordinary replacement is blocked for 24 hours. Risk exits, Invalid Decisions, Neutrality Breaches, and Flat Targets bypass this restriction.
• A new target requires absolute weight changes totaling at least five percent of NAV and expected improvement of at least twice incremental estimated cost.
• Liquidity is trailing 30-day median daily USDT quote volume. Each trade is capped at 0.5 percent of trailing median hourly quote volume.
• The Capacity Reference is 100,000 USDT. Base costs are 5 bps commission, 2 bps spread/slippage, and 50 bps times square root of participation. Stress costs are 10 bps commission, 10 bps spread/slippage, and 150 bps times square root of participation.
• Funding Cash Flow is discrete at the actual funding timestamp using the pre-settlement position, contemporaneous reference notional, and point-in-time rate.
• Performance Attribution separately reports price alpha, funding, commission, spread/slippage, impact, and net PnL.
• Walk-Forward Evaluation uses 12 months for initialization/calibration and 24 months for hourly out-of-sample decisions.
• The Ablation Set includes cash, ordinary-momentum Dollar Neutrality, Residual Momentum Dollar Neutrality, the complete dual-neutral strategy, and 1,000 randomized-ranking null portfolios.
• Promotion requires Base net Sharpe at least 1.0, Stress net Sharpe at least 0.75, positive Stress cumulative return, Stress maximum drawdown at most 10 percent, a positive 168-hour block-bootstrap mean lower bound, and performance above the 95th percentile of randomized nulls.
• Promotion also requires zero silent skips, invalid-input targets, neutrality/participation violations, and unexplained ledger differences, plus valid results for at least 90 percent of Decision Times.
• The complete strategy must beat the better simple ablation's Stress Sharpe or have comparable Sharpe while improving both absolute BTC beta and maximum drawdown by at least 30 percent.
• Research failure is a Research Rejection, stops before Signal integration, and does not trigger automatic tuning.
• Research and portfolio workflows live in a focused Cross-Sectional Neutral service; venue reads are behind a Binance research adapter; Strategy API V2 contains only a thin Signal bridge.
• Signal integration introduces a durable target-group header. Target legs use the existing portfolio, rebalance-group, and target-weight intent fields.
• The header is authoritative for strategy/version, Decision Time, canonical target hash, constraint evidence, and commit status. Header and legs are written in one transaction.
• Target legs are terminal Portfolio Target Signals and never eligible for order execution. Removed instruments have explicit zero weights.
• Group identity is deterministic from strategy, run/version context, and Decision Time. Leg identity adds instrument and side. Repeated identity must match the complete target hash.
• Signal Continuity loads the latest Emitted Target Portfolio across runs only when strategy identity and Registered Strategy Version are unchanged. Runtime state is cache-only.
• Invalid global input records failure and emits no group. Database commit establishes authority; one idempotent Signal Notification is attempted afterward.
• Signal requests with nonzero credential IDs are rejected. The manifest declares signal-only authority and deployment rejects live mode.
• Canonical schema is updated in idempotent bootstrap SQL and a dated incremental migration. The unused portfolio execution-plan schema remains unchanged.
• Signal Deployment never calculates virtual PnL or claims positions, fills, cash, or execution.
• Deterministic replay requires identical membership, outcomes, and target direction; weights are canonicalized to 12 decimal places for hashing, while aggregate metrics use declared tolerances.

Testing Decisions

• Tests assert external behavior: target membership/direction, weights within tolerance, manifest/hash behavior, transaction visibility, failure type, side effects, and absence of execution effects. They do not couple to helper or solver internals.
• The highest research seam is a complete Research Run over a fixed miniature point-in-time dataset. It verifies the manifest, decisions, target hashes, attribution, promotion/rejection, and Invalid Decision evidence.
• The highest persistence seam is the target-group repository against real PostgreSQL. It verifies atomic commit, rollback, idempotent replay, hash conflicts, zero targets, same-version continuity, and cross-version isolation.
• The highest runtime seam is Strategy API V2 signal dispatch. It verifies one complete target group, credential/live rejection, invalid inputs, commit-before-notification, and no pending order, exchange request, position, fill, cash, or virtual PnL.
• Dataset tests cover canonical manifests, partition hashes, atomic publication, deterministic identity, provenance, missing/corrupt partitions, duplicate timestamps, and nonfinite values.
• Adapter tests cover precision, timestamps, quote-volume units, funding availability, contract validity intervals, pagination, rate-limit accounting, and fail-loud partial collection.
• Factor tests use hand-calculated panels for log returns, clipping, OLS, fixed-coefficient residuals, z-scores, and cohort maturity without look-ahead.
• Portfolio property tests cover feasible and infeasible cross-sections, all hard constraints, participation, determinism, and independent post-solve validation.
• Rebalance tests cover Rank Buffer, holding exemptions, Material Target Change, Cost Coverage Gate, invalid-alpha Flat Targets, and Neutrality Breaches.
• Accounting tests cover funding timestamps, pre-settlement positions, cost signs and formulas, attribution reconciliation, and zero unexplained difference.
• Statistical tests cover walk-forward boundaries, matured cohorts, bootstrap blocks, randomized nulls, ablations, and threshold boundaries.
• Migration tests verify fresh bootstrap and incremental upgrade converge and remain idempotent.
• Dependency checks verify SciPy and PyArrow are declared and locked.
• Prior art includes existing content-addressed snapshot hash tests, database bootstrap/migration tests, Strategy API V2 runtime tests, and release-gate tests.
• Red-green work is bounded to three repair attempts per failure category and 30 minutes per attempt. Exhaustion produces an explicit incomplete-result report rather than weakened assertions.

Out of Scope

• Live orders, live credentials, routing, pending orders, fills, reconciliation, and production trading authority.
• A Shadow subsystem, paper broker, virtual positions, virtual cash, or Signal PnL.
• Testnet, production deployment, canary release, or operational authorization.
• Automatic parameter tuning after Research Rejection.
• Maker execution as the primary model; it is sensitivity analysis only.
• Multi-exchange, spot, inverse, options, dated futures, or non-USDT instruments.
• Alternative primary alpha factors, machine-learning models, discretionary overrides, or AI-driven thresholds.
• Web UI, dashboards, manual target editing, or a target-execution consumer.
• Calibrating cost assumptions from live fills.
• Treating successful tests or promotion as authorization to trade real funds.

Further Notes

• Agreed domain vocabulary is maintained in the Cross-Sectional Market-Neutral Strategy glossary.
• The immutable Research Dataset and signal-only target-group choices are recorded as architectural decisions.
• Implementation must complete and evaluate Research before modifying the Signal path.
• The existing portfolio execution-plan tables are intentionally not reused because their live, quantity, fill, and execution semantics conflict with a signal-only Target Portfolio.
• The existing content-addressed gzip-JSON snapshot is prior art for canonicalization and tamper detection but is not sufficient as the Research Dataset.
• A clean dependency environment currently lacks SciPy and a Parquet engine; both must be explicitly declared and locked.