docs: add rpc/dlob/candles notes

doc/candles-cache.md

@@ -0,0 +1,39 @@
+# Candles cache: precompute wszystkich timeframe (1s…1d)
+
+Cel: przełączanie `tf` w UI ma być natychmiastowe. Backend ma **ciągle liczyć** i **przechowywać** świeczki dla wszystkich timeframe:
+
+`1s 3s 5s 15s 30s 1m 3m 5m 15m 30m 1h 4h 12h 1d`
+
+## Jak to działa
+
+1) Ticki (append-only) lądują w `drift_ticks`.
+2) Worker `candles-cache-worker`:
+   - liczy świeczki dla **każdego** `bucket_seconds` bezpośrednio z `drift_ticks`,
+   - trzyma w DB “ostatnie N” świec (domyślnie `N=1024`) per `(symbol, source, tf)`,
+   - jeśli danych historycznych jest mniej (np. brak wielu dni) — zapisuje tylko to, co istnieje,
+   - robi backfill/warmup przy starcie i potem dopisuje “na bieżąco” w pętli.
+3) API `GET /v1/chart` czyta **cache-first** z `drift_candles_cache` (fallback do on-demand funkcji, jeśli cache pusty).
+
+## Tabela
+
+- `drift_candles_cache` (Timescale hypertable, partycjonowanie po `bucket`)
+  - `bucket_seconds` = długość świecy w sekundach
+  - `source=''` oznacza “(any)” (brak filtra po źródle ticków)
+
+## Worker
+
+Plik: `services/candles-worker/candles-cache-worker.mjs`
+
+Env:
+- `CANDLES_SYMBOLS` (np. `SOL-PERP,PUMP-PERP`)
+- `CANDLES_SOURCES` (np. `any,drift_oracle`)
+- `CANDLES_TFS` (np. `1s,3s,5s,15s,...,1d`)
+- `CANDLES_TARGET_POINTS` (default `1024`)
+- `CANDLES_BACKFILL_DAYS` (opcjonalnie: wymusza minimalny warmup “co najmniej X dni”)
+- `CANDLES_POLL_MS` (default `5000`)
+
+## Dlaczego to jest szybkie
+
+- najcięższe agregacje są robione raz i utrzymywane “na bieżąco”,
+- przełączenie `tf` to tylko query po gotowych wierszach (`order_by bucket desc limit N`),
+- “flow/brick stack” w `/v1/chart` jest liczone z cache “point candles” (np. `1s/3s/5s/15s/…`) bez skanowania `drift_ticks`.

doc/dlob-basics.md

@@ -0,0 +1,216 @@
+# DLOB + L1…L10 — podstawy (co jest czym i gdzie to liczymy)
+
+Ten dokument wyjaśnia pojęcia:
+- **DLOB** (Drift Limit Order Book),
+- **L1 / L2 / L3** oraz potoczne **L1…L10**,
+- na jakich warstwach w naszym stacku powstają dane i metryki,
+- gdzie “pracuje AI” (modele/strategie) vs gdzie jest execution (order placement).
+
+## Co to jest DLOB
+
+**DLOB** = *Decentralized Limit Order Book* w Drift.
+
+W praktyce: to jest **księga zleceń** dla rynku (np. `SOL-PERP`):
+- **bids** = zlecenia kupna (po stronie bid),
+- **asks** = zlecenia sprzedaży (po stronie ask).
+
+Księga ma wiele “poziomów” cenowych; przy każdej cenie stoi pewna ilość (size).
+
+## L1 / L2 / L3 (format i sens)
+
+### L1 (Top of Book)
+L1 to skrót od “top of book”:
+- **best bid** = najwyższa cena kupna (pierwszy poziom po stronie bid),
+- **best ask** = najniższa cena sprzedaży (pierwszy poziom po stronie ask).
+
+Z L1 najczęściej liczysz:
+- **spread** = `best_ask - best_bid`,
+- **mid** = `(best_bid + best_ask) / 2`.
+
+### L2 (zagregowane poziomy)
+L2 to lista poziomów (levels) po obu stronach:
+- `bids: [{ price, size }, ...]` (zwykle posortowane malejąco po `price`)
+- `asks: [{ price, size }, ...]` (zwykle posortowane rosnąco po `price`)
+
+To jest najpopularniejszy “orderbook UI”: słupki/heat per poziom ceny.
+
+### L3 (pojedyncze zlecenia)
+L3 to “niezagregowane” dane: pojedyncze zlecenia (większy wolumen danych).
+U nas pod UI i metryki zazwyczaj wystarcza L2.
+
+## L1…L10 (co to znaczy w praktyce)
+
+**L1…L10** to potoczne określenie:
+> “pierwsze 10 poziomów z L2 najbliżej top of book”.
+
+To nie jest osobny format; to po prostu wycinek L2.
+
+W naszym stacku “ile leveli bierzemy” kontroluje:
+- `DLOB_DEPTH` (np. 10 → “L1…L10”).
+
+## Jak to działa w naszym stacku (warstwy)
+
+Poniżej “łańcuch” od źródła do metryk:
+
+### Warstwa A: On-chain → DLOB w pamięci (VPS/k3s)
+Komponent: `dlob-publisher`.
+
+- Łączy się do Solany przez `ENDPOINT` (HTTP RPC) i `WS_ENDPOINT` (WebSocket).
+- Subskrybuje konta/zdarzenia i buduje DLOB (orderbook) w pamięci.
+- Publikuje snapshoty do Redis (u nas: `dlob-redis`).
+
+To jest najbliżej źródła i zwykle najbardziej “real-time”.
+
+### Warstwa B: Cache + REST API (VPS/k3s)
+Komponenty: `dlob-redis` + `dlob-server`.
+
+- `dlob-redis` trzyma snapshoty/publish.
+- `dlob-server` udostępnia HTTP:
+  - `GET /l2?marketName=SOL-PERP&depth=10` → L2 (bids/asks + best bid/ask itp.)
+  - `GET /l3?...` → L3 (jeśli potrzebujesz)
+
+To jest warstwa dystrybucji danych “w klastrze”, żeby inne serwisy nie musiały gadać bezpośrednio z Solaną.
+
+Uwaga o rynkach:
+- `dlob-publisher` ładuje rynki wg `PERP_MARKETS_TO_LOAD` (indeksy) / `SPOT_MARKETS_TO_LOAD`.
+- Jeśli rynek nie jest załadowany przez publisher, `dlob-server` nie rozpozna `marketName`.
+
+### Warstwa C: Metryki w DB/Hasura (VPS/k3s)
+Komponenty: `dlob-worker`, `dlob-depth-worker`, `dlob-slippage-worker`.
+
+To są “workery pod UI/AI”, które liczą metryki i zapisują je do Postgresa (Hasura).
+
+#### `dlob-worker` (collector + basic stats)
+Wejście:
+- odpytuje `dlob-server` po HTTP `/l2` (źródło L2),
+- rynki: `DLOB_MARKETS`,
+- głębokość (ile leveli): `DLOB_DEPTH`,
+- częstotliwość: `DLOB_POLL_MS`.
+
+Wyjście (upsert do DB):
+- `dlob_l2_latest` = snapshot L2 “latest” per market,
+- `dlob_stats_latest` = pochodne metryki liczone z top‑N leveli (N=`DLOB_DEPTH`), m.in.:
+  - `mid_price`, `spread_abs`, `spread_bps`,
+  - `depth_bid_*` / `depth_ask_*`,
+  - `imbalance`.
+
+Czyli: jeśli pytasz “gdzie liczymy L1…L10 metryki” → tutaj (w `dlob-worker`), bo bierze top‑N leveli z L2.
+
+#### `dlob-depth-worker` (depth w bandach bps)
+Wejście:
+- czyta z DB `dlob_l2_latest` (czyli już “przetworzone” L2).
+
+Wyjście:
+- `dlob_depth_bps_latest` = płynność w pasmach wokół mid (np. ±5/10/20/50/100/200 bps).
+
+To nie jest “L1…L10”, tylko “ile płynności mieści się w oknie cenowym” wokół mid.
+
+#### `dlob-slippage-worker` (slippage vs size)
+Wejście:
+- czyta z DB `dlob_l2_latest`.
+
+Wyjście:
+- `dlob_slippage_latest` = symulacja wykonania zlecenia (market) po L2 dla progów `DLOB_SLIPPAGE_SIZES_USD`.
+
+To jest bardzo użyteczne jako feature do strategii (“ile kosztuje wejście/wyjście teraz dla X USD”).
+
+## Gdzie “pracuje AI” (TFT itp.)
+
+AI/strategia powinna pracować na warstwie “features”, a nie na surowych subskrypcjach Solany:
+
+Najczęstszy zestaw wejść dla modelu:
+- candles/ticki (np. `drift_ticks` + `get_drift_candles(...)`),
+- bieżące statsy z DLOB:
+  - `dlob_stats_latest` (mid/spread/depth/imbalance),
+  - `dlob_depth_bps_latest` (depth w bandach),
+  - `dlob_slippage_latest` (slippage vs size),
+- opcjonalnie pełny snapshot L2 (z `dlob_l2_latest`), jeśli model potrzebuje “kształtu” książki.
+
+Kluczowa zasada bezpieczeństwa:
+- **Model (np. na Vast)** może sugerować “desired state” (wejść/wyjść/parametry),
+- **Executor na VPS** zawsze odpowiada za:
+  - risk checks,
+  - składanie/cancel/close,
+  - klucze prywatne i podpisywanie transakcji,
+  - kill switch.
+
+## Szybki słownik (1-liner)
+
+- **bid**: kupno, zielona strona książki
+- **ask**: sprzedaż, czerwona strona książki
+- **best bid / best ask (L1)**: top-of-book
+- **spread**: koszt “wejścia/wyjścia natychmiast” (ask-bid)
+- **mid**: punkt odniesienia między bid/ask
+- **L2**: lista poziomów `{price,size}`
+- **L1…L10**: top 10 poziomów z L2 (u nas kontrolowane przez `DLOB_DEPTH`)
+
+## Jak liczymy “liquidity” i “kasa” (USD) w metrykach
+
+W UI/DB słowo “liquidity” zwykle oznacza **depth**: “ile wolumenu stoi w orderbooku blisko ceny”.
+U nas trzymamy to rozdzielnie dla bid/ask oraz w dwóch wariantach:
+
+### A) Top‑N leveli (np. L1…L10) — `dlob_stats_latest`
+Liczone w `dlob-worker` na podstawie L2 z `/l2`:
+
+- Bierzemy pierwsze `N = DLOB_DEPTH` leveli z `bids` i `asks`.
+- Każdy level ma:
+  - `price = price_int / PRICE_PRECISION`
+  - `size_base = size_int / BASE_PRECISION`
+  - “kasa” (notional) na tym levelu: `size_usd = size_base * price`
+- Sumujemy po levelach:
+  - `depth_bid_base = Σ size_base` (po stronie bid),
+  - `depth_bid_usd = Σ (size_base * price)` (po stronie bid),
+  - analogicznie `depth_ask_base`, `depth_ask_usd` (po stronie ask).
+
+To odpowiada intuicji “ile jest płynności na L1…LN”.
+
+### B) Okno cenowe w bps od mid — `dlob_depth_bps_latest`
+Liczone w `dlob-depth-worker` na podstawie `dlob_l2_latest`:
+
+- Dla pasma `band_bps` wyznaczamy:
+  - `minBidPrice = mid * (1 - band_bps/10_000)`
+  - `maxAskPrice = mid * (1 + band_bps/10_000)`
+- Sumujemy wszystkie levele, które mieszczą się w tym oknie:
+  - bids: `price >= minBidPrice`
+  - asks: `price <= maxAskPrice`
+- Liczymy sumy:
+  - `bid_base`, `bid_usd`, `ask_base`, `ask_usd` tak jak wyżej (`usd = base * price`).
+
+To odpowiada intuicji “ile płynności jest *blisko* ceny w ±X bps”.
+
+### Ważne doprecyzowanie
+
+Te liczby to **notional z orderbooka** (ile “stoi” na poziomach cenowych).
+Nie są to “pieniądze w kontrakcie”, tylko przybliżenie kosztu/pojemności wykonania przy danej cenie i bez przesunięcia rynku.
+
+## Spec: Orderbook UI (L1…L10 + “liquidity bars”)
+
+Wizualizacja orderbooka (jak na screenach) jest oparta o L2 i pokazuje tylko top‑N leveli:
+- `N` = liczba leveli wyświetlanych na stronę (np. 10 → “L1…L10”).
+
+### Kolumny / wartości
+
+Na każdym levelu liczymy:
+- `size_usd = size_base * price`
+
+W UI pokazujemy:
+- `Size (USD)` = `size_usd` dla danego poziomu,
+- `Total (USD)` = suma skumulowana od best‑price “w głąb” (cumulative):
+  - bids: kumulacja od best bid w dół,
+  - asks: kumulacja od best ask w górę (w UI zwykle best ask jest bliżej środka).
+
+### “Liquidity bars” (znormalizowane słupki tła)
+
+Żeby “na oko” widzieć gdzie stoi płynność:
+
+1) **Level bar (per‑poziom)** — normalizacja do największego `size_usd` w widocznych levelach danej strony:
+   - `level_scale = size_usd / max(size_usd w widoku)`
+2) **Total bar (cumulative)** — normalizacja do największego `total_usd` w widocznych levelach danej strony:
+   - `total_scale = total_usd / max(total_usd w widoku)`
+
+Żeby duże “ściany” nie zabijały kontrastu, warto użyć krzywej:
+- `scale_curved = sqrt(clamp01(scale))`
+
+Interpretacja:
+- **level bar** = “ile stoi na tym poziomie”,
+- **total bar** = “ile stoi łącznie do tego poziomu”.

