Files
plm-lottery/docs/adr/ADR-52-riorganizzazioni-catena-contengono-invece-ignorarle.md
T
davideandClaude Sonnet 5.5 ca50ef62f3 Require real proof of work in headers and link every advance to the tip (B-74, ELC-11, ELC-12, ELC-22, ELC-23)
A header only had to meet the target it declared for itself, so a fabricated one with
`bits = 0x207fffff` passed half the time, a jump of several blocks was accepted without
being linked to the tip (a fake header at a huge height locked `tip_height` and froze every
draw), and an ordinary one-block reorganisation closed the session on every server.

- draw.py: MAINNET_POW_LIMIT (00000000ffff...ffff); header_meets_its_own_target also
  refuses a claimed target easier than POW_LIMIT.
- ElectrumListener._apply_header is async and takes the active client. A single block must
  chain by prev_hash; a jump downloads the headers in between (blockchain.block.headers,
  at most 2016 per request, ElectrumClient.get_block_headers) and each must carry valid
  work and chain, otherwise HeaderValidationError ends the session.
- The listener keeps the last 10 headers (`_window`), built from the process's first header
  and its 9 predecessors (which must chain into it). A header that does not join the tip is
  walked back to its fork point inside the window and the server's branch is followed
  instead of ending the session; a fork older than the window, or a branch that does not
  end at the announced header, still ends it. The audit row and the pause for deep reorgs
  are B-85; a competing header at the tip's own height is still ignored until then.
- _header_at also serves older heights from the window.

Tests changed because the spec changed: the mainnet powLimit cannot be mined in a test, so
tests/unit/conftest.py swaps in a regtest limit at import time (the new tests put the real
one back); the _apply_header tests are async; the two _run_once tests serve the first
header's 9 predecessors; test_apply_header_skips_linkage_check_across_a_height_gap is
replaced by the jump tests, since that behaviour is exactly what the finding removed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-14 15:45:34 +02:00

3.1 KiB

ADR-52 — Le riorganizzazioni della catena si contengono invece di ignorarle

  • Stato: Accettata — implementazione da completare (B-82, B-85)
  • Area: Conferme e fiducia nella rete
  • 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

Le riorganizzazioni della catena si contengono invece di ignorarle (decisione del 2026-09-28). Tre misure:

  • si rilevano: il listener tiene gli ultimi 10 header e segue una biforcazione fino al punto comune; ogni riorganizzazione scrive chain_reorg_detected con profondità e altezze. Una biforcazione che non trova il punto comune entro 10 header è trattata come un header non valido (fine della sessione e rotazione, ADR-26);
  • si fermano quelle profonde: una profondità ≥ 2 mette in pausa la lotteria (paused_reason = 'reorg', ADR-28) finché l'operatore non la riprende;
  • si paga solo ciò che è in catena: prima di costruire un pagamento le monete dell'indirizzo del round si verificano con il quorum; i partecipanti la cui scommessa non c'è più diventano reorged_out e la ripartizione 70/30 si calcola su ciò che resta. Se manca la scommessa del vincitore, il pagamento è trattenuto (payout_blocked) e la lotteria va in pausa.

Regole in connessione-electrum.md e ciclo-di-vita-del-round.md (B-82, B-85).

  • Motivazione: la regola precedente («1 conferma, nessun rollback») presupponeva riorganizzazioni rare e innocue. Con la potenza di PLM in affitto una riorganizzazione è un attacco possibile, e senza queste misure una sola scommessa sparita rende il round impagabile per sempre (B-82), mentre una riorganizzazione di un blocco, normale in qualunque catena, veniva scambiata per un server ostile (B-74).
  • Alternative scartate: ignorare le riorganizzazioni (la regola precedente); un rollback completo (ricalcolare saldi già spesi e ripetere estrazioni già rivelate non è sempre possibile e sposterebbe denaro senza l'operatore); pausa anche per profondità 1 (una riorganizzazione di un blocco è frequente e non tocca i depositi a 6 conferme, ADR-06).
  • Conseguenze: un attacco al 51% resta possibile; queste misure lo rendono visibile, fanno sì che non blocchi la lotteria in modo irrecuperabile e limitano il danno a ciò che l'attaccante ha rimosso ([LIM-24]).

Codice: app/electrum/listener.py:ElectrumListener._apply_header · app/rounds/scheduler.py:RoundScheduler._trigger_payout · app/rounds/service.py:open_new_round_if_needed · Test: — Stato: da implementare (B-82, B-85) · Oggi: una riorganizzazione è seguita ma non registrata e non mette in pausa la lotteria; un header concorrente alla stessa altezza è ignorato; il pagamento non verifica le monete del round.