Abandon a transaction only on proof, and keep watching failed rows (B-78, TX-15, TX-17, TX-23, TX-26, ELC-28, DAT-33, DAT-36, DAT-69, DAT-72, AUD-11, AUD-12, AUD-31, AUD-39, API-32)

reconcile_once abandoned a row when the *active* server's history lacked its txid:
after 120s for `building` (which a restart onto a different server makes likely),
after 6h for `pending`, and all at once after a forward clock jump. It re-checked the
status but not the txid, so it raced the bumper, and a `failed` row was never looked at
again.

- The reconciler asks every server (ElectrumListener.get_histories, active + others) for
  the history of the row's address and looks for every txid of the row. Present on any
  server -> promoted (adopting the version found). Absent is only "no server of the
  quorum knows it" and needs the active server plus the quorum minimum of the others to
  have answered; even then nothing is released without proof:
  (a) an input spent in a block by a transaction that is none of the row's versions,
      agreed by a strict majority of a quorum of the other servers (confirmed_spender), or
  (b) a rebroadcast of the latest raw tx to every server (rebroadcast_everywhere)
      refused by all of them, explicitly, for missing/spent inputs.
  Accepted or "already known" by any server means alive; a fee refusal is not proof
  (`building` -> `pending` for the bumper, `pending` untouched); too few answers or
  anything else leaves the row alone. failure_reason names the proof.
- The write re-reads status *and* current_txid under begin_immediate (TX-26).
- pending_transactions.failed_at (set by _abandon and _release_failed_withdrawal) starts
  a 14-day watch: a failed row that a majority of the other servers (at least the quorum
  minimum) list in a block becomes `confirmed`, writes pending_tx_resurrected once and
  pauses the lottery with paused_reason `resurrected_tx`; linked rows are not corrected.
  The confirmation is by quorum of histories for now; merkle proofs come with B-83.
- round_config.paused_reason (migration b7d2e41c9a05, with the failed_at one): `operator`
  from POST /admin/pause (which accepts an optional `note` and never overwrites an
  automatic reason), cleared by resume, which logs the reason it lifted; exposed on
  /admin/config and GET /rounds/current. rounds/pause.py:pause_automatically is the
  system's way in.
- PendingTransactionReconciler takes the listener as `network`; with none it can promote
  but never abandon.

Tests changed because the spec changed: the three reconciler tests that expect an
abandonment (and the one in test_tx_versions) now supply a network that proves the
transaction is gone.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
davideandClaude Sonnet 5.5 committed 2026-10-14 15:07:09 +02:00
1 parent f936d6660c
commit a4b160e240
29 files changed
+1280 -201

No files matched your search