doc/drift-costs.md

@@ -0,0 +1,120 @@
+# Drift Perp: koszty wejścia/edycji/wyjścia (stan na 2026-01-31)
+
+Ten dokument zbiera **wszystkie realne składowe kosztu** przy handlu perps na Drift, żebyśmy mogli je liczyć na backendzie i wizualizować w UI.
+
+## 1) Składowe kosztu (per trade / per pozycja)
+
+### A. Opłata transakcyjna Drift (maker/taker)
+- **Taker fee**: procent od **notional** (wartości pozycji w USD/USDC).
+- **Maker fee**: zwykle **ujemny** (rebate) dla zleceń maker (np. post-only), zgodnie z aktualnym cennikiem.
+- Stawki zależą od wolumenu 30D oraz stakingu DRIFT (dodatkowe zniżki / większe rebate).
+- W **High Leverage Mode** taker fee może być podbite (np. 2× najniższy tier).
+> TODO: potwierdzić aktualne stawki fee (z Drift SDK / on-chain) i zapisać je jako “source of truth” dla backendu.
+
+**Wzór (pojedynczy fill):**
+- `notional = |size_base| * fill_price`
+- `trade_fee_usd = notional * fee_rate` (dla maker `fee_rate` może być < 0)
+
+### B. Slippage / spread (koszt rynkowy)
+To nie jest fee protokołu, ale realny koszt wejścia/wyjścia:
+- `slippage_cost_usd ≈ (fill_price - mid_price) * size_base` (znak zależy od long/short)
+- U nas to powinno być liczone z DLOB (L2 + symulacja fill).
+
+### C. Funding (koszt/zarobek w czasie trzymania pozycji)
+- Funding jest naliczany w czasie i realizowany przy akcjach użytkownika (trade/deposit/withdraw) – w praktyce dla krótkich holdingów (minuty–1h) zwykle jest małym składnikiem, ale nie zawsze zerowym.
+
+**Wzór (upraszczając):**
+- `funding_usd ≈ Σ (position_notional_usd * funding_rate_interval)`
+
+### D. P&L settlement / “unsettled P&L” (wpływ na withdraw)
+- Żeby **wypłacić zysk**, czasem trzeba wykonać `settlePNL` (rozlicza P&L do P&L Pool; nie zamyka pozycji, tylko zmienia cost basis).
+- Jeśli brakuje środków w per-market P&L Pool, zysk może być częściowo **unsettled** i nie będzie w pełni wypłacalny od razu.
+
+### E. Liquidation penalty (jeśli konto spadnie poniżej maintenance)
+- Przy wejściu w liquidację protokół najpierw anuluje otwarte ordery/LP, a następnie liquidator może redukować pozycje.
+- “Penalty/fee” jest ustawiana per-market i zwykle jest wyższa niż zwykły taker fee (żeby dać rebate liquidatorowi).
+
+### F. Koszt sieci Solana (per instrukcja / per tx)
+To koszt “infrastrukturalny” każdej akcji on-chain (order, cancel, modify, settlePNL, deposit/withdraw, close).
+- **Base fee**: 5000 lamports per signature (minimum).
+- **Priority fee**: opcjonalny, zależy od congestion.
+- Jednorazowo może dojść **rent/account creation** (np. token account), jeśli czegoś brakuje.
+
+## 2) “Ile kosztuje” konkretna akcja (checklista)
+
+### Wejście w pozycję (open / increase)
+1) **Solana tx fee** (base + ewentualnie priority)
+2) **Drift trading fee** (maker/taker) od notional
+3) **Slippage/spread** (z DLOB)
+4) (w tle) funding zaczyna naliczać się w czasie
+
+### Zmiana pozycji (increase/decrease/flip)
+To po prostu kolejny trade:
+- znowu `tx fee + trading fee + slippage`
+- oraz często realizacja funding (zależy od tego czy funding został zaktualizowany)
+
+### Wyjście z pozycji (close)
+1) `tx fee`
+2) `trading fee` (druga strona round-trip)
+3) `slippage`
+4) **realized PnL** = różnica cen ± funding − fees
+5) jeśli chcesz wypłacić: możliwe `settlePNL` oraz limit z P&L pool
+
+### Edycja zlecenia (modify)
+Zwykle koszt to:
+- `tx fee` (czasem modify = cancel+place, zależnie od ścieżki w kliencie)
+- brak trading fee, jeśli nie było fill
+
+### Cancel zlecenia
+- `tx fee`
+- brak trading fee (jeśli 0 fill)
+
+### Monitorowanie zysku / risk (PnL, margin, health)
+On-chain: bez kosztu, jeśli tylko czytasz RPC/indexera.
+Koszt pojawia się dopiero przy akcjach typu trade/cancel/settle/withdraw.
+
+## 3) Przykład liczbowy (taker, round-trip)
+
+Załóż:
+- `notional = 10,000 USDC`
+- `taker_fee_rate = 0.0350%` (PRZYKŁAD – realna stawka zależy od tieru)
+
+Wtedy:
+- wejście: `10,000 * 0.00035 = 3.50 USDC`
+- wyjście: `3.50 USDC`
+- razem fee (bez slippage/funding): `7.00 USDC` + 2× Solana tx fee (+ priority jeśli ustawisz).
+
+## 4) Co musimy znać, żeby liczyć to “dokładnie” w backendzie
+
+Minimalny zestaw wejść:
+- market (np. `SOL-PERP`)
+- order type (market/limit/post-only), przewidywany fill path (taker vs maker)
+- notional/size, przewidywany fill (DLOB simulation)
+- fee tier użytkownika + staking/discounty + ew. “fee adjusted markets”
+- funding history + horyzont (np. 1h/4h/24h/7d)
+- czy chcemy uwzględniać `settlePNL` oraz status “unsettled PnL” przed withdraw
+
+---
+
+## 5) Słownik (kluczowe pojęcia w UI/API)
+
+Poniżej jest skrót pojęć, których używamy w warstwach “Costs (New)” i “Costs (Active)”:
+
+- `notional` — wartość pozycji w USD (np. 10 USD); na tym liczymy bps i fee.
+- `bps` (basis points) — punkty bazowe: `1 bps = 0.01% = 0.0001`.  
+  Przeliczenie na koszt: `koszt_usd ≈ notional_usd * bps / 10_000`.
+- `fee` — opłata protokołu Drift (maker/taker) od `notional`; zwykle stała dla danego trybu/tieru.
+- `tx fee` — koszt transakcji na Solanie (base fee + ewentualny priority fee).
+- `slippage` — koszt rynkowy wejścia/wyjścia, bo wykonujesz się gorzej niż `mid` (zależy od płynności).
+- `impact (bps)` — slippage wyrażony w bps (dla danego notionalu).
+- `spread` — różnica `best_ask - best_bid`; “minimalny” koszt natychmiastowego wejścia/wyjścia w płytkim booku.
+- `mid` — `(best_bid + best_ask) / 2`; punkt odniesienia ceny z orderbooka.
+- `VWAP` — średnia cena wykonania dla danego rozmiaru (symulacja fill po L2).
+- `breakeven (bps)` — minimalny ruch ceny (w bps), żeby koszty się zwróciły (wyjść na 0).
+- `PnL` (profit and loss) — zysk/strata:
+  - `unrealized PnL` — “na papierze”, gdy pozycja jest otwarta (zależy od ceny teraz),
+  - `realized PnL` — zrealizowany po zamknięciu (lub częściowym zamknięciu) pozycji,
+  - `net PnL` — PnL po odjęciu kosztów (`fee + tx + slippage + funding`).
+- `funding` — okresowa płatność long↔short; koszt albo zysk zależny od rynku i czasu trzymania.
+- `close now` — estymata kosztu natychmiastowego zamknięcia pozycji (zwykle po przeciwnej stronie booka).
+- `modify` / `reprice` — koszt “zarządzania zleceniem” (cancel+place itp.), głównie `tx fee` (czasem wielokrotnie).

doc/drift-data-bez-solana-rpc.md

