From 0e56f63e632a6a5ed27332bafd44836539e10150 Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Tue, 21 Jul 2026 15:06:51 +0200 Subject: [PATCH] Document the DB-only config model and the new dashboard sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md and docs/guida-admin.md now describe RoundConfig as the sole source of truth for business parameters, with no env var counterpart — defaults live as hardcoded model column defaults, not app/config.py. guida-admin.md documents the four new dashboard sections (Round, Transazioni pendenti, Audit log alongside Parametri/Utenti). setup.md points readers to the admin panel instead of .env for those values. Co-Authored-By: Claude Sonnet 5 --- CLAUDE.md | 5 ++-- docs/guida-admin.md | 65 ++++++++++++++++++++++++++++++++++----------- docs/setup.md | 6 +++-- 3 files changed, 55 insertions(+), 21 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8118d53..1129054 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -60,9 +60,8 @@ Known risk: `docker-compose.yml` sets `restart: unless-stopped` on `app`, so a c - **PLM node access**: Electrum protocol only (no full node/P2P). Bootstrap server for development: `santantonio.sytes.net:50002` (SSL). - **Auth**: Argon2 password hashing + JWT sessions. - **Secrets**: master xprv encrypted at rest with a symmetric scheme (AES-GCM/Fernet); the encryption key itself lives in an env var, never in the DB or in git. -- **Operational config** (fee/commission address, RBF fee-bump wallet, etc.): stored in a DB config table, not env vars — must be editable without a redeploy. -- **Round duration**: configurable via env var, default 10 minutes (not hardcoded). -- **Round cooldown**: `ROUND_COOLDOWN_SECONDS` (default 30s) — gap after a round closes before the next one opens, so players have time to see the outcome. Not in the original flowchart; added afterwards as an explicit design decision. +- **Operational config**: every business/round parameter (fee address, bet amount, round duration, round cooldown, minimum amount, network fee rate, RBF timeout) lives in the `round_config` DB table (single row, `app/rounds/config.py`) and is only editable live via the admin dashboard (`/admin`) or its API — no env var involved at all, no redeploy or restart needed. Defaults for a brand-new instance are hardcoded column defaults on the `RoundConfig` model (`app/db/models.py`), not `app/config.py`. Secrets and infra wiring (master key, JWT secret, Electrum host, admin token, database URL) stay env-var-driven in `.env` since those genuinely need a restart. +- **Round cooldown**: gap after a round closes before the next one opens, so players have time to see the outcome (default 30s). Not in the original flowchart; added afterwards as an explicit design decision. ## PLM network parameters diff --git a/docs/guida-admin.md b/docs/guida-admin.md index 6f586d3..415d38e 100644 --- a/docs/guida-admin.md +++ b/docs/guida-admin.md @@ -7,28 +7,50 @@ server sia già avviato — vedi [running-the-server.md](running-the-server.md). Il pannello admin è su **`https:///admin`** — **non è collegato** da nessun link nell'interfaccia utente (né in entrata né in uscita): ci si -arriva solo conoscendo l'URL. Non è protetto da login personale, ma da un -**token condiviso** (`ADMIN_TOKEN`, definito in `.env`). +arriva solo conoscendo l'URL. La pagina mostra solo un campo token finché non +accedi: non è protetta da login personale, ma da un **token condiviso** +(`ADMIN_TOKEN`, definito in `.env`). -Apri la pagina, incolla il valore di `ADMIN_TOKEN` nel campo "Admin token" e -usa i bottoni: +Incolla il valore di `ADMIN_TOKEN` e premi "Accedi" (o Invio): se il token è +valido, si apre la dashboard con una navbar in alto e carica automaticamente +tutte le sezioni — nessun bottone "Carica" separato. Il token resta in +`sessionStorage` (si perde chiudendo la tab/il browser); "Esci" torna alla +sola schermata di login. -- **"Carica configurazione attuale"** → mostra `fee_address` e - `bet_amount_sats` (in PLM) correnti -- **"Salva"** → aggiorna i valori nel database, effetto immediato, nessun - riavvio del server necessario +## Sezioni della dashboard -## Cosa si configura +- **Parametri** — configurazione operativa (vedi tabella sotto) +- **Utenti** — elenco utenti, saldo, accesso alla chiave privata +- **Round** — storico round: stato, vincitore, importi, txid di payout +- **Transazioni pendenti** — bet/payout/prelievi non ancora confermati, candidati al fee-bump RBF +- **Audit log** — eventi registrati dal sistema (config cambiata, bet, payout, accessi a chiavi private, ecc.) + +## Parametri + +Tutti i parametri operativi/di business sono nella sezione "Parametri", +salvati nel database — modificabili in qualsiasi momento, effetto immediato, +**nessun riavvio del server necessario**. Non esiste alcuna variabile +d'ambiente equivalente: `.env` contiene solo segreti e configurazione di +infrastruttura (chiave master, JWT, Electrum, token admin), non parametri di +business — quelli si toccano solo da qui. | Campo | Significato | |---|---| | **Fee address** | L'indirizzo PLM su cui finisce il 30% di ogni round (fee). Obbligatorio: i payout **non partono** se questo campo è vuoto. | -| **Bet amount (PLM)** | Il costo fisso d'ingresso per round, mostrato/impostato in PLM (internamente il backend lavora in sats: 1 PLM = 100.000.000 sats). | +| **Bet amount (PLM)** | Il costo fisso d'ingresso per round. | +| **Durata round (secondi)** | Quanto resta aperto un round prima di chiudersi ed estrarre il vincitore. | +| **Pausa tra un round e il successivo (secondi)** | Cooldown dopo la chiusura di un round, prima che il successivo si apra — dà tempo ai giocatori di vedere l'esito. | +| **Importo minimo deposito/prelievo (PLM)** | Soglia minima per un prelievo (i depositi non hanno un controllo minimo lato server, solo un floor consigliato). | +| **Fee rate di rete (sat/vB)** | Fee per byte usata per costruire bet, payout e prelievi. | +| **Timeout prima del fee-bump RBF (secondi)** | Dopo quanto tempo senza conferma una transazione viene ritrasmessa con fee più alta. | -`ROUND_DURATION_SECONDS` (durata del round) e `ROUND_COOLDOWN_SECONDS` (pausa -tra un round e il successivo, default 30s) **non** sono qui: sono variabili -d'ambiente in `.env`, non modificabili a runtime — per cambiarle serve -riavviare il server con il nuovo valore. +Tutti gli importi in PLM vengono convertiti in sats (1 PLM = 100.000.000 sats) +solo nella chiamata API — il backend lavora sempre in sats. + +Su un'istanza nuova (mai avviata), questi campi partono con dei default +hardcoded nel codice (`RoundConfig` in `app/db/models.py`: bet 10 PLM, round +10 minuti, cooldown 30s, minimo 1 PLM, fee 1 sat/vB, RBF timeout 900s) — vanno +comunque rivisti e confermati dal pannello prima del primo utilizzo reale. ## Alternative all'interfaccia grafica @@ -40,13 +62,24 @@ nell'header `X-Admin-Token`: # leggere la configurazione curl https:///admin/config -H "X-Admin-Token: " -# aggiornarla (importi in sats: 10 PLM = 1000000000) +# aggiornarla (importi in sats: 10 PLM = 1000000000; solo i campi passati vengono cambiati) curl -X PUT https:///admin/config \ -H "X-Admin-Token: " \ -H "Content-Type: application/json" \ - -d '{"fee_address": "plm1q...", "bet_amount_sats": 1000000000}' + -d '{"fee_address": "plm1q...", "bet_amount_sats": 1000000000, "round_duration_seconds": 600}' ``` +## Utenti e chiave privata + +La card "Utenti" elenca id, username, indirizzo e saldo di ogni utente +registrato. Il bottone "Mostra" su ogni riga rivela la chiave privata (WIF) +di quell'utente, dietro conferma esplicita — serve per interventi manuali +(es. restituire fondi bloccati). **Ogni visualizzazione viene registrata +nell'audit log** (`admin_privkey_accessed`). Questo non introduce una nuova +falla: il server è già custodial, la chiave master da cui derivano tutte le +chiavi utente vive sul server — questo pannello espone solo qualcosa che +l'operatore può già fare via script. + ## Limiti noti - Il token è unico e condiviso: non c'è identità per singolo admin né audit diff --git a/docs/setup.md b/docs/setup.md index 00e233b..a69b116 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -29,8 +29,10 @@ cp .env.example .env | `ADMIN_TOKEN` | Token bearer richiesto sugli endpoint admin (header `X-Admin-Token`). | `python -c "import secrets; print(secrets.token_urlsafe(32))"` | Le altre chiavi di `.env` (`DATABASE_URL`, `ELECTRUM_HOST`/`PORT`/`USE_SSL`, -`MASTER_KEY_PATH`, `ROUND_DURATION_SECONDS`) hanno default sensati in -`.env.example` — modificali se serve (es. round più corti per i test). +`MASTER_KEY_PATH`) hanno default sensati in `.env.example`. Nota: `.env` +contiene solo segreti e configurazione di infrastruttura — i parametri di +business (bet amount, durata round, fee, ecc.) si configurano dal pannello +admin dopo l'avvio, non qui — vedi [guida-admin.md](guida-admin.md). **Non committare mai `.env`.** È già escluso da `.gitignore`.