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:
1 parent
61efbb0e37
commit
88221b0dbd
15 files changed
+4524
-1172
No files matched your search
@@ -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`.
|
||||
Reference in new issue
Block a user