Files
plm-lottery/docs/ciclo-di-vita-del-round.md
T

344 lines
20 KiB
Markdown
Raw Normal View History

# 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,<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](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<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](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`