# Ciclo di vita del round Fase 4 del [funzionamento generale](come-funziona.md): come un round si apre, si chiude, estrae un vincitore e lo paga. Tutto è guidato da `RoundScheduler`, che si risveglia ogni 5 secondi. I requisiti usano il prefisso `RND`, secondo la convenzione di [processo-di-modifica.md](processo-di-modifica.md). Le colonne della tabella `rounds` sono descritte in [modello-dati.md](modello-dati.md), gli eventi di audit in [audit-log.md](audit-log.md), le attività in background in [architettura.md](architettura.md). - **[RND-01]** Lo scheduler esegue un passo ogni 5 secondi (`_TICK_INTERVAL_SECONDS`). Un passo non fa nulla se non c'è connessione a Electrum: senza rete nessun round si apre, si chiude o si paga. Un errore in un passo viene registrato nei log e non ferma i passi successivi. *Codice:* `app/rounds/scheduler.py:RoundScheduler.run`, `app/rounds/scheduler.py:RoundScheduler._tick` · *Test:* `tests/unit/test_scheduler.py` ## Gli stati ```mermaid stateDiagram-v2 [*] --> open: nessun round attivo,
pausa tra i round trascorsa,
lotteria non in manutenzione,
indirizzo commissioni impostato open --> closing: scade il tempo
(al primo passo dopo la scadenza) closing --> closing: scommesse ancora in volo closing --> closed: nessun partecipante confermato closing --> drawing: tutte le scommesse confermate drawing --> drawing: blocco non corroborato,
si attende il successivo drawing --> paying_out: nuovo blocco corroborato,
vincitore scelto paying_out --> paying_out: pagamento fallito o abbandonato,
nuovo tentativo dopo 60s paying_out --> closed: pagamento confermato closed --> [*] ``` | Stato | Significato | |---|---| | `open` | Accetta scommesse fino alla scadenza | | `closing` | Scadenza passata: nessuna nuova scommessa, si aspettano quelle già inviate | | `drawing` | Partecipanti fissati, si attende il blocco che sceglie il vincitore | | `paying_out` | Vincitore noto, pagamento in costruzione, inviato o in attesa di conferma | | `closed` | Concluso (con o senza vincitore) | - **[RND-02]** Gli stati sono esattamente quelli della tabella e le sole transizioni sono quelle del diagramma; `closed` è definitivo. *Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`, `app/rounds/scheduler.py:RoundScheduler._close_and_draw`, `app/rounds/confirmation.py:_on_payout_confirmed` · *Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_confirmation.py` - **[RND-03]** **Al massimo un round attivo alla volta** (cioè in uno stato diverso da `closed`). Non è una convenzione ma un vincolo del database: un indice univoco (`ix_rounds_single_active`) fa fallire un secondo inserimento concorrente, e il codice di apertura in quel caso adotta il round già creato (fino a 3 tentativi, `_OPEN_ROUND_ATTEMPTS`). Se mai risultassero due round attivi, si usa il più recente e lo si segnala nei log come violazione. *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` ## 0 · Apertura L'apertura viene tentata a ogni passo dello scheduler e anche da ogni richiesta di scommessa (vedi [scommesse-e-prelievi.md](scommesse-e-prelievi.md#quando-è-accettata)). - **[RND-04]** Un nuovo round si apre solo quando **tutte** queste condizioni sono vere: - nessun round è attivo (il precedente è `closed`); - è trascorsa la **pausa tra i round** del round chiuso più recente, contata dal suo `closed_at`: per un round pagato è il momento della conferma del pagamento, per un round chiuso senza partecipanti è il momento della chiusura. Serve a lasciare ai giocatori il tempo di vedere il risultato; - la lotteria **non è in manutenzione** (`POST /admin/pause`); - l'**indirizzo delle commissioni** (`fee_address`) è impostato (un valore di soli spazi conta come vuoto). Senza, il pagamento non si potrebbe costruire, quindi il round non viene nemmeno aperto invece di bloccarsi più avanti con i soldi già nel montepremi. *Codice:* `app/rounds/service.py:open_new_round_if_needed`, `app/rounds/service.py:rounds_can_open` · *Test:* `tests/unit/test_rounds_service.py` - **[RND-05]** All'apertura il round **fotografa** la durata (`round_duration_seconds`, 600s predefiniti) e la pausa (`round_cooldown_seconds`, 30s predefiniti) correnti. Scadenza del round e pausa successiva usano sempre i valori fotografati: una modifica da `/admin` vale dal round successivo, mai per quello in corso. *Codice:* `app/rounds/service.py:open_new_round_if_needed`, `app/rounds/service.py:round_deadline` · *Test:* `tests/unit/test_rounds_service.py`, `tests/unit/test_scheduler.py` - **[RND-06]** La pausa di manutenzione e l'indirizzo mancante bloccano solo l'apertura del *prossimo* round: un round già in corso prosegue fino al pagamento, anche se l'indirizzo viene cancellato nel frattempo. `GET /rounds/current` espone i due casi separatamente (`lottery_paused`, `lottery_configured`) perché `/` mostri avvisi diversi. Le procedure sono in [guida-admin.md](guida-admin.md). *Codice:* `app/rounds/service.py:open_new_round_if_needed`, `app/api/routes/rounds.py:current_round` · *Test:* `tests/unit/test_rounds_service.py`, `tests/unit/test_rounds_route.py` - **[RND-07]** L'apertura di un round invia una notifica SSE. *Codice:* `app/rounds/service.py:open_new_round_if_needed` ## 1 · Round aperto Il round accetta scommesse fino a `apertura + durata`. Le regole di accettazione sono in [scommesse-e-prelievi.md](scommesse-e-prelievi.md#quando-è-accettata). - **[RND-08]** La scadenza (`closes_at`) è `opened_at` più la durata fotografata all'apertura; è la stessa usata per rifiutare le scommesse e per chiudere il round. *Codice:* `app/rounds/service.py:round_deadline`, `app/rounds/service.py:round_accepts_bets` · *Test:* `tests/unit/test_rounds_service.py` - **[RND-09]** `GET /rounds/current` pubblica il montepremi in due forme: - `jackpot_sats` e `participant_count`: calcolati sulle sole scommesse **confermate** — esattamente ciò che l'estrazione considererà e che il pagamento potrà spendere. `jackpot_sats` è già il 70% del vincitore (arrotondato per difetto) della somma degli importi netti, non l'intero montepremi; resta un limite superiore, perché la commissione del pagamento sarà dedotta da lì; - `pending_jackpot_sats` e `pending_participant_count`: gli stessi valori includendo le scommesse ancora in volo (`building`, `broadcast`), come totali e non come differenze; `has_pending_bets` dice se differiscono. *Codice:* `app/api/routes/rounds.py:current_round`, `app/rounds/service.py:winner_share` · *Test:* `tests/unit/test_rounds_route.py` - **[RND-10]** `user_played` è vero solo se chi chiama è autenticato e ha una scommessa nel round attivo; senza login la risposta non è personalizzata. *Codice:* `app/api/routes/rounds.py:current_round` · *Test:* `tests/unit/test_rounds_route.py` L'interfaccia mostra in grande i valori confermati e la differenza come suffisso ambra "+N in attesa": chi ha appena scommesso vede subito la propria giocata, ma il montepremi pubblicizzato non supera mai quello che verrà pagato. ## 2 · Chiusura - **[RND-11]** Al primo passo dello scheduler dopo la scadenza (quindi entro circa 5 secondi) il round passa a `closing`, qualunque cosa stia accadendo: si annota `closed_at` e si invia una notifica SSE. Le scommesse sono però rifiutate già dall'istante della scadenza ([BET-04](scommesse-e-prelievi.md#quando-è-accettata)). *Codice:* `app/rounds/scheduler.py:RoundScheduler._tick` · *Test:* `tests/unit/test_scheduler.py` - **[RND-12]** Poi il round **attende che ogni scommessa già inviata sia confermata** (il "semaforo giallo"): finché esiste un partecipante in stato `building` o `broadcast` il round resta `closing` e il controllo si ripete al passo successivo. Il controllo viene ripetuto anche nella stessa sessione del database in cui si fissa l'elenco dei partecipanti, così una scommessa salvata tra i due controlli non può restare esclusa. Una scommessa partita un attimo prima della scadenza resta quindi valida e non va persa. Ciò che impedisce all'attesa di durare per sempre è il riconciliatore, che prima o poi abbandona una scommessa che non conferma mai ([TX-17](transazioni-e-riconciliazione.md#riconciliazione)). *Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`, `app/rounds/scheduler.py:RoundScheduler._close_and_draw` · *Test:* `tests/unit/test_scheduler.py` - **[RND-13]** Quando non resta nulla in volo e **nessun partecipante è confermato**, il round passa a `closed` senza vincitore, si scrive `round_closed` (con `participants: 0`) e si invia una notifica SSE. *Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` · *Test:* `tests/unit/test_scheduler.py` - **[RND-14]** Con **almeno un partecipante confermato**, si fissa l'elenco dei partecipanti confermati, ordinato per momento di invio della scommessa, si somma il montepremi dai loro importi netti, e il round passa a `drawing` annotando `drawing_started_at`; si invia una notifica SSE. L'altezza della catena nota in quell'istante diventa il riferimento dell'estrazione. *Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` · *Test:* `tests/unit/test_scheduler.py` ## 3 · Estrazione L'estrazione usa come fonte di casualità l'**hash di un blocco confermato dopo la chiusura**, un valore che nessuno conosceva mentre le scommesse erano aperte. ```mermaid flowchart TB A["Altezza nota alla chiusura
(se sconosciuta: la prima che si
viene a sapere, draw_baseline_tip_unknown)"] --> B{"La punta della catena
è più alta?
(controllo ogni 5s)"} B -- "No" --> B B -- "Sì" --> C{"La maggioranza degli
altri server conferma
l'hash a quell'altezza?"} C -- "No" --> D["Registrato in audit
(draw_header_corroboration_failed),
quell'altezza diventa il nuovo riferimento"] --> B C -- "Sì" --> E["seme = hash come numero intero
indice = seme mod numero partecipanti"] E --> F["Vincitore = partecipante all'indice"] ``` - **[RND-15]** L'estrazione attende che la punta della catena superi l'altezza di riferimento, controllando ogni 5 secondi; il blocco candidato è la punta nota in quel momento (di norma il primo blocco dopo la chiusura). Per tutta l'attesa lo scheduler resta dentro l'estrazione e non esegue altri passi. *Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_next_block` · *Test:* `tests/unit/test_scheduler.py` - **[RND-16]** **Blocco corroborato**: l'header ricevuto dal server Electrum attivo è l'unica fonte di casualità, quindi un server malevolo che lo falsificasse sceglierebbe il vincitore. Per questo, prima di usarlo, lo si fa confermare dagli altri server ([ELC-15](connessione-electrum.md#5-il-quorum)). Se la conferma manca, si scrive `draw_header_corroboration_failed` (altezza e hash riportato), il blocco non viene mai usato e si attende un blocco ulteriore. *Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_next_block`, `app/electrum/listener.py:ElectrumListener.corroborate_header` · *Test:* `tests/unit/test_scheduler.py` - **[RND-17]** **Algoritmo**: seme = hash del blocco letto come numero esadecimale, indice = seme modulo numero dei partecipanti, vincitore = il partecipante in quella posizione dell'elenco ordinato per momento di invio. **Probabilità uguale per tutti**: ogni partecipante ha una e una sola posizione nell'elenco, indipendentemente dall'importo. *Codice:* `app/rounds/draw.py:draw_winner`, `app/rounds/scheduler.py:RoundScheduler._close_and_draw` · *Test:* `tests/unit/test_draw.py` - **[RND-18]** **Verificabile**: il round salva altezza e hash del blocco (`draw_block_height`, `draw_block_hash`), il seme (`seed_int`), il vincitore e il montepremi (`pool_amount_sats`), passa a `paying_out`, scrive `winner_drawn` (indirizzo del vincitore, montepremi, altezza, hash, numero di partecipanti) e invia una notifica SSE. Chiunque, con l'hash del blocco e l'elenco dei partecipanti, può rifare il calcolo. Il primo tentativo di pagamento parte subito dopo. *Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` · *Test:* `tests/unit/test_scheduler.py` - **[RND-19]** **Altezza iniziale sconosciuta**: se alla chiusura l'altezza della catena non era nota (valore 0), non si parte da zero (qualunque blocco già esistente sarebbe "successivo", e quindi prevedibile): si attende il primo header, se ne adotta l'altezza come riferimento, si scrive `draw_baseline_tip_unknown` e si aspetta un blocco strettamente successivo. In condizioni normali non accade, perché la connessione è resa disponibile solo con l'altezza già nota ([ELC-07](connessione-electrum.md#3-caduta-rilevata)). *Codice:* `app/rounds/scheduler.py:RoundScheduler._adopt_baseline_tip` · *Test:* `tests/unit/test_scheduler.py` - **[RND-20]** **Attesa lunga ma visibile**: l'attesa non ha un limite, perché dipende davvero dall'arrivo di un blocco. Ogni 60 secondi se ne registra l'avanzamento nei log; dopo 6 minuti (`_DRAW_STALL_THRESHOLD_SECONDS` = 360s) viene scritto un evento `draw_stalled`, ripetuto ogni 6 minuti finché l'attesa continua. Durante `drawing`, `GET /rounds/current` espone `draw_waiting_since` (l'orario di inizio dell'attesa); negli altri stati il campo è assente. *Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_next_block`, `app/api/routes/rounds.py:current_round` · *Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_rounds_route.py` L'algoritmo è volutamente semplice ed è pensato per essere **sostituito** (vedi [decisioni-e-limiti.md](decisioni-e-limiti.md)). ## 4 · Pagamento Con il vincitore noto il round è in `paying_out` e si costruisce il pagamento, firmato con la chiave del montepremi. - **[RND-21]** **Ripartizione**: il vincitore riceve il 70% del montepremi arrotondato per difetto, l'indirizzo delle commissioni il resto (30% più l'eventuale resto dell'arrotondamento). La ripartizione è fissata nel codice, non modificabile da `/admin`. *Codice:* `app/rounds/service.py:winner_share`, `app/rounds/scheduler.py:RoundScheduler._trigger_payout` · *Test:* `tests/unit/test_payout_builder.py` - **[RND-22]** Il pagamento spende le monete **confermate** dell'indirizzo del montepremi, lette dal server Electrum attivo ed escluse quelle già impegnate da un altro pagamento non risolto ([RND-26]), scelte dalla più grande fino a coprire il montepremi e al massimo 500 (`MAX_PAYOUT_TX_INPUTS`). Non abbastanza monete dà il motivo `insufficient pool UTXOs`, troppe `too_many_inputs`. *Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout`, `app/wallet/psbt_builder.py:build_payout_transaction` · *Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_payout_builder.py` - **[RND-23]** La transazione ha un'uscita verso l'indirizzo del vincitore, una verso l'indirizzo delle commissioni e, se supera 294 sat, una di resto verso il montepremi (un resto inferiore va alla commissione di rete). La **commissione di rete** (stimata su tre uscite, a `fee_rate_sat_vb`) è pagata dalla quota del vincitore, così il 30% resta intatto. Se la quota del vincitore meno la commissione, o la quota delle commissioni, scende sotto 294 sat, il pagamento non si costruisce (`winner_share_below_network_fee`, `commission_below_dust_limit`). *Codice:* `app/wallet/psbt_builder.py:build_payout_transaction` · *Test:* `tests/unit/test_payout_builder.py` - **[RND-24]** **Prima si scrive, poi si invia**: prima dell'invio il round registra importo del vincitore (`winner_amount_sats`), commissioni (`fee_amount_sats`) e txid (`payout_txid`), e si salva una transazione in corso di tipo `payout` in stato `building`. Se l'invio riesce, la transazione passa a `pending` e si scrive `payout_sent`. Se fallisce, la riga resta `building` e si scrive `payout_failed`: sarà il riconciliatore a constatare che la rete non la conosce, abbandonarla e liberare il round per un nuovo tentativo ([TX-18](transazioni-e-riconciliazione.md#pagamenti-del-round-riprovare-senza-pagare-due-volte)). *Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout` · *Test:* `tests/unit/test_scheduler.py` - **[RND-25]** Ogni tentativo che non arriva all'invio riuscito scrive un evento `payout_failed` con il motivo: `electrum client not connected`, `no fee_address configured`, `winner user not found`, `insufficient pool UTXOs`, il codice dell'errore di costruzione (`too_many_inputs`, `winner_share_below_network_fee`, `commission_below_dust_limit`), `payout build failed` per ogni altro errore di costruzione, `broadcast rejected`. A ogni passo lo scheduler riesamina un round in `paying_out` e riprova **al massimo una volta ogni 60 secondi** (`_PAYOUT_RETRY_INTERVAL_SECONDS`), misurati dall'ultimo `payout_failed` di quel round; senza alcun `payout_failed` (ad esempio dopo un riavvio) riprova subito. *Codice:* `app/rounds/scheduler.py:RoundScheduler._retry_payout_if_due`, `app/rounds/scheduler.py:RoundScheduler._log_payout_failure` · *Test:* `tests/unit/test_scheduler.py` - **[RND-26]** Due protezioni impediscono di pagare due volte: non si costruisce un nuovo pagamento se per il round ne esiste già uno `building` o `pending` (il tentativo termina senza fare nulla), e le monete del montepremi impegnate da un qualunque pagamento non risolto, anche di un round precedente, sono escluse dalla selezione. *Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout`, `app/rounds/scheduler.py:_reserved_payout_outpoints` · *Test:* `tests/unit/test_scheduler.py` - **[RND-27]** Se il pagamento non conferma in tempo si applica l'RBF, pagato dal resto del montepremi ([TX-11](transazioni-e-riconciliazione.md#rbf-accelerare-una-transazione-lenta)). *Codice:* `app/tx/broadcast.py:bump_fee` - **[RND-28]** Quando il pagamento è confermato il round passa a `closed` e `closed_at` viene riscritto con l'orario della conferma: da lì parte la pausa prima del round successivo. Il vincitore si vede accreditare la vincita come un normale deposito ([registrazione-e-depositi.md](registrazione-e-depositi.md#deposito)). *Codice:* `app/rounds/confirmation.py:_on_payout_confirmed` · *Test:* `tests/unit/test_confirmation.py` ## Tempi reali Tra lo scadere del timer e l'arrivo della vincita ci sono **tre conferme distinte**, ognuna in un blocco diverso: 1. l'ultima scommessa in volo (può essere già avvenuta prima della scadenza); 2. il blocco dell'estrazione, necessariamente successivo al punto 1; 3. il pagamento, costruito solo dopo il punto 2. Con blocchi da 120 secondi sono circa **2–4 minuti** nel caso migliore e **4–6** nel peggiore, indipendentemente da `draw_animation_seconds`. ## Cosa vede il giocatore Due livelli indipendenti: - **[RND-29]** A **tutti** i visitatori, per l'intera durata di `closing`, `drawing` e `paying_out`, un riquadro con la fase in corso (ad esempio "Pagamento al vincitore in corso…"). *Codice:* `app/static/app.js:refreshRound` - **[RND-30]** **In più**, solo a chi ha giocato quel round (`user_played`), il riquadro personale "Hai vinto!" / "Non hai vinto". Il risultato compare quando il vincitore è noto (quindi da `paying_out`), non prima di `draw_animation_seconds` (20s predefiniti) dall'orario di chiusura del server `closes_at` — così ricaricare la pagina non fa ripartire il conto alla rovescia — e, per il vincitore, solo quando è noto l'importo vinto. *Codice:* `app/static/app.js:refreshRound` - **[RND-31]** Una volta rivelato, il risultato resta salvato nel browser (`localStorage.plm_persisted_result`) anche dopo che il round è `closed` (quando `GET /rounds/current` non lo restituisce più), fino all'apertura di un round nuovo. Per un dispositivo che si è perso del tutto la finestra, `GET /users/me/last-round-result` restituisce dal database l'ultimo round `closed` a cui l'utente ha partecipato, se ha vinto e l'importo vinto. *Codice:* `app/static/app.js:checkLastRoundResult`, `app/api/routes/users.py:last_round_result` ## Limite noto - **[RND-32]** Se il server si riavvia mentre un round è in `drawing`, l'attesa del blocco **non riprende da sola**: lo scheduler riprende i round in `closing` e `paying_out`, ma su un round in `drawing` non fa nulla. È l'ultimo prerequisito mancante per un funzionamento completamente non presidiato (vedi [decisioni-e-limiti.md](decisioni-e-limiti.md)). *Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`