Files
plm-lottery/docs/adr/ADR-52-riorganizzazioni-catena-contengono-invece-ignorarle.md
T
davideandClaude Sonnet 5.5 50b68d2957 Follow and record chain reorganisations, pausing on deep ones (B-85, ELC-09, ELC-22, ELC-23, ELC-24, AUD-38, DAT-69)
A reorganisation was neither recorded nor acted upon, and a competing header at the tip's
own height was ignored for as long as the tip stood, leaving the listener on an orphan.

- A header at the height we hold with a different hash is followed through the same
  fork-point search as any other reorg (ELC-09) instead of being ignored; it still has to
  bring valid work and a connected chain.
- ElectrumListener._record_reorg writes `chain_reorg_detected` (depth, fork height, old and
  new tip height and hash) before the window moves, so a failed write ends the session and
  the next server's announcement of the same fork is recorded then. Depth 1 is a
  transaction of its own; depth >= 2 also pauses the lottery with paused_reason 'reorg'
  and writes `lottery_paused` in the same transaction (begin_immediate first).
- Docs: ELC-09/22/23/24, AUD-03/11/38, DAT-30/69, OPS-30, RND-04, ADR-26/52 lose their
  B-85 "da implementare" lines.

Tests changed because the spec changed: test_apply_header_ignores_a_competing_header_at_
the_current_tip_height encoded the B-64 behaviour that ELC-09 now reverses; it is replaced
by test_a_competing_header_at_the_tip_height_is_a_reorg_to_follow and the depth tests.

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

3.0 KiB

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

  • Stato: Accettata — implementazione da completare (B-82)
  • 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._record_reorg · app/rounds/scheduler.py:RoundScheduler._trigger_payout · app/rounds/service.py:open_new_round_if_needed · Test: tests/unit/test_electrum_listener.py Stato: da implementare (B-82) · Oggi: il pagamento non verifica le monete del round: le prime due misure (rilevare, fermare) sono attive.