davide/plm-lottery
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1433813ec7d8fbebb47085e7ec6ca36bca2dd9c6
plm-lottery/docs
T
History
davideandClaude Sonnet 5.5 8b182ac8b6 Snapshot the bet cost, fee address and pool cap onto the round at open, and cap the pool (B-95, RND-05, RND-06, RND-23, BET-20, BET-21, DAT-26, DAT-27, DAT-61, DAT-62, API-21, API-30, API-31, ADR-10, LIM-16) 
Only the duration and the cooldown (and, since B-73, the draw confirmations) were copied onto
the round when it opened. The cost of a bet and the fee address were read live, so an edit from
/admin in the middle of a round gave the players of that round different stakes for the same
chance and redirected the commission of the round in progress.

- `rounds.bet_amount_sats`, `rounds.fee_address` and `rounds.max_round_pool_sats` are copied from
  round_config in the transaction that opens the round (Alembic a7d3e9f15b48: plain add_column,
  existing rounds backfilled with the current configuration, i.e. what they were using; the
  expression indexes untouched). `place_bet` charges the round's cost, `_trigger_payout` pays the
  round's fee address (an empty one on the row still stops the payout, as before),
  `GET /rounds/current` advertises the round's cost while one is active and the configured one
  otherwise. The minimum withdrawal and the fee rate stay live, by design (ADR-20, ADR-10).
- `round_config.max_round_pool_sats` (0 = none, otherwise >= the bet cost and <= 4e15, in
  /admin and PUT/GET /admin/config): a bet is refused with `round_full` (params also carry
  `max_round_pool_sats`) once the sum of the round's participant rows, in-flight ones included,
  has reached the round's cap, before anything moves; the pool can exceed it by one bet at most.
  A cap under the bet cost is a 422 `max_round_pool_below_bet_amount`.
- PUT /admin/config's payability check (RND-40) now also judges a fee-rate change against the
  bet cost the round in progress opened with, which can be lower than the configured one.
- `error.round_full` no longer says "maximum of N players" (it also fires for the pool cap): the
  seven translations are generic.

Ambiguity resolved: the spec said the cap is snapshotted (RND-05, BET-20, ARC) in some places and
"applies immediately, also to the round in progress" in the round_config table of modello-dati;
the snapshot wins, with a column on `rounds` (modello-dati/api/guide-admin brought in line).

