trade-frontend/doc/stats.md

DLOB stats — definicje i wizualizacja

Ten dokument opisuje metryki liczone z orderbooka DLOB (Drift Limit Order Book) oraz propozycje, jak je prezentować w naszej wizualizacji (warstwami/panelami).

Źródła danych (tabele)

dlob_l2_latest (snapshot L2, “surowy”)

Snapshot top‑N leveli orderbooka per market.

• bids / asks: tablice poziomów { price, size } (wartości zwykle w “skalowanych intach” wg PRICE_PRECISION i BASE_PRECISION).
• best_bid_price / best_ask_price, mark_price, oracle_price: w praktyce do szybkiego odczytu top‑of‑book (ale najdokładniej liczyć z bids/asks).
• ts, slot: czas/slot źródłowego snapshota z DLOB.
• updated_at: kiedy worker zapisał snapshot do DB (do oceny “świeżości”).

Z tego źródła robimy: orderbook UI (paski/heat), mikro‑ceny, symulacje fill.

dlob_stats_latest (agregat z L2 pod UI)

Pochodne metryki liczone na podstawie dlob_l2_latest (lub równoważnego L2), trzymane jako “latest” per market.

Metryki:

• best_bid_price, best_ask_price (USD): najlepszy bid/ask.
• mid_price (USD): (best_bid_price + best_ask_price) / 2.
• spread_abs (USD): best_ask_price - best_bid_price.
• spread_bps (bps): (spread_abs / mid_price) * 10_000 (1 bps = 0.01%).
• depth_levels (liczba): ile leveli z każdej strony weszło do “depth”.
• depth_bid_base, depth_ask_base (base asset): suma size (w jednostkach bazowych) po top‑N levelach.
• depth_bid_usd, depth_ask_usd (USD): suma size_base * price po top‑N levelach.
• imbalance ([-1..1]): (depth_bid_usd - depth_ask_usd) / (depth_bid_usd + depth_ask_usd); >0 = relatywnie większa płynność po bid.
• mark_price, oracle_price (USD): ceny referencyjne (mark i oracle).
• ts, slot, updated_at: metadane czasu/świeżości.

To jest najszybsze źródło do overlay na wykresie i do KPI w headerze.

dlob_depth_bps_latest (płynność w pasmach wokół mid)

Metryki głębokości, ale nie “top‑N leveli” tylko “okno odległości od ceny” w bps.

Klucz:

• (market_name, band_bps) np. 5/10/20/50/100/200 bps.

Interpretacja:

• Dla danego band_bps sumujemy płynność tylko z poziomów, które mieszczą się w oknie ±band_bps wokół mid_price.

Metryki:

• bid_base, ask_base (base asset): suma size w oknie.
• bid_usd, ask_usd (USD): suma size_base * price w oknie.
• imbalance ([-1..1]): jak wyżej, ale per band.
• mid_price, best_bid_price, best_ask_price (USD): do kontekstu wyliczeń.
• ts, slot, updated_at, raw: metadane/diagnostyka.

To jest najlepsze źródło do wykresów “jak gruby jest orderbook blisko ceny”.

dlob_slippage_latest (symulacja slippage vs rozmiar)

Symulacja wykonania zlecenia rynkowego po L2.

Klucz:

• (market_name, side, size_usd) gdzie side ∈ {buy,sell} a size_usd to predefiniowane progi (np. 100/500/1000/…).

Metryki:

• impact_bps (bps): wpływ wykonania vs mid_price (zwykle vwap względem mid).
• vwap_price (USD): średnia cena wykonania.
• worst_price (USD): najgorszy poziom dotknięty podczas fill.
• filled_usd, filled_base: ile realnie weszło w fill (gdy brak płynności, może być < docelowego).
• fill_pct (%): 100% = pełny fill.
• levels_consumed: ile leveli zostało “zjedzone”.
• mid_price, ts, slot, updated_at, raw: metadane/diagnostyka.