@@ -0,0 +1,109 @@
+# Drift / Solana: czy mamy dostęp do danych bez Solana RPC?
+
+Pytanie ma dwa znaczenia — rozdzielmy je jasno:
+
+1) **bez własnego (bare metal) RPC** — czyli nie utrzymujemy swojego `solana-validator --rpc`, ale korzystamy z dostawcy RPC albo zewnętrznych serwisów,
+2) **bez żadnego RPC w ogóle** — czyli nikt w naszym systemie nie pyta Solany o stan on‑chain.
+
+TL;DR:
+- **Bez własnego RPC**: tak, da się na start (hosted RPC +/lub serwisy zewnętrzne).
+- **Bez żadnego RPC**: tylko częściowo (dane “rynkowe” można brać z zewnętrznego DLOB), ale **stan konta/pozycji/fille/funding** i tak pochodzi z chaina, więc ktoś musi mieć RPC.
+
+---
+
+## Co z Twojego “speca” da się mieć bez własnego RPC?
+
+Poniżej mapowanie kategorii danych (z Twojego opisu A–F) na źródła:
+
+### B) Prices / microstructure (oracle/mark/BBO, “close now”)
+
+**Da się bez własnego RPC**:
+- Tak. W naszym stacku te dane mogą pochodzić z pipeline DLOB (`dlob_*_latest`) i ticków (`drift_ticks`), które są już w DB i dostępne przez Hasurę / `trade-api`.
+
+**Da się bez żadnego RPC w naszej infra** (czyli “my nie łączymy się do RPC”):
+- Częściowo tak, jeśli polegamy na zewnętrznym źródle L2/BBO (np. `https://dlob.drift.trade`) — ale to źródło i tak jest zasilane przez czyjeś RPC.
+
+### A) Position snapshot (pozycja: base, entry, side)
+
+**Bez własnego RPC**:
+- Tak, jeśli mamy **jakikolwiek** komponent (executor/collector) korzystający z hosted RPC (Helius/QuickNode/itp.) i zapisujący snapshot pozycji do DB.
+
+**Bez żadnego RPC**:
+- Praktycznie nie (pozycja jest stanem konta on‑chain). Wyjątek: jeśli Twój executor/bot sam utrzymuje lokalny stan i zapisuje go do DB — ale po restarcie i tak potrzebujesz reconcile z chaina (czyli RPC).
+
+### C) Account risk (margin/liquidation/health)
+
+**Bez własnego RPC**:
+- Tak, jeśli collector liczy to na backendzie z danych Drift (przez hosted RPC) i zapisuje do TS (`contract_metrics_ts` / analogicznie).
+
+**Bez żadnego RPC**:
+- Nie, bo margin/liq zależy od stanu konta i parametrów rynku on‑chain.
+
+### D) Fills / trades (realized PnL + fees + slippage)
+
+**Bez własnego RPC**:
+- Tak, jeśli:
+  - executor składa zlecenia i loguje fille do `bot_events` (to już mamy jako koncept), albo
+  - collector subskrybuje eventy transakcji / kont przez hosted RPC i zapisuje fille do DB.
+
+**Bez żadnego RPC**:
+- Tylko jeśli fille są już zapisane w DB (np. przez bota). Na bieżąco — ktoś musi je wyciągać z chaina.
+
+### E) Funding / payments
+
+**Bez własnego RPC**:
+- Tak, ale ktoś musi pobierać funding rate / funding payment (hosted RPC lub inny feed) i zapisywać do DB.
+
+**Bez żadnego RPC**:
+- Jak wyżej: tylko z historii zapisanej w DB; na żywo potrzebujesz źródła z chaina.
+
+### F) Order lifecycle costs (cancel/replace/tx)
+
+**Bez własnego RPC**:
+- Tak, jeśli executor:
+  - loguje akcje (create/cancel/replace) i ich koszty (`tx_fee_usd`, priority fee) do `bot_events`, albo
+  - collector wyciąga metryki tx z RPC i mapuje do orderów.
+
+**Bez żadnego RPC**:
+- Tylko retrospektywnie (jeśli już w DB).
+
+---
+
+## Co to znaczy praktycznie dla architektury “backend liczy, UI tylko wyświetla”?
+
+UI/Visualizer **może działać bez bezpośredniego kontaktu z RPC** (łączy się do `trade-api` + Hasura).
+
+Natomiast backend “compute” (k3s) ma dwie opcje zasilania:
+
+1) **Hosted RPC** (na start)  
+   - pro: szybciej, taniej, mniej ops,
+   - con: limit subskrypcji/WS, możliwe rwania, vendor lock‑in.
+
+2) **Własny RPC + Geyser/Yellowstone** (docelowo)  
+   - pro: kontrola, stabilność na większej skali, streaming “pro”,
+   - con: koszt i ops (dyski/IO, tuning, monitoring).
+
+W obu przypadkach “backend liczy” działa tak samo — różni się tylko źródło surowych danych.
+
+---
+
+## Co już mamy w DB “bez RPC w UI”
+
+Z obecnego pipeline (VPS/k3s) mamy “rynkowe” dane pod BBO/slippage:
+- `dlob_l2_latest`, `dlob_stats_latest`, `dlob_slippage_latest`, `dlob_depth_bps_latest` (+ TS przez `*_ts`)
+- `drift_ticks` (ticki/ceny)
+
+To wystarcza do:
+- estymat wejścia/wyjścia (“close now”),
+- wykresów spread/slippage/depth,
+- części SIM (model slippage/fee) **bez** znajomości pełnego stanu konta.
+
+Do pełnego `contract_metrics_ts` (PnL + risk) brakuje nam jeszcze stałego feedu:
+- pozycji konta + margin/liq,
+- filli i funding (albo z chaina, albo z logów executora).
+
+## Zobacz też
+
+- “Kanoniczna” architektura w pełni self-hosted (RPC + DLOB): `doc/rpc-dlob-kanoniczna-architektura.md`
+- Runbook: bare metal RPC + Geyser/Yellowstone gRPC: `doc/solana-rpc-geyser-setup.md`
+- Mapa dokumentów o RPC/DLOB/metrykach: `doc/solana-rpc.md`

doc/drift-perp-contract.md

@@ -0,0 +1,262 @@
+# Drift PERP “kontrakt bota” (SOL-PERP) — spec intent → egzekucja → audyt
+
+Ten dokument definiuje **przyszłościowy** kontrakt między:
+- **Vast (model/transformer na GPU)**: generuje *trade intent* (bez sekretów),
+- **k3s/VPS (executor)**: waliduje ryzyko, wystawia i prowadzi zlecenia na Drift, loguje zdarzenia,
+- **UI (visualizer)**: tylko wizualizuje warstwy i stan kontraktów (live + historia).
+
+Kluczowa zasada: **model nigdy nie ma kluczy** i nie “handluje”. Handluje tylko executor w k3s.
+
+Powiązane:
+- Strategia “eskalacja horyzontu” (1m→5m→15m→30m→1h z bramkami): `doc/strategy-eskalacja-horyzontu.md`
+
+---
+
+## 1) Co nazywamy “kontraktem” (u nas vs Drift)
+
+Na Drift istnieją:
+- **orders** (zlecenia): limit/market/trigger, post-only, reduce-only, IOC/GTC itd.
+- **position** (pozycja): rozmiar, kierunek, średnia cena, PnL itd.
+- **konto/margin**: collateral i health.
+
+W naszym systemie **kontrakt bota** to byt aplikacyjny (DB + logika), który:
+1) opisuje *intent* (wejście + prowadzenie + wyjście),
+2) mapuje intent na 1..N orderów na Drift,
+3) jest **idempotentny** (nie dubluje orderów po restarcie),
+4) jest **modyfikowalny** (cancel+place / zmiana desired state),
+5) jest **kończony** (exit policy lub kill-switch),
+6) jest **audytowalny** (pełny log decyzji i akcji).
+
+---
+
+## 2) Wybór “lepszy i przyszłościowy”
+
+### A) Cena jako offset, nie absolutna cena (recommended)
+
+Model zwraca cenę wejścia/wyjścia jako **offset** (ticks/bps) względem top-of-book / mid, a nie jako `limit_price`.
+
+Dlaczego:
+- odporniejsze na latency (cena się przesuwa, offset pozostaje sensowny),
+- łatwiejsze “reprice” (edit policy jest naturalna),
+- mniejsze ryzyko “starej ceny” przy krótkim TTL.
+
+Executor i tak zna:
+- `best_bid/best_ask/mid`,
+- tick size i step size,
+- aktualne gates (spread/slippage/depth/freshness).
+
+### B) Desired-state jako rdzeń (recommended)
+
+Kontrakt jest prowadzony jako **desired-state loop**:
+- model/kontrakt mówi “co chcę mieć” (np. `target_exposure_usd`),
+- executor porównuje “observed vs desired” i wykonuje minimalne akcje.
+
+To upraszcza:
+- edycję (zmiana target, update policy),
+- reconcile po restarcie,
+- panic exit.
+
+---
+
+## 3) Role: Vast vs executor (k3s)
+
+### Vast (model) zwraca
+- kompletny **trade_intent**: parametry wejścia/prowadzenia/wyjścia,
+- sugestie gates (np. spread/slippage/depth), **ale** nie może ich omijać,
+- `confidence/urgency` (metadata).
+
+### Executor (k3s) jest “single source of execution”
+- waliduje gates i limity,
+- normalizuje do tick/step,
+- nadaje idempotentne `client_order_id`,
+- składa/canceluje/zamyka (reduce-only),
+- prowadzi state machine,
+- loguje eventy i mierzy koszty.
+
+---
+
+## 4) Spec: `trade_intent` (Vast → k3s)
+
+Format jest wersjonowany: `intent_schema_version`.
+
+### 4.1 Minimalny szkielet
+
+```jsonc
+{
+  "intent_schema_version": 1,
+  "decision_id": "ulid-or-uuid",
+  "bot_id": "bot-sol-perp-01",
+  "ts": "2026-01-31T00:00:00.000Z",
+  "ttl_ms": 15000,
+
+  "market_name": "SOL-PERP",
+  "subaccount_id": 0,
+
+  "mode": "enter|manage|exit|panic",
+  "confidence": 0.0,
+  "urgency": 0.0,
+
+  "desired": {
+    "target_exposure_usd": 0,
+    "max_position_usd": 200,
+    "min_trade_usd": 5
+  },
+
+  "entry": {
+    "side": "long|short",
+    "order_type": "post_only_limit|limit|market",
+    "size_usd": 25,
+    "limit_offset": { "ref": "best_bid|best_ask|mid", "ticks": 1 },
+    "time_in_force": "GTC|IOC",
+    "cancel_if_not_filled_ms": 8000
+  },
+
+  "manage": {
+    "reprice_after_ms": 750,
+    "reprice_offset_ticks": 1,
+    "max_reprices_per_min": 30,
+    "cooldown_ms": 250
+  },
+
+  "exit": {
+    "max_hold_s": 180,
+    "stop_loss_bps": 25,
+    "take_profit_bps": 35,
+    "exit_order_type": "reduce_only_limit|reduce_only_market",
+    "exit_limit_offset": { "ref": "best_bid|best_ask|mid", "ticks": 1 }
+  },
+
+  "gates": {
+    "freshness_max_ms": 1500,
+    "max_spread_bps": 10,
+    "max_slippage_bps": 25,
+    "min_depth_topn_usd": 5000,
+    "min_depth_band": { "band_bps": 20, "min_usd": 8000 }
+  }
+}
+```
+
+### 4.2 Zasady interpretacji
+
+- `ttl_ms`: po tym czasie executor ma prawo *zignorować* intent (stary sygnał).
+- `mode`:
+  - `enter`: wolno otwierać/rozszerzać pozycję,
+  - `manage`: tylko zarządzanie już istniejącą pozycją/ordreami (bez zwiększania ryzyka),
+  - `exit`: przejście do `target_exposure_usd=0` i zamykanie,
+  - `panic`: natychmiast cancel + close (reduce-only), potem `off`.
+- `desired.target_exposure_usd` jest źródłem prawdy, ale executor ma **hard cap** `max_position_usd` (model może sugerować, executor egzekwuje).
+- `limit_offset`:
+  - `ref=best_bid` dla wejścia long (maker),
+  - `ref=best_ask` dla wejścia short,
+  - ticks/bps są zaokrąglane do tick size rynku.
+
+---
+
+## 5) Mapowanie `trade_intent` → Drift order params (PERP)
+
+Executor buduje “order template” (pseudopola):
+
+- `marketIndex` (wynik mapowania `market_name`)
+- `direction`: `long|short`
+- `orderType`: `market|limit` (+ `trigger*` jeśli później dodamy SL/TP jako ordery trigger)
+- `baseAssetAmount` (z `size_usd` przeliczone do base i zaokrąglone do `baseStepSize`)
+- `price` (dla limit): z `limit_offset` + aktualne top-of-book, zaokrąglone do `priceTickSize`
+- `postOnly`: true, jeśli `order_type=post_only_limit`
+- `reduceOnly`: true na wyjściu (`exit_order_type=reduce_only_*`)
+- `immediateOrCancel`: true, jeśli `time_in_force=IOC`
+- `clientOrderId` / `userOrderId`: deterministycznie z `decision_id` (patrz niżej)
+
+### 5.1 Idempotencja: `client_order_id`
+
+Wymaganie: po restarcie executora nie może dojść do “double order”.
+
+Zasada:
+- każde wejście/wyjście ma stabilne `client_order_id` wywiedzione z `decision_id`,
+- jeśli Drift nie wspiera pełnego “modify”, executor robi `cancel + place` ale zachowuje spójne ID (np. `decision_id` + suffix `-r1`, `-r2` dla reprices).
+
+---
+
+## 6) State machine kontraktu (minimal)
+
+Rekomendowane stany:
+- `off` (nie handluje)
+- `pending_entry` (intent zaakceptowany, order wysłany)
+- `entered` (pozycja ≠ 0 lub entry fill)
+- `managing` (utrzymuje desired state / repricing)
+- `exiting` (reduce-only close w toku)
+- `closed` (pozycja 0, brak orderów)
+- `rejected` (gates fail / TTL expired)
+- `panic` (cancel+close; potem `off`)
+
+Każda zmiana stanu = event do DB.
+
+---
+
+## 7) Co UI wizualizuje (warstwy) a co liczy backend
+
+UI nie liczy. UI:
+- subskrybuje `*_latest` (live),
+- pobiera `*_ts` (historia),
+- renderuje warstwy i kontrakty.
+
+Backend liczy:
+- DLOB: `dlob_*_latest` + (docelowo) `dlob_*_ts`
+- ticks/candles: `drift_ticks` + `get_drift_candles(...)`
+- kontrakty: `bot_intents` / `bot_contracts` / `bot_events` (+ TS wersje)
+
+---
+
+## 8) Metryki do strojenia (co mierzyć i jakie okna czasowe)
+
+Cel: stroić gates, politykę repricing i parametry exit.
+
+### 8.1 Mikrostruktura (gates) — z czego stroimy progi
+Źródła: `dlob_stats_*`, `dlob_depth_*`, `dlob_slippage_*`.
+
+Mierz (per market, live + TS):
+- `spread_bps`
+- `impact_bps` dla docelowych `size_usd` (buy/sell)
+- `depth_bid_usd`, `depth_ask_usd` (top‑N)
+- depth w bandach (`band_bps`): `bid_usd/ask_usd`
+- `freshness_ms` (now - updated_at)
+
+Okno strojenia:
+- start: **7 dni** TS (wystarczy do percentyli i pór doby),
+- docelowo: 30+ dni (downsample 1m/5m) dla stabilniejszych reżimów.
+
+Jak stroić:
+- progi na percentylach (P90/P95), nie na średniej,
+- osobne percentyle per “godzina doby” (płynność) i per “vol regime”.
+
+### 8.2 Jakość egzekucji (czy entry/manage działa)
+Źródła: `bot_events` (audyt) + snapshoty z momentu decyzji.
+
+Mierz per kontrakt:
+- `time_to_first_fill_ms`, `time_to_full_fill_ms`
+- `fill_pct`, `avg_fill_price`
+- `reprice_count`, `cancel_count`
+- `expected_execution_bps` (z DLOB w chwili decyzji) vs `realized_execution_bps`
+- “churn cost”: `tx_count` i (jeśli liczymy) `priority_fee` sumarycznie
+
+Okno strojenia:
+- 24h (szybki smoke po deployu),
+- 7 dni (tuning),
+- 30 dni (stabilizacja).
+
+### 8.3 Wynik i ryzyko (czy strategia ma edge)
+Mierz:
+- `hold_time_s`
+- reason exit: `tp|sl|time|regime|panic`
+- MAE/MFE w bps w trakcie hold
+- PnL (jeśli macie komplet danych) albo proxy w bps
+
+Okno:
+- 7 dni minimalnie, ale sensowniej 30+ dni (reżimy).
+
+---
+
+## 9) Następny krok implementacyjny (po akceptacji)
+
+1) Dodać tabele TS dla warstw (min. 7 dni retencji).
+2) Dodać tabele i logi kontraktów (`bot_contracts`, `bot_events`, opcjonalnie `bot_intents_ts`).
+3) Dodać “executor” (observe → dry-run → live) oraz integrację Vast.

