docs(snapshot): sync workspace documentation

rpc/geyser-dlob.md

@@ -0,0 +1,79 @@
+# Geyser (Yellowstone gRPC) + Drift DLOB
+
+Ten dokument jest “praktycznym mostem” między:
+
+- **RPC boxem** (bare metal) z `agave/solana-validator` i pluginem **Geyser/Yellowstone gRPC**,
+- a **VPS** (k3s), gdzie działa **Drift DLOB** (publisher + redis + server + statsy).
+
+Cel: realtime feed “prosto z noda” (gRPC), bez wystawiania RPC publicznie.
+
+## Założenia sieciowe (must-have)
+
+- Bare metal ↔ VPS po **WireGuard**.
+- Porty RPC/WS/gRPC dostępne **tylko** po WG (albo bind do WG IP + firewall).
+- Publicznie nie wystawiamy:
+  - Solana RPC/WS,
+  - Yellowstone gRPC,
+  - Redis.
+
+## Porty (typowe)
+
+To nie są twarde wymagania, ale typowy setup wygląda tak:
+
+- Solana JSON-RPC HTTP: `8899`
+- Solana pubsub WS: `8900`
+- Yellowstone gRPC: `10000`
+
+## Jak to mapuje się na env (VPS)
+
+W `trade-staging` trzymaj endpointy jako secrety i wstrzykuj do podów:
+
+- `ENDPOINT=http://<rpc_wg_ip>:8899`
+- `WS_ENDPOINT=ws://<rpc_wg_ip>:8900`
+- `GRPC_ENDPOINT=http://<rpc_wg_ip>:10000`
+- `TOKEN=...` (jeśli włączasz auth w Yellowstone)
+
+Uwaga:
+
+- W naszym kodzie `dlob-publisher` w trybie gRPC używa gRPC głównie do `OrderSubscriber`.
+  DriftClient (accountSubscriber) nadal polega na WS/polling (gRPC dla driftClient jest w kodzie wyłączone),
+  więc **WS endpoint nadal musi działać**.
+- Dla `OrderSubscriber` w trybie gRPC mamy lokalny auto-reconnect. Jeśli Yellowstone zamknie stream albo zwroci `14 UNAVAILABLE: Connection dropped`, publisher nie powinien juz wychodzic z `exit 1`; zamiast tego czyści stream i probuje wznowic subskrypcje. Backoff jest sterowany przez `GRPC_RECONNECT_DELAY_MS` i domyslnie wynosi `1000 ms`.
+
+## DLOB: zalecana konfiguracja na start (2 markety)
+
+Przykład ustawień dla `dlob-publisher`:
+
+- `ENV=mainnet-beta`
+- `PERP_MARKETS_TO_LOAD=0,75` (2 markety)
+- `USE_ORDER_SUBSCRIBER=true`
+- `USE_WEBSOCKET=true` (dla DriftClient / slotów)
+- `USE_GRPC=true`
+- `GRPC_CLIENT=yellowstone`
+- `GRPC_ENDPOINT=...`
+- `TOKEN=...` (jeśli wymagany)
+- (opcjonalnie) `DISABLE_GPA_REFRESH=true` (żeby zmniejszyć polling)
+
+Jeśli po drodze okaże się, że gRPC jest niestabilne, nadal możesz wrócić do trybu WS:
+
+- wyłącz `USE_GRPC` i zostaw `USE_WEBSOCKET=true`.
+
+Ale operacyjnie najpierw warto sprawdzic logi reconnectu, bo krotkie dropy streamu powinny byc teraz obslugiwane bez restartu poda.
+
+## Minimalne testy “czy działa”
+
+Z perspektywy VPS:
+
+1) Sprawdź, czy gRPC port jest osiągalny po WG (np. TCP connect do `10000`).
+2) W logach `dlob-publisher` powinno być widoczne, że `useGrpc: true` (albo analogiczna flaga).
+3) Metryki DLOB powinny pokazywać rosnące liczniki update’ów (publisher) oraz świeże sloty.
+
+## Co to daje vs zwykły RPC/WS
+
+- Niższa latencja i stabilniejszy stream zmian kont (szczególnie, gdy klientów WS jest dużo).
+- Mniej “pchania” ciężkich subskrypcji przez publiczny RPC.
+
+Co to nie rozwiązuje:
+
+- “Pamięciożerności” DLOB jako takiej (stan orderbooka i user map rośnie z rynkami i aktywnością).
+- Wymaga nadal rozsądnej konfiguracji rynku (na start: mała lista marketów).