This commit is contained in:
davide committed 2026-09-28 15:36:38 +02:00
1 parent 61efbb0e37
commit c5e7daa9c7
15 files changed
+4514 -1172

No files matched your search

+52 -11
View File
@@ -18,12 +18,22 @@ sezione rimanda al documento che la approfondisce.
| [operativita.md](operativita.md) | Backup, riavvii, procedure per gli incidenti |
| [decisioni-e-limiti.md](decisioni-e-limiti.md) | Decisioni di progetto con le loro motivazioni, limiti noti accettati |
| [storico-bug.md](storico-bug.md) | Tutti i bug B-nn trovati e corretti, con commit e test |
| [piano-correzioni.md](piano-correzioni.md) | Decisioni della revisione del 2026-09-28 e ordine in cui implementare le correzioni ancora aperte |
Questi documenti sono la **specifica** del software: ogni regola ha un
identificativo stabile (ad esempio `RND-11`) con il riferimento al codice che
la implementa. Come si usano per modificare il software è spiegato in
[processo-di-modifica.md](processo-di-modifica.md).
Dalla revisione del 2026-09-28 la specifica descrive il comportamento
**atteso**, che in alcuni punti è più avanti del codice. I requisiti che il
codice non soddisfa ancora sono marcati `*Stato:* da implementare (B-nn)` e
dicono in una riga cosa fa il codice oggi (`git grep "da implementare"` li
elenca tutti); anche questa panoramica descrive il comportamento atteso. Le
decisioni prese e l'ordine di implementazione sono in
[piano-correzioni.md](piano-correzioni.md), il dettaglio tecnico di ogni voce
in [BUGS.md](../BUGS.md).
Per installazione e avvio vedi [setup.md](setup.md) e
[running-the-server.md](running-the-server.md); per l'uso delle interfacce
[guida-utente.md](guida-utente.md) e [guida-admin.md](guida-admin.md).
@@ -32,8 +42,10 @@ Per installazione e avvio vedi [setup.md](setup.md) e
Gli utenti depositano PLM su un indirizzo personale custodito dal server,
comprano un biglietto a costo fisso per il round in corso, e allo scadere del
round l'hash del primo blocco successivo sceglie un vincitore, che riceve il
70% del montepremi; il 30% va alla piattaforma.
round un seme che combina un segreto su cui il server si è impegnato
all'apertura, l'hash di un blocco successivo alla chiusura e l'elenco dei
partecipanti sceglie un vincitore, che riceve il 70% del montepremi; il 30%
va alla piattaforma.
## Scelte di fondo
@@ -43,14 +55,30 @@ round l'hash del primo blocco successivo sceglie un vincitore, che riceve il
depositi, riceve le vincite e riceve il resto di ogni scommessa e prelievo.
- **Nessun nodo completo.** Tutto l'accesso alla rete passa dal protocollo
Electrum (vedi [connessione-electrum.md](connessione-electrum.md)).
- **1 conferma** per ogni tipo di transazione: depositi, scommesse, pagamenti,
prelievi.
- **6 conferme per i depositi, 1 per tutto il resto.** Il deposito è l'unico
ingresso che un utente può spendere due volte, perché scommesse, pagamenti
e prelievi li firma solo il server; le uscite coinbase richiedono 120
conferme (vedi [registrazione-e-depositi.md](registrazione-e-depositi.md#deposito)).
- **Estrazione con commit-reveal.** All'apertura il server si impegna su un
segreto pubblicandone l'impronta; alla chiusura si fissano elenco dei
partecipanti e altezza del blocco; il segreto viene rivelato dopo
l'estrazione. Chi produce i blocchi non può calcolare il vincitore e
l'operatore non può cambiare il segreto; chiunque può verificare il
risultato con la prova pubblica (vedi
[ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#3--estrazione)).
- **Un indirizzo del montepremi per ogni round**, così soldi e cronologia di
un round restano separati da quelli degli altri.
- **Nel dubbio non si liberano i fondi.** Una transazione viene annullata solo
con una prova, mai per un timeout o per il silenzio di un solo server (vedi
[transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md)).
- **Parametri operativi nel database**, modificabili a caldo da `/admin`
(costo della scommessa, durata del round, commissioni…). Nel file `.env`
restano solo segreti e collegamenti infrastrutturali.
## Le cinque fasi
Diagramma del **comportamento atteso**:
```mermaid
flowchart LR
subgraph REG["1 · Registrazione"]
@@ -60,7 +88,7 @@ flowchart LR
subgraph DEP["2 · Deposito"]
direction TB
B1["L'utente invia PLM<br/>al proprio indirizzo"] --> B2{"1 conferma e<br/>corroborato dagli<br/>altri server?"}
B1["L'utente invia PLM<br/>al proprio indirizzo"] --> B2{"6 conferme e<br/>corroborato dagli<br/>altri server?"}
B2 -- "No" --> B1b["Si riprova al prossimo<br/>aggiornamento"] --> B2
B2 -- "Sì" --> B3["Saldo accreditato"]
end
@@ -68,7 +96,7 @@ flowchart LR
subgraph PLAY["3 · Scommessa"]
direction TB
C1{"Saldo sufficiente,<br/>nessuna scommessa attiva,<br/>round aperto e non pieno?"}
C1 -- "Sì" --> C2["Transazione: indirizzo utente →<br/>montepremi, resto all'utente"]
C1 -- "Sì" --> C2["Transazione: indirizzo utente →<br/>montepremi del round, resto all'utente"]
C2 --> C3{"Confermata?"}
C3 -- "No, troppo tempo" --> C4["Commissione aumentata<br/>(RBF) e reinvio"] --> C3
C3 -- "Sì" --> C5["Partecipante del round"]
@@ -76,9 +104,14 @@ flowchart LR
subgraph DRAW["4 · Round ed estrazione"]
direction TB
D1["Scadenza del round"] --> D2["Si attendono le scommesse<br/>già in volo"]
D2 --> D3["Il primo blocco successivo<br/>sceglie il vincitore"]
D3 --> D4["70% al vincitore,<br/>30% alla piattaforma"]
D0["Apertura: indirizzo del montepremi<br/>del round, impronta del segreto pubblicata"] --> D1["Scadenza del round"]
D1 --> D2["Si attendono le scommesse<br/>già in volo"]
D2 --> D3["Si fissano partecipanti<br/>e altezza del blocco"]
D3 --> D3b["Blocco con 3 conferme, header<br/>concordato dal quorum:<br/>segreto + blocco + partecipanti<br/>scelgono il vincitore"]
D3b --> D3c["Segreto rivelato,<br/>prova pubblica"]
D3c --> D3d{"Scommesse ancora<br/>sulla catena?"}
D3d -- "Sì (quelle sparite<br/>sono escluse)" --> D4["70% al vincitore, 30% alla piattaforma<br/>meno la riserva per l'RBF"]
D3d -- "Sparita quella<br/>del vincitore" --> D5["Pagamento bloccato,<br/>lotteria in pausa"]
end
subgraph WITHDRAW["5 · Prelievo"]
@@ -139,7 +172,7 @@ solo polling.
| Parametro | Valore predefinito | Modificabile |
|---|---|---|
| Costo della scommessa | 10 PLM | da `/admin` |
| Costo della scommessa | 10 PLM | da `/admin`, vale dal round successivo (B-95) |
| Ripartizione del montepremi | 70% vincitore / 30% piattaforma | no, è nel codice |
| Durata del round | 600s | da `/admin`, vale dal round successivo |
| Pausa tra un round e l'altro | 30s | da `/admin`, vale dal round successivo |
@@ -148,4 +181,12 @@ solo polling.
| Prelievo minimo | pari al costo della scommessa | segue il costo |
| Deposito minimo | nessuno | — |
| Partecipanti massimi per round | 400 | no, è nel codice |
| Conferme richieste | 1 | no, è nel codice |
| Tetto al montepremi del round (`max_round_pool_sats`) | 0 = nessun tetto (B-95) | da `/admin`, vale dal round successivo |
| Conferme per i depositi (`deposit_confirmations`) | 6; 120 per le uscite coinbase (B-82) | da `/admin`; le 120 coinbase no, sono nel codice |
| Conferme sul blocco di estrazione (`draw_confirmations`) | 3 (B-73) | da `/admin`, vale dal round successivo |
| Conferme per scommesse, pagamenti, prelievi | 1 | no, è nel codice |
| Indirizzo del montepremi | uno per round, `m/84'/746'/0'/2/<id_round>` (B-80) | no, è nel codice |
| Riserva per l'RBF sul pagamento | `max(294 sat, dimensione stimata × 10 sat/vB)`, tolta dalla quota della piattaforma, verso `m/84'/746'/0'/1/0` (B-79) | no, è nel codice |
Un B-nn nella tabella indica un parametro del comportamento atteso non ancora
implementato (vedi [piano-correzioni.md](piano-correzioni.md)).