temp
This commit is contained in:
1 parent
61efbb0e37
commit
c5e7daa9c7
15 files changed
+4514
-1172
No files matched your search
+445
-145
@@ -2,7 +2,7 @@
|
||||
|
||||
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.
|
||||
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
|
||||
@@ -10,25 +10,38 @@ I requisiti usano il prefisso `RND`, secondo la convenzione 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.
|
||||
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 manutenzione,<br/>indirizzo commissioni impostato
|
||||
[*] --> 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
|
||||
closing --> closing: scommesse ancora in volo,<br/>oppure altezza della catena non nota
|
||||
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
|
||||
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 --> [*]
|
||||
```
|
||||
@@ -37,8 +50,8 @@ stateDiagram-v2
|
||||
|---|---|
|
||||
| `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 |
|
||||
| `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
|
||||
@@ -67,31 +80,85 @@ richiesta di scommessa (vedi
|
||||
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`);
|
||||
- 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). 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.
|
||||
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`
|
||||
- **[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.
|
||||
*Stato:* da implementare (B-85, B-79) · *Oggi:* l'unica pausa è quella
|
||||
manuale (`paused`) e `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`
|
||||
- **[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.
|
||||
*Test:* `tests/unit/test_rounds_service.py`, `tests/unit/test_scheduler.py` (solo durata e pausa)
|
||||
*Stato:* da implementare (B-95, B-73) · *Oggi:* sono fotografate solo durata
|
||||
e pausa; costo della scommessa e `fee_address` sono letti dalla
|
||||
configurazione a ogni uso, `draw_confirmations` e `max_round_pool_sats` non
|
||||
esistono.
|
||||
- **[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` ·
|
||||
*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 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/api/routes/rounds.py:current_round` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-73) · *Oggi:* il round non ha alcun segreto;
|
||||
il seme dipende solo dall'hash del blocco.
|
||||
- **[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) (B-80)) 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) (B-80).
|
||||
*Codice:* `app/rounds/service.py:open_new_round_if_needed`, `app/wallet/hd.py:derive_pool_key` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-80) · *Oggi:* tutti i round usano lo stesso
|
||||
indirizzo `m/84'/746'/0'/1/0` (`derive_pool_key`).
|
||||
|
||||
## 1 · Round aperto
|
||||
|
||||
@@ -109,8 +176,8 @@ accettazione sono in
|
||||
**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ì;
|
||||
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.
|
||||
@@ -128,169 +195,345 @@ 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)).
|
||||
- **[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`
|
||||
*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. 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)).
|
||||
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`
|
||||
*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)
|
||||
*Stato:* da implementare (B-78) · *Oggi:* l'attesa è già senza limite, ma
|
||||
il riconciliatore abbandona una scommessa anche solo perché la cronologia
|
||||
del server attivo non contiene il suo txid, senza altra prova.
|
||||
- **[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.
|
||||
- **[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` ·
|
||||
*Test:* `tests/unit/test_scheduler.py`
|
||||
*Test:* — (nessun test porta `_close_and_draw` con partecipanti confermati fino a `drawing`)
|
||||
*Stato:* da implementare (B-73, B-81) · *Oggi:* l'elenco è ordinato per
|
||||
`broadcast_at` (che il pubblico non vede e che non ha spareggio) e resta
|
||||
solo in memoria; non esistono `draw_position` né `participants_hash`.
|
||||
- **[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:* —
|
||||
*Stato:* da implementare (B-73) · *Oggi:* si usa la punta vista al primo
|
||||
controllo utile, che può essere un blocco successivo; dopo una
|
||||
corroborazione fallita il riferimento avanza all'altezza rifiutata.
|
||||
|
||||
## 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.
|
||||
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["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)"}
|
||||
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{"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"]
|
||||
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 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.
|
||||
- **[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_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.
|
||||
*Test:* `tests/unit/test_scheduler.py` (solo il comportamento attuale)
|
||||
*Stato:* da implementare (B-73, B-81) · *Oggi:* si attende che la punta
|
||||
superi l'altezza di riferimento e si usa la punta stessa, con una sola
|
||||
conferma; per tutta l'attesa lo scheduler resta bloccato dentro
|
||||
`_close_and_draw` e non esegue altri passi.
|
||||
- **[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.
|
||||
*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.
|
||||
*Test:* `tests/unit/test_scheduler.py` (solo il comportamento attuale)
|
||||
*Stato:* da implementare (B-73) · *Oggi:* si usa l'header della punta
|
||||
ricevuto dal server attivo, chiedendo agli altri solo di confermarlo; se la
|
||||
conferma manca, si attende un blocco ulteriore e si usa quello, così il
|
||||
server attivo può scegliere quale blocco reale seminare tacendone uno.
|
||||
- **[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_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.
|
||||
*Test:* `tests/unit/test_draw.py` (solo `draw_winner`; nessun test lato scheduler)
|
||||
*Stato:* da implementare (B-73) · *Oggi:* seme = hash del blocco letto come
|
||||
numero esadecimale, applicato all'elenco ordinato per `broadcast_at`.
|
||||
- **[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`). Solo **dopo** quel commit `server_seed`
|
||||
diventa pubblico ([RND-37]); 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._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`
|
||||
*Test:* — (nessun test porta `_close_and_draw` con partecipanti confermati fino a `paying_out`)
|
||||
*Stato:* da implementare (B-73) · *Oggi:* il calcolo non è ripetibile da
|
||||
terzi: l'ordine dei partecipanti è per `broadcast_at`, noto solo al server
|
||||
e senza spareggio fra valori uguali.
|
||||
- **[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`, `app/rounds/scheduler.py:RoundScheduler._adopt_baseline_tip` ·
|
||||
*Test:* `tests/unit/test_scheduler.py` (solo il comportamento attuale)
|
||||
*Stato:* da implementare (B-73) · *Oggi:* il round entra comunque in
|
||||
`drawing`, attende il primo header, ne adotta l'altezza come riferimento,
|
||||
scrive `draw_baseline_tip_unknown` e aspetta un blocco successivo.
|
||||
- **[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.
|
||||
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_next_block`, `app/api/routes/rounds.py:current_round` ·
|
||||
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_rounds_route.py`
|
||||
*Stato:* da implementare (B-73) · *Oggi:* i 360 secondi si contano
|
||||
dall'inizio dell'attesa; con 3 conferme richieste l'evento scatterebbe in
|
||||
quasi ogni round.
|
||||
- **[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._close_and_draw` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-81) · *Oggi:* elenco dei partecipanti e altezza
|
||||
di riferimento esistono solo in memoria e `_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` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-73) · *Oggi:* non esiste alcun endpoint di
|
||||
prova; `GET /rounds/current` non espone partecipanti né dati
|
||||
dell'estrazione, e i round chiusi non sono consultabili pubblicamente.
|
||||
|
||||
L'algoritmo è volutamente semplice ed è pensato per essere **sostituito**
|
||||
(vedi [decisioni-e-limiti.md](decisioni-e-limiti.md)).
|
||||
### 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
|
||||
[decisioni-e-limiti.md](decisioni-e-limiti.md#round-ed-estrazione) (B-73).
|
||||
L'algoritmo resta un componente **sostituibile** (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.
|
||||
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
|
||||
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`.
|
||||
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`
|
||||
- **[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`.
|
||||
*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`
|
||||
- **[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
|
||||
*Stato:* da implementare (B-80, B-82) · *Oggi:* spende le monete confermate
|
||||
dell'indirizzo condiviso lette dal solo server attivo, scelte dalla più
|
||||
grande fino a coprire il montepremi, qualunque sia la loro provenienza.
|
||||
- **[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ì 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`,
|
||||
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`
|
||||
*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`) e txid (`payout_txid`), e si salva una transazione in
|
||||
(`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 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)).
|
||||
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`
|
||||
- **[RND-25]** Ogni tentativo che non arriva all'invio riuscito scrive un
|
||||
evento `payout_failed` con il motivo: `electrum client not connected`,
|
||||
*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`. 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.
|
||||
di costruzione, `broadcast rejected`. 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`
|
||||
*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 le monete del
|
||||
montepremi impegnate da un qualunque pagamento non risolto, anche di un
|
||||
`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
|
||||
dal resto del montepremi ([TX-11](transazioni-e-riconciliazione.md#rbf-accelerare-una-transazione-lenta)).
|
||||
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
|
||||
@@ -298,18 +541,77 @@ pagamento, firmato con la chiave del montepremi.
|
||||
([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 con un solo partecipante non si potrebbe
|
||||
pagare. Con `netto` = `bet_amount_sats − estimate_vsize(MAX_TX_INPUTS, 2) ×
|
||||
fee_rate_sat_vb` (la scommessa più piccola che può arrivare al montepremi)
|
||||
devono valere entrambe:
|
||||
- `winner_share(netto) − estimate_vsize(1, 3) × fee_rate_sat_vb ≥
|
||||
DUST_LIMIT_SATS`;
|
||||
- `netto − winner_share(netto) − riserva ≥ DUST_LIMIT_SATS`, con la
|
||||
riserva di [RND-38] calcolata su un ingresso.
|
||||
|
||||
Si usano i valori della configurazione al momento dell'apertura.
|
||||
*Codice:* `app/rounds/service.py:rounds_can_open` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-79) · *Oggi:* `rounds_can_open` controlla solo
|
||||
che `fee_address` non sia vuoto.
|
||||
|
||||
## Tempi reali
|
||||
|
||||
Tra lo scadere del timer e l'arrivo della vincita ci sono **tre conferme
|
||||
distinte**, ognuna in un blocco diverso:
|
||||
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à avvenuta prima della scadenza);
|
||||
2. il blocco dell'estrazione, necessariamente successivo al punto 1;
|
||||
3. il pagamento, costruito solo dopo il punto 2.
|
||||
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.
|
||||
|
||||
Con blocchi da 120 secondi sono circa **2–4 minuti** nel caso migliore e
|
||||
**4–6** nel peggiore, indipendentemente da `draw_animation_seconds`.
|
||||
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
|
||||
|
||||
@@ -336,9 +638,7 @@ Due livelli indipendenti:
|
||||
|
||||
## 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`
|
||||
- ~~[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.
|
||||
Reference in new issue
Block a user