davideandClaude Sonnet 5.5
ccd15807ed
`bump_fee` only required `change > fee delta`. A change at the 294 sat minimum (a full-balance
withdrawal) shrank to ~153 sat after the very first minimum bump, relay policy refuses a
replacement with a sub-dust output, and the bumper tried again every 30 seconds for ever, with
nothing but a log line to show for it.
- When what would be left of the reducible output (the user's change, a payout's bump
reserve) is under DUST_LIMIT_SATS the output is dropped and its whole value goes to the fee:
that replacement is valid and the last one possible. If the output does not exist, or even
its whole value is below BIP125's minimum increase (vsize x 1 sat/vB), RbfError. The
recorded fee rate uses the replacement's own, smaller, size.
- RbfError now carries a `reason` (`change_too_small`, `max_fee_rate`, `replacement_rejected`);
RbfBumper._record_failure writes one `rbf_bump_failed` row {pending_transaction_id, kind,
txid, reason, message[:200]} with the row's user_id/round_id, in a transaction of its own,
once per (current txid, reason) - the audit log is the dedupe clock (AUD-09) - and the pending
row is untouched. A new txid or a new reason writes a new row.
- bump_fee's docstring no longer cites the "bet without change" case that B-62 removed.
No existing test changed (all bumps they make leave a change well above dust). New
tests/unit/test_rbf_dust.py: the 294 sat case end to end (recipient untouched, whole change to
the fee, last bump impossible), the exact boundary (leaves 294 kept / leaves 293 dropped), a
change under the minimum increase, a payout's reserve dropped with the winner and fee outputs
byte-identical, and the audit rows for each reason, once per pair, new row on a new txid or
reason, round/user attribution. Mutation-checked: the dust test of the output and the
once-per-pair check 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 |