To jest idealne do “Dynamic Slippage” w formularzu i do wykresu slippage‑vs‑size.

Jak nanieść na wizualizację (warstwy/panele)

Poniżej propozycja warstw, pogrupowanych tak, żeby serie w jednej warstwie były w tej samej “domenie” (jednostki i semantyka).

Warstwa 1: Cena / Quotes (oś Y = USD, overlay na głównym wykresie)

Źródło: dlob_stats_latest.

• Linie: mark_price i oracle_price (referencje).
• Linie: best_bid_price i best_ask_price (top‑of‑book).
• Opcjonalnie: mid_price jako linia przerywana.
• Opcjonalnie: “spread band” (wypełnienie między bid i ask).

Efekt: w jednym miejscu widać gdzie jest rynek + jak szeroki jest spread.

Warstwa 2: Spread (panel pod wykresem, oś Y = bps)

Źródło: dlob_stats_latest.

• Linia: spread_bps.
• Tooltip/secondary: spread_abs (USD) jako dodatkowa informacja (zwykle bez drugiej osi, żeby nie mieszać skali).

Efekt: szybkie “koszt wejścia/wyjścia” i jego zmienność.

Warstwa 3: Płynność top‑N + imbalance (panel, oś Y = USD + opcjonalnie linia imbalance)

Źródło: dlob_stats_latest.

• Area: depth_bid_usd i depth_ask_usd (dwie serie, zielona/czerwona).
• Opcjonalnie: linia imbalance (druga oś, zakres [-1..1]) albo jako wskaźnik liczbowy.

Efekt: ile jest płynności “najbliżej” top‑of‑book (w definicji top‑N leveli).

Warstwa 4: Płynność jako funkcja odległości (bps bands) (panel)

Źródło: dlob_depth_bps_latest.

Dwa czytelne warianty prezentacji:

1. Fan chart / multi‑line:

   • Linie bid_usd(band_bps) i ask_usd(band_bps) dla kilku bandów (np. 10/50/200).

2. Stacked:

   • Słupki/area pokazujące “ile dodaje kolejne pasmo” (np. 0–10, 10–20, 20–50 bps), osobno dla bid i ask.

Efekt: “jak szybko rośnie płynność, gdy odchodzę od mid”.

Warstwa 5: Slippage vs size (osobny panel XY, nie timeline)

Źródło: dlob_slippage_latest.

• Oś X: size_usd.
• Oś Y: impact_bps.
• Dwie krzywe: buy i sell.
• Marker: aktualny “Order Value” z formularza (punkt na krzywej).

Efekt: bardzo czytelna krzywa kosztu wykonania względem rozmiaru.

Warstwa 6: Heat / “paski” orderbooka (widok orderbook albo overlay z ograniczeniem)

Źródło: dlob_l2_latest.

• Paski (zielone/czerwone) per poziom ceny, intensywność ∝ size (jak na Drift UI).
• To najlepiej działa jako:
  • osobny panel “Orderbook” (snapshot), albo
  • “edge overlay” przy prawej krawędzi wykresu (bez historii).

Efekt: “gdzie stoją ściany” i jak się zmieniają.

Uwaga o historii (“latest” vs wykres w czasie)

Tabele *_latest są świetne do live UI i subscriptions, ale nie przechowują historii do rysowania timeline (np. spread przez ostatnie 24h).

Jeśli chcemy historię:

• opcja A: dodać osobne tabele time‑series (np. dlob_stats_ts, dlob_depth_bps_ts, dlob_slippage_ts) i zasilać je workerem,
• opcja B: rozszerzyć ingest ticków (drift_ticks) o dodatkowe pola/nową tabelę eventów dla metryk orderbooka.

Wtedy warstwy 2–5 mogą być prawdziwymi wykresami “w czasie”, a nie tylko bieżącym odczytem.