davideandClaude Sonnet 5.5
2b6ddb019b
place_bet and request_withdrawal released everything on any exception from the broadcast, including the 15s timeout and a connection dropped after the write. The tx may have propagated: a bet's sats landed in the pool with no participant, a withdrawal left while its row said failed and its coins were spendable again. - client: ElectrumRpcError (subclass of ElectrumError) is raised only for a reply carrying a JSON-RPC `error`; timeouts, drops and write errors stay plain ElectrumError. - tx/outcome.py:broadcast_with_verdict sorts a broadcast into accepted / refused / uncertain. A refusal is verified first: ElectrumListener.transaction_known asks blockchain.transaction.get of the active server and every other one (10s each) — any server returning the tx means accepted; the active server plus MIN_QUORUM_RESPONSES others all denying it means refused (ALLOW_NO_QUORUM keeps the reduced rule); too few answers is uncertain. "already known" wording is only a shortcut that skips the check. With no network to ask, a refusal is uncertain. - place_bet / request_withdrawal / _trigger_payout use it: only a verified refusal releases; uncertain leaves the rows building for the reconciler, publishes SSE and POST /bets and POST /withdrawals answer 202 with status building; "already known" promotes a payout (payout_sent) like any accepted broadcast. - An accepted transaction is fanned out to every other server (ElectrumListener.fan_out_transaction, best effort, off the caller's path). The RBF replacement in bump_fee is left for B-77, which rewrites that function. Tests changed because the spec changed: the existing "refused broadcast" tests raised a bare RuntimeError (now an uncertain outcome) and are made explicit refusals (rpc_error) with a network that denies the tx; direct route calls pass a Response; FakePayoutListener gains the network surface. 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 |