plm-lottery/docs/registrazione-e-depositi.md

Registrazione, depositi e saldo

Fasi 1 e 2 del funzionamento generale: come nasce un account e come i fondi entrano nella piattaforma.

I requisiti usano i prefissi REG (registrazione e account) e DEP (depositi e saldo), secondo la convenzione di processo-di-modifica.md. Gli endpoint citati sono descritti in dettaglio in api.md; hashing, token e limiti di frequenza in sicurezza.md; le colonne delle tabelle in modello-dati.md; gli eventi di audit in audit-log.md.

Registrazione

L'utente sceglie username e password (POST /auth/register). Il server:

1. salva la password come hash Argon2 (mai in chiaro);
2. assegna all'utente il prossimo indice libero e deriva da questo il suo indirizzo, secondo lo schema BIP84 m/84'/746'/0'/0/<indice> a partire dalla master xprv cifrata. Ne risulta un indirizzo P2WPKH (plm1…);
3. collega l'indirizzo al profilo, in modo permanente;
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).

• [REG-01] Lo username è lungo da 3 a 32 caratteri, composto solo da lettere ASCII, cifre, _, . e -; la password è lunga da 8 (MIN_PASSWORD_LENGTH) a 256 caratteri. Una richiesta che non rispetta questi vincoli è rifiutata con HTTP 422 prima di qualunque altra verifica. Codice: app/auth/routes.py:RegisterRequest, app/auth/security.py:MIN_PASSWORD_LENGTH · Test: tests/unit/test_users.py
• [REG-02] Gli username non distinguono maiuscole e minuscole: Mario e mario sono lo stesso account. Uno username già usato, in qualunque combinazione di maiuscole, è rifiutato con username_taken (HTTP 409), sia dal controllo iniziale sia se la collisione emerge solo al salvataggio (registrazione concorrente). L'unicità è garantita dal database con un indice univoco su lower(username). Il nome resta però salvato come è stato digitato. Codice: app/auth/routes.py:register, app/db/models.py:User · Test: tests/unit/test_auth.py
• [REG-03] La password è salvata solo come hash Argon2, calcolato fuori dal ciclo di eventi (in un thread separato) per non bloccare le attività in background. Codice: app/auth/security.py:hash_password_async · Test: tests/unit/test_security.py
• [REG-04] L'indice di derivazione del nuovo utente è il massimo indice esistente più uno (0 per il primo utente); l'indirizzo è il P2WPKH di m/84'/746'/0'/0/<indice>, con prefisso bech32 plm. Se il salvataggio fallisce per una collisione sull'indice (due registrazioni concorrenti), si 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
• [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 "indirizzo vincite" separato. Codice: app/db/models.py:User, app/bets/service.py:place_bet, app/withdrawals/service.py:request_withdrawal, app/rounds/scheduler.py:RoundScheduler._trigger_payout · Test: tests/unit/test_bets.py, tests/unit/test_withdrawals.py
• [REG-06] Una registrazione riuscita risponde HTTP 201 con un token di sessione (access_token) e l'indirizzo: l'utente è già autenticato, senza un login separato. Codice: app/auth/routes.py:register · Test: tests/unit/test_users.py
• [REG-07] Subito dopo il salvataggio, l'indirizzo viene aggiunto agli indirizzi osservati e, se la connessione Electrum è attiva, gli ci si iscrive in un'attività separata. Se non c'è connessione, o l'iscrizione fallisce, l'errore viene solo registrato nei log: la registrazione riesce comunque, e l'indirizzo viene ripreso dalla reiscrizione completa alla prossima riconnessione (ELC-18) o dal giro periodico di 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. Codice: app/auth/routes.py:register, app/auth/rate_limit.py:AuthRateLimiters · Test: tests/unit/test_auth.py

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.

• [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 · 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. 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
• [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 restituisce un token nuovo perché la sessione corrente continui senza nuovo login. Codice: app/api/routes/users.py:change_password · Test: tests/unit/test_users.py
• [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 nuova, la restituisce una sola volta perché venga comunicata all'utente, incrementa token_version (invalidando tutte le sessioni) e scrive l'evento admin_password_reset. Un utente inesistente dà HTTP 404. Procedura in guida-admin.md. Codice: app/api/routes/admin.py:reset_user_password · Test: tests/unit/test_admin.py

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.

• [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). Codice: app/wallet/hd.py:derive_pool_key, app/wallet/hd.py:derive_pool_address · Test: tests/unit/test_pending_address.py

Deposito

L'utente invia PLM al proprio indirizzo da qualunque wallet esterno. Non c'è un importo minimo.

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"]
    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)"]
    B --> H{"Una moneta data per spesa<br/>fuori è ricomparsa?"}
    H -- "Sì" --> 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.

• [DEP-01] Non c'è un importo minimo di deposito. Codice: app/deposits/service.py:credit_confirmed_utxos
• [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. 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 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). Codice: app/deposits/service.py:find_new_credit_candidates · Test: tests/unit/test_deposits.py
• [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 (ELC-17). 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 successivo (notifica o giro periodico), e nei log resta un avviso. Codice: app/electrum/listener.py:ElectrumListener.refresh_user, app/electrum/listener.py:ElectrumListener.corroborate_utxo_credit · Test: tests/unit/test_electrum_listener.py
• [DEP-05] L'accredito registra la moneta (txid, posizione, importo, altezza) in modo idempotente — una moneta già registrata non viene mai accreditata due volte, e il database impone l'unicità della coppia txid/posizione —, scrive per ciascuna un evento deposit_credited, ricalcola il saldo e invia una notifica SSE. Codice: app/deposits/service.py:credit_confirmed_utxos · Test: tests/unit/test_deposits.py
• [DEP-06] Monete spese altrove. Una moneta registrata come non spesa che non compare più nell'elenco è candidata alla spesa esterna (ad esempio perché qualcuno ha usato la chiave privata esportata dall'admin). Le monete spese dalla piattaforma stessa non sono mai candidate, perché vengono segnate come spese già al momento della costruzione della transazione. Se l'elenco è completamente vuoto mentre il database conosce monete non spese, non si produce alcun candidato: una risposta vuota è trattata come 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 (ELC-16). 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, si scrive utxo_spent_externally, si ricalcola il saldo e si invia una notifica SSE. 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 è 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 · Test: tests/unit/test_deposits.py
• [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 stessa funzione di aggiornamento, così i due percorsi non possono comportarsi diversamente. 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] 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. Codice: app/deposits/reconcile.py:DepositReconciler.run, app/deposits/reconcile.py:DepositReconciler._sweep_once · Test: tests/unit/test_deposit_reconcile.py

Il saldo mostrato

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), in una nuova moneta che però è confermata solo al blocco successivo.

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

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).

• [DEP-11] Il saldo confermato (balance_sats, colonna cached_balance_sats) è la somma delle monete registrate dell'utente non segnate come spese. Viene ricalcolato nella stessa transazione del database di ogni operazione che registra, spende, libera o reintegra monete. 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 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. 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 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). Codice: app/withdrawals/service.py:request_withdrawal · Test: tests/unit/test_withdrawals.py