Complete the target spec for the 2026-09-28 review (B-73..B-98)
Finishes what 88221b0 started: sicurezza.md, audit-log.md and storico-bug.md
now describe the target behaviour too, the operator guides are corrected
against today's code, and api.md gains the missing /health/ready and
/admin/electrum sections plus every new error code in its catalog.
Harmonised names and owners across documents (the `resurrected_tx` pause
reason, the reconciler as the one that watches failed rows, the full
`winner_drawn` payload, a reason for an unanswered pre-payout pool check,
one corroboration-failure row per hash instead of one per tick).
Adds B-98 (coin selection stops at the first covering UTXO and refuses a
payable bet), tightens RND-40 to check both 1 and 400 participants and to
guard PUT /admin/config, and gives a stalled `closing` round a signal
(TX-29, closing_stalled).
Records three decisions confirmed on 2026-09-29: the draw's server_seed is
stored Fernet-encrypted until revealed (SEC-56, DAT-64), the chosen abuse
and key-check thresholds (SEC-49, SEC-54, SEC-55), and a broadcast
rejection is verified against every server before any coin is released,
so matching "already known" text is a shortcut, not a safety condition
(TX-04).
Spec only; no code changed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
88221b0dbd
commit
4be58709d1
16 files changed
+1377
-323
No files matched your search
@@ -136,8 +136,11 @@ richiesta di scommessa (vedi
|
||||
*Codice:* `app/rounds/service.py:open_new_round_if_needed`
|
||||
- **[RND-34]** **Impegno sul segreto**: all'apertura il server genera un
|
||||
segreto di 32 byte casuali (`server_seed`, da un generatore
|
||||
crittograficamente sicuro), lo salva sul round e pubblica solo la sua
|
||||
impronta `server_seed_hash = sha256(server_seed)`, esposta da
|
||||
crittograficamente sicuro), lo salva sul round **cifrato** con la chiave
|
||||
della master xprv (`server_seed_enc`, [modello-dati.md](modello-dati.md)
|
||||
DAT-64: il database non contiene mai il segreto in chiaro prima della
|
||||
rivelazione) e pubblica solo la sua impronta
|
||||
`server_seed_hash = sha256(server_seed)`, esposta da
|
||||
`GET /rounds/current` e dalla prova pubblica ([RND-37]) fin dall'apertura.
|
||||
`server_seed` non è esposto da nessun endpoint, `/admin` compreso, finché il
|
||||
vincitore non è salvato ([RND-18]).
|
||||
@@ -307,7 +310,10 @@ flowchart TB
|
||||
il quorum non concorda o non risponde abbastanza, si scrive
|
||||
`draw_header_corroboration_failed` (altezza e hash riportati) e al passo
|
||||
successivo si richiede **la stessa altezza**: il round non passa mai a un
|
||||
blocco diverso.
|
||||
blocco diverso. L'evento si scrive una volta per ogni hash diverso
|
||||
riportato dal server attivo per quell'altezza, non a ogni richiesta, così
|
||||
un disaccordo che dura non scrive una riga ogni 5 secondi; la durata
|
||||
dell'attesa resta visibile tramite `draw_stalled` ([RND-20]).
|
||||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_next_block`, `app/electrum/listener.py:ElectrumListener.corroborate_header` ·
|
||||
*Test:* `tests/unit/test_scheduler.py` (solo il comportamento attuale)
|
||||
*Stato:* da implementare (B-73) · *Oggi:* si usa l'header della punta
|
||||
@@ -330,8 +336,11 @@ flowchart TB
|
||||
`draw_block_hash`), il seme (`seed_int`), il vincitore e il montepremi
|
||||
(`pool_amount_sats`), passa a `paying_out` e scrive `winner_drawn`
|
||||
(indirizzo del vincitore, montepremi, altezza, hash, numero di
|
||||
partecipanti, `participants_hash`). Solo **dopo** quel commit `server_seed`
|
||||
diventa pubblico ([RND-37]); si invia una notifica SSE. Da quel momento
|
||||
partecipanti, `participants_hash`, `draw_height`, `server_seed` e `seed`
|
||||
in esadecimale, [audit-log.md](audit-log.md) AUD-24). `server_seed` entra
|
||||
nel registro nella stessa transazione in cui il vincitore viene salvato, e
|
||||
diventa pubblico tramite la prova ([RND-37]) solo dopo quel commit; si invia
|
||||
una notifica SSE. Da quel momento
|
||||
chiunque, con i dati della prova pubblica e la catena, può rifare il calcolo
|
||||
e ottenere lo stesso vincitore (vedi
|
||||
[Come si verifica un'estrazione](#come-si-verifica-unestrazione)). Il primo
|
||||
@@ -506,7 +515,9 @@ del montepremi del round.
|
||||
`insufficient pool UTXOs`, il codice dell'errore di costruzione
|
||||
(`too_many_inputs`, `winner_share_below_network_fee`,
|
||||
`commission_below_dust_limit`), `payout build failed` per ogni altro errore
|
||||
di costruzione, `broadcast rejected`. Fanno eccezione due casi, che non
|
||||
di costruzione, `broadcast rejected`, e — *da implementare (B-82)* —
|
||||
`pool verification unavailable` quando la verifica del montepremi prima del
|
||||
pagamento ([RND-39]) non ottiene abbastanza risposte dal quorum. Fanno eccezione due casi, che non
|
||||
scrivono `payout_failed`: un pagamento già in volo per il round ([RND-26]),
|
||||
che termina il tentativo senza scrivere nulla, e un pagamento bloccato
|
||||
([RND-39]), che scrive `payout_blocked`. A ogni passo lo scheduler
|
||||
@@ -578,20 +589,28 @@ del montepremi del round.
|
||||
`insufficient pool UTXOs` a ogni tentativo, con i soldi di tutti gli altri
|
||||
bloccati.
|
||||
- **[RND-40]** **Configurazione pagabile**: `rounds_can_open` rifiuta una
|
||||
configurazione in cui un round con un solo partecipante non si potrebbe
|
||||
pagare. Con `netto` = `bet_amount_sats − estimate_vsize(MAX_TX_INPUTS, 2) ×
|
||||
fee_rate_sat_vb` (la scommessa più piccola che può arrivare al montepremi)
|
||||
devono valere entrambe:
|
||||
- `winner_share(netto) − estimate_vsize(1, 3) × fee_rate_sat_vb ≥
|
||||
configurazione in cui un round non si potrebbe pagare, verificandola per
|
||||
**n = 1** e per **n = `MAX_PARTICIPANTS_PER_ROUND`** partecipanti (i due
|
||||
estremi: con uno solo la commissione è minima, con il massimo è massima la
|
||||
riserva, che cresce con gli ingressi). Con `netto` = `bet_amount_sats −
|
||||
estimate_vsize(MAX_TX_INPUTS, 2) × fee_rate_sat_vb` (la scommessa più piccola
|
||||
che può arrivare al montepremi) e `montepremi = n × netto`, per entrambi i
|
||||
valori di n devono valere:
|
||||
- `winner_share(montepremi) − estimate_vsize(n, 3) × fee_rate_sat_vb ≥
|
||||
DUST_LIMIT_SATS`;
|
||||
- `netto − winner_share(netto) − riserva ≥ DUST_LIMIT_SATS`, con la
|
||||
riserva di [RND-38] calcolata su un ingresso.
|
||||
- `montepremi − winner_share(montepremi) − riserva(n) ≥ DUST_LIMIT_SATS`,
|
||||
con `riserva(n)` quella di [RND-38] calcolata su n ingressi.
|
||||
|
||||
Si usano i valori della configurazione al momento dell'apertura.
|
||||
*Codice:* `app/rounds/service.py:rounds_can_open` ·
|
||||
La stessa verifica si applica a `PUT /admin/config`: una modifica di
|
||||
`bet_amount_sats` o `fee_rate_sat_vb` che la farebbe fallire è rifiutata,
|
||||
così un aumento della commissione di rete a round in corso non può rendere
|
||||
impagabile il round (il pagamento legge `fee_rate_sat_vb` al momento della
|
||||
costruzione).
|
||||
*Codice:* `app/rounds/service.py:rounds_can_open`, `app/api/routes/admin.py` ·
|
||||
*Test:* —
|
||||
*Stato:* da implementare (B-79) · *Oggi:* `rounds_can_open` controlla solo
|
||||
che `fee_address` non sia vuoto.
|
||||
che `fee_address` non sia vuoto, e `PUT /admin/config` non fa verifiche di
|
||||
pagabilità.
|
||||
|
||||
## Tempi reali
|
||||
|
||||
|
||||
Reference in new issue
Block a user