docs(snapshot): sync workspace documentation
This commit is contained in:
158
stats.md
Normal file
158
stats.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# 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.
|
||||
|
||||
Reference in New Issue
Block a user