doc/k3s-runtime-map.md

@@ -0,0 +1,165 @@
+# k3s runtime map (VPS `qstack`) — co działa i po co
+
+Ten dokument opisuje **aktualny runtime na VPS** (k3s) dla projektu `trade`: jakie komponenty działają w klastrze, jak płynie dane oraz które tabele/metrki są “źródłem prawdy” dla UI.
+
+Zakładamy namespace: `trade-staging`.
+
+## TL;DR (logika)
+
+- **Dane są zbierane i liczone na backendzie** (k3s).
+- UI (`trade-frontend`) **tylko wizualizuje** i proxy’uje ruch (API + GraphQL + WS).
+- Hasura to **jedyny GraphQL/WS** na “metrics/live” (subscriptions).
+- Postgres/Timescale trzyma:
+  - ticki (`drift_ticks`) + candles (funkcja `get_drift_candles`)
+  - “latest” warstw DLOB (`dlob_*_latest`)
+  - (opcjonalnie) historię warstw (`dlob_*_ts`)
+
+## Mapa (ruch z zewnątrz)
+
+```
+Internet
+  |
+  v
+Ingress/Traefik
+  |
+  +--> trade-frontend   (https://trade.mpabi.pl)
+  |       - /api        -> trade-api
+  |       - /graphql    -> hasura
+  |       - /graphql-ws -> hasura (WS subscriptions; protokół graphql-ws)
+  |
+  +--> (opcjonalnie inne ingressy w tym samym klastrze)
+```
+
+### `trade-frontend` (UI + reverse-proxy)
+
+- **Rola:** UI + proxy do usług w klastrze.
+- **Dlaczego:** przeglądarka nie dostaje sekretów; token read jest wstrzykiwany server‑side, a WS działa przez proxy.
+- **Wejście:** HTTP/WS od użytkownika.
+- **Wyjście:**
+  - `/api/*` → `trade-api`
+  - `/graphql` (HTTP) → `hasura`
+  - `/graphql-ws` (WS) → `hasura`
+
+## Mapa (dane rynkowe — ticki / candles)
+
+```
+Solana RPC/WS (zewn.)
+  |
+  v
+trade-ingestor
+  |
+  v
+trade-api  -> Postgres/Timescale (drift_ticks)
+  |
+  +--> /v1/chart (candles + wskaźniki liczone na backendzie)
+  |
+  v
+Hasura (GraphQL query/subscriptions dla wybranych tabel)
+```
+
+### `trade-ingestor`
+
+- **Rola:** pobiera dane (oracle/mark) i wysyła ticki do API.
+- **Wyjście:** ticki zapisane do `drift_ticks` przez `trade-api`.
+
+### `trade-api`
+
+- **Rola:** API dla UI i algów (healthz, ticks, chart).
+- **DB:** zapis do `drift_ticks`.
+- **Agregacje:** candles (`get_drift_candles`) + wskaźniki (backend).
+
+## Mapa (DLOB — orderbook + metryki warstw)
+
+```
+Solana RPC/WS (zewn.)
+  |
+  v
+dlob-publisher  ---->  dlob-redis  <----  dlob-server (/l2, /l3)
+                                \
+                                 \ (opcjonalne źródło L2)
+                                  v
+                            dlob-worker (kolektor L2)
+                                  |
+                                  v
+                         Postgres/Hasura: dlob_l2_latest + dlob_stats_latest
+                                  |
+                     +------------+------------+
+                     |                         |
+                     v                         v
+          dlob-depth-worker            dlob-slippage-worker
+          (bands ±bps)                (impact vs size USD)
+                     |                         |
+                     v                         v
+   Postgres/Hasura: dlob_depth_bps_latest   Postgres/Hasura: dlob_slippage_latest
+                     |
+                     v
+             (opcjonalnie) dlob-ts-archiver
+                     |
+                     v
+   Postgres/Timescale: dlob_stats_ts / dlob_depth_bps_ts / dlob_slippage_ts
+```
+
+### `dlob-publisher`
+
+- **Rola:** utrzymuje “żywy” DLOB (on‑chain) i publikuje snapshoty do Redis.
+- **Wejście:** Solana RPC/WS.
+- **Wyjście:** publikacja do `dlob-redis`.
+
+### `dlob-redis`
+
+- **Rola:** cache/pubsub pomiędzy publisherem i serwerem HTTP.
+
+### `dlob-server`
+
+- **Rola:** serwuje REST `/l2` i `/l3` na podstawie cache Redis (do debugowania i/lub jako źródło L2).
+
+### `dlob-worker` (kolektor L2 + “basic stats”)
+
+- **Rola:** pobiera snapshoty L2 i liczy podstawowe metryki (`dlob_stats_latest`).
+- **Źródło L2:** w praktyce:
+  - albo zewnętrzne `https://dlob.drift.trade/l2`
+  - albo wewnętrzne `http://dlob-server:6969/l2` (jeśli tak ustawione)
+- **Zapis do tabel:**
+  - `dlob_l2_latest` (raw L2)
+  - `dlob_stats_latest` (bid/ask/mid/spread/depth/imbalance)
+
+### `dlob-depth-worker` (depth bands ±bps)
+
+- **Rola:** liczy płynność w pasmach ±bps wokół mid.
+- **Źródło:** `dlob_l2_latest`
+- **Zapis:** `dlob_depth_bps_latest` (klucz: `market_name + band_bps`)
+
+### `dlob-slippage-worker` (slippage vs size)
+
+- **Rola:** symuluje market fill po L2 dla zadanych rozmiarów (USD) i liczy `impact_bps`.
+- **Źródło:** `dlob_l2_latest`
+- **Zapis:** `dlob_slippage_latest` (klucz: `market_name + side + size_usd`)
+
+### `dlob-ts-archiver` (historia warstw)
+
+- **Rola:** zapisuje “timeline” dla warstw do hypertabli Timescale (historia pod UI).
+- **Źródło:** `dlob_stats_latest`, `dlob_depth_bps_latest`, `dlob_slippage_latest`
+- **Zapis:** `dlob_stats_ts`, `dlob_depth_bps_ts`, `dlob_slippage_ts`
+- **Retencja (startowo):** ~7 dni (policy w Timescale).
+
+## Co UI realnie czyta (dla “nowych funkcji”)
+
+- live/subscriptions:
+  - `dlob_stats_latest`
+  - `dlob_depth_bps_latest`
+  - `dlob_slippage_latest`
+- (jeśli dołączymy w UI wykres “historia”):
+  - `dlob_stats_ts`
+  - `dlob_depth_bps_ts`
+  - `dlob_slippage_ts`
+
+## Najczęstsze miejsca problemów (diagnostyka)
+
+- Jeśli UI nie pokazuje warstw:
+  - sprawdź czy Hasura trackuje tabele i ma `public select` (bootstrap job),
+  - sprawdź, czy workery odświeżają `updated_at` w `dlob_*_latest`.
+- Jeśli `dlob-worker` loguje 503:
+  - to zwykle problem na ścieżce `DLOB_HTTP_URL` (upstream/LB/IPv6) — wtedy przełącz na `http://dlob-server:6969`.
+- Jeśli WS subscriptions nie łączą:
+  - sprawdź proxy `/graphql-ws` w `trade-frontend` i origin/CORS w Hasurze.
+

