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

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.

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

  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.

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

  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.

  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.

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

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

  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.

  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