Files
plm-lottery/docs/adr/ADR-25-blocco-estrazione-fissato-altezza-successivo-chiusura.md
T
davideandClaude Sonnet 5.5 db24287ea5 Make the draw a commit-reveal at a fixed, confirmed, quorum-agreed height with a public proof (B-73, RND-14 … RND-20, RND-33 … RND-37, DAT-61 … DAT-66, API-25, API-45, AUD-24 … AUD-27, AUD-37, ELC-15, SEC-56, ADR-24, ADR-25)
The seed was the hash of the first block seen after the close, so a miner holding tickets
could withhold blocks until one made them win, the active Electrum server could pick which
real block was used by not announcing another (a failed corroboration even moved the draw to
the next block), and the participant order was the server-only `broadcast_at` with no
tie-break, so nobody could recompute the result.

- Open: every round gets a 32-byte `server_seed`, stored only Fernet-encrypted with the
  master-xprv key (`server_seed_enc`), with its published `server_seed_hash`;
  `draw_confirmations` is copied from round_config. The plaintext column is written only by
  the reveal.
- Entering `drawing` (one transaction, `draw_committed` audit row): participants ordered by
  bet txid, each `draw_position`, `participants_hash` (sha256 of `txid:vout:address\n`
  lines; new `bet_vout`), `draw_height = tip_at_close + 1`. A tip of 0 keeps the round
  `closing` (`draw_baseline_tip_unknown`, once per round). All persisted, so a resumed draw
  reads rather than recomputes (the `_tick` branch itself is B-81).
- `_complete_draw` / `_wait_for_draw_block` replace `_wait_for_next_block`: wait for
  `draw_confirmations` blocks from `draw_height`, then `ElectrumListener.agreed_block_hash`
  asks every server, the active one included, for the header at that exact height (valid
  work, >= 2 other answers, strict majority of all); no agreement means the same height is
  asked again and `draw_header_corroboration_failed` is written once per distinct reported
  hash. `draw_stalled` now counts from the last tip advance, or from when the quorum started
  to fail. Seed = sha256(server_seed || block_hash || participants_hash), index = seed mod n.
- The winner, the seed and the reveal (`server_seed`, `winner_drawn` payload) are written in
  one transaction; a round closing with no participants reveals too. A round opened before
  this change (no commitment) is given a secret as it enters `drawing`.
- `GET /rounds/{id}/proof` (public, 404 `round_not_found`, translated in all 7 languages) and
  the new fields on `GET /rounds/current`; `draw_confirmations` in `/admin/config` and the
  /admin form; `server_seed_hash`/`draw_height` in `/admin/rounds`, never the secret.
- Alembic d3e8b15a7c42 (plain add_column / create_index, expression indexes untouched).
- Docs: the B-73 `*Stato:*`/`*Oggi:*` lines are gone, guides and CLAUDE.md describe the new
  draw. Ambiguities resolved in api.md: the proof's participants also carry `amount_sats`
  (RND-37 lists it); `seed` is decimal in the proof and hex in the audit row, as specified.

Tests changed because the spec changed: ElectrumListener.corroborate_header (asked only the
other servers about the block the active one announced) is replaced by agreed_block_hash and
its quorum tests ported; draw_winner takes the secret and the list fingerprint; the four
_wait_for_next_block scheduler tests are replaced by _wait_for_draw_block ones (fixed height,
confirmations, same-height retry, stall clock). New: test_draw_proof.py recomputes the winner
independently from the public proof, checks the plaintext secret is nowhere in the database,
the API or the log before the reveal, and that a second pass over a `drawing` round yields
the same winner. Mutation-checked: ordering by broadcast_at, an early reveal and asking the
tip instead of the draw height each fail tests.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-14 16:29:09 +02:00

2.7 KiB

ADR-25 — Il blocco di estrazione è fissato per altezza, è successivo alla chiusura, e si usa solo quando è confermato e corroborato

  • Stato: Accettata — implementazione da completare (B-81)
  • Area: Round ed estrazione
  • Fonte di verità per: la scelta di progetto descritta qui sotto; i requisiti (PREFISSO-NN) che la attuano stanno nei documenti di dominio, indicati nelle Conseguenze.

Decisione

Il blocco di estrazione è fissato per altezza, è successivo alla chiusura, e si usa solo quando è confermato e corroborato. All'ingresso in drawing si salva draw_height = tip_at_close + 1, che non cambia più. Si attende che quel blocco abbia draw_confirmations conferme (3 per default, fotografato all'apertura, ADR-10), poi si chiede a tutti i server l'header a quell'altezza: serve l'accordo del quorum (ADR-07); in caso di disaccordo si attende e si richiede la stessa altezza, mai un blocco diverso. L'attesa non ha timeout (l'entropia dipende davvero da un blocco futuro) ma è osservabile (draw_stalled, draw_waiting_since) e riprendibile: draw_height, participants_hash e la posizione di ogni partecipante sono salvati, e lo scheduler riprende un round in drawing dopo un errore o un riavvio con lo stesso esito. Un'altezza 0 alla chiusura significa «sconosciuta»: la prima altezza appresa fa da base.

  • Motivazione: un hash già pubblico mentre le scommesse erano aperte renderebbe il vincitore prevedibile (B-63); un header fabbricato sceglierebbe il vincitore (B-28); un'altezza non fissata lascia al server attivo la scelta di quale blocco reale usare, e passare a «un blocco ulteriore» dopo una corroborazione fallita gli dà un secondo tentativo (B-73). Le conferme sul blocco di estrazione evitano che una riorganizzazione cambi il seme dopo l'estrazione. Uno stato tenuto solo in memoria bloccava il round in drawing a ogni eccezione (B-81).
  • Alternative scartate: timeout sull'attesa con ripiego su un altro blocco (riaprirebbe la scelta del blocco).

Codice: app/rounds/scheduler.py:RoundScheduler._wait_for_draw_block · app/rounds/scheduler.py:RoundScheduler._close_and_draw · app/rounds/scheduler.py:RoundScheduler._tick · Test: tests/unit/test_scheduler.py::test_a_block_relayer_cannot_choose_the_block_that_seeds_the_draw, tests/unit/test_scheduler.py::test_a_disagreement_asks_the_same_height_again_and_is_audited_once_per_hash Stato: da implementare (B-81) · Oggi: draw_height, participants_hash e le posizioni sono salvati, ma _tick salta i round in drawing: dopo un errore o un riavvio il round non riparte.