doc/rpc-dlob-kanoniczna-architektura.md

@@ -0,0 +1,115 @@
+# Kanoniczna architektura Drift: własny Solana RPC + własny DLOB
+
+Poniżej jest krótka i konkretna notatka: **co da się wyciągnąć z własnego Solana RPC** oraz **po co jest własny DLOB** w kontekście Drift (perp) i metryk pod trading/SIM.
+
+## 1) Własny Solana RPC — co z niego wyciągniesz
+
+Z **własnego RPC** (full node, a do backfillu najlepiej archival) możesz pobrać **wszystkie dane kontowe i ryzyko**.
+
+### Dane pozycji i konta (RPC)
+
+- pozycja (long/short, size, entry)
+- unrealized PnL
+- realized PnL (z konta użytkownika / fills)
+- margin, free collateral
+- liquidation price
+- health / margin ratio
+- funding (naliczony + historyczny)
+
+Źródło: **konta programu Drift** (User, PerpMarket, SpotMarket). Technicznie: subskrypcje kont + (jeśli potrzebne) `getProgramAccounts`.
+
+### Fills / transakcje / fees (RPC)
+
+- fill price
+- fee (maker/taker)
+- reduce / add
+- tx fee + priority fee
+
+Źródła:
+- logi transakcji,
+- eventy Drift,
+- historia transakcji walleta.
+
+Uwaga: backfill 7d+ jest ciężki bez archival RPC, ale nadal wykonalny (koszt/IO/limity).
+
+### Ceny (RPC)
+
+- oracle price
+- mark price (ze stanu rynku)
+
+W praktyce wystarczy RPC + subskrypcje kont.
+
+## 2) Własny DLOB — po co i co daje
+
+**DLOB jest off-chain**, ale jest budowany z **on-chain zleceń limit**.
+
+Co daje DLOB (i to jest kluczowe do “close now” i slippage):
+- best bid / best ask (BBO)
+- mid price
+- spread
+- realistyczny slippage
+- sensowne “close now cost” (na podstawie top-of-book / L2)
+
+Bez DLOB zwykle zostaje heurystyka na mark/oracle + założony spread/slippage.
+
+### Jak to zrobić praktycznie
+
+Najprostsza opcja to uruchomienie serwisu DLOB (publisher/server) z Drift SDK, który:
+- subskrybuje RPC/WS,
+- buduje orderbook,
+- wystawia API (BBO/depth itp.),
+- a worker liczy metryki (spread/depth/slippage) i zapisuje je do DB.
+
+W tym repo mamy opis aktualnego pipeline DLOB w `doc/dlob-services.md` oraz plan “RPC + Geyser/Yellowstone” w `doc/solana-rpc-geyser-setup.md`.
+
+## 3) Mapowanie: metryki → źródło danych
+
+| Metryka | RPC | DLOB |
+| --- | --- | --- |
+| unrealized PnL | ✅ | ❌ |
+| realized / net PnL | ✅ | ❌ |
+| fees / funding / tx | ✅ | ❌ |
+| margin / liq / health | ✅ | ❌ |
+| time in trade | ✅ | ❌ |
+| best bid / ask | ❌ | ✅ |
+| spread / mid | ❌ | ✅ |
+| close now cost | ⚠️ heurystyka | ✅ |
+| expected slippage | ⚠️ | ✅ |
+
+## 4) 100% self-hosted (bez vendor lock‑in)
+
+Da się zrobić w pełni self-hosted (bez Heliusa/cudzych API).
+
+Prosty diagram:
+
+```
+[ Solana RPC (+ WS) ]
+        ↓
+[ Drift SDK / subscriptions ]
+        ↓
+[ DLOB (publisher/server) ]
+        ↓
+[ Worker (metrics TS) ]
+        ↓
+[ API / Monitor / SIM ]
+        ↓
+[ UI (tylko rysuje) ]
+```
+
+## 5) Jedyny realny haczyk (operacyjnie)
+
+- `getProgramAccounts` + websockety wymagają solidnego RPC.
+- Tanie/limtowane RPC często:
+  - blokują/limitują GPA,
+  - ucinają payload,
+  - dropią WS.
+
+Własny RPC = stabilność i przewidywalność na większej skali.
+
+## 6) TL;DR
+
+- Tak: wyciągniesz wszystko z własnego RPC + własnego DLOB.
+- RPC = pozycja, PnL, ryzyko, funding.
+- DLOB = bid/ask, spread, slippage, close-now.
+- To pasuje idealnie pod scalping + SIM (backend liczy, UI tylko wyświetla).
+

doc/rpc/topol.html

