trade-doc/bots.md

# Boty (auto-trading) na Drift PERP — architektura VPS + Vast

Ten dokument opisuje docelową architekturę “botów”, które:
- potrafią otworzyć pozycję na wybranym rynku PERP,
- mierzą i publikują statsy (m.in. DLOB/L2, spread, depth, slippage),
- mogą zostać **zatrzymane / zmodyfikowane / natychmiast spłaszczone** (exit) w każdej chwili,
- działają na VPS (k3s) bez ręcznych zmian “na żywo” (snapshot deploy; patrz `doc/workflow.md`).

## Założenia i cele

### Cele
- **Separation of concerns:** model/strategia nie ma dostępu do kluczy; wykonanie transakcji jest tylko na VPS.
- **Kill switch:** jeden przełącznik ma natychmiast zatrzymać bota i wyjść z pozycji (cancel + close/reduce-only).
- **Desired-state loop:** bot nie “wydaje komend” ad‑hoc; utrzymuje stan docelowy (np. target exposure) i zbiega do niego.
- **Obserwowalność:** każda decyzja i akcja ma log/metrykę/event w DB.

Słownik pojęć (DLOB/L1…L10): `doc/dlob-basics.md`.
Strategia MVP (sekundy → minuty): `doc/bot-strategy-reversal.md`.

### Non-goals (na start)
- HFT / ultra-low-latency (na początku stawiamy na stabilność i kontrolę).
- Multi-venue routing i arbitraż między giełdami.
- Zarządzanie portfelem wielu subkont per user (to może wejść później).

## Warstwy systemu (docelowo)

### 1) Data plane (VPS/k3s): market data + statsy
Cel: zapewnić botom i UI spójne, “lokalne” źródła danych.

Aktualne elementy (już istnieją w repo/stacku):
- `dlob-publisher-hot` → buduje hot-path DLOB z Solany i publikuje `dlob-hot:*` do `dlob-redis`.
- `dlob-publisher-all` → buduje pełny feed rynku i publikuje `dlob-all:*` do `dlob-redis`.
- `dlob-hot-redis-to-postgres-raw-writer` → zapisuje raw `hot` do PostgreSQL.
- `dlob-hot-postgres-to-postgres-derived-writer` → buduje derived `hot`.
- `dlob-all-redis-to-postgres-derived-writer` → buduje derived `all`.
- `Hasura` → wystawia te dane jako GraphQL + subscriptions dla UI i botów.

Konfiguracja rynków:
- `DLOB_MARKETS` (symbole: np. `SOL-PERP`, `BTC-PERP`, `1MBONK-PERP`).
- `PERP_MARKETS_TO_LOAD` (indeksy rynków ładowane przez `dlob-publisher-hot` / `dlob-publisher-all`).

### 2) Execution plane (VPS/k3s): bot executor (klucze + transakcje)
Cel: jedyne miejsce, gdzie występują klucze prywatne i podpisywanie transakcji.

Warianty uruchomienia:
- **A) 1 Deployment na bota**: proste izolowanie i rollout per bot.
- **B) 1 Deployment “executor” obsługujący wiele botów**: łatwiejszy pooling połączeń/RPC, ale większy blast radius.

Minimalne wymagania executora:
- Czyta konfigurację bota (desired state) z DB (Hasura/Postgres).
- Subskrybuje statsy/telemetrię z Hasury (GraphQL + subscriptions) lub odpytuje okresowo.
- Wykonuje akcje tradingowe (place/modify/cancel/close) z ograniczeniami ryzyka.
- Ma **hard kill switch** (patrz niżej).

## Maszyneria bota (to jest kluczowe)

To, czy bot “działa bezpiecznie”, zależy mniej od samego modelu, a bardziej od maszynerii: pętli kontrolnej, zarządzania orderami i bezpiecznego wyjścia.

Poniżej minimalny podział odpowiedzialności wewnątrz executora (nawet jeśli to jest jeden proces):

