344 lines
20 KiB
Markdown
344 lines
20 KiB
Markdown
# 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`
|