+16 -25
View File
@@ -162,7 +162,7 @@ erDiagram
string replaced_by_txid
int attempt_count
string failure_reason
datetime failed_at "da implementare"
datetime failed_at
datetime updated_at
}
pending_transaction_txids {
@@ -391,9 +391,8 @@ del database sono tutti uguali, perché arrivano tutti dallo stesso percorso
*Codice:* le funzioni in tabella ·
*Test:* `tests/unit/test_deposits.py`, `tests/unit/test_bets.py`,
`tests/unit/test_withdrawals.py`, `tests/unit/test_reconcile.py`
*Stato:* da implementare (B-78, B-83) · *Oggi:* l'abbandono avviene sul
silenzio del solo server attivo, il reintegro sulla parola del solo server
attivo.
*Stato:* da implementare (B-83) · *Oggi:* il reintegro avviene sulla parola
del solo server attivo.
- **[DAT-13]** Il riconciliatore libera un input solo se il suo `spent_txid` è
uno dei txid della riga che sta abbandonando (`current_txid` o una sua
@@ -798,7 +797,7 @@ senza riavviare (vedi [limiti-noti.md](limiti-noti.md)).
| `draw_confirmations` | Integer | `3` | 1 – 20 | Conferme richieste sul blocco di estrazione ([DAT-62]) — *da implementare (B-73)* | Dal round **successivo**, copiato all'apertura ([DAT-61]) |
| `max_round_pool_sats` | BigInteger | `0` (tetto disattivato) | `0`, oppure `≥ bet_amount_sats` e `≤ 4 000 000 000 000 000` (400 × 100 000 PLM) | Tetto alla somma delle scommesse di un round ([DAT-27], [DAT-62]) — *da implementare (B-95)* | Subito, anche per il round in corso: vale per le scommesse successive |
| `paused` | Boolean | `False` | non modificabile da `PUT /admin/config` | Pausa della lotteria | Subito per l'apertura del round successivo; il round in corso non è toccato |
| `paused_reason` | String(16) | `NULL` | non modificabile da `PUT /admin/config` | Perché la lotteria è in pausa ([DAT-69]) — *da implementare (B-78, B-82, B-85)* | Insieme a `paused` |
| `paused_reason` | String(16) | `NULL` | non modificabile da `PUT /admin/config` | Perché la lotteria è in pausa ([DAT-69]) | Insieme a `paused` |
| `updated_at` | DateTime | `utcnow`, aggiornato a ogni modifica (`onupdate`) | — | Ultima modifica della riga | ORM |
- **[DAT-28]** La tabella contiene al più una riga, creata alla prima lettura
@@ -828,8 +827,8 @@ senza riavviare (vedi [limiti-noti.md](limiti-noti.md)).
[DAT-69], che scrivono la propria voce di audit.
*Codice:* `app/api/routes/admin.py:pause_lottery` ·
`app/api/routes/admin.py:resume_lottery` · *Test:* `tests/unit/test_admin.py`
*Stato:* da implementare (B-78, B-82, B-85) · *Oggi:* `paused_reason` non
esiste e nessun codice mette in pausa la lotteria da solo.
*Stato:* da implementare (B-82, B-85) · *Oggi:* l'unica pausa automatica è
`resurrected_tx` (B-78); quelle di B-82 e B-85 non esistono ancora.
- **[DAT-62]** `deposit_confirmations` (predefinito 6) è il numero di
conferme dopo cui un output che paga un utente si accredita ([DAT-10]);
@@ -868,9 +867,10 @@ senza riavviare (vedi [limiti-noti.md](limiti-noti.md)).
`app/api/routes/admin.py:resume_lottery` ·
`app/electrum/listener.py:ElectrumListener._apply_header` ·
`app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
`app/tx/reconcile.py:reconcile_once` · *Test:* —
*Stato:* da implementare (B-78, B-82, B-85, B-90) · *Oggi:* esiste solo
`paused`, scritto solo dai due endpoint admin.
`app/tx/reconcile.py:reconcile_once` · *Test:* `tests/unit/test_pause_reason.py`
*Stato:* da implementare (B-82, B-85, B-90) · *Oggi:* si scrivono solo
`operator` (`POST /admin/pause`) e `resurrected_tx` (il riconciliatore);
`reorg`, `payout_blocked` e `START_PAUSED` non hanno ancora chi li scrive.
- **[DAT-31]** Con `fee_address` vuoto (o di soli spazi) non si apre nessun round
(B-66). Una volta impostato, l'API non permette di svuotarlo di nuovo: la
@@ -902,7 +902,7 @@ riconciliatore (vedi
| `replaced_by_txid` | String(64) | sì | `NULL` | Il txid **sostituito** dall'ultimo bump (nonostante il nome, punta all'indietro). La cronologia completa è in `pending_transaction_txids` ([DAT-70]) e questa colonna resta solo informativa | `bump_fee` |
| `attempt_count` | Integer | no | `1` | 1 + numero di bump riusciti | `bump_fee` |
| `failure_reason` | String(128) | sì | `NULL` | Perché la transazione è fallita; solo con `status = failed` | `_abandon`; `_release_failed_withdrawal` |
| `failed_at` | DateTime | sì | `NULL` | Istante del passaggio a `failed`; da lì si contano i 14 giorni di sorveglianza ([DAT-72]) — *da implementare (B-78)* | `_abandon`; `_release_failed_withdrawal` |
| `failed_at` | DateTime | sì | `NULL` | Istante del passaggio a `failed`; da lì si contano i 14 giorni di sorveglianza ([DAT-72]) | `_abandon`; `_release_failed_withdrawal` |
| `updated_at` | DateTime | no | `utcnow`, `onupdate` | Ultima modifica | ORM |
Le funzioni citate sono `app/bets/service.py:place_bet`,
@@ -967,11 +967,8 @@ Le funzioni citate sono `app/bets/service.py:place_bet`,
guarda le righe `pending`, più le `failed` entro 14 giorni.
*Codice:* le funzioni in tabella ·
*Test:* `tests/unit/test_confirmation.py`, `tests/unit/test_reconcile.py`,
`tests/unit/test_scheduler.py`, `tests/unit/test_bets.py`,
`tests/unit/test_withdrawals.py`
*Stato:* da implementare (B-78) · *Oggi:* l'abbandono avviene quando la
cronologia del solo server attivo non contiene `current_txid`; il poller
guarda solo le righe `pending` e una riga `failed` non viene più guardata.
`tests/unit/test_reconcile_proof.py`, `tests/unit/test_scheduler.py`,
`tests/unit/test_bets.py`, `tests/unit/test_withdrawals.py`
- **[DAT-34]** Dopo la creazione, `current_txid`, `raw_tx_hex`,
`fee_rate_sat_vb`, `replaced_by_txid`, `attempt_count` e `last_broadcast_at`
@@ -1012,9 +1009,7 @@ Le funzioni citate sono `app/bets/service.py:place_bet`,
conserva `failure_reason` e `failed_at`.
*Codice:* `app/tx/reconcile.py:_abandon` ·
`app/withdrawals/service.py:_release_failed_withdrawal` ·
*Test:* `tests/unit/test_reconcile.py`
*Stato:* da implementare (B-78) · *Oggi:* il riconciliatore scrive sempre
`"not found on chain"` e `failed_at` non esiste.
*Test:* `tests/unit/test_reconcile.py`, `tests/unit/test_reconcile_proof.py`
- **[DAT-72]** Una riga `failed` con `failed_at` negli ultimi 14 giorni resta
tra quelle che il riconciliatore controlla a ogni giro (120 s,
@@ -1027,9 +1022,7 @@ Le funzioni citate sono `app/bets/service.py:place_bet`,
ricostruite automaticamente: le riallinea l'operatore
([operativita.md](operativita.md) B-78).
*Codice:* `app/tx/reconcile.py:reconcile_once` · `app/tx/reconcile.py:_abandon` ·
*Test:* —
*Stato:* da implementare (B-78) · *Oggi:* una riga `failed` non viene mai
più letta.
*Test:* `tests/unit/test_reconcile_proof.py`
- **[DAT-37]** Per le righe `bet` e `withdrawal` in `building`/`pending`,
`raw_tx_hex` è la fonte del saldo "in attesa" (gli output che tornano
@@ -1138,9 +1131,7 @@ dall'utente.
Se la riga `pending_transactions` di un prelievo `failed` risorge
([DAT-72]), il prelievo resta `failed` finché l'operatore non lo riallinea.
*Codice:* le funzioni in tabella ·
*Test:* `tests/unit/test_withdrawals.py`, `tests/unit/test_reconcile.py`
*Stato:* da implementare (B-78) · *Oggi:* l'abbandono non richiede una
prova.
*Test:* `tests/unit/test_withdrawals.py`, `tests/unit/test_reconcile.py`, `tests/unit/test_reconcile_proof.py`
- **[DAT-40]** `amount_requested_sats` è ciò che l'utente ha chiesto;
`amount_sent_sats` è l'output effettivo verso il destinatario: l'importo