- **Config store**: odczyt `bot_config` (desired state) + zapis `bot_state`.
- **Market data adapter**: pobiera features z Hasury (np. `dlob_stats_latest`, `dlob_depth_bps_latest`, `dlob_slippage_latest`, candles).
- **Strategy adapter**: tworzy propozycję “desired” (lokalnie lub z Vast). Nie robi transakcji.
- **Risk engine**: weryfikuje limity (max pozycja, max slippage, max order rate, timeouts, freshness danych).
- **Order manager**: mapuje “desired” → konkretne akcje: place/modify/cancel; pilnuje idempotencji i retry.
- **Position reconciler**: porównuje stan konta (pozycje/ordery) z DB i “desired”; wykrywa rozjazdy.
- **Kill switch**: zawsze dostępny; wymusza cancel + close i przejście do `mode=off`.

### Stan bota jako state machine (proponowane)

Traktuj to jak automat stanów, żeby uniknąć chaosu “ifów”:
- `off`: bot nie wysyła transakcji (może tylko heartbeat).
- `observe`: liczy/loguje decyzje, ale nie handluje.
- `trade`: aktywny, utrzymuje desired-state.
- `panic`: tryb awaryjny; cancel + close; potem `off`.

Opcjonalne stany pośrednie (jeśli potrzebne): `entering`, `managing`, `exiting`.

### Minimalny model danych (MVP)

Docelowo boty muszą być “sterowane” i audytowalne z DB:

- `bot_config` (sterowanie):
  - `mode`: `off|observe|trade`
  - `market_name` (np. `SOL-PERP`)
  - `target_exposure_usd` / `target_base`
  - limity: `max_position_usd`, `max_slippage_bps`, `max_orders_per_min`, `cooldown_ms`
  - `kill_switch` (bool)
  - `strategy`: `{ type, params, model_endpoint, model_version }`
- `bot_state` (status runtime):
  - `last_heartbeat_at`, `last_error`, `last_action_at`
  - `position_snapshot` (opcjonalnie)
- `bot_events` (audit log):
  - `decision` (wejście modelu/strategii + features hash + wersja)
  - `order_sent`, `order_ack`, `order_filled`, `order_canceled`
  - `panic_exit`, `error`

W MVP możesz zacząć od: `bot_config` + `bot_events`, a `bot_state` dodać po pierwszym działającym loopie.

### 3) Model plane (Vast): sygnały i inference (bez kluczy)
Cel: trenowanie/inference modeli na Vast, ale bez dostępu do środków.

Kontrakt między VPS a Vast:
- VPS wysyła “features snapshot” (np. statsy DLOB + candles + pozycja).
- Vast zwraca “decision” (np. `target_base`, `target_notional_usd`, `side`, `confidence`, `params`).
- VPS decyduje o wykonaniu i podpisuje transakcje.

Zasada: Vast **nigdy** nie dostaje sekretów (RPC keys, prywatne klucze, tokeny).

### 4) RPC: dedykowany Solana RPC/WS (VPS)
Cel: stabilność + mniejsze opóźnienia dla `dlob-publisher` i executora.

Założenia:
- `dlob-publisher` i executor używają tego samego RPC/WS (lub dwóch endpointów tej samej infrastruktury).
- W przyszłości możliwy fallback na publiczny endpoint (z ograniczeniami).

## Desired-state loop (core idea)

Bot działa jako pętla kontrolna:
1) Odczytaj `desired_state` (z DB) + bieżący stan (pozycja, ordery, rynek).
2) Policz różnicę (`delta`) i oceń ryzyko/limity.
3) Wykonaj minimalny zestaw akcji, żeby przybliżyć się do `desired_state`.
4) Zapisz eventy (co zrobił i dlaczego).

Przykładowe `desired_state` (na start):
- `mode`: `off | observe | trade`
- `market`: `SOL-PERP` (lub lista)
- `target_exposure_usd` albo `target_base`
- `max_position_usd`, `max_leverage`, `max_slippage_bps`
- `order_policy`: `market | limit | post_only | chase`
- `cooldown_ms`, `max_orders_per_min`

