Files
plm-lottery/docs/adr/ADR-03-ogni-round-ha-proprio-indirizzo-montepremi.md
davideandClaude Sonnet 5.5 fd6a91e93d Give every round its own pool address (B-80, RND-35, DAT-60, DAT-11, REG-14, SEC-08, BET-12, RND-22, WDR-14, SEC-43, API-23, API-36)
All bets of all rounds paid one address (m/84'/746'/0'/1/0), so its history
grew forever, other rounds' money and stray coins mixed with a round's own, and
the payout picked from everything it held.

- hd.py: derive_pool_key/derive_pool_address(round_id) on branch 2
  (m/84'/746'/0'/2/<round_id>); no argument is the reserve address 1/0.
  derive_round_pool_key checks the key against the address stored on the round,
  so a payout can never be signed for money its key does not control.
- rounds.pool_address (migration 477bddae1a84, existing rounds backfilled with
  the reserve address since that is where their bets went; add_column, not a
  batch alter, so the expression indexes stay): written in the transaction that
  inserts the round, once its id exists.
- place_bet pays round.pool_address; the payout reads, signs and takes change at
  the round's own address; own_address_for and bump_fee's _signing_context follow
  the round (confirmation poller and reconciler pass round_id).
- Withdrawals to any round pool address, the reserve address or fee_address are
  refused (withdrawal_to_platform_address, 400, all seven languages).
- GET /rounds/current and GET /admin/rounds expose pool_address.
- RND-22/DAT-11 stay "da implementare" for B-82: the payout still spends every
  confirmed coin at the round's address, not only the participants' outpoints
  (participants carry no bet_vout yet).
- tests/unit/conftest.py: every test now gets a throwaway master key. Opening a
  round derives an address, and tests that merely opened a round were silently
  reading the real key from the local .env.
- Existing tests changed because the spec changed: payout fixtures give their
  round a pool_address; the reconciler's address-cache test uses two payouts of
  one round (rows of different rounds no longer share an address);
  own_address_for now takes the round id.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-14 13:52:32 +02:00

37 lines
2.4 KiB
Markdown

# ADR-03 — Ogni round ha il proprio indirizzo del montepremi
- **Stato:** Accettata
- **Area:** Custodia, chiavi e indirizzi
- **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
**Ogni round ha il proprio indirizzo del montepremi**
(decisione del 2026-09-28), derivato dalla stessa master key sul ramo
`m/84'/746'/0'/2/<round_id>` e salvato sulla riga del round
(`rounds.pool_address`). Le scommesse di un round pagano solo il suo
indirizzo e il pagamento spende solo le monete di quell'indirizzo. Il vecchio
indirizzo unico `m/84'/746'/0'/1/0` diventa l'**indirizzo di riserva** del
montepremi, che riceve la riserva per l'RBF di ogni pagamento ([ADR-17](ADR-17-commissione-pagamento-esce-dalla-quota-vincitore.md));
i round aperti prima della modifica mantengono quell'indirizzo come
montepremi. Un prelievo verso un indirizzo del montepremi, di riserva o delle
commissioni è rifiutato. Il ramo `0` resta riservato agli utenti.
- *Motivazione:* con un indirizzo unico la cronologia cresce senza limite
(e con essa le risposte del server, B-75), il denaro di round diversi e le
monete estranee si mescolano, e un backup ripristinato ripete un round
contro ciò che il montepremi contiene oggi (B-90). Separare gli indirizzi
isola denaro, cronologia e pagamento di ogni round.
- *Alternative scartate:* un indirizzo unico con contabilità per round nel
database (non limita la cronologia e non isola le monete estranee);
consolidamento periodico dell'indirizzo unico (sposta il problema, non lo
toglie).
- *Conseguenze:* nessun segreto aggiuntivo (tutto deriva dalla master
key); una moneta estranea inviata all'indirizzo di un round chiuso resta
lì, visibile ma fuori da ogni pagamento; il margine fra partecipanti e
ingressi del pagamento ([ADR-21](ADR-21-tre-limiti-distinti-sul-numero-monete.md)) non si consuma più nel tempo ([LIM-17]).
Regole in [ciclo-di-vita-del-round.md](../ciclo-di-vita-del-round.md#4--pagamento)
e [scommesse-e-prelievi.md](../scommesse-e-prelievi.md#prelievo).
*Codice:* `app/wallet/hd.py:derive_pool_key` · `app/wallet/hd.py:derive_pool_address` · `app/wallet/hd.py:derive_round_pool_key` · `app/rounds/service.py:open_new_round_if_needed` ·
*Test:* `tests/unit/test_round_pool_address.py`, `tests/unit/test_pending_address.py`