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>
This commit is contained in:
1 parent
526a649c8b
commit
61efbb0e37
29 files changed
+6964
-310
No files matched your search
@@ -0,0 +1,230 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user