## Kill switch (must-have)

Kill switch ma działać bez udziału modelu i bez UI.

Źródła kill switch (kolejność priorytetu):
1) **Env var** executora (np. `BOT_KILL_SWITCH=1`) → natychmiastowy “panic mode”.
2) Flaga w DB (np. `bot_config.kill_switch=true`).
3) Warunek bezpieczeństwa (np. RPC lag, brak danych, brak świeżości L2, zbyt duży drawdown).

Akcja kill switch (docelowy runbook):
- `cancel_all` na rynku (lub subkoncie),
- `close_position` (preferowane: reduce-only, kontrola slippage),
- przejście bota do `mode=off` + zapis eventu “panic_exit”.

## Awaria VPS: co się dzieje z transakcjami i jak się zabezpieczyć

Kluczowe fakty:
- **Nie da się “ubić” wysłanej transakcji** na Solanie. Jeśli tx została przyjęta do sieci i wyląduje w bloku, jej efekt jest on-chain.
- To, co można zrobić po awarii, to **kolejne transakcje korygujące**: `cancel` / `close` / `reduce-only`.

W praktyce awarie dzielą się na 3 przypadki:

1) **Tx nie weszła (dropped/expired)** → po restarcie robisz reconcile i jedziesz dalej.
2) **Tx weszła i postawiła order** → po restarcie reconcile zobaczy otwarte ordery i może je utrzymać/zmodyfikować/cancel.
3) **Tx weszła i zmieniła pozycję** → po restarcie reconcile zobaczy pozycję i może ją domknąć lub dopasować do desired-state.

### Reconcile po starcie (must-have)

Każdy bot po restarcie powinien:
- wczytać `bot_config` (desired state),
- pobrać stan on-chain (pozycje + otwarte ordery dla rynku/subkonta),
- porównać “observed” vs “desired” i wykonać minimalne akcje korekcyjne.

To chroni przed sytuacją: “wysłaliśmy akcję, VPS padł przed zapisaniem eventu”.

## Guardian / Safety bot (żeby wyjść mimo padnięcia executora)

Jeśli wymaganie brzmi: “w każdej chwili możemy wyjść”, to kill switch nie może mieszkać tylko w tym samym VPS/klastrze co executor.

Proponowany wzorzec:
- Osobny, mały serwis **`bot-guardian`** uruchomiony **poza** głównym VPS (drugi VPS / inny klaster / inna VM).
- Guardian ma dostęp do:
  - RPC/WS,
  - klucza lub uprawnień do cancel/close (patrz uwagi bezpieczeństwa),
  - sygnału “czy executor żyje” (np. `bot_state.last_heartbeat_at` w DB albo endpoint health).

Zachowanie:
- Jeśli heartbeat executora jest starszy niż `T_fail` (np. 10–30s) → guardian włącza “panic mode”:
  - `cancel_all_orders`,
  - `close_position` (reduce-only; z limitem slippage),
  - zapis eventu `panic_exit` (jeśli ma dostęp do DB).

Uwaga: guardian nie potrzebuje modelu/AI. Ma być “głupi i niezawodny”.

### Minimalne bezpieczeństwo guardiana

- Klucze: trzymane jako secret tylko na hoście guardiana; nie w repo.
- Zakres: jeśli to możliwe, ogranicz klucz do subkonta / minimalnych uprawnień (w zależności od możliwości Drift/Solana).
- Rate-limit: zabezpieczenie przed pętlą panic (np. `panic_cooldown_ms`).

## HA executora (opcjonalnie): leader election

Jeśli chcesz 2 repliki executora (na jednym lub wielu węzłach), potrzebujesz single-writer:
- tylko **leader** składa transakcje,
- **follower** obserwuje i jest gotowy przejąć.

Wzorzec:
- lease w DB/Redis (np. rekord “lock” z TTL),
- leader odnawia lease co N sekund,
- brak odnowienia → follower przejmuje i robi reconcile.

