plm-lottery/docs/operativita.md

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, i comandi Docker di tutti i giorni in running-the-server.md, l'uso del pannello in 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. Il funzionamento interno che spiega perché un round si blocca è in ciclo-di-vita-del-round.md, transazioni-e-riconciliazione.md e connessione-electrum.md.

Topologia

flowchart LR
    Internet -- "80 / 443" --> caddy["container caddy<br/>(TLS, header di sicurezza)"]
    caddy -- "app:8123" --> app["container app<br/>(FastAPI + 6 attività)"]
    app -- "Electrum SSL" --> E1["server Electrum<br/>primario"]
    app -. "rotazione e quorum" .-> E2["server di riserva<br/>(ELECTRUM_FALLBACK_SERVERS)"]
    app --- db[("./data/db<br/>plm_lottery.db")]
    app --- keys[("./data/keys<br/>master.xprv.enc")]
    app --- logs[("./data/logs<br/>app.log")]
    caddy --- cdata[("volumi Docker<br/>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). 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:

  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).

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:

     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=<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 <tipo> 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/<nome>.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)
  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