diff --git a/.agents/current-state.md b/.agents/current-state.md index a3a99c9..bd9ece9 100644 --- a/.agents/current-state.md +++ b/.agents/current-state.md @@ -3,7 +3,7 @@ ## Active Stage - **Stage**: Stage D.2 — Supervised Broker Submit Safety - **Last Updated**: 2026-03-27 -- **Focus**: Stage D.2 is centered on closing ambiguity around supervised Kraken submit, especially idempotency, reconciliation, and post-submit operator safety. +- **Focus**: Stage D.2 is centered on closing ambiguity around supervised Hyperliquid submit, especially idempotency, reconciliation, and post-submit operator safety. - **Authority Note**: Stepbit-facing integration remains a secondary boundary track. QuantLab stays autonomous and external consumer needs do not override QuantLab-owned priorities. - **Product Identity Note**: Publicly, QuantLab should now be described as a `web3 app` in direction, but still as a supervised and safety-first execution system in current maturity. - **Performance Note**: QuantLab remains Python-first. Native acceleration is now treated as a measured hotspot tactic, with the backtest engine as the first realistic candidate if profiling justifies escalation. @@ -31,14 +31,14 @@ ## Active Work - **Stage Open**: Stage D.2 is now the primary execution-safety focus. -- **Current Priority**: Close ambiguous-submit risk before widening broker execution beyond the first supervised Kraken submit path. +- **Current Priority**: Close ambiguous-submit risk before widening broker execution beyond the first supervised Hyperliquid submit path. - **Active Focus Areas**: - make the first supervised broker submit path idempotency-safer - - reconcile ambiguous submit states against real Kraken order state + - reconcile ambiguous submit states against real Hyperliquid order state - add aggregate health and alert visibility over canonical broker submission sessions - keep broker execution auditable before any broader live routing or retry logic - preserve paper-session discipline as a prerequisite, not the current bottleneck - - keep Kraken as the first implemented execution boundary while positioning Hyperliquid as the first next venue intended for personal connection + - keep Hyperliquid as the active execution boundary while positioning Kraken as legacy compatibility and Hyperliquid as the first next venue intended for personal connection - treat Bitget as a later optional comparison venue after Hyperliquid, not a current priority - review whether the current boundary can express Hyperliquid signer, wallet, routing, and websocket semantics without ad hoc adapter leaks - keep the first Hyperliquid supervised submit path intentionally narrow and auditable before adding richer session, status, or websocket execution work diff --git a/README.md b/README.md index 3cb665b..691d53d 100644 --- a/README.md +++ b/README.md @@ -25,14 +25,14 @@ QuantLab is currently transitioning from a strong paper-operations base into **S The paper layer is now materially operational, and the current broker-facing focus is: -- reconcile the first supervised Kraken submit path before widening live execution +- reconcile the first supervised Hyperliquid submit path before widening live execution - close idempotency and ambiguous-submit gaps before adding more broker power - keep paper-session discipline as a prerequisite, not as the current bottleneck Execution venue strategy note: -- `Kraken` remains the first implemented real-execution backend -- `Hyperliquid` is the first next venue intended for personal connection and supervised practical use +- `Hyperliquid` is the active execution venue direction +- `Kraken` remains implemented compatibility / history, not the active next target - `Bitget` is a later optional comparison venue, after Hyperliquid, not the next default target - this is why `QuantLab web3 app` is now the right public direction, even though the product is still earlier in runtime maturity than that label's end-state implies - `BrokerAdapter` remains the current code name, but the architecture should now be read as an execution-venue boundary, not only a CEX-style broker boundary diff --git a/docs/execution-venue-strategy.md b/docs/execution-venue-strategy.md index db35fbc..8f34a86 100644 --- a/docs/execution-venue-strategy.md +++ b/docs/execution-venue-strategy.md @@ -5,14 +5,14 @@ Date: 2026-03-26 ## Decision -QuantLab keeps `Kraken` as the first implemented real-execution backend. +QuantLab keeps `Hyperliquid` as the active execution venue direction. -At the same time, `Hyperliquid` becomes the first venue intended for personal connection and supervised practical use once the execution boundary is ready for that step. +`Kraken` remains implemented compatibility/history and can still serve as a reference backend, but it is no longer the active next target. This means: -- `Kraken` remains the first backend used to prove the safety boundary, validation flow, submit discipline, and reconciliation model -- `Hyperliquid` becomes the first next venue to target for real personal use +- `Hyperliquid` is the venue used to prove the active safety boundary, validation flow, submit discipline, and reconciliation model +- `Kraken` remains a reference implementation and compatibility boundary - `Binance` is no longer the default next comparison venue ahead of `Hyperliquid` - the current code name `BrokerAdapter` stays in place for continuity, but the architecture should be read as an `execution venue` boundary, not only a centralized-exchange broker boundary @@ -20,7 +20,7 @@ This means: The first implemented backend and the first venue worth using personally do not need to be the same thing. -`Kraken` is still a strong first implementation target because it is a disciplined and familiar boundary for: +`Hyperliquid` is the active implementation target because it is the boundary the project is currently using to prove: - local execution policy - authenticated preflight @@ -28,7 +28,7 @@ The first implemented backend and the first venue worth using personally do not - supervised submit safety - reconciliation and post-submit state tracking -But for actual personal connection and future execution design, `Hyperliquid` is strategically more interesting. +`Kraken` remains a useful reference boundary, but it is not the active next target. According to the official documentation, Hyperliquid is a performant L1 built around a fully onchain financial system, with HyperCore and HyperEVM secured by HyperBFT. HyperCore includes fully onchain spot and perpetual order books where orders, cancels, trades, and liquidations happen with one-block finality, and the docs state current support for up to 200k orders per second. Source: [About Hyperliquid](https://hyperliquid.gitbook.io/hyperliquid-docs). @@ -44,12 +44,12 @@ That combination makes Hyperliquid materially different from a standard CEX adap ## Architectural Interpretation -The architectural lesson is not "replace Kraken." +The architectural lesson is not "delete all historical Kraken work." The lesson is: -- `Kraken` is the first safety proving ground -- `Hyperliquid` is the first next venue that tests whether the QuantLab boundary is genuinely venue-agnostic +- `Hyperliquid` is the active safety proving ground +- `Kraken` remains a compatibility/reference boundary If the current `BrokerAdapter` only feels natural for CEX-style REST brokers, then the abstraction is still too narrow. If it can also support: @@ -66,10 +66,10 @@ then the abstraction is becoming strong enough for the direction QuantLab actual For roadmap and implementation sequencing: -1. keep Kraken as the first implemented backend and finish its submit-safety boundary cleanly +1. keep Hyperliquid as the active backend focus and finish its submit-safety boundary cleanly 2. do not rename `BrokerAdapter` in code yet just for terminology 3. update architecture and roadmap language so it is clear that this boundary is really an execution-venue boundary -4. move `Hyperliquid` ahead of `Binance` as the next venue target for real personal connection and future comparison work +4. keep `Kraken` as compatibility/reference and move `Hyperliquid` ahead of `Binance` as the next venue target for real personal connection and future comparison work 5. treat `Binance` as optional later comparison work, not the default second venue ## What This Does Not Mean diff --git a/docs/roadmap.md b/docs/roadmap.md index bbda40b..2efa865 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -249,18 +249,17 @@ Exit condition: The first real execution-venue integration should follow this decision framework: -- start with Kraken as the first real broker target - define and stabilize `BrokerAdapter` before integrating any exchange-specific backend -- keep `Kraken` as the first implemented backend and safety proving ground -- move `Hyperliquid` ahead of `Binance` as the first next venue intended for personal connection and supervised practical use +- keep `Hyperliquid` as the active execution-venue target for personal connection and supervised practical use +- keep `Kraken` as implemented compatibility/history rather than the active next target - consider `Bitget` as optional later comparison work after `Hyperliquid`, not the default next venue - treat `Binance` as optional later comparison work, not the default next venue - treat CCXT as optional acceleration for prototypes, smoke tests, or broad exchange experimentation, not as the authority of the execution design Rationale: -- Kraken is the preferred first integration because it is a credible first real boundary for disciplined execution work -- Hyperliquid is the preferred next venue because it tests whether the current abstraction can handle a high-performance onchain order-book venue, not only a conventional CEX-style broker +- Hyperliquid is the preferred active venue because it tests whether the current abstraction can handle a high-performance onchain order-book venue, not only a conventional CEX-style broker +- Kraken remains useful as compatibility history and a reference implementation, but it is no longer the active next strategic target - Binance remains useful later as an additional comparison backend, but it is no longer the default next strategic target - CCXT is useful when speed matters, but native integrations remain preferable when QuantLab needs tighter control over errors, rate limits, retries, and private execution flows diff --git a/docs/supervised-broker-runbook.md b/docs/supervised-broker-runbook.md index 9dacd1a..f8d6d14 100644 --- a/docs/supervised-broker-runbook.md +++ b/docs/supervised-broker-runbook.md @@ -53,11 +53,13 @@ Before attempting the first supervised broker evidence run, generate a readiness python main.py --broker-evidence-readiness-outdir outputs/broker_evidence ``` +Hyperliquid is the preferred first corridor for the current execution direction. + If you already know which corridor you want to exercise first, make it explicit: ```bash -python main.py --broker-evidence-readiness-outdir outputs/broker_evidence --broker-evidence-corridor kraken python main.py --broker-evidence-readiness-outdir outputs/broker_evidence --broker-evidence-corridor hyperliquid +python main.py --broker-evidence-readiness-outdir outputs/broker_evidence --broker-evidence-corridor kraken ``` Use this check to fail early on: diff --git a/landing/index.html b/landing/index.html index de201c2..d2863f4 100644 --- a/landing/index.html +++ b/landing/index.html @@ -3,11 +3,12 @@ - QuantLab | Shell de trabajo cuantitativo + QuantLab | Hyperliquid-first quantitative shell + @@ -35,11 +36,11 @@
-
Research, paper discipline y execution safety
+
Hyperliquid-first, paper discipline y execution safety