To ogranicza ryzyko “double-trading”, ale nie zastępuje guardiana (bo oba mogą paść razem).

## Model kosztów (expected vs realized) — entry/exit/modify

Bot powinien umieć policzyć:
- **expected costs** (przed wejściem/wyjściem): czy trade ma sens i czy mieści się w limitach,
- **realized costs** (po fakcie): ile faktycznie kosztowało wejście/wyjście + ile “spaliły” modyfikacje.

W praktyce koszty dzielą się na 3 kubełki:
1) koszt mikrostruktury (spread/slippage/market impact),
2) fee maker/taker + funding (opcjonalnie),
3) koszt tx na Solanie (network fee + priority) oraz koszt modyfikacji (cancel+place).

### 1) Koszt wejścia/wyjścia z orderbooka (spread/slippage)

Źródła danych:
- `dlob_stats_latest`: `mid_price`, `spread_bps`, `best_bid_price`, `best_ask_price`
- `dlob_slippage_latest`: `impact_bps`, `vwap_price`, `fill_pct` dla `size_usd` i `side`

Warianty:
- **Taker/market (lub agresywny limit krzyżujący)**: używaj `impact_bps` z `dlob_slippage_latest` jako “expected execution cost vs mid”.
- **Maker/post-only**: policz 2 scenariusze:
  - “maker-fill”: koszt vs mid wynikający z `limit_price` (zwykle lepszy niż taker),
  - “fallback-taker”: jeśli nie fill → koszt = `impact_bps` (jak taker).

Przykładowa definicja kosztu vs mid (bps), jeśli liczysz z cen:
- buy: `cost_bps = (fill_price / mid_at_submit - 1) * 10_000`
- sell: `cost_bps = (1 - fill_price / mid_at_submit) * 10_000`

Uwaga: `mid` się rusza, więc to jest miara “kosztu wykonania względem chwilowego środka rynku” (przydatna do strojenia), a nie pełne PnL.

### 2) Fee maker/taker i funding (opcjonalnie)

Na MVP trzymaj fee jako parametry konfiguracyjne:
- `fee_maker_bps`
- `fee_taker_bps`

Realized fee licz po fill:
- `fee_usd = fill_notional_usd * fee_rate_bps / 10_000`

Funding dla holdów “minuty” zwykle jest mały; można dodać później.

### 3) Koszt transakcyjny (Solana fee + priority) i koszt modyfikacji

Fakty:
- “modyfikacja” ordera to zazwyczaj **cancel + place** → zwykle 2 transakcje.
- Nie da się “ubić” wysłanej transakcji; można tylko wysłać korektę (cancel/close) kolejną tx.

Definicje:
- `tx_fee_usd` = koszt jednej transakcji w USD (network fee + priority fee).
- `tx_fee_bps = (tx_fee_usd / notional_usd) * 10_000`

Koszt modyfikacji (expected):
- `expected_modify_cost_usd ≈ expected_reprices * (tx_fee_cancel_usd + tx_fee_place_usd)`
- `expected_modify_cost_bps = (expected_modify_cost_usd / entry_notional_usd) * 10_000`

Źródło `tx_fee_usd`:
- na start: stałe estymaty w `bot_config`,
- później: estymata “priority fee” z feedu/endpointu + przelicznik SOL→USD.

### Expected total cost (proponowana metryka bramkująca)

Na ticku decyzji licz:
- `expected_total_cost_bps = execution_bps + fee_bps + tx_bps + expected_modify_bps (+ funding_bps)`

I bramkuj wejście/wyjście:
- `expected_total_cost_bps <= max_expected_total_cost_bps`

## Parametry kosztów (do `bot_config`) — propozycja

Minimalny zestaw:
- `fee_maker_bps`, `fee_taker_bps`
- `max_expected_total_cost_bps`
- `max_expected_modify_bps` (opcjonalnie osobny limit na “cancel+place spam”)
- `tx_fee_usd_est` (albo `tx_fee_sol_est` + `sol_price_usd_est`)
- `expected_reprices_per_entry`

