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

+42 -10
View File
@@ -100,9 +100,9 @@ monete:
| Esito | Cosa significa | Cosa si fa |
|---|---|---|
| Accettato | Il server risponde con il txid, oppure rifiuta dicendo che la transazione è già nota | Si promuove la riga ([BET-17](scommesse-e-prelievi.md#cosa-succede), [WDR-12](scommesse-e-prelievi.md#prelievo)) |
| Rifiutato esplicitamente | Il server risponde con un errore JSON-RPC diverso da "già nota" | Si annulla tutto ([TX-04]) |
| Incerto | Timeout, connessione caduta, errore di scrittura sul socket: la transazione può essere partita | Non si libera nulla ([TX-20]) |
| Accettato | Il server risponde con il txid, oppure rifiuta ma almeno un server conosce la transazione | Si promuove la riga ([BET-17](scommesse-e-prelievi.md#cosa-succede), [WDR-12](scommesse-e-prelievi.md#prelievo)) |
| Rifiutato esplicitamente | Il server risponde con un errore JSON-RPC **e** nessun server interrogato conosce la transazione | Si annulla tutto ([TX-04]) |
| Incerto | Timeout, connessione caduta, errore di scrittura sul socket, oppure un rifiuto la cui verifica non ottiene risposte: la transazione può essere partita | Non si libera nulla ([TX-20]) |
- **[TX-04]** Solo un **rifiuto esplicito** — una risposta del server con un
oggetto `error` JSON-RPC — all'invio di una scommessa o di un prelievo
@@ -111,12 +111,27 @@ monete:
notifica SSE. Per una scommessa partecipante e riga vengono **cancellati**;
per un prelievo prelievo e riga restano, in stato `failed`. L'utente riceve
`broadcast_failed` con codice HTTP **502**, perché è stata la rete a
rifiutare, non la sua richiesta a essere sbagliata. Un rifiuto che dice che
la transazione è **già nota** (messaggi che contengono `already known`,
`already in mempool`, `txn-already-known`, `txn-already-in-mempool` o
`transaction already in block chain`) non è un rifiuto: vale come invio
accettato.
*Codice:* `app/bets/service.py:_release_failed_bet`, `app/withdrawals/service.py:_release_failed_withdrawal`, `app/electrum/client.py:ElectrumClient.broadcast` ·
rifiutare, non la sua richiesta a essere sbagliata.
**Prima di annullare, il rifiuto si verifica.** Il testo dell'errore non
basta a distinguere un rifiuto vero da un "già nota" (i server usano
messaggi diversi e non esiste un codice standard), quindi dopo ogni rifiuto
si chiede `blockchain.transaction.get` per il txid al server attivo e a
tutti i server di riserva (10 s ciascuno):
- se **almeno uno** restituisce la transazione, l'invio vale come
**accettato** (la transazione è in rete);
- se **tutti quelli che rispondono** dicono di non conoscerla, e rispondono
almeno il server attivo e il numero minimo di server del quorum
([connessione-electrum.md](connessione-electrum.md#5-il-quorum)), si
annulla;
- se le risposte non bastano, l'esito è **incerto** ([TX-20]).
Il riconoscimento dei messaggi "già nota" (`already known`,
`already in mempool`, `txn-already-known`, `txn-already-in-mempool`,
`transaction already in block chain`) resta solo una scorciatoia che salta
la verifica: un messaggio non riconosciuto non può più far liberare le
monete di una transazione partita, al massimo costa una verifica in più.
*Codice:* `app/bets/service.py:_release_failed_bet`, `app/withdrawals/service.py:_release_failed_withdrawal`, `app/electrum/client.py:ElectrumClient.broadcast`, `app/electrum/client.py:ElectrumClient.get_transaction` ·
*Test:* `tests/unit/test_bets.py`, `tests/unit/test_withdrawals.py`
*Stato:* da implementare (B-76) · *Oggi:* qualunque eccezione dell'invio,
compresi il timeout di 15 secondi, la connessione caduta dopo la scrittura
@@ -301,6 +316,10 @@ sostituibilità fin dal primo invio.
rete scrivono un evento `rbf_bump_failed` ([audit-log.md](audit-log.md)
(B-87)) con la riga, il txid corrente e il motivo; la riga resta `pending`
e il tentativo si ripete al giro successivo in cui è dovuto ([TX-09]).
L'evento si scrive **una volta per coppia (txid corrente, motivo)**: un
tentativo che fallisce di nuovo per lo stesso motivo sullo stesso txid va
solo nei log, così una transazione non accelerabile non riempie il registro
con una riga ogni 30 secondi.
*Codice:* `app/tx/broadcast.py:RbfBumper._tick` ·
*Test:* —
*Stato:* da implementare (B-87) · *Oggi:* l'errore finisce solo nei log
@@ -398,7 +417,7 @@ riserva di [TX-11] serve proprio a dargli un'uscita da ridurre.
Se uno di essi risulta confermato ([TX-22]) — una transazione data per
morta che invece è arrivata in un blocco — si scrive una sola volta
`pending_tx_resurrected` ([audit-log.md](audit-log.md) (B-78)) e la
lotteria viene messa in pausa (`paused_reason = 'tx_resurrected'`) perché
lotteria viene messa in pausa (`paused_reason = 'resurrected_tx'`) perché
l'operatore rimetta in ordine partecipante, prelievo o pagamento; il
riconciliatore non corregge da solo le righe collegate.
*Codice:* `app/tx/reconcile.py:reconcile_once` ·
@@ -420,6 +439,19 @@ riserva di [TX-11] serve proprio a dargli un'uscita da ridurre.
mempool, il round resta in `closing`.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`, `app/tx/reconcile.py:reconcile_once` ·
*Test:* `tests/unit/test_scheduler.py`
- **[TX-29]** L'attesa in `closing` senza tempo massimo ([TX-25]) è
**visibile**: quando un round resta in `closing` oltre la scadenza per più
di `CLOSING_STALL_THRESHOLD_SECONDS` (1800 s), lo scheduler scrive un
evento `closing_stalled` ([audit-log.md](audit-log.md) (B-96)) con il round,
il numero di scommesse ancora in volo e i loro txid, e lo ripete ogni 1800 s
finché l'attesa dura; `GET /rounds/current` espone da quando il round attende
(`closing_waiting_since`). L'operatore decide con la procedura di
[operativita.md](operativita.md) (B-96); il sistema non esclude da solo una
scommessa in volo dall'estrazione.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick` ·
*Test:* —
*Stato:* da implementare (B-96) · *Oggi:* l'attesa non produce alcun
segnale oltre al round che resta in `closing`.
## Pagamenti del round: riprovare senza pagare due volte