Tests changed because the spec changed: the payout fixtures seed the round's own fee address, and
the old "fee address missing" payout test now empties the round's address (clearing it in the
configuration mid-round must not stop the payout). New test_round_snapshot.py: the copy at open,
edits reaching only the next round, every bet of a round paying the same stake whether the cost
is raised or lowered meanwhile, the payout following the round's address (and surviving it being
cleared in the configuration), the cap (exactly at the cap is full, in-flight bets count, no cap,
a mid-round edit of the cap does not apply, the refused player's coins untouched), plus the route,
the admin bounds and the two 422s, the fee-rate check against the round's own cost, and the
migration backfill. Mutation-checked: charging the live cost, paying the live address, not
copying the cap and `>` instead of `>=` each fail tests.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-16 15:12:00 +02:00
..
adr
Snapshot the bet cost, fee address and pool cap onto the round at open, and cap the pool (B-95, RND-05, RND-06, RND-23, BET-20, BET-21, DAT-26, DAT-27, DAT-61, DAT-62, API-21, API-30, API-31, ADR-10, LIM-16)
2026-10-16 15:12:00 +02:00
api.md
Snapshot the bet cost, fee address and pool cap onto the round at open, and cap the pool (B-95, RND-05, RND-06, RND-23, BET-20, BET-21, DAT-26, DAT-27, DAT-61, DAT-62, API-21, API-30, API-31, ADR-10, LIM-16)
2026-10-16 15:12:00 +02:00
architettura.md
Snapshot the bet cost, fee address and pool cap onto the round at open, and cap the pool (B-95, RND-05, RND-06, RND-23, BET-20, BET-21, DAT-26, DAT-27, DAT-61, DAT-62, API-21, API-30, API-31, ADR-10, LIM-16)
2026-10-16 15:12:00 +02:00
audit-log.md
Snapshot the bet cost, fee address and pool cap onto the round at open, and cap the pool (B-95, RND-05, RND-06, RND-23, BET-20, BET-21, DAT-26, DAT-27, DAT-61, DAT-62, API-21, API-30, API-31, ADR-10, LIM-16)
2026-10-16 15:12:00 +02:00
ciclo-di-vita-del-round.md
Snapshot the bet cost, fee address and pool cap onto the round at open, and cap the pool (B-95, RND-05, RND-06, RND-23, BET-20, BET-21, DAT-26, DAT-27, DAT-61, DAT-62, API-21, API-30, API-31, ADR-10, LIM-16)
2026-10-16 15:12:00 +02:00
come-funziona.md
Make the draw a commit-reveal at a fixed, confirmed, quorum-agreed height with a public proof (B-73, RND-14 … RND-20, RND-33 … RND-37, DAT-61 … DAT-66, API-25, API-45, AUD-24 … AUD-27, AUD-37, ELC-15, SEC-56, ADR-24, ADR-25)
2026-10-14 16:29:09 +02:00
connessione-electrum.md
Credit deposits at deposit_confirmations and verify the round's coins with the quorum before paying (B-82, DEP-03, DEP-04, DEP-09, DEP-12, DEP-14, ELC-17, ELC-27, RND-21, RND-22, RND-25, RND-39, DAT-10, DAT-11, DAT-24, DAT-62, DAT-67, DAT-68, AUD-12, AUD-44, AUD-45, API-30, API-31, API-36, ADR-06, ADR-52)
2026-10-16 14:25:41 +02:00
guida-admin.md
Snapshot the bet cost, fee address and pool cap onto the round at open, and cap the pool (B-95, RND-05, RND-06, RND-23, BET-20, BET-21, DAT-26, DAT-27, DAT-61, DAT-62, API-21, API-30, API-31, ADR-10, LIM-16)
2026-10-16 15:12:00 +02:00
guida-utente.md
Credit deposits at deposit_confirmations and verify the round's coins with the quorum before paying (B-82, DEP-03, DEP-04, DEP-09, DEP-12, DEP-14, ELC-17, ELC-27, RND-21, RND-22, RND-25, RND-39, DAT-10, DAT-11, DAT-24, DAT-62, DAT-67, DAT-68, AUD-12, AUD-44, AUD-45, API-30, API-31, API-36, ADR-06, ADR-52)
2026-10-16 14:25:41 +02:00
limiti-noti.md
Snapshot the bet cost, fee address and pool cap onto the round at open, and cap the pool (B-95, RND-05, RND-06, RND-23, BET-20, BET-21, DAT-26, DAT-27, DAT-61, DAT-62, API-21, API-30, API-31, ADR-10, LIM-16)
2026-10-16 15:12:00 +02:00
modello-dati.md
Snapshot the bet cost, fee address and pool cap onto the round at open, and cap the pool (B-95, RND-05, RND-06, RND-23, BET-20, BET-21, DAT-26, DAT-27, DAT-61, DAT-62, API-21, API-30, API-31, ADR-10, LIM-16)
2026-10-16 15:12:00 +02:00
operativita.md
Drop a dust-sized change into the fee on an RBF bump and audit every refused bump (B-87, TX-11, TX-24, AUD-40, AUD-09, ADR-19)
2026-10-16 14:53:10 +02:00
piano-correzioni.md
Restructure docs: docs-first, SSOT, one ADR per decision
2026-10-14 12:05:57 +02:00
processo-di-modifica.md
Make the draw a commit-reveal at a fixed, confirmed, quorum-agreed height with a public proof (B-73, RND-14 … RND-20, RND-33 … RND-37, DAT-61 … DAT-66, API-25, API-45, AUD-24 … AUD-27, AUD-37, ELC-15, SEC-56, ADR-24, ADR-25)
2026-10-14 16:29:09 +02:00
README.md
Restructure docs: docs-first, SSOT, one ADR per decision
2026-10-14 12:05:57 +02:00
registrazione-e-depositi.md
Credit deposits at deposit_confirmations and verify the round's coins with the quorum before paying (B-82, DEP-03, DEP-04, DEP-09, DEP-12, DEP-14, ELC-17, ELC-27, RND-21, RND-22, RND-25, RND-39, DAT-10, DAT-11, DAT-24, DAT-62, DAT-67, DAT-68, AUD-12, AUD-44, AUD-45, API-30, API-31, API-36, ADR-06, ADR-52)
2026-10-16 14:25:41 +02:00
running-the-server.md
Restructure docs: docs-first, SSOT, one ADR per decision
2026-10-14 12:05:57 +02:00
scommesse-e-prelievi.md
Snapshot the bet cost, fee address and pool cap onto the round at open, and cap the pool (B-95, RND-05, RND-06, RND-23, BET-20, BET-21, DAT-26, DAT-27, DAT-61, DAT-62, API-21, API-30, API-31, ADR-10, LIM-16)
2026-10-16 15:12:00 +02:00
setup.md
Require a real Electrum quorum and allow certificate pinning (B-84, ELC-01, ELC-03, ELC-14, ELC-19, ARC-20, OPS-12)
2026-10-14 14:04:35 +02:00
sicurezza.md
Credit deposits at deposit_confirmations and verify the round's coins with the quorum before paying (B-82, DEP-03, DEP-04, DEP-09, DEP-12, DEP-14, ELC-17, ELC-27, RND-21, RND-22, RND-25, RND-39, DAT-10, DAT-11, DAT-24, DAT-62, DAT-67, DAT-68, AUD-12, AUD-44, AUD-45, API-30, API-31, API-36, ADR-06, ADR-52)
2026-10-16 14:25:41 +02:00
storico-bug.md
Snapshot the bet cost, fee address and pool cap onto the round at open, and cap the pool (B-95, RND-05, RND-06, RND-23, BET-20, BET-21, DAT-26, DAT-27, DAT-61, DAT-62, API-21, API-30, API-31, ADR-10, LIM-16)
2026-10-16 15:12:00 +02:00
transazioni-e-riconciliazione.md
Drop a dust-sized change into the fee on an RBF bump and audit every refused bump (B-87, TX-11, TX-24, AUD-40, AUD-09, ADR-19)
2026-10-16 14:53:10 +02:00

README.md

Documentazione di PLM Lottery

Questa cartella è la fonte di verità del progetto: si lavora docs-first (prima si scrive o si modifica la documentazione, poi il codice) e ogni informazione ha un solo proprietario (SSOT). Questo file è l'indice: da qui si raggiunge tutto il resto.

I tre principi

  1. Docs-first. Nessuna modifica di comportamento parte dal codice. Si modifica il requisito (o si scrive l'ADR, se è una scelta nuova), poi si implementa, poi si testa. Spec, codice e test entrano nello stesso commit.
  2. SSOT — un solo proprietario per ogni informazione. Il perché di una scelta sta in un ADR; il cosa verificabile in un requisito (PREFISSO-NN) del documento di dominio; il come nel codice; la cronologia dei difetti in storico-bug.md. Gli altri documenti rimandano all'ID, non ripetono il testo. Se due documenti dicono cose diverse, vince la specifica e si corregge l'altro.
  3. Un ADR per ogni funzionalità. Ogni funzionalità nuova inizia con un ADR in adr/ (modello: adr/TEMPLATE.md) che registra contesto, decisione, alternative scartate e conseguenze, e ne elenca i requisiti.

Dove si trova cosa

Domanda Dove
Perché è fatto così? Quali alternative sono state scartate? adr/ — indice per area e tabella funzionalità → ADR
Cosa deve fare esattamente il software? I documenti di dominio qui sotto (requisiti con ID stabile)
Quali limiti abbiamo accettato? limiti-noti.md (LIM-nn)
Che bug sono stati trovati/corretti? Quali restano aperti? storico-bug.md; i soli aperti in ../BUGS.md
In che ordine si implementano le correzioni aperte? piano-correzioni.md
Come si modifica la documentazione/il codice? processo-di-modifica.md
Come si installa, si avvia, si usa? Guide operative qui sotto

Specifica (documenti di dominio)

Punto d'ingresso narrativo: come-funziona.md.

Documento Prefisso Contenuto
registrazione-e-depositi.md REG, DEP Account, indirizzi, depositi, saldo
scommesse-e-prelievi.md BET, WDR Scommesse e prelievi
ciclo-di-vita-del-round.md RND Apertura, chiusura, estrazione, pagamento
transazioni-e-riconciliazione.md TX Ciclo di vita delle transazioni, RBF, riconciliazione
connessione-electrum.md ELC Accesso alla rete PLM e difese
architettura.md ARC Struttura del codice, processi, frontend, test
modello-dati.md DAT Tabelle, campi, stati, vincoli
api.md API Endpoint, risposte, codici di errore
sicurezza.md SEC Fiducia, chiavi, autenticazione, limiti sui tentativi
audit-log.md AUD Catalogo degli eventi di audit
operativita.md OPS Backup, riavvii, incidenti

Decisioni, limiti, storia

Documento Prefisso Contenuto
adr/ ADR Una decisione di progetto per file (53 al momento)
limiti-noti.md LIM Limiti accettati consapevolmente
storico-bug.md B-nn Tutti i bug trovati e corretti
piano-correzioni.md — Ordine di implementazione delle correzioni aperte

Guide operative (senza requisiti)

setup.md · running-the-server.md · guida-utente.md · guida-admin.md. Si aggiornano quando la specifica cambia qualcosa di visibile.

Lingua

La documentazione di docs/ è in italiano, per scelta esplicita; tutto il resto del repository (codice, commenti, commit, CLAUDE.md, BUGS.md) è in inglese.

Reference in new issue View Git Blame Copy Permalink