# Operatività Manuale operativo di PLM Lottery: dove stanno i dati, cosa salvare, cosa succede a un riavvio, e cosa fare quando qualcosa si blocca. Presuppone installazione e avvio già fatti: la prima configurazione è in [setup.md](setup.md), i comandi Docker di tutti i giorni in [running-the-server.md](running-the-server.md), l'uso del pannello in [guida-admin.md](guida-admin.md). Qui c'è quello che quelle guide non coprono. Le procedure citano spesso eventi del registro di audit: il loro significato esatto è in [audit-log.md](audit-log.md). Il funzionamento interno che spiega *perché* un round si blocca è in [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md), [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md) e [connessione-electrum.md](connessione-electrum.md). ## Topologia ```mermaid flowchart LR Internet -- "80 / 443" --> caddy["container caddy
(TLS, header di sicurezza)"] caddy -- "app:8123" --> app["container app
(FastAPI + 6 attività)"] app -- "Electrum SSL" --> E1["server Electrum
primario"] app -. "rotazione e quorum" .-> E2["server di riserva
(ELECTRUM_FALLBACK_SERVERS)"] app --- db[("./data/db
plm_lottery.db")] app --- keys[("./data/keys
master.xprv.enc")] app --- logs[("./data/logs
app.log")] caddy --- cdata[("volumi Docker
caddy_data, caddy_config")] ``` - **[OPS-01]** Il deployment è composto da due container definiti in `docker-compose.yml`, entrambi con `restart: unless-stopped`: `app` (questo codice, porta 8123 esposta solo sulla rete interna) e `caddy` (reverse proxy sulle porte 80 e 443 dell'host). Il container `app` monta tre cartelle dell'host: `./data/db` su `/app/db_data`, `./data/keys` su `/app/key_data`, `./data/logs` su `/app/logs`; `DATABASE_URL` e `MASTER_KEY_PATH` sono sovrascritti per puntare lì. Caddy tiene certificati e stato ACME nei volumi Docker con nome `caddy_data` e `caddy_config`, non in `./data`. *Codice:* `docker-compose.yml`, `Caddyfile` - **[OPS-02]** All'avvio il container `app` esegue, in quest'ordine: controllo che il file della master key esista (altrimenti esce con errore e un suggerimento del comando da lanciare), `alembic upgrade head`, avvio del server. Durante l'avvio dell'applicazione `validate_runtime_secrets` rifiuta di partire se `JWT_SECRET` è più corto di 32 caratteri o `XPRV_ENCRYPTION_KEY` è vuoto, e `parse_endpoints` rifiuta una voce malformata in `ELECTRUM_FALLBACK_SERVERS`. Un `ADMIN_TOKEN` vuoto non blocca l'avvio: il pannello resta chiuso a tutti. *Codice:* `Dockerfile` (`CMD`), `app/main.py:lifespan`, `app/config.py:validate_runtime_secrets`, `app/electrum/client.py:parse_endpoints` · *Test:* `tests/unit/test_config.py`, `tests/unit/test_electrum_client.py` - **[OPS-03]** Il database SQLite lavora in modalità **WAL**: accanto a `plm_lottery.db` esistono `plm_lottery.db-wal` e `plm_lottery.db-shm`, e le scritture più recenti possono trovarsi solo nel file `-wal`. I tre file vanno sempre trattati insieme. *Codice:* `app/db/base.py:_register_sqlite_pragmas` · *Test:* `tests/unit/test_db_base.py` - **[OPS-04]** `/health` risponde sempre `{"status": "ok"}` finché il processo è vivo: **non** dice nulla sulla connessione Electrum né sullo stato dei round. Non va usato come unico segnale di salute (vedi [Segnali da tenere d'occhio](#segnali-da-tenere-docchio)). *Codice:* `app/main.py:health` ## Backup e ripristino ### Cosa salvare | Cosa | Dove | Quanto spesso | Perché | |---|---|---|---| | Database | `./data/db/plm_lottery.db` (+ `-wal`, `-shm`) | Spesso (almeno giornaliero) | Utenti, indici di derivazione, UTXO, round, prelievi, audit | | Master key cifrata | `./data/keys/master.xprv.enc` | Una volta (non cambia) | Da essa derivano tutti gli indirizzi e il montepremi | | `XPRV_ENCRYPTION_KEY` | `.env` | Una volta, **in un luogo separato** dalla master key | Senza, la master key cifrata è illeggibile | | Altri segreti di `.env` | `.env` | A ogni cambio | `JWT_SECRET`, `ADMIN_TOKEN`, server Electrum | | Stato di Caddy | volume `caddy_data` | Facoltativo | Certificati; Caddy li richiede di nuovo se mancano | - **[OPS-05]** Master key cifrata e `XPRV_ENCRYPTION_KEY` si salvano **in posti diversi**: uno dei due da solo non basta a spendere, entrambi insieme danno il controllo di tutti i fondi. Perderli entrambi significa perdere per sempre i fondi di tutti gli utenti e del montepremi. In alternativa si può conservare offline la xprv in chiaro, ottenuta con `scripts/decrypt_master_key.py`: in quel caso quella copia da sola è la chiave di tutto. *Codice:* `app/wallet/keystore.py:decrypt_xprv`, `scripts/decrypt_master_key.py` - **[OPS-06]** Un backup coerente del database, **senza fermare il server**, si fa con l'API di backup di SQLite, che include il contenuto del file WAL: ```bash docker compose exec app python -c "import sqlite3; s=sqlite3.connect('/app/db_data/plm_lottery.db'); d=sqlite3.connect('/app/db_data/backup.db'); s.backup(d); d.close(); s.close()" # il file compare come ./data/db/backup.db sull'host: spostarlo altrove ``` Copiare a mano il solo `plm_lottery.db` mentre il server gira **non** è un backup affidabile ([OPS-03]). In alternativa: `docker compose stop app`, copiare i tre file, `docker compose start app`, ma quel riavvio ha le conseguenze descritte in [OPS-10]. *Codice:* `app/db/base.py:_register_sqlite_pragmas` ### Ripristino - **[OPS-07]** Procedura di ripristino: 1. `docker compose down`. 2. Rimettere `.env` (con la stessa `XPRV_ENCRYPTION_KEY` usata per cifrare la master key) e `./data/keys/master.xprv.enc`. Se si ha solo la xprv in chiaro, ricifrarla con `scripts/encrypt_master_key.py`. 3. Rimettere il database in `./data/db/plm_lottery.db` e **cancellare** eventuali `-wal`/`-shm` rimasti dall'istanza precedente, che non appartengono al file ripristinato. 4. `docker compose up -d --build`. Le migrazioni si applicano da sole. 5. Controllare in `/admin` lo stato del round attivo e le transazioni pendenti; un round rimasto in `drawing` nel backup va sbloccato con [OPS-13]. All'avvio il riconciliatore delle transazioni e, dopo 300s, il controllo periodico dei depositi riallineano il database alla catena: UTXO spesi dopo il backup vengono segnati come spesi all'esterno (`utxo_spent_externally`), quelli arrivati dopo vengono accreditati. *Codice:* `app/tx/reconcile.py:reconcile_once`, `app/deposits/reconcile.py:DepositReconciler` - **[OPS-08]** **Rischio di un backup vecchio: indirizzi riassegnati.** Il nuovo utente riceve l'indice di derivazione `max(derivation_index) + 1`. Gli utenti registrati dopo il backup spariscono con il ripristino, e i loro indici vengono riassegnati ai prossimi iscritti: il nuovo utente riceve lo **stesso indirizzo** di un utente perso, e con esso i fondi che quello vi aveva depositato. Il codice non ha alcuna protezione contro questo caso, né un modo per sospendere le registrazioni. Dopo un ripristino da un backup non recentissimo, prima di riaprire il servizio, bisogna ricostruire gli utenti mancanti (ad esempio dai log di `POST /auth/register` in `app.log`, se ancora presenti) oppure accettare consapevolmente il rischio. *Codice:* `app/auth/routes.py:register` ## Riavvio Un riavvio avviene a ogni deploy (`docker compose up -d --build`), a ogni modifica di `.env` e da solo dopo un crash (`restart: unless-stopped`). - **[OPS-09]** Al riavvio nessuna attività lavora finché il listener non ha una connessione con un'altezza di catena nota. Poi, a seconda dello stato del round attivo: | Stato al momento del riavvio | Cosa succede | |---|---| | nessun round / `closed` | Si apre un nuovo round rispettando il cooldown del round precedente | | `open` | Riprende: la scadenza è calcolata dai valori salvati sul round | | `closing` | Riprende: si aspetta che le scommesse in volo confermino, poi si estrae | | `drawing` | **Non riprende.** Il round resta in `drawing` per sempre e nessun nuovo round si apre. Serve [OPS-13] | | `paying_out` | Riprende: il pagamento viene ritentato subito se non c'è un `payout_failed` negli ultimi 60s; un pagamento già in volo non viene duplicato | Le transazioni rimaste `building` (crash a metà invio) vengono risolte dal riconciliatore, non prima di 120 secondi dalla loro creazione e al primo passaggio con la connessione attiva (i passaggi sono ogni 120s, e quello "immediato" all'avvio di norma trova la connessione non ancora pronta e viene saltato): promosse se sono in catena, abbandonate altrimenti. Si perdono invece, perché solo in memoria: i blocchi dei login per troppi tentativi e la quota di registrazioni per IP, le connessioni SSE (i browser si riconnettono da soli), i lock per utente. *Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`, `app/rounds/scheduler.py:RoundScheduler._retry_payout_if_due`, `app/tx/reconcile.py:reconcile_once` · *Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_reconcile.py` - **[OPS-10]** **Riavvio sicuro** (deploy, modifica di `.env`, rotazione di un segreto): 1. In `/admin` → Parametri → Manutenzione, "Interrompi dopo questo round" (`POST /admin/pause`). Il round in corso finisce normalmente. 2. Aspettare che `GET /rounds/current` non riporti più un round attivo (`round_id` vuoto) e che in "Transazioni pendenti" non ci siano scommesse o prelievi `building`. 3. Riavviare (`docker compose up -d --build`, oppure `docker compose up -d` per un cambio di `.env`). 4. Controllare in `data/logs/app.log` la riga `Electrum connected to …`, poi "Riprendi lotteria" (`POST /admin/resume`). La pausa non blocca scommesse e prelievi sul round in corso, né registrazioni e depositi. Un riavvio con il round in `open`, `closing` o `paying_out` è comunque sicuro ([OPS-09]); quello da evitare è il riavvio durante `drawing`. *Codice:* `app/api/routes/admin.py:pause_lottery`, `app/rounds/service.py:open_new_round_if_needed` · *Test:* `tests/unit/test_admin.py` ## Procedure di intervento Ogni procedura ha la stessa forma: come si riconosce, perché succede, cosa fare. Per leggere il log: `tail -f data/logs/app.log` sull'host (i messaggi dell'applicazione non compaiono in `docker compose logs`, vedi [audit-log.md](audit-log.md)). ### Electrum irraggiungibile - **[OPS-11]** **Sintomi.** In `/admin` la pillola "Blocco #N" e `chain_tip_height` di `GET /rounds/current` restano fermi sull'ultimo valore noto (l'altezza non si azzera alla disconnessione, quindi *non* si vede un errore, si vede un numero che non cresce). Scommesse e prelievi rispondono 503 `network_unavailable`. Nel log: `Electrum session on … failed`, `Electrum session on … ending`, `all N Electrum server(s) unreachable, retrying in Ns`. Lo scheduler e le altre attività saltano i loro cicli; un round in `drawing` continua ad aspettare e dopo 360s scrive `draw_stalled`. **Causa.** Tutti i server configurati sono giù, irraggiungibili, o rifiutati (un header che non supera la validazione chiude la sessione e fa passare al server successivo). **Cosa fare.** 1. Nessuna azione è necessaria per il ripristino: il listener prova il server successivo subito e, dopo un giro completo di fallimenti, riprova con attesa crescente da 1 a 30 secondi, all'infinito. 2. Verificare la raggiungibilità dal server: `docker compose exec app python scripts/electrum_smoke_test.py` (prova solo il primario, vedi [OPS-26]). 3. Se i server configurati sono davvero tutti inutilizzabili, aggiungerne altri in `ELECTRUM_FALLBACK_SERVERS` (elenco di riferimento: `ChainProfiles.Mainnet.BootstrapServers` del repository PalladiumWallet) e riavviare. **Se un round è in `drawing`, il riavvio lo blocca**: seguire poi [OPS-13]. *Codice:* `app/electrum/listener.py:ElectrumListener.run`, `app/api/routes/bets.py`, `app/api/routes/withdrawals.py` · *Test:* `tests/unit/test_electrum_listener.py` - **[OPS-12]** Con `ELECTRUM_FALLBACK_SERVERS` vuoto la corroborazione passa sempre (non c'è nessuno a cui chiedere), ma un solo server guasto ferma tutto. Con server di riserva configurati ma tutti irraggiungibili, la corroborazione **fallisce**: depositi non accreditati, estrazione che scarta ogni blocco (`draw_header_corroboration_failed`) e segnalazioni di spesa esterna ignorate, anche se il server attivo funziona. In produzione servono almeno due server di riserva raggiungibili. *Codice:* `app/electrum/listener.py:ElectrumListener._corroborate_majority` · *Test:* `tests/unit/test_electrum_listener.py` ### Round bloccato in `drawing` - **[OPS-13]** **Sintomi.** `GET /rounds/current` riporta `status: "drawing"` con `draw_waiting_since` lontano nel tempo; nessun nuovo round si apre. Possibili cause visibili: - righe `draw_stalled` ripetute ogni 6 minuti: l'altezza della catena non sale (Electrum, vedi [OPS-11]); - righe `draw_header_corroboration_failed`, una per blocco: i blocchi arrivano ma gli altri server non li confermano (vedi [OPS-12]); - **nessuna riga nuova e nessun messaggio `still waiting for a block` nel log**: l'attesa non è più in corso. Succede dopo un riavvio del processo, oppure dopo un'eccezione durante l'attesa (messaggio `round scheduler tick failed`, per esempio un database bloccato mentre si scriveva `draw_stalled`). In questo caso il round non si sbloccherà mai da solo. **Causa.** L'attesa del blocco di estrazione vive solo dentro la chiamata dello scheduler che ha portato il round in `drawing`; a ogni ciclo successivo lo scheduler vede `drawing` e non fa nulla. Nessun codice riprende l'attesa. **Cosa fare.** Nei primi due casi basta risolvere la causa (Electrum, server di riserva): l'estrazione avviene da sola al primo blocco valido. Nel terzo caso **non esiste una procedura supportata dal codice**. L'unico intervento possibile è una modifica manuale del database che riporti il round a `closing`, lo stato da cui lo scheduler rifà l'estrazione da capo: 1. Annotare l'id del round (dal pannello, sezione Round) e controllare che sia davvero in `drawing` e che `winner_user_id` sia vuoto. 2. `docker compose stop app`. 3. Aggiornare lo stato: ```bash docker compose run --rm --no-deps app python -c "import sqlite3; c=sqlite3.connect('/app/db_data/plm_lottery.db'); n=c.execute(\"UPDATE rounds SET status='closing' WHERE id= AND status='drawing' AND winner_user_id IS NULL\").rowcount; c.commit(); print(n, 'riga aggiornata')" ``` Deve stampare `1 riga aggiornata`. 4. `docker compose start app`. 5. Al primo ciclo lo scheduler rilegge i partecipanti confermati, riporta il round in `drawing` con un nuovo `drawing_started_at` e aspetta un blocco successivo all'altezza *attuale*; poi estrae e paga normalmente (`winner_drawn`, `payout_sent`). Conseguenze da sapere: l'estrazione usa un blocco successivo al momento dello sblocco invece del primo blocco dopo la chiusura, quindi quale blocco decide il vincitore dipende da quando l'operatore interviene; la modifica non lascia alcuna riga nel registro di audit, quindi va annotata altrove, con data, id del round e motivo. I partecipanti non cambiano: il round è fuori da `open`, quindi nessuna scommessa nuova può entrare. *Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`, `app/rounds/scheduler.py:RoundScheduler._close_and_draw`, `app/rounds/scheduler.py:RoundScheduler._wait_for_next_block` ### Round bloccato in `closing` - **[OPS-14]** **Sintomi.** `GET /rounds/current` riporta `status: "closing"` a lungo, con `has_pending_bets` vero; nel log compare `round N: N bet(s) still in flight at close time, waiting` o nulla (il controllo principale non scrive). In "Transazioni pendenti" c'è almeno una riga `bet` di quel round in `building` o `pending`. **Causa.** Il round non estrae finché ogni scommessa trasmessa non ha una conferma. Una scommessa `pending` che resta nel mempool non viene mai abbandonata dal riconciliatore, che abbandona solo ciò che **non compare** nella cronologia dell'indirizzo: finché il server Electrum la conosce, anche non confermata, il round aspetta. **Cosa fare.** 1. Controllare `attempt_count` e `fee_rate_sat_vb` della riga: il `RbfBumper` alza la commissione di 1 sat/vB ogni `rbf_timeout_seconds` (predefinito 900s) dall'ultimo invio. Se sale, la scommessa confermerà da sola. 2. Se nel log compare `could not bump pending_transaction N`, l'RBF è impossibile: vedi [OPS-17]. 3. Se la riga è `building` da più di 2 minuti, il riconciliatore la risolve al suo prossimo passaggio (ogni 120s). 4. Una transazione che il server non conosce più viene abbandonata dopo 6 ore dal primo invio (`pending_tx_abandoned`); il partecipante viene rimosso e il round può chiudere. *Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`, `app/tx/broadcast.py:RbfBumper`, `app/tx/reconcile.py:_is_due` · *Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_broadcast.py`, `tests/unit/test_reconcile.py` ### Round bloccato in `paying_out` - **[OPS-15]** **Sintomi.** `status: "paying_out"` a lungo e, nel registro di audit, righe `payout_failed` dello stesso round, al massimo una al minuto. Il campo `reason` dice il motivo. Lo scheduler riprova da solo ogni 60 secondi: una volta rimossa la causa, il pagamento parte al tentativo successivo senza altri interventi. | `reason` | Cosa fare | |---|---| | `electrum client not connected` | Vedi [OPS-11]. Si risolve da sola al ritorno della connessione | | `no fee_address configured` | Impostare `fee_address` in `/admin` → Parametri. Succede solo se è stato svuotato a round in corso | | `winner user not found` | Possibile solo se la riga dell'utente è stata cancellata a mano dal database. Nessuna procedura supportata: ripristinare la riga | | `insufficient pool UTXOs` | Vedi sotto | | `too_many_inputs` | Il pagamento richiederebbe più di 500 UTXO del montepremi (resti accumulati in molti round). Serve consolidare gli UTXO del montepremi con la sua chiave: **nessuno strumento lo fa**, vedi [OPS-24] | | `winner_share_below_network_fee` | Il montepremi è troppo piccolo per la commissione di rete. Abbassare `fee_rate_sat_vb`; se è già 1, nessuna procedura supportata | | `commission_below_dust_limit` | Il 30% è sotto 294 sat (montepremi sotto circa 1.000 sat, solo con un costo della scommessa minuscolo). Nessuna procedura supportata | | `payout build failed` | Leggere la traccia nel log (`round N payout build failed`) | | `broadcast rejected` | Si risolve da sola: la riga `building` viene abbandonata dal riconciliatore entro 2–4 minuti, `payout_txid` si azzera e il pagamento viene ricostruito. Se si ripete, la rete rifiuta la transazione: controllare il messaggio nel log e `fee_rate_sat_vb` | **`insufficient pool UTXOs`.** Il pagamento usa solo gli UTXO **confermati** dell'indirizzo del montepremi, escludendo quelli già riservati da un altro pagamento `building` o `pending` non risolto. Controllare in "Transazioni pendenti" se c'è un `payout` di un round precedente ancora aperto: finché resta tale, i suoi input sono esclusi. L'indirizzo del montepremi non è mostrato dal pannello; si ottiene con `docker compose exec app python -c "from app.wallet.hd import derive_pool_address; print(derive_pool_address())"` e se ne può controllare il saldo con un explorer. Un pagamento già in volo (riga `payout` `building` o `pending` del round) non viene mai duplicato: finché esiste, i tentativi vengono saltati senza scrivere `payout_failed` e il round aspetta la conferma o l'abbandono. *Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout`, `app/rounds/scheduler.py:RoundScheduler._retry_payout_if_due`, `app/rounds/scheduler.py:_reserved_payout_outpoints` · *Test:* `tests/unit/test_scheduler.py` ### Transazione abbandonata - **[OPS-16]** **Sintomi.** Riga `pending_tx_abandoned` nel registro di audit; nel log `abandoned pending_transaction …`; la riga in "Transazioni pendenti" passa a `failed`. **Causa.** La transazione non compare più nella cronologia del proprio indirizzo: mai partita (riga `building` da oltre 120s) o scomparsa dal mempool (riga `pending` da oltre 6 ore dal primo invio). **Effetto e cosa fare.** Il sistema ha già annullato tutto: UTXO liberati e saldo ricalcolato; per una scommessa il partecipante è rimosso (l'utente può riscommettere se il round è ancora aperto); per un prelievo la richiesta è `failed` e l'utente, che non vede lo storico, va avvisato di ripeterla; per un pagamento `payout_txid` è azzerato e il nuovo tentativo parte da solo. Se gli abbandoni sono frequenti, la commissione di rete configurata è probabilmente troppo bassa. *Codice:* `app/tx/reconcile.py:_abandon` · *Test:* `tests/unit/test_reconcile.py` ### RBF impossibile - **[OPS-17]** **Sintomi.** Nel log, ogni 30 secondi per la stessa riga, `could not bump pending_transaction N` con un `RbfError`: "no change output large enough to absorb a fee bump" oppure "already at the maximum fee rate". Nessuna riga di audit. `attempt_count` smette di salire. **Causa.** L'RBF riduce solo il resto che torna al mittente; se il resto non basta a coprire l'aumento, o la commissione è già al massimo (10.000 sat/vB), non si può fare. **Cosa fare.** Nessuna procedura supportata. La transazione resta in attesa alla commissione che ha: conferma da sola quando il mempool si svuota, oppure, se sparisce dal mempool, viene abbandonata dopo 6 ore ([OPS-16]). Se blocca un round in `closing` ([OPS-14]), l'alternativa manuale è spendere il resto non confermato con una commissione alta (CPFP) usando la chiave dell'utente ([OPS-23]); il sistema accrediterà l'uscita della nuova transazione come un normale deposito. *Codice:* `app/tx/broadcast.py:bump_fee`, `app/tx/broadcast.py:RbfBumper._tick` · *Test:* `tests/unit/test_broadcast.py` ### Deposito non accreditato - **[OPS-18]** **Sintomi.** Un utente segnala un deposito che non vede nel saldo. **Cause, in ordine di probabilità.** 1. La transazione non ha ancora 1 conferma: il deposito non viene mostrato nemmeno come "in attesa" finché non è in un blocco. 2. La corroborazione fallisce: nel log `N new UTXO(s) for user_id=… not corroborated by the other servers` e spesso `could not corroborate … with any of N other configured server(s)`. Vedi [OPS-12]. 3. La sottoscrizione dell'indirizzo si è persa (log `could not subscribe a newly-registered user's address` o `resubscribing all users failed partway through`). 4. Electrum irraggiungibile ([OPS-11]). **Cosa fare.** Verificare con un explorer che la transazione sia confermata e paghi esattamente l'indirizzo dell'utente (sezione Utenti del pannello). Poi aspettare: `DepositReconciler` ricontrolla ogni indirizzo ogni 300 secondi e accredita tutto ciò che il quorum conferma, indipendentemente dalle notifiche. Un riavvio risottoscrive tutti gli indirizzi, ma non serve e va fatto con [OPS-10]. Ogni accredito lascia una riga `deposit_credited`. *Codice:* `app/electrum/listener.py:ElectrumListener.refresh_user`, `app/deposits/reconcile.py:DepositReconciler._sweep_once` · *Test:* `tests/unit/test_electrum_listener.py`, `tests/unit/test_deposit_reconcile.py` ### Utente bloccato fuori - **[OPS-19]** **Password dimenticata.** In `/admin` → Utenti → "Reset": viene generata una nuova password casuale, mostrata una sola volta, da comunicare all'utente per un canale di cui ci si fida (non esiste un'email). Tutte le sessioni esistenti dell'utente vengono invalidate. Resta la riga `admin_password_reset`. Verificare l'identità di chi chiede: chi riceve la password controlla i fondi. **Troppi tentativi.** Dopo 5 login falliti sullo stesso username (20 dallo stesso IP) ogni ulteriore errore impone un'attesa che parte da 2 secondi e raddoppia fino a 300; il contatore si azzera dopo 15 minuti senza errori o al primo login riuscito. Basta aspettare; un riavvio azzera tutti i contatori ma non è necessario. *Codice:* `app/api/routes/admin.py:reset_user_password`, `app/auth/rate_limit.py:AuthRateLimiters` · *Test:* `tests/unit/test_admin.py`, `tests/unit/test_rate_limit.py` ### Segreto compromesso - **[OPS-20]** **`ADMIN_TOKEN` trapelato.** Chi lo possiede può esportare la chiave privata di qualunque utente, cambiare `fee_address`, resettare password e mettere in pausa la lotteria. 1. Generare un nuovo token (`python -c "import secrets; print(secrets.token_urlsafe(32))"`), scriverlo in `.env` e riavviare ([OPS-10], ma senza aspettare la fine del round se l'urgenza lo richiede ed evitando solo lo stato `drawing`). Il vecchio token smette di funzionare subito; gli operatori rientrano nel pannello con quello nuovo. 2. Nel registro di audit cercare, dal momento presunto della fuga: `admin_privkey_accessed` (quali chiavi sono uscite), `config_updated` (soprattutto `fee_address`), `admin_password_reset` (account presi), e per quegli utenti `withdrawal_sent`. 3. **La chiave di un utente esportata resta compromessa per sempre**: l'indirizzo di un utente è permanente e il codice non ha un modo per assegnargliene un altro. L'unica difesa è spostare subito i fondi di quell'indirizzo ([OPS-23]) e avvisare l'utente di non depositarvi più. *Codice:* `app/api/routes/admin.py:require_admin` - **[OPS-21]** **`JWT_SECRET` trapelato.** Chi lo possiede può fabbricare una sessione valida per qualunque utente e quindi scommettere o prelevarne i fondi. Generare un nuovo segreto di almeno 32 caratteri, scriverlo in `.env` e riavviare: **tutte** le sessioni esistenti diventano invalide e ogni utente deve rifare il login. Poi controllare `withdrawal_sent` nel registro di audit per prelievi inattesi. Per invalidare le sessioni di un solo utente basta invece un reset della sua password ([OPS-19]). *Codice:* `app/auth/security.py:decode_access_token`, `app/config.py:validate_runtime_secrets` - **[OPS-22]** **Rotazione di `XPRV_ENCRYPTION_KEY`** (la master key non cambia, cambia solo la sua cifratura): 1. `PYTHONPATH=. python scripts/decrypt_master_key.py` con la chiave vecchia in `.env`, e conservare la xprv stampata solo per il tempo necessario. 2. Generare la chiave nuova (`python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`) e scriverla in `.env`. 3. `PYTHONPATH=. python scripts/encrypt_master_key.py --overwrite` e incollare la xprv. 4. Riavviare ([OPS-10]) e aggiornare i backup ([OPS-05]). **Se è trapelata la master key stessa** (file cifrato *e* chiave, oppure la xprv in chiaro), sono a rischio tutti i fondi degli utenti e del montepremi. Non esiste una procedura supportata per passare a una nuova master key: ogni indirizzo, compreso quello del montepremi, deriva da essa, e cambiarla cambierebbe tutti gli indirizzi senza spostare i fondi né aggiornare il database. *Codice:* `app/wallet/keystore.py:encrypt_xprv`, `app/wallet/hd.py:_load_account_key` ### Intervento manuale sui fondi - **[OPS-23]** **Spostare i fondi di un utente con la sua chiave privata.** Serve per restituire fondi bloccati, per un CPFP ([OPS-17]) o dopo una fuga della chiave ([OPS-20]). 1. In "Transazioni pendenti" verificare che l'utente non abbia scommesse o prelievi `building`/`pending`: i loro input sono già impegnati e spenderli altrove crea un conflitto che fa fallire una delle due transazioni. 2. Per evitare che l'utente agisca nel frattempo, si può resettarne la password ([OPS-19]), che chiude le sue sessioni. 3. `/admin` → Utenti → "Mostra" (riga `admin_privkey_accessed`). La chiave WIF va importata in un portafoglio PLM (per esempio PalladiumWallet), mai salvata altrove. 4. Inviare i fondi dove serve. 5. Quando la spesa è confermata, il listener vede gli UTXO scomparire, chiede conferma agli altri server e li segna come spesi all'esterno (`utxo_spent_externally`): il saldo nel database scende da solo. Nulla va modificato a mano. **Restituire fondi a un utente** non richiede chiavi: si inviano al suo indirizzo e vengono accreditati come un deposito (`deposit_credited`). *Codice:* `app/api/routes/admin.py:user_privkey`, `app/deposits/service.py:mark_utxos_spent_externally` - **[OPS-24]** **Fondi del montepremi.** La chiave del montepremi (`m/84'/746'/0'/1/0` della master key) non è esportabile dal pannello né da alcuno script: l'unico modo è derivarla a mano dalla xprv ottenuta con `scripts/decrypt_master_key.py`. Non c'è quindi una procedura supportata per consolidare gli UTXO del montepremi (`too_many_inputs`) o per recuperare resti accumulati. Spendere UTXO del montepremi fuori dal sistema non è rilevato come spesa esterna (l'indirizzo non è in `utxo_events`) e può far fallire il pagamento di un round in corso (`insufficient pool UTXOs` o una trasmissione rifiutata): farlo solo senza round in `paying_out`. *Codice:* `app/wallet/hd.py:derive_pool_key`, `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ## Segnali da tenere d'occhio - **[OPS-25]** Non esiste un sistema di allarmi: i segnali vanno controllati a mano o con uno strumento esterno che interroghi l'API e legga il log. | Segnale | Dove | Allarme se | |---|---|---| | Altezza della catena | `chain_tip_height` in `GET /rounds/current` | Non cresce per più di ~10 minuti (blocchi ogni 120s): Electrum giù ([OPS-11]) | | Stato e durata del round | `status`, `closes_at`, `draw_waiting_since` in `GET /rounds/current` | `closing` o `paying_out` per più di qualche blocco; `drawing` oltre 6 minuti ([OPS-13]–[OPS-15]) | | Istanza configurata | `lottery_configured` in `GET /rounds/current` | `false`: manca `fee_address`, nessun round si apre | | Pausa dimenticata | `lottery_paused` in `GET /rounds/current` | `true` fuori da una manutenzione | | Pagamenti ed estrazioni | Audit: `payout_failed`, `draw_stalled`, `draw_header_corroboration_failed` | Qualunque occorrenza | | Transazioni perse | Audit: `pending_tx_abandoned` | Frequenti: commissione troppo bassa | | Spese esterne | Audit: `utxo_spent_externally` | Non dovute a un intervento dell'operatore: chiave dell'utente compromessa o server che mente | | Uso del pannello | Audit: `admin_privkey_accessed`, `config_updated`, `admin_password_reset` | Non attribuibili a un operatore: `ADMIN_TOKEN` compromesso ([OPS-20]) | | Transazioni lente | `/admin` → Transazioni pendenti | `attempt_count` alto o `broadcast_at` vecchio di ore | | Log | `data/logs/app.log` | `all N Electrum server(s) unreachable`, `round scheduler tick failed`, `could not bump`, `invariant violated` | | Disco | `./data/db`, `./data/logs` | Il database cresce senza limite (registro di audit incluso); i log ruotano a 6 × 10 MB | *Codice:* `app/api/routes/rounds.py`, `app/api/routes/admin.py`, `app/logging_config.py:setup_logging` ## Script manuali Si lanciano dal venv sull'host (`source .venv/bin/activate`, con `PYTHONPATH=.`) oppure nel container con `docker compose run --rm app python scripts/.py`. Nel container `MASTER_KEY_PATH` punta a `/app/key_data/master.xprv.enc`, cioè allo stesso file `./data/keys` dell'host; dal venv conta il `MASTER_KEY_PATH` di `.env`. - **[OPS-26]** Gli script disponibili: | Script | Cosa fa | Quando | |---|---|---| | `scripts/generate_master_key.py` | Crea una master key casuale, la cifra con `XPRV_ENCRYPTION_KEY` e la scrive in `MASTER_KEY_PATH`. Si rifiuta se il file esiste già | Una sola volta, alla prima installazione ([setup.md](setup.md)) | | `scripts/encrypt_master_key.py` | Cifra una xprv incollata (input nascosto) e la scrive in `MASTER_KEY_PATH`, con ripiego su `./data/keys/` se la cartella di `MASTER_KEY_PATH` non esiste. Rifiuta una xpub e un file già presente senza `--overwrite` | Installazione con una xprv generata altrove; ripristino da xprv in chiaro ([OPS-07]); rotazione della cifratura ([OPS-22]) | | `scripts/decrypt_master_key.py` | Decifra e stampa la xprv, dopo aver chiesto di scrivere `yes`. Cerca il file in `MASTER_KEY_PATH`, poi in `./data/keys/master.xprv.enc` | Backup offline ([OPS-05]), rotazione ([OPS-22]), recupero dei fondi del montepremi ([OPS-24]) | | `scripts/electrum_smoke_test.py` | Si collega **solo** al server primario (`ELECTRUM_HOST`/`PORT`/`USE_SSL`), fa l'handshake, si iscrive agli header e stampa l'altezza | Diagnosi di [OPS-11]. Per provare un server di riserva, lanciarlo con `ELECTRUM_HOST`/`ELECTRUM_PORT` impostati su quel server | `generate_master_key.py` non ha il ripiego su `./data/keys/` degli altri due: dal venv scrive esattamente dove dice `MASTER_KEY_PATH` di `.env`. *Codice:* `scripts/generate_master_key.py`, `app/wallet/hd.py:generate_master_key`, `scripts/encrypt_master_key.py`, `scripts/decrypt_master_key.py`, `scripts/electrum_smoke_test.py`