0 Fork 0

Files

T

davideandClaude Sonnet 5.5 b424f670c5 Restructure docs: docs-first, SSOT, one ADR per decision

- Add docs/README.md as the index of all documentation.
- Split the 52 DEC entries of decisioni-e-limiti.md into docs/adr/ADR-NN
  files (same numbers), add ADR-53 (audit log), TEMPLATE.md and an ADR index
  with a feature -> ADR table.
- Rename decisioni-e-limiti.md to limiti-noti.md (LIM only) and rewrite all
  DEC-nn references as links to the ADRs.
- Document the docs-first / SSOT / ADR rules in processo-di-modifica.md and
  map the docs in CLAUDE.md and README.md.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

2026-10-14 12:05:57 +02:00

10 KiB

Raw Permalink Blame History

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

10 KiB Raw Permalink Blame History Unescape Escape