docs(snapshot): sync workspace documentation

rpc/software-placement.md

@@ -0,0 +1,89 @@
+# Strategia rozmieszczenia softu (bare metal / VPS / Vast)
+
+Celem jest:
+
+- **stabilny, prywatny feed danych** (Solana RPC → DLOB → statsy),
+- **bezpieczne wykonanie transakcji** (klucze tylko na VPS),
+- **skalowanie ML** (trening na Vast), bez kompromisu bezpieczeństwa.
+
+Źródła kontekstu w repo:
+
+- DLOB i przepływ danych: `doc/dlob-services.md`
+- Boty i podział na plane’y: `doc/bots.md`
+
+## Zasady (priorytety)
+
+1) **RPC box jest “lean”** — żadnych baz danych, Grafany, workerów, botów.
+2) **Klucze tylko w execution plane** — żadnych kluczy na Vast i w UI.
+3) **Publicznie tylko read/control plane** — bez endpointu “podpisz i wyślij”.
+4) **Ogranicz rynki** na start (np. `PERP_MARKETS_TO_LOAD=0,75`), żeby odchudzić cały pipeline.
+
+## Co gdzie uruchamiamy
+
+### Bare metal (Solana RPC box)
+
+Uruchamiaj:
+
+- `agave/solana-validator` jako prywatny RPC (non-voting).
+- (Opcjonalnie) `geyser` / `yellowstone-grpc` plugin, jeśli chcesz feed “faster-than-RPC”.
+- WireGuard + firewall + chrony.
+- Monitoring: `node_exporter` + probe zdrowia RPC.
+
+Nie uruchamiaj:
+
+- DLOB, Redis, Hasura/Postgres, Grafana, botów.
+
+Powód: RAM 192 GB jest cenny dla noda; trzymamy minimalną liczbę procesów i klientów.
+
+### VPS (k3s / “app + trading box”)
+
+Uruchamiaj:
+
+- **Data plane**:
+  - `dlob-publisher-hot` i `dlob-publisher-all` (czytają z prywatnego RPC/WS lub gRPC),
+  - `dlob-redis`,
+  - `dlob-hot-redis-to-postgres-raw-writer`,
+  - `dlob-hot-postgres-to-postgres-derived-writer`,
+  - `dlob-all-redis-to-postgres-derived-writer`,
+  - Postgres + Hasura (GraphQL/WS dla “latest” tabel i sterowania botami).
+- **Execution plane**:
+  - `bot-executor` (klucze, podpisywanie transakcji, risk, kill switch).
+- **Control plane / UI**:
+  - `trade-frontend` (proxy/auth + UI),
+  - `trade-api` (narzędzia: tokeny, admin, pomocnicze endpointy).
+- Monitoring:
+  - Prometheus/Grafana/Alertmanager.
+
+Wystawianie na zewnątrz (rekomendacja):
+
+- Publicznie: UI + GraphQL (Hasura) + ewentualnie read-only API.
+- Control plane: endpointy do ustawiania `bot_config` i odczytu `bot_state/bot_events` (z auth).
+- **Nie publicznie**: `bot-executor`, prywatny RPC, Redis.
+
+### Vast (GPU / “model plane”)
+
+Uruchamiaj:
+
+- Trening transformera na danych wyeksportowanych z VPS (batch).
+- Ewentualnie inference endpoint (jeśli chcesz oddzielić obciążenie od VPS).
+
+Nie uruchamiaj / nie przechowuj:
+
+- kluczy prywatnych,
+- tokenów do środków,
+- dostępu do prywatnego RPC po VPN (nie jest potrzebny do treningu).
+
+## Kontrakt VPS ↔ Vast (bezpieczny)
+
+- VPS wysyła: “feature snapshots” / dataset (bez sekretów).
+- Vast zwraca: “decision” (np. target exposure/side/confidence).
+- VPS decyduje o wykonaniu (risk engine) i podpisuje transakcję (executor).
+
+## Minimalny start (2 markety)
+
+1) DLOB:
+   - `PERP_MARKETS_TO_LOAD=0,75` (i analogicznie dla TOB monitoring, jeśli używasz).
+2) Execution:
+   - `bot-executor` czyta config z DB, nie z requestów “na żywo”.
+3) Public API:
+   - brak “sign & send”; tylko control-plane + read-only dane.