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

39 lines
2.8 KiB
Markdown

# 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](ADR-52-riorganizzazioni-catena-contengono-invece-ignorarle.md)), non un server
ostile. Un header senza `hex` è ignorato senza chiudere la sessione. Regole
in [connessione-electrum.md](../connessione-electrum.md#4-header-validati-non-creduti)
(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](ADR-24-l-estrazione-commit-reveal-fra-server.md) 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](ADR-07-ogni-decisione-sposta-denaro-base-risposta.md)) 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.