docs: add rpc/dlob/candles notes

doc/trading-readiness.md

@@ -0,0 +1,119 @@
+# Trading readiness (staging → live) — checklista i brakujące elementy
+
+Ten dokument odpowiada na pytanie: **czy obecny warsztat jest “już dobry do trade”** i co musi być dopięte, zanim przejdziemy z obserwacji do live tradingu.
+
+W skrócie:
+- Fundament jest dobry do **prototypowania i stagingu**.
+- Do “pro trading” brakuje kilku krytycznych elementów bezpieczeństwa, audytu i historii danych.
+
+---
+
+## 1) Co już mamy (mocne strony)
+
+- **k3s + GitOps/snapshoty**: każdy deploy to snapshot, rollback jednym ruchem (`doc/workflow.md`).
+- **DLOB pipeline**: orderbook → statsy (spread/depth/slippage) pod UI/strategie (`doc/dlob-basics.md`, `doc/dlob-services.md`).
+- **Ingest ticków do DB**: dane rynkowe w Postgres/Timescale + candles przez funkcję (`doc/workflow-api-ingest.md`).
+- **UI/Visualizer**: warstwy i panele do obserwacji rynku (`doc/stats.md`).
+- **Model plane separation**: Vast ma robić inference bez sekretów (docelowo) (`doc/drift-perp-contract.md` + `doc/vast-gpu-runbook.md`).
+- **Plan pod własny RPC + streaming**: bare metal RPC + Geyser/Yellowstone gRPC (`doc/solana-rpc-geyser-setup.md`).
+- **Wyjaśnienie “czy da się bez RPC”**: co możemy policzyć z DB i DLOB, a co wymaga feedu on‑chain (`doc/drift-data-bez-solana-rpc.md`).
+
+To jest wystarczające do:
+- obserwacji live,
+- strojenia UI,
+- budowy i testów pipeline’u danych,
+- “paper trading” / dry-run w executorze.
+
+---
+
+## 2) Co jest krytycznie brakujące do live tradingu
+
+Poniższe punkty są “must‑have” zanim bot zacznie realnie składać zlecenia na Drift.
+
+### 2.1 Kontrakty bota + audyt (DB)
+
+Wymagane tabele i log:
+- `bot_contracts` (stan kontraktu / desired-state)
+- `bot_events` (decision, order_sent, order_ack, fill, cancel, exit, error, panic)
+- mapowanie: `decision_id -> client_order_id -> drift_order_id -> tx_sig`
+
+Cel:
+- da się odtworzyć “co poszło na chain”,
+- UI pokazuje stan kontraktów (live + historia),
+- łatwe debugowanie i strojenie.
+
+### 2.2 Reconcile po restarcie (must-have)
+
+Executor po starcie zawsze:
+- czyta `bot_contracts` (desired),
+- pobiera observed state z Drift (pozycje + open ordery),
+- porównuje i wykonuje minimalne akcje korekcyjne.
+
+Bez tego ryzykujesz:
+- “ghost orders”,
+- utrzymanie pozycji mimo utraty kontekstu.
+
+### 2.3 Kill-switch + guardian poza klastrem (must-have)
+
+Kill-switch w executorze to za mało, bo klaster/VPS może paść.
+
+Wzorzec:
+- osobny mały serwis `bot-guardian` poza głównym VPS/k3s,
+- jeśli heartbeat executora jest stary → guardian robi `cancel_all` + `reduce_only close`.
+
+### 2.4 Hard risk caps niezależne od modelu
+
+Nawet jeśli Vast zwraca pełny `trade_intent`, executor musi egzekwować:
+- `max_position_usd`, `max_leverage` (pośrednio), `max_orders_per_min`,
+- `max_slippage_bps`, `max_spread_bps`, `freshness_max_ms`,
+- circuit breakers (np. feed down, RPC lag, drawdown).
+
+Model może proponować parametry, ale nie może omijać twardych limitów.
+
+### 2.5 Historia danych (TS), retencja i downsample
+
+`*_latest` jest świetne do live, ale do strojenia potrzebujesz TS:
+- DLOB: `dlob_stats_ts`, `dlob_depth_bps_ts`, `dlob_slippage_ts` (min. 7 dni)
+- kontrakty: `bot_events_ts` / log z timestampem
+
+Docelowo:
+- trzymać gęste 7 dni,
+- trzymać dłużej downsample (np. 1m/5m) pod analizy reżimów.
+
+### 2.6 Monitoring i alerty (operacyjne)
+
+Minimum alertów:
+- feed freshness (DLOB/ticki),
+- RPC slot lag / error rate,
+- order reject rate,
+- panic triggers,
+- disk fill/iowait (RPC node).
+
+---
+
+## 3) “Go/No-Go” do pierwszego live (small size)
+
+**Go** jeśli:
+- kontrakty i eventy są w DB,
+- reconcile działa (test restartu),
+- kill-switch działa (test: panic → flat),
+- mamy twarde limity ryzyka,
+- mamy podstawowe alerty,
+- mamy 7 dni TS pod progi (albo chociaż 24h na start) i znamy percentyle spread/slippage/depth.
+
+**No-Go** jeśli:
+- nie potrafimy deterministycznie zidentyfikować orderów (brak `client_order_id` / brak logów),
+- restart executora może zostawić pozycję bez kontroli,
+- nie ma niezależnego guardiana.
+
+---
+
+## 4) Proponowana kolejność implementacji (minimalny path)
+
+1) `bot_contracts` + `bot_events` + UI podgląd kontraktów (read-only).
+2) “observe-only executor” (bez tx) → loguje decyzje z modelu/reguł.
+3) TS history: DLOB (7 dni) + podstawowe agregacje.
+4) Dry-run/paper: executor wylicza i loguje order plan (bez tx).
+5) Live minimal: mały size, limit/post-only + chase, twarde caps.
+6) Guardian poza klastrem.
+7) Geyser/Yellowstone (jeśli WS RPC nie trzyma stabilnie na skali).