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:
davideandClaude Opus 5.5 committed 2026-09-29 09:17:52 +02:00
1 parent 88221b0dbd
commit 4be58709d1
16 files changed
+1377 -323

No files matched your search

+35 -16
View File
@@ -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