plm-lottery/docs/piano-correzioni.md

Piano delle correzioni (revisione del 2026-09-28)

La revisione della specifica del 2026-09-28 (coin e catena, macchina a stati del denaro, operatività, coerenza dei documenti) ha trovato falle logiche nella struttura del software. Questo documento raccoglie le decisioni prese e l'ordine in cui implementarle.

La specifica è già stata aggiornata al comportamento atteso. Ogni requisito che il codice non soddisfa ancora è marcato *Stato:* da implementare (B-nn) e dice in una riga cosa fa il codice oggi (vedi processo-di-modifica.md). Il dettaglio tecnico di ogni voce, in inglese, è in BUGS.md.

Le decisioni

1. Estrazione con commit-reveal. Il vincitore non deve essere calcolabile da chi produce o trasmette i blocchi: la potenza di calcolo di PLM (~22 TH/s) si può affittare. All'apertura il server si impegna su un segreto pubblicandone l'impronta. Alla chiusura si fissano l'elenco dei partecipanti e l'altezza del blocco. Il seme combina segreto, blocco ed elenco, e il segreto viene rivelato dopo. Un minatore non sa chi vincerebbe e quindi non ha motivo di scartare blocchi. L'operatore non può cambiare il segreto dopo averne pubblicato l'impronta. → ciclo-di-vita-del-round.md, B-73
2. Nel dubbio non si liberano mai i fondi. Una transazione viene annullata solo con una prova: un rifiuto esplicito della rete, oppure i suoi ingressi spesi da un'altra transazione confermata. Mai per un timeout o per il silenzio di un solo server. → transazioni-e-riconciliazione.md, B-76, B-77, B-78
3. Un indirizzo del montepremi per ogni round. Soldi, cronologia e pagamento di un round restano separati da quelli di tutti gli altri round. → B-80
4. 6 conferme per i depositi (configurabili). Tutte le altre transazioni restano a 1: il deposito è l'unico ingresso che un utente può spendere due volte, perché il resto lo firma solo il server. → registrazione-e-depositi.md, B-82
5. Le riorganizzazioni della catena si contengono. Si rilevano, si mette in pausa la lotteria quando sono profonde, e si paga solo ciò che risulta davvero sulla catena. → B-82, B-85

Limite accettato: un attacco al 51% su PLM resta possibile e riguarda chiunque usi PLM, non solo la lotteria. Queste misure fanno sì che non convenga e che non blocchi la lotteria; non lo rendono impossibile. Vedi limiti-noti.md.

Decisioni confermate il 2026-09-29

Scelte di dettaglio emerse scrivendo la specifica, confermate prima di iniziare l'implementazione:

1. Il segreto dell'estrazione è cifrato a riposo. Fino alla rivelazione il database contiene server_seed solo cifrato con la chiave della master xprv, così una copia del database o un backup non bastano a prevedere il vincitore di un round aperto. All'avvio il server verifica di poterlo decifrare. → sicurezza.md SEC-56, modello-dati.md DAT-64, B-73
2. Soglie di protezione:
   • cambio password: dal 5° tentativo sbagliato attese che raddoppiano da 2 a 300 secondi, azzerate dopo 900 secondi senza errori o a un cambio riuscito (sicurezza.md SEC-54);
   • segnalazioni di bug: al massimo 10 all'ora per IP (sicurezza.md SEC-55);
   • verifica della chiave all'avvio: indirizzo di riserva, i 10 utenti con indice più basso e i 10 con indice più alto, gli ultimi 10 round con indirizzo proprio, e il segreto di ogni round non ancora rivelato (sicurezza.md SEC-49). → B-89, B-94
3. Un rifiuto dell'invio si verifica prima di liberare le monete. Il testo degli errori Electrum non distingue in modo affidabile un rifiuto da un "già in mempool", e il protocollo non ha un codice standard. Dopo ogni rifiuto si chiede la transazione a tutti i server: basta che uno la conosca perché l'invio valga come accettato, e si annulla solo se nessuno la conosce. Il riconoscimento del testo resta una scorciatoia, non una condizione di sicurezza. → transazioni-e-riconciliazione.md TX-04, B-76

