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](processo-di-modifica.md#requisiti-non-ancora-implementati)).
Il dettaglio tecnico di ogni voce, in inglese, è in [BUGS.md](../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](ciclo-di-vita-del-round.md#3--estrazione), 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](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](registrazione-e-depositi.md#deposito), 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](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](sicurezza.md#sec-56) SEC-56,
   [modello-dati.md](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](sicurezza.md) SEC-54);
   - segnalazioni di bug: al massimo 10 all'ora per IP
     ([sicurezza.md](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](sicurezza.md#sec-49) 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](transazioni-e-riconciliazione.md#invio-rifiutato)
   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](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](operativita.md#prova-su-rete-reale).

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