plm-lottery/docs/decisioni-e-limiti.md

# Decisioni di progetto e limiti noti

Questo documento raccoglie due cose che non si ricavano leggendo un singolo
file del codice:

- **le decisioni di progetto (`DEC`)**: scelte deliberate, con il motivo, le
  alternative scartate dove sono note e le conseguenze. Chi vuole cambiarne
  una deve saperlo prima di toccare il codice, perché altri requisiti ne
  dipendono;
- **i limiti noti (`LIM`)**: difetti di copertura o di robustezza accettati
  consapevolmente, con l'impatto, ciò che oggi li attenua e cosa servirebbe
  per chiuderli.

Un limite noto **non è un bug**: un bug è un comportamento che contraddice la
specifica e prende un numero `B-nn` ([storico-bug.md](storico-bug.md)). Se si
decide di chiudere un limite, si aggiorna prima la voce `LIM` qui (o la si
barra come rimossa) e poi il requisito del documento di dominio, secondo
[processo-di-modifica.md](processo-di-modifica.md).

Ogni voce rimanda al codice che la incarna. I dettagli di comportamento stanno
nei documenti di dominio, a cui si rimanda invece di ripeterli.

---

## Parte 1 — Decisioni di progetto (DEC)

Formato di ogni voce: **decisione** in grassetto, poi *Motivazione*,
*Alternative scartate* (dove note), *Conseguenze*, e i riferimenti.

### Custodia, chiavi e indirizzi

- **[DEC-01]** **La piattaforma è custodiale: tutte le chiavi sono generate e
  tenute dal server.** Una sola master xprv, cifrata con Fernet a riposo; la
  chiave di cifratura sta in una variabile d'ambiente (`XPRV_ENCRYPTION_KEY`),
  mai nel database né in git. L'utente non controlla nulla finché non preleva.
  - *Motivazione:* un'esperienza da «conto» (registrazione con username e
    password, scommessa con un clic) senza portafoglio lato utente, firme o
    PSBT da gestire nel browser.
  - *Alternative scartate:* portafoglio non custodiale con firma lato client.
  - *Conseguenze:* la compromissione del server (file cifrato + variabile
    d'ambiente) espone tutti i fondi; da qui l'esportazione WIF accettata
    ([DEC-39]), l'assenza di recupero password ([DEC-37]) e il modello di
    minaccia di [sicurezza.md](sicurezza.md).

  *Codice:* `app/wallet/hd.py:_load_account_key` · `app/wallet/keystore.py:decrypt_xprv` · `app/wallet/hd.py:generate_master_key` ·
  *Test:* `tests/unit/test_hd.py`

- **[DEC-02]** **Un indirizzo per utente, permanente, per tutti gli usi.**
  Alla registrazione il server deriva un indirizzo P2WPKH BIP84
  (`m/84'/746'/0'/0/<indice>`, un indice per utente, assegnato come massimo
  esistente + 1). Lo stesso indirizzo è indirizzo di deposito, riceve le
  vincite e riceve il resto di ogni scommessa e prelievo. Non esiste un
  «indirizzo vincitore» separato.
  - *Motivazione:* un solo indirizzo da osservare per utente, un solo saldo da
    ricostruire (`utxo_events`), e le vincite accreditate dal normale percorso
    dei depositi senza logica dedicata.
  - *Conseguenze:* nessuna privacy fra depositi, vincite e resti; un prelievo
    verso il proprio indirizzo è rifiutato (renderebbe indistinguibili
    destinatario e resto); il pagamento di un round si considera accreditato
    quando il listener vede la moneta sull'indirizzo del vincitore
    (vedi [registrazione-e-depositi.md](registrazione-e-depositi.md)).

  *Codice:* `app/auth/routes.py:register` · `app/wallet/hd.py:derive_user_address` · `app/rounds/confirmation.py:_on_payout_confirmed` ·
  *Test:* `tests/unit/test_hd.py`, `tests/unit/test_users.py`

- **[DEC-03]** **Il montepremi è un unico indirizzo, derivato dalla stessa
  master key sul ramo `1/0` dell'account** (il ramo `0` è riservato agli
  utenti). Tutte le scommesse di tutti i round arrivano lì e il pagamento è
  firmato con quella chiave.
  - *Motivazione:* nessun segreto aggiuntivo da custodire.
  - *Conseguenze:* i round condividono lo stesso insieme di monete; i resti di
    polvere e le monete avanzate si accumulano sull'indirizzo senza
    consolidamento automatico ([LIM-17]).

  *Codice:* `app/wallet/hd.py:derive_pool_key` · `app/wallet/hd.py:derive_pool_address` ·
  *Test:* `tests/unit/test_pending_address.py`

- **[DEC-04]** **Accesso alla rete solo via protocollo Electrum**, senza nodo
  completo né P2P. Una sola connessione attiva serve tutto (accrediti, invii,
  conferme, altezza della catena).
  - *Motivazione:* nessun nodo da installare e sincronizzare.
  - *Conseguenze:* la connessione è il principale punto singolo di guasto e il
    principale rischio di integrità; da qui le difese di [DEC-07] e
    [DEC-26] e i limiti [LIM-11], [LIM-12], [LIM-14]. Dettagli in
    [connessione-electrum.md](connessione-electrum.md).

  *Codice:* `app/electrum/client.py:ElectrumClient` · `app/electrum/listener.py:ElectrumListener` · `app/main.py:lifespan`

- **[DEC-05]** **Solo indirizzi bech32 PLM (`plm1…`) come destinazione.** Un
  prelievo verso un indirizzo legacy (`P…`) o di un'altra catena (`bc1…`) è
  rifiutato; lo stesso controllo vale per `fee_address` e per `/qr/{address}`.
  - *Motivazione:* un indirizzo di un'altra catena si interpreta comunque come
    witness program valido, quindi la transazione si costruirebbe e i fondi
    sarebbero irrecuperabili.

  *Codice:* `app/wallet/address.py:is_valid_plm_address` · `app/withdrawals/service.py:request_withdrawal` · `app/api/routes/admin.py:RoundConfigUpdate` ·
  *Test:* `tests/unit/test_withdrawals.py::test_withdrawal_rejects_non_plm_address`

### Conferme e fiducia nella rete

- **[DEC-06]** **Una conferma per ogni tipo di transazione** (deposito,
  scommessa, pagamento, prelievo), senza logica di rollback in caso di reorg.
  Non si introducono soglie diverse (3, 6…) senza una decisione esplicita.
  - *Motivazione:* blocchi da 120s e importi da lotteria; un round
    attende già tre blocchi in sequenza (vedi
    [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md)).
  - *Conseguenze:* rischio di reorg a 1 conferma accettato ([LIM-10]).

  *Codice:* `app/tx/confirmation.py:poll_once` · `app/deposits/service.py:find_new_credit_candidates` ·
  *Test:* `tests/unit/test_confirmation.py::test_unconfirmed_tx_is_left_pending`, `tests/unit/test_deposits.py::test_unconfirmed_entry_is_ignored`

- **[DEC-07]** **Ogni decisione che sposta denaro in base a una risposta di
  rete è corroborata da un quorum degli altri server configurati**: il blocco
  che semina l'estrazione, una moneta data per spesa all'esterno, un nuovo
  deposito da accreditare. Si interrogano solo gli *altri* server, mai quello
  attivo (che è ciò che un attaccante controllerebbe); serve la maggioranza
  stretta di chi risponde. Senza server di riserva configurati la
  corroborazione passa sempre; se nessuno risponde, fallisce.
  - *Motivazione:* un solo server ostile non deve poter scegliere il
    vincitore (B-28), azzerare un saldo (B-29) o gonfiarlo (B-59). I saldi si
    muovono in entrambe le direzioni, quindi entrambe richiedono il quorum.
  - *Conseguenze:* una corroborazione fallita **ritarda**, non perde: il
    deposito è riproposto al refresh successivo, l'estrazione attende un blocco
    ulteriore. Lista vuota di server di riserva = fiducia nel solo server
    primario ([LIM-11]). Non tutte le letture sono corroborate ([LIM-12]).

  *Codice:* `app/electrum/listener.py:ElectrumListener._corroborate_majority` · `app/electrum/listener.py:ElectrumListener.corroborate_header` · `app/electrum/listener.py:ElectrumListener.corroborate_utxo_spent` · `app/electrum/listener.py:ElectrumListener.corroborate_utxo_credit` ·
  *Test:* `tests/unit/test_electrum_listener.py`

