Author SHA1 Message Date
davideandClaude Sonnet 5 88221b0dbd Document the 2026-09-28 specification review and its fixes (B-73..B-97)
Fourth full audit, run against the docs/ specification instead of the code
alone, found logical flaws rooted in PLM's small hashrate (~22 TH/s): a
minable draw, no distinction between "never broadcast" and "unknown if
broadcast", an Electrum client that degrades as the pool address's history
grows, and 1-confirmation deposits on a chain where a reorg is rentable.

The spec now describes the target behaviour for every finding, marked
*Stato:* da implementare (B-nn) with an *Oggi:* line for what the code does
now; docs/piano-correzioni.md records the design decisions and the
implementation order. No code changed — this is spec-only, per B-nn
convention when a bug reveals the spec itself was incomplete.

Also documents, as an accepted-but-open risk (LIM-24), that the optional
jackpot cap (max_round_pool_sats) isn't tied to the cost of a 51% attack —
deferred, not decided.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-28 15:51:13 +02:00
davideandClaude Opus 5.5 61efbb0e37 Replace flowchart/ with a traceable specification in docs/
The two Mermaid diagrams under flowchart/ described the intended flow but
had drifted from the code and carried no link back to it. docs/ now holds
the specification instead: 15 Italian documents (flows, architecture, data
model, API, security, audit log, operations, decisions and limits, bug
history) with 472 numbered requirements, each pointing at the function
that implements it and the test that covers it. docs/processo-di-modifica.md
defines the ID convention and the spec -> code -> test change workflow, and
CLAUDE.md now names docs/ as authoritative.

Writing the spec from the code also corrected stale claims in CLAUDE.md
(B-41's get_history check, BUGS.md still tracking B-71/B-72, Cache-Control
scope, the error contract's bare-string exceptions) and in the operator
guides (payouts do retry, only `drawing` fails to resume, rounds do not
open without fee_address). The B-70 doc test now pins the prose in
docs/scommesse-e-prelievi.md instead of the deleted diagram.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 12:16:01 +02:00
31 changed files with 10317 additions and 311 deletions

No files matched your search

-1
View File
@@ -8,4 +8,3 @@ master.xprv.enc
*.egg-info/
logs/
data/
flowchart/*.pdf
+333 -1
View File
@@ -1,4 +1,9 @@
# BUGS.md — audit of 2026-08-03
# BUGS.md — open findings
Two audits currently have open entries: 2026-08-03 (B-71, B-72, below) and the
2026-09-28 specification review (B-73 … B-97, at the end of the file).
## Audit of 2026-08-03
Third full-codebase audit, opened after the 2026-07-26 (B-01 … B-24) and
2026-07-27 (B-25 … B-49) lists were emptied. Numbering continues from the last
@@ -65,3 +70,330 @@ only supported way to run the server (`docs/running-the-server.md` and README we
updated, this file was not). The venv genuinely is needed for tests, migrations and
the key scripts — the wording just needs to say that instead of implying a second
way to run the server.
---
# Audit of 2026-09-28 — specification review (B-73 … B-97)
Fourth audit, run against the new specification in `docs/` rather than the code
alone: four independent reviews (coin/chain mechanics, money state machine,
DevOps, spec cross-validation), with the critical claims re-verified in code.
The target behaviour of every entry below is now written into `docs/` as
requirements marked `*Stato:* da implementare (B-nn)`; the Italian overview, the
design decisions and the implementation order are in
[docs/piano-correzioni.md](docs/piano-correzioni.md). The code has **not** been
changed yet. Same convention as above: one commit per entry, with its own
regression test, spec + code + test together.
Design decisions taken with the owner on 2026-09-28 (they change existing
decisions, see `docs/decisioni-e-limiti.md`):
- **Draw by commit-reveal.** The winner must not be computable by anyone who
controls block production, since PLM's hashrate (~22 TH/s) is rentable.
- **Never release funds on doubt.** A money-moving row is rolled back only on proof
(an explicit rejection, or its inputs confirmed-spent elsewhere), never on a
timeout or on one server's silence.
- **One pool address per round**, so a round's money, history and payout are
isolated from every other round's.
- **Deposits need 6 confirmations** (configurable), everything else keeps 1: the
deposit is the only input a user can double-spend.
- **Contain reorgs instead of pretending they don't happen:** detect them, pause
on deep ones, and pay out only what is verifiably on chain.
## Critical
### B-73 — The draw can be steered by whoever produces or relays blocks
The seed is the block hash alone, so a miner holding tickets can withhold blocks
until one makes them win, and the active Electrum server can pick which real block
is used (it only has to skip announcing one; corroboration checks that the block
exists, not that it is the first after closing). The participant order uses the
server-only `broadcast_at` with no tie-break, so the draw is not reproducible.
Fix (commit-reveal): at round open generate a 32-byte `server_seed`, store it,
publish only `server_seed_hash = sha256(server_seed)`. On entering `drawing`, fix
the participant list ordered by confirmed bet txid (ascending), publish
`participants_hash = sha256` of the `txid:vout:address` lines, and fix
`draw_height = tip_at_close + 1` (persisted, never moved). Wait until the chain has
`draw_confirmations` (round_config, default 3, snapshotted at open) blocks from
`draw_height`, fetch the header *at `draw_height`* from every server, require the
quorum to agree (on disagreement wait and re-ask for the same height). Seed =
`sha256(server_seed || block_hash || participants_hash)` as an integer, index = seed
mod n. Reveal `server_seed` once the winner is persisted, and expose the full proof
at `GET /rounds/{id}/proof`.
### B-74 — Headers are accepted without a minimum-difficulty check, and a jump skips the linkage check
`header_meets_its_own_target` never compares `bits` against the chain's powLimit, so
a header with `bits=0x207fffff` passes with no work. A multi-block jump is not
linked to the current tip. A fake header at a huge height locks `tip_height` (it
never regresses) and freezes every draw. Conversely an ordinary 1-block reorg kills
the session on every server until the next block.
Fix: reject `bits` easier than powLimit; on any advance of more than one block fetch
the intermediate headers (`blockchain.block.headers`) and validate the chain; on a
linkage mismatch walk back up to 10 headers to find the fork point and follow the
reorg instead of ending the session (reorg handling: B-85).
### B-75 — Replies over 64 KiB kill the connection; the pool's history grows past that
`asyncio.open_connection` uses the default 64 KiB `StreamReader` limit; a longer
reply line raises `ValueError` in `_read_loop` and closes the connection. The
confirmation poller and the reconciler fetch the pool address's full history every
cycle, which passes 64 KiB after ~800 transactions: from then on every 10s poll
drops the only connection and payouts never confirm. A few hundred dust outputs sent
to any public address trigger the same thing on purpose.
Fix: 16 MiB reader limit; an oversized or malformed reply is a request error, not a
dead connection; UTXOs below `DUST_LIMIT_SATS` are ignored for crediting and
selection; per-round pool addresses (B-80) keep every address's history bounded.
### B-76 — An ambiguous broadcast is rolled back as if refused
`place_bet`/`request_withdrawal` release everything on *any* broadcast exception,
including the 15s timeout and a drop after the write. The tx may have propagated: the
bet's sats land in the pool with no participant, the withdrawal leaves while its row
says `failed`.
Fix: only an explicit JSON-RPC rejection releases immediately (an "already known /
already in mempool" rejection is success). A timeout or disconnect leaves the rows
`building` for the reconciler and the API answers 202 with the row in `building`.
After the active server accepts, the raw tx is also sent to every fallback
(best effort).
### B-77 — Only the latest txid is tracked, and `bump_fee` broadcasts before it persists
The poller and the reconciler match `current_txid` only (`replaced_by_txid` keeps
one step and nothing reads it). If an earlier version of a bumped tx confirms, it is
never seen; after 6h the row is abandoned — a confirmed bet's participant deleted, a
sent withdrawal marked failed, a paid payout rebuilt. `bump_fee` broadcasts in phase
2 and persists in phase 3, unconditionally, so a crash or a `database is locked` in
between, or an abandon that ran meanwhile, desynchronises DB and chain.
Fix: a `pending_transaction_txids` table holding every txid (and raw tx) a row ever
had; a confirmation of *any* of them confirms the row and retargets every reference
to it. The replacement is written (as a candidate) before it is broadcast; phase 3
updates with `WHERE status='pending' AND current_txid=<old>` and treats zero rows as
a conflict to reconcile.
### B-78 — Abandonment rests on one server's silence
`reconcile_once` abandons when the active server's `get_history` lacks the txid —
after 120s for `building` rows, which a restart onto a different server makes
likely, and all at once after a forward clock jump. It re-checks status but not the
txid, so it races the bumper. A `failed` row is never looked at again.
Fix: abandon only on proof — (a) an input confirmed-spent by a different txid
(quorum), or (b) no server of the quorum knows any txid of the row *and* a
rebroadcast of the latest raw tx to all servers is explicitly refused for
missing/spent inputs. A fee-related refusal is not proof (bump instead). The re-check
includes `current_txid`. `failed` rows stay watched for 14 days; a late confirmation
writes `pending_tx_resurrected` and pauses the lottery for the operator.
### B-79 — A payout normally has no change output, so it cannot be fee-bumped
The pool normally holds exactly the round's bet outputs, the payout spends them all
for exactly `pool_amount_sats`, so there is no change and `bump_fee` can never help.
A payout stuck in a mempool is also never abandoned (the server still knows it): the
round stays in `paying_out` and no new round opens.
Fix: every payout carries a **bump reserve** output of
`max(DUST_LIMIT_SATS, estimated_vsize × 10 sat/vB)`, taken from the commission share
and paid to the pool reserve address (`m/84'/746'/0'/1/0`, the old pool address);
RBF shrinks that output. `rounds_can_open` refuses a configuration in which a
one-participant round could not cover winner fee + reserve + dust commission.
### B-80 — One pool address for every round
All bets of all rounds pay one address: its history grows forever (B-75), stray
money and other rounds' money mix with this round's, and a restored backup replays a
round against whatever the pool holds now.
Fix: each round gets its own pool address `m/84'/746'/0'/2/<round_id>`, stored on
the round (`rounds.pool_address`); bets pay it, the payout spends only its UTXOs.
Rounds opened before this change keep the old address. Withdrawals to any pool,
reserve or fee address are refused.
### B-81 — `drawing` wedges on any exception, not only on restart
The participant snapshot and `tip_at_close` live only in memory; `_tick` skips
`drawing`. Any exception during the wait (`database is locked` writing an audit row,
a malformed header) leaves the round in `drawing` forever.
Fix: persist `draw_height`, `participants_hash` and each participant's
`draw_position` when entering `drawing`; `_tick` re-enters the wait for a round in
`drawing`, idempotently. Together with B-73's fixed height and committed seed, a
resumed draw always yields the same winner.
### B-82 — A deposit reorged out after a bet leaves the round unpayable
Deposits are credited at 1 confirmation. A user can bet, then (if they lost)
double-spend the deposit the bet spent with a private chain: the bet disappears but
its participant stays `confirmed` and counted, and the payout fails "insufficient
pool UTXOs" forever with every other player's money stuck. Immature coinbase outputs
are also credited at 1 confirmation (maturity is 120).
Fix: deposits credited at `deposit_confirmations` (round_config, default 6),
coinbase outputs at 120. Before building a payout the round address's UTXOs are
verified with the quorum; participants whose bet outpoint is gone are marked
`reorged_out` and the 70/30 split is computed on what is actually there. If the
winner's own bet is gone the payout is held (`payout_blocked`) and the lottery pauses.
## High
### B-83 — Confirmations and reinstatement trust the active server alone
`poll_once` marks a tx confirmed on one server's `height > 0`, and
`reinstate_reappeared_utxos` restores a UTXO on its word, so a hostile active server
can report a never-relayed payout as confirmed (winner unpaid) or a phantom bet.
Broadcasts go to the active server only.
Fix: a confirmation is accepted once the quorum returns a valid merkle proof
(`blockchain.transaction.get_merkle`) against a header we hold; reinstatement needs
the same quorum as a credit (B-59); broadcasts fan out (B-76).
### B-84 — The quorum can be one server, or none, silently
An empty `ELECTRUM_FALLBACK_SERVERS` (the `.env.example` default) disables every
corroboration; with fallbacks, the majority is over whoever answers, so one reachable
fallback decides. TLS certificates are not verified.
Fix: at least 2 fallbacks and at least 2 responders for every corroboration, or the
server refuses to start (override `ALLOW_NO_QUORUM=true`, development only); optional
certificate pinning per endpoint (`host:port:pin=<sha256>`).
### B-85 — Reorgs are neither followed nor surfaced
Nothing detects a reorg; a 1-block reorg is treated as a hostile server (B-74).
Fix: the listener keeps the last 10 headers; a fork is followed to its fork point, a
`chain_reorg_detected` audit row records depth and heights, and a depth ≥ 2 pauses
the lottery (`paused_reason = 'reorg'`) until the operator resumes it.
### B-86 — A connected but stalled server is never replaced
`ping` keeps succeeding while the server stops following the chain; nothing compares
tip progress with the other servers, and a restart goes back to the primary.
Fix: if the tip has not advanced for 360s and any other server reports a higher tip,
rotate. `GET /health/ready` and `/admin` expose connection state, endpoint and
last-header age (B-92).
### B-87 — The RBF bump can leave a dust change output
`bump_fee` only requires change > fee delta. A 294-sat change (full-balance
withdrawal) becomes ~153 sat after the minimum bump and every replacement is refused
by relay, every 30s.
Fix: when a bump would leave change below `DUST_LIMIT_SATS`, the change output is
dropped and its value goes to the fee (the replacement is then final); `RbfError`
and every refused bump write a `rbf_bump_failed` audit row.
### B-88 — SQLite transactions are not what the code assumes
pysqlite's legacy mode issues `BEGIN` only at the first DML, so reads before it are
not isolated, the "write-snapshot conflict" handled in `place_bet` cannot happen, and
lock waits surface as `database is locked` after 5s in arbitrary places.
`synchronous=NORMAL` can lose the last commits on power loss (e.g. a registration,
reusing its derivation index).
Fix: `BEGIN IMMEDIATE` for every money-moving transaction, `synchronous=FULL`,
explicit handling of busy timeouts after a broadcast.
### B-89 — Key problems surface only at first use
Startup checks only that the key file exists and `XPRV_ENCRYPTION_KEY` is non-empty;
a wrong key or a different xprv is found at the first registration or payout, and a
different xprv silently moves the pool address. The scripts accept any xprv and write
files `0644`.
Fix: at startup decrypt the key and check the pool reserve address and a sample of
stored user addresses; refuse to serve on mismatch. The scripts refuse an xprv whose
derived addresses differ from the DB's and write `0600`.
### B-90 — Restoring a backup is unsafe
A restored DB reopens rounds that were already drawn and paid, and reassigns the
derivation indexes of users registered after the backup to new users — who then
receive the old users' funds.
Fix: `START_PAUSED=true` starts with the lottery paused; at startup the next 20
indexes past the highest assigned are checked for on-chain history and, if any has
some, registration is refused until the operator reconciles (`restore_gap_detected`);
per-round addresses (B-80) and B-82's pre-payout check make a replayed round
unpayable instead of payable twice.
### B-91 — Host and supply-chain hardening
The container runs as root, `.env` and key files are world-readable, dependencies are
unpinned `>=` and base images float, secrets sit in env vars visible to
`docker inspect`.
Fix: non-root `USER`, `0600`/`0700` permissions, a hash-pinned lock file,
digest-pinned base images, the Fernet key mounted as a file rather than an env var.
## Medium
### B-92 — No health, readiness or real audit browsing
`/health` always answers ok; nothing exposes Electrum state; the audit endpoint
returns only the latest 500 rows unfiltered; registration writes no audit row; the
access log records Caddy's IP; app logs go only to the file.
Fix: `GET /health/ready` (Electrum connected, tip age < 360s, scheduler heartbeat <
30s) used as the container healthcheck; Electrum status in `/admin`; audit filters by
event type, round, user and time, with pagination; `user_registered` audit row with
index and address; uvicorn proxy headers from Caddy only; logs also to stdout.
### B-93 — Deploys and rollbacks
A deploy with an open SSE stream never shuts down gracefully (uvicorn waits, Docker
kills after 10s); an older image cannot start on a newer DB; images are untagged;
`SITE_ADDRESS` passed per command reverts to `localhost` on the next plain
`docker compose up`.
Fix: close SSE streams on shutdown, `stop_grace_period: 30s`, await task
cancellation; tag images per release; `SITE_ADDRESS` in `.env` with `${SITE_ADDRESS:?}`;
documented pre-deploy backup and downgrade procedure.
### B-94 — Account and endpoint abuse limits
`change-password` has no rate limit, no audit and no maximum length; login fields
have no length bounds; `POST /bug-reports` is anonymous and unlimited;
`GET /admin/users` has no pagination; admin, SSE and framework errors are bare
strings; static JS/CSS have no `Cache-Control`.
Fix: throttle and audit (`password_changed`) the password change, cap every
credential field at 256, rate-limit bug reports per IP, paginate the user list,
structured errors everywhere, `Cache-Control: no-cache` on static files.
### B-95 — Round parameters read live instead of snapshotted
Only duration and cooldown are snapshotted at open; bet amount, `fee_address` and the
new `draw_confirmations` are read live, so an edit mid-round changes the round in
progress (e.g. redirects its commission).
Fix: snapshot `bet_amount_sats`, `fee_address` and `draw_confirmations` on the round
at open. Optional per-round cap `max_round_pool_sats` (round_config, 0 = disabled):
once reached, further bets get `round_full`.
### B-96 — Smaller state inconsistencies
A reduced full-balance withdrawal is not re-checked against the minimum; an abandoned
payout leaves `winner_amount_sats`/`fee_amount_sats` set; a promoted payout writes no
`payout_sent` and a promoted bet no `bet_placed`; the reconciler pings SSE for every
row it checks; concurrent refreshes of one user can collide on the unique outpoint
and end the Electrum session; `listener.client` is read outside the per-user lock;
a bet covered only by pending change gets `insufficient_balance` instead of
`balance_pending_confirmation`.
Fix: each as described, one regression test per item.
### B-97 — Migrations can silently drop the expression indexes
`batch_alter_table` on SQLite rebuilds the table and drops `ix_rounds_single_active`
and `ix_users_username_lower` with only a warning; autogenerate ignores them; no test
runs the migrations.
Fix: a test that runs `alembic upgrade head` on an empty DB and asserts both indexes
exist; any batch migration on those tables recreates them explicitly.
+10 -10
View File
@@ -12,11 +12,11 @@ All 10 stages of the original build order are code-complete and unit-tested —
Verified on mainnet with real money: registration + address derivation, deposit crediting (1-conf), a real 10 PLM bet (broadcast → confirmed → change credited back), and one full round cycle (close → draw on a real block hash → 70/30 payout with sat math checked against the broadcast tx → confirmation → close → next round auto-opened). **Withdrawal and the RBF bump path have never been exercised against a live broadcast** — unit-tested only.
Two full-codebase audits — 2026-07-26 (24 findings, 5 critical) and 2026-07-27 (25 more, B-25 … B-49) — are **all fixed** as of 2026-07-27, each with its own regression test. They were tracked in a `BUGS.md` that was deleted once the list emptied, so the ~276 `B-nn` markers left in comments across the code are pointers into git history (`git log --all --grep 'B-nn'` finds the commit that fixed one, and `git show f1a1145:BUGS.md`-style the file as it stood). A closed list is not the same as no bugs: the suite is unit-only (`tests/integration/` is empty), and withdrawal and the RBF bump have never been live-broadcast. "Known gaps" at the end of this file is for limitations accepted **by design** instead. A new finding gets the next B-nn, in its own commit with its own regression test.
Two full-codebase audits — 2026-07-26 (24 findings, 5 critical) and 2026-07-27 (25 more, B-25 … B-49) — are **all fixed** as of 2026-07-27, each with its own regression test. A third audit (2026-08-03, B-52 … B-72) and a fourth, the 2026-09-28 specification review (B-73 … B-97: draw manipulation, ambiguous broadcasts, single-txid tracking, single-server abandonment, the 64 KiB Electrum reply limit, unbumpable payouts, 1-conf deposit reorgs, ops hazards), live in the tracked [BUGS.md](BUGS.md), which lists only what is still **open** (B-71 … B-97 at the time of writing). The spec in `docs/` already describes the *target* behaviour for all of them — every affected requirement is marked `*Stato:* da implementare (B-nn)` with an `*Oggi:*` line saying what the code does now, so read both before assuming a requirement is implemented; the design decisions and the implementation order are in [docs/piano-correzioni.md](docs/piano-correzioni.md); the full history of every B-nn, open and closed, is in [docs/storico-bug.md](docs/storico-bug.md). Closed findings leave the file, so the ~276 `B-nn` markers left in comments across the code are pointers into git history (`git log --all --grep 'B-nn'` finds the commit that fixed one, and `git show f1a1145:BUGS.md`-style the file as it stood). A closed list is not the same as no bugs: the suite is unit-only (`tests/integration/` is empty), and withdrawal and the RBF bump have never been live-broadcast. "Known gaps" at the end of this file is for limitations accepted **by design** instead. A new finding gets the next B-nn, in its own commit with its own regression test.
Before writing code, read the "Architecture" section below in full plus the diagrams in [flowchart/](flowchart/): [platform-overview.mmd](flowchart/platform-overview.mmd) (the 5-phase flow) and [round-lifecycle.mmd](flowchart/round-lifecycle.mmd) (the round/draw lifecycle). Every node **and edge label** (conditions, retries, loops) is a behaviour that must be implemented as described. Regenerate the companion PDFs with `flowchart/render-pdf.sh <file>.mmd` after editing either.
**[docs/](docs/) is the specification, and it is authoritative.** Every verifiable rule there has a stable requirement ID (`RND-04`, `BET-02`, …) with `*Codice:*`/`*Test:*` pointers to what implements it; the index is [docs/come-funziona.md](docs/come-funziona.md) and the ID convention and change workflow are in [docs/processo-di-modifica.md](docs/processo-di-modifica.md). A behaviour change starts in the spec: edit or add the requirement, implement it, cite the ID in the test docstring and the commit message, and ship spec + code + test in one commit. If this file and the spec disagree, the spec wins and this file is the one to fix. Before writing code, read the relevant spec documents and the "Architecture" section below.
Human-facing guides are in [docs/](docs/), in Italian by explicit request (an exception to the English-only rule): [setup.md](docs/setup.md), [running-the-server.md](docs/running-the-server.md), [guida-utente.md](docs/guida-utente.md), [guida-admin.md](docs/guida-admin.md). README's Quick start and `docs/running-the-server.md` are Docker-only, matching this file — a bare `uvicorn --reload` workflow was removed from both (B-44).
Human-facing guides are in [docs/](docs/), in Italian by explicit request (an exception to the English-only rule): the specification starting at [come-funziona.md](docs/come-funziona.md), the operational guides [setup.md](docs/setup.md), [running-the-server.md](docs/running-the-server.md), [guida-utente.md](docs/guida-utente.md), [guida-admin.md](docs/guida-admin.md). README's Quick start and `docs/running-the-server.md` are Docker-only, matching this file — a bare `uvicorn --reload` workflow was removed from both (B-44).
## Commands
@@ -97,7 +97,7 @@ Source of truth: the `PalladiumWallet` repo — [ChainProfiles.cs](../PalladiumW
`GET /rounds/current`'s `jackpot_sats` is the winner's 70% share, not the whole pool, and the pool is summed from the participants' actual `bet_amount_sats` (each already net of its own bet fee) rather than `count × current bet amount` — editing the bet amount mid-round must not move an in-progress round's advertised jackpot (B-11). It counts **confirmed participants only** (B-65), matching what the draw picks from and what the payout can spend, with `pending_participant_count`/`pending_jackpot_sats`/`has_pending_bets` reporting the in-flight bets alongside — inclusive figures, not deltas, exactly like `pending_balance_sats` (see "Balance display"). `/`'s round card shows the confirmed numbers big and the difference as an amber "+N in attesa" suffix, so a player who just bet sees their own bet immediately without the advertised jackpot ever exceeding what will be paid.
**Round cooldown** (`round_cooldown_seconds`, not in the original flowchart): gap after a round closes before the next opens, so players can see the outcome.
**Round cooldown** (`round_cooldown_seconds`, not in the original design): gap after a round closes before the next opens, so players can see the outcome.
**Maintenance pause** (`RoundConfig.paused`): toggled by `POST /admin/pause` / `POST /admin/resume` — a deliberate operator action with its own "Manutenzione" card in `/admin`, audit-logged `lottery_paused`/`lottery_resumed`, not a plain config field. It only stops the *next* round from opening (`rounds/service.py:open_new_round_if_needed`); a round in progress still closes, draws and pays its winner. Exposed as `lottery_paused` so `/` can show a banner.
@@ -142,13 +142,13 @@ One connection serves everything — deposit credits, broadcasts, confirmations,
- **Bounded requests** (`_REQUEST_TIMEOUT_SECONDS` = 15s); a timeout tears the connection down. Unbounded waits used to hang `POST /bets` *while holding the per-user lock*, and could stall the confirmation poller permanently.
- **The drop is observable**: `client.wait_closed()` resolves when the read loop dies, and `_run_once` races it against the notification consumers and a 60s `server.ping`. Without it the listener sat on queues nobody would ever fill while `listener.client` still looked alive.
- **Headers are validated, not trusted** (`_apply_header`): the tip never regresses, a header must meet the difficulty target it claims, and a single-block advance must chain from the current tip's hash. Failure raises `HeaderValidationError`, which ends the session like a dropped connection and rotates away — that header is the draw's only entropy, so a fabricated one picks the winner. Two more headers are refused *without* ending the session, since neither implies a hostile server (B-64): one at a height we already hold a header for (a reorg at the tip, or one server disagreeing — the hash committed to for a height is never swapped under us, and `corroborate_header` is what catches us holding an orphan), and one carrying no `hex` at all (nothing to validate or draw from, and applying the height alone would break the `tip_height`/`tip_header_hex` pairing). `_run_once` separately refuses to publish the client while *no* tip is known, so the ignore-don't-kill choice can't reopen B-63.
- **A quorum corroborates every money-moving decision** (`_corroborate_majority`, 10s per server, asking only the *other* endpoints — never the active one, which is what a MITM controls): `corroborate_header` before a block seeds the draw (B-28), `corroborate_utxo_spent` before a UTXO missing from one `listunspent` is written off as externally spent (B-29), and `corroborate_utxo_credit` before a new outpoint credits a balance — same outpoint, same amount, confirmed (B-59). Balances move in both directions, so both directions need the same quorum. No fallbacks configured → returns True (the accepted risk of an empty `ELECTRUM_FALLBACK_SERVERS`); nobody answers → returns **False**, since an unreachable network proves nothing. A failed credit corroboration only *delays*: `find_new_credit_candidates` re-offers the outpoint on the next refresh or `DepositReconciler` sweep.
- **A quorum corroborates every money-moving decision** (`_corroborate_majority`, 10s per server, asking only the *other* endpoints — never the active one, which is what a MITM controls): `corroborate_header` before a block seeds the draw (B-28), `corroborate_utxo_spent` before a UTXO missing from one `listunspent` is written off as externally spent (B-29), and `corroborate_utxo_credit` before a new outpoint credits a balance — same outpoint, same amount, confirmed (B-59). Balances move in both directions, so both directions need the same quorum — with one exception today: `deposits/service.py:reinstate_reappeared_utxos` restores a reappeared UTXO on the active server's word alone. No fallbacks configured → returns True (the accepted risk of an empty `ELECTRUM_FALLBACK_SERVERS`); nobody answers → returns **False**, since an unreachable network proves nothing. A failed credit corroboration only *delays*: `find_new_credit_candidates` re-offers the outpoint on the next refresh or `DepositReconciler` sweep.
On reconnect `_subscribe_all_users` runs as its own task with bounded concurrency (`_RESUBSCRIBE_CONCURRENCY` = 20) rather than inline and serially — otherwise a large user base froze `tip_height`, and with it an in-flight draw, for the whole sweep (B-31); one user's failure is logged and skipped. `address_for_new_user` (called right after registration) is best-effort by design: on failure that address stays unsubscribed until the next reconnect or `DepositReconciler` sweep.
## Architecture — the 5 phases
Diagrams: [platform-overview.mmd](flowchart/platform-overview.mmd), [round-lifecycle.mmd](flowchart/round-lifecycle.mmd).
Diagrams: [come-funziona.md](docs/come-funziona.md) (the 5 phases), [ciclo-di-vita-del-round.md](docs/ciclo-di-vita-del-round.md) (the round/draw lifecycle).
**REG** — on signup the server derives a P2WPKH address via BIP84 (`m/84'/coin'/0'/0/index`, one index per user) from the encrypted master xprv. Permanent, and doubles as deposit address, winnings address and withdrawal change address.
@@ -166,7 +166,7 @@ Diagrams: [platform-overview.mmd](flowchart/platform-overview.mmd), [round-lifec
**WITHDRAW** — the only way out to an external address: PSBT user-address → external + change back to the user, fee deducted from the withdrawn amount, same RBF pattern. A full-balance withdrawal moves `balance - DUST_LIMIT_SATS` so the change output (and with it the ability to fee-bump) always exists — `Withdrawal.amount_requested_sats` vs `amount_sent_sats` is what records the difference (B-62).
PLAY and WITHDRAW share a **per-user lock** (`tx/locks.py`): a bet-build and a withdrawal-build can never be in flight at once, since both spend the same UTXO set. That is the *only* mutual exclusion between them (B-70): a withdrawal is accepted while a bet is still unconfirmed, as long as confirmed, unspent UTXOs cover it — the lock plus `select_utxos` skipping anything already marked `spent_txid` is what prevents the two from picking the same input, so freezing the rest of the balance for a block on top of that would restrict the user without protecting anything.
PLAY and WITHDRAW share a **per-user lock** (`tx/locks.py`): a bet-build and a withdrawal-build can never be in flight at once, since both spend the same UTXO set. That is the *only* mutual exclusion between them (B-70): a withdrawal is accepted while a bet is still unconfirmed, as long as confirmed, unspent UTXOs cover it — the lock plus `place_bet`/`request_withdrawal` only ever offering `select_utxos` UTXOs with `spent_txid IS NULL` is what prevents the two from picking the same input, so freezing the rest of the balance for a block on top of that would restrict the user without protecting anything.
**Three separate on-chain confirmations sit between the timer hitting zero and the payout landing** — a common point of confusion:
1. **Last bet's confirmation** — the round doesn't even flip to `"closing"` until every broadcast bet has 1 conf (`_tick`'s `pending_count` check). May already have happened before the deadline.
@@ -197,7 +197,7 @@ Everything that spends money is written **before** it is broadcast and resolved
- `building` is written first, UTXOs already marked `spent_txid`, and committed *before* the broadcast (`bets/service.py`, `withdrawals/service.py`, and `scheduler.py:_trigger_payout` — the same shape in four phases, so no DB session is ever held across a network call). A crash in that window leaves evidence, not coins spent on-chain with no record.
- A refused broadcast releases the UTXOs, restores the balance, removes the participant (or marks the withdrawal `failed`), audit-logs, and raises `broadcast_failed` → **502**, since the network refused it, not the caller.
- `tx/reconcile.py` asks the chain about anything still `building`/`pending`: present → promote; positively unknown → `failed` with a `failure_reason`, inputs released, domain row rolled back, `pending_tx_abandoned` logged. Grace differs by state (120s `building`, 6h `pending`, so the bumper gets its attempts first). A *transport* failure never abandons anything — only a server that positively doesn't know the tx, currently inferred by substring-matching the error text (fragile — B-41).
- `tx/reconcile.py` asks the chain about anything still `building`/`pending`: present → promote; positively unknown → `failed` with a `failure_reason`, inputs released, domain row rolled back, `pending_tx_abandoned` logged. Grace differs by state (120s `building`, 6h `pending`, so the bumper gets its attempts first). A *transport* failure never abandons anything — only a server that positively doesn't know the tx, established by the tx's txid being absent from `get_history` of the address it spends from/pays back to (`app/tx/pending_address.py:own_address_for`) — B-41 replaced the old substring-matching on error text. A tx still in the server's mempool is never abandoned, so in practice that is what bounds the `closing` wait.
`UtxoEvent.spent_txid` must always equal the tx's *current* txid, so `bump_fee` retargets it along with `RoundParticipant.bet_txid`, `Withdrawal.txid` and `Round.payout_txid` on every bump. `broadcast_at` is the *first* broadcast and is never rewritten (the reconciler's abandon clock measures from it); `last_broadcast_at` is what a bump updates and `should_bump` reads. Confirmation handlers key off immutable ids (`round_id`/`user_id`, `withdrawal_id`), never the txid, which changes under them.
@@ -207,7 +207,7 @@ Everything that spends money is written **before** it is broadcast and resolved
## Frontends
Two static SPAs served directly by FastAPI (`main.py` mounts `app/static/` and adds routes for `/admin`, `/guida`, `/report-bug`) — no build step, no framework, no bundler, `Cache-Control: no-store`.
Two static SPAs served directly by FastAPI (`main.py` mounts `app/static/` and adds routes for `/admin`, `/guida`, `/report-bug`) — no build step, no framework, no bundler. `Cache-Control: no-store` is set on the four HTML routes only; the JS/CSS under the `StaticFiles` mount get ETag/Last-Modified and no Cache-Control.
- **`/`** — end-user test UI: register/login, then a navbar dashboard with four panels (Deposito with a QR from `GET /qr/{address}`, Bet, Prelievo, Profilo — account info + self-service password change via `POST /users/me/change-password`), above a persistent round-status card and the chain-status bar with the language switcher.
- **`/admin`** — gated by a token screen (not a login: just `X-Admin-Token` vs `ADMIN_TOKEN`), then six sections each backed by its own `/admin/*` endpoint: Parametri (`RoundConfig` + the Manutenzione card), Utenti (list, WIF privkey export, password reset — both audit-logged), Round, Transazioni pendenti, Audit log, Bug report (triage `open` → `read` → `resolved`, audit-logged `bug_report_status_changed`); plus a live Electrum/tip-height pill. **Deliberately not linked from `/`** in either direction.
@@ -224,7 +224,7 @@ Both talk to the same JSON API; there's no admin/user API split beyond `require_
- `/report-bug`'s `bugReport.englishNotice` string is itself translated into all 7 languages — it just always *says*, in whichever language the visitor reads, to write the actual bug description in English (so the admin panel, which is Italian-operator-facing and untranslated, doesn't end up with reports in 7 different languages).
- `/admin` is intentionally untranslated (operator-facing, Italian), as is `/guida`.
**API error contract** (`app/api/errors.py`) — the API is single-language by design. Failures answer with a structured `detail`: `{"code", "message", "params"}`, where `message` is English for non-dashboard consumers and `code` is what the frontend maps to `error.<code>` in `i18n.js` (falling back to `message` for an unknown code). `BetError`/`WithdrawalError` subclass `ApiError` and carry the code from where the failure happens. Even the catch-all 500 handler answers in that shape (`internal_error`), so clients never special-case unexpected errors, and the exception text stays in `logs/app.log`. Adding a user-facing error: give it a code, add `error.<code>` to all 7 languages, and pass values through `params` (amounts as `*_sats` — the frontend derives a `*_plm` sibling) instead of baking them into English text.
**API error contract** (`app/api/errors.py`) — the API is single-language by design. Failures answer with a structured `detail`: `{"code", "message", "params"}`, where `message` is English for non-dashboard consumers and `code` is what the frontend maps to `error.<code>` in `i18n.js` (falling back to `message` for an unknown code). `BetError`/`WithdrawalError` subclass `ApiError` and carry the code from where the failure happens. Even the catch-all 500 handler answers in that shape (`internal_error`), so clients rarely special-case unexpected errors (the exceptions — `require_admin`'s 403/404s, the SSE 503, FastAPI's own 401/404/405/422 — still carry a bare-string or list `detail`; see `docs/api.md`), and the exception text stays in `logs/app.log`. Adding a user-facing error: give it a code, add `error.<code>` to all 7 languages, and pass values through `params` (amounts as `*_sats` — the frontend derives a `*_plm` sibling) instead of baking them into English text.
## Non-obvious domain decisions
+1 -1
View File
@@ -41,7 +41,7 @@ domain).
## Documentation
- [CLAUDE.md](CLAUDE.md) — architecture, commands, domain decisions, known gaps (for anyone/anything working on the code)
- [flowchart/](flowchart/) — the source-of-truth flow diagrams the implementation follows node-by-node: [platform-overview.mmd](flowchart/platform-overview.mmd) (the 5-phase flow) and [round-lifecycle.mmd](flowchart/round-lifecycle.mmd) (the round/draw lifecycle)
- [docs/come-funziona.md](docs/come-funziona.md) — the specification (Italian): how the platform works, with diagrams and traceable requirement IDs; it indexes every per-topic document (flows, architecture, data model, API, security, audit log, operations, decisions and limits, bug history). [docs/processo-di-modifica.md](docs/processo-di-modifica.md) describes how a change goes from the spec to the code
- [docs/setup.md](docs/setup.md) — one-time setup (secrets, master key, migrations)
- [docs/running-the-server.md](docs/running-the-server.md) — how to launch it with Docker+Caddy (dev vs. production TLS)
- [docs/guida-utente.md](docs/guida-utente.md) — end-user guide to the test UI (Italian)
+3 -3
View File
@@ -78,9 +78,9 @@ def header_meets_its_own_target(header_hex: str) -> bool:
def draw_winner(participants: list[str], block_hash_hex: str) -> str:
"""v1 draw algorithm (flowchart.mmd, node R): seed = block hash as an integer,
index = seed mod participant_count, winner = participants[index]. Anyone can
recompute and verify it from public data. Deliberately simple/replaceable."""
"""v1 draw algorithm (docs/ciclo-di-vita-del-round.md): seed = block hash as an
integer, index = seed mod participant_count, winner = participants[index]. Anyone
can recompute and verify it from public data. Deliberately simple/replaceable."""
if not participants:
raise ValueError("no participants to draw from")
seed = int(block_hash_hex, 16)
+4 -4
View File
@@ -39,10 +39,10 @@ _DRAW_STALL_THRESHOLD_SECONDS = 360 # a few multiples of PLM's 120s block time
class RoundScheduler:
"""Background task implementing flowchart.mmd's DRAW subgraph: closes the
round on its timer (once any in-flight bets have confirmed), draws a winner
from the next confirmed block, and broadcasts the payout. The next round only
opens once this one is fully closed (rounds/service.get_active_round)."""
"""Background task implementing the round lifecycle (docs/ciclo-di-vita-del-round.md):
closes the round on its timer (once any in-flight bets have confirmed), draws a
winner from the next confirmed block, and broadcasts the payout. The next round
only opens once this one is fully closed (rounds/service.get_active_round)."""
def __init__(self, session_factory: async_sessionmaker, listener: ElectrumListener):
self._session_factory = session_factory
+1 -1
View File
@@ -51,7 +51,7 @@ def derive_user_wif(derivation_index: int) -> str:
def derive_pool_key() -> HDKey:
"""The "indirizzo padre" from the flowchart: all bets are sent here, and
"""The pool key ("indirizzo padre"): all bets are sent here, and
payouts are signed with this key. Reserved on branch 1 of the account (branch 0
is user addresses), index 0 — not a spec requirement, an implementation choice
to keep it in the same encrypted master key rather than a separate secret."""
+1038
View File
File diff suppressed because it is too large. Load diff
+1002
View File
File diff suppressed because it is too large. Load diff
+443
View File
@@ -0,0 +1,443 @@
# Registro di audit
Il registro di audit è la traccia, nel database, di ciò che ha mosso denaro o
cambiato la configurazione: scommesse, prelievi, depositi accreditati,
estrazioni, pagamenti, interventi dell'operatore. È il primo posto da guardare
per ricostruire cosa è successo dopo un problema, ed è l'unica forma di
responsabilità che esiste per le azioni dal pannello admin, che non ha
un'identità per singolo operatore (vedi [sicurezza.md](sicurezza.md)).
Questo documento descrive come il registro viene scritto e letto, e cataloga
ogni tipo di evento. Le colonne della tabella `audit_log` sono descritte in
[modello-dati.md](modello-dati.md); le procedure che partono da un evento
(per esempio un `payout_failed`) sono in [operativita.md](operativita.md).
## Come si scrive
- **[AUD-01]** Ogni riga di audit nasce da un'unica funzione,
`write_audit_log(session, event_type, payload, user_id=None, round_id=None)`.
La funzione **non fa commit**: aggiunge la riga alla sessione del chiamante,
che la salva insieme al resto delle sue modifiche. Nessun altro punto del
codice crea righe `AuditLog`.
*Codice:* `app/audit/log.py:write_audit_log`
- **[AUD-02]** Per gli eventi che accompagnano un cambiamento di stato, la riga
di audit è salvata **nella stessa transazione** del cambiamento che descrive:
o si salvano entrambi, o nessuno dei due. Vale per tutti gli eventi del
catalogo tranne quelli elencati in [AUD-03].
*Codice:* i chiamanti elencati nel catalogo, ognuno dei quali chiama
`write_audit_log` e poi `session.commit()` sulla stessa sessione.
- **[AUD-03]** Quattro eventi sono **solo osservativi**: non accompagnano un
cambiamento di stato e vengono salvati in una transazione propria, aperta
apposta. Sono `draw_baseline_tip_unknown`, `draw_header_corroboration_failed`,
`draw_stalled` e `payout_failed`. Per `payout_failed` la scrittura è anche
*best effort*: se fallisce, l'errore viene registrato nel log applicativo
(`could not record the payout failure of round …`) e ignorato.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_next_block`,
`app/rounds/scheduler.py:RoundScheduler._adopt_baseline_tip`,
`app/rounds/scheduler.py:RoundScheduler._log_payout_failure`
- **[AUD-04]** Il `payload` è un dizionario serializzato in JSON nella colonna
`payload_json`; `created_at` è impostato dal database all'inserimento, in
UTC. `user_id` e `round_id` sono chiavi esterne opzionali, valorizzate come
indicato evento per evento nel catalogo.
*Codice:* `app/audit/log.py:write_audit_log`, `app/db/models.py:AuditLog`
- **[AUD-05]** Il registro è **in sola aggiunta**: nessuna parte del codice
modifica o cancella una riga di `audit_log`, e non c'è alcuna rotazione o
scadenza. La tabella cresce per sempre.
*Codice:* `app/audit/log.py:write_audit_log` (unico punto di scrittura)
- **[AUD-06]** `event_type` è una colonna `String(32)`. Il nome più lungo oggi
in uso, `draw_header_corroboration_failed`, occupa esattamente 32 caratteri:
un nuovo tipo di evento deve restare entro questo limite. SQLite non lo fa
rispettare, un altro database lo farebbe.
*Codice:* `app/db/models.py:AuditLog`
## Come si legge
- **[AUD-07]** `GET /admin/audit-log` (protetto da `X-Admin-Token`) restituisce
le righe dalla più recente (ordine per `id` decrescente), con il parametro
`limit` (predefinito 200, minimo 1, massimo 500). Ogni elemento contiene
`id`, `event_type`, `payload` (già decodificato da JSON), `user_id`,
`round_id` e `created_at` in ISO 8601 UTC. **Non esistono filtri** per tipo
di evento, utente o round, né paginazione: le righe più vecchie delle ultime
500 si leggono solo direttamente dal database.
*Codice:* `app/api/routes/admin.py:list_audit_log` ·
*Test:* `tests/unit/test_admin.py`
- **[AUD-08]** La sezione "Audit log" di `/admin` chiama l'endpoint senza
parametri (quindi le ultime 200 righe) al login e ogni volta che si apre la
sezione, e mostra id, tipo, payload JSON grezzo, utente, round e data. Non ha
filtri né ricerca.
*Codice:* `app/static/admin.js:loadAuditLog`
- **[AUD-09]** Una sola logica del programma rilegge il registro:
`_retry_payout_if_due` usa la riga `payout_failed` più recente del round come
orologio per decidere se ritentare il pagamento. Se è più recente di 60
secondi (`_PAYOUT_RETRY_INTERVAL_SECONDS`) il tentativo viene saltato; se non
esiste, il tentativo parte subito. Nessun'altra decisione dipende dal
registro.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._retry_payout_if_due` ·
*Test:* `tests/unit/test_scheduler.py`
## Catalogo degli eventi
Legenda delle colonne `user_id` / `round_id`: **sì** = sempre valorizzato,
**no** = sempre vuoto, **dipende** = come spiegato nel testo. Gli importi sono
sempre in satoshi.
```mermaid
flowchart LR
subgraph Operatore["Pannello admin"]
config_updated
lottery_paused
lottery_resumed
admin_privkey_accessed
admin_password_reset
bug_report_status_changed
end
subgraph Fondi["Denaro degli utenti"]
deposit_credited
utxo_spent_externally
utxo_external_spend_reinstated
bet_placed
bet_broadcast_failed
withdrawal_sent
withdrawal_broadcast_failed
end
subgraph Round["Round"]
round_closed
winner_drawn
draw_baseline_tip_unknown
draw_header_corroboration_failed
draw_stalled
payout_failed
payout_sent
end
subgraph Ricon["Riconciliazione"]
pending_tx_recovered
pending_tx_abandoned
end
```
### Pannello admin
- **[AUD-10]** `config_updated` — un `PUT /admin/config` ha cambiato almeno un
parametro. Payload: un oggetto con una chiave per ogni campo **effettivamente
cambiato**, ciascuna `{"from": <valore precedente>, "to": <valore nuovo>}`
(i campi sono quelli di `_CONFIG_FIELDS`: `fee_address`, `bet_amount_sats`,
`round_duration_seconds`, `round_cooldown_seconds`, `fee_rate_sat_vb`,
`rbf_timeout_seconds`, `draw_animation_seconds`). Un campo inviato con lo
stesso valore che aveva non compare; se nulla cambia, non si scrive nessuna
riga. `user_id` no, `round_id` no. Stessa transazione della modifica.
*Codice:* `app/api/routes/admin.py:update_config` ·
*Test:* `tests/unit/test_admin.py`
- **[AUD-11]** `lottery_paused` — `POST /admin/pause`. Payload vuoto `{}`.
`user_id` no, `round_id` no. Viene scritto a ogni chiamata, anche se la
lotteria era già in pausa. Stessa transazione di `paused = true`.
*Codice:* `app/api/routes/admin.py:pause_lottery` ·
*Test:* nessun test verifica la riga di audit.
- **[AUD-12]** `lottery_resumed` — `POST /admin/resume`. Payload vuoto `{}`.
`user_id` no, `round_id` no. Scritto a ogni chiamata, anche se la lotteria
non era in pausa. Stessa transazione di `paused = false`.
*Codice:* `app/api/routes/admin.py:resume_lottery` ·
*Test:* nessun test verifica la riga di audit.
- **[AUD-13]** `admin_privkey_accessed` — `GET /admin/users/{id}/privkey` ha
esportato la chiave privata (WIF) di un utente. Payload `{"user_id"}`.
`user_id` sì (l'utente la cui chiave è stata esportata), `round_id` no. La
riga è salvata **prima** che la risposta con la chiave venga restituita: se
il salvataggio fallisce, la chiave non esce. Per un utente inesistente
(404) non si scrive nulla. Questa registrazione non va mai rimossa (vedi
[decisioni-e-limiti.md](decisioni-e-limiti.md)).
*Codice:* `app/api/routes/admin.py:user_privkey` ·
*Test:* nessun test verifica la riga di audit (`tests/unit/test_admin.py`
copre solo l'esportazione).
- **[AUD-14]** `admin_password_reset` — `POST /admin/users/{id}/reset-password`
ha impostato una nuova password casuale. Payload `{"user_id"}`; la nuova
password **non** compare. `user_id` sì, `round_id` no. Stessa transazione del
nuovo hash e dell'incremento di `token_version` (che invalida le sessioni
esistenti).
*Codice:* `app/api/routes/admin.py:reset_user_password` ·
*Test:* nessun test verifica la riga di audit.
- **[AUD-15]** `bug_report_status_changed` — `POST /admin/bug-reports/{id}/status`
ha cambiato lo stato di una segnalazione. Payload
`{"report_id", "from", "to"}` con gli stati `open`/`read`/`resolved`.
`user_id` dipende: è l'autore della segnalazione, vuoto se era anonima;
`round_id` no. Se lo stato richiesto è quello già presente non si scrive
nulla. Stessa transazione del cambio di stato.
*Codice:* `app/api/routes/admin.py:update_bug_report_status` ·
*Test:* `tests/unit/test_bug_reports.py`
### Denaro degli utenti
- **[AUD-16]** `deposit_credited` — un nuovo UTXO confermato sull'indirizzo di
un utente è stato accreditato, dopo la corroborazione degli altri server
(vedi [registrazione-e-depositi.md](registrazione-e-depositi.md)). Una riga
per UTXO. Payload `{"txid", "vout", "amount_sats"}`. `user_id` sì,
`round_id` no. Stessa transazione dell'inserimento in `utxo_events` e del
ricalcolo del saldo. Attenzione: non riguarda solo i depositi dall'esterno.
Anche **le vincite** (l'uscita del pagamento verso il vincitore) e **i resti**
di scommesse e prelievi arrivano all'indirizzo dell'utente e vengono
accreditati per la stessa strada, quindi producono anche loro un
`deposit_credited`.
*Codice:* `app/deposits/service.py:credit_confirmed_utxos` ·
*Test:* nessun test verifica la riga di audit.
- **[AUD-17]** `utxo_spent_externally` — un UTXO che il database considerava
non speso non è più tra quelli non spesi, secondo il server attivo e la
maggioranza degli altri: è stato speso fuori dalla piattaforma (per esempio
con la chiave esportata). Una riga per UTXO. Payload
`{"txid", "vout", "amount_sats"}`. `user_id` sì, `round_id` no. Stessa
transazione della marcatura (`spent_txid = "external-spend"`) e del ricalcolo
del saldo.
*Codice:* `app/deposits/service.py:mark_utxos_spent_externally` ·
*Test:* `tests/unit/test_deposits.py`
- **[AUD-18]** `utxo_external_spend_reinstated` — un UTXO segnato come speso
all'esterno è ricomparso tra i non spesi e la marcatura è stata annullata.
Payload `{"txid", "vout", "amount_sats"}`. `user_id` sì, `round_id` no.
Stessa transazione dell'annullamento e del ricalcolo del saldo.
*Codice:* `app/deposits/service.py:reinstate_reappeared_utxos` ·
*Test:* `tests/unit/test_deposits.py`
- **[AUD-19]** `bet_placed` — la rete ha accettato la transazione di una
scommessa. Payload `{"txid", "amount_sats"}`: `txid` è quello del primo
invio (un successivo RBF non aggiorna la riga), `amount_sats` è l'importo
che arriva al montepremi, cioè la puntata **al netto** della commissione di
rete. `user_id` sì, `round_id` sì. Stessa transazione che porta il
partecipante a `broadcast` e la transazione pendente a `pending`.
*Codice:* `app/bets/service.py:place_bet` ·
*Test:* `tests/unit/test_bets.py`
- **[AUD-20]** `bet_broadcast_failed` — la rete ha rifiutato la transazione di
una scommessa; gli UTXO sono stati liberati e il partecipante rimosso.
Payload `{"txid", "reason"}`, con `reason` il testo dell'errore troncato a
200 caratteri. `user_id` sì, `round_id` **no** (a differenza di
`bet_placed`). Stessa transazione del ripristino.
*Codice:* `app/bets/service.py:_release_failed_bet` ·
*Test:* `tests/unit/test_bets.py`
- **[AUD-21]** `withdrawal_sent` — la rete ha accettato la transazione di un
prelievo. Payload `{"txid", "amount_sent_sats", "external_address"}`:
`amount_sent_sats` è quanto arriva davvero all'indirizzo esterno (al netto
della commissione e dell'eventuale limite di polvere, vedi
[scommesse-e-prelievi.md](scommesse-e-prelievi.md)). L'id del prelievo non è
nel payload. `user_id` sì, `round_id` no. Stessa transazione che porta il
prelievo a `broadcast`.
*Codice:* `app/withdrawals/service.py:request_withdrawal` ·
*Test:* nessun test verifica la riga di audit.
- **[AUD-22]** `withdrawal_broadcast_failed` — la rete ha rifiutato la
transazione di un prelievo; gli UTXO sono stati liberati e il prelievo
segnato `failed`. Payload `{"txid", "reason"}` (`reason` troncato a 200
caratteri). `user_id` sì, `round_id` no. Stessa transazione del ripristino.
*Codice:* `app/withdrawals/service.py:_release_failed_withdrawal` ·
*Test:* nessun test verifica la riga di audit.
### Round
- **[AUD-23]** `round_closed` — un round è stato chiuso **senza partecipanti
confermati**. Payload `{"participants": 0}`. `user_id` no, `round_id` sì.
Stessa transazione del passaggio a `closed`. È l'unico caso in cui la
chiusura di un round viene registrata: un round chiuso dopo la conferma del
pagamento non produce alcuna riga (vedi [AUD-32]).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
*Test:* `tests/unit/test_scheduler.py`
- **[AUD-24]** `winner_drawn` — il vincitore è stato estratto. Payload
`{"winner_address", "pool_amount_sats", "block_height", "block_hash",
"participants"}`: indirizzo del vincitore, montepremi totale (somma delle
puntate nette), altezza e hash del blocco usato come seme, numero di
partecipanti. `user_id` sì (il vincitore), `round_id` sì. Stessa transazione
che salva i dati dell'estrazione sul round e lo porta a `paying_out`.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
*Test:* `tests/unit/test_scheduler.py`
- **[AUD-25]** `draw_baseline_tip_unknown` — al momento della chiusura
l'altezza della catena non era nota, quindi il primo blocco ricevuto è stato
preso come base e l'estrazione aspetta il blocco successivo. Payload
`{"baseline_height"}`. `user_id` no, `round_id` sì. Transazione propria
([AUD-03]). Dovrebbe essere irraggiungibile (lo scheduler non lavora senza
un'altezza nota), vedi [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._adopt_baseline_tip` ·
*Test:* `tests/unit/test_scheduler.py`
- **[AUD-26]** `draw_header_corroboration_failed` — il blocco candidato per
l'estrazione non è stato confermato dalla maggioranza degli altri server
Electrum (o nessuno ha risposto); l'estrazione aspetta un blocco ulteriore.
Una riga per ogni blocco candidato rifiutato. Payload
`{"height", "reported_hash"}`. `user_id` no, `round_id` sì. Transazione
propria ([AUD-03]).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_next_block` ·
*Test:* `tests/unit/test_scheduler.py`
- **[AUD-27]** `draw_stalled` — l'estrazione aspetta un nuovo blocco da più di
360 secondi (`_DRAW_STALL_THRESHOLD_SECONDS`), contati da
`drawing_started_at`; la riga si ripete ogni 360 secondi finché l'attesa
continua. Payload `{"tip_at_close", "current_tip_height",
"elapsed_seconds"}`. Nota: `tip_at_close` è la base *attuale* dell'attesa, che
dopo un `draw_header_corroboration_failed` diventa l'altezza del candidato
rifiutato, non più quella della chiusura. `user_id` no, `round_id` sì.
Transazione propria ([AUD-03]). Non viene scritta mentre è in corso una
corroborazione, solo mentre si aspetta un blocco.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_next_block` ·
*Test:* `tests/unit/test_scheduler.py`
- **[AUD-28]** `payout_failed` — un tentativo di pagamento non è partito.
Payload `{"round_id", "reason"}`. `user_id` dipende: il vincitore, tranne
quando il motivo è l'assenza di connessione (vuoto); `round_id` sì.
Transazione propria e *best effort* ([AUD-03]); è l'orologio del nuovo
tentativo ([AUD-09]). Valori possibili di `reason`:
| `reason` | Causa |
|---|---|
| `electrum client not connected` | Nessuna connessione Electrum al momento del tentativo |
| `no fee_address configured` | `fee_address` vuoto nella configurazione |
| `winner user not found` | L'utente vincitore non esiste più nel database |
| `insufficient pool UTXOs` | Gli UTXO confermati e non riservati dell'indirizzo del montepremi non coprono l'importo |
| `too_many_inputs` | Servirebbero più di `MAX_PAYOUT_TX_INPUTS` (500) input |
| `winner_share_below_network_fee` | La quota del vincitore non copre la commissione di rete |
| `commission_below_dust_limit` | La quota della piattaforma è sotto il limite di polvere |
| `payout build failed` | Qualunque altro errore nella costruzione (per esempio un `fee_address` malformato) |
| `broadcast rejected` | La rete ha rifiutato la transazione; la riga `building` resta al riconciliatore |
Un tentativo saltato perché esiste già un pagamento `building` o `pending`
per il round **non** scrive `payout_failed`. Cosa fare per ogni motivo è
descritto in [operativita.md](operativita.md).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout`,
`app/rounds/scheduler.py:RoundScheduler._log_payout_failure` ·
*Test:* `tests/unit/test_scheduler.py`
- **[AUD-29]** `payout_sent` — la rete ha accettato la transazione di
pagamento. Payload `{"txid", "winner_sats", "commission_sats"}`: quanto
riceve il vincitore (già al netto della commissione di rete) e quanto va a
`fee_address`. `user_id` sì (il vincitore), `round_id` sì. Stessa transazione
che porta la transazione pendente da `building` a `pending`.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
*Test:* `tests/unit/test_scheduler.py`
### Riconciliazione
- **[AUD-30]** `pending_tx_recovered` — una transazione rimasta `building`
(tipicamente per un riavvio a metà invio) risulta invece presente in catena
ed è stata promossa a `pending`. Payload
`{"pending_transaction_id", "kind", "txid"}`. `user_id` e `round_id`
dipendono dal tipo: sono quelli della riga `pending_transactions` (per un
pagamento `user_id` è vuoto, per un prelievo `round_id` è vuoto). Stessa
transazione della promozione. Vedi
[transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md).
*Codice:* `app/tx/reconcile.py:_promote` ·
*Test:* nessun test verifica la riga di audit.
- **[AUD-31]** `pending_tx_abandoned` — una transazione `building` o `pending`
non compare nella cronologia del proprio indirizzo ed è stata dichiarata
persa: stato `failed`, UTXO liberati, partecipante rimosso o prelievo
`failed`, `payout_txid` del round azzerato. Payload
`{"pending_transaction_id", "kind", "txid", "reason", "utxos_released"}`, con
`reason` oggi sempre `"not found on chain"` e `utxos_released` il numero di
UTXO liberati (sempre 0 per un pagamento, perché l'indirizzo del montepremi
non è tracciato in `utxo_events`). `user_id` e `round_id` come in [AUD-30].
Stessa transazione dell'abbandono.
*Codice:* `app/tx/reconcile.py:_abandon` ·
*Test:* `tests/unit/test_reconcile.py`
## Cosa non viene registrato
- **[AUD-32]** Questi fatti **non** producono una riga di audit; restano
ricostruibili solo dallo stato delle tabelle o dal log applicativo:
- apertura di un round;
- passaggi di stato del round a `closing` e `drawing`, e la chiusura dopo la
conferma del pagamento (`_on_payout_confirmed`);
- conferma di una scommessa, di un prelievo o di un pagamento
(`ConfirmationPoller`);
- ogni aumento di commissione RBF e ogni RBF impossibile (solo log);
- registrazione, login, login falliti e blocchi per troppi tentativi;
- cambio password fatto dall'utente (`POST /users/me/change-password`);
- invio di una segnalazione di bug;
- accesso in lettura al pannello admin (elenchi utenti, round, audit).
*Codice:* `app/rounds/service.py:open_new_round_if_needed`,
`app/rounds/scheduler.py:RoundScheduler._tick`,
`app/rounds/confirmation.py:_on_payout_confirmed`,
`app/tx/confirmation.py:poll_once`, `app/tx/broadcast.py:bump_fee`
## Log applicativo
Il registro di audit è nel database e si vede da `/admin`; il log applicativo
è un file di testo e contiene molto di più (errori, riconnessioni, attese), ma
va letto sul server.
- **[AUD-33]** All'importazione di `app.main`, `setup_logging` aggiunge al
logger radice (livello `INFO`) un `RotatingFileHandler` su `logs/app.log`,
relativo alla radice del progetto: 10 MB per file, 5 file di rotazione
(`app.log.1` … `app.log.5`), formato
`data ora LIVELLO [logger] messaggio`. Lo stesso handler è aggiunto a
`uvicorn.error` e `uvicorn.access`, che non propagano al radice. Nel
container la radice del progetto è `/app`, e `/app/logs` è montato su
`./data/logs` dell'host.
*Codice:* `app/logging_config.py:setup_logging`, `docker-compose.yml`
- **[AUD-34]** Il logger radice ha **solo** l'handler su file: i messaggi dei
moduli dell'applicazione (scheduler, listener, riconciliatori) finiscono in
`data/logs/app.log` e non sull'output del container. `docker compose logs app`
mostra solo ciò che uvicorn scrive con la propria configurazione (avvio,
richieste) e l'output di avvio del container (controllo della chiave,
migrazioni Alembic).
*Codice:* `app/logging_config.py:setup_logging`
- **[AUD-35]** Un'eccezione non gestita in una richiesta HTTP viene registrata
per intero nel log (`Unhandled error on <metodo> <percorso>`) e al client
arriva solo un errore generico `internal_error` con stato 500, senza il testo
dell'eccezione.
*Codice:* `app/main.py:log_unhandled_exception`
- **[AUD-36]** Le richieste di polling delle due interfacce (per esempio
`/rounds/current` ogni 15 secondi per ogni pagina aperta, più un aggiornamento
a ogni evento SSE) vengono tutte registrate da `uvicorn.access`. Con 60 MB di spazio complessivo, la rotazione può cancellare
in poche ore o giorni i messaggi più vecchi: il log non è un archivio, il
registro di audit sì.
*Codice:* `app/logging_config.py:setup_logging`
### Messaggi di log che contano
Messaggi non accompagnati da una riga di audit ma utili in esercizio. Il
nome tra parentesi quadre nel log è il modulo (`app.rounds.scheduler`, ecc.).
| Livello | Modulo | Messaggio (inizio) | Significato |
|---|---|---|---|
| WARNING | `app.electrum.listener` | `all N Electrum server(s) unreachable, retrying in Ns` | Tutti i server provati hanno fallito; attesa da 1 a 30s prima del giro successivo |
| ERROR (con traccia) | `app.electrum.listener` | `Electrum session on … failed` | Errore nell'aprire la sessione: connessione, primo header, primo header rifiutato |
| INFO | `app.electrum.listener` | `Electrum connected to …` / `Electrum connection to … ended, reconnecting` | Connessione aperta / chiusa normalmente |
| WARNING | `app.electrum.listener` | `Electrum session on … ending: …` | Motivo della fine di una sessione già aperta (ping scaduto, socket chiuso, header successivo rifiutato con `HeaderValidationError`) |
| WARNING | `app.electrum.listener` | `ignoring Electrum header at height …` / `ignoring a competing header …` | Header scartato senza chiudere la sessione (senza hex, più basso, concorrente) |
| WARNING | `app.electrum.listener` | `could not corroborate … with any of N other configured server(s)` | Nessun altro server ha risposto: la corroborazione fallisce |
| WARNING | `app.electrum.listener` | `N new UTXO(s) for user_id=… not corroborated by the other servers` | Deposito non ancora accreditato; si riprova al prossimo aggiornamento |
| WARNING | `app.electrum.listener` | `N UTXO(s) spent outside the platform for user_id=…` | Accompagna `utxo_spent_externally` |
| WARNING | `app.electrum.listener` | `could not subscribe a newly-registered user's address` / `resubscribing all users failed partway through` | Sottoscrizione persa; la recupera `DepositReconciler` entro 300s |
| ERROR (con traccia) | `app.electrum.listener` | `failed to resubscribe user_id=…` | Un singolo utente non risottoscritto alla riconnessione |
| WARNING | `app.deposits.service` | `listunspent for user_id=… returned no entries at all …` | Risposta vuota per un indirizzo con fondi: ignorata come incompleta |
| ERROR (con traccia) | `app.deposits.reconcile` | `deposit reconciliation failed for user_id=…` | Il controllo periodico di un utente è fallito |
| ERROR (con traccia) | `app.rounds.scheduler` | `round scheduler tick failed` | Eccezione in un ciclo dello scheduler. Se avviene durante `drawing`, il round resta bloccato (vedi [operativita.md](operativita.md)) |
| INFO | `app.rounds.scheduler` | `round N: N bet(s) still in flight at close time, waiting` | Chiusura rinviata per scommesse ancora in volo |
| INFO | `app.rounds.scheduler` | `round N: still waiting for a block past height …` | Estrazione in attesa, ogni 60s |
| ERROR | `app.rounds.scheduler` | `round N: block … header … could not be corroborated …` | Accompagna `draw_header_corroboration_failed` |
| WARNING | `app.rounds.scheduler` | `round N: chain tip was unknown at closing time …` | Accompagna `draw_baseline_tip_unknown` |
| ERROR | `app.rounds.scheduler` | `round N payout blocked: …` / `payout deferred: not connected` / `payout failed: …` / `payout build failed` / `payout broadcast failed` | Accompagnano i vari `payout_failed` |
| INFO | `app.rounds.scheduler` | `round N payout already in flight (pending_transaction N), skipping` | Pagamento già in volo. Mentre aspetta la conferma, ricompare a ogni ciclo (ogni 5s) |
| ERROR (con traccia) | `app.rounds.scheduler` | `could not record the payout failure of round N` | Il `payout_failed` stesso non è stato salvato |
| ERROR | `app.rounds.service` | `invariant violated: N rounds are active at once` | Più di un round attivo: non dovrebbe mai accadere |
| ERROR | `app.rounds.service` | `could not open a round after 3 attempts` | Conflitti ripetuti all'apertura di un round |
| ERROR (con traccia) | `app.tx.broadcast` | `could not bump pending_transaction N` | RBF impossibile (resto insufficiente o commissione già al massimo). Si ripete ogni 30s finché la transazione conferma o viene abbandonata |
| INFO | `app.tx.broadcast` | `bumped <tipo> pending_transaction N: <vecchio> -> <nuovo>` | RBF riuscito: l'unica traccia di un aumento di commissione |
| WARNING | `app.tx.confirmation` | `could not fetch history for pending_transaction …` | Controllo di conferma non riuscito, si riprova tra 10s |
| WARNING | `app.tx.reconcile` | `could not check pending_transaction … against the chain` | Il riconciliatore non ha potuto decidere; non abbandona nulla |
| WARNING | `app.tx.reconcile` | `abandoned <tipo> pending_transaction …` | Accompagna `pending_tx_abandoned` |
| ERROR | `app.tx.reconcile` | `round N payout tx … vanished — round needs operator attention` | Pagamento abbandonato; il nuovo tentativo automatico parte da solo |
| ERROR | `app.auth.security` | `stored password hash is unparseable …` | Hash di password corrotto nel database: quell'utente non può accedere |
| ERROR (con traccia) | `app.main` | `Unhandled error on …` | Errore 500 su una richiesta ([AUD-35]) |
+644
View File
@@ -0,0 +1,644 @@
# Ciclo di vita del round
Fase 4 del [funzionamento generale](come-funziona.md): come un round si apre,
si chiude, estrae un vincitore e lo paga. Tutto è guidato da `RoundScheduler`,
che esegue un passo ogni 5 secondi.
I requisiti usano il prefisso `RND`, secondo la convenzione di
[processo-di-modifica.md](processo-di-modifica.md). Le colonne della tabella
`rounds` sono descritte in [modello-dati.md](modello-dati.md), gli eventi di
audit in [audit-log.md](audit-log.md), le attività in background in
[architettura.md](architettura.md).
Questo documento descrive il comportamento **atteso** dopo la revisione del
2026-09-28. I requisiti che il codice non soddisfa ancora sono marcati
*Stato:* da implementare, con una riga *Oggi* che dice cosa fa il codice
adesso; l'ordine di implementazione è in
[piano-correzioni.md](piano-correzioni.md).
- **[RND-01]** Lo scheduler esegue un passo, poi attende
`_TICK_INTERVAL_SECONDS` (5s) prima del successivo. Un passo non fa nulla
se non c'è connessione a Electrum: senza rete nessun round si apre, si
chiude, estrae o si paga. Un errore in un passo viene registrato nei log e
il passo successivo riparte dallo stato salvato nel database, **in
qualunque stato sia il round**, `drawing` compreso ([RND-36]).
*Codice:* `app/rounds/scheduler.py:RoundScheduler.run`, `app/rounds/scheduler.py:RoundScheduler._tick` ·
*Test:* `tests/unit/test_scheduler.py`
*Stato:* da implementare (B-81) · *Oggi:* un errore durante l'attesa del
blocco lascia il round in `drawing` per sempre, perché `_tick` non fa nulla
sui round in quello stato.
## Gli stati
Diagramma del **comportamento atteso**:
```mermaid
stateDiagram-v2
[*] --> open: nessun round attivo,<br/>pausa tra i round trascorsa,<br/>lotteria non in pausa,<br/>configurazione pagabile
open --> closing: scade il tempo<br/>(al primo passo dopo la scadenza)
closing --> closing: scommesse ancora in volo,<br/>oppure altezza della catena non nota
closing --> closed: nessun partecipante confermato
closing --> drawing: tutte le scommesse confermate:<br/>partecipanti, participants_hash<br/>e draw_height salvati
drawing --> drawing: conferme insufficienti, oppure<br/>i server non concordano sull'header:<br/>si richiede la stessa altezza<br/>(anche dopo un errore o un riavvio)
drawing --> paying_out: header a draw_height concordato,<br/>vincitore salvato, server_seed rivelato
paying_out --> paying_out: pagamento fallito o abbandonato,<br/>nuovo tentativo dopo 60s;<br/>oppure bloccato (payout_blocked)
paying_out --> closed: pagamento confermato
closed --> [*]
```
| Stato | Significato |
|---|---|
| `open` | Accetta scommesse fino alla scadenza |
| `closing` | Scadenza passata: nessuna nuova scommessa, si aspettano quelle già inviate |
| `drawing` | Partecipanti e altezza del blocco fissati, si attendono le conferme del blocco che sceglie il vincitore |
| `paying_out` | Vincitore noto, pagamento in verifica, in costruzione, inviato o in attesa di conferma |
| `closed` | Concluso (con o senza vincitore) |
- **[RND-02]** Gli stati sono esattamente quelli della tabella e le sole
transizioni sono quelle del diagramma; `closed` è definitivo.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`, `app/rounds/scheduler.py:RoundScheduler._close_and_draw`, `app/rounds/confirmation.py:_on_payout_confirmed` ·
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_confirmation.py`
- **[RND-03]** **Al massimo un round attivo alla volta** (cioè in uno stato
diverso da `closed`). Non è una convenzione ma un vincolo del database: un
indice univoco (`ix_rounds_single_active`) fa fallire un secondo inserimento
concorrente, e il codice di apertura in quel caso adotta il round già creato
(fino a 3 tentativi, `_OPEN_ROUND_ATTEMPTS`). Se mai risultassero due round
attivi, si usa il più recente e lo si segnala nei log come violazione.
*Codice:* `app/db/models.py:Round`, `app/rounds/service.py:open_new_round_if_needed`, `app/rounds/service.py:get_active_round` ·
*Test:* `tests/unit/test_rounds_service.py`
## 0 · Apertura
L'apertura viene tentata a ogni passo dello scheduler e anche da ogni
richiesta di scommessa (vedi
[scommesse-e-prelievi.md](scommesse-e-prelievi.md#quando-è-accettata)).
- **[RND-04]** Un nuovo round si apre solo quando **tutte** queste condizioni
sono vere:
- nessun round è attivo (il precedente è `closed`);
- è trascorsa la **pausa tra i round** del round chiuso più recente, contata
dal suo `closed_at`: per un round pagato è il momento della conferma del
pagamento, per un round chiuso senza partecipanti è il momento della
chiusura. Serve a lasciare ai giocatori il tempo di vedere il risultato;
- la lotteria **non è in pausa**, né per manutenzione (`POST /admin/pause`)
né per una pausa automatica: riorganizzazione della catena profonda almeno
2 blocchi ([connessione-electrum.md](connessione-electrum.md) (B-85)),
pagamento bloccato ([RND-39]), transazione abbandonata poi confermata
([transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md) (B-78)),
avvio con `START_PAUSED=true` ([operativita.md](operativita.md) (B-90)).
Il motivo è salvato in `paused_reason`
([modello-dati.md](modello-dati.md) (B-85)) e solo l'operatore toglie la
pausa;
- l'**indirizzo delle commissioni** (`fee_address`) è impostato (un valore
di soli spazi conta come vuoto) e la configurazione corrente permette di
pagare anche un round con un solo partecipante ([RND-40]). Altrimenti il
pagamento non si potrebbe costruire, quindi il round non viene nemmeno
aperto invece di bloccarsi più avanti con i soldi già nel montepremi.
*Codice:* `app/rounds/service.py:open_new_round_if_needed`, `app/rounds/service.py:rounds_can_open` ·
*Test:* `tests/unit/test_rounds_service.py`
*Stato:* da implementare (B-85, B-79) · *Oggi:* l'unica pausa è quella
manuale (`paused`) e `rounds_can_open` controlla solo che `fee_address` non
sia vuoto.
- **[RND-05]** All'apertura il round **fotografa** i parametri correnti che lo
governano: durata (`round_duration_seconds`, 600s predefiniti), pausa
successiva (`round_cooldown_seconds`, 30s predefiniti), costo della
scommessa (`bet_amount_sats`), indirizzo delle commissioni (`fee_address`),
conferme richieste sul blocco di estrazione (`draw_confirmations`, 3
predefinite) e tetto al montepremi (`max_round_pool_sats`, 0 = nessun
tetto; il rifiuto delle scommesse oltre il tetto è in
[scommesse-e-prelievi.md](scommesse-e-prelievi.md#quando-è-accettata) (B-95)).
Il round usa sempre i valori fotografati: una modifica da `/admin` vale dal
round successivo, mai per quello in corso.
*Codice:* `app/rounds/service.py:open_new_round_if_needed`, `app/rounds/service.py:round_deadline` ·
*Test:* `tests/unit/test_rounds_service.py`, `tests/unit/test_scheduler.py` (solo durata e pausa)
*Stato:* da implementare (B-95, B-73) · *Oggi:* sono fotografate solo durata
e pausa; costo della scommessa e `fee_address` sono letti dalla
configurazione a ogni uso, `draw_confirmations` e `max_round_pool_sats` non
esistono.
- **[RND-06]** Pause e configurazione non pagabile bloccano solo l'apertura
del *prossimo* round: un round già in corso prosegue fino al pagamento con i
valori fotografati all'apertura ([RND-05]), quindi una modifica di
`fee_address` durante il round non ne cambia la destinazione della
commissione. L'API di amministrazione non permette di svuotare
`fee_address` (un valore vuoto non è un indirizzo PLM valido).
`GET /rounds/current` espone i due casi separatamente (`lottery_paused`,
`lottery_configured`) perché `/` mostri avvisi diversi. Le procedure sono in
[guida-admin.md](guida-admin.md).
*Codice:* `app/rounds/service.py:open_new_round_if_needed`, `app/api/routes/rounds.py:current_round`, `app/api/routes/admin.py:RoundConfigUpdate` ·
*Test:* `tests/unit/test_rounds_service.py`, `tests/unit/test_rounds_route.py`
*Stato:* da implementare (B-95) · *Oggi:* il pagamento legge `fee_address`
dalla configurazione a ogni tentativo: una modifica durante il round
sposta la commissione del round in corso, e un `fee_address` vuoto (solo
modificando il database a mano) blocca il pagamento con
`no fee_address configured`.
- **[RND-07]** L'apertura di un round invia una notifica SSE.
*Codice:* `app/rounds/service.py:open_new_round_if_needed`
- **[RND-34]** **Impegno sul segreto**: all'apertura il server genera un
segreto di 32 byte casuali (`server_seed`, da un generatore
crittograficamente sicuro), lo salva sul round e pubblica solo la sua
impronta `server_seed_hash = sha256(server_seed)`, esposta da
`GET /rounds/current` e dalla prova pubblica ([RND-37]) fin dall'apertura.
`server_seed` non è esposto da nessun endpoint, `/admin` compreso, finché il
vincitore non è salvato ([RND-18]).
*Codice:* `app/rounds/service.py:open_new_round_if_needed`, `app/api/routes/rounds.py:current_round` ·
*Test:* —
*Stato:* da implementare (B-73) · *Oggi:* il round non ha alcun segreto;
il seme dipende solo dall'hash del blocco.
- **[RND-35]** **Un indirizzo del montepremi per round**: all'apertura il
round riceve un proprio indirizzo `m/84'/746'/0'/2/<round_id>`, salvato in
`rounds.pool_address` ed esposto da `GET /rounds/current`. Le scommesse del
round pagano quell'indirizzo
([scommesse-e-prelievi.md](scommesse-e-prelievi.md#cosa-succede) (B-80)) e il
pagamento spende solo monete di quell'indirizzo ([RND-22]). I round aperti
prima di questa modifica mantengono l'indirizzo condiviso
`m/84'/746'/0'/1/0`, che diventa l'**indirizzo di riserva** ([RND-38]).
Il rifiuto dei prelievi verso indirizzi di montepremi, riserva o
commissioni è in [scommesse-e-prelievi.md](scommesse-e-prelievi.md#prelievo) (B-80).
*Codice:* `app/rounds/service.py:open_new_round_if_needed`, `app/wallet/hd.py:derive_pool_key` ·
*Test:* —
*Stato:* da implementare (B-80) · *Oggi:* tutti i round usano lo stesso
indirizzo `m/84'/746'/0'/1/0` (`derive_pool_key`).
## 1 · Round aperto
Il round accetta scommesse fino a `apertura + durata`. Le regole di
accettazione sono in
[scommesse-e-prelievi.md](scommesse-e-prelievi.md#quando-è-accettata).
- **[RND-08]** La scadenza (`closes_at`) è `opened_at` più la durata
fotografata all'apertura; è la stessa usata per rifiutare le scommesse e per
chiudere il round.
*Codice:* `app/rounds/service.py:round_deadline`, `app/rounds/service.py:round_accepts_bets` ·
*Test:* `tests/unit/test_rounds_service.py`
- **[RND-09]** `GET /rounds/current` pubblica il montepremi in due forme:
- `jackpot_sats` e `participant_count`: calcolati sulle sole scommesse
**confermate** — esattamente ciò che l'estrazione considererà e che il
pagamento potrà spendere. `jackpot_sats` è già il 70% del vincitore
(arrotondato per difetto) della somma degli importi netti, non l'intero
montepremi; resta un limite superiore, perché la commissione di rete del
pagamento sarà dedotta da lì;
- `pending_jackpot_sats` e `pending_participant_count`: gli stessi valori
includendo le scommesse ancora in volo (`building`, `broadcast`), come
totali e non come differenze; `has_pending_bets` dice se differiscono.
*Codice:* `app/api/routes/rounds.py:current_round`, `app/rounds/service.py:winner_share` ·
*Test:* `tests/unit/test_rounds_route.py`
- **[RND-10]** `user_played` è vero solo se chi chiama è autenticato e ha una
scommessa nel round attivo; senza login la risposta non è personalizzata.
*Codice:* `app/api/routes/rounds.py:current_round` ·
*Test:* `tests/unit/test_rounds_route.py`
L'interfaccia mostra in grande i valori confermati e la differenza come
suffisso ambra "+N in attesa": chi ha appena scommesso vede subito la propria
giocata, ma il montepremi pubblicizzato non supera mai quello che verrà pagato.
## 2 · Chiusura
- **[RND-11]** Al primo passo dello scheduler che inizia dopo la scadenza (i
passi sono separati da `_TICK_INTERVAL_SECONDS` = 5s di attesa) il round
passa a `closing`, qualunque cosa stia accadendo: si annota `closed_at` e si
invia una notifica SSE. Le scommesse sono però rifiutate già dall'istante
della scadenza ([BET-04](scommesse-e-prelievi.md#quando-è-accettata)).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick` ·
*Test:* `tests/unit/test_scheduler.py` (verifica solo lo stato finale; nessun test controlla `closed_at` né la notifica SSE)
- **[RND-12]** Poi il round **attende che ogni scommessa già inviata sia
confermata** (il "semaforo giallo"): finché esiste un partecipante in stato
`building` o `broadcast` il round resta `closing` e il controllo si ripete
al passo successivo. Il controllo viene ripetuto anche nella stessa sessione
del database in cui si fissa l'elenco dei partecipanti, così una scommessa
salvata tra i due controlli non può restare esclusa. Una scommessa partita
un attimo prima della scadenza resta quindi valida e non va persa.
**L'attesa non ha un limite di tempo**: finisce solo quando ogni scommessa
in volo è confermata oppure la sua riga viene abbandonata dal
riconciliatore, che la abbandona solo con una prova
([TX-17](transazioni-e-riconciliazione.md#riconciliazione), B-78). Una scommessa
che resta nel mempool non viene mai abbandonata: a farla confermare è
l'aumento della commissione
([TX-11](transazioni-e-riconciliazione.md#rbf-accelerare-una-transazione-lenta)),
pagato dall'utente.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`, `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
*Test:* `tests/unit/test_scheduler.py` (solo il secondo controllo, in `_close_and_draw`; nessun test copre l'attesa in `_tick` con una scommessa in volo)
*Stato:* da implementare (B-78) · *Oggi:* l'attesa è già senza limite, ma
il riconciliatore abbandona una scommessa anche solo perché la cronologia
del server attivo non contiene il suo txid, senza altra prova.
- **[RND-13]** Quando non resta nulla in volo e **nessun partecipante è
confermato**, il round passa a `closed` senza vincitore, si scrive
`round_closed` (con `participants: 0`) e si invia una notifica SSE.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
*Test:* `tests/unit/test_scheduler.py`
- **[RND-14]** Con **almeno un partecipante confermato**, nella stessa
transazione del database che porta il round a `drawing`:
- si fissa l'elenco dei partecipanti confermati, **ordinato per txid della
scommessa** in ordine crescente (txid in esadecimale minuscolo, nell'ordine
mostrato dagli explorer; due scommesse non hanno mai lo stesso txid), e si
salva su ogni partecipante la sua posizione `draw_position`, da 0 a n−1;
- si calcola e si salva `participants_hash` = sha256 delle righe
`txid:vout:indirizzo`, una per partecipante nell'ordine di
`draw_position`, dove `vout` è l'uscita della scommessa verso l'indirizzo
del montepremi del round (in decimale) e `indirizzo` è quello
dell'utente; ogni riga termina con `\n`, testo UTF-8;
- si salva l'altezza del blocco di estrazione ([RND-33]);
- si somma il montepremi dagli importi netti e si annota
`drawing_started_at`.
Dopo il commit si invia una notifica SSE; da quel momento `participants_hash`
e `draw_height` sono pubblici ([RND-37]).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
*Test:* — (nessun test porta `_close_and_draw` con partecipanti confermati fino a `drawing`)
*Stato:* da implementare (B-73, B-81) · *Oggi:* l'elenco è ordinato per
`broadcast_at` (che il pubblico non vede e che non ha spareggio) e resta
solo in memoria; non esistono `draw_position` né `participants_hash`.
- **[RND-33]** L'altezza del blocco di estrazione è fissata all'ingresso in
`drawing` come `draw_height = tip_at_close + 1`, dove `tip_at_close` è
l'altezza della catena nota in quell'istante, e non cambia più: né per una
conferma mancata, né per un errore, né per un riavvio.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
*Test:* —
*Stato:* da implementare (B-73) · *Oggi:* si usa la punta vista al primo
controllo utile, che può essere un blocco successivo; dopo una
corroborazione fallita il riferimento avanza all'altezza rifiutata.
## 3 · Estrazione
L'estrazione combina tre valori che nessuno conosce tutti insieme prima che
sia troppo tardi per cambiarli:
- il **segreto del server** (`server_seed`), fissato all'apertura e noto solo
al server, ma impegnato pubblicamente con la sua impronta ([RND-34]): il
server non può cambiarlo dopo;
- l'**hash del blocco** all'altezza `draw_height`, che non esisteva quando
partecipanti e altezza sono stati fissati;
- l'**impronta dei partecipanti** (`participants_hash`), pubblicata prima che
quel blocco esista ([RND-14]).
Chi produce o trasmette i blocchi non conosce il segreto, quindi non sa quale
blocco farebbe vincere chi: non ha motivo di nasconderne o sceglierne uno.
L'operatore conosce il segreto ma non il blocco, e non può più cambiare né
il segreto né l'elenco. Diagramma del **comportamento atteso**:
```mermaid
flowchart TB
A["Ingresso in drawing: salvati<br/>partecipanti ordinati per txid,<br/>participants_hash, draw_height = tip + 1"] --> B{"La catena ha draw_confirmations<br/>blocchi a partire da draw_height?<br/>(controllo a ogni passo)"}
B -- "No" --> B
B -- "Sì" --> C{"Tutti i server interrogati<br/>sull'header a draw_height:<br/>il quorum concorda?"}
C -- "No" --> D["Registrato in audit<br/>(draw_header_corroboration_failed);<br/>al passo successivo si richiede<br/>la stessa altezza"] --> B
C -- "Sì" --> E["seme = sha256(server_seed ‖ hash del blocco ‖ participants_hash)<br/>indice = seme mod numero partecipanti"]
E --> F["Vincitore = partecipante con draw_position = indice,<br/>salvato; poi server_seed rivelato"]
```
- **[RND-15]** L'estrazione attende che il blocco a `draw_height` abbia
`draw_confirmations` conferme (il valore fotografato all'apertura,
[RND-05]), cioè che l'altezza della catena sia almeno
`draw_height + draw_confirmations − 1`. La condizione si controlla a ogni
passo dello scheduler, rileggendo dal database tutto ciò che serve
([RND-36]).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_next_block` ·
*Test:* `tests/unit/test_scheduler.py` (solo il comportamento attuale)
*Stato:* da implementare (B-73, B-81) · *Oggi:* si attende che la punta
superi l'altezza di riferimento e si usa la punta stessa, con una sola
conferma; per tutta l'attesa lo scheduler resta bloccato dentro
`_close_and_draw` e non esegue altri passi.
- **[RND-16]** **Header concordato**: raggiunte le conferme, l'header
all'altezza `draw_height` (e non la punta corrente) viene chiesto a tutti i
server configurati, attivo compreso, e lo si usa solo se il quorum concorda
sullo stesso hash, con il numero minimo di risposte fissato in
[connessione-electrum.md](connessione-electrum.md#5-il-quorum) (B-84). Se
il quorum non concorda o non risponde abbastanza, si scrive
`draw_header_corroboration_failed` (altezza e hash riportati) e al passo
successivo si richiede **la stessa altezza**: il round non passa mai a un
blocco diverso.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_next_block`, `app/electrum/listener.py:ElectrumListener.corroborate_header` ·
*Test:* `tests/unit/test_scheduler.py` (solo il comportamento attuale)
*Stato:* da implementare (B-73) · *Oggi:* si usa l'header della punta
ricevuto dal server attivo, chiedendo agli altri solo di confermarlo; se la
conferma manca, si attende un blocco ulteriore e si usa quello, così il
server attivo può scegliere quale blocco reale seminare tacendone uno.
- **[RND-17]** **Algoritmo**: seme = sha256 della concatenazione di
`server_seed` (32 byte), hash del blocco a `draw_height` (32 byte,
nell'ordine mostrato dagli explorer) e `participants_hash` (32 byte),
letto come intero senza segno big-endian; indice = seme modulo numero dei
partecipanti; vincitore = il partecipante con `draw_position` uguale
all'indice. **Probabilità uguale per tutti**: ogni partecipante ha una e
una sola posizione nell'elenco, indipendentemente dall'importo.
*Codice:* `app/rounds/draw.py:draw_winner`, `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
*Test:* `tests/unit/test_draw.py` (solo `draw_winner`; nessun test lato scheduler)
*Stato:* da implementare (B-73) · *Oggi:* seme = hash del blocco letto come
numero esadecimale, applicato all'elenco ordinato per `broadcast_at`.
- **[RND-18]** **Verificabile**: in un'unica transazione del database il
round salva altezza e hash del blocco (`draw_block_height` = `draw_height`,
`draw_block_hash`), il seme (`seed_int`), il vincitore e il montepremi
(`pool_amount_sats`), passa a `paying_out` e scrive `winner_drawn`
(indirizzo del vincitore, montepremi, altezza, hash, numero di
partecipanti, `participants_hash`). Solo **dopo** quel commit `server_seed`
diventa pubblico ([RND-37]); si invia una notifica SSE. Da quel momento
chiunque, con i dati della prova pubblica e la catena, può rifare il calcolo
e ottenere lo stesso vincitore (vedi
[Come si verifica un'estrazione](#come-si-verifica-unestrazione)). Il primo
tentativo di pagamento parte subito dopo, nello stesso passo.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
*Test:* — (nessun test porta `_close_and_draw` con partecipanti confermati fino a `paying_out`)
*Stato:* da implementare (B-73) · *Oggi:* il calcolo non è ripetibile da
terzi: l'ordine dei partecipanti è per `broadcast_at`, noto solo al server
e senza spareggio fra valori uguali.
- **[RND-19]** **Altezza sconosciuta alla chiusura**: se, quando il round
sarebbe pronto per `drawing`, l'altezza della catena non è nota (valore 0),
il round resta `closing` e il passaggio viene ritentato al passo
successivo, scrivendo `draw_baseline_tip_unknown` una volta per round:
`draw_height` si fissa solo su un'altezza realmente nota ([RND-33]). In
condizioni normali non accade, perché la connessione è resa disponibile solo
con l'altezza già nota ([ELC-07](connessione-electrum.md#3-caduta-rilevata)).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw`, `app/rounds/scheduler.py:RoundScheduler._adopt_baseline_tip` ·
*Test:* `tests/unit/test_scheduler.py` (solo il comportamento attuale)
*Stato:* da implementare (B-73) · *Oggi:* il round entra comunque in
`drawing`, attende il primo header, ne adotta l'altezza come riferimento,
scrive `draw_baseline_tip_unknown` e aspetta un blocco successivo.
- **[RND-20]** **Attesa lunga ma visibile**: l'attesa non ha un limite,
perché dipende davvero dall'arrivo dei blocchi. Ogni 60 secondi
(`_DRAW_PROGRESS_LOG_INTERVAL_SECONDS`) se ne registra l'avanzamento nei
log. Se per 360 secondi (`_DRAW_STALL_THRESHOLD_SECONDS`) la catena non
avanza mentre il round attende le conferme, oppure il quorum continua a non
concordare, viene scritto un evento `draw_stalled`, ripetuto ogni 360
secondi finché la situazione dura. Durante `drawing`, `GET /rounds/current`
espone `draw_waiting_since` (l'orario di inizio dell'attesa); negli altri
stati il campo è assente.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_next_block`, `app/api/routes/rounds.py:current_round` ·
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_rounds_route.py`
*Stato:* da implementare (B-73) · *Oggi:* i 360 secondi si contano
dall'inizio dell'attesa; con 3 conferme richieste l'evento scatterebbe in
quasi ogni round.
- **[RND-36]** **Estrazione ripresa**: tutto ciò che l'estrazione usa
(`server_seed`, elenco con `draw_position`, `participants_hash`,
`draw_height`, `draw_confirmations`) è nel database dall'ingresso in
`drawing`. A ogni passo, per un round in `drawing`, lo scheduler rifà il
controllo di [RND-15] da quei valori, anche dopo un errore in un passo
precedente o un riavvio del server. La ripresa è idempotente: l'estrazione
ripresa dà sempre lo stesso vincitore, e un round già passato a
`paying_out` non viene estratto di nuovo.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`, `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
*Test:* —
*Stato:* da implementare (B-81) · *Oggi:* elenco dei partecipanti e altezza
di riferimento esistono solo in memoria e `_tick` salta i round in
`drawing`: dopo un errore o un riavvio il round resta in `drawing` per
sempre.
- **[RND-37]** **Prova pubblica**: `GET /rounds/{id}/proof`, senza
autenticazione, restituisce per un round: `server_seed_hash` e
`pool_address` (dall'apertura); dall'ingresso in `drawing` l'elenco dei
partecipanti (`draw_position`, txid, `vout`, indirizzo, importo netto),
`participants_hash`, `draw_height` e `draw_confirmations`; dal salvataggio
del vincitore `server_seed`, `draw_block_hash`, il seme, l'indice, il
vincitore e, quando esiste, il txid del pagamento. Un campo non ancora
disponibile è `null`. Il formato della risposta è in [api.md](api.md) (B-73).
*Codice:* `app/api/routes/rounds.py` ·
*Test:* —
*Stato:* da implementare (B-73) · *Oggi:* non esiste alcun endpoint di
prova; `GET /rounds/current` non espone partecipanti né dati
dell'estrazione, e i round chiusi non sono consultabili pubblicamente.
### Come si verifica un'estrazione
Chiunque può controllare un round concluso con la sola prova pubblica e un
qualunque nodo o explorer PLM, senza fidarsi del server:
1. **Impegno.** Annotare `server_seed_hash` mentre il round è aperto (è
pubblico dall'apertura). Dopo la rivelazione, verificare che
`sha256(server_seed)` sia uguale a quel valore: il segreto usato è quello
fissato all'apertura.
2. **Partecipanti.** Per ogni riga dell'elenco verificare sulla catena che la
transazione `txid` esista, sia confermata, abbia l'uscita `vout` verso
`pool_address` con l'importo indicato e sia firmata dall'indirizzo
indicato. Poiché l'indirizzo del montepremi è del solo round ([RND-35]),
la sua cronologia mostra anche che nessuna scommessa confermata prima
della chiusura manca dall'elenco.
3. **Ordine.** Verificare che le righe siano in ordine crescente di txid e
che `draw_position` vada da 0 a n−1 senza salti.
4. **Impronta dei partecipanti.** Ricostruire le righe `txid:vout:indirizzo`
(ognuna terminata da `\n`), calcolarne lo sha256 e confrontarlo con
`participants_hash`. Chi ha osservato la prova durante `drawing` sa anche
che impronta e `draw_height` erano pubblici prima che il blocco esistesse.
5. **Blocco.** Verificare che `draw_block_hash` sia l'hash del blocco
all'altezza `draw_height` della catena principale.
6. **Calcolo.** Calcolare sha256 della concatenazione dei 32 byte di
`server_seed`, dei 32 byte dell'hash del blocco e dei 32 byte di
`participants_hash`; leggerlo come intero big-endian; l'indice è quel
numero modulo n. Il vincitore dichiarato deve essere la riga con quella
`draw_position`.
7. **Pagamento.** Verificare che la transazione di pagamento spenda le
scommesse del round e paghi l'indirizzo del vincitore
([RND-21], [RND-23]).
Il controllo non esclude un operatore che sia anche minatore: conoscendo il
segreto potrebbe scegliere quale blocco pubblicare a `draw_height`. È un
rischio accettato, descritto in
[decisioni-e-limiti.md](decisioni-e-limiti.md#round-ed-estrazione) (B-73).
L'algoritmo resta un componente **sostituibile** (vedi
[decisioni-e-limiti.md](decisioni-e-limiti.md)).
## 4 · Pagamento
Con il vincitore noto il round è in `paying_out`: si verificano le monete del
round, si costruisce il pagamento e lo si firma con la chiave dell'indirizzo
del montepremi del round.
- **[RND-21]** **Ripartizione**: il vincitore riceve il 70% del montepremi
verificato ([RND-39]) arrotondato per difetto, meno la commissione di rete
([RND-23]); l'indirizzo delle commissioni riceve il resto (30% più
l'eventuale resto dell'arrotondamento) meno la riserva per l'RBF
([RND-38]). La ripartizione è fissata nel codice, non modificabile da
`/admin`.
*Codice:* `app/rounds/service.py:winner_share`, `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
*Test:* `tests/unit/test_payout_builder.py`
*Stato:* da implementare (B-79, B-82) · *Oggi:* la ripartizione si calcola
su `pool_amount_sats` fissato all'estrazione e l'indirizzo delle
commissioni riceve l'intera quota del 30%.
- **[RND-22]** Il pagamento spende le uscite delle scommesse dei partecipanti
del round **verificate** ([RND-39]), all'indirizzo del montepremi del round
([RND-35]), e nient'altro: altre monete arrivate a quell'indirizzo non
vengono toccate. Sono escluse quelle già impegnate da un altro pagamento
non risolto ([RND-26]); il limite è di 500 ingressi
(`MAX_PAYOUT_TX_INPUTS`), superiore al massimo di partecipanti per round
([BET-06](scommesse-e-prelievi.md#quando-è-accettata)). Troppi ingressi dà
il motivo `too_many_inputs`. Per i round aperti prima dell'indirizzo per
round si spendono le monete confermate dell'indirizzo condiviso, scelte
dalla più grande fino a coprire il montepremi; non abbastanza monete dà
`insufficient pool UTXOs`.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout`, `app/wallet/psbt_builder.py:build_payout_transaction` ·
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_payout_builder.py`
*Stato:* da implementare (B-80, B-82) · *Oggi:* spende le monete confermate
dell'indirizzo condiviso lette dal solo server attivo, scelte dalla più
grande fino a coprire il montepremi, qualunque sia la loro provenienza.
- **[RND-23]** La transazione ha un'uscita verso l'indirizzo del vincitore,
una verso l'indirizzo delle commissioni fotografato all'apertura
([RND-05]) e una verso l'indirizzo di riserva ([RND-38]). Se gli ingressi
superano quanto serve (solo per i round aperti prima dell'indirizzo per
round), il resto va all'indirizzo di riserva se è di almeno 294 sat
(`DUST_LIMIT_SATS`), altrimenti va alla commissione di rete. La
**commissione di rete** (stimata su tre uscite, a `fee_rate_sat_vb`) è
pagata dalla quota del vincitore, così la quota delle commissioni non la
paga. Se la quota del vincitore meno la commissione di rete, o la quota
delle commissioni meno la riserva, è inferiore a 294 sat, il pagamento non
si costruisce (`winner_share_below_network_fee`,
`commission_below_dust_limit`).
*Codice:* `app/wallet/psbt_builder.py:build_payout_transaction` ·
*Test:* `tests/unit/test_payout_builder.py` (nessun test copre `commission_below_dust_limit`)
*Stato:* da implementare (B-79, B-95) · *Oggi:* la terza uscita è un resto
verso l'indirizzo del montepremi, presente solo se è di almeno 294 sat e
assente quando le monete spese sono esattamente le scommesse del round; non c'è riserva, la soglia di 294 sat si applica all'intera
quota delle commissioni e `fee_address` è letto dalla configurazione.
- **[RND-24]** **Prima si scrive, poi si invia**: prima dell'invio il round
registra importo del vincitore (`winner_amount_sats`), commissioni
(`fee_amount_sats`), riserva per l'RBF (`bump_reserve_sats`, [RND-38]) e
txid (`payout_txid`), e si salva una transazione in
corso di tipo `payout` in stato `building`. Se l'invio riesce, la
transazione passa a `pending` e si scrive `payout_sent`. Se non riesce, si
scrive `payout_failed` e la riga resta `building`: la risolve il
riconciliatore, secondo le regole di invio e di abbandono di
[transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md#pagamenti-del-round-riprovare-senza-pagare-due-volte)
(TX-18, B-76, B-78); solo un abbandono libera il round per un nuovo
tentativo.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
*Test:* `tests/unit/test_scheduler.py`
*Stato:* da implementare (B-79) · *Oggi:* tutto come descritto, tranne
`bump_reserve_sats`, che non esiste.
- **[RND-25]** Ogni tentativo che si ferma prima di un invio riuscito scrive
un evento `payout_failed` con il motivo: `electrum client not connected`,
`no fee_address configured`, `winner user not found`,
`insufficient pool UTXOs`, il codice dell'errore di costruzione
(`too_many_inputs`, `winner_share_below_network_fee`,
`commission_below_dust_limit`), `payout build failed` per ogni altro errore
di costruzione, `broadcast rejected`. Fanno eccezione due casi, che non
scrivono `payout_failed`: un pagamento già in volo per il round ([RND-26]),
che termina il tentativo senza scrivere nulla, e un pagamento bloccato
([RND-39]), che scrive `payout_blocked`. A ogni passo lo scheduler
riesamina un round in `paying_out` e riprova **al massimo una volta ogni 60
secondi** (`_PAYOUT_RETRY_INTERVAL_SECONDS`), misurati dall'ultimo
`payout_failed` di quel round; senza alcun `payout_failed` (ad esempio dopo
un riavvio, o mentre un pagamento è in volo) riprova al passo successivo.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._retry_payout_if_due`, `app/rounds/scheduler.py:RoundScheduler._log_payout_failure` ·
*Test:* `tests/unit/test_scheduler.py` (verificati solo i motivi `electrum client not connected` e `no fee_address configured`; per l'invio fallito solo la presenza di `payout_failed`)
- **[RND-26]** Due protezioni impediscono di pagare due volte: non si
costruisce un nuovo pagamento se per il round ne esiste già uno `building` o
`pending` (il tentativo termina senza fare nulla e senza scrivere eventi),
e le monete impegnate da un qualunque pagamento non risolto, anche di un
round precedente, sono escluse dalla selezione.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout`, `app/rounds/scheduler.py:_reserved_payout_outpoints` ·
*Test:* `tests/unit/test_scheduler.py`
- **[RND-27]** Se il pagamento non conferma in tempo si applica l'RBF, pagato
riducendo l'uscita di riserva ([RND-38]); le uscite del vincitore e delle
commissioni non cambiano
([TX-11](transazioni-e-riconciliazione.md#rbf-accelerare-una-transazione-lenta)).
*Codice:* `app/tx/broadcast.py:bump_fee`
*Stato:* da implementare (B-79) · *Oggi:* l'RBF può ridurre solo il resto
verso il montepremi, che non esiste quando le monete spese sono
esattamente le scommesse del round: un pagamento bloccato nel
mempool non si può accelerare, e poiché il server lo conosce non viene
nemmeno abbandonato, quindi il round resta in `paying_out` e nessun nuovo
round si apre.
- **[RND-28]** Quando il pagamento è confermato il round passa a `closed` e
`closed_at` viene riscritto con l'orario della conferma: da lì parte la
pausa prima del round successivo. Il vincitore si vede accreditare la
vincita come un normale deposito
([registrazione-e-depositi.md](registrazione-e-depositi.md#deposito)).
*Codice:* `app/rounds/confirmation.py:_on_payout_confirmed` ·
*Test:* `tests/unit/test_confirmation.py`
- **[RND-38]** **Riserva per l'RBF**: ogni pagamento ha un'uscita di riserva
verso l'indirizzo di riserva `m/84'/746'/0'/1/0` di valore
`max(DUST_LIMIT_SATS, estimate_vsize(ingressi, 3) × 10 sat/vB)`, dove 10
sat/vB è la costante `PAYOUT_BUMP_RESERVE_SAT_VB`. La riserva è tolta
dalla quota delle commissioni, mai da quella del vincitore; è ciò che
l'RBF riduce ([RND-27]).
*Codice:* `app/wallet/psbt_builder.py:build_payout_transaction`, `app/wallet/hd.py:derive_pool_key` ·
*Test:* —
*Stato:* da implementare (B-79) · *Oggi:* non esiste alcuna riserva.
- **[RND-39]** **Verifica prima del pagamento**: prima di costruire il
pagamento, le uscite delle scommesse dei partecipanti vengono verificate
all'indirizzo del montepremi del round con il quorum dei server
([connessione-electrum.md](connessione-electrum.md#5-il-quorum) (B-82)).
- Un partecipante la cui uscita il quorum dice **assente** (la scommessa è
sparita dalla catena, ad esempio per una riorganizzazione) passa a
`reorged_out` ([modello-dati.md](modello-dati.md) (B-82)) ed è escluso
dal montepremi; `pool_amount_sats` viene riscritto con la somma delle
uscite verificate e la ripartizione ([RND-21]) si calcola su quella.
- Se è assente la scommessa **del vincitore**, il pagamento non si
costruisce: si scrive `payout_blocked`, si annota il blocco sul round,
la lotteria va in pausa automatica ([RND-04]) e il round resta in
`paying_out` senza altri tentativi finché l'operatore non toglie la pausa
(`POST /admin/resume`); al tentativo successivo la verifica si ripete. Lo
schema è in [modello-dati.md](modello-dati.md) (B-82), la procedura in
[operativita.md](operativita.md) (B-82).
- Se il quorum non risponde o non concorda, non si conclude nulla: nessun
partecipante cambia stato, il tentativo termina con `payout_failed` e si
riprova secondo [RND-25].
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
*Test:* —
*Stato:* da implementare (B-82) · *Oggi:* le monete sono lette dal solo
server attivo e nessun partecipante viene mai escluso: se una scommessa
sparisce dalla catena il pagamento fallisce con
`insufficient pool UTXOs` a ogni tentativo, con i soldi di tutti gli altri
bloccati.
- **[RND-40]** **Configurazione pagabile**: `rounds_can_open` rifiuta una
configurazione in cui un round con un solo partecipante non si potrebbe
pagare. Con `netto` = `bet_amount_sats − estimate_vsize(MAX_TX_INPUTS, 2) ×
fee_rate_sat_vb` (la scommessa più piccola che può arrivare al montepremi)
devono valere entrambe:
- `winner_share(netto) − estimate_vsize(1, 3) × fee_rate_sat_vb ≥
DUST_LIMIT_SATS`;
- `netto − winner_share(netto) − riserva ≥ DUST_LIMIT_SATS`, con la
riserva di [RND-38] calcolata su un ingresso.
Si usano i valori della configurazione al momento dell'apertura.
*Codice:* `app/rounds/service.py:rounds_can_open` ·
*Test:* —
*Stato:* da implementare (B-79) · *Oggi:* `rounds_can_open` controlla solo
che `fee_address` non sia vuoto.
## Tempi reali
Tra lo scadere del timer e l'arrivo della vincita ci sono **tre attese di
conferma distinte**:
1. l'ultima scommessa in volo (può essere già confermata prima della
scadenza);
2. il blocco dell'estrazione a `draw_height`, il primo dopo il punto 1, più
i blocchi successivi fino a `draw_confirmations` conferme (3 predefinite,
quindi 3 blocchi);
3. il pagamento, costruito solo dopo il punto 2, che richiede un altro blocco.
I blocchi PLM arrivano in media ogni 120 secondi, ma l'intervallo fra due
blocchi non ha un limite superiore: non esiste un "caso peggiore". A valori
medi, dalla conferma dell'ultima scommessa servono 3 blocchi per l'estrazione
e 1 per il pagamento, cioè 4 blocchi (8 minuti in media), indipendentemente
da `draw_animation_seconds`. I depositi richiedono a parte più conferme prima
di poter essere giocati
([registrazione-e-depositi.md](registrazione-e-depositi.md#deposito) (B-82)).
## Cosa vede il giocatore
Due livelli indipendenti:
- **[RND-29]** A **tutti** i visitatori, per l'intera durata di `closing`,
`drawing` e `paying_out`, un riquadro con la fase in corso (ad esempio
"Pagamento al vincitore in corso…").
*Codice:* `app/static/app.js:refreshRound`
- **[RND-30]** **In più**, solo a chi ha giocato quel round
(`user_played`), il riquadro personale "Hai vinto!" / "Non hai vinto". Il
risultato compare quando il vincitore è noto (quindi da `paying_out`), non
prima di `draw_animation_seconds` (20s predefiniti) dall'orario di chiusura
del server `closes_at` — così ricaricare la pagina non fa ripartire il conto
alla rovescia — e, per il vincitore, solo quando è noto l'importo vinto.
*Codice:* `app/static/app.js:refreshRound`
- **[RND-31]** Una volta rivelato, il risultato resta salvato nel browser
(`localStorage.plm_persisted_result`) anche dopo che il round è `closed`
(quando `GET /rounds/current` non lo restituisce più), fino all'apertura di
un round nuovo. Per un dispositivo che si è perso del tutto la finestra,
`GET /users/me/last-round-result` restituisce dal database l'ultimo round
`closed` a cui l'utente ha partecipato, se ha vinto e l'importo vinto.
*Codice:* `app/static/app.js:checkLastRoundResult`, `app/api/routes/users.py:last_round_result`
## Limite noto
- ~~[RND-32]~~ Assorbito da [RND-36]: nel comportamento atteso un round in
`drawing` riprende da solo dopo un riavvio o un errore. Finché B-81 non è
implementato il limite resta: lo scheduler riprende i round in `closing` e
`paying_out`, ma su un round in `drawing` non fa nulla.
+192
View File
@@ -0,0 +1,192 @@
# Come funziona PLM Lottery
Panoramica del funzionamento della piattaforma. È il punto di partenza: ogni
sezione rimanda al documento che la approfondisce.
| Documento | Cosa spiega |
|---|---|
| [registrazione-e-depositi.md](registrazione-e-depositi.md) | Come nasce un account, come arrivano i fondi, come si calcola il saldo mostrato |
| [scommesse-e-prelievi.md](scommesse-e-prelievi.md) | Come si piazza una scommessa e come si ritirano i fondi |
| [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md) | Apertura, chiusura, estrazione del vincitore, pagamento |
| [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md) | Come ogni movimento di denaro viene registrato, inviato, accelerato (RBF) e riconciliato con la catena |
| [connessione-electrum.md](connessione-electrum.md) | Come il server parla con la rete PLM e perché non si fida di un solo server |
| [architettura.md](architettura.md) | Struttura del codice, processi in background, configurazione, frontend, traduzioni, test |
| [modello-dati.md](modello-dati.md) | Tabelle del database, campi, stati, vincoli, migrazioni |
| [api.md](api.md) | Tutti gli endpoint HTTP, formato delle risposte, catalogo dei codici di errore |
| [sicurezza.md](sicurezza.md) | Modello di fiducia, chiavi e segreti, autenticazione, limiti sui tentativi, header HTTP |
| [audit-log.md](audit-log.md) | Catalogo degli eventi del registro di audit |
| [operativita.md](operativita.md) | Backup, riavvii, procedure per gli incidenti |
| [decisioni-e-limiti.md](decisioni-e-limiti.md) | Decisioni di progetto con le loro motivazioni, limiti noti accettati |
| [storico-bug.md](storico-bug.md) | Tutti i bug B-nn trovati e corretti, con commit e test |
| [piano-correzioni.md](piano-correzioni.md) | Decisioni della revisione del 2026-09-28 e ordine in cui implementare le correzioni ancora aperte |
Questi documenti sono la **specifica** del software: ogni regola ha un
identificativo stabile (ad esempio `RND-11`) con il riferimento al codice che
la implementa. Come si usano per modificare il software è spiegato in
[processo-di-modifica.md](processo-di-modifica.md).
Dalla revisione del 2026-09-28 la specifica descrive il comportamento
**atteso**, che in alcuni punti è più avanti del codice. I requisiti che il
codice non soddisfa ancora sono marcati `*Stato:* da implementare (B-nn)` e
dicono in una riga cosa fa il codice oggi (`git grep "da implementare"` li
elenca tutti); anche questa panoramica descrive il comportamento atteso. Le
decisioni prese e l'ordine di implementazione sono in
[piano-correzioni.md](piano-correzioni.md), il dettaglio tecnico di ogni voce
in [BUGS.md](../BUGS.md).
Per installazione e avvio vedi [setup.md](setup.md) e
[running-the-server.md](running-the-server.md); per l'uso delle interfacce
[guida-utente.md](guida-utente.md) e [guida-admin.md](guida-admin.md).
## In una frase
Gli utenti depositano PLM su un indirizzo personale custodito dal server,
comprano un biglietto a costo fisso per il round in corso, e allo scadere del
round un seme che combina un segreto su cui il server si è impegnato
all'apertura, l'hash di un blocco successivo alla chiusura e l'elenco dei
partecipanti sceglie un vincitore, che riceve il 70% del montepremi; il 30%
va alla piattaforma.
## Scelte di fondo
- **Custodiale.** Le chiavi sono generate e tenute dal server (una master xprv
cifrata a riposo). L'utente non controlla nulla finché non preleva.
- **Un indirizzo per utente, per sempre.** Lo stesso indirizzo serve per i
depositi, riceve le vincite e riceve il resto di ogni scommessa e prelievo.
- **Nessun nodo completo.** Tutto l'accesso alla rete passa dal protocollo
Electrum (vedi [connessione-electrum.md](connessione-electrum.md)).
- **6 conferme per i depositi, 1 per tutto il resto.** Il deposito è l'unico
ingresso che un utente può spendere due volte, perché scommesse, pagamenti
e prelievi li firma solo il server; le uscite coinbase richiedono 120
conferme (vedi [registrazione-e-depositi.md](registrazione-e-depositi.md#deposito)).
- **Estrazione con commit-reveal.** All'apertura il server si impegna su un
segreto pubblicandone l'impronta; alla chiusura si fissano elenco dei
partecipanti e altezza del blocco; il segreto viene rivelato dopo
l'estrazione. Chi produce i blocchi non può calcolare il vincitore e
l'operatore non può cambiare il segreto; chiunque può verificare il
risultato con la prova pubblica (vedi
[ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#3--estrazione)).
- **Un indirizzo del montepremi per ogni round**, così soldi e cronologia di
un round restano separati da quelli degli altri.
- **Nel dubbio non si liberano i fondi.** Una transazione viene annullata solo
con una prova, mai per un timeout o per il silenzio di un solo server (vedi
[transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md)).
- **Parametri operativi nel database**, modificabili a caldo da `/admin`
(costo della scommessa, durata del round, commissioni…). Nel file `.env`
restano solo segreti e collegamenti infrastrutturali.
## Le cinque fasi
Diagramma del **comportamento atteso**:
```mermaid
flowchart LR
subgraph REG["1 · Registrazione"]
direction TB
A1["Username + password"] --> A2["Il server deriva un indirizzo<br/>dedicato e permanente"]
end
subgraph DEP["2 · Deposito"]
direction TB
B1["L'utente invia PLM<br/>al proprio indirizzo"] --> B2{"6 conferme e<br/>corroborato dagli<br/>altri server?"}
B2 -- "No" --> B1b["Si riprova al prossimo<br/>aggiornamento"] --> B2
B2 -- "Sì" --> B3["Saldo accreditato"]
end
subgraph PLAY["3 · Scommessa"]
direction TB
C1{"Saldo sufficiente,<br/>nessuna scommessa attiva,<br/>round aperto e non pieno?"}
C1 -- "Sì" --> C2["Transazione: indirizzo utente →<br/>montepremi del round, resto all'utente"]
C2 --> C3{"Confermata?"}
C3 -- "No, troppo tempo" --> C4["Commissione aumentata<br/>(RBF) e reinvio"] --> C3
C3 -- "Sì" --> C5["Partecipante del round"]
end
subgraph DRAW["4 · Round ed estrazione"]
direction TB
D0["Apertura: indirizzo del montepremi<br/>del round, impronta del segreto pubblicata"] --> D1["Scadenza del round"]
D1 --> D2["Si attendono le scommesse<br/>già in volo"]
D2 --> D3["Si fissano partecipanti<br/>e altezza del blocco"]
D3 --> D3b["Blocco con 3 conferme, header<br/>concordato dal quorum:<br/>segreto + blocco + partecipanti<br/>scelgono il vincitore"]
D3b --> D3c["Segreto rivelato,<br/>prova pubblica"]
D3c --> D3d{"Scommesse ancora<br/>sulla catena?"}
D3d -- "Sì (quelle sparite<br/>sono escluse)" --> D4["70% al vincitore, 30% alla piattaforma<br/>meno la riserva per l'RBF"]
D3d -- "Sparita quella<br/>del vincitore" --> D5["Pagamento bloccato,<br/>lotteria in pausa"]
end
subgraph WITHDRAW["5 · Prelievo"]
direction TB
E1["Indirizzo esterno + importo"] --> E2["Transazione: indirizzo utente →<br/>esterno, resto all'utente"]
E2 --> E3{"Confermata?"}
E3 -- "No, troppo tempo" --> E4["RBF e reinvio"] --> E3
E3 -- "Sì" --> E5["Saldo aggiornato"]
end
A2 --> B1
B3 --> C1
B3 --> E1
C5 --> D1
D4 -.->|"round successivo"| C1
```
1. **Registrazione** — [registrazione-e-depositi.md](registrazione-e-depositi.md#registrazione)
2. **Deposito** — [registrazione-e-depositi.md](registrazione-e-depositi.md#deposito)
3. **Scommessa** — [scommesse-e-prelievi.md](scommesse-e-prelievi.md#scommessa)
4. **Round ed estrazione** — [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md)
5. **Prelievo** — [scommesse-e-prelievi.md](scommesse-e-prelievi.md#prelievo)
## Componenti
Un solo processo Python (FastAPI) dietro Caddy, con un database SQLite. Dentro
il processo girano, oltre all'API HTTP, sei attività in background avviate
all'avvio del server:
| Attività | Ogni | Cosa fa |
|---|---|---|
| `ElectrumListener` | connessione continua, ping ogni 60s | L'unica connessione alla rete: riceve i nuovi blocchi, osserva gli indirizzi di tutti gli utenti, accredita i depositi |
| `RoundScheduler` | 5s | Apre e chiude i round, esegue l'estrazione, avvia e riprova i pagamenti |
| `ConfirmationPoller` | 10s | Porta le transazioni da "in attesa" a "confermate" |
| `RbfBumper` | 30s | Aumenta la commissione di ciò che non conferma entro il tempo limite |
| `PendingTransactionReconciler` | all'avvio, poi 120s | Confronta con la catena ogni transazione rimasta a metà |
| `DepositReconciler` | 300s | Ricontrolla tutti gli indirizzi, nel caso una notifica sia andata persa |
La cadenza di queste attività è ciò che determina quanto in fretta il sistema
si ripara da solo dopo un problema.
Le due interfacce web sono pagine statiche servite dallo stesso server, senza
build né framework:
- **`/`** — l'interfaccia per i giocatori (registrazione, deposito, scommessa,
prelievo, profilo, stato del round), tradotta in 7 lingue.
- **`/admin`** — il pannello operatore, protetto da un token condiviso,
in italiano.
Entrambe interrogano periodicamente l'API e in più ascoltano un canale
**SSE** (`GET /rounds/stream`): un semplice segnale "è cambiato qualcosa,
ricarica" inviato a ogni evento rilevante (round aperto o cambiato di stato,
scommessa o prelievo inviato, transazione confermata, deposito accreditato,
nuovo blocco). Se il canale cade, le pagine continuano a funzionare con il
solo polling.
## Parametri principali
| Parametro | Valore predefinito | Modificabile |
|---|---|---|
| Costo della scommessa | 10 PLM | da `/admin`, vale dal round successivo (B-95) |
| Ripartizione del montepremi | 70% vincitore / 30% piattaforma | no, è nel codice |
| Durata del round | 600s | da `/admin`, vale dal round successivo |
| Pausa tra un round e l'altro | 30s | da `/admin`, vale dal round successivo |
| Commissione di rete | 1 sat/vB | da `/admin` |
| Tempo prima di un RBF | 900s | da `/admin` |
| Prelievo minimo | pari al costo della scommessa | segue il costo |
| Deposito minimo | nessuno | — |
| Partecipanti massimi per round | 400 | no, è nel codice |
| Tetto al montepremi del round (`max_round_pool_sats`) | 0 = nessun tetto (B-95) | da `/admin`, vale dal round successivo |
| Conferme per i depositi (`deposit_confirmations`) | 6; 120 per le uscite coinbase (B-82) | da `/admin`; le 120 coinbase no, sono nel codice |
| Conferme sul blocco di estrazione (`draw_confirmations`) | 3 (B-73) | da `/admin`, vale dal round successivo |
| Conferme per scommesse, pagamenti, prelievi | 1 | no, è nel codice |
| Indirizzo del montepremi | uno per round, `m/84'/746'/0'/2/<id_round>` (B-80) | no, è nel codice |
| Riserva per l'RBF sul pagamento | `max(294 sat, dimensione stimata × 10 sat/vB)`, tolta dalla quota della piattaforma, verso `m/84'/746'/0'/1/0` (B-79) | no, è nel codice |
Un B-nn nella tabella indica un parametro del comportamento atteso non ancora
implementato (vedi [piano-correzioni.md](piano-correzioni.md)).
+393
View File
@@ -0,0 +1,393 @@
# Connessione alla rete PLM (Electrum)
Il server non gestisce un nodo completo: parla con la rete PLM esclusivamente
tramite il **protocollo Electrum**, con **una sola connessione** alla volta.
Da quella connessione passa tutto — accredito dei depositi, invio delle
transazioni, conferme, altezza della catena su cui attende l'estrazione — per
cui è sia il principale punto di rottura sia, se il server dall'altra parte
fosse ostile, il principale rischio per l'integrità.
I requisiti usano il prefisso `ELC`, secondo la convenzione di
[processo-di-modifica.md](processo-di-modifica.md). La configurazione
(`.env`) è descritta in [setup.md](setup.md), i rischi accettati in
[sicurezza.md](sicurezza.md) e [decisioni-e-limiti.md](decisioni-e-limiti.md).
Questo documento descrive il comportamento **atteso** dopo la revisione del
2026-09-28; i requisiti che il codice non soddisfa ancora sono marcati
*da implementare* (vedi [piano-correzioni.md](piano-correzioni.md)).
Le difese sono cinque.
## 1. Rotazione tra server
`ELECTRUM_HOST`/`ELECTRUM_PORT` è il server principale;
`ELECTRUM_FALLBACK_SERVERS` è un elenco di riserva nel formato
`host:porta[:<modo>]`, separato da virgole.
- **[ELC-01]** L'elenco dei server è il principale (con TLS secondo
`ELECTRUM_USE_SSL`) seguito da quelli di riserva. Ogni voce di riserva è
`host:porta` (TLS), `host:porta:<modo>` con `<modo>` tra `ssl`/`tls` (TLS) e
`notls`/`plain` (in chiaro), oppure `host:porta:pin=<sha256>` (TLS con
certificato fissato, [ELC-03]); `<sha256>` sono 64 cifre esadecimali. Le
voci vuote sono ignorate e i duplicati eliminati mantenendo la prima
posizione. Una voce malformata blocca l'avvio subito, non durante il guasto
in cui servirebbe.
*Codice:* `app/electrum/client.py:parse_endpoints` ·
*Test:* `tests/unit/test_electrum_client.py`
*Stato:* da implementare (B-84), per la forma `pin=` · *Oggi:* il terzo
campo accetta solo `ssl`/`tls`/`notls`/`plain`; `pin=…` è una voce
malformata.
- **[ELC-02]** Dopo ogni sessione fallita o caduta si prova **subito** il
server successivo nell'elenco, a rotazione; l'attesa crescente (da 1s
raddoppiando fino a 30s) scatta solo dopo che ogni server ha fallito una
volta di seguito. Una sessione che si era stabilita azzera l'attesa. Senza
alcun server configurato il listener si ferma con un errore nei log.
*Codice:* `app/electrum/listener.py:ElectrumListener.run` ·
*Test:* `tests/unit/test_electrum_listener.py`
- **[ELC-03]** Con TLS la connessione è cifrata. Il certificato non è
verificato contro un'autorità (i server Electrum usano spesso certificati
autofirmati), ma può essere **fissato**: per una voce con `pin=<sha256>`
([ELC-01]), e per il server principale con `ELECTRUM_CERT_PIN`, lo SHA-256
del certificato del server in formato DER deve coincidere con il valore
configurato, altrimenti la connessione fallisce come un server
irraggiungibile e si passa al successivo ([ELC-02]). Senza pin la fiducia
non viene dal TLS ma dal quorum ([§ 5](#5-il-quorum)). Ogni connessione si
apre con la stretta di mano `server.version`.
*Codice:* `app/electrum/client.py:ElectrumClient.connect` · *Test:* —
*Stato:* da implementare (B-84) · *Oggi:* nessun certificato viene mai
verificato; non esiste un modo di fissarlo.
- **[ELC-19]** Il server **rifiuta di avviarsi** se, dopo l'eliminazione dei
duplicati, l'elenco contiene meno di **2 server di riserva** oltre al
principale: con meno di tre server il quorum di [ELC-14] non può mai avere
due risposte indipendenti da quella del server attivo. L'unica eccezione è
`ALLOW_NO_QUORUM=true`, **solo per lo sviluppo**: il server parte, scrive un
avviso nei log a ogni avvio, e le corroborazioni seguono la regola ridotta
di [ELC-14].
*Codice:* `app/config.py:validate_runtime_secrets`, `app/main.py:lifespan` · *Test:* —
*Stato:* da implementare (B-84) · *Oggi:* un `ELECTRUM_FALLBACK_SERVERS`
vuoto (il valore di `.env.example`) è accettato in silenzio e disattiva
ogni corroborazione.
## 2. Richieste con limite di tempo
- **[ELC-04]** Ogni richiesta ha un limite di 15 secondi
(`_REQUEST_TIMEOUT_SECONDS`); allo scadere la connessione viene chiusa, la
sessione termina e si passa al server successivo. Quando la connessione cade,
tutte le richieste in attesa falliscono subito invece di restare sospese.
Senza questo limite una risposta mai arrivata poteva bloccare una scommessa
(con il blocco per-utente acquisito) o fermare per sempre il controllo delle
conferme.
*Codice:* `app/electrum/client.py:ElectrumClient.request`, `app/electrum/client.py:ElectrumClient._read_loop` ·
*Test:* `tests/unit/test_electrum_client.py`
- **[ELC-20]** Una riga di risposta può essere lunga fino a **16 MiB**
(16 777 216 byte). Una riga più lunga, o una riga che non è JSON valido,
è un errore **della richiesta**, non della connessione: la riga viene
scartata fino al suo a capo e la connessione resta aperta. La richiesta a
cui rispondeva fallisce subito con un errore se il suo `id` si legge nei
primi o negli ultimi 256 byte della riga; altrimenti fallisce allo scadere
di [ELC-04].
*Codice:* `app/electrum/client.py:ElectrumClient.connect`, `app/electrum/client.py:ElectrumClient._read_loop` · *Test:* —
*Stato:* da implementare (B-75) · *Oggi:* il lettore ha il limite
predefinito di asyncio (64 KiB); una riga più lunga, o non JSON, interrompe
`_read_loop` e chiude l'unica connessione. La cronologia dell'indirizzo del
montepremi supera 64 KiB dopo 800 transazioni (stima di B-75), e da lì ogni controllo
delle conferme la fa cadere.
## 3. Caduta rilevata
- **[ELC-05]** La connessione viene pingata (`server.ping`) ogni 60 secondi
(`_PING_INTERVAL_SECONDS`); un ping fallito chiude la sessione.
*Codice:* `app/electrum/listener.py:ElectrumListener._keepalive`
- **[ELC-06]** La chiusura della connessione è un evento osservato: la
sessione termina non appena la connessione si chiude, il ping fallisce o
l'elaborazione degli header si interrompe con un errore. Il listener non
resta quindi in attesa di notifiche che non arriveranno mai mentre sembra
ancora connesso; a sessione finita il client non è più disponibile. Un
errore nell'aggiornamento di **un** utente dopo una notifica del suo
indirizzo non termina la sessione
([DEP-16](registrazione-e-depositi.md#deposito)).
*Codice:* `app/electrum/listener.py:ElectrumListener._run_once`, `app/electrum/client.py:ElectrumClient.wait_closed`, `app/electrum/listener.py:ElectrumListener._consume_scripthash` ·
*Test:* `tests/unit/test_electrum_client.py`
*Stato:* da implementare (B-96), per gli errori di aggiornamento di un
utente · *Oggi:* qualunque eccezione in `refresh_user` chiamato da
`_consume_scripthash` (ad esempio la collisione sull'outpoint di due
aggiornamenti concorrenti) termina la sessione.
- **[ELC-07]** Una connessione viene resa disponibile al resto del sistema
**solo dopo** che il primo header è stato applicato: se il client c'è,
l'altezza della catena è nota. Se il primo header è inutilizzabile (privo
del contenuto binario) e non si conosce ancora alcuna altezza, la sessione
viene rifiutata e si passa al server successivo. Chi trova il client assente
(ad esempio durante una riconnessione) salta semplicemente quel giro, e
scommesse e prelievi rispondono `network_unavailable`.
*Codice:* `app/electrum/listener.py:ElectrumListener._run_once` ·
*Test:* `tests/unit/test_electrum_listener.py`
- **[ELC-21]** **Server fermo.** Un server può restare connesso e rispondere
ai ping senza più seguire la catena. A ogni ping di [ELC-05], se l'ultimo
header accettato ha più di **360 secondi**, il listener chiede la punta
(`blockchain.headers.subscribe`) a ciascuno degli altri server configurati,
con i tempi di [ELC-14]; se almeno uno riporta un'altezza **maggiore** di
quella nota, la sessione termina e si passa al server successivo
nell'elenco ([ELC-02]). Se nessuno riporta un'altezza maggiore (la rete
non ha prodotto blocchi) la sessione continua.
*Codice:* `app/electrum/listener.py:ElectrumListener._keepalive` · *Test:* —
*Stato:* da implementare (B-86) · *Oggi:* nulla confronta l'avanzamento
della punta con gli altri server; un server fermo che risponde ai ping
resta il server attivo indefinitamente.
## 4. Header validati, non creduti
Ogni nuovo header di blocco — quello ricevuto all'iscrizione e ogni successivo
annunciato dal server — viene controllato prima di essere accettato. Il
listener tiene gli **ultimi 10 header** accettati ([ELC-22]): è ciò che gli
permette di riconoscere una riorganizzazione e seguirla invece di scambiarla
per un server ostile.
```mermaid
flowchart TB
A["Header annunciato<br/>all'altezza H"] --> B{"Ha il contenuto<br/>binario?"}
B -- "No" --> I1["Ignorato (ELC-10)"]
B -- "Sì" --> C{"H rispetto alla<br/>punta T"}
C -- "H < T" --> I2["Ignorato (ELC-08)"]
C -- "H = T, stesso hash" --> I3["Ignorato (ELC-09)"]
C -- "H = T, hash diverso" --> F
C -- "H > T" --> D["Si scaricano gli header<br/>T+1 … H−1 (ELC-12)"]
D --> E{"80 byte, bits non più<br/>facili del powLimit, hash<br/>entro il bersaglio? (ELC-11)"}
E -- "No" --> X["HeaderValidationError:<br/>sessione chiusa,<br/>server successivo"]
E -- "Sì" --> G{"T+1 si aggancia<br/>alla punta T?"}
G -- "Sì, e la catena<br/>è collegata fino a H" --> OK["Punta = H<br/>finestra aggiornata (ELC-13)"]
G -- "No" --> F["Ricerca del punto di<br/>biforcazione negli ultimi<br/>10 header (ELC-23)"]
F -- "Trovato" --> R["Si segue il nuovo ramo<br/>chain_reorg_detected;<br/>pausa se profondità ≥ 2 (ELC-24)"]
F -- "Non trovato" --> X
```
*Comportamento atteso.* Oggi un salto di più blocchi non viene collegato, la
difficoltà non è confrontata con il powLimit, e un header che non si aggancia
chiude la sessione.
Tre casi vengono semplicemente **ignorati**, con un avviso nei log e senza
chiudere la sessione, perché non indicano un server ostile:
- **[ELC-08]** un header per un'altezza **inferiore** a quella nota: l'altezza
non torna mai indietro. Un server rimasto indietro non sposta la punta, e un
ramo più corto del nostro non viene seguito. Il rovescio va detto: se un
header falso a un'altezza molto alta venisse accettato, nessun header
onesto (più basso) lo sostituirebbe più; la punta resta bloccata fino al
riavvio del processo (l'altezza è solo in memoria). Con [ELC-11] e
[ELC-12] quell'header deve portarsi dietro una catena collegata di header
con lavoro valido; e comunque non sceglie il vincitore, perché il blocco di
estrazione è letto a un'altezza fissa e confermato dal quorum ([ELC-15]):
l'estrazione attende, e l'attesa è visibile (`draw_stalled`,
`GET /health/ready`, [ELC-29]).
- **[ELC-09]** un header per l'altezza **già nota** con lo **stesso** hash
(lo stesso blocco riannunciato). Un header per l'altezza già nota con un
hash **diverso** non è ignorato: è una riorganizzazione in punta e si
segue secondo [ELC-23].
*Stato:* da implementare (B-85), per il caso con hash diverso · *Oggi:*
anche un hash diverso è ignorato e quello già adottato non viene mai
sostituito.
- **[ELC-10]** un header privo del contenuto binario: non c'è nulla da
validare né da usare per l'estrazione.
*Codice:* `app/electrum/listener.py:ElectrumListener._apply_header` ·
*Test:* `tests/unit/test_electrum_listener.py`
I controlli seguenti invece, se falliscono, **chiudono la sessione** e fanno
passare a un altro server.
- **[ELC-11]** L'header deve essere lungo 80 byte; il bersaglio che dichiara
(campo `bits`) non deve essere più facile del **powLimit** di PLM mainnet,
`00000000ffffffffffffffffffffffffffffffffffffffffffffffffffffffff`
(in forma compatta `0x1d00ffff`, lo stesso di Bitcoin; fonte:
`palladiumcore/src/chainparams.cpp`, `consensus.powLimit` della rete
principale); e il suo hash deve rispettare quel bersaglio. Il controllo
toglie la contraffazione **gratuita**, non quella economica: anche al
powLimit un header costa in media 2³² hash, 43 µs per un ASIC da
100 TH/s. Ciò che protegge davvero l'estrazione è il quorum sul blocco
([ELC-15]).
*Codice:* `app/rounds/draw.py:header_meets_its_own_target`, `app/electrum/listener.py:ElectrumListener._apply_header` ·
*Test:* `tests/unit/test_draw.py`, `tests/unit/test_electrum_listener.py`
*Stato:* da implementare (B-74), per il confronto con il powLimit ·
*Oggi:* si verifica solo che l'hash rispetti il bersaglio che l'header
stesso dichiara. Poiché è chi fabbrica l'header a scegliere `bits`, il
controllo non respinge un header mai minato: con `bits = 0x207fffff`
(bersaglio `0x7fffff · 2²³²`, appena sotto 2²⁵⁵) lo passa un header casuale con probabilità 1/2.
- **[ELC-12]** **Ogni** avanzamento della punta deve essere collegato alla
punta corrente. Un avanzamento di un blocco deve avere come `prev_hash`
l'hash della punta. Per un avanzamento di più blocchi, dalla punta `T` a
`H`, si scaricano dal server attivo gli header `T+1 … H−1`
(`blockchain.block.headers`, a blocchi di al più 2016 header per
richiesta); ciascuno deve superare [ELC-11] e agganciarsi al precedente, e
`H` all'ultimo. Un header scaricato che non supera [ELC-11], o una catena
scaricata spezzata, chiude la sessione. Se invece è il **primo** passo
(`T+1`, o `H` stesso per un avanzamento di un blocco) a non agganciarsi
alla punta, non si chiude la sessione: è una possibile riorganizzazione e
si segue [ELC-23].
*Codice:* `app/rounds/draw.py:header_prev_hash`, `app/electrum/listener.py:ElectrumListener._apply_header`, `app/electrum/client.py:ElectrumClient.request` ·
*Test:* `tests/unit/test_draw.py`, `tests/unit/test_electrum_listener.py`
*Stato:* da implementare (B-74) · *Oggi:* il collegamento si verifica solo
per un avanzamento di un blocco; un salto di più blocchi è accettato con il
solo controllo di difficoltà. Un avanzamento di un blocco che non si
aggancia chiude la sessione: per questo una normale riorganizzazione di un
blocco (la nostra punta `N` diventa orfana) fa chiudere la sessione su
**ogni** server — ciascuno annuncia `N+1` sul nuovo ramo, che non si
aggancia alla nostra `N` — finché l'arrivo di `N+2` non rende l'avanzamento
un salto di due blocchi, accettato senza controllo di collegamento.
- **[ELC-13]** Un header accettato aggiorna insieme altezza e contenuto della
punta (mai uno senza l'altro) e la finestra di [ELC-22]. Ogni notifica di
nuovi header invia una notifica SSE, perché è proprio ciò che l'estrazione
attende.
*Codice:* `app/electrum/listener.py:ElectrumListener._apply_header`, `app/electrum/listener.py:ElectrumListener._consume_headers` ·
*Test:* `tests/unit/test_electrum_listener.py`
- **[ELC-22]** Il listener tiene in memoria gli **ultimi 10 header**
accettati (altezza → contenuto), punta compresa. Il primo header del
processo non ha nulla a cui agganciarsi ed è accettato con il solo
[ELC-11]; subito dopo si scaricano i 9 header precedenti, che devono
superare [ELC-11] ed essere collegati fra loro e al primo, altrimenti la
sessione si chiude. La finestra sopravvive alle riconnessioni, non ai
riavvii.
*Codice:* `app/electrum/listener.py:ElectrumListener._apply_header`, `app/electrum/listener.py:ElectrumListener._run_once` · *Test:* —
*Stato:* da implementare (B-85) · *Oggi:* si tiene solo la punta
(`tip_height`, `tip_header_hex`).
### Riorganizzazioni
- **[ELC-23]** Quando un header non si aggancia alla punta ([ELC-12]) o ne
sostituisce l'hash alla stessa altezza ([ELC-09]), il listener cerca il
**punto di biforcazione**: chiede al server attivo gli header delle altezze
della finestra, dalla punta verso il basso, fino a 10, e prende la più alta
altezza in cui l'hash del server coincide con il nostro. Se lo trova, il
ramo del server dal punto di biforcazione fino al nuovo header deve
superare [ELC-11] ed essere collegato; allora sostituisce la finestra sopra
il punto di biforcazione e il nuovo header diventa la punta. Se non lo
trova entro 10 header (una biforcazione più profonda, o un server su
un'altra catena), la sessione si chiude come per [ELC-11].
*Codice:* `app/electrum/listener.py:ElectrumListener._apply_header` · *Test:* —
*Stato:* da implementare (B-74, B-85) · *Oggi:* nessuna riorganizzazione è
rilevata né seguita; vedi l'*Oggi* di [ELC-12].
- **[ELC-24]** Ogni riorganizzazione seguita scrive l'evento
`chain_reorg_detected` con la profondità (numero dei nostri blocchi
sostituiti, cioè vecchia altezza della punta meno altezza del punto di
biforcazione), l'altezza del punto di biforcazione, la vecchia e la nuova
altezza della punta e i due hash di punta. Con profondità **≥ 2** la
lotteria va in pausa (`paused = true`, `paused_reason = 'reorg'`, vedi
[modello-dati.md](modello-dati.md) B-85) finché l'operatore non la
riprende: come ogni pausa, impedisce solo l'apertura del round successivo.
Con profondità 1 si scrive solo l'evento.
*Codice:* `app/electrum/listener.py:ElectrumListener._apply_header`, `app/db/models.py:RoundConfig` · *Test:* —
*Stato:* da implementare (B-85) · *Oggi:* l'evento non esiste e nulla mette
in pausa la lotteria da solo.
## 5. Il quorum
Ogni decisione che sposta denaro in base a una risposta della rete viene
confermata dagli **altri** server configurati, mai dal solo server attivo
(che è proprio quello che un attaccante controllerebbe).
Oggi non è ancora così: solo le tre verifiche [ELC-15]–[ELC-17] sono
corroborate. Le conferme delle transazioni (`app/tx/confirmation.py:poll_once`),
l'abbandono di una transazione (`app/tx/reconcile.py:reconcile_once`), il
reintegro di una moneta ricomparsa
(`app/deposits/service.py:reinstate_reappeared_utxos`) e la lettura delle
monete del montepremi per il pagamento
(`app/rounds/scheduler.py:RoundScheduler._trigger_payout`) si basano sul solo
server attivo; sono le righe [ELC-26], [ELC-28], [ELC-25] e [ELC-27].
- **[ELC-14]** La corroborazione interroga in parallelo tutti i server
configurati tranne quello attivo, ciascuno con una connessione nuova e un
limite di 10 secondi (`_CORROBORATION_TIMEOUT_SECONDS`) per collegarsi e 10
per rispondere. Un server che non risponde o dà errore non conta. Passa se
hanno risposto **almeno 2** server **e** concorda la **maggioranza stretta
di quelli che hanno risposto**; con meno di 2 risposte **fallisce**: una
rete irraggiungibile, o un solo server raggiungibile, non prova nulla.
Con `ALLOW_NO_QUORUM=true` ([ELC-19]) vale invece la regola ridotta: senza
altri server configurati la verifica passa, altrimenti basta la
maggioranza stretta delle risposte, anche di una sola.
*Codice:* `app/electrum/listener.py:ElectrumListener._corroborate_majority` ·
*Test:* `tests/unit/test_electrum_listener.py`
*Stato:* da implementare (B-84) · *Oggi:* vale per tutti la regola ridotta.
Senza server di riserva ogni verifica passa; con server di riserva la
maggioranza è calcolata su chi ha risposto, quindi **una risposta su una
decide**: se è raggiungibile un solo altro server, la sua parola basta.
Nessuna risposta fa fallire la verifica.
| ID | Prima di… | Si verifica che… |
|---|---|---|
| **[ELC-15]** | usare un blocco per l'estrazione | l'header che ciascun server restituisce per l'altezza di estrazione (`blockchain.block.header`) abbia lo stesso hash; regole complete in [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#3--estrazione) (B-73) |
| **[ELC-16]** | togliere dal saldo una moneta sparita | l'altro server non elenchi più la moneta tra quelle non spese |
| **[ELC-17]** | accreditare un deposito | l'altro server elenchi la moneta tra quelle non spese, con lo stesso importo, a un'altezza che le dà almeno le conferme richieste ([DEP-03](registrazione-e-depositi.md#deposito)) contate sulla nostra punta |
| **[ELC-25]** | reintegrare una moneta data per spesa fuori | l'altro server elenchi la moneta tra quelle non spese, con lo stesso importo e confermata (altezza maggiore di 0), come per un accredito |
| **[ELC-26]** | segnare confermata una transazione | l'altro server restituisca per il txid una prova merkle (`blockchain.transaction.get_merkle`) che, ricalcolata, dà la radice merkle dell'header di quell'altezza; l'header è quello della finestra ([ELC-22]) o, se più vecchio, quello su cui concorda il quorum come in [ELC-15]. Regole della conferma in [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md#conferma) (B-83) |
| **[ELC-27]** | costruire il pagamento di un round | l'altro server elenchi come non spese le monete delle scommesse del round all'indirizzo del suo montepremi; regole in [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#4--pagamento) (B-82) |
| **[ELC-28]** | abbandonare una transazione | l'altro server riporti un suo ingresso speso in un blocco da un txid diverso, oppure non conosca nessuno dei suoi txid; regole in [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md#riconciliazione) (B-78) |
*Codice:* `app/electrum/listener.py:ElectrumListener.corroborate_header`,
`app/electrum/listener.py:ElectrumListener.corroborate_utxo_spent`,
`app/electrum/listener.py:ElectrumListener.corroborate_utxo_credit`,
`app/electrum/listener.py:ElectrumListener._corroborate_majority` ·
*Test:* `tests/unit/test_electrum_listener.py`
Stato delle righe della tabella:
- [ELC-15] — *Stato:* da implementare (B-73) · *Oggi:* si corrobora l'header
del primo blocco che il server attivo ha annunciato dopo la chiusura,
chiedendo solo agli altri server; se la verifica fallisce si passa al blocco
successivo invece di richiedere la stessa altezza.
- [ELC-17] — *Stato:* da implementare (B-82) · *Oggi:* basta un'altezza
maggiore di 0 (1 conferma).
- [ELC-25] — *Stato:* da implementare (B-83) · *Oggi:* il reintegro si basa
sulla sola risposta del server attivo.
- [ELC-26] — *Stato:* da implementare (B-83) · *Oggi:* una transazione è
confermata quando la cronologia dell'indirizzo sul server attivo la riporta
con altezza maggiore di 0.
- [ELC-27] — *Stato:* da implementare (B-82) · *Oggi:* il pagamento sceglie
fra le monete che il server attivo elenca per il montepremi.
- [ELC-28] — *Stato:* da implementare (B-78) · *Oggi:* si abbandona quando la
cronologia dell'indirizzo sul server attivo non contiene il txid.
I saldi si muovono in entrambe le direzioni, quindi entrambe richiedono lo
stesso quorum. Le conseguenze di una verifica non riuscita:
- un accredito non verificato è solo **rimandato**, non perso: la moneta viene
riproposta al controllo successivo
([DEP-04](registrazione-e-depositi.md#deposito));
- una moneta sparita non verificata resta nel saldo
([DEP-07](registrazione-e-depositi.md#deposito)), una moneta ricomparsa non
verificata resta fuori ([DEP-08](registrazione-e-depositi.md#deposito));
- una conferma non verificata lascia la transazione in attesa, e si riprova
al controllo successivo;
- un blocco di estrazione non verificato fa attendere e richiedere la stessa
altezza, e lo si registra in audit (`draw_header_corroboration_failed`,
[ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#3--estrazione)).
L'**invio** di una transazione non è una corroborazione ma usa gli stessi
server: dopo che il server attivo l'ha accettata, la transazione grezza viene
inviata anche a ogni server di riserva, al meglio. La regola è in
[transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md) (B-76,
B-83); oggi l'invio va al solo server attivo.
## Riconnessione
- **[ELC-18]** Alla riconnessione il listener si reiscrive agli indirizzi di
tutti gli utenti (letti dal database) e ne aggiorna le monete, in
un'attività separata, al massimo 20 alla volta (`_RESUBSCRIBE_CONCURRENCY`):
in questo modo l'altezza della catena — e con essa un'eventuale estrazione
in corso — continua ad aggiornarsi durante la reiscrizione. Un utente la cui
reiscrizione fallisce viene registrato nei log e saltato; lo riprende il
giro periodico di `DepositReconciler`
([DEP-10](registrazione-e-depositi.md#dep-10)). Se la sessione termina,
la reiscrizione in corso viene interrotta.
*Codice:* `app/electrum/listener.py:ElectrumListener._subscribe_all_users`, `app/electrum/listener.py:ElectrumListener._run_once` ·
*Test:* `tests/unit/test_electrum_listener.py`
## Stato della connessione
- **[ELC-29]** Il listener espone lo stato della connessione: se è connesso,
il server attivo, l'altezza della punta e da quanti secondi è stato
accettato l'ultimo header. Lo leggono `GET /health/ready` (non pronto se non
connesso o se l'ultimo header ha più di 360 secondi,
[api.md](api.md) B-92) e l'indicatore Electrum di `/admin`. L'altezza
corrente resta visibile anche nella barra di stato della catena di `/` (da
`chain_tip_height` di `GET /rounds/current`).
*Codice:* `app/electrum/listener.py:ElectrumListener.current_endpoint`, `app/main.py:health` · *Test:* —
*Stato:* da implementare (B-86, B-92) · *Oggi:* `/health` risponde sempre
`ok`; l'età dell'ultimo header non è registrata da nessuna parte e `/admin`
mostra solo l'altezza.
File diff suppressed because it is too large. Load diff
+17 -8
View File
@@ -2,6 +2,8 @@
Come gestire la configurazione operativa di PLM Lottery. Presuppone che il
server sia già avviato — vedi [running-the-server.md](running-the-server.md).
Per il funzionamento interno (stati del round, riconciliazione delle
transazioni, connessione Electrum) vedi [come-funziona.md](come-funziona.md).
## Accesso
@@ -23,7 +25,8 @@ sola schermata di login.
- **Utenti** — elenco utenti, saldo, accesso alla chiave privata, reset password
- **Round** — storico round: stato, vincitore, importi, txid di payout
- **Transazioni pendenti** — bet/payout/prelievi non ancora confermati, candidati al fee-bump RBF
- **Audit log** — eventi registrati dal sistema (config cambiata, bet, payout, accessi a chiavi private, ecc.)
- **Audit log** — eventi registrati dal sistema (config cambiata, bet, payout, accessi a chiavi private, ecc.; catalogo completo in [audit-log.md](audit-log.md))
- **Bug report** — segnalazioni inviate da `/report-bug`, da smistare `open` → `read` → `resolved`
## Parametri
@@ -90,8 +93,11 @@ sempre **chi ha originato la transazione**, non il destinatario: per bet e
prelievi è l'utente stesso (gli torna un resto più piccolo), per i payout è
il pool (il resto che torna all'indirizzo pool si riduce) — la quota del
vincitore e quella delle fee, già fissate, non vengono mai toccate. Se non
c'è un resto abbastanza grande da assorbire l'aumento, il bump fallisce e
resta un intervento manuale (vedi "Limiti noti").
c'è un resto abbastanza grande da assorbire l'aumento, il bump fallisce: la
transazione resta in attesa finché non conferma da sola o finché il
riconciliatore non la abbandona liberandone le monete (vedi
[transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md) e
[operativita.md](operativita.md)).
## Round
@@ -125,7 +131,7 @@ Eventi a cui vale la pena prestare attenzione:
| `pending_tx_abandoned` | Una transazione trasmessa è scomparsa dalla catena e il sistema l'ha dichiarata persa: UTXO liberati, bet rimossa o prelievo segnato `failed`. Se capita spesso, la fee rate configurata è probabilmente troppo bassa. |
| `pending_tx_recovered` | Una transazione che si credeva incompleta è invece finita in catena (tipicamente dopo un riavvio a metà invio) e il sistema l'ha ripresa da sé. |
| `bug_report_status_changed` | Un admin ha cambiato lo stato di una segnalazione (payload: `report_id`, stato precedente e nuovo). Con un token admin unico e condiviso, questa riga è l'unica traccia di chi tocca le segnalazioni. |
| `payout_failed` | Il payout di un round non è partito. Il round resta in `paying_out` e **richiede intervento manuale**: non esiste un retry automatico. Controlla `fee_address`, il saldo dell'indirizzo pool e la connessione Electrum. |
| `payout_failed` | Un tentativo di payout di un round non è partito; il campo `reason` dice perché. Il round resta in `paying_out` e lo scheduler **riprova da solo al massimo una volta ogni 60 secondi**. Se l'evento si ripete, controlla `fee_address`, il saldo dell'indirizzo pool e la connessione Electrum (procedure in [operativita.md](operativita.md)). |
## Alternative all'interfaccia grafica
@@ -182,11 +188,14 @@ per l'utente: solo un admin col token può farlo.
- Il token è unico e condiviso: non c'è identità per singolo admin né audit
di chi ha cambiato cosa (oltre alla tabella `audit_log` generica).
- Nessun rate limiting sugli endpoint admin (né su registrazione/bet/
prelievo utente).
- Nessun rate limiting sugli endpoint admin, né su bet e prelievo. Solo il
login (tentativi falliti) e la registrazione (5 account/ora per IP) sono
limitati — vedi [sicurezza.md](sicurezza.md).
- Se un payout fallisce (es. Electrum disconnesso, UTXO insufficienti), il
round resta bloccato in `paying_out` senza retry automatico — richiede
intervento manuale.
round resta in `paying_out` e il payout viene ritentato ogni 60 secondi;
alcuni motivi però non si risolvono da soli (vedi
[operativita.md](operativita.md)).
- Elenco completo dei limiti accettati: [decisioni-e-limiti.md](decisioni-e-limiti.md).
Per l'elenco completo dei gap noti vedi la sezione "Known gaps / TODO" in
`CLAUDE.md`.
+2
View File
@@ -2,6 +2,8 @@
Come usare PLM Lottery dall'interfaccia web (`https://<host>/` — vedi
[running-the-server.md](running-the-server.md) per come avviare il server).
Per cosa succede dietro le quinte (depositi, round, estrazione, pagamenti) vedi
[come-funziona.md](come-funziona.md).
## Registrazione e accesso
+1546
View File
File diff suppressed because it is too large. Load diff
+956
View File
@@ -0,0 +1,956 @@
# Operatività
Manuale operativo di PLM Lottery: dove stanno i dati, cosa salvare, cosa
succede a un riavvio, e cosa fare quando qualcosa si blocca. Presuppone
installazione e avvio già fatti: la prima configurazione è in
[setup.md](setup.md), i comandi Docker di tutti i giorni in
[running-the-server.md](running-the-server.md), l'uso del pannello in
[guida-admin.md](guida-admin.md). Qui c'è quello che quelle guide non coprono.
Le procedure citano spesso eventi del registro di audit: il loro significato
esatto è in [audit-log.md](audit-log.md). Il funzionamento interno che spiega
*perché* un round si blocca è in
[ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md),
[transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md) e
[connessione-electrum.md](connessione-electrum.md).
**Procedure e requisiti.** Le procedure (i passi numerati) descrivono cosa
fare **con il codice di oggi**; dove una correzione in corso le cambierà, una
nota "Dopo B-nn" dice come. I requisiti marcati *da implementare* descrivono
invece il comportamento atteso, non ancora presente (vedi
[processo-di-modifica.md](processo-di-modifica.md#requisiti-non-ancora-implementati)).
## Topologia
```mermaid
flowchart LR
Internet -- "80 / 443" --> caddy["container caddy<br/>(TLS, header di sicurezza)"]
caddy -- "app:8123" --> app["container app<br/>(FastAPI + 6 attività)"]
app -- "Electrum SSL" --> E1["server Electrum<br/>primario"]
app -. "rotazione e quorum" .-> E2["server di riserva<br/>(ELECTRUM_FALLBACK_SERVERS)"]
app --- db[("./data/db<br/>plm_lottery.db")]
app --- keys[("./data/keys<br/>master.xprv.enc")]
app --- logs[("./data/logs<br/>app.log")]
caddy --- cdata[("volumi Docker<br/>caddy_data, caddy_config")]
```
- **[OPS-01]** Il deployment è composto da due container definiti in
`docker-compose.yml`, entrambi con `restart: unless-stopped`: `app` (questo
codice, porta 8123 esposta solo sulla rete interna) e `caddy` (reverse proxy
sulle porte 80 e 443 dell'host). Il container `app` monta tre cartelle
dell'host: `./data/db` su `/app/db_data`, `./data/keys` su `/app/key_data`,
`./data/logs` su `/app/logs`; `DATABASE_URL` e `MASTER_KEY_PATH` sono
sovrascritti per puntare lì. Caddy tiene certificati e stato ACME nei volumi
Docker con nome `caddy_data` e `caddy_config`, non in `./data`.
*Codice:* `docker-compose.yml`, `Caddyfile`
Oggi il container gira come root, e i file che scrive in `./data` (database,
backup, chiave cifrata dagli script) appartengono a root sull'host. Dopo B-91
gira come utente non root, con `./data` in `0700` e i file di chiave in
`0600`, e la chiave di cifratura sta in un file a parte
([architettura.md](architettura.md) ARC-03, ARC-05;
[SEC-51](sicurezza.md#sec-51)); le procedure che scrivono in `./data`
dovranno allora rispettare quel proprietario.
- **[OPS-02]** All'avvio il container `app` esegue, in quest'ordine: controllo
che il file della master key esista (altrimenti esce con errore e un
suggerimento del comando da lanciare), `alembic upgrade head`, avvio del
server. Durante l'avvio dell'applicazione il server rifiuta di servire se
un segreto non è valido ([SEC-12](sicurezza.md#sec-12)), se la master key
non si decifra o non corrisponde agli indirizzi già salvati
([SEC-49](sicurezza.md#sec-49)), se una voce di
`ELECTRUM_FALLBACK_SERVERS` è malformata (`parse_endpoints`) o se il quorum
minimo non è configurato ([OPS-12]). Un `ADMIN_TOKEN` vuoto non blocca
l'avvio: il pannello resta chiuso a tutti. Un rifiuto termina il processo;
con `restart: unless-stopped` il container riparte e fallisce di nuovo,
quindi il sintomo è un container che si riavvia in continuazione, con il
motivo nell'output di `docker compose logs app`.
*Codice:* `Dockerfile` (`CMD`), `app/main.py:lifespan`,
`app/config.py:validate_runtime_secrets`,
`app/electrum/client.py:parse_endpoints`, `app/wallet/hd.py:_load_account_key` ·
*Test:* `tests/unit/test_config.py`, `tests/unit/test_electrum_client.py`
*Stato:* da implementare (B-89, B-84) · *Oggi:* della master key si
controlla solo che il file esista e che `XPRV_ENCRYPTION_KEY` non sia vuota;
una chiave sbagliata emerge alla prima derivazione, e il server parte anche
senza server di riserva.
- **[OPS-03]** Il database SQLite lavora in modalità **WAL**: accanto a
`plm_lottery.db` esistono `plm_lottery.db-wal` e `plm_lottery.db-shm`, e le
scritture più recenti possono trovarsi solo nel file `-wal`. I tre file vanno
sempre trattati insieme.
*Codice:* `app/db/base.py:_register_sqlite_pragmas` ·
*Test:* `tests/unit/test_db_base.py`
- **[OPS-04]** `/health` risponde sempre `{"status": "ok"}` finché il processo
è vivo: **non** dice nulla sulla connessione Electrum né sullo stato dei
round. Non va usato come unico segnale di salute (vedi
[Segnali da tenere d'occhio](#segnali-da-tenere-docchio)).
*Codice:* `app/main.py:health`
Dopo B-92 esiste anche `GET /health/ready`, che risponde 503 se la
connessione Electrum manca, l'ultimo header è vecchio o lo scheduler non gira
([api.md](api.md) API-46), ed è il `healthcheck` del container
([architettura.md](architettura.md) ARC-61). Un container `unhealthy` **non**
viene riavviato da Docker: è un segnale per l'operatore
([OPS-25]), da trattare con [OPS-11] o [OPS-13].
## Backup e ripristino
### Cosa salvare
| Cosa | Dove | Quanto spesso | Perché |
|---|---|---|---|
| Database | `./data/db/plm_lottery.db` (+ `-wal`, `-shm`) | Spesso (almeno giornaliero) e **prima di ogni deploy** | Utenti, indici di derivazione, UTXO, round, prelievi, audit |
| Master key cifrata | `./data/keys/master.xprv.enc` | Una volta (non cambia) | Da essa derivano tutti gli indirizzi e il montepremi |
| `XPRV_ENCRYPTION_KEY` | `.env` | Una volta, **in un luogo separato** dalla master key | Senza, la master key cifrata è illeggibile |
| Altri segreti di `.env` | `.env` | A ogni cambio | `JWT_SECRET`, `ADMIN_TOKEN`, server Electrum, `SITE_ADDRESS` |
| Stato di Caddy | volume `caddy_data` | Facoltativo | Certificati; Caddy li richiede di nuovo se mancano |
Il file da salvare è `./data/keys/master.xprv.enc`, quello che il container
legge. Su questa installazione esiste anche una seconda copia,
`./master.xprv.enc` nella radice del progetto, a cui punta il
`MASTER_KEY_PATH` di `.env` (B-71): oggi decifrano alla stessa xprv, ma non è
il file dell'app. Dopo B-91 la chiave di cifratura non sta più in `.env` ma
nel file `./secrets/xprv_encryption.key` ([SEC-53](sicurezza.md#sec-53),
[architettura.md](architettura.md) ARC-05), fuori da `./data/`: si salva come
oggi la variabile, separata dalla master key.
- **[OPS-05]** Master key cifrata e `XPRV_ENCRYPTION_KEY` si salvano **in posti
diversi**: uno dei due da solo non basta a spendere, entrambi insieme danno il
controllo di tutti i fondi. Perderli entrambi significa perdere per sempre i
fondi di tutti gli utenti e del montepremi. In alternativa si può conservare
offline la xprv in chiaro, ottenuta con `scripts/decrypt_master_key.py`: in
quel caso quella copia da sola è la chiave di tutto.
*Codice:* `app/wallet/keystore.py:decrypt_xprv`,
`scripts/decrypt_master_key.py`
- **[OPS-06]** Un backup coerente del database, **senza fermare il server**, si
fa con l'API di backup di SQLite, che include il contenuto del file WAL:
```bash
docker compose exec app python -c "import sqlite3; s=sqlite3.connect('/app/db_data/plm_lottery.db'); d=sqlite3.connect('/app/db_data/backup.db'); s.backup(d); d.close(); s.close()"
# il file compare come ./data/db/backup.db sull'host: spostarlo altrove
```
Copiare a mano il solo `plm_lottery.db` mentre il server gira **non** è un
backup affidabile ([OPS-03]). In alternativa: `docker compose stop app`,
copiare i tre file, `docker compose start app`, ma quel riavvio ha le
conseguenze descritte in [OPS-10]. Oggi il file di backup appartiene a root
sull'host ([Topologia](#topologia)).
*Codice:* `app/db/base.py:_register_sqlite_pragmas`
### Ripristino
Un database ripristinato è **indietro rispetto alla catena**: round già
estratti e pagati risultano ancora aperti, scommesse e prelievi fatti dopo il
backup non esistono, utenti registrati dopo il backup sono spariti. La
procedura serve a impedire che il sistema *rigiochi* quel passato con il
denaro di oggi.
- **[OPS-07]** Procedura di ripristino:
1. `docker compose down`. Il pubblico non deve raggiungere l'app finché la
procedura non è finita: `caddy` si riavvia solo al passo 10.
2. Rimettere `.env` (con la stessa `XPRV_ENCRYPTION_KEY` usata per cifrare la
master key) e `./data/keys/master.xprv.enc`. Se si ha solo la xprv in
chiaro, ricifrarla con `scripts/encrypt_master_key.py` lanciato nel
container (vedi [OPS-22], passo 0, per il perché).
3. Rimettere il database in `./data/db/plm_lottery.db` e **cancellare**
eventuali `-wal`/`-shm` rimasti dall'istanza precedente, che non
appartengono al file ripristinato.
4. **Mettere in pausa la lotteria nel database ripristinato, prima di
avviare l'app** (il valore di `paused` è quello del backup):
```bash
docker compose run --rm --no-deps app python -c "import sqlite3; c=sqlite3.connect('/app/db_data/plm_lottery.db'); c.execute('UPDATE round_config SET paused=1'); c.commit(); print('pausa impostata')"
```
La modifica non lascia una riga di audit: annotarla altrove.
Dopo B-90 si usa invece `START_PAUSED=true` in `.env` ([OPS-27]), che
scrive anche il motivo della pausa e la riga di audit.
5. **Elencare, sempre ad app ferma, i round non chiusi e le transazioni in
volo** del backup:
```bash
docker compose run --rm --no-deps app python -c "import sqlite3; c=sqlite3.connect('/app/db_data/plm_lottery.db'); print('ROUND'); [print(r) for r in c.execute(\"SELECT id,status,winner_user_id,payout_txid FROM rounds WHERE status!='closed'\")]; print('PENDING'); [print(r) for r in c.execute(\"SELECT id,kind,status,round_id,current_txid FROM pending_transactions WHERE status IN ('building','pending')\")]"
```
e, per ogni round trovato, i partecipanti
(`SELECT user_id,status,bet_txid FROM round_participants WHERE round_id=<ID>`,
con lo stesso comando).
6. **Confrontare ogni round non chiuso con la catena**, con un explorer,
**prima** di avviare l'app. È necessario perché la pausa ferma solo
l'apertura di round nuovi: appena c'è connessione, un round del backup in
`open`, `closing` o `paying_out` riprende da solo, chiude, estrae e paga
([OPS-09]). Oggi tutti i round usano lo stesso indirizzo del montepremi
(`derive_pool_address`, vedi [OPS-15]), quindi un pagamento rifatto
spenderebbe il denaro dei round successivi. Per ogni round:
- si guardano le uscite delle sue scommesse verso l'indirizzo del
montepremi (i `bet_txid` dei partecipanti) e, se c'è, `payout_txid`;
- **se una di quelle uscite è già spesa, o `payout_txid` è confermato**,
il round è già stato pagato dopo il backup. Va chiuso a mano, e ogni
sua riga `payout` ancora `building`/`pending` va segnata `failed`,
altrimenti il riconciliatore la abbandonerebbe e lo scheduler
ricostruirebbe il pagamento:
```bash
docker compose run --rm --no-deps app python -c "import sqlite3; c=sqlite3.connect('/app/db_data/plm_lottery.db'); print(c.execute(\"UPDATE rounds SET status='closed', closed_at=CURRENT_TIMESTAMP WHERE id=<ID> AND status!='closed'\").rowcount, 'round'); print(c.execute(\"UPDATE pending_transactions SET status='failed', failure_reason='restore: round already paid' WHERE kind='payout' AND round_id=<ID> AND status IN ('building','pending')\").rowcount, 'payout'); c.commit()"
```
Unica eccezione: se `payout_txid` della riga `pending` è proprio la
transazione confermata, non serve toccare nulla, perché il
`ConfirmationPoller` chiude il round da sé;
- **se tutte le uscite sono ancora non spese**, il round non è stato
pagato e può riprendere. I giocatori che hanno scommesso su quel round
*dopo* il backup non sono tra i partecipanti, ma i loro soldi sono nel
montepremi: annotarli per un rimborso manuale (nessuna procedura
supportata, vedi [OPS-24]);
- un round in `drawing` **non va mai sbloccato con [OPS-13]** prima di
questo controllo: se è già stato pagato, va chiuso come sopra.
Annotare ogni modifica (data, id, motivo): nessuna lascia una riga di
audit.
7. **Controllare gli indirizzi riassegnabili** con [OPS-28], sempre ad app
ferma.
8. Avviare **solo** l'app: `docker compose up -d --build app` (il servizio
`caddy` resta fermo). Le migrazioni si applicano da sole.
9. In `data/logs/app.log` aspettare `Electrum connected to …`. Alla
connessione il listener risottoscrive e aggiorna subito ogni utente
([ELC-18](connessione-electrum.md#riconnessione)), senza aspettare il giro
di 300 secondi di `DepositReconciler`: gli UTXO spesi dopo il backup
(scommesse e prelievi persi dal database) vengono segnati come spesi
all'esterno (`utxo_spent_externally`), quelli arrivati dopo vengono
accreditati (`deposit_credited`). Il riconciliatore risolve le righe
`building`/`pending` del backup al suo primo passaggio con la connessione
attiva. Controllare il registro di audit e "Transazioni pendenti".
10. `docker compose up -d` (riavvia `caddy`) e "Riprendi lotteria".
**Il rischio di replay.** Il riallineamento dei saldi è automatico e
immediato; quello dei round no. Ogni round del backup non ancora `closed`
riprende da solo appena c'è connessione, **anche con la lotteria in pausa**,
e ogni scommessa fatta dopo il backup è persa come partecipazione (il suo
UTXO risulta speso all'esterno, i suoi soldi sono nel montepremi). I passi
4–6 esistono per questo e vanno eseguiti prima del passo 8. Dopo B-80 e B-82
un round rigiocato paga solo gli UTXO del proprio indirizzo, dopo averli
verificati sulla rete, e resta quindi non pagabile invece di essere pagato
due volte; il controllo del passo 6 resta comunque il modo di sapere quali
round del backup sono già conclusi.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`,
`app/tx/reconcile.py:reconcile_once`,
`app/electrum/listener.py:ElectrumListener._subscribe_all_users`
- **[OPS-08]** **Rischio di un backup vecchio: indirizzi riassegnati.** Il
nuovo utente riceve l'indice di derivazione `max(derivation_index) + 1`.
Gli utenti registrati dopo il backup spariscono con il ripristino, e i loro
indici vengono riassegnati ai prossimi iscritti: il nuovo utente riceve lo
**stesso indirizzo** di un utente perso, e con esso i fondi che quello vi
aveva depositato. Oggi il codice non ha alcuna protezione: l'unica è la
procedura [OPS-28]. Dopo B-90 l'app controlla da sola gli indici successivi
e sospende le registrazioni
([REG-15](registrazione-e-depositi.md#registrazione)); la procedura resta il
modo di rimuovere la sospensione. Gli utenti persi non si possono
ricostruire dai log: `app.log` non registra né username né indice di una
registrazione, e il log di accesso riporta l'indirizzo di Caddy, non quello
del client.
*Codice:* `app/auth/routes.py:register`
- **[OPS-27]** Con `START_PAUSED=true` in `.env` l'app, all'avvio e prima che
lo scheduler faccia il suo primo ciclo, mette in pausa la lotteria come una
pausa dell'operatore (`paused_reason = 'operator'`, senza sovrascrivere un
motivo automatico già presente, [modello-dati.md](modello-dati.md) B-85) e
scrive `lottery_paused`; la pausa resta finché l'operatore non la toglie
("Riprendi lotteria"). Con il valore predefinito `false` l'avvio non tocca
la pausa.
*Codice:* `app/config.py:Settings`, `app/main.py:lifespan`,
`app/rounds/service.py:open_new_round_if_needed` ·
*Test:* —
*Stato:* da implementare (B-90) · *Oggi:* la variabile non esiste; la pausa
si imposta a mano nel database (passo 4 di [OPS-07]).
- **[OPS-28]** **Occupare gli indici di utenti persi.** Procedura, ad app
ferma, valida oggi e dopo B-90:
1. Trovare il massimo indice assegnato e ricavare gli indirizzi dei 20
indici successivi:
```bash
docker compose run --rm --no-deps app python -c "import sqlite3; from app.wallet.hd import derive_user_address; M=sqlite3.connect('/app/db_data/plm_lottery.db').execute('SELECT COALESCE(MAX(derivation_index),-1) FROM users').fetchone()[0]; print('max', M); [print(i, derive_user_address(i)) for i in range(M+1, M+21)]"
```
2. Controllare con un explorer quali hanno una cronologia. Se ne ha uno fra
gli ultimi della lista, ripetere il passo 1 partendo dal più alto con
cronologia.
3. Se nessuno ha cronologia, non c'è nulla da fare. Altrimenti inserire un
**account segnaposto per ogni indice** da `max + 1` fino al più alto con
cronologia (compresi quelli senza cronologia in mezzo, perché gli indici
si assegnano in ordine):
```bash
docker compose run --rm --no-deps app python -c "import sqlite3, secrets; from datetime import datetime, timezone; from app.auth.security import hash_password; from app.wallet.hd import derive_user_address; c=sqlite3.connect('/app/db_data/plm_lottery.db'); A, B = <DA>, <A>; [c.execute('INSERT INTO users (username, password_hash, derivation_index, address, cached_balance_sats, token_version, created_at) VALUES (?, ?, ?, ?, 0, 0, ?)', ('restore-%d' % i, hash_password(secrets.token_urlsafe(32)), i, derive_user_address(i), datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M:%S.%f'))) for i in range(A, B + 1)]; c.commit(); print(B - A + 1, 'segnaposto')"
```
La password casuale non viene mostrata a nessuno: l'account non è
utilizzabile finché l'operatore non lo consegna. L'inserimento non
lascia una riga di audit: annotarlo altrove.
4. All'avvio il listener si iscrive anche agli indirizzi segnaposto e
accredita i loro fondi. Quando un utente perso si presenta e dimostra di
conoscere il proprio indirizzo, gli si consegna il segnaposto
corrispondente con un reset della password ([OPS-19]).
Dopo B-90 il controllo automatico di
[REG-15](registrazione-e-depositi.md#registrazione), al riavvio successivo,
non trova più indirizzi usati oltre i segnaposto e le registrazioni
riprendono.
*Codice:* `app/wallet/hd.py:derive_user_address`,
`app/auth/security.py:hash_password`, `app/db/models.py:User`
## Riavvio
Un riavvio avviene a ogni deploy (`docker compose up -d --build`), a ogni
modifica di `.env` e da solo dopo un crash (`restart: unless-stopped`).
- **[OPS-09]** Al riavvio nessuna attività lavora finché il listener non ha una
connessione con un'altezza di catena nota. Poi, a seconda dello stato del
round attivo:
| Stato al momento del riavvio | Cosa succede |
|---|---|
| nessun round / `closed` | Si apre un nuovo round rispettando il cooldown del round precedente |
| `open` | Riprende: la scadenza è calcolata dai valori salvati sul round |
| `closing` | Riprende: si aspetta che le scommesse in volo confermino, poi si estrae |
| `drawing` | Riprende l'attesa dello stesso blocco di estrazione, con gli stessi partecipanti, e produce lo stesso vincitore ([ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#3--estrazione), B-81) |
| `paying_out` | Riprende: il pagamento viene ritentato subito se non c'è un `payout_failed` negli ultimi 60s; un pagamento già in volo non viene duplicato |
Le transazioni rimaste `building` (crash a metà invio) vengono risolte dal
riconciliatore secondo le regole di
[transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md)
(B-78): promosse se in catena, abbandonate solo con una prova. Si perdono
invece, perché solo in memoria: i blocchi dei login per troppi tentativi e
le quote per IP, le connessioni SSE (i browser si riconnettono da soli), i
lock per utente.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`,
`app/rounds/scheduler.py:RoundScheduler._retry_payout_if_due`,
`app/tx/reconcile.py:reconcile_once` ·
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_reconcile.py`
*Stato:* da implementare (B-81, B-78) · *Oggi:* un round in `drawing`
**non riprende**: resta in `drawing` per sempre e nessun nuovo round si apre
(serve [OPS-13]); una riga `building` non trovata nella cronologia del
server attivo viene abbandonata dopo 120 secondi dalla creazione, al primo
passaggio del riconciliatore (ogni 120s) con la connessione attiva.
- **[OPS-10]** **Riavvio sicuro e deploy** (nuova versione, modifica di
`.env`, rotazione di un segreto):
1. **Backup** del database ([OPS-06]), copiato fuori dall'host. Annotare la
versione in uso (`git rev-parse HEAD`) e la revisione del database
(`docker compose exec app alembic current`): servono per un rollback
([OPS-29]).
2. Verificare che `SITE_ADDRESS` sia scritto in `.env`
(`grep '^SITE_ADDRESS=' .env`). Se è stato passato solo sulla riga di
comando (`SITE_ADDRESS=… docker compose up -d`), un semplice
`docker compose up -d --build` lo perde e Caddy torna a `localhost` con un
certificato autofirmato: il sito pubblico smette di funzionare.
3. In `/admin` → Parametri → Manutenzione, "Interrompi dopo questo round"
(`POST /admin/pause`). Il round in corso finisce normalmente.
4. Aspettare che `GET /rounds/current` non riporti più un round attivo
(`round_id` vuoto, cioè l'ultimo round è `closed`) e che in "Transazioni
pendenti" non ci siano righe `building` (la sezione elenca anche righe già
confermate o fallite: guardare la colonna Stato).
5. Riavviare (`docker compose up -d --build`, oppure `docker compose up -d`
per un cambio di `.env`).
6. Controllare in `data/logs/app.log` la riga `Electrum connected to …`,
poi "Riprendi lotteria" (`POST /admin/resume`).
**Perché aspettare `closed` e non solo la pausa.** Oggi l'arresto non è
pulito: con uno stream SSE aperto (basta una pagina `/` aperta) uvicorn
aspetta che si chiuda, e Docker uccide il processo dopo 10 secondi. Ogni
deploy è quindi, per il codice, un crash: durante `drawing` blocca il round
([OPS-13]), durante un invio lascia una riga `building`. Dopo B-93 l'arresto
chiude gli stream e le attività entro 30 secondi; il riavvio
durante `drawing` diventa sicuro con B-81 ([OPS-09]).
La pausa non blocca scommesse e prelievi sul round in corso, né
registrazioni e depositi.
*Codice:* `app/api/routes/admin.py:pause_lottery`,
`app/rounds/service.py:open_new_round_if_needed` ·
*Test:* `tests/unit/test_admin.py`
Dopo B-93 lo spegnimento chiude gli stream SSE e attende le attività, entro
`stop_grace_period: 30s` ([architettura.md](architettura.md) ARC-22); ogni
rilascio ha un'immagine con un tag di versione e `SITE_ADDRESS` è
obbligatorio in `.env`: senza, `docker compose` rifiuta di partire invece di
ripiegare su `localhost` ([architettura.md](architettura.md) ARC-01, ARC-05).
- **[OPS-29]** **Rollback a una versione precedente.** Un'immagine vecchia non
parte su un database con migrazioni più nuove: il suo `alembic upgrade head`
non riconosce la revisione del database e il container esce, e si riavvia in
continuazione. Il database va quindi riportato indietro **con l'immagine
nuova, prima** di cambiare versione:
1. Pausa e attesa di `closed` come in [OPS-10], poi backup ([OPS-06]).
2. Trovare la revisione di destinazione: nella versione a cui si torna,
dal venv, `alembic heads` (legge solo i file di migrazione, non il
database).
3. `docker compose stop app`, poi, con l'immagine nuova ancora in uso,
`docker compose run --rm --no-deps app alembic downgrade <revisione>`.
4. `git checkout <versione>` e `docker compose up -d --build`.
5. Controllare il log e riprendere la lotteria.
Un downgrade cancella le colonne e le tabelle aggiunte dalle migrazioni
annullate, con i loro dati. Se un downgrade fallisce, si ripristina il
backup del passo 1 di [OPS-10] con [OPS-07], perdendo ciò che è successo
dopo il deploy. Dopo B-93 il passo 4 usa il tag dell'immagine precedente
invece di ricostruirla.
*Codice:* `migrations/`, `Dockerfile` (`CMD`)
## Procedure di intervento
Ogni procedura ha la stessa forma: come si riconosce, perché succede, cosa
fare. Per leggere il log: `tail -f data/logs/app.log` sull'host. I messaggi
dell'applicazione (scheduler, listener, riconciliatori) sono **solo** in quel
file; `docker compose logs app` mostra soltanto l'output di avvio del
container (controllo della chiave, migrazioni) e ciò che uvicorn scrive per
conto suo (avvio, richieste, errori di avvio). Vedi
[audit-log.md](audit-log.md#log-applicativo).
Dopo B-92 il log applicativo va anche sull'output del container e si legge
con `docker compose logs app` ([architettura.md](architettura.md) ARC-09).
### Electrum irraggiungibile
- **[OPS-11]**
**Sintomi.** In `/admin` la pillola "Blocco #N" e `chain_tip_height` di
`GET /rounds/current` restano fermi sull'ultimo valore noto (l'altezza non si
azzera alla disconnessione, quindi *non* si vede un errore, si vede un numero
che non cresce). Due casi diversi:
- **server irraggiungibili**: scommesse e prelievi rispondono 503
`network_unavailable`; nel log `Electrum session on … failed`,
`Electrum session on … ending`,
`all N Electrum server(s) unreachable, retrying in Ns`. Lo scheduler e le
altre attività saltano i loro cicli;
- **server connesso ma fermo**: nessun errore nel log, l'ultima riga di
connessione è `Electrum connected to <server>`, `ping` riesce, ma
l'altezza non cresce mentre un explorer o un altro server riportano
blocchi nuovi. Scommesse e prelievi vengono accettati, ma nulla conferma.
In entrambi i casi un round in `drawing` continua ad aspettare e dopo 360s
scrive `draw_stalled`.
**Causa.** Nel primo caso tutti i server configurati sono giù,
irraggiungibili o rifiutati (un header che non supera la validazione chiude
la sessione e fa passare al server successivo). Nel secondo il server attivo
ha smesso di seguire la catena: il listener lo rileva solo se la connessione
cade.
**Cosa fare.**
1. *Server irraggiungibili*: il listener prova il server successivo subito
e, dopo un giro completo di fallimenti, riprova con attesa crescente da 1
a 30 secondi, all'infinito. Se un server torna, la connessione si
ristabilisce da sola.
2. *Server fermo*: il ripristino **non** è automatico. Un riavvio riparte
sempre dal primario (`ELECTRUM_HOST`), quindi aiuta solo se il server
fermo è una riserva. Se il fermo è il primario, in `.env` sostituirlo con
un server che funziona (spostandolo tra le riserve o togliendolo) e
riavviare con [OPS-10]. Dopo B-86 il listener cambia server da solo
quando la punta non avanza da 360s e un altro server ne riporta una più
alta ([ELC-21](connessione-electrum.md#3-caduta-rilevata)).
3. Verificare un server dal container, senza toccare quello in esecuzione:
`docker compose run --rm --no-deps -e ELECTRUM_HOST=<host> -e ELECTRUM_PORT=<porta> app python scripts/electrum_smoke_test.py`
(senza `-e` prova il primario, vedi [OPS-26]). L'altezza stampata si
confronta con quella di `GET /rounds/current`.
4. Se i server configurati sono davvero tutti inutilizzabili, aggiungerne
altri in `ELECTRUM_FALLBACK_SERVERS` (elenco di riferimento:
`ChainProfiles.Mainnet.BootstrapServers` del repository PalladiumWallet) e
riavviare. **Se un round è in `drawing`, oggi il riavvio lo blocca**:
seguire poi [OPS-13].
*Codice:* `app/electrum/listener.py:ElectrumListener.run`,
`app/electrum/listener.py:ElectrumListener._keepalive`,
`app/api/routes/bets.py`, `app/api/routes/withdrawals.py` ·
*Test:* `tests/unit/test_electrum_listener.py`
- **[OPS-12]** Le regole del quorum sono di
[connessione-electrum.md](connessione-electrum.md): almeno 2 server di
riserva configurati o il server non parte
([ELC-19](connessione-electrum.md#1-rotazione-tra-server)), almeno 2
risposte per ogni corroborazione
([ELC-14](connessione-electrum.md#5-il-quorum)). La conseguenza operativa:
con meno di 2 server di riserva **raggiungibili** ogni corroborazione
fallisce, anche se il server attivo funziona — depositi non accreditati,
estrazione in attesa, segnalazioni di spesa esterna ignorate, nessun denaro
mosso. In produzione vanno quindi configurati almeno 3 server di riserva,
così che la caduta di uno non fermi la lotteria. `ALLOW_NO_QUORUM=true` non
si usa mai in produzione.
*Codice:* `app/electrum/listener.py:ElectrumListener._corroborate_majority`,
`app/main.py:lifespan` ·
*Test:* `tests/unit/test_electrum_listener.py`
*Stato:* da implementare (B-84) · *Oggi:* con `ELECTRUM_FALLBACK_SERVERS`
vuoto (il valore di `.env.example`) il server parte e la corroborazione
passa sempre: un solo server decide tutto. Con server di riserva la
maggioranza è su chi risponde, quindi basta una sola riserva raggiungibile;
se nessuna risponde, la corroborazione fallisce
(`draw_header_corroboration_failed` a ogni blocco).
### Round bloccato in `drawing`
- **[OPS-13]**
**Sintomi.** `GET /rounds/current` riporta `status: "drawing"` con
`draw_waiting_since` lontano nel tempo; nessun nuovo round si apre. Possibili
cause visibili:
- righe `draw_stalled` ripetute ogni 6 minuti: l'altezza della catena non
sale (Electrum, vedi [OPS-11]);
- righe `draw_header_corroboration_failed`, una per blocco: i blocchi
arrivano ma gli altri server non li confermano (vedi [OPS-12]);
- **nessuna riga nuova e nessun messaggio `still waiting for a block` nel
log**: l'attesa non è più in corso. Succede dopo un riavvio del processo,
oppure dopo un'eccezione durante l'attesa (messaggio
`round scheduler tick failed`, per esempio un database bloccato mentre si
scriveva `draw_stalled`). In questo caso il round non si sbloccherà mai da
solo.
**Causa.** L'attesa del blocco di estrazione vive solo dentro la chiamata
dello scheduler che ha portato il round in `drawing`; a ogni ciclo successivo
lo scheduler vede `drawing` e non fa nulla. Nessun codice riprende l'attesa.
Dopo B-81 lo scheduler riprende da solo un round in `drawing` e il terzo
caso scompare.
**Cosa fare.** Nei primi due casi basta risolvere la causa (Electrum,
server di riserva): l'estrazione avviene da sola al primo blocco valido.
Nel terzo caso **non esiste una procedura supportata dal codice**. L'unico
intervento possibile è una modifica manuale del database che riporti il round
a `closing`, lo stato da cui lo scheduler rifà l'estrazione da capo.
**Vale solo per un round bloccato nell'istanza in esercizio: un round in
`drawing` arrivato da un backup ripristinato si tratta con [OPS-07],
passo 6**, perché potrebbe essere già stato pagato.
1. Annotare l'id del round (dal pannello, sezione Round) e controllare che
sia davvero in `drawing` e che `winner_user_id` sia vuoto.
2. `docker compose stop app`.
3. Aggiornare lo stato:
```bash
docker compose run --rm --no-deps app python -c "import sqlite3; c=sqlite3.connect('/app/db_data/plm_lottery.db'); n=c.execute(\"UPDATE rounds SET status='closing' WHERE id=<ID> AND status='drawing' AND winner_user_id IS NULL\").rowcount; c.commit(); print(n, 'riga aggiornata')"
```
Deve stampare `1 riga aggiornata`.
4. `docker compose start app`.
5. Al primo ciclo lo scheduler rilegge i partecipanti confermati, riporta il
round in `drawing` con un nuovo `drawing_started_at` e aspetta un blocco
successivo all'altezza *attuale*; poi estrae e paga normalmente
(`winner_drawn`, `payout_sent`).
Conseguenze da sapere: l'estrazione usa un blocco successivo al momento
dello sblocco invece del primo blocco dopo la chiusura, quindi quale blocco
decide il vincitore dipende da quando l'operatore interviene; la modifica non
lascia alcuna riga nel registro di audit, quindi va annotata altrove, con
data, id del round e motivo. I partecipanti non cambiano: il round è fuori da
`open`, quindi nessuna scommessa nuova può entrare.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`,
`app/rounds/scheduler.py:RoundScheduler._close_and_draw`,
`app/rounds/scheduler.py:RoundScheduler._wait_for_next_block`
### Round bloccato in `closing`
- **[OPS-14]**
**Sintomi.** `GET /rounds/current` riporta `status: "closing"` a lungo, con
`has_pending_bets` vero; nel log compare
`round N: N bet(s) still in flight at close time, waiting` o nulla (il
controllo principale non scrive). In "Transazioni pendenti" c'è almeno una
riga `bet` di quel round in `building` o `pending`.
**Causa.** Il round non estrae finché ogni scommessa trasmessa non ha una
conferma. Una scommessa `pending` che resta nel mempool non viene mai
abbandonata dal riconciliatore, che abbandona solo ciò che **non compare**
nella cronologia dell'indirizzo: finché il server Electrum la conosce, anche
non confermata, il round aspetta.
**Cosa fare.**
1. Controllare `attempt_count` e `fee_rate_sat_vb` della riga: il
`RbfBumper` alza la commissione di 1 sat/vB ogni `rbf_timeout_seconds`
(predefinito 900s) dall'ultimo invio. Se sale, la scommessa confermerà
quando la commissione basta al mempool.
2. Se nel log compare `could not bump pending_transaction N`, l'RBF è
impossibile: vedi [OPS-17].
3. Se la riga è `building` da più di 2 minuti, il riconciliatore la risolve
al suo prossimo passaggio (ogni 120s).
4. Una transazione che il server attivo non conosce più viene abbandonata
dopo 6 ore dal primo invio (`pending_tx_abandoned`); il partecipante viene
rimosso e il round può chiudere. Dopo B-78 l'abbandono richiede una prova
(ingressi spesi altrove, o un nuovo invio rifiutato da tutti i server):
una transazione che nessuno conosce ma i cui ingressi non sono spesi non
viene più abbandonata per il solo passare del tempo.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`,
`app/tx/broadcast.py:RbfBumper`, `app/tx/reconcile.py:_is_due` ·
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_broadcast.py`,
`tests/unit/test_reconcile.py`
### Round bloccato in `paying_out`
- **[OPS-15]**
**Sintomi.** `status: "paying_out"` a lungo e, nel registro di audit, righe
`payout_failed` dello stesso round, al massimo una al minuto. Il campo
`reason` dice il motivo. Lo scheduler riprova da solo ogni 60 secondi: una
volta rimossa la causa, il pagamento parte al tentativo successivo senza
altri interventi. Un round in `paying_out` senza `payout_failed` e con una
riga `payout` `pending` che non conferma è un pagamento fermo nel mempool:
vedi [OPS-17].
| `reason` | Cosa fare |
|---|---|
| `electrum client not connected` | Vedi [OPS-11]. Si risolve da sola al ritorno della connessione |
| `no fee_address configured` | Impostare `fee_address` in `/admin` → Parametri. Succede solo se è stato svuotato a round in corso |
| `winner user not found` | Possibile solo se la riga dell'utente è stata cancellata a mano dal database. Nessuna procedura supportata: ripristinare la riga |
| `insufficient pool UTXOs` | Vedi sotto |
| `too_many_inputs` | Il pagamento richiederebbe più di 500 UTXO del montepremi (resti accumulati in molti round). Serve consolidare gli UTXO del montepremi con la sua chiave: **nessuno strumento lo fa**, vedi [OPS-24] |
| `winner_share_below_network_fee` | Il montepremi è troppo piccolo per la commissione di rete. Abbassare `fee_rate_sat_vb`; se è già 1, nessuna procedura supportata |
| `commission_below_dust_limit` | Il 30% è sotto 294 sat (montepremi sotto 980 sat, solo con un costo della scommessa minuscolo). Nessuna procedura supportata |
| `payout build failed` | Leggere la traccia nel log (`round N payout build failed`) |
| `broadcast rejected` | Si risolve da sola: la riga `building` viene abbandonata dal riconciliatore fra 120 e 240 secondi dopo (al primo passaggio oltre i 120s), `payout_txid` si azzera e il pagamento viene ricostruito. Se si ripete, la rete rifiuta la transazione: controllare il messaggio nel log e `fee_rate_sat_vb`. Oggi lo stesso motivo compare anche per un timeout o una connessione caduta durante l'invio, quando la transazione potrebbe essere partita; dopo B-76 solo un rifiuto esplicito libera la riga |
**`insufficient pool UTXOs`.** Il pagamento usa solo gli UTXO **confermati**
dell'indirizzo del montepremi, escludendo quelli già riservati da un altro
pagamento `building` o `pending` non risolto. Controllare in "Transazioni
pendenti" se c'è un `payout` di un round precedente ancora aperto: finché
resta tale, i suoi input sono esclusi. L'indirizzo del montepremi non è
mostrato dal pannello; si ottiene con
`docker compose exec app python -c "from app.wallet.hd import derive_pool_address; print(derive_pool_address())"`
e se ne può controllare il saldo con un explorer. Dopo B-80 ogni round ha
il proprio indirizzo (`rounds.pool_address`), e dopo B-82 un'uscita di
scommessa scomparsa dalla catena esclude quel partecipante invece di
bloccare il pagamento; solo la scommessa scomparsa del vincitore lo blocca
([OPS-30]).
Un pagamento già in volo (riga `payout` `building` o `pending` del round)
non viene mai duplicato: finché esiste, i tentativi vengono saltati senza
scrivere `payout_failed` e il round aspetta la conferma o l'abbandono.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout`,
`app/rounds/scheduler.py:RoundScheduler._retry_payout_if_due`,
`app/rounds/scheduler.py:_reserved_payout_outpoints` ·
*Test:* `tests/unit/test_scheduler.py`
### Transazione abbandonata
- **[OPS-16]**
**Sintomi.** Riga `pending_tx_abandoned` nel registro di audit; nel log
`abandoned <tipo> pending_transaction …`; la riga in "Transazioni pendenti"
passa a `failed`.
**Causa.** Oggi: la transazione non compare nella cronologia del proprio
indirizzo secondo il **solo server attivo**: mai partita (riga `building` da
oltre 120s) o scomparsa dal mempool (riga `pending` da oltre 6 ore dal primo
invio). Non è una prova: un server diverso da quello che ha ricevuto l'invio
può non conoscerla, e una versione precedente di una transazione accelerata
con RBF non viene cercata (B-77).
**Effetto e cosa fare.** Il sistema ha già annullato tutto: UTXO liberati e
saldo ricalcolato; per una scommessa il partecipante è rimosso (l'utente può
riscommettere se il round è ancora aperto); per un prelievo la richiesta è
`failed` e l'utente, che non vede lo storico, va avvisato di ripeterla; per
un pagamento `payout_txid` è azzerato e il nuovo tentativo parte da solo.
**Prima di avvisare l'utente o lasciar ripartire un pagamento, verificare
con un explorer** che né `txid` del payload né una sua versione precedente
(`replaced_by_txid` della riga) siano in catena: se lo sono, i fondi si sono
mossi davvero e il database dice il contrario. Per un prelievo, gli UTXO
liberati verranno poi segnati come spesi all'esterno dalla corroborazione;
per un pagamento già arrivato al vincitore, mettere subito in pausa la
lotteria e trattare il round come in [OPS-07], passo 6. Se gli abbandoni
sono frequenti, la commissione di rete configurata è probabilmente troppo
bassa. Dopo B-78 si abbandona solo con una prova, e una riga `failed` che
conferma più tardi mette in pausa la lotteria da sola ([OPS-30]).
*Codice:* `app/tx/reconcile.py:_abandon` ·
*Test:* `tests/unit/test_reconcile.py`
### RBF impossibile
- **[OPS-17]**
**Sintomi.** Nel log, ogni 30 secondi per la stessa riga,
`could not bump pending_transaction N` con un `RbfError`: "no change output
large enough to absorb a fee bump" oppure "already at the maximum fee rate".
Nessuna riga di audit. `attempt_count` smette di salire. Un aumento che la
rete rifiuta (per esempio perché il resto scenderebbe sotto la soglia di
polvere) compare invece come errore di invio nello stesso messaggio.
**Causa.** L'RBF riduce solo il resto che torna al mittente; se il resto non
basta a coprire l'aumento, o la commissione è già al massimo (10.000 sat/vB),
non si può fare. **Un pagamento di norma non ha resto** (spende esattamente
gli UTXO del montepremi), quindi oggi un pagamento fermo nel mempool non si
può accelerare in nessun caso.
**Cosa fare.** Nessuna procedura supportata. La transazione resta in attesa
alla commissione che ha: conferma quando il mempool la accetta, oppure, se
sparisce dal mempool, viene abbandonata dopo 6 ore ([OPS-16]). Se blocca un
round in `closing` ([OPS-14]), l'alternativa manuale è spendere il resto non
confermato con una commissione alta (CPFP) usando la chiave dell'utente
([OPS-23]); il sistema accrediterà l'uscita della nuova transazione come un
normale deposito. Per un pagamento non c'è un'alternativa supportata: la
chiave del montepremi non è esportabile ([OPS-24]).
Dopo B-79 ogni pagamento ha un'uscita di riserva che l'RBF può ridurre;
dopo B-87 un aumento che lascerebbe un resto sotto la soglia di polvere
toglie il resto invece di fallire, e ogni fallimento scrive
`rbf_bump_failed`.
*Codice:* `app/tx/broadcast.py:bump_fee`, `app/tx/broadcast.py:RbfBumper._tick` ·
*Test:* `tests/unit/test_broadcast.py`
### Deposito non accreditato
- **[OPS-18]**
**Sintomi.** Un utente segnala un deposito che non vede nel saldo.
**Cause, in ordine di probabilità.**
1. La transazione non ha ancora le conferme richieste: oggi 1, dopo B-82
`deposit_confirmations` (predefinito 6) e 120 per un'uscita coinbase
([registrazione-e-depositi.md](registrazione-e-depositi.md#deposito)).
Il deposito non viene mostrato nemmeno come "in attesa" finché non le ha.
2. La corroborazione fallisce: nel log
`N new UTXO(s) for user_id=… not corroborated by the other servers` e
spesso `could not corroborate … with any of N other configured server(s)`.
Vedi [OPS-12].
3. La sottoscrizione dell'indirizzo si è persa (log
`could not subscribe a newly-registered user's address` o
`resubscribing all users failed partway through`).
4. Electrum irraggiungibile o fermo ([OPS-11]).
5. Dopo B-75: l'importo è sotto `DUST_LIMIT_SATS` (294 sat) e non viene
accreditato per scelta.
**Cosa fare.** Verificare con un explorer che la transazione abbia le
conferme richieste e paghi esattamente l'indirizzo dell'utente (sezione
Utenti del pannello). Poi aspettare: `DepositReconciler` ricontrolla ogni
indirizzo ogni 300 secondi e accredita tutto ciò che il quorum conferma,
indipendentemente dalle notifiche. Un riavvio risottoscrive tutti gli
indirizzi, ma non serve e va fatto con [OPS-10]. Ogni accredito lascia una
riga `deposit_credited`.
*Codice:* `app/electrum/listener.py:ElectrumListener.refresh_user`,
`app/deposits/reconcile.py:DepositReconciler._sweep_once` ·
*Test:* `tests/unit/test_electrum_listener.py`,
`tests/unit/test_deposit_reconcile.py`
### Utente bloccato fuori
- **[OPS-19]**
**Password dimenticata.** In `/admin` → Utenti → "Reset": viene generata una
nuova password casuale, mostrata una sola volta, da comunicare all'utente per
un canale di cui ci si fida (non esiste un'email). Tutte le sessioni esistenti
dell'utente vengono invalidate. Resta la riga `admin_password_reset`.
Verificare l'identità di chi chiede: chi riceve la password controlla i fondi.
**Troppi tentativi.** Il login ha un freno per username e uno per IP
([SEC-30](sicurezza.md#sec-30)). Basta aspettare che il blocco scada; un
riavvio azzera tutti i contatori ma non è necessario.
*Codice:* `app/api/routes/admin.py:reset_user_password`,
`app/auth/rate_limit.py:AuthRateLimiters` ·
*Test:* `tests/unit/test_admin.py`, `tests/unit/test_rate_limit.py`
### Segreto compromesso
- **[OPS-20]** **`ADMIN_TOKEN` trapelato.** Chi lo possiede può esportare la
chiave privata di qualunque utente, cambiare `fee_address`, resettare
password e mettere in pausa la lotteria.
1. Generare un nuovo token
(`python -c "import secrets; print(secrets.token_urlsafe(32))"`),
scriverlo in `.env` e riavviare ([OPS-10], ma senza aspettare la fine del
round se l'urgenza lo richiede ed evitando solo lo stato `drawing`). Il
vecchio token smette di funzionare subito; gli operatori rientrano nel
pannello con quello nuovo.
2. Nel registro di audit cercare, dal momento presunto della fuga:
`admin_privkey_accessed` (quali chiavi sono uscite), `config_updated`
(soprattutto `fee_address`), `admin_password_reset` (account presi), e per
quegli utenti `withdrawal_sent`.
3. **La chiave di un utente esportata resta compromessa per sempre**:
l'indirizzo di un utente è permanente e il codice non ha un modo per
assegnargliene un altro. L'unica difesa è spostare subito i fondi di
quell'indirizzo ([OPS-23]) e avvisare l'utente di non depositarvi più.
*Codice:* `app/api/routes/admin.py:require_admin`
- **[OPS-21]** **`JWT_SECRET` trapelato.** Chi lo possiede può fabbricare una
sessione valida per qualunque utente e quindi scommettere o prelevarne i
fondi. Generare un nuovo segreto di almeno 32 caratteri, scriverlo in `.env` e
riavviare: **tutte** le sessioni esistenti diventano invalide e ogni utente
deve rifare il login. Poi controllare `withdrawal_sent` nel registro di audit
per prelievi inattesi. Per invalidare le sessioni di un solo utente basta
invece un reset della sua password ([OPS-19]).
*Codice:* `app/auth/security.py:decode_access_token`,
`app/config.py:validate_runtime_secrets`
- **[OPS-22]** **Rotazione di `XPRV_ENCRYPTION_KEY`** (la master key non
cambia, cambia solo la sua cifratura). Tutti i passi girano **nel
container**, dove `MASTER_KEY_PATH` è forzato su
`/app/key_data/master.xprv.enc`, cioè il file che l'app legge:
0. **Verificare quale file si sta ruotando.** Il file dell'app è
`./data/keys/master.xprv.enc`. Dal venv gli script usano invece il
`MASTER_KEY_PATH` di `.env` (`grep '^MASTER_KEY_PATH=' .env`), che su
questa installazione punta alla copia `./master.xprv.enc` nella radice
(B-71): una rotazione fatta dal venv riscriverebbe quella copia, l'app
leggerebbe il file vecchio con la chiave nuova e fallirebbe alla prima
derivazione. Per questo nessun passo usa il venv.
1. Pausa, attesa di `closed` e backup come in [OPS-10], poi
`docker compose stop app`. Tenere una copia del file attuale per poter
tornare indietro: `cp data/keys/master.xprv.enc data/keys/master.xprv.enc.old`.
2. Annotare gli indirizzi derivati con la chiave vecchia:
```bash
docker compose run --rm --no-deps app python -c "from app.wallet.hd import derive_pool_address, derive_user_address; print(derive_pool_address(), derive_user_address(0))"
```
3. `docker compose run --rm --no-deps app python scripts/decrypt_master_key.py`
con la chiave vecchia ancora in `.env`, e conservare la xprv stampata
solo per il tempo necessario.
4. Generare la chiave nuova
(`python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`)
e scriverla in `.env` al posto della vecchia.
5. `docker compose run --rm --no-deps app python scripts/encrypt_master_key.py --overwrite`
e incollare la xprv.
6. **Verificare la decifratura con la chiave nuova prima di riavviare**:
rilanciare il comando del passo 2. Deve stampare gli stessi due
indirizzi. Se dà errore o indirizzi diversi, non avviare l'app: rimettere
in `.env` la chiave vecchia e `master.xprv.enc.old` al posto del file, e
ricominciare.
7. `docker compose up -d`, controllare il log, riprendere la lotteria.
8. Aggiornare i backup ([OPS-05]) e cancellare `master.xprv.enc.old`. Se la
rotazione è dovuta a una fuga della chiave vecchia, distruggere anche ogni
copia cifrata con essa: la copia nella radice (`./master.xprv.enc`, B-71)
e i backup precedenti del file. Il file scritto dal container appartiene a
root con permessi `0644`: `sudo chmod 600 data/keys/master.xprv.enc`.
Dopo B-89 gli script scrivono `0600` e rifiutano una xprv i cui
indirizzi non coincidono con quelli del database
([SEC-50](sicurezza.md#sec-50)); dopo B-91 la chiave sta in un file e non
in `.env` ([SEC-53](sicurezza.md#sec-53)).
**Se è trapelata la master key stessa** (file cifrato *e* chiave, oppure la
xprv in chiaro), sono a rischio tutti i fondi degli utenti e del montepremi.
Non esiste una procedura supportata per passare a una nuova master key: ogni
indirizzo, compreso quello del montepremi, deriva da essa, e cambiarla
cambierebbe tutti gli indirizzi senza spostare i fondi né aggiornare il
database.
*Codice:* `app/wallet/keystore.py:encrypt_xprv`, `app/wallet/hd.py:_load_account_key`,
`scripts/encrypt_master_key.py`, `scripts/decrypt_master_key.py`
### Pausa automatica
- **[OPS-30]** Oltre all'operatore, il sistema mette in pausa la lotteria da
sé in tre casi, ognuno con il proprio motivo (`paused_reason`, valori in
[modello-dati.md](modello-dati.md) B-85) e una riga di audit. La pausa ha
l'effetto di sempre: nessun round nuovo si apre, quello in corso prosegue
salvo dove indicato. Solo l'operatore la toglie ("Riprendi lotteria", che
azzera anche il motivo); `/admin` mostra il motivo. Prima di riprendere
l'operatore esegue la verifica della tabella.
| Motivo | Quando | Cosa fare prima di riprendere |
|---|---|---|
| `operator` | "Interrompi dopo questo round", oppure avvio con `START_PAUSED=true` ([OPS-27]) | Dopo un ripristino, le verifiche di [OPS-07] |
| `reorg` | Riorganizzazione della catena profonda almeno 2 blocchi (`chain_reorg_detected`, [ELC-24](connessione-electrum.md#riorganizzazioni), B-85) | Confrontare con un explorer e con i server di riserva ([OPS-11], passo 3) la punta attuale e l'altezza di biforcazione del payload. Controllare le righe `participant_reorged_out`, `utxo_spent_externally` e `pending_tx_resurrected` scritte dopo. Riprendere quando la punta ha superato l'altezza di biforcazione di almeno `deposit_confirmations` blocchi senza un'altra `chain_reorg_detected` |
| `resurrected_tx` | Una transazione dichiarata `failed` è stata confermata (`pending_tx_resurrected`, [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md#riconciliazione), B-78) | La riga torna `confirmed`, ma le righe collegate restano come le aveva lasciate l'abbandono: il database dice che i fondi non si sono mossi, la catena il contrario. Secondo `kind` del payload: *prelievo* → l'utente ha ricevuto i fondi, e il prelievo risulta `failed`; gli UTXO liberati verranno segnati come spesi all'esterno dalla corroborazione, ma nel frattempo erano di nuovo spendibili: controllare che l'utente non li abbia già prelevati o scommessi con un'altra transazione; *scommessa* → i soldi sono nel montepremi del round senza partecipante: rimborso manuale ([OPS-24]); *pagamento* → il vincitore potrebbe essere stato pagato due volte: confrontare `payout_txid` del round con la catena |
| `payout_blocked` | La scommessa del vincitore non è più sulla catena ([RND-39](ciclo-di-vita-del-round.md#4--pagamento), B-82) | Il round resta in `paying_out` con `payout_blocked_at`. Verificare con un explorer che l'uscita della scommessa sia davvero spesa altrove (doppia spesa del deposito): è il segno di un probabile attacco, e le prove vanno conservate. Alla ripresa la verifica di RND-39 si ripete: se la scommessa è ancora assente, il pagamento resta bloccato e la lotteria torna in pausa |
*Codice:* `app/api/routes/admin.py:pause_lottery`,
`app/api/routes/admin.py:resume_lottery`,
`app/rounds/service.py:open_new_round_if_needed`,
`app/electrum/listener.py:ElectrumListener._apply_header`,
`app/tx/confirmation.py:poll_once`,
`app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
*Test:* —
*Stato:* da implementare (B-85, B-78, B-82, B-90) · *Oggi:* esiste solo la
pausa dell'operatore, senza motivo; nessun evento del sistema mette in pausa
la lotteria.
### Intervento manuale sui fondi
- **[OPS-23]** **Spostare i fondi di un utente con la sua chiave privata.**
Serve per restituire fondi bloccati, per un CPFP ([OPS-17]) o dopo una fuga
della chiave ([OPS-20]).
1. In "Transazioni pendenti" verificare che l'utente non abbia scommesse o
prelievi `building`/`pending`: i loro input sono già impegnati e
spenderli altrove crea un conflitto che fa fallire una delle due
transazioni.
2. Per evitare che l'utente agisca nel frattempo, si può resettarne la
password ([OPS-19]), che chiude le sue sessioni.
3. `/admin` → Utenti → "Mostra" (riga `admin_privkey_accessed`). La chiave
WIF va importata in un portafoglio PLM (per esempio PalladiumWallet), mai
salvata altrove.
4. Inviare i fondi dove serve.
5. Quando la spesa è confermata, il listener vede gli UTXO scomparire, chiede
conferma agli altri server e li segna come spesi all'esterno
(`utxo_spent_externally`): il saldo nel database scende da solo. Nulla va
modificato a mano.
**Restituire fondi a un utente** non richiede chiavi: si inviano al suo
indirizzo e vengono accreditati come un deposito (`deposit_credited`).
*Codice:* `app/api/routes/admin.py:user_privkey`,
`app/deposits/service.py:mark_utxos_spent_externally`
- **[OPS-24]** **Fondi del montepremi.** La chiave del montepremi
(`m/84'/746'/0'/1/0` della master key) non è esportabile dal pannello né da
alcuno script: l'unico modo è derivarla a mano dalla xprv ottenuta con
`scripts/decrypt_master_key.py`. Non c'è quindi una procedura supportata per
consolidare gli UTXO del montepremi (`too_many_inputs`), per recuperare
resti accumulati o per rimborsare una scommessa rimasta senza partecipante.
Spendere UTXO del montepremi fuori dal sistema non è rilevato come spesa
esterna (l'indirizzo non è in `utxo_events`) e può far fallire il pagamento
di un round in corso (`insufficient pool UTXOs` o una trasmissione
rifiutata): farlo solo senza round in `paying_out`. Dopo B-80 ogni round ha
il proprio indirizzo `m/84'/746'/0'/2/<round_id>` e `m/84'/746'/0'/1/0`
diventa l'indirizzo di riserva; il pagamento di un round spende solo le
uscite delle sue scommesse.
*Codice:* `app/wallet/hd.py:derive_pool_key`,
`app/rounds/scheduler.py:RoundScheduler._trigger_payout`
## Segnali da tenere d'occhio
- **[OPS-25]** Non esiste un sistema di allarmi: i segnali vanno controllati
a mano o con uno strumento esterno che interroghi l'API e legga il log.
| Segnale | Dove | Allarme se |
|---|---|---|
| Altezza della catena | `chain_tip_height` in `GET /rounds/current` | Non cresce per più di 10 minuti (blocchi ogni 120s): Electrum giù o fermo ([OPS-11]) |
| Stato e durata del round | `status`, `closes_at`, `draw_waiting_since` in `GET /rounds/current` | `closing` o `paying_out` per più di 3 blocchi (6 minuti); `drawing` oltre 6 minuti ([OPS-13]–[OPS-15]) |
| Istanza configurata | `lottery_configured` in `GET /rounds/current` | `false`: manca `fee_address`, nessun round si apre |
| Pausa dimenticata | `lottery_paused` in `GET /rounds/current` | `true` fuori da una manutenzione |
| Pagamenti ed estrazioni | Audit: `payout_failed`, `draw_stalled`, `draw_header_corroboration_failed` | Qualunque occorrenza |
| Transazioni perse | Audit: `pending_tx_abandoned` | Qualunque occorrenza va verificata ([OPS-16]); frequenti: commissione troppo bassa |
| Spese esterne | Audit: `utxo_spent_externally` | Non dovute a un intervento dell'operatore: chiave dell'utente compromessa o server che mente |
| Uso del pannello | Audit: `admin_privkey_accessed`, `config_updated`, `admin_password_reset` | Non attribuibili a un operatore: `ADMIN_TOKEN` compromesso ([OPS-20]) |
| Transazioni lente | `/admin` → Transazioni pendenti | `attempt_count` alto o `broadcast_at` (primo invio) vecchio di ore |
| Log | `data/logs/app.log` | `all N Electrum server(s) unreachable`, `round scheduler tick failed`, `could not bump`, `invariant violated` |
| Disco | `./data/db`, `./data/logs` | Il database cresce senza limite (registro di audit incluso); i log ruotano a 6 × 10 MB |
| Container | `docker compose ps` | `app` che si riavvia in continuazione: rifiuto all'avvio ([OPS-02]) |
| Prontezza (dopo B-92) | `GET /health/ready`, `docker compose ps` | 503 / `unhealthy` ([OPS-04]) |
| Catena e sistema (dopo B-78, B-82, B-85, B-87, B-90) | Audit: `chain_reorg_detected`, `pending_tx_resurrected`, `payout_blocked`, `participant_reorged_out`, `rbf_bump_failed`, `restore_gap_detected`; `paused_reason` diverso da `operator` | Qualunque occorrenza ([OPS-30], [OPS-28]) |
*Codice:* `app/api/routes/rounds.py`, `app/api/routes/admin.py`,
`app/logging_config.py:setup_logging`
Dopo B-92 l'indicatore Electrum di `/admin` mostra lo stato della
connessione ([ELC-29](connessione-electrum.md#stato-della-connessione)):
connessa o no, server attivo, altezza, età dell'ultimo header. Oggi mostra
solo l'ultima altezza nota ("Blocco #N"), che resta visibile anche a
connessione caduta.
## Prova su rete reale
I test automatici simulano la rete. Nessuna delle falle critiche della
revisione del 2026-09-28 sarebbe emersa da essi, e prelievo e RBF non sono mai
stati trasmessi davvero. Prima di aprire al pubblico, e dopo le correzioni di
[piano-correzioni.md](piano-correzioni.md), serve una prova su un'istanza di
staging collegata alla rete PLM reale (o, dove indicato, a una rete di prova),
con importi piccoli (costo della scommessa 0,1 PLM) e guasti provocati di
proposito.
- **[OPS-31]** L'istanza si apre al pubblico solo dopo che ogni prova della
tabella è stata eseguita e ha dato l'esito atteso. Per ogni prova si
annotano data, versione (`git rev-parse HEAD`), txid coinvolti ed esito, e
una prova con esito diverso diventa una voce di [BUGS.md](../BUGS.md).
*Codice:* —
| # | Prova | Come | Esito atteso |
|---|---|---|---|
| 1 | Ciclo completo | Due utenti, depositi, una scommessa ciascuno, un round intero | Deposito accreditato dopo `deposit_confirmations` conferme; `draw_committed` all'ingresso in `drawing`; vincitore, seme rivelato e prova di `GET /rounds/{id}/proof` ricalcolabili a mano; ripartizione 70/30 al satoshi; round `closed` e round successivo aperto |
| 2 | Prelievo reale | Prelievo parziale e prelievo dell'intero saldo | Transazione confermata; importo e resto come in [scommesse-e-prelievi.md](scommesse-e-prelievi.md); il prelievo totale lascia un resto di almeno `DUST_LIMIT_SATS` |
| 3 | Server ucciso durante un invio | Interrompere la rete del server Electrum attivo (o `docker compose kill app`) mentre una scommessa e un prelievo sono in invio | Nessun rilascio senza prova (B-76): la risposta è 202 o l'errore esplicito; la riga resta `building` e il riconciliatore la promuove se la transazione è in catena; nessun UTXO liberato per una transazione partita |
| 4 | Riavvio durante `drawing` | `docker compose restart app` con un round in `drawing` | Il round riprende da solo (B-81) con lo stesso `draw_height` e gli stessi partecipanti, e il vincitore è quello calcolabile dalla prova |
| 5 | Pagamento fermo a commissione bassa | `fee_rate_sat_vb` = 1 con mempool affollato, oppure invio del pagamento a un solo server che non lo propaga | Dopo `rbf_timeout_seconds` il pagamento viene accelerato riducendo l'uscita di riserva (B-79) e conferma; se l'aumento è impossibile compare `rbf_bump_failed` (B-87) |
| 6 | Riorganizzazione di 1 blocco | Solo su una rete di prova con due minatori, se disponibile | La punta segue il ramo nuovo senza chiudere la sessione; `chain_reorg_detected` con profondità 1; nessuna pausa. Con profondità 2: pausa con motivo `reorg` (B-85, B-74) |
| 7 | Cronologia molto lunga | Indirizzo con risposta oltre 64 KiB (per esempio mille piccoli invii a un indirizzo di prova) | La connessione resta aperta (limite di 16 MiB); le uscite sotto `DUST_LIMIT_SATS` non vengono accreditate (B-75) |
| 8 | Tutte le riserve giù | Bloccare con il firewall ogni server di `ELECTRUM_FALLBACK_SERVERS` | Accrediti rinviati, estrazione in attesa, nessuna spesa esterna registrata, nessun denaro mosso; al ritorno dei server tutto riprende. Un avvio con meno di 2 riserve è rifiutato (B-84) |
| 9 | Server connesso ma fermo | Un server Electrum di prova che smette di seguire la catena | Dopo 360 secondi senza avanzamento il listener passa a un server con una punta più alta (B-86); `GET /health/ready` risponde 503 nel frattempo (B-92) |
| 10 | Salto dell'orologio | Portare avanti l'orologio dell'host di 7 ore con transazioni `pending` | Nessuna transazione abbandonata per il solo tempo trascorso (B-78) |
| 11 | Disco pieno | Riempire il filesystem di `./data/db` durante l'attività | Nessuna transazione trasmessa senza la sua riga salvata prima; scommesse e prelievi falliscono prima dell'invio; liberato lo spazio, il sistema riprende senza interventi sul database |
| 12 | Ripristino da backup | Backup, poi un round completo e una registrazione, poi [OPS-07] | Avvio in pausa con `START_PAUSED=true`; `restore_gap_detected` e registrazioni rifiutate; il round rigiocato non viene pagato una seconda volta (B-90, B-80, B-82) |
| 13 | Chiave sbagliata | Avvio con una `XPRV_ENCRYPTION_KEY` diversa, poi con una master key diversa | Il server rifiuta di servire in entrambi i casi (B-89) |
| 14 | Deploy con stream aperti | `docker compose up -d --build` con pagine `/` aperte | Arresto completo entro 30 secondi senza uccisione del processo (B-93) |
## Script manuali
Si lanciano nel container con `docker compose run --rm --no-deps app python
scripts/<nome>.py`, oppure dal venv sull'host (`source .venv/bin/activate`,
con `PYTHONPATH=.`). Nel container `MASTER_KEY_PATH` punta a
`/app/key_data/master.xprv.enc`, cioè allo stesso file `./data/keys` dell'host;
dal venv conta il `MASTER_KEY_PATH` di `.env`, che su questa installazione
punta a un'altra copia (B-71, vedi [OPS-22], passo 0): per gli script sulla
master key usare il container.
- **[OPS-26]** Gli script disponibili:
| Script | Cosa fa | Quando |
|---|---|---|
| `scripts/generate_master_key.py` | Crea una master key casuale, la cifra con `XPRV_ENCRYPTION_KEY` e la scrive in `MASTER_KEY_PATH`. Si rifiuta se il file esiste già | Una sola volta, alla prima installazione ([setup.md](setup.md)) |
| `scripts/encrypt_master_key.py` | Cifra una xprv incollata (input nascosto) e la scrive in `MASTER_KEY_PATH`, con ripiego su `./data/keys/` se la cartella di `MASTER_KEY_PATH` non esiste. Rifiuta una xpub e un file già presente senza `--overwrite` | Installazione con una xprv generata altrove; ripristino da xprv in chiaro ([OPS-07]); rotazione della cifratura ([OPS-22]) |
| `scripts/decrypt_master_key.py` | Decifra e stampa la xprv, dopo aver chiesto di scrivere `yes`. Cerca il file in `MASTER_KEY_PATH`, poi in `./data/keys/master.xprv.enc` | Backup offline ([OPS-05]), rotazione ([OPS-22]), recupero dei fondi del montepremi ([OPS-24]) |
| `scripts/electrum_smoke_test.py` | Si collega **solo** al server primario (`ELECTRUM_HOST`/`PORT`/`USE_SSL`), fa l'handshake, si iscrive agli header e stampa l'altezza | Diagnosi di [OPS-11]. Per provare un altro server, lanciarlo con `-e ELECTRUM_HOST=… -e ELECTRUM_PORT=…` |
`generate_master_key.py` non ha il ripiego su `./data/keys/` degli altri
due: dal venv scrive esattamente dove dice `MASTER_KEY_PATH` di `.env`. I
file scritti hanno i permessi predefiniti del sistema (di norma `0644`) e,
nel container, appartengono a root. Dopo B-89 gli script scrivono `0600` e
rifiutano una xprv diversa da quella degli indirizzi già nel database
([SEC-50](sicurezza.md#sec-50)).
*Codice:* `scripts/generate_master_key.py`, `app/wallet/hd.py:generate_master_key`,
`scripts/encrypt_master_key.py`, `scripts/decrypt_master_key.py`,
`scripts/electrum_smoke_test.py`
+127
View File
@@ -0,0 +1,127 @@
# Piano delle correzioni (revisione del 2026-09-28)
La revisione della specifica del 2026-09-28 (coin e catena, macchina a stati
del denaro, operatività, coerenza dei documenti) ha trovato falle logiche
nella struttura del software. Questo documento raccoglie **le decisioni prese**
e **l'ordine in cui implementarle**.
La specifica è già stata aggiornata al comportamento **atteso**. Ogni
requisito che il codice non soddisfa ancora è marcato
`*Stato:* da implementare (B-nn)` e dice in una riga cosa fa il codice oggi
(vedi [processo-di-modifica.md](processo-di-modifica.md#requisiti-non-ancora-implementati)).
Il dettaglio tecnico di ogni voce, in inglese, è in [BUGS.md](../BUGS.md).
## Le decisioni
1. **Estrazione con commit-reveal.** Il vincitore non deve essere calcolabile
da chi produce o trasmette i blocchi: la potenza di calcolo di PLM
(~22 TH/s) si può affittare. All'apertura il server si impegna su un
segreto pubblicandone l'impronta. Alla chiusura si fissano l'elenco dei
partecipanti e l'altezza del blocco. Il seme combina segreto, blocco ed
elenco, e il segreto viene rivelato dopo. Un minatore non sa chi vincerebbe
e quindi non ha motivo di scartare blocchi. L'operatore non può cambiare
il segreto dopo averne pubblicato l'impronta.
→ [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#3--estrazione), B-73
2. **Nel dubbio non si liberano mai i fondi.** Una transazione viene
annullata solo con una prova: un rifiuto esplicito della rete, oppure i suoi
ingressi spesi da un'altra transazione confermata. Mai per un timeout o per
il silenzio di un solo server.
→ [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md), B-76, B-77, B-78
3. **Un indirizzo del montepremi per ogni round.** Soldi, cronologia e
pagamento di un round restano separati da quelli di tutti gli altri round.
→ B-80
4. **6 conferme per i depositi** (configurabili). Tutte le altre transazioni
restano a 1: il deposito è l'unico ingresso che un utente può spendere due
volte, perché il resto lo firma solo il server.
→ [registrazione-e-depositi.md](registrazione-e-depositi.md#deposito), B-82
5. **Le riorganizzazioni della catena si contengono.** Si rilevano, si mette
in pausa la lotteria quando sono profonde, e si paga solo ciò che risulta
davvero sulla catena.
→ B-82, B-85
**Limite accettato:** un attacco al 51% su PLM resta possibile e riguarda
chiunque usi PLM, non solo la lotteria. Queste misure fanno sì che non
convenga e che non blocchi la lotteria; non lo rendono impossibile. Vedi
[decisioni-e-limiti.md](decisioni-e-limiti.md).
## Ordine di implementazione
Le fasi vanno eseguite in ordine: ognuna si appoggia sulle precedenti.
Dentro una fase l'ordine è indicativo. Ogni voce è un commit a sé, con il suo
test di regressione, secondo [processo-di-modifica.md](processo-di-modifica.md).
### Fase 1 — Fondamenta
| Voce | Cosa | Gravità |
|---|---|---|
| B-88 | Transazioni SQLite vere (`BEGIN IMMEDIATE`, `synchronous=FULL`) | alta |
| B-75 | Client Electrum: limite di 16 MiB, risposta troppo grande = errore della richiesta, UTXO sotto la soglia di dust ignorati | critica |
| B-97 | Test che esegue le migrazioni e verifica gli indici | media |
| B-80 | Indirizzo del montepremi per round | critica |
### Fase 2 — Nel dubbio non liberare
| Voce | Cosa | Gravità |
|---|---|---|
| B-84 | Quorum minimo obbligatorio (almeno 2 server di riserva, almeno 2 risposte) | alta |
| B-76 | Invio ambiguo: la riga resta `building`, invio a tutti i server | critica |
| B-77 | Tutti i txid della catena di sostituzioni; RBF salvato prima dell'invio | critica |
| B-78 | Abbandono solo con prova; le righe `failed` restano sorvegliate | critica |
| B-83 | Conferme e reintegri verificati dal quorum (prova merkle) | alta |
### Fase 3 — Estrazione
| Voce | Cosa | Gravità |
|---|---|---|
| B-74 | Header: difficoltà minima, collegamento verificato su ogni salto | critica |
| B-85 | Riorganizzazioni seguite, registrate, con pausa se profonde | alta |
| B-86 | Rotazione se il server si ferma | alta |
| B-73 | Commit-reveal, altezza fissa, conferme sul blocco di estrazione, prova pubblica | critica |
| B-81 | `drawing` riprende dopo un errore o un riavvio | critica |
### Fase 4 — Pagamento
| Voce | Cosa | Gravità |
|---|---|---|
| B-79 | Riserva per l'RBF su ogni pagamento | critica |
| B-82 | 6 conferme sui depositi, 120 sulle coinbase, verifica prima del pagamento | critica |
| B-87 | RBF che non lascia resti sotto la soglia di dust | alta |
| B-95 | Parametri del round fotografati all'apertura, tetto al montepremi | media |
### Fase 5 — Operatività
| Voce | Cosa | Gravità |
|---|---|---|
| B-71 | Una sola copia della master key e del database | bassa |
| B-72 | `setup.md` senza il falso "in locale o via Docker" | bassa |
| B-89 | Verifica della chiave all'avvio | alta |
| B-90 | Ripristino da backup sicuro | alta |
| B-92 | Readiness, stato Electrum, filtri dell'audit, log | media |
| B-93 | Deploy e rollback | media |
| B-91 | Container non root, permessi, dipendenze fissate | alta |
### Fase 6 — Rifiniture
| Voce | Cosa | Gravità |
|---|---|---|
| B-94 | Limiti su cambio password, login, bug report; errori strutturati | media |
| B-96 | Incoerenze minori (sette voci, un test ciascuna) | media |
### Fase 7 — Prova su rete reale
Nessuna delle falle critiche sarebbe stata trovata dai test attuali, che
simulano tutto. Prima di aprire al pubblico serve una prova con importi
piccoli e guasti provocati di proposito, secondo la lista di
[operativita.md](operativita.md#prova-su-rete-reale).
## Correzioni solo documentali già applicate
Nella stessa revisione sono state corrette, senza un B-nn perché il codice non
cambia:
- affermazioni false sul comportamento attuale: timeout trattato come rifiuto,
"prima o poi abbandonata", quorum "su ogni decisione", tempi "nel caso
peggiore", resto di 294 sat "accelerabile";
- due procedure operative pericolose: il ripristino con sblocco di `drawing`
(OPS-07) e la rotazione della chiave di cifratura (OPS-22);
- puntatori sbagliati e requisiti duplicati in più documenti;
- formulazioni vaghe in regole normative.
+120
View File
@@ -0,0 +1,120 @@
# Processo di modifica: dalla documentazione al codice
La cartella `docs/` è la **specifica** di PLM Lottery. Descrive cosa il
software fa e perché; il codice è l'implementazione di questa specifica.
Ogni modifica di comportamento parte da qui.
## Convenzione dei requisiti
Ogni regola verificabile ha un **identificativo stabile**, nella forma
`PREFISSO-NN`, scritto in grassetto all'inizio del punto che la descrive,
seguito dai riferimenti all'implementazione e, dove esistono, ai test:
```markdown
- **[RND-11]** Al primo passo dello scheduler successivo alla scadenza il round
passa a `closing`; le scommesse sono però rifiutate già dall'istante della
scadenza ([BET-04]).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick` ·
*Test:* `tests/unit/test_scheduler.py`
```
Regole della convenzione:
- **Un identificativo non si riusa mai.** Un requisito eliminato resta nel
documento come `~~[RND-11]~~ Rimosso: <motivo>`, così i riferimenti già
scritti (commenti, commit, test) non puntano a una regola diversa.
- **I numeri non si rinumerano.** Un requisito nuovo prende il numero
successivo al più alto del suo prefisso, anche se finisce in mezzo al testo.
- **I riferimenti al codice** sono `percorso:funzione` o `percorso:Classe.metodo`,
mai numeri di riga (cambiano a ogni modifica).
- Il testo descrittivo che non contiene regole (introduzioni, spiegazioni,
esempi) non ha identificativo.
- **Un solo proprietario per regola.** Ogni regola ha l'identificativo in un
solo documento; gli altri documenti che la citano rimandano a quell'ID
invece di ripeterla con un ID proprio. Il documento di dominio (round,
scommesse, transazioni…) è proprietario del comportamento, `DAT` dello
schema, `SEC` delle soglie di sicurezza.
- **Niente formulazioni vaghe nelle regole.** "Circa", "normalmente", "prima o
poi" non compaiono in un requisito: si scrive la condizione esatta, con il
nome della costante.
### Requisiti non ancora implementati
La specifica può essere più avanti del codice: è il caso normale fra il passo 1
e il passo 3 del ciclo qui sotto. Un requisito che il codice non soddisfa
ancora porta, subito dopo i riferimenti, una riga di stato e una che dice cosa
fa il codice oggi:
```markdown
- **[RND-33]** L'altezza del blocco di estrazione è fissata all'ingresso in
`drawing` come `tip_at_close + 1` e non cambia più.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
*Test:* —
*Stato:* da implementare (B-73) · *Oggi:* si usa la punta vista al primo
controllo utile, che può essere un blocco successivo.
```
- *Codice* indica dove andrà l'implementazione (il file o la funzione
esistente più vicina); *Test* è `—` finché il test non esiste.
- Il B-nn rimanda alla voce di [BUGS.md](../BUGS.md) che descrive la
correzione; l'ordine di implementazione è in
[piano-correzioni.md](piano-correzioni.md).
- Quando il codice viene implementato, nello stesso commit si tolgono le righe
*Stato* e *Oggi* e si completano *Codice* e *Test*. `git grep "da
implementare"` elenca in ogni momento tutto ciò che manca.
- Un requisito modificato (non nuovo) mantiene il suo identificativo: il testo
descrive il comportamento atteso, *Oggi* quello attuale.
### Prefissi
| Prefisso | Documento | Ambito |
|---|---|---|
| `ARC` | [architettura.md](architettura.md) | Struttura del codice, processi, frontend, test |
| `DAT` | [modello-dati.md](modello-dati.md) | Tabelle, campi, stati, vincoli |
| `API` | [api.md](api.md) | Endpoint, formato delle risposte, codici di errore |
| `SEC` | [sicurezza.md](sicurezza.md) | Chiavi, autenticazione, limiti, rischi accettati |
| `REG` | [registrazione-e-depositi.md](registrazione-e-depositi.md) | Registrazione e account |
| `DEP` | [registrazione-e-depositi.md](registrazione-e-depositi.md) | Depositi e saldo |
| `BET` | [scommesse-e-prelievi.md](scommesse-e-prelievi.md) | Scommesse |
| `WDR` | [scommesse-e-prelievi.md](scommesse-e-prelievi.md) | Prelievi |
| `RND` | [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md) | Round, estrazione, pagamento |
| `TX` | [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md) | Ciclo di vita delle transazioni, RBF, riconciliazione |
| `ELC` | [connessione-electrum.md](connessione-electrum.md) | Connessione alla rete |
| `AUD` | [audit-log.md](audit-log.md) | Eventi del registro di audit |
| `OPS` | [operativita.md](operativita.md) | Procedure operative |
| `DEC` | [decisioni-e-limiti.md](decisioni-e-limiti.md) | Decisioni di progetto |
| `LIM` | [decisioni-e-limiti.md](decisioni-e-limiti.md) | Limiti noti accettati |
## Il ciclo di una modifica
1. **Modificare la specifica.** Si cambia il testo del requisito in `docs/`
(o se ne aggiunge uno nuovo con il prossimo numero libero). Se la modifica
tocca una decisione (`DEC-*`) o un limite (`LIM-*`), si aggiorna anche
quello.
2. **Individuare l'impatto.** I riferimenti *Codice* e *Test* del requisito
dicono dove intervenire. Si cercano anche le altre occorrenze
dell'identificativo nel repository (`git grep RND-11`) e i requisiti di
altri documenti che dipendono dallo stesso codice.
3. **Implementare e testare.** Si modifica il codice e si aggiunge o aggiorna
un test che verifica il nuovo comportamento. Il test cita l'identificativo
nella sua docstring.
4. **Allineare i riferimenti.** Se il codice si è spostato (funzione
rinominata, file diviso), si aggiornano i riferimenti *Codice* del
requisito.
5. **Commit unico.** Specifica, codice e test entrano nello stesso commit,
con l'identificativo nel messaggio (ad esempio
`Close the round on its own deadline (RND-11)`).
Una correzione di bug che non cambia la specifica (il codice non faceva ciò
che il documento già diceva) segue la convenzione `B-nn` descritta in
[storico-bug.md](storico-bug.md): numero successivo, commit dedicato, test di
regressione. Se invece il bug rivela che la specifica era sbagliata o
incompleta, si corregge prima la specifica, come per qualunque altra modifica.
## Documenti della specifica
Il punto d'ingresso è [come-funziona.md](come-funziona.md). Le guide
operative ([setup.md](setup.md), [running-the-server.md](running-the-server.md),
[guida-utente.md](guida-utente.md), [guida-admin.md](guida-admin.md)) non
contengono requisiti: descrivono come usare il software, e si aggiornano
quando la specifica cambia qualcosa di visibile.
+428
View File
@@ -0,0 +1,428 @@
# Registrazione, depositi e saldo
Fasi 1 e 2 del [funzionamento generale](come-funziona.md): come nasce un
account e come i fondi entrano nella piattaforma.
I requisiti usano i prefissi `REG` (registrazione e account) e `DEP` (depositi
e saldo), secondo la convenzione di
[processo-di-modifica.md](processo-di-modifica.md). Gli endpoint citati sono
descritti in dettaglio in [api.md](api.md); hashing, token e limiti di
frequenza in [sicurezza.md](sicurezza.md); le colonne delle tabelle in
[modello-dati.md](modello-dati.md); gli eventi di audit in
[audit-log.md](audit-log.md). Il documento descrive il comportamento
**atteso** dopo la revisione del 2026-09-28; i requisiti che il codice non
soddisfa ancora sono marcati *da implementare* (vedi
[piano-correzioni.md](piano-correzioni.md)).
## Registrazione
L'utente sceglie username e password (`POST /auth/register`). Il server:
1. salva la password come hash **Argon2** (mai in chiaro);
2. assegna all'utente il prossimo indice libero e deriva da questo il suo
indirizzo, secondo lo schema BIP84 `m/84'/746'/0'/0/<indice>` a partire
dalla master xprv cifrata. Ne risulta un indirizzo P2WPKH (`plm1…`);
3. collega l'indirizzo al profilo, in modo **permanente**;
4. si iscrive, via Electrum, alle notifiche di quell'indirizzo. Questo passo
è "al meglio": se fallisce, l'indirizzo viene comunque ripreso alla
riconnessione successiva o al giro periodico di `DepositReconciler`
([DEP-10](#dep-10)).
- **[REG-01]** Lo username è lungo da 3 a 32 caratteri, composto solo da
lettere ASCII, cifre, `_`, `.` e `-`; la password è lunga da 8
(`MIN_PASSWORD_LENGTH`) a 256 caratteri. Una richiesta che non rispetta
questi vincoli è rifiutata con HTTP 422 prima di qualunque altra verifica.
*Codice:* `app/auth/routes.py:RegisterRequest`, `app/auth/security.py:MIN_PASSWORD_LENGTH` ·
*Test:* `tests/unit/test_users.py`
- **[REG-02]** Gli username **non distinguono maiuscole e minuscole**:
`Mario` e `mario` sono lo stesso account. Uno username già usato, in
qualunque combinazione di maiuscole, è rifiutato con `username_taken`
(HTTP 409), sia dal controllo iniziale sia se la collisione emerge solo al
salvataggio (registrazione concorrente). L'unicità è garantita dal database
con un indice univoco su `lower(username)`. Il nome resta però salvato come
è stato digitato.
*Codice:* `app/auth/routes.py:register`, `app/db/models.py:User` ·
*Test:* `tests/unit/test_auth.py`
- **[REG-03]** La password è salvata solo come hash Argon2, calcolato fuori
dal ciclo di eventi (in un thread separato) per non bloccare le attività in
background.
*Codice:* `app/auth/security.py:hash_password_async` ·
*Test:* `tests/unit/test_security.py`
- **[REG-04]** L'indice di derivazione del nuovo utente è il massimo indice
esistente più uno (0 per il primo utente); l'indirizzo è il P2WPKH di
`m/84'/746'/0'/0/<indice>`, con prefisso bech32 `plm`. Se il salvataggio
fallisce per una collisione sull'indice (due registrazioni concorrenti), si
riprova con un indice ricalcolato fino a 5 volte (`_MAX_REGISTER_RETRIES`),
poi la richiesta fallisce con `derivation_index_conflict` (HTTP 409).
*Codice:* `app/auth/routes.py:register`, `app/wallet/hd.py:derive_user_address` ·
*Test:* `tests/unit/test_hd.py` (solo la derivazione dell'indirizzo:
nessun test copre i tentativi ripetuti né `derivation_index_conflict`)
- **[REG-05]** L'indirizzo è **permanente** e unico per utente, ed è allo
stesso tempo indirizzo di deposito, destinazione delle vincite e
destinazione del resto di ogni scommessa e prelievo: non esiste un
"indirizzo vincite" separato.
*Codice:* `app/db/models.py:User`, `app/bets/service.py:place_bet`, `app/withdrawals/service.py:request_withdrawal`, `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
*Test:* `tests/unit/test_bets.py`, `tests/unit/test_withdrawals.py`
- **[REG-06]** Una registrazione riuscita risponde HTTP 201 con un token di
sessione (`access_token`) e l'indirizzo: l'utente è già autenticato, senza
un login separato.
*Codice:* `app/auth/routes.py:register` ·
*Test:* `tests/unit/test_users.py`
- **[REG-07]** Subito dopo il salvataggio, l'indirizzo viene aggiunto agli
indirizzi osservati e, se la connessione Electrum è attiva, gli ci si iscrive
in un'attività separata. Se non c'è connessione, o l'iscrizione fallisce,
l'errore viene solo registrato nei log: la registrazione riesce comunque, e
l'indirizzo viene ripreso dalla reiscrizione completa alla prossima
riconnessione ([ELC-18](connessione-electrum.md#riconnessione)) o dal giro
periodico di [DEP-10](#dep-10).
*Codice:* `app/electrum/listener.py:ElectrumListener.address_for_new_user` ·
*Test:* `tests/unit/test_electrum_listener.py`
- ~~[REG-08]~~ Assorbito da [SEC-31](sicurezza.md#limiti-di-frequenza):
la quota di registrazioni per IP (soglia, finestra, momento del controllo,
risposta `rate_limited`) è una soglia di sicurezza e ha lì il suo unico
proprietario; qui non resta nulla di specifico del dominio.
- **[REG-15]** **Indici già usati dopo un ripristino.** Un database
ripristinato da un backup non conosce gli utenti registrati dopo il backup,
e riassegnerebbe i loro indici — e quindi i loro indirizzi, con i fondi che
contengono — a utenti nuovi. Per questo, all'avvio, appena la connessione
Electrum è disponibile, si controllano i **20 indici successivi** al
massimo indice assegnato (da 0 a 19 se non c'è alcun utente): per ciascun
indirizzo si chiede la cronologia (`blockchain.scripthash.get_history`) al
server attivo e a ogni server del quorum, e basta che **uno** riporti una
transazione perché l'indirizzo conti come usato. Se almeno un indirizzo è
usato si scrive `restore_gap_detected` (indici e indirizzi con
cronologia) e la registrazione viene rifiutata con
`registration_unavailable` (HTTP 503) finché, a un avvio successivo, il
controllo non trova più alcun indirizzo usato: l'operatore deve prima
ricostruire gli utenti mancanti (procedura in
[operativita.md](operativita.md#ripristino), B-90). La registrazione è
rifiutata allo stesso modo finché il controllo non è stato completato.
*Codice:* `app/main.py:lifespan`, `app/auth/routes.py:register`, `app/wallet/hd.py:derive_user_address` · *Test:* —
*Stato:* da implementare (B-90) · *Oggi:* nessun controllo; dopo un
ripristino il prossimo utente riceve il primo indice non presente nel
database, anche se il suo indirizzo ha già ricevuto fondi.
- **[REG-16]** Ogni registrazione riuscita scrive l'evento `user_registered`
con l'indice di derivazione e l'indirizzo assegnati, nella stessa
transazione che crea l'utente.
*Codice:* `app/auth/routes.py:register` · *Test:* —
*Stato:* da implementare (B-92) · *Oggi:* la registrazione non scrive alcun
evento di audit.
### Sessione e password
Il login (`POST /auth/login`) restituisce un token di sessione. Cambiare la
password (dal Profilo) o farsela reimpostare dall'operatore invalida
**tutte** le sessioni aperte in precedenza. Formato, durata e revoca del token
sono regole di sicurezza ([SEC-21, SEC-22](sicurezza.md#token-di-sessione-jwt));
il freno sui tentativi di login falliti è
[SEC-30](sicurezza.md#limiti-di-frequenza).
- **[REG-09]** Il login confronta lo username senza distinguere maiuscole e
minuscole. Username inesistente e password sbagliata producono la stessa
risposta, `invalid_credentials` (HTTP 401), così che non si possa scoprire
quali account esistono. Una risposta riuscita contiene `access_token` e
l'indirizzo dell'utente. Username e password del login sono lunghi al
massimo 256 caratteri ciascuno; oltre, la richiesta è rifiutata con HTTP 422
prima di qualunque verifica.
*Codice:* `app/auth/routes.py:login`, `app/auth/routes.py:LoginRequest` ·
*Test:* `tests/unit/test_auth.py`
*Stato:* da implementare (B-94), per la lunghezza massima · *Oggi:* i campi
del login non hanno limiti di lunghezza.
- ~~[REG-10]~~ Assorbito da [SEC-30](sicurezza.md#limiti-di-frequenza):
il freno sui login falliti (chiavi, soglie, azzeramento) non ha nulla di
specifico del dominio oltre a ciò che SEC-30 già dice.
- ~~[REG-11]~~ Assorbito da [SEC-22](sicurezza.md#token-di-sessione-jwt):
scadenza, versione del token e rifiuto con `session_expired` sono regole di
sicurezza (SEC-21, SEC-22, SEC-23) e non resta nulla di specifico del
dominio.
- **[REG-12]** Il cambio password (`POST /users/me/change-password`, dal
Profilo) richiede la password attuale — altrimenti `current_password_incorrect`
(HTTP 401) — e una nuova password di almeno 8 caratteri — altrimenti
`password_too_short` (HTTP 400). Entrambi i campi sono lunghi al massimo
256 caratteri, altrimenti HTTP 422. I tentativi con password attuale
sbagliata sono frenati come il login (soglie in
[sicurezza.md](sicurezza.md#limiti-di-frequenza), B-94). Se riesce,
incrementa `token_version`, invalidando **tutte** le sessioni aperte,
compresa quella della richiesta, scrive l'evento `password_changed` e
restituisce un token nuovo perché la sessione corrente continui senza nuovo
login. Questo requisito è il proprietario del flusso; [sicurezza.md](sicurezza.md)
e [api.md](api.md) vi rimandano.
*Codice:* `app/api/routes/users.py:change_password` ·
*Test:* `tests/unit/test_users.py`
*Stato:* da implementare (B-94), per lunghezza massima, freno ed evento
`password_changed` · *Oggi:* nessun limite di lunghezza, nessun freno sui
tentativi, nessun evento di audit.
- **[REG-13]** Non esiste recupero password: non viene raccolta alcuna email.
L'unica strada è il reset dall'operatore
(`POST /admin/users/{id}/reset-password`), che imposta una password casuale
nuova, la restituisce **una sola volta** perché venga comunicata
all'utente, incrementa `token_version` (invalidando tutte le sessioni) e
scrive l'evento `admin_password_reset`. Un utente inesistente dà HTTP 404.
Procedura in [guida-admin.md](guida-admin.md).
*Codice:* `app/api/routes/admin.py:reset_user_password` ·
*Test:* `tests/unit/test_admin.py`
### Il conto del montepremi
Oltre agli indirizzi utente, dalla stessa master key si derivano gli indirizzi
del **montepremi**: uno per ogni round, su cui arrivano le scommesse di quel
round e da cui parte il suo pagamento, e un indirizzo di **riserva** che
riceve la riserva per l'RBF di ogni pagamento
([ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#4--pagamento), B-79).
- **[REG-14]** Gli utenti stanno sul ramo `0` dell'account
(`m/84'/746'/0'/0/<indice>`). Il montepremi di un round è il P2WPKH di
`m/84'/746'/0'/2/<round_id>`, salvato sul round all'apertura; l'indirizzo
di riserva è il P2WPKH di `m/84'/746'/0'/1/0`, che è anche il montepremi
dei round aperti prima di questa modifica. Le loro monete non sono
registrate tra le monete degli utenti: il pagamento le legge dalla rete e
le verifica con il quorum
([ELC-27](connessione-electrum.md#5-il-quorum)).
*Codice:* `app/wallet/hd.py:derive_pool_key`, `app/wallet/hd.py:derive_pool_address` ·
*Test:* `tests/unit/test_pending_address.py`
*Stato:* da implementare (B-80) · *Oggi:* esiste un solo indirizzo del
montepremi, `m/84'/746'/0'/1/0`, per tutti i round.
## Deposito
L'utente invia PLM al proprio indirizzo da qualunque wallet esterno.
Un **deposito** è una moneta arrivata all'indirizzo di un utente da una
transazione che la piattaforma non ha costruito. Le monete prodotte dalle
transazioni della piattaforma — il resto di scommesse e prelievi, le
vincite — arrivano allo stesso indirizzo e passano per lo stesso codice, ma
con la soglia di conferme delle transazioni della piattaforma (1): il
deposito è l'unico ingresso che un utente può spendere due volte
([DEC-06](decisioni-e-limiti.md)).
```mermaid
flowchart TB
A["Notifica Electrum per l'indirizzo,<br/>(re)iscrizione, oppure<br/>giro periodico (DEP-09)"] --> L["Aggiornamenti dello stesso<br/>utente in fila (DEP-15)"]
L --> B["Si legge l'elenco delle<br/>monete (UTXO) dell'indirizzo<br/>dal server attivo"]
B --> DU{"Moneta sotto<br/>DUST_LIMIT_SATS?"}
DU -- "Sì" --> Z["Ignorata (DEP-01)"]
DU -- "No" --> C{"Moneta nuova<br/>e confermata?"}
C -- "No" --> Z2["Nulla da fare"]
C -- "Sì" --> K["Soglia (DEP-03):<br/>1 se la transazione è della piattaforma,<br/>120 se coinbase,<br/>altrimenti deposit_confirmations"]
K --> KK{"Conferme ≥ soglia?"}
KK -- "No" --> P["Mostrata come in attesa<br/>nel saldo mostrato (DEP-14)"]
KK -- "Sì" --> D{"Il quorum degli altri<br/>server conferma moneta,<br/>importo e conferme?"}
D -- "No / meno di 2 risposte" --> R["Accredito rinviato<br/>al prossimo controllo"]
D -- "Sì" --> E["Moneta registrata,<br/>saldo ricalcolato<br/>(deposit_credited)"]
B --> F{"Una moneta nota<br/>non spesa è sparita?"}
F -- "Sì, e il quorum<br/>la conferma spesa" --> G["Segnata come spesa<br/>fuori dalla piattaforma<br/>(utxo_spent_externally)"]
B --> H{"Una moneta data per spesa<br/>fuori è ricomparsa?"}
H -- "Sì, e il quorum<br/>la conferma non spesa" --> I["Reintegrata<br/>(utxo_external_spend_reinstated)"]
```
*Comportamento atteso.* Oggi ogni moneta confermata si accredita a 1
conferma, di qualunque importo e anche se coinbase; il reintegro non è
corroborato; gli aggiornamenti dello stesso utente non sono in fila; le
monete sotto la soglia non compaiono nel saldo mostrato.
- **[DEP-01]** Non c'è un importo minimo di deposito oltre alla soglia di
polvere: una moneta di valore inferiore a `DUST_LIMIT_SATS` (294 sat) non
viene mai accreditata né mostrata, e non entra in alcun altro controllo di
questo documento. Non è spendibile in modo economico e, se accreditata,
farebbe crescere senza limite il lavoro di ogni aggiornamento; chiunque
può inviarne a qualunque indirizzo pubblico.
*Codice:* `app/deposits/service.py:find_new_credit_candidates`, `app/deposits/service.py:credit_confirmed_utxos`, `app/wallet/psbt_builder.py:DUST_LIMIT_SATS` · *Test:* —
*Stato:* da implementare (B-75) · *Oggi:* si accredita una moneta di
qualunque importo.
- **[DEP-02]** Un aggiornamento dell'indirizzo di un utente legge l'elenco
delle monete non spese (`listunspent`) dal server Electrum attivo e procede
in tre fasi. **Lettura**, senza scrivere nulla: individuazione degli
accrediti nuovi, delle monete ricomparse e delle monete sparite.
**Corroborazione** presso gli altri server di accrediti
([ELC-17](connessione-electrum.md#5-il-quorum)), reintegri
([ELC-25](connessione-electrum.md#5-il-quorum)) e sparizioni
([ELC-16](connessione-electrum.md#5-il-quorum)). **Scrittura** dei soli
casi corroborati, ricontrollando lo stato di ogni moneta al salvataggio.
Nessuna sessione del database resta aperta durante le chiamate di rete.
*Codice:* `app/electrum/listener.py:ElectrumListener.refresh_user` ·
*Test:* `tests/unit/test_electrum_listener.py`
*Stato:* da implementare (B-83) · *Oggi:* il reintegro delle monete
ricomparse viene **scritto e committato già nella fase di lettura**, prima
di qualunque corroborazione; solo accrediti e sparizioni sono corroborati
prima di essere scritti.
- **[DEP-03]** **Soglia di conferme.** Una moneta è candidata all'accredito
solo se è confermata (altezza maggiore di 0: le monete ancora in mempool
sono ignorate), non è già registrata e ha raggiunto la sua soglia di
conferme. Le conferme sono `punta − altezza + 1`, sulla punta validata del
listener ([connessione-electrum.md](connessione-electrum.md#4-header-validati-non-creduti)).
La soglia è:
- **1** se la transazione che l'ha creata è una transazione della
piattaforma (uno qualunque dei txid di una riga di
`pending_transactions`, compresi quelli sostituiti da un RBF,
[modello-dati.md](modello-dati.md) B-77): resto di scommesse e prelievi,
vincite;
- **120** (la maturità delle coinbase di PLM, `COINBASE_MATURITY` in
`palladiumcore/src/consensus/consensus.h`) se la transazione è una
coinbase, cioè il suo unico ingresso ha l'outpoint nullo. Lo si stabilisce
dalla transazione grezza (`blockchain.transaction.get`), accettata solo se
il suo hash coincide con il txid;
- **`deposit_confirmations`** (`round_config`, predefinito 6,
[modello-dati.md](modello-dati.md) B-82) in ogni altro caso.
Una moneta accreditata e poi sparita per una riorganizzazione più profonda
della soglia segue la strada delle monete spese altrove
([DEP-06], [DEP-07]); non c'è altra logica di annullamento.
*Codice:* `app/deposits/service.py:find_new_credit_candidates`, `app/electrum/listener.py:ElectrumListener.refresh_user` ·
*Test:* `tests/unit/test_deposits.py`
*Stato:* da implementare (B-82) · *Oggi:* **una conferma basta** per ogni
moneta, deposito o coinbase che sia.
- **[DEP-04]** **Ogni accredito è corroborato.** Prima di aumentare un saldo,
il server chiede agli *altri* server Electrum configurati se quella moneta
esiste davvero, con quell'importo e con le conferme richieste
([ELC-17](connessione-electrum.md#5-il-quorum)). Un server malevolo non può
quindi inventarsi un deposito. Se la verifica non riesce l'accredito non è
perso, solo rimandato: la moneta viene riproposta all'aggiornamento
successivo (notifica o giro periodico), e nei log resta un avviso.
*Codice:* `app/electrum/listener.py:ElectrumListener.refresh_user`, `app/electrum/listener.py:ElectrumListener.corroborate_utxo_credit` ·
*Test:* `tests/unit/test_electrum_listener.py`
- **[DEP-05]** L'accredito registra la moneta (txid, posizione, importo,
altezza) in modo idempotente — una moneta già registrata non viene mai
accreditata due volte, e il database impone l'unicità della coppia
txid/posizione —, scrive per ciascuna un evento `deposit_credited`,
ricalcola il saldo e invia una notifica SSE.
*Codice:* `app/deposits/service.py:credit_confirmed_utxos` ·
*Test:* `tests/unit/test_deposits.py`
- **[DEP-06]** **Monete spese altrove.** Una moneta registrata come non spesa
che non compare più nell'elenco è *candidata* alla spesa esterna (ad esempio
perché qualcuno ha usato la chiave privata esportata dall'admin). Le monete
spese dalla piattaforma stessa non sono mai candidate, perché vengono
segnate come spese già al momento della costruzione della transazione. Se
l'elenco è **completamente vuoto** mentre il database conosce monete non
spese, non si produce alcun candidato: una risposta vuota è trattata come
incompleta, non come una spesa di tutto.
*Codice:* `app/deposits/service.py:find_utxos_missing_from` ·
*Test:* `tests/unit/test_deposits.py`
- **[DEP-07]** Un candidato viene tolto dal saldo solo dopo che il quorum
degli altri server conferma che la moneta non è più non spesa
([ELC-16](connessione-electrum.md#5-il-quorum)). Al salvataggio si
ricontrolla che la moneta sia ancora non spesa (nel frattempo potrebbe
averla spesa la piattaforma); la si segna con il marcatore di spesa esterna,
si scrive `utxo_spent_externally`, si ricalcola il saldo e si invia una
notifica SSE.
*Codice:* `app/electrum/listener.py:ElectrumListener.refresh_user`, `app/deposits/service.py:mark_utxos_spent_externally` ·
*Test:* `tests/unit/test_deposits.py`, `tests/unit/test_electrum_listener.py`
- **[DEP-08]** **Reintegro.** Una moneta segnata come spesa fuori dalla
piattaforma che ricompare nell'elenco viene reintegrata solo dopo che il
quorum degli altri server la conferma non spesa, con lo stesso importo e
confermata, come per un accredito
([ELC-25](connessione-electrum.md#5-il-quorum)). Al salvataggio si
ricontrolla che porti ancora il marcatore di spesa esterna; il marcatore è
rimosso, si scrive `utxo_external_spend_reinstated`, si ricalcola il saldo e
si invia una notifica SSE. Se la verifica non riesce la moneta resta fuori
dal saldo e viene riproposta all'aggiornamento successivo.
*Codice:* `app/deposits/service.py:reinstate_reappeared_utxos`, `app/electrum/listener.py:ElectrumListener.refresh_user` ·
*Test:* `tests/unit/test_deposits.py`
*Stato:* da implementare (B-83) · *Oggi:* il reintegro si basa sulla sola
risposta del server attivo, senza corroborazione.
- **[DEP-09]** **Due vie, un solo codice.** Un aggiornamento parte quando il
server notifica un cambiamento su un indirizzo osservato, alla
(re)iscrizione di un indirizzo, e al giro periodico: tutte e tre usano la
stessa funzione di aggiornamento, così i due percorsi non possono
comportarsi diversamente.
*Codice:* `app/electrum/listener.py:ElectrumListener._consume_scripthash`, `app/electrum/listener.py:ElectrumListener._subscribe_and_refresh`, `app/deposits/reconcile.py:DepositReconciler._sweep_once` ·
*Test:* `tests/unit/test_deposit_reconcile.py`
- **[DEP-10]** <a id="dep-10"></a>Il giro periodico (`DepositReconciler`)
riaggiorna **tutti** gli utenti, non solo quelli che risultano non
iscritti: serve a recuperare un'iscrizione persa silenziosamente. Prima di
ogni giro, incluso il primo, attende 300 s (`_SWEEP_INTERVAL_SECONDS`)
dalla fine del giro precedente (per il primo, dall'avvio); i giri sono
seriali, e dentro un giro gli utenti sono aggiornati uno alla volta. Il giro
salta se non c'è connessione, si interrompe se la connessione cade a metà
(la reiscrizione alla riconnessione copre tutti), e l'errore su un utente
viene registrato senza fermare gli altri.
*Codice:* `app/deposits/reconcile.py:DepositReconciler.run`, `app/deposits/reconcile.py:DepositReconciler._sweep_once` ·
*Test:* `tests/unit/test_deposit_reconcile.py`
- **[DEP-15]** Gli aggiornamenti dello **stesso** utente sono serializzati:
una notifica, la reiscrizione e il giro periodico possono chiederli insieme,
ma ne gira uno alla volta per utente, in ordine di arrivo. Il blocco è
proprio dell'aggiornamento e distinto da quello per-utente di scommesse e
prelievi ([scommesse-e-prelievi.md](scommesse-e-prelievi.md)), così una
corroborazione in corso non ritarda una scommessa. Utenti diversi si
aggiornano in parallelo come oggi.
*Codice:* `app/electrum/listener.py:ElectrumListener.refresh_user` · *Test:* —
*Stato:* da implementare (B-96) · *Oggi:* due aggiornamenti dello stesso
utente possono girare insieme e tentare di accreditare la stessa moneta.
- **[DEP-16]** Un errore durante l'aggiornamento di un utente non chiude la
connessione Electrum: viene registrato nei log e l'utente viene ripreso
all'aggiornamento successivo. In particolare una violazione dell'unicità
txid/posizione all'accredito ([DEP-05]) vale come "moneta già registrata":
si annulla la transazione del database di quell'accredito e si prosegue.
Fa eccezione solo la caduta della connessione stessa, che termina la
sessione come in [ELC-06](connessione-electrum.md#3-caduta-rilevata).
*Codice:* `app/electrum/listener.py:ElectrumListener._consume_scripthash`, `app/deposits/service.py:credit_confirmed_utxos` · *Test:* —
*Stato:* da implementare (B-96) · *Oggi:* l'eccezione risale da
`refresh_user` a `_consume_scripthash` e termina la sessione Electrum.
## Il saldo mostrato
Scommesse e prelievi spendono monete **intere**: per pagare 10 PLM con una
moneta da 50, la moneta da 50 viene spesa tutta e 40 tornano all'utente come
resto (nella scommessa la commissione è dedotta dai 10 PLM, vedi
[scommesse-e-prelievi.md](scommesse-e-prelievi.md#cosa-succede)), in una nuova
moneta che però è confermata solo al blocco successivo. Allo stesso modo un
deposito resta non spendibile finché non raggiunge la sua soglia di conferme
([DEP-03]).
Per questo esistono due saldi, entrambi restituiti da `GET /users/me`:
| Campo | Cosa conta | A cosa serve |
|---|---|---|
| `balance_sats` | Solo monete accreditate e non spese | È ciò che si può spendere: prelievo massimo, controlli sulla scommessa |
| `pending_balance_sats` | Il precedente **più** il resto delle proprie transazioni ancora in corso **più** i depositi confermati ma sotto la soglia | È ciò che l'interfaccia mostra |
Senza il secondo, subito dopo una scommessa l'utente vedrebbe sparire l'intero
resto (spesso molto più dei 10 PLM giocati) fino alla conferma, e un
deposito resterebbe invisibile finché non raggiunge `deposit_confirmations`
conferme. L'interfaccia mostra il saldo
in **verde** quando tutto è confermato e in **ambra** finché c'è qualcosa in
corso (`has_pending`).
- **[DEP-11]** Il saldo confermato (`balance_sats`, colonna
`cached_balance_sats`) è la somma delle monete registrate dell'utente non
segnate come spese. Viene ricalcolato nella stessa transazione del database
di ogni operazione che registra, spende, libera o reintegra monete.
*Codice:* `app/wallet/balance.py:recompute_balance` ·
*Test:* `tests/unit/test_deposits.py`
- **[DEP-12]** Il saldo mostrato (`pending_balance_sats`) è il saldo
confermato più: (a) le uscite verso l'indirizzo dell'utente di ogni sua
scommessa o prelievo in stato `building` o `pending`, lette dalla
transazione corrente (aggiornata a ogni RBF); (b) i depositi in attesa di
[DEP-14]. Un'uscita già registrata come moneta (perché il resto è stato
accreditato prima che la transazione risultasse confermata) non viene
contata due volte. `has_pending` è vero finché esiste almeno una
transazione di (a) o un deposito di (b).
*Codice:* `app/wallet/balance.py:compute_pending_balance`, `app/api/routes/users.py:me` ·
*Test:* `tests/unit/test_balance.py`
*Stato:* da implementare (B-82), per la parte (b) · *Oggi:* conta solo la
parte (a).
- **[DEP-14]** **Depositi in attesa.** Una moneta sopra la soglia di polvere,
confermata (altezza maggiore di 0), non ancora registrata e con meno
conferme della sua soglia ([DEP-03]) è un *deposito in attesa*. Il listener
tiene, per ogni utente, l'insieme dei depositi in attesa visti all'ultimo
aggiornamento, sostituendolo a ogni aggiornamento: un deposito sparito
dall'elenco (ad esempio per una riorganizzazione) smette di essere mostrato,
uno accreditato passa nel saldo confermato. L'insieme sta solo in memoria —
non sposta denaro e non è spendibile, quindi non è corroborato — e dopo un
riavvio si ricostruisce alla prima reiscrizione ([ELC-18](connessione-electrum.md#riconnessione)).
Le monete ancora in mempool non sono depositi in attesa.
*Codice:* `app/electrum/listener.py:ElectrumListener.refresh_user`, `app/wallet/balance.py:compute_pending_balance` · *Test:* —
*Stato:* da implementare (B-82) · *Oggi:* con la soglia a 1 conferma non
esistono depositi in attesa; una moneta in mempool non compare in nessun
saldo.
- **[DEP-13]** Ogni spesa (scommessa, prelievo) usa solo monete accreditate e
non spese: il saldo mostrato è informativo, non spendibile. Se un utente
chiede un prelievo o una scommessa coperti dal saldo mostrato ma non ancora
da quello confermato, riceve l'errore `balance_pending_confirmation`
("attendi la conferma") invece di un generico "saldo insufficiente" che
contraddirebbe ciò che vede ([WDR-05](scommesse-e-prelievi.md#prelievo); per
la scommessa [scommesse-e-prelievi.md](scommesse-e-prelievi.md), B-96).
*Codice:* `app/withdrawals/service.py:request_withdrawal`, `app/bets/service.py:place_bet` ·
*Test:* `tests/unit/test_withdrawals.py`
*Stato:* da implementare (B-96), per la scommessa · *Oggi:* solo il
prelievo distingue i due casi; una scommessa coperta solo dal saldo
mostrato riceve `insufficient_balance`.
+7 -5
View File
@@ -64,8 +64,10 @@ docker compose down # ferma e rimuove i container (i dati in ./data/
### ⚠️ Attenzione: riavvii automatici a metà round
`docker-compose.yml` imposta `restart: unless-stopped` sul container dell'app:
se crasha, riparte da solo. Questo però non è ancora sicuro in ogni caso — se
il crash avviene mentre un round è in stato `closing`/`drawing`/`paying_out`,
lo scheduler non lo riprende al riavvio e il round resta bloccato (gap noto,
vedi "Known gaps" in `CLAUDE.md`). Non trattare questo setup come
"non supervisionato" finché quel gap non è risolto.
se crasha, riparte da solo. Questo però non è ancora sicuro in ogni caso: i
round in `closing` e `paying_out` riprendono da soli al riavvio, ma se il
crash avviene mentre un round è in `drawing`, lo scheduler non lo riprende e
il round resta bloccato (limite noto, vedi
[decisioni-e-limiti.md](decisioni-e-limiti.md); procedura in
[operativita.md](operativita.md)). Non trattare questo setup come
"non supervisionato" finché quel limite non è risolto.
+378
View File
@@ -0,0 +1,378 @@
# Scommesse e prelievi
Fasi 3 e 5 del [funzionamento generale](come-funziona.md): le due operazioni
con cui l'utente spende il proprio saldo. Hanno la stessa forma — una
transazione dal suo indirizzo verso una destinazione, con il resto che torna a
lui — e condividono le stesse regole di sicurezza.
I requisiti usano i prefissi `BET` (scommesse) e `WDR` (prelievi), secondo la
convenzione di [processo-di-modifica.md](processo-di-modifica.md). Il formato
delle risposte e il catalogo completo dei codici di errore sono in
[api.md](api.md); cosa succede a una transazione dopo l'invio in
[transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md).
Costanti citate in questo documento (tutte in `app/wallet/psbt_builder.py`):
| Costante | Valore | Significato |
|---|---|---|
| `DUST_LIMIT_SATS` | 294 sat | Resto minimo di ogni transazione utente |
| `MAX_TX_INPUTS` | 50 | Monete massime in ingresso per scommessa o prelievo |
| `MAX_PARTICIPANTS_PER_ROUND` | 400 | Partecipanti massimi per round |
| `MAX_PAYOUT_TX_INPUTS` | 500 | Monete massime in ingresso per il pagamento del round |
## Scommessa
### Quando è accettata
Prima dei controlli valgono due condizioni di contorno:
- **[BET-01]** Se il server non è connesso alla rete, la scommessa è
rifiutata con `network_unavailable` (HTTP 503) prima di qualunque altro
controllo.
*Codice:* `app/api/routes/bets.py:create_bet` ·
*Test:* — (nessun test verifica `network_unavailable`)
- **[BET-02]** Tutta l'elaborazione di una scommessa, dai controlli all'invio,
avviene tenendo il **blocco per-utente**, lo stesso usato dal prelievo
([WDR-01](#prelievo)). Il client della rete usato per la scommessa
(`listener.client`) viene letto **dopo** aver acquisito il blocco, così
un'attesa sul blocco durante una riconnessione non fa usare una connessione
già chiusa; il controllo di [BET-01] si fa su quel valore.
*Codice:* `app/api/routes/bets.py:create_bet`, `app/tx/locks.py:UserLocks.acquire` ·
*Test:* —
*Stato:* da implementare (B-96) · *Oggi:* `listener.client` viene letto e
controllato prima di acquisire il blocco.
Una scommessa (`POST /bets`, senza corpo) passa solo se **tutte** queste
condizioni sono vere, verificate nell'ordine della tabella; altrimenti viene
rifiutata con il codice indicato (HTTP 400), prima che si muova qualunque
cifra. Il **costo** è quello del round ([BET-21]):
| ID | Condizione | Codice di errore |
|---|---|---|
| **[BET-03]** | C'è un round attivo. Se non ce n'è nessuno e le condizioni di apertura sono soddisfatte ([RND-04](ciclo-di-vita-del-round.md#0--apertura)), è la scommessa stessa ad aprirlo | `no_round_open` |
| **[BET-04]** | Il round è in stato `open` e la sua **scadenza** — apertura più la durata fotografata all'apertura (`opened_at + duration_seconds`), non lo stato nel database — non è ancora passata | `round_closing` |
| **[BET-05]** | L'utente non ha già una scommessa in questo round (in qualunque stato) | `already_betting` |
| **[BET-06]** | Il round ha meno di 400 partecipanti (`MAX_PARTICIPANTS_PER_ROUND`), contando anche quelli non ancora confermati | `round_full` (parametro `max_participants`) |
| **[BET-20]** | Se il round ha un tetto al montepremi (`max_round_pool_sats` fotografato all'apertura, [RND-05](ciclo-di-vita-del-round.md#0--apertura)) diverso da 0, la somma degli importi netti dei partecipanti del round, contando anche quelli non ancora confermati, è minore del tetto. *Stato:* da implementare (B-95) · *Oggi:* il tetto non esiste | `round_full` |
| **[BET-07]** | La somma delle monete confermate e non spese copre il costo della scommessa | `balance_pending_confirmation` se lo coprirebbe il saldo comprensivo di quanto è in corso (parametro `pending_sats`), altrimenti `insufficient_balance` (parametro `required_sats`), come per il prelievo ([WDR-05](#prelievo)). *Stato:* da implementare (B-96) · *Oggi:* sempre `insufficient_balance`, anche quando il saldo mostrato all'utente copre la scommessa |
| **[BET-08]** | Il costo si copre con al massimo 50 monete (`MAX_TX_INPUTS`), scelte dalla più grande fino a coprirlo | `too_many_inputs` (parametro `max_inputs`) |
| **[BET-09]** | Le monete scelte ([BET-08]) superano il costo di almeno 294 sat (`DUST_LIMIT_SATS`), che restano come resto | `balance_leaves_no_change` (parametro `required_extra_sats`) |
| **[BET-10]** | Il costo meno la commissione di rete resta positivo e di almeno 294 sat | `amount_below_network_fee`, `amount_below_dust_limit` |
*Codice:* `app/bets/service.py:place_bet`, `app/rounds/service.py:round_accepts_bets`,
`app/wallet/psbt_builder.py:select_utxos`, `app/wallet/psbt_builder.py:build_signed_transaction` ·
*Test:* `tests/unit/test_bets.py`, `tests/unit/test_withdrawals.py`, `tests/unit/test_psbt_builder.py`
(nessun test verifica `no_round_open`)
Lo stato nel database non basta per la scadenza ([BET-04]) perché lo
scheduler controlla ogni 5 secondi: fino a 5 secondi il round può risultare
ancora `open` oltre la scadenza.
La selezione si ferma alla prima moneta che porta il totale a coprire il
costo ([BET-08]): il resto di [BET-09] si misura su quelle monete, non
sull'intero saldo.
- **[BET-21]** Il **costo** di una scommessa è il `bet_amount_sats`
fotografato sul round alla sua apertura
([RND-05](ciclo-di-vita-del-round.md#0--apertura)), non il valore corrente
di `round_config`: una modifica da `/admin` vale dal round successivo.
*Codice:* `app/bets/service.py:place_bet` ·
*Test:* —
*Stato:* da implementare (B-95) · *Oggi:* il costo è letto da
`round_config` a ogni scommessa, quindi una modifica vale subito anche per
il round in corso.
- **[BET-11]** La scadenza viene verificata due volte: all'arrivo della
richiesta ([BET-04]) e di nuovo dopo aver costruito e firmato la
transazione. L'iscrizione al round viene poi salvata nella stessa
transazione del database — aperta con `BEGIN IMMEDIATE`
([TX-28](transazioni-e-riconciliazione.md#il-principio-prima-si-scrive-poi-si-invia))
— di un *compare-and-set* sulla riga del round
(`UPDATE rounds … WHERE status = 'open'`): se il round non è più aperto in
quell'istante esatto tutto viene annullato prima dell'invio e la scommessa è
rifiutata con `round_closing`. Così nessuna scommessa può finire nel
montepremi senza essere inclusa nell'estrazione. Un `OperationalError` in
questo punto non è un conflitto di scrittura (SQLite non ne produce): è il
blocco in scrittura non ottenuto entro 5 secondi (`database is locked`).
Anche in quel caso tutto viene annullato prima dell'invio, ma la risposta è
`service_busy` (HTTP 503), perché il round non è necessariamente in
chiusura.
*Codice:* `app/bets/service.py:place_bet` ·
*Test:* `tests/unit/test_bets.py`
*Stato:* da implementare (B-88) · *Oggi:* la transazione si apre con la
prima scrittura, non con `BEGIN IMMEDIATE`; un `OperationalError` viene
trattato come un conflitto di scrittura e risponde `round_closing`.
- **[BET-22]** `MAX_PARTICIPANTS_PER_ROUND` è minore di
`MAX_PAYOUT_TX_INPUTS`. Il pagamento spende una moneta del montepremi per
ogni scommessa, e una singola transazione di pagamento può spenderne al
massimo 500; bloccare il 401° giocatore all'ingresso ([BET-06]) fa sì che
il numero di monete non impedisca mai di pagare un round. La differenza
lascia spazio ad altre monete presenti sull'indirizzo del montepremi del
round (pagamenti arrivati da fuori).
*Codice:* `app/wallet/psbt_builder.py:MAX_PARTICIPANTS_PER_ROUND`, `app/bets/service.py:place_bet` ·
*Test:* `tests/unit/test_payout_builder.py`, `tests/unit/test_bets.py`
Oggi il montepremi è un solo indirizzo per tutti i round, e la differenza fra
400 e 500 copre anche i resti accumulati dai pagamenti precedenti; con un
indirizzo per round
([RND-35](ciclo-di-vita-del-round.md#0--apertura), B-80) restano solo i
pagamenti arrivati da fuori. Il numero di ingressi non è l'unica cosa che può
impedire un pagamento: vedi
[ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#4--pagamento).
### Cosa succede
Comportamento atteso:
```mermaid
flowchart TB
A["Richiesta di scommessa"] --> B["Blocco per-utente acquisito"]
B --> N{"Connessi<br/>alla rete?"}
N -- "No" --> N1["network_unavailable (503)"]
N -- "Sì" --> C["Controlli (tabella sopra)"]
C --> D["Scelta delle monete,<br/>dalla più grande"]
D --> E["Transazione firmata:<br/>costo meno commissione → montepremi del round<br/>resto → indirizzo utente"]
E --> CAS{"Scadenza non passata e<br/>round ancora 'open'<br/>(compare-and-set)?"}
CAS -- "No" --> CAS1["Annullato prima dell'invio:<br/>round_closing"]
CAS -- "Sì" --> F["Salvataggio PRIMA dell'invio:<br/>monete segnate come spese,<br/>partecipante 'building'"]
F --> G{"Risposta del server"}
G -- "Rifiuto esplicito" --> H["Tutto annullato: monete liberate,<br/>saldo ripristinato,<br/>partecipante rimosso (errore 502)"]
G -- "Nessuna risposta<br/>(timeout, connessione caduta)" --> U["Nulla liberato: partecipante 'building'<br/>(202), decide il riconciliatore"]
G -- "Accettata o già nota" --> I["Partecipante 'broadcast'<br/>(in attesa), inviata anche<br/>agli altri server"]
U --> R{"Il riconciliatore<br/>la trova in rete?"}
R -- "Sì" --> I
R -- "No, e c'è la prova<br/>che non è partita" --> X
I --> J{"Confermata entro<br/>il tempo limite?"}
J -- "No" --> K["Commissione aumentata (RBF),<br/>pagata dal resto dell'utente;<br/>un resto che finirebbe sotto 294 sat<br/>va tutto in commissione"] --> J
J -- "Mai, e c'è la prova<br/>che non è partita" --> X["Abbandonata dal riconciliatore:<br/>monete liberate, partecipante rimosso"]
J -- "Sì (prova merkle del quorum)" --> L["Partecipante confermato:<br/>entra nell'estrazione"]
```
- **[BET-12]** La transazione spende monete **intere** dell'utente, scelte
dalla più grande; tutti gli ingressi segnalano la sostituibilità (BIP125,
`RBF_SEQUENCE`). Ha due uscite: il costo meno la commissione verso
l'**indirizzo del montepremi del round** (`rounds.pool_address`,
[RND-35](ciclo-di-vita-del-round.md#0--apertura)), e il resto (monete
spese meno il costo) verso l'indirizzo dell'utente.
*Codice:* `app/wallet/psbt_builder.py:select_utxos`, `app/wallet/psbt_builder.py:build_signed_transaction`, `app/bets/service.py:place_bet` ·
*Test:* `tests/unit/test_psbt_builder.py`
*Stato:* da implementare (B-80) · *Oggi:* tutte le scommesse di tutti i
round pagano lo stesso indirizzo (`derive_pool_address`,
`m/84'/746'/0'/1/0`).
- **[BET-13]** La **commissione di rete** è la dimensione stimata della
transazione per `fee_rate_sat_vb` (1 sat/vB predefinito, modificabile da
`/admin`) ed è **dedotta dal costo** della scommessa: al montepremi arriva
il costo meno la commissione, e l'importo registrato per il partecipante
(`bet_amount_sats`) è proprio questo netto. Per questo il montepremi si
calcola sommando gli importi effettivi delle scommesse, non moltiplicando il
numero di giocatori per il costo.
*Codice:* `app/wallet/psbt_builder.py:build_signed_transaction`, `app/bets/service.py:place_bet` ·
*Test:* `tests/unit/test_psbt_builder.py`, `tests/unit/test_rounds_route.py`
- **[BET-14]** Il **resto** torna sempre allo stesso indirizzo dell'utente ed è
sempre di almeno 294 sat (`DUST_LIMIT_SATS`). A differenza del prelievo, la
scommessa non riduce mai il proprio importo per far posto al resto: la
rifiuta ([BET-09]). Le monete scelte devono quindi superare il costo di
almeno 294 sat. Questo resto è l'uscita che l'RBF riduce o elimina, secondo
la regola di
[TX-11](transazioni-e-riconciliazione.md#rbf-accelerare-una-transazione-lenta):
un resto di 294 sat non regge una riduzione (l'aumento minimo è di 141 sat a
1 sat/vB), quindi garantisce una sola accelerazione, che lo elimina.
*Codice:* `app/wallet/psbt_builder.py:build_signed_transaction` ·
*Test:* `tests/unit/test_withdrawals.py` (i test del resto delle scommesse
sono lì: `test_a_bet_from_a_balance_equal_to_the_bet_is_refused`,
`test_a_bet_with_a_dust_limit_of_headroom_is_accepted`),
`tests/unit/test_psbt_builder.py`
- **[BET-15]** **Prima si scrive, poi si invia.** Prima dell'invio, in
un'unica transazione del database, le monete spese vengono segnate come tali
(con il txid della scommessa), il saldo viene ricalcolato, e si registrano il
partecipante (stato `building`, con l'orario di invio `broadcast_at`) e la
transazione in corso (stato `building`). L'ordine dei partecipanti
nell'estrazione è definito in
[ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#3--estrazione).
Dettagli in
[transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md#il-principio-prima-si-scrive-poi-si-invia).
*Codice:* `app/bets/service.py:place_bet` ·
*Test:* `tests/unit/test_bets.py`
- **[BET-16]** Se il server **rifiuta esplicitamente** l'invio
([TX-04](transazioni-e-riconciliazione.md#invio-rifiutato)), tutto torna
com'era: monete liberate, partecipante e transazione in corso
**cancellati**, saldo ricalcolato, evento `bet_broadcast_failed` nel
registro di audit, notifica SSE; la risposta è `broadcast_failed`
(HTTP 502).
*Codice:* `app/bets/service.py:_release_failed_bet`, `app/api/routes/bets.py:create_bet` ·
*Test:* `tests/unit/test_bets.py`
*Stato:* da implementare (B-76) · *Oggi:* tutto viene annullato per
qualunque errore dell'invio, anche un timeout o una connessione caduta
dopo la scrittura, quando la transazione può essere già in rete: i suoi
sat arrivano al montepremi senza partecipante.
- **[BET-23]** Se l'invio ha un **esito incerto**
([TX-20](transazioni-e-riconciliazione.md#invio-rifiutato)), partecipante e
transazione in corso restano `building` con le monete ancora segnate come
spese, e la risposta è HTTP **202** con `round_id`, `bet_txid`,
`bet_amount_sats` e `status` = `building`. Il partecipante conta per il
limite di [BET-06] e tiene il round in `closing` finché il riconciliatore
non lo promuove o lo abbandona.
*Codice:* `app/bets/service.py:place_bet`, `app/api/routes/bets.py:create_bet` ·
*Test:* —
*Stato:* da implementare (B-76) · *Oggi:* un esito incerto è trattato come
un rifiuto ([BET-16]).
- **[BET-17]** Se l'invio è accettato — anche con un rifiuto "già nota"
([TX-04](transazioni-e-riconciliazione.md#invio-rifiutato)) — il
partecipante passa a `broadcast`, la transazione in corso a `pending`, si
scrive `bet_placed` (txid e importo netto) e si invia una notifica SSE; la
transazione viene poi inviata anche agli altri server
([TX-21](transazioni-e-riconciliazione.md#invio-rifiutato)). La risposta è
HTTP 201 con `round_id`, `bet_txid`, `bet_amount_sats` e `status`. Una
scommessa promossa dal riconciliatore scrive `bet_placed` in quel momento
([TX-16](transazioni-e-riconciliazione.md#riconciliazione)).
*Codice:* `app/bets/service.py:place_bet`, `app/api/routes/bets.py:create_bet` ·
*Test:* `tests/unit/test_bets.py`
*Stato:* da implementare (B-76) · *Oggi:* un "già nota" è trattato come un
rifiuto e la transazione va solo al server attivo.
- **[BET-18]** Alla conferma il partecipante passa a `confirmed`
([TX-07](transazioni-e-riconciliazione.md#conferma)). Solo le scommesse
**confermate** partecipano all'estrazione; il round, allo scadere, aspetta
che tutte quelle già inviate confermino (vedi
[ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#2--chiusura)).
*Codice:* `app/bets/confirmation.py:_on_bet_confirmed` ·
*Test:* `tests/unit/test_confirmation.py`
- **[BET-19]** Tutte le scommesse hanno **la stessa probabilità** di vincere,
indipendentemente dall'importo netto e da tutto il resto
([RND-17](ciclo-di-vita-del-round.md#3--estrazione)).
*Codice:* `app/rounds/draw.py:draw_winner` ·
*Test:* `tests/unit/test_draw.py`
## Prelievo
Il prelievo (`POST /withdrawals`, con `external_address` e `amount_sats`) è
l'**unico** modo per portare fondi fuori dalla piattaforma, verso un indirizzo
esterno scelto dall'utente.
- **[WDR-01]** Come per la scommessa, un prelievo senza connessione alla rete
è rifiutato con `network_unavailable` (HTTP 503), e tutta l'elaborazione
avviene tenendo il **blocco per-utente**; il client della rete viene letto
e controllato dopo aver acquisito il blocco, come in [BET-02].
*Codice:* `app/api/routes/withdrawals.py:create_withdrawal`, `app/tx/locks.py:UserLocks.acquire` ·
*Test:* — (nessun test verifica `network_unavailable`)
*Stato:* da implementare (B-96) · *Oggi:* `listener.client` viene letto e
controllato prima di acquisire il blocco.
Le condizioni sono verificate nell'ordine della tabella; un rifiuto risponde
HTTP 400 prima che si muova qualunque cifra:
| ID | Condizione | Codice di errore |
|---|---|---|
| **[WDR-02]** | L'indirizzo di destinazione è un indirizzo PLM bech32: inizia con `plm1` ed è decodificabile. Un indirizzo di un'altra catena (ad esempio `bc1…`) o in formato legacy (`P…`) è rifiutato | `invalid_address` |
| **[WDR-03]** | L'indirizzo di destinazione non è l'indirizzo di deposito dell'utente stesso | `withdrawal_to_own_address` |
| **[WDR-14]** | L'indirizzo di destinazione non è un indirizzo della piattaforma: l'indirizzo del montepremi di un round qualunque (`rounds.pool_address`), l'indirizzo di riserva (`m/84'/746'/0'/1/0`, [RND-35](ciclo-di-vita-del-round.md#0--apertura)), il `fee_address` corrente di `round_config` o quello fotografato su un round. *Stato:* da implementare (B-80) · *Oggi:* nessun controllo; un prelievo verso il montepremi finisce fra le monete di un round | `withdrawal_to_platform_address` |
| **[WDR-04]** | L'importo è almeno pari al costo di una scommessa **corrente** in `round_config` (`bet_amount_sats`; non esiste un minimo separato, e non si usa il costo fotografato su un round) | `amount_below_minimum` (parametro `minimum_sats`) |
| **[WDR-05]** | La somma delle monete confermate e non spese copre l'importo | `balance_pending_confirmation` se lo coprirebbe il saldo comprensivo di quanto è in corso (parametro `pending_sats`), altrimenti `insufficient_balance` (parametro `required_sats`) |
| **[WDR-06]** | L'importo si copre con al massimo 50 monete (`MAX_TX_INPUTS`) | `too_many_inputs` (parametro `max_inputs`) |
| **[WDR-07]** | L'importo meno la commissione di rete resta positivo e di almeno 294 sat | `amount_below_network_fee`, `amount_below_dust_limit` |
*Codice:* `app/withdrawals/service.py:request_withdrawal`, `app/wallet/address.py:is_valid_plm_address`,
`app/wallet/psbt_builder.py:build_signed_transaction` ·
*Test:* `tests/unit/test_withdrawals.py`, `tests/unit/test_psbt_builder.py`
La struttura è identica alla scommessa: transazione firmata dall'indirizzo
dell'utente verso l'indirizzo esterno, resto all'utente, **commissione dedotta
dall'importo prelevato**, salvataggio prima dell'invio, annullamento completo
solo se la rete rifiuta esplicitamente, RBF se non conferma in tempo.
- **[WDR-08]** La transazione spende monete intere dell'utente (dalla più
grande, ingressi sostituibili BIP125); all'indirizzo esterno arriva
l'importo meno la commissione di rete, il resto torna all'indirizzo
dell'utente.
*Codice:* `app/wallet/psbt_builder.py:build_signed_transaction` ·
*Test:* `tests/unit/test_psbt_builder.py`, `tests/unit/test_withdrawals.py`
- **[WDR-09]** **Resto garantito.** Se l'importo richiesto lascerebbe un resto
inferiore a 294 sat (`DUST_LIMIT_SATS`) — ad esempio il prelievo
dell'intero saldo —, l'importo viene ridotto quanto basta perché il resto
sia esattamente 294 sat, che restano sul conto dell'utente. Chi preleva
tutto riceve quindi il saldo meno 294 sat meno la commissione. Il database
registra sia l'importo richiesto (`amount_requested_sats`) sia quello
effettivamente inviato al destinatario, al netto della commissione
(`amount_sent_sats`). Come per la scommessa ([BET-14]), questo resto è
l'uscita che l'RBF riduce o elimina
([TX-11](transazioni-e-riconciliazione.md#rbf-accelerare-una-transazione-lenta)).
*Codice:* `app/wallet/psbt_builder.py:build_signed_transaction`, `app/withdrawals/service.py:request_withdrawal` ·
*Test:* `tests/unit/test_withdrawals.py`, `tests/unit/test_psbt_builder.py`
- **[WDR-15]** L'importo ridotto da [WDR-09] viene verificato di nuovo
contro il minimo di [WDR-04]: se è sceso sotto `bet_amount_sats`, il
prelievo è rifiutato con `amount_below_minimum` (parametro `minimum_sats`)
prima che si muova qualunque cifra.
*Codice:* `app/withdrawals/service.py:request_withdrawal` ·
*Test:* —
*Stato:* da implementare (B-96) · *Oggi:* il minimo è verificato solo
sull'importo richiesto, quindi un prelievo dell'intero saldo può inviare
fino a 294 sat meno del minimo.
- **[WDR-10]** Prima dell'invio, in un'unica transazione del database
([TX-28](transazioni-e-riconciliazione.md#il-principio-prima-si-scrive-poi-si-invia)),
le monete spese vengono segnate come tali, il saldo ricalcolato, e si
registrano il prelievo e la transazione in corso, entrambi in stato
`building`.
*Codice:* `app/withdrawals/service.py:request_withdrawal` ·
*Test:* `tests/unit/test_withdrawals.py`
- **[WDR-11]** Se il server **rifiuta esplicitamente** l'invio
([TX-04](transazioni-e-riconciliazione.md#invio-rifiutato)), le monete
vengono liberate e il saldo ricalcolato, ma — a differenza della
scommessa — il prelievo **non viene cancellato**: resta come `failed`
(senza txid), così come la transazione in corso (con il motivo in
`failure_reason`); si scrive `withdrawal_broadcast_failed`, si invia una
notifica SSE e la risposta è `broadcast_failed` (HTTP 502).
*Codice:* `app/withdrawals/service.py:_release_failed_withdrawal`, `app/api/routes/withdrawals.py:create_withdrawal` ·
*Test:* `tests/unit/test_withdrawals.py` (nessun test verifica l'evento
`withdrawal_broadcast_failed`)
*Stato:* da implementare (B-76) · *Oggi:* tutto viene annullato per
qualunque errore dell'invio, anche un timeout o una connessione caduta
dopo la scrittura: la transazione può essere partita mentre il prelievo
risulta `failed` e le monete di nuovo spendibili.
- **[WDR-16]** Se l'invio ha un **esito incerto**
([TX-20](transazioni-e-riconciliazione.md#invio-rifiutato)), prelievo e
transazione in corso restano `building` con le monete ancora segnate come
spese, e la risposta è HTTP **202** con `txid`, `amount_requested_sats`,
`amount_sent_sats` e `status` = `building`; sarà il riconciliatore a
promuoverlo o abbandonarlo.
*Codice:* `app/withdrawals/service.py:request_withdrawal`, `app/api/routes/withdrawals.py:create_withdrawal` ·
*Test:* —
*Stato:* da implementare (B-76) · *Oggi:* un esito incerto è trattato come
un rifiuto ([WDR-11]).
- **[WDR-12]** Se l'invio è accettato — anche con un rifiuto "già nota"
([TX-04](transazioni-e-riconciliazione.md#invio-rifiutato)) — il prelievo
passa a `broadcast`, la transazione in corso a `pending`, si scrive
`withdrawal_sent` (txid, importo inviato, indirizzo esterno) e si invia una
notifica SSE; la transazione viene poi inviata anche agli altri server
([TX-21](transazioni-e-riconciliazione.md#invio-rifiutato)). La risposta è
HTTP 201 con `txid`, `amount_requested_sats`, `amount_sent_sats` e
`status`. Alla conferma il prelievo passa a `confirmed`
([TX-07](transazioni-e-riconciliazione.md#conferma)).
*Codice:* `app/withdrawals/service.py:request_withdrawal`, `app/withdrawals/confirmation.py:_on_withdrawal_confirmed` ·
*Test:* `tests/unit/test_withdrawals.py`
*Stato:* da implementare (B-76) · *Oggi:* un "già nota" è trattato come un
rifiuto e la transazione va solo al server attivo.
## Scommessa e prelievo insieme
Scommessa e prelievo spendono le stesse monete, quindi non devono mai sceglierne
una in comune. Questo è garantito da due meccanismi:
1. un **blocco per-utente** ([BET-02](#quando-è-accettata),
[WDR-01](#prelievo)): la costruzione di una scommessa e quella di un
prelievo dello stesso utente non possono mai essere in corso nello stesso
momento;
2. la selezione delle monete **salta quelle già segnate come spese**, anche se
la transazione che le spende non è ancora confermata
([BET-07](#quando-è-accettata), [WDR-05](#prelievo)).
- **[WDR-13]** Non c'è altro vincolo: un prelievo è accettato
anche mentre una scommessa attende conferma (e viceversa), purché le monete
confermate e ancora libere lo coprano. Congelare il resto del saldo per un blocco non
aggiungerebbe alcuna sicurezza.
*Codice:* `app/withdrawals/service.py:request_withdrawal`, `app/bets/service.py:place_bet` ·
*Test:* `tests/unit/test_withdrawals.py`
Il blocco per-utente vive nella memoria del processo: vale finché il server è
un solo processo (vedi [architettura.md](architettura.md) e
[decisioni-e-limiti.md](decisioni-e-limiti.md)).
Cosa succede a una transazione dopo l'invio — conferma, RBF, abbandono — è
descritto in [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md).
+9 -5
View File
@@ -35,8 +35,11 @@ cp .env.example .env
| `JWT_SECRET` | Firma i token di sessione degli utenti. | `python -c "import secrets; print(secrets.token_urlsafe(32))"` |
| `ADMIN_TOKEN` | Token bearer richiesto sugli endpoint admin (header `X-Admin-Token`). | `python -c "import secrets; print(secrets.token_urlsafe(32))"` |
Le altre chiavi di `.env` (`DATABASE_URL`, `ELECTRUM_HOST`/`PORT`/`USE_SSL`,
`MASTER_KEY_PATH`) hanno default sensati in `.env.example`.
Le chiavi Electrum (`ELECTRUM_HOST`/`PORT`/`USE_SSL`) hanno default sensati in
`.env.example`. `DATABASE_URL` e `MASTER_KEY_PATH` non sono elencate lì:
hanno un default in `app/config.py`, e dentro il container vengono comunque
sovrascritte da `docker-compose.yml` per puntare a `./data/` (elenco completo
delle variabili in [architettura.md](architettura.md)).
`ENABLE_API_DOCS` (default `false`) controlla Swagger/ReDoc/l'OpenAPI JSON grezzo
su `/docs`, `/redoc` e `/openapi.json`: espongono l'intera superficie dell'API,
@@ -119,9 +122,10 @@ pip install -e ".[dev]"
## 6. Impostare l'indirizzo delle fee
Prima che il primo round possa pagare, un admin deve impostare `fee_address`
tramite il pannello admin o l'API — vedi [guida-admin.md](guida-admin.md). I
payout si rifiutano di partire finché non è impostato.
Prima che si possa aprire il primo round, un admin deve impostare
`fee_address` tramite il pannello admin o l'API — vedi
[guida-admin.md](guida-admin.md). Finché non è impostato **nessun round si
apre**, perché il pagamento non si potrebbe costruire.
A questo punto l'istanza è pronta per essere avviata — continua con
[running-the-server.md](running-the-server.md).
+515
View File
@@ -0,0 +1,515 @@
# Sicurezza
Come PLM Lottery protegge le chiavi, le sessioni e l'accesso all'API, e
quali rischi accetta consapevolmente. Il documento descrive il codice così
com'è: dove un meccanismo manca, lo dice.
Per la difesa contro server Electrum ostili (validazione degli header,
quorum di corroborazione) vedi [connessione-electrum.md](connessione-electrum.md);
per gli endpoint e i codici di errore [api.md](api.md); per l'elenco degli
eventi di audit [audit-log.md](audit-log.md); per backup e procedure
operative [operativita.md](operativita.md); per le decisioni di progetto e i
limiti accettati [decisioni-e-limiti.md](decisioni-e-limiti.md).
## Modello di fiducia
La piattaforma è **custodiale**: tutte le chiavi private sono generate e
conservate dal server. L'utente non controlla nulla finché non preleva.
| Soggetto | Fiducia | Perché |
|---|---|---|
| Operatore (chi ha `ADMIN_TOKEN`) | **Totale** | Può esportare la chiave privata di ogni utente, reimpostare le password, cambiare l'indirizzo delle commissioni. |
| Host del server (chi ha accesso al filesystem o a Docker) | **Totale** | Sullo stesso host stanno la master key cifrata *e* la chiave che la decifra (`.env`). |
| Utenti | Nessuna | Ogni input è validato; ogni azione è legata al proprio account tramite JWT. |
| Server Electrum | Nessuna | Header validati e decisioni che muovono denaro corroborate da un quorum: vedi [connessione-electrum.md](connessione-electrum.md#5-il-quorum). |
| Rete e client HTTP | Nessuna | TLS terminato da Caddy; l'IP del client è ricavato solo dall'hop scritto da Caddy. |
| Caddy (reverse proxy) | Totale | È l'unico proxy davanti all'app, e l'unica fonte di `X-Forwarded-For` di cui l'app si fida. |
- **[SEC-01]** Tutte le chiavi private (utenti e montepremi) derivano da
un'unica master xprv generata e custodita dal server; nessuna chiave è mai
generata o conservata lato client.
*Codice:* `app/wallet/hd.py:generate_master_key`, `app/wallet/hd.py:_load_account_key`
## Inventario dei segreti
| Segreto | Dove vive | Come si genera | Se trapela | Se si perde | Rotazione |
|---|---|---|---|---|---|
| Master xprv | File cifrato `MASTER_KEY_PATH` (in Docker `./data/keys/master.xprv.enc`, montato in `/app/key_data/`) | `scripts/generate_master_key.py` (32 byte da `os.urandom`) oppure importata con `scripts/encrypt_master_key.py` | Il file da solo è inutile senza `XPRV_ENCRYPTION_KEY`; insieme, chi li ha può spendere **tutti** i fondi (utenti e montepremi) | Tutti i fondi diventano irrecuperabili, salvo un backup in chiaro ottenuto con `decrypt_master_key.py` | **Non ruotabile**: gli indirizzi degli utenti sono permanenti e derivati da essa |
| `XPRV_ENCRYPTION_KEY` | `.env` (variabile d'ambiente del container) | `Fernet.generate_key()` (comando in `.env.example`) | Insieme al file cifrato: come sopra | Il file cifrato non è più leggibile: fondi persi senza backup della xprv | Manuale: decifrare con la chiave vecchia, impostare la nuova, `encrypt_master_key.py --overwrite`. Non esiste uno script dedicato |
| `JWT_SECRET` | `.env` | `secrets.token_urlsafe(32)` | Chiunque può firmare un token per qualunque utente (con il `tv` corretto, che è un piccolo intero) e agire come lui, prelievi compresi | Nessuna perdita di dati: se ne genera uno nuovo | Cambiarlo e riavviare invalida **tutte** le sessioni |
| `ADMIN_TOKEN` | `.env`; nel browser dell'operatore in `sessionStorage` (`plm_admin_token`) | `secrets.token_urlsafe(32)` | Accesso completo a `/admin/*`, compreso l'export delle chiavi private | Nessuna: se ne imposta uno nuovo | Cambiarlo e riavviare; l'operatore reinserisce il token |
| Hash delle password | Tabella `users` (SQLite, `./data/db/`) | Argon2id | Attacco offline a dizionario, rallentato dai parametri Argon2 | — | Reset dall'operatore |
| JWT dell'utente | Browser, `localStorage` (`plm_token`) | Emesso al login/registrazione | Sessione dell'utente fino alla scadenza (24h) o al cambio password | — | Cambio password o reset dall'operatore |
- **[SEC-02]** I segreti (`XPRV_ENCRYPTION_KEY`, `JWT_SECRET`, `ADMIN_TOKEN`)
stanno solo in `.env`, mai nel database o nel repository; `.env`, i file
`master.xprv.enc`, i database `*.db`, `data/` e `logs/` sono esclusi sia da
git sia dall'immagine Docker.
*Codice:* `app/config.py:Settings`, `.gitignore`, `.dockerignore`
- **[SEC-03]** Tutti i parametri operativi stanno nel database
(`round_config`); in `.env` restano solo segreti e collegamenti
infrastrutturali (database, percorso della master key, server Electrum,
documentazione API). Cambiare un valore di `.env` richiede un riavvio.
*Codice:* `app/config.py:Settings`
`.env.example` documenta le chiavi necessarie e il comando per generarle;
non elenca `DATABASE_URL` né `MASTER_KEY_PATH`, che in Docker sono comunque
sovrascritte da `docker-compose.yml`.
## Ciclo di vita della master key
```mermaid
flowchart TD
G["generate_master_key.py<br/>seed casuale 32 byte"] --> E
I["encrypt_master_key.py<br/>xprv importata (input nascosto)"] --> E
E["Cifratura Fernet<br/>con XPRV_ENCRYPTION_KEY"] --> F[("master.xprv.enc<br/>./data/keys/")]
F --> L["Primo uso a runtime:<br/>decifratura e derivazione<br/>di m/84'/746'/0'"]
L --> U["Utenti<br/>m/84'/746'/0'/0/indice"]
L --> P["Montepremi<br/>m/84'/746'/0'/1/0"]
F --> D["decrypt_master_key.py<br/>stampa la xprv in chiaro<br/>(solo recupero)"]
```
### Generazione
- **[SEC-04]** La master key si crea solo con uno script manuale, mai tramite
API: `generate_master_key.py` genera un seed casuale di 32 byte, ne ricava
la xprv (versione PLM mainnet), la cifra e la scrive in `MASTER_KEY_PATH`.
Rifiuta di sovrascrivere un file esistente; entrambi gli script di
creazione rifiutano di partire se `XPRV_ENCRYPTION_KEY` è vuota.
*Codice:* `app/wallet/hd.py:generate_master_key`, `scripts/generate_master_key.py`
- **[SEC-05]** `encrypt_master_key.py` importa una xprv generata altrove: la
legge con input nascosto (`getpass`), verifica che sia una chiave estesa
valida e **privata** (rifiuta una xpub), e la cifra con lo stesso schema.
Non può verificare che sia una chiave PLM: PLM usa gli stessi byte di
versione xprv di Bitcoin. Sovrascrive un file esistente solo con
`--overwrite`.
*Codice:* `scripts/encrypt_master_key.py`
### Cifratura a riposo
- **[SEC-06]** Il file della master key contiene la xprv in base58 cifrata con
**Fernet** (AES-128-CBC + HMAC-SHA256) usando `XPRV_ENCRYPTION_KEY`. La xprv
in chiaro non viene mai scritta su disco dal server.
*Codice:* `app/wallet/keystore.py:encrypt_xprv`, `app/wallet/keystore.py:decrypt_xprv`
La cifratura protegge da una copia del solo file (un backup di `data/`
finito nel posto sbagliato), **non** da chi ha accesso all'host: la chiave di
decifratura sta nel `.env` accanto. Gli script non impostano permessi
restrittivi sul file scritto: valgono quelli predefiniti del sistema.
### Derivazione
- **[SEC-07]** Gli indirizzi utente seguono BIP84 con coin type 746:
`m/84'/746'/0'/0/<derivation_index>`, un indice per utente, P2WPKH con HRP
`plm`.
*Codice:* `app/wallet/hd.py:derive_user_key`, `app/wallet/hd.py:derive_user_address`,
`app/wallet/plm_network.py` ·
*Test:* `tests/unit/test_hd.py`
- **[SEC-08]** La chiave del montepremi è `m/84'/746'/0'/1/0` (ramo 1
dell'account, indice 0): sta nella stessa master key, non è un segreto
separato. Non esiste un endpoint che ne esporti la chiave privata.
*Codice:* `app/wallet/hd.py:derive_pool_key`, `app/wallet/hd.py:derive_pool_address`
### Caricamento a runtime
- **[SEC-09]** La master key viene letta e decifrata **al primo uso** (la
prima derivazione, tipicamente una registrazione o il primo pagamento), non
all'avvio. Da quel momento la chiave dell'account `m/84'/746'/0'` resta in
memoria nel processo per tutta la sua durata; la root xprv non viene
conservata.
*Codice:* `app/wallet/hd.py:_load_account_key`
### Recupero
- **[SEC-10]** `decrypt_master_key.py` decifra e stampa la xprv in chiaro, solo
dopo una conferma esplicita (`yes`) e un avviso sul terminale. Se il
percorso di `MASTER_KEY_PATH` non esiste usa `./data/keys/master.xprv.enc`.
Non esiste un equivalente via API o pannello.
*Codice:* `scripts/decrypt_master_key.py`
## Regole di avvio
- **[SEC-11]** Il container rifiuta di partire se il file della master key non
esiste in `MASTER_KEY_PATH`, prima ancora delle migrazioni.
*Codice:* `Dockerfile` (comando `CMD`)
- **[SEC-12]** All'avvio il server **rifiuta di servire** se `JWT_SECRET` ha
meno di 32 caratteri o se `XPRV_ENCRYPTION_KEY` è vuota; tutti i problemi
sono riportati insieme in un unico `ConfigError`. Il controllo è nel
lifespan, non nella classe `Settings`, perché test e script importano la
configurazione senza avere segreti reali.
*Codice:* `app/config.py:validate_runtime_secrets`, `app/main.py:lifespan` ·
*Test:* `tests/unit/test_config.py`
- **[SEC-13]** Un `ADMIN_TOKEN` vuoto **non** blocca l'avvio: il pannello
risulta semplicemente chiuso (vedi [SEC-24]).
*Codice:* `app/config.py:validate_runtime_secrets` ·
*Test:* `tests/unit/test_config.py`
Il controllo di avvio verifica che `XPRV_ENCRYPTION_KEY` non sia vuota, non
che sia una chiave Fernet valida né che decifri davvero il file: una chiave
malformata o sbagliata emerge solo al primo uso della master key ([SEC-09]).
## Autenticazione degli utenti
Il flusso di registrazione e login è descritto in
[registrazione-e-depositi.md](registrazione-e-depositi.md#registrazione);
qui ci sono le regole di sicurezza.
### Password
- **[SEC-14]** Le password sono salvate come hash **Argon2id** con i parametri
predefiniti di `argon2-cffi` (`PasswordHasher()` senza argomenti; con la
versione installata 25.1: time cost 3, memoria 64 MiB, parallelismo 4, sale
16 byte, hash 32 byte). Mai in chiaro, mai recuperabili.
*Codice:* `app/auth/security.py:hash_password` ·
*Test:* `tests/unit/test_security.py`
- **[SEC-15]** Ogni hash e verifica chiamati da codice asincrono passano da
`hash_password_async`/`verify_password_async`, che eseguono Argon2 in un
thread del threadpool: un login non deve bloccare l'event loop e con esso le
attività in background. Le versioni sincrone restano per test e script.
*Codice:* `app/auth/security.py:hash_password_async`, `app/auth/security.py:verify_password_async` ·
*Test:* `tests/unit/test_security.py`
- **[SEC-16]** Qualunque errore di verifica (password sbagliata, hash
illeggibile) vale come "password errata", mai come errore del server; un
hash illeggibile viene anche registrato nel log.
*Codice:* `app/auth/security.py:verify_password` ·
*Test:* `tests/unit/test_security.py`
- **[SEC-17]** Lunghezza minima della password: 8 caratteri
(`MIN_PASSWORD_LENGTH`), la stessa costante per registrazione e cambio
password. Alla registrazione la password ha anche un massimo di 256
caratteri; il cambio password e il login non impongono un massimo.
*Codice:* `app/auth/security.py:MIN_PASSWORD_LENGTH`, `app/auth/routes.py:RegisterRequest`,
`app/api/routes/users.py:change_password` ·
*Test:* `tests/unit/test_users.py`
- **[SEC-18]** Lo username è di 3–32 caratteri, solo `A-Z a-z 0-9 _ . -`, e
**non distingue maiuscole e minuscole**: l'unicità è garantita da un indice
unico su `lower(username)` e registrazione e login confrontano
`lower(...)`. Il nome resta salvato come digitato.
*Codice:* `app/auth/routes.py:RegisterRequest`, `app/auth/routes.py:register`,
`app/auth/routes.py:login`, `app/db/models.py:User` ·
*Test:* `tests/unit/test_auth.py`
- **[SEC-19]** Il login risponde allo stesso modo (401 `invalid_credentials`)
sia per uno username inesistente sia per una password errata, e i due casi
alimentano lo stesso contatore di tentativi. Nota: se lo username non
esiste la verifica Argon2 non viene eseguita, quindi i due casi hanno tempi
di risposta diversi. La registrazione, invece, rivela per costruzione se uno
username è occupato (409 `username_taken`).
*Codice:* `app/auth/routes.py:login` ·
*Test:* `tests/unit/test_auth.py`
- **[SEC-20]** Non esiste recupero della password né reset self-service
(nessuna email è raccolta). Un utente autenticato può *cambiarla* solo
fornendo quella attuale; altrimenti serve il reset dall'operatore
([SEC-27]).
*Codice:* `app/api/routes/users.py:change_password` ·
*Test:* `tests/unit/test_users.py`
### Token di sessione (JWT)
- **[SEC-21]** Login e registrazione restituiscono un JWT **HS256** firmato con
`JWT_SECRET`, valido `jwt_expire_minutes` (predefinito 1440 = 24 ore). Le
claim sono `sub` (id utente), `tv` (versione del token) ed `exp`. La
decodifica accetta solo l'algoritmo configurato. Il client lo invia come
`Authorization: Bearer …` e lo conserva in `localStorage`.
*Codice:* `app/auth/security.py:create_access_token`, `app/auth/security.py:decode_access_token` ·
*Test:* `tests/unit/test_security.py`
- **[SEC-22]** I token sono **revocabili**: ogni richiesta autenticata
confronta la claim `tv` con `User.token_version` e rifiuta (401
`session_expired`) un token con una versione diversa, un token non valido o
scaduto, o un utente inesistente. Il cambio password self-service e il reset
dell'operatore incrementano `token_version`, invalidando ogni sessione
precedente; il cambio password restituisce un token nuovo, così la sessione
corrente resta attiva. Un token privo di `tv` (emesso prima della sua
introduzione) vale come `tv = 0`.
*Codice:* `app/auth/dependencies.py:get_current_user`, `app/api/routes/users.py:change_password`,
`app/api/routes/admin.py:reset_user_password` ·
*Test:* `tests/unit/test_users.py`, `tests/unit/test_security.py`, `tests/unit/test_admin.py`
- **[SEC-23]** Gli endpoint raggiungibili anche da non autenticati (ad esempio
`GET /rounds/current`, `POST /bug-reports`) usano l'utente solo per
personalizzare la risposta: un token assente, non valido o superato li fa
trattare come anonimi, senza errore.
*Codice:* `app/auth/dependencies.py:get_optional_user` ·
*Test:* `tests/unit/test_rounds_route.py`, `tests/unit/test_bug_reports.py`
## Autenticazione dell'operatore
Il pannello `/admin` è una pagina statica pubblica; la protezione sta sugli
endpoint `/admin/*`, che richiedono l'header `X-Admin-Token`.
- **[SEC-24]** Ogni endpoint `/admin/*` confronta `X-Admin-Token` con
`ADMIN_TOKEN` in tempo costante (`secrets.compare_digest` sui byte UTF-8,
così un token con caratteri non ASCII dà 403 e non 500). Se `ADMIN_TOKEN` è
vuoto **ogni** richiesta è rifiutata con 403, prima del confronto (che su due
stringhe vuote darebbe esito positivo).
*Codice:* `app/api/routes/admin.py:require_admin` ·
*Test:* `tests/unit/test_admin.py`
- **[SEC-25]** Il token è **unico e condiviso**: non esiste un'identità per
singolo operatore, e l'audit log registra *cosa* è cambiato ma non *chi*
l'ha fatto. Non c'è limite di tentativi né lunghezza minima imposta su
`ADMIN_TOKEN`. Nel browser il token è tenuto in `sessionStorage`, quindi si
perde alla chiusura della scheda.
*Codice:* `app/api/routes/admin.py:require_admin`, `app/static/admin.js`
Il token protegge: configurazione e pausa/ripresa della lotteria, elenco
utenti con saldi, export della chiave privata, reset della password, storico
dei round, transazioni pendenti, audit log, bug report. L'elenco completo
degli endpoint è in [api.md](api.md).
- **[SEC-26]** `GET /admin/users/{id}/privkey` esporta la chiave privata WIF
dell'utente: è **intenzionale** (il server ha già la master key; l'endpoint
espone solo ciò che l'operatore potrebbe comunque ricavare). Ogni accesso
scrive `admin_privkey_accessed` nell'audit log (con l'id utente, mai la
chiave). Il pannello mostra la WIF con `textContent`, senza conservarla.
*Codice:* `app/api/routes/admin.py:user_privkey`, `app/wallet/hd.py:derive_user_wif` ·
*Test:* `tests/unit/test_admin.py`
- **[SEC-27]** `POST /admin/users/{id}/reset-password` imposta una password
casuale (`secrets.token_urlsafe(12)`, 16 caratteri), la restituisce **una
sola volta** perché l'operatore la comunichi, incrementa `token_version`
([SEC-22]) e scrive `admin_password_reset` nell'audit log (senza la
password).
*Codice:* `app/api/routes/admin.py:reset_user_password` ·
*Test:* `tests/unit/test_admin.py`
- **[SEC-28]** Ogni azione dell'operatore che cambia lo stato lascia una
traccia nell'audit log: modifica della configurazione (`config_updated`,
con valori prima/dopo, niente se nulla cambia), pausa e ripresa
(`lottery_paused`/`lottery_resumed`, e `paused` non è modificabile da
`PUT /admin/config`), cambio di stato di un bug report
(`bug_report_status_changed`). Il catalogo completo è in
[audit-log.md](audit-log.md).
*Codice:* `app/api/routes/admin.py:update_config`, `app/api/routes/admin.py:pause_lottery`,
`app/api/routes/admin.py:resume_lottery`, `app/api/routes/admin.py:update_bug_report_status` ·
*Test:* `tests/unit/test_admin.py`, `tests/unit/test_bug_reports.py`
- **[SEC-29]** `fee_address`, se modificato dall'operatore, deve essere un
indirizzo PLM bech32 valido (checksum e HRP `plm`): un indirizzo di un'altra
catena manderebbe ogni commissione su uno script irraggiungibile. Anche gli
altri parametri di `PUT /admin/config` hanno limiti minimi e massimi.
*Codice:* `app/api/routes/admin.py:RoundConfigUpdate` ·
*Test:* `tests/unit/test_admin.py`
## Limiti di frequenza
Tutti i limitatori sono **in memoria, nel singolo processo**: si azzerano a
ogni riavvio e non funzionerebbero con più worker.
| Limitatore | Chiave | Regola | Dove |
|---|---|---|---|
| Login per username | `user:<username minuscolo>` | Dal 5° fallimento: blocco di 2s, raddoppiato a ogni fallimento successivo, massimo 300s. Il contatore si azzera dopo 900s senza fallimenti, o con un login riuscito | `POST /auth/login` |
| Login per IP | `ip:<ip>` | Dal 20° fallimento: stessa progressione (2s → 300s), stesso decadimento di 900s. **Non** si azzera con un login riuscito | `POST /auth/login` |
| Registrazione per IP | `ip:<ip>` | Al massimo 5 account creati per IP in una finestra mobile di 3600s. Contano solo gli account creati davvero | `POST /auth/register` |
| Stream SSE per IP | IP | Al massimo 5 stream contemporanei per IP: il 6° chiude il più vecchio dello stesso IP | `GET /rounds/stream` |
| Stream SSE globale | — | Al massimo 500 stream contemporanei: oltre, 503 | `GET /rounds/stream` |
- **[SEC-30]** Il login è bloccato se **uno qualunque** dei due limitatori
(username o IP) è in blocco, anche con la password giusta; la risposta è
429 `rate_limited` con `retry_after_seconds` nei `params`. Ogni fallimento
alimenta entrambi i limitatori; un successo azzera solo quello dello
username.
*Codice:* `app/auth/routes.py:login`, `app/auth/rate_limit.py:RateLimiter`,
`app/auth/rate_limit.py:AuthRateLimiters` ·
*Test:* `tests/unit/test_auth.py`, `tests/unit/test_rate_limit.py`
- **[SEC-31]** La registrazione è una **quota**, non un freno sui fallimenti:
5 account per IP ogni 3600s (finestra mobile). Il controllo avviene prima
dell'hash Argon2; un tentativo che non crea l'account (username occupato,
input non valido) non consuma la quota. Oltre la quota: 429 `rate_limited`
con l'attesa esatta fino all'uscita dalla finestra dell'account più vecchio.
*Codice:* `app/auth/routes.py:register`, `app/auth/rate_limit.py:RollingQuota` ·
*Test:* `tests/unit/test_auth.py`, `tests/unit/test_rate_limit.py`
- **[SEC-32]** La memoria dei limitatori è limitata: le voci esaurite vengono
rimosse (al più ogni 60s, e alla lettura), e comunque non si superano 50.000
chiavi; oltre, si scartano le voci più vicine alla scadenza, mai i blocchi
più recenti.
*Codice:* `app/auth/rate_limit.py:RateLimiter._prune`, `app/auth/rate_limit.py:RollingQuota._prune` ·
*Test:* `tests/unit/test_rate_limit.py`
- **[SEC-33]** Il canale SSE accetta al massimo 5 stream contemporanei per IP
(il sesto chiude il più vecchio dello stesso IP invece di essere
rifiutato) e 500 in totale (oltre, 503; il browser ripiega sul polling).
*Codice:* `app/rounds/events.py:RoundEventBroadcaster.subscribe`,
`app/api/routes/rounds.py:round_stream` ·
*Test:* `tests/unit/test_round_events.py`
- **[SEC-34]** **Non** hanno limiti di frequenza: scommesse, prelievi, cambio
password (tentativi sulla password attuale compresi), endpoint admin
(tentativi sul token compresi), invio di bug report (anche anonimi), QR,
`GET /rounds/current` e gli altri endpoint di lettura. Scommesse e prelievi
sono serializzati per utente dal blocco per-utente (vedi
[scommesse-e-prelievi.md](scommesse-e-prelievi.md#scommessa-e-prelievo-insieme)),
che non è un limite di frequenza.
*Codice:* `app/api/routes/bets.py`, `app/api/routes/withdrawals.py`,
`app/api/routes/users.py:change_password`, `app/api/routes/bug_reports.py:create_bug_report`
## Indirizzo IP del client
Ogni controllo basato sull'IP (limitatori di login e registrazione, limite
SSE per IP) usa la stessa funzione.
- **[SEC-35]** L'IP del client è l'**ultimo** elemento di `X-Forwarded-For`
(quello scritto dall'hop più vicino, cioè Caddy), non il primo, che il
client può falsificare. Senza l'header si usa l'indirizzo della connessione,
e in mancanza anche di quello `unknown`.
*Codice:* `app/api/client_ip.py:client_ip` ·
*Test:* `tests/unit/test_client_ip.py`
- **[SEC-36]** Caddy **sovrascrive** `X-Forwarded-For` con l'indirizzo reale
del peer (`header_up X-Forwarded-For {remote_host}`) invece di accodarlo a
quello inviato dal client. Le due difese ([SEC-35] e questa) reggono
ciascuna da sola.
*Codice:* `Caddyfile` ·
*Test:* `tests/unit/test_caddyfile_security_headers.py`
- **[SEC-37]** Il container `app` non è pubblicato sull'host: la porta 8123
è solo dichiarata con `expose` sulla rete interna di compose, e l'unico ingresso
dall'esterno è Caddy (porte 80 e 443). È questo che rende affidabile
l'ultimo hop di `X-Forwarded-For`.
*Codice:* `docker-compose.yml`
## TLS e header HTTP
- **[SEC-38]** Caddy termina TLS: con `SITE_ADDRESS` impostato ottiene e
rinnova un certificato Let's Encrypt; con il valore predefinito
`localhost` usa un certificato autofirmato della propria CA interna.
*Codice:* `Caddyfile`, `docker-compose.yml`
- **[SEC-39]** Caddy aggiunge a ogni risposta questi header:
```
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
X-Frame-Options "DENY"
Referrer-Policy "strict-origin-when-cross-origin"
Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self'; connect-src 'self'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'; object-src 'none'"
```
*Codice:* `Caddyfile` ·
*Test:* `tests/unit/test_caddyfile_security_headers.py`
La CSP è la principale difesa contro l'XSS, rilevante perché il JWT sta in
`localStorage` e uno script iniettato potrebbe leggerlo. `script-src` e
`style-src` richiedono però `'unsafe-inline'`: entrambe le SPA usano gestori
`onclick` e attributi `style=""` inline ovunque, e toglierli è un refactoring
a sé. L'unica risorsa esterna ammessa è Google Fonts (l'`@import` in
`style.css`/`admin.css`). I dati provenienti dal server inseriti con
`innerHTML` nei due pannelli passano da una funzione `escapeHtml`.
- **[SEC-40]** Le pagine HTML (`/`, `/admin`, `/guida`, `/report-bug`) sono
servite con `Cache-Control: no-store`. Non è configurato alcun middleware
CORS: il browser consente le chiamate all'API solo dalla stessa origine.
*Codice:* `app/main.py:index_page`, `app/main.py:admin_panel`
## Superficie esposta
- **[SEC-41]** La documentazione interattiva dell'API (Swagger `/docs`, ReDoc
`/redoc`, `/openapi.json`) è **disattivata** salvo `ENABLE_API_DOCS=true`,
da usare solo in sviluppo: elencherebbe l'intera API, admin compreso.
*Codice:* `app/config.py:Settings`, `app/main.py` ·
*Test:* `tests/unit/test_docs_disabled.py`
- **[SEC-42]** Un errore non gestito risponde 500 con il formato di errore
standard (`internal_error`) e **senza** il testo dell'eccezione, che resta
solo in `logs/app.log`.
*Codice:* `app/main.py:log_unhandled_exception`
Il pannello `/admin` non è collegato da `/` (né viceversa), ma è una scelta
di discrezione, non una protezione: la pagina è pubblica, gli endpoint no.
## Validazione degli input
- **[SEC-43]** Un indirizzo fornito dall'esterno (destinazione di un prelievo,
`fee_address`, QR) è accettato solo se inizia con `plm1` **e** supera la
decodifica bech32 con checksum: un indirizzo valido di un'altra catena
(`bc1…`) sarebbe altrimenti uno script valido su cui i fondi andrebbero
persi. Il prelievo verso il proprio indirizzo di deposito è rifiutato.
*Codice:* `app/wallet/address.py:is_valid_plm_address`,
`app/withdrawals/service.py:request_withdrawal` ·
*Test:* `tests/unit/test_withdrawals.py`, `tests/unit/test_qr.py`
- **[SEC-44]** `GET /qr/{address}` è pubblico (lo carica un `<img>`, che non
può portare il token) ma limitato: rifiuta con 400 `invalid_address` un
indirizzo più lungo di 100 caratteri o non valido ([SEC-43]) prima di
generare qualunque immagine; il rendering avviene fuori dall'event loop ed è
memorizzato per al più 512 indirizzi.
*Codice:* `app/api/routes/qr.py:address_qr`, `app/api/routes/qr.py:_render_png` ·
*Test:* `tests/unit/test_qr.py`
- **[SEC-45]** Un bug report ha una descrizione obbligatoria di 1–2000
caratteri (non vuota dopo il trim) e un contatto facoltativo di al più 256
caratteri. Può essere inviato anche da non autenticati; se il mittente è
autenticato viene associato al suo account, e solo lui vede i propri report
(`GET /bug-reports/mine`, autenticato).
*Codice:* `app/api/routes/bug_reports.py:BugReportCreate`,
`app/api/routes/bug_reports.py:create_bug_report`,
`app/api/routes/bug_reports.py:list_my_bug_reports` ·
*Test:* `tests/unit/test_bug_reports.py`
- **[SEC-46]** Gli endpoint admin che elencano dati (round, audit log,
transazioni pendenti, bug report) accettano `limit` tra 1 e 500. L'elenco
utenti non è paginato.
*Codice:* `app/api/routes/admin.py:list_rounds`, `app/api/routes/admin.py:list_audit_log`,
`app/api/routes/admin.py:list_pending_transactions`, `app/api/routes/admin.py:list_bug_reports`,
`app/api/routes/admin.py:list_users` ·
*Test:* `tests/unit/test_admin.py`
Tutto l'accesso al database passa dall'ORM di SQLAlchemy con parametri, senza
SQL composto da stringhe.
## Dati conservati e log
- **[SEC-47]** Di un utente si conservano solo: username (come digitato), hash
Argon2 della password, indice di derivazione, indirizzo, saldo in cache,
`token_version`, data di creazione. **Nessuna email** né altro dato
anagrafico. L'unico campo libero che può contenere un recapito è il
`contact` facoltativo di un bug report. Gli indirizzi IP dei client non
sono salvati nel database: l'app li usa solo nella memoria dei limitatori.
*Codice:* `app/db/models.py:User`, `app/db/models.py:BugReport`
La struttura completa delle tabelle è in [modello-dati.md](modello-dati.md).
- **[SEC-48]** Nessun segreto finisce nei log o nell'audit log: né password
(nemmeno quella generata dal reset), né WIF, né token, né la master key. Il
log applicativo (`logs/app.log`, rotazione a 10 MB × 5 file) contiene i
messaggi dell'app e di uvicorn, incluso il log di accesso di uvicorn
(indirizzo del peer diretto, metodo, percorso, esito: nessun percorso
contiene un segreto, e gli header `Authorization`/`X-Admin-Token` non sono
registrati). L'unico script che stampa un segreto è
`decrypt_master_key.py`, per scelta e dopo conferma. WIF e password
generate dal reset compaiono solo nella risposta HTTP all'operatore.
*Codice:* `app/logging_config.py:setup_logging`, `app/api/routes/admin.py:user_privkey`,
`app/api/routes/admin.py:reset_user_password`
## Rischi accettati
Limiti noti e voluti, descritti in dettaglio in
[decisioni-e-limiti.md](decisioni-e-limiti.md):
- **Custodia totale.** Chi controlla l'host o `ADMIN_TOKEN` controlla tutti i
fondi; la cifratura a riposo non protegge da chi ha accesso all'host.
- **Token admin unico e condiviso**, senza identità per operatore né limite
di tentativi: una fuga ha il raggio d'azione massimo.
- **JWT in `localStorage`**, quindi leggibile da un eventuale XSS; la CSP lo
mitiga ma ammette script inline.
- **Limiti di frequenza solo su login, registrazione e SSE**, in memoria e per
singolo processo.
- **Nessuna corroborazione se `ELECTRUM_FALLBACK_SERVERS` è vuoto**: il server
Electrum principale diventa fidato (vedi
[connessione-electrum.md](connessione-electrum.md#5-il-quorum)).
- **Una sola conferma** per ogni transazione, con il rischio di
riorganizzazione accettato e nessuna logica di rollback.
- **La master key non è ruotabile**: gli indirizzi degli utenti sono
permanenti.
+213
View File
@@ -0,0 +1,213 @@
# Storico dei bug
Registro di tutti i difetti numerati `B-nn` trovati finora: cosa non andava,
quanto era grave, quale commit lo ha corretto e quale test impedisce che
ritorni. È la memoria storica del progetto; le regole valide oggi stanno negli
altri documenti della specifica, a cui la colonna **Area** rimanda per
prefisso (vedi [processo-di-modifica.md](processo-di-modifica.md#prefissi)).
Questo file non contiene requisiti e quindi non ha identificativi propri.
## Convenzione
- **Un difetto nuovo prende il prossimo numero libero**, senza riusare né
rinumerare quelli esistenti. **Il prossimo numero libero è `B-73`.**
- **Un commit dedicato per ogni difetto**, con il numero nel messaggio (ad
esempio `Snapshot a round's timing when it opens (B-61)`), così
`git log --all --grep 'B-nn'` ritrova sempre come è stato chiuso.
- **Un test di regressione per ogni difetto**, che cita il numero nella sua
docstring o in un commento. Dove un test automatico non è possibile (resa
grafica nel browser, layout dell'immagine Docker) lo si dichiara, come nelle
righe marcate *manuale* qui sotto.
- **Il marcatore `B-nn` va anche nel codice**, in un commento accanto alla
correzione: le centinaia di riferimenti sparsi in codice e test sono puntatori verso
questo registro e verso la storia git.
- **Prima la specifica, se era sbagliata.** Una correzione che riporta il
codice a ciò che i documenti già dicevano è solo un `B-nn`. Se invece il
difetto rivela che la specifica era sbagliata o incompleta, si corregge prima
il requisito in `docs/`, come per qualunque altra modifica
([processo-di-modifica.md](processo-di-modifica.md#il-ciclo-di-una-modifica)).
- I limiti accettati **per scelta** non sono bug e non prendono un `B-nn`:
stanno in [decisioni-e-limiti.md](decisioni-e-limiti.md).
### Da dove vengono questi dati
I difetti sono stati tracciati in un file `BUGS.md` alla radice del
repository, riscritto a ogni audit:
| Versione | Commit | Contenuto |
|---|---|---|
| Audit 2026-07-26 | `fb734bb`, `9b6a4a2`, `845ba98` | B-01 … B-24, con gravità, correzione proposta e, nell'ultima versione, la nota **Fixed** di ciascuno |
| Audit 2026-07-27 | `43d2321`, `7224ca0` | B-25 … B-49 con gravità |
| Chiusura | `0d2fef6` | file cancellato quando entrambe le liste erano vuote |
| Audit 2026-08-03 | `99d7a1e` e successivi | B-52 … B-72, ogni voce rimossa al momento della correzione |
Per leggere una versione: `git show <commit>:BUGS.md`. Il `BUGS.md` attuale,
presente nel ramo `main`, contiene solo le voci ancora aperte (B-71 e B-72).
La gravità è quella registrata in `BUGS.md` al momento dell'audit. Il terzo
audit la definiva così, e la stessa scala vale in sostanza anche per i primi
due: **critica** = denaro bloccato o perso, oppure la lotteria si ferma;
**alta** = un controllo di sicurezza che non regge, o un difetto con effetti
seri sul denaro; **media** = comportamento errato con danni circoscritti;
**bassa** = igiene, oppure documentazione non allineata al codice.
---
## Audit del 2026-07-26 (B-01 … B-24)
Primo audit completo del codice (commit di partenza `d4e0974`, 79 test verdi,
nessuno dei quali copriva questi casi). Le correzioni sono raggruppate per
tema in otto commit, fra `cc88763` e `dc4d576`, e il loro esito è registrato
in `845ba98`. La suite passò da 79 a 139 test.
La causa comune dei quattro difetti critici principali (B-01 … B-04) era che
**il codice considerava un invio come definitivo e la connessione come
infallibile**: non esisteva alcuna riconciliazione fra database e catena.
| B-nn | Difetto | Gravità | Commit | Test di regressione | Area |
|---|---|---|---|---|---|
| B-01 | Una connessione Electrum caduta bloccava per sempre l'intero server: nessuna riconnessione, nessun timeout sulle richieste, nessun keepalive | Critica | `7c4e998` Survive a dropped Electrum connection, and fall back to other servers | `test_electrum_client.py::test_request_times_out_instead_of_hanging_forever`, `::test_wait_closed_resolves_when_the_read_loop_dies`; `test_electrum_listener.py::test_rotates_to_the_next_server_after_a_failed_session` | ELC |
| B-02 | Un RBF su una scommessa lasciava `RoundParticipant.bet_txid` sul vecchio txid, e il round restava in `closing` per sempre | Critica | `d528c5b` Let the system recover from a broadcast that never confirms | `test_confirmation.py::test_bet_confirms_after_an_rbf_bump_changed_the_txid`; `test_broadcast.py::test_bump_fee_retargets_every_stored_txid` | TX, BET |
| B-03 | Un solo txid irrisolvibile interrompeva il rilevamento delle conferme per tutte le altre transazioni | Critica | `d528c5b` | `test_confirmation.py::test_one_unresolvable_candidate_does_not_block_the_others` | TX |
| B-04 | Nessuna riconciliazione: una transazione scartata dalla rete congelava per sempre le monete spese e i fondi dell'utente | Critica | `cc88763` Make "one active round" a DB invariant and record why a tx failed; `d528c5b` | `test_reconcile.py` | TX |
| B-05 | `fee_address` e parametri numerici della configurazione non validati: un valore errato bloccava il pagamento o mandava la commissione a uno script non spendibile | Critica | `daf66fd` Fix the round-open race, the advertised jackpot, and payout error handling; `85dce22` Validate admin config and registration input, and log config changes | `test_admin.py::test_config_rejects_unusable_values` | API, RND |
| B-06 | Venivano create uscite di resto sotto la soglia di polvere, rendendo la transazione non inoltrabile | Alta | `b4d7038` Leave dust-sized change to the fee instead of creating it | `test_psbt_builder.py::test_a_below_dust_change_output_is_never_created` | BET, WDR |
| B-07 | Un invio rifiutato dalla rete arrivava al client come HTTP 500, fuori dal contratto d'errore strutturato | Alta | `d528c5b` | `test_bets.py::test_failed_broadcast_reports_the_broadcast_failed_code`; `test_withdrawals.py::test_failed_broadcast_marks_the_withdrawal_failed_and_frees_the_coins` | BET, WDR, API |
| B-08 | La scommessa veniva inviata prima di essere salvata: un errore al commit perdeva il denaro senza lasciare traccia | Alta | `d528c5b` | `test_bets.py::test_bet_is_persisted_before_it_is_broadcast`, `::test_failed_broadcast_leaves_nothing_behind` | BET, TX |
| B-09 | Una corsa permetteva due round `open` contemporanei, che bloccavano per sempre i round successivi | Alta | `cc88763`; `daf66fd` | `test_rounds_service.py::test_losing_the_open_race_reuses_the_winning_round`, `::test_the_database_refuses_a_second_active_round` | RND, DAT |
| B-10 | `PUT /admin/config` non scriveva nulla nel registro di audit | Alta | `85dce22` | `test_admin.py::test_config_update_is_audit_logged`, `::test_pause_cannot_be_toggled_through_the_config_endpoint` | AUD |
| B-11 | Il montepremi mostrato non era l'importo che il vincitore avrebbe ricevuto | Alta | `daf66fd` | `test_rounds_route.py::test_jackpot_comes_from_the_participants_actual_bets` | RND, API |
| B-12 | La registrazione non validava né username né password, a differenza del cambio password | Alta | `85dce22`; `dc4d576` Format amounts, guard the loading state, and translate the new errors | `test_users.py::test_register_rejects_weak_credentials` | REG, SEC |
| B-13 | `verify_password` trasformava un hash salvato malformato in un 500 invece che in un 401 | Media | `85dce22` | `test_security.py::test_verify_password_returns_false_for_an_unparseable_hash` | SEC |
| B-14 | Token admin confrontato con `!=` invece che a tempo costante | Media | `85dce22` | coperto dai test di autenticazione admin esistenti (`test_admin.py::test_admin_rejects_wrong_token`); nessun marcatore B-14 nel codice | SEC |
| B-15 | `JWT_SECRET` o `XPRV_ENCRYPTION_KEY` vuoti non venivano rifiutati all'avvio | Media | `25f4a1c` Refuse to start half-configured, and keep failures machine-readable | `test_config.py` | SEC |
| B-16 | `GET /guida` rispondeva 500 in Docker perché `docs/` non era copiata nell'immagine | Media | `25f4a1c` (crash eliminato, 404 `guide_unavailable`); superato da `447bbba`, che serve un segnaposto statico `app/static/guida.html` | *manuale* (dipende dal layout dell'immagine); nessun marcatore B-16 nel codice | ARC, OPS |
| B-17 | La ricerca dell'uscita di resto nell'RBF poteva ridurre l'uscita del destinatario invece del resto (prelievo verso il proprio indirizzo) | Media | `d528c5b` | `test_withdrawals.py::test_withdrawal_to_own_address_is_rejected` | WDR, TX |
| B-18 | Sessione del database tenuta aperta durante le chiamate di rete del pagamento | Media | `daf66fd` | coperto dai test dello scheduler esistenti (`test_scheduler.py`) | RND, TX |
| B-19 | `tip_height` assegnato senza controllo di monotonia (reorg o cambio server lo facevano regredire) | Media | `7c4e998` | `test_electrum_listener.py::test_tip_never_moves_backwards` | ELC |
| B-20 | `PendingTransaction.replaced_by_txid` mai scritto: colonna morta mostrata in `/admin` | Bassa | `d528c5b` | `test_broadcast.py::test_bump_fee_retargets_every_stored_txid` | TX, DAT |
| B-21 | Variabile locale inutilizzata e accesso ad attributi di oggetti ORM staccati dalla sessione nel poller delle conferme | Bassa | `d528c5b` | coperto da `test_confirmation.py` | TX |
| B-22 | Importi mostrati con una divisione in virgola mobile: artefatti visibili agli utenti | Bassa | `dc4d576` | *manuale* (resa nel browser) | ARC |
| B-23 | Due `withLoading` concorrenti sullo stesso pulsante potevano lasciarlo bloccato sull'etichetta di caricamento | Bassa | `dc4d576` | *manuale* (interazione nel browser) | ARC |
| B-24 | Il gestore globale delle eccezioni rispondeva con un `detail` stringa invece che strutturato | Bassa | `25f4a1c` | `test_rounds_route.py::test_unhandled_errors_use_the_structured_detail_shape` | API |
Note:
- **B-09** fu corretto diversamente dal piano: invece di rendere lo scheduler
l'unico a poter aprire un round, entrambi i chiamanti restano e il conflitto
sull'indice unico viene recuperato con un numero limitato di tentativi.
- **B-15** fu corretto con una validazione all'avvio (`validate_runtime_secrets`
chiamata dal lifespan) invece che con un validatore Pydantic, per non
rendere ogni import e l'intera suite di test dipendenti da un `.env`.
- **B-16** era stato dichiarato «parzialmente corretto per scelta»: la copia di
`docs/` nell'immagine fu scritta e poi ritirata su richiesta del
proprietario. Oggi `/guida` serve un segnaposto (vedi
[decisioni-e-limiti.md](decisioni-e-limiti.md)).
---
## Audit del 2026-07-27 (B-25 … B-49)
Secondo audit completo: 25 difetti (4 critici, 6 alti, 7 medi, 8 bassi), con
139 test verdi al momento dell'audit. Corretti nel ramo `audit-2026-07-27`,
unito con `5cfe2d6`; ognuno ha il proprio commit. La suite passò da 139 a 253
test.
L'osservazione finale di quell'audit resta valida: il codice era rigoroso sui
guasti già capitati e silenzioso su quelli mai visti.
| B-nn | Difetto | Gravità | Commit | Test di regressione | Area |
|---|---|---|---|---|---|
| B-25 | Il pagamento non aveva la scrittura in due fasi (salvare prima, inviare poi) che avevano scommesse e prelievi | Critica | `f13f685` Persist the payout before broadcasting it | `test_scheduler.py::test_trigger_payout_persists_before_broadcasting`, `::test_trigger_payout_broadcast_failure_leaves_a_recoverable_row` | RND, TX |
| B-26 | Un errore transitorio al momento del pagamento, o un riavvio, lasciava il round in `paying_out` per sempre | Critica | `50a43ae` Retry a stuck payout automatically, and log every failure | `test_scheduler.py::test_tick_retries_a_stuck_paying_out_round_with_no_recent_failure`, `::test_trigger_payout_logs_a_failure_when_not_connected` | RND |
| B-27 | Ogni RBF azzerava l'orologio di abbandono del riconciliatore, che quindi non scattava mai | Critica | `933760e` Decouple the RBF abandon clock from the bump clock | `test_reconcile.py::test_abandons_a_repeatedly_bumped_tx_despite_a_recent_last_broadcast`; `test_broadcast.py::test_should_bump_measures_from_last_broadcast_not_first` | TX |
| B-28 | Un server Electrum ostile (o un attacco man-in-the-middle) poteva scegliere da solo il vincitore del round | Critica | `0ce0562` Validate Electrum headers and corroborate the draw's block | `test_electrum_listener.py::test_apply_header_rejects_one_that_fails_its_own_pow_target`; `test_scheduler.py::test_wait_for_next_block_retries_after_a_failed_corroboration`; `test_draw.py::test_header_meets_its_own_target_accepts_a_real_mined_header` | ELC, RND |
| B-29 | Una moneta assente da un solo `listunspent` veniva segnata come spesa all'esterno subito e irreversibilmente | Alta | `e8fdea0` Corroborate an external spend before marking a UTXO gone | `test_electrum_listener.py::test_refresh_user_does_not_mark_when_corroboration_fails`; `test_deposits.py::test_find_utxos_missing_from_skips_a_totally_empty_response` | DEP, ELC |
| B-30 | Nessuna riconciliazione dei depositi: una sottoscrizione persa significava depositi mai accreditati | Alta | `63df38d` Add a periodic deposit reconciler, and stop losing subscribe tasks | `test_deposit_reconcile.py`; `test_electrum_listener.py::test_address_for_new_user_retains_and_logs_a_failed_subscribe_task` | DEP |
| B-31 | Alla riconnessione la risottoscrizione di tutti gli utenti era seriale e bloccava l'altezza della catena, e con essa un'estrazione in corso | Alta | `12df041` Resubscribe concurrently and in the background on reconnect | `test_electrum_listener.py::test_subscribe_all_users_bounds_concurrency`, `::test_run_once_keeps_consuming_headers_while_resubscribing` | ELC |
| B-32 | `bump_fee` poteva ritentare per sempre sotto il minimo di commissione imposto da BIP125, senza tetto al fee rate | Alta | `17c557b` Meet BIP125's relay minimum on every RBF bump, and cap the fee rate | `test_broadcast.py::test_bump_fee_meets_bip125_minimum_when_old_fee_already_exceeds_target`, `::test_bump_fee_refuses_once_at_the_max_fee_rate` | TX |
| B-33 | Nessuna protezione dai tentativi ripetuti sul login di un portafoglio custodiale | Alta | `16802ca` Throttle login and registration with exponential backoff | `test_auth.py::test_login_locks_out_after_repeated_failures`, `::test_login_failures_against_one_account_do_not_lock_out_another` | SEC |
| B-34 | Cambio password e reset admin non invalidavano le sessioni già emesse | Alta | `739fc9f` Invalidate existing sessions on password change/reset | `test_users.py::test_change_password_invalidates_the_old_token_but_not_the_new_one`; `test_admin.py::test_admin_resets_user_password`; `test_security.py::test_jwt_decode_defaults_token_version_for_tokens_issued_before_it_existed` | SEC |
| B-35 | Ogni orario dell'API era senza fuso, e il frontend lo interpretava come ora locale | Media | `bb8b712` Stamp UTC on naive API timestamps before serializing | `test_api_timeutil.py::test_naive_datetime_is_stamped_utc`; `test_users.py::test_me_created_at_is_utc_stamped` | API |
| B-36 | L'attesa del blocco per l'estrazione non aveva né timeout né visibilità | Media | `7fa26df` Make a stalled draw wait observable | `test_scheduler.py::test_wait_for_next_block_logs_a_stall_audit_entry_past_the_threshold`; `test_rounds_route.py::test_draw_waiting_since_is_exposed_only_while_drawing` | RND, AUD |
| B-37 | Saldo mostrato e saldo spendibile divergevano, e l'errore «saldo insufficiente» non lo spiegava | Media | `0b44fe6` Distinguish a pending-only balance from a truly insufficient one | `test_withdrawals.py::test_withdrawal_distinguishes_pending_from_truly_insufficient_balance` | WDR, DEP |
| B-38 | Il tetto globale di 500 abbonati SSE era un modo gratuito per negare il canale in tempo reale a tutti | Media | `702b37b` Cap SSE subscribers per client IP instead of only globally | `test_round_events.py::test_subscribe_evicts_the_same_ips_oldest_connection_past_its_cap` | SEC, ARC |
| B-39 | SQLite senza WAL né `busy_timeout`, con più attività che scrivono in parallelo | Media | `97545ad` Run SQLite in WAL mode with a busy_timeout | `test_db_base.py` | ARC, DAT |
| B-40 | `bump_fee` teneva aperta una sessione del database durante N chiamate di rete, e calcolava gli importi da un valore in virgola mobile | Media | `08c566d` Restructure bump_fee into three phases, drop float fee math | `test_broadcast.py::test_bump_fee_holds_no_session_open_during_network_calls` | TX |
| B-41 | Conferme e riconciliazione dipendevano da `blockchain.transaction.get` in modalità verbose, rifiutata da molti server, e l'abbandono si basava sul confronto testuale del messaggio d'errore | Media | `4124dc0` Check confirmation/existence via scripthash history, not verbose replies | `test_confirmation.py::test_one_unresolvable_candidate_does_not_block_the_others`; `test_reconcile.py`; `test_pending_address.py` | TX, ELC |
| B-42 | `/docs`, ReDoc e lo schema OpenAPI esposti in produzione, endpoint admin compresi | Bassa | `22e3cfb` Disable Swagger/ReDoc/OpenAPI JSON by default | `test_docs_disabled.py` | SEC |
| B-43 | Nessun header di sicurezza HTTP (CSP, HSTS, `X-Frame-Options`…) | Bassa | `d60da11` Add baseline HTTP security headers in Caddy | `test_caddyfile_security_headers.py` | SEC |
| B-44 | README e `docs/running-the-server.md` documentavano un `uvicorn --reload` diretto, contro la regola «solo Docker» | Bassa | `a574db0` Align README and running-the-server.md with the Docker-only policy | `test_docs_no_bare_uvicorn.py` | OPS |
| B-45 | Endpoint admin di elenco senza limiti validati né paginazione | Bassa | `6045c89` Bound admin list endpoint limits, add status filter to pending-transactions | `test_admin.py::test_admin_list_endpoints_reject_out_of_range_limit`, `::test_admin_pending_transactions_status_filter` | API |
| B-46 | `secrets.compare_digest` su una stringa con caratteri non ASCII sollevava `TypeError` (500 invece di 403) | Bassa | `31bc9a3` Compare admin token as UTF-8 bytes to avoid TypeError on non-ASCII input | `test_admin.py::test_admin_rejects_non_ascii_token_with_403_not_500` | SEC |
| B-47 | Colonne `String` senza lunghezza per testi lunghi (`raw_tx_hex`, `payload_json`) | Bassa | `6a90136` Widen raw_tx_hex and payload_json from String to Text | `test_models_text_columns.py` | DAT |
| B-48 | Nessun limite al numero di monete in ingresso: un indirizzo frammentato erodeva la propria scommessa o il proprio prelievo in commissioni | Bassa | `4c80c1c` Cap the number of inputs a transaction may spend | `test_psbt_builder.py::test_select_utxos_never_exceeds_the_input_cap`; `test_bets.py::test_place_bet_reports_a_too_fragmented_balance_distinctly` | BET, WDR |
| B-49 | I percorsi di annullamento di scommessa e prelievo non pubblicavano un aggiornamento SSE | Bassa | `e7f844b` Publish an SSE update from the bet/withdrawal rollback paths | `test_bets.py::test_failed_broadcast_publishes_an_sse_update`; `test_withdrawals.py::test_failed_broadcast_publishes_an_sse_update` | BET, WDR, ARC |
---
## Fuori audit (B-50, B-51)
Trovati il 2026-07-31 osservando il sistema in funzione, fra il secondo e il
terzo audit; non sono mai comparsi in un `BUGS.md` e la gravità non è stata
registrata. Il terzo audit riparte «dall'ultimo difetto corretto, B-51».
| B-nn | Difetto | Gravità | Commit | Test di regressione | Area |
|---|---|---|---|---|---|
| B-50 | Il banner di vincita appariva prima che `winner_amount_sats` fosse noto, mostrando «Hai vinto! +— PLM» | — | `9207bbc` Don't reveal the win banner before winner_amount_sats is known | *manuale* (solo `app/static/app.js`); nessun marcatore B-50 nel codice | RND, ARC |
| B-51 | Il saldo in attesa contava due volte il resto di una scommessa o di un prelievo già accreditato dal listener | — | `fe909be` Don't double-count a bet/withdrawal's own change in pending balance | `test_balance.py::test_pending_balance_does_not_double_count_change_already_credited` (senza marcatore B-51) | DEP |
---
## Audit del 2026-08-03 (B-52 … B-72)
Terzo audit completo (264 test verdi al momento dell'audit), aperto con
`99d7a1e` nel ramo `audit-2026-08-03`, poi confluito in `main`. Ogni difetto è
stato rimosso da `BUGS.md` nel suo stesso commit di correzione. Due voci
restano aperte.
L'audit ricorda anche un problema **non numerato**, perché già elencato fra i
limiti accettati: lo stato `drawing` non riprende dopo un riavvio (vedi
[decisioni-e-limiti.md](decisioni-e-limiti.md)).
| B-nn | Difetto | Gravità | Commit | Test di regressione | Area |
|---|---|---|---|---|---|
| B-52 | Un round con più di ~50 partecipanti bloccava la piattaforma per sempre: il pagamento usava il limite di 50 monete in ingresso pensato per le transazioni utente | Critica | `025754c` Cap participants per round and give the payout its own input limit | `test_bets.py::test_place_bet_rejects_the_bet_past_the_participant_cap`; `test_payout_builder.py::test_payout_spends_more_utxos_than_a_user_transaction_may`; `test_scheduler.py::test_trigger_payout_pays_a_round_with_more_participants_than_max_tx_inputs` | RND, BET |
| B-53 | Una scommessa poteva finire nel montepremi ed essere comunque esclusa dall'estrazione | Critica | `64f6229` Close the window where a bet pays into a round it was left out of | `test_bets.py::test_place_bet_refuses_when_the_round_closed_between_the_check_and_the_commit`, `::test_place_bet_rechecks_the_deadline_after_building_the_transaction`; `test_scheduler.py::test_close_and_draw_waits_when_a_bet_appears_after_the_tick_check` | BET, RND |
| B-54 | `X-Forwarded-For` accettato alla cieca: ogni controllo basato sull'IP era aggirabile | Alta | `907e32e` Make X-Forwarded-For trustworthy instead of attacker-controlled | `test_client_ip.py::test_client_ip_takes_the_last_hop_of_a_forwarded_chain`, `::test_client_ip_ignores_a_client_supplied_prefix`; `test_caddyfile_security_headers.py::test_forwarded_for_is_overwritten_with_the_real_peer` | SEC |
| B-55 | L'hashing Argon2 girava sull'event loop, bloccando l'intero processo a ogni login | Alta | `9c7befe` Hash and verify passwords off the event loop | `test_security.py::test_hash_password_async_keeps_the_event_loop_free`, `::test_verify_password_async_keeps_the_event_loop_free` | SEC |
| B-56 | Il dizionario dei contatori del limitatore di tentativi non veniva mai sfoltito | Alta | `ab65728` Bound the rate limiter's bucket dict | `test_rate_limit.py::test_the_dict_is_capped_even_within_one_sweep_interval`, `::test_spent_buckets_are_swept_on_the_next_failure` | SEC |
| B-57 | Username confrontati distinguendo maiuscole e minuscole, mentre la chiave del limitatore no | Alta | `5772135` Make usernames one case-insensitive namespace | `test_auth.py::test_registration_refuses_a_username_differing_only_by_case`, `::test_login_accepts_the_username_in_any_case`, `::test_the_database_itself_rejects_a_case_variant` | REG, SEC |
| B-58 | Il limite sulle registrazioni contava i successi come fallimenti ed era solo per IP | Alta | `0aac73e` Bound registrations with a per-IP quota instead of failure backoff | `test_auth.py::test_registration_is_quota_limited_per_ip`, `::test_failed_registrations_do_not_consume_the_quota` | SEC, REG |
| B-59 | L'accredito dei depositi non era corroborato dagli altri server, a differenza del rilevamento delle spese esterne | Alta | `6246b13` Corroborate deposit credits, not just external spends | `test_electrum_listener.py::test_refresh_user_does_not_credit_a_utxo_only_our_own_server_reports`, `::test_refresh_user_credits_once_the_others_corroborate` | DEP, ELC |
| B-60 | `POST /admin/bug-reports/{id}/status` non scriveva nulla nel registro di audit | Alta | `77e07e8` Audit-log bug report status changes | `test_bug_reports.py::test_status_change_is_audit_logged`, `::test_setting_the_status_it_already_has_logs_nothing` | AUD |
| B-61 | Le modifiche alla configurazione si applicavano retroattivamente al round in corso | Media | `37cc5ee` Snapshot a round's timing when it opens | `test_scheduler.py::test_tick_ignores_a_config_duration_edited_mid_round`; `test_rounds_service.py::test_a_new_round_snapshots_the_current_config_timing` | RND |
| B-62 | «Preleva tutto» produceva sempre una transazione senza resto, quindi impossibile da accelerare con RBF | Media | `8dd913e` Always keep a change output, so every tx stays fee-bumpable | `test_psbt_builder.py::test_build_signed_transaction_refuses_an_amount_that_would_leave_no_change`; `test_withdrawals.py::test_full_balance_withdrawal_keeps_a_bumpable_change_output` | TX, WDR, BET |
| B-63 | Subito dopo la connessione, con `tip_height == 0`, un'estrazione poteva usare un blocco precedente alla chiusura | Media | `8a0ebec` Never let a draw be seeded by a block that predates the close | `test_scheduler.py::test_wait_for_next_block_never_seeds_the_draw_from_a_pre_close_block`; `test_electrum_listener.py::test_run_once_publishes_the_client_only_once_the_tip_is_known` | RND, ELC |
| B-64 | `_apply_header` accettava un header alla stessa altezza senza controllo di concatenazione | Media | `c0314e2` Never swap the tip's hash sideways, and never split it from its height | `test_electrum_listener.py::test_apply_header_ignores_a_competing_header_at_the_current_tip_height`, `::test_apply_header_ignores_one_carrying_no_hex` | ELC |
| B-65 | `/rounds/current` contava i partecipanti non confermati, che estrazione e pagamento invece escludono | Media | `c4b2dc3` Advertise the jackpot that will actually be paid | `test_rounds_route.py::test_advertised_jackpot_covers_only_the_bets_that_will_be_paid` | RND, API |
| B-66 | Nulla impediva di aprire round senza `fee_address` configurato, rendendoli impagabili | Media | `23d5879` Refuse to open a round that could not pay its winner | `test_rounds_service.py::test_withholds_new_round_while_no_fee_address_is_configured`, `::test_a_round_in_progress_survives_the_fee_address_being_cleared`; `test_rounds_route.py::test_lottery_configured_flags_a_missing_fee_address` | RND |
| B-67 | `/qr/{address}` non autenticato, sincrono e validato solo nella forma | Media | `5f6abe5` Validate and bound the QR endpoint | `test_qr.py` | API, SEC |
| B-68 | CLAUDE.md e README descrivevano uno stato che il codice aveva superato | Bassa | `162ceed` Describe the code the docs actually ship with | `test_docs_current.py` | ARC |
| B-69 | Commenti nel codice non più veri | Bassa | `666cb1a` Retire in-code comments that outlived what they described | `test_code_comments.py` | ARC |
| B-70 | Il diagramma diceva che prelievo e scommessa in corso non potevano coesistere, ma il codice non lo impone (e non deve) | Bassa | `526a649` Say what bets and withdrawals actually exclude | `test_withdrawals.py::test_withdrawal_is_allowed_while_a_bet_is_still_unconfirmed`, `::test_the_docs_no_longer_claim_bets_and_withdrawals_are_exclusive` | WDR |
| B-71 | `.env` punta `MASTER_KEY_PATH` a una seconda copia della chiave master (e `DATABASE_URL` a un secondo database) invece che ai file in `./data/` letti dal container | Bassa | **aperto** | — | OPS, SEC |
| B-72 | `docs/setup.md` presenta ancora l'installazione come «in locale o via Docker», contro la regola «solo Docker» | Bassa | **aperto** | — | OPS |
Note:
- `8f3cdcb` e `421fe72` sono commit di sola contabilità di `BUGS.md` (registrano
gli hash delle correzioni di B-53 e B-54), non correzioni.
- Il test di B-70 sulla documentazione legge la sezione «Scommessa e prelievo
insieme» di [scommesse-e-prelievi.md](scommesse-e-prelievi.md): quel titolo e
le frasi che il test cerca vanno mantenuti.
## Stato attuale
- **Corretti:** B-01 … B-70, tranne B-16, che è chiuso nella sostanza (il
crash è eliminato e `/guida` serve un segnaposto) ma lascia la guida vera
come limite accettato.
- **Aperti:** B-71, B-72 (entrambi di gravità bassa, entrambi operativi o di
documentazione).
- **Prossimo numero libero:** `B-73`.
+461
View File
@@ -0,0 +1,461 @@
# Transazioni e riconciliazione
Come ogni movimento di denaro — scommessa, prelievo, pagamento del round —
viene registrato, inviato, accelerato e infine confrontato con la catena.
L'obiettivo è che il sistema si rimetta in ordine da solo dopo un crash o un
problema di rete, senza interventi manuali sul database, e che **nel dubbio
non liberi mai i fondi**: una transazione si annulla solo con una prova che
non è partita, mai per un timeout o per il silenzio di un solo server
(decisione 2 di [piano-correzioni.md](piano-correzioni.md#le-decisioni)).
I requisiti usano il prefisso `TX`, secondo la convenzione di
[processo-di-modifica.md](processo-di-modifica.md). Le colonne delle tabelle
`pending_transactions` e `pending_transaction_txids` sono descritte in
[modello-dati.md](modello-dati.md), gli eventi di audit in
[audit-log.md](audit-log.md), le attività in background e le loro cadenze in
[architettura.md](architettura.md).
## Il principio: prima si scrive, poi si invia
Nessuna transazione viene inviata alla rete senza che il database ne abbia già
traccia. Ogni transazione in uscita ha una riga `PendingTransaction` che
attraversa questi stati (comportamento atteso):
```mermaid
stateDiagram-v2
[*] --> building: transazione firmata,<br/>monete segnate come spese,<br/>salvato PRIMA dell'invio
building --> pending: il server accetta l'invio<br/>(anche "già nota")
building --> building: invio incerto (timeout,<br/>connessione caduta): nulla liberato
building --> [*]: scommessa rifiutata esplicitamente<br/>(riga cancellata, tutto annullato)
building --> failed: prelievo rifiutato esplicitamente<br/>(tutto annullato)
building --> pending: il riconciliatore trova in rete<br/>uno dei suoi txid (dopo 120s)
building --> failed: il riconciliatore ha la prova<br/>che non è partita (dopo 120s)
pending --> pending: nessuna conferma<br/>entro il tempo limite → RBF
pending --> confirmed: prova merkle del quorum<br/>per uno dei suoi txid
pending --> failed: il riconciliatore ha la prova<br/>che non è partita (dopo 6h dal primo invio)
failed --> failed: conferma tardiva entro 14 giorni:<br/>pending_tx_resurrected + pausa
confirmed --> [*]
failed --> [*]: dopo 14 giorni
```
- **[TX-01]** Ogni transazione in uscita ha una riga `PendingTransaction` di
tipo `bet`, `withdrawal` o `payout`, con stato `building`, `pending`,
`confirmed` o `failed`. La riga (stato `building`, con la transazione
firmata completa) viene salvata e committata **prima** dell'invio, nella
stessa transazione del database in cui le monete spese vengono segnate come
tali e si registra l'oggetto collegato (partecipante, prelievo, dati di
pagamento del round).
*Codice:* `app/bets/service.py:place_bet`, `app/withdrawals/service.py:request_withdrawal`, `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
*Test:* `tests/unit/test_bets.py`, `tests/unit/test_scheduler.py`
- **[TX-02]** Il database non viene mai tenuto aperto durante una chiamata di
rete: la scrittura di `building` è committata, poi si invia, poi si aggiorna
(in una nuova sessione per il pagamento). Se il processo muore proprio in
mezzo, resta la prova di cosa stava succedendo, non monete spese in catena
senza alcun record.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout`, `app/tx/broadcast.py:bump_fee` ·
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_broadcast.py`
- **[TX-03]** `broadcast_at` è l'orario in cui la riga è stata scritta, cioè
del **primo** invio, e non viene mai riscritto; `last_broadcast_at` è
quello dell'ultimo invio, ed è l'unico che l'RBF aggiorna.
*Codice:* `app/db/models.py:PendingTransaction`, `app/tx/broadcast.py:bump_fee` ·
*Test:* `tests/unit/test_broadcast.py`
- **[TX-19]** **Tutte le versioni sono registrate.** Ogni txid che una riga
ha avuto, con la sua transazione completa, è una riga di
`pending_transaction_txids` ([modello-dati.md](modello-dati.md) (B-77)): la
prima versione è scritta insieme alla riga `PendingTransaction` ([TX-01]),
ogni sostituzione RBF prima di essere inviata ([TX-12]). Conferma
([TX-06]), riconciliazione ([TX-15]) e sorveglianza delle righe `failed`
([TX-23]) cercano **ogni** txid della riga, non solo `current_txid`. Quando
la versione trovata in catena non è quella corrente, `current_txid` e
`raw_tx_hex` diventano quelli della versione trovata e il txid viene
propagato ovunque sia registrato, come dopo un RBF ([TX-12]).
*Codice:* `app/tx/confirmation.py:poll_once`, `app/tx/reconcile.py:reconcile_once`, `app/tx/broadcast.py:_retarget_txid_references` ·
*Test:* —
*Stato:* da implementare (B-77) · *Oggi:* si conserva solo il txid corrente
(più il precedente in `replaced_by_txid`, che nessuno legge); se conferma
una versione precedente a un RBF non viene riconosciuta.
- **[TX-28]** Ogni transazione del database che sposta denaro — la scrittura
di `building` ([TX-01]), la promozione dopo l'invio, l'annullamento dopo un
rifiuto, le due scritture dell'RBF ([TX-12]), la promozione e l'abbandono
del riconciliatore, la conferma ([TX-07]) — si apre con `BEGIN IMMEDIATE`,
cioè prende il blocco in scrittura di SQLite **prima** delle proprie
letture, così quelle letture non possono cambiare fino al commit. Se il
blocco non si ottiene entro il tempo di attesa di SQLite (5 secondi,
`_SQLITE_BUSY_TIMEOUT_MS`) l'operazione fallisce con `database is locked`
e viene annullata: prima dell'invio non si è mosso nulla; dopo un invio
riuscito le righe restano `building` e vale [TX-20]. La durabilità dei
commit (`synchronous=FULL`) è descritta in
[architettura.md](architettura.md) (B-88).
*Codice:* `app/db/base.py:_register_sqlite_pragmas`, `app/bets/service.py:place_bet`, `app/withdrawals/service.py:request_withdrawal` ·
*Test:* —
*Stato:* da implementare (B-88) · *Oggi:* pysqlite in modalità legacy apre
la transazione solo alla prima scrittura, quindi le letture precedenti non
sono isolate; un'attesa del blocco oltre 5 secondi emerge come
`OperationalError` in un punto qualunque, anche dopo un invio riuscito.
### Invio rifiutato
Un invio può finire in tre modi, e solo uno di essi permette di liberare le
monete:
| Esito | Cosa significa | Cosa si fa |
|---|---|---|
| Accettato | Il server risponde con il txid, oppure rifiuta dicendo che la transazione è già nota | Si promuove la riga ([BET-17](scommesse-e-prelievi.md#cosa-succede), [WDR-12](scommesse-e-prelievi.md#prelievo)) |
| Rifiutato esplicitamente | Il server risponde con un errore JSON-RPC diverso da "già nota" | Si annulla tutto ([TX-04]) |
| Incerto | Timeout, connessione caduta, errore di scrittura sul socket: la transazione può essere partita | Non si libera nulla ([TX-20]) |
- **[TX-04]** Solo un **rifiuto esplicito** — una risposta del server con un
oggetto `error` JSON-RPC — all'invio di una scommessa o di un prelievo
annulla tutto: monete liberate, saldo ripristinato, evento scritto nel
registro di audit (`bet_broadcast_failed`, `withdrawal_broadcast_failed`),
notifica SSE. Per una scommessa partecipante e riga vengono **cancellati**;
per un prelievo prelievo e riga restano, in stato `failed`. L'utente riceve
`broadcast_failed` con codice HTTP **502**, perché è stata la rete a
rifiutare, non la sua richiesta a essere sbagliata. Un rifiuto che dice che
la transazione è **già nota** (messaggi che contengono `already known`,
`already in mempool`, `txn-already-known`, `txn-already-in-mempool` o
`transaction already in block chain`) non è un rifiuto: vale come invio
accettato.
*Codice:* `app/bets/service.py:_release_failed_bet`, `app/withdrawals/service.py:_release_failed_withdrawal`, `app/electrum/client.py:ElectrumClient.broadcast` ·
*Test:* `tests/unit/test_bets.py`, `tests/unit/test_withdrawals.py`
*Stato:* da implementare (B-76) · *Oggi:* qualunque eccezione dell'invio,
compresi il timeout di 15 secondi, la connessione caduta dopo la scrittura
e il "già nota", annulla tutto e risponde 502, anche se la transazione può
essere già in rete.
- **[TX-20]** **Invio incerto.** Se l'invio di una scommessa o di un prelievo
finisce senza una risposta del server (timeout, connessione caduta, errore
di scrittura), o se il commit della promozione successiva a un invio
accettato fallisce ([TX-28]), non si libera nulla: monete spese,
partecipante o prelievo e riga `PendingTransaction` restano `building`, e
sarà il riconciliatore a stabilire se la transazione è partita ([TX-16],
[TX-17]). L'utente riceve HTTP **202** con l'oggetto nello stato
`building` ([BET-23](scommesse-e-prelievi.md#cosa-succede),
[WDR-16](scommesse-e-prelievi.md#prelievo)) e si invia una notifica SSE.
*Codice:* `app/bets/service.py:place_bet`, `app/withdrawals/service.py:request_withdrawal` ·
*Test:* —
*Stato:* da implementare (B-76) · *Oggi:* l'invio incerto è trattato come
un rifiuto ([TX-04]); un commit fallito dopo un invio accettato solleva un
errore 500 lasciando le righe `building`.
- **[TX-21]** **Invio a tutti i server.** Dopo che il server attivo ha
accettato una transazione ([TX-04]) — scommessa, prelievo, pagamento o
sostituzione RBF — la stessa transazione viene inviata anche a ogni altro
server configurato. È un tentativo in più, non una condizione: un errore di
questi invii viene solo registrato nei log, non cambia lo stato della riga
e non ritarda la risposta all'utente.
*Codice:* `app/electrum/listener.py:ElectrumListener`, `app/bets/service.py:place_bet`, `app/withdrawals/service.py:request_withdrawal`, `app/rounds/scheduler.py:RoundScheduler._trigger_payout`, `app/tx/broadcast.py:bump_fee` ·
*Test:* —
*Stato:* da implementare (B-76) · *Oggi:* ogni transazione viene inviata
solo al server attivo.
- **[TX-05]** Se l'invio di un pagamento non è accettato — rifiuto esplicito
o esito incerto — la riga resta `building` e si scrive `payout_failed`
(`broadcast rejected`): è il riconciliatore a decidere, interrogando la
rete, se la transazione è partita o no ([TX-16], [TX-17]). Un rifiuto
"già nota" ([TX-04]) vale come invio accettato: la riga passa a `pending` e
si scrive `payout_sent`.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
*Test:* `tests/unit/test_scheduler.py`
*Stato:* da implementare (B-76) · *Oggi:* anche il "già nota" lascia la
riga `building` con `payout_failed`, finché il riconciliatore non la
promuove.
## Conferma
- **[TX-06]** `ConfirmationPoller` controlla ogni 10 secondi le transazioni
in stato `pending` (non quelle `building`), e salta il giro se non c'è
connessione. Per ciascuna legge la cronologia
(`blockchain.scripthash.get_history`) dell'indirizzo che la spende —
l'indirizzo dell'utente, o l'indirizzo del montepremi del round per un
pagamento — e cerca **ogni** txid della riga ([TX-19]); un txid che vi
compare con altezza maggiore di 0 è il candidato alla conferma, che viene
accettata solo alle condizioni di [TX-22]. La cronologia è letta una volta
per indirizzo a ogni giro; un indirizzo che non si riesce a leggere non
blocca gli altri.
*Codice:* `app/tx/confirmation.py:poll_once`, `app/tx/pending_address.py:own_address_for` ·
*Test:* `tests/unit/test_confirmation.py`
*Stato:* da implementare (B-77, B-80) · *Oggi:* cerca solo `current_txid`,
nella cronologia dell'unico indirizzo del montepremi condiviso da tutti i
round per i pagamenti; un'altezza maggiore di 0 riportata dal solo server
attivo basta a confermare ([TX-22]).
- **[TX-22]** **Conferma verificata.** Un candidato ([TX-06]) è confermato
solo quando il quorum dei server
([connessione-electrum.md](connessione-electrum.md) (B-84)) restituisce per
quel txid una prova merkle valida (`blockchain.transaction.get_merkle`)
contro l'header dell'altezza indicata. L'header è quello già validato dal
listener ([connessione-electrum.md](connessione-electrum.md) (B-74)); se
il listener non lo tiene più, è quello su cui il quorum concorda. Senza
quorum, o con una prova non valida, la riga resta `pending` e si riprova al
giro successivo.
*Codice:* `app/tx/confirmation.py:poll_once`, `app/electrum/listener.py:ElectrumListener._corroborate_majority` ·
*Test:* —
*Stato:* da implementare (B-83) · *Oggi:* basta la parola del server
attivo: un server ostile può dichiarare confermato un pagamento mai
trasmesso.
- **[TX-07]** Alla conferma la riga passa a `confirmed` e, nella stessa
transazione del database, viene chiamato il gestore del suo tipo; poi si
invia una notifica SSE:
| Tipo | Cosa succede alla conferma |
|---|---|
| Scommessa | Il partecipante (se `building` o `broadcast`) diventa `confirmed`, con `confirmed_at`, ed entra nell'estrazione |
| Prelievo | Il prelievo (se `building` o `broadcast`) diventa `confirmed`, con `confirmed_at` |
| Pagamento | Il round (se `paying_out`) passa a `closed`, `closed_at` diventa l'orario della conferma e parte la pausa prima del successivo |
*Codice:* `app/tx/confirmation.py:poll_once`, `app/bets/confirmation.py:_on_bet_confirmed`, `app/withdrawals/confirmation.py:_on_withdrawal_confirmed`, `app/rounds/confirmation.py:_on_payout_confirmed` ·
*Test:* `tests/unit/test_confirmation.py`
- **[TX-08]** I gestori ritrovano l'oggetto a cui la transazione si riferisce
tramite identificativi fissi (round e utente per la scommessa, prelievo,
round per il pagamento), **mai principalmente tramite il txid**, perché il
txid cambia a ogni RBF; il txid serve solo come ripiego per righe prive di
quei collegamenti.
*Codice:* `app/bets/confirmation.py:_on_bet_confirmed`, `app/rounds/confirmation.py:_on_payout_confirmed` ·
*Test:* `tests/unit/test_confirmation.py`
I gestori sono registrati all'avvio importando i moduli `confirmation` di
scommesse, round e prelievi (vedi [architettura.md](architettura.md)).
## RBF: accelerare una transazione lenta
Se una transazione resta senza conferma oltre `rbf_timeout_seconds` (900s
predefiniti), `RbfBumper` la ricostruisce con una commissione più alta e la
reinvia (Replace-By-Fee). Tutte le transazioni della piattaforma segnalano la
sostituibilità fin dal primo invio.
- **[TX-09]** `RbfBumper` controlla ogni 30 secondi le righe in stato
`pending` (salta il giro senza connessione) e accelera quelle il cui
`last_broadcast_at` è più vecchio di `rbf_timeout_seconds`: dopo ogni
accelerazione la transazione ha di nuovo l'intero tempo limite. Un errore
su una riga non ferma le altre.
*Codice:* `app/tx/broadcast.py:RbfBumper._tick`, `app/tx/broadcast.py:should_bump` ·
*Test:* `tests/unit/test_broadcast.py`
- **[TX-10]** La nuova commissione punta a 1 sat/vB in più della tariffa
registrata (`_FEE_RATE_INCREMENT`), senza superare 10.000 sat/vB
(`MAX_FEE_RATE_SAT_VB`); l'aumento assoluto non è mai inferiore alla
dimensione stimata della transazione per 1 sat/vB, il minimo richiesto da
BIP125 per una sostituzione. Una riga già a 10.000 sat/vB non viene più
accelerata. Gli importi delle monete spese sono letti dalle transazioni
precedenti come interi in satoshi.
*Codice:* `app/tx/broadcast.py:bump_fee`, `app/tx/broadcast.py:_prevout_amount` ·
*Test:* `tests/unit/test_broadcast.py`
- **[TX-11]** **Chi paga l'accelerazione.** La sostituzione spende le stesse
monete e riduce del solo aumento un'unica uscita, quella che torna alla
piattaforma o al mittente: il **resto dell'utente** per scommesse e
prelievi, l'**uscita di riserva** verso l'indirizzo di riserva del
montepremi (`m/84'/746'/0'/1/0`) per i pagamenti
([ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#4--pagamento)
(B-79)). Le uscite verso la controparte (montepremi, indirizzo esterno,
vincitore, indirizzo commissioni) non vengono mai toccate. Se dopo la
riduzione quell'uscita scenderebbe sotto `DUST_LIMIT_SATS` (294 sat),
l'uscita viene **eliminata** e tutto il suo valore va in commissione: la
sostituzione non ha più nulla da ridurre ed è quindi **l'ultima**, e la
riga non viene più accelerata. Se l'uscita non esiste, o se nemmeno la sua
eliminazione raggiunge l'aumento minimo di [TX-10], l'accelerazione non è
possibile ([TX-24]). Una transazione che non si può accelerare resta
`pending` finché conferma o finché il riconciliatore ha la prova che non è
partita ([TX-17]): finché almeno un server la tiene in mempool non viene
mai abbandonata.
*Codice:* `app/tx/broadcast.py:bump_fee`, `app/tx/broadcast.py:_find_change_output` ·
*Test:* `tests/unit/test_broadcast.py`
*Stato:* da implementare (B-79, B-87) · *Oggi:* per il pagamento si cerca
un resto verso l'indirizzo del montepremi, che esiste solo se le monete
scelte superano vincitore più commissioni di almeno 294 sat: quando il
montepremi contiene esattamente le scommesse del round il pagamento le
spende tutte per esattamente `pool_amount_sats`, non ha resto e non è
accelerabile; per scommesse e prelievi basta che il resto superi
l'aumento, così un resto di 294 sat diventa 153 sat, sotto la soglia di
dust, e la rete rifiuta la sostituzione a ogni giro.
- **[TX-12]** **Prima si scrive la sostituzione, poi si invia.** La
sostituzione firmata viene registrata come candidata in
`pending_transaction_txids` (txid e transazione completa, [TX-19]) e
committata **prima** dell'invio. Dopo l'invio (accettato o incerto) la riga
viene aggiornata con un aggiornamento condizionato
(`UPDATE … WHERE id = … AND status = 'pending' AND current_txid = <txid
sostituito>`): nuovo txid (`current_txid`), nuova transazione
(`raw_tx_hex`), txid sostituito (`replaced_by_txid`), tariffa
effettivamente pagata, numero di tentativi e `last_broadcast_at`; nella
stessa transazione il nuovo txid viene propagato ovunque sia registrato:
monete spese (`spent_txid`), partecipante (`bet_txid`), prelievo (`txid`),
round (`payout_txid`). Se la sostituzione è rifiutata esplicitamente la
riga non cambia ([TX-24]).
*Codice:* `app/tx/broadcast.py:bump_fee`, `app/tx/broadcast.py:_retarget_txid_references` ·
*Test:* `tests/unit/test_broadcast.py`
*Stato:* da implementare (B-77) · *Oggi:* la sostituzione viene inviata
senza essere registrata, e la riga viene aggiornata solo dopo l'invio, senza
condizioni: un crash o un `database is locked` in mezzo lascia in rete una
transazione che il database non conosce.
- **[TX-13]** L'RBF non tocca una riga che è cambiata sotto di lui. Prima di
costruire la sostituzione, se la riga non esiste più o non è più
`pending` (ad esempio è appena stata confermata), non si fa nulla. Dopo
l'invio, se l'aggiornamento condizionato di [TX-12] non trova la riga
(stato o `current_txid` cambiati nel frattempo: confermata, abbandonata o
già sostituita), è un **conflitto**: la riga non viene sovrascritta, la
candidata resta registrata — la conferma e la riconciliazione la cercano
comunque ([TX-19]) — e il conflitto viene scritto nei log.
*Codice:* `app/tx/broadcast.py:bump_fee` ·
*Test:* `tests/unit/test_broadcast.py`
*Stato:* da implementare (B-77) · *Oggi:* il controllo avviene solo prima
della costruzione; dopo l'invio la riga viene aggiornata senza ricontrollare
né lo stato né `current_txid`, anche se nel frattempo è stata confermata o
abbandonata.
- **[TX-24]** Un'accelerazione impossibile ([TX-11], o la riga già a
`MAX_FEE_RATE_SAT_VB`) o una sostituzione rifiutata esplicitamente dalla
rete scrivono un evento `rbf_bump_failed` ([audit-log.md](audit-log.md)
(B-87)) con la riga, il txid corrente e il motivo; la riga resta `pending`
e il tentativo si ripete al giro successivo in cui è dovuto ([TX-09]).
*Codice:* `app/tx/broadcast.py:RbfBumper._tick` ·
*Test:* —
*Stato:* da implementare (B-87) · *Oggi:* l'errore finisce solo nei log
dell'applicazione, invisibile da `/admin`.
Il resto minimo di scommesse e prelievi è di 294 sat
([BET-14](scommesse-e-prelievi.md#cosa-succede),
[WDR-09](scommesse-e-prelievi.md#prelievo)), ma non basta a una riduzione:
una scommessa con una moneta in ingresso e due uscite misura 141 vB, quindi
l'aumento minimo a 1 sat/vB è di 141 sat e lascerebbe un resto di 153 sat,
sotto la soglia di dust. Con un resto minimo la prima accelerazione elimina il
resto ([TX-11]) ed è anche l'ultima; un resto più grande permette più
accelerazioni prima di arrivare lì. Il pagamento del round, invece, non ha
resto quando il montepremi contiene esattamente le scommesse del round: la
riserva di [TX-11] serve proprio a dargli un'uscita da ridurre.
## Riconciliazione
- **[TX-14]** `PendingTransactionReconciler` gira all'avvio e poi ogni 120
secondi (salta il giro senza connessione), e considera ogni transazione
ancora `building` o `pending` trascorso il suo periodo di tolleranza,
misurato da `broadcast_at` (il primo invio, che l'RBF non sposta): 120s per
`building`, 6 ore per `pending`, così l'RBF ha il tempo di fare i suoi
tentativi. Il periodo di tolleranza stabilisce solo da quando la riga viene
esaminata: l'abbandono richiede comunque una prova ([TX-17]).
*Codice:* `app/tx/reconcile.py:PendingTransactionReconciler.run`, `app/tx/reconcile.py:_is_due` ·
*Test:* `tests/unit/test_reconcile.py`
- **[TX-15]** Il riconciliatore chiede a ogni server del quorum
([connessione-electrum.md](connessione-electrum.md) (B-84)) la cronologia
(`blockchain.scripthash.get_history`) dell'indirizzo che spende la riga, e
cerca **ogni** txid della riga ([TX-19]), in mempool o in un blocco. La
transazione è **presente** se almeno un server conosce almeno uno dei suoi
txid ([TX-16]); è **assente** solo se nessun server del quorum ne conosce
alcuno, e anche in quel caso l'assenza da sola non basta ad abbandonarla
([TX-17]). Un **errore di rete** non porta a nulla: la riga resta com'è
fino al giro successivo.
*Codice:* `app/tx/reconcile.py:reconcile_once`, `app/electrum/listener.py:ElectrumListener._corroborate_majority` ·
*Test:* `tests/unit/test_reconcile.py`
*Stato:* da implementare (B-78) · *Oggi:* si interroga solo il server
attivo e solo per `current_txid`, e un txid assente dalla sua cronologia è
trattato come "sconosciuto alla rete": dopo un riavvio su un server diverso
una riga `building` viene abbandonata dopo 120s anche se la transazione è
nella mempool degli altri nodi (che la tengono fino a 336 ore con le
impostazioni predefinite di Bitcoin Core, contro le 6 ore di tolleranza).
- **[TX-26]** Prima di scrivere un esito, il riconciliatore rilegge la riga
nella propria transazione del database ([TX-28]) e non fa nulla se il suo
stato **o il suo `current_txid`** non sono più quelli che aveva quando ha
interrogato la rete (una conferma o un RBF avvenuti nel frattempo).
*Codice:* `app/tx/reconcile.py:reconcile_once` ·
*Test:* —
*Stato:* da implementare (B-78) · *Oggi:* ricontrolla solo lo stato, quindi
può abbandonare una riga appena sostituita dall'RBF sulla base del txid
precedente.
- **[TX-16]** **Presente in rete**: una riga `building` viene promossa a
`pending` (e partecipante o prelievo da `building` a `broadcast`), con un
evento `pending_tx_recovered` e l'evento che l'invio riuscito avrebbe
scritto: `bet_placed` per una scommessa, `withdrawal_sent` per un
prelievo, `payout_sent` per un pagamento. Se il txid trovato non è quello
corrente vale [TX-19]. Da lì la conferma segue la via normale. Una riga già
`pending` presente in rete non viene toccata.
*Codice:* `app/tx/reconcile.py:_promote` ·
*Test:* `tests/unit/test_reconcile.py`
*Stato:* da implementare (B-96) · *Oggi:* si scrive solo
`pending_tx_recovered`: una scommessa o un pagamento recuperati non hanno
mai `bet_placed` o `payout_sent` (e un prelievo recuperato non ha
`withdrawal_sent`).
- **[TX-17]** **Abbandono solo con prova.** Una riga viene abbandonata solo
se vale una di queste due prove:
1. un suo ingresso risulta **speso in un blocco** da una transazione che
non è nessuna delle sue versioni ([TX-19]), confermato dal quorum
([connessione-electrum.md](connessione-electrum.md) (B-84));
2. nessun server del quorum conosce alcuno dei suoi txid ([TX-15]) **e**
il reinvio della sua versione più recente (`raw_tx_hex`) a tutti i server
viene rifiutato esplicitamente perché gli ingressi mancano o sono già
spesi (`missing-inputs`, `bad-txns-inputs-missingorspent`).
Un rifiuto del reinvio per commissione insufficiente non è una prova: una
riga `pending` resta com'è e la accelera l'RBF ([TX-09]); una riga
`building` passa a `pending` come in [TX-16], così che l'RBF la possa
accelerare. Un reinvio accettato da almeno un server significa che la
transazione è viva: vale [TX-16]. Con la prova, la riga passa a `failed`
con il motivo in `failure_reason`; le monete che risultano ancora impegnate
da *questa* transazione vengono liberate (non quelle già spese da altro);
il partecipante viene rimosso, o il prelievo segnato `failed` senza txid; il
saldo dell'utente viene ricalcolato; si scrive `pending_tx_abandoned` (con
il numero di monete liberate) e si invia una notifica SSE.
*Codice:* `app/tx/reconcile.py:_abandon`, `app/tx/reconcile.py:_release_inputs`, `app/tx/reconcile.py:reconcile_once` ·
*Test:* `tests/unit/test_reconcile.py`
*Stato:* da implementare (B-78) · *Oggi:* basta che la cronologia del
server attivo non contenga `current_txid` (motivo `not found on chain`),
senza reinvio e senza guardare gli ingressi.
- **[TX-23]** **Le righe `failed` restano sorvegliate** per 14 giorni dal
passaggio a `failed` (`failed_at`, [modello-dati.md](modello-dati.md)
(B-78)): a ogni giro il riconciliatore cerca i loro txid come in [TX-15].
Se uno di essi risulta confermato ([TX-22]) — una transazione data per
morta che invece è arrivata in un blocco — si scrive una sola volta
`pending_tx_resurrected` ([audit-log.md](audit-log.md) (B-78)) e la
lotteria viene messa in pausa (`paused_reason = 'tx_resurrected'`) perché
l'operatore rimetta in ordine partecipante, prelievo o pagamento; il
riconciliatore non corregge da solo le righe collegate.
*Codice:* `app/tx/reconcile.py:reconcile_once` ·
*Test:* —
*Stato:* da implementare (B-78) · *Oggi:* una riga `failed` non viene più
guardata: se la transazione conferma dopo l'abbandono, nessuno se ne
accorge.
- **[TX-27]** Il riconciliatore invia una notifica SSE solo per le righe di
cui ha cambiato qualcosa (promozione, abbandono, riallineamento del txid),
non per ogni riga esaminata.
*Codice:* `app/tx/reconcile.py:reconcile_once` ·
*Test:* —
*Stato:* da implementare (B-96) · *Oggi:* pubblica una notifica per ogni
riga che ha interrogato, anche quando non cambia nulla.
- **[TX-25]** Una scommessa in volo esce dall'attesa del round in `closing`
([ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#2--chiusura)) in
due soli modi: confermata ([TX-07]) o abbandonata con prova ([TX-17]). Non
esiste un tempo massimo: finché almeno un server tiene la transazione in
mempool, il round resta in `closing`.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`, `app/tx/reconcile.py:reconcile_once` ·
*Test:* `tests/unit/test_scheduler.py`
## Pagamenti del round: riprovare senza pagare due volte
Il pagamento ha bisogno di più protezioni degli altri tipi, perché è
l'operazione che lo scheduler ritenta da solo. Le regole sono in
[ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#4--pagamento):
ogni tentativo fallito scrive un evento `payout_failed` con il motivo, così
`/admin` mostra **perché** un round è fermo, e i tentativi sono limitati a
uno ogni 60 secondi usando proprio l'ultimo `payout_failed` come orologio
([RND-25](ciclo-di-vita-del-round.md#4--pagamento)); non si costruisce un
pagamento se ne esiste già uno `building` o `pending` per quel round, e le
monete del montepremi già impegnate da un pagamento non risolto sono escluse
dalla selezione ([RND-26](ciclo-di-vita-del-round.md#4--pagamento)). Senza
queste ultime due, un nuovo tentativo potrebbe pagare il vincitore due volte.
- **[TX-18]** Un pagamento abbandonato ([TX-17]) non libera monete utente
(quelle del montepremi non sono registrate): azzera `payout_txid`,
`winner_amount_sats` e `fee_amount_sats` del round, che resta in
`paying_out` senza transazione né importi di un pagamento che non esiste, e
lo scheduler ricostruisce il pagamento al tentativo successivo.
*Codice:* `app/tx/reconcile.py:_abandon`, `app/rounds/scheduler.py:RoundScheduler._retry_payout_if_due` ·
*Test:* — (`tests/unit/test_scheduler.py` verifica i nuovi tentativi di un
round in `paying_out`, non la sequenza abbandono → ricostruzione)
*Stato:* da implementare (B-96) · *Oggi:* azzera solo `payout_txid`;
`winner_amount_sats` e `fee_amount_sats` restano quelli del pagamento
abbandonato.
## Dove guardare
Nel pannello `/admin` (vedi [guida-admin.md](guida-admin.md) e
[operativita.md](operativita.md)):
- **Transazioni pendenti** — tutto ciò che è `building` o `pending`, con
orari di invio e candidati all'RBF;
- **Audit log** — `payout_sent`, `payout_failed`, `pending_tx_recovered`,
`pending_tx_abandoned`, `draw_stalled` e tutti gli altri eventi; con le
correzioni in corso anche `rbf_bump_failed` ([TX-24]) e
`pending_tx_resurrected` ([TX-23]);
- **Round** — stato di ogni round, vincitore e txid del pagamento.
-51
View File
@@ -1,51 +0,0 @@
flowchart LR
subgraph REG["FASE 1 - Registrazione"]
direction TB
A1["L'utente si registra\n(username + password)"] --> A2["Il server genera un indirizzo\ndedicato e permanente per l'utente\n(chiave segreta cifrata,\ncustodita dal server)"]
A2 --> A3["L'indirizzo viene collegato\nal profilo utente\n(sara' sia l'indirizzo di deposito\nche quello che ricevera' vincite\ne prelievi)"]
end
subgraph DEP["FASE 2 - Deposito"]
direction TB
B1["L'utente invia PLM\nal proprio indirizzo dedicato"] --> B2["Il sistema monitora\nl'indirizzo sulla blockchain"]
B2 --> B3{"Transazione\nconfermata?"}
B3 -- "No" --> B2
B3 -- "Si'" --> B4["Saldo dell'utente\naccreditato nel sistema"]
end
subgraph PLAY["FASE 3 - Scommessa"]
direction TB
C1{"L'utente vuole\nscommettere?\n(costo fisso, es. 10 PLM;\nal massimo una scommessa\nattiva alla volta)"}
C1 -- "Si', saldo sufficiente" --> C2["Si prepara la transazione:\ndal suo indirizzo verso\nil conto comune del montepremi\n(con resto che torna a lui)"]
C2 --> C3["Transazione firmata\ne inviata alla rete"]
C3 --> C4{"Confermata?"}
C4 -- "No, troppo tempo" --> C5["Si aumenta la commissione\ne si reinvia"]
C5 --> C3
C4 -- "Si'" --> C6["L'utente e' ufficialmente\npartecipante al round in corso"]
end
subgraph DRAW["FASE 4 - Round ed estrazione"]
direction TB
D0["(dettaglio completo in\nround-lifecycle.mmd)"] -.-> D1["Il round ha un tempo limite\nper accettare scommesse"]
D1 --> D2["Allo scadere, si aspettano\nle scommesse gia' in corso\ne poi il round si chiude"]
D2 --> D3["Si estrae un vincitore\nin modo casuale e verificabile\n(hash del primo blocco\ndopo la chiusura)"]
D3 --> D4["Il montepremi viene diviso:\n70% al vincitore\n30% alla piattaforma"]
D4 --> D5["Pagamento inviato e confermato\nsulla rete\n(stesso schema di riprova\ncon commissione aumentata\nin caso di ritardo)"]
end
subgraph WITHDRAW["FASE 5 - Prelievo"]
direction TB
E1["L'utente richiede un prelievo:\nindirizzo esterno + importo\n(spende solo saldo confermato\ne non ancora impegnato: una scommessa\nin attesa di conferma non lo blocca,\nma le due operazioni non vengono\nmai preparate nello stesso momento)"] --> E2["Si prepara e firma la transazione:\ndal suo indirizzo verso\nl'indirizzo esterno indicato\n(con resto che torna a lui)"]
E2 --> E3["Transazione inviata\nalla rete"]
E3 --> E4{"Confermata?"}
E4 -- "No, troppo tempo" --> E5["Si aumenta la commissione\ne si reinvia"]
E5 --> E3
E4 -- "Si'" --> E6["Saldo dell'utente aggiornato"]
end
A3 --> B1
B4 --> C1
B4 --> E1
C6 --> D1
D5 -.->|"round successivo"| C1
-163
View File
@@ -1,163 +0,0 @@
#!/usr/bin/env bash
# Regenerates professional-looking A4 and A3 landscape PDFs from a Mermaid
# .mmd flowchart: consistent color theme, legible fonts, a title (read from
# the .mmd's own YAML frontmatter) and a footer with the generation date.
#
# Usage:
# ./render-pdf.sh [path/to/file.mmd]
#
# Defaults to round-lifecycle.mmd in this same directory.
# Produces <name>-A4.pdf and <name>-A3.pdf next to the .mmd file.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
MMD_FILE="${1:-$SCRIPT_DIR/round-lifecycle.mmd}"
if [[ ! -f "$MMD_FILE" ]]; then
echo "Errore: file non trovato: $MMD_FILE" >&2
exit 1
fi
OUT_DIR="$(cd "$(dirname "$MMD_FILE")" && pwd)"
BASE="$(basename "$MMD_FILE" .mmd)"
SVG_TMP="$OUT_DIR/.${BASE}.tmp.svg"
CONFIG_TMP="$OUT_DIR/.${BASE}.tmp-config.json"
cleanup() {
rm -f "$SVG_TMP" "$CONFIG_TMP" "$OUT_DIR/.${BASE}.tmp-A4.html" "$OUT_DIR/.${BASE}.tmp-A3.html"
}
trap cleanup EXIT
# Consistent, print-friendly color theme (indigo nodes/edges, warm amber phase
# clusters, generous font size) instead of mermaid's flat default palette.
cat > "$CONFIG_TMP" <<'EOF'
{
"theme": "base",
"themeVariables": {
"fontFamily": "\"Segoe UI\", Helvetica, Arial, sans-serif",
"fontSize": "17px",
"primaryColor": "#c9d6f7",
"primaryBorderColor": "#3949ab",
"primaryTextColor": "#1a1a2e",
"lineColor": "#3949ab",
"secondaryColor": "#fff8e1",
"tertiaryColor": "#ffffff",
"clusterBkg": "#fff8e1",
"clusterBorder": "#c9a227",
"edgeLabelBackground": "#c9d6f7",
"titleColor": "#1a1a2e"
},
"flowchart": {
"curve": "basis",
"padding": 16,
"htmlLabels": true,
"nodeSpacing": 100,
"rankSpacing": 25
}
}
EOF
echo "-> Rendering diagram to SVG..."
npx -y @mermaid-js/mermaid-cli -i "$MMD_FILE" -o "$SVG_TMP" -b white -c "$CONFIG_TMP"
echo "-> Building print-ready A4/A3 PDFs..."
# mermaid-cli pulls in puppeteer as a transitive dependency; reuse that install
# instead of adding a separate one just for this script.
PUPPETEER_DIR="$(dirname "$(find "$HOME/.npm/_npx" -maxdepth 3 -type d -name puppeteer 2>/dev/null | head -n1)")"
if [[ -z "$PUPPETEER_DIR" || ! -d "$PUPPETEER_DIR" ]]; then
echo "Errore: modulo puppeteer non trovato (serve mermaid-cli gia' eseguito almeno una volta)." >&2
exit 1
fi
export NODE_PATH="$PUPPETEER_DIR"
GENERATED_AT="$(date '+%d/%m/%Y %H:%M')"
# Human title for the header banner; falls back to a prettified filename for
# any .mmd this script hasn't been told about explicitly.
case "$BASE" in
round-lifecycle) TITLE="Ciclo di vita di un round" ;;
platform-overview) TITLE="Flusso completo della piattaforma" ;;
*) TITLE="$(echo "$BASE" | tr '-' ' ' | sed 's/\b\(.\)/\u\1/g')" ;;
esac
node -e '
const fs = require("fs");
const path = require("path");
const puppeteer = require("puppeteer");
const outDir = process.argv[1];
const base = process.argv[2];
const svgPath = process.argv[3];
const generatedAt = process.argv[4];
const title = process.argv[5];
const svg = fs.readFileSync(svgPath, "utf-8");
function htmlFor(size) {
return `<!doctype html>
<html><head><meta charset="utf-8">
<style>
html, body { margin:0; padding:0; height:100%; font-family: "Segoe UI", Helvetica, Arial, sans-serif; }
body { display:flex; flex-direction:column; height:100%; box-sizing:border-box; padding:4mm 6mm; }
.header {
flex:0 0 auto;
display:flex;
align-items:baseline;
gap:3mm;
border-bottom:1.5pt solid #3949ab;
padding-bottom:1.5mm;
margin-bottom:2mm;
}
.header .brand { font-size:12pt; font-weight:700; color:#3949ab; }
.header .title { font-size:10pt; font-weight:400; color:#1a1a2e; }
.diagram { flex:1 1 auto; min-height:0; display:flex; align-items:flex-start; justify-content:center; }
.diagram svg { width:100%; height:auto; max-width:100%; max-height:100%; }
.footer {
flex:0 0 auto;
display:flex;
justify-content:space-between;
align-items:center;
border-top:0.5pt solid #c9c9d6;
padding-top:2mm;
margin-top:2mm;
font-size:8pt;
color:#6b6b7a;
}
</style>
</head><body>
<div class="header">
<span class="brand">PLM Lottery</span>
<span class="title">${title}</span>
</div>
<div class="diagram">${svg}</div>
<div class="footer">
<span>Diagramma di flusso</span>
<span>Generato il ${generatedAt} &middot; formato ${size} orizzontale</span>
</div>
</body></html>`;
}
(async () => {
const browser = await puppeteer.launch({ args: ["--no-sandbox"] });
const page = await browser.newPage();
for (const fmt of ["A4", "A3"]) {
const htmlPath = path.join(outDir, `.${base}.tmp-${fmt}.html`);
fs.writeFileSync(htmlPath, htmlFor(fmt));
await page.goto("file://" + htmlPath, { waitUntil: "networkidle0" });
const pdfPath = path.join(outDir, `${base}-${fmt}.pdf`);
await page.pdf({
path: pdfPath,
format: fmt,
landscape: true,
printBackground: true,
margin: { top: "6mm", bottom: "6mm", left: "6mm", right: "6mm" },
});
console.log(" " + pdfPath);
}
await browser.close();
})();
' "$OUT_DIR" "$BASE" "$SVG_TMP" "$GENERATED_AT" "$TITLE"
echo "Fatto."
-50
View File
@@ -1,50 +0,0 @@
flowchart LR
A["Il round precedente\nsi e' chiuso\n(pagamento vincitore confermato)"] --> B{"Lotteria in pausa\nmanutenzione?"}
B -- "Si'" --> B_WAIT["Si attende"]
B_WAIT --> B
B -- "No" --> C["Breve attesa\n'di raffreddamento'\n(cosi' i giocatori vedono\nil risultato precedente)"]
C --> D["Si apre un nuovo round\n(stato: APERTO)\ncon un limite di tempo\nper scommettere"]
subgraph OPEN["FASE 1 - Round aperto (accetta scommesse)"]
direction TB
D --> F["Un giocatore\npiazza una scommessa"]
F --> G{"E' arrivata prima\ndella scadenza\ndel round?"}
G -- "Si'" --> H["Accettata:\ngiocatore aggiunto\nai partecipanti"]
G -- "No, troppo tardi" --> F2["Rifiutata:\nil round non e' piu'\nin tempo per accettarla"]
H --> F
F2 --> F
end
D -.->|"scade il tempo"| I
subgraph CLOSING["FASE 2 - Chiusura"]
direction TB
I["Il round raggiunge la sua scadenza\n(indipendentemente dalle scommesse\ngia' in corso, che restano valide):\nda questo momento nessuna\nnuova scommessa e' accettata"] --> J{"Ci sono scommesse\ngia' inviate ma non\nancora confermate?"}
J -- "Si'" --> J_WAIT["Si attende qualche secondo\ne si ricontrolla"]
J_WAIT --> J
J -- "No, tutte confermate" --> K["Il round si chiude:\nsi fotografa lo stato\nattuale della blockchain"]
end
subgraph DRAWING["FASE 3 - Estrazione vincitore"]
direction TB
K --> L{"C'e' almeno\nun partecipante?"}
L -- "No" --> M["Round concluso\nsenza vincitore"]
L -- "Si'" --> N["Si attende il primo\nnuovo blocco dopo\nla chiusura del round"]
N --> O["L'hash del blocco\nsceglie il vincitore\nin modo casuale e verificabile\n(stessa probabilita' per tutti)"]
end
subgraph PAYING["FASE 4 - Pagamento"]
direction TB
O --> P["Si calcola\nil montepremi totale"]
P --> Q["Si divide:\n70% al vincitore\n30% alla piattaforma"]
Q --> R["Si prepara e firma\nla transazione di pagamento"]
R --> S["La transazione\nviene inviata"]
S --> T{"Confermata\nsulla rete?"}
T -- "No, troppo tempo" --> T2["Si aumenta la\ncommissione e si reinvia"]
T2 --> S
T -- "Si'" --> U["Vincitore registrato\nnel registro di controllo"]
end
U --> V["Round CHIUSO\n(il ciclo ricomincia\ndall'inizio per\nil round successivo)"]
M --> V
+8 -8
View File
@@ -304,7 +304,7 @@ async def test_a_bet_with_a_dust_limit_of_headroom_is_accepted(session_factory):
async def test_withdrawal_is_allowed_while_a_bet_is_still_unconfirmed(session_factory):
"""B-70: the flowchart's WITHDRAW node used to state that a withdrawal cannot
"""B-70: the (since removed) flowchart's WITHDRAW node used to state that a withdrawal cannot
happen together with a bet in progress. It can, and should: the hazard is the two
picking the *same* UTXO, which is already excluded twice over — the per-user lock
(app/tx/locks.py) keeps the two builds from ever being in flight at once, and
@@ -345,13 +345,13 @@ async def test_withdrawal_is_allowed_while_a_bet_is_still_unconfirmed(session_fa
assert pending_kinds == {"bet", "withdrawal"}
def test_the_flowchart_no_longer_claims_bets_and_withdrawals_are_exclusive():
def test_the_docs_no_longer_claim_bets_and_withdrawals_are_exclusive():
from pathlib import Path
diagram = (
Path(__file__).resolve().parents[2] / "flowchart" / "platform-overview.mmd"
doc = (
Path(__file__).resolve().parents[2] / "docs" / "scommesse-e-prelievi.md"
).read_text(encoding="utf-8")
node = [line for line in diagram.splitlines() if line.strip().startswith("E1[")]
assert len(node) == 1
assert "non puo' avvenire insieme" not in node[0]
assert "saldo confermato" in node[0]
section = doc.split("## Scommessa e prelievo insieme", 1)[1]
assert "non puo' avvenire insieme" not in doc
assert "blocco per-utente" in section
assert "anche mentre una scommessa" in section