154 lines
8.4 KiB
Markdown
154 lines
8.4 KiB
Markdown
# Serwisy DLOB na VPS (k3s / `trade-staging`)
|
||
|
||
Ten dokument opisuje rolę serwisów “DLOB” uruchomionych w namespace `trade-staging` oraz ich przepływ danych.
|
||
|
||
## Czy `dlob-worker` pracuje na VPS?
|
||
|
||
Tak — wszystkie serwisy wymienione niżej działają **na VPS** jako Deploymenty w klastrze k3s, w namespace `trade-staging`.
|
||
|
||
## Czy na VPS jest GraphQL/WS dla stats i orderbook?
|
||
|
||
Tak — **GraphQL wystawia Hasura** (na VPS w k3s), a nie `dlob-server`.
|
||
|
||
- Dane L2 i liczone statsy są zapisane do Postgresa jako tabele `dlob_*_latest` i są dostępne przez Hasurę jako GraphQL (query + subscriptions).
|
||
- Z zewnątrz korzystamy przez frontend (proxy) pod:
|
||
- HTTP: `https://trade.rv32i.pl/graphql`
|
||
- WS: `wss://trade.rv32i.pl/graphql` (subskrypcje, protokół `graphql-ws`)
|
||
|
||
`dlob-server` wystawia **REST** (np. `/l2`, `/l3`) w klastrze; to jest źródło danych dla workerów albo do debugowania.
|
||
|
||
## TL;DR: kto co robi
|
||
|
||
### `dlob-worker`
|
||
- **Rola:** kolektor L2 + wyliczenie “basic stats”.
|
||
- **Wejście:** HTTP L2 z `DLOB_HTTP_URL` (u nas obecnie `https://dlob.drift.trade`, ale można przełączyć na `http://dlob-server:6969`).
|
||
- **Wyjście:** upsert do Hasury (Postgres) tabel:
|
||
- `dlob_l2_latest` (raw snapshot L2, JSON leveli)
|
||
- `dlob_stats_latest` (pochodne: best bid/ask, mid, spread, depth, imbalance, itp.)
|
||
- **Częstotliwość:** `DLOB_POLL_MS` (u nas 500 ms).
|
||
|
||
### `dlob-slippage-worker`
|
||
- **Rola:** symulacja slippage vs rozmiar zlecenia na podstawie L2.
|
||
- **Wejście:** czyta z Hasury `dlob_l2_latest` (dla listy rynków).
|
||
- **Wyjście:** upsert do Hasury tabeli `dlob_slippage_latest` (m.in. `impact_bps`, `vwap_price`, `worst_price`, `fill_pct`).
|
||
- **Częstotliwość:** `DLOB_POLL_MS` (u nas 1000 ms); rozmiary w `DLOB_SLIPPAGE_SIZES_USD`.
|
||
|
||
### `dlob-depth-worker`
|
||
- **Rola:** metryki “głębokości” w pasmach ±bps wokół mid.
|
||
- **Wejście:** czyta z Hasury `dlob_l2_latest`.
|
||
- **Wyjście:** upsert do Hasury tabeli `dlob_depth_bps_latest` (per `(market_name, band_bps)`).
|
||
- **Częstotliwość:** `DLOB_POLL_MS` (u nas 1000 ms); pasma w `DLOB_DEPTH_BPS_BANDS`.
|
||
|
||
### `dlob-publisher`
|
||
- **Rola:** utrzymuje “żywy” DLOB na podstawie subskrypcji on-chain i publikuje snapshoty do Redis.
|
||
- **Wejście:** Solana RPC/WS (`ENDPOINT`, `WS_ENDPOINT` z secreta `trade-dlob-rpc`), Drift SDK; konfiguracja rynków np. `PERP_MARKETS_TO_LOAD`.
|
||
- **Wyjście:** zapis/publish do `dlob-redis` (cache / pubsub / streamy), z którego korzysta serwer HTTP (i ewentualnie WS manager).
|
||
|
||
### `dlob-server`
|
||
- **Rola:** HTTP API do danych DLOB (np. `/l2`, `/l3`) serwowane z cache Redis.
|
||
- **Wejście:** `dlob-redis` + slot subscriber (do oceny “świeżości” danych).
|
||
- **Wyjście:** endpoint HTTP w klastrze (Service `dlob-server:6969`), który może być źródłem dla `dlob-worker` (gdy `DLOB_HTTP_URL=http://dlob-server:6969`).
|
||
|
||
### `dlob-redis`
|
||
- **Rola:** Redis (u nas single-node “cluster mode”) jako **cache i kanał komunikacji** między `dlob-publisher` a `dlob-server`.
|
||
- **Uwagi:** to “klej” między komponentami publish/serve; bez niego publisher i server nie współpracują.
|
||
|
||
## Jak to się spina (przepływ danych)
|
||
|
||
1) `dlob-publisher` (on-chain) → publikuje snapshoty do `dlob-redis`.
|
||
2) `dlob-server` → serwuje `/l2` i `/l3` z `dlob-redis` (HTTP w klastrze).
|
||
3) `dlob-worker` → pobiera L2 (obecnie z `https://dlob.drift.trade`; opcjonalnie z `dlob-server`) i zapisuje “latest” do Hasury/DB.
|
||
4) `dlob-slippage-worker` + `dlob-depth-worker` → liczą agregaty z `dlob_l2_latest` i zapisują do Hasury/DB (pod UI).
|
||
|
||
## Co to jest L1 / L2 / L3 (orderbook)
|
||
|
||
- `L1` (top-of-book): tylko najlepszy bid i najlepszy ask (czasem też spread).
|
||
- `L2` (Level 2): **zagregowane poziomy cenowe** po stronie bid/ask — lista leveli `{ price, size }`, gdzie `size` to suma wolumenu na danej cenie (to jest typowy “orderbook UI” i baza pod spread/depth/imbalance).
|
||
- `L3` (Level 3): **niezagregowane, pojedyncze zlecenia** (każde osobno, zwykle z dodatkowymi polami/identyfikatorami). Większy wolumen danych; przydatne do “pro” analiz i debugowania mikrostruktury.
|
||
|
||
W tym stacku:
|
||
- `dlob-server` udostępnia REST endpointy `/l2` i `/l3`.
|
||
- Hasura/DB trzyma “latest” snapshot L2 w `dlob_l2_latest` oraz metryki w `dlob_stats_latest` / `dlob_depth_bps_latest` / `dlob_slippage_latest`.
|
||
|
||
## Słownik pojęć (bid/ask/spread i metryki)
|
||
|
||
### Podstawy orderbooka
|
||
|
||
- **Bid**: zlecenia kupna (chęć kupna). W orderbooku “bid side”.
|
||
- **Ask**: zlecenia sprzedaży (chęć sprzedaży). W orderbooku “ask side”.
|
||
- **Best bid / best ask**: najlepsza (najwyższa) cena kupna i najlepsza (najniższa) cena sprzedaży na topie księgi (L1).
|
||
- **Spread**: różnica pomiędzy `best_ask` a `best_bid`. Im mniejszy spread, tym “taniej” wejść/wyjść (mniej kosztów natychmiastowej realizacji).
|
||
- **Mid price**: cena “po środku”: `(best_bid + best_ask) / 2`. Używana jako punkt odniesienia do bps i slippage.
|
||
- **Level**: pojedynczy poziom cenowy w L2 (np. `price=100.00`, `size=12.3`).
|
||
- **Size**: ilość/płynność na poziomie (zwykle w jednostkach “base asset”).
|
||
- **Base / Quote**:
|
||
- `base` = instrument bazowy (np. SOL),
|
||
- `quote` = waluta wyceny (często USD).
|
||
|
||
## Kolory w UI (visualizer)
|
||
|
||
- `bid` / “buy side” = zielony (`.pos`, `#22c55e`)
|
||
- `ask` / “sell side” = czerwony (`.neg`, `#ef4444`)
|
||
- “flat” / brak zmiany = niebieski (`#60a5fa`) — używany m.in. w “brick stack” pod świecami
|
||
|
||
### Jednostki i skróty
|
||
|
||
- **bps (basis points)**: 1 bps = 0.01% = `0.0001`. Np. 25 bps = 0.25%.
|
||
- **USD**: u nas wiele wartości jest przeliczanych do USD (np. `size_base * price`).
|
||
|
||
### Metryki “stats” (np. `dlob_stats_latest`)
|
||
|
||
- `spread_abs` (USD): `best_ask - best_bid`.
|
||
- `spread_bps` (bps): `(spread_abs / mid_price) * 10_000`.
|
||
- `depth_levels`: ile leveli (top‑N) z każdej strony braliśmy do liczenia “depth”.
|
||
- `depth_bid_base` / `depth_ask_base`: suma `size` po top‑N levelach bid/ask (w base).
|
||
- `depth_bid_usd` / `depth_ask_usd`: suma `size_base * price` po top‑N levelach (w USD).
|
||
- `imbalance` ([-1..1]): miara asymetrii płynności:
|
||
- `(depth_bid_usd - depth_ask_usd) / (depth_bid_usd + depth_ask_usd)`
|
||
- >0 = relatywnie więcej płynności po bid, <0 = po ask.
|
||
- `oracle_price`: cena z oracla (np. Pyth) jako punkt odniesienia.
|
||
- `mark_price`: “mark” z rynku/perp (cena referencyjna dla rozliczeń); różni się od oracle/top-of-book.
|
||
|
||
### Metryki “depth bands” (np. `dlob_depth_bps_latest`)
|
||
|
||
- `band_bps`: szerokość pasma wokół `mid_price` (np. 5/10/20/50/100/200 bps).
|
||
- `bid_usd` / `ask_usd`: płynność po danej stronie, ale **tylko z poziomów mieszczących się w oknie ±`band_bps`** wokół mid.
|
||
- `imbalance`: jak wyżej, ale liczony per band.
|
||
|
||
### Metryki “slippage” (np. `dlob_slippage_latest`)
|
||
|
||
To jest symulacja “gdybym teraz zrobił market order o rozmiarze X” na podstawie L2.
|
||
|
||
- `size_usd`: docelowy rozmiar zlecenia w USD.
|
||
- `vwap_price`: średnia cena realizacji (Volume Weighted Average Price) dla symulowanego fill.
|
||
- `impact_bps`: koszt/odchylenie względem `mid_price` wyrażone w bps (zwykle na bazie `vwap` vs `mid`).
|
||
- `worst_price`: najgorsza cena dotknięta podczas “zjadania” kolejnych leveli.
|
||
- `filled_usd` / `filled_base`: ile realnie udało się wypełnić (może być < docelowego, jeśli brakuje płynności).
|
||
- `fill_pct`: procent wypełnienia (100% = pełny fill).
|
||
- `levels_consumed`: ile leveli zostało “zjedzonych” podczas fill.
|
||
|
||
### Metadane czasu (“świeżość”)
|
||
|
||
- `ts`: timestamp źródła (czas snapshotu).
|
||
- `slot`: slot Solany, z którego pochodzi snapshot (monotoniczny “numer czasu” chaina).
|
||
- `updated_at`: kiedy nasz worker zapisał/odświeżył rekord w DB (do oceny, czy dane są świeże).
|
||
|
||
## Szybka diagnostyka na VPS
|
||
|
||
```bash
|
||
KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n trade-staging get deploy | grep -E 'dlob-(worker|slippage-worker|depth-worker|publisher|server|redis)'
|
||
KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n trade-staging logs deploy/dlob-worker --tail=80
|
||
KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n trade-staging logs deploy/dlob-publisher --tail=80
|
||
KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n trade-staging logs deploy/dlob-server --tail=80
|
||
```
|
||
|
||
## Ważna uwaga (źródło L2 w `dlob-worker`)
|
||
|
||
Jeśli chcesz, żeby `dlob-worker` polegał na **naszym** stacku (własny RPC + `dlob-publisher` + `dlob-server`), ustaw:
|
||
|
||
- `DLOB_HTTP_URL=http://dlob-server:6969`
|
||
|
||
Aktualnie w `trade-staging` jest ustawione:
|
||
|
||
- `DLOB_HTTP_URL=https://dlob.drift.trade`
|