@@ -0,0 +1,211 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Professional Drift Trading Stack (Own Solana RPC + Own DLOB)</title>
+  <style>
+    :root { color-scheme: light dark; }
+    body {
+      font-family: system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif;
+      line-height: 1.5;
+      margin: 0;
+      padding: 32px 20px;
+      max-width: 980px;
+      margin-inline: auto;
+    }
+    header { margin-bottom: 24px; }
+    h1 { font-size: 1.6rem; margin: 0 0 8px; }
+    .subtitle { opacity: 0.85; margin: 0; }
+    .card {
+      border: 1px solid rgba(127,127,127,0.35);
+      border-radius: 14px;
+      padding: 18px 18px;
+      margin: 14px 0;
+      background: rgba(127,127,127,0.05);
+    }
+    h2 { font-size: 1.2rem; margin: 0 0 10px; }
+    h3 { font-size: 1.05rem; margin: 14px 0 8px; }
+    ul { margin: 8px 0 0 18px; }
+    li { margin: 6px 0; }
+    code, pre { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+    .note {
+      border-left: 4px solid rgba(127,127,127,0.55);
+      padding: 10px 12px;
+      margin: 10px 0 0;
+      background: rgba(127,127,127,0.07);
+      border-radius: 10px;
+    }
+    .pill {
+      display: inline-block;
+      padding: 2px 10px;
+      border: 1px solid rgba(127,127,127,0.35);
+      border-radius: 999px;
+      font-size: 0.85rem;
+      opacity: 0.9;
+    }
+  </style>
+</head>
+
+<body>
+  <header>
+    <h1>Professional Drift Trading Stack</h1>
+    <p class="subtitle">
+      Own Solana RPC + Own Drift DLOB (Orderbook). Main rule:
+      <strong>keep the RPC box lean</strong>, put “trading services” on your second VPS.
+      <span class="pill">Target: min 10 markets</span>
+    </p>
+  </header>
+
+  <section class="card">
+    <h2>Overview</h2>
+    <p>
+      Yes — you can build a professional Drift trading stack with your own Solana RPC + your own DLOB,
+      but you’ll want a few supporting services around them. The main rule:
+      keep the RPC box lean, put “trading services” on your second VPS.
+    </p>
+  </section>
+
+  <section class="card">
+    <h2>On the Solana RPC server (dedicated) — keep it lean</h2>
+
+    <h3>Must-have</h3>
+    <ul>
+      <li>
+        <strong>Solana validator/RPC node</strong><br />
+        The base RPC your whole stack reads from / sends transactions through.
+      </li>
+      <li>
+        <strong>WireGuard</strong><br />
+        So RPC is reachable only privately (your second VPS + your admin).
+      </li>
+      <li>
+        <strong>Firewall (nftables/ufw)</strong><br />
+        Block RPC ports on public NIC; allow them only on WireGuard.
+      </li>
+      <li>
+        <strong>Time sync (chrony)</strong><br />
+        For stable networking, logs, and trading timestamps.
+      </li>
+      <li>
+        <strong>Monitoring exporters</strong>
+        <ul>
+          <li><strong>node_exporter</strong> (CPU/RAM/disk/iowait/network)</li>
+          <li><strong>solana-exporter</strong> (RPC/validator health via RPC)</li>
+        </ul>
+      </li>
+      <li>
+        <strong>Log + disk hygiene</strong>
+        <ul>
+          <li>logrotate/journald limits</li>
+          <li>NVMe health (smartmontools/nvme-cli)</li>
+          <li>alerts on disk filling / iowait</li>
+        </ul>
+      </li>
+    </ul>
+
+    <h3>Optional but “pro”</h3>
+    <ul>
+      <li>
+        <strong>Geyser streaming (Yellowstone gRPC plugin)</strong><br />
+        This gives ultra-low-latency streams of accounts/tx/slots compared to polling RPC.
+        Useful if you build your own real-time analytics pipeline.
+        <div class="note">
+          For Drift specifically, you can run without Geyser at the beginning,
+          but it’s the next step when you want “faster-than-RPC” feeds.
+        </div>
+      </li>
+    </ul>
+  </section>
+
+  <section class="card">
+    <h2>On the second VPS (your trading / app box) — where “pro trading” lives</h2>
+
+    <h3>Must-have</h3>
+    <ul>
+      <li>
+        <strong>Drift DLOB server (self-hosted)</strong><br />
+        This maintains the Drift decentralized orderbook view “fresh off your RPC” and exposes
+        REST + WS + gRPC/polling, plus health/metrics.
+      </li>
+      <li>
+        <strong>(Optional but common) Drift Gateway</strong><br />
+        A self-hosted API gateway to interact with Drift; handy for standardized API endpoints
+        around trading / market info.
+      </li>
+      <li>
+        <strong>Cache (Redis)</strong><br />
+        Cache top-of-book, funding, oracle snapshots, risk checks; protects your DLOB + RPC
+        from bursty bot load.
+      </li>
+      <li>
+        <strong>Metrics + dashboards</strong><br />
+        Prometheus + Grafana + Alertmanager
+        <div class="note">
+          Keep Grafana off the validator box; common ops guidance is to separate monitoring UI for safety.
+        </div>
+      </li>
+      <li>
+        <strong>Your trading services</strong>
+        <ul>
+          <li>strategy engine(s)</li>
+          <li>execution service (transaction builder/sender)</li>
+          <li>risk service (position limits, kill-switch, circuit breakers)</li>
+        </ul>
+      </li>
+    </ul>
+
+    <h3>Optional, depending on how “institutional” you want</h3>
+    <ul>
+      <li>
+        <strong>Database (Postgres/Timescale)</strong><br />
+        Persist fills, order events, PnL series, backtesting datasets.
+      </li>
+      <li>
+        <strong>Message bus (NATS/Kafka/Redis Streams)</strong><br />
+        Decouple ingestion (orderbook/events) from strategies/execution.
+      </li>
+    </ul>
+  </section>
+
+  <section class="card">
+    <h2>Cost model (since you asked “cost per request”)</h2>
+    <p>
+      With your own RPC, there is no per-request billing. The “cost” is:
+    </p>
+    <ul>
+      <li>fixed monthly servers (your €149/m + the second VPS),</li>
+      <li>and capacity (CPU/RAM/NVMe/bandwidth) consumed by:
+        <ul>
+          <li>DLOB syncing from RPC,</li>
+          <li>number of WS subscriptions,</li>
+          <li>how many markets you track.</li>
+        </ul>
+      </li>
+    </ul>
+    <p class="note">
+      DLOB exists specifically to reduce RPC load by serving orderbook/trade views to clients
+      instead of every client rebuilding it from chain.
+    </p>
+  </section>
+
+  <section class="card">
+    <h2>Minimal “pro” starting set (recommended)</h2>
+    <ul>
+      <li><strong>RPC box:</strong> Solana RPC + WireGuard + firewall + node_exporter + solana-exporter</li>
+      <li><strong>App VPS:</strong> DLOB server + Redis + Prometheus/Grafana + your bot services</li>
+    </ul>
+    <p class="note">
+      For <strong>min 10 markets</strong>, expect the first scaling pressure to come from
+      continuous streaming + decoding + caching (DLOB + Redis + your strategy/execution),
+      and from your RPC’s WS load. Next step after the minimal set is usually:
+      better streaming (Geyser) or more RAM/NVMe depending on bottleneck.
+    </p>
+  </section>
+
+  <footer style="opacity:.75; margin-top: 22px;">
+    <small>Saved as HTML — you can paste this into a file like <code>drift-stack.html</code>.</small>
+  </footer>
+</body>
+</html>
+

doc/solana-rpc-geyser-setup.md

@@ -0,0 +1,284 @@
+# Bare metal: Solana RPC (non‑voting) + Geyser/“Yellowstone” gRPC (Ubuntu 24.04)
+
+Cel: postawić **jedną maszynę** jako **źródło danych on‑chain**:
+- Solana `validator` w trybie **non‑voting** z **RPC + WS** (tylko prywatnie),
+- **Geyser gRPC** (“Yellowstone”) jako stabilny, skalowalny feed account/tx/slot,
+- serwisy tradingowe (DLOB/boty/DB/UI) działają **osobno** na VPS/k3s.
+
+Ten dokument jest runbookiem. Nie zawiera sekretów.
+
+---
+
+## Powiązane dokumenty (DLOB + metryki + koszty)
+
+Żeby spiąć “RPC/Geyser → dane → metryki → UI”, zobacz też:
+
+- Mapa dokumentów o RPC/DLOB/metrykach: `doc/solana-rpc.md`
+- DLOB (co działa w k3s, jakie tabele, skąd dane): `doc/dlob-services.md`
+- DLOB basics (L1/L2/L3, pojęcia): `doc/dlob-basics.md`
+- Ingest ticków / candles / źródła danych: `doc/workflow-api-ingest.md`
+- Readiness do live tradingu (w tym plan pod własny RPC + streaming): `doc/trading-readiness.md`
+- Czy da się bez własnego RPC / bez RPC w ogóle (mapowanie źródeł danych): `doc/drift-data-bez-solana-rpc.md`
+- Kanoniczna architektura “własny RPC + własny DLOB” (co skąd bierzemy): `doc/rpc-dlob-kanoniczna-architektura.md`
+- Koszty kontraktu: API compute/monitor (backend liczy, UI tylko rysuje): `doc/contract-cost-api.md`
+- Kanoniczny payload eventów bota pod koszty/PnL (żeby agregacje działały): `doc/bot-events-cost-payload.md`
+
+## 0) Założenia
+
+- OS: **Ubuntu 24.04**
+- Sprzęt: **Ryzen 9 9950X, 192GB RAM, 2× Gen5 NVMe, 1Gbps**
+- Rola: **RPC node bez voting** (brak vote account)
+- Prywatny dostęp: **WireGuard** między bare metal a k3s/VPS
+
+---
+
+## 1) Dlaczego RPC+WS i gRPC jednocześnie
+
+- **RPC/WS** (HTTP + WebSocket) zostaje jako:
+  - wysyłka transakcji (place/cancel/close),
+  - odczyty ad‑hoc i fallback.
+- **Geyser/Yellowstone gRPC** jest preferowany jako:
+  - stabilny stream updates (account/slot/tx) dla DLOB/indexerów,
+  - mniejsze “rwanie” niż WS przy większej skali.
+
+W praktyce: data plane = gRPC, execution plane = RPC.
+
+---
+
+## 2) Podział dysków (must‑have)
+
+Rekomendacja (żeby uniknąć I/O contention):
+- NVMe #1: ledger / accounts
+  - mount: `/solana/ledger`
+- NVMe #2: snapshots / logs / plugin state
+  - mount: `/solana/snapshots`
+  - ewentualnie: `/var/lib/yellowstone`
+
+---
+
+## 3) Porty (proponowane)
+
+Publicznie:
+- `22/tcp` (SSH) – tylko z Twoich IP (allowlist)
+
+Tylko po WireGuard (private):
+- `8899/tcp` RPC HTTP
+- `8900/tcp` RPC WS
+- `10000/tcp` Geyser gRPC (Yellowstone)
+
+Uwaga: dokładne porty Solany (gossip/TPU) są inne i zależą od flag; one zwykle muszą być publicznie osiągalne do sieci Solany, ale **RPC ma być private**.
+
+---
+
+## 4) WireGuard (skeleton)
+
+Założenie: bare metal = `wg0 = 10.8.0.1`, k3s/VPS = `wg0 = 10.8.0.2`.
+
+### 4.1 Bare metal: `/etc/wireguard/wg0.conf`
+
+```ini
+[Interface]
+Address = 10.8.0.1/24
+ListenPort = 51820
+PrivateKey = <BARE_METAL_PRIVATE_KEY>
+
+# opcjonalnie: NAT dla ruchu wychodzącego
+# PostUp = iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
+# PostDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE
+
+[Peer]
+PublicKey = <K3S_PUBLIC_KEY>
+AllowedIPs = 10.8.0.2/32
+```
+
+### 4.2 VPS/k3s: `/etc/wireguard/wg0.conf`
+
+```ini
+[Interface]
+Address = 10.8.0.2/24
+PrivateKey = <K3S_PRIVATE_KEY>
+
+[Peer]
+PublicKey = <BARE_METAL_PUBLIC_KEY>
+Endpoint = <BARE_METAL_PUBLIC_IP>:51820
+AllowedIPs = 10.8.0.1/32
+PersistentKeepalive = 25
+```
+
+Start:
+
+```bash
+sudo systemctl enable --now wg-quick@wg0
+```
+
+Test:
+
+```bash
+ping -c 2 10.8.0.1
+```
+
+---
+
+## 5) Firewall: zasada “RPC i gRPC tylko private”
+
+Wariant z `ufw` (przykład, dopasuj do swojego środowiska):
+
+```bash
+sudo ufw default deny incoming
+sudo ufw default allow outgoing
+
+# SSH – najlepiej allowlist Twoje IP
+sudo ufw allow 22/tcp
+
+# WireGuard
+sudo ufw allow 51820/udp
+
+# RPC/WS/gRPC tylko na interfejsie wg0 (ufw ma ograniczone wsparcie; alternatywnie nftables)
+# Minimalnie: nie otwieraj 8899/8900/10000 na publicznym NIC.
+
+sudo ufw enable
+sudo ufw status verbose
+```
+
+---
+
+## 6) Instalacja i uruchomienie Solany (non‑voting)
+
+### 6.1 Zasada bezpieczeństwa
+- identity key i konfiguracja tylko na serwerze,
+- nie commituj tego do gita,
+- RPC ma być “private RPC”.
+
+### 6.2 Flagi mogą się zmieniać
+Solana bywa zmienna w detalach CLI. Zawsze weryfikuj:
+
+```bash
+solana-validator --help | less
+```
+
+### 6.3 Minimalny szkic uruchomienia (do uzupełnienia)
+
+Poniżej jest “kształt” – nie traktuj jako jedyny prawdziwy set flag:
+
+```bash
+solana-validator \
+  --identity /etc/solana/identity.json \
+  --ledger /solana/ledger \
+  --snapshots /solana/snapshots \
+  --rpc-port 8899 \
+  --rpc-bind-address 10.8.0.1 \
+  --private-rpc \
+  --ws-port 8900 \
+  --dynamic-port-range 8000-8020 \
+  --no-voting \
+  --entrypoint <ENTRYPOINT_1> \
+  --entrypoint <ENTRYPOINT_2> \
+  --entrypoint <ENTRYPOINT_3> \
+  --expected-genesis-hash <GENESIS_HASH> \
+  --wal-recovery-mode skip_any_corrupted_record
+```
+
+Uwagi:
+- `--rpc-bind-address` ustaw na IP WireGuard (private).
+- `--no-voting` = non‑voting.
+- `--dynamic-port-range` i reszta portów zależą od Twojej polityki sieciowej.
+
+### 6.4 systemd (skeleton)
+
+Plik: `/etc/systemd/system/solana-validator.service`
+
+```ini
+[Unit]
+Description=Solana Validator (non-voting, private RPC)
+After=network-online.target wg-quick@wg0.service
+Wants=network-online.target
+
+[Service]
+User=solana
+Group=solana
+LimitNOFILE=1048576
+ExecStart=/usr/local/bin/solana-validator <ARGS...>
+Restart=always
+RestartSec=3
+TimeoutStopSec=120
+
+[Install]
+WantedBy=multi-user.target
+```
+
+---
+
+## 7) Geyser / “Yellowstone” gRPC
+
+### 7.1 Co to jest
+Geyser to plugin, który “wypycha” stream danych z runtime’u walidatora.
+Yellowstone gRPC to popularny stack, który wystawia ten stream przez gRPC.
+
+### 7.2 Model wdrożenia (recommended)
+- plugin jest skonfigurowany przy starcie `solana-validator` (`--geyser-plugin-config <path>`),
+- gRPC endpoint nasłuchuje na `10.8.0.1:10000` (private),
+- klienci (k3s) subskrybują gRPC.
+
+### 7.3 Konfiguracja pluginu (placeholder)
+Dokładny format config zależy od wybranego pluginu/wersji.
+Trzymaj config jako plik na serwerze, np. `/etc/solana/geyser-grpc.json`.
+
+Wymagania, które chcemy mieć niezależnie od implementacji:
+- bind na interfejsie WireGuard (`10.8.0.1`),
+- opcjonalny auth/token dla klientów,
+- limit/allowlist klientów,
+- logi do journald + limitowanie.
+
+Test (z VPS/k3s po WireGuard):
+- port open: `nc -vz 10.8.0.1 10000` (albo `grpcurl` jeśli masz),
+- stream slotów/health (zależy od klienta).
+
+---
+
+## 8) Integracja z naszym stackiem `trade`
+
+### 8.1 Co zmieniamy w k3s
+
+Aktualizujemy secreta z endpointami RPC/WS dla `dlob-publisher` i executora:
+- `ENDPOINT=http://10.8.0.1:8899`
+- `WS_ENDPOINT=ws://10.8.0.1:8900`
+
+Docelowo dodamy również:
+- `GEYSER_GRPC_URL=http://10.8.0.1:10000` (lub `grpc://...`) do collectorów.
+
+### 8.2 Fallback
+Zostawiamy fallback RPC endpoint (np. publiczny provider) dla:
+- awarii bare-metala,
+- bootstrapu,
+- sanity check.
+
+Executor ma zawsze mieć tryb degradacji:
+- Vast down → `observe/off`,
+- feed down → `panic` lub `off` zależnie od ryzyka.
+
+---
+
+## 9) Operacje i monitoring (must‑have)
+
+Mierz/alertuj:
+- slot lag / “behind”,
+- iowait + saturacja NVMe,
+- disk fill (`ledger` rośnie),
+- restart loop serwisów,
+- liczba klientów gRPC / błędy streamu,
+- RPC latencja / error rate.
+
+Minimalne narzędzia:
+- `node_exporter` + Prometheus/Grafana,
+- logrotate/journald limity,
+- `smartctl`/`nvme smart-log` dla NVMe.
+
+---
+
+## 10) Gotowość do startu (checklista)
+
+- [ ] WireGuard działa (ping wg IP).
+- [ ] RPC/WS/gRPC są dostępne tylko po WG.
+- [ ] `solana-validator` trzyma sync, nie robi OOM, I/O stabilne.
+- [ ] Geyser gRPC stream stabilny (brak częstych reconnect).
+- [ ] `dlob-publisher` działa na nowych endpointach bez “No ws data … resubscribing”.

doc/solana-rpc.md

@@ -0,0 +1,20 @@
+# Solana RPC w tym projekcie (mapa dokumentów)
+
+Ten plik jest “spisem treści” do dokumentów o **Solana RPC/WS**, **Geyser/Yellowstone gRPC** oraz tego, jak te źródła danych zasilają **DLOB + metryki + UI**.
+
+## Runbooki i architektura
+
+- Bare metal RPC (non‑voting) + Geyser/Yellowstone gRPC: `doc/solana-rpc-geyser-setup.md`
+- “Kanoniczna” architektura self‑hosted (RPC + DLOB → DB/Hasura → API → UI): `doc/rpc-dlob-kanoniczna-architektura.md`
+- Czy da się bez własnego RPC / bez RPC w ogóle (mapowanie źródeł danych): `doc/drift-data-bez-solana-rpc.md`
+
+## DLOB i warstwy danych
+
+- Serwisy DLOB w k3s/VPS + przepływ danych: `doc/dlob-services.md`
+- Pojęcia i metryki DLOB (L1/L2/L3, bps, slippage): `doc/dlob-basics.md`
+
+## Metryki i koszty kontraktów (backend liczy, UI rysuje)
+
+- API do liczenia kosztów “new contract” + monitor kontraktu: `doc/contract-cost-api.md`
+- Słownik kosztów, PnL i pojęć (UI + backend): `doc/drift-costs.md`
+

doc/strategy-eskalacja-horyzontu.md

@@ -0,0 +1,111 @@
+# Strategia: eskalacja horyzontu (1m → 5m → 15m → 30m → 1h) z bramkami ryzyka i kosztów
+
+Cel: jeżeli trade nie domyka celu w krótkim oknie (np. **1m**), możemy **kontrolowanie** przejść na dłuższy horyzont (**5m/15m/30m/1h**) *bez wpadania w “przetrzymanie straty”*.
+
+Klucz: to ma działać jako **state machine** z twardymi bramkami (gates), a nie jako “zostawię i zobaczę”.
+
+---
+
+## 1) Model: “czas na realizację celu” + eskalacja okna
+
+### Parametry (na start)
+- `target_bps` albo `target_usd` (np. +3 bps, +6 bps…)
+- `ttl_per_mode` (time-to-live per tryb):
+  - `1m`: 60–120 s
+  - `5m`: 5–10 min
+  - `15m`: 15–30 min
+  - `30m`: 30–60 min
+  - `1h`: 1–3 h
+
+### Zasada
+Jeśli w danym trybie **nie osiągniesz celu w TTL**, to:
+- albo **zamykanie**,
+- albo **eskalacja** do wyższego okna — *tylko* jeśli spełnione są bramki (ryzyko/koszty/struktura).
+
+---
+
+## 2) Bramki (gates) — kiedy eskalacja jest dozwolona
+
+### Gate RISK (twarde)
+Jeśli którykolwiek warunek jest niespełniony → **wyjście teraz** (close now).
+
+Przykładowe progi:
+- `health >= 0.70`
+- `margin_ratio >= 0.15..0.20` (zależnie od dźwigni)
+- odległość do `liq_price` >= `X%` albo >= `k * ATR`
+- `max_drawdown` w oknie bieżącym nie przekracza limitu
+
+### Gate COSTS (twarde)
+- `close_now_cost_usd` nie “zjada” potencjału (np. koszty nie mogą przekroczyć `target_usd` albo `target_bps`)
+- przy dłuższych trybach (30m/1h) uwzględnij wpływ funding:
+  - `funding_expected(next_window)` nie dominuje nad edge
+
+### Gate STRUCTURE / EDGE (miękkie, ale zalecane)
+Przykłady:
+- trend/edge na wyższym oknie nie jest przeciw (np. 5m dla eskalacji 1m→5m)
+- spread/slippage z DLOB nie rosną anormalnie
+
+---
+
+## 3) Logika przejść (state machine)
+
+Stan początkowy: `mode=1m`.
+
+Jeżeli `ttl_expired` i `target_not_hit`:
+- jeśli `risk_ok && costs_ok && structure_ok` → awans do następnego trybu,
+- inaczej → `close_now`.
+
+Przejścia:
+- `1m` → `5m`
+- `5m` → `15m`
+- `15m` → `30m`
+- `30m` → `1h`
+
+Ważne: awans = **zmiana reżimu** (inne TTL/target/gates), a nie “przeciąganie”.
+
+---
+
+## 4) Pułapka i dwa “hamulce”
+
+Pułapka:
+> “nie poszło w 1m, to poczekam 5m, jak nie to 15m…” → swing bez planu
+
+### Hamulec A: limit eskalacji
+- max 1–2 awanse na trade (np. `1m→5m→15m` i koniec)
+
+### Hamulec B: limit straty per tryb
+- jeśli w trybie 1m strata przekroczy `stop_1m` → wyjście
+- nie wolno “przenosić” tej samej straty w nieskończoność do 1h
+
+---
+
+## 5) Jak to zaszyć w naszym backendzie (worker + API)
+
+W `contract_metrics_ts` (lub w warstwie kontraktu) trzymaj:
+- `mode_current`
+- `mode_enter_ts`
+- `ttl_s_for_mode`
+- `target_bps_for_mode`
+- `gates_passed`:
+  - `risk: boolean`
+  - `costs: boolean`
+  - `structure: boolean`
+- (opcjonalnie) `escalations_used` / `escalations_remaining`
+
+### SIM: “czy eskalacja ma sens”
+Endpoint typu `POST /v1/simulate/escalate` (MVP) może zwracać:
+- `expected_costs` (close now / next window)
+- `risk_after` (health/margin/liq)
+- `assumptions` (np. BBO+extra bps, fee tier)
+
+---
+
+## 6) TL;DR
+
+- Tak, eskalacja czasu ma sens **jeśli jest kontrolowana**.
+- Robimy to jako **state machine** z:
+  - twardym `RISK gate`,
+  - twardym `COST gate`,
+  - limitem eskalacji,
+  - stopem per tryb.
+

doc/todo-before-baremetal.md

@@ -0,0 +1,94 @@
+# TODO przed zakupem bare metal (RPC+Geyser) — żeby dzień 0 poszedł gładko
+
+Cel: zanim kupisz bare metal, dopinamy wszystko, co nie wymaga własnego RPC, żeby po zakupie:
+- tylko postawić RPC+Geyser wg runbooka,
+- przepiąć endpointy w k3s i zrobić rollout,
+- zweryfikować stabilność feedu i gotowość do live.
+
+---
+
+## A) Decyzje i parametry (bez kodu, ale blokują implementację)
+
+- [ ] **Docelowe porty i adresacja WireGuard**:
+  - WG subnet (np. `10.8.0.0/24`), IP bare metal i IP k3s/VPS
+  - port WG (np. `51820/udp`)
+  - private bind dla: RPC `8899`, WS `8900`, gRPC `10000`
+- [ ] **Polityka dostępu**:
+  - allowlist IP do SSH
+  - czy gRPC wymaga auth/token dla klientów
+- [ ] **Retencja danych (start)**:
+  - TS: 7 dni “gęsto” (np. 1–5s) + czy robimy downsample 1m na dłużej
+- [ ] **Model intent**:
+  - potwierdzone: offset (ticks/bps) + desired-state (jest w `doc/drift-perp-contract.md`)
+- [ ] **Ryzyko (hard caps)**:
+  - max position USD, max reprices/min, max slippage/spread, freshness
+
+---
+
+## B) Dane i historia (żeby warstwy działały live+history)
+
+- [ ] **DLOB TS tables**: `dlob_stats_ts`, `dlob_depth_bps_ts`, `dlob_slippage_ts`
+  - indeksy `(market_name, ts)` i retencja 7 dni
+- [ ] **Archiver/collector**:
+  - worker, który zapisuje TS (z `*_latest` do `*_ts`), albo rozszerzenie istniejących workerów
+- [ ] **Downsample (opcjonalnie, ale pro)**:
+  - continuous aggregates (Timescale) lub job 1m/5m
+- [ ] **Hasura bootstrap**:
+  - track tabel TS + uprawnienia `select` (public) dla UI history
+
+---
+
+## C) Kontrakty bota i audyt (must-have przed live)
+
+- [ ] **Schema**:
+  - `bot_contracts` (desired-state + status)
+  - `bot_events` (audit log)
+  - mapowanie: `decision_id`, `client_order_id`, `drift_order_id`, `tx_sig`
+- [ ] **Observe-only executor** (k3s):
+  - buduje features i zapisuje `decision` do `bot_events`, bez składania tx
+- [ ] **Reconcile logic (no trade yet)**:
+  - start → odczyt observed state z Drift → porównanie do DB → log “diff”
+- [ ] **Kill-switch w executorze**:
+  - env var + DB flag + safety triggers (feed stale, RPC lag)
+
+---
+
+## D) Vast (GPU tylko na kilka godzin) — przygotowanie pod ephemeral training
+
+- [ ] **Dataset export** (z k3s/DB):
+  - jeden plik `parquet/jsonl.zst` + `dataset_version` (hash)
+  - minimalny “train split / eval split”
+- [ ] **Training entrypoint** (jedna komenda):
+  - skrypt/komenda, która: download dataset → train → eval → export
+- [ ] **Artifact upload**:
+  - preferowane: scp na VPS/k3s albo Gitea Packages
+  - wersjonowanie: `model_version` + `dataset_version`
+- [ ] **Predictor contract test**:
+  - walidator JSON schema `trade_intent`
+  - test: “intent TTL expired” + “gates fail” + “panic”
+
+---
+
+## E) UI (warstwy + live/history, bez liczenia w JS)
+
+- [ ] **Tryb Live/History**:
+  - Live: subscriptions na `*_latest`
+  - History: query na `*_ts` + timeframe `tf`
+- [ ] **Warstwy/Panele z `doc/stats.md`**:
+  - mapowanie 1:1 na tabele (brak obliczeń w UI)
+- [ ] **Podgląd kontraktów**:
+  - panel “Contracts” z `bot_contracts` + “Event timeline” z `bot_events`
+
+---
+
+## F) Operacje (żeby bare metal nie stał się snowflake)
+
+- [ ] **Sekrety i endpointy**:
+  - w k3s: secret `trade-dlob-rpc` / analogiczny na nowy endpoint (WG)
+  - fallback endpoint (np. public provider) jako opcjonalny drugi URL
+- [ ] **Monitoring/alerty na k3s**:
+  - freshness DLOB/ticks, error rate workerów, restart loops
+- [ ] **Checklist “Day 0”**:
+  - przejście krok po kroku wg `doc/solana-rpc-geyser-setup.md`
+  - smoke test: `dlob-publisher` bez reconnect storm
+

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).

