Files
plm-lottery/docs/ciclo-di-vita-del-round.md
T
davideandClaude Opus 5.5 61efbb0e37 Replace flowchart/ with a traceable specification in docs/
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>
2026-09-28 12:16:01 +02:00

20 KiB
Raw Blame History

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

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

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

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). 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). 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). 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). Codice: app/rounds/scheduler.py:RoundScheduler._tick