The two Mermaid diagrams under flowchart/ described the intended flow but had drifted from the code and carried no link back to it. docs/ now holds the specification instead: 15 Italian documents (flows, architecture, data model, API, security, audit log, operations, decisions and limits, bug history) with 472 numbered requirements, each pointing at the function that implements it and the test that covers it. docs/processo-di-modifica.md defines the ID convention and the spec -> code -> test change workflow, and CLAUDE.md now names docs/ as authoritative. Writing the spec from the code also corrected stale claims in CLAUDE.md (B-41's get_history check, BUGS.md still tracking B-71/B-72, Cache-Control scope, the error contract's bare-string exceptions) and in the operator guides (payouts do retry, only `drawing` fails to resume, rounds do not open without fee_address). The B-70 doc test now pins the prose in docs/scommesse-e-prelievi.md instead of the deleted diagram. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
20 KiB
Ciclo di vita del round
Fase 4 del funzionamento generale: 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. Le colonne della tabella
rounds sono descritte in modello-dati.md, gli eventi di
audit in audit-log.md, le attività in background in
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
stateDiagram-v2
[*] --> open: nessun round attivo,<br/>pausa tra i round trascorsa,<br/>lotteria non in manutenzione,<br/>indirizzo commissioni impostato
open --> closing: scade il tempo<br/>(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,<br/>si attende il successivo
drawing --> paying_out: nuovo blocco corroborato,<br/>vincitore scelto
paying_out --> paying_out: pagamento fallito o abbandonato,<br/>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).
-
[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 - nessun round è attivo (il precedente è
-
[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/adminvale 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/currentespone i due casi separatamente (lottery_paused,lottery_configured) perché/mostri avvisi diversi. Le procedure sono in 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.
-
[RND-08] La scadenza (
closes_at) èopened_atpiù 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/currentpubblica il montepremi in due forme:jackpot_satseparticipant_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_satsepending_participant_count: gli stessi valori includendo le scommesse ancora in volo (building,broadcast), come totali e non come differenze;has_pending_betsdice 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 annotaclosed_ate si invia una notifica SSE. Le scommesse sono però rifiutate già dall'istante della scadenza (BET-04). 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
buildingobroadcastil round restaclosinge 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). 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
closedsenza vincitore, si scriveround_closed(conparticipants: 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
drawingannotandodrawing_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.
flowchart TB
A["Altezza nota alla chiusura<br/>(se sconosciuta: la prima che si<br/>viene a sapere, draw_baseline_tip_unknown)"] --> B{"La punta della catena<br/>è più alta?<br/>(controllo ogni 5s)"}
B -- "No" --> B
B -- "Sì" --> C{"La maggioranza degli<br/>altri server conferma<br/>l'hash a quell'altezza?"}
C -- "No" --> D["Registrato in audit<br/>(draw_header_corroboration_failed),<br/>quell'altezza diventa il nuovo riferimento"] --> B
C -- "Sì" --> E["seme = hash come numero intero<br/>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). 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 apaying_out, scrivewinner_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_unknowne si aspetta un blocco strettamente successivo. In condizioni normali non accade, perché la connessione è resa disponibile solo con l'altezza già nota (ELC-07). 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 eventodraw_stalled, ripetuto ogni 6 minuti finché l'attesa continua. Durantedrawing,GET /rounds/currentesponedraw_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).
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 motivoinsufficient pool UTXOs, troppetoo_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 tipopayoutin statobuilding. Se l'invio riesce, la transazione passa apendinge si scrivepayout_sent. Se fallisce, la riga restabuildinge si scrivepayout_failed: sarà il riconciliatore a constatare che la rete non la conosce, abbandonarla e liberare il round per un nuovo tentativo (TX-18). 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_failedcon 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 failedper ogni altro errore di costruzione,broadcast rejected. A ogni passo lo scheduler riesamina un round inpaying_oute riprova al massimo una volta ogni 60 secondi (_PAYOUT_RETRY_INTERVAL_SECONDS), misurati dall'ultimopayout_faileddi quel round; senza alcunpayout_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
buildingopending(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).
Codice:
app/tx/broadcast.py:bump_fee - [RND-28] Quando il pagamento è confermato il round passa a
closedeclosed_atviene 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). 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:
- l'ultima scommessa in volo (può essere già avvenuta prima della scadenza);
- il blocco dell'estrazione, necessariamente successivo al punto 1;
- 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,drawingepaying_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 dapaying_out), non prima didraw_animation_seconds(20s predefiniti) dall'orario di chiusura del servercloses_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(quandoGET /rounds/currentnon 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-resultrestituisce dal database l'ultimo roundcloseda 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 inclosingepaying_out, ma su un round indrawingnon fa nulla. È l'ultimo prerequisito mancante per un funzionamento completamente non presidiato (vedi decisioni-e-limiti.md). Codice:app/rounds/scheduler.py:RoundScheduler._tick