Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
88221b0dbd | ||
|
|
61efbb0e37 |
No files matched your search
@@ -8,4 +8,3 @@ master.xprv.enc
|
||||
*.egg-info/
|
||||
logs/
|
||||
data/
|
||||
flowchart/*.pdf
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
@@ -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)
|
||||
|
||||
@@ -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
@@ -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
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
@@ -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]) |
|
||||
@@ -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.
|
||||
@@ -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)).
|
||||
@@ -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
@@ -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,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
|
||||
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
@@ -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`
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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`.
|
||||
@@ -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.
|
||||
@@ -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
@@ -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).
|
||||
@@ -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.
|
||||
@@ -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`.
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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} · 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."
|
||||
@@ -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
|
||||
@@ -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
|
||||
Reference in new issue
Block a user