The seed was the hash of the first block seen after the close, so a miner holding tickets
could withhold blocks until one made them win, the active Electrum server could pick which
real block was used by not announcing another (a failed corroboration even moved the draw to
the next block), and the participant order was the server-only `broadcast_at` with no
tie-break, so nobody could recompute the result.
- Open: every round gets a 32-byte `server_seed`, stored only Fernet-encrypted with the
master-xprv key (`server_seed_enc`), with its published `server_seed_hash`;
`draw_confirmations` is copied from round_config. The plaintext column is written only by
the reveal.
- Entering `drawing` (one transaction, `draw_committed` audit row): participants ordered by
bet txid, each `draw_position`, `participants_hash` (sha256 of `txid:vout:address\n`
lines; new `bet_vout`), `draw_height = tip_at_close + 1`. A tip of 0 keeps the round
`closing` (`draw_baseline_tip_unknown`, once per round). All persisted, so a resumed draw
reads rather than recomputes (the `_tick` branch itself is B-81).
- `_complete_draw` / `_wait_for_draw_block` replace `_wait_for_next_block`: wait for
`draw_confirmations` blocks from `draw_height`, then `ElectrumListener.agreed_block_hash`
asks every server, the active one included, for the header at that exact height (valid
work, >= 2 other answers, strict majority of all); no agreement means the same height is
asked again and `draw_header_corroboration_failed` is written once per distinct reported
hash. `draw_stalled` now counts from the last tip advance, or from when the quorum started
to fail. Seed = sha256(server_seed || block_hash || participants_hash), index = seed mod n.
- The winner, the seed and the reveal (`server_seed`, `winner_drawn` payload) are written in
one transaction; a round closing with no participants reveals too. A round opened before
this change (no commitment) is given a secret as it enters `drawing`.
- `GET /rounds/{id}/proof` (public, 404 `round_not_found`, translated in all 7 languages) and
the new fields on `GET /rounds/current`; `draw_confirmations` in `/admin/config` and the
/admin form; `server_seed_hash`/`draw_height` in `/admin/rounds`, never the secret.
- Alembic d3e8b15a7c42 (plain add_column / create_index, expression indexes untouched).
- Docs: the B-73 `*Stato:*`/`*Oggi:*` lines are gone, guides and CLAUDE.md describe the new
draw. Ambiguities resolved in api.md: the proof's participants also carry `amount_sats`
(RND-37 lists it); `seed` is decimal in the proof and hex in the audit row, as specified.
Tests changed because the spec changed: ElectrumListener.corroborate_header (asked only the
other servers about the block the active one announced) is replaced by agreed_block_hash and
its quorum tests ported; draw_winner takes the secret and the list fingerprint; the four
_wait_for_next_block scheduler tests are replaced by _wait_for_draw_block ones (fixed height,
confirmations, same-height retry, stall clock). New: test_draw_proof.py recomputes the winner
independently from the public proof, checks the plaintext secret is nowhere in the database,
the API or the log before the reveal, and that a second pass over a `drawing` round yields
the same winner. Mutation-checked: ordering by broadcast_at, an early reveal and asking the
tip instead of the draw height each fail tests.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
631 lines
40 KiB
Markdown
631 lines
40 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 esegue un passo 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).
|
||
|
||
Questo documento descrive il comportamento **atteso** dopo la revisione del
|
||
2026-09-28. I requisiti che il codice non soddisfa ancora sono marcati
|
||
*Stato:* da implementare, con una riga *Oggi* che dice cosa fa il codice
|
||
adesso; l'ordine di implementazione è in
|
||
[piano-correzioni.md](piano-correzioni.md).
|
||
|
||
- **[RND-01]** Lo scheduler esegue un passo, poi attende
|
||
`_TICK_INTERVAL_SECONDS` (5s) prima del successivo. Un passo non fa nulla
|
||
se non c'è connessione a Electrum: senza rete nessun round si apre, si
|
||
chiude, estrae o si paga. Un errore in un passo viene registrato nei log e
|
||
il passo successivo riparte dallo stato salvato nel database, **in
|
||
qualunque stato sia il round**, `drawing` compreso ([RND-36]).
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler.run`, `app/rounds/scheduler.py:RoundScheduler._tick` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
*Stato:* da implementare (B-81) · *Oggi:* un errore durante l'attesa del
|
||
blocco lascia il round in `drawing` per sempre, perché `_tick` non fa nulla
|
||
sui round in quello stato.
|
||
|
||
## Gli stati
|
||
|
||
Diagramma del **comportamento atteso**:
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> open: nessun round attivo,<br/>pausa tra i round trascorsa,<br/>lotteria non in pausa,<br/>configurazione pagabile
|
||
open --> closing: scade il tempo<br/>(al primo passo dopo la scadenza)
|
||
closing --> closing: scommesse ancora in volo,<br/>oppure altezza della catena non nota
|
||
closing --> closed: nessun partecipante confermato
|
||
closing --> drawing: tutte le scommesse confermate:<br/>partecipanti, participants_hash<br/>e draw_height salvati
|
||
drawing --> drawing: conferme insufficienti, oppure<br/>i server non concordano sull'header:<br/>si richiede la stessa altezza<br/>(anche dopo un errore o un riavvio)
|
||
drawing --> paying_out: header a draw_height concordato,<br/>vincitore salvato, server_seed rivelato
|
||
paying_out --> paying_out: pagamento fallito o abbandonato,<br/>nuovo tentativo dopo 60s;<br/>oppure bloccato (payout_blocked)
|
||
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 e altezza del blocco fissati, si attendono le conferme del blocco che sceglie il vincitore |
|
||
| `paying_out` | Vincitore noto, pagamento in verifica, 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 pausa**, né per manutenzione (`POST /admin/pause`)
|
||
né per una pausa automatica: riorganizzazione della catena profonda almeno
|
||
2 blocchi ([connessione-electrum.md](connessione-electrum.md) (B-85)),
|
||
pagamento bloccato ([RND-39]), transazione abbandonata poi confermata
|
||
([transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md) (B-78)),
|
||
avvio con `START_PAUSED=true` ([operativita.md](operativita.md) (B-90)).
|
||
Il motivo è salvato in `paused_reason`
|
||
([modello-dati.md](modello-dati.md) (B-85)) e solo l'operatore toglie la
|
||
pausa;
|
||
- l'**indirizzo delle commissioni** (`fee_address`) è impostato (un valore
|
||
di soli spazi conta come vuoto) e la configurazione corrente permette di
|
||
pagare anche un round con un solo partecipante ([RND-40]). Altrimenti 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`
|
||
*Stato:* da implementare (B-79) · *Oggi:* `rounds_can_open` controlla solo
|
||
che `fee_address` non sia vuoto.
|
||
- **[RND-05]** All'apertura il round **fotografa** i parametri correnti che lo
|
||
governano: durata (`round_duration_seconds`, 600s predefiniti), pausa
|
||
successiva (`round_cooldown_seconds`, 30s predefiniti), costo della
|
||
scommessa (`bet_amount_sats`), indirizzo delle commissioni (`fee_address`),
|
||
conferme richieste sul blocco di estrazione (`draw_confirmations`, 3
|
||
predefinite) e tetto al montepremi (`max_round_pool_sats`, 0 = nessun
|
||
tetto; il rifiuto delle scommesse oltre il tetto è in
|
||
[scommesse-e-prelievi.md](scommesse-e-prelievi.md#quando-è-accettata) (B-95)).
|
||
Il round usa 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` (solo durata e pausa)
|
||
*Stato:* da implementare (B-95) · *Oggi:* sono fotografate durata, pausa e
|
||
`draw_confirmations`; costo della scommessa e `fee_address` sono letti dalla
|
||
configurazione a ogni uso, `max_round_pool_sats` non esiste.
|
||
- **[RND-06]** Pause e configurazione non pagabile bloccano solo l'apertura
|
||
del *prossimo* round: un round già in corso prosegue fino al pagamento con i
|
||
valori fotografati all'apertura ([RND-05]), quindi una modifica di
|
||
`fee_address` durante il round non ne cambia la destinazione della
|
||
commissione. L'API di amministrazione non permette di svuotare
|
||
`fee_address` (un valore vuoto non è un indirizzo PLM valido).
|
||
`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`, `app/api/routes/admin.py:RoundConfigUpdate` ·
|
||
*Test:* `tests/unit/test_rounds_service.py`, `tests/unit/test_rounds_route.py`
|
||
*Stato:* da implementare (B-95) · *Oggi:* il pagamento legge `fee_address`
|
||
dalla configurazione a ogni tentativo: una modifica durante il round
|
||
sposta la commissione del round in corso, e un `fee_address` vuoto (solo
|
||
modificando il database a mano) blocca il pagamento con
|
||
`no fee_address configured`.
|
||
- **[RND-07]** L'apertura di un round invia una notifica SSE.
|
||
*Codice:* `app/rounds/service.py:open_new_round_if_needed`
|
||
- **[RND-34]** **Impegno sul segreto**: all'apertura il server genera un
|
||
segreto di 32 byte casuali (`server_seed`, da un generatore
|
||
crittograficamente sicuro), lo salva sul round **cifrato** con la chiave
|
||
della master xprv (`server_seed_enc`, [modello-dati.md](modello-dati.md)
|
||
DAT-64: il database non contiene mai il segreto in chiaro prima della
|
||
rivelazione) e pubblica solo la sua impronta
|
||
`server_seed_hash = sha256(server_seed)`, esposta da
|
||
`GET /rounds/current` e dalla prova pubblica ([RND-37]) fin dall'apertura.
|
||
`server_seed` non è esposto da nessun endpoint, `/admin` compreso, finché il
|
||
vincitore non è salvato ([RND-18]).
|
||
*Codice:* `app/rounds/service.py:open_new_round_if_needed`, `app/rounds/draw.py:new_server_seed`, `app/wallet/keystore.py:encrypt_round_seed`, `app/api/routes/rounds.py:current_round` ·
|
||
*Test:* `tests/unit/test_rounds_service.py`, `tests/unit/test_draw_proof.py`
|
||
- **[RND-35]** **Un indirizzo del montepremi per round**: all'apertura il
|
||
round riceve un proprio indirizzo `m/84'/746'/0'/2/<round_id>`, salvato in
|
||
`rounds.pool_address` ed esposto da `GET /rounds/current`. Le scommesse del
|
||
round pagano quell'indirizzo
|
||
([scommesse-e-prelievi.md](scommesse-e-prelievi.md#cosa-succede)) e il
|
||
pagamento spende solo monete di quell'indirizzo ([RND-22]). I round aperti
|
||
prima di questa modifica mantengono l'indirizzo condiviso
|
||
`m/84'/746'/0'/1/0`, che diventa l'**indirizzo di riserva** ([RND-38]).
|
||
Il rifiuto dei prelievi verso indirizzi di montepremi, riserva o
|
||
commissioni è in [scommesse-e-prelievi.md](scommesse-e-prelievi.md#prelievo).
|
||
*Codice:* `app/rounds/service.py:open_new_round_if_needed`, `app/wallet/hd.py:derive_pool_key`, `app/wallet/hd.py:derive_round_pool_key` ·
|
||
*Test:* `tests/unit/test_round_pool_address.py`
|
||
|
||
## 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 di rete 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 che inizia dopo la scadenza (i
|
||
passi sono separati da `_TICK_INTERVAL_SECONDS` = 5s di attesa) 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` (verifica solo lo stato finale; nessun test controlla `closed_at` né la notifica SSE)
|
||
- **[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.
|
||
**L'attesa non ha un limite di tempo**: finisce solo quando ogni scommessa
|
||
in volo è confermata oppure la sua riga viene abbandonata dal
|
||
riconciliatore, che la abbandona solo con una prova
|
||
([TX-17](transazioni-e-riconciliazione.md#riconciliazione), B-78). Una scommessa
|
||
che resta nel mempool non viene mai abbandonata: a farla confermare è
|
||
l'aumento della commissione
|
||
([TX-11](transazioni-e-riconciliazione.md#rbf-accelerare-una-transazione-lenta)),
|
||
pagato dall'utente.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`, `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
|
||
*Test:* `tests/unit/test_scheduler.py` (solo il secondo controllo, in `_close_and_draw`; nessun test copre l'attesa in `_tick` con una scommessa in volo), `tests/unit/test_reconcile_proof.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**, nella stessa
|
||
transazione del database che porta il round a `drawing`:
|
||
- si fissa l'elenco dei partecipanti confermati, **ordinato per txid della
|
||
scommessa** in ordine crescente (txid in esadecimale minuscolo, nell'ordine
|
||
mostrato dagli explorer; due scommesse non hanno mai lo stesso txid), e si
|
||
salva su ogni partecipante la sua posizione `draw_position`, da 0 a n−1;
|
||
- si calcola e si salva `participants_hash` = sha256 delle righe
|
||
`txid:vout:indirizzo`, una per partecipante nell'ordine di
|
||
`draw_position`, dove `vout` è l'uscita della scommessa verso l'indirizzo
|
||
del montepremi del round (in decimale) e `indirizzo` è quello
|
||
dell'utente; ogni riga termina con `\n`, testo UTF-8;
|
||
- si salva l'altezza del blocco di estrazione ([RND-33]);
|
||
- si somma il montepremi dagli importi netti e si annota
|
||
`drawing_started_at`.
|
||
|
||
Dopo il commit si invia una notifica SSE; da quel momento `participants_hash`
|
||
e `draw_height` sono pubblici ([RND-37]).
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw`, `app/rounds/draw.py:participants_hash` ·
|
||
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_draw.py`, `tests/unit/test_draw_proof.py`
|
||
- **[RND-33]** L'altezza del blocco di estrazione è fissata all'ingresso in
|
||
`drawing` come `draw_height = tip_at_close + 1`, dove `tip_at_close` è
|
||
l'altezza della catena nota in quell'istante, e non cambia più: né per una
|
||
conferma mancata, né per un errore, né per un riavvio.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
|
||
## 3 · Estrazione
|
||
|
||
L'estrazione combina tre valori che nessuno conosce tutti insieme prima che
|
||
sia troppo tardi per cambiarli:
|
||
|
||
- il **segreto del server** (`server_seed`), fissato all'apertura e noto solo
|
||
al server, ma impegnato pubblicamente con la sua impronta ([RND-34]): il
|
||
server non può cambiarlo dopo;
|
||
- l'**hash del blocco** all'altezza `draw_height`, che non esisteva quando
|
||
partecipanti e altezza sono stati fissati;
|
||
- l'**impronta dei partecipanti** (`participants_hash`), pubblicata prima che
|
||
quel blocco esista ([RND-14]).
|
||
|
||
Chi produce o trasmette i blocchi non conosce il segreto, quindi non sa quale
|
||
blocco farebbe vincere chi: non ha motivo di nasconderne o sceglierne uno.
|
||
L'operatore conosce il segreto ma non il blocco, e non può più cambiare né
|
||
il segreto né l'elenco. Diagramma del **comportamento atteso**:
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
A["Ingresso in drawing: salvati<br/>partecipanti ordinati per txid,<br/>participants_hash, draw_height = tip + 1"] --> B{"La catena ha draw_confirmations<br/>blocchi a partire da draw_height?<br/>(controllo a ogni passo)"}
|
||
B -- "No" --> B
|
||
B -- "Sì" --> C{"Tutti i server interrogati<br/>sull'header a draw_height:<br/>il quorum concorda?"}
|
||
C -- "No" --> D["Registrato in audit<br/>(draw_header_corroboration_failed);<br/>al passo successivo si richiede<br/>la stessa altezza"] --> B
|
||
C -- "Sì" --> E["seme = sha256(server_seed ‖ hash del blocco ‖ participants_hash)<br/>indice = seme mod numero partecipanti"]
|
||
E --> F["Vincitore = partecipante con draw_position = indice,<br/>salvato; poi server_seed rivelato"]
|
||
```
|
||
|
||
- **[RND-15]** L'estrazione attende che il blocco a `draw_height` abbia
|
||
`draw_confirmations` conferme (il valore fotografato all'apertura,
|
||
[RND-05]), cioè che l'altezza della catena sia almeno
|
||
`draw_height + draw_confirmations − 1`. La condizione si controlla a ogni
|
||
passo dello scheduler, rileggendo dal database tutto ciò che serve
|
||
([RND-36]).
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_draw_block` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
*Stato:* da implementare (B-81) · *Oggi:* la condizione si controlla dentro
|
||
`_close_and_draw`, che resta in attesa per tutta la durata senza che
|
||
`_tick` la riprenda: dopo un errore o un riavvio non riparte.
|
||
- **[RND-16]** **Header concordato**: raggiunte le conferme, l'header
|
||
all'altezza `draw_height` (e non la punta corrente) viene chiesto a tutti i
|
||
server configurati, attivo compreso, e lo si usa solo se il quorum concorda
|
||
sullo stesso hash, con il numero minimo di risposte fissato in
|
||
[connessione-electrum.md](connessione-electrum.md#5-il-quorum) (B-84). Se
|
||
il quorum non concorda o non risponde abbastanza, si scrive
|
||
`draw_header_corroboration_failed` (altezza e hash riportati) e al passo
|
||
successivo si richiede **la stessa altezza**: il round non passa mai a un
|
||
blocco diverso. L'evento si scrive una volta per ogni hash diverso
|
||
riportato dal server attivo per quell'altezza, non a ogni richiesta, così
|
||
un disaccordo che dura non scrive una riga ogni 5 secondi; la durata
|
||
dell'attesa resta visibile tramite `draw_stalled` ([RND-20]).
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_draw_block`, `app/electrum/listener.py:ElectrumListener.agreed_block_hash` ·
|
||
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_electrum_listener.py`
|
||
- **[RND-17]** **Algoritmo**: seme = sha256 della concatenazione di
|
||
`server_seed` (32 byte), hash del blocco a `draw_height` (32 byte,
|
||
nell'ordine mostrato dagli explorer) e `participants_hash` (32 byte),
|
||
letto come intero senza segno big-endian; indice = seme modulo numero dei
|
||
partecipanti; vincitore = il partecipante con `draw_position` uguale
|
||
all'indice. **Probabilità uguale per tutti**: ogni partecipante ha una e
|
||
una sola posizione nell'elenco, indipendentemente dall'importo.
|
||
*Codice:* `app/rounds/draw.py:draw_seed`, `app/rounds/draw.py:draw_index`, `app/rounds/draw.py:draw_winner`, `app/rounds/scheduler.py:RoundScheduler._complete_draw` ·
|
||
*Test:* `tests/unit/test_draw.py`, `tests/unit/test_draw_proof.py`
|
||
- **[RND-18]** **Verificabile**: in un'unica transazione del database il
|
||
round salva altezza e hash del blocco (`draw_block_height` = `draw_height`,
|
||
`draw_block_hash`), il seme (`seed_int`), il vincitore e il montepremi
|
||
(`pool_amount_sats`), passa a `paying_out` e scrive `winner_drawn`
|
||
(indirizzo del vincitore, montepremi, altezza, hash, numero di
|
||
partecipanti, `participants_hash`, `draw_height`, `server_seed` e `seed`
|
||
in esadecimale, [audit-log.md](audit-log.md) AUD-24). `server_seed` entra
|
||
nel registro nella stessa transazione in cui il vincitore viene salvato, e
|
||
diventa pubblico tramite la prova ([RND-37]) solo dopo quel commit; si invia
|
||
una notifica SSE. Da quel momento
|
||
chiunque, con i dati della prova pubblica e la catena, può rifare il calcolo
|
||
e ottenere lo stesso vincitore (vedi
|
||
[Come si verifica un'estrazione](#come-si-verifica-unestrazione)). Il primo
|
||
tentativo di pagamento parte subito dopo, nello stesso passo.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._complete_draw` ·
|
||
*Test:* `tests/unit/test_draw_proof.py`
|
||
- **[RND-19]** **Altezza sconosciuta alla chiusura**: se, quando il round
|
||
sarebbe pronto per `drawing`, l'altezza della catena non è nota (valore 0),
|
||
il round resta `closing` e il passaggio viene ritentato al passo
|
||
successivo, scrivendo `draw_baseline_tip_unknown` una volta per round:
|
||
`draw_height` si fissa solo su un'altezza realmente nota ([RND-33]). 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._close_and_draw` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
- **[RND-20]** **Attesa lunga ma visibile**: l'attesa non ha un limite,
|
||
perché dipende davvero dall'arrivo dei blocchi. Ogni 60 secondi
|
||
(`_DRAW_PROGRESS_LOG_INTERVAL_SECONDS`) se ne registra l'avanzamento nei
|
||
log. Se per 360 secondi (`_DRAW_STALL_THRESHOLD_SECONDS`) la catena non
|
||
avanza mentre il round attende le conferme, oppure il quorum continua a non
|
||
concordare, viene scritto un evento `draw_stalled`, ripetuto ogni 360
|
||
secondi finché la situazione dura. 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_draw_block`, `app/api/routes/rounds.py:current_round` ·
|
||
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_rounds_route.py`
|
||
- **[RND-36]** **Estrazione ripresa**: tutto ciò che l'estrazione usa
|
||
(`server_seed`, elenco con `draw_position`, `participants_hash`,
|
||
`draw_height`, `draw_confirmations`) è nel database dall'ingresso in
|
||
`drawing`. A ogni passo, per un round in `drawing`, lo scheduler rifà il
|
||
controllo di [RND-15] da quei valori, anche dopo un errore in un passo
|
||
precedente o un riavvio del server. La ripresa è idempotente: l'estrazione
|
||
ripresa dà sempre lo stesso vincitore, e un round già passato a
|
||
`paying_out` non viene estratto di nuovo.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`, `app/rounds/scheduler.py:RoundScheduler._complete_draw` ·
|
||
*Test:* `tests/unit/test_draw_proof.py` (solo `_complete_draw`)
|
||
*Stato:* da implementare (B-81) · *Oggi:* tutto ciò che serve è nel database
|
||
e `_complete_draw` è idempotente, ma `_tick` salta i round in `drawing`:
|
||
dopo un errore o un riavvio il round resta in `drawing` per sempre.
|
||
- **[RND-37]** **Prova pubblica**: `GET /rounds/{id}/proof`, senza
|
||
autenticazione, restituisce per un round: `server_seed_hash` e
|
||
`pool_address` (dall'apertura); dall'ingresso in `drawing` l'elenco dei
|
||
partecipanti (`draw_position`, txid, `vout`, indirizzo, importo netto),
|
||
`participants_hash`, `draw_height` e `draw_confirmations`; dal salvataggio
|
||
del vincitore `server_seed`, `draw_block_hash`, il seme, l'indice, il
|
||
vincitore e, quando esiste, il txid del pagamento. Un campo non ancora
|
||
disponibile è `null`. Il formato della risposta è in [api.md](api.md) (B-73).
|
||
*Codice:* `app/api/routes/rounds.py:round_proof` ·
|
||
*Test:* `tests/unit/test_draw_proof.py`
|
||
|
||
### Come si verifica un'estrazione
|
||
|
||
Chiunque può controllare un round concluso con la sola prova pubblica e un
|
||
qualunque nodo o explorer PLM, senza fidarsi del server:
|
||
|
||
1. **Impegno.** Annotare `server_seed_hash` mentre il round è aperto (è
|
||
pubblico dall'apertura). Dopo la rivelazione, verificare che
|
||
`sha256(server_seed)` sia uguale a quel valore: il segreto usato è quello
|
||
fissato all'apertura.
|
||
2. **Partecipanti.** Per ogni riga dell'elenco verificare sulla catena che la
|
||
transazione `txid` esista, sia confermata, abbia l'uscita `vout` verso
|
||
`pool_address` con l'importo indicato e sia firmata dall'indirizzo
|
||
indicato. Poiché l'indirizzo del montepremi è del solo round ([RND-35]),
|
||
la sua cronologia mostra anche che nessuna scommessa confermata prima
|
||
della chiusura manca dall'elenco.
|
||
3. **Ordine.** Verificare che le righe siano in ordine crescente di txid e
|
||
che `draw_position` vada da 0 a n−1 senza salti.
|
||
4. **Impronta dei partecipanti.** Ricostruire le righe `txid:vout:indirizzo`
|
||
(ognuna terminata da `\n`), calcolarne lo sha256 e confrontarlo con
|
||
`participants_hash`. Chi ha osservato la prova durante `drawing` sa anche
|
||
che impronta e `draw_height` erano pubblici prima che il blocco esistesse.
|
||
5. **Blocco.** Verificare che `draw_block_hash` sia l'hash del blocco
|
||
all'altezza `draw_height` della catena principale.
|
||
6. **Calcolo.** Calcolare sha256 della concatenazione dei 32 byte di
|
||
`server_seed`, dei 32 byte dell'hash del blocco e dei 32 byte di
|
||
`participants_hash`; leggerlo come intero big-endian; l'indice è quel
|
||
numero modulo n. Il vincitore dichiarato deve essere la riga con quella
|
||
`draw_position`.
|
||
7. **Pagamento.** Verificare che la transazione di pagamento spenda le
|
||
scommesse del round e paghi l'indirizzo del vincitore
|
||
([RND-21], [RND-23]).
|
||
|
||
Il controllo non esclude un operatore che sia anche minatore: conoscendo il
|
||
segreto potrebbe scegliere quale blocco pubblicare a `draw_height`. È un
|
||
rischio accettato, descritto in
|
||
[limiti-noti.md](adr/README.md#round-ed-estrazione) (B-73).
|
||
L'algoritmo resta un componente **sostituibile** (vedi
|
||
[limiti-noti.md](limiti-noti.md)).
|
||
|
||
## 4 · Pagamento
|
||
|
||
Con il vincitore noto il round è in `paying_out`: si verificano le monete del
|
||
round, si costruisce il pagamento e lo si firma con la chiave dell'indirizzo
|
||
del montepremi del round.
|
||
|
||
- **[RND-21]** **Ripartizione**: il vincitore riceve il 70% del montepremi
|
||
verificato ([RND-39]) arrotondato per difetto, meno la commissione di rete
|
||
([RND-23]); l'indirizzo delle commissioni riceve il resto (30% più
|
||
l'eventuale resto dell'arrotondamento) meno la riserva per l'RBF
|
||
([RND-38]). 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`
|
||
*Stato:* da implementare (B-79, B-82) · *Oggi:* la ripartizione si calcola
|
||
su `pool_amount_sats` fissato all'estrazione e l'indirizzo delle
|
||
commissioni riceve l'intera quota del 30%.
|
||
- **[RND-22]** Il pagamento spende le uscite delle scommesse dei partecipanti
|
||
del round **verificate** ([RND-39]), all'indirizzo del montepremi del round
|
||
([RND-35]), e nient'altro: altre monete arrivate a quell'indirizzo non
|
||
vengono toccate. Sono escluse quelle già impegnate da un altro pagamento
|
||
non risolto ([RND-26]); il limite è di 500 ingressi
|
||
(`MAX_PAYOUT_TX_INPUTS`), superiore al massimo di partecipanti per round
|
||
([BET-06](scommesse-e-prelievi.md#quando-è-accettata)). Troppi ingressi dà
|
||
il motivo `too_many_inputs`. Per i round aperti prima dell'indirizzo per
|
||
round si spendono le monete confermate dell'indirizzo condiviso, scelte
|
||
dalla più grande fino a coprire il montepremi; non abbastanza monete dà
|
||
`insufficient pool UTXOs`.
|
||
*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`, `tests/unit/test_round_pool_address.py`
|
||
*Stato:* da implementare (B-82) · *Oggi:* spende le monete confermate
|
||
dell'indirizzo del round (per un round vecchio, di quello condiviso) lette
|
||
dal solo server attivo, scelte dalla più grande fino a coprire il
|
||
montepremi, e non solo le uscite delle scommesse dei partecipanti: un'altra
|
||
moneta arrivata a quell'indirizzo verrebbe spesa.
|
||
- **[RND-23]** La transazione ha un'uscita verso l'indirizzo del vincitore,
|
||
una verso l'indirizzo delle commissioni fotografato all'apertura
|
||
([RND-05]) e una verso l'indirizzo di riserva ([RND-38]). Se gli ingressi
|
||
superano quanto serve (solo per i round aperti prima dell'indirizzo per
|
||
round), il resto va all'indirizzo di riserva se è di almeno 294 sat
|
||
(`DUST_LIMIT_SATS`), altrimenti va alla commissione di rete. La
|
||
**commissione di rete** (stimata su tre uscite, a `fee_rate_sat_vb`) è
|
||
pagata dalla quota del vincitore, così la quota delle commissioni non la
|
||
paga. Se la quota del vincitore meno la commissione di rete, o la quota
|
||
delle commissioni meno la riserva, è inferiore a 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` (nessun test copre `commission_below_dust_limit`)
|
||
*Stato:* da implementare (B-79, B-95) · *Oggi:* la terza uscita è un resto
|
||
verso l'indirizzo del montepremi, presente solo se è di almeno 294 sat e
|
||
assente quando le monete spese sono esattamente le scommesse del round; non c'è riserva, la soglia di 294 sat si applica all'intera
|
||
quota delle commissioni e `fee_address` è letto dalla configurazione.
|
||
- **[RND-24]** **Prima si scrive, poi si invia**: prima dell'invio il round
|
||
registra importo del vincitore (`winner_amount_sats`), commissioni
|
||
(`fee_amount_sats`), riserva per l'RBF (`bump_reserve_sats`, [RND-38]) 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 non riesce, si
|
||
scrive `payout_failed` e la riga resta `building`: la risolve il
|
||
riconciliatore, secondo le regole di invio e di abbandono di
|
||
[transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md#pagamenti-del-round-riprovare-senza-pagare-due-volte)
|
||
(TX-18, B-76, B-78); solo un abbandono libera il round per un nuovo
|
||
tentativo.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
*Stato:* da implementare (B-79) · *Oggi:* tutto come descritto, tranne
|
||
`bump_reserve_sats`, che non esiste.
|
||
- **[RND-25]** Ogni tentativo che si ferma prima di un 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`, e — *da implementare (B-82)* —
|
||
`pool verification unavailable` quando la verifica del montepremi prima del
|
||
pagamento ([RND-39]) non ottiene abbastanza risposte dal quorum. Fanno eccezione due casi, che non
|
||
scrivono `payout_failed`: un pagamento già in volo per il round ([RND-26]),
|
||
che termina il tentativo senza scrivere nulla, e un pagamento bloccato
|
||
([RND-39]), che scrive `payout_blocked`. 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, o mentre un pagamento è in volo) riprova al passo successivo.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._retry_payout_if_due`, `app/rounds/scheduler.py:RoundScheduler._log_payout_failure` ·
|
||
*Test:* `tests/unit/test_scheduler.py` (verificati solo i motivi `electrum client not connected` e `no fee_address configured`; per l'invio fallito solo la presenza di `payout_failed`)
|
||
- **[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 senza scrivere eventi),
|
||
e le monete 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
|
||
riducendo l'uscita di riserva ([RND-38]); le uscite del vincitore e delle
|
||
commissioni non cambiano
|
||
([TX-11](transazioni-e-riconciliazione.md#rbf-accelerare-una-transazione-lenta)).
|
||
*Codice:* `app/tx/broadcast.py:bump_fee`
|
||
*Stato:* da implementare (B-79) · *Oggi:* l'RBF può ridurre solo il resto
|
||
verso il montepremi, che non esiste quando le monete spese sono
|
||
esattamente le scommesse del round: un pagamento bloccato nel
|
||
mempool non si può accelerare, e poiché il server lo conosce non viene
|
||
nemmeno abbandonato, quindi il round resta in `paying_out` e nessun nuovo
|
||
round si apre.
|
||
- **[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`
|
||
- **[RND-38]** **Riserva per l'RBF**: ogni pagamento ha un'uscita di riserva
|
||
verso l'indirizzo di riserva `m/84'/746'/0'/1/0` di valore
|
||
`max(DUST_LIMIT_SATS, estimate_vsize(ingressi, 3) × 10 sat/vB)`, dove 10
|
||
sat/vB è la costante `PAYOUT_BUMP_RESERVE_SAT_VB`. La riserva è tolta
|
||
dalla quota delle commissioni, mai da quella del vincitore; è ciò che
|
||
l'RBF riduce ([RND-27]).
|
||
*Codice:* `app/wallet/psbt_builder.py:build_payout_transaction`, `app/wallet/hd.py:derive_pool_key` ·
|
||
*Test:* —
|
||
*Stato:* da implementare (B-79) · *Oggi:* non esiste alcuna riserva.
|
||
- **[RND-39]** **Verifica prima del pagamento**: prima di costruire il
|
||
pagamento, le uscite delle scommesse dei partecipanti vengono verificate
|
||
all'indirizzo del montepremi del round con il quorum dei server
|
||
([connessione-electrum.md](connessione-electrum.md#5-il-quorum) (B-82)).
|
||
- Un partecipante la cui uscita il quorum dice **assente** (la scommessa è
|
||
sparita dalla catena, ad esempio per una riorganizzazione) passa a
|
||
`reorged_out` ([modello-dati.md](modello-dati.md) (B-82)) ed è escluso
|
||
dal montepremi; `pool_amount_sats` viene riscritto con la somma delle
|
||
uscite verificate e la ripartizione ([RND-21]) si calcola su quella.
|
||
- Se è assente la scommessa **del vincitore**, il pagamento non si
|
||
costruisce: si scrive `payout_blocked`, si annota il blocco sul round,
|
||
la lotteria va in pausa automatica ([RND-04]) e il round resta in
|
||
`paying_out` senza altri tentativi finché l'operatore non toglie la pausa
|
||
(`POST /admin/resume`); al tentativo successivo la verifica si ripete. Lo
|
||
schema è in [modello-dati.md](modello-dati.md) (B-82), la procedura in
|
||
[operativita.md](operativita.md) (B-82).
|
||
- Se il quorum non risponde o non concorda, non si conclude nulla: nessun
|
||
partecipante cambia stato, il tentativo termina con `payout_failed` e si
|
||
riprova secondo [RND-25].
|
||
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
|
||
*Test:* —
|
||
*Stato:* da implementare (B-82) · *Oggi:* le monete sono lette dal solo
|
||
server attivo e nessun partecipante viene mai escluso: se una scommessa
|
||
sparisce dalla catena il pagamento fallisce con
|
||
`insufficient pool UTXOs` a ogni tentativo, con i soldi di tutti gli altri
|
||
bloccati.
|
||
- **[RND-40]** **Configurazione pagabile**: `rounds_can_open` rifiuta una
|
||
configurazione in cui un round non si potrebbe pagare, verificandola per
|
||
**n = 1** e per **n = `MAX_PARTICIPANTS_PER_ROUND`** partecipanti (i due
|
||
estremi: con uno solo la commissione è minima, con il massimo è massima la
|
||
riserva, che cresce con gli ingressi). Con `netto` = `bet_amount_sats −
|
||
estimate_vsize(MAX_TX_INPUTS, 2) × fee_rate_sat_vb` (la scommessa più piccola
|
||
che può arrivare al montepremi) e `montepremi = n × netto`, per entrambi i
|
||
valori di n devono valere:
|
||
- `winner_share(montepremi) − estimate_vsize(n, 3) × fee_rate_sat_vb ≥
|
||
DUST_LIMIT_SATS`;
|
||
- `montepremi − winner_share(montepremi) − riserva(n) ≥ DUST_LIMIT_SATS`,
|
||
con `riserva(n)` quella di [RND-38] calcolata su n ingressi.
|
||
|
||
La stessa verifica si applica a `PUT /admin/config`: una modifica di
|
||
`bet_amount_sats` o `fee_rate_sat_vb` che la farebbe fallire è rifiutata,
|
||
così un aumento della commissione di rete a round in corso non può rendere
|
||
impagabile il round (il pagamento legge `fee_rate_sat_vb` al momento della
|
||
costruzione).
|
||
*Codice:* `app/rounds/service.py:rounds_can_open`, `app/api/routes/admin.py` ·
|
||
*Test:* —
|
||
*Stato:* da implementare (B-79) · *Oggi:* `rounds_can_open` controlla solo
|
||
che `fee_address` non sia vuoto, e `PUT /admin/config` non fa verifiche di
|
||
pagabilità.
|
||
|
||
## Tempi reali
|
||
|
||
Tra lo scadere del timer e l'arrivo della vincita ci sono **tre attese di
|
||
conferma distinte**:
|
||
|
||
1. l'ultima scommessa in volo (può essere già confermata prima della
|
||
scadenza);
|
||
2. il blocco dell'estrazione a `draw_height`, il primo dopo il punto 1, più
|
||
i blocchi successivi fino a `draw_confirmations` conferme (3 predefinite,
|
||
quindi 3 blocchi);
|
||
3. il pagamento, costruito solo dopo il punto 2, che richiede un altro blocco.
|
||
|
||
I blocchi PLM arrivano in media ogni 120 secondi, ma l'intervallo fra due
|
||
blocchi non ha un limite superiore: non esiste un "caso peggiore". A valori
|
||
medi, dalla conferma dell'ultima scommessa servono 3 blocchi per l'estrazione
|
||
e 1 per il pagamento, cioè 4 blocchi (8 minuti in media), indipendentemente
|
||
da `draw_animation_seconds`. I depositi richiedono a parte più conferme prima
|
||
di poter essere giocati
|
||
([registrazione-e-depositi.md](registrazione-e-depositi.md#deposito) (B-82)).
|
||
|
||
## 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]~~ Assorbito da [RND-36]: nel comportamento atteso un round in
|
||
`drawing` riprende da solo dopo un riavvio o un errore. Finché B-81 non è
|
||
implementato il limite resta: lo scheduler riprende i round in `closing` e
|
||
`paying_out`, ma su un round in `drawing` non fa nulla.
|