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