Document the 2026-09-28 specification review and its fixes (B-73..B-97)

Fourth full audit, run against the docs/ specification instead of the code
alone, found logical flaws rooted in PLM's small hashrate (~22 TH/s): a
minable draw, no distinction between "never broadcast" and "unknown if
broadcast", an Electrum client that degrades as the pool address's history
grows, and 1-confirmation deposits on a chain where a reorg is rentable.

The spec now describes the target behaviour for every finding, marked
*Stato:* da implementare (B-nn) with an *Oggi:* line for what the code does
now; docs/piano-correzioni.md records the design decisions and the
implementation order. No code changed — this is spec-only, per B-nn
convention when a bug reveals the spec itself was incomplete.

Also documents, as an accepted-but-open risk (LIM-24), that the optional
jackpot cap (max_round_pool_sats) isn't tied to the cost of a 51% attack —
deferred, not decided.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
davideandClaude Sonnet 5 committed 2026-09-28 15:51:13 +02:00
1 parent 61efbb0e37
commit 88221b0dbd
15 files changed
+4524 -1172

No files matched your search

+237 -96
View File
@@ -9,7 +9,10 @@ e saldo), secondo la convenzione di
descritti in dettaglio in [api.md](api.md); hashing, token e limiti di
frequenza in [sicurezza.md](sicurezza.md); le colonne delle tabelle in
[modello-dati.md](modello-dati.md); gli eventi di audit in
[audit-log.md](audit-log.md).
[audit-log.md](audit-log.md). Il documento descrive il comportamento
**atteso** dopo la revisione del 2026-09-28; i requisiti che il codice non
soddisfa ancora sono marcati *da implementare* (vedi
[piano-correzioni.md](piano-correzioni.md)).
## Registrazione
@@ -23,7 +26,7 @@ L'utente sceglie username e password (`POST /auth/register`). Il server:
4. si iscrive, via Electrum, alle notifiche di quell'indirizzo. Questo passo
è "al meglio": se fallisce, l'indirizzo viene comunque ripreso alla
riconnessione successiva o al giro periodico di `DepositReconciler`
(ogni 5 minuti).
([DEP-10](#dep-10)).
- **[REG-01]** Lo username è lungo da 3 a 32 caratteri, composto solo da
lettere ASCII, cifre, `_`, `.` e `-`; la password è lunga da 8
@@ -52,7 +55,8 @@ L'utente sceglie username e password (`POST /auth/register`). Il server:
riprova con un indice ricalcolato fino a 5 volte (`_MAX_REGISTER_RETRIES`),
poi la richiesta fallisce con `derivation_index_conflict` (HTTP 409).
*Codice:* `app/auth/routes.py:register`, `app/wallet/hd.py:derive_user_address` ·
*Test:* `tests/unit/test_hd.py`
*Test:* `tests/unit/test_hd.py` (solo la derivazione dell'indirizzo:
nessun test copre i tentativi ripetuti né `derivation_index_conflict`)
- **[REG-05]** L'indirizzo è **permanente** e unico per utente, ed è allo
stesso tempo indirizzo di deposito, destinazione delle vincite e
destinazione del resto di ogni scommessa e prelievo: non esiste un
@@ -73,51 +77,81 @@ L'utente sceglie username e password (`POST /auth/register`). Il server:
periodico di [DEP-10](#dep-10).
*Codice:* `app/electrum/listener.py:ElectrumListener.address_for_new_user` ·
*Test:* `tests/unit/test_electrum_listener.py`
- **[REG-08]** La registrazione è limitata a **5 account all'ora per
indirizzo IP**. Il limite è verificato prima di calcolare l'hash, e conta
solo le registrazioni riuscite; oltre il limite la risposta è
`rate_limited` (HTTP 429) con `retry_after_seconds`. I dettagli sono in
[sicurezza.md](sicurezza.md).
*Codice:* `app/auth/routes.py:register`, `app/auth/rate_limit.py:AuthRateLimiters` ·
*Test:* `tests/unit/test_auth.py`
- ~~[REG-08]~~ Assorbito da [SEC-31](sicurezza.md#limiti-di-frequenza):
la quota di registrazioni per IP (soglia, finestra, momento del controllo,
risposta `rate_limited`) è una soglia di sicurezza e ha lì il suo unico
proprietario; qui non resta nulla di specifico del dominio.
- **[REG-15]** **Indici già usati dopo un ripristino.** Un database
ripristinato da un backup non conosce gli utenti registrati dopo il backup,
e riassegnerebbe i loro indici — e quindi i loro indirizzi, con i fondi che
contengono — a utenti nuovi. Per questo, all'avvio, appena la connessione
Electrum è disponibile, si controllano i **20 indici successivi** al
massimo indice assegnato (da 0 a 19 se non c'è alcun utente): per ciascun
indirizzo si chiede la cronologia (`blockchain.scripthash.get_history`) al
server attivo e a ogni server del quorum, e basta che **uno** riporti una
transazione perché l'indirizzo conti come usato. Se almeno un indirizzo è
usato si scrive `restore_gap_detected` (indici e indirizzi con
cronologia) e la registrazione viene rifiutata con
`registration_unavailable` (HTTP 503) finché, a un avvio successivo, il
controllo non trova più alcun indirizzo usato: l'operatore deve prima
ricostruire gli utenti mancanti (procedura in
[operativita.md](operativita.md#ripristino), B-90). La registrazione è
rifiutata allo stesso modo finché il controllo non è stato completato.
*Codice:* `app/main.py:lifespan`, `app/auth/routes.py:register`, `app/wallet/hd.py:derive_user_address` · *Test:* —
*Stato:* da implementare (B-90) · *Oggi:* nessun controllo; dopo un
ripristino il prossimo utente riceve il primo indice non presente nel
database, anche se il suo indirizzo ha già ricevuto fondi.
- **[REG-16]** Ogni registrazione riuscita scrive l'evento `user_registered`
con l'indice di derivazione e l'indirizzo assegnati, nella stessa
transazione che crea l'utente.
*Codice:* `app/auth/routes.py:register` · *Test:* —
*Stato:* da implementare (B-92) · *Oggi:* la registrazione non scrive alcun
evento di audit.
### Sessione e password
Il login (`POST /auth/login`) restituisce un token JWT valido 24 ore. Cambiare
la password (dal Profilo) o farsela reimpostare dall'operatore invalida
**tutte** le sessioni aperte in precedenza.
Il login (`POST /auth/login`) restituisce un token di sessione. Cambiare la
password (dal Profilo) o farsela reimpostare dall'operatore invalida
**tutte** le sessioni aperte in precedenza. Formato, durata e revoca del token
sono regole di sicurezza ([SEC-21, SEC-22](sicurezza.md#token-di-sessione-jwt));
il freno sui tentativi di login falliti è
[SEC-30](sicurezza.md#limiti-di-frequenza).
- **[REG-09]** Il login confronta lo username senza distinguere maiuscole e
minuscole. Username inesistente e password sbagliata producono la stessa
risposta, `invalid_credentials` (HTTP 401), così che non si possa scoprire
quali account esistono. Una risposta riuscita contiene `access_token` e
l'indirizzo dell'utente.
*Codice:* `app/auth/routes.py:login` ·
l'indirizzo dell'utente. Username e password del login sono lunghi al
massimo 256 caratteri ciascuno; oltre, la richiesta è rifiutata con HTTP 422
prima di qualunque verifica.
*Codice:* `app/auth/routes.py:login`, `app/auth/routes.py:LoginRequest` ·
*Test:* `tests/unit/test_auth.py`
- **[REG-10]** I tentativi di login falliti sono frenati sia per username sia
per IP; durante il blocco la risposta è `rate_limited` (HTTP 429) con
`retry_after_seconds`. Un login riuscito azzera il contatore dello username,
non quello dell'IP. Soglie e tempi sono in [sicurezza.md](sicurezza.md).
*Codice:* `app/auth/routes.py:login`, `app/auth/rate_limit.py:RateLimiter` ·
*Test:* `tests/unit/test_auth.py`
- **[REG-11]** Il token di sessione scade dopo 24 ore (`jwt_expire_minutes`)
e porta con sé la versione del token dell'utente (`token_version`). Un token
la cui versione non coincide più con quella dell'utente, oppure scaduto,
malformato o di un utente inesistente, è rifiutato con `session_expired`
(HTTP 401) dagli endpoint autenticati, e trattato come "non autenticato"
dagli endpoint accessibili anche senza login. Un token emesso prima che la
versione esistesse vale come versione 0.
*Codice:* `app/auth/security.py:create_access_token`, `app/auth/security.py:decode_access_token`, `app/auth/dependencies.py:get_current_user`, `app/auth/dependencies.py:get_optional_user` ·
*Test:* `tests/unit/test_security.py`, `tests/unit/test_users.py`
*Stato:* da implementare (B-94), per la lunghezza massima · *Oggi:* i campi
del login non hanno limiti di lunghezza.
- ~~[REG-10]~~ Assorbito da [SEC-30](sicurezza.md#limiti-di-frequenza):
il freno sui login falliti (chiavi, soglie, azzeramento) non ha nulla di
specifico del dominio oltre a ciò che SEC-30 già dice.
- ~~[REG-11]~~ Assorbito da [SEC-22](sicurezza.md#token-di-sessione-jwt):
scadenza, versione del token e rifiuto con `session_expired` sono regole di
sicurezza (SEC-21, SEC-22, SEC-23) e non resta nulla di specifico del
dominio.
- **[REG-12]** Il cambio password (`POST /users/me/change-password`, dal
Profilo) richiede la password attuale — altrimenti `current_password_incorrect`
(HTTP 401) — e una nuova password di almeno 8 caratteri — altrimenti
`password_too_short` (HTTP 400). Se riesce, incrementa `token_version`,
invalidando **tutte** le sessioni aperte, compresa quella della richiesta, e
`password_too_short` (HTTP 400). Entrambi i campi sono lunghi al massimo
256 caratteri, altrimenti HTTP 422. I tentativi con password attuale
sbagliata sono frenati come il login (soglie in
[sicurezza.md](sicurezza.md#limiti-di-frequenza), B-94). Se riesce,
incrementa `token_version`, invalidando **tutte** le sessioni aperte,
compresa quella della richiesta, scrive l'evento `password_changed` e
restituisce un token nuovo perché la sessione corrente continui senza nuovo
login.
login. Questo requisito è il proprietario del flusso; [sicurezza.md](sicurezza.md)
e [api.md](api.md) vi rimandano.
*Codice:* `app/api/routes/users.py:change_password` ·
*Test:* `tests/unit/test_users.py`
*Stato:* da implementare (B-94), per lunghezza massima, freno ed evento
`password_changed` · *Oggi:* nessun limite di lunghezza, nessun freno sui
tentativi, nessun evento di audit.
- **[REG-13]** Non esiste recupero password: non viene raccolta alcuna email.
L'unica strada è il reset dall'operatore
(`POST /admin/users/{id}/reset-password`), che imposta una password casuale
@@ -130,63 +164,116 @@ la password (dal Profilo) o farsela reimpostare dall'operatore invalida
### Il conto del montepremi
Oltre agli indirizzi utente, dalla stessa master key si deriva un indirizzo
riservato al **montepremi**. Tutte le scommesse vengono inviate lì, e i
pagamenti ai vincitori sono firmati con la sua chiave.
Oltre agli indirizzi utente, dalla stessa master key si derivano gli indirizzi
del **montepremi**: uno per ogni round, su cui arrivano le scommesse di quel
round e da cui parte il suo pagamento, e un indirizzo di **riserva** che
riceve la riserva per l'RBF di ogni pagamento
([ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#4--pagamento), B-79).
- **[REG-14]** L'indirizzo del montepremi è il P2WPKH del ramo `1/0`
dell'account (`m/84'/746'/0'/1/0`), mentre gli utenti stanno sul ramo `0`.
Le sue monete non sono registrate tra le monete degli utenti: il pagamento
le legge direttamente dalla rete (vedi
[ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#4--pagamento)).
- **[REG-14]** Gli utenti stanno sul ramo `0` dell'account
(`m/84'/746'/0'/0/<indice>`). Il montepremi di un round è il P2WPKH di
`m/84'/746'/0'/2/<round_id>`, salvato sul round all'apertura; l'indirizzo
di riserva è il P2WPKH di `m/84'/746'/0'/1/0`, che è anche il montepremi
dei round aperti prima di questa modifica. Le loro monete non sono
registrate tra le monete degli utenti: il pagamento le legge dalla rete e
le verifica con il quorum
([ELC-27](connessione-electrum.md#5-il-quorum)).
*Codice:* `app/wallet/hd.py:derive_pool_key`, `app/wallet/hd.py:derive_pool_address` ·
*Test:* `tests/unit/test_pending_address.py`
*Stato:* da implementare (B-80) · *Oggi:* esiste un solo indirizzo del
montepremi, `m/84'/746'/0'/1/0`, per tutti i round.
## Deposito
L'utente invia PLM al proprio indirizzo da qualunque wallet esterno. Non c'è
un importo minimo.
L'utente invia PLM al proprio indirizzo da qualunque wallet esterno.
Un **deposito** è una moneta arrivata all'indirizzo di un utente da una
transazione che la piattaforma non ha costruito. Le monete prodotte dalle
transazioni della piattaforma — il resto di scommesse e prelievi, le
vincite — arrivano allo stesso indirizzo e passano per lo stesso codice, ma
con la soglia di conferme delle transazioni della piattaforma (1): il
deposito è l'unico ingresso che un utente può spendere due volte
([DEC-06](decisioni-e-limiti.md)).
```mermaid
flowchart TB
A["Arriva una notifica Electrum<br/>per l'indirizzo, oppure<br/>il giro periodico di controllo"] --> B["Si legge l'elenco delle<br/>monete (UTXO) dell'indirizzo<br/>dal server attivo"]
B --> C{"Moneta nuova<br/>con almeno 1 conferma?"}
C -- "No" --> Z["Nulla da fare"]
C -- "Sì" --> D{"La maggioranza degli<br/>altri server conferma stessa<br/>moneta, stesso importo?"}
D -- "No / non rispondono" --> R["Accredito rinviato<br/>al prossimo controllo"]
A["Notifica Electrum per l'indirizzo,<br/>(re)iscrizione, oppure<br/>giro periodico (DEP-09)"] --> L["Aggiornamenti dello stesso<br/>utente in fila (DEP-15)"]
L --> B["Si legge l'elenco delle<br/>monete (UTXO) dell'indirizzo<br/>dal server attivo"]
B --> DU{"Moneta sotto<br/>DUST_LIMIT_SATS?"}
DU -- "Sì" --> Z["Ignorata (DEP-01)"]
DU -- "No" --> C{"Moneta nuova<br/>e confermata?"}
C -- "No" --> Z2["Nulla da fare"]
C -- "Sì" --> K["Soglia (DEP-03):<br/>1 se la transazione è della piattaforma,<br/>120 se coinbase,<br/>altrimenti deposit_confirmations"]
K --> KK{"Conferme ≥ soglia?"}
KK -- "No" --> P["Mostrata come in attesa<br/>nel saldo mostrato (DEP-14)"]
KK -- "Sì" --> D{"Il quorum degli altri<br/>server conferma moneta,<br/>importo e conferme?"}
D -- "No / meno di 2 risposte" --> R["Accredito rinviato<br/>al prossimo controllo"]
D -- "Sì" --> E["Moneta registrata,<br/>saldo ricalcolato<br/>(deposit_credited)"]
B --> F{"Una moneta nota<br/>non spesa è sparita?"}
F -- "Sì, e la maggioranza degli<br/>altri server la conferma spesa" --> G["Segnata come spesa<br/>fuori dalla piattaforma<br/>(utxo_spent_externally)"]
F -- "Sì, e il quorum<br/>la conferma spesa" --> G["Segnata come spesa<br/>fuori dalla piattaforma<br/>(utxo_spent_externally)"]
B --> H{"Una moneta data per spesa<br/>fuori è ricomparsa?"}
H -- "Sì" --> I["Reintegrata<br/>(utxo_external_spend_reinstated)"]
H -- "Sì, e il quorum<br/>la conferma non spesa" --> I["Reintegrata<br/>(utxo_external_spend_reinstated)"]
```
Le vincite arrivano allo stesso modo: il pagamento del round è una normale
transazione verso l'indirizzo del vincitore, e viene accreditato come un
deposito. Lo stesso vale per il resto di scommesse e prelievi, che torna
all'indirizzo dell'utente.
*Comportamento atteso.* Oggi ogni moneta confermata si accredita a 1
conferma, di qualunque importo e anche se coinbase; il reintegro non è
corroborato; gli aggiornamenti dello stesso utente non sono in fila; le
monete sotto la soglia non compaiono nel saldo mostrato.
- **[DEP-01]** Non c'è un importo minimo di deposito.
*Codice:* `app/deposits/service.py:credit_confirmed_utxos`
- **[DEP-01]** Non c'è un importo minimo di deposito oltre alla soglia di
polvere: una moneta di valore inferiore a `DUST_LIMIT_SATS` (294 sat) non
viene mai accreditata né mostrata, e non entra in alcun altro controllo di
questo documento. Non è spendibile in modo economico e, se accreditata,
farebbe crescere senza limite il lavoro di ogni aggiornamento; chiunque
può inviarne a qualunque indirizzo pubblico.
*Codice:* `app/deposits/service.py:find_new_credit_candidates`, `app/deposits/service.py:credit_confirmed_utxos`, `app/wallet/psbt_builder.py:DUST_LIMIT_SATS` · *Test:* —
*Stato:* da implementare (B-75) · *Oggi:* si accredita una moneta di
qualunque importo.
- **[DEP-02]** Un aggiornamento dell'indirizzo di un utente legge l'elenco
delle monete non spese (`listunspent`) dal server Electrum attivo ed esegue,
in quest'ordine: individuazione degli accrediti nuovi, reintegro delle
monete ricomparse, individuazione delle monete sparite; poi corrobora
accrediti e sparizioni presso gli altri server e solo dopo scrive il
risultato. Nessuna sessione del database resta aperta durante le chiamate
di rete.
delle monete non spese (`listunspent`) dal server Electrum attivo e procede
in tre fasi. **Lettura**, senza scrivere nulla: individuazione degli
accrediti nuovi, delle monete ricomparse e delle monete sparite.
**Corroborazione** presso gli altri server di accrediti
([ELC-17](connessione-electrum.md#5-il-quorum)), reintegri
([ELC-25](connessione-electrum.md#5-il-quorum)) e sparizioni
([ELC-16](connessione-electrum.md#5-il-quorum)). **Scrittura** dei soli
casi corroborati, ricontrollando lo stato di ogni moneta al salvataggio.
Nessuna sessione del database resta aperta durante le chiamate di rete.
*Codice:* `app/electrum/listener.py:ElectrumListener.refresh_user` ·
*Test:* `tests/unit/test_electrum_listener.py`
- **[DEP-03]** **Una conferma basta.** Una moneta è candidata all'accredito
*Stato:* da implementare (B-83) · *Oggi:* il reintegro delle monete
ricomparse viene **scritto e committato già nella fase di lettura**, prima
di qualunque corroborazione; solo accrediti e sparizioni sono corroborati
prima di essere scritti.
- **[DEP-03]** **Soglia di conferme.** Una moneta è candidata all'accredito
solo se è confermata (altezza maggiore di 0: le monete ancora in mempool
sono ignorate) e non è già registrata. Il rischio di una riorganizzazione
della catena a 1 conferma è accettato consapevolmente; non c'è logica di
annullamento (vedi [decisioni-e-limiti.md](decisioni-e-limiti.md)).
*Codice:* `app/deposits/service.py:find_new_credit_candidates` ·
sono ignorate), non è già registrata e ha raggiunto la sua soglia di
conferme. Le conferme sono `punta − altezza + 1`, sulla punta validata del
listener ([connessione-electrum.md](connessione-electrum.md#4-header-validati-non-creduti)).
La soglia è:
- **1** se la transazione che l'ha creata è una transazione della
piattaforma (uno qualunque dei txid di una riga di
`pending_transactions`, compresi quelli sostituiti da un RBF,
[modello-dati.md](modello-dati.md) B-77): resto di scommesse e prelievi,
vincite;
- **120** (la maturità delle coinbase di PLM, `COINBASE_MATURITY` in
`palladiumcore/src/consensus/consensus.h`) se la transazione è una
coinbase, cioè il suo unico ingresso ha l'outpoint nullo. Lo si stabilisce
dalla transazione grezza (`blockchain.transaction.get`), accettata solo se
il suo hash coincide con il txid;
- **`deposit_confirmations`** (`round_config`, predefinito 6,
[modello-dati.md](modello-dati.md) B-82) in ogni altro caso.
Una moneta accreditata e poi sparita per una riorganizzazione più profonda
della soglia segue la strada delle monete spese altrove
([DEP-06], [DEP-07]); non c'è altra logica di annullamento.
*Codice:* `app/deposits/service.py:find_new_credit_candidates`, `app/electrum/listener.py:ElectrumListener.refresh_user` ·
*Test:* `tests/unit/test_deposits.py`
*Stato:* da implementare (B-82) · *Oggi:* **una conferma basta** per ogni
moneta, deposito o coinbase che sia.
- **[DEP-04]** **Ogni accredito è corroborato.** Prima di aumentare un saldo,
il server chiede agli *altri* server Electrum configurati se quella moneta
esiste davvero, con quell'importo, confermata
esiste davvero, con quell'importo e con le conferme richieste
([ELC-17](connessione-electrum.md#5-il-quorum)). Un server malevolo non può
quindi inventarsi un deposito. Se la verifica non riesce l'accredito non è
perso, solo rimandato: la moneta viene riproposta all'aggiornamento
@@ -210,8 +297,8 @@ all'indirizzo dell'utente.
incompleta, non come una spesa di tutto.
*Codice:* `app/deposits/service.py:find_utxos_missing_from` ·
*Test:* `tests/unit/test_deposits.py`
- **[DEP-07]** Un candidato viene tolto dal saldo solo dopo che la
maggioranza degli altri server conferma che la moneta non è più non spesa
- **[DEP-07]** Un candidato viene tolto dal saldo solo dopo che il quorum
degli altri server conferma che la moneta non è più non spesa
([ELC-16](connessione-electrum.md#5-il-quorum)). Al salvataggio si
ricontrolla che la moneta sia ancora non spesa (nel frattempo potrebbe
averla spesa la piattaforma); la si segna con il marcatore di spesa esterna,
@@ -220,12 +307,18 @@ all'indirizzo dell'utente.
*Codice:* `app/electrum/listener.py:ElectrumListener.refresh_user`, `app/deposits/service.py:mark_utxos_spent_externally` ·
*Test:* `tests/unit/test_deposits.py`, `tests/unit/test_electrum_listener.py`
- **[DEP-08]** **Reintegro.** Una moneta segnata come spesa fuori dalla
piattaforma che ricompare nell'elenco viene reintegrata: il marcatore è
piattaforma che ricompare nell'elenco viene reintegrata solo dopo che il
quorum degli altri server la conferma non spesa, con lo stesso importo e
confermata, come per un accredito
([ELC-25](connessione-electrum.md#5-il-quorum)). Al salvataggio si
ricontrolla che porti ancora il marcatore di spesa esterna; il marcatore è
rimosso, si scrive `utxo_external_spend_reinstated`, si ricalcola il saldo e
si invia una notifica SSE. Il reintegro si basa sulla sola risposta del
server attivo, senza corroborazione.
*Codice:* `app/deposits/service.py:reinstate_reappeared_utxos` ·
si invia una notifica SSE. Se la verifica non riesce la moneta resta fuori
dal saldo e viene riproposta all'aggiornamento successivo.
*Codice:* `app/deposits/service.py:reinstate_reappeared_utxos`, `app/electrum/listener.py:ElectrumListener.refresh_user` ·
*Test:* `tests/unit/test_deposits.py`
*Stato:* da implementare (B-83) · *Oggi:* il reintegro si basa sulla sola
risposta del server attivo, senza corroborazione.
- **[DEP-09]** **Due vie, un solo codice.** Un aggiornamento parte quando il
server notifica un cambiamento su un indirizzo osservato, alla
(re)iscrizione di un indirizzo, e al giro periodico: tutte e tre usano la
@@ -234,13 +327,36 @@ all'indirizzo dell'utente.
*Codice:* `app/electrum/listener.py:ElectrumListener._consume_scripthash`, `app/electrum/listener.py:ElectrumListener._subscribe_and_refresh`, `app/deposits/reconcile.py:DepositReconciler._sweep_once` ·
*Test:* `tests/unit/test_deposit_reconcile.py`
- **[DEP-10]** <a id="dep-10"></a>Il giro periodico (`DepositReconciler`)
attende 300 secondi, poi riaggiorna **tutti** gli utenti, non solo quelli
che risultano non iscritti: serve a recuperare un'iscrizione persa
silenziosamente. Il giro salta se non c'è connessione, si interrompe se la
connessione cade a metà (la reiscrizione alla riconnessione copre tutti), e
l'errore su un utente viene registrato senza fermare gli altri.
riaggiorna **tutti** gli utenti, non solo quelli che risultano non
iscritti: serve a recuperare un'iscrizione persa silenziosamente. Prima di
ogni giro, incluso il primo, attende 300 s (`_SWEEP_INTERVAL_SECONDS`)
dalla fine del giro precedente (per il primo, dall'avvio); i giri sono
seriali, e dentro un giro gli utenti sono aggiornati uno alla volta. Il giro
salta se non c'è connessione, si interrompe se la connessione cade a metà
(la reiscrizione alla riconnessione copre tutti), e l'errore su un utente
viene registrato senza fermare gli altri.
*Codice:* `app/deposits/reconcile.py:DepositReconciler.run`, `app/deposits/reconcile.py:DepositReconciler._sweep_once` ·
*Test:* `tests/unit/test_deposit_reconcile.py`
- **[DEP-15]** Gli aggiornamenti dello **stesso** utente sono serializzati:
una notifica, la reiscrizione e il giro periodico possono chiederli insieme,
ma ne gira uno alla volta per utente, in ordine di arrivo. Il blocco è
proprio dell'aggiornamento e distinto da quello per-utente di scommesse e
prelievi ([scommesse-e-prelievi.md](scommesse-e-prelievi.md)), così una
corroborazione in corso non ritarda una scommessa. Utenti diversi si
aggiornano in parallelo come oggi.
*Codice:* `app/electrum/listener.py:ElectrumListener.refresh_user` · *Test:* —
*Stato:* da implementare (B-96) · *Oggi:* due aggiornamenti dello stesso
utente possono girare insieme e tentare di accreditare la stessa moneta.
- **[DEP-16]** Un errore durante l'aggiornamento di un utente non chiude la
connessione Electrum: viene registrato nei log e l'utente viene ripreso
all'aggiornamento successivo. In particolare una violazione dell'unicità
txid/posizione all'accredito ([DEP-05]) vale come "moneta già registrata":
si annulla la transazione del database di quell'accredito e si prosegue.
Fa eccezione solo la caduta della connessione stessa, che termina la
sessione come in [ELC-06](connessione-electrum.md#3-caduta-rilevata).
*Codice:* `app/electrum/listener.py:ElectrumListener._consume_scripthash`, `app/deposits/service.py:credit_confirmed_utxos` · *Test:* —
*Stato:* da implementare (B-96) · *Oggi:* l'eccezione risale da
`refresh_user` a `_consume_scripthash` e termina la sessione Electrum.
## Il saldo mostrato
@@ -248,19 +364,23 @@ Scommesse e prelievi spendono monete **intere**: per pagare 10 PLM con una
moneta da 50, la moneta da 50 viene spesa tutta e 40 tornano all'utente come
resto (nella scommessa la commissione è dedotta dai 10 PLM, vedi
[scommesse-e-prelievi.md](scommesse-e-prelievi.md#cosa-succede)), in una nuova
moneta che però è confermata solo al blocco successivo.
moneta che però è confermata solo al blocco successivo. Allo stesso modo un
deposito resta non spendibile finché non raggiunge la sua soglia di conferme
([DEP-03]).
Per questo esistono due saldi, entrambi restituiti da `GET /users/me`:
| Campo | Cosa conta | A cosa serve |
|---|---|---|
| `balance_sats` | Solo monete confermate e non spese | È ciò che si può spendere: prelievo massimo, controlli sulla scommessa |
| `pending_balance_sats` | Il precedente **più** il resto delle proprie transazioni ancora in corso | È ciò che l'interfaccia mostra |
| `balance_sats` | Solo monete accreditate e non spese | È ciò che si può spendere: prelievo massimo, controlli sulla scommessa |
| `pending_balance_sats` | Il precedente **più** il resto delle proprie transazioni ancora in corso **più** i depositi confermati ma sotto la soglia | È ciò che l'interfaccia mostra |
Senza il secondo, subito dopo una scommessa l'utente vedrebbe sparire l'intero
resto (spesso molto più dei 10 PLM giocati) fino alla conferma. L'interfaccia
mostra il saldo in **verde** quando tutto è confermato e in **ambra** finché
c'è qualcosa in corso (`has_pending`).
resto (spesso molto più dei 10 PLM giocati) fino alla conferma, e un
deposito resterebbe invisibile finché non raggiunge `deposit_confirmations`
conferme. L'interfaccia mostra il saldo
in **verde** quando tutto è confermato e in **ambra** finché c'è qualcosa in
corso (`has_pending`).
- **[DEP-11]** Il saldo confermato (`balance_sats`, colonna
`cached_balance_sats`) è la somma delle monete registrate dell'utente non
@@ -269,19 +389,40 @@ c'è qualcosa in corso (`has_pending`).
*Codice:* `app/wallet/balance.py:recompute_balance` ·
*Test:* `tests/unit/test_deposits.py`
- **[DEP-12]** Il saldo mostrato (`pending_balance_sats`) è il saldo
confermato più le uscite verso l'indirizzo dell'utente di ogni sua
confermato più: (a) le uscite verso l'indirizzo dell'utente di ogni sua
scommessa o prelievo in stato `building` o `pending`, lette dalla
transazione corrente (aggiornata a ogni RBF). Un'uscita già registrata come
moneta (perché il resto è stato accreditato prima che la transazione
risultasse confermata) non viene contata due volte. `has_pending` è vero
finché esiste almeno una di queste transazioni.
transazione corrente (aggiornata a ogni RBF); (b) i depositi in attesa di
[DEP-14]. Un'uscita già registrata come moneta (perché il resto è stato
accreditato prima che la transazione risultasse confermata) non viene
contata due volte. `has_pending` è vero finché esiste almeno una
transazione di (a) o un deposito di (b).
*Codice:* `app/wallet/balance.py:compute_pending_balance`, `app/api/routes/users.py:me` ·
*Test:* `tests/unit/test_balance.py`
- **[DEP-13]** Ogni spesa (scommessa, prelievo) usa solo monete confermate e
*Stato:* da implementare (B-82), per la parte (b) · *Oggi:* conta solo la
parte (a).
- **[DEP-14]** **Depositi in attesa.** Una moneta sopra la soglia di polvere,
confermata (altezza maggiore di 0), non ancora registrata e con meno
conferme della sua soglia ([DEP-03]) è un *deposito in attesa*. Il listener
tiene, per ogni utente, l'insieme dei depositi in attesa visti all'ultimo
aggiornamento, sostituendolo a ogni aggiornamento: un deposito sparito
dall'elenco (ad esempio per una riorganizzazione) smette di essere mostrato,
uno accreditato passa nel saldo confermato. L'insieme sta solo in memoria —
non sposta denaro e non è spendibile, quindi non è corroborato — e dopo un
riavvio si ricostruisce alla prima reiscrizione ([ELC-18](connessione-electrum.md#riconnessione)).
Le monete ancora in mempool non sono depositi in attesa.
*Codice:* `app/electrum/listener.py:ElectrumListener.refresh_user`, `app/wallet/balance.py:compute_pending_balance` · *Test:* —
*Stato:* da implementare (B-82) · *Oggi:* con la soglia a 1 conferma non
esistono depositi in attesa; una moneta in mempool non compare in nessun
saldo.
- **[DEP-13]** Ogni spesa (scommessa, prelievo) usa solo monete accreditate e
non spese: il saldo mostrato è informativo, non spendibile. Se un utente
chiede un prelievo coperto dal saldo mostrato ma non ancora da quello
confermato, riceve l'errore `balance_pending_confirmation` ("attendi la
conferma") invece di un generico "saldo insufficiente" che contraddirebbe
ciò che vede ([WDR-05](scommesse-e-prelievi.md#prelievo)).
*Codice:* `app/withdrawals/service.py:request_withdrawal` ·
chiede un prelievo o una scommessa coperti dal saldo mostrato ma non ancora
da quello confermato, riceve l'errore `balance_pending_confirmation`
("attendi la conferma") invece di un generico "saldo insufficiente" che
contraddirebbe ciò che vede ([WDR-05](scommesse-e-prelievi.md#prelievo); per
la scommessa [scommesse-e-prelievi.md](scommesse-e-prelievi.md), B-96).
*Codice:* `app/withdrawals/service.py:request_withdrawal`, `app/bets/service.py:place_bet` ·
*Test:* `tests/unit/test_withdrawals.py`
*Stato:* da implementare (B-96), per la scommessa · *Oggi:* solo il
prelievo distingue i due casi; una scommessa coperta solo dal saldo
mostrato riceve `insufficient_balance`.