Ordine di implementazione

Le fasi vanno eseguite in ordine: ognuna si appoggia sulle precedenti. Dentro una fase l'ordine è indicativo. Ogni voce è un commit a sé, con il suo test di regressione, secondo processo-di-modifica.md.

Fase 1 — Fondamenta

Voce	Cosa	Gravità
B-88	Transazioni SQLite vere (BEGIN IMMEDIATE, synchronous=FULL)	alta
B-75	Client Electrum: limite di 16 MiB, risposta troppo grande = errore della richiesta, UTXO sotto la soglia di dust ignorati	critica
B-97	Test che esegue le migrazioni e verifica gli indici	media
B-80	Indirizzo del montepremi per round	critica

Fase 2 — Nel dubbio non liberare

Voce	Cosa	Gravità
B-84	Quorum minimo obbligatorio (almeno 2 server di riserva, almeno 2 risposte)	alta
B-76	Invio ambiguo: la riga resta building, invio a tutti i server	critica
B-77	Tutti i txid della catena di sostituzioni; RBF salvato prima dell'invio	critica
B-78	Abbandono solo con prova; le righe failed restano sorvegliate	critica
B-83	Conferme e reintegri verificati dal quorum (prova merkle)	alta

Fase 3 — Estrazione

Voce	Cosa	Gravità
B-74	Header: difficoltà minima, collegamento verificato su ogni salto	critica
B-85	Riorganizzazioni seguite, registrate, con pausa se profonde	alta
B-86	Rotazione se il server si ferma	alta
B-73	Commit-reveal, altezza fissa, conferme sul blocco di estrazione, prova pubblica	critica
B-81	drawing riprende dopo un errore o un riavvio	critica

Fase 4 — Pagamento

Voce	Cosa	Gravità
B-79	Riserva per l'RBF su ogni pagamento	critica
B-82	6 conferme sui depositi, 120 sulle coinbase, verifica prima del pagamento	critica
B-87	RBF che non lascia resti sotto la soglia di dust	alta
B-95	Parametri del round fotografati all'apertura, tetto al montepremi	media

Fase 5 — Operatività

Voce	Cosa	Gravità
B-71	Una sola copia della master key e del database	bassa
B-72	setup.md senza il falso "in locale o via Docker"	bassa
B-89	Verifica della chiave all'avvio	alta
B-90	Ripristino da backup sicuro	alta
B-92	Readiness, stato Electrum, filtri dell'audit, log	media
B-93	Deploy e rollback	media
B-91	Container non root, permessi, dipendenze fissate	alta

Fase 6 — Rifiniture

Voce	Cosa	Gravità
B-94	Limiti su cambio password, login, bug report; errori strutturati	media
B-96	Incoerenze minori (sette voci, un test ciascuna)	media
B-98	Selezione delle monete che garantisce il resto quando il saldo lo permette	media

Fase 7 — Prova su rete reale

Nessuna delle falle critiche sarebbe stata trovata dai test attuali, che simulano tutto. Prima di aprire al pubblico serve una prova con importi piccoli e guasti provocati di proposito, secondo la lista di operativita.md.

Correzioni solo documentali già applicate

Nella stessa revisione sono state corrette, senza un B-nn perché il codice non cambia:

• affermazioni false sul comportamento attuale: timeout trattato come rifiuto, "prima o poi abbandonata", quorum "su ogni decisione", tempi "nel caso peggiore", resto di 294 sat "accelerabile";
• due procedure operative pericolose: il ripristino con sblocco di drawing (OPS-07) e la rotazione della chiave di cifratura (OPS-22);
• puntatori sbagliati e requisiti duplicati in più documenti;
• formulazioni vaghe in regole normative.