temp
This commit is contained in:
1 parent
61efbb0e37
commit
c5e7daa9c7
15 files changed
+4514
-1172
No files matched your search
@@ -3,33 +3,39 @@
|
||||
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.
|
||||
problema di rete, senza interventi manuali sul database, e che **nel dubbio
|
||||
non liberi mai i fondi**: una transazione si annulla solo con una prova che
|
||||
non è partita, mai per un timeout o per il silenzio di un solo server
|
||||
(decisione 2 di [piano-correzioni.md](piano-correzioni.md#le-decisioni)).
|
||||
|
||||
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).
|
||||
[processo-di-modifica.md](processo-di-modifica.md). Le colonne delle tabelle
|
||||
`pending_transactions` e `pending_transaction_txids` 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:
|
||||
attraversa questi stati (comportamento atteso):
|
||||
|
||||
```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)
|
||||
building --> pending: il server accetta l'invio<br/>(anche "già nota")
|
||||
building --> building: invio incerto (timeout,<br/>connessione caduta): nulla liberato
|
||||
building --> [*]: scommessa rifiutata esplicitamente<br/>(riga cancellata, tutto annullato)
|
||||
building --> failed: prelievo rifiutato esplicitamente<br/>(tutto annullato)
|
||||
building --> pending: il riconciliatore trova in rete<br/>uno dei suoi txid (dopo 120s)
|
||||
building --> failed: il riconciliatore ha la prova<br/>che non è partita (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)
|
||||
pending --> confirmed: prova merkle del quorum<br/>per uno dei suoi txid
|
||||
pending --> failed: il riconciliatore ha la prova<br/>che non è partita (dopo 6h dal primo invio)
|
||||
failed --> failed: conferma tardiva entro 14 giorni:<br/>pending_tx_resurrected + pausa
|
||||
confirmed --> [*]
|
||||
failed --> [*]
|
||||
failed --> [*]: dopo 14 giorni
|
||||
```
|
||||
|
||||
- **[TX-01]** Ogni transazione in uscita ha una riga `PendingTransaction` di
|
||||
@@ -53,25 +59,104 @@ stateDiagram-v2
|
||||
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`
|
||||
- **[TX-19]** **Tutte le versioni sono registrate.** Ogni txid che una riga
|
||||
ha avuto, con la sua transazione completa, è una riga di
|
||||
`pending_transaction_txids` ([modello-dati.md](modello-dati.md) (B-77)): la
|
||||
prima versione è scritta insieme alla riga `PendingTransaction` ([TX-01]),
|
||||
ogni sostituzione RBF prima di essere inviata ([TX-12]). Conferma
|
||||
([TX-06]), riconciliazione ([TX-15]) e sorveglianza delle righe `failed`
|
||||
([TX-23]) cercano **ogni** txid della riga, non solo `current_txid`. Quando
|
||||
la versione trovata in catena non è quella corrente, `current_txid` e
|
||||
`raw_tx_hex` diventano quelli della versione trovata e il txid viene
|
||||
propagato ovunque sia registrato, come dopo un RBF ([TX-12]).
|
||||
*Codice:* `app/tx/confirmation.py:poll_once`, `app/tx/reconcile.py:reconcile_once`, `app/tx/broadcast.py:_retarget_txid_references` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-77) · *Oggi:* si conserva solo il txid corrente
|
||||
(più il precedente in `replaced_by_txid`, che nessuno legge); se conferma
|
||||
una versione precedente a un RBF non viene riconosciuta.
|
||||
- **[TX-28]** Ogni transazione del database che sposta denaro — la scrittura
|
||||
di `building` ([TX-01]), la promozione dopo l'invio, l'annullamento dopo un
|
||||
rifiuto, le due scritture dell'RBF ([TX-12]), la promozione e l'abbandono
|
||||
del riconciliatore, la conferma ([TX-07]) — si apre con `BEGIN IMMEDIATE`,
|
||||
cioè prende il blocco in scrittura di SQLite **prima** delle proprie
|
||||
letture, così quelle letture non possono cambiare fino al commit. Se il
|
||||
blocco non si ottiene entro il tempo di attesa di SQLite (5 secondi,
|
||||
`_SQLITE_BUSY_TIMEOUT_MS`) l'operazione fallisce con `database is locked`
|
||||
e viene annullata: prima dell'invio non si è mosso nulla; dopo un invio
|
||||
riuscito le righe restano `building` e vale [TX-20]. La durabilità dei
|
||||
commit (`synchronous=FULL`) è descritta in
|
||||
[architettura.md](architettura.md) (B-88).
|
||||
*Codice:* `app/db/base.py:_register_sqlite_pragmas`, `app/bets/service.py:place_bet`, `app/withdrawals/service.py:request_withdrawal` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-88) · *Oggi:* pysqlite in modalità legacy apre
|
||||
la transazione solo alla prima scrittura, quindi le letture precedenti non
|
||||
sono isolate; un'attesa del blocco oltre 5 secondi emerge come
|
||||
`OperationalError` in un punto qualunque, anche dopo un invio riuscito.
|
||||
|
||||
### 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
|
||||
Un invio può finire in tre modi, e solo uno di essi permette di liberare le
|
||||
monete:
|
||||
|
||||
| Esito | Cosa significa | Cosa si fa |
|
||||
|---|---|---|
|
||||
| Accettato | Il server risponde con il txid, oppure rifiuta dicendo che la transazione è già nota | Si promuove la riga ([BET-17](scommesse-e-prelievi.md#cosa-succede), [WDR-12](scommesse-e-prelievi.md#prelievo)) |
|
||||
| Rifiutato esplicitamente | Il server risponde con un errore JSON-RPC diverso da "già nota" | Si annulla tutto ([TX-04]) |
|
||||
| Incerto | Timeout, connessione caduta, errore di scrittura sul socket: la transazione può essere partita | Non si libera nulla ([TX-20]) |
|
||||
|
||||
- **[TX-04]** Solo un **rifiuto esplicito** — una risposta del server con un
|
||||
oggetto `error` JSON-RPC — all'invio di una scommessa o di un prelievo
|
||||
annulla tutto: 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` ·
|
||||
rifiutare, non la sua richiesta a essere sbagliata. Un rifiuto che dice che
|
||||
la transazione è **già nota** (messaggi che contengono `already known`,
|
||||
`already in mempool`, `txn-already-known`, `txn-already-in-mempool` o
|
||||
`transaction already in block chain`) non è un rifiuto: vale come invio
|
||||
accettato.
|
||||
*Codice:* `app/bets/service.py:_release_failed_bet`, `app/withdrawals/service.py:_release_failed_withdrawal`, `app/electrum/client.py:ElectrumClient.broadcast` ·
|
||||
*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]).
|
||||
*Stato:* da implementare (B-76) · *Oggi:* qualunque eccezione dell'invio,
|
||||
compresi il timeout di 15 secondi, la connessione caduta dopo la scrittura
|
||||
e il "già nota", annulla tutto e risponde 502, anche se la transazione può
|
||||
essere già in rete.
|
||||
- **[TX-20]** **Invio incerto.** Se l'invio di una scommessa o di un prelievo
|
||||
finisce senza una risposta del server (timeout, connessione caduta, errore
|
||||
di scrittura), o se il commit della promozione successiva a un invio
|
||||
accettato fallisce ([TX-28]), non si libera nulla: monete spese,
|
||||
partecipante o prelievo e riga `PendingTransaction` restano `building`, e
|
||||
sarà il riconciliatore a stabilire se la transazione è partita ([TX-16],
|
||||
[TX-17]). L'utente riceve HTTP **202** con l'oggetto nello stato
|
||||
`building` ([BET-23](scommesse-e-prelievi.md#cosa-succede),
|
||||
[WDR-16](scommesse-e-prelievi.md#prelievo)) e si invia una notifica SSE.
|
||||
*Codice:* `app/bets/service.py:place_bet`, `app/withdrawals/service.py:request_withdrawal` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-76) · *Oggi:* l'invio incerto è trattato come
|
||||
un rifiuto ([TX-04]); un commit fallito dopo un invio accettato solleva un
|
||||
errore 500 lasciando le righe `building`.
|
||||
- **[TX-21]** **Invio a tutti i server.** Dopo che il server attivo ha
|
||||
accettato una transazione ([TX-04]) — scommessa, prelievo, pagamento o
|
||||
sostituzione RBF — la stessa transazione viene inviata anche a ogni altro
|
||||
server configurato. È un tentativo in più, non una condizione: un errore di
|
||||
questi invii viene solo registrato nei log, non cambia lo stato della riga
|
||||
e non ritarda la risposta all'utente.
|
||||
*Codice:* `app/electrum/listener.py:ElectrumListener`, `app/bets/service.py:place_bet`, `app/withdrawals/service.py:request_withdrawal`, `app/rounds/scheduler.py:RoundScheduler._trigger_payout`, `app/tx/broadcast.py:bump_fee` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-76) · *Oggi:* ogni transazione viene inviata
|
||||
solo al server attivo.
|
||||
- **[TX-05]** Se l'invio di un pagamento non è accettato — rifiuto esplicito
|
||||
o esito incerto — 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]). Un rifiuto
|
||||
"già nota" ([TX-04]) vale come invio accettato: la riga passa a `pending` e
|
||||
si scrive `payout_sent`.
|
||||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
|
||||
*Test:* `tests/unit/test_scheduler.py`
|
||||
*Stato:* da implementare (B-76) · *Oggi:* anche il "già nota" lascia la
|
||||
riga `building` con `payout_failed`, finché il riconciliatore non la
|
||||
promuove.
|
||||
|
||||
## Conferma
|
||||
|
||||
@@ -79,13 +164,33 @@ stateDiagram-v2
|
||||
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.
|
||||
l'indirizzo dell'utente, o l'indirizzo del montepremi del round per un
|
||||
pagamento — e cerca **ogni** txid della riga ([TX-19]); un txid che vi
|
||||
compare con altezza maggiore di 0 è il candidato alla conferma, che viene
|
||||
accettata solo alle condizioni di [TX-22]. 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
|
||||
*Stato:* da implementare (B-77, B-80) · *Oggi:* cerca solo `current_txid`,
|
||||
nella cronologia dell'unico indirizzo del montepremi condiviso da tutti i
|
||||
round per i pagamenti; un'altezza maggiore di 0 riportata dal solo server
|
||||
attivo basta a confermare ([TX-22]).
|
||||
- **[TX-22]** **Conferma verificata.** Un candidato ([TX-06]) è confermato
|
||||
solo quando il quorum dei server
|
||||
([connessione-electrum.md](connessione-electrum.md) (B-84)) restituisce per
|
||||
quel txid una prova merkle valida (`blockchain.transaction.get_merkle`)
|
||||
contro l'header dell'altezza indicata. L'header è quello già validato dal
|
||||
listener ([connessione-electrum.md](connessione-electrum.md) (B-74)); se
|
||||
il listener non lo tiene più, è quello su cui il quorum concorda. Senza
|
||||
quorum, o con una prova non valida, la riga resta `pending` e si riprova al
|
||||
giro successivo.
|
||||
*Codice:* `app/tx/confirmation.py:poll_once`, `app/electrum/listener.py:ElectrumListener._corroborate_majority` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-83) · *Oggi:* basta la parola del server
|
||||
attivo: un server ostile può dichiarare confermato un pagamento mai
|
||||
trasmesso.
|
||||
- **[TX-07]** Alla 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:
|
||||
|
||||
@@ -119,7 +224,7 @@ sostituibilità fin dal primo invio.
|
||||
`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.
|
||||
su una riga 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
|
||||
@@ -131,35 +236,86 @@ sostituibilità fin dal primo invio.
|
||||
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.
|
||||
- **[TX-11]** **Chi paga l'accelerazione.** La sostituzione spende le stesse
|
||||
monete e riduce del solo aumento un'unica uscita, quella che torna alla
|
||||
piattaforma o al mittente: il **resto dell'utente** per scommesse e
|
||||
prelievi, l'**uscita di riserva** verso l'indirizzo di riserva del
|
||||
montepremi (`m/84'/746'/0'/1/0`) per i pagamenti
|
||||
([ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#4--pagamento)
|
||||
(B-79)). Le uscite verso la controparte (montepremi, indirizzo esterno,
|
||||
vincitore, indirizzo commissioni) non vengono mai toccate. Se dopo la
|
||||
riduzione quell'uscita scenderebbe sotto `DUST_LIMIT_SATS` (294 sat),
|
||||
l'uscita viene **eliminata** e tutto il suo valore va in commissione: la
|
||||
sostituzione non ha più nulla da ridurre ed è quindi **l'ultima**, e la
|
||||
riga non viene più accelerata. Se l'uscita non esiste, o se nemmeno la sua
|
||||
eliminazione raggiunge l'aumento minimo di [TX-10], l'accelerazione non è
|
||||
possibile ([TX-24]). Una transazione che non si può accelerare resta
|
||||
`pending` finché conferma o finché il riconciliatore ha la prova che non è
|
||||
partita ([TX-17]): finché almeno un server la tiene in mempool non viene
|
||||
mai abbandonata.
|
||||
*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`).
|
||||
*Stato:* da implementare (B-79, B-87) · *Oggi:* per il pagamento si cerca
|
||||
un resto verso l'indirizzo del montepremi, che esiste solo se le monete
|
||||
scelte superano vincitore più commissioni di almeno 294 sat: quando il
|
||||
montepremi contiene esattamente le scommesse del round il pagamento le
|
||||
spende tutte per esattamente `pool_amount_sats`, non ha resto e non è
|
||||
accelerabile; per scommesse e prelievi basta che il resto superi
|
||||
l'aumento, così un resto di 294 sat diventa 153 sat, sotto la soglia di
|
||||
dust, e la rete rifiuta la sostituzione a ogni giro.
|
||||
- **[TX-12]** **Prima si scrive la sostituzione, poi si invia.** La
|
||||
sostituzione firmata viene registrata come candidata in
|
||||
`pending_transaction_txids` (txid e transazione completa, [TX-19]) e
|
||||
committata **prima** dell'invio. Dopo l'invio (accettato o incerto) la riga
|
||||
viene aggiornata con un aggiornamento condizionato
|
||||
(`UPDATE … WHERE id = … AND status = 'pending' AND current_txid = <txid
|
||||
sostituito>`): nuovo txid (`current_txid`), nuova transazione
|
||||
(`raw_tx_hex`), txid sostituito (`replaced_by_txid`), tariffa
|
||||
effettivamente pagata, numero di tentativi e `last_broadcast_at`; nella
|
||||
stessa transazione il nuovo txid viene propagato ovunque sia registrato:
|
||||
monete spese (`spent_txid`), partecipante (`bet_txid`), prelievo (`txid`),
|
||||
round (`payout_txid`). Se la sostituzione è rifiutata esplicitamente la
|
||||
riga non cambia ([TX-24]).
|
||||
*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.
|
||||
*Stato:* da implementare (B-77) · *Oggi:* la sostituzione viene inviata
|
||||
senza essere registrata, e la riga viene aggiornata solo dopo l'invio, senza
|
||||
condizioni: un crash o un `database is locked` in mezzo lascia in rete una
|
||||
transazione che il database non conosce.
|
||||
- **[TX-13]** L'RBF non tocca una riga che è cambiata sotto di lui. Prima di
|
||||
costruire la sostituzione, se la riga non esiste più o non è più
|
||||
`pending` (ad esempio è appena stata confermata), non si fa nulla. Dopo
|
||||
l'invio, se l'aggiornamento condizionato di [TX-12] non trova la riga
|
||||
(stato o `current_txid` cambiati nel frattempo: confermata, abbandonata o
|
||||
già sostituita), è un **conflitto**: la riga non viene sovrascritta, la
|
||||
candidata resta registrata — la conferma e la riconciliazione la cercano
|
||||
comunque ([TX-19]) — e il conflitto viene scritto nei log.
|
||||
*Codice:* `app/tx/broadcast.py:bump_fee` ·
|
||||
*Test:* `tests/unit/test_broadcast.py`
|
||||
*Stato:* da implementare (B-77) · *Oggi:* il controllo avviene solo prima
|
||||
della costruzione; dopo l'invio la riga viene aggiornata senza ricontrollare
|
||||
né lo stato né `current_txid`, anche se nel frattempo è stata confermata o
|
||||
abbandonata.
|
||||
- **[TX-24]** Un'accelerazione impossibile ([TX-11], o la riga già a
|
||||
`MAX_FEE_RATE_SAT_VB`) o una sostituzione rifiutata esplicitamente dalla
|
||||
rete scrivono un evento `rbf_bump_failed` ([audit-log.md](audit-log.md)
|
||||
(B-87)) con la riga, il txid corrente e il motivo; la riga resta `pending`
|
||||
e il tentativo si ripete al giro successivo in cui è dovuto ([TX-09]).
|
||||
*Codice:* `app/tx/broadcast.py:RbfBumper._tick` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-87) · *Oggi:* l'errore finisce solo nei log
|
||||
dell'applicazione, invisibile da `/admin`.
|
||||
|
||||
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.
|
||||
Il resto minimo di scommesse e prelievi è di 294 sat
|
||||
([BET-14](scommesse-e-prelievi.md#cosa-succede),
|
||||
[WDR-09](scommesse-e-prelievi.md#prelievo)), ma non basta a una riduzione:
|
||||
una scommessa con una moneta in ingresso e due uscite misura 141 vB, quindi
|
||||
l'aumento minimo a 1 sat/vB è di 141 sat e lascerebbe un resto di 153 sat,
|
||||
sotto la soglia di dust. Con un resto minimo la prima accelerazione elimina il
|
||||
resto ([TX-11]) ed è anche l'ultima; un resto più grande permette più
|
||||
accelerazioni prima di arrivare lì. Il pagamento del round, invece, non ha
|
||||
resto quando il montepremi contiene esattamente le scommesse del round: la
|
||||
riserva di [TX-11] serve proprio a dargli un'uscita da ridurre.
|
||||
|
||||
## Riconciliazione
|
||||
|
||||
@@ -168,34 +324,102 @@ montepremi di almeno 294 sat: senza resto non è accelerabile.
|
||||
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.
|
||||
tentativi. Il periodo di tolleranza stabilisce solo da quando la riga viene
|
||||
esaminata: l'abbandono richiede comunque una prova ([TX-17]).
|
||||
*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` ·
|
||||
- **[TX-15]** Il riconciliatore chiede a ogni server del quorum
|
||||
([connessione-electrum.md](connessione-electrum.md) (B-84)) la cronologia
|
||||
(`blockchain.scripthash.get_history`) dell'indirizzo che spende la riga, e
|
||||
cerca **ogni** txid della riga ([TX-19]), in mempool o in un blocco. La
|
||||
transazione è **presente** se almeno un server conosce almeno uno dei suoi
|
||||
txid ([TX-16]); è **assente** solo se nessun server del quorum ne conosce
|
||||
alcuno, e anche in quel caso l'assenza da sola non basta ad abbandonarla
|
||||
([TX-17]). Un **errore di rete** non porta a nulla: la riga resta com'è
|
||||
fino al giro successivo.
|
||||
*Codice:* `app/tx/reconcile.py:reconcile_once`, `app/electrum/listener.py:ElectrumListener._corroborate_majority` ·
|
||||
*Test:* `tests/unit/test_reconcile.py`
|
||||
*Stato:* da implementare (B-78) · *Oggi:* si interroga solo il server
|
||||
attivo e solo per `current_txid`, e un txid assente dalla sua cronologia è
|
||||
trattato come "sconosciuto alla rete": dopo un riavvio su un server diverso
|
||||
una riga `building` viene abbandonata dopo 120s anche se la transazione è
|
||||
nella mempool degli altri nodi (che la tengono fino a 336 ore con le
|
||||
impostazioni predefinite di Bitcoin Core, contro le 6 ore di tolleranza).
|
||||
- **[TX-26]** Prima di scrivere un esito, il riconciliatore rilegge la riga
|
||||
nella propria transazione del database ([TX-28]) e non fa nulla se il suo
|
||||
stato **o il suo `current_txid`** non sono più quelli che aveva quando ha
|
||||
interrogato la rete (una conferma o un RBF avvenuti nel frattempo).
|
||||
*Codice:* `app/tx/reconcile.py:reconcile_once` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-78) · *Oggi:* ricontrolla solo lo stato, quindi
|
||||
può abbandonare una riga appena sostituita dall'RBF sulla base del txid
|
||||
precedente.
|
||||
- **[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.
|
||||
evento `pending_tx_recovered` e l'evento che l'invio riuscito avrebbe
|
||||
scritto: `bet_placed` per una scommessa, `withdrawal_sent` per un
|
||||
prelievo, `payout_sent` per un pagamento. Se il txid trovato non è quello
|
||||
corrente vale [TX-19]. 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`
|
||||
*Stato:* da implementare (B-96) · *Oggi:* si scrive solo
|
||||
`pending_tx_recovered`: una scommessa o un pagamento recuperati non hanno
|
||||
mai `bet_placed` o `payout_sent` (e un prelievo recuperato non ha
|
||||
`withdrawal_sent`).
|
||||
- **[TX-17]** **Abbandono solo con prova.** Una riga viene abbandonata solo
|
||||
se vale una di queste due prove:
|
||||
1. un suo ingresso risulta **speso in un blocco** da una transazione che
|
||||
non è nessuna delle sue versioni ([TX-19]), confermato dal quorum
|
||||
([connessione-electrum.md](connessione-electrum.md) (B-84));
|
||||
2. nessun server del quorum conosce alcuno dei suoi txid ([TX-15]) **e**
|
||||
il reinvio della sua versione più recente (`raw_tx_hex`) a tutti i server
|
||||
viene rifiutato esplicitamente perché gli ingressi mancano o sono già
|
||||
spesi (`missing-inputs`, `bad-txns-inputs-missingorspent`).
|
||||
|
||||
È questo che rende finita l'attesa del round in `closing`: una scommessa che
|
||||
non confermerà mai viene prima o poi abbandonata e rimossa.
|
||||
Un rifiuto del reinvio per commissione insufficiente non è una prova: una
|
||||
riga `pending` resta com'è e la accelera l'RBF ([TX-09]); una riga
|
||||
`building` passa a `pending` come in [TX-16], così che l'RBF la possa
|
||||
accelerare. Un reinvio accettato da almeno un server significa che la
|
||||
transazione è viva: vale [TX-16]. Con la prova, la riga passa a `failed`
|
||||
con il motivo in `failure_reason`; 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`, `app/tx/reconcile.py:reconcile_once` ·
|
||||
*Test:* `tests/unit/test_reconcile.py`
|
||||
*Stato:* da implementare (B-78) · *Oggi:* basta che la cronologia del
|
||||
server attivo non contenga `current_txid` (motivo `not found on chain`),
|
||||
senza reinvio e senza guardare gli ingressi.
|
||||
- **[TX-23]** **Le righe `failed` restano sorvegliate** per 14 giorni dal
|
||||
passaggio a `failed` (`failed_at`, [modello-dati.md](modello-dati.md)
|
||||
(B-78)): a ogni giro il riconciliatore cerca i loro txid come in [TX-15].
|
||||
Se uno di essi risulta confermato ([TX-22]) — una transazione data per
|
||||
morta che invece è arrivata in un blocco — si scrive una sola volta
|
||||
`pending_tx_resurrected` ([audit-log.md](audit-log.md) (B-78)) e la
|
||||
lotteria viene messa in pausa (`paused_reason = 'tx_resurrected'`) perché
|
||||
l'operatore rimetta in ordine partecipante, prelievo o pagamento; il
|
||||
riconciliatore non corregge da solo le righe collegate.
|
||||
*Codice:* `app/tx/reconcile.py:reconcile_once` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-78) · *Oggi:* una riga `failed` non viene più
|
||||
guardata: se la transazione conferma dopo l'abbandono, nessuno se ne
|
||||
accorge.
|
||||
- **[TX-27]** Il riconciliatore invia una notifica SSE solo per le righe di
|
||||
cui ha cambiato qualcosa (promozione, abbandono, riallineamento del txid),
|
||||
non per ogni riga esaminata.
|
||||
*Codice:* `app/tx/reconcile.py:reconcile_once` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-96) · *Oggi:* pubblica una notifica per ogni
|
||||
riga che ha interrogato, anche quando non cambia nulla.
|
||||
- **[TX-25]** Una scommessa in volo esce dall'attesa del round in `closing`
|
||||
([ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#2--chiusura)) in
|
||||
due soli modi: confermata ([TX-07]) o abbandonata con prova ([TX-17]). Non
|
||||
esiste un tempo massimo: finché almeno un server tiene la transazione in
|
||||
mempool, il round resta in `closing`.
|
||||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`, `app/tx/reconcile.py:reconcile_once` ·
|
||||
*Test:* `tests/unit/test_scheduler.py`
|
||||
|
||||
## Pagamenti del round: riprovare senza pagare due volte
|
||||
|
||||
@@ -211,12 +435,17 @@ 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.
|
||||
- **[TX-18]** Un pagamento abbandonato ([TX-17]) non libera monete utente
|
||||
(quelle del montepremi non sono registrate): azzera `payout_txid`,
|
||||
`winner_amount_sats` e `fee_amount_sats` del round, che resta in
|
||||
`paying_out` senza transazione né importi di un pagamento che non esiste, 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`
|
||||
*Test:* — (`tests/unit/test_scheduler.py` verifica i nuovi tentativi di un
|
||||
round in `paying_out`, non la sequenza abbandono → ricostruzione)
|
||||
*Stato:* da implementare (B-96) · *Oggi:* azzera solo `payout_txid`;
|
||||
`winner_amount_sats` e `fee_amount_sats` restano quelli del pagamento
|
||||
abbandonato.
|
||||
|
||||
## Dove guardare
|
||||
|
||||
@@ -226,5 +455,7 @@ Nel pannello `/admin` (vedi [guida-admin.md](guida-admin.md) e
|
||||
- **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;
|
||||
`pending_tx_abandoned`, `draw_stalled` e tutti gli altri eventi; con le
|
||||
correzioni in corso anche `rbf_bump_failed` ([TX-24]) e
|
||||
`pending_tx_resurrected` ([TX-23]);
|
||||
- **Round** — stato di ogni round, vincitore e txid del pagamento.
|
||||
Reference in new issue
Block a user