doc/vast-gpu-runbook.md

@@ -0,0 +1,123 @@
+# Vast GPU (kilka godzin) — runbook do trenowania + eksportu modelu
+
+Cel: używać Vast (GPU) jako **krótkiej sesji treningowej** (kilka godzin), a wynik (wagi/adapter) zapisać trwałe i wersjonowane.
+
+W tym projekcie Vast:
+- **nie dostaje sekretów tradingowych**,
+- nie ma dostępu do kluczy,
+- zwraca tylko `trade_intent`/predykcje.
+
+---
+
+## 1) Najważniejsza zasada przy krótkim wynajmie
+
+Vast jest “ephemeral”. Żeby nie stracić pracy:
+
+- wszystko musi być **reproducible** (konfig + kod + seed),
+- model output musi być **mały** i łatwy do przeniesienia (preferuj LoRA/adaptery),
+- checkpointy i final artifacts muszą być **uploadowane** poza maszynę (Gitea packages/S3/scp).
+
+---
+
+## 2) Co potrzebujemy mieć gotowe przed startem sesji
+
+### 2.1 Kod i entrypoint
+
+W repo powinien istnieć “one command training”, np.:
+- `python -m train ...` albo `bash scripts/train.sh ...`
+
+Zasada: komenda sama:
+- pobiera dataset (albo czyta lokalny plik),
+- trenuje,
+- zapisuje `artifacts/`,
+- robi upload.
+
+### 2.2 Dataset (krótki transfer)
+
+Dla sesji “kilka godzin” unikaj wielkich transferów.
+
+Rekomendacja:
+- zbuduj dataset jako plik (np. `jsonl`/`parquet`) i spakuj (`zstd`),
+- trzymaj wersję datasetu (hash) i loguj ją do metryk.
+
+Źródło danych (rekomendowane u nas):
+- `Postgres/Timescale` w k3s → eksport do pliku (offline), potem upload.
+
+### 2.3 Bazowy model
+
+Masz 2 ścieżki:
+- pobierasz z internetu (HF) na Vast (szybko, ale zależy od sieci),
+- albo trzymasz bazę w swoim storage i ściągasz kontrolowanie.
+
+Na start preferuj LoRA na umiarkowanym modelu i krótkiej sekwencji.
+
+---
+
+## 3) Co uruchamiamy na Vast
+
+### 3.1 Kontener
+
+Najprościej: jeden Docker image z zależnościami (PyTorch + libs).
+Obraz powinien być **pinned** (digest) i gotowy do uruchomienia bez `pip install` w trakcie.
+
+### 3.2 Konfiguracja treningu (config file)
+
+Trzymaj config jako plik (np. YAML/JSON) i loguj go do artifactów:
+- `model_name`, `model_version`
+- `dataset_version` (hash)
+- `seq_len`, `batch_size`, `grad_accum`, `lr`
+- `lora_r`, `lora_alpha`, `lora_dropout` (jeśli LoRA)
+- `seed`
+
+### 3.3 Output
+
+Preferowane outputy:
+- LoRA adapter (mały): `adapter.safetensors` + config
+- metryki treningu: `metrics.json`
+- walidacja: `eval_report.json`
+
+Opcjonalnie:
+- export do ONNX/TensorRT jeśli planujesz inference poza GPU (zależne od modelu).
+
+---
+
+## 4) Gdzie trzymamy artefakty (żeby nie zniknęły)
+
+Opcje (w kolejności prostoty):
+
+1) **scp na VPS/k3s** (na start najprostsze)
+2) **Gitea Packages** (jeśli chcesz wersjonować jako “package”)
+3) **S3/MinIO** (najbardziej skalowalne)
+
+Minimalne wymaganie: zawsze zapisuj `model_version` i `dataset_version` obok wag.
+
+---
+
+## 5) Jak to łączy się z executor / UI
+
+Model na Vast zwraca `trade_intent` (patrz `doc/drift-perp-contract.md`).
+Executor w k3s:
+- buduje features z DB,
+- woła predictor,
+- waliduje gates,
+- loguje:
+  - `decision_id`, `model_version`, `features_hash`, `intent`,
+  - outcome (fill/exit).
+
+Jeśli Vast jest niedostępny:
+- executor przechodzi w `observe/off` (nie handluje),
+- UI nadal pokazuje warstwy rynku (DLOB/ticki).
+
+---
+
+## 6) Checklist “kilka godzin” (operacyjnie)
+
+- [ ] Vast instance: GPU + wystarczająco VRAM + szybki disk.
+- [ ] Pull docker image (pinned).
+- [ ] Download dataset (jedna komenda).
+- [ ] Train (z logowaniem metryk co N kroków).
+- [ ] Eval (krótki).
+- [ ] Export adapter/weights.
+- [ ] Upload artifacts (scp / packages / S3).
+- [ ] Zapisz `model_version` do DB/config (k3s) przed użyciem.
+

