docs: add rpc/dlob/candles notes

doc/drift-costs.md

@@ -0,0 +1,120 @@
+# Drift Perp: koszty wejścia/edycji/wyjścia (stan na 2026-01-31)
+
+Ten dokument zbiera **wszystkie realne składowe kosztu** przy handlu perps na Drift, żebyśmy mogli je liczyć na backendzie i wizualizować w UI.
+
+## 1) Składowe kosztu (per trade / per pozycja)
+
+### A. Opłata transakcyjna Drift (maker/taker)
+- **Taker fee**: procent od **notional** (wartości pozycji w USD/USDC).
+- **Maker fee**: zwykle **ujemny** (rebate) dla zleceń maker (np. post-only), zgodnie z aktualnym cennikiem.
+- Stawki zależą od wolumenu 30D oraz stakingu DRIFT (dodatkowe zniżki / większe rebate).
+- W **High Leverage Mode** taker fee może być podbite (np. 2× najniższy tier).
+> TODO: potwierdzić aktualne stawki fee (z Drift SDK / on-chain) i zapisać je jako “source of truth” dla backendu.
+
+**Wzór (pojedynczy fill):**
+- `notional = |size_base| * fill_price`
+- `trade_fee_usd = notional * fee_rate` (dla maker `fee_rate` może być < 0)
+
+### B. Slippage / spread (koszt rynkowy)
+To nie jest fee protokołu, ale realny koszt wejścia/wyjścia:
+- `slippage_cost_usd ≈ (fill_price - mid_price) * size_base` (znak zależy od long/short)
+- U nas to powinno być liczone z DLOB (L2 + symulacja fill).
+
+### C. Funding (koszt/zarobek w czasie trzymania pozycji)
+- Funding jest naliczany w czasie i realizowany przy akcjach użytkownika (trade/deposit/withdraw) – w praktyce dla krótkich holdingów (minuty–1h) zwykle jest małym składnikiem, ale nie zawsze zerowym.
+
+**Wzór (upraszczając):**
+- `funding_usd ≈ Σ (position_notional_usd * funding_rate_interval)`
+
+### D. P&L settlement / “unsettled P&L” (wpływ na withdraw)
+- Żeby **wypłacić zysk**, czasem trzeba wykonać `settlePNL` (rozlicza P&L do P&L Pool; nie zamyka pozycji, tylko zmienia cost basis).
+- Jeśli brakuje środków w per-market P&L Pool, zysk może być częściowo **unsettled** i nie będzie w pełni wypłacalny od razu.
+
+### E. Liquidation penalty (jeśli konto spadnie poniżej maintenance)
+- Przy wejściu w liquidację protokół najpierw anuluje otwarte ordery/LP, a następnie liquidator może redukować pozycje.
+- “Penalty/fee” jest ustawiana per-market i zwykle jest wyższa niż zwykły taker fee (żeby dać rebate liquidatorowi).
+
+### F. Koszt sieci Solana (per instrukcja / per tx)
+To koszt “infrastrukturalny” każdej akcji on-chain (order, cancel, modify, settlePNL, deposit/withdraw, close).
+- **Base fee**: 5000 lamports per signature (minimum).
+- **Priority fee**: opcjonalny, zależy od congestion.
+- Jednorazowo może dojść **rent/account creation** (np. token account), jeśli czegoś brakuje.
+
+## 2) “Ile kosztuje” konkretna akcja (checklista)
+
+### Wejście w pozycję (open / increase)
+1) **Solana tx fee** (base + ewentualnie priority)
+2) **Drift trading fee** (maker/taker) od notional
+3) **Slippage/spread** (z DLOB)
+4) (w tle) funding zaczyna naliczać się w czasie
+
+### Zmiana pozycji (increase/decrease/flip)
+To po prostu kolejny trade:
+- znowu `tx fee + trading fee + slippage`
+- oraz często realizacja funding (zależy od tego czy funding został zaktualizowany)
+
+### Wyjście z pozycji (close)
+1) `tx fee`
+2) `trading fee` (druga strona round-trip)
+3) `slippage`
+4) **realized PnL** = różnica cen ± funding − fees
+5) jeśli chcesz wypłacić: możliwe `settlePNL` oraz limit z P&L pool
+
+### Edycja zlecenia (modify)
+Zwykle koszt to:
+- `tx fee` (czasem modify = cancel+place, zależnie od ścieżki w kliencie)
+- brak trading fee, jeśli nie było fill
+
+### Cancel zlecenia
+- `tx fee`
+- brak trading fee (jeśli 0 fill)
+
+### Monitorowanie zysku / risk (PnL, margin, health)
+On-chain: bez kosztu, jeśli tylko czytasz RPC/indexera.
+Koszt pojawia się dopiero przy akcjach typu trade/cancel/settle/withdraw.
+
+## 3) Przykład liczbowy (taker, round-trip)
+
+Załóż:
+- `notional = 10,000 USDC`
+- `taker_fee_rate = 0.0350%` (PRZYKŁAD – realna stawka zależy od tieru)
+
+Wtedy:
+- wejście: `10,000 * 0.00035 = 3.50 USDC`
+- wyjście: `3.50 USDC`
+- razem fee (bez slippage/funding): `7.00 USDC` + 2× Solana tx fee (+ priority jeśli ustawisz).
+
+## 4) Co musimy znać, żeby liczyć to “dokładnie” w backendzie
+
+Minimalny zestaw wejść:
+- market (np. `SOL-PERP`)
+- order type (market/limit/post-only), przewidywany fill path (taker vs maker)
+- notional/size, przewidywany fill (DLOB simulation)
+- fee tier użytkownika + staking/discounty + ew. “fee adjusted markets”
+- funding history + horyzont (np. 1h/4h/24h/7d)
+- czy chcemy uwzględniać `settlePNL` oraz status “unsettled PnL” przed withdraw
+
+---
+
+## 5) Słownik (kluczowe pojęcia w UI/API)
+
+Poniżej jest skrót pojęć, których używamy w warstwach “Costs (New)” i “Costs (Active)”:
+
+- `notional` — wartość pozycji w USD (np. 10 USD); na tym liczymy bps i fee.
+- `bps` (basis points) — punkty bazowe: `1 bps = 0.01% = 0.0001`.  
+  Przeliczenie na koszt: `koszt_usd ≈ notional_usd * bps / 10_000`.
+- `fee` — opłata protokołu Drift (maker/taker) od `notional`; zwykle stała dla danego trybu/tieru.
+- `tx fee` — koszt transakcji na Solanie (base fee + ewentualny priority fee).
+- `slippage` — koszt rynkowy wejścia/wyjścia, bo wykonujesz się gorzej niż `mid` (zależy od płynności).
+- `impact (bps)` — slippage wyrażony w bps (dla danego notionalu).
+- `spread` — różnica `best_ask - best_bid`; “minimalny” koszt natychmiastowego wejścia/wyjścia w płytkim booku.
+- `mid` — `(best_bid + best_ask) / 2`; punkt odniesienia ceny z orderbooka.
+- `VWAP` — średnia cena wykonania dla danego rozmiaru (symulacja fill po L2).
+- `breakeven (bps)` — minimalny ruch ceny (w bps), żeby koszty się zwróciły (wyjść na 0).
+- `PnL` (profit and loss) — zysk/strata:
+  - `unrealized PnL` — “na papierze”, gdy pozycja jest otwarta (zależy od ceny teraz),
+  - `realized PnL` — zrealizowany po zamknięciu (lub częściowym zamknięciu) pozycji,
+  - `net PnL` — PnL po odjęciu kosztów (`fee + tx + slippage + funding`).
+- `funding` — okresowa płatność long↔short; koszt albo zysk zależny od rynku i czasu trzymania.
+- `close now` — estymata kosztu natychmiastowego zamknięcia pozycji (zwykle po przeciwnej stronie booka).
+- `modify` / `reprice` — koszt “zarządzania zleceniem” (cancel+place itp.), głównie `tx fee` (czasem wielokrotnie).