A3: simulated ledger with idempotency (WEB-22, WEB-23, ADR-59, ARC-75..77, DAT-80)

One Ledger interface (deposit, bet, confirm, reject, exclude, payout) with a
simulated implementation chosen by LEDGER_BACKEND, refused on mainnet. Every
operation is a single write-locked transaction with its audit row; the same
request key is the same operation, a key reused for something else is an
error. The server validates round, deadline, the round's own quota, limits and
funds. The balance is derived from the ledger. Tests include six processes
racing on one SQLite file; the idempotency tests were checked to fail when
the replay is removed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
davideandClaude Sonnet 5.5 committed 2026-11-16 13:23:29 +01:00
1 parent 0eba7bcfe6
commit eded058dbb
12 files changed
+924 -4

No files matched your search

+25
View File
@@ -990,3 +990,28 @@ non è rimosso le sezioni precedenti descrivono lo stato storico. Scelte: [ADR-5
solo `DJANGO_DEBUG=true` (sviluppo senza Docker) ne genera uno non sicuro.
*Stato:* implementato (A1) ·
*Codice:* `config/settings.py` · *Test:* `tests/django/test_scaffold.py::test_refuses_to_start_without_a_secret`
- **[ARC-75]** **Il denaro si muove attraverso un'interfaccia sola.** Viste e worker usano `Ledger`
(`deposit`, `place_bet`, `confirm_bet`, `reject_bet`, `exclude_bet`, `pay_winner`, `confirm_payout`);
`LEDGER_BACKEND` sceglie l'implementazione. Nella Fase A è `SimulatedLedger` (fondi che esistono solo nel
database, la conferma è una chiamata); nella Fase B un'implementazione di catena sta dietro gli stessi metodi
senza toccare viste né modelli ([ADR-59](adr/ADR-59-motore-plm-pacchetto-senza-framework-ledger-simulato.md)).
Il ledger simulato **non parte su `mainnet`** (`PLM_NETWORK=mainnet` con `LEDGER_BACKEND=simulated` è un errore
di configurazione), e `PLM_NETWORK` e `LEDGER_BACKEND` sconosciuti sono rifiutati all'avvio.
*Stato:* implementato (A3) ·
*Codice:* `apps/lottery/ledger.py`, `config/settings.py` ·
*Test:* `tests/django/test_ledger.py::test_the_simulated_ledger_cannot_run_on_mainnet`, `test_get_ledger_follows_the_configuration`
- **[ARC-76]** **Idempotenza.** Ogni richiesta di deposito o di puntata porta una chiave (`request_id`):
la stessa chiave dello stesso giocatore è la stessa operazione. Il secondo invio restituisce l'esito del primo
(`replayed`), non addebita né registra nulla e non scrive una seconda riga di audit; una chiave riusata per
un'altra operazione (importo, tipo o round diversi) è l'errore `idempotency_conflict`. La puntata richiede la
chiave (`missing_request_id`). Il vincolo `(user, request_id)` di [DAT-78] è la rete di sicurezza.
*Stato:* implementato (A3) ·
*Codice:* `apps/lottery/ledger.py:SimulatedLedger._replay` ·
*Test:* `tests/django/test_ledger.py::test_the_same_bet_request_is_one_bet`, `test_the_same_deposit_request_is_one_deposit`, `test_concurrent_requests_with_the_same_key_make_one_bet`
- **[ARC-77]** **Un'operazione è una transazione.** Controlli e scritture di ogni operazione del ledger stanno in una
sola transazione che prende subito il blocco di scrittura ([ARC-70]), così nessun'altra richiesta si inserisce fra
la verifica del saldo e l'addebito; la riga di audit si scrive nella stessa transazione ([AUD-47]). Un'operazione
rifiutata non lascia nulla. Una puntata concorrente dello stesso giocatore nello stesso round ne produce una sola.
*Stato:* implementato (A3) ·
*Codice:* `apps/lottery/ledger.py` ·
*Test:* `tests/django/test_ledger.py::test_a_failed_operation_leaves_nothing_behind`, `test_concurrent_requests_with_different_keys_make_one_bet` (sei processi su un solo file SQLite)
+6
View File
@@ -1525,3 +1525,9 @@ Le tabelle di catena (UTXO, versioni delle transazioni, depositi, indici HD) arr
[ADR-56](adr/ADR-56-staff-account-individuali-permessi-mfa-dopo-pilota.md)); username unico senza distinzione fra
maiuscole ([DAT-06]), memorizzato come digitato.
*Stato:* implementato (A1) · *Codice:* `apps/accounts/models.py` · *Test:* `tests/django/test_scaffold.py::test_usernames_are_unique_ignoring_case`
- **[DAT-80]** **Il saldo si deriva dal libro mastro.** `balance_of(user)` somma le righe di `Movement`:
**spendibile** = righe `confirmed` + addebiti `pending` (una puntata o un prelievo in corso riserva subito il suo
importo); **in conferma** = accrediti `pending`; le righe `failed` non contano. Non esiste un saldo memorizzato
accanto alle righe, quindi non può divergere da esse.
*Stato:* implementato (A3) · *Codice:* `apps/lottery/balances.py:balance_of` ·
*Test:* `tests/django/test_ledger.py::test_a_pending_deposit_is_incoming_not_spendable`, `test_a_whole_round_conserves_the_money`
+6
View File
@@ -80,8 +80,14 @@ backend FastAPI (vedi [architettura.md](architettura.md)).
- **[WEB-22]** Prima di inviare una puntata si mostrano round e importo; il
server valida disponibilità, quota, limiti e stato del round. Dopo l'invio
si mostra lo stato effettivo (attesa, conferma, rifiuto o esclusione).
*Stato:* validazione e stati implementati nel ledger (A3: round, scadenza, quota del round, limiti, fondi,
`round_closing`, `already_betting`, `round_full`, `bets_suspended`, `balance_pending_confirmation`, rifiuto ed esclusione);
la schermata con l'A7 ·
*Codice:* `apps/lottery/ledger.py:SimulatedLedger.place_bet` · *Test:* `tests/django/test_ledger.py`
- **[WEB-23]** Un doppio invio della stessa richiesta produce una sola
operazione logica (chiave di idempotenza associata alla richiesta).
*Stato:* implementato nel ledger (A3, [ARC-76]); il modulo di invio con l'A7 ·
*Test:* `tests/django/test_ledger.py::test_the_same_bet_request_is_one_bet`
- **[WEB-24]** Il prelievo mostra, prima della conferma, indirizzo, importo
richiesto, commissione e importo netto previsto. Lo storico distingue lo stato
dell'operazione dal TXID corrente e lo collega all'explorer quando disponibile.