QuantLab es tu shell de trabajo para investigacion cuantitativa y ejecucion supervisada.

Una superficie unificada para lanzar experimentos, revisar runs, comparar resultados, - inspeccionar artifacts y avanzar solo cuando el sistema esta listo. + inspeccionar artifacts y avanzar solo cuando el sistema y la venue activa estan listos.

Ver la shell @@ -51,7 +52,7 @@

QuantLab es tu shell de trabajo para investigacion cuantitativa y ejecucion Compare Artifacts Paper Ops - Execution Boundaries + Hyperliquid

@@ -74,7 +75,7 @@

QuantLab es tu shell de trabajo para investigacion cuantitativa y ejecucion
research_ui up
-
stepbit optional
+
hyperliquid active
paper health ok
@@ -450,7 +451,7 @@

Paper Ops mas fuertes

04

Execution safety

-

Preflight, submit supervision y boundaries de broker mas serios.

+

Preflight, submit supervision y boundaries de broker mas serios sobre la venue activa.

05 diff --git a/src/quantlab/cli/broker_evidence_readiness.py b/src/quantlab/cli/broker_evidence_readiness.py index b7e26e9..9ac087b 100644 --- a/src/quantlab/cli/broker_evidence_readiness.py +++ b/src/quantlab/cli/broker_evidence_readiness.py @@ -114,10 +114,10 @@ def build_broker_evidence_readiness_report(args, *, project_root: Path) -> dict[ resolved_corridor = "kraken" elif requested_corridor == "hyperliquid": resolved_corridor = "hyperliquid" - elif kraken_ready: - resolved_corridor = "kraken" elif hyperliquid_ready: resolved_corridor = "hyperliquid" + elif kraken_ready: + resolved_corridor = "kraken" selected_ready = { "kraken": kraken_ready, @@ -136,7 +136,7 @@ def build_broker_evidence_readiness_report(args, *, project_root: Path) -> dict[ "project_root": str(project_root), "requested_corridor": requested_corridor, "resolved_corridor": resolved_corridor, - "recommended_first_corridor": "kraken", + "recommended_first_corridor": "hyperliquid", "runbook": { "path": str(runbook_path), "exists": runbook_path.exists(), diff --git a/test/test_broker_evidence_readiness.py b/test/test_broker_evidence_readiness.py index 04a8a90..fbee0fd 100644 --- a/test/test_broker_evidence_readiness.py +++ b/test/test_broker_evidence_readiness.py @@ -88,3 +88,20 @@ def test_handle_broker_evidence_readiness_accepts_ready_kraken_path(monkeypatch, assert result["resolved_corridor"] == "kraken" payload = json.loads((outdir / ARTIFACT_FILENAME).read_text(encoding="utf-8")) assert payload["ready_for_evidence_pass"] is True + + +def test_build_broker_evidence_readiness_report_prefers_hyperliquid_when_both_are_ready(monkeypatch, tmp_path: Path): + args = _build_args() + + monkeypatch.setenv("KRAKEN_API_KEY", "demo-key") + monkeypatch.setenv("KRAKEN_API_SECRET", "demo-secret") + monkeypatch.setenv("HYPERLIQUID_PRIVATE_KEY", "demo-private-key") + monkeypatch.setenv("HYPERLIQUID_ACCOUNT", "0x5C3CE658Ab5a953F3870678e99e3bE8eD0eA8e80") + monkeypatch.setenv("HYPERLIQUID_SIGNER_ID", "0x5e1079D0b32dDe739340C13C869a97d9b6552eF2") + monkeypatch.setenv("HYPERLIQUID_SIGNER_TYPE", "agent_wallet") + + report = build_broker_evidence_readiness_report(args, project_root=tmp_path) + + assert report["recommended_first_corridor"] == "hyperliquid" + assert report["resolved_corridor"] == "hyperliquid" + assert report["ready_for_evidence_pass"] is False