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

13 KiB

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. Le colonne della tabella pending_transactions sono descritte in modello-dati.md, gli eventi di audit in audit-log.md, le attività in background e le loro cadenze in 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:

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

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). 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: 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); 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). 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 e 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.