122 lines
4.3 KiB
Markdown
122 lines
4.3 KiB
Markdown
# Minimalne API dla bot-executora (k3s) + auth
|
||
|
||
Ten dokument opisuje **minimalny** zestaw endpointów i zasad bezpieczeństwa dla warstwy
|
||
**execution plane** (`bot-executor`) i **control plane** (API do sterowania botami) na VPS (k3s).
|
||
|
||
Cel: wysyłać transakcje na Drift **bez wystawiania publicznie** endpointu typu “podpisz i wyślij tx”.
|
||
|
||
Powiązane:
|
||
|
||
- Architektura botów: `doc/bots.md`
|
||
- DLOB / statsy na VPS: `doc/dlob-services.md`
|
||
- Topologia: `doc/rpc/README.md`
|
||
|
||
## Rozdział odpowiedzialności
|
||
|
||
### `bot-executor` (execution plane, private)
|
||
|
||
- Ma klucze prywatne (tylko tutaj).
|
||
- Podpisuje i wysyła transakcje na Drift przez prywatny Solana RPC.
|
||
- Czyta “desired state” z DB (`bot_config`) i zapisuje audyt (`bot_events`) + heartbeat (`bot_state`).
|
||
- **Nie** przyjmuje z zewnątrz “raw tx do podpisu”.
|
||
|
||
### Control plane (public/edge, auth)
|
||
|
||
- Ustawianie `bot_config` (mode/target/limity/kill switch).
|
||
- Odczyt `bot_state` i `bot_events`.
|
||
- Autoryzacja: tokeny/ACL/WireGuard (zależnie od klienta).
|
||
|
||
Control plane może być zrobiony na dwa sposoby:
|
||
|
||
1) **Hasura GraphQL** (z rolami i RLS) — szybkie, ale wymaga dopięcia uprawnień.
|
||
2) **`trade-api` endpointy** (HTTP) — prostsze do “opiniowania” auth (Bearer token scopes).
|
||
|
||
## Model danych (minimum)
|
||
|
||
Minimalne tabele (wg `doc/bots.md`):
|
||
|
||
- `bot_config`: desired state (mode, market, limity, kill_switch, strategia)
|
||
- `bot_state`: heartbeat + ostatni błąd/akcja
|
||
- `bot_events`: log audytowy (decision/order/panic/error)
|
||
|
||
## Auth (rekomendacja minimalna)
|
||
|
||
Warstwy:
|
||
|
||
1) **Sieć**: tylko przez WireGuard / allowlist IP (najprostsze i skuteczne).
|
||
2) **Aplikacja**: tokeny + scopes (np. `Authorization: Bearer ...`).
|
||
3) (Opcjonalnie) **mTLS/HMAC** service-to-service w klastrze, jeśli chcesz twardsze granice.
|
||
|
||
W tym repo masz już wzorzec tokenów w `api_tokens` + walidacja w `services/api/server.mjs`.
|
||
|
||
### Scopes (propozycja)
|
||
|
||
- `bots:read` — odczyt `bot_config/state/events`
|
||
- `bots:write` — zmiana `bot_config` (mode/params/kill switch)
|
||
- `exec:panic` — wymuszenie panic (jeśli zdecydujesz się na osobny endpoint; zwykle wystarczy `kill_switch=true`)
|
||
|
||
## Control plane API (HTTP) — propozycja endpointów
|
||
|
||
Te endpointy wystawiaj publicznie (za auth), ale **niech one tylko zmieniają DB**, a nie wysyłają transakcje.
|
||
|
||
### Konfiguracja bota
|
||
|
||
- `GET /v1/bots` (scope: `bots:read`)
|
||
- lista botów (id, name, market, mode, kill_switch, updated_at)
|
||
|
||
- `GET /v1/bots/:id` (scope: `bots:read`)
|
||
- pełny `bot_config`
|
||
|
||
- `POST /v1/bots` (scope: `bots:write`)
|
||
- tworzy nowy `bot_config`
|
||
|
||
- `PATCH /v1/bots/:id` (scope: `bots:write`)
|
||
- aktualizacja (np. limity, target exposure, params)
|
||
|
||
### Kill switch / mode (najczęstsze akcje)
|
||
|
||
- `POST /v1/bots/:id/mode` (scope: `bots:write`)
|
||
- body: `{ "mode": "off" | "observe" | "trade" }`
|
||
|
||
- `POST /v1/bots/:id/kill-switch` (scope: `bots:write`)
|
||
- body: `{ "enabled": true | false }`
|
||
- Executor traktuje `enabled=true` jako “panic” i wykonuje runbook (`cancel_all` + `close_position`) opisany w `doc/bots.md`.
|
||
|
||
### Status i audyt
|
||
|
||
- `GET /v1/bots/:id/state` (scope: `bots:read`)
|
||
- heartbeat, last_error, last_action_at
|
||
|
||
- `GET /v1/bots/:id/events?limit=200` (scope: `bots:read`)
|
||
- ostatnie eventy (decision/order/panic/error)
|
||
|
||
## `bot-executor` API (private) — minimalne endpointy
|
||
|
||
To API **nie musi być wystawione** poza klaster. Wystarczy Service `ClusterIP`.
|
||
|
||
- `GET /healthz` — liveness (bez auth)
|
||
- `GET /readyz` — readiness (bez auth; np. czy jest połączenie z RPC + DB)
|
||
- (Opcjonalnie) `POST /v1/reconcile` — ręczny reconcile (auth tylko wewnętrzny / admin)
|
||
|
||
Zamiast `POST /v1/panic` preferuj sterowanie przez DB (`kill_switch=true`), bo to daje audyt i działa nawet,
|
||
gdy control plane jest odcięty od samego executora.
|
||
|
||
## Deployment w k3s (propozycja)
|
||
|
||
- `Deployment/bot-executor`:
|
||
- env: RPC endpoints (po WG), Hasura URL, market list, itp.
|
||
- secret: keypair / seed, ewentualnie API tokeny
|
||
- zasoby: limity CPU/RAM (żeby executor nie “zjadał” node’a)
|
||
|
||
- `Service/bot-executor` (ClusterIP)
|
||
- brak Ingress (domyślnie)
|
||
|
||
- Monitoring:
|
||
- `Prometheus` scrape `/metrics` (jeśli dodasz)
|
||
|
||
## Co z “wysłaniem kontraktu” na Drift?
|
||
|
||
- `bot-executor` robi to przez Drift SDK → Solana RPC (`sendTransaction`).
|
||
- Control plane **nie** wysyła tx; tylko ustawia desired state.
|
||
|