230 lines
13 KiB
Markdown
230 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.
|