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

+33 -8
View File
@@ -1,7 +1,7 @@
# BUGS.md — open findings
Two audits currently have open entries: 2026-08-03 (B-71, B-72, below) and the
2026-09-28 specification review (B-73 … B-97, at the end of the file).
2026-09-28 specification review (B-73 … B-98, at the end of the file).
## Audit of 2026-08-03
@@ -73,7 +73,7 @@ way to run the server.
---
# Audit of 2026-09-28 — specification review (B-73 … B-97)
# Audit of 2026-09-28 — specification review (B-73 … B-98)
Fourth audit, run against the new specification in `docs/` rather than the code
alone: four independent reviews (coin/chain mechanics, money state machine,
@@ -110,7 +110,9 @@ is used (it only has to skip announcing one; corroboration checks that the block
exists, not that it is the first after closing). The participant order uses the
server-only `broadcast_at` with no tie-break, so the draw is not reproducible.
Fix (commit-reveal): at round open generate a 32-byte `server_seed`, store it,
Fix (commit-reveal): at round open generate a 32-byte `server_seed`, store it
**encrypted** (`server_seed_enc`, Fernet with the master-xprv key, so a DB copy or
backup alone never reveals it; the plaintext column is written only at reveal), and
publish only `server_seed_hash = sha256(server_seed)`. On entering `drawing`, fix
the participant list ordered by confirmed bet txid (ascending), publish
`participants_hash = sha256` of the `txid:vout:address` lines, and fix
@@ -155,8 +157,13 @@ including the 15s timeout and a drop after the write. The tx may have propagated
bet's sats land in the pool with no participant, the withdrawal leaves while its row
says `failed`.
Fix: only an explicit JSON-RPC rejection releases immediately (an "already known /
already in mempool" rejection is success). A timeout or disconnect leaves the rows
Fix: only an explicit JSON-RPC rejection can release, and only after verifying it:
`blockchain.transaction.get(txid)` is asked of the active server and every fallback
(10s each). Any server returning the tx → accepted; every responder denying it, with
the active server and the quorum minimum among them → released; too few answers →
uncertain (below). Matching "already known / already in mempool" messages is only a
shortcut that skips the check, so an unrecognised message can never release a tx
that is on the network (spec: TX-04). A timeout or disconnect leaves the rows
`building` for the reconciler and the API answers 202 with the row in `building`.
After the active server accepts, the raw tx is also sent to every fallback
(best effort).
@@ -201,7 +208,9 @@ Fix: every payout carries a **bump reserve** output of
`max(DUST_LIMIT_SATS, estimated_vsize × 10 sat/vB)`, taken from the commission share
and paid to the pool reserve address (`m/84'/746'/0'/1/0`, the old pool address);
RBF shrinks that output. `rounds_can_open` refuses a configuration in which a
one-participant round could not cover winner fee + reserve + dust commission.
round of 1 or of `MAX_PARTICIPANTS_PER_ROUND` participants could not cover winner
fee + reserve + dust commission, and `PUT /admin/config` refuses a bet amount or
fee rate that would fail the same check (spec: RND-40).
### B-80 — One pool address for every round
@@ -385,9 +394,12 @@ payout leaves `winner_amount_sats`/`fee_amount_sats` set; a promoted payout writ
row it checks; concurrent refreshes of one user can collide on the unique outpoint
and end the Electrum session; `listener.client` is read outside the per-user lock;
a bet covered only by pending change gets `insufficient_balance` instead of
`balance_pending_confirmation`.
`balance_pending_confirmation`. A round waiting in `closing` on a bet that never
leaves the mempool gives no signal at all.
Fix: each as described, one regression test per item.
Fix: each as described, one regression test per item; for the `closing` wait, a
`closing_stalled` audit row every 1800s past the deadline and `closing_waiting_since`
on `GET /rounds/current` (spec: TX-29).
### B-97 — Migrations can silently drop the expression indexes
@@ -397,3 +409,16 @@ runs the migrations.
Fix: a test that runs `alembic upgrade head` on an empty DB and asserts both indexes
exist; any batch migration on those tables recreates them explicitly.
### B-98 — Coin selection stops at the first covering UTXO, refusing a payable bet
Found while writing the spec on 2026-09-28 (medium). `select_utxos` returns as soon
as the selected total covers the target. When that happens exactly (a 10 PLM coin
for a 10 PLM bet), the change is 0: the bet is refused with
`balance_leaves_no_change` and a withdrawal is reduced by `DUST_LIMIT_SATS`, even
though a second coin would have left a proper change output.
Fix: select until the total covers `target + DUST_LIMIT_SATS` (still largest-first,
still capped at `max_inputs`); only when every allowed coin together cannot reach it
fall back to today's behaviour (refuse the bet, reduce the withdrawal). Spec:
`docs/scommesse-e-prelievi.md` BET-24.