doc/visualizer-layers-ui.md

@@ -0,0 +1,89 @@
+# Visualizer UI: kafelki → warstwy (stack)
+
+Ten dokument opisuje MVP dla przełączania układu UI w `apps/visualizer`:
+
+- **Grid (kafelki / standard)**: obecny layout aplikacji.
+- **Stack (warstwy / fullscreen)**: jedna aktywna warstwa jest na wierzchu (fullscreen), a kolejność warstw można ustawiać przez **DnD**.
+
+## Zachowanie (MVP)
+
+### Wejście / wyjście ze stack
+- **Chart**: przycisk `Fullscreen` w pasku narzędzi wykresu przełącza tryb `grid` ↔ `stack` (dla warstwy `chart`).
+- **DLOB**: przycisk `Fullscreen` w nagłówku DLOB przełącza tryb `grid` ↔ `stack` (dla warstwy `dlob`).
+- Wyjście ze stack:
+  - przycisk `Back` w panelu warstw
+  - klawisz `Esc` **dwa razy** (w ciągu ~0.8s)
+
+### Warstwy i DnD
+- W stack pojawia się panel `Layers` jako **wysuwany drawer z boku**.
+- Lista w panelu jest **od góry (top) do dołu (bottom)**:
+  - element na górze listy jest `active` (czyli jest “na wierzchu”).
+- **DnD** na liście:
+  - przeciągnij element i upuść na inny — zmienisz kolejność (top/bottom).
+- Kliknięcie elementu na liście przenosi go na wierzch (`active`).
+
+### Warstwy kosztów (Costs)
+- Są dwie osobne warstwy kosztów:
+  - `Costs (New)` — estymata nowego kontraktu (domyślnie **na samej górze**),
+  - `Costs (Active)` — monitoring puszczonego kontraktu (pojawia się i jest ustawiana **jeden poziom niżej** po wpisaniu `contract_id`).
+- Możesz zmienić kolejność DnD (to nadpisuje domyślne ustawienie).
+- Po pierwszym DnD aplikacja oznacza układ jako “manualny” i nie przestawia już automatycznie warstw przy pojawieniu się `contract_id`.
+
+### Auto-hide + lock
+- Domyślnie drawer ma **auto-hide** (chowa się po ~1s po zjechaniu kursorem z panelu).
+- Przycisk `Auto/Locked`:
+  - `Auto` = auto-hide włączony,
+  - `Locked` = auto-hide wyłączony (drawer zostaje otwarty).
+- Drawer otwiera się po najechaniu kursorem na wąski “hotspot” przy lewym brzegu ekranu.
+
+### Opacity (UI)
+- W drawerze są suwaki:
+  - `Backdrop` (przyciemnienie tła w stack)
+  - `Panel` (tło drawera)
+- Wartości są zapisywane w localStorage (`trade.stackBackdropOpacity`, `trade.stackDrawerOpacity`).
+
+### Opacity (warstwy)
+- Każda warstwa ma swój suwak opacity (0–100%):
+  - `0%` = warstwa niewidoczna,
+  - `100%` = pełna widoczność.
+- DnD nadal ustawia kolejność (z-index), a interakcje trafiają do warstwy `active` (top).
+- Wartości są zapisywane w localStorage (`trade.layerOpacity`).
+
+### Jasność (warstwy)
+- Każda warstwa ma suwak `brightness` (60–180%).
+- To jest filtr UI (nie wpływa na dane), przydatny gdy chcesz rozjaśnić wykres/DLOB w stack.
+- Wartości są zapisywane w localStorage (`trade.layerBrightness`).
+
+### Widoczność + lock (warstwy)
+- Ikona “oka” przełącza widoczność warstwy (nie resetuje suwaka opacity).
+- Ikona “kłódki” blokuje warstwę:
+  - nie da się jej przeciągać (DnD),
+  - suwak opacity jest wyłączony,
+  - klik w wiersz nie zmienia kolejności (nie “wypycha” na top).
+- Ustawienia są zapisywane w localStorage (`trade.layerVisible`, `trade.layerLocked`).
+
+## Implementacja (gdzie w kodzie)
+- Sterowanie układem i panel `Layers`: `apps/visualizer/src/App.tsx`
+  - `trade.layoutMode` w localStorage: `'grid' | 'stack'`
+  - `trade.stackOrder` w localStorage: kolejność warstw (z-index; ostatni = top)
+  - `trade.stackOrderManual` w localStorage: czy użytkownik zmienił kolejność przez DnD (blokuje auto-przestawianie)
+  - `trade.stackPanelLocked` w localStorage: blokada auto-hide panelu warstw
+  - `trade.contractId` w localStorage: aktywny kontrakt do monitoringu
+- Fullscreen chart przez warstwy: `apps/visualizer/src/features/chart/ChartPanel.tsx`
+  - `fullscreenOverride` + `onToggleFullscreenOverride` (fullscreen kontrolowany z zewnątrz, bez backdropu)
+- Fullscreen DLOB: `apps/visualizer/src/features/market/DlobDashboard.tsx`
+  - `isFullscreen` + `onToggleFullscreen` (przycisk w nagłówku)
+- Panel kosztów: `apps/visualizer/src/features/contracts/ContractCostsPanel.tsx`
+
+## Co dalej (kolejne iteracje)
+
+MVP nie robi jeszcze “prawdziwego” układu kafelków z:
+- drag/resize okien w trybie stack,
+- wyświetlaniem kilku warstw jednocześnie (np. jako nakładające się okna),
+- przełączaniem grid→stack przez zoom kafelka (z animacją).
+
+Proponowane następne kroki:
+1) wydzielić `Pane` abstraction (id, title, render, hotkeys),
+2) zrobić `grid` jako faktyczne kafelki (Chart, DLOB, Orderbook, TradeForm),
+3) dodać “zoom” kafelka → wejście do stack,
+4) dodać opcjonalnie drag/resize w stack (na start tylko z-index + focus).