### Configurazione e ambiente

- **[DEC-08]** **I parametri operativi stanno nel database, i segreti
  nell'ambiente.** Ogni parametro di business (costo della scommessa, durata e
  pausa del round, animazione, fee rate, timeout RBF, `fee_address`, pausa) è
  una colonna dell'unica riga di `round_config`, modificabile a caldo da
  `/admin`; i valori iniziali sono i default delle colonne di `RoundConfig`,
  non `app/config.py`. In `.env` restano solo segreti e collegamenti
  (master key, JWT, host Electrum, token admin, URL del database).
  - *Motivazione:* regolare la lotteria senza ridistribuire né riavviare;
    i segreti richiedono comunque un riavvio e non vanno scambiati a caldo.
  - *Conseguenze:* ogni modifica è validata con limiti espliciti ([DEC-09]) e
    registrata in audit come `config_updated` con prima/dopo.

  *Codice:* `app/db/models.py:RoundConfig` · `app/rounds/config.py:get_round_config` · `app/config.py:Settings` · `app/api/routes/admin.py:update_config` ·
  *Test:* `tests/unit/test_admin.py::test_admin_reads_and_updates_config`, `tests/unit/test_admin.py::test_config_update_is_audit_logged`

- **[DEC-09]** **Le modifiche di configurazione sono validate, non fidate.**
  Ogni campo numerico ha limiti (ad esempio `fee_rate_sat_vb` fra 1 e
  `MAX_FEE_RATE_SAT_VB`, `round_duration_seconds` almeno 30) e `fee_address`
  deve essere un indirizzo PLM valido. `paused` non è modificabile da
  `PUT /admin/config`.
  - *Motivazione:* un fee rate a 0 produce transazioni che nessun nodo inoltra,
    una durata a 0 fa scadere il round appena aperto, un `fee_address` estraneo
    manda la commissione in uno script irrecuperabile (B-05).

  *Codice:* `app/api/routes/admin.py:RoundConfigUpdate` ·
  *Test:* `tests/unit/test_admin.py::test_config_rejects_unusable_values`, `tests/unit/test_admin.py::test_pause_cannot_be_toggled_through_the_config_endpoint`

- **[DEC-10]** **I tempi del round sono fotografati all'apertura.** Durata e
  pausa successiva vengono copiate sulla riga del round quando si apre; una
  modifica vale dal round successivo, mai per quello in corso. La pausa fra
  due round è quella annunciata dal round appena chiuso.
  - *Motivazione:* abbassare la durata a metà round lo chiudeva all'istante e
    spostava il conto alla rovescia di tutti i client (B-61).
  - *Conseguenze:* **solo i tempi** sono fotografati. Costo della scommessa,
    fee rate e `fee_address` sono letti dal vivo ([LIM-16]).

  *Codice:* `app/rounds/service.py:open_new_round_if_needed` · `app/rounds/service.py:round_deadline` ·
  *Test:* `tests/unit/test_rounds_service.py::test_a_new_round_snapshots_the_current_config_timing`, `tests/unit/test_scheduler.py::test_tick_ignores_a_config_duration_edited_mid_round`, `tests/unit/test_rounds_service.py::test_cooldown_comes_from_the_round_that_closed`

- **[DEC-11]** **Il server rifiuta di partire con segreti inadeguati**:
  `JWT_SECRET` sotto i 32 caratteri o `XPRV_ENCRYPTION_KEY` vuota fermano
  l'avvio. Un `ADMIN_TOKEN` vuoto invece non è fatale: il pannello resta
  chiuso a tutti. Il controllo è nel lifespan, non in un validatore di
  `Settings`.
  - *Motivazione:* evitare un container che sembra sano e si rompe al primo
    utente reale; tenerlo fuori da `Settings` permette a import e test di
    funzionare senza `.env`.
  - *Alternative scartate:* validatore Pydantic su `Settings` (avrebbe fatto
    fallire la raccolta dei test su un clone pulito, B-15).

  *Codice:* `app/config.py:validate_runtime_secrets` · `app/main.py:lifespan` · `app/api/routes/admin.py:require_admin` ·
  *Test:* `tests/unit/test_config.py`

- **[DEC-12]** **Il server gira solo in Docker, in sviluppo come in
  produzione**, dietro Caddy (TLS automatico, certificato autofirmato su
  `localhost`). Il container rifiuta di partire senza il file della master
  key, applica le migrazioni Alembic all'avvio e si riavvia da solo
  (`restart: unless-stopped`). Il venv serve solo per test, migrazioni e
  script della chiave.
  - *Motivazione:* un solo modo di eseguire il server, identico ovunque.
  - *Conseguenze:* dopo un crash `closing` e `paying_out` riprendono da soli,
    `drawing` no ([LIM-01]). Procedure in [operativita.md](operativita.md).

  *Codice:* `Dockerfile` · `docker-compose.yml` · `Caddyfile` ·
  *Test:* `tests/unit/test_docs_no_bare_uvicorn.py`

- **[DEC-13]** **Un solo processo, un solo file SQLite** (modalità WAL con
  `busy_timeout`). Canale SSE, blocchi per-utente, limitatori di tentativi e
  cache sono in memoria.
  - *Motivazione:* semplicità a scala di ~100 utenti concorrenti.
  - *Alternative scartate:* Redis o un database con lock condivisi, da non
    introdurre in via speculativa.
  - *Conseguenze:* nessuna distribuzione su più worker ([LIM-18]). L'unico
    invariante che non dipende dal processo singolo è «al più un round
    attivo», garantito da un indice ([DEC-22]).

  *Codice:* `app/db/base.py:_register_sqlite_pragmas` · `app/tx/locks.py:UserLocks` · `app/rounds/events.py:RoundEventBroadcaster` ·
  *Test:* `tests/unit/test_db_base.py`

### Economia del gioco

- **[DEC-14]** **Ripartizione fissa 70% al vincitore / 30% alla piattaforma**,
  con l'arrotondamento a favore delle commissioni. È nel codice, non nella
  configurazione: cambiarla è una modifica del software.
  - *Motivazione:* una regola economica di fondo non deve poter cambiare con un
    clic dal pannello. Un'unica funzione alimenta sia il montepremi mostrato sia
    il pagamento, così i due non possono divergere.

  *Codice:* `app/rounds/service.py:winner_share` · `app/rounds/scheduler.py:RoundScheduler._trigger_payout` · `app/api/routes/rounds.py:current_round` ·
  *Test:* `tests/unit/test_payout_builder.py::test_payout_deducts_fee_only_from_winner_share`

- **[DEC-15]** **Biglietto a prezzo fisso, una scommessa per utente per round,
  probabilità uguale per tutti** indipendentemente dall'importo effettivo.
  Nessun deposito minimo.
  - *Conseguenze:* l'estrazione sceglie fra indirizzi, non pesa gli importi.
    Poiché il costo è letto dal vivo, una modifica a metà round crea poste
    diverse con la stessa probabilità ([LIM-16]).

  *Codice:* `app/bets/service.py:place_bet` · `app/rounds/draw.py:draw_winner` ·
  *Test:* `tests/unit/test_bets.py::test_place_bet_rejects_second_bet_same_round`

- **[DEC-16]** **La commissione di rete si toglie dall'importo che si
  muove**, non si aggiunge sopra: per una scommessa arriva al montepremi il
  costo meno la commissione, per un prelievo arriva a destinazione l'importo
  meno la commissione.
  - *Conseguenze:* il montepremi si calcola sommando gli importi effettivi
    delle scommesse, non moltiplicando il numero di giocatori per il costo
    (B-11); il prelievo registra sia l'importo richiesto sia quello inviato.

  *Codice:* `app/wallet/psbt_builder.py:build_signed_transaction` ·
  *Test:* `tests/unit/test_psbt_builder.py::test_build_signed_transaction_deducts_fee_from_amount_not_change`

