trade-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 aktualny łańcuch od źródła do metryk w live runtime:

Warstwa A: On-chain → DLOB w pamięci (VPS/k3s)

Komponenty: dlob-publisher-hot i dlob-publisher-all.

• Łączą się do Solany przez prywatny RPC/WS/gRPC.
• Budują DLOB w pamięci.
• Publikują snapshoty do Redis:
  • dlob-hot:*
  • dlob-all:*

To jest najbliżej źródła i najbardziej “real-time”.

Warstwa B: Redis → PostgreSQL (VPS/k3s)

Komponenty:

• dlob-hot-redis-to-postgres-raw-writer
• dlob-hot-postgres-to-postgres-derived-writer
• dlob-all-redis-to-postgres-derived-writer

Ten etap:

• utrwala raw hot w PostgreSQL,
• buduje derived layer hot i all,
• zapisuje znormalizowane poziomy orderbooka oraz metryki top-of-book do tabel dlob_*_derived_*.

Warstwa C: Hasura + aplikacja

• Hasura wystawia derived tables jako GraphQL + subscriptions.
• UI i narzędzia aplikacyjne czytają z dlob_hot_derived_latest oraz dlob_all_derived_latest.
• Metryki depth/slippage nie są już liczone przez osobne workery k3s; bieżąca ścieżka aplikacji wylicza je z danych L2/derived.

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_*_derived_latest

Zapisywane w writerach warstwy pochodnej na podstawie live snapshotów orderbooka:

• Bierzemy znormalizowane top level’e z bids_norm i asks_norm.
• Każdy level ma:
  • price
  • size_base
  • “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

W aktualnej ścieżce aplikacji to liczenie jest robione z danych L2/derived, a nie przez osobny backend worker:

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