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

2.4 KiB

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); 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) non si consuma più nel tempo ([LIM-17]). Regole in ciclo-di-vita-del-round.md e scommesse-e-prelievi.md.

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