Files
plm-lottery/docs/transazioni-e-riconciliazione.md
T
davideandClaude Opus 5.5 61efbb0e37 Replace flowchart/ with a traceable specification in docs/
The two Mermaid diagrams under flowchart/ described the intended flow but
had drifted from the code and carried no link back to it. docs/ now holds
the specification instead: 15 Italian documents (flows, architecture, data
model, API, security, audit log, operations, decisions and limits, bug
history) with 472 numbered requirements, each pointing at the function
that implements it and the test that covers it. docs/processo-di-modifica.md
defines the ID convention and the spec -> code -> test change workflow, and
CLAUDE.md now names docs/ as authoritative.

Writing the spec from the code also corrected stale claims in CLAUDE.md
(B-41's get_history check, BUGS.md still tracking B-71/B-72, Cache-Control
scope, the error contract's bare-string exceptions) and in the operator
guides (payouts do retry, only `drawing` fails to resume, rounds do not
open without fee_address). The B-70 doc test now pins the prose in
docs/scommesse-e-prelievi.md instead of the deleted diagram.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 12:16:01 +02:00

231 lines
13 KiB
Markdown

# Transazioni e riconciliazione
Come ogni movimento di denaro — scommessa, prelievo, pagamento del round —
viene registrato, inviato, accelerato e infine confrontato con la catena.
L'obiettivo è che il sistema si rimetta in ordine da solo dopo un crash o un
problema di rete, senza interventi manuali sul database.
I requisiti usano il prefisso `TX`, secondo la convenzione di
[processo-di-modifica.md](processo-di-modifica.md). Le colonne della tabella
`pending_transactions` sono descritte in [modello-dati.md](modello-dati.md),
gli eventi di audit in [audit-log.md](audit-log.md), le attività in
background e le loro cadenze in [architettura.md](architettura.md).
## Il principio: prima si scrive, poi si invia
Nessuna transazione viene inviata alla rete senza che il database ne abbia già
traccia. Ogni transazione in uscita ha una riga `PendingTransaction` che
attraversa questi stati:
```mermaid
stateDiagram-v2
[*] --> building: transazione firmata,<br/>monete segnate come spese,<br/>salvato PRIMA dell'invio
building --> pending: la rete accetta l'invio
building --> [*]: scommessa rifiutata dalla rete<br/>(riga cancellata, tutto annullato)
building --> failed: prelievo rifiutato dalla rete<br/>(tutto annullato)
building --> pending: il riconciliatore la trova<br/>in rete (dopo 120s)
building --> failed: il riconciliatore non la<br/>trova in rete (dopo 120s)
pending --> pending: nessuna conferma<br/>entro il tempo limite → RBF
pending --> confirmed: 1 conferma
pending --> failed: il riconciliatore non la<br/>trova in rete (dopo 6h dal primo invio)
confirmed --> [*]
failed --> [*]
```
- **[TX-01]** Ogni transazione in uscita ha una riga `PendingTransaction` di
tipo `bet`, `withdrawal` o `payout`, con stato `building`, `pending`,
`confirmed` o `failed`. La riga (stato `building`, con la transazione
firmata completa) viene salvata e committata **prima** dell'invio, nella
stessa transazione del database in cui le monete spese vengono segnate come
tali e si registra l'oggetto collegato (partecipante, prelievo, dati di
pagamento del round).
*Codice:* `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_scheduler.py`
- **[TX-02]** Il database non viene mai tenuto aperto durante una chiamata di
rete: la scrittura di `building` è committata, poi si invia, poi si aggiorna
(in una nuova sessione per il pagamento). Se il processo muore proprio in
mezzo, resta la prova di cosa stava succedendo, non monete spese in catena
senza alcun record.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout`, `app/tx/broadcast.py:bump_fee` ·
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_broadcast.py`
- **[TX-03]** `broadcast_at` è l'orario in cui la riga è stata scritta, cioè
del **primo** invio, e non viene mai riscritto; `last_broadcast_at` è
quello dell'ultimo invio, ed è l'unico che l'RBF aggiorna.
*Codice:* `app/db/models.py:PendingTransaction`, `app/tx/broadcast.py:bump_fee` ·
*Test:* `tests/unit/test_broadcast.py`
### Invio rifiutato
- **[TX-04]** Se l'invio di una scommessa o di un prelievo fallisce, tutto
torna com'era: monete liberate, saldo ripristinato, evento scritto nel
registro di audit (`bet_broadcast_failed`, `withdrawal_broadcast_failed`),
notifica SSE. Per una scommessa partecipante e riga vengono **cancellati**;
per un prelievo prelievo e riga restano, in stato `failed`. L'utente riceve
`broadcast_failed` con codice HTTP **502**, perché è stata la rete a
rifiutare, non la sua richiesta a essere sbagliata. Qualunque errore
dell'invio è trattato così, anche la scadenza del tempo di risposta.
*Codice:* `app/bets/service.py:_release_failed_bet`, `app/withdrawals/service.py:_release_failed_withdrawal` ·
*Test:* `tests/unit/test_bets.py`, `tests/unit/test_withdrawals.py`
- **[TX-05]** Se l'invio di un pagamento fallisce, la riga resta `building`
e si scrive `payout_failed` (`broadcast rejected`): è il riconciliatore a
decidere, interrogando la rete, se la transazione è partita o no
([TX-16], [TX-17]).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
*Test:* `tests/unit/test_scheduler.py`
## Conferma
- **[TX-06]** `ConfirmationPoller` controlla ogni 10 secondi le transazioni
in stato `pending` (non quelle `building`), e salta il giro se non c'è
connessione. Per ciascuna legge la cronologia
(`blockchain.scripthash.get_history`) dell'indirizzo che la spende —
l'indirizzo dell'utente, o quello del montepremi per un pagamento — e la
considera confermata quando il suo txid corrente vi compare con altezza
maggiore di 0. La cronologia è letta una volta per indirizzo a ogni giro;
un indirizzo che non si riesce a leggere non blocca gli altri.
*Codice:* `app/tx/confirmation.py:poll_once`, `app/tx/pending_address.py:own_address_for` ·
*Test:* `tests/unit/test_confirmation.py`
- **[TX-07]** Alla prima conferma la riga passa a `confirmed` e, nella stessa
transazione del database, viene chiamato il gestore del suo tipo; poi si
invia una notifica SSE:
| Tipo | Cosa succede alla conferma |
|---|---|
| Scommessa | Il partecipante (se `building` o `broadcast`) diventa `confirmed`, con `confirmed_at`, ed entra nell'estrazione |
| Prelievo | Il prelievo (se `building` o `broadcast`) diventa `confirmed`, con `confirmed_at` |
| Pagamento | Il round (se `paying_out`) passa a `closed`, `closed_at` diventa l'orario della conferma e parte la pausa prima del successivo |
*Codice:* `app/tx/confirmation.py:poll_once`, `app/bets/confirmation.py:_on_bet_confirmed`, `app/withdrawals/confirmation.py:_on_withdrawal_confirmed`, `app/rounds/confirmation.py:_on_payout_confirmed` ·
*Test:* `tests/unit/test_confirmation.py`
- **[TX-08]** I gestori ritrovano l'oggetto a cui la transazione si riferisce
tramite identificativi fissi (round e utente per la scommessa, prelievo,
round per il pagamento), **mai principalmente tramite il txid**, perché il
txid cambia a ogni RBF; il txid serve solo come ripiego per righe prive di
quei collegamenti.
*Codice:* `app/bets/confirmation.py:_on_bet_confirmed`, `app/rounds/confirmation.py:_on_payout_confirmed` ·
*Test:* `tests/unit/test_confirmation.py`
I gestori sono registrati all'avvio importando i moduli `confirmation` di
scommesse, round e prelievi (vedi [architettura.md](architettura.md)).
## RBF: accelerare una transazione lenta
Se una transazione resta senza conferma oltre `rbf_timeout_seconds` (900s
predefiniti), `RbfBumper` la ricostruisce con una commissione più alta e la
reinvia (Replace-By-Fee). Tutte le transazioni della piattaforma segnalano la
sostituibilità fin dal primo invio.
- **[TX-09]** `RbfBumper` controlla ogni 30 secondi le righe in stato
`pending` (salta il giro senza connessione) e accelera quelle il cui
`last_broadcast_at` è più vecchio di `rbf_timeout_seconds`: dopo ogni
accelerazione la transazione ha di nuovo l'intero tempo limite. Un errore
su una riga viene registrato nei log e non ferma le altre.
*Codice:* `app/tx/broadcast.py:RbfBumper._tick`, `app/tx/broadcast.py:should_bump` ·
*Test:* `tests/unit/test_broadcast.py`
- **[TX-10]** La nuova commissione punta a 1 sat/vB in più della tariffa
registrata (`_FEE_RATE_INCREMENT`), senza superare 10.000 sat/vB
(`MAX_FEE_RATE_SAT_VB`); l'aumento assoluto non è mai inferiore alla
dimensione stimata della transazione per 1 sat/vB, il minimo richiesto da
BIP125 per una sostituzione. Una riga già a 10.000 sat/vB non viene più
accelerata. Gli importi delle monete spese sono letti dalle transazioni
precedenti come interi in satoshi.
*Codice:* `app/tx/broadcast.py:bump_fee`, `app/tx/broadcast.py:_prevout_amount` ·
*Test:* `tests/unit/test_broadcast.py`
- **[TX-11]** **Paga chi riceve il resto**: la sostituzione spende le stesse
monete e riduce del solo aumento l'uscita di resto verso il mittente —
l'utente per scommesse e prelievi, il montepremi per i pagamenti. Le uscite
verso la controparte (montepremi, indirizzo esterno, vincitore, indirizzo
commissioni) non vengono mai toccate. Se non c'è un'uscita di resto verso il
mittente, o non supera l'aumento, l'accelerazione non è possibile: l'errore
viene registrato nei log, la transazione resta in attesa (il tentativo si
ripete a ogni giro) e prima o poi viene abbandonata dal riconciliatore, che
ne libera le monete.
*Codice:* `app/tx/broadcast.py:bump_fee`, `app/tx/broadcast.py:_find_change_output` ·
*Test:* `tests/unit/test_broadcast.py`
- **[TX-12]** Dopo l'invio della sostituzione la riga registra il nuovo txid
(`current_txid`), la nuova transazione (`raw_tx_hex`), il txid sostituito
(`replaced_by_txid`), la tariffa effettivamente pagata, il numero di
tentativi e `last_broadcast_at`. Il nuovo txid viene propagato ovunque sia
registrato: monete spese (`spent_txid`), partecipante (`bet_txid`),
prelievo (`txid`), round (`payout_txid`).
*Codice:* `app/tx/broadcast.py:bump_fee`, `app/tx/broadcast.py:_retarget_txid_references` ·
*Test:* `tests/unit/test_broadcast.py`
- **[TX-13]** Se al momento dell'accelerazione la riga non esiste più o non è
più `pending` (ad esempio è appena stata confermata), non si fa nulla.
*Codice:* `app/tx/broadcast.py:bump_fee` ·
*Test:* `tests/unit/test_broadcast.py`
Scommesse e prelievi nascono sempre con un'uscita di resto di almeno 294 sat
proprio perché l'RBF abbia qualcosa da ridurre
([scommesse-e-prelievi.md](scommesse-e-prelievi.md)). Il pagamento del round
invece ha un resto verso il montepremi solo quando le monete spese superano il
montepremi di almeno 294 sat: senza resto non è accelerabile.
## Riconciliazione
- **[TX-14]** `PendingTransactionReconciler` gira all'avvio e poi ogni 120
secondi (salta il giro senza connessione), e considera ogni transazione
ancora `building` o `pending` trascorso il suo periodo di tolleranza,
misurato da `broadcast_at` (il primo invio, che l'RBF non sposta): 120s per
`building`, 6 ore per `pending`, così l'RBF ha il tempo di fare i suoi
tentativi.
*Codice:* `app/tx/reconcile.py:PendingTransactionReconciler.run`, `app/tx/reconcile.py:_is_due` ·
*Test:* `tests/unit/test_reconcile.py`
- **[TX-15]** L'esistenza di una transazione si decide cercando il suo txid
corrente nella cronologia (`blockchain.scripthash.get_history`)
dell'indirizzo che la spende, in mempool o in un blocco. Un **errore di
rete** non porta a nulla: la riga resta com'è fino al giro successivo. Solo
un server che risponde con una cronologia priva del txid porta
all'abbandono, mai un server irraggiungibile.
*Codice:* `app/tx/reconcile.py:reconcile_once` ·
*Test:* `tests/unit/test_reconcile.py`
- **[TX-16]** **Presente in rete**: una riga `building` viene promossa a
`pending` (e partecipante o prelievo da `building` a `broadcast`), con un
evento `pending_tx_recovered`; da lì la conferma segue la via normale. Una
riga già `pending` presente in rete non viene toccata.
*Codice:* `app/tx/reconcile.py:_promote` ·
*Test:* `tests/unit/test_reconcile.py`
- **[TX-17]** **Sconosciuta alla rete**: la riga passa a `failed` con motivo
`not found on chain`; le monete che risultano ancora impegnate da *questa*
transazione vengono liberate (non quelle già spese da altro); il
partecipante viene rimosso, o il prelievo segnato `failed` senza txid; il
saldo dell'utente viene ricalcolato; si scrive `pending_tx_abandoned`
(con il numero di monete liberate) e si invia una notifica SSE.
*Codice:* `app/tx/reconcile.py:_abandon`, `app/tx/reconcile.py:_release_inputs` ·
*Test:* `tests/unit/test_reconcile.py`
È questo che rende finita l'attesa del round in `closing`: una scommessa che
non confermerà mai viene prima o poi abbandonata e rimossa.
## Pagamenti del round: riprovare senza pagare due volte
Il pagamento ha bisogno di più protezioni degli altri tipi, perché è
l'operazione che lo scheduler ritenta da solo. Le regole sono in
[ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#4--pagamento):
ogni tentativo fallito scrive un evento `payout_failed` con il motivo, così
`/admin` mostra **perché** un round è fermo, e i tentativi sono limitati a
uno ogni 60 secondi usando proprio l'ultimo `payout_failed` come orologio
([RND-25](ciclo-di-vita-del-round.md#4--pagamento)); non si costruisce un
pagamento se ne esiste già uno `building` o `pending` per quel round, e le
monete del montepremi già impegnate da un pagamento non risolto sono escluse
dalla selezione ([RND-26](ciclo-di-vita-del-round.md#4--pagamento)). Senza
queste ultime due, un nuovo tentativo potrebbe pagare il vincitore due volte.
- **[TX-18]** Un pagamento abbandonato non libera monete utente (quelle del
montepremi non sono registrate): azzera `payout_txid` del round, che resta
in `paying_out` senza transazione, e lo scheduler ricostruisce il pagamento
al tentativo successivo.
*Codice:* `app/tx/reconcile.py:_abandon`, `app/rounds/scheduler.py:RoundScheduler._retry_payout_if_due` ·
*Test:* `tests/unit/test_scheduler.py`
## Dove guardare
Nel pannello `/admin` (vedi [guida-admin.md](guida-admin.md) e
[operativita.md](operativita.md)):
- **Transazioni pendenti** — tutto ciò che è `building` o `pending`, con
orari di invio e candidati all'RBF;
- **Audit log** — `payout_sent`, `payout_failed`, `pending_tx_recovered`,
`pending_tx_abandoned`, `draw_stalled` e tutti gli altri eventi;
- **Round** — stato di ogni round, vincitore e txid del pagamento.