# Hyperliquid Copy-Research-System – Umsetzungs-Roadmap

**Datum:** 2026-06-14
**Arbeitsname:** `ctb_copy`
**Entscheidung:** Bauen, aber strikt als read-only Research-/Shadow-System. Keine Live-Copy-Orders, keine Vault-Deposits, keine gemeinsame API-Wallet mit dem bestehenden Tiny-Live-Bot.

## Leitplanken

- Copytrading wird als **Leader-Due-Diligence + Shadow-Copy-Forschung** behandelt, nicht als „Gewinner kopieren“.
- Der bestehende Live-Bot bleibt getrennt. `ctb_copy` bekommt keinen Import auf Live-Executor-Module und keine Order-Side-Effects.
- Alle Bewertungen gelten erst **ab Discovery-Zeitpunkt**, um Survivorship Bias zu reduzieren.
- Kostenmodell ist konservativ: Fees, Spread, Slippage, Funding und Delay-Penalty werden immer abgezogen.
- Wallets mit möglichem Hidden-Hedge bleiben Research-only, solange On-Exchange-Verhalten nicht konsistent replizierbar ist.

## Zielarchitektur

```text
src/ctb_copy/
  collectors/
    hyperliquid_vault_collector.py
    hyperliquid_wallet_collector.py
    market_context_collector.py
  scoring/
    leader_scorecard.py
    vault_due_diligence.py
    regime_attribution.py
    replication_quality.py
  shadow/
    position_shadow_engine.py
    follower_fill_model.py
    portfolio_allocator.py
  risk/
    copy_pretrade_gate.py
    exposure_aggregator.py
    leader_kill_rules.py
  reports/
    daily_copy_report.py
    weekly_leader_review.py
```

## Phase 0 – Sicherheitsfundament und Contracts

**Ziel:** Ein testbares, side-effect-freies Modulgerüst.

Akzeptanzkriterien:

- `ctb_copy` ist separater Package-Namespace.
- Kein Import von `src.execution.hyperliquid_live_executor` oder Exchange-SDK-Orderpfaden.
- Runtime-Daten gehen unter `runtime/copy_research/` oder `~/.local/state/...`, nicht in Git.
- Basistests für Kostenmodell, Scorecard-Gates, Pretrade-Gate und Read-only Collector laufen grün.

## Phase 1 – Read-only Collector

**Ziel:** Discovery-Snapshots statt rückblickender Gewinnerselektion.

Bausteine:

- Vault-Snapshot-Collector: Vault-ID, Leader, TVL, PnL, Drawdown, offene Positionen soweit verfügbar.
- Wallet-Collector: `clearinghouseState`, `userFillsByTime`, `openOrders`, `portfolio`.
- Market-Context-Collector: Funding, OI, Volatilität, Regime-Tags.
- Snapshot-Journal JSONL ab Discovery-Zeitpunkt.

Akzeptanzkriterien:

- Collector kann mit Fake-Transport getestet werden.
- Collector schreibt optional JSONL, aber nur wenn explizit aufgerufen.
- API-Degradation erzeugt `status=degraded`, keine Orders, keine Tuning-Aktionen.

## Phase 2 – Leader-/Vault-Scorecard

**Ziel:** Watchlist mit harten Research-/Candidate-/Blocked-Gates.

Metriken:

- `realized_pnl`, `unrealized_pnl_share`, `max_drawdown`, `closed_trades`, `age_days`
- `top_coin_pnl_share`, `top_trade_pnl_share`, Liquidationsabstand
- `leader_correlation`, `coin_overlap`, `direction_overlap`, `regime_overlap`, `drawdown_overlap`, `crowding_score`
- Regime Attribution: Bull, Bear, Sideways, High Vol, Negative/Positive Funding

Gates:

- Research-Kandidat: >=30 geschlossene Shadow-Trades.
- Candidate: >=75–100 geschlossene Shadow-Trades oder >=90 Kalendertage Beobachtung.
- Live-preview-ready: >=90 Tage, >=75 Trades, mindestens zwei Marktphasen, Netto-PnL > 0, Profit Factor >=1.3, Top-Leader/Top-Coin <=40 %, Korrelation/Crowding grün.

## Phase 3 – Position-level Shadow Copy

**Ziel:** Replizierbarkeit messen, nicht Fills blind kopieren.

Regeln:

- Copy nur bei Position-/Exposure-Wechseln, nicht bei jedem Fill.
- `position_age >= 6h` oder klarer Swing-/Position-Trade.
- Nicht kopieren, wenn Leader bereits >0.5R im Gewinn ist.
- Nicht kopieren, wenn Entry-Abstand, Spread, Tiefe, Funding oder Liquidationsabstand schlecht sind.
- Nicht kopieren, wenn gleiche Exposure bereits über andere Leader existiert.

Akzeptanzkriterien:

- Shadow-Engine berechnet follower_net_pnl = gross - entry_fee - exit_fee - spread - slippage - funding - delay.
- Jedes Shadow-Signal speichert Block-/Allow-Grund.
- Open Exposure und unrealized PnL werden im Report getrennt von closed net PnL ausgewiesen.

## Phase 4 – Daily/Weekly Research Reports

**Ziel:** Entscheide anhand von belastbaren Beobachtungen.

Daily Report:

- neue Leader/Vaults entdeckt,
- Watchlist-Änderungen,
- Shadow-PnL nach Kosten,
- Blockgründe,
- API-/Datenqualität,
- Konzentration/Crowding.

Weekly Review:

- Candidate-Verschiebungen,
- Regime-Performance,
- Leader-Stilbrüche,
- Hidden-Hedge-/Manipulationsverdacht,
- klare Live-Nein/Noch-nicht/Research-Fortsetzen-Empfehlung.

## Phase 5 – Paper Portfolio

**Ziel:** Mehrere Leader in einem simulierten Portfolio mit Exposure-Kappen testen.

Limits:

- 500-USDC-Szenario: max total copy exposure 10–15 % notional.
- Max per Leader: 3–5 % notional.
- Risk per Copy-Idee: 0.10–0.25 %.
- Max parallel Copy-Positions: 1.
- Pause, wenn Main-Bot Daily-Loss-Gate aktiv ist.

## Phase 6 – Live Preview, später und nur nach Freigabe

Hard Gates vor jedem echten Copytrade:

```text
copy_shadow_trades >= 75
copy_shadow_days >= 90
net_pnl_after_costs > 0
profit_factor_after_costs >= 1.3
max_drawdown <= 50% des geplanten Monatsverlustlimits
top_leader_pnl_share <= 40%
top_coin_pnl_share <= 40%
leader_correlation_cluster_limit grün
funding_costs eingerechnet
slippage_model konservativ
reconcile grün
kill_switch grün
telegram_alerts grün
no_shared_api_wallet_with_other_live_process
```

Zusätzlich:

- eigene API-Wallet,
- eigener Prozess,
- eigene Nonce-Verwaltung,
- reduce-only Stops/Trigger-Schutz,
- explizite Live-Copy-Freigabe.

## Aktueller Startumfang v0

In diesem Sprint wird nur Phase 0 begonnen:

- `ctb_copy` Package-Gerüst,
- konservatives Follower-Kostenmodell,
- Scorecard-Gates,
- Copy-Pretrade-Gate,
- read-only Hyperliquid Info-Collector mit Fake-Transport-Tests,
- keine Live-Ausführung.