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.

Procedure e requisiti. Le procedure (i passi numerati) descrivono cosa fare con il codice di oggi; dove una correzione in corso le cambierà, una nota "Dopo B-nn" dice come. I requisiti marcati da implementare descrivono invece il comportamento atteso, non ancora presente (vedi processo-di-modifica.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

Oggi il container gira come root, e i file che scrive in ./data (database, backup, chiave cifrata dagli script) appartengono a root sull'host. Dopo B-91 gira come utente non root, con ./data in 0700 e i file di chiave in 0600, e la chiave di cifratura sta in un file a parte (architettura.md ARC-03, ARC-05; SEC-51); le procedure che scrivono in ./data dovranno allora rispettare quel proprietario.

• [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 il server rifiuta di servire se un segreto non è valido (SEC-12), se la master key non si decifra o non corrisponde agli indirizzi già salvati (SEC-49), se una voce di ELECTRUM_FALLBACK_SERVERS è malformata (parse_endpoints) o se il quorum minimo non è configurato ([OPS-12]). Un ADMIN_TOKEN vuoto non blocca l'avvio: il pannello resta chiuso a tutti. Un rifiuto termina il processo; con restart: unless-stopped il container riparte e fallisce di nuovo, quindi il sintomo è un container che si riavvia in continuazione, con il motivo nell'output di docker compose logs app. Codice: Dockerfile (CMD), app/main.py:lifespan, app/config.py:validate_runtime_secrets, app/electrum/client.py:parse_endpoints, app/wallet/hd.py:_load_account_key · Test: tests/unit/test_config.py, tests/unit/test_electrum_client.py Stato: da implementare (B-89, B-84) · Oggi: della master key si controlla solo che il file esista e che XPRV_ENCRYPTION_KEY non sia vuota; una chiave sbagliata emerge alla prima derivazione, e il server parte anche senza server di riserva.

• [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

Dopo B-92 esiste anche GET /health/ready, che risponde 503 se la connessione Electrum manca, l'ultimo header è vecchio o lo scheduler non gira (api.md API-46), ed è il healthcheck del container (architettura.md ARC-61). Un container unhealthy non viene riavviato da Docker: è un segnale per l'operatore ([OPS-25]), da trattare con [OPS-11] o [OPS-13].

Backup e ripristino

Cosa salvare

Cosa	Dove	Quanto spesso	Perché
Database	./data/db/plm_lottery.db (+ -wal, -shm)	Spesso (almeno giornaliero) e prima di ogni deploy	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, SITE_ADDRESS
Stato di Caddy	volume caddy_data	Facoltativo	Certificati; Caddy li richiede di nuovo se mancano

Il file da salvare è ./data/keys/master.xprv.enc, quello che il container legge. Su questa installazione esiste anche una seconda copia, ./master.xprv.enc nella radice del progetto, a cui punta il MASTER_KEY_PATH di .env (B-71): oggi decifrano alla stessa xprv, ma non è il file dell'app. Dopo B-91 la chiave di cifratura non sta più in .env ma nel file ./secrets/xprv_encryption.key (SEC-53, architettura.md ARC-05), fuori da ./data/: si salva come oggi la variabile, separata dalla master key.

• [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. Dopo B-73 la stessa chiave protegge anche il segreto dell'estrazione dei round aperti (sicurezza.md SEC-56): è un motivo in più per non conservarla insieme ai backup del database ([OPS-06]). 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]. Oggi il file di backup appartiene a root sull'host (Topologia). Codice: app/db/base.py:_register_sqlite_pragmas

Ripristino

Un database ripristinato è indietro rispetto alla catena: round già estratti e pagati risultano ancora aperti, scommesse e prelievi fatti dopo il backup non esistono, utenti registrati dopo il backup sono spariti. La procedura serve a impedire che il sistema rigiochi quel passato con il denaro di oggi.

• [OPS-07] Procedura di ripristino:

  1. docker compose down. Il pubblico non deve raggiungere l'app finché la procedura non è finita: caddy si riavvia solo al passo 10.
  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 lanciato nel container (vedi [OPS-22], passo 0, per il perché).
  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. Mettere in pausa la lotteria nel database ripristinato, prima di avviare l'app (il valore di paused è quello del backup):

     docker compose run --rm --no-deps app python -c "import sqlite3; c=sqlite3.connect('/app/db_data/plm_lottery.db'); c.execute('UPDATE round_config SET paused=1'); c.commit(); print('pausa impostata')"
     

     La modifica non lascia una riga di audit: annotarla altrove. Dopo B-90 si usa invece START_PAUSED=true in .env ([OPS-27]), che scrive anche il motivo della pausa e la riga di audit.
  5. Elencare, sempre ad app ferma, i round non chiusi e le transazioni in volo del backup:

     docker compose run --rm --no-deps app python -c "import sqlite3; c=sqlite3.connect('/app/db_data/plm_lottery.db'); print('ROUND'); [print(r) for r in c.execute(\"SELECT id,status,winner_user_id,payout_txid FROM rounds WHERE status!='closed'\")]; print('PENDING'); [print(r) for r in c.execute(\"SELECT id,kind,status,round_id,current_txid FROM pending_transactions WHERE status IN ('building','pending')\")]"
     

     e, per ogni round trovato, i partecipanti (SELECT user_id,status,bet_txid FROM round_participants WHERE round_id=<ID>, con lo stesso comando).
  6. Confrontare ogni round non chiuso con la catena, con un explorer, prima di avviare l'app. È necessario perché la pausa ferma solo l'apertura di round nuovi: appena c'è connessione, un round del backup in open, closing o paying_out riprende da solo, chiude, estrae e paga ([OPS-09]). Oggi tutti i round usano lo stesso indirizzo del montepremi (derive_pool_address, vedi [OPS-15]), quindi un pagamento rifatto spenderebbe il denaro dei round successivi. Per ogni round:
     • si guardano le uscite delle sue scommesse verso l'indirizzo del montepremi (i bet_txid dei partecipanti) e, se c'è, payout_txid;
     • se una di quelle uscite è già spesa, o payout_txid è confermato, il round è già stato pagato dopo il backup. Va chiuso a mano, e ogni sua riga payout ancora building/pending va segnata failed, altrimenti il riconciliatore la abbandonerebbe e lo scheduler ricostruirebbe il pagamento:

       docker compose run --rm --no-deps app python -c "import sqlite3; c=sqlite3.connect('/app/db_data/plm_lottery.db'); print(c.execute(\"UPDATE rounds SET status='closed', closed_at=CURRENT_TIMESTAMP WHERE id=<ID> AND status!='closed'\").rowcount, 'round'); print(c.execute(\"UPDATE pending_transactions SET status='failed', failure_reason='restore: round already paid' WHERE kind='payout' AND round_id=<ID> AND status IN ('building','pending')\").rowcount, 'payout'); c.commit()"
       

       Unica eccezione: se payout_txid della riga pending è proprio la transazione confermata, non serve toccare nulla, perché il ConfirmationPoller chiude il round da sé;
     • se tutte le uscite sono ancora non spese, il round non è stato pagato e può riprendere. I giocatori che hanno scommesso su quel round dopo il backup non sono tra i partecipanti, ma i loro soldi sono nel montepremi: annotarli per un rimborso manuale (nessuna procedura supportata, vedi [OPS-24]);
     • un round in drawing non va mai sbloccato con [OPS-13] prima di questo controllo: se è già stato pagato, va chiuso come sopra. Annotare ogni modifica (data, id, motivo): nessuna lascia una riga di audit.
  7. Controllare gli indirizzi riassegnabili con [OPS-28], sempre ad app ferma.
  8. Avviare solo l'app: docker compose up -d --build app (il servizio caddy resta fermo). Le migrazioni si applicano da sole.
  9. In data/logs/app.log aspettare Electrum connected to …. Alla connessione il listener risottoscrive e aggiorna subito ogni utente (ELC-18), senza aspettare il giro di 300 secondi di DepositReconciler: gli UTXO spesi dopo il backup (scommesse e prelievi persi dal database) vengono segnati come spesi all'esterno (utxo_spent_externally), quelli arrivati dopo vengono accreditati (deposit_credited). Il riconciliatore risolve le righe building/pending del backup al suo primo passaggio con la connessione attiva. Controllare il registro di audit e "Transazioni pendenti".
  10. docker compose up -d (riavvia caddy) e "Riprendi lotteria".

  Il rischio di replay. Il riallineamento dei saldi è automatico e immediato; quello dei round no. Ogni round del backup non ancora closed riprende da solo appena c'è connessione, anche con la lotteria in pausa, e ogni scommessa fatta dopo il backup è persa come partecipazione (il suo UTXO risulta speso all'esterno, i suoi soldi sono nel montepremi). I passi 4–6 esistono per questo e vanno eseguiti prima del passo 8. Dopo B-80 e B-82 un round rigiocato paga solo gli UTXO del proprio indirizzo, dopo averli verificati sulla rete, e resta quindi non pagabile invece di essere pagato due volte; il controllo del passo 6 resta comunque il modo di sapere quali round del backup sono già conclusi. Codice: app/rounds/scheduler.py:RoundScheduler._tick, app/tx/reconcile.py:reconcile_once, app/electrum/listener.py:ElectrumListener._subscribe_all_users

• [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. Oggi il codice non ha alcuna protezione: l'unica è la procedura [OPS-28]. Dopo B-90 l'app controlla da sola gli indici successivi e sospende le registrazioni (REG-15); la procedura resta il modo di rimuovere la sospensione. Gli utenti persi non si possono ricostruire dai log: app.log non registra né username né indice di una registrazione, e il log di accesso riporta l'indirizzo di Caddy, non quello del client. Codice: app/auth/routes.py:register

• [OPS-27] Con START_PAUSED=true in .env l'app, all'avvio e prima che lo scheduler faccia il suo primo ciclo, mette in pausa la lotteria come una pausa dell'operatore (paused_reason = 'operator', senza sovrascrivere un motivo automatico già presente, modello-dati.md B-85) e scrive lottery_paused; la pausa resta finché l'operatore non la toglie ("Riprendi lotteria"). Con il valore predefinito false l'avvio non tocca la pausa. Codice: app/config.py:Settings, app/main.py:lifespan, app/rounds/service.py:open_new_round_if_needed · Test: — Stato: da implementare (B-90) · Oggi: la variabile non esiste; la pausa si imposta a mano nel database (passo 4 di [OPS-07]).

• [OPS-28] Occupare gli indici di utenti persi. Procedura, ad app ferma, valida oggi e dopo B-90:

  1. Trovare il massimo indice assegnato e ricavare gli indirizzi dei 20 indici successivi:

     docker compose run --rm --no-deps app python -c "import sqlite3; from app.wallet.hd import derive_user_address; M=sqlite3.connect('/app/db_data/plm_lottery.db').execute('SELECT COALESCE(MAX(derivation_index),-1) FROM users').fetchone()[0]; print('max', M); [print(i, derive_user_address(i)) for i in range(M+1, M+21)]"
     

  2. Controllare con un explorer quali hanno una cronologia. Se ne ha uno fra gli ultimi della lista, ripetere il passo 1 partendo dal più alto con cronologia.
  3. Se nessuno ha cronologia, non c'è nulla da fare. Altrimenti inserire un account segnaposto per ogni indice da max + 1 fino al più alto con cronologia (compresi quelli senza cronologia in mezzo, perché gli indici si assegnano in ordine):

     docker compose run --rm --no-deps app python -c "import sqlite3, secrets; from datetime import datetime, timezone; from app.auth.security import hash_password; from app.wallet.hd import derive_user_address; c=sqlite3.connect('/app/db_data/plm_lottery.db'); A, B = <DA>, <A>; [c.execute('INSERT INTO users (username, password_hash, derivation_index, address, cached_balance_sats, token_version, created_at) VALUES (?, ?, ?, ?, 0, 0, ?)', ('restore-%d' % i, hash_password(secrets.token_urlsafe(32)), i, derive_user_address(i), datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M:%S.%f'))) for i in range(A, B + 1)]; c.commit(); print(B - A + 1, 'segnaposto')"
     

     La password casuale non viene mostrata a nessuno: l'account non è utilizzabile finché l'operatore non lo consegna. L'inserimento non lascia una riga di audit: annotarlo altrove.
  4. All'avvio il listener si iscrive anche agli indirizzi segnaposto e accredita i loro fondi. Quando un utente perso si presenta e dimostra di conoscere il proprio indirizzo, gli si consegna il segnaposto corrispondente con un reset della password ([OPS-19]).

  Dopo B-90 il controllo automatico di REG-15, al riavvio successivo, non trova più indirizzi usati oltre i segnaposto e le registrazioni riprendono. Codice: app/wallet/hd.py:derive_user_address, app/auth/security.py:hash_password, app/db/models.py:User

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	Riprende l'attesa dello stesso blocco di estrazione, con gli stessi partecipanti, e produce lo stesso vincitore (ciclo-di-vita-del-round.md, B-81)
  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 secondo le regole di transazioni-e-riconciliazione.md (B-78): promosse se in catena, abbandonate solo con una prova. Si perdono invece, perché solo in memoria: i blocchi dei login per troppi tentativi e le quote 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 Stato: da implementare (B-81, B-78) · Oggi: un round in drawing non riprende: resta in drawing per sempre e nessun nuovo round si apre (serve [OPS-13]); una riga building non trovata nella cronologia del server attivo viene abbandonata dopo 120 secondi dalla creazione, al primo passaggio del riconciliatore (ogni 120s) con la connessione attiva.

• [OPS-10] Riavvio sicuro e deploy (nuova versione, modifica di .env, rotazione di un segreto):

  1. Backup del database ([OPS-06]), copiato fuori dall'host. Annotare la versione in uso (git rev-parse HEAD) e la revisione del database (docker compose exec app alembic current): servono per un rollback ([OPS-29]).
  2. Verificare che SITE_ADDRESS sia scritto in .env (grep '^SITE_ADDRESS=' .env). Se è stato passato solo sulla riga di comando (SITE_ADDRESS=… docker compose up -d), un semplice docker compose up -d --build lo perde e Caddy torna a localhost con un certificato autofirmato: il sito pubblico smette di funzionare.
  3. In /admin → Parametri → Manutenzione, "Interrompi dopo questo round" (POST /admin/pause). Il round in corso finisce normalmente.
  4. Aspettare che GET /rounds/current non riporti più un round attivo (round_id vuoto, cioè l'ultimo round è closed) e che in "Transazioni pendenti" non ci siano righe building (la sezione elenca anche righe già confermate o fallite: guardare la colonna Stato).
  5. Riavviare (docker compose up -d --build, oppure docker compose up -d per un cambio di .env).
  6. Controllare in data/logs/app.log la riga Electrum connected to …, poi "Riprendi lotteria" (POST /admin/resume).

  Perché aspettare closed e non solo la pausa. Oggi l'arresto non è pulito: con uno stream SSE aperto (basta una pagina / aperta) uvicorn aspetta che si chiuda, e Docker uccide il processo dopo 10 secondi. Ogni deploy è quindi, per il codice, un crash: durante drawing blocca il round ([OPS-13]), durante un invio lascia una riga building. Dopo B-93 l'arresto chiude gli stream e le attività entro 30 secondi; il riavvio durante drawing diventa sicuro con B-81 ([OPS-09]).

  La pausa non blocca scommesse e prelievi sul round in corso, né registrazioni e depositi. Codice: app/api/routes/admin.py:pause_lottery, app/rounds/service.py:open_new_round_if_needed · Test: tests/unit/test_admin.py

Dopo B-93 lo spegnimento chiude gli stream SSE e attende le attività, entro stop_grace_period: 30s (architettura.md ARC-22); ogni rilascio ha un'immagine con un tag di versione e SITE_ADDRESS è obbligatorio in .env: senza, docker compose rifiuta di partire invece di ripiegare su localhost (architettura.md ARC-01, ARC-05).

• [OPS-29] Rollback a una versione precedente. Un'immagine vecchia non parte su un database con migrazioni più nuove: il suo alembic upgrade head non riconosce la revisione del database e il container esce, e si riavvia in continuazione. Il database va quindi riportato indietro con l'immagine nuova, prima di cambiare versione:

  1. Pausa e attesa di closed come in [OPS-10], poi backup ([OPS-06]).
  2. Trovare la revisione di destinazione: nella versione a cui si torna, dal venv, alembic heads (legge solo i file di migrazione, non il database).
  3. docker compose stop app, poi, con l'immagine nuova ancora in uso, docker compose run --rm --no-deps app alembic downgrade <revisione>.
  4. git checkout <versione> e docker compose up -d --build.
  5. Controllare il log e riprendere la lotteria.

  Un downgrade cancella le colonne e le tabelle aggiunte dalle migrazioni annullate, con i loro dati. Se un downgrade fallisce, si ripristina il backup del passo 1 di [OPS-10] con [OPS-07], perdendo ciò che è successo dopo il deploy. Dopo B-93 il passo 4 usa il tag dell'immagine precedente invece di ricostruirla. Codice: migrations/, Dockerfile (CMD)

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 (scheduler, listener, riconciliatori) sono solo in quel file; docker compose logs app mostra soltanto l'output di avvio del container (controllo della chiave, migrazioni) e ciò che uvicorn scrive per conto suo (avvio, richieste, errori di avvio). Vedi audit-log.md.

Dopo B-92 il log applicativo va anche sull'output del container e si legge con docker compose logs app (architettura.md ARC-09).

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). Due casi diversi:

  • server irraggiungibili: 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;
  • server connesso ma fermo: nessun errore nel log, l'ultima riga di connessione è Electrum connected to <server>, ping riesce, ma l'altezza non cresce mentre un explorer o un altro server riportano blocchi nuovi. Scommesse e prelievi vengono accettati, ma nulla conferma.

  In entrambi i casi un round in drawing continua ad aspettare e dopo 360s scrive draw_stalled. Causa. Nel primo caso 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). Nel secondo il server attivo ha smesso di seguire la catena: il listener lo rileva solo se la connessione cade. Cosa fare.

  1. Server irraggiungibili: 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. Se un server torna, la connessione si ristabilisce da sola.
  2. Server fermo: il ripristino non è automatico. Un riavvio riparte sempre dal primario (ELECTRUM_HOST), quindi aiuta solo se il server fermo è una riserva. Se il fermo è il primario, in .env sostituirlo con un server che funziona (spostandolo tra le riserve o togliendolo) e riavviare con [OPS-10]. Dopo B-86 il listener cambia server da solo quando la punta non avanza da 360s e un altro server ne riporta una più alta (ELC-21).
  3. Verificare un server dal container, senza toccare quello in esecuzione: docker compose run --rm --no-deps -e ELECTRUM_HOST=<host> -e ELECTRUM_PORT=<porta> app python scripts/electrum_smoke_test.py (senza -e prova il primario, vedi [OPS-26]). L'altezza stampata si confronta con quella di GET /rounds/current.
  4. 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, oggi il riavvio lo blocca: seguire poi [OPS-13]. Codice: app/electrum/listener.py:ElectrumListener.run, app/electrum/listener.py:ElectrumListener._keepalive, app/api/routes/bets.py, app/api/routes/withdrawals.py · Test: tests/unit/test_electrum_listener.py

• [OPS-12] Le regole del quorum sono di connessione-electrum.md: almeno 2 server di riserva configurati o il server non parte (ELC-19), almeno 2 risposte per ogni corroborazione (ELC-14). La conseguenza operativa: con meno di 2 server di riserva raggiungibili ogni corroborazione fallisce, anche se il server attivo funziona — depositi non accreditati, estrazione in attesa, segnalazioni di spesa esterna ignorate, nessun denaro mosso. In produzione vanno quindi configurati almeno 3 server di riserva, così che la caduta di uno non fermi la lotteria. ALLOW_NO_QUORUM=true non si usa mai in produzione. Codice: app/electrum/listener.py:ElectrumListener._corroborate_majority, app/main.py:lifespan · Test: tests/unit/test_electrum_listener.py Stato: da implementare (B-84) · Oggi: con ELECTRUM_FALLBACK_SERVERS vuoto (il valore di .env.example) il server parte e la corroborazione passa sempre: un solo server decide tutto. Con server di riserva la maggioranza è su chi risponde, quindi basta una sola riserva raggiungibile; se nessuna risponde, la corroborazione fallisce (draw_header_corroboration_failed a ogni blocco).

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. Dopo B-81 lo scheduler riprende da solo un round in drawing e il terzo caso scompare.

  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. Vale solo per un round bloccato nell'istanza in esercizio: un round in drawing arrivato da un backup ripristinato si tratta con [OPS-07], passo 6, perché potrebbe essere già stato pagato.

  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à quando la commissione basta al mempool.
  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 attivo non conosce più viene abbandonata dopo 6 ore dal primo invio (pending_tx_abandoned); il partecipante viene rimosso e il round può chiudere. Dopo B-78 l'abbandono richiede una prova (ingressi spesi altrove, o un nuovo invio rifiutato da tutti i server): una transazione che nessuno conosce ma i cui ingressi non sono spesi non viene più abbandonata per il solo passare del tempo. 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. Un round in paying_out senza payout_failed e con una riga payout pending che non conferma è un pagamento fermo nel mempool: vedi [OPS-17].

  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 980 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 fra 120 e 240 secondi dopo (al primo passaggio oltre i 120s), 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. Oggi lo stesso motivo compare anche per un timeout o una connessione caduta durante l'invio, quando la transazione potrebbe essere partita; dopo B-76 solo un rifiuto esplicito libera la riga

  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. Dopo B-80 ogni round ha il proprio indirizzo (rounds.pool_address), e dopo B-82 un'uscita di scommessa scomparsa dalla catena esclude quel partecipante invece di bloccare il pagamento; solo la scommessa scomparsa del vincitore lo blocca ([OPS-30]).

  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. Oggi: la transazione non compare nella cronologia del proprio indirizzo secondo il solo server attivo: mai partita (riga building da oltre 120s) o scomparsa dal mempool (riga pending da oltre 6 ore dal primo invio). Non è una prova: un server diverso da quello che ha ricevuto l'invio può non conoscerla, e una versione precedente di una transazione accelerata con RBF non viene cercata (B-77). 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. Prima di avvisare l'utente o lasciar ripartire un pagamento, verificare con un explorer che né txid del payload né una sua versione precedente (replaced_by_txid della riga) siano in catena: se lo sono, i fondi si sono mossi davvero e il database dice il contrario. Per un prelievo, gli UTXO liberati verranno poi segnati come spesi all'esterno dalla corroborazione; per un pagamento già arrivato al vincitore, mettere subito in pausa la lotteria e trattare il round come in [OPS-07], passo 6. Se gli abbandoni sono frequenti, la commissione di rete configurata è probabilmente troppo bassa. Dopo B-78 si abbandona solo con una prova, e una riga failed che conferma più tardi mette in pausa la lotteria da sola ([OPS-30]). 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. Un aumento che la rete rifiuta (per esempio perché il resto scenderebbe sotto la soglia di polvere) compare invece come errore di invio nello stesso messaggio. 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. Un pagamento di norma non ha resto (spende esattamente gli UTXO del montepremi), quindi oggi un pagamento fermo nel mempool non si può accelerare in nessun caso. Cosa fare. Nessuna procedura supportata. La transazione resta in attesa alla commissione che ha: conferma quando il mempool la accetta, 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. Per un pagamento non c'è un'alternativa supportata: la chiave del montepremi non è esportabile ([OPS-24]). Dopo B-79 ogni pagamento ha un'uscita di riserva che l'RBF può ridurre; dopo B-87 un aumento che lascerebbe un resto sotto la soglia di polvere toglie il resto invece di fallire, e ogni fallimento scrive rbf_bump_failed. 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 le conferme richieste: oggi 1, dopo B-82 deposit_confirmations (predefinito 6) e 120 per un'uscita coinbase (registrazione-e-depositi.md). Il deposito non viene mostrato nemmeno come "in attesa" finché non le ha.
  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 o fermo ([OPS-11]).
  5. L'importo è sotto DUST_LIMIT_SATS (294 sat) e non viene accreditato per scelta. Cosa fare. Verificare con un explorer che la transazione abbia le conferme richieste 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. Il login ha un freno per username e uno per IP (SEC-30). Basta aspettare che il blocco scada; 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). Tutti i passi girano nel container, dove MASTER_KEY_PATH è forzato su /app/key_data/master.xprv.enc, cioè il file che l'app legge: 0. Verificare quale file si sta ruotando. Il file dell'app è ./data/keys/master.xprv.enc. Dal venv gli script usano invece il MASTER_KEY_PATH di .env (grep '^MASTER_KEY_PATH=' .env), che su questa installazione punta alla copia ./master.xprv.enc nella radice (B-71): una rotazione fatta dal venv riscriverebbe quella copia, l'app leggerebbe il file vecchio con la chiave nuova e fallirebbe alla prima derivazione. Per questo nessun passo usa il venv.

  1. Pausa, attesa di closed e backup come in [OPS-10], poi docker compose stop app. Dopo B-73 questo passo garantisce anche che nessun round abbia il segreto dell'estrazione ancora cifrato con la chiave vecchia (sicurezza.md SEC-56): tutti i round closed sono già rivelati, e il round successivo cifrerà il suo con la chiave nuova. Tenere una copia del file attuale per poter tornare indietro: cp data/keys/master.xprv.enc data/keys/master.xprv.enc.old.
  2. Annotare gli indirizzi derivati con la chiave vecchia:

     docker compose run --rm --no-deps app python -c "from app.wallet.hd import derive_pool_address, derive_user_address; print(derive_pool_address(), derive_user_address(0))"
     

  3. docker compose run --rm --no-deps app python scripts/decrypt_master_key.py con la chiave vecchia ancora in .env, e conservare la xprv stampata solo per il tempo necessario.
  4. Generare la chiave nuova (python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())") e scriverla in .env al posto della vecchia.
  5. docker compose run --rm --no-deps app python scripts/encrypt_master_key.py --overwrite e incollare la xprv.
  6. Verificare la decifratura con la chiave nuova prima di riavviare: rilanciare il comando del passo 2. Deve stampare gli stessi due indirizzi. Se dà errore o indirizzi diversi, non avviare l'app: rimettere in .env la chiave vecchia e master.xprv.enc.old al posto del file, e ricominciare.
  7. docker compose up -d, controllare il log, riprendere la lotteria.
  8. Aggiornare i backup ([OPS-05]) e cancellare master.xprv.enc.old. Se la rotazione è dovuta a una fuga della chiave vecchia, distruggere anche ogni copia cifrata con essa: la copia nella radice (./master.xprv.enc, B-71) e i backup precedenti del file. Il file scritto dal container appartiene a root con permessi 0644: sudo chmod 600 data/keys/master.xprv.enc. Dopo B-89 gli script scrivono 0600 e rifiutano una xprv i cui indirizzi non coincidono con quelli del database (SEC-50); dopo B-91 la chiave sta in un file e non in .env (SEC-53).

  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, scripts/encrypt_master_key.py, scripts/decrypt_master_key.py

Pausa automatica

• [OPS-30] Oltre all'operatore, il sistema mette in pausa la lotteria da sé in tre casi, ognuno con il proprio motivo (paused_reason, valori in modello-dati.md B-85) e una riga di audit. La pausa ha l'effetto di sempre: nessun round nuovo si apre, quello in corso prosegue salvo dove indicato. Solo l'operatore la toglie ("Riprendi lotteria", che azzera anche il motivo); /admin mostra il motivo. Prima di riprendere l'operatore esegue la verifica della tabella.

  Motivo	Quando	Cosa fare prima di riprendere
  operator	"Interrompi dopo questo round", oppure avvio con START_PAUSED=true ([OPS-27])	Dopo un ripristino, le verifiche di [OPS-07]
  reorg	Riorganizzazione della catena profonda almeno 2 blocchi (chain_reorg_detected, ELC-24, B-85)	Confrontare con un explorer e con i server di riserva ([OPS-11], passo 3) la punta attuale e l'altezza di biforcazione del payload. Controllare le righe participant_reorged_out, utxo_spent_externally e pending_tx_resurrected scritte dopo. Riprendere quando la punta ha superato l'altezza di biforcazione di almeno deposit_confirmations blocchi senza un'altra chain_reorg_detected
  resurrected_tx	Una transazione dichiarata failed è stata confermata (pending_tx_resurrected, transazioni-e-riconciliazione.md, B-78)	La riga torna confirmed, ma le righe collegate restano come le aveva lasciate l'abbandono: il database dice che i fondi non si sono mossi, la catena il contrario. Secondo kind del payload: prelievo → l'utente ha ricevuto i fondi, e il prelievo risulta failed; gli UTXO liberati verranno segnati come spesi all'esterno dalla corroborazione, ma nel frattempo erano di nuovo spendibili: controllare che l'utente non li abbia già prelevati o scommessi con un'altra transazione; scommessa → i soldi sono nel montepremi del round senza partecipante: rimborso manuale ([OPS-24]); pagamento → il vincitore potrebbe essere stato pagato due volte: confrontare payout_txid del round con la catena
  payout_blocked	La scommessa del vincitore non è più sulla catena (RND-39, B-82)	Il round resta in paying_out con payout_blocked_at. Verificare con un explorer che l'uscita della scommessa sia davvero spesa altrove (doppia spesa del deposito): è il segno di un probabile attacco, e le prove vanno conservate. Alla ripresa la verifica di RND-39 si ripete: se la scommessa è ancora assente, il pagamento resta bloccato e la lotteria torna in pausa

  Codice: app/api/routes/admin.py:pause_lottery, app/api/routes/admin.py:resume_lottery, app/rounds/service.py:open_new_round_if_needed, app/electrum/listener.py:ElectrumListener._apply_header, app/tx/confirmation.py:poll_once, app/rounds/scheduler.py:RoundScheduler._trigger_payout · Test: — Stato: da implementare (B-85, B-78, B-82, B-90) · Oggi: esiste solo la pausa dell'operatore, senza motivo; nessun evento del sistema mette in pausa la lotteria.

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), per recuperare resti accumulati o per rimborsare una scommessa rimasta senza partecipante. 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. Dopo B-80 ogni round ha il proprio indirizzo m/84'/746'/0'/2/<round_id> e m/84'/746'/0'/1/0 diventa l'indirizzo di riserva; il pagamento di un round spende solo le uscite delle sue scommesse. 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ù o fermo ([OPS-11])
  Stato e durata del round	status, closes_at, draw_waiting_since in GET /rounds/current	closing o paying_out per più di 3 blocchi (6 minuti); 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	Qualunque occorrenza va verificata ([OPS-16]); 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 (primo invio) 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
  Container	docker compose ps	app che si riavvia in continuazione: rifiuto all'avvio ([OPS-02])
  Prontezza (dopo B-92)	GET /health/ready, docker compose ps	503 / unhealthy ([OPS-04])
  Catena e sistema (dopo B-78, B-82, B-85, B-87, B-90)	Audit: chain_reorg_detected, pending_tx_resurrected, payout_blocked, participant_reorged_out, rbf_bump_failed, restore_gap_detected; paused_reason diverso da operator	Qualunque occorrenza ([OPS-30], [OPS-28])

  Codice: app/api/routes/rounds.py, app/api/routes/admin.py, app/logging_config.py:setup_logging

Dopo B-92 l'indicatore Electrum di /admin mostra lo stato della connessione (ELC-29): connessa o no, server attivo, altezza, età dell'ultimo header. Oggi mostra solo l'ultima altezza nota ("Blocco #N"), che resta visibile anche a connessione caduta.

Prova su rete reale

I test automatici simulano la rete. Nessuna delle falle critiche della revisione del 2026-09-28 sarebbe emersa da essi, e prelievo e RBF non sono mai stati trasmessi davvero. Prima di aprire al pubblico, e dopo le correzioni di piano-correzioni.md, serve una prova su un'istanza di staging collegata alla rete PLM reale (o, dove indicato, a una rete di prova), con importi piccoli (costo della scommessa 0,1 PLM) e guasti provocati di proposito.

• [OPS-31] L'istanza si apre al pubblico solo dopo che ogni prova della tabella è stata eseguita e ha dato l'esito atteso. Per ogni prova si annotano data, versione (git rev-parse HEAD), txid coinvolti ed esito, e una prova con esito diverso diventa una voce di BUGS.md. Codice: —

  #	Prova	Come	Esito atteso
  1	Ciclo completo	Due utenti, depositi, una scommessa ciascuno, un round intero	Deposito accreditato dopo deposit_confirmations conferme; draw_committed all'ingresso in drawing; vincitore, seme rivelato e prova di GET /rounds/{id}/proof ricalcolabili a mano; ripartizione 70/30 al satoshi; round closed e round successivo aperto
  2	Prelievo reale	Prelievo parziale e prelievo dell'intero saldo	Transazione confermata; importo e resto come in scommesse-e-prelievi.md; il prelievo totale lascia un resto di almeno DUST_LIMIT_SATS
  3	Server ucciso durante un invio	Interrompere la rete del server Electrum attivo (o docker compose kill app) mentre una scommessa e un prelievo sono in invio	Nessun rilascio senza prova (B-76): la risposta è 202 o l'errore esplicito; la riga resta building e il riconciliatore la promuove se la transazione è in catena; nessun UTXO liberato per una transazione partita
  4	Riavvio durante drawing	docker compose restart app con un round in drawing	Il round riprende da solo (B-81) con lo stesso draw_height e gli stessi partecipanti, e il vincitore è quello calcolabile dalla prova
  5	Pagamento fermo a commissione bassa	fee_rate_sat_vb = 1 con mempool affollato, oppure invio del pagamento a un solo server che non lo propaga	Dopo rbf_timeout_seconds il pagamento viene accelerato riducendo l'uscita di riserva (B-79) e conferma; se l'aumento è impossibile compare rbf_bump_failed (B-87)
  6	Riorganizzazione di 1 blocco	Solo su una rete di prova con due minatori, se disponibile	La punta segue il ramo nuovo senza chiudere la sessione; chain_reorg_detected con profondità 1; nessuna pausa. Con profondità 2: pausa con motivo reorg (B-85, B-74)
  7	Cronologia molto lunga	Indirizzo con risposta oltre 64 KiB (per esempio mille piccoli invii a un indirizzo di prova)	La connessione resta aperta (limite di 16 MiB); le uscite sotto DUST_LIMIT_SATS non vengono accreditate (B-75)
  8	Tutte le riserve giù	Bloccare con il firewall ogni server di ELECTRUM_FALLBACK_SERVERS	Accrediti rinviati, estrazione in attesa, nessuna spesa esterna registrata, nessun denaro mosso; al ritorno dei server tutto riprende. Un avvio con meno di 2 riserve è rifiutato (B-84)
  9	Server connesso ma fermo	Un server Electrum di prova che smette di seguire la catena	Dopo 360 secondi senza avanzamento il listener passa a un server con una punta più alta (B-86); GET /health/ready risponde 503 nel frattempo (B-92)
  10	Salto dell'orologio	Portare avanti l'orologio dell'host di 7 ore con transazioni pending	Nessuna transazione abbandonata per il solo tempo trascorso (B-78)
  11	Disco pieno	Riempire il filesystem di ./data/db durante l'attività	Nessuna transazione trasmessa senza la sua riga salvata prima; scommesse e prelievi falliscono prima dell'invio; liberato lo spazio, il sistema riprende senza interventi sul database
  12	Ripristino da backup	Backup, poi un round completo e una registrazione, poi [OPS-07]	Avvio in pausa con START_PAUSED=true; restore_gap_detected e registrazioni rifiutate; il round rigiocato non viene pagato una seconda volta (B-90, B-80, B-82)
  13	Chiave sbagliata	Avvio con una XPRV_ENCRYPTION_KEY diversa, poi con una master key diversa	Il server rifiuta di servire in entrambi i casi (B-89)
  14	Deploy con stream aperti	docker compose up -d --build con pagine / aperte	Arresto completo entro 30 secondi senza uccisione del processo (B-93)

Script manuali

Si lanciano nel container con docker compose run --rm --no-deps app python scripts/<nome>.py, oppure dal venv sull'host (source .venv/bin/activate, con PYTHONPATH=.). 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, che su questa installazione punta a un'altra copia (B-71, vedi [OPS-22], passo 0): per gli script sulla master key usare il container.

• [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 altro server, lanciarlo con -e ELECTRUM_HOST=… -e ELECTRUM_PORT=…

  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. I file scritti hanno i permessi predefiniti del sistema (di norma 0644) e, nel container, appartengono a root. Dopo B-89 gli script scrivono 0600 e rifiutano una xprv diversa da quella degli indirizzi già nel database (SEC-50). 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