davideandClaude Sonnet 5.5
8b182ac8b6
Only the duration and the cooldown (and, since B-73, the draw confirmations) were copied onto the round when it opened. The cost of a bet and the fee address were read live, so an edit from /admin in the middle of a round gave the players of that round different stakes for the same chance and redirected the commission of the round in progress. - `rounds.bet_amount_sats`, `rounds.fee_address` and `rounds.max_round_pool_sats` are copied from round_config in the transaction that opens the round (Alembic a7d3e9f15b48: plain add_column, existing rounds backfilled with the current configuration, i.e. what they were using; the expression indexes untouched). `place_bet` charges the round's cost, `_trigger_payout` pays the round's fee address (an empty one on the row still stops the payout, as before), `GET /rounds/current` advertises the round's cost while one is active and the configured one otherwise. The minimum withdrawal and the fee rate stay live, by design (ADR-20, ADR-10). - `round_config.max_round_pool_sats` (0 = none, otherwise >= the bet cost and <= 4e15, in /admin and PUT/GET /admin/config): a bet is refused with `round_full` (params also carry `max_round_pool_sats`) once the sum of the round's participant rows, in-flight ones included, has reached the round's cap, before anything moves; the pool can exceed it by one bet at most. A cap under the bet cost is a 422 `max_round_pool_below_bet_amount`. - PUT /admin/config's payability check (RND-40) now also judges a fee-rate change against the bet cost the round in progress opened with, which can be lower than the configured one. - `error.round_full` no longer says "maximum of N players" (it also fires for the pool cap): the seven translations are generic. Ambiguity resolved: the spec said the cap is snapshotted (RND-05, BET-20, ARC) in some places and "applies immediately, also to the round in progress" in the round_config table of modello-dati; the snapshot wins, with a column on `rounds` (modello-dati/api/guide-admin brought in line). Tests changed because the spec changed: the payout fixtures seed the round's own fee address, and the old "fee address missing" payout test now empties the round's address (clearing it in the configuration mid-round must not stop the payout). New test_round_snapshot.py: the copy at open, edits reaching only the next round, every bet of a round paying the same stake whether the cost is raised or lowered meanwhile, the payout following the round's address (and surviving it being cleared in the configuration), the cap (exactly at the cap is full, in-flight bets count, no cap, a mid-round edit of the cap does not apply, the refused player's coins untouched), plus the route, the admin bounds and the two 422s, the fee-rate check against the round's own cost, and the migration backfill. Mutation-checked: charging the live cost, paying the live address, not copying the cap and `>` instead of `>=` each fail tests. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Architecture Decision Records (ADR)
Una decisione di progetto = un file. Ogni ADR spiega perché una scelta è stata fatta (contesto, alternative scartate, conseguenze); le regole verificabili che la attuano restano nei documenti di dominio con il loro PREFISSO-NN. Così ogni informazione ha un solo proprietario: l'ADR possiede il perché, il requisito possiede il cosa, il codice il come. Regole: processo-di-modifica.md. Modello per i nuovi: TEMPLATE.md.
Gli identificativi ADR-NN sono stabili e non si riusano (i primi 52 coincidono con i vecchi DEC-NN). Un ADR superato non si cancella: passa a Sostituita da ADR-MM.
Indice per area
Custodia, chiavi e indirizzi
| ADR | Decisione |
|---|---|
| ADR-01 | La piattaforma è custodiale: tutte le chiavi sono generate e tenute dal server |
| ADR-02 | Un indirizzo per utente, permanente, per tutti gli usi |
| ADR-03 | Ogni round ha il proprio indirizzo del montepremi |
| ADR-04 | Accesso alla rete solo via protocollo Electrum |
| ADR-05 | Solo indirizzi bech32 PLM (plm1…) come destinazione |
Conferme e fiducia nella rete
| ADR | Decisione |
|---|---|
| ADR-06 | I depositi richiedono deposit_confirmations conferme (6 per default, configurabile in round_config), le uscite coinbase 120; ogni altra transazione ne richiede 1 |
| ADR-07 | Ogni decisione che sposta denaro in base a una risposta di rete è corroborata da un quorum degli altri server configurati |
| ADR-52 | Le riorganizzazioni della catena si contengono invece di ignorarle |
Configurazione e ambiente
| ADR | Decisione |
|---|---|
| ADR-08 | I parametri operativi stanno nel database, i segreti nell'ambiente |
| ADR-09 | Le modifiche di configurazione sono validate, non fidate |
| ADR-10 | I parametri del round sono fotografati all'apertura |
| ADR-11 | Il server rifiuta di partire con segreti inadeguati |
| ADR-12 | Il server gira solo in Docker, in sviluppo come in produzione |
| ADR-13 | Un solo processo, un solo file SQLite |
Economia del gioco
| ADR | Decisione |
|---|---|
| ADR-14 | Ripartizione fissa 70% al vincitore / 30% alla piattaforma |
| ADR-15 | Biglietto a prezzo fisso, una scommessa per utente per round, probabilità uguale per tutti |
| ADR-16 | La commissione di rete si toglie dall'importo che si muove |
| ADR-17 | La commissione del pagamento esce dalla quota del vincitore; la riserva per l'RBF esce dalla quota della piattaforma |
| ADR-18 | L'accelerazione RBF la paga chi riceve il resto |
| ADR-19 | Ogni transazione utente conserva un'uscita di resto verso l'utente, e un'accelerazione che porterebbe quel resto sotto DUST_LIMIT_SATS (294 sat) lo elimina |
| ADR-20 | Il prelievo minimo è il costo corrente della scommessa |
| ADR-21 | Tre limiti distinti sul numero di monete e di giocatori: |
Round ed estrazione
| ADR | Decisione |
|---|---|
| ADR-22 | Al più un round attivo, come invariante del database |
| ADR-23 | Il limite per scommettere è la scadenza del round stesso, non il suo stato nel database |
| ADR-24 | L'estrazione è un commit-reveal fra il server e un blocco futuro |
| ADR-25 | Il blocco di estrazione è fissato per altezza, è successivo alla chiusura, e si usa solo quando è confermato e corroborato |
| ADR-26 | Validazione degli header concatenata, senza ricalcolo della difficoltà |
| ADR-27 | Pausa di cortesia fra un round e l'altro |
| ADR-28 | La pausa per manutenzione ferma solo il round successivo |
| ADR-29 | Senza fee_address non si apre nessun round |
| ADR-30 | Il montepremi annunciato è quello che sarà pagato |
Denaro in movimento
| ADR | Decisione |
|---|---|
| ADR-31 | Tutto ciò che spende denaro si scrive prima di inviarlo |
| ADR-32 | Il pagamento si ritenta da solo, mai due volte |
| ADR-33 | Scommessa e prelievo si escludono solo tramite il blocco per-utente |
| ADR-34 | Saldo spendibile e saldo mostrato sono due numeri distinti |
| ADR-35 | Aritmetica solo in satoshi interi |
| ADR-51 | Nel dubbio non si liberano mai i fondi |
Account, amministrazione e sicurezza
| ADR | Decisione |
|---|---|
| ADR-36 | Password con Argon2, sessioni con JWT HS256 da 24 ore, revocabili |
| ADR-37 | Nessun recupero password, solo reset |
| ADR-38 | Gli username sono un unico spazio di nomi senza distinzione fra maiuscole e minuscole |
| ADR-39 | L'esportazione della chiave privata WIF di un utente è voluta, non una vulnerabilità |
| ADR-40 | L'amministrazione usa un unico token condiviso |
| ADR-41 | Limitazione dei tentativi solo su login e registrazione |
| ADR-42 | L'IP del client è l'ultimo elemento di X-Forwarded-For |
| ADR-43 | Header di sicurezza nel proxy, con 'unsafe-inline' accettato |
| ADR-44 | /qr/{address} è pubblico ma limitato |
| ADR-45 | Segnalazioni di bug aperte a tutti, triage in admin |
| ADR-53 | Il registro di audit è in sola aggiunta e si scrive nella transazione che descrive |
Interfacce, API e lingue
| ADR | Decisione |
|---|---|
| ADR-46 | Il canale SSE è un'aggiunta al polling, non un sostituto |
| ADR-47 | L'API parla una sola lingua e risponde con codici |
| ADR-48 | Le pagine per l'utente (/ e /report-bug) sono in 7 lingue |
| ADR-49 | Il pannello /admin e la pagina /guida non sono tradotti |
| ADR-50 | Frontend statici, senza framework né build |
Funzionalità → ADR
Per ogni funzionalità, gli ADR da leggere prima di toccarla.
| Funzionalità | Prefisso | Documento di dominio | ADR |
|---|---|---|---|
| Registrazione e account | REG |
registrazione-e-depositi.md | 01, 02, 36, 37, 38 |
| Depositi e saldo | DEP |
registrazione-e-depositi.md | 06, 07, 34, 35, 52 |
| Scommesse | BET |
scommesse-e-prelievi.md | 15, 16, 19, 21, 23, 33 |
| Prelievi | WDR |
scommesse-e-prelievi.md | 05, 18, 19, 20, 33 |
| Round, estrazione, pagamento | RND |
ciclo-di-vita-del-round.md | 03, 10, 14, 17, 21–30, 32 |
| Transazioni, RBF, riconciliazione | TX |
transazioni-e-riconciliazione.md | 17, 18, 31, 32, 51 |
| Connessione Electrum | ELC |
connessione-electrum.md | 04, 07, 26, 52 |
| Registro di audit | AUD |
audit-log.md | 40, 53 |
| Amministrazione | SEC, API |
sicurezza.md, api.md | 09, 28, 29, 39, 40 |
| Sicurezza (limiti, header, QR) | SEC |
sicurezza.md | 41, 42, 43, 44 |
| Segnalazioni di bug | API |
api.md | 45 |
| Tempo reale (SSE) | ARC |
architettura.md | 46 |
| Interfacce e lingue | ARC, API |
architettura.md | 47, 48, 49, 50 |
| Configurazione e ambiente | ARC, OPS |
architettura.md, operativita.md | 08, 09, 10, 11, 12, 13 |
Le decisioni del 2026-09-28
| Decisione | ADR | B-nn |
|---|---|---|
| Estrazione con commit-reveal | ADR-24, ADR-25 | B-73, B-81 |
| Nel dubbio non si liberano mai i fondi | ADR-51 | B-76, B-77, B-78 |
| Un indirizzo del montepremi per ogni round | ADR-03 | B-80 |
| 6 conferme per i depositi, 1 per il resto | ADR-06 | B-82 |
| Le riorganizzazioni della catena si contengono | ADR-52 | B-82, B-85 |