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>
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
PendingTransactiondi tipobet,withdrawalopayout, con statobuilding,pending,confirmedofailed. La riga (statobuilding, 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 statofailed. L'utente ricevebroadcast_failedcon 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
buildinge si scrivepayout_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]
ConfirmationPollercontrolla ogni 10 secondi le transazioni in statopending(non quellebuilding), 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
confirmede, 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 buildingobroadcast) diventaconfirmed, conconfirmed_at, ed entra nell'estrazionePrelievo Il prelievo (se buildingobroadcast) diventaconfirmed, conconfirmed_atPagamento Il round (se paying_out) passa aclosed,closed_atdiventa l'orario della conferma e parte la pausa prima del successivoCodice:
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]
RbfBumpercontrolla ogni 30 secondi le righe in statopending(salta il giro senza connessione) e accelera quelle il cuilast_broadcast_atè più vecchio dirbf_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 elast_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]
PendingTransactionReconcilergira all'avvio e poi ogni 120 secondi (salta il giro senza connessione), e considera ogni transazione ancorabuildingopendingtrascorso il suo periodo di tolleranza, misurato dabroadcast_at(il primo invio, che l'RBF non sposta): 120s perbuilding, 6 ore perpending, 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
buildingviene promossa apending(e partecipante o prelievo dabuildingabroadcast), con un eventopending_tx_recovered; da lì la conferma segue la via normale. Una riga giàpendingpresente 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
failedcon motivonot 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 segnatofailedsenza txid; il saldo dell'utente viene ricalcolato; si scrivepending_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_txiddel round, che resta inpaying_outsenza 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 è
buildingopending, con orari di invio e candidati all'RBF; - Audit log —
payout_sent,payout_failed,pending_tx_recovered,pending_tx_abandoned,draw_stallede tutti gli altri eventi; - Round — stato di ogni round, vincitore e txid del pagamento.