- **[DEC-17]** **La commissione del pagamento esce dalla quota del
  vincitore**; il 30% della piattaforma resta intatto.
  - *Conseguenze:* il montepremi annunciato (il 70% delle scommesse
    confermate) supera di poco quanto il vincitore riceve davvero; la
    differenza, la commissione del pagamento, non è nota finché il pagamento non
    è costruito.

  *Codice:* `app/wallet/psbt_builder.py:build_payout_transaction` ·
  *Test:* `tests/unit/test_payout_builder.py::test_payout_deducts_fee_only_from_winner_share`

- **[DEC-18]** **L'accelerazione RBF la paga chi riceve il resto**: l'utente
  per scommesse e prelievi, il montepremi per i pagamenti. Le uscite verso la
  controparte (montepremi, indirizzo esterno, vincitore, `fee_address`) non si
  toccano mai; si riduce solo il resto del mittente.
  - *Conseguenze:* una transazione senza resto non si può accelerare
    ([LIM-02]).

  *Codice:* `app/tx/broadcast.py:bump_fee` · `app/tx/broadcast.py:_find_change_output` ·
  *Test:* `tests/unit/test_broadcast.py`

- **[DEC-19]** **Ogni transazione utente conserva un'uscita di resto di almeno
  `DUST_LIMIT_SATS` (294 sat)**, così resta accelerabile. Chi preleva tutto
  sposta il saldo meno 294 sat, che restano sul conto (e la commissione di rete
  esce, come sempre, dall'importo spostato); una scommessa da un saldo
  pari al costo è rifiutata con `balance_leaves_no_change`, perché il prezzo
  fisso non si può ridurre.
  - *Motivazione:* un prelievo totale produceva una transazione a un'uscita
    che nessun RBF poteva salvare (B-62). Aggiungere monete non avrebbe
    aiutato: la transazione le spendeva già tutte.
  - *Conseguenze:* **il pagamento del round fa eccezione**: un resto del
    montepremi sotto la soglia va alla commissione e, nel caso normale, il
    pagamento non ha resto ([LIM-02]).

  *Codice:* `app/wallet/psbt_builder.py:build_signed_transaction` · `app/withdrawals/service.py:request_withdrawal` ·
  *Test:* `tests/unit/test_psbt_builder.py::test_build_signed_transaction_refuses_an_amount_that_would_leave_no_change`, `tests/unit/test_withdrawals.py::test_full_balance_withdrawal_keeps_a_bumpable_change_output`, `tests/unit/test_withdrawals.py::test_a_bet_from_a_balance_equal_to_the_bet_is_refused`

- **[DEC-20]** **Il prelievo minimo è il costo corrente della scommessa**, senza
  un campo di configurazione separato.
  - *Motivazione:* un parametro in meno da tenere coerente.
  - *Conseguenze:* alzare il costo della scommessa alza anche il prelievo
    minimo, con effetto immediato.

  *Codice:* `app/withdrawals/service.py:request_withdrawal` ·
  *Test:* `tests/unit/test_withdrawals.py::test_withdrawal_rejects_amount_below_minimum`

- **[DEC-21]** **Tre limiti distinti sul numero di monete e di giocatori:**

  | Costante | Valore | Protegge da |
  |---|---|---|
  | `MAX_TX_INPUTS` | 50 | una transazione utente (scommessa, prelievo) che erode l'importo in commissioni per un indirizzo troppo frammentato; oltre, `too_many_inputs` |
  | `MAX_PAYOUT_TX_INPUTS` | 500 | un pagamento troppo grande per le regole di inoltro (~1470 ingressi a 100 kvB); un terzo del margine |
  | `MAX_PARTICIPANTS_PER_ROUND` | 400 | un round impagabile: il 401° giocatore è rifiutato con `round_full` **prima** che si muova denaro |

  - *Motivazione:* il pagamento spende una moneta del montepremi per scommessa;
    usare per esso il limite utente rendeva impagabile ogni round oltre ~50
    giocatori e fermava la lotteria (B-52). I 100 di differenza fra 400 e 500
    lasciano spazio alle monete avanzate da round precedenti.
  - *Conseguenze:* «ogni round si può pagare» è un invariante verificato
    all'ingresso, non una scoperta al momento del pagamento. Il conteggio dei
    partecipanti include quelli non ancora confermati (direzione prudente).

  *Codice:* `app/wallet/psbt_builder.py:select_utxos` · `app/bets/service.py:place_bet` · `app/wallet/psbt_builder.py:build_payout_transaction` ·
  *Test:* `tests/unit/test_psbt_builder.py::test_select_utxos_never_exceeds_the_input_cap`, `tests/unit/test_bets.py::test_place_bet_rejects_the_bet_past_the_participant_cap`, `tests/unit/test_payout_builder.py::test_payout_at_the_participant_cap_stays_well_inside_relay_limits`

### Round ed estrazione

- **[DEC-22]** **Al più un round attivo, come invariante del database.** Un
  indice unico su un'espressione costante, limitato agli stati attivi, fa
  fallire in modo pulito il secondo inserimento concorrente; chi perde adotta
  il round del vincitore (al massimo 3 tentativi). I round non si
  sovrappongono mai: il successivo si apre solo quando il precedente è
  `closed`.
  - *Alternative scartate:* rendere lo scheduler l'unico autore dei round (la
    prima scommessa dopo una pausa non avrebbe potuto aprirne uno, B-09).

  *Codice:* `app/db/models.py:Round` · `app/rounds/service.py:open_new_round_if_needed` · `app/rounds/service.py:get_active_round` ·
  *Test:* `tests/unit/test_rounds_service.py::test_the_database_refuses_a_second_active_round`, `tests/unit/test_rounds_service.py::test_losing_the_open_race_reuses_the_winning_round`

- **[DEC-23]** **Il limite per scommettere è la scadenza del round stesso, non
  il suo stato nel database**, e la chiusura «a semaforo giallo» aspetta che
  ogni scommessa già inviata sia confermata prima di estrarre. L'iscrizione è
  salvata con un compare-and-set sulla riga del round.
  - *Motivazione:* lo scheduler controlla ogni 5s, quindi lo stato può restare
    `open` oltre la scadenza; senza il compare-and-set una scommessa poteva
    finire nel montepremi ed essere esclusa dall'estrazione (B-53).
  - *Conseguenze:* l'attesa in `closing` è limitata solo dall'abbandono di una
    scommessa che non conferma mai ([LIM-03]). Dettagli in
    [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md).

  *Codice:* `app/rounds/service.py:round_accepts_bets` · `app/bets/service.py:place_bet` · `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
  *Test:* `tests/unit/test_bets.py::test_place_bet_refuses_when_the_round_closed_between_the_check_and_the_commit`, `tests/unit/test_scheduler.py::test_close_and_draw_waits_when_a_bet_appears_after_the_tick_check`

- **[DEC-24]** **L'algoritmo di estrazione è un componente sostituibile, non il
  disegno definitivo**: seme = hash del primo blocco confermato dopo la
  chiusura, indice = seme modulo numero di partecipanti confermati, ordinati per
  orario di invio della scommessa. Non si deve architettare il resto del
  sistema attorno alla sua forma attuale.
  - *Motivazione:* semplice e deterministico, pensato per essere rimpiazzato.
  - *Conseguenze:* vedi [LIM-13] per i limiti di questa forma (entropia
    dal minatore, verificabilità, pareggi).

  *Codice:* `app/rounds/draw.py:draw_winner` · `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
  *Test:* `tests/unit/test_draw.py`

