A4: round lifecycle, commit-reveal draw and simulated chain (RND-41..44, ADR-57, ADR-59)

lifecycle.tick runs the round from open to closed one write-locked step at a
time, resumable from the database (an interrupted draw gives the same
winner). Draw primitives move to plm_engine.draw and are shared with the old
module. SimulatedChain and settle() stand in for blocks and confirmations;
the worker runs both every tick and opens the first round. The round secret
is stored encrypted and revealed with the winner; the proof exposes no
usernames. Mutation checks confirmed the wait for in-flight bets and the
txid ordering are caught by the tests.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
davideandClaude Sonnet 5.5 committed 2026-11-16 13:43:09 +01:00
1 parent eded058dbb
commit 1d4b53d778
17 files changed
+978 -67

No files matched your search

+46
View File
@@ -585,3 +585,49 @@ Due livelli indipendenti:
- ~~[RND-32]~~ Assorbito da [RND-36]: nel comportamento atteso un round in
`drawing` riprende da solo dopo un riavvio o un errore (B-81).
## Il ciclo nel sito Django (migrazione in corso)
Il worker del nuovo sito ([ADR-55](adr/ADR-55-sqlite-wal-web-worker-processi-separati.md)) porta in `apps/lottery/lifecycle.py`
la stessa macchina a stati e le stesse regole di sopra, sul modello Django ([DAT-78]); finché il vecchio scheduler non
è rimosso (roadmap D1) il resto del documento resta lo stato storico. In particolare valgono, con questo codice:
apertura con parametri copiati ([RND-05], [DAT-61]), un solo round attivo ([RND-02]), scadenza propria del round
([RND-11], [ADR-23](adr/ADR-23-limite-scommettere-scadenza-round-stesso-suo.md)), attesa delle puntate in volo ([RND-13]),
elenco ordinato per txid con impronta e altezza fissati in una transazione ([RND-14], [RND-19], [DAT-65]), attesa delle
conferme del blocco e blocco mai sostituito ([RND-15], [RND-16]), vincitore ricalcolabile e rivelazione del segreto con
il vincitore ([RND-17], [RND-18]), ripresa dopo un errore con lo stesso vincitore ([RND-36]), pagamento 70/30 ([RND-21])
e pausa che ferma solo il round successivo ([ADR-57](adr/ADR-57-due-pause-distinte-dopo-round-e-incidente.md)).
*Codice:* `apps/lottery/lifecycle.py` · *Test:* `tests/django/test_lifecycle.py`. Aggiunte e differenze:
- **[RND-41]** **Un passo alla volta, senza stato in memoria.** `lifecycle.tick` esegue i passi che il round può fare
adesso (al massimo 8 per chiamata) e si ferma; ogni passo è una transazione con blocco di scrittura e la sua riga di
audit ([ARC-77]), e rilegge il round dentro la transazione. Un passo che fallisce lascia il round dov'era; il tick
successivo lo riprende da quello che il database contiene. Un tick che non cambia nulla non scrive nulla.
*Stato:* implementato (A4) ·
*Codice:* `apps/lottery/lifecycle.py:tick` ·
*Test:* `tests/django/test_lifecycle.py::test_an_interrupted_draw_gives_the_same_winner`, `test_a_tick_that_changes_nothing_writes_nothing`
- **[RND-42]** **Catena e conferme simulate.** Con `LEDGER_BACKEND=simulated` la catena esiste solo nel tempo: il blocco `h`
è prodotto `h` intervalli (`SIMULATED_BLOCK_SECONDS`, 20 s) dopo un'epoca fissa e il suo hash è una funzione di `h`;
non si memorizza nulla, quindi un riavvio non cambia niente. Una puntata, un deposito o un pagamento simulati si
confermano `SIMULATED_CONFIRM_SECONDS` (5 s) dopo l'invio. Il blocco di estrazione resta quello dell'altezza
fissata, mai un altro; un'altezza futura non ha hash ([RND-16]). Il worker esegue `settle` e `tick` a ogni giro.
*Stato:* implementato (A4); la catena reale con la Fase B ·
*Codice:* `apps/lottery/simulation.py`, `apps/lottery/management/commands/run_worker.py` ·
*Test:* `tests/django/test_lifecycle.py::test_a_whole_round_on_the_simulated_chain`, `test_settling_confirms_only_what_has_waited_long_enough`
- **[RND-43]** **Il segreto del round è cifrato a riposo.** Alla pubblicazione dell'impegno ([RND-34]) il segreto si
salva cifrato (Fernet, chiave derivata da `DJANGO_SECRET_KEY`); la colonna in chiaro resta vuota fino alla
rivelazione, quindi una copia del solo database non dice chi vincerà. Con un'altra chiave il segreto non si decifra.
*Stato:* implementato (A4); la chiave dedicata torna con la Fase B ·
*Codice:* `apps/lottery/seedbox.py` ·
*Test:* `tests/django/test_lifecycle.py::test_the_round_secret_needs_the_right_key`
- **[RND-44]** **La prova non espone gli account.** L'elenco di estrazione e la sua impronta contengono, per ogni
partecipante, il txid e l'uscita della sua scommessa e un indirizzo pseudonimo ([ADR-59](adr/ADR-59-motore-plm-pacchetto-senza-framework-ledger-simulato.md)):
nel pilota derivato dall'id dell'account senza rivelarlo, in Fase B l'indirizzo HD. Nessun username compare.
*Stato:* implementato (A4) ·
*Codice:* `apps/lottery/addresses.py`, `apps/lottery/simulation.py:simulated_address` ·
*Test:* `tests/django/test_lifecycle.py::test_the_proof_does_not_expose_usernames`
- **Differenze rispetto al vecchio scheduler.** `closed_at` è l'istante in cui il round si chiude del tutto (pagamento
confermato, o chiusura senza partecipanti) e da lì parte la pausa fra round; non si scrive all'ingresso in `closing`.
Gli eventi di stallo dell'estrazione (`draw_stalled`, `draw_baseline_tip_unknown`, `draw_header_corroboration_failed`) e
la verifica del montepremi sulla catena riguardano la catena reale e arrivano con la Fase B (B8). Senza `fee_address`
un round non si apre solo con il ledger reale ([ADR-29](adr/ADR-29-senza-fee-address-apre-nessun-round.md)).