To działa zarówno dla strategii regułowych, jak i ML (model może dać `urgency`, ale executor i tak liczy koszty).

## Logowanie kosztów (do `bot_events`) — propozycja

Żeby stroić progi i ocenić jakość wejść, zapisuj:

### Na decyzji (przed wysłaniem orderów)
- `mid_at_submit`, `spread_bps_at_submit`
- `slippage_quote`: `impact_bps`, `vwap_price`, `fill_pct` (dla danego `size_usd`)
- `expected_cost_bps_breakdown`: `{ execution_bps, fee_bps, tx_bps, expected_modify_bps, total_bps }`
- `order_intent`: `{ policy, limit_price, size_usd, side }`

### Po fill / wyjściu
- `realized_execution_bps` (vs `mid_at_submit`), osobno entry i exit
- `realized_fee_usd`, `realized_tx_usd`
- `modify_count`: liczba cancel+place w trakcie wejścia/zarządzania
- `time_to_fill_ms`, `hold_time_s`

To daje realną pętlę feedbacku: “koszt vs jakość sygnału” i “czy chase zjada edge”.

## Obserwowalność i audyt (DB + logi)

W DB trzymamy:
- Konfigurację (`bot_config`) — desired state i limity.
- Stan (`bot_state`) — ostatnia decyzja, last heartbeat, ostatni błąd.
- Eventy (`bot_events`) — “decision”, “order_sent”, “order_filled”, “panic_exit”, “error”.

MVP może zacząć od samego `bot_events` + `bot_config`, a resztę dodać po pierwszym działającym loopie.

## Interfejsy (kontrakty)

### VPS ↔ Hasura
- Executor czyta: `dlob_*_latest` + `drift_ticks`/candles + własne tabele botów.
- Executor pisze: `bot_events`, `bot_state` (oraz ewentualnie `bot_orders`).

### VPS ↔ Vast
- HTTP endpoint (lub gRPC) “predict”.
- Kontrakty muszą być wersjonowane (`model_version`) i logowane w `bot_events`.

## Bezpieczeństwo (sekrety)

Zasady:
- Prywatne klucze i tokeny są tylko w K8s Secret (na VPS) i nigdy nie trafiają do repo.
- Vast nie dostaje sekretów.
- Logi nie mogą wypisywać URL z api-key ani payloadów z sekretami.

## Deployment (k3s + GitOps)

Zasady deployu: snapshoty, brak ręcznych zmian na VPS (`doc/workflow.md`).

Docelowe komponenty w `trade-deploy` (do dopięcia):
- `Deployment/bot-executor` (albo `Deployment/bot-<name>`),
- `Secret/bot-executor-keys` (klucze/konfiguracja),
- NetworkPolicy (opcjonalnie) ograniczająca ruch do Vast i RPC.

## Plan budowy (iteracyjnie)

### Etap 0: Observe-only (bez handlu)
- `bot_config` + `bot_events`.
- Executor subskrybuje `dlob_stats_latest` i loguje “decision” bez transakcji.
- Kill switch działa (przełącza tryb i loguje).

### Etap 1: Paper trading / dry-run
- Executor wylicza ordery i zapisuje je do DB, ale nie wysyła na chain.
- UI pokazuje “co by zrobił”.

### Etap 2: Live trading (minimal)
- Wejście/wyjście market/limit z restrykcjami ryzyka.
- Panic exit: cancel + close.

### Etap 3: Integracja z modelem (Vast)
- Predictor endpoint, wersjonowanie modeli, fallback (jeśli Vast down → observe/off).

## Otwarte pytania (do uzupełnienia)

- Czy bot ma działać na jednym rynku PERP czy wielu jednocześnie?
- Jaki tryb wejścia/wyjścia: market vs limit vs post-only/chase?
- Jakie KPI/limity: max drawdown, max slippage, max position, timeouts?
- Jak rozdzielamy konta/subkonta (1 bot = 1 subkonto?) i jak to audytujemy?