B7: confirmations with merkle proof, adoption of the confirmed version, RBF bumper and reconciler (TX-30..33, DAT-85)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
davideandClaude Sonnet 5.5 committed 2026-11-16 16:29:08 +01:00
1 parent feff993584
commit fa57d2e5ab
20 files changed
+1165 -20

No files matched your search

+2 -2
View File
@@ -4,7 +4,7 @@
## Project status (old stack)
All 10 stages of the original build order are code-complete and unit-tested — 1288 tests, the old stack's under `tests/unit/` and the Django ones under `tests/django/` (`tests/integration/` needs the local regtest node and skips itself without it). Beyond them: Docker + Caddy deployment, admin dashboard (`/admin`), static test UI (`/`), pending-inclusive balance display, an SSE push channel layered over the original polling, self-service password change + admin password reset, and the reconciliation/corroboration machinery below.
All 10 stages of the original build order are code-complete and unit-tested — 1336 tests, the old stack's under `tests/unit/` and the Django ones under `tests/django/` (`tests/integration/` needs the local regtest node and skips itself without it). Beyond them: Docker + Caddy deployment, admin dashboard (`/admin`), static test UI (`/`), pending-inclusive balance display, an SSE push channel layered over the original polling, self-service password change + admin password reset, and the reconciliation/corroboration machinery below.
Verified on mainnet with real money: registration + address derivation, deposit crediting (at the time, 1-conf; deposits now need `deposit_confirmations`), a real 10 PLM bet (broadcast → confirmed → change credited back), and one full round cycle (close → draw on a real block hash → 70/30 payout with sat math checked against the broadcast tx → confirmation → close → next round auto-opened). **Withdrawal and the RBF bump path have never been exercised against a live broadcast** — unit-tested only.
@@ -30,7 +30,7 @@ PYTHONPATH=. python scripts/decrypt_master_key.py # ops recovery: decrypt+pr
PYTHONPATH=. python scripts/encrypt_master_key.py # ops bootstrap: import an externally-generated xprv (--overwrite to replace)
PYTHONPATH=. python scripts/electrum_smoke_test.py # manual check: connect, handshake, subscribe to headers, print the tip
python -m pytest # all 1288 tests
python -m pytest # all 1336 tests
python -m pytest tests/unit/test_hd.py # one file
python -m pytest tests/unit/test_hd.py::test_derivation_is_deterministic # one test
```
+5 -1
View File
@@ -1500,7 +1500,7 @@ Le tabelle di catena (UTXO, versioni delle transazioni, depositi, indici HD) son
si elimina. Ogni importo è un intero in unità minime ([DAT-01]) e ogni timestamp è in UTC con fuso ([DAT-02]).
*Stato:* implementato (A2) · *Codice:* `apps/lottery/models.py` · *Test:* `tests/django/test_models.py::test_rows_that_carry_money_cannot_be_deleted_with_their_owner`
- **[DAT-77]** **Parametri e pause: `LotteryConfig`.** Una sola riga (`id = 1`, vincolo) con quota (10 PLM),
durata (600 s), pausa fra round (30 s), conferme richieste a un deposito (1–100, default 6, [DAT-62]; si cambia da `/admin/` con audit e vale subito per gli accrediti successivi), conferme del blocco di estrazione (1–20, default 3), commissione di rete in sat/vB (1–5 000, default 1: vale per le transazioni costruite dopo), tetto del
durata (600 s), pausa fra round (30 s), conferme richieste a un deposito (1–100, default 6, [DAT-62]; si cambia da `/admin/` con audit e vale subito per gli accrediti successivi), tempo oltre il quale una transazione lenta si accelera (`rbf_timeout_seconds`, 60–86 400 s, default 900), conferme del blocco di estrazione (1–20, default 3), commissione di rete in sat/vB (1–5 000, default 1: vale per le transazioni costruite dopo), tetto del
montepremi (0 = nessuno) e i tre interruttori di [ADR-57](adr/ADR-57-due-pause-distinte-dopo-round-e-incidente.md):
`pause_after_round`, `new_bets_suspended`, `withdrawals_suspended`. Valori non positivi o fuori intervallo
sono rifiutati dal database. I parametri si **copiano su `Round` all'apertura** ([DAT-61]); la copia la fa il
@@ -1557,4 +1557,8 @@ Le tabelle di catena (UTXO, versioni delle transazioni, depositi, indici HD) son
Un output è un solo deposito e un `credited` ha sempre il movimento e la data di accredito.
*Stato:* tabella implementata (B4); il listener e l'accredito sono B5 · *Codice:* `apps/lottery/models.py:Deposit` ·
*Test:* `tests/django/test_chain_models.py::test_a_credited_deposit_has_its_movement_and_date`, `test_an_output_is_one_deposit`
- **[DAT-85]** **Stato di invio di una transazione.** `ChainTransaction` registra la commissione della versione corrente
(`fee_rate_sat_vb`), l'istante dell'ultimo invio (`last_broadcast_at`, che l'RBF aggiorna mentre `broadcast_at` resta il primo) e il numero di
tentativi (`attempt_count`). Sono ciò che il bumper e il riconciliatore leggono ([TX-32], [TX-33]).
*Stato:* implementato (B7) · *Codice:* `apps/lottery/models.py:ChainTransaction` · *Test:* `tests/django/test_chain_rbf.py`
+39
View File
@@ -420,3 +420,42 @@ Nel pannello `/admin` (vedi [guida-admin.md](guida-admin.md) e
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.
## Transazioni sul sito Django (B7)
Il sito Django riscrive conferma, accelerazione e riconciliazione sull'ORM (`ChainTransaction`, [DAT-83]). Per ora riguardano le
**scommesse**; prelievi e pagamenti (B8, B9) usano gli stessi meccanismi. Restano fuori, e sono B10: il rilevamento delle
riorganizzazioni (finestra degli ultimi header, [ELC-22]…[ELC-24]) e le monete già accreditate che poi spariscono ([DEP-06]…[DEP-08]).
- **[TX-30]** **Conferma verificata, con tutte le versioni.** Il worker legge la cronologia dell'indirizzo che spende ogni transazione
`pending` e cerca **ogni** versione ([DAT-83]); una versione con altezza maggiore di 0 è candidata e si confermerà solo con la prova
merkle di [TX-22] (header dell'altezza con lavoro valido per il profilo, prova data dagli altri server a maggioranza,
[ELC-14]). Senza prova la riga resta `pending` e si riprova. Tre fasi: lettura del database, rete senza database aperto, scrittura.
*Stato:* implementato (B7) · *Codice:* `apps/lottery/confirmation.py`, `apps/lottery/electrum_chain.py:ElectrumChain.observe_confirmations` ·
*Test:* `tests/django/test_chain_confirmation.py`, `tests/integration/test_confirmation_regtest.py`
- **[TX-31]** **Si adotta la versione confermata.** Se a confermarsi è una versione **diversa** da `current_txid` (l'originale mentre
una sostituzione era in volo, o una sostituzione che il processo non aveva fatto in tempo a registrare), la riga adotta quel txid e quella
transazione grezza, e lo propaga a scommessa (`bet_txid`) e monete spese (`spent_txid`). Alla conferma di una scommessa: la
`Participation` diventa `confirmed` con `confirmed_at` ed entra nell'estrazione, il movimento di puntata diventa `confirmed`, le monete
spese risultano spese, e l'audit scrive `tx_confirmed`; tutto nella stessa transazione del database ([TX-26]).
*Stato:* implementato (B7) · *Codice:* `apps/lottery/confirmation.py:apply_confirmations` ·
*Test:* `tests/django/test_chain_confirmation.py::test_a_bet_is_confirmed_and_enters_the_draw`, `test_an_earlier_version_that_confirms_is_adopted`
- **[TX-32]** **Accelerazione (RBF).** Una transazione `pending` il cui ultimo invio è più vecchio di `rbf_timeout_seconds`
(`LotteryConfig`, 900 s) è ricostruita con una commissione di 1 sat/vB in più (mai oltre 5 000, mai meno dell'aumento minimo di BIP125),
spendendo le stesse monete; l'aumento si toglie **solo** dal resto del giocatore, e se ne resterebbe meno di 294 sat il resto sparisce
e quella è l'ultima accelerazione ([TX-10], [TX-11]). La sostituzione firmata è registrata come versione **prima** di trasmetterla
([TX-12]); dopo l'invio (accettato o incerto) la riga passa alla nuova versione con un aggiornamento condizionato a stato `pending` e
`current_txid` invariato, altrimenti è un conflitto e la candidata resta registrata ([TX-13]). Se la rete rifiuta la sostituzione o
l'accelerazione è impossibile, la riga non cambia e si scrive `rbf_bump_failed` una sola volta per coppia (txid, motivo) ([TX-24]).
*Stato:* implementato (B7) · *Codice:* `apps/lottery/rbf.py` ·
*Test:* `tests/django/test_chain_rbf.py`, `tests/integration/test_confirmation_regtest.py`
- **[TX-33]** **Riconciliazione e abbandono solo con prova.** Il worker esamina le transazioni `building` da oltre 120 s e `pending` da oltre
6 ore dal primo invio. Se almeno un server conosce una versione, la riga è viva: `building` passa a `pending` (`pending_tx_recovered`).
Se nessuno la conosce, si **ritrasmette** la versione più recente: accettata = viva; rifiutata con prova **per ingressi mancanti o già spesi**
= abbandono (la transazione è `failed` con il motivo, le monete ancora impegnate da *questa* transazione tornano libere, la scommessa è
respinta, il movimento non conta più, `tx_abandoned`); rifiutata per altro (commissione) o incerta = nessun abbandono. Le righe `failed`
restano sorvegliate 14 giorni: se una loro versione risulta confermata si scrive una sola volta `tx_resurrected` e le nuove puntate
si sospendono per l'operatore ([TX-23]). Non esiste un tempo massimo che abbandoni una transazione che un server tiene in mempool.
*Stato:* implementato (B7); la seconda prova di [TX-17] (ingresso speso in un blocco da un'altra transazione) è B10 ·
*Codice:* `apps/lottery/reconcile.py` · *Test:* `tests/django/test_chain_reconcile.py`