Files
plm-lottery/docs/adr/ADR-26-validazione-degli-header-concatenata-senza-ricalcolo.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

2.8 KiB

ADR-26 — Validazione degli header concatenata, senza ricalcolo della difficoltà

  • Stato: Accettata — implementazione da completare (B-85)
  • 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

Validazione degli header concatenata, senza ricalcolo della difficoltà. Un header deve dichiarare un bersaglio non più facile del limite di rete (powLimit, 0x00000000ffff…), rispettare quel bersaglio e concatenarsi alla catena che teniamo: su un avanzamento di più blocchi si scaricano gli header intermedi e si verifica tutta la catena. Il listener tiene gli ultimi 10 header; un header che non si concatena alla punta ma a uno di essi è una riorganizzazione da seguire (ADR-52), non un server ostile. Un header senza hex è ignorato senza chiudere la sessione. Regole in connessione-electrum.md (B-74, B-85).

  • Motivazione: il controllo «rispetta il bersaglio che dichiara», da solo, non è una difesa: il bersaglio lo sceglie chi produce l'header, e con bits=0x207fffff un header passa senza lavoro. Un salto di più blocchi non collegato alla punta permetteva di fissare un'altezza enorme, che non regredisce mai, e congelare ogni estrazione (B-74). Trattare ogni riorganizzazione di un blocco come un server ostile chiudeva la sessione su tutti i server fino al blocco successivo.
  • Alternative scartate: validazione completa della catena con le regole di ricalcolo della difficoltà di PLM (fuori scopo: servirebbe la storia delle difficoltà, e il commit-reveal di ADR-24 toglie a un header fabbricato il potere di scegliere il vincitore).
  • Conseguenze: un header a difficoltà minima costa ancora poco lavoro ([LIM-14]); a fermare una catena fabbricata sono la concatenazione, il quorum (ADR-07) e il fatto che il seme dipende anche da server_seed.

Codice: app/electrum/listener.py:ElectrumListener._apply_header · app/rounds/draw.py:header_meets_its_own_target · Test: tests/unit/test_electrum_listener.py::test_a_multi_block_jump_is_validated_by_fetching_the_headers_in_between, tests/unit/test_electrum_listener.py::test_a_fork_is_walked_back_and_followed_instead_of_ending_the_session, tests/unit/test_draw.py::test_a_header_below_the_pow_limit_is_rejected_even_if_it_meets_its_own_target Stato: da implementare (B-85), per l'header concorrente alla stessa altezza · Oggi: un header concorrente alla stessa altezza della punta è ignorato invece di essere seguito.