- **[DEC-25]** **Il blocco che semina l'estrazione deve essere successivo alla
  chiusura e corroborato.** L'attesa del blocco non ha timeout (l'entropia
  dipende davvero da un blocco futuro) ma è osservabile (`draw_stalled`,
  `draw_waiting_since`). Un'altezza `0` alla chiusura significa «sconosciuta»:
  la prima altezza appresa diventa la base e si attende un blocco ancora
  successivo.
  - *Motivazione:* un hash già pubblico mentre le scommesse erano aperte
    renderebbe il vincitore prevedibile (B-63); un header fabbricato
    sceglierebbe il vincitore (B-28).

  *Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_next_block` · `app/rounds/scheduler.py:RoundScheduler._adopt_baseline_tip` ·
  *Test:* `tests/unit/test_scheduler.py::test_wait_for_next_block_never_seeds_the_draw_from_a_pre_close_block`, `tests/unit/test_scheduler.py::test_wait_for_next_block_retries_after_a_failed_corroboration`

- **[DEC-26]** **Validazione minima degli header, senza catena completa.** Un
  header deve rispettare il bersaglio di difficoltà che dichiara e, se avanza
  di un solo blocco, concatenarsi alla punta attuale; la punta non regredisce
  mai; un secondo header alla stessa altezza o un header senza `hex` vengono
  ignorati senza chiudere la sessione.
  - *Motivazione:* bloccare header inventati senza scaricare e validare la
    storia delle difficoltà; lasciare al quorum ([DEC-07]) il caso residuo.
  - *Alternative scartate:* validazione completa della catena degli header
    (fuori scopo per la v1).
  - *Conseguenze:* [LIM-14].

  *Codice:* `app/electrum/listener.py:ElectrumListener._apply_header` · `app/rounds/draw.py:header_meets_its_own_target` ·
  *Test:* `tests/unit/test_electrum_listener.py::test_apply_header_rejects_one_that_does_not_chain_from_the_tip`, `tests/unit/test_electrum_listener.py::test_apply_header_ignores_a_competing_header_at_the_current_tip_height`

- **[DEC-27]** **Pausa di cortesia fra un round e l'altro**
  (`round_cooldown_seconds`, 30s), contata dalla **conferma del pagamento**, non
  dall'inizio della chiusura, così i giocatori vedono l'esito.

  *Codice:* `app/rounds/confirmation.py:_on_payout_confirmed` · `app/rounds/service.py:open_new_round_if_needed` ·
  *Test:* `tests/unit/test_rounds_service.py::test_withholds_new_round_during_cooldown`

- **[DEC-28]** **La pausa per manutenzione ferma solo il round successivo.**
  È un'azione esplicita dell'operatore con endpoint propri e registrati in
  audit (`lottery_paused`, `lottery_resumed`), non un campo di configurazione;
  il round in corso chiude, estrae e paga normalmente.
  - *Motivazione:* sospendere a metà un round con denaro nel montepremi
    creerebbe proprio lo stato bloccato che la pausa vuole evitare.

  *Codice:* `app/api/routes/admin.py:pause_lottery` · `app/api/routes/admin.py:resume_lottery` · `app/rounds/service.py:open_new_round_if_needed` ·
  *Test:* `tests/unit/test_rounds_service.py::test_withholds_new_round_while_paused`, `tests/unit/test_rounds_service.py::test_pause_does_not_interrupt_a_round_in_progress`, `tests/unit/test_admin.py::test_admin_can_pause_and_resume_the_lottery`

- **[DEC-29]** **Senza `fee_address` non si apre nessun round.** Il campo non ha
  valore predefinito: l'operatore deve impostare il proprio. Finché manca, nessun
  round si apre (`lottery_configured = false` su `GET /rounds/current`, avviso
  in `/admin`); un round già in corso invece chiude, estrae e paga anche se
  l'indirizzo viene cancellato. Qualunque altra condizione che renderebbe un
  round impagabile va aggiunta nello stesso punto.
  - *Motivazione:* un round aperto senza `fee_address` raccoglieva scommesse e
    solo al pagamento scopriva di non poter essere pagato (B-66).

  *Codice:* `app/rounds/service.py:rounds_can_open` · `app/rounds/config.py:get_round_config` ·
  *Test:* `tests/unit/test_rounds_service.py::test_withholds_new_round_while_no_fee_address_is_configured`, `tests/unit/test_rounds_service.py::test_a_round_in_progress_survives_the_fee_address_being_cleared`, `tests/unit/test_rounds_route.py::test_lottery_configured_flags_a_missing_fee_address`

- **[DEC-30]** **Il montepremi annunciato è quello che sarà pagato**: il 70%
  delle sole scommesse confermate, affiancato dai valori «in attesa» che
  includono le scommesse in volo (valori inclusivi, non differenze).
  - *Motivazione:* mai annunciare più di quanto l'estrazione e il pagamento
    considereranno (B-65), senza nascondere al giocatore la propria scommessa
    appena fatta.

  *Codice:* `app/api/routes/rounds.py:current_round` ·
  *Test:* `tests/unit/test_rounds_route.py::test_advertised_jackpot_covers_only_the_bets_that_will_be_paid`

### Denaro in movimento

- **[DEC-31]** **Tutto ciò che spende denaro si scrive prima di inviarlo** (stato
  `building`, monete già segnate come spese) e si risolve contro la catena
  dopo; nessuna sessione del database resta aperta durante una chiamata di
  rete. Un invio rifiutato annulla tutto e risponde **502**.
  - *Motivazione:* un crash fra invio e salvataggio lasciava monete spese in
    catena senza traccia (B-08, B-25). Dettagli in
    [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md).

  *Codice:* `app/bets/service.py:place_bet` · `app/withdrawals/service.py:request_withdrawal` · `app/rounds/scheduler.py:RoundScheduler._trigger_payout` · `app/tx/reconcile.py:reconcile_once` ·
  *Test:* `tests/unit/test_bets.py::test_bet_is_persisted_before_it_is_broadcast`, `tests/unit/test_scheduler.py::test_trigger_payout_persists_before_broadcasting`, `tests/unit/test_reconcile.py`

- **[DEC-32]** **Il pagamento si ritenta da solo, mai due volte**: un tentativo
  ogni 60s, usando l'ultimo `payout_failed` in audit come orologio; prima di
  costruire si rifiuta se esiste già un pagamento `building`/`pending` per il
  round, e si escludono le monete impegnate da pagamenti non risolti.

  *Codice:* `app/rounds/scheduler.py:RoundScheduler._retry_payout_if_due` · `app/rounds/scheduler.py:_reserved_payout_outpoints` ·
  *Test:* `tests/unit/test_scheduler.py::test_trigger_payout_skips_when_already_in_flight`, `tests/unit/test_scheduler.py::test_tick_throttles_retry_after_a_recent_payout_failure`, `tests/unit/test_scheduler.py::test_reserved_payout_outpoints_excludes_utxos_claimed_by_a_stale_payout`

- **[DEC-33]** **Scommessa e prelievo si escludono solo tramite il blocco
  per-utente** sulla *costruzione*: un prelievo è accettato anche mentre una
  scommessa attende conferma, purché le monete confermate e libere lo coprano.
  - *Motivazione:* il rischio è che scelgano la stessa moneta, già escluso dal
    blocco e dal fatto che la selezione salta le monete segnate come spese;
    congelare il resto del saldo non aggiungerebbe sicurezza (B-70).

  *Codice:* `app/tx/locks.py:UserLocks` · `app/api/routes/bets.py:create_bet` · `app/api/routes/withdrawals.py:create_withdrawal` ·
  *Test:* `tests/unit/test_withdrawals.py::test_withdrawal_is_allowed_while_a_bet_is_still_unconfirmed`

- **[DEC-34]** **Saldo spendibile e saldo mostrato sono due numeri distinti.**
  Si spende solo il confermato (`balance_sats`); si mostra quello che include i
  resti ancora in volo (`pending_balance_sats`, in ambra finché non conferma).
  Un prelievo coperto solo dal secondo riceve `balance_pending_confirmation`.
  - *Motivazione:* la selezione a monete intere sottrae l'intera moneta al
    saldo confermato già all'invio, molto più di quanto si stia spostando.

  *Codice:* `app/wallet/balance.py:compute_pending_balance` · `app/wallet/balance.py:recompute_balance` · `app/api/routes/users.py:me` ·
  *Test:* `tests/unit/test_balance.py`, `tests/unit/test_withdrawals.py::test_withdrawal_distinguishes_pending_from_truly_insufficient_balance`

- **[DEC-35]** **Aritmetica solo in satoshi interi**, anche per i valori letti
  dalla rete: l'importo di una moneta spesa si ricava dalla transazione grezza,
  non dal valore decimale restituito dal server.

  *Codice:* `app/tx/broadcast.py:_prevout_amount` · `app/wallet/psbt_builder.py:estimate_vsize` ·
  *Test:* `tests/unit/test_broadcast.py::test_bump_fee_holds_no_session_open_during_network_calls`

### Account, amministrazione e sicurezza

- **[DEC-36]** **Password con Argon2, sessioni con JWT HS256 da 24 ore,
  revocabili.** Il token porta la versione dell'account (`tv`); cambio password
  e reset admin la incrementano e invalidano tutte le sessioni precedenti. Un
  token senza `tv` vale come versione 0, così il rilascio non ha disconnesso
  nessuno. Argon2 gira fuori dall'event loop.
  - *Motivazione:* un reset per account compromesso deve buttare fuori subito
    l'attaccante (B-34); Argon2 inline bloccava l'intero processo, attività in
    background comprese (B-55).

  *Codice:* `app/auth/security.py:create_access_token` · `app/auth/security.py:decode_access_token` · `app/auth/dependencies.py:get_current_user` · `app/auth/security.py:verify_password_async` ·
  *Test:* `tests/unit/test_security.py`, `tests/unit/test_users.py::test_change_password_invalidates_the_old_token_but_not_the_new_one`

- **[DEC-37]** **Nessun recupero password, solo reset.** Non si raccoglie
  nessuna email. L'utente autenticato può *cambiare* la password fornendo
  quella attuale; chi l'ha persa si rivolge all'operatore, che con
  `POST /admin/users/{id}/reset-password` ne genera una casuale, mostrata una
  volta sola e registrata in audit (`admin_password_reset`).

  *Codice:* `app/api/routes/users.py:change_password` · `app/api/routes/admin.py:reset_user_password` ·
  *Test:* `tests/unit/test_users.py::test_change_password_requires_current_password`, `tests/unit/test_admin.py::test_admin_resets_user_password`

- **[DEC-38]** **Gli username sono un unico spazio di nomi senza distinzione fra
  maiuscole e minuscole**, garantito da un indice unico su `lower(username)`;
  il nome resta salvato come digitato (è ciò che mostrano `/admin` e l'audit).
  Sono ammessi solo caratteri ASCII `[A-Za-z0-9_.-]`, 3–32. La migrazione si
  rifiuta di partire se due account esistenti differiscono solo per le
  maiuscole, invece di sceglierne uno da rinominare: entrambi potrebbero avere
  fondi.
  - *Motivazione:* «Bob» e «bob» erano due account che condividevano il
    contatore dei tentativi e un comodo vettore di impersonazione (B-57).

  *Codice:* `app/db/models.py:User` · `app/auth/routes.py:register` · `app/auth/routes.py:login` ·
  *Test:* `tests/unit/test_auth.py::test_registration_refuses_a_username_differing_only_by_case`, `tests/unit/test_auth.py::test_the_database_itself_rejects_a_case_variant`

- **[DEC-39]** **L'esportazione della chiave privata WIF di un utente è
  voluta, non una vulnerabilità.** Il server possiede già la master key:
  l'endpoint espone via API solo ciò che un operatore potrebbe comunque
  ottenere con uno script (ad esempio per recuperare fondi bloccati). Ogni
  accesso scrive `admin_privkey_accessed`, e quella registrazione non va tolta.

  *Codice:* `app/api/routes/admin.py:user_privkey` · `app/wallet/hd.py:derive_user_wif` ·
  *Test:* `tests/unit/test_admin.py::test_admin_exports_user_privkey`

- **[DEC-40]** **L'amministrazione usa un unico token condiviso**
  (`X-Admin-Token` confrontato a tempo costante sui byte UTF-8 con
  `ADMIN_TOKEN`), non un login per operatore. `/admin` mostra una schermata di
  inserimento del token, **non è collegato da `/`** (né `/` da `/admin`) ed è in
  italiano, non tradotto.
  - *Conseguenze:* l'audit registra *cosa* è cambiato, mai *chi* l'ha fatto
    ([LIM-06]).

  *Codice:* `app/api/routes/admin.py:require_admin` · `app/main.py:admin_panel` · `app/static/admin.html` ·
  *Test:* `tests/unit/test_admin.py::test_admin_requires_token`, `tests/unit/test_admin.py::test_admin_rejects_non_ascii_token_with_403_not_500`

- **[DEC-41]** **Limitazione dei tentativi solo su login e registrazione**, in
  memoria. Il login usa un ritardo esponenziale per username (dopo 5 errori) e
  per IP (dopo 20, soglia più alta per non punire una rete condivisa); un
  login riuscito azzera solo il contatore dello username. La registrazione usa
  invece una **quota** di 5 account per IP all'ora, consumata solo dagli
  account creati davvero. I contatori sono limitati in numero.
  - *Motivazione:* indovinare una password e creare account in massa sono due
    problemi diversi (B-33, B-58); il ritardo punisce i tentativi, la quota
    limita la produzione.
  - *Conseguenze:* nessun limite su scommesse, prelievi, admin, cambio
    password ([LIM-07]).

  *Codice:* `app/auth/rate_limit.py:AuthRateLimiters` · `app/auth/rate_limit.py:RateLimiter` · `app/auth/rate_limit.py:RollingQuota` · `app/auth/routes.py:login` ·
  *Test:* `tests/unit/test_auth.py`, `tests/unit/test_rate_limit.py`

- **[DEC-42]** **L'IP del client è l'ultimo elemento di `X-Forwarded-For`**, e
  Caddy sovrascrive l'header con il vero indirizzo del peer. Un solo proxy
  fidato sta davanti all'applicazione, che non è esposta direttamente.
  - *Motivazione:* il primo elemento è scelto dal client; leggerlo rendeva
    aggirabile ogni controllo per IP (B-54). Basta una delle due misure.

  *Codice:* `app/api/client_ip.py:client_ip` · `Caddyfile` ·
  *Test:* `tests/unit/test_client_ip.py`, `tests/unit/test_caddyfile_security_headers.py::test_forwarded_for_is_overwritten_with_the_real_peer`

- **[DEC-43]** **Header di sicurezza nel proxy, con `'unsafe-inline'`
  accettato**: HSTS, `nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy` e una
  CSP `default-src 'self'` più Google Fonts. Script e stili inline restano
  permessi perché entrambe le SPA usano `onclick` e `style=""`; rimuoverli è un
  refactoring a parte. La documentazione automatica dell'API (`/docs`,
  `/redoc`, `/openapi.json`) è spenta per default (`ENABLE_API_DOCS`).
  - *Conseguenze:* [LIM-09].

  *Codice:* `Caddyfile` · `app/main.py` · `app/config.py:Settings` ·
  *Test:* `tests/unit/test_caddyfile_security_headers.py`, `tests/unit/test_docs_disabled.py`

- **[DEC-44]** **`/qr/{address}` è pubblico ma limitato**: nessuna
  autenticazione (lo usa un `<img>`, che non può portare il token), ma
  l'indirizzo è validato davvero, la lunghezza è limitata, la resa è in cache
  (512 voci) e fuori dall'event loop.

  *Codice:* `app/api/routes/qr.py:address_qr` ·
  *Test:* `tests/unit/test_qr.py`

- **[DEC-45]** **Segnalazioni di bug aperte a tutti, triage in admin.** Si può
  inviare una segnalazione da autenticati (viene attribuita all'utente) o no;
  il testo va scritto in inglese, e la pagina lo dice nella lingua del
  visitatore. Gli stati sono `open` → `read` → `resolved`, e ogni cambio reale
  di stato è registrato in audit.

  *Codice:* `app/api/routes/bug_reports.py:create_bug_report` · `app/api/routes/admin.py:update_bug_report_status` ·
  *Test:* `tests/unit/test_bug_reports.py`

### Interfacce, API e lingue

- **[DEC-46]** **Il canale SSE è un'aggiunta al polling, non un sostituto.**
  Nessun contenuto e nessuna autenticazione: è solo un «è cambiato qualcosa,
  ricarica»; la personalizzazione resta negli endpoint REST autenticati. Un
  unico segnale per tutti (non per utente), una coda da 1 elemento per client
  così le notifiche ridondanti si fondono, tetto di 500 connessioni globali e 5
  per IP (oltre, si chiude la connessione più vecchia dello stesso IP). Le
  pagine ricaricano anche all'evento `open` di ogni riconnessione.
  - *Alternative scartate:* canale per utente (servirebbe autenticazione sul
    flusso e sapere a chi interessa ogni evento); Redis pub/sub (solo quando ci
    saranno più processi).
  - *Conseguenze:* se il canale cade o è bloccato, le pagine continuano a
    funzionare con il solo polling.

  *Codice:* `app/rounds/events.py:RoundEventBroadcaster` · `app/api/routes/rounds.py:round_stream` ·
  *Test:* `tests/unit/test_round_events.py`

- **[DEC-47]** **L'API parla una sola lingua e risponde con codici.** Ogni
  errore rivolto all'utente ha `detail = {code, message, params}`: `message` è
  in inglese per chi non usa la dashboard, `code` è ciò che il frontend traduce
  (`error.<code>`), `params` porta i valori (gli importi come `*_sats`). Anche
  l'errore 500 generico ha questa forma (`internal_error`) e non espone il
  testo dell'eccezione.
  - *Conseguenze:* aggiungere un errore significa dargli un codice e
    aggiungere `error.<code>` in tutte le 7 lingue (vedi [api.md](api.md)).

  *Codice:* `app/api/errors.py:ApiError` · `app/api/errors.py:http_error` · `app/main.py:log_unhandled_exception` ·
  *Test:* `tests/unit/test_rounds_route.py::test_unhandled_errors_use_the_structured_detail_shape`

- **[DEC-48]** **Le pagine per l'utente (`/` e `/report-bug`) sono in 7 lingue**
  (en, it, es, fr, de, ru, zh) da un'unica tabella piatta, senza build né
  download. Lingua scelta da `localStorage.plm_lang`, poi dal browser, poi
  inglese; nessun'altra lingua di riserva oltre l'inglese. Il selettore di `/`
  sta nella barra di stato della catena, non nella barra di navigazione
  (nascosta prima del login). Un elemento è tradotto *o* dagli attributi
  `data-i18n` *o* dal codice con `t()`, mai da entrambi. Tutte le lingue devono
  avere esattamente le stesse chiavi.
  - *Conseguenze:* la parità delle chiavi non è verificata da un test
    ([LIM-21]).

  *Codice:* `app/static/i18n.js:t` · `app/static/i18n.js:applyStaticTranslations` · `app/static/i18n.js:setLanguage` · `app/static/app.js:onLanguageChange`

- **[DEC-49]** **Il pannello `/admin` e la pagina `/guida` non sono tradotti**
  (sono in italiano, per l'operatore).

  *Codice:* `app/static/admin.html` · `app/static/guida.html`

- **[DEC-50]** **Frontend statici, senza framework né build**: due SPA servite
  direttamente da FastAPI con `Cache-Control: no-store`, che parlano con la
  stessa API JSON (nessuna separazione fra API utente e admin oltre al
  controllo del token).

  *Codice:* `app/main.py:index_page` · `app/main.py:admin_panel` · `app/static/app.js` · `app/static/admin.js`

---

## Parte 2 — Limiti noti (LIM)

Formato di ogni voce: descrizione, *Impatto*, *Mitigazione attuale*, *Per
chiuderlo*, e il codice coinvolto.

### Quali limiti bloccano il funzionamento non presidiato

| Limite | Blocca il non presidiato? |
|---|---|
| [LIM-01] `drawing` non riprende dopo un riavvio | **Sì** — è lo stato che resta fermo con denaro in gioco, e l'ultimo prerequisito dichiarato |
| [LIM-02] RBF di una sola forma (e pagamento senza resto) | **Sì, in caso di congestione della rete** |
| [LIM-03] Attesa in `closing` fino a 6 ore | **Sì, in caso di congestione** (conseguenza di LIM-02) |
| [LIM-04] Prelievo e RBF mai provati in rete reale | **Sì, come verifica** — da fare prima di lasciare il sistema da solo |
| [LIM-06] Token admin unico | No per il funzionamento, ma è il rischio di sicurezza più ampio |
| tutti gli altri | No |

### Robustezza del ciclo di vita

- **[LIM-01]** **Lo stato `drawing` non riprende dopo un riavvio.** Lo
  scheduler gestisce `open`, `closing` e `paying_out` a ogni giro; l'attesa del
  blocco (`_wait_for_next_block`) vive solo dentro la chiamata a
  `_close_and_draw` che l'ha avviata, con la lista dei partecipanti in memoria.
  Se il processo si ferma in quel momento, nessuno la riprende. Il terzo audit
  (2026-08-03) lo ha ribadito come problema **critico**, senza numerarlo
  perché già elencato qui.
  - *Impatto:* il round resta in `drawing` per sempre con il montepremi dentro;
    poiché un nuovo round si apre solo a round chiuso, **l'intera lotteria si
    ferma**. Con `restart: unless-stopped` un crash in quella finestra è
    esattamente il caso che non si ripara da solo.
  - *Mitigazione attuale:* l'attesa è osservabile — log periodici, evento
    `draw_stalled` dopo 360s (e poi a ogni intervallo), `draw_waiting_since` su
    `GET /rounds/current`. Il recupero è manuale (vedi
    [operativita.md](operativita.md)).
  - *Per chiuderlo:* salvare sulla riga del round l'altezza di base
    dell'estrazione al passaggio in `drawing` e, in `_tick`, rientrare in
    `_wait_for_next_block` per un round `drawing` senza un'attesa in corso,
    ricostruendo i partecipanti dal database (sono già tutti `confirmed` e
    ordinabili per `broadcast_at`).

  *Codice:* `app/rounds/scheduler.py:RoundScheduler._tick` · `app/rounds/scheduler.py:RoundScheduler._close_and_draw` · `app/rounds/scheduler.py:RoundScheduler._wait_for_next_block`

- **[LIM-02]** **L'RBF gestisce una sola forma di transazione**: un'unica uscita
  di resto verso il mittente, abbastanza grande da assorbire l'aumento. Non c'è
  il ripiego «aggiungi un'altra moneta». Ogni aumento costa almeno 1 sat/vB
  sull'intera dimensione della transazione (circa 141 sat per una transazione
  con un ingresso e due uscite) e si toglie dal resto; quando l'aumento supera
  il resto, `bump_fee` solleva `RbfError`. Inoltre `bump_fee` **non controlla
  che il resto ridotto resti sopra la soglia di polvere**: con un resto vicino
  al minimo di 294 sat ([DEC-19]) già il primo aumento produce un'uscita sotto
  soglia, che le regole di inoltro standard rifiutano. **Il pagamento del
  round, nel caso normale, non ha alcun resto** (spende esattamente il
  montepremi del round, e un resto sotto soglia va alla commissione), quindi
  non è accelerabile affatto.
  - *Impatto:* con la rete congestionata una transazione a 1 sat/vB può
    restare in mempool indefinitamente. Poiché il riconciliatore abbandona solo
    ciò che il server **non conosce**, una transazione ferma ma presente in
    mempool non viene mai abbandonata: una scommessa così blocca il round in
    `closing`, un pagamento così lo blocca in `paying_out`. `RbfBumper`
    registra un errore ogni 30s.
  - *Mitigazione attuale:* resto minimo garantito sulle transazioni utente;
    tetto al fee rate (`MAX_FEE_RATE_SAT_VB`); abbandono dopo 6 ore per ciò che
    sparisce dalla rete; ritentativo automatico del pagamento dopo un
    abbandono.
  - *Per chiuderlo:* aggiungere ingressi a una transazione da accelerare
    (dall'indirizzo del mittente), oppure CPFP sul resto; per il pagamento,
    garantire un'uscita di resto verso il montepremi come per le transazioni
    utente; in ogni caso rifiutare un aumento che lasci il resto sotto
    `DUST_LIMIT_SATS`. Il docstring di `bump_fee` cita ancora come esempio «una scommessa
    senza resto», caso che dopo B-62 non esiste più.

  *Codice:* `app/tx/broadcast.py:bump_fee` · `app/wallet/psbt_builder.py:build_payout_transaction` · `app/tx/reconcile.py:reconcile_once`

- **[LIM-03]** **L'attesa in `closing` non ha un limite proprio.** Il round
  aspetta ogni scommessa `building`/`broadcast`; a porre fine all'attesa di una
  scommessa che non conferma è solo il riconciliatore, dopo 6 ore dal primo
  invio (e solo se la transazione è sparita dalla rete, [LIM-02]).
  - *Impatto:* un round può restare chiuso ma non estratto per ore; nessun
    nuovo round si apre nel frattempo.
  - *Mitigazione attuale:* lo stato è visibile (`closing`) e il pannello
    «Transazioni pendenti» mostra la scommessa che trattiene il round.
  - *Per chiuderlo:* una politica esplicita per le scommesse lente (per esempio
    escluderle e rimborsarle dopo un tempo massimo), che è una modifica della
    specifica del round, non una correzione.

  *Codice:* `app/rounds/scheduler.py:RoundScheduler._tick` · `app/tx/reconcile.py:_is_due`

- **[LIM-04]** **Prelievo e accelerazione RBF non sono mai stati inviati in una
  rete reale.** Sono coperti da test unitari, rami di errore e annullamento
  compresi; il resto del flusso (registrazione, deposito, scommessa, un ciclo
  completo di round con pagamento) è stato verificato in mainnet.
  - *Impatto:* un errore di costruzione o di firma specifico della rete reale
    emergerebbe al primo prelievo di un utente vero.
  - *Per chiuderlo:* un prelievo e un RBF reali in mainnet, con verifica
    dell'aritmetica sulla transazione inviata.

  *Codice:* `app/withdrawals/service.py:request_withdrawal` · `app/tx/broadcast.py:bump_fee`

- **[LIM-05]** **Nessun test di integrazione con una connessione Electrum
  vera.** `tests/integration/` è vuota; la verifica dal vivo è stata tutta
  manuale (`scripts/electrum_smoke_test.py`, script ad hoc, transazioni reali).
  - *Impatto:* le differenze di comportamento fra implementazioni di server
    Electrum (formati di risposta, errori) emergono solo in produzione.
  - *Per chiuderlo:* una suite su testnet o regtest, o contro un server
    registrato.

  *Codice:* `tests/integration/__init__.py` · `scripts/electrum_smoke_test.py`

### Sicurezza e amministrazione

- **[LIM-06]** **Un unico token admin condiviso, senza identità per
  operatore.** Il registro di audit dice *cosa* è cambiato (per esempio
  `config_updated` con prima/dopo) ma non *chi*. Il token dà accesso a elenco
  utenti, esportazione delle chiavi private, reset delle password e storico.
  Non c'è limite ai tentativi sul token.
  - *Impatto:* una fuga del token ha il raggio d'azione più ampio del sistema,
    ed è impossibile attribuire un'azione a una persona.
  - *Mitigazione attuale:* confronto a tempo costante, pannello chiuso se il
    token è vuoto, ogni azione sensibile in audit, `/admin` non collegato dalla
    pagina pubblica. Dettagli in [sicurezza.md](sicurezza.md).
  - *Per chiuderlo:* account amministrativi individuali (con l'identità scritta
    in ogni voce di audit) e limitazione dei tentativi sul token.

  *Codice:* `app/api/routes/admin.py:require_admin` · `app/audit/log.py:write_audit_log`

- **[LIM-07]** **Nessuna limitazione di frequenza su scommesse, prelievi,
  endpoint admin, cambio password e segnalazioni di bug.** Solo login e
  registrazione sono limitati ([DEC-41]); il canale SSE ha tetti di
  concorrenza (500 globali, 5 per IP), non di frequenza.
  - *Impatto:* un utente autenticato può martellare scommesse e prelievi (il
    blocco per-utente li serializza, non li limita); il cambio password
    permette di provare password attuali senza ritardi a chi possiede già un
    token valido; le segnalazioni anonime possono riempire il database.
  - *Per chiuderlo:* un limitatore per utente e per IP sugli endpoint
    interessati, sullo stesso modello di `RateLimiter`/`RollingQuota`.

  *Codice:* `app/api/routes/bets.py:create_bet` · `app/api/routes/withdrawals.py:create_withdrawal` · `app/api/routes/users.py:change_password` · `app/api/routes/bug_reports.py:create_bug_report`

- **[LIM-08]** **Nessun registro di sicurezza lato utente.** Login, login
  falliti e cambio password dell'utente non scrivono voci di audit (le scrive
  solo il reset da parte dell'admin).
  - *Impatto:* dopo una compromissione non c'è traccia di quando e da dove sia
    avvenuto l'accesso.
  - *Per chiuderlo:* eventi di audit per questi casi (vedi
    [audit-log.md](audit-log.md)).

  *Codice:* `app/auth/routes.py:login` · `app/api/routes/users.py:change_password`

- **[LIM-09]** **Il JWT sta in `localStorage` e la CSP ammette script inline.**
  Una falla XSS permetterebbe di leggere il token.
  - *Mitigazione attuale:* CSP `default-src 'self'`, `frame-ancestors 'none'`,
    escape dei valori controllati dall'utente nelle pagine; sessioni revocabili
    ([DEC-36]).
  - *Per chiuderlo:* togliere gestori e stili inline dalle SPA per poter
    eliminare `'unsafe-inline'`, oppure spostare la sessione in un cookie
    `HttpOnly`.

  *Codice:* `Caddyfile` · `app/static/app.js`

### Fiducia nella rete

- **[LIM-10]** **Rischio di reorg a 1 conferma accettato, senza rollback.** Un
  deposito accreditato a 1 conferma può sparire con una riorganizzazione; la
  punta della catena non regredisce mai e un header concorrente alla stessa
  altezza è ignorato.
  - *Mitigazione attuale:* una moneta che sparisce dall'elenco del server viene,
    previo quorum, segnata come spesa all'esterno e tolta dal saldo; se
    riappare viene ripristinata. Una scommessa costruita su una moneta
    scomparsa è rifiutata dalla rete e annullata.
  - *Per chiuderlo:* soglie di conferma più alte (decisione esplicita,
    [DEC-06]) o una gestione completa dei reorg.

  *Codice:* `app/deposits/service.py:find_utxos_missing_from` · `app/deposits/service.py:reinstate_reappeared_utxos` · `app/electrum/listener.py:ElectrumListener._apply_header`

- **[LIM-11]** **Senza server di riserva configurati la corroborazione passa
  sempre.** Con `ELECTRUM_FALLBACK_SERVERS` vuoto il solo server primario decide
  estrazione, spese esterne e accrediti. Anche con server di riserva, la
  maggioranza è calcolata **su chi risponde**, fra server scelti dall'operatore.
  - *Impatto:* chi controlla il server primario (o la maggioranza dei server
    raggiungibili) può scegliere il vincitore o alterare i saldi mostrati.
  - *Mitigazione attuale:* nessun server risponde → la corroborazione
    **fallisce** (una rete irraggiungibile non prova nulla).
  - *Per chiuderlo:* rendere obbligatorio un numero minimo di server di riserva,
    o un quorum minimo di risposte.

  *Codice:* `app/electrum/listener.py:ElectrumListener._corroborate_majority`

- **[LIM-12]** **Non tutte le letture di rete sono corroborate.** Passano dal
  solo server attivo: la conferma di scommesse, pagamenti e prelievi
  (`poll_once`), la decisione del riconciliatore che una transazione «non
  esiste più», l'elenco delle monete del montepremi usato per il pagamento, e il
  ripristino di una moneta prima segnata come spesa all'esterno.
  - *Impatto:* un server ostile potrebbe far considerare confermata una
    scommessa che non lo è, o far abbandonare a torto una transazione viva
    (liberandone le monete e, per un pagamento, azzerando `payout_txid`),
    lasciando il database in disaccordo con la catena; il ripristino non
    corroborato può reintegrare nel saldo una moneta davvero spesa.
  - *Mitigazione attuale:* l'abbandono avviene solo dopo 6 ore per `pending`; un
    invio basato su monete inesistenti è rifiutato dalla rete.
  - *Per chiuderlo:* estendere il quorum di [DEC-07] a queste decisioni.
    Il ripristino in particolare contraddice il principio «entrambe le
    direzioni richiedono il quorum» ed è un candidato a un `B-nn`.

  *Codice:* `app/tx/confirmation.py:poll_once` · `app/tx/reconcile.py:reconcile_once` · `app/deposits/service.py:reinstate_reappeared_utxos` · `app/rounds/scheduler.py:RoundScheduler._trigger_payout`

- **[LIM-13]** **Limiti della forma attuale dell'estrazione.**
  - *Entropia dal minatore:* chi mina il blocco può scegliere di non
    pubblicarlo se l'esito non gli conviene, rinunciando alla ricompensa.
  - *Verificabilità:* l'ordine dei partecipanti è l'orario di invio registrato
    dal server, un dato non pubblico; un giocatore non può ricalcolare da solo
    l'esito dai soli dati di catena (il commento di `draw_winner` dice il
    contrario).
  - *Pareggi:* due scommesse con lo stesso `broadcast_at` non hanno un criterio
    secondario di ordinamento.
  - *Distorsione del modulo:* un seme da 256 bit modulo al più 400 partecipanti
    introduce una distorsione trascurabile.
  - *Per chiuderlo:* sostituire l'algoritmo ([DEC-24]) con uno che pubblichi
    l'ordine dei partecipanti (o lo derivi da dati di catena) e un criterio di
    pareggio totale.

  *Codice:* `app/rounds/draw.py:draw_winner` · `app/rounds/scheduler.py:RoundScheduler._close_and_draw`

- **[LIM-14]** **La validazione degli header non ricostruisce la difficoltà
  reale.** Un server può dichiarare un bersaglio facile e minare davvero un
  header a quella difficoltà con hardware modesto; la concatenazione si
  verifica solo per un avanzamento di un blocco esatto.
  - *Mitigazione attuale:* la corroborazione del blocco usato per l'estrazione
    ([DEC-07], [DEC-25]).
  - *Per chiuderlo:* validazione della catena degli header con le regole di
    ricalcolo della difficoltà di PLM.

  *Codice:* `app/rounds/draw.py:header_meets_its_own_target` · `app/electrum/listener.py:ElectrumListener._apply_header`

- **[LIM-15]** **La sottoscrizione di un nuovo indirizzo è a sforzo
  singolo.** Se fallisce subito dopo la registrazione, l'indirizzo resta non
  osservato fino alla riconnessione successiva o al giro di `DepositReconciler`
  (300s, che attende prima di partire).
  - *Impatto:* un deposito fatto subito dopo la registrazione può tardare fino
    a cinque minuti.

  *Codice:* `app/electrum/listener.py:ElectrumListener.address_for_new_user` · `app/deposits/reconcile.py:DepositReconciler`

### Configurazione ed economia

- **[LIM-16]** **Solo i tempi del round sono fotografati all'apertura.** Costo
  della scommessa, fee rate e `fee_address` sono letti dal vivo.
  - *Impatto:* cambiare il costo a metà round fa pagare poste diverse a
    giocatori con la stessa probabilità, e cambia subito il prelievo minimo;
    cambiare `fee_address` a metà round devia la commissione del round in
    corso (la modifica è comunque registrata in audit).
  - *Per chiuderlo:* fotografare anche questi campi sulla riga del round, come
    già si fa per durata e pausa ([DEC-10]).

  *Codice:* `app/bets/service.py:place_bet` · `app/rounds/scheduler.py:RoundScheduler._trigger_payout` · `app/withdrawals/service.py:request_withdrawal`

- **[LIM-17]** **Nessun consolidamento automatico del montepremi.** Monete
  avanzate e resti si accumulano sull'unico indirizzo del montepremi; il
  margine fra 400 partecipanti e 500 ingressi ([DEC-21]) si consuma nel tempo.
  - *Impatto:* raggiunto il limite, il pagamento fallisce con
    `too_many_inputs` e il round resta in `paying_out`, con un `payout_failed`
    ogni 60s.
  - *Per chiuderlo:* un'operazione di consolidamento (manuale o automatica) del
    montepremi. Procedura in [operativita.md](operativita.md).

  *Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout` · `app/wallet/psbt_builder.py:build_payout_transaction`

### Prodotto e interfacce

- **[LIM-18]** **Il sistema presuppone un solo processo.** Canale SSE, blocchi
  per-utente, limitatori di tentativi, cache dei QR e della chiave dell'account
  sono in memoria.
  - *Impatto:* con più worker, due costruzioni dello stesso utente potrebbero
    scegliere le stesse monete, i limiti per IP si dividerebbero per worker e
    gli eventi SSE arriverebbero solo ai client dello stesso worker.
  - *Per chiuderlo:* canale condiviso (Redis pub/sub) e lock su database o
    Redis. L'invariante del round attivo è già un indice e non rientra qui.

  *Codice:* `app/tx/locks.py:UserLocks` · `app/rounds/events.py:RoundEventBroadcaster` · `app/auth/rate_limit.py:AuthRateLimiters`

- **[LIM-19]** **Nessuna cronologia per l'utente.** L'utente non vede lo storico
  dei round, delle scommesse, dei depositi o dei prelievi: un prelievo fallito
  lascia una riga `failed` che l'utente non può mai vedere. Esistono solo
  `GET /users/me/last-round-result` (l'ultimo round giocato) e
  `GET /bug-reports/mine`. L'operatore ha invece `/admin/rounds`,
  `/admin/pending-transactions`, `/admin/audit-log`.
  - *Per chiuderlo:* endpoint e sezione di cronologia personale.

  *Codice:* `app/api/routes/users.py:last_round_result` · `app/withdrawals/service.py:request_withdrawal`

- **[LIM-20]** **`/guida` è un segnaposto.** Il collegamento funziona ma la
  pagina dice che la guida arriverà. (`/report-bug` invece è completa e
  tradotta.)

  *Codice:* `app/main.py:user_guide` · `app/static/guida.html`

- **[LIM-21]** **La parità delle chiavi di traduzione non è verificata da un
  test.** Oggi le 7 lingue hanno le stesse 151 chiavi, ma nulla lo impone: una
  chiave mancante ricade sull'inglese e, se manca anche lì, viene mostrata la
  chiave grezza.
  - *Per chiuderlo:* un test che confronti gli insiemi di chiavi di
    `TRANSLATIONS`.

  *Codice:* `app/static/i18n.js:t`

- **[LIM-22]** **L'API di amministrazione e alcuni errori di contorno non usano
  il formato d'errore strutturato.** Gli endpoint `/admin/*` rispondono con un
  `detail` stringa (per esempio `"invalid admin token"`, `"user not found"`), e
  così il 503 del canale SSE oltre il tetto; è coerente con un pannello non
  tradotto, ma non è dichiarato altrove.
  - *Per chiuderlo:* usare `http_error` anche lì, se il pannello dovrà mai
    tradurre o distinguere gli errori.

  *Codice:* `app/api/routes/admin.py:require_admin` · `app/api/routes/rounds.py:round_stream`

- **[LIM-23]** **`GET /admin/users` non ha limite né paginazione**, a
  differenza degli altri elenchi admin.
  - *Impatto:* con molti utenti la risposta cresce senza limite.

  *Codice:* `app/api/routes/admin.py:list_users`