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

# Registrazione, depositi e saldo

Fasi 1 e 2 del [funzionamento generale](come-funziona.md): 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](processo-di-modifica.md). Gli endpoint citati sono
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).

## 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](connessione-electrum.md#riconnessione)) o dal giro
  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`

### 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](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](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](ciclo-di-vita-del-round.md#4--pagamento)).
  *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.

```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"]
    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](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](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
  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](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,
  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]** <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.
  *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](scommesse-e-prelievi.md#cosa-succede)), 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](scommesse-e-prelievi.md#prelievo)).
  *Codice:* `app/withdrawals/service.py:request_withdrawal` ·
  *Test:* `tests/unit/test_withdrawals.py`