trade-frontend/doc/dlob-basics.md

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