Author SHA1 Message Date
davideandClaude Sonnet 5.5 db24287ea5 Make the draw a commit-reveal at a fixed, confirmed, quorum-agreed height with a public proof (B-73, RND-14 … RND-20, RND-33 … RND-37, DAT-61 … DAT-66, API-25, API-45, AUD-24 … AUD-27, AUD-37, ELC-15, SEC-56, ADR-24, ADR-25)
The seed was the hash of the first block seen after the close, so a miner holding tickets
could withhold blocks until one made them win, the active Electrum server could pick which
real block was used by not announcing another (a failed corroboration even moved the draw to
the next block), and the participant order was the server-only `broadcast_at` with no
tie-break, so nobody could recompute the result.

- Open: every round gets a 32-byte `server_seed`, stored only Fernet-encrypted with the
  master-xprv key (`server_seed_enc`), with its published `server_seed_hash`;
  `draw_confirmations` is copied from round_config. The plaintext column is written only by
  the reveal.
- Entering `drawing` (one transaction, `draw_committed` audit row): participants ordered by
  bet txid, each `draw_position`, `participants_hash` (sha256 of `txid:vout:address\n`
  lines; new `bet_vout`), `draw_height = tip_at_close + 1`. A tip of 0 keeps the round
  `closing` (`draw_baseline_tip_unknown`, once per round). All persisted, so a resumed draw
  reads rather than recomputes (the `_tick` branch itself is B-81).
- `_complete_draw` / `_wait_for_draw_block` replace `_wait_for_next_block`: wait for
  `draw_confirmations` blocks from `draw_height`, then `ElectrumListener.agreed_block_hash`
  asks every server, the active one included, for the header at that exact height (valid
  work, >= 2 other answers, strict majority of all); no agreement means the same height is
  asked again and `draw_header_corroboration_failed` is written once per distinct reported
  hash. `draw_stalled` now counts from the last tip advance, or from when the quorum started
  to fail. Seed = sha256(server_seed || block_hash || participants_hash), index = seed mod n.
- The winner, the seed and the reveal (`server_seed`, `winner_drawn` payload) are written in
  one transaction; a round closing with no participants reveals too. A round opened before
  this change (no commitment) is given a secret as it enters `drawing`.
- `GET /rounds/{id}/proof` (public, 404 `round_not_found`, translated in all 7 languages) and
  the new fields on `GET /rounds/current`; `draw_confirmations` in `/admin/config` and the
  /admin form; `server_seed_hash`/`draw_height` in `/admin/rounds`, never the secret.
- Alembic d3e8b15a7c42 (plain add_column / create_index, expression indexes untouched).
- Docs: the B-73 `*Stato:*`/`*Oggi:*` lines are gone, guides and CLAUDE.md describe the new
  draw. Ambiguities resolved in api.md: the proof's participants also carry `amount_sats`
  (RND-37 lists it); `seed` is decimal in the proof and hex in the audit row, as specified.

Tests changed because the spec changed: ElectrumListener.corroborate_header (asked only the
other servers about the block the active one announced) is replaced by agreed_block_hash and
its quorum tests ported; draw_winner takes the secret and the list fingerprint; the four
_wait_for_next_block scheduler tests are replaced by _wait_for_draw_block ones (fixed height,
confirmations, same-height retry, stall clock). New: test_draw_proof.py recomputes the winner
independently from the public proof, checks the plaintext secret is nowhere in the database,
the API or the log before the reveal, and that a second pass over a `drawing` round yields
the same winner. Mutation-checked: ordering by broadcast_at, an early reveal and asking the
tip instead of the draw height each fail tests.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-14 16:29:09 +02:00
davideandClaude Sonnet 5.5 82d078e2d6 Rotate away from a connected server that stopped following the chain (B-86, ELC-21, ARC-26)
`server.ping` keeps succeeding on a server that is stalled, and nothing compared its tip
with the others', so it stayed the active server for ever.

- The listener records when the last header was accepted (monotonic clock, a module
  attribute so tests can move it).
- After every successful ping, ElectrumListener._check_not_stalled: once the last accepted
  header is older than 360s the other servers are asked for their tip
  (blockchain.headers.subscribe, ELC-14's timeouts); if any reports a higher height than
  ours the session ends with ServerStalledError and run() rotates to the next server. If
  none does the chain is just quiet and the session goes on.

No existing test changed. ELC-29 and /admin/electrum (the connection state and the age of
the last header, B-92) are untouched.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-14 16:01:44 +02:00
davideandClaude Sonnet 5.5 50b68d2957 Follow and record chain reorganisations, pausing on deep ones (B-85, ELC-09, ELC-22, ELC-23, ELC-24, AUD-38, DAT-69)
A reorganisation was neither recorded nor acted upon, and a competing header at the tip's
own height was ignored for as long as the tip stood, leaving the listener on an orphan.

- A header at the height we hold with a different hash is followed through the same
  fork-point search as any other reorg (ELC-09) instead of being ignored; it still has to
  bring valid work and a connected chain.
- ElectrumListener._record_reorg writes `chain_reorg_detected` (depth, fork height, old and
  new tip height and hash) before the window moves, so a failed write ends the session and
  the next server's announcement of the same fork is recorded then. Depth 1 is a
  transaction of its own; depth >= 2 also pauses the lottery with paused_reason 'reorg'
  and writes `lottery_paused` in the same transaction (begin_immediate first).
- Docs: ELC-09/22/23/24, AUD-03/11/38, DAT-30/69, OPS-30, RND-04, ADR-26/52 lose their
  B-85 "da implementare" lines.

Tests changed because the spec changed: test_apply_header_ignores_a_competing_header_at_
the_current_tip_height encoded the B-64 behaviour that ELC-09 now reverses; it is replaced
by test_a_competing_header_at_the_tip_height_is_a_reorg_to_follow and the depth tests.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-14 15:56:21 +02:00
davideandClaude Sonnet 5.5 ca50ef62f3 Require real proof of work in headers and link every advance to the tip (B-74, ELC-11, ELC-12, ELC-22, ELC-23)
A header only had to meet the target it declared for itself, so a fabricated one with
`bits = 0x207fffff` passed half the time, a jump of several blocks was accepted without
being linked to the tip (a fake header at a huge height locked `tip_height` and froze every
draw), and an ordinary one-block reorganisation closed the session on every server.

- draw.py: MAINNET_POW_LIMIT (00000000ffff...ffff); header_meets_its_own_target also
  refuses a claimed target easier than POW_LIMIT.
- ElectrumListener._apply_header is async and takes the active client. A single block must
  chain by prev_hash; a jump downloads the headers in between (blockchain.block.headers,
  at most 2016 per request, ElectrumClient.get_block_headers) and each must carry valid
  work and chain, otherwise HeaderValidationError ends the session.
- The listener keeps the last 10 headers (`_window`), built from the process's first header
  and its 9 predecessors (which must chain into it). A header that does not join the tip is
  walked back to its fork point inside the window and the server's branch is followed
  instead of ending the session; a fork older than the window, or a branch that does not
  end at the announced header, still ends it. The audit row and the pause for deep reorgs
  are B-85; a competing header at the tip's own height is still ignored until then.
- _header_at also serves older heights from the window.

Tests changed because the spec changed: the mainnet powLimit cannot be mined in a test, so
tests/unit/conftest.py swaps in a regtest limit at import time (the new tests put the real
one back); the _apply_header tests are async; the two _run_once tests serve the first
header's 9 predecessors; test_apply_header_skips_linkage_check_across_a_height_gap is
replaced by the jump tests, since that behaviour is exactly what the finding removed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-14 15:45:34 +02:00
davideandClaude Sonnet 5.5 a3c51719bd Confirm transactions by merkle proof and reinstate coins only on a quorum (B-83, TX-06, TX-22, TX-23, ELC-25, ELC-26, DEP-02, DEP-08, AUD-18, ADR-07)
poll_once marked a transaction confirmed on one server's `height > 0`, and
reinstate_reappeared_utxos restored a coin written off as spent outside the platform on
the active server's word alone, so a hostile active server could report a
never-relayed payout as confirmed (winner unpaid, round closed) or put a spent coin
back into a balance.

- electrum/merkle.py: pure merkle-branch verification against a block header.
- ElectrumListener.confirmation_proven(txid, height): the *other* servers are asked for
  blockchain.transaction.get_merkle; a strict majority of at least the quorum minimum
  must return a proof that recomputes to the merkle root of that block's header (block
  height and position checked too). The header is the tip the listener holds, or for an
  older block the one a majority of the quorum agrees on and that meets its own target;
  a height above our tip cannot be proven. Quorum rules are _corroborate_majority's.
- poll_once takes the listener as `network`: the active server's history only nominates
  a candidate (txid, height); the row confirms only when the proof holds, and stays
  pending otherwise. With no network nothing confirms. ConfirmationPoller wires it.
- The reconciler's late-confirmation check of failed rows (B-78) now puts each claimed
  (txid, height) to the same proof instead of counting histories.
- refresh_user splits reinstatement like a credit: find_reinstate_candidates (read-only;
  same outpoint, recorded amount, confirmed) -> corroborate_utxo_reinstatement (same
  quorum as a credit) -> reinstate_reappeared_utxos writes only what was corroborated,
  rechecking the mark under the lock. Nothing is committed in the read phase any more.
- Broadcast fan-out, the third part of the finding, shipped with B-76.

Tests changed because the spec changed: every poll_once call now passes a network that
proves (FakeNetwork) — the confirmation tests are otherwise unchanged; the failed-row
"quorum does not confirm" test now asserts the claim goes to the proof.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-14 15:29:30 +02:00
davideandClaude Sonnet 5.5 a4b160e240 Abandon a transaction only on proof, and keep watching failed rows (B-78, TX-15, TX-17, TX-23, TX-26, ELC-28, DAT-33, DAT-36, DAT-69, DAT-72, AUD-11, AUD-12, AUD-31, AUD-39, API-32)
reconcile_once abandoned a row when the *active* server's history lacked its txid:
after 120s for `building` (which a restart onto a different server makes likely),
after 6h for `pending`, and all at once after a forward clock jump. It re-checked the
status but not the txid, so it raced the bumper, and a `failed` row was never looked at
again.

- The reconciler asks every server (ElectrumListener.get_histories, active + others) for
  the history of the row's address and looks for every txid of the row. Present on any
  server -> promoted (adopting the version found). Absent is only "no server of the
  quorum knows it" and needs the active server plus the quorum minimum of the others to
  have answered; even then nothing is released without proof:
  (a) an input spent in a block by a transaction that is none of the row's versions,
      agreed by a strict majority of a quorum of the other servers (confirmed_spender), or
  (b) a rebroadcast of the latest raw tx to every server (rebroadcast_everywhere)
      refused by all of them, explicitly, for missing/spent inputs.
  Accepted or "already known" by any server means alive; a fee refusal is not proof
  (`building` -> `pending` for the bumper, `pending` untouched); too few answers or
  anything else leaves the row alone. failure_reason names the proof.
- The write re-reads status *and* current_txid under begin_immediate (TX-26).
- pending_transactions.failed_at (set by _abandon and _release_failed_withdrawal) starts
  a 14-day watch: a failed row that a majority of the other servers (at least the quorum
  minimum) list in a block becomes `confirmed`, writes pending_tx_resurrected once and
  pauses the lottery with paused_reason `resurrected_tx`; linked rows are not corrected.
  The confirmation is by quorum of histories for now; merkle proofs come with B-83.
- round_config.paused_reason (migration b7d2e41c9a05, with the failed_at one): `operator`
  from POST /admin/pause (which accepts an optional `note` and never overwrites an
  automatic reason), cleared by resume, which logs the reason it lifted; exposed on
  /admin/config and GET /rounds/current. rounds/pause.py:pause_automatically is the
  system's way in.
- PendingTransactionReconciler takes the listener as `network`; with none it can promote
  but never abandon.

Tests changed because the spec changed: the three reconciler tests that expect an
abandonment (and the one in test_tx_versions) now supply a network that proves the
transaction is gone.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-14 15:07:09 +02:00
davideandClaude Sonnet 5.5 f936d6660c Track every version of a bumped transaction and write the RBF replacement before broadcasting it (B-77, TX-12, TX-13, TX-19, TX-21, DAT-13, DAT-14, DAT-34, DAT-44, DAT-45, DAT-70, DAT-71)
The poller and the reconciler matched current_txid only. If an earlier version of
a bumped transaction confirmed it was never seen, and after 6h the row was abandoned:
a confirmed bet's participant deleted, a sent withdrawal marked failed, a paid payout
rebuilt. bump_fee also broadcast in phase 2 and persisted in phase 3 unconditionally,
so a crash or a `database is locked` in between left a transaction on the network that
the DB did not know, and an abandon or a confirmation in the meantime was overwritten.

- New table pending_transaction_txids (migration a3f5c2d9b7e1; txid unique, index on
  the owning row; existing rows backfilled with current_txid + raw and the txid their
  last bump replaced, raw_hex empty). Written with the row by place_bet,
  request_withdrawal and _trigger_payout; removed with a bet row that a verified
  refusal deletes (DAT-38).
- bump_fee in four phases: read, build and sign, commit the replacement as a candidate
  version, broadcast (verdict of B-76, fanned out when accepted; an explicit refusal
  raises RbfError and leaves the row), then switch the row over with
  `UPDATE ... WHERE status='pending' AND current_txid=<replaced>`. Zero rows matched is
  a logged conflict: nothing is overwritten and the candidate stays recorded. An
  uncertain broadcast adopts the replacement. A retry rebuilds the same candidate
  without tripping the unique txid.
- poll_once and reconcile_once look for every txid of a row. When the version found is
  not the current one, broadcast.adopt_version makes it current (raw tx included) and
  retargets spent_txid, bet_txid, withdrawals.txid and payout_txid as a bump does,
  before the confirmation handler runs. _release_inputs frees inputs claimed by any
  version of the row.
- RbfBumper takes the listener as `network`.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-14 14:46:43 +02:00
davideandClaude Sonnet 5.5 2b6ddb019b Never roll back an ambiguous broadcast as if it had been refused (B-76, TX-04, TX-05, TX-20, TX-21, BET-16, BET-17, BET-23, WDR-11, WDR-12, WDR-16, API-13)
place_bet and request_withdrawal released everything on any exception from the
broadcast, including the 15s timeout and a connection dropped after the write. The
tx may have propagated: a bet's sats landed in the pool with no participant, a
withdrawal left while its row said failed and its coins were spendable again.

- client: ElectrumRpcError (subclass of ElectrumError) is raised only for a reply
  carrying a JSON-RPC `error`; timeouts, drops and write errors stay plain
  ElectrumError.
- tx/outcome.py:broadcast_with_verdict sorts a broadcast into accepted / refused /
  uncertain. A refusal is verified first: ElectrumListener.transaction_known asks
  blockchain.transaction.get of the active server and every other one (10s each) —
  any server returning the tx means accepted; the active server plus
  MIN_QUORUM_RESPONSES others all denying it means refused (ALLOW_NO_QUORUM keeps
  the reduced rule); too few answers is uncertain. "already known" wording is only a
  shortcut that skips the check. With no network to ask, a refusal is uncertain.
- place_bet / request_withdrawal / _trigger_payout use it: only a verified refusal
  releases; uncertain leaves the rows building for the reconciler, publishes SSE and
  POST /bets and POST /withdrawals answer 202 with status building; "already known"
  promotes a payout (payout_sent) like any accepted broadcast.
- An accepted transaction is fanned out to every other server
  (ElectrumListener.fan_out_transaction, best effort, off the caller's path). The RBF
  replacement in bump_fee is left for B-77, which rewrites that function.

Tests changed because the spec changed: the existing "refused broadcast" tests raised
a bare RuntimeError (now an uncertain outcome) and are made explicit refusals
(rpc_error) with a network that denies the tx; direct route calls pass a Response;
FakePayoutListener gains the network surface.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-14 14:22:20 +02:00
davideandClaude Sonnet 5.5 13cb66cc06 Require a real Electrum quorum and allow certificate pinning (B-84, ELC-01, ELC-03, ELC-14, ELC-19, ARC-20, OPS-12)
An empty ELECTRUM_FALLBACK_SERVERS (the .env.example default) silently made every
corroboration pass, and with fallbacks the majority was taken over whoever
answered, so one reachable fallback decided alone. TLS certificates were never
checked.

- _corroborate_majority passes only with at least 2 answers (MIN_QUORUM_RESPONSES)
  and a strict majority of the answers; no other server configured, or fewer than
  2 answering, fails. ALLOW_NO_QUORUM=true keeps the old reduced rule.
- config.validate_quorum_servers, called from the lifespan after parse_endpoints,
  refuses to start with fewer than 2 fallback servers unless ALLOW_NO_QUORUM=true
  (which logs a warning at every start).
- Optional pinning: `host:port[:mode]:pin=<sha256>` per fallback and
  ELECTRUM_CERT_PIN for the primary; ElectrumClient compares the SHA-256 of the
  DER certificate after the TLS handshake and a mismatch fails like an unreachable
  server. A pin on a plaintext entry is a startup error.
- .env.example now ships the four bootstrap servers and documents both new
  variables; docs/setup.md, spec, storico and BUGS.md updated.
- Tests changed because the spec changed: the two "no other servers configured ->
  True" corroboration tests now assert that outcome only under allow_no_quorum.

Note: a dev .env with fewer than 2 fallback servers will now refuse to start.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-14 14:04:35 +02:00
davideandClaude Sonnet 5.5 fd6a91e93d Give every round its own pool address (B-80, RND-35, DAT-60, DAT-11, REG-14, SEC-08, BET-12, RND-22, WDR-14, SEC-43, API-23, API-36)
All bets of all rounds paid one address (m/84'/746'/0'/1/0), so its history
grew forever, other rounds' money and stray coins mixed with a round's own, and
the payout picked from everything it held.

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

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-14 13:52:32 +02:00
davideandClaude Sonnet 5.5 cc63753439 Test that the migration chain keeps the expression indexes (B-97, DAT-75, DAT-56, ARC-62)
batch_alter_table on SQLite rebuilds the table and silently drops
ix_rounds_single_active and ix_users_username_lower, autogenerate never sees them,
and no test ran the migrations (the others build the schema with create_all).

tests/unit/test_migrations.py runs `alembic upgrade head` on an empty file DB in a
subprocess and asserts both indexes exist with their definition (read from
sqlite_master) and that a second active round and a case-variant username are
refused. Verified to fail when a batch_alter_table on rounds is added to the last
migration. The current chain already preserves both indexes, so no migration changes.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-14 12:22:08 +02:00
davideandClaude Sonnet 5.5 daec4749c2 Survive oversized Electrum replies and ignore dust deposits (B-75, ELC-20, DEP-01, DAT-10)
A reply line over asyncio's default 64 KiB StreamReader limit raised out of
_read_loop and closed the only connection; the pool address's get_history passes
that after ~800 transactions, and dust sent to any public address does it on
purpose.

- ElectrumClient opens the stream with a 16 MiB limit and frames lines itself:
  an oversized line is discarded up to its newline, a non-JSON line is dropped,
  and the request whose id is readable in the first/last 256 bytes fails at once;
  the connection stays up either way.
- Coins below DUST_LIMIT_SATS are never offered as credit candidates, never
  credited, and select_utxos never selects them.
- Spec (ELC-20, DEP-01, DAT-10, ARC), storico, BUGS.md and test counts updated.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-14 12:14:12 +02:00
davideandClaude Sonnet 5.5 b424f670c5 Restructure docs: docs-first, SSOT, one ADR per decision
- Add docs/README.md as the index of all documentation.
- Split the 52 DEC entries of decisioni-e-limiti.md into docs/adr/ADR-NN
  files (same numbers), add ADR-53 (audit log), TEMPLATE.md and an ADR index
  with a feature -> ADR table.
- Rename decisioni-e-limiti.md to limiti-noti.md (LIM only) and rewrite all
  DEC-nn references as links to the ADRs.
- Document the docs-first / SSOT / ADR rules in processo-di-modifica.md and
  map the docs in CLAUDE.md and README.md.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-14 12:05:57 +02:00
davideandClaude Sonnet 5.5 7ba8e22bb4 Real SQLite transactions: BEGIN IMMEDIATE and synchronous=FULL (B-88, DAT-74, DAT-52, ARC-07, TX-28, BET-11, DAT-16)
pysqlite's legacy mode emitted BEGIN only at the first DML, so every read
before it ran outside any transaction and a lock wait surfaced as "database is
locked" at an arbitrary later statement; place_bet also mistook that error for
a write-snapshot conflict, which SQLite cannot produce.

- _register_sqlite_pragmas: synchronous=FULL, isolation_level=None and a
  `begin` event that emits BEGIN / BEGIN IMMEDIATE.
- begin_immediate(session): takes the write lock before the first read; called
  first thing in place_bet, request_withdrawal, the scheduler transitions,
  _trigger_payout, the confirmation poller, the reconciler, bump_fee's persist
  phase, deposit crediting / external-spend marking / reinstating, and the
  derivation-index allocation at registration.
- A lock not granted before a broadcast answers service_busy (503, all seven
  languages), nothing built or sent; after a broadcast nothing is undone, the
  rows stay `building` for the reconciler.
- Spec, storico, BUGS.md and CLAUDE.md updated; 37 new tests on a real file DB.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-09-29 16:26:01 +02:00
davideandClaude Opus 5.5 4be58709d1 Complete the target spec for the 2026-09-28 review (B-73..B-98)
Finishes what 88221b0 started: sicurezza.md, audit-log.md and storico-bug.md
now describe the target behaviour too, the operator guides are corrected
against today's code, and api.md gains the missing /health/ready and
/admin/electrum sections plus every new error code in its catalog.

Harmonised names and owners across documents (the `resurrected_tx` pause
reason, the reconciler as the one that watches failed rows, the full
`winner_drawn` payload, a reason for an unanswered pre-payout pool check,
one corroboration-failure row per hash instead of one per tick).

Adds B-98 (coin selection stops at the first covering UTXO and refuses a
payable bet), tightens RND-40 to check both 1 and 400 participants and to
guard PUT /admin/config, and gives a stalled `closing` round a signal
(TX-29, closing_stalled).

Records three decisions confirmed on 2026-09-29: the draw's server_seed is
stored Fernet-encrypted until revealed (SEC-56, DAT-64), the chosen abuse
and key-check thresholds (SEC-49, SEC-54, SEC-55), and a broadcast
rejection is verified against every server before any coin is released,
so matching "already known" text is a shortcut, not a safety condition
(TX-04).

Spec only; no code changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 09:17:52 +02:00
davideandClaude Sonnet 5 88221b0dbd Document the 2026-09-28 specification review and its fixes (B-73..B-97)
Fourth full audit, run against the docs/ specification instead of the code
alone, found logical flaws rooted in PLM's small hashrate (~22 TH/s): a
minable draw, no distinction between "never broadcast" and "unknown if
broadcast", an Electrum client that degrades as the pool address's history
grows, and 1-confirmation deposits on a chain where a reorg is rentable.

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

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

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

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

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

No files matched your search

+20 -5
View File
@@ -3,17 +3,32 @@ ELECTRUM_PORT=50002
ELECTRUM_USE_SSL=true
# Additional Electrum servers to fall back to, comma-separated. Each entry is
# `host:port` (TLS, the normal case) or `host:port:notls`. The listener rotates
# over the primary above plus these, so one unreachable server costs a single
# reconnect attempt instead of an outage — every deposit credit, broadcast and
# `host:port` (TLS, the normal case), `host:port:notls`, or `host:port:pin=<sha256>`
# (TLS, and the server's DER certificate must hash to that SHA-256, in hex). The
# listener rotates over the primary above plus these, so one unreachable server costs
# a single reconnect attempt instead of an outage — every deposit credit, broadcast and
# confirmation goes through this one connection, which makes a single server the
# platform's biggest single point of failure. A typo here fails at startup rather
# than during the outage when the fallback is what you need.
#
# AT LEAST 2 are required (B-84): every decision that moves money is corroborated by
# the *other* servers and needs two independent answers, so with fewer than two
# fallbacks the server refuses to start (override: ALLOW_NO_QUORUM, development only).
# Configure three or more in production, so one being down does not stop the lottery.
#
# These are the mainnet bootstrap servers from the PalladiumWallet repo
# (src/Core/Chain/ChainProfiles.cs, ChainProfiles.Mainnet.BootstrapServers) — the
# same ones the reference wallet falls back to:
# Example: ELECTRUM_FALLBACK_SERVERS=173.212.224.67:50002,144.91.120.225:50002,66.94.115.80:50002,89.117.149.130:50002
ELECTRUM_FALLBACK_SERVERS=
ELECTRUM_FALLBACK_SERVERS=173.212.224.67:50002,144.91.120.225:50002,66.94.115.80:50002,89.117.149.130:50002
# Optional: SHA-256 (hex) of the primary server's DER certificate. A connection that
# presents another certificate fails like an unreachable server. Empty = not pinned.
ELECTRUM_CERT_PIN=
# Development only: start with fewer than 2 fallback servers (corroboration then falls
# back to the weak rule: a single answer decides, or nothing is checked at all).
# NEVER true in production.
ALLOW_NO_QUORUM=false
# Fernet key protecting the master xprv at rest. Generate with:
# python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-1
View File
@@ -8,4 +8,3 @@ master.xprv.enc
*.egg-info/
logs/
data/
flowchart/*.pdf
+194 -1
View File
@@ -1,4 +1,9 @@
# BUGS.md — audit of 2026-08-03
# BUGS.md — open findings
Two audits currently have open entries: 2026-08-03 (B-71, B-72, below) and the
2026-09-28 specification review (B-73 … B-98, 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,191 @@ 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-98)
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/limiti-noti.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-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
round of 1 or of `MAX_PARTICIPANTS_PER_ROUND` participants could not cover winner
fee + reserve + dust commission, and `PUT /admin/config` refuses a bet amount or
fee rate that would fail the same check (spec: RND-40).
### 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-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-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`. A round waiting in `closing` on a bet that never
leaves the mempool gives no signal at all.
Fix: each as described, one regression test per item; for the `closing` wait, a
`closing_stalled` audit row every 1800s past the deadline and `closing_waiting_since`
on `GET /rounds/current` (spec: TX-29).
### B-98 — Coin selection stops at the first covering UTXO, refusing a payable bet
Found while writing the spec on 2026-09-28 (medium). `select_utxos` returns as soon
as the selected total covers the target. When that happens exactly (a 10 PLM coin
for a 10 PLM bet), the change is 0: the bet is refused with
`balance_leaves_no_change` and a withdrawal is reduced by `DUST_LIMIT_SATS`, even
though a second coin would have left a proper change output.
Fix: select until the total covers `target + DUST_LIMIT_SATS` (still largest-first,
still capped at `max_inputs`); only when every allowed coin together cannot reach it
fall back to today's behaviour (refuse the bet, reduce the withdrawal). Spec:
`docs/scommesse-e-prelievi.md` BET-24.
+45 -26
View File
@@ -8,15 +8,31 @@ The user communicates in Italian in chat — reply to them in Italian. Everythin
## Project status
All 10 stages of the original build order are code-complete and unit-tested — 351 tests, all under `tests/unit/` (`tests/integration/` is an empty package). Beyond them: Docker + Caddy deployment, admin dashboard (`/admin`), static test UI (`/`), pending-inclusive balance display, an SSE push channel layered over the original polling, self-service password change + admin password reset, and the reconciliation/corroboration machinery below.
All 10 stages of the original build order are code-complete and unit-tested — 617 tests, all under `tests/unit/` (`tests/integration/` is an empty package). Beyond them: Docker + Caddy deployment, admin dashboard (`/admin`), static test UI (`/`), pending-inclusive balance display, an SSE push channel layered over the original polling, self-service password change + admin password reset, and the reconciliation/corroboration machinery below.
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-98: 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-98 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/README.md) 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).
## Documentation map (docs-first, SSOT, ADR)
**Entry point: [docs/README.md](docs/README.md)** — the index of everything under `docs/`. Three rules, all in [docs/processo-di-modifica.md](docs/processo-di-modifica.md):
1. **Docs-first.** Behaviour changes start in `docs/`, never in the code. Spec + code + test ship in one commit, with the requirement/ADR ID in the test docstring and the commit message.
2. **SSOT.** Every fact has one owner; everything else links to its ID instead of restating it. *Why* → an ADR ([docs/adr/](docs/adr/README.md)); *what* (verifiable rule) → a `PREFIX-NN` requirement in the domain document; *how* → the code; accepted limits → [limiti-noti.md](docs/limiti-noti.md) (`LIM-nn`); found/fixed defects → [storico-bug.md](docs/storico-bug.md) (`B-nn`, open ones in [BUGS.md](BUGS.md)). If two documents disagree, the spec wins and the other one gets fixed. This file included: it summarises, it does not own.
3. **One ADR per feature/decision.** A new feature, or a change of an existing choice, starts with an ADR from [docs/adr/TEMPLATE.md](docs/adr/TEMPLATE.md) (next free `ADR-NN`, never reused or rewritten — a superseded one becomes "Sostituita da ADR-MM"), then its requirements, then the code. Add it to the area index and the feature → ADR table in [docs/adr/README.md](docs/adr/README.md). Before touching a feature, read its ADRs there.
| Need | Go to |
|---|---|
| Why is it built this way / alternatives rejected | [docs/adr/README.md](docs/adr/README.md) (the old `DEC-nn` are now `ADR-nn`, same numbers) |
| What exactly must it do | domain docs listed in [docs/README.md](docs/README.md) (`RND`, `BET`, `WDR`, `DEP`, `REG`, `TX`, `ELC`, `AUD`, `ARC`, `DAT`, `API`, `SEC`, `OPS`) |
| Narrative overview | [docs/come-funziona.md](docs/come-funziona.md) |
| Accepted limits | [docs/limiti-noti.md](docs/limiti-noti.md) |
| Fix order for open B-nn | [docs/piano-correzioni.md](docs/piano-correzioni.md) |
## Commands
@@ -33,7 +49,7 @@ PYTHONPATH=. python scripts/decrypt_master_key.py # ops recovery: decrypt+pr
PYTHONPATH=. python scripts/encrypt_master_key.py # ops bootstrap: import an externally-generated xprv (--overwrite to replace)
PYTHONPATH=. python scripts/electrum_smoke_test.py # manual check: connect, handshake, subscribe to headers, print the tip
python -m pytest # all 351 tests
python -m pytest # all 617 tests
python -m pytest tests/unit/test_hd.py # one file
python -m pytest tests/unit/test_hd.py::test_derivation_is_deterministic # one test
```
@@ -86,6 +102,7 @@ Source of truth: the `PalladiumWallet` repo — [ChainProfiles.cs](../PalladiumW
| Prize split | **70% winner / 30% fees**, rounding remainder to fees | **hardcoded** in `rounds/scheduler.py` — a code change, not an admin edit |
| Round duration / cooldown | 600s / 30s | `RoundConfig`, but **snapshotted onto `Round.duration_seconds`/`cooldown_seconds` when a round opens** (B-61) — an edit applies from the next round, never to the one in progress |
| Draw animation | 20s (cosmetic frontend minimum only) | `RoundConfig` |
| Draw confirmations | 3 blocks on the draw block (`draw_confirmations`, 1–20) | `RoundConfig`, admin-editable, **snapshotted onto `Round.draw_confirmations` at open** (B-73) |
| Fee rate / RBF timeout | 1 sat/vB / 900s | `RoundConfig` |
| Min withdrawal | = current `bet_amount_sats` (no separate field) | `withdrawals/service.py` |
| Min deposit | none | — |
@@ -97,9 +114,9 @@ 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.
**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, with `paused_reason` (B-78, DAT-69): `operator`, or an automatic reason the system wrote itself (`resurrected_tx` so far, `rounds/pause.py`) — an operator pause never overwrites an automatic one, and resume clears whichever it is.
**No `fee_address`, no rounds** (`rounds/service.py:rounds_can_open`, B-66): the payout pays the 30% commission to `fee_address`, which has no column default because an operator must set their own — so until they do, `open_new_round_if_needed` refuses to open a round at all. Otherwise every round took bets, confirmed them and only then discovered it was unpayable, wedging in `paying_out` with money already in the pool and needing manual recovery. Same scope as pausing: a round already in progress still closes, draws and pays out (clearing the address mid-round is exactly the operator slip that must not strand a live round). Surfaced as `lottery_configured` on `GET /rounds/current` — `/` shows a *different* banner from the maintenance one, since "come back later" would be false — and as a warning on `/admin`'s Parametri card, the one screen that can fix it. Anything else that would make a round unpayable belongs in `rounds_can_open` next to it, not discovered at payout time.
@@ -111,12 +128,12 @@ Source of truth: the `PalladiumWallet` repo — [ChainProfiles.cs](../PalladiumW
| `app/api/routes/` | `admin`, `bets`, `withdrawals`, `rounds` (incl. SSE), `users`, `qr`, `bug_reports`; `app/api/errors.py` holds the error contract and `app/api/client_ip.py` the trusted-peer extraction every IP-keyed control uses |
| `app/auth/` | routes (register/login), Argon2 + JWT (`security.py`), `get_current_user`/`get_optional_user`, login/registration throttling (`rate_limit.py`) |
| `app/db/` | `models.py` (all tables + the active-round index), engine/session factories |
| `app/wallet/` | HD derivation + WIF export (`hd.py`), PLM network constants, address/scripthash, balance math, `psbt_builder.py` (build/sign bet, withdrawal, payout; `select_utxos`) |
| `app/wallet/` | HD derivation (users `0/i`, per-round pool `2/<round_id>`, reserve `1/0`) + WIF export (`hd.py`), PLM network constants, address/scripthash, balance math, `psbt_builder.py` (build/sign bet, withdrawal, payout; `select_utxos`) |
| `app/electrum/` | `client.py` (JSON-RPC, endpoint parsing, timeouts), `listener.py` (the one connection: rotation, keepalive, header validation, corroboration, deposit crediting) |
| `app/deposits/` | crediting / external-spend detection / reinstatement (`service.py`), periodic sweep (`reconcile.py`) |
| `app/bets/`, `app/withdrawals/` | build+broadcast services and their confirmation handlers |
| `app/rounds/` | `scheduler.py` (close/draw/payout), `service.py` (open/active-round rules), `draw.py` (header math + winner pick), `config.py`, `events.py` (SSE pub/sub) |
| `app/tx/` | `broadcast.py` (RBF bumper), `confirmation.py` (poller + handler registry), `reconcile.py`, `locks.py` (per-user locks) |
| `app/rounds/` | `scheduler.py` (close/draw/payout), `service.py` (open/active-round rules), `draw.py` (header math, powLimit, commit-reveal seed + winner pick), `config.py`, `events.py` (SSE pub/sub) |
| `app/tx/` | `broadcast.py` (RBF bumper), `outcome.py` (broadcast verdict, B-76), `versions.py` (every txid of a row, B-77), `confirmation.py` (poller + handler registry), `reconcile.py`, `locks.py` (per-user locks) |
| `app/static/` | the two SPAs (`index.html`/`app.js`/`style.css`, `admin.html`/`admin.js`/`admin.css`) + `i18n.js` |
## Background tasks
@@ -138,17 +155,17 @@ Chain access goes through `listener.client`, passed as `lambda: listener.client`
One connection serves everything — deposit credits, broadcasts, confirmations, the tip the draw waits on — so it's both the biggest single point of failure and, with a hostile server on the other end, the biggest integrity risk. Five defences:
- **Rotation.** `ELECTRUM_HOST`/`PORT` is primary, `ELECTRUM_FALLBACK_SERVERS` a comma-separated `host:port[:notls]` list (`client.py:parse_endpoints` rejects malformed entries at startup, not during the outage when the fallback is needed). After any failed or dropped session the next server is tried immediately; the backoff (1s doubling to 30s) only kicks in once every server has had a turn.
- **Rotation.** `ELECTRUM_HOST`/`PORT` is primary, `ELECTRUM_FALLBACK_SERVERS` a comma-separated `host:port[:notls][:pin=<sha256>]` list (`client.py:parse_endpoints` rejects malformed entries at startup, not during the outage when the fallback is needed; `pin=` fixes the server's DER certificate hash, `ELECTRUM_CERT_PIN` does the same for the primary, B-84). The server **refuses to start with fewer than 2 fallbacks** (`config.validate_quorum_servers`, B-84; `ALLOW_NO_QUORUM=true` overrides it, development only). After any failed or dropped session the next server is tried immediately; the backoff (1s doubling to 30s) only kicks in once every server has had a turn.
- **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.
- **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`. A server that keeps answering pings but stopped following the chain is caught too (B-86): at every ping, if no header has been *accepted* for 360s (`_STALL_SECONDS`), `_check_not_stalled` asks the other servers for their tip and ends the session with `ServerStalledError` if any is higher, so `run()` rotates; none higher means a quiet chain and the session goes on. Without it the listener sat on queues nobody would ever fill while `listener.client` still looked alive.
- **Headers are validated, not trusted** (`_apply_header`, async since B-74): the tip never regresses, a header must meet the difficulty target it claims *and* that target must be no easier than `draw.POW_LIMIT` (PLM's powLimit; `tests/unit/conftest.py` swaps in a regtest limit so tests can mine headers, and the tests of the limit itself put `MAINNET_POW_LIMIT` back), and every advance must be linked to the tip: a single block by its `prev_hash`, a jump by downloading the headers in between (`blockchain.block.headers`, ≤2016 per request) from the active server and checking each. 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. The listener keeps the last 10 headers (`_window`, built from the first header plus its 9 predecessors); a header that does not join the tip is a reorg, walked back to its fork point inside the window and followed (`_follow_reorg`), a fork older than the window ends the session. A followed reorg writes `chain_reorg_detected` *before* the window moves (`_record_reorg`, B-85), and a depth of 2 or more pauses the lottery with `paused_reason = 'reorg'` in the same transaction; a header at the tip's own height with a different hash is a reorg too, not ignored. One more header is refused *without* ending the session (B-64): 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 — and since B-83 that includes `corroborate_utxo_reinstatement` before a UTXO written off as externally spent is put back (same outpoint, amount, confirmed; `deposits/service.py:find_reinstate_candidates` only reads, `reinstate_reappeared_utxos` writes what the quorum agreed on), and `confirmation_proven` before a tx is marked confirmed: `tx/confirmation.py:poll_once` takes the height the active server reports only as a *claim*, and the row confirms when a strict majority of at least 2 of the *other* servers return a `get_merkle` proof that recomputes to the merkle root of the block's header (`electrum/merkle.py`; the header is the tip we hold, or for an older block the one the quorum agrees on and that meets its own target). With no `network` nothing confirms. The one decision still on the active server's word is the pool-coin listing for a payout (B-82). It needs **at least 2 answers** and a strict majority of those that answered (B-84): fewer → returns **False**, since one voice decides nothing independently and an unreachable network proves nothing. Only `ALLOW_NO_QUORUM=true` keeps the old reduced rule (no other server → True, otherwise a majority of whoever answers). 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.
@@ -159,21 +176,21 @@ Diagrams: [platform-overview.mmd](flowchart/platform-overview.mmd), [round-lifec
**DRAW** — configurable timer (default 600s):
- *Bet cutoff is the round's own deadline* (`round_deadline` = `opened_at + Round.duration_seconds`, the value snapshotted at open time — B-61), **not** the DB status: `place_bet` calls `rounds/service.round_accepts_bets`, which rejects once the deadline passes even while `status` is still `"open"` (the 5s scheduler tick can lag behind it). Once a round leaves `open`, no new bets either, and no new round opens until this one is fully `closed`. The deadline is checked twice — on arrival and again after the transaction is built — and the participant row is then committed behind a **compare-and-set on the round row** (`UPDATE rounds ... WHERE status = 'open'`, B-53): the scheduler flips `open` → `closing` in a transaction of its own and only counts in-flight bets afterwards, so without the CAS a bet could commit in between, be excluded from the draw (only `confirmed` participants are drawn) and still have its sats land in the pool with no refund path. Its mirror image on the scheduler side is `_close_and_draw` re-counting in-flight bets in the same session it snapshots the participants from.
- *"Yellow light":* closing **waits for every already-broadcast bet to confirm** before drawing, so a bet in flight at the boundary isn't lost (`building` counts as in-flight; what bounds the wait is the reconciler eventually abandoning a bet that never confirms).
- *Algorithm* (deliberately simple, meant to be replaced): first block confirmed after closing — corroborated by the other servers first, and on failure the draw waits for a *further* block and writes a `draw_header_corroboration_failed` audit entry rather than stalling silently — hash as seed, `index = seed mod participant_count` over participants ordered by **broadcast timestamp** (also the tie-break when two bets land in the same block). Equal probability for everyone, regardless of amount. The baseline the draw compares against (`tip_at_close`) must be a height we actually knew at closing time: a `0` there means *unknown*, not "the chain is at zero", so `_wait_for_next_block` adopts the first height it then learns as the baseline and waits for a block strictly after it (`draw_baseline_tip_unknown`, B-63) — seeding from a block that already existed while bets were open would make the winner predictable to whoever was watching the chain.
- *Payout* is signed with the pool key; its **fee comes out of the winner's 70%**, leaving the 30% fee share intact. Same timeout → RBF → rebroadcast pattern.
- *Algorithm* (deliberately simple, meant to be replaced; **commit-reveal since B-73**, spec RND-14 … RND-20, RND-34 … RND-37): at open the round gets a 32-byte `server_seed` — stored only **Fernet-encrypted** with the master-xprv key (`server_seed_enc`; the plaintext column `server_seed` stays NULL until the reveal) — and publishes `server_seed_hash = sha256(seed)`. Entering `drawing` fixes, in one transaction with the status change, the confirmed participants **ordered by bet txid ascending** (public data, no ties — never `broadcast_at`), each one's `draw_position`, `participants_hash` (sha256 of `txid:vout:address\n` lines; `bet_vout` is the output paying the round's pool address), and `draw_height = tip_at_close + 1`, and writes `draw_committed`. The draw waits until the chain has `draw_confirmations` blocks from `draw_height` (snapshotted at open from `round_config`, default 3), then asks **every** server, the active one included, for the header *at that exact height* (`ElectrumListener.agreed_block_hash`: valid work, at least 2 other answers, strict majority of all answers) — no agreement means the same height is asked again, never another block, so whoever mines or relays blocks cannot pick the one that seeds the draw (`draw_header_corroboration_failed`, once per distinct hash the active server reported). `seed = sha256(server_seed ‖ block_hash ‖ participants_hash)` as a big-endian integer, `index = seed mod n`, winner = participant with that `draw_position`; equal probability for everyone, regardless of amount. The reveal (`server_seed` column + `winner_drawn` payload) happens in the same transaction that stores the winner (or when a round closes with no participants), and `GET /rounds/{id}/proof` (public) returns everything needed to recompute it. A tip of 0 at closing means *unknown*: the round stays `closing` (`draw_baseline_tip_unknown`, once per round, B-63) because `draw_height` must come from a height we actually knew. `draw_stalled` fires when the chain has not advanced for 360s while waiting for confirmations, or the quorum keeps failing to agree. `_complete_draw` reads everything it needs from the database (`_close_and_draw` enters `drawing` and then calls it); a round opened before B-73 (no `server_seed_enc`) is given a secret as it enters `drawing`.
- *Payout* is signed with the round's own pool key — every round has its own pool address `m/84'/746'/0'/2/<round_id>`, stored in `rounds.pool_address` when the round opens (B-80; `derive_pool_address(round_id)`, `derive_round_pool_key`), and bets pay it, the payout reads and spends only its coins, and a withdrawal to it (or to the reserve address `1/0`, or to `fee_address`) is refused with `withdrawal_to_platform_address`. Rounds opened before B-80 keep the old shared `1/0` address as their pool; it is now the *reserve* address. The payout's **fee comes out of the winner's 70%**, leaving the 30% fee share intact. Same timeout → RBF → rebroadcast pattern.
- *UI, two independent layers.* A generic phase box ("Pagamento al vincitore in corso…") shows to **every** viewer for the whole closing/drawing/paying_out span — pure cosmetic text driven by `status`. **Additively**, a personalized "Hai vinto!/Non hai vinto" box appears only where `user_played` is true (computed via `get_optional_user`, since the endpoint is reachable logged-out) — nobody else has anything to reveal.
- *Reveal timing.* Delayed by at least `draw_animation_seconds`, anchored to the server's `closes_at` so a reload can't reset the countdown, and decoupled from the real (~block-time) wait for `winner_user_id`. Once revealed it's persisted in `localStorage.plm_persisted_result`, surviving the move to `closed` — at which point `get_active_round` stops returning the round and `winner_user_id` disappears from `GET /rounds/current`. `GET /users/me/last-round-result` is the durable DB-backed backstop for a device that missed the live window entirely. Full logic: `refreshRound`/`checkLastRoundResult` in `app/static/app.js`.
**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.
2. **The draw block** — `_wait_for_next_block` waits for `tip_height > tip_at_close`, recorded only once step 1 is done, so this is necessarily a later block.
2. **The draw block** — fixed at `draw_height = tip_at_close + 1` (recorded only once step 1 is done, so necessarily a later block) and read once the chain has `draw_confirmations` blocks from it (3 by default, so it is really ~3 blocks, not one).
3. **Payout confirmation** — built only after step 2's winner is known, so it needs yet another block; the generic `ConfirmationPoller` tracks it.
At 120s blocks that's ~4–6 min worst case (last bet confirms right at the deadline), ~2–4 min best case — independent of `draw_animation_seconds`.
At 120s blocks that's ~8–10 min worst case (last bet confirms right at the deadline), ~6–8 min best case with the default 3 draw confirmations — independent of `draw_animation_seconds`.
## Balance display
@@ -196,10 +213,12 @@ Both SPAs refresh on an `update` message *or* on `open` — the latter fires on
Everything that spends money is written **before** it is broadcast and resolved against the chain afterwards; this is what makes the system recover without manual DB edits. `PendingTransaction.status`: `building` → `pending` → `confirmed`, or `failed`.
- `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).
- **Nothing is released on doubt (B-76).** `tx/outcome.py:broadcast_with_verdict` sorts a broadcast into accepted / refused / uncertain. Only an explicit JSON-RPC error (`ElectrumRpcError`) that `ElectrumListener.transaction_known` then confirms — the active server and the quorum minimum of the others all say they do not know the tx — releases the UTXOs, restores the balance, removes the participant (or marks the withdrawal `failed`), audit-logs, and raises `broadcast_failed` → **502**. If any server returns the tx, or the message is an "already known" one, it counts as accepted. A timeout, a dropped connection or a refusal that could not be verified leaves the rows `building` for the reconciler and the API answers **202**. An accepted tx is also fanned out to every other server (`fan_out_transaction`, best effort).
- `tx/reconcile.py` asks the **quorum** about anything still `building`/`pending` (every txid of the row, on the active server and every other one): present on any server → promote (and adopt the version found); otherwise **nothing is given up without proof** (B-78, ADR-51): a row is abandoned — `failed` with the proof in `failure_reason`, inputs released, domain row rolled back, `pending_tx_abandoned` logged — only if one of its inputs is spent *in a block* by another tx and the other servers agree (`confirmed_spender`), or no server knows any txid *and* a rebroadcast of its latest raw tx (`rebroadcast_everywhere`) is refused by every server for missing/spent inputs. A fee refusal is not proof (`building` → `pending` for the bumper); too few answers, a transport failure or the age of the row prove nothing. Grace only decides from when a row is examined (120s `building`, 6h `pending`). The write re-checks status *and* `current_txid` under `begin_immediate` (TX-26). `failed` rows stay watched for 14 days (`failed_at`): one that confirms late is marked `confirmed`, `pending_tx_resurrected` is logged and the lottery pauses (`paused_reason = 'resurrected_tx'`, `rounds/pause.py`); the linked rows are never corrected by the system. A tx still in some 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.
**SQLite transactions are real ones (B-88).** `_register_sqlite_pragmas` sets `synchronous=FULL` and switches pysqlite's implicit `BEGIN` off (`isolation_level = None`); an engine `begin` event emits `BEGIN` itself, so every read is inside a transaction. Every transaction that moves money or fixes its state opens with `await begin_immediate(session)` (`app/db/base.py`) — `BEGIN IMMEDIATE`, i.e. the write lock *before* the first read (it commits the caller's read-only transaction first and refuses a session with unflushed changes). A lock not granted within `busy_timeout` raises `OperationalError`: **before** a broadcast that means "refuse" (`service_busy`, 503, nothing built or sent); **after** one nothing is undone — the row stays `building` and the reconciler resolves it. New money-moving write code must call `begin_immediate` first, and tests of that must use a file DB whose engine went through `_register_sqlite_pragmas` (an in-memory engine without it never emits `BEGIN IMMEDIATE`).
`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. **Every version a row ever had is tracked (B-77):** `pending_transaction_txids` (`app/tx/versions.py`) holds each txid with its raw tx, written with the row and, for an RBF replacement, *before* it is broadcast; the poller and the reconciler look for all of them, and when the network holds a version other than the current one `broadcast.py:adopt_version` makes it current and retargets everything. `bump_fee` ends with a conditional `UPDATE … WHERE status='pending' AND current_txid=<replaced>`; zero rows is a logged conflict, never an overwrite. `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.
**Payouts retry, and are guarded against paying twice.** Every tick re-examines a `paying_out` round: `_retry_payout_if_due` throttles to one attempt per 60s using the latest `payout_failed` audit entry as its clock (a build failure leaves no DB row to throttle on), and every early return in `_trigger_payout` writes one, so `/admin` shows *why* a round is stuck. Before building, `_trigger_payout` refuses if a `building`/`pending` payout already exists for the round, and `_reserved_payout_outpoints` excludes pool UTXOs claimed by any unresolved payout — without both, a retry would pay the winner twice.
@@ -207,7 +226,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 +243,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
@@ -243,7 +262,7 @@ Explicit design choices, not derivable from any single file — respect them:
Accepted **by design** — distinct from the audit findings above (all fixed), which are not duplicated here.
- **`drawing` doesn't resume after a restart.** `_tick()` handles `open`, `closing` and `paying_out` (the last via `_retry_payout_if_due`); nothing re-enters `_wait_for_next_block` after a crash. That wait is unbounded by design (the draw's entropy genuinely depends on a future block) but no longer silent — past `_DRAW_STALL_THRESHOLD_SECONDS` it logs progress and writes a `draw_stalled` audit entry, and `GET /rounds/current`'s `draw_waiting_since` surfaces it live (B-36). Restart-resumption itself remains the last prerequisite for running unattended.
- **`drawing` doesn't resume after a restart.** `_tick()` handles `open`, `closing` and `paying_out` (the last via `_retry_payout_if_due`); nothing re-enters `_complete_draw` after a crash (everything it needs is in the database since B-73, only the `_tick` branch is missing — B-81). That wait is unbounded by design (the draw's entropy genuinely depends on a future block) but no longer silent — past `_DRAW_STALL_THRESHOLD_SECONDS` it logs progress and writes a `draw_stalled` audit entry, and `GET /rounds/current`'s `draw_waiting_since` surfaces it live (B-36). Restart-resumption itself remains the last prerequisite for running unattended.
- **RBF handles one shape only**: a single change output, back to the tx's own sender, big enough to absorb the increase. No extra-input fallback, and none would help the case that used to hurt (an amount equal to the whole input total leaves no other UTXO to add) — which is why `build_signed_transaction` now guarantees a change output of at least `DUST_LIMIT_SATS` instead (B-62): a withdrawal for the full balance moves a dust limit less, a bet from a balance equal to the bet is refused with `balance_leaves_no_change`. What's left is a bump whose *delta* exceeds an otherwise-fine change output, which still raises `RbfError`; that tx is eventually abandoned and its UTXOs released.
- **Withdrawal and RBF bump are unit-tested but never live-broadcast** (failure and rollback branches included — still not a real network).
- **No user-facing history of rounds or transactions.** `GET /users/me/last-round-result` covers exactly one case (the reveal backstop above) and `GET /bug-reports/mine` one more (the reporter's own reports). Admin has `/admin/rounds`, `/admin/pending-transactions`, `/admin/audit-log`; a user has no equivalent — a failed withdrawal leaves a `failed` row they can never see, which argues for closing this.
+3 -2
View File
@@ -41,7 +41,8 @@ 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/README.md](docs/README.md) — **index of all documentation** (docs-first, single source of truth, one ADR per decision: [docs/adr/](docs/adr/README.md))
- [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)
@@ -61,7 +62,7 @@ python -m pytest # all tests
python -m pytest tests/unit/test_hd.py # one file
```
351 unit tests cover HD derivation, PSBT building, the Electrum client, bets,
617 unit tests cover HD derivation, PSBT building, the Electrum client, bets,
deposits, withdrawals, the round/draw engine, RBF fee-bumping, admin config,
the pending-inclusive balance calculation, and the SSE push channel. No
automated integration tests against a live Electrum connection — mainnet
+35 -4
View File
@@ -13,6 +13,7 @@ from app.config import settings
from app.db.models import AuditLog, BugReport, PendingTransaction, Round, User
from app.db.session import get_session
from app.rounds.config import get_round_config
from app.rounds.pause import AUTOMATIC_REASONS, OPERATOR_REASON
from app.wallet.address import is_valid_plm_address
from app.wallet.hd import derive_user_wif
from app.wallet.psbt_builder import MAX_FEE_RATE_SAT_VB
@@ -44,6 +45,7 @@ _CONFIG_FIELDS = (
"fee_rate_sat_vb",
"rbf_timeout_seconds",
"draw_animation_seconds",
"draw_confirmations", # B-73 (DAT-62)
)
@@ -55,7 +57,9 @@ class RoundConfigResponse(BaseModel):
fee_rate_sat_vb: int
rbf_timeout_seconds: int
draw_animation_seconds: int
draw_confirmations: int # B-73 (DAT-62)
paused: bool
paused_reason: str | None = None # B-78 (DAT-69): why, or None when not paused
class RoundConfigUpdate(BaseModel):
@@ -75,6 +79,7 @@ class RoundConfigUpdate(BaseModel):
fee_rate_sat_vb: int | None = Field(default=None, ge=1, le=MAX_FEE_RATE_SAT_VB)
rbf_timeout_seconds: int | None = Field(default=None, ge=60, le=7 * 24 * 3600)
draw_animation_seconds: int | None = Field(default=None, ge=0, le=600)
draw_confirmations: int | None = Field(default=None, ge=1, le=20) # B-73 (DAT-62)
@field_validator("fee_address")
@classmethod
@@ -93,6 +98,7 @@ class RoundConfigUpdate(BaseModel):
def _config_response(config) -> RoundConfigResponse:
fields = {field: getattr(config, field) for field in _CONFIG_FIELDS}
fields["paused"] = config.paused
fields["paused_reason"] = config.paused_reason
return RoundConfigResponse(**fields)
@@ -128,14 +134,29 @@ async def update_config(
return _config_response(config)
class PauseRequest(BaseModel):
note: str | None = Field(default=None, max_length=256)
@router.post("/pause", response_model=RoundConfigResponse, dependencies=[Depends(require_admin)])
async def pause_lottery(session: AsyncSession = Depends(get_session)) -> RoundConfigResponse:
async def pause_lottery(
body: PauseRequest | None = None, session: AsyncSession = Depends(get_session)
) -> RoundConfigResponse:
"""Maintenance switch: the round in progress (if any) still closes, draws,
and pays out its winner normally — only opening the *next* round is
suppressed until /admin/resume is called (rounds/service.py)."""
suppressed until /admin/resume is called (rounds/service.py).
B-78 (DAT-69, API-32): the reason is "operator", except that an automatic reason
already in force stays — it is the one that needs a look. The audit row always
says `operator` for this call."""
config = await get_round_config(session)
if not (config.paused and config.paused_reason in AUTOMATIC_REASONS):
config.paused_reason = OPERATOR_REASON
config.paused = True
await write_audit_log(session, "lottery_paused", {})
payload = {"reason": OPERATOR_REASON}
if body is not None and body.note:
payload["note"] = body.note
await write_audit_log(session, "lottery_paused", payload)
await session.commit()
return _config_response(config)
@@ -143,8 +164,12 @@ async def pause_lottery(session: AsyncSession = Depends(get_session)) -> RoundCo
@router.post("/resume", response_model=RoundConfigResponse, dependencies=[Depends(require_admin)])
async def resume_lottery(session: AsyncSession = Depends(get_session)) -> RoundConfigResponse:
config = await get_round_config(session)
# B-78 (AUD-12): the reason the resume took away, so the log says what the operator
# agreed to resume (None when the lottery was not paused).
lifted = config.paused_reason if config.paused else None
config.paused = False
await write_audit_log(session, "lottery_resumed", {})
config.paused_reason = None
await write_audit_log(session, "lottery_resumed", {"reason": lifted})
await session.commit()
return _config_response(config)
@@ -241,6 +266,9 @@ class AdminRoundResponse(BaseModel):
winner_amount_sats: int | None
fee_amount_sats: int | None
payout_txid: str | None
pool_address: str | None # B-80
server_seed_hash: str | None # B-73 (API-36): the commitment only — never the secret
draw_height: int | None # B-73
@router.get("/rounds", response_model=list[AdminRoundResponse], dependencies=[Depends(require_admin)])
@@ -268,6 +296,9 @@ async def list_rounds(
winner_amount_sats=r.winner_amount_sats,
fee_amount_sats=r.fee_amount_sats,
payout_txid=r.payout_txid,
pool_address=r.pool_address or None,
server_seed_hash=r.server_seed_hash,
draw_height=r.draw_height,
)
for r in rounds
]
+10 -2
View File
@@ -1,4 +1,4 @@
from fastapi import APIRouter, Depends, Request, status
from fastapi import APIRouter, Depends, Request, Response, status
from pydantic import BaseModel
from sqlalchemy.ext.asyncio import AsyncSession
@@ -21,6 +21,7 @@ class BetResponse(BaseModel):
@router.post("", response_model=BetResponse, status_code=status.HTTP_201_CREATED)
async def create_bet(
request: Request,
response: Response,
user: User = Depends(get_current_user),
session: AsyncSession = Depends(get_session),
) -> BetResponse:
@@ -34,17 +35,24 @@ async def create_bet(
async with request.app.state.user_locks.acquire(user.id):
try:
participant = await place_bet(session, listener.client, user)
participant = await place_bet(session, listener.client, user, network=listener)
except BetError as exc:
# A rejected broadcast isn't the client's fault — it's the network
# refusing our transaction, so it answers 502 rather than 400 (B-07).
code = (
status.HTTP_502_BAD_GATEWAY
if exc.code == "broadcast_failed"
else status.HTTP_503_SERVICE_UNAVAILABLE # B-88: write lock not granted, nothing sent
if exc.code == "service_busy"
else status.HTTP_400_BAD_REQUEST
)
raise from_api_error(code, exc) from exc
if participant.status == "building":
# B-76 (TX-20, BET-23): the outcome of the broadcast is uncertain — the tx may
# already be on the network — so the bet is accepted for processing, not
# confirmed as sent, and the reconciler settles it.
response.status_code = status.HTTP_202_ACCEPTED
return BetResponse(
round_id=participant.round_id,
bet_txid=participant.bet_txid,
+107 -1
View File
@@ -9,9 +9,10 @@ from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.client_ip import client_ip
from app.api.errors import http_error
from app.api.timeutil import isoformat_utc
from app.auth.dependencies import get_optional_user
from app.db.models import RoundParticipant, User
from app.db.models import Round, RoundParticipant, User
from app.db.session import get_session
from app.rounds.config import get_round_config
from app.rounds.events import EVICTED, RoundEventCapacityError, broadcaster
@@ -89,6 +90,9 @@ class CurrentRoundResponse(BaseModel):
server_time: str
round_id: int | None = None
status: str | None = None
# B-80 (RND-35): this round's own pool address, so anyone can verify its money on
# an explorer; null when there is no active round.
pool_address: str | None = None
opened_at: str | None = None
closes_at: str | None = None
# B-65: confirmed participants only — the ones the draw actually picks from and
@@ -115,8 +119,16 @@ class CurrentRoundResponse(BaseModel):
# waiting for a block" rather than a countdown implying a bounded wait — this
# phase has no timeout, only draw_animation_seconds' cosmetic minimum.
draw_waiting_since: str | None = None
# B-73 (RND-34, RND-14): the commitment published from the opening, and what is fixed
# on entering "drawing". The secret itself is never in this response (API-45 has it, once
# revealed).
server_seed_hash: str | None = None
participants_hash: str | None = None
draw_height: int | None = None
draw_confirmations: int | None = None
chain_tip_height: int | None = None
lottery_paused: bool = False
paused_reason: str | None = None # B-78 (DAT-69): operator / resurrected_tx / ..., None if not paused
# B-66: false while the instance is missing configuration a round cannot run
# without (today: fee_address) — no round will open until it's set, so this is
# the difference between "wait, the next round is coming" and "nothing is coming
@@ -144,6 +156,7 @@ async def current_round(
draw_animation_seconds=config.draw_animation_seconds,
chain_tip_height=chain_tip_height,
lottery_paused=config.paused,
paused_reason=config.paused_reason,
lottery_configured=rounds_can_open(config),
)
@@ -205,6 +218,7 @@ async def current_round(
server_time=datetime.now(timezone.utc).isoformat(),
round_id=round_.id,
status=round_.status,
pool_address=round_.pool_address or None,
opened_at=opened_at.isoformat(),
closes_at=closes_at.isoformat(),
participant_count=participant_count,
@@ -219,8 +233,100 @@ async def current_round(
draw_block_height=round_.draw_block_height,
draw_block_hash=round_.draw_block_hash,
draw_waiting_since=isoformat_utc(round_.drawing_started_at) if round_.status == "drawing" else None,
server_seed_hash=round_.server_seed_hash,
participants_hash=round_.participants_hash,
draw_height=round_.draw_height,
draw_confirmations=round_.draw_confirmations,
chain_tip_height=chain_tip_height,
lottery_paused=config.paused,
paused_reason=config.paused_reason,
lottery_configured=rounds_can_open(config),
user_played=user_played,
)
class ProofParticipant(BaseModel):
draw_position: int
txid: str
vout: int
address: str
amount_sats: int
status: str
class RoundProofResponse(BaseModel):
round_id: int
status: str
algorithm: str
pool_address: str | None
server_seed_hash: str | None
server_seed: str | None
draw_height: int | None
draw_confirmations: int
participants: list[ProofParticipant]
participants_hash: str | None
draw_block_hash: str | None
seed: str | None
winner_index: int | None
winner_address: str | None
payout_txid: str | None
@router.get("/{round_id}/proof", response_model=RoundProofResponse)
async def round_proof(round_id: int, session: AsyncSession = Depends(get_session)) -> RoundProofResponse:
"""B-73 (RND-37, API-45): everything needed to recompute a round's winner without
trusting the server — public, unauthenticated, for a round in any state. A field that
does not exist yet is null (or an empty list).
`server_seed` is the plaintext column, which is written only by the reveal (the same
transaction that stores the winner, or the close of a round without participants), so
there is no state of the round in which this endpoint can return it early.
"""
round_ = await session.get(Round, round_id)
if round_ is None:
raise http_error(404, "round_not_found", "round not found")
rows = (
await session.execute(
select(RoundParticipant, User.address)
.join(User, User.id == RoundParticipant.user_id)
.where(RoundParticipant.round_id == round_id, RoundParticipant.draw_position.is_not(None))
.order_by(RoundParticipant.draw_position)
)
).all()
participants = [
ProofParticipant(
draw_position=p.draw_position,
txid=p.bet_txid,
vout=p.bet_vout,
address=address,
amount_sats=p.bet_amount_sats,
status=p.status,
)
for p, address in rows
]
seed_decimal = round_.seed_int
winner_index = None
winner_address = None
if seed_decimal is not None and participants:
winner_index = int(seed_decimal) % len(participants)
winner_address = participants[winner_index].address
return RoundProofResponse(
round_id=round_.id,
status=round_.status,
algorithm="commit-reveal-v1" if round_.server_seed_hash else "block-hash-v0",
pool_address=round_.pool_address or None,
server_seed_hash=round_.server_seed_hash,
server_seed=round_.server_seed,
draw_height=round_.draw_height,
draw_confirmations=round_.draw_confirmations,
participants=participants,
participants_hash=round_.participants_hash,
draw_block_hash=round_.draw_block_hash,
seed=seed_decimal,
winner_index=winner_index,
winner_address=winner_address,
payout_txid=round_.payout_txid,
)
+9 -2
View File
@@ -1,4 +1,4 @@
from fastapi import APIRouter, Depends, Request, status
from fastapi import APIRouter, Depends, Request, Response, status
from pydantic import BaseModel
from sqlalchemy.ext.asyncio import AsyncSession
@@ -27,6 +27,7 @@ class WithdrawalResponse(BaseModel):
async def create_withdrawal(
body: WithdrawalRequest,
request: Request,
response: Response,
user: User = Depends(get_current_user),
session: AsyncSession = Depends(get_session),
) -> WithdrawalResponse:
@@ -41,16 +42,22 @@ async def create_withdrawal(
async with request.app.state.user_locks.acquire(user.id):
try:
withdrawal = await request_withdrawal(
session, listener.client, user, body.external_address, body.amount_sats
session, listener.client, user, body.external_address, body.amount_sats, network=listener
)
except WithdrawalError as exc:
code = (
status.HTTP_502_BAD_GATEWAY # the network refused it, not the caller (B-07)
if exc.code == "broadcast_failed"
else status.HTTP_503_SERVICE_UNAVAILABLE # B-88: write lock not granted, nothing sent
if exc.code == "service_busy"
else status.HTTP_400_BAD_REQUEST
)
raise from_api_error(code, exc) from exc
if withdrawal.status == "building":
# B-76 (TX-20, WDR-16): uncertain broadcast — accepted for processing, the
# reconciler decides whether the transaction left.
response.status_code = status.HTTP_202_ACCEPTED
return WithdrawalResponse(
txid=withdrawal.txid,
amount_requested_sats=withdrawal.amount_requested_sats,
+14 -1
View File
@@ -1,7 +1,7 @@
from fastapi import APIRouter, Depends, Request, status
from pydantic import BaseModel, Field
from sqlalchemy import func, select
from sqlalchemy.exc import IntegrityError
from sqlalchemy.exc import IntegrityError, OperationalError
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.client_ip import client_ip as _client_ip
@@ -13,6 +13,7 @@ from app.auth.security import (
hash_password_async,
verify_password_async,
)
from app.db.base import begin_immediate
from app.db.models import User
from app.db.session import get_session
from app.wallet.hd import derive_user_address
@@ -89,6 +90,18 @@ async def register(
password_hash = await hash_password_async(body.password)
for _ in range(_MAX_REGISTER_RETRIES):
# B-88: the max(derivation_index) read and the insert that uses it are one
# transaction under the write lock — with a plain BEGIN two concurrent
# registrations both read the same maximum and one of them failed on the
# unique index. A lock that cannot be had is a "try again", not a 500.
try:
await begin_immediate(session)
except OperationalError as exc:
raise http_error(
status.HTTP_503_SERVICE_UNAVAILABLE,
"service_busy",
"the service is busy right now, nothing was sent — please try again",
) from exc
max_index = await session.scalar(select(func.max(User.derivation_index)))
next_index = 0 if max_index is None else max_index + 1
address = derive_user_address(next_index)
+83 -15
View File
@@ -1,3 +1,4 @@
import logging
from datetime import datetime, timezone
from embit import script
@@ -7,15 +8,19 @@ from sqlalchemy.ext.asyncio import AsyncSession
from app.api.errors import ApiError
from app.audit.log import write_audit_log
from app.db.base import begin_immediate
from app.db.models import PendingTransaction, Round, RoundParticipant, User, UtxoEvent
from app.electrum.client import ElectrumClient
from app.rounds.config import get_round_config
from app.rounds.events import broadcaster
from app.rounds.service import open_new_round_if_needed, round_accepts_bets
from app.tx.versions import delete_versions, record_version
from app.tx.outcome import BroadcastOutcome, TransactionNetwork, broadcast_with_verdict
from app.wallet.balance import recompute_balance
from app.wallet.hd import derive_pool_address, derive_user_key
from app.wallet.hd import derive_user_key
from app.wallet.psbt_builder import (
MAX_PARTICIPANTS_PER_ROUND,
RECIPIENT_VOUT,
BuiltTransaction,
InsufficientFundsError,
Utxo,
@@ -23,6 +28,9 @@ from app.wallet.psbt_builder import (
)
logger = logging.getLogger(__name__)
class BetError(ApiError):
pass
@@ -32,7 +40,23 @@ class _RoundClosedDuringBuild(Exception):
being built. Never leaves place_bet — it becomes a `round_closing` BetError."""
async def place_bet(session: AsyncSession, client: ElectrumClient, user: User) -> RoundParticipant:
async def place_bet(
session: AsyncSession, client: ElectrumClient, user: User, network: TransactionNetwork | None = None
) -> RoundParticipant:
"""`network` (the ElectrumListener) is what verifies a refused broadcast and fans an
accepted one out (B-76); without it a refusal can never be proven, so it never
releases anything."""
# B-88 (DAT-74, BET-11): take SQLite's write lock before the first read, so the
# balance, the free UTXOs, the participants and the round's status read below are
# the state the phase-1 write lands on — a plain BEGIN only starts at the first
# write, leaving every read before it outside any transaction. Failing to get the
# lock within busy_timeout is not a conflict about this bet: nothing has been
# built or broadcast yet, so the player is simply asked to retry.
try:
await begin_immediate(session)
except OperationalError as exc:
raise _service_busy() from exc
round_ = await open_new_round_if_needed(session)
if round_ is None:
raise BetError("no_round_open", "no round open right now, please try again shortly")
@@ -69,6 +93,11 @@ async def place_bet(session: AsyncSession, client: ElectrumClient, user: User) -
max_participants=MAX_PARTICIPANTS_PER_ROUND,
)
if not round_.pool_address:
# B-80: open_new_round_if_needed always writes it; a row without one cannot
# take money that would then have nowhere verifiable to go.
raise RuntimeError(f"round {round_.id} has no pool address")
bet_amount = config.bet_amount_sats
unspent = (
@@ -88,7 +117,7 @@ async def place_bet(session: AsyncSession, client: ElectrumClient, user: User) -
signing_key=user_key,
from_script=from_script,
utxos=utxos,
to_address=derive_pool_address(),
to_address=round_.pool_address, # B-80: this round's own pool address
amount_sats=bet_amount,
change_address=user.address,
fee_rate_sat_vb=config.fee_rate_sat_vb,
@@ -115,12 +144,14 @@ async def place_bet(session: AsyncSession, client: ElectrumClient, user: User) -
user_id=user.id,
bet_amount_sats=built.recipient_sats,
bet_txid=built.txid,
bet_vout=RECIPIENT_VOUT, # B-73 (DAT-63)
broadcast_at=broadcast_at,
status="building",
)
session.add(participant)
pending = _pending_transaction(round_.id, user.id, built, config.fee_rate_sat_vb)
session.add(pending)
await record_version(session, pending, built.txid, built.raw_hex) # B-77: the first version, with the row
# B-53: the deadline check at the top of this function happened before the UTXO
# scan and the signing above, so re-check it here against the clock as it is now —
@@ -148,26 +179,55 @@ async def place_bet(session: AsyncSession, client: ElectrumClient, user: User) -
if guard.rowcount != 1:
raise _RoundClosedDuringBuild
await session.commit()
except (_RoundClosedDuringBuild, OperationalError) as exc:
# OperationalError here is SQLite's write-snapshot conflict: the round row
# changed under us, which is the same situation as the guard matching nothing.
except _RoundClosedDuringBuild as exc:
# Nothing has been broadcast yet, so the rollback undoes phase 1 entirely —
# the UTXOs stay unspent and no participant row survives.
await session.rollback()
raise BetError(
"round_closing", "the current round is closing, please try again shortly"
) from exc
except OperationalError as exc:
# B-88: SQLite has no write-snapshot conflicts — an OperationalError here is
# the lock wait (busy_timeout) expiring, which says nothing about the round.
# Same rollback, but the honest answer is "busy", not "closing".
await session.rollback()
raise _service_busy() from exc
# --- Phase 2: broadcast, then promote both rows to their live state ---------
try:
await client.broadcast(built.raw_hex)
except Exception as exc:
# The node refused it (fee too low, dust, mempool conflict, or simply an
# unreachable server) — nothing is on-chain, so undo phase 1 completely and
# give the user a translatable failure instead of a bare 500 (B-07).
await _release_failed_bet(session, participant, pending, built, user.id, str(exc))
raise BetError("broadcast_failed", f"the network refused the transaction: {exc}") from exc
# B-76 (TX-04, TX-20): only a *verified* refusal undoes phase 1. A timeout, a
# dropped connection or a refusal nobody could verify leaves the tx possibly on the
# network, and releasing the coins then sent the bet's sats into the pool with no
# participant behind them — so those rows stay "building" for the reconciler.
verdict = await broadcast_with_verdict(client, network, built.raw_hex, built.txid)
if verdict.outcome is BroadcastOutcome.REFUSED:
# The network refused it (fee too low, dust, mempool conflict) and no server
# knows it — nothing is on-chain, so undo phase 1 completely and give the user
# a translatable failure instead of a bare 500 (B-07).
try:
await _release_failed_bet(session, participant, pending, built, user.id, verdict.reason)
except OperationalError:
# B-88: the database is busy, so the release could not be written. The
# rows stay "building" — the state phase 1 committed — and the
# reconciler resolves them against the chain.
await session.rollback()
logger.error("could not release the failed bet %s: database busy, left to the reconciler", built.txid)
raise BetError("broadcast_failed", f"the network refused the transaction: {verdict.reason}")
if verdict.outcome is BroadcastOutcome.UNCERTAIN:
logger.warning("bet %s: broadcast outcome uncertain (%s), left 'building' for the reconciler", built.txid, verdict.reason)
await session.refresh(participant) # reports the status the DB really holds: building
broadcaster.publish() # an in-flight bet counts towards the round's figures
return participant
# B-88: after the broadcast nothing may be undone. If the lock cannot be had the
# rows stay "building" (the tx is on the network) and the reconciler promotes
# them; the caller still gets the participant, with the status the DB holds.
try:
await begin_immediate(session)
except OperationalError:
await session.rollback()
logger.error("bet %s broadcast but the database is busy: left 'building' for the reconciler", built.txid)
await session.refresh(participant) # reports the status the DB really holds
return participant
participant.status = "broadcast"
pending.status = "pending"
await write_audit_log(
@@ -177,7 +237,6 @@ async def place_bet(session: AsyncSession, client: ElectrumClient, user: User) -
user_id=user.id,
round_id=round_.id,
)
await session.commit()
await session.refresh(participant)
broadcaster.publish() # participant_count/jackpot changed — nudge every dashboard to refetch
@@ -195,6 +254,7 @@ async def _release_failed_bet(
"""Undo phase 1 after a failed broadcast: free the UTXOs the build reserved, drop
the two rows, and restore the balance. Same shape as what the reconciler does for
a tx that turns out never to have made it onto the chain."""
await begin_immediate(session) # B-88
for spent in built.spent_utxos:
row = await session.scalar(
select(UtxoEvent).where(UtxoEvent.txid == spent.txid, UtxoEvent.vout == spent.vout)
@@ -202,6 +262,7 @@ async def _release_failed_bet(
if row is not None:
row.spent_txid = None
await session.delete(participant)
await delete_versions(session, pending.id) # B-77 (DAT-38): the versions go with the row
await session.delete(pending)
await recompute_balance(session, user_id)
await write_audit_log(
@@ -218,6 +279,13 @@ async def _release_failed_bet(
broadcaster.publish()
def _service_busy() -> BetError:
return BetError(
"service_busy",
"the service is busy right now, nothing was sent — please try again",
)
def _pending_transaction(
round_id: int, user_id: int, built: BuiltTransaction, fee_rate_sat_vb: int
) -> PendingTransaction:
+49
View File
@@ -1,3 +1,5 @@
import logging
from pydantic_settings import BaseSettings, SettingsConfigDict
# Minimum JWT signing key length. HS256 keys shorter than the hash output weaken
@@ -5,6 +7,14 @@ from pydantic_settings import BaseSettings, SettingsConfigDict
# than being shipped by accident.
MIN_JWT_SECRET_LENGTH = 32
# B-84 (ELC-19, ELC-14): fallback servers needed besides the primary. With fewer than
# three servers, a corroboration (which never asks the active one) cannot have two
# independent answers — one server would decide, or none would.
MIN_QUORUM_FALLBACK_SERVERS = 2
MIN_QUORUM_RESPONSES = 2
logger = logging.getLogger(__name__)
class Settings(BaseSettings):
model_config = SettingsConfigDict(env_file=".env", extra="ignore")
@@ -21,6 +31,15 @@ class Settings(BaseSettings):
# connection, which makes a single hardcoded server the platform's biggest
# single point of failure. Parsed by electrum.client.parse_endpoints.
electrum_fallback_servers: str = ""
# B-84 (ELC-03): SHA-256 (hex) of the primary server's DER certificate. Empty = not
# pinned. Fallback servers carry their own `:pin=<sha256>` in the list above.
electrum_cert_pin: str = ""
# B-84 (ELC-19): development only. Lets the server start with fewer than
# MIN_QUORUM_FALLBACK_SERVERS fallback servers, and corroboration then follows the
# reduced rule (no other server: passes; otherwise a strict majority of however
# many answer, even one). Never for production: it is exactly the single-server
# trust the quorum exists to remove.
allow_no_quorum: bool = False
xprv_encryption_key: str = ""
master_key_path: str = "./master.xprv.enc"
@@ -79,3 +98,33 @@ def validate_runtime_secrets(config: Settings | None = None) -> None:
)
if problems:
raise ConfigError("invalid configuration in .env: " + "; ".join(problems))
def validate_quorum_servers(endpoints: list, config: Settings | None = None) -> None:
"""B-84 (ELC-19): refuse to serve with fewer than MIN_QUORUM_FALLBACK_SERVERS
fallback servers (`endpoints` is the deduplicated rotation: primary first, then the
fallbacks), unless ALLOW_NO_QUORUM=true. The old behaviour — an empty
ELECTRUM_FALLBACK_SERVERS, the .env.example default — silently made every
corroboration pass, i.e. one server decided the draw, the credits and the spends.
Called from the lifespan, after parse_endpoints, rather than from
validate_runtime_secrets: it needs the parsed list, and a Settings validator would
couple every import (tests included) to a populated .env.
"""
config = config or settings
fallbacks = len(endpoints) - 1
if fallbacks >= MIN_QUORUM_FALLBACK_SERVERS:
return
if config.allow_no_quorum:
logger.warning(
"ALLOW_NO_QUORUM=true: only %s fallback Electrum server(s) configured (%s needed) — "
"corroboration is reduced to the weaker rule. Development only, never in production.",
fallbacks,
MIN_QUORUM_FALLBACK_SERVERS,
)
return
raise ConfigError(
f"ELECTRUM_FALLBACK_SERVERS lists {fallbacks} usable fallback server(s) besides the primary, "
f"but at least {MIN_QUORUM_FALLBACK_SERVERS} are required so every corroboration has two independent "
"answers (set ALLOW_NO_QUORUM=true to override, development only)"
)
+55 -3
View File
@@ -1,5 +1,5 @@
from sqlalchemy import event
from sqlalchemy.ext.asyncio import AsyncEngine, async_sessionmaker, create_async_engine
from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
from sqlalchemy.orm import DeclarativeBase
from app.config import settings
@@ -12,6 +12,11 @@ from app.config import settings
_SQLITE_BUSY_TIMEOUT_MS = 5000
# Execution option read by the `begin` event below: which BEGIN a connection's next
# transaction opens with. Set through `begin_immediate`, never by hand.
_BEGIN_MODE_OPTION = "sqlite_begin_mode"
def _register_sqlite_pragmas(target_engine: AsyncEngine) -> None:
"""Without WAL, SQLite's default (rollback-journal) mode lets a writer block
every reader for the duration of its transaction, and a second writer arriving
@@ -21,22 +26,69 @@ def _register_sqlite_pragmas(target_engine: AsyncEngine) -> None:
busy_timeout gives a second writer a real window to wait for the first
instead of an instant `OperationalError`.
B-88: two more things, both about the code's transactions being what it
assumes. `synchronous=FULL`, because with WAL `NORMAL` can lose the last
commits on power loss — a registration, and with it a derivation index that
would then be handed to the next user. And real transaction control: pysqlite's
legacy mode emits `BEGIN` only at the first INSERT/UPDATE/DELETE, so every read
before it ran outside any transaction and the lock wait surfaced as `database is
locked` at an arbitrary later statement. `isolation_level = None` turns the
driver's implicit BEGIN off and the `begin` event emits it ourselves — a plain
`BEGIN` by default, `BEGIN IMMEDIATE` for a transaction opened through
`begin_immediate`, which takes the write lock *before* the first read so that
what a money-moving transaction reads is what it then writes on top of.
No-op for any dialect other than sqlite (e.g. a future PostgreSQL
DATABASE_URL), which neither needs nor understands these pragmas.
DATABASE_URL), which neither needs nor understands any of this.
"""
if target_engine.dialect.name != "sqlite":
return
@event.listens_for(target_engine.sync_engine, "connect")
def _set_sqlite_pragmas(dbapi_connection, connection_record) -> None:
# Before the pragmas: journal_mode cannot change inside a transaction, and in
# legacy mode the driver may have one open.
dbapi_connection.isolation_level = None
cursor = dbapi_connection.cursor()
try:
cursor.execute("PRAGMA journal_mode=WAL")
cursor.execute("PRAGMA synchronous=NORMAL")
cursor.execute("PRAGMA synchronous=FULL") # B-88
cursor.execute(f"PRAGMA busy_timeout={_SQLITE_BUSY_TIMEOUT_MS}")
finally:
cursor.close()
@event.listens_for(target_engine.sync_engine, "begin")
def _emit_begin(conn) -> None: # B-88
mode = conn.get_execution_options().get(_BEGIN_MODE_OPTION, "DEFERRED")
conn.exec_driver_sql("BEGIN IMMEDIATE" if mode == "IMMEDIATE" else "BEGIN")
async def begin_immediate(session: AsyncSession) -> None:
"""B-88: start the session's next transaction with `BEGIN IMMEDIATE`, i.e. take
SQLite's write lock now, before the first read.
Every transaction that moves money or fixes its state calls this first thing, so
that what it reads (balance, free UTXOs, participants, the round's status) cannot
change under it before its own writes, and so that the wait for the lock happens
here — at the very start, before anything has been broadcast — instead of at the
first write. Raises `sqlalchemy.exc.OperationalError` ("database is locked") when
the lock is not granted within `busy_timeout`; the caller decides whether that
means "refuse" (before a broadcast) or "leave it to the reconciler" (after).
A transaction the session already has open is committed first — a lock cannot be
upgraded in place, and the callers open the transaction with nothing but reads
behind them (typically the authentication lookup). Pending, unflushed changes
make that unsafe to do silently, so they are an error.
Harmless on a session whose engine did not go through `_register_sqlite_pragmas`
(the option is simply never read) and on a non-sqlite dialect.
"""
if session.new or session.dirty or session.deleted:
raise RuntimeError("begin_immediate called with unflushed changes on the session")
if session.in_transaction():
await session.commit()
await session.connection(execution_options={_BEGIN_MODE_OPTION: "IMMEDIATE"})
engine = create_async_engine(settings.database_url)
_register_sqlite_pragmas(engine)
+70 -2
View File
@@ -92,6 +92,12 @@ class Round(Base):
# the gap it announced is the gap that's honoured.
duration_seconds: Mapped[int] = mapped_column(default=600, server_default="600")
cooldown_seconds: Mapped[int] = mapped_column(default=30, server_default="30")
# B-80 (DAT-60, RND-35): this round's own pool address, m/84'/746'/0'/2/<id>. The id
# only exists once the row is flushed, so the row is inserted with "" and the real
# address is written in the same transaction (rounds/service.py:open_new_round_if_needed)
# — "" is never visible outside it, and every consumer refuses it. Rounds opened before
# B-80 hold the reserve address (m/84'/746'/0'/1/0), their old shared pool.
pool_address: Mapped[str] = mapped_column(String(128), default="", server_default="")
# Set once, when status flips to "drawing" (rounds/scheduler.py:_close_and_draw).
# Lets both the audit log (B-36's draw_stalled entries) and GET /rounds/current
# (draw_waiting_since) measure how long a round has been waiting on a block,
@@ -105,20 +111,48 @@ class Round(Base):
winner_amount_sats: Mapped[int | None] = mapped_column(BigInteger, default=None)
fee_amount_sats: Mapped[int | None] = mapped_column(BigInteger, default=None)
payout_txid: Mapped[str | None] = mapped_column(String(64), default=None)
# B-73 (DAT-61, DAT-64, DAT-65): the commit-reveal draw. `server_seed_enc` is the round's
# 32-byte secret Fernet-encrypted with the master-xprv key, written at open together with
# `server_seed_hash` (sha256 of the secret, published from then on); the plaintext
# `server_seed` stays NULL until the reveal, in the transaction that stores the winner (or
# at the close of a round without participants), so a copy of the database alone never
# tells who will win. `participants_hash`, `draw_height` and each participant's
# `draw_position` are written when the round enters "drawing" and never change — what a
# resumed draw (B-81) reads instead of recomputing. `draw_confirmations` is the number of
# blocks the chain must have from `draw_height` before its hash is read, copied from the
# config at open.
draw_confirmations: Mapped[int] = mapped_column(default=3, server_default="3")
server_seed_enc: Mapped[str | None] = mapped_column(Text, default=None)
server_seed: Mapped[str | None] = mapped_column(String(64), default=None)
server_seed_hash: Mapped[str | None] = mapped_column(String(64), default=None)
participants_hash: Mapped[str | None] = mapped_column(String(64), default=None)
draw_height: Mapped[int | None] = mapped_column(default=None)
class RoundParticipant(Base):
__tablename__ = "round_participants"
__table_args__ = (UniqueConstraint("round_id", "user_id"),)
__table_args__ = (
UniqueConstraint("round_id", "user_id"),
# B-73 (DAT-66): one draw position per participant; NULLs (not yet in an ordered
# list) do not collide.
Index("ux_round_participants_round_draw_position", "round_id", "draw_position", unique=True),
)
id: Mapped[int] = mapped_column(primary_key=True)
round_id: Mapped[int] = mapped_column(ForeignKey("rounds.id"), index=True)
user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), index=True)
bet_amount_sats: Mapped[int] = mapped_column(BigInteger)
bet_txid: Mapped[str] = mapped_column(String(64))
# Ordering / tie-break field per spec: broadcast time, not confirmation time.
# B-73 (DAT-63): which output of the bet transaction pays the round's pool address —
# together with bet_txid the outpoint the draw list publishes and the payout spends.
bet_vout: Mapped[int] = mapped_column(default=0, server_default="0")
# Informational only since B-73 (DAT-25): the draw order is by bet_txid, which anyone
# can check, not by this server-side timestamp.
broadcast_at: Mapped[datetime] = mapped_column(default=utcnow)
confirmed_at: Mapped[datetime | None] = mapped_column(default=None)
# B-73 (DAT-66): 0-based position in the ordered draw list, written once on entering
# "drawing" for every confirmed participant.
draw_position: Mapped[int | None] = mapped_column(default=None)
status: Mapped[str] = mapped_column(String(16), default="broadcast")
@@ -143,12 +177,22 @@ class RoundConfig(Base):
# NOT gate the actual draw, which still waits for a real confirmed block for
# its entropy (rounds/scheduler.py) — that can take longer than this value.
draw_animation_seconds: Mapped[int] = mapped_column(default=20)
# B-73 (DAT-62): blocks the chain must have from a round's draw_height before the hash
# of that block is read; copied onto each round when it opens (DAT-61), so an edit
# applies from the next round.
draw_confirmations: Mapped[int] = mapped_column(default=3, server_default="3")
fee_rate_sat_vb: Mapped[int] = mapped_column(default=1)
rbf_timeout_seconds: Mapped[int] = mapped_column(default=900)
# Maintenance switch: when true, the round currently in progress still runs to
# completion (closes, draws, pays out the winner) but no new round is opened
# afterwards — see rounds/service.py:open_new_round_if_needed.
paused: Mapped[bool] = mapped_column(default=False)
# B-78 (DAT-69): why the lottery is paused — NULL exactly when `paused` is false.
# "operator" (POST /admin/pause) or an automatic reason the system wrote itself
# ("resurrected_tx" so far; "reorg" and "payout_blocked" belong to B-85 and B-82).
# An automatic reason is never overwritten by an operator pause, so the cause that
# needs a look is not lost; POST /admin/resume clears whichever it is.
paused_reason: Mapped[str | None] = mapped_column(String(16), default=None)
updated_at: Mapped[datetime] = mapped_column(default=utcnow, onupdate=utcnow)
@@ -191,9 +235,33 @@ class PendingTransaction(Base):
attempt_count: Mapped[int] = mapped_column(default=1)
# Why the reconciler gave up on this tx — operator-facing, only set on "failed".
failure_reason: Mapped[str | None] = mapped_column(String(128), default=None)
# B-78 (DAT-72): when the row went to "failed". A failed row stays watched for
# FAILED_WATCH_DAYS from here: a transaction given up for dead can still confirm.
failed_at: Mapped[datetime | None] = mapped_column(default=None)
updated_at: Mapped[datetime] = mapped_column(default=utcnow, onupdate=utcnow)
class PendingTransactionTxid(Base):
"""Every version a PendingTransaction has ever had (B-77, DAT-70, DAT-71): the first
one, each RBF replacement and each candidate written before a bump is broadcast.
The network may confirm *any* of them — the original while a bump was in flight, a
replacement the process crashed before recording — so the poller and the reconciler
look for every txid of a row, not only `current_txid`. Rows are never modified or
deleted (except with the `bet` row `_release_failed_bet` removes); `txid` is unique
over the whole table, so a txid belongs to exactly one platform transaction.
`raw_hex` is empty only for a `replaced_by_txid` reconstructed by the migration,
whose raw transaction is no longer available."""
__tablename__ = "pending_transaction_txids"
id: Mapped[int] = mapped_column(primary_key=True)
pending_transaction_id: Mapped[int] = mapped_column(ForeignKey("pending_transactions.id"), index=True)
txid: Mapped[str] = mapped_column(String(64), unique=True)
raw_hex: Mapped[str] = mapped_column(Text)
created_at: Mapped[datetime] = mapped_column(default=utcnow)
class Withdrawal(Base):
__tablename__ = "withdrawals"
+58 -3
View File
@@ -4,9 +4,11 @@ from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from app.audit.log import write_audit_log
from app.db.base import begin_immediate
from app.db.models import UtxoEvent
from app.rounds.events import broadcaster
from app.wallet.balance import recompute_balance
from app.wallet.psbt_builder import DUST_LIMIT_SATS
logger = logging.getLogger(__name__)
@@ -14,7 +16,7 @@ logger = logging.getLogger(__name__)
async def find_new_credit_candidates(session: AsyncSession, user_id: int, entries: list[dict]) -> list[dict]:
"""The subset of `entries` that would actually credit something: confirmed
(height > 0, per the Electrum convention where <= 0 means mempool) and not
already recorded.
already recorded, and not dust (B-75: below DUST_LIMIT_SATS nothing is credited).
Split out from credit_confirmed_utxos so the caller
(electrum/listener.py:refresh_user) can corroborate each *new* outpoint
@@ -33,7 +35,9 @@ async def find_new_credit_candidates(session: AsyncSession, user_id: int, entrie
return [
entry
for entry in entries
if entry["height"] > 0 and (entry["tx_hash"], entry["tx_pos"]) not in existing_keys
if entry["height"] > 0
and entry["value"] >= DUST_LIMIT_SATS # B-75 (DEP-01)
and (entry["tx_hash"], entry["tx_pos"]) not in existing_keys
]
@@ -45,7 +49,12 @@ async def credit_confirmed_utxos(session: AsyncSession, user_id: int, entries: l
entries: [{"tx_hash": ..., "tx_pos": ..., "height": ..., "value": ...}, ...]
height <= 0 means unconfirmed (mempool) per the Electrum protocol convention —
skipped, since the spec requires 1 confirmation before crediting.
B-88: opens with BEGIN IMMEDIATE, so the "already recorded?" read and the inserts
it guards are one transaction — the unique (txid, vout) constraint stays the
backstop, not the mechanism.
"""
await begin_immediate(session)
existing_keys = {
(txid, vout)
for txid, vout in (
@@ -57,6 +66,11 @@ async def credit_confirmed_utxos(session: AsyncSession, user_id: int, entries: l
for entry in entries:
if entry["height"] <= 0:
continue
if entry["value"] < DUST_LIMIT_SATS:
# B-75 (DEP-01): anyone can send dust to a public address; crediting it would
# make every later refresh of this user's address do more work, for coins
# that cost more to spend than they are worth.
continue
key = (entry["tx_hash"], entry["tx_pos"])
if key in existing_keys:
continue
@@ -89,15 +103,55 @@ async def credit_confirmed_utxos(session: AsyncSession, user_id: int, entries: l
_EXTERNAL_SPEND_SENTINEL = "external-spend"
async def find_reinstate_candidates(session: AsyncSession, user_id: int, entries: list[dict]) -> list[dict]:
"""Outpoints flagged as spent outside the platform that this refresh's `listunspent`
lists again, confirmed and for the amount we recorded — the *candidates* for
reinstatement (B-83, DEP-02, DEP-08). Read-only: like a new credit (B-59) and a
candidate external spend (B-29), a reinstatement moves a balance, so the caller
(electrum/listener.py:refresh_user) must have the other servers corroborate each
candidate before reinstate_reappeared_utxos writes it. An entry whose amount differs
from our record is not a candidate: it is not the coin we wrote off."""
flagged = (
await session.scalars(
select(UtxoEvent).where(UtxoEvent.user_id == user_id, UtxoEvent.spent_txid == _EXTERNAL_SPEND_SENTINEL)
)
).all()
amounts = {(row.txid, row.vout): row.amount_sats for row in flagged}
return [
entry
for entry in entries
if amounts.get((entry["tx_hash"], entry["tx_pos"])) == entry.get("value") and (entry.get("height") or 0) > 0
]
async def reinstate_reappeared_utxos(session: AsyncSession, user_id: int, entries: list[dict]) -> int:
"""The reverse of a mark applied by find_utxos_missing_from/
mark_utxos_spent_externally (B-29): if an outpoint we'd previously flagged as
spent outside the platform reappears as unspent in a later listunspent, undo
the mark instead of leaving it permanent no matter what the chain says
afterwards. Cheap and purely DB-side — always safe to run on every refresh.
afterwards.
Persistence only, for entries the caller has **already corroborated** against the
other servers (B-83, ELC-25) — it used to run on the active server's word alone, so a
hostile one could put a spent coin back into a balance. Re-checks, under the write
lock, that each row still carries the mark before clearing it (DEP-08).
"""
current_keys = {(entry["tx_hash"], entry["tx_pos"]) for entry in entries}
# B-88: the lock is only worth taking when there is something to write, and this
# runs on every refresh — so look first (plain columns), then take it and read the
# rows again under it.
flagged = (
await session.execute(
select(UtxoEvent.txid, UtxoEvent.vout).where(
UtxoEvent.user_id == user_id, UtxoEvent.spent_txid == _EXTERNAL_SPEND_SENTINEL
)
)
).all()
if not any((txid, vout) in current_keys for txid, vout in flagged):
return 0
await begin_immediate(session)
marked_rows = (
await session.scalars(
select(UtxoEvent).where(
@@ -178,6 +232,7 @@ async def mark_utxos_spent_externally(session: AsyncSession, user_id: int, utxo_
may have resolved it (a legitimate platform spend, or a prior refresh) between
when the caller read the candidate list and finished corroborating it.
"""
await begin_immediate(session) # B-88: that re-check and the mark are one transaction
marked = 0
for utxo_id in utxo_ids:
row = await session.get(UtxoEvent, utxo_id)
+186 -24
View File
@@ -1,57 +1,104 @@
import asyncio
import hashlib
import itertools
import json
import logging
import re
import ssl
from typing import NamedTuple
logger = logging.getLogger(__name__)
class ElectrumEndpoint(NamedTuple):
"""One server to connect to. The listener rotates over a list of these so a
single unreachable or misbehaving server doesn't take the platform down —
every consumer of PLM chain data goes through this one connection."""
every consumer of PLM chain data goes through this one connection.
`pin` (B-84, ELC-03) is the SHA-256 of the server's DER certificate, in lower-case
hex; when set, a connection presenting any other certificate fails like an
unreachable server. Only meaningful with TLS."""
host: str
port: int
use_ssl: bool = True
pin: str | None = None
def __str__(self) -> str:
return f"{self.host}:{self.port}{'' if self.use_ssl else ' (plaintext)'}"
return f"{self.host}:{self.port}{'' if self.use_ssl else ' (plaintext)'}{' (pinned)' if self.pin else ''}"
_PIN_PATTERN = re.compile(r"[0-9a-f]{64}")
def normalize_pin(raw: str, entry: str) -> str:
"""A certificate pin as lower-case hex, or ValueError: 64 hexadecimal digits."""
pin = raw.strip().lower()
if not _PIN_PATTERN.fullmatch(pin):
raise ValueError(f"invalid certificate pin in Electrum server {entry!r}: expected 64 hex digits (sha256)")
return pin
def parse_endpoints(
primary_host: str, primary_port: int, primary_use_ssl: bool, fallback_spec: str
primary_host: str,
primary_port: int,
primary_use_ssl: bool,
fallback_spec: str,
primary_pin: str = "",
) -> list[ElectrumEndpoint]:
"""Build the connection rotation: the primary server first, then whatever
ELECTRUM_FALLBACK_SERVERS lists.
`fallback_spec` is comma-separated, each entry `host:port` (TLS, the normal
case) or `host:port:notls`. Malformed entries raise ValueError rather than
being skipped: a typo in a fallback server is something to fix at startup,
not to discover during an outage, when the fallback is what's needed.
case), `host:port:notls`, `host:port:pin=<sha256>` (TLS with a pinned certificate,
B-84) or `host:port:notls`/`ssl`/`tls` followed by `:pin=<sha256>`. A pin on a
plaintext entry is refused: there is no certificate to pin. `primary_pin` is the
same pin for the primary (ELECTRUM_CERT_PIN). Malformed entries raise ValueError
rather than being skipped: a typo in a fallback server is something to fix at
startup, not to discover during an outage, when the fallback is what's needed.
Duplicates are dropped, keeping first position.
"""
endpoints = [ElectrumEndpoint(primary_host, primary_port, primary_use_ssl)]
syntax = "expected host:port[:notls][:pin=<sha256>]"
pin = normalize_pin(primary_pin, "ELECTRUM_CERT_PIN") if primary_pin.strip() else None
if pin and not primary_use_ssl:
raise ValueError("ELECTRUM_CERT_PIN needs TLS: ELECTRUM_USE_SSL is off")
endpoints = [ElectrumEndpoint(primary_host, primary_port, primary_use_ssl, pin)]
for raw in fallback_spec.split(","):
entry = raw.strip()
if not entry:
continue
parts = entry.split(":")
if len(parts) not in (2, 3):
raise ValueError(f"invalid Electrum server {entry!r}: expected host:port[:notls]")
if not 2 <= len(parts) <= 4:
raise ValueError(f"invalid Electrum server {entry!r}: {syntax}")
host, port = parts[0].strip(), parts[1].strip()
if not host or not port.isdigit():
raise ValueError(f"invalid Electrum server {entry!r}: expected host:port[:notls]")
raise ValueError(f"invalid Electrum server {entry!r}: {syntax}")
use_ssl = True
if len(parts) == 3:
flag = parts[2].strip().lower()
if flag not in ("ssl", "tls", "notls", "plain"):
pin = None
mode_seen = False
for extra in parts[2:]:
extra = extra.strip()
if extra.lower().startswith("pin="):
if pin is not None:
raise ValueError(f"invalid Electrum server {entry!r}: more than one pin")
pin = normalize_pin(extra[4:], entry)
continue
flag = extra.lower()
if mode_seen or flag not in ("ssl", "tls", "notls", "plain"):
raise ValueError(f"invalid TLS flag {flag!r} in Electrum server {entry!r}")
mode_seen = True
use_ssl = flag in ("ssl", "tls")
endpoints.append(ElectrumEndpoint(host, int(port), use_ssl))
if pin and not use_ssl:
raise ValueError(f"invalid Electrum server {entry!r}: a pin needs TLS")
endpoints.append(ElectrumEndpoint(host, int(port), use_ssl, pin))
deduped: list[ElectrumEndpoint] = []
seen: set[tuple] = set()
for endpoint in endpoints:
if endpoint not in deduped:
key = (endpoint.host, endpoint.port, endpoint.use_ssl)
if key not in seen:
seen.add(key)
deduped.append(endpoint)
return deduped
@@ -64,11 +111,37 @@ def parse_endpoints(
# and the confirmation poller could stop polling permanently.
_REQUEST_TIMEOUT_SECONDS = 15
# Longest reply line the client accepts (B-75, ELC-20). asyncio's default StreamReader
# limit is 64 KiB, and a longer line used to raise out of the read loop and close the
# only connection: the pool address's get_history passed that after ~800 transactions
# (and a few hundred dust outputs sent to any public address do it on purpose), after
# which every confirmation poll dropped the connection and payouts never confirmed.
_MAX_LINE_BYTES = 16 * 1024 * 1024
_READ_CHUNK_BYTES = 64 * 1024
# How much of each end of a discarded line is kept to find the reply's `id` in, so the
# request it answered can fail at once instead of waiting out the 15s timeout.
_ID_SNIFF_BYTES = 256
_ID_PATTERN = re.compile(rb'"id"\s*:\s*(\d+)')
class ElectrumError(Exception):
pass
class ElectrumRpcError(ElectrumError):
"""The server *answered* with a JSON-RPC `error` object (B-76, TX-04). It is the
only failure that says anything about the request itself: a timeout, a dropped
connection or a write error (plain ElectrumError) leaves it unknown whether the
server ever acted on it. `args[0]` is the error object as the server sent it."""
@property
def message(self) -> str:
detail = self.args[0] if self.args else ""
if isinstance(detail, dict):
return str(detail.get("message", detail))
return str(detail)
class ElectrumClient:
"""Minimal asyncio Electrum protocol client: line-delimited JSON-RPC over TLS.
@@ -83,10 +156,11 @@ class ElectrumClient:
notification queues nobody will ever fill again.
"""
def __init__(self, host: str, port: int, use_ssl: bool = True):
def __init__(self, host: str, port: int, use_ssl: bool = True, pin: str | None = None):
self.host = host
self.port = port
self.use_ssl = use_ssl
self.pin = pin.lower() if pin else None
self._reader: asyncio.StreamReader | None = None
self._writer: asyncio.StreamWriter | None = None
self._id_counter = itertools.count(1)
@@ -98,16 +172,36 @@ class ElectrumClient:
async def connect(self) -> None:
# Electrum servers commonly present self-signed certs; the protocol's trust
# model is server consensus, not TLS PKI, so we only use SSL for transport
# encryption and don't verify the certificate chain/hostname.
# encryption and don't verify the certificate chain/hostname. What can be
# asked instead is that the certificate be *the* one the operator pinned
# (B-84, ELC-03): without a pin, whoever sits on the path to a server takes
# its place, and only the quorum stands between that and the draw.
ssl_context = None
if self.use_ssl:
ssl_context = ssl.create_default_context()
ssl_context.check_hostname = False
ssl_context.verify_mode = ssl.CERT_NONE
self._reader, self._writer = await asyncio.open_connection(self.host, self.port, ssl=ssl_context)
self._reader, self._writer = await asyncio.open_connection(
self.host, self.port, ssl=ssl_context, limit=_MAX_LINE_BYTES
)
if self.pin:
try:
self._check_pin()
except ElectrumError:
self._writer.close()
raise
self._read_task = asyncio.create_task(self._read_loop())
await self.request("server.version", ["plm-lottery", "1.4"])
def _check_pin(self) -> None:
"""The server's DER certificate must hash to the pinned SHA-256 (B-84, ELC-03)."""
ssl_object = self._writer.get_extra_info("ssl_object") if self._writer is not None else None
der = ssl_object.getpeercert(binary_form=True) if ssl_object is not None else None
if not der:
raise ElectrumError(f"{self.host}:{self.port} presented no certificate to check against the pin")
if hashlib.sha256(der).hexdigest() != self.pin:
raise ElectrumError(f"{self.host}:{self.port} certificate does not match the configured pin")
async def close(self) -> None:
self._closed.set()
if self._read_task is not None:
@@ -186,17 +280,58 @@ class ElectrumClient:
async def get_transaction(self, txid: str, verbose: bool = False) -> object:
return await self.request("blockchain.transaction.get", [txid, verbose])
async def get_merkle(self, txid: str, height: int) -> dict:
"""The merkle branch proving `txid` is in the block at `height` (B-83, ELC-26)."""
return await self.request("blockchain.transaction.get_merkle", [txid, height])
async def get_block_header(self, height: int) -> str:
return await self.request("blockchain.block.header", [height])
async def get_block_headers(self, start_height: int, count: int) -> dict:
"""`count` consecutive headers from `start_height` (B-74, ELC-12), as the server's
{"count", "hex", "max"}: `hex` is the 80-byte headers concatenated, and the server
may return fewer than asked (never more than its `max`)."""
return await self.request("blockchain.block.headers", [start_height, count])
async def _read_loop(self) -> None:
"""Frame the stream into lines by hand rather than with StreamReader.readline:
readline raises on a line over the limit, and that exception used to end this
loop and with it the connection. An oversized line is now dropped up to its
newline (B-75, ELC-20) and the connection stays up."""
assert self._reader is not None
buffer = bytearray()
discarding = False
head = b""
tail = b""
try:
while True:
line = await self._reader.readline()
if not line:
chunk = await self._reader.read(_READ_CHUNK_BYTES)
if not chunk:
break
message = json.loads(line)
self._dispatch(message)
while chunk:
newline = chunk.find(b"\n")
piece = chunk if newline < 0 else chunk[:newline]
chunk = b"" if newline < 0 else chunk[newline + 1 :]
if discarding:
tail = (tail + piece)[-_ID_SNIFF_BYTES:]
else:
buffer += piece
if len(buffer) > _MAX_LINE_BYTES:
discarding = True
head = bytes(buffer[:_ID_SNIFF_BYTES])
tail = bytes(buffer[-_ID_SNIFF_BYTES:])
buffer.clear()
if newline >= 0:
if discarding:
self._fail_unreadable_reply(head + b" " + tail, "reply exceeds the line limit")
discarding = False
else:
self._handle_line(bytes(buffer))
buffer.clear()
if buffer and not discarding:
self._handle_line(bytes(buffer)) # a final line the server never terminated
finally:
# Whatever ended this loop — clean EOF, protocol error, TLS failure — the
# Whatever ended this loop — clean EOF, TLS failure — the
# connection is unusable from here on. Setting this is what makes the
# death observable to wait_closed(), and so to the listener's reconnect
# logic; without it the listener waited on notification queues nobody
@@ -208,6 +343,33 @@ class ElectrumClient:
future.set_exception(error)
self._pending.clear()
def _handle_line(self, line: bytes) -> None:
if not line.strip():
return
try:
message = json.loads(line)
except ValueError:
# A reply that is not JSON is a problem of that one request, not of the
# connection (B-75).
self._fail_unreadable_reply(line[:_ID_SNIFF_BYTES] + b" " + line[-_ID_SNIFF_BYTES:], "reply is not valid JSON")
return
if not isinstance(message, dict):
logger.warning("ignoring an Electrum message that is not a JSON object")
return
self._dispatch(message)
def _fail_unreadable_reply(self, sample: bytes, reason: str) -> None:
"""Fail the request an unusable reply belongs to, when its `id` can be read
from `sample` (the first and last bytes of the line); otherwise that request
fails by its own timeout (ELC-04)."""
logger.warning("dropping an unusable Electrum reply: %s", reason)
for match in _ID_PATTERN.finditer(sample):
future = self._pending.pop(int(match.group(1)), None)
if future is not None:
if not future.done():
future.set_exception(ElectrumError(reason))
return
def _dispatch(self, message: dict) -> None:
message_id = message.get("id")
if message_id is not None and message_id in self._pending:
@@ -215,7 +377,7 @@ class ElectrumClient:
if future.done():
return
if message.get("error"):
future.set_exception(ElectrumError(message["error"]))
future.set_exception(ElectrumRpcError(message["error"]))
else:
future.set_result(message.get("result"))
elif "method" in message:
+557 -84
View File
@@ -1,19 +1,28 @@
import asyncio
import logging
import time
from collections import Counter
from collections.abc import Callable
from embit.transaction import Transaction
from sqlalchemy import select
from sqlalchemy.ext.asyncio import async_sessionmaker
from app.audit.log import write_audit_log
from app.db.base import begin_immediate
from app.db.models import User
from app.deposits.service import (
credit_confirmed_utxos,
find_new_credit_candidates,
find_reinstate_candidates,
find_utxos_missing_from,
mark_utxos_spent_externally,
reinstate_reappeared_utxos,
)
from app.electrum.client import ElectrumClient, ElectrumEndpoint
from app.config import MIN_QUORUM_RESPONSES
from app.electrum.client import ElectrumClient, ElectrumEndpoint, ElectrumRpcError
from app.electrum.merkle import proof_matches_header
from app.electrum.quorum import ServerAnswers
from app.electrum.scripthash import address_to_scripthash
from app.rounds.draw import (
HeaderValidationError,
@@ -22,6 +31,7 @@ from app.rounds.draw import (
header_prev_hash,
)
from app.rounds.events import broadcaster
from app.rounds.pause import pause_automatically
logger = logging.getLogger(__name__)
@@ -41,6 +51,31 @@ _CORROBORATION_TIMEOUT_SECONDS = 10
# of simultaneous in-flight requests against the one active connection.
_RESUBSCRIBE_CONCURRENCY = 20
# How many of the latest accepted headers the listener keeps (B-74/B-85, ELC-22): what lets
# it recognise a reorganisation and walk back to its fork point instead of mistaking it for
# a hostile server. Also the deepest fork it will follow.
_HEADER_WINDOW = 10
# B-86 (ELC-21): a connected server whose last accepted header is older than this is asked
# about by comparing its tip with the other servers' at every ping. Three block times of
# 120s: late enough that an ordinary slow stretch of the chain does not trigger the check.
_STALL_SECONDS = 360
# The clock the stall check reads — a module attribute so a test can move time.
_monotonic = time.monotonic
# A reorganisation at least this deep pauses the lottery (B-85, ELC-24): one block is
# ordinary on any chain, two or more is worth a look before a new round opens.
_REORG_PAUSE_DEPTH = 2
# `blockchain.block.headers` serves at most this many headers per request (ELC-12).
_MAX_HEADERS_PER_REQUEST = 2016
class ServerStalledError(Exception):
"""The active server stopped following the chain while others report a higher tip
(B-86, ELC-21). Ends the session like a dropped connection, so run() rotates."""
class ElectrumListener:
"""Long-lived background task: keeps one Electrum connection open, subscribes
@@ -63,10 +98,13 @@ class ElectrumListener:
client_factory: Callable[[ElectrumEndpoint], ElectrumClient],
session_factory: async_sessionmaker,
endpoints: list[ElectrumEndpoint] | None = None,
allow_no_quorum: bool = False,
):
self._client_factory = client_factory
self._session_factory = session_factory
self._endpoints = list(endpoints or [])
# B-84 (ELC-19): ALLOW_NO_QUORUM, development only — see _corroborate_majority.
self._allow_no_quorum = allow_no_quorum
self._endpoint_index = 0
self._scripthash_to_user: dict[str, int] = {}
# Retains address_for_new_user's fire-and-forget subscribe task so it
@@ -76,6 +114,11 @@ class ElectrumListener:
self._background_tasks: set[asyncio.Task] = set()
self.tip_height: int = 0
self.tip_header_hex: str | None = None
# B-74 (ELC-22): height -> header of the last _HEADER_WINDOW accepted headers, tip
# included. Survives reconnections, not restarts.
self._window: dict[int, str] = {}
# B-86: when the last header was accepted (monotonic seconds), None until one is.
self._last_header_at: float | None = None
self.client: ElectrumClient | None = None
@property
@@ -164,7 +207,7 @@ class ElectrumListener:
try:
header = await client.subscribe_headers()
self._apply_header(header)
await self._apply_header(header, client)
if self.tip_header_hex is None:
# B-64: the header was unusable (no hex) and we have never had a tip,
# so publishing this client would hand every consumer a connection
@@ -193,7 +236,7 @@ class ElectrumListener:
# keepalive are what make the drop observable. Whichever finishes first
# ends the session and sends run() around to the next server.
tasks = [
asyncio.create_task(self._consume_headers(headers_queue)),
asyncio.create_task(self._consume_headers(headers_queue, client)),
asyncio.create_task(self._consume_scripthash(scripthash_queue)),
asyncio.create_task(self._keepalive(client)),
asyncio.create_task(client.wait_closed()),
@@ -239,6 +282,29 @@ class ElectrumListener:
while True:
await asyncio.sleep(_PING_INTERVAL_SECONDS)
await client.ping() # raises (and so ends the session) on timeout or a dead socket
await self._check_not_stalled()
async def _check_not_stalled(self) -> None:
"""B-86 (ELC-21): `server.ping` keeps succeeding on a server that has stopped
following the chain, so liveness alone never replaced one. When the last accepted
header is older than _STALL_SECONDS, ask every *other* server for its tip
(`blockchain.headers.subscribe`, with ELC-14's timeouts): if any reports a higher one
than we know, this session ends and the listener moves to the next server. If none
does, the network simply produced no block and the session goes on."""
if self._last_header_at is None or _monotonic() - self._last_header_at <= _STALL_SECONDS:
return
async def _tip_height(client: ElectrumClient) -> int | None:
header = await client.subscribe_headers()
height = header.get("height") if isinstance(header, dict) else None
return height if isinstance(height, int) else None
heights = [h for h in await self._ask_other_servers(_tip_height) if h is not None]
if any(height > self.tip_height for height in heights):
raise ServerStalledError(
f"no header accepted for {_monotonic() - self._last_header_at:.0f}s while another server "
f"reports tip {max(heights)} (ours: {self.tip_height})"
)
async def _subscribe_all_users(self) -> None:
"""B-31: subscribes with bounded concurrency (_RESUBSCRIBE_CONCURRENCY at
@@ -268,29 +334,27 @@ class ElectrumListener:
await self.client.subscribe_scripthash(scripthash)
await self.refresh_user(user_id, scripthash)
def _apply_header(self, header: dict) -> None:
"""Record a new chain tip, refusing to move backwards or sideways.
async def _apply_header(self, header: dict, client: ElectrumClient | None = None) -> None:
"""Record a new chain tip after checking it (ELC-08 … ELC-13, ELC-22, ELC-23).
Full reorg handling is out of scope for v1 by explicit design decision, but
the tip must never regress: `_wait_for_next_block` waits for
`tip_height > tip_at_close`, so a lower height would silently add a block to
the draw's wait. height and hex are applied together or not at all —
applying a losing header's hex would leave tip_height and tip_header_hex
describing different blocks, and that hex is the draw's entropy source.
The tip never regresses, and `tip_height`/`tip_header_hex` always describe the
same block: they are applied together or not at all, since that hex is where a
draw's entropy comes from. A header that is ignored (no hex, below the tip, the
tip itself again) changes nothing and ends nothing.
Two validation checks guard against a hostile or MITM'd server simply
fabricating a header (B-28), since that header is the draw's sole source of
entropy: it must satisfy the difficulty target it claims for itself, and —
when it's a direct single-block advance from our own current tip, the only
case we can check without a full header chain — it must chain from that
tip's hash. Either failure raises HeaderValidationError rather than
silently ignoring the header, which (via _consume_headers/_run_once) ends
this session the same way a dropped connection would, so run() rotates to
the next configured server instead of continuing to trust this one.
Everything else must be proven, because a forged header steers a draw (B-28):
it must meet the target it claims *and* that target must be no easier than
PLM's powLimit (B-74, ELC-11), and every advance must be linked to the tip we
hold (ELC-12) — a single block by its `prev_hash`, a jump of several by
downloading the headers in between from `client` and checking each. A header that
fails these raises HeaderValidationError, which (via _consume_headers/_run_once)
ends this session like a dropped connection and rotates to the next server.
Two more headers are refused without ending the session, since neither is
evidence of a hostile server the way the above are (B-64): one carrying no
hex, and one at the height we already hold a header for.
A header that merely does not *join* our tip is not hostile in itself: it is a
reorganisation, and is followed back to its fork point inside the last
_HEADER_WINDOW headers (B-74, ELC-23) instead of ending the session on every
server until the next block arrives. `client` is the active connection the
missing headers are fetched from.
"""
height = header["height"]
header_hex = header.get("hex")
@@ -310,7 +374,7 @@ class ElectrumListener:
)
return
if height < self.tip_height:
if self.tip_header_hex is not None and height < self.tip_height:
logger.warning(
"ignoring Electrum header at height %s, below the current tip %s (reorg or server switch?)",
height,
@@ -318,38 +382,159 @@ class ElectrumListener:
)
return
if height == self.tip_height and self.tip_header_hex:
# B-64: a second header for the height we already hold one for. Either the
# same block re-announced (nothing to do) or a competing one — a reorg at
# the tip, or a server swapping out the very hash a draw may be about to
# use. The linkage check above cannot speak to this case at all, since
# there is no height advance to check. Whichever it is, the hash committed
# to for a height is not replaced under us: if ours turns out to be the
# orphan, corroborate_header (B-28) refuses to seed a draw from it and the
# draw waits for a further block instead.
if header_hex != self.tip_header_hex:
logger.warning(
"ignoring a competing header at the current tip height %s "
"(reorg at the tip, or a server disagreeing with the rest)",
height,
)
if self.tip_header_hex is not None and height == self.tip_height:
if header_hex == self.tip_header_hex:
return # the same block announced again
# B-85 (ELC-09): another block at the height we hold — a reorg at the tip. It is
# followed like any other fork (it must bring the work and the chain to show for
# it), not ignored: ignoring it left us on an orphan for as long as the tip
# stood, and a draw seeded from it would have been refused by the quorum.
await self._follow_reorg(height, header_hex, client)
return
if not header_meets_its_own_target(header_hex):
raise HeaderValidationError(
f"header at height {height} does not satisfy its own claimed difficulty target"
)
if (
self.tip_header_hex
and height == self.tip_height + 1
and header_prev_hash(header_hex) != header_hex_to_block_hash(self.tip_header_hex)
):
raise HeaderValidationError(
f"header at height {height} does not chain from the current tip (height {self.tip_height})"
f"header at height {height} is not a valid proof of work "
"(its hash misses the target it claims, or the target is easier than the powLimit)"
)
self.tip_height = height
self.tip_header_hex = header_hex
if self.tip_header_hex is None:
await self._adopt_first_header(height, header_hex, client)
return
tip_hash = header_hex_to_block_hash(self.tip_header_hex)
if height == self.tip_height + 1:
if header_prev_hash(header_hex) == tip_hash:
self._extend_window([(height, header_hex)])
return
await self._follow_reorg(height, header_hex, client)
return
# A jump of several blocks (a reconnect, a server that was ahead of us): link it to
# the tip by fetching what lies in between — an unlinked jump used to be accepted
# on the strength of its own difficulty alone.
if client is None:
raise HeaderValidationError(f"cannot link the header at height {height} to the tip: no connection to fetch from")
between = await self._fetch_headers(client, self.tip_height + 1, height - self.tip_height - 1)
chain = [*between, header_hex]
self._check_chained(chain, header_prev_hash(chain[0])) # internal linkage and work only
if header_prev_hash(chain[0]) != tip_hash:
await self._follow_reorg(height, header_hex, client)
return
self._extend_window([(self.tip_height + 1 + i, h) for i, h in enumerate(chain)])
async def _fetch_headers(self, client: ElectrumClient, start: int, count: int) -> list[str]:
"""`count` headers from `start` (blockchain.block.headers, at most
_MAX_HEADERS_PER_REQUEST per request). A server that returns fewer than it must,
or something that is not whole 80-byte headers, ends the session."""
headers: list[str] = []
while len(headers) < count:
wanted = min(count - len(headers), _MAX_HEADERS_PER_REQUEST)
reply = await client.get_block_headers(start + len(headers), wanted)
got = reply.get("count") if isinstance(reply, dict) else None
raw = reply.get("hex") if isinstance(reply, dict) else None
if not isinstance(got, int) or not isinstance(raw, str) or not 0 < got <= wanted or len(raw) != got * 160:
raise HeaderValidationError(
f"the server returned an unusable reply for headers {start + len(headers)}..+{wanted}"
)
headers.extend(raw[i : i + 160] for i in range(0, len(raw), 160))
return headers
@staticmethod
def _check_chained(headers: list[str], prev_hash: str) -> None:
"""Every header carries valid work and each one builds on the one before it, the
first on `prev_hash` (ELC-11, ELC-12). Raises HeaderValidationError."""
for header_hex in headers:
if not header_meets_its_own_target(header_hex):
raise HeaderValidationError("a downloaded header is not a valid proof of work")
if header_prev_hash(header_hex) != prev_hash:
raise HeaderValidationError("the downloaded headers are not a connected chain")
prev_hash = header_hex_to_block_hash(header_hex)
def _extend_window(self, entries: list[tuple[int, str]]) -> None:
"""Make `entries` (consecutive heights, the last the new tip) part of the window,
replacing anything at or above their first height, and move the tip with it."""
first = entries[0][0]
for stale in [h for h in self._window if h >= first]:
del self._window[stale]
self._window.update(entries)
for old in sorted(self._window)[:-_HEADER_WINDOW]:
del self._window[old]
self.tip_height, self.tip_header_hex = entries[-1]
self._last_header_at = _monotonic()
async def _adopt_first_header(self, height: int, header_hex: str, client: ElectrumClient | None) -> None:
"""The process's first header has nothing to join, so it is taken on its work alone
— and the (up to) 9 headers before it are downloaded and must chain into it,
which is what the window of ELC-22 is made of."""
entries: list[tuple[int, str]] = []
if client is not None and height > 0:
count = min(_HEADER_WINDOW - 1, height)
before = await self._fetch_headers(client, height - count, count)
first_prev = header_prev_hash(before[0])
self._check_chained(before, first_prev)
if header_prev_hash(header_hex) != header_hex_to_block_hash(before[-1]):
raise HeaderValidationError(f"the header at height {height} does not chain from the headers before it")
entries = [(height - count + i, h) for i, h in enumerate(before)]
self._window.clear()
self._extend_window([*entries, (height, header_hex)])
async def _follow_reorg(self, height: int, header_hex: str, client: ElectrumClient | None) -> None:
"""The header at `height` does not build on our tip: find where the server's chain
and ours part (the highest window height at which the server's hash is the same as
ours) and, if that is inside the window, adopt the server's branch from there on
(ELC-23). A fork older than the window, or a branch that is not a connected chain
of valid work ending at the announced header, raises HeaderValidationError."""
if client is None:
raise HeaderValidationError(f"the header at height {height} does not join the tip and there is no connection to follow it")
lowest = min(self._window)
ours = [self._window[h] for h in range(lowest, self.tip_height + 1)]
theirs = await self._fetch_headers(client, lowest, len(ours))
fork_height = None
for offset in range(len(ours) - 1, -1, -1):
if header_hex_to_block_hash(theirs[offset]) == header_hex_to_block_hash(ours[offset]):
fork_height = lowest + offset
break
if fork_height is None:
raise HeaderValidationError(
f"the header at height {height} forks more than {_HEADER_WINDOW} blocks below our tip {self.tip_height}"
)
branch = await self._fetch_headers(client, fork_height + 1, height - fork_height)
if branch[-1] != header_hex:
raise HeaderValidationError(f"the server's branch does not end at the header it announced at height {height}")
self._check_chained(branch, header_hex_to_block_hash(self._window[fork_height]))
old_height, old_hex = self.tip_height, self.tip_header_hex
# Recorded *before* the window moves: if the write fails the session ends, the next
# server announces the same fork against an unchanged window, and the event is
# written then — a reorg is never followed without a trace.
await self._record_reorg(
depth=old_height - fork_height,
fork_height=fork_height,
old_tip_height=old_height,
old_tip_hash=header_hex_to_block_hash(old_hex),
new_tip_height=height,
new_tip_hash=header_hex_to_block_hash(header_hex),
)
self._extend_window([(fork_height + 1 + i, h) for i, h in enumerate(branch)])
async def _record_reorg(self, **payload) -> None:
"""B-85 (ELC-24, AUD-38): the audit row of a followed reorganisation; a depth of 2
or more also pauses the lottery (`paused_reason = 'reorg'`), in the same transaction
as the row and as the `lottery_paused` one. Depth 1 is only observed: a one-block
reorganisation is ordinary on any chain and touches no deposit."""
logger.warning(
"followed a chain reorganisation of depth %s: fork at height %s, tip %s -> %s",
payload["depth"],
payload["fork_height"],
payload["old_tip_height"],
payload["new_tip_height"],
)
async with self._session_factory() as session:
await begin_immediate(session)
await write_audit_log(session, "chain_reorg_detected", payload)
if payload["depth"] >= _REORG_PAUSE_DEPTH:
await pause_automatically(session, "reorg")
await session.commit()
async def _corroborate_majority(
self,
@@ -357,60 +542,257 @@ class ElectrumListener:
agrees: Callable[[object], bool],
description: str,
) -> bool:
"""Shared quorum logic behind corroborate_header (B-28) and
corroborate_utxo_spent (B-29): ask every *other* configured server (never
"""Shared quorum logic behind
corroborate_utxo_spent (B-29), credits and reinstatements: ask every *other* configured server (never
the currently active one — that's exactly what a hostile server or a MITM
would control) and require a strict majority of the ones that actually
answer to agree, via `agrees`, with what our own connection reported.
Returns True with no other servers configured — nothing to corroborate
against, a risk accepted when ELECTRUM_FALLBACK_SERVERS was left empty
(see CLAUDE.md). Returns False (never silently "passes") if none of the
others could be reached, since an unreachable network proves nothing
either way.
The quorum is strict (B-84, ELC-14): it passes only when **at least
MIN_QUORUM_RESPONSES** of the other servers answered *and* a strict majority of
those that answered agree. Fewer answers — one reachable server, or none, or no
other server configured at all — fail, since a lone voice decides nothing
independently and an unreachable network proves nothing. Startup already refuses
to run with fewer than two fallbacks (config.validate_quorum_servers), so with a
sound configuration "too few answered" means servers are down, and the
corroboration simply fails (a delay, never a loss — the callers retry).
Only with ALLOW_NO_QUORUM=true (development) does the reduced rule apply: no
other server configured passes, and otherwise a strict majority of whoever
answered decides, even a single answer.
"""
others = [endpoint for endpoint in self._endpoints if endpoint != self.current_endpoint]
if not others:
if not others and self._allow_no_quorum:
return True
if not others:
logger.warning("could not corroborate %s: no other Electrum server is configured", description)
return False
results = await asyncio.gather(*(ask(endpoint) for endpoint in others))
responded = [result for result in results if result is not None]
if not responded:
minimum = 1 if self._allow_no_quorum else MIN_QUORUM_RESPONSES
if len(responded) < minimum:
logger.warning(
"could not corroborate %s with any of %s other configured server(s)", description, len(others)
"could not corroborate %s: %s of %s other configured server(s) answered, %s needed",
description,
len(responded),
len(others),
minimum,
)
return False
agreements = sum(1 for result in responded if agrees(result))
return agreements * 2 > len(responded)
async def corroborate_header(self, height: int, expected_hash: str) -> bool:
"""B-28: is `expected_hash` — the header our own active connection
reported for `height` — corroborated by other configured servers before
the draw (rounds/scheduler.py:_wait_for_next_block) treats it as
trustworthy entropy? Without this, a single hostile server (or a MITM on
the one active connection) can single-handedly decide who wins every
round; this raises the bar to controlling a majority of the configured
servers. See _corroborate_majority for the shared quorum logic.
"""
# --- Asking every server (B-76, TX-04, TX-21) ---------------------------------
async def _ask(endpoint: ElectrumEndpoint) -> str | None:
def _other_endpoints(self) -> list[ElectrumEndpoint]:
return [endpoint for endpoint in self._endpoints if endpoint != self.current_endpoint]
def _minimum_other_answers(self) -> int:
"""How many *other* servers must answer before their silence or agreement
counts as the network's: MIN_QUORUM_RESPONSES, or the reduced development rule
of ALLOW_NO_QUORUM (one answer, none if no other server is configured)."""
if not self._allow_no_quorum:
return MIN_QUORUM_RESPONSES
return 1 if self._other_endpoints() else 0
async def _ask_other_servers(self, ask: Callable[[ElectrumClient], "asyncio.Future"]) -> list:
"""`ask(client)` on a fresh connection to every endpoint but the active one, in
parallel, each bounded by _CORROBORATION_TIMEOUT_SECONDS; a server that cannot be
reached or does not answer in time yields None. `ask` itself decides what an
answer is (it may return None for an unusable one)."""
async def _one(endpoint: ElectrumEndpoint):
client = self._client_factory(endpoint)
try:
await asyncio.wait_for(client.connect(), timeout=_CORROBORATION_TIMEOUT_SECONDS)
result = await asyncio.wait_for(
client.request("blockchain.block.header", [height]),
timeout=_CORROBORATION_TIMEOUT_SECONDS,
)
if not isinstance(result, str):
return None
return header_hex_to_block_hash(result)
return await asyncio.wait_for(ask(client), timeout=_CORROBORATION_TIMEOUT_SECONDS)
except Exception:
return None
finally:
await client.close()
return await self._corroborate_majority(_ask, lambda block_hash: block_hash == expected_hash, f"block {height} header")
return list(await asyncio.gather(*(_one(endpoint) for endpoint in self._other_endpoints())))
async def _ask_active_server(self, ask: Callable[[ElectrumClient], "asyncio.Future"]):
client = self.client
if client is None:
return None
try:
return await asyncio.wait_for(ask(client), timeout=_CORROBORATION_TIMEOUT_SECONDS)
except Exception:
return None
async def transaction_known(self, txid: str) -> bool | None:
"""Does the network know `txid`? Asked of the active server and every other
configured one with `blockchain.transaction.get` (B-76, TX-04):
* True — at least one server returns the transaction: it is on the network,
whatever the server that refused it said;
* False — every server that answered says it does not know it, and the active
server and the minimum number of the others (see _minimum_other_answers) are
among them: nobody has it;
* None — too few answers to tell. Nothing may be released on this.
"""
async def _ask(client: ElectrumClient) -> bool | None:
try:
raw = await client.get_transaction(txid, False)
except ElectrumRpcError:
return False # an explicit "no such transaction"
except Exception:
return None
try:
if isinstance(raw, str) and Transaction.parse(bytes.fromhex(raw)).txid().hex() == txid:
return True
except Exception:
pass
return None # a reply that is not this transaction proves nothing either way
active = await self._ask_active_server(_ask)
others = await self._ask_other_servers(_ask)
if active is True or any(answer is True for answer in others):
return True
answered_others = [answer for answer in others if answer is not None]
if active is False and len(answered_others) >= self._minimum_other_answers():
return False
return None
def fan_out_transaction(self, raw_tx_hex: str) -> None:
"""Send an accepted transaction to every other configured server too (B-76,
TX-21): a second route onto the network in case the active server's own relay
is weak. Best effort and off the caller's path — a failure is only logged."""
async def _send() -> None:
async def _broadcast(client: ElectrumClient) -> str:
return await client.broadcast(raw_tx_hex)
results = await self._ask_other_servers(_broadcast)
logger.info(
"fanned a transaction out to %s other server(s), %s answered", len(results), sum(r is not None for r in results)
)
task = asyncio.create_task(_send())
self._background_tasks.add(task)
task.add_done_callback(self._background_tasks.discard)
# --- What the network knows of a transaction (B-78, TX-15, TX-17) -------------------
async def _ask_everyone(self, ask: Callable[[ElectrumClient], "asyncio.Future"]) -> ServerAnswers:
active, others = await asyncio.gather(self._ask_active_server(ask), self._ask_other_servers(ask))
return ServerAnswers(active, tuple(others), self._minimum_other_answers())
async def get_histories(self, scripthash: str) -> ServerAnswers:
"""`blockchain.scripthash.get_history` of `scripthash` from the active server and
every other one: each answer is the list of {"tx_hash", "height"} entries."""
async def _ask(client: ElectrumClient) -> list | None:
try:
history = await client.get_history(scripthash)
except Exception:
return None
return history if isinstance(history, list) else None
return await self._ask_everyone(_ask)
async def rebroadcast_everywhere(self, raw_tx_hex: str) -> ServerAnswers:
"""Send `raw_tx_hex` to the active server and every other one and report what each
said: ("accepted", "") or ("refused", <its message>) — an explicit JSON-RPC error —
and None for a server that gave no answer at all (TX-17). A tx the servers already
have comes back as a refusal with an "already known" message; the caller reads it."""
async def _ask(client: ElectrumClient) -> tuple | None:
try:
await client.broadcast(raw_tx_hex)
except ElectrumRpcError as exc:
return ("refused", exc.message)
except Exception:
return None
return ("accepted", "")
return await self._ask_everyone(_ask)
async def confirmed_spender(
self, scripthash: str, own_txids: set[str], outpoints: set[tuple[str, int]]
) -> str | None:
"""The txid of a transaction, none of the row's own versions, that spends one of
`outpoints` and is **in a block** — the first proof by which a row may be given
up (TX-17): its inputs went elsewhere. Asked of the *other* servers only (the
active one is what a hostile peer would control) and returned only when at least
the quorum minimum answered and a strict majority of the answerers name the same
txid. Each server looks through the confirmed history of the address the row
spends from.
"""
async def _ask(client: ElectrumClient) -> str | None:
history = await client.get_history(scripthash)
for entry in history:
txid = entry.get("tx_hash")
if txid in own_txids or (entry.get("height") or 0) <= 0:
continue
raw = await client.get_transaction(txid, False)
tx = Transaction.parse(bytes.fromhex(raw))
if tx.txid().hex() != txid:
continue
if any((vin.txid.hex(), vin.vout) in outpoints for vin in tx.vin):
return txid
return "" # looked everywhere: no conflicting transaction
answers = await self._ask_other_servers(_ask)
answered = [answer for answer in answers if answer is not None]
if len(answered) < max(self._minimum_other_answers(), 1):
return None
counts = Counter(answer for answer in answered if answer)
if not counts:
return None
txid, votes = counts.most_common(1)[0]
return txid if votes * 2 > len(answered) else None
async def agreed_block_hash(self, height: int) -> tuple[str | None, str | None]:
"""B-73 (RND-16, ELC-15): the hash of the block at exactly `height` — the draw's
entropy — as the *quorum* agrees on it, and what the active server said about it.
The header at that height (`blockchain.block.header`) is asked of every configured
server, the active one included, each over its own connection and within ELC-14's
timeouts. A header only counts if it is 80 bytes of valid work (ELC-11). The hash is
returned only when at least the quorum minimum of the *other* servers answered and a
strict majority of everybody who answered names the same one; otherwise the first
element is None and the caller asks again for **the same height** — the draw never
moves to a different block, so whoever relays blocks cannot pick one. The second
element is the active server's own answer (None if it gave none), for the audit row
written on a disagreement.
The old rule asked only the *other* servers to confirm the block the active one had
announced first after the close, which still let the active server choose which real
block seeded the draw simply by never announcing another.
"""
async def _ask(client: ElectrumClient) -> str | None:
header = await client.get_block_header(height)
if not isinstance(header, str) or not header_meets_its_own_target(header):
return None
return header_hex_to_block_hash(header)
answers = await self._ask_everyone(_ask)
reported = answers.active
if len(answers.answered_others) < self._minimum_other_answers():
logger.warning(
"block %s: %s of the other servers answered, %s needed", height, len(answers.answered_others),
self._minimum_other_answers(),
)
return None, reported
votes = Counter(answers.all)
if not votes:
return None, reported
block_hash, count = votes.most_common(1)[0]
if count * 2 <= len(answers.all):
return None, reported
if reported is not None and reported != block_hash:
logger.warning(
"block %s: the active server reported %s but the other servers agree on %s", height, reported, block_hash
)
return block_hash, reported
async def corroborate_utxo_spent(self, scripthash: str, txid: str, vout: int) -> bool:
"""B-29: before deposits/service.py's find_utxos_missing_from candidates
@@ -459,6 +841,26 @@ class ElectrumListener:
only credited once the quorum agrees.
"""
return await self._corroborate_unspent_confirmed(
scripthash, txid, vout, value, f"credit of {value} sats at {txid}:{vout}"
)
async def corroborate_utxo_reinstatement(self, scripthash: str, txid: str, vout: int, value: int) -> bool:
"""B-83 (ELC-25, DEP-08): the same quorum as a credit, for an outpoint that was
written off as spent outside the platform and has reappeared among the unspent.
Balances move in both directions and both need the same agreement: reinstating
on the active server's word alone let a hostile one put a spent coin back into a
balance."""
return await self._corroborate_unspent_confirmed(
scripthash, txid, vout, value, f"reinstatement of {value} sats at {txid}:{vout}"
)
async def _corroborate_unspent_confirmed(
self, scripthash: str, txid: str, vout: int, value: int, description: str
) -> bool:
"""Do the other servers list this outpoint as unspent, for the same amount, and
confirmed (height > 0)? Shared by credits (B-59) and reinstatements (B-83)."""
async def _ask(endpoint: ElectrumEndpoint) -> bool | None:
client = self._client_factory(endpoint)
try:
@@ -478,15 +880,64 @@ class ElectrumListener:
finally:
await client.close()
return await self._corroborate_majority(
_ask, lambda agrees: agrees, f"credit of {value} sats at {txid}:{vout}"
)
return await self._corroborate_majority(_ask, lambda agrees: agrees, description)
async def _consume_headers(self, queue: asyncio.Queue) -> None:
# --- Confirmations proven by merkle branch (B-83, TX-22, ELC-26) ---------------------
async def _header_at(self, height: int) -> str | None:
"""The header of block `height` that a merkle proof is checked against: the tip
we hold (validated as it arrived), or for an older block the one a strict
majority of at least the quorum minimum of the other servers agree on, which must
also satisfy its own difficulty target. None when neither is available — in
particular for a height above our tip, which we have no way to check."""
if height <= 0 or height > self.tip_height:
return None
if height == self.tip_height and self.tip_header_hex:
return self.tip_header_hex
if height in self._window:
return self._window[height] # validated as it arrived (ELC-22)
async def _ask(client: ElectrumClient) -> str | None:
header = await client.get_block_header(height)
return header if isinstance(header, str) and header_meets_its_own_target(header) else None
answers = [a for a in await self._ask_other_servers(_ask) if a is not None]
if len(answers) < max(self._minimum_other_answers(), 1):
return None
header, votes = Counter(answers).most_common(1)[0]
return header if votes * 2 > len(answers) else None
async def confirmation_proven(self, txid: str, height: int) -> bool:
"""Is `txid` in the block at `height`? Accepted only when the quorum returns a
valid merkle proof — `blockchain.transaction.get_merkle` from the *other* servers
(never the active one, which is what a hostile peer controls) that recomputes to
the merkle root of that block's header, which we hold or the quorum agrees on. A
strict majority of at least the quorum minimum must prove it; otherwise the answer
is False and the caller simply asks again at its next pass (a delay, never a
loss)."""
header = await self._header_at(height)
if header is None:
logger.warning("cannot check the merkle proof of %s at height %s: no trusted header for it", txid, height)
return False
async def _ask(endpoint: ElectrumEndpoint) -> bool | None:
client = self._client_factory(endpoint)
try:
await asyncio.wait_for(client.connect(), timeout=_CORROBORATION_TIMEOUT_SECONDS)
proof = await asyncio.wait_for(client.get_merkle(txid, height), timeout=_CORROBORATION_TIMEOUT_SECONDS)
return proof_matches_header(txid, height, proof, header)
except Exception:
return None
finally:
await client.close()
return await self._corroborate_majority(_ask, lambda proven: proven, f"merkle proof of {txid} at height {height}")
async def _consume_headers(self, queue: asyncio.Queue, client: ElectrumClient | None = None) -> None:
while True:
params = await queue.get()
for header in params:
self._apply_header(header)
await self._apply_header(header, client)
# A new block is exactly what the "drawing" phase is waiting on
# (rounds/scheduler.py:_wait_for_next_block) — nudge dashboards to
# refetch instead of waiting for their next poll.
@@ -510,7 +961,8 @@ class ElectrumListener:
async with self._session_factory() as session:
credit_candidates = await find_new_credit_candidates(session, user_id, entries)
reinstated = await reinstate_reappeared_utxos(session, user_id, entries)
# B-83 (DEP-02): candidates only — nothing is written before the quorum agrees.
reinstate_candidates = await find_reinstate_candidates(session, user_id, entries)
candidates = [
(row.id, row.txid, row.vout)
for row in await find_utxos_missing_from(session, user_id, entries)
@@ -524,6 +976,27 @@ class ElectrumListener:
)
]
# B-83 (ELC-25, DEP-08): a coin written off as spent outside the platform comes back
# into the balance only on the same quorum as a credit.
corroborated_reinstatements = [
entry
for entry in reinstate_candidates
if await self.corroborate_utxo_reinstatement(
scripthash, entry["tx_hash"], entry["tx_pos"], entry["value"]
)
]
reinstated = 0
if corroborated_reinstatements:
async with self._session_factory() as session:
reinstated = await reinstate_reappeared_utxos(session, user_id, corroborated_reinstatements)
if len(corroborated_reinstatements) < len(reinstate_candidates):
logger.warning(
"%s reappeared UTXO(s) for user_id=%s not corroborated by the other servers — "
"left out of the balance, will retry on the next refresh",
len(reinstate_candidates) - len(corroborated_reinstatements),
user_id,
)
credited = 0
if corroborated_credits:
async with self._session_factory() as session:
+57
View File
@@ -0,0 +1,57 @@
"""Merkle proofs (B-83, TX-22, ELC-26).
`blockchain.transaction.get_merkle` answers with the branch that links a transaction to
its block's merkle root. Checking it against a header **we hold** is what turns "a server
says this tx is at height h" into something a hostile server cannot fake without mining.
"""
import hashlib
_HEADER_LENGTH_BYTES = 80
_MERKLE_ROOT_OFFSET = 36
_MERKLE_ROOT_LENGTH = 32
_MAX_BRANCH_LENGTH = 40 # 2^40 transactions in a block is already absurd
def _sha256d(data: bytes) -> bytes:
return hashlib.sha256(hashlib.sha256(data).digest()).digest()
def header_merkle_root(header_hex: str) -> bytes:
"""The merkle root committed to by a raw 80-byte header, in internal byte order."""
header = bytes.fromhex(header_hex)
if len(header) != _HEADER_LENGTH_BYTES:
raise ValueError(f"a block header is {_HEADER_LENGTH_BYTES} bytes, got {len(header)}")
return header[_MERKLE_ROOT_OFFSET : _MERKLE_ROOT_OFFSET + _MERKLE_ROOT_LENGTH]
def merkle_root_from_branch(txid: str, branch: list[str], position: int) -> bytes:
"""The merkle root (internal byte order) a transaction `txid` at index `position` of
its block reaches through `branch` — the sibling hashes, bottom-up, in the display
order Electrum uses for txids."""
if position < 0 or len(branch) > _MAX_BRANCH_LENGTH or position >> len(branch):
raise ValueError("merkle position does not fit the branch")
current = bytes.fromhex(txid)[::-1]
index = position
for sibling_hex in branch:
sibling = bytes.fromhex(sibling_hex)[::-1]
if len(sibling) != 32:
raise ValueError("merkle branch element is not 32 bytes")
current = _sha256d(sibling + current) if index & 1 else _sha256d(current + sibling)
index >>= 1
return current
def proof_matches_header(txid: str, height: int, proof: object, header_hex: str) -> bool:
"""Does `proof` — a `get_merkle` reply — put `txid` in the block at `height` whose
header is `header_hex`? Any malformed reply is simply "no"."""
try:
if not isinstance(proof, dict) or int(proof["block_height"]) != height:
return False
branch = proof["merkle"]
if not isinstance(branch, list):
return False
root = merkle_root_from_branch(txid, [str(item) for item in branch], int(proof["pos"]))
return root == header_merkle_root(header_hex)
except (KeyError, TypeError, ValueError):
return False
+27
View File
@@ -0,0 +1,27 @@
"""What a question put to every server came back with (B-78).
`active` is the answer of the connection the platform is running on, `others` those of
each other configured server in configuration order; `None` stands for "no usable
answer" (unreachable, timed out, an error that is not an answer)."""
from typing import NamedTuple
class ServerAnswers(NamedTuple):
active: object | None
others: tuple
others_needed: int # how many of `others` must have answered for the network to count
@property
def answered_others(self) -> list:
return [answer for answer in self.others if answer is not None]
@property
def complete(self) -> bool:
"""Enough of the network answered for its silence to mean something: the active
server and at least `others_needed` of the others."""
return self.active is not None and len(self.answered_others) >= self.others_needed
@property
def all(self) -> list:
return ([] if self.active is None else [self.active]) + self.answered_others
+10 -6
View File
@@ -22,7 +22,7 @@ from app.api.routes.users import router as users_router
from app.api.routes.withdrawals import router as withdrawals_router
from app.auth.routes import router as auth_router
from app.api.errors import ApiError
from app.config import settings, validate_runtime_secrets
from app.config import settings, validate_quorum_servers, validate_runtime_secrets
from app.db.base import AsyncSessionLocal
from app.deposits.reconcile import DepositReconciler
from app.electrum.client import ElectrumClient, ElectrumEndpoint, parse_endpoints
@@ -37,7 +37,7 @@ logger = logging.getLogger(__name__)
def _make_electrum_client(endpoint: ElectrumEndpoint) -> ElectrumClient:
return ElectrumClient(endpoint.host, endpoint.port, endpoint.use_ssl)
return ElectrumClient(endpoint.host, endpoint.port, endpoint.use_ssl, endpoint.pin)
@asynccontextmanager
@@ -50,19 +50,23 @@ async def lifespan(app: FastAPI):
settings.electrum_port,
settings.electrum_use_ssl,
settings.electrum_fallback_servers,
settings.electrum_cert_pin,
)
validate_quorum_servers(endpoints) # B-84: refuses to serve without a usable quorum
logger.info("Electrum endpoints (in rotation order): %s", ", ".join(str(e) for e in endpoints))
listener = ElectrumListener(_make_electrum_client, AsyncSessionLocal, endpoints)
listener = ElectrumListener(
_make_electrum_client, AsyncSessionLocal, endpoints, allow_no_quorum=settings.allow_no_quorum
)
app.state.electrum_listener = listener
app.state.user_locks = UserLocks()
scheduler = RoundScheduler(AsyncSessionLocal, listener)
poller = ConfirmationPoller(AsyncSessionLocal, lambda: listener.client)
bumper = RbfBumper(AsyncSessionLocal, lambda: listener.client)
poller = ConfirmationPoller(AsyncSessionLocal, lambda: listener.client, network=listener)
bumper = RbfBumper(AsyncSessionLocal, lambda: listener.client, network=listener)
# Resolves in-flight transactions against the chain — the piece that lets the
# system recover on its own from a broadcast that never confirmed (B-04/B-08).
reconciler = PendingTransactionReconciler(AsyncSessionLocal, lambda: listener.client)
reconciler = PendingTransactionReconciler(AsyncSessionLocal, lambda: listener.client, network=listener)
# Periodic safety net for deposit crediting/external-spend detection,
# independent of scripthash-change notifications — catches a subscription
# silently lost on an otherwise healthy connection (B-30).
+67 -11
View File
@@ -1,4 +1,5 @@
import hashlib
import secrets
# Byte offsets of a standard 80-byte block header: version(4) + prev_block(32) +
# merkle_root(32) + timestamp(4) + bits(4) + nonce(4).
@@ -9,6 +10,16 @@ _BITS_OFFSET = 72
_BITS_LENGTH = 4
# B-74 (ELC-11): the proof-of-work floor of PLM mainnet — `consensus.powLimit` in
# palladiumcore/src/chainparams.cpp, the same as Bitcoin's. A header claiming a target
# *easier* than this was not mined to the chain's rules, whatever its own hash says, so
# the claimed target alone (which is whoever fabricates the header's to choose) is not a
# proof of work. Read through the module at call time so a test can swap in a regtest
# limit to mine headers cheaply; production code never changes it.
MAINNET_POW_LIMIT = int("00000000" + "ff" * 28, 16)
POW_LIMIT = MAINNET_POW_LIMIT
class HeaderValidationError(Exception):
"""Raised by ElectrumListener._apply_header (B-28) when a header either doesn't
satisfy the difficulty target it claims for itself, or doesn't chain from the
@@ -48,7 +59,8 @@ def _target_from_bits(bits: int) -> int:
def header_meets_its_own_target(header_hex: str) -> bool:
"""Whether this header's hash satisfies the difficulty target *it claims for
itself* (the `bits` field). Rejects a header that was never actually mined —
itself* (the `bits` field), and that target is no easier than the chain's powLimit
(B-74, ELC-11 — without that, a fabricated header just claims `bits = 0x207fffff`). Rejects a header that was never actually mined —
e.g. one fabricated wholesale by a hostile or MITM'd Electrum server (B-28),
since satisfying a self-chosen target still requires real proof-of-work.
@@ -57,8 +69,8 @@ def header_meets_its_own_target(header_hex: str) -> bool:
a real but implausibly low self-chosen difficulty: a server could still declare
an easy target and grind it out with modest hardware. That residual risk is why
the draw additionally requires the winning block's header to be corroborated by
the *other* configured servers before using it as the seed (see
ElectrumListener.corroborate_header and rounds/scheduler.py:_wait_for_next_block)
the configured servers at a fixed height before using it as the seed (see
ElectrumListener.agreed_block_hash and rounds/scheduler.py:_wait_for_draw_block)
rather than relying on this check alone.
"""
header_bytes = bytes.fromhex(header_hex)
@@ -66,7 +78,7 @@ def header_meets_its_own_target(header_hex: str) -> bool:
return False
bits = int.from_bytes(header_bytes[_BITS_OFFSET : _BITS_OFFSET + _BITS_LENGTH], "little")
target = _target_from_bits(bits)
if target <= 0:
if target <= 0 or target > POW_LIMIT: # B-74: not easier than the chain's powLimit
return False
digest = hashlib.sha256(hashlib.sha256(header_bytes).digest()).digest()
# The hash as the integer comparable against `target`: this is the same digest
@@ -77,12 +89,56 @@ def header_meets_its_own_target(header_hex: str) -> bool:
return hash_int <= target
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."""
def sha256_hex(data: bytes) -> str:
return hashlib.sha256(data).hexdigest()
def new_server_seed() -> str:
"""B-73 (RND-34, DAT-64): a round's secret — 32 random bytes from the OS CSPRNG, as
64 lowercase hex characters."""
return secrets.token_bytes(32).hex()
def server_seed_commitment(server_seed_hex: str) -> str:
"""`server_seed_hash`: sha256 of the secret's 32 bytes, published from the opening of
the round so the operator cannot change the secret afterwards (RND-34)."""
return sha256_hex(bytes.fromhex(server_seed_hex))
def participants_hash(rows: list[tuple[str, int, str]]) -> str:
"""The fingerprint of the ordered draw list (RND-14): sha256 of one `txid:vout:address`
line per participant, in `draw_position` order, each line ending in `\n`, UTF-8. `txid`
is the bet transaction's, lowercase hex as explorers show it; `vout` is the output paying
the round's pool address, in decimal; `address` is the participant's own."""
text = "".join(f"{txid}:{vout}:{address}\n" for txid, vout, address in rows)
return sha256_hex(text.encode("utf-8"))
def draw_seed(server_seed_hex: str, block_hash_hex: str, participants_hash_hex: str) -> int:
"""RND-17: sha256 of the secret (32 bytes), the hash of the block at `draw_height` (32
bytes, in the order explorers show it) and `participants_hash` (32 bytes), read as an
unsigned big-endian integer. Nobody who lacks the secret can predict it, and the
operator, who knows the secret, cannot know the block when committing to the list."""
digest = hashlib.sha256(
bytes.fromhex(server_seed_hex) + bytes.fromhex(block_hash_hex) + bytes.fromhex(participants_hash_hex)
).digest()
return int.from_bytes(digest, "big")
def draw_index(seed: int, participant_count: int) -> int:
"""The winner's `draw_position`: seed modulo the number of participants. Every
participant holds exactly one position, so odds are equal whatever the amount."""
if participant_count <= 0:
raise ValueError("no participants to draw from")
return seed % participant_count
def draw_winner(participants: list[str], server_seed_hex: str, block_hash_hex: str, participants_hash_hex: str) -> str:
"""The v1 draw algorithm (docs/ciclo-di-vita-del-round.md RND-17), recomputable by anyone
from the public proof (GET /rounds/{id}/proof): `participants` are the entries in
`draw_position` order, the winner is the one at `draw_index(draw_seed(...), n)`. Deliberately
simple and replaceable."""
if not participants:
raise ValueError("no participants to draw from")
seed = int(block_hash_hex, 16)
index = seed % len(participants)
return participants[index]
seed = draw_seed(server_seed_hex, block_hash_hex, participants_hash_hex)
return participants[draw_index(seed, len(participants))]
+30
View File
@@ -0,0 +1,30 @@
"""Pausing the lottery from code (B-78, DAT-69, AUD-11).
A pause only stops the *next* round from opening (rounds/service.py:rounds_can_open); a
round in progress still closes, draws and pays. Besides the operator's own switch there
are pauses the system raises itself when something needs a human look — a transaction
given up for dead that confirmed after all (`resurrected_tx`, B-78) and, in later
findings, a deep reorg (`reorg`, B-85) and a payout whose winning bet left the chain
(`payout_blocked`, B-82).
"""
from sqlalchemy.ext.asyncio import AsyncSession
from app.audit.log import write_audit_log
from app.rounds.config import get_round_config
OPERATOR_REASON = "operator"
AUTOMATIC_REASONS = ("reorg", "payout_blocked", "resurrected_tx")
async def pause_automatically(session: AsyncSession, reason: str) -> None:
"""Pause the lottery for an automatic `reason` in the caller's transaction and write
the `lottery_paused` row. An automatic reason is written even over a pause that is
already active (DAT-69): the cause that needs checking must not be hidden behind an
earlier one, and an operator pause is never what overrides it."""
if reason not in AUTOMATIC_REASONS:
raise ValueError(f"not an automatic pause reason: {reason!r}")
config = await get_round_config(session)
config.paused = True
config.paused_reason = reason
await write_audit_log(session, "lottery_paused", {"reason": reason})
+256 -129
View File
@@ -5,17 +5,28 @@ from datetime import datetime, timedelta, timezone
from embit import script
from embit.transaction import Transaction
from sqlalchemy import func, select
from sqlalchemy.exc import OperationalError
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from app.audit.log import write_audit_log
from app.db.base import begin_immediate
from app.db.models import AuditLog, PendingTransaction, Round, RoundParticipant, User
from app.electrum.listener import ElectrumListener
from app.electrum.scripthash import address_to_scripthash
from app.rounds.config import get_round_config
from app.rounds.draw import draw_winner, header_hex_to_block_hash
from app.rounds.draw import (
draw_index,
draw_seed,
new_server_seed,
participants_hash,
server_seed_commitment,
)
from app.rounds.events import broadcaster
from app.rounds.service import open_new_round_if_needed, round_deadline, winner_share
from app.wallet.hd import derive_pool_key
from app.tx.outcome import BroadcastOutcome, broadcast_with_verdict
from app.tx.versions import record_version
from app.wallet.hd import derive_round_pool_key
from app.wallet.keystore import decrypt_round_seed, encrypt_round_seed
from app.wallet.plm_network import PLM_MAINNET
from app.wallet.psbt_builder import InsufficientFundsError, Utxo, build_payout_transaction
@@ -39,10 +50,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
@@ -63,6 +74,10 @@ class RoundScheduler:
return
async with self._session_factory() as session:
# B-88: every state transition below starts with BEGIN IMMEDIATE (DAT-74).
# A busy database raises out of the tick, which run() logs and retries at
# the next one — nothing has been written yet.
await begin_immediate(session)
round_ = await open_new_round_if_needed(session)
await session.commit()
if round_ is None:
@@ -90,6 +105,7 @@ class RoundScheduler:
return
async with self._session_factory() as session:
await begin_immediate(session) # B-88
round_ = await session.get(Round, round_id)
# No new bets from here on, regardless of how long the pending-bet
# wait below takes — flip to "closing" immediately so it's observable
@@ -119,7 +135,12 @@ class RoundScheduler:
await self._close_and_draw(round_id)
async def _close_and_draw(self, round_id: int) -> None:
"""Close a `closing` round once nothing is in flight: either close it (no confirmed
participant) or commit to the draw — fix the participant list, its fingerprint and the
draw height, all in one transaction, and enter `drawing` (RND-13, RND-14, RND-33,
DAT-65) — then run the draw itself (`_complete_draw`)."""
async with self._session_factory() as session:
await begin_immediate(session) # B-88
round_ = await session.get(Round, round_id)
# B-53: re-check for in-flight bets in the *same* session that snapshots
@@ -143,47 +164,140 @@ class RoundScheduler:
)
return
# B-73 (RND-14, DAT-66): the draw order is the bet txid, ascending — a value the
# public can read off the chain, with no ties (two bets never share a txid). The
# server-only `broadcast_at` it replaces could not be checked by anyone.
participants = (
await session.scalars(
select(RoundParticipant)
.where(RoundParticipant.round_id == round_id, RoundParticipant.status == "confirmed")
.order_by(RoundParticipant.broadcast_at)
.order_by(RoundParticipant.bet_txid)
)
).all()
if not participants:
round_.status = "closed"
# DAT-64: nothing was drawn, so the secret has nothing left to protect.
if round_.server_seed_enc and not round_.server_seed:
round_.server_seed = decrypt_round_seed(round_.server_seed_enc)
await write_audit_log(session, "round_closed", {"participants": 0}, round_id=round_id)
await session.commit()
broadcaster.publish()
logger.info("round %s closed with no participants", round_id)
return
pool_amount = sum(p.bet_amount_sats for p in participants)
addresses: list[str] = []
user_by_address: dict[str, int] = {}
for p in participants:
user = await session.get(User, p.user_id)
addresses.append(user.address)
user_by_address[user.address] = user.id
# B-73 (RND-19, RND-33): draw_height is "the height we knew at closing, plus one", so
# an unknown height (0) cannot be a base — the round stays "closing" and this is
# tried again at the next step, with one audit row per round.
tip_at_close = self._listener.tip_height
if tip_at_close <= 0:
already_written = await session.scalar(
select(func.count())
.select_from(AuditLog)
.where(AuditLog.event_type == "draw_baseline_tip_unknown", AuditLog.round_id == round_id)
)
if not already_written:
logger.warning("round %s: chain tip unknown at closing time, not entering drawing yet", round_id)
await write_audit_log(session, "draw_baseline_tip_unknown", {}, round_id=round_id)
await session.commit()
return
users = {
user.id: user
for user in (
await session.scalars(select(User).where(User.id.in_({p.user_id for p in participants})))
).all()
}
if not round_.server_seed_enc:
# A round opened before B-73 has no commitment. Give it a secret now: it still
# cannot be known to anyone who could steer the block, because the list and the
# height are fixed below before that block exists — only the early publication
# of the commitment is missing for this one round.
seed = new_server_seed()
round_.server_seed_hash = server_seed_commitment(seed)
round_.server_seed_enc = encrypt_round_seed(seed)
for position, participant in enumerate(participants):
participant.draw_position = position
round_.participants_hash = participants_hash(
[(p.bet_txid, p.bet_vout, users[p.user_id].address) for p in participants]
)
round_.draw_height = tip_at_close + 1
round_.pool_amount_sats = sum(p.bet_amount_sats for p in participants)
round_.status = "drawing"
drawing_started_at = datetime.now(timezone.utc)
round_.drawing_started_at = drawing_started_at
round_.drawing_started_at = datetime.now(timezone.utc)
await write_audit_log(
session,
"draw_committed",
{
"participants_hash": round_.participants_hash,
"draw_height": round_.draw_height,
"participants": len(participants),
"server_seed_hash": round_.server_seed_hash,
},
round_id=round_id,
)
await session.commit()
broadcaster.publish()
tip_at_close = self._listener.tip_height
block_height, block_hash = await self._wait_for_next_block(round_id, tip_at_close, drawing_started_at)
winner_address = draw_winner(addresses, block_hash)
await self._complete_draw(round_id)
async def _complete_draw(self, round_id: int) -> None:
"""The draw of a round in `drawing`, from nothing but what the database holds (RND-36,
DAT-65): wait for the block at `draw_height` to be confirmed and agreed on by the
quorum, compute the winner, store it and reveal the secret in one transaction, then
start the payout. Idempotent — a round no longer in `drawing`, or with a winner
already stored, is left alone."""
async with self._session_factory() as session:
round_ = await session.get(Round, round_id)
round_.draw_block_height = block_height
if round_ is None or round_.status != "drawing" or round_.winner_user_id is not None:
return
draw_height = round_.draw_height
draw_confirmations = round_.draw_confirmations
committed_hash = round_.participants_hash
server_seed_enc = round_.server_seed_enc
server_seed_hash = round_.server_seed_hash
waiting_since = round_.drawing_started_at.replace(tzinfo=timezone.utc)
block_hash = await self._wait_for_draw_block(round_id, draw_height, draw_confirmations, waiting_since)
server_seed = decrypt_round_seed(server_seed_enc)
if server_seed_commitment(server_seed) != server_seed_hash:
raise RuntimeError(f"round {round_id}: the stored secret does not match its published commitment")
async with self._session_factory() as session:
await begin_immediate(session) # B-88
round_ = await session.get(Round, round_id)
if round_.status != "drawing" or round_.winner_user_id is not None:
return # drawn meanwhile (a second pass over the same round)
participants = (
await session.scalars(
select(RoundParticipant)
.where(RoundParticipant.round_id == round_id, RoundParticipant.draw_position.is_not(None))
.order_by(RoundParticipant.draw_position)
)
).all()
users = {
user.id: user
for user in (
await session.scalars(select(User).where(User.id.in_({p.user_id for p in participants})))
).all()
}
ordered_rows = [(p.bet_txid, p.bet_vout, users[p.user_id].address) for p in participants]
if participants_hash(ordered_rows) != committed_hash:
raise RuntimeError(f"round {round_id}: the draw list no longer matches its published fingerprint")
seed = draw_seed(server_seed, block_hash, committed_hash)
winner = participants[draw_index(seed, len(participants))]
winner_address = users[winner.user_id].address
pool_amount = sum(p.bet_amount_sats for p in participants if p.status == "confirmed")
round_.draw_block_height = draw_height
round_.draw_block_hash = block_hash
round_.seed_int = str(int(block_hash, 16))
round_.winner_user_id = user_by_address[winner_address]
round_.seed_int = str(seed)
round_.winner_user_id = winner.user_id
round_.pool_amount_sats = pool_amount
# The reveal (RND-18, DAT-64): the plaintext secret becomes visible in the same
# transaction that stores the winner, never before.
round_.server_seed = server_seed
round_.status = "paying_out"
await write_audit_log(
session,
@@ -191,11 +305,15 @@ class RoundScheduler:
{
"winner_address": winner_address,
"pool_amount_sats": pool_amount,
"block_height": block_height,
"block_height": draw_height,
"block_hash": block_hash,
"participants": len(addresses),
"participants": len(participants),
"draw_height": draw_height,
"participants_hash": committed_hash,
"server_seed": server_seed,
"seed": f"{seed:064x}",
},
user_id=user_by_address[winner_address],
user_id=winner.user_id,
round_id=round_id,
)
await session.commit()
@@ -204,115 +322,94 @@ class RoundScheduler:
logger.info("round %s: winner=%s pool=%s", round_id, winner_address, pool_amount)
await self._trigger_payout(round_id)
async def _wait_for_next_block(
self, round_id: int, tip_at_close: int, waiting_since: datetime
) -> tuple[int, str]:
"""Waits for a block after tip_at_close and, before handing it back as the
draw's entropy source, requires it to be corroborated by the other
configured Electrum servers (B-28) — our own active connection is exactly
the thing a hostile server or a MITM would control, so its header alone is
not enough to seed a payout. A candidate that fails corroboration is never
used: this keeps waiting for a further block and tries corroborating that
one instead, logging why every time so a stuck draw is visible in
/admin's audit log rather than a silent, unexplained wait.
async def _wait_for_draw_block(
self, round_id: int, draw_height: int, confirmations: int, waiting_since: datetime
) -> str:
"""The hash of the block at `draw_height`, once it is safe to seed the draw with it
(RND-15, RND-16, RND-20; B-73): the chain must have `confirmations` blocks from that
height (a tip of at least `draw_height + confirmations - 1`), and then the quorum of
servers must agree on the header *at that exact height* — never on the tip, never on
a later block. If they do not agree the same height is asked again at the next step
and `draw_header_corroboration_failed` is written once per distinct hash the active
server reported, so a disagreement that lasts does not write a row every 5 seconds.
Whoever produces or relays blocks therefore cannot choose which block seeds the draw:
withholding or delaying one only delays the draw.
This wait has no timeout — it can't, since the draw's entropy genuinely
depends on a future block. B-36: what it lacked was *visibility*, so a
connection that stopped advancing the tip left the round silently frozen
in "drawing" with nothing in the logs or /admin to explain why. Progress
is now logged periodically, and past _DRAW_STALL_THRESHOLD_SECONDS a
draw_stalled audit entry is written (and re-written every threshold
interval for as long as the stall continues) so the wait shows up next
to the draw_header_corroboration_failed entries above.
B-63: `tip_at_close` of 0 means the tip was *unknown* when the round closed,
not that the chain was at height zero — and "the first block we hear about"
is then not necessarily a block mined after the close. Rather than seed the
draw from a hash that may already have been public while bets were open, the
first height we do learn becomes the baseline and this waits for a block
strictly after it. Since the Electrum listener now only publishes its client
once a header has been applied, and _tick won't run without one, this should
be unreachable — it stays as the local statement of what the draw actually
requires, since nothing else in this function would notice if that stopped
holding.
The wait has no timeout — the entropy genuinely depends on a future block — but it is
observable (B-36): progress is logged every _DRAW_PROGRESS_LOG_INTERVAL_SECONDS, and a
`draw_stalled` row is written when for _DRAW_STALL_THRESHOLD_SECONDS the chain has not
advanced while the round waits for confirmations, or the quorum has been failing to
agree — and repeated every threshold for as long as that lasts. The clock restarts
whenever the tip advances during the confirmation wait, so a chain that is merely
producing its three blocks at the normal pace never counts as stalled.
"""
next_progress_log_at = waiting_since + timedelta(seconds=_DRAW_PROGRESS_LOG_INTERVAL_SECONDS)
next_stall_audit_at = waiting_since + timedelta(seconds=_DRAW_STALL_THRESHOLD_SECONDS)
if tip_at_close <= 0:
tip_at_close = await self._adopt_baseline_tip(round_id)
required_tip = draw_height + confirmations - 1
now = datetime.now(timezone.utc)
next_progress_log_at = now + timedelta(seconds=_DRAW_PROGRESS_LOG_INTERVAL_SECONDS)
stall_since = now
next_stall_audit_at = now + timedelta(seconds=_DRAW_STALL_THRESHOLD_SECONDS)
last_tip = self._listener.tip_height
agreeing = False # True once the confirmations are there and only the quorum is awaited
reported_hashes: set[str | None] = set()
while True:
while self._listener.tip_height <= tip_at_close or not self._listener.tip_header_hex:
now = datetime.now(timezone.utc)
if now >= next_progress_log_at:
logger.info(
"round %s: still waiting for a block past height %s (%.0fs since drawing started)",
now = datetime.now(timezone.utc)
tip = self._listener.tip_height
if tip >= required_tip:
if not agreeing:
agreeing = True
stall_since = now
next_stall_audit_at = now + timedelta(seconds=_DRAW_STALL_THRESHOLD_SECONDS)
block_hash, reported = await self._listener.agreed_block_hash(draw_height)
if block_hash is not None:
return block_hash
if reported not in reported_hashes:
reported_hashes.add(reported)
logger.error(
"round %s: block %s header (active server: %s) is not agreed by the other Electrum "
"servers; asking again for the same height",
round_id,
tip_at_close,
(now - waiting_since).total_seconds(),
draw_height,
reported,
)
next_progress_log_at = now + timedelta(seconds=_DRAW_PROGRESS_LOG_INTERVAL_SECONDS)
if now >= next_stall_audit_at:
async with self._session_factory() as session:
await write_audit_log(
session,
"draw_stalled",
{
"tip_at_close": tip_at_close,
"current_tip_height": self._listener.tip_height,
"elapsed_seconds": int((now - waiting_since).total_seconds()),
},
"draw_header_corroboration_failed",
{"height": draw_height, "reported_hash": reported},
round_id=round_id,
)
await session.commit()
next_stall_audit_at = now + timedelta(seconds=_DRAW_STALL_THRESHOLD_SECONDS)
await asyncio.sleep(_TICK_INTERVAL_SECONDS)
height = self._listener.tip_height
block_hash = header_hex_to_block_hash(self._listener.tip_header_hex)
if await self._listener.corroborate_header(height, block_hash):
return height, block_hash
logger.error(
"round %s: block %s header %s could not be corroborated by other Electrum servers; "
"waiting for a further block",
round_id,
height,
block_hash,
)
async with self._session_factory() as session:
await write_audit_log(
session,
"draw_header_corroboration_failed",
{"height": height, "reported_hash": block_hash},
round_id=round_id,
)
await session.commit()
tip_at_close = height
elif tip != last_tip:
last_tip = tip
stall_since = now
next_stall_audit_at = now + timedelta(seconds=_DRAW_STALL_THRESHOLD_SECONDS)
async def _adopt_baseline_tip(self, round_id: int) -> int:
"""B-63: the height the draw must find a *later* block than, for the case
where the tip wasn't known at closing time. Waits for a header to arrive and
takes that height as the baseline — the block it describes may predate the
close, which is exactly why it is used as the floor rather than as the seed —
and records why, since a draw that waits one extra block should be explainable
from /admin rather than looking like a stall.
"""
while not self._listener.tip_header_hex or self._listener.tip_height <= 0:
if now >= next_progress_log_at:
logger.info(
"round %s: still waiting for block %s (%s confirmation(s) needed, chain at %s, %.0fs since drawing started)",
round_id,
draw_height,
confirmations,
tip,
(now - waiting_since).total_seconds(),
)
next_progress_log_at = now + timedelta(seconds=_DRAW_PROGRESS_LOG_INTERVAL_SECONDS)
if now >= next_stall_audit_at:
async with self._session_factory() as session:
await write_audit_log(
session,
"draw_stalled",
{
"draw_height": draw_height,
"current_tip_height": tip,
"elapsed_seconds": int((now - stall_since).total_seconds()),
},
round_id=round_id,
)
await session.commit()
next_stall_audit_at = now + timedelta(seconds=_DRAW_STALL_THRESHOLD_SECONDS)
await asyncio.sleep(_TICK_INTERVAL_SECONDS)
height = self._listener.tip_height
logger.warning(
"round %s: chain tip was unknown at closing time; using height %s as the draw baseline "
"and waiting for a further block",
round_id,
height,
)
async with self._session_factory() as session:
await write_audit_log(
session,
"draw_baseline_tip_unknown",
{"baseline_height": height},
round_id=round_id,
)
await session.commit()
return height
async def _retry_payout_if_due(self, round_id: int) -> None:
"""B-26: whether a "paying_out" round is due for another payout attempt.
@@ -361,6 +458,12 @@ class RoundScheduler:
# --- Phase 1: read (session closed before any network I/O) ---------------
async with self._session_factory() as session:
try:
await begin_immediate(session) # B-88
except OperationalError:
# Nothing built or sent yet: try again at the next tick.
logger.warning("round %s payout deferred: database busy", round_id)
return
round_ = await session.get(Round, round_id)
already_in_flight = await session.scalar(
select(PendingTransaction).where(
@@ -385,6 +488,7 @@ class RoundScheduler:
fee_address = config.fee_address
fee_rate = config.fee_rate_sat_vb
pool_amount_sats = round_.pool_amount_sats
round_pool_address = round_.pool_address # B-80 ("" fails in derive_round_pool_key below)
winner_user_id = round_.winner_user_id
winner = await session.get(User, winner_user_id)
winner_address = winner.address if winner is not None else None
@@ -406,7 +510,10 @@ class RoundScheduler:
# --- Phase 2: build (network read only, no DB write yet) -----------------
try:
pool_key = derive_pool_key()
# B-80 (RND-22): the round's own key and address — only the coins at this
# round's pool address are ever read, so no other round's money (and no
# stray coin sent to another address) can end up among the inputs.
pool_key = derive_round_pool_key(round_id, round_pool_address)
pool_script_obj = script.p2wpkh(pool_key.to_public())
pool_address = pool_script_obj.address(network=PLM_MAINNET)
entries = await client.listunspent(address_to_scripthash(pool_address))
@@ -450,6 +557,13 @@ class RoundScheduler:
# --- Phase 3: persist the intent, *then* broadcast (B-25) -----------------
async with self._session_factory() as session:
try:
await begin_immediate(session) # B-88
except OperationalError:
# Not written, not broadcast: the payout is simply rebuilt on the retry.
logger.warning("round %s payout deferred before broadcast: database busy", round_id)
await self._log_payout_failure(round_id, winner_user_id, "database busy")
return
round_ = await session.get(Round, round_id)
round_.winner_amount_sats = built.winner_sats
round_.fee_amount_sats = built.commission_sats
@@ -466,21 +580,34 @@ class RoundScheduler:
status="building",
)
session.add(pending)
await record_version(session, pending, built.txid, built.raw_hex) # B-77: the first version
await session.commit()
pending_id = pending.id
# --- Phase 4: broadcast, then promote the pending row --------------------
try:
await client.broadcast(built.raw_hex)
except Exception:
# The row stays "building": the reconciler will ask the chain about it
# and, finding nothing, abandon it and clear payout_txid (B-25) — instead
# of the round being stuck with a payout_txid that never went anywhere.
logger.exception("round %s payout broadcast failed", round_id)
# B-76 (TX-05): the same three outcomes as a bet's broadcast. Accepted — the
# server took it, or refused with "already known" / a server of the network
# holds it — promotes the row; a refusal and an uncertain outcome both leave it
# "building" with a payout_failed entry, since which of the two it really was
# is the reconciler's call, made against the chain (TX-16, TX-17).
verdict = await broadcast_with_verdict(client, self._listener, built.raw_hex, built.txid)
if verdict.outcome is not BroadcastOutcome.ACCEPTED:
logger.error("round %s payout broadcast not accepted (%s): %s", round_id, verdict.outcome.value, verdict.reason)
await self._log_payout_failure(round_id, winner_user_id, "broadcast rejected")
return
async with self._session_factory() as session:
try:
await begin_immediate(session) # B-88
except OperationalError:
# The tx is on the network; the row stays "building" and the
# reconciler finds it on the chain and promotes it (TX-28).
logger.error(
"round %s payout %s broadcast but the database is busy: left 'building'",
round_id,
built.txid,
)
return
pending = await session.get(PendingTransaction, pending_id)
pending.status = "pending"
await write_audit_log(
+20
View File
@@ -8,6 +8,9 @@ from sqlalchemy.ext.asyncio import AsyncSession
from app.db.models import Round, RoundConfig
from app.rounds.config import get_round_config
from app.rounds.events import broadcaster
from app.rounds.draw import new_server_seed, server_seed_commitment
from app.wallet.hd import derive_pool_address
from app.wallet.keystore import encrypt_round_seed
logger = logging.getLogger(__name__)
@@ -23,6 +26,16 @@ _OPEN_ROUND_ATTEMPTS = 3
# advertised jackpot (rounds.py) and the actual payout (scheduler.py) can't diverge.
def _new_round_secret() -> dict:
"""B-73 (RND-34): a fresh secret for a round about to open, as the columns that hold it —
its published commitment and its encrypted form, never the plaintext."""
server_seed = new_server_seed()
return {
"server_seed_hash": server_seed_commitment(server_seed),
"server_seed_enc": encrypt_round_seed(server_seed),
}
def winner_share(pool_amount_sats: int) -> int:
return pool_amount_sats * 70 // 100
@@ -128,6 +141,10 @@ async def open_new_round_if_needed(session: AsyncSession) -> Round | None:
status="open",
duration_seconds=config.round_duration_seconds,
cooldown_seconds=config.round_cooldown_seconds,
draw_confirmations=config.draw_confirmations, # B-73 (DAT-61)
# B-73 (RND-34, DAT-64): the commitment, then the secret itself encrypted — the
# plaintext column stays NULL until the reveal.
**_new_round_secret(),
)
session.add(round_)
try:
@@ -152,6 +169,9 @@ async def open_new_round_if_needed(session: AsyncSession) -> Round | None:
# only tells subscribers "go refetch", and by the time an SSE client's
# refetch request actually lands, this in-process commit (microseconds
# away) has essentially always already happened.
# B-80 (RND-35, DAT-60): the round's own pool address, now that its id exists —
# still inside the caller's transaction, so no committed round ever lacks one.
round_.pool_address = derive_pool_address(round_.id)
broadcaster.publish()
return round_
+2
View File
@@ -83,6 +83,8 @@
<input id="admin-round-cooldown" inputmode="numeric" placeholder="es. 30">
<label for="admin-draw-animation">Durata animazione estrazione (secondi)</label>
<input id="admin-draw-animation" inputmode="numeric" placeholder="es. 20">
<label for="admin-draw-confirmations">Conferme sul blocco di estrazione (1–20, dal round successivo)</label>
<input id="admin-draw-confirmations" inputmode="numeric" placeholder="es. 3">
<label for="admin-fee-rate">Fee rate di rete (sat/vB)</label>
<input id="admin-fee-rate" inputmode="numeric" placeholder="es. 1">
<label for="admin-rbf-timeout">Timeout prima del fee-bump RBF (secondi)</label>
+2
View File
@@ -150,6 +150,7 @@ async function adminLoadConfig() {
document.getElementById('admin-round-duration').value = data.round_duration_seconds;
document.getElementById('admin-round-cooldown').value = data.round_cooldown_seconds;
document.getElementById('admin-draw-animation').value = data.draw_animation_seconds;
document.getElementById('admin-draw-confirmations').value = data.draw_confirmations;
document.getElementById('admin-fee-rate').value = data.fee_rate_sat_vb;
document.getElementById('admin-rbf-timeout').value = data.rbf_timeout_seconds;
renderMaintenanceState(data.paused);
@@ -209,6 +210,7 @@ async function adminSave() {
round_duration_seconds: parseInt(document.getElementById('admin-round-duration').value, 10),
round_cooldown_seconds: parseInt(document.getElementById('admin-round-cooldown').value, 10),
draw_animation_seconds: parseInt(document.getElementById('admin-draw-animation').value, 10),
draw_confirmations: parseInt(document.getElementById('admin-draw-confirmations').value, 10),
fee_rate_sat_vb: parseInt(document.getElementById('admin-fee-rate').value, 10),
rbf_timeout_seconds: parseInt(document.getElementById('admin-rbf-timeout').value, 10),
};
+21
View File
@@ -149,6 +149,7 @@ const TRANSLATIONS = {
'error.balance_pending_confirmation': 'You have {pending_plm} PLM pending confirmation — it is not spendable yet.',
'error.amount_below_network_fee': 'The amount is too small to cover the network fee.',
'error.invalid_address': 'Not a valid PLM address (it must start with plm1q…).',
'error.round_not_found': 'Round not found.',
'error.amount_below_minimum': 'The minimum withdrawal amount is {minimum_plm} PLM.',
'error.current_password_incorrect': 'The current password is incorrect.',
'error.password_too_short': 'The new password must be at least {minimum} characters.',
@@ -159,9 +160,11 @@ const TRANSLATIONS = {
'error.invalid_request': 'Invalid request, please check the entered data.',
'error.invalid_amount': 'Enter an amount greater than zero.',
'error.broadcast_failed': 'The network refused the transaction. Please try again shortly.',
'error.service_busy': 'The service is busy right now and nothing was sent. Please try again in a moment.',
'error.amount_below_dust_limit': 'The amount is too small to be sent.',
'error.too_many_inputs': 'Your balance is split across too many small deposits to be spent in a single transaction (max {max_inputs}). Please contact support to consolidate it.',
'error.withdrawal_to_own_address': 'That is your own deposit address — withdraw to an external wallet.',
'error.withdrawal_to_platform_address': 'That is an address of this platform — withdraw to an external wallet.',
'error.internal_error': 'Unexpected server error. Please try again shortly.',
'error.guide_unavailable': 'The guide is not available right now.',
'error.rate_limited': 'Too many attempts, please try again in {retry_after_seconds} seconds.',
@@ -314,6 +317,7 @@ const TRANSLATIONS = {
'error.balance_pending_confirmation': 'Hai {pending_plm} PLM in attesa di conferma — non ancora disponibili per la spesa.',
'error.amount_below_network_fee': "L'importo è troppo basso per coprire la fee di rete.",
'error.invalid_address': 'Indirizzo PLM non valido (deve iniziare con plm1q…).',
'error.round_not_found': 'Round non trovato.',
'error.amount_below_minimum': "L'importo minimo di prelievo è {minimum_plm} PLM.",
'error.current_password_incorrect': 'La password attuale non è corretta.',
'error.password_too_short': 'La nuova password deve avere almeno {minimum} caratteri.',
@@ -324,9 +328,11 @@ const TRANSLATIONS = {
'error.invalid_request': 'Richiesta non valida, controlla i dati inseriti.',
'error.invalid_amount': 'Inserisci un importo maggiore di zero.',
'error.broadcast_failed': 'La rete ha rifiutato la transazione. Riprova tra poco.',
'error.service_busy': 'Il servizio è occupato in questo momento e non è stato inviato nulla. Riprova tra poco.',
'error.amount_below_dust_limit': "L'importo è troppo basso per essere inviato.",
'error.too_many_inputs': 'Il tuo saldo è suddiviso in troppi piccoli depositi per essere speso in una sola transazione (max {max_inputs}). Contatta l\'assistenza per consolidarlo.',
'error.withdrawal_to_own_address': 'Questo è il tuo indirizzo di deposito — preleva verso un wallet esterno.',
'error.withdrawal_to_platform_address': 'Questo è un indirizzo della piattaforma — preleva verso un wallet esterno.',
'error.internal_error': 'Errore inatteso del server. Riprova tra poco.',
'error.guide_unavailable': 'La guida non è disponibile in questo momento.',
'error.rate_limited': 'Troppi tentativi, riprova tra {retry_after_seconds} secondi.',
@@ -479,6 +485,7 @@ const TRANSLATIONS = {
'error.balance_pending_confirmation': 'Tienes {pending_plm} PLM pendientes de confirmación — todavía no se pueden gastar.',
'error.amount_below_network_fee': 'El importe es demasiado pequeño para cubrir la comisión de red.',
'error.invalid_address': 'Dirección PLM no válida (debe empezar por plm1q…).',
'error.round_not_found': 'Ronda no encontrada.',
'error.amount_below_minimum': 'El importe mínimo de retiro es {minimum_plm} PLM.',
'error.current_password_incorrect': 'La contraseña actual no es correcta.',
'error.password_too_short': 'La nueva contraseña debe tener al menos {minimum} caracteres.',
@@ -489,9 +496,11 @@ const TRANSLATIONS = {
'error.invalid_request': 'Solicitud no válida, revisa los datos introducidos.',
'error.invalid_amount': 'Introduce un importe mayor que cero.',
'error.broadcast_failed': 'La red rechazó la transacción. Inténtalo de nuevo en un momento.',
'error.service_busy': 'El servicio está ocupado en este momento y no se ha enviado nada. Inténtalo de nuevo en un momento.',
'error.amount_below_dust_limit': 'El importe es demasiado pequeño para enviarse.',
'error.too_many_inputs': 'Tu saldo está repartido en demasiados depósitos pequeños para gastarse en una sola transacción (máx. {max_inputs}). Contacta con soporte para consolidarlo.',
'error.withdrawal_to_own_address': 'Esa es tu propia dirección de depósito — retira a una cartera externa.',
'error.withdrawal_to_platform_address': 'Esa es una dirección de la propia plataforma — retira a una cartera externa.',
'error.internal_error': 'Error inesperado del servidor. Inténtalo de nuevo en un momento.',
'error.guide_unavailable': 'La guía no está disponible en este momento.',
'error.rate_limited': 'Demasiados intentos, inténtalo de nuevo en {retry_after_seconds} segundos.',
@@ -644,6 +653,7 @@ const TRANSLATIONS = {
'error.balance_pending_confirmation': 'Vous avez {pending_plm} PLM en attente de confirmation — pas encore disponibles.',
'error.amount_below_network_fee': 'Le montant est trop faible pour couvrir les frais de réseau.',
'error.invalid_address': 'Adresse PLM invalide (elle doit commencer par plm1q…).',
'error.round_not_found': 'Manche introuvable.',
'error.amount_below_minimum': 'Le montant minimum de retrait est de {minimum_plm} PLM.',
'error.current_password_incorrect': "Le mot de passe actuel n'est pas correct.",
'error.password_too_short': 'Le nouveau mot de passe doit comporter au moins {minimum} caractères.',
@@ -654,9 +664,11 @@ const TRANSLATIONS = {
'error.invalid_request': 'Requête invalide, vérifiez les données saisies.',
'error.invalid_amount': 'Saisissez un montant supérieur à zéro.',
'error.broadcast_failed': 'Le réseau a refusé la transaction. Veuillez réessayer dans un instant.',
'error.service_busy': 'Le service est occupé pour le moment et rien n\'a été envoyé. Veuillez réessayer dans un instant.',
'error.amount_below_dust_limit': "Le montant est trop faible pour être envoyé.",
'error.too_many_inputs': 'Votre solde est réparti sur trop de petits dépôts pour être dépensé en une seule transaction (max {max_inputs}). Contactez le support pour le consolider.',
'error.withdrawal_to_own_address': "C'est votre propre adresse de dépôt — retirez vers un portefeuille externe.",
'error.withdrawal_to_platform_address': "C'est une adresse de la plateforme elle-même — retirez vers un portefeuille externe.",
'error.internal_error': 'Erreur inattendue du serveur. Veuillez réessayer dans un instant.',
'error.guide_unavailable': "Le guide n'est pas disponible pour le moment.",
'error.rate_limited': 'Trop de tentatives, réessayez dans {retry_after_seconds} secondes.',
@@ -809,6 +821,7 @@ const TRANSLATIONS = {
'error.balance_pending_confirmation': 'Sie haben {pending_plm} PLM, die noch auf Bestätigung warten — noch nicht verfügbar.',
'error.amount_below_network_fee': 'Der Betrag ist zu klein, um die Netzwerkgebühr zu decken.',
'error.invalid_address': 'Keine gültige PLM-Adresse (sie muss mit plm1q… beginnen).',
'error.round_not_found': 'Runde nicht gefunden.',
'error.amount_below_minimum': 'Der Mindestauszahlungsbetrag beträgt {minimum_plm} PLM.',
'error.current_password_incorrect': 'Das aktuelle Passwort ist nicht korrekt.',
'error.password_too_short': 'Das neue Passwort muss mindestens {minimum} Zeichen lang sein.',
@@ -819,9 +832,11 @@ const TRANSLATIONS = {
'error.invalid_request': 'Ungültige Anfrage, bitte überprüfe die eingegebenen Daten.',
'error.invalid_amount': 'Gib einen Betrag größer als null ein.',
'error.broadcast_failed': 'Das Netzwerk hat die Transaktion abgelehnt. Bitte versuche es in Kürze erneut.',
'error.service_busy': 'Der Dienst ist gerade ausgelastet und es wurde nichts gesendet. Bitte versuche es gleich noch einmal.',
'error.amount_below_dust_limit': 'Der Betrag ist zu klein, um gesendet zu werden.',
'error.too_many_inputs': 'Ihr Guthaben ist auf zu viele kleine Einzahlungen verteilt, um in einer einzigen Transaktion ausgegeben zu werden (max. {max_inputs}). Bitte wenden Sie sich an den Support, um es zusammenzufassen.',
'error.withdrawal_to_own_address': 'Das ist deine eigene Einzahlungsadresse — zahle auf eine externe Wallet aus.',
'error.withdrawal_to_platform_address': 'Das ist eine Adresse der Plattform selbst — zahle auf eine externe Wallet aus.',
'error.internal_error': 'Unerwarteter Serverfehler. Bitte versuche es in Kürze erneut.',
'error.guide_unavailable': 'Die Anleitung ist derzeit nicht verfügbar.',
'error.rate_limited': 'Zu viele Versuche, bitte versuche es in {retry_after_seconds} Sekunden erneut.',
@@ -974,6 +989,7 @@ const TRANSLATIONS = {
'error.balance_pending_confirmation': 'У вас есть {pending_plm} PLM, ожидающих подтверждения — они пока недоступны для расходования.',
'error.amount_below_network_fee': 'Сумма слишком мала, чтобы покрыть комиссию сети.',
'error.invalid_address': 'Некорректный адрес PLM (он должен начинаться с plm1q…).',
'error.round_not_found': 'Раунд не найден.',
'error.amount_below_minimum': 'Минимальная сумма вывода — {minimum_plm} PLM.',
'error.current_password_incorrect': 'Текущий пароль указан неверно.',
'error.password_too_short': 'Новый пароль должен содержать не менее {minimum} символов.',
@@ -984,9 +1000,11 @@ const TRANSLATIONS = {
'error.invalid_request': 'Некорректный запрос, проверьте введённые данные.',
'error.invalid_amount': 'Введите сумму больше нуля.',
'error.broadcast_failed': 'Сеть отклонила транзакцию. Попробуйте ещё раз через минуту.',
'error.service_busy': 'Сервис сейчас занят, ничего не было отправлено. Попробуйте ещё раз через минуту.',
'error.amount_below_dust_limit': 'Сумма слишком мала для отправки.',
'error.too_many_inputs': 'Ваш баланс разбит на слишком много мелких депозитов, чтобы потратить его одной транзакцией (максимум {max_inputs}). Обратитесь в поддержку для консолидации.',
'error.withdrawal_to_own_address': 'Это ваш собственный адрес для депозита — выводите на внешний кошелёк.',
'error.withdrawal_to_platform_address': 'Это адрес самой платформы — выводите на внешний кошелёк.',
'error.internal_error': 'Непредвиденная ошибка сервера. Попробуйте ещё раз через минуту.',
'error.guide_unavailable': 'Руководство сейчас недоступно.',
'error.rate_limited': 'Слишком много попыток, повторите через {retry_after_seconds} сек.',
@@ -1139,6 +1157,7 @@ const TRANSLATIONS = {
'error.balance_pending_confirmation': '您有 {pending_plm} PLM 待确认 —— 尚不可用于支出。',
'error.amount_below_network_fee': '金额太小,不足以支付网络手续费。',
'error.invalid_address': 'PLM 地址无效(必须以 plm1q… 开头)。',
'error.round_not_found': '未找到该轮次。',
'error.amount_below_minimum': '最低提现金额为 {minimum_plm} PLM。',
'error.current_password_incorrect': '当前密码不正确。',
'error.password_too_short': '新密码长度至少需要 {minimum} 个字符。',
@@ -1149,9 +1168,11 @@ const TRANSLATIONS = {
'error.invalid_request': '请求无效,请检查填写的内容。',
'error.invalid_amount': '请输入大于零的金额。',
'error.broadcast_failed': '网络拒绝了该交易,请稍后重试。',
'error.service_busy': '服务当前繁忙,没有发送任何内容,请稍后重试。',
'error.amount_below_dust_limit': '金额过小,无法发送。',
'error.too_many_inputs': '您的余额分散在过多的小额存款中,无法在一笔交易中花费(最多 {max_inputs} 笔)。请联系客服进行归集。',
'error.withdrawal_to_own_address': '这是你自己的充值地址 — 请提现到外部钱包。',
'error.withdrawal_to_platform_address': '这是平台自己的地址 — 请提现到外部钱包。',
'error.internal_error': '服务器发生意外错误,请稍后重试。',
'error.guide_unavailable': '指南当前不可用。',
'error.rate_limited': '尝试次数过多,请在 {retry_after_seconds} 秒后重试。',
+123 -24
View File
@@ -6,13 +6,24 @@ from embit import script
from embit.psbt import PSBT
from embit.transaction import Transaction, TransactionInput, TransactionOutput
from embit.finalizer import finalize_psbt
from sqlalchemy import select
from sqlalchemy import select, update
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from app.db.models import PendingTransaction, Round, RoundParticipant, User, UtxoEvent, Withdrawal
from app.db.base import begin_immediate
from app.db.models import (
PendingTransaction,
PendingTransactionTxid,
Round,
RoundParticipant,
User,
UtxoEvent,
Withdrawal,
)
from app.electrum.client import ElectrumClient
from app.rounds.config import get_round_config
from app.wallet.hd import derive_pool_key, derive_user_key
from app.tx.outcome import BroadcastOutcome, TransactionNetwork, broadcast_with_verdict
from app.tx.versions import record_version
from app.wallet.hd import derive_round_pool_key, derive_user_key
from app.wallet.plm_network import PLM_MAINNET
from app.wallet.psbt_builder import MAX_FEE_RATE_SAT_VB, RBF_SEQUENCE, estimate_vsize
@@ -48,12 +59,18 @@ def should_bump(pending: PendingTransaction, now: datetime, timeout_seconds: int
return now >= pending.last_broadcast_at.replace(tzinfo=timezone.utc) + timedelta(seconds=timeout_seconds)
async def _signing_context(session: AsyncSession, kind: str, user_id: int | None) -> tuple:
async def _signing_context(
session: AsyncSession, kind: str, user_id: int | None, round_id: int | None = None
) -> tuple:
"""Returns (signing_key, own_script, own_address) for the single sender that
controls every input of this tx — a user for bet/withdrawal, the pool for
payout. All our builders only ever spend one address's UTXOs per tx."""
payout (the round's own pool key, B-80). All our builders only ever spend one
address's UTXOs per tx."""
if kind == "payout":
key = derive_pool_key()
round_ = await session.get(Round, round_id) if round_id is not None else None
if round_ is None or not round_.pool_address:
raise RbfError(f"payout of round {round_id}: the round has no pool address")
key = derive_round_pool_key(round_.id, round_.pool_address)
else:
user = await session.get(User, user_id)
key = derive_user_key(user.derivation_index)
@@ -86,28 +103,42 @@ def _find_change_output(tx: Transaction, change_address: str) -> int | None:
async def bump_fee(
session_factory: async_sessionmaker, client: ElectrumClient, pending_id: int
session_factory: async_sessionmaker,
client: ElectrumClient,
pending_id: int,
network: TransactionNetwork | None = None,
) -> str | None:
"""Rebuild pending_transaction `pending_id`'s transaction with a higher fee
(same inputs, same recipient outputs, the extra fee taken from the change
output) and rebroadcast. Returns the new txid, or None if there was nothing
to do (the row is gone or already left "pending" — a normal race with
confirmation, not an error).
confirmation, not an error, or a conflict recorded below).
Three phases, so no DB session is held across the network calls this needs
Four phases, so no DB session is held across the network calls this needs
(one get_transaction per input, then a broadcast) — the same shape used
elsewhere for exactly this reason (B-18, rounds/scheduler.py:_trigger_payout;
B-31, electrum/listener.py:refresh_user) and now here too (B-40): read what's
needed and close the session, do the chain work, then reopen to persist.
B-77 (TX-12, TX-13, DAT-34): the replacement is **written before it is broadcast**.
It used to be sent in the chain phase and recorded afterwards, unconditionally, so
a crash or a `database is locked` in between left a transaction on the network
that the database did not know, and an abandon or a confirmation that happened in
the meantime was silently overwritten. Now the signed replacement is committed as
a *candidate* version (pending_transaction_txids) first; a candidate that is never
broadcast is harmless, and one that is — and then confirms — is recognised like any
other version. After the broadcast the row is switched over with a conditional
UPDATE (status still pending, current_txid still the one replaced); zero rows
matched is a conflict: the row is left alone, the candidate stays recorded, and
the reconciler resolves it.
Only handles the common case: exactly one change output paying back to the
tx's own sender address, large enough to absorb the increase. If there's no
such output (e.g. an exact-amount bet with no change), this raises RbfError —
bumping such a tx would require selecting additional inputs, which isn't
implemented for the MVP; it needs manual operator intervention. Also raises
RbfError, rather than bumping, once the row is already at MAX_FEE_RATE_SAT_VB
(B-32) — the reconciler abandons it if it never confirms (B-27), instead of
this retrying an ever-higher fee forever.
(B-32), and when the network explicitly refuses the replacement (TX-24).
"""
# --- Phase 1: read what's needed, close the session before any network call ---
async with session_factory() as session:
@@ -124,9 +155,10 @@ async def bump_fee(
kind = pending.kind
current_fee_rate = pending.fee_rate_sat_vb
raw_tx_hex = pending.raw_tx_hex
signing_key, own_script, own_address = await _signing_context(session, kind, pending.user_id)
old_txid = pending.current_txid
signing_key, own_script, own_address = await _signing_context(session, kind, pending.user_id, pending.round_id)
# --- Phase 2: chain reads, signing, and the broadcast — no DB session open ----
# --- Phase 2: chain reads and signing — no DB session open, nothing sent yet ---
old_tx = Transaction.parse(bytes.fromhex(raw_tx_hex))
input_amounts = [await _prevout_amount(client, vin) for vin in old_tx.vin]
total_in = sum(input_amounts)
@@ -171,26 +203,69 @@ async def bump_fee(
raw_hex = final_tx.serialize().hex()
new_txid = final_tx.txid().hex()
await client.broadcast(raw_hex)
# --- Phase 3: persist the outcome ----------------------------------------------
# --- Phase 3: record the replacement as a candidate, *then* broadcast ----------
async with session_factory() as session:
await begin_immediate(session) # B-88
pending = await session.get(PendingTransaction, pending_id)
old_txid = pending.current_txid
pending.replaced_by_txid = old_txid # points backwards: what current_txid replaced
pending.current_txid = new_txid
pending.raw_tx_hex = raw_hex
if pending is None or pending.status != "pending" or pending.current_txid != old_txid:
logger.info("pending_transaction %s changed while its bump was being built; skipping", pending_id)
return None
await record_version(session, pending, new_txid, raw_hex) # B-77 (TX-12, DAT-71)
await session.commit()
verdict = await broadcast_with_verdict(client, network, raw_hex, new_txid) # B-76: also fans out
if verdict.outcome is BroadcastOutcome.REFUSED:
# The network explicitly refused the replacement and no server knows it: the row
# is unchanged and keeps the version that is on the network (TX-24). The
# candidate stays recorded — it was never relayed, so nobody will confirm it.
raise RbfError(f"pending_transaction {pending_id}: the network refused the replacement: {verdict.reason}")
# ACCEPTED, or UNCERTAIN: the replacement may well be on the network, so the row
# follows it (TX-12); the old version stays recorded and is still recognised should
# it be the one that confirms.
# --- Phase 4: switch the row over, conditionally --------------------------------
async with session_factory() as session:
await begin_immediate(session) # B-88
# The *actual* resulting rate, not target_fee_rate: when the BIP125-minimum
# floor above raised fee_delta past the naive target, the tx now pays more
# than target_fee_rate implied. Recording the true rate keeps the next bump's
# arithmetic honest instead of drifting from what's really being paid.
pending.fee_rate_sat_vb = (old_fee + fee_delta) // vsize
pending.attempt_count += 1
# last_broadcast_at, not broadcast_at (B-27): broadcast_at must stay the *first*
# broadcast, since reconcile.py's abandon-after-N-hours grace period is measured
# from it — overwriting it here used to reset that clock on every bump, so a
# repeatedly-bumped-but-never-mined tx was never abandoned.
pending.last_broadcast_at = datetime.now(timezone.utc)
result = await session.execute(
update(PendingTransaction)
.where(
PendingTransaction.id == pending_id,
PendingTransaction.status == "pending",
PendingTransaction.current_txid == old_txid,
)
.values(
replaced_by_txid=old_txid, # points backwards: what current_txid replaced
current_txid=new_txid,
raw_tx_hex=raw_hex,
fee_rate_sat_vb=(old_fee + fee_delta) // vsize,
attempt_count=PendingTransaction.attempt_count + 1,
last_broadcast_at=datetime.now(timezone.utc),
)
.execution_options(synchronize_session=False)
)
if result.rowcount != 1:
# Confirmed, abandoned or already re-bumped while we were broadcasting. The
# row is not overwritten; the candidate is still recorded, and confirmation
# and reconciliation look for it like any other version (TX-13).
await session.rollback()
logger.warning(
"bump of pending_transaction %s: the row changed during the broadcast (replaced %s by %s); "
"left to the reconciler",
pending_id,
old_txid,
new_txid,
)
return None
pending = await session.get(PendingTransaction, pending_id)
await _retarget_txid_references(session, pending, old_txid, new_txid)
await session.commit()
@@ -198,6 +273,29 @@ async def bump_fee(
return new_txid
async def adopt_version(session: AsyncSession, pending: PendingTransaction, txid: str) -> None:
"""The network confirmed (or holds) a version of this row other than the current one
— an earlier version of a bumped transaction, or a candidate whose switch-over never
happened (B-77, TX-19, DAT-14). `current_txid` and `raw_tx_hex` become that
version's, and the txid is propagated everywhere it is recorded, exactly as after a
bump; without it the inputs of a replaced transaction would no longer be
recognised as the row's (DAT-13)."""
if txid == pending.current_txid:
return
version = await session.scalar(
select(PendingTransactionTxid).where(
PendingTransactionTxid.txid == txid, PendingTransactionTxid.pending_transaction_id == pending.id
)
)
old_txid = pending.current_txid
pending.replaced_by_txid = old_txid
pending.current_txid = txid
if version is not None and version.raw_hex:
pending.raw_tx_hex = version.raw_hex # empty only for a migration-reconstructed txid
await _retarget_txid_references(session, pending, old_txid, txid)
logger.warning("pending_transaction %s: version %s found on the network, replacing %s", pending.id, txid, old_txid)
async def _retarget_txid_references(
session: AsyncSession, pending: PendingTransaction, old_txid: str, new_txid: str
) -> None:
@@ -239,9 +337,10 @@ async def _retarget_txid_references(
class RbfBumper:
def __init__(self, session_factory: async_sessionmaker, get_client):
def __init__(self, session_factory: async_sessionmaker, get_client, network: TransactionNetwork | None = None):
self._session_factory = session_factory
self._get_client = get_client
self._network = network # B-76/B-77: verifies and fans out a replacement
async def run(self) -> None:
while True:
@@ -266,7 +365,7 @@ class RbfBumper:
for pending_id in due_ids:
try:
await bump_fee(self._session_factory, client, pending_id)
await bump_fee(self._session_factory, client, pending_id, network=self._network)
except RbfError:
logger.exception("could not bump pending_transaction %s", pending_id)
except Exception:
+57 -10
View File
@@ -1,15 +1,19 @@
import asyncio
import logging
from collections.abc import Awaitable, Callable
from typing import Protocol
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from app.db.base import begin_immediate
from app.db.models import PendingTransaction
from app.electrum.client import ElectrumClient
from app.electrum.scripthash import address_to_scripthash
from app.rounds.events import broadcaster
from app.tx.broadcast import adopt_version
from app.tx.pending_address import own_address_for
from app.tx.versions import txids_by_row
logger = logging.getLogger(__name__)
@@ -26,7 +30,19 @@ def register_handler(kind: str, handler: ConfirmationHandler) -> None:
_handlers[kind] = handler
async def poll_once(session_factory: async_sessionmaker, client: ElectrumClient) -> int:
class ConfirmationProver(Protocol):
"""The part of ElectrumListener a confirmation needs (B-83): the quorum's verdict on
a merkle proof of `txid` at `height`."""
async def confirmation_proven(self, txid: str, height: int) -> bool: ...
async def poll_once(session_factory: async_sessionmaker, client: ElectrumClient, network: ConfirmationProver | None) -> int:
"""One pass over the `pending` rows. The active server's history only nominates a
candidate: a row is confirmed when the quorum proves it with a merkle proof
(B-83, TX-22). With no `network` to ask nothing can be confirmed — the active
server's word alone is exactly what a hostile one would use to declare a payout that
was never broadcast confirmed."""
async with session_factory() as session:
# Plain columns, not entities: nothing then outlives the session, so this
# can't break if expire_on_commit is ever turned on (B-21).
@@ -37,24 +53,28 @@ async def poll_once(session_factory: async_sessionmaker, client: ElectrumClient)
PendingTransaction.current_txid,
PendingTransaction.kind,
PendingTransaction.user_id,
PendingTransaction.round_id,
).where(PendingTransaction.status == "pending")
)
).all()
# Resolved once per candidate while the session is still open, and cached
# by scripthash below — every "payout" row shares the same pool address,
# so this also avoids asking the server the same history twice per tick.
# by scripthash below — the payout rows of one round share its pool
# address (B-80), so this also avoids asking the server the same history twice.
scripthash_by_id: dict[int, str] = {}
for pending_id, _txid, kind, user_id in candidates:
# B-77 (TX-06, TX-19): every txid a row ever had, not only the current one — an
# earlier version of a bumped transaction may be the one that confirms.
txids_by_id = await txids_by_row(session, {pending_id: txid for pending_id, txid, *_ in candidates})
for pending_id, _txid, kind, user_id, round_id in candidates:
try:
address = await own_address_for(session, kind, user_id)
address = await own_address_for(session, kind, user_id, round_id)
scripthash_by_id[pending_id] = address_to_scripthash(address)
except Exception:
logger.exception("could not derive the address for pending_transaction %s", pending_id)
confirmed = 0
history_cache: dict[str, list[dict]] = {}
for pending_id, txid, kind, _user_id in candidates:
for pending_id, txid, kind, _user_id, _round_id in candidates:
scripthash = scripthash_by_id.get(pending_id)
if scripthash is None:
continue # address derivation failed above; already logged
@@ -72,17 +92,38 @@ async def poll_once(session_factory: async_sessionmaker, client: ElectrumClient)
logger.warning("could not fetch history for pending_transaction %s (txid %s)", pending_id, txid, exc_info=True)
continue
entry = next((e for e in history_cache[scripthash] if e.get("tx_hash") == txid), None)
known_txids = txids_by_id[pending_id]
# height > 0 means confirmed at that height; 0 or absent means still in
# the mempool (or the server doesn't know this txid at all yet) — either
# way, not confirmed, so keep waiting.
if entry is None or entry.get("height", 0) <= 0:
entry = next(
(e for e in history_cache[scripthash] if e.get("tx_hash") in known_txids and e.get("height", 0) > 0),
None,
)
if entry is None:
continue
# B-83 (TX-22, ELC-26): the height is a claim of the active server. The quorum has
# to return a valid merkle proof of the txid against that block's header; without
# one the row stays pending and is looked at again on the next pass.
if network is None or not await network.confirmation_proven(entry["tx_hash"], entry["height"]):
logger.warning(
"pending_transaction %s: %s reported at height %s but the quorum did not prove it — still pending",
pending_id,
entry["tx_hash"],
entry["height"],
)
continue
async with session_factory() as session:
await begin_immediate(session) # B-88: read the row and write its outcome under one lock
row = await session.get(PendingTransaction, pending_id)
if row is None or row.status != "pending":
continue
if entry["tx_hash"] != row.current_txid:
# The confirmed version is not the current one (B-77, DAT-14): realign
# the row and everything that recorded its txid *before* the handler runs.
await adopt_version(session, row, entry["tx_hash"])
row.status = "confirmed"
handler = _handlers.get(kind)
if handler is not None:
@@ -95,16 +136,22 @@ async def poll_once(session_factory: async_sessionmaker, client: ElectrumClient)
class ConfirmationPoller:
def __init__(self, session_factory: async_sessionmaker, get_client: Callable[[], ElectrumClient | None]):
def __init__(
self,
session_factory: async_sessionmaker,
get_client: Callable[[], ElectrumClient | None],
network: ConfirmationProver | None = None,
):
self._session_factory = session_factory
self._get_client = get_client
self._network = network # the ElectrumListener, which holds the headers and asks the quorum
async def run(self) -> None:
while True:
client = self._get_client()
if client is not None:
try:
await poll_once(self._session_factory, client)
await poll_once(self._session_factory, client, self._network)
except asyncio.CancelledError:
raise
except Exception:
+101
View File
@@ -0,0 +1,101 @@
"""What a broadcast attempt amounted to (B-76, TX-04, TX-20, TX-21).
Money may only be released on proof that a transaction never left. The text of an
Electrum error cannot give that proof (servers word "already in the mempool" in many
ways and there is no standard code), and a timeout or a dropped connection says
nothing about whether the server acted before it went quiet. So a broadcast ends in
one of three ways, and only one of them frees coins:
ACCEPTED the server answered with the txid, or refused but at least one server of
the network (the active one or any other) returns the transaction;
REFUSED the server answered with an explicit JSON-RPC error *and* the active
server plus the quorum minimum of the others all say they do not know the
transaction;
UNCERTAIN anything else — a timeout, a dropped connection, a write error, a
refusal whose verification could not get enough answers.
"""
import logging
from enum import Enum
from typing import NamedTuple, Protocol
from app.electrum.client import ElectrumRpcError
logger = logging.getLogger(__name__)
# Messages by which a node says it already has the transaction. Recognising one skips
# the verification below; *not* recognising a message never releases anything, it only
# costs one more round of questions (TX-04).
_ALREADY_KNOWN_MARKERS = (
"already known",
"already in mempool",
"already in the mempool",
"txn-already-known",
"txn-already-in-mempool",
"already in block chain",
"already in blockchain",
)
class BroadcastOutcome(Enum):
ACCEPTED = "accepted"
REFUSED = "refused"
UNCERTAIN = "uncertain"
class BroadcastVerdict(NamedTuple):
outcome: BroadcastOutcome
reason: str # the server's own wording or the failure's, for logs and audit rows
class TransactionNetwork(Protocol):
"""The part of ElectrumListener a broadcast needs (see electrum/listener.py)."""
async def transaction_known(self, txid: str) -> bool | None: ...
def fan_out_transaction(self, raw_tx_hex: str) -> None: ...
def is_already_known(message: str) -> bool:
lowered = message.lower()
return any(marker in lowered for marker in _ALREADY_KNOWN_MARKERS)
async def broadcast_with_verdict(client, network: TransactionNetwork | None, raw_tx_hex: str, txid: str) -> BroadcastVerdict:
"""Broadcast `raw_tx_hex` through the active `client` and say what happened.
With no `network` to ask, an explicit refusal cannot be verified and therefore
comes back UNCERTAIN: the doubt never frees coins. An accepted transaction is
sent to every other server too (best effort, TX-21)."""
try:
await client.broadcast(raw_tx_hex)
except ElectrumRpcError as exc:
reason = exc.message
if is_already_known(reason):
known: bool | None = True
elif network is None:
known = None
else:
known = await network.transaction_known(txid)
if known is True:
_fan_out(network, raw_tx_hex)
return BroadcastVerdict(BroadcastOutcome.ACCEPTED, reason)
if known is False:
return BroadcastVerdict(BroadcastOutcome.REFUSED, reason)
logger.warning("broadcast of %s was refused (%s) but the refusal could not be verified", txid, reason)
return BroadcastVerdict(BroadcastOutcome.UNCERTAIN, reason)
except Exception as exc:
# Timeout, dropped connection, write error: the server may have relayed it.
logger.warning("broadcast of %s ended without an answer (%r): outcome uncertain", txid, exc)
return BroadcastVerdict(BroadcastOutcome.UNCERTAIN, str(exc) or type(exc).__name__)
_fan_out(network, raw_tx_hex)
return BroadcastVerdict(BroadcastOutcome.ACCEPTED, "")
def _fan_out(network: TransactionNetwork | None, raw_tx_hex: str) -> None:
if network is None:
return
try:
network.fan_out_transaction(raw_tx_hex)
except Exception:
logger.exception("could not start the fan-out of an accepted transaction")
+11 -5
View File
@@ -1,12 +1,15 @@
from sqlalchemy.ext.asyncio import AsyncSession
from app.db.models import User
from app.wallet.hd import derive_pool_address, derive_user_address
from app.db.models import Round, User
from app.wallet.hd import derive_user_address
async def own_address_for(session: AsyncSession, kind: str, user_id: int | None) -> str:
async def own_address_for(
session: AsyncSession, kind: str, user_id: int | None, round_id: int | None = None
) -> str:
"""The address that owns every input of a PendingTransaction of this kind —
a user's own address for a bet/withdrawal, the pool address for a payout.
a user's own address for a bet/withdrawal, the pool address of the round for a
payout (B-80: each round has its own, stored on the round).
All our builders only ever spend one address's UTXOs per tx (see
tx/broadcast.py:_signing_context, which derives the same address alongside
the signing key it also needs).
@@ -17,6 +20,9 @@ async def own_address_for(session: AsyncSession, kind: str, user_id: int | None)
different addresses for the same row.
"""
if kind == "payout":
return derive_pool_address()
round_ = await session.get(Round, round_id) if round_id is not None else None
if round_ is None or not round_.pool_address:
raise ValueError(f"payout of round {round_id}: the round has no pool address")
return round_.pool_address
user = await session.get(User, user_id)
return derive_user_address(user.derivation_index)
+258 -48
View File
@@ -13,15 +13,26 @@ balance simply lost them, with no path back short of editing the DB by hand
What it does, per PendingTransaction that isn't already terminal:
* status "building" — we crashed (or were killed) between writing the row and
broadcasting. Ask the chain: if the tx is there after all, promote everything
to its live state; if it isn't, release the UTXOs and undo the intent.
broadcasting. Ask the network: if any server knows one of the row's txids,
promote everything to its live state.
* status "pending" — broadcast, still unconfirmed. Left alone until it has been
unconfirmed for `_ABANDON_AFTER_SECONDS`, since absence from one server's
mempool is not proof of death; only then is it abandoned like the above.
unconfirmed for `_ABANDON_AFTER_SECONDS`, and even then only examined.
Deliberately conservative: it never touches a tx the chain knows about, and the
grace period is long (multiples of the RBF timeout) so a slow-but-alive tx is
bumped by RbfBumper rather than abandoned here.
and then *nothing is given up without proof* (B-78, ADR-51, TX-17). A row is
abandoned — its coins released — only when
(a) one of its inputs is spent **in a block** by a transaction that is none of its
own versions, and the other servers agree; or
(b) no server of the quorum knows any txid of the row **and** sending its latest
raw transaction to every server is refused, explicitly and by all of them, for
missing or already-spent inputs.
Absence from one server's history proves nothing — after a restart onto a different
server that is the normal state of a tx the new server has not seen — and neither
does the age of the row. A refusal for fee reasons is no proof either: such a row is
promoted (building) or left to the RBF bumper (pending). A transport failure never
resolves anything. Failed rows stay watched for `FAILED_WATCH_DAYS`: if one of them
confirms after all, the lottery is paused for the operator (TX-23).
"""
import asyncio
@@ -34,11 +45,24 @@ from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from app.audit.log import write_audit_log
from app.db.models import PendingTransaction, Round, RoundParticipant, UtxoEvent, Withdrawal
from app.db.base import begin_immediate
from app.db.models import (
PendingTransaction,
PendingTransactionTxid,
Round,
RoundParticipant,
UtxoEvent,
Withdrawal,
)
from app.electrum.client import ElectrumClient
from app.electrum.quorum import ServerAnswers
from app.electrum.scripthash import address_to_scripthash
from app.rounds.events import broadcaster
from app.rounds.pause import pause_automatically
from app.tx.broadcast import adopt_version
from app.tx.outcome import is_already_known
from app.tx.pending_address import own_address_for
from app.tx.versions import txids_by_row, txids_of
from app.wallet.balance import recompute_balance
logger = logging.getLogger(__name__)
@@ -50,14 +74,32 @@ _POLL_INTERVAL_SECONDS = 120
_BUILDING_GRACE_SECONDS = 120
# A "pending" row was accepted by a node once. Give it a wide margin — the RBF
# bumper gets several attempts inside this window — before concluding it's gone.
# bumper gets several attempts inside this window — before it is even examined.
_ABANDON_AFTER_SECONDS = 6 * 60 * 60
# How long a failed row keeps being looked at (B-78, DAT-72): a transaction given up
# for dead can still arrive in a block.
FAILED_WATCH_DAYS = 14
# How many distinct (txid, height) claims of one failed row are put to the quorum per pass.
_MAX_RESURRECTION_CLAIMS = 3
# What a node says when the transaction's inputs do not exist or are spent already.
_MISSING_INPUTS_MARKERS = ("missing-inputs", "missingorspent", "missing inputs", "inputs-missing")
# What it says when only the fee is the problem: not proof of anything.
_FEE_MARKERS = ("min relay fee", "mempool min fee", "insufficient fee", "fee not met", "fee too low", "fee rate")
class PendingTransactionReconciler:
def __init__(self, session_factory: async_sessionmaker, get_client: Callable[[], ElectrumClient | None]):
def __init__(
self,
session_factory: async_sessionmaker,
get_client: Callable[[], ElectrumClient | None],
network=None,
):
self._session_factory = session_factory
self._get_client = get_client
self._network = network # the ElectrumListener: histories of every server, rebroadcast, spenders
async def run(self) -> None:
# Runs once promptly at startup: a crash mid-broadcast is exactly the case
@@ -66,7 +108,7 @@ class PendingTransactionReconciler:
client = self._get_client()
if client is not None:
try:
await reconcile_once(self._session_factory, client)
await reconcile_once(self._session_factory, client, self._network)
except asyncio.CancelledError:
raise
except Exception:
@@ -74,81 +116,246 @@ class PendingTransactionReconciler:
await asyncio.sleep(_POLL_INTERVAL_SECONDS)
async def reconcile_once(session_factory: async_sessionmaker, client: ElectrumClient) -> int:
"""Returns how many rows were resolved (promoted or abandoned).
class _Candidate:
__slots__ = ("row_id", "status", "txid", "scripthash", "known_txids", "raw_hex")
Existence is decided by checking whether a row's own address's history
(blockchain.scripthash.get_history) includes its txid at all — mempool or
mined — rather than asking blockchain.transaction.get for a verbose reply
(B-41): several Electrum server implementations and versions reject the
verbose flag outright, and the previous substring-matching on the error
text (looking for "missing", "not found", ...) was fragile as the basis for
a decision that releases funds. A transport failure fetching history still
raises and leaves the row alone until next time — get_history not
returning our txid is the only thing that means "gone". History is cached
per scripthash within one pass, since every "payout" row shares the same
pool address.
def __init__(self, row_id, status, txid, scripthash, known_txids, raw_hex):
self.row_id = row_id
self.status = status
self.txid = txid
self.scripthash = scripthash
self.known_txids = known_txids
self.raw_hex = raw_hex
async def reconcile_once(
session_factory: async_sessionmaker, client: ElectrumClient, network=None
) -> int:
"""Returns how many rows were resolved (promoted, abandoned, realigned or
resurrected).
Existence is decided by asking every server of the quorum for the history of the
row's own address (blockchain.scripthash.get_history) and looking for **every** txid
the row has had, mempool or mined (B-41, B-77, B-78) — never for a verbose
blockchain.transaction.get reply, which several servers reject outright, and never
on error text. History is cached per scripthash within one pass, since the payout
rows of one round share its pool address (B-80). With no `network` only the active
server is asked, which can promote a row but never abandon one.
"""
now = datetime.now(timezone.utc)
async with session_factory() as session:
rows = (
await session.scalars(
select(PendingTransaction).where(PendingTransaction.status.in_(("building", "pending")))
select(PendingTransaction).where(PendingTransaction.status.in_(("building", "pending", "failed")))
)
).all()
candidates = []
txids_by_id = await txids_by_row(session, {row.id: row.current_txid for row in rows})
candidates: list[_Candidate] = []
for row in rows:
if not _is_due(row, now):
continue
try:
address = await own_address_for(session, row.kind, row.user_id)
address = await own_address_for(session, row.kind, row.user_id, row.round_id)
scripthash = address_to_scripthash(address)
except Exception:
logger.exception("could not derive the address for pending_transaction %s", row.id)
continue
candidates.append((row.id, row.status, row.current_txid, scripthash))
candidates.append(
_Candidate(row.id, row.status, row.current_txid, scripthash, txids_by_id[row.id], row.raw_tx_hex)
)
resolved = 0
history_cache: dict[str, list[dict]] = {}
for row_id, status, txid, scripthash in candidates:
history_cache: dict[str, ServerAnswers] = {}
for candidate in candidates:
try:
if scripthash not in history_cache:
history_cache[scripthash] = await client.get_history(scripthash)
exists = any(entry.get("tx_hash") == txid for entry in history_cache[scripthash])
if candidate.scripthash not in history_cache:
history_cache[candidate.scripthash] = await _histories(client, network, candidate.scripthash)
answers = history_cache[candidate.scripthash]
decision = await _decide(network, candidate, answers)
except Exception:
# Transport/server problem — say nothing about this tx and try again on
# the next pass rather than abandoning a tx that may be perfectly alive.
logger.warning("could not check pending_transaction %s (txid %s) against the chain", row_id, txid)
logger.warning(
"could not check pending_transaction %s (txid %s) against the chain",
candidate.row_id,
candidate.txid,
exc_info=True,
)
continue
if decision is None:
continue
async with session_factory() as session:
row = await session.get(PendingTransaction, row_id)
if row is None or row.status != status:
continue # something else moved it while we were asking
if exists:
await begin_immediate(session) # B-88: the re-check and the resolution under one lock
row = await session.get(PendingTransaction, candidate.row_id)
# TX-26: the status *and* the current txid must still be what they were when
# the network was asked — a confirmation or an RBF in the meantime changes
# what the answer means.
if row is None or row.status != candidate.status or row.current_txid != candidate.txid:
continue
kind, payload = decision
changed = False
if kind == "resurrected":
await _resurrect(session, row, *payload)
changed = True
elif kind == "present":
if payload and payload != row.current_txid:
# Another version of the row is the one on the network (B-77, TX-19):
# the row follows it, so the inputs and the domain row point at it.
await adopt_version(session, row, payload)
changed = True
if row.status == "building":
await _promote(session, row)
resolved += 1
else:
await _abandon(session, row, "not found on chain")
resolved += 1
changed = True
elif kind == "promote":
await _promote(session, row)
changed = True
elif kind == "abandon":
await _abandon(session, row, payload)
changed = True
await session.commit()
resolved += changed
broadcaster.publish()
return resolved
async def _histories(client: ElectrumClient, network, scripthash: str) -> ServerAnswers:
if network is not None:
return await network.get_histories(scripthash)
# No quorum to ask: the active server alone can show a transaction exists, but its
# silence can never be taken for absence (`complete` stays false).
return ServerAnswers(await client.get_history(scripthash), (), 1)
def _entries_for(answers: ServerAnswers, known_txids: set[str]) -> list[tuple[str, int, bool]]:
"""(txid, height, from_active) for every history entry of every answering server that
is one of the row's txids."""
found: list[tuple[str, int, bool]] = []
if answers.active is not None:
found += [(e["tx_hash"], e.get("height") or 0, True) for e in answers.active if e.get("tx_hash") in known_txids]
for history in answers.answered_others:
found += [(e["tx_hash"], e.get("height") or 0, False) for e in history if e.get("tx_hash") in known_txids]
return found
def _confirmed_candidates(answers: ServerAnswers, known_txids: set[str]) -> list[tuple[str, int]]:
"""(txid, height) of every txid of the row that any answering server lists in a block,
the one most servers agree on first. They are only *claims*: each is proven by the
quorum's merkle proofs before it is believed (B-83, TX-22)."""
votes: dict[tuple[str, int], int] = {}
for history in answers.all:
for entry in history:
if entry.get("tx_hash") in known_txids and (entry.get("height") or 0) > 0:
key = (entry["tx_hash"], entry["height"])
votes[key] = votes.get(key, 0) + 1
return [key for key, _ in sorted(votes.items(), key=lambda item: -item[1])]
async def _decide(network, candidate: _Candidate, answers: ServerAnswers):
"""What the network says about one row, as ("present", txid | None), ("promote", None),
("abandon", reason), ("resurrected", (txid, height)) or None for "nothing to do or
not enough to tell". Pure reads — nothing is written here."""
if candidate.status == "failed":
if network is None:
return None # nothing can be proven without the quorum
for txid, height in _confirmed_candidates(answers, candidate.known_txids)[:_MAX_RESURRECTION_CLAIMS]:
if await network.confirmation_proven(txid, height):
return ("resurrected", (txid, height))
return None
found = _entries_for(answers, candidate.known_txids)
if found:
# Prefer a version that is mined, then the current one, then any.
mined = [txid for txid, height, _ in found if height > 0]
present = {txid for txid, _, _ in found}
chosen = mined[0] if mined else (candidate.txid if candidate.txid in present else found[0][0])
return ("present", chosen)
if not answers.complete:
logger.warning(
"pending_transaction %s (txid %s): too few servers answered to say the tx is unknown — left as is",
candidate.row_id,
candidate.txid,
)
return None
if network is None:
return None
# No server of the quorum knows any txid of the row. That alone proves nothing (TX-15).
tx = Transaction.parse(bytes.fromhex(candidate.raw_hex))
outpoints = {(vin.txid.hex(), vin.vout) for vin in tx.vin}
spender = await network.confirmed_spender(candidate.scripthash, candidate.known_txids, outpoints)
if spender is not None:
return ("abandon", f"input spent in a block by {spender}")
rebroadcast: ServerAnswers = await network.rebroadcast_everywhere(candidate.raw_hex)
verdicts = rebroadcast.all
if any(v[0] == "accepted" or (v[0] == "refused" and is_already_known(v[1])) for v in verdicts):
# It was alive after all (or is again): the same as having found it.
return ("present", None)
refusals = [v[1].lower() for v in verdicts if v[0] == "refused"]
if rebroadcast.complete and len(refusals) == len(verdicts) and all(
any(marker in message for marker in _MISSING_INPUTS_MARKERS) for message in refusals
):
return ("abandon", f"rebroadcast refused for missing inputs: {refusals[0]}")
if candidate.status == "building" and any(any(marker in m for marker in _FEE_MARKERS) for m in refusals):
return ("promote", None) # not proof: let the RBF bumper accelerate it (TX-17)
return None
def _is_due(row: PendingTransaction, now: datetime) -> bool:
if row.status == "failed":
# B-78 (TX-23, DAT-72): watched every pass for FAILED_WATCH_DAYS from failed_at.
failed_at = row.failed_at or row.updated_at
return failed_at is not None and now < failed_at.replace(tzinfo=timezone.utc) + timedelta(days=FAILED_WATCH_DAYS)
# Deliberately broadcast_at (the *first* broadcast), not last_broadcast_at: an
# RBF bump used to overwrite this same field, which reset this grace period on
# every bump and meant a repeatedly-bumped-but-never-mined tx was never
# abandoned (B-27). tx/broadcast.py:bump_fee now only ever touches
# last_broadcast_at, so this keeps measuring from when the tx first appeared,
# no matter how many times it's since been bumped.
# no matter how many times it's since been bumped. The period only decides from
# when a row is *examined*; giving it up still needs proof (TX-14, TX-17).
grace = _BUILDING_GRACE_SECONDS if row.status == "building" else _ABANDON_AFTER_SECONDS
return now >= row.broadcast_at.replace(tzinfo=timezone.utc) + timedelta(seconds=grace)
async def _resurrect(session: AsyncSession, row: PendingTransaction, txid: str, height: int) -> None:
"""A row given up for dead was mined (B-78, TX-23, DAT-72). The row becomes
`confirmed` and the lottery is paused for the operator: the domain rows the
abandonment already rolled back (a deleted participant, a failed withdrawal, released
coins, a rebuilt payout) are *not* put back by the system, which cannot know what has
happened to them since."""
if txid != row.current_txid:
version_raw = None
version = await session.scalar(
select(PendingTransactionTxid).where(
PendingTransactionTxid.txid == txid, PendingTransactionTxid.pending_transaction_id == row.id
)
)
if version is not None and version.raw_hex:
version_raw = version.raw_hex
row.current_txid = txid
if version_raw:
row.raw_tx_hex = version_raw
row.status = "confirmed"
await write_audit_log(
session,
"pending_tx_resurrected",
{"pending_transaction_id": row.id, "kind": row.kind, "txid": txid, "block_height": height},
user_id=row.user_id,
round_id=row.round_id,
)
await pause_automatically(session, "resurrected_tx")
logger.error(
"%s pending_transaction %s was given up as failed but tx %s is in block %s — lottery paused for the operator",
row.kind,
row.id,
txid,
height,
)
async def _promote(session: AsyncSession, row: PendingTransaction) -> None:
"""The tx did make it onto the chain before we died — finish what phase 2 of
place_bet/request_withdrawal would have done."""
@@ -178,10 +385,12 @@ async def _promote(session: AsyncSession, row: PendingTransaction) -> None:
async def _abandon(session: AsyncSession, row: PendingTransaction, reason: str) -> None:
"""The tx is gone for good. Release whatever it reserved so the funds come back,
and roll the domain row back to something truthful."""
reason = reason[:128]
row.status = "failed"
row.failure_reason = reason[:128]
row.failure_reason = reason
row.failed_at = datetime.now(timezone.utc) # B-78: starts the 14-day watch
released = await _release_inputs(session, row)
released = await _release_inputs(session, row, await txids_of(session, row))
if row.kind == "bet":
participant = await session.scalar(
@@ -239,7 +448,7 @@ async def _abandon(session: AsyncSession, row: PendingTransaction, reason: str)
)
async def _release_inputs(session: AsyncSession, row: PendingTransaction) -> int:
async def _release_inputs(session: AsyncSession, row: PendingTransaction, own_txids: set[str] | None = None) -> int:
"""Clear spent_txid on every UTXO this transaction consumed, so the balance
counts them again. The inputs come from the stored raw tx, which is kept current
across RBF bumps, so this works for a bumped tx too."""
@@ -255,8 +464,9 @@ async def _release_inputs(session: AsyncSession, row: PendingTransaction) -> int
select(UtxoEvent).where(UtxoEvent.txid == vin.txid.hex(), UtxoEvent.vout == vin.vout)
)
# Only release what this tx actually reserved: if another tx has since spent
# the same UTXO, its claim is the live one and must not be cleared.
if utxo is not None and utxo.spent_txid == row.current_txid:
# the same UTXO, its claim is the live one and must not be cleared. "This tx"
# is any version of the row (B-77, DAT-13), not only its current one.
if utxo is not None and utxo.spent_txid in (own_txids or {row.current_txid}):
utxo.spent_txid = None
released += 1
return released
+53
View File
@@ -0,0 +1,53 @@
"""The versions of a pending transaction (B-77, DAT-70, DAT-71, TX-19).
A bumped transaction has several txids and any of them may be the one that confirms.
Everything that looks a transaction up on the chain asks for all of them."""
from sqlalchemy import delete, select
from sqlalchemy.ext.asyncio import AsyncSession
from app.db.models import PendingTransaction, PendingTransactionTxid
async def record_version(session: AsyncSession, pending: PendingTransaction, txid: str, raw_hex: str) -> None:
"""Write `txid` as a version of `pending` in the caller's transaction. Idempotent for
the same pair (a bump retried after an uncertain broadcast rebuilds the same
transaction); a txid already held by another row is an error — it is unique across
the platform."""
if pending.id is None:
await session.flush()
existing = await session.scalar(select(PendingTransactionTxid).where(PendingTransactionTxid.txid == txid))
if existing is not None:
if existing.pending_transaction_id != pending.id:
raise ValueError(f"txid {txid} already belongs to pending_transaction {existing.pending_transaction_id}")
return
session.add(PendingTransactionTxid(pending_transaction_id=pending.id, txid=txid, raw_hex=raw_hex))
async def txids_of(session: AsyncSession, pending: PendingTransaction) -> set[str]:
"""Every txid of the row: all its recorded versions plus `current_txid` (a row
written before the table existed, or by a test, may have no version row for it)."""
rows = await session.scalars(
select(PendingTransactionTxid.txid).where(PendingTransactionTxid.pending_transaction_id == pending.id)
)
return {pending.current_txid, *rows.all()}
async def txids_by_row(session: AsyncSession, current: dict[int, str]) -> dict[int, set[str]]:
"""`txids_of` for many rows at once; `current` maps row id -> current_txid."""
result = {row_id: {txid} for row_id, txid in current.items()}
if not result:
return result
rows = await session.execute(
select(PendingTransactionTxid.pending_transaction_id, PendingTransactionTxid.txid).where(
PendingTransactionTxid.pending_transaction_id.in_(list(result))
)
)
for row_id, txid in rows.all():
result[row_id].add(txid)
return result
async def delete_versions(session: AsyncSession, pending_id: int) -> None:
"""The versions go with a `bet` row that a verified refusal deletes (DAT-38)."""
await session.execute(delete(PendingTransactionTxid).where(PendingTransactionTxid.pending_transaction_id == pending_id))
+31 -8
View File
@@ -50,14 +50,37 @@ def derive_user_wif(derivation_index: int) -> str:
return PrivateKey(key.secret, compressed=True, network=PLM_MAINNET).wif(network=PLM_MAINNET)
def derive_pool_key() -> HDKey:
"""The "indirizzo padre" from the flowchart: 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."""
return _load_account_key().derive("1/0")
def derive_pool_key(round_id: int | None = None) -> HDKey:
"""A pool key. With a `round_id`, that round's own key on branch 2 of the account
(`m/84'/746'/0'/2/<round_id>`, B-80, RND-35): its bets are paid to it and its
payout is signed with it, so one round's money and history never mix with another's.
Without one, the **reserve** key at branch 1, index 0 — the single pool address every
round used before B-80, still the pool of the rounds opened back then and the
destination of the payout's bump reserve. Branch 0 is users. Not a spec requirement
of the coin, an implementation choice to keep every key under the one encrypted
master key rather than in separate secrets."""
if round_id is None:
return _load_account_key().derive("1/0")
if round_id < 1:
raise ValueError(f"invalid round id {round_id}")
return _load_account_key().derive(f"2/{round_id}")
def derive_pool_address() -> str:
pub = derive_pool_key().to_public()
def derive_pool_address(round_id: int | None = None) -> str:
"""The pool address of a round (B-80), or the reserve address without a `round_id`."""
pub = derive_pool_key(round_id).to_public()
return script.p2wpkh(pub).address(network=PLM_MAINNET)
def derive_round_pool_key(round_id: int, pool_address: str) -> HDKey:
"""The key that controls `pool_address`, the address stored on round `round_id`.
A round opened before B-80 stores the reserve address and is signed with the reserve
key; every other round with its own. Checking the derived address against the stored
one means a key can never be used for money it does not control, and a mismatch (a
different master key, a corrupted row) fails loudly instead of building a transaction
that spends someone else's coins."""
for key in (derive_pool_key(round_id), derive_pool_key()):
if script.p2wpkh(key.to_public()).address(network=PLM_MAINNET) == pool_address:
return key
raise ValueError(f"round {round_id}: no pool key controls the stored address {pool_address!r}")
+11
View File
@@ -9,3 +9,14 @@ def encrypt_xprv(xprv_base58: str) -> bytes:
def decrypt_xprv(token: bytes) -> str:
return Fernet(settings.xprv_encryption_key).decrypt(token).decode()
def encrypt_round_seed(server_seed_hex: str) -> str:
"""B-73 (DAT-64, SEC-56): a round's secret encrypted at rest with the same key that
protects the master xprv, so a copy of the database alone never reveals it. The Fernet
token is ASCII, stored as text."""
return Fernet(settings.xprv_encryption_key).encrypt(server_seed_hex.encode()).decode()
def decrypt_round_seed(token: str) -> str:
return Fernet(settings.xprv_encryption_key).decrypt(token.encode()).decode()
+10 -1
View File
@@ -82,6 +82,11 @@ class InsufficientFundsError(Exception):
self.params = params
# B-73 (DAT-63): the recipient is always the first output of a single-recipient transaction
# (the change, when there is one, follows it) — which is what a bet records as `bet_vout`.
RECIPIENT_VOUT = 0
@dataclass
class Utxo:
txid: str
@@ -120,7 +125,11 @@ def select_utxos(
eat into their own bet/withdrawal, while the payout drains a pool holding one
UTXO per bet and needs MAX_PAYOUT_TX_INPUTS to be able to pay a full round at
all."""
ordered = sorted(utxos, key=lambda u: u.amount_sats, reverse=True)
# B-75: a UTXO below the dust limit is never offered, even if one is already on
# record: it costs more to spend than it is worth.
ordered = sorted(
(u for u in utxos if u.amount_sats >= DUST_LIMIT_SATS), key=lambda u: u.amount_sats, reverse=True
)
selected: list[Utxo] = []
total = 0
for utxo in ordered:
+86 -10
View File
@@ -1,16 +1,23 @@
import logging
from datetime import datetime, timezone
from embit import script
from sqlalchemy import select
from sqlalchemy.exc import OperationalError
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.errors import ApiError
from app.audit.log import write_audit_log
from app.db.models import PendingTransaction, User, UtxoEvent, Withdrawal
from app.db.base import begin_immediate
from app.db.models import PendingTransaction, Round, User, UtxoEvent, Withdrawal
from app.electrum.client import ElectrumClient
from app.rounds.config import get_round_config
from app.rounds.events import broadcaster
from app.tx.versions import record_version
from app.tx.outcome import BroadcastOutcome, TransactionNetwork, broadcast_with_verdict
from app.wallet.address import is_valid_plm_address
from app.wallet.balance import compute_pending_balance, recompute_balance
from app.wallet.hd import derive_user_key
from app.wallet.hd import derive_pool_address, derive_user_key
from app.wallet.psbt_builder import (
BuiltTransaction,
InsufficientFundsError,
@@ -19,12 +26,20 @@ from app.wallet.psbt_builder import (
)
logger = logging.getLogger(__name__)
class WithdrawalError(ApiError):
pass
async def request_withdrawal(
session: AsyncSession, client: ElectrumClient, user: User, external_address: str, amount_sats: int
session: AsyncSession,
client: ElectrumClient,
user: User,
external_address: str,
amount_sats: int,
network: TransactionNetwork | None = None,
) -> Withdrawal:
# Checked before anything else: an address from another chain parses fine as a
# witness program (see wallet/address.py), so without this the tx would build,
@@ -43,7 +58,35 @@ async def request_withdrawal(
"that is your own deposit address — withdraw to an external wallet instead",
)
# B-88 (DAT-74, TX-28): the write lock before the first read that decides
# anything, so the UTXOs selected below are the ones phase 1 then marks spent.
# Taken only after the checks that need no database at all, so a malformed
# request never queues for it. No lock within busy_timeout means nothing has been
# built or broadcast: the caller is asked to retry.
try:
await begin_immediate(session)
except OperationalError as exc:
raise WithdrawalError(
"service_busy", "the service is busy right now, nothing was sent — please try again"
) from exc
config = await get_round_config(session)
# B-80 (WDR-14): never to an address of the platform itself. Coins sent to a round's
# pool address land among that round's UTXOs, and to the reserve or fee address they
# leave the user's balance for good; the amount would be spent from the balance and
# then belong to nobody. Compared lower-cased, since bech32 is case-insensitive.
platform_addresses = {derive_pool_address().lower(), config.fee_address.strip().lower()}
platform_addresses.update(
address.lower() for address in await session.scalars(select(Round.pool_address).distinct()) if address
)
platform_addresses.discard("")
if external_address.strip().lower() in platform_addresses:
raise WithdrawalError(
"withdrawal_to_platform_address",
"that is an address of the platform itself — withdraw to an external wallet instead",
)
if amount_sats < config.bet_amount_sats:
raise WithdrawalError(
"amount_below_minimum",
@@ -125,16 +168,47 @@ async def request_withdrawal(
status="building",
)
session.add(pending)
await record_version(session, pending, built.txid, built.raw_hex) # B-77: the first version, with the row
await session.commit()
try:
await client.broadcast(built.raw_hex)
except Exception as exc:
await _release_failed_withdrawal(session, withdrawal, pending, built, user.id, str(exc))
raise WithdrawalError(
"broadcast_failed", f"the network refused the transaction: {exc}"
) from exc
# B-76 (TX-04, TX-20): only a verified refusal releases the coins. A timeout, a
# drop after the write, or a refusal nobody could verify may mean the transaction
# left: the withdrawal would then be paid out while its row said "failed" and its
# coins were spendable again. Those outcomes leave the rows "building".
verdict = await broadcast_with_verdict(client, network, built.raw_hex, built.txid)
if verdict.outcome is BroadcastOutcome.REFUSED:
try:
await _release_failed_withdrawal(session, withdrawal, pending, built, user.id, verdict.reason)
except OperationalError:
# B-88: the release could not be written (database busy). The rows stay
# "building", the state committed before the broadcast, and the
# reconciler resolves them against the chain.
await session.rollback()
logger.error(
"could not release the failed withdrawal %s: database busy, left to the reconciler", built.txid
)
raise WithdrawalError("broadcast_failed", f"the network refused the transaction: {verdict.reason}")
if verdict.outcome is BroadcastOutcome.UNCERTAIN:
logger.warning(
"withdrawal %s: broadcast outcome uncertain (%s), left 'building' for the reconciler",
built.txid,
verdict.reason,
)
await session.refresh(withdrawal)
broadcaster.publish()
return withdrawal
# B-88: after the broadcast nothing is undone. Without the lock the rows stay
# "building" and the reconciler promotes them; the caller sees the real status.
try:
await begin_immediate(session)
except OperationalError:
await session.rollback()
logger.error(
"withdrawal %s broadcast but the database is busy: left 'building' for the reconciler", built.txid
)
await session.refresh(withdrawal)
return withdrawal
withdrawal.status = "broadcast"
pending.status = "pending"
await write_audit_log(
@@ -162,6 +236,7 @@ async def _release_failed_withdrawal(
The Withdrawal row is kept (marked "failed") rather than deleted: unlike a bet, a
withdrawal is an instruction the user gave, and they should be able to see that it
didn't go through."""
await begin_immediate(session) # B-88
for spent in built.spent_utxos:
row = await session.scalar(
select(UtxoEvent).where(UtxoEvent.txid == spent.txid, UtxoEvent.vout == spent.vout)
@@ -172,6 +247,7 @@ async def _release_failed_withdrawal(
withdrawal.txid = None
pending.status = "failed"
pending.failure_reason = reason[:128]
pending.failed_at = datetime.now(timezone.utc) # B-78 (DAT-36): starts the 14-day watch
await recompute_balance(session, user_id)
await write_audit_log(
session,
+73
View File
@@ -0,0 +1,73 @@
# Documentazione di PLM Lottery
Questa cartella è la **fonte di verità** del progetto: si lavora **docs-first**
(prima si scrive o si modifica la documentazione, poi il codice) e ogni
informazione ha **un solo proprietario** (SSOT). Questo file è l'indice: da
qui si raggiunge tutto il resto.
## I tre principi
1. **Docs-first.** Nessuna modifica di comportamento parte dal codice. Si
modifica il requisito (o si scrive l'ADR, se è una scelta nuova), poi si
implementa, poi si testa. Spec, codice e test entrano nello stesso commit.
2. **SSOT — un solo proprietario per ogni informazione.** Il *perché* di una
scelta sta in un ADR; il *cosa* verificabile in un requisito
(`PREFISSO-NN`) del documento di dominio; il *come* nel codice; la cronologia
dei difetti in `storico-bug.md`. Gli altri documenti **rimandano all'ID**,
non ripetono il testo. Se due documenti dicono cose diverse, vince la
specifica e si corregge l'altro.
3. **Un ADR per ogni funzionalità.** Ogni funzionalità nuova inizia con un ADR
in [adr/](adr/README.md) (modello: [adr/TEMPLATE.md](adr/TEMPLATE.md)) che
registra contesto, decisione, alternative scartate e conseguenze, e ne
elenca i requisiti.
## Dove si trova cosa
| Domanda | Dove |
|---|---|
| Perché è fatto così? Quali alternative sono state scartate? | [adr/](adr/README.md) — indice per area e tabella funzionalità → ADR |
| Cosa deve fare esattamente il software? | I documenti di dominio qui sotto (requisiti con ID stabile) |
| Quali limiti abbiamo accettato? | [limiti-noti.md](limiti-noti.md) (`LIM-nn`) |
| Che bug sono stati trovati/corretti? Quali restano aperti? | [storico-bug.md](storico-bug.md); i soli aperti in [../BUGS.md](../BUGS.md) |
| In che ordine si implementano le correzioni aperte? | [piano-correzioni.md](piano-correzioni.md) |
| Come si modifica la documentazione/il codice? | [processo-di-modifica.md](processo-di-modifica.md) |
| Come si installa, si avvia, si usa? | Guide operative qui sotto |
## Specifica (documenti di dominio)
Punto d'ingresso narrativo: [come-funziona.md](come-funziona.md).
| Documento | Prefisso | Contenuto |
|---|---|---|
| [registrazione-e-depositi.md](registrazione-e-depositi.md) | `REG`, `DEP` | Account, indirizzi, depositi, saldo |
| [scommesse-e-prelievi.md](scommesse-e-prelievi.md) | `BET`, `WDR` | Scommesse e prelievi |
| [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md) | `RND` | Apertura, chiusura, estrazione, pagamento |
| [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md) | `TX` | Ciclo di vita delle transazioni, RBF, riconciliazione |
| [connessione-electrum.md](connessione-electrum.md) | `ELC` | Accesso alla rete PLM e difese |
| [architettura.md](architettura.md) | `ARC` | Struttura del codice, processi, frontend, test |
| [modello-dati.md](modello-dati.md) | `DAT` | Tabelle, campi, stati, vincoli |
| [api.md](api.md) | `API` | Endpoint, risposte, codici di errore |
| [sicurezza.md](sicurezza.md) | `SEC` | Fiducia, chiavi, autenticazione, limiti sui tentativi |
| [audit-log.md](audit-log.md) | `AUD` | Catalogo degli eventi di audit |
| [operativita.md](operativita.md) | `OPS` | Backup, riavvii, incidenti |
## Decisioni, limiti, storia
| Documento | Prefisso | Contenuto |
|---|---|---|
| [adr/](adr/README.md) | `ADR` | Una decisione di progetto per file (53 al momento) |
| [limiti-noti.md](limiti-noti.md) | `LIM` | Limiti accettati consapevolmente |
| [storico-bug.md](storico-bug.md) | `B-nn` | Tutti i bug trovati e corretti |
| [piano-correzioni.md](piano-correzioni.md) | — | Ordine di implementazione delle correzioni aperte |
## Guide operative (senza requisiti)
[setup.md](setup.md) · [running-the-server.md](running-the-server.md) ·
[guida-utente.md](guida-utente.md) · [guida-admin.md](guida-admin.md). Si
aggiornano quando la specifica cambia qualcosa di visibile.
## Lingua
La documentazione di `docs/` è in italiano, per scelta esplicita; tutto il
resto del repository (codice, commenti, commit, `CLAUDE.md`, `BUGS.md`) è in
inglese.
@@ -0,0 +1,27 @@
# ADR-01 — La piattaforma è custodiale: tutte le chiavi sono generate e tenute dal server
- **Stato:** Accettata — implementazione da completare (B-91)
- **Area:** Custodia, chiavi e indirizzi
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**La piattaforma è custodiale: tutte le chiavi sono generate e
tenute dal server.** Una sola master xprv, cifrata con Fernet a riposo; la
chiave di cifratura sta in un file montato nel container
(`XPRV_ENCRYPTION_KEY_FILE`, permessi `0600`, vedi
[architettura.md](../architettura.md#configurazione)), mai nel database né in
git. L'utente non controlla nulla finché non preleva.
- *Motivazione:* un'esperienza da «conto» (registrazione con username e
password, scommessa con un clic) senza portafoglio lato utente, firme o
PSBT da gestire nel browser.
- *Alternative scartate:* portafoglio non custodiale con firma lato client.
- *Conseguenze:* la compromissione del server (file cifrato + variabile
d'ambiente) espone tutti i fondi; da qui l'esportazione WIF accettata
([ADR-39](ADR-39-l-esportazione-chiave-privata-wif-utente.md)), l'assenza di recupero password ([ADR-37](ADR-37-nessun-recupero-password-reset.md)) e il modello di
minaccia di [sicurezza.md](../sicurezza.md).
*Codice:* `app/wallet/hd.py:_load_account_key` · `app/wallet/keystore.py:decrypt_xprv` · `app/wallet/hd.py:generate_master_key` ·
*Test:* `tests/unit/test_hd.py`
*Stato:* da implementare (B-91) · *Oggi:* la chiave di cifratura è la
variabile d'ambiente `XPRV_ENCRYPTION_KEY`, visibile con `docker inspect`.
@@ -0,0 +1,25 @@
# ADR-02 — Un indirizzo per utente, permanente, per tutti gli usi
- **Stato:** Accettata
- **Area:** Custodia, chiavi e indirizzi
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Un indirizzo per utente, permanente, per tutti gli usi.**
Alla registrazione il server deriva un indirizzo P2WPKH BIP84
(`m/84'/746'/0'/0/<indice>`, un indice per utente, assegnato come massimo
esistente + 1). Lo stesso indirizzo è indirizzo di deposito, riceve le
vincite e riceve il resto di ogni scommessa e prelievo. Non esiste un
«indirizzo vincitore» separato.
- *Motivazione:* un solo indirizzo da osservare per utente, un solo saldo da
ricostruire (`utxo_events`), e le vincite accreditate dal normale percorso
dei depositi senza logica dedicata.
- *Conseguenze:* nessuna privacy fra depositi, vincite e resti; un prelievo
verso il proprio indirizzo è rifiutato (renderebbe indistinguibili
destinatario e resto); il pagamento di un round si considera accreditato
quando il listener vede la moneta sull'indirizzo del vincitore
(vedi [registrazione-e-depositi.md](../registrazione-e-depositi.md)).
*Codice:* `app/auth/routes.py:register` · `app/wallet/hd.py:derive_user_address` · `app/rounds/confirmation.py:_on_payout_confirmed` ·
*Test:* `tests/unit/test_hd.py`, `tests/unit/test_users.py`
@@ -0,0 +1,36 @@
# ADR-03 — Ogni round ha il proprio indirizzo del montepremi
- **Stato:** Accettata
- **Area:** Custodia, chiavi e indirizzi
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Ogni round ha il proprio indirizzo del montepremi**
(decisione del 2026-09-28), derivato dalla stessa master key sul ramo
`m/84'/746'/0'/2/<round_id>` e salvato sulla riga del round
(`rounds.pool_address`). Le scommesse di un round pagano solo il suo
indirizzo e il pagamento spende solo le monete di quell'indirizzo. Il vecchio
indirizzo unico `m/84'/746'/0'/1/0` diventa l'**indirizzo di riserva** del
montepremi, che riceve la riserva per l'RBF di ogni pagamento ([ADR-17](ADR-17-commissione-pagamento-esce-dalla-quota-vincitore.md));
i round aperti prima della modifica mantengono quell'indirizzo come
montepremi. Un prelievo verso un indirizzo del montepremi, di riserva o delle
commissioni è rifiutato. Il ramo `0` resta riservato agli utenti.
- *Motivazione:* con un indirizzo unico la cronologia cresce senza limite
(e con essa le risposte del server, B-75), il denaro di round diversi e le
monete estranee si mescolano, e un backup ripristinato ripete un round
contro ciò che il montepremi contiene oggi (B-90). Separare gli indirizzi
isola denaro, cronologia e pagamento di ogni round.
- *Alternative scartate:* un indirizzo unico con contabilità per round nel
database (non limita la cronologia e non isola le monete estranee);
consolidamento periodico dell'indirizzo unico (sposta il problema, non lo
toglie).
- *Conseguenze:* nessun segreto aggiuntivo (tutto deriva dalla master
key); una moneta estranea inviata all'indirizzo di un round chiuso resta
lì, visibile ma fuori da ogni pagamento; il margine fra partecipanti e
ingressi del pagamento ([ADR-21](ADR-21-tre-limiti-distinti-sul-numero-monete.md)) non si consuma più nel tempo ([LIM-17]).
Regole in [ciclo-di-vita-del-round.md](../ciclo-di-vita-del-round.md#4--pagamento)
e [scommesse-e-prelievi.md](../scommesse-e-prelievi.md#prelievo).
*Codice:* `app/wallet/hd.py:derive_pool_key` · `app/wallet/hd.py:derive_pool_address` · `app/wallet/hd.py:derive_round_pool_key` · `app/rounds/service.py:open_new_round_if_needed` ·
*Test:* `tests/unit/test_round_pool_address.py`, `tests/unit/test_pending_address.py`
@@ -0,0 +1,18 @@
# ADR-04 — Accesso alla rete solo via protocollo Electrum
- **Stato:** Accettata
- **Area:** Custodia, chiavi e indirizzi
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Accesso alla rete solo via protocollo Electrum**, senza nodo
completo né P2P. Una sola connessione attiva serve tutto (accrediti, invii,
conferme, altezza della catena).
- *Motivazione:* nessun nodo da installare e sincronizzare.
- *Conseguenze:* la connessione è il principale punto singolo di guasto e il
principale rischio di integrità; da qui le difese di [ADR-07](ADR-07-ogni-decisione-sposta-denaro-base-risposta.md),
[ADR-26](ADR-26-validazione-degli-header-concatenata-senza-ricalcolo.md) e [ADR-52](ADR-52-riorganizzazioni-catena-contengono-invece-ignorarle.md) e i limiti [LIM-11], [LIM-12], [LIM-14]. Dettagli in
[connessione-electrum.md](../connessione-electrum.md).
*Codice:* `app/electrum/client.py:ElectrumClient` · `app/electrum/listener.py:ElectrumListener` · `app/main.py:lifespan`
@@ -0,0 +1,17 @@
# ADR-05 — Solo indirizzi bech32 PLM (`plm1…`) come destinazione
- **Stato:** Accettata
- **Area:** Custodia, chiavi e indirizzi
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Solo indirizzi bech32 PLM (`plm1…`) come destinazione.** Un
prelievo verso un indirizzo legacy (`P…`) o di un'altra catena (`bc1…`) è
rifiutato; lo stesso controllo vale per `fee_address` e per `/qr/{address}`.
- *Motivazione:* un indirizzo di un'altra catena si interpreta comunque come
witness program valido, quindi la transazione si costruirebbe e i fondi
sarebbero irrecuperabili.
*Codice:* `app/wallet/address.py:is_valid_plm_address` · `app/withdrawals/service.py:request_withdrawal` · `app/api/routes/admin.py:RoundConfigUpdate` ·
*Test:* `tests/unit/test_withdrawals.py::test_withdrawal_rejects_non_plm_address`
@@ -0,0 +1,40 @@
# ADR-06 — I depositi richiedono `deposit_confirmations` conferme (6 per default, configurabile in `round_config`), le uscite coinbase 120; ogni altra transazione ne richiede 1
- **Stato:** Accettata — implementazione da completare (B-82)
- **Area:** Conferme e fiducia nella rete
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**I depositi richiedono `deposit_confirmations` conferme (6
per default, configurabile in `round_config`), le uscite coinbase 120; ogni
altra transazione ne richiede 1** (decisione del 2026-09-28). «Deposito» è
una moneta arrivata all'indirizzo di un utente da una transazione che la
piattaforma non ha costruito; le uscite delle transazioni della piattaforma
(resto di scommesse e prelievi, vincite) si accreditano a 1 conferma come
le transazioni che le hanno prodotte. Le soglie si cambiano solo con una
decisione esplicita.
- *Motivazione:* il deposito è **l'unico ingresso che un utente può spendere
due volte**: tutto il resto lo firma solo il server. Un utente che
scommette con un deposito a 1 conferma e poi, se perde, lo sostituisce con
una catena privata fa sparire la propria scommessa dal montepremi mentre il
partecipante resta contato, e il round diventa impagabile per tutti
(B-82). La potenza di calcolo di PLM (~22 TH/s) si può affittare, quindi
una riorganizzazione di 1–2 blocchi è alla portata di un singolo
attaccante; 6 conferme la rendono costosa quanto sei blocchi di tutta la
rete. È anche la soglia di spendibilità del portafoglio di riferimento
([LIM-27]).
- *Alternative scartate:* 1 conferma per tutto (la regola precedente,
esposta al doppio speso del deposito); 6 conferme per tutto (allunga ogni
round di cinque blocchi per coprire transazioni che l'utente non può
sostituire); scommesse ammesse solo da monete a 6 conferme ma depositi
mostrati prima (due saldi da spiegare all'utente per lo stesso rischio).
- *Conseguenze:* un deposito diventa spendibile dopo 6 blocchi (12 minuti
in media, con blocchi da 120s) invece di 1; il rischio residuo (una riorganizzazione più profonda di 6 blocchi)
è contenuto da [ADR-52](ADR-52-riorganizzazioni-catena-contengono-invece-ignorarle.md) e accettato in [LIM-24]. Regole in
[registrazione-e-depositi.md](../registrazione-e-depositi.md#deposito) (B-82).
*Codice:* `app/tx/confirmation.py:poll_once` · `app/deposits/service.py:find_new_credit_candidates` ·
*Test:* `tests/unit/test_confirmation.py::test_unconfirmed_tx_is_left_pending`, `tests/unit/test_deposits.py::test_unconfirmed_entry_is_ignored`
*Stato:* da implementare (B-82) · *Oggi:* ogni moneta, deposito o coinbase
compresi, si accredita a 1 conferma.
@@ -0,0 +1,35 @@
# ADR-07 — Ogni decisione che sposta denaro in base a una risposta di rete è corroborata da un quorum degli altri server configurati
- **Stato:** Accettata
- **Area:** Conferme e fiducia nella rete
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Ogni decisione che sposta denaro in base a una risposta di
rete è corroborata da un quorum degli altri server configurati**: il blocco
che semina l'estrazione, una moneta data per spesa all'esterno, un nuovo
deposito da accreditare, il ripristino di una moneta, la conferma di una
transazione (con prova merkle contro un header che possediamo), l'abbandono
di una transazione, le monete del round verificate prima del pagamento. Si
interrogano solo gli *altri* server, mai quello attivo (che è ciò che un
attaccante controllerebbe); servono **almeno 2 risposte** e la maggioranza
stretta di chi risponde. Il server rifiuta di partire con meno di 2 server
di riserva, salvo `ALLOW_NO_QUORUM=true` (solo sviluppo). Se rispondono meno
di 2 server, la corroborazione fallisce.
- *Motivazione:* un solo server ostile non deve poter scegliere il
vincitore (B-28), azzerare un saldo (B-29) o gonfiarlo (B-59), né far
credere confermato un pagamento mai trasmesso (B-83). I saldi si muovono in
entrambe le direzioni, quindi entrambe richiedono il quorum. Con 0 o 1
server di riserva la «maggioranza» è una sola voce, o nessuna (B-84).
- *Alternative scartate:* quorum facoltativo, che passa sempre con la lista
vuota (la regola precedente: il default di `.env.example` spegneva ogni
difesa senza avvisare).
- *Conseguenze:* una corroborazione fallita **ritarda**, non perde e non
libera fondi ([ADR-51](ADR-51-dubbio-liberano-mai-fondi.md)): il deposito è riproposto al refresh successivo,
l'estrazione richiede di nuovo lo stesso blocco. Il quorum resta fra server
scelti dall'operatore ([LIM-11]). Regole in
[connessione-electrum.md](../connessione-electrum.md#5-il-quorum) (B-83, B-84).
*Codice:* `app/electrum/listener.py:ElectrumListener._corroborate_majority` · `app/electrum/listener.py:ElectrumListener.agreed_block_hash` · `app/electrum/listener.py:ElectrumListener.corroborate_utxo_spent` · `app/electrum/listener.py:ElectrumListener.corroborate_utxo_credit` · `app/electrum/listener.py:ElectrumListener.corroborate_utxo_reinstatement` · `app/electrum/listener.py:ElectrumListener.confirmation_proven` · `app/main.py:lifespan` ·
*Test:* `tests/unit/test_electrum_listener.py`, `tests/unit/test_confirmation_proof.py`
@@ -0,0 +1,22 @@
# ADR-08 — I parametri operativi stanno nel database, i segreti nell'ambiente
- **Stato:** Accettata
- **Area:** Configurazione e ambiente
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**I parametri operativi stanno nel database, i segreti
nell'ambiente.** Ogni parametro di business (costo della scommessa, durata e
pausa del round, animazione, fee rate, timeout RBF, `fee_address`, pausa) è
una colonna dell'unica riga di `round_config`, modificabile a caldo da
`/admin`; i valori iniziali sono i default delle colonne di `RoundConfig`,
non `app/config.py`. In `.env` restano solo segreti e collegamenti
(master key, JWT, host Electrum, token admin, URL del database).
- *Motivazione:* regolare la lotteria senza ridistribuire né riavviare;
i segreti richiedono comunque un riavvio e non vanno scambiati a caldo.
- *Conseguenze:* ogni modifica è validata con limiti espliciti ([ADR-09](ADR-09-modifiche-configurazione-validate-fidate.md)) e
registrata in audit come `config_updated` con prima/dopo.
*Codice:* `app/db/models.py:RoundConfig` · `app/rounds/config.py:get_round_config` · `app/config.py:Settings` · `app/api/routes/admin.py:update_config` ·
*Test:* `tests/unit/test_admin.py::test_admin_reads_and_updates_config`, `tests/unit/test_admin.py::test_config_update_is_audit_logged`
@@ -0,0 +1,19 @@
# ADR-09 — Le modifiche di configurazione sono validate, non fidate
- **Stato:** Accettata
- **Area:** Configurazione e ambiente
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Le modifiche di configurazione sono validate, non fidate.**
Ogni campo numerico ha limiti (ad esempio `fee_rate_sat_vb` fra 1 e
`MAX_FEE_RATE_SAT_VB`, `round_duration_seconds` almeno 30) e `fee_address`
deve essere un indirizzo PLM valido. `paused` non è modificabile da
`PUT /admin/config`.
- *Motivazione:* un fee rate a 0 produce transazioni che nessun nodo inoltra,
una durata a 0 fa scadere il round appena aperto, un `fee_address` estraneo
manda la commissione in uno script irrecuperabile (B-05).
*Codice:* `app/api/routes/admin.py:RoundConfigUpdate` ·
*Test:* `tests/unit/test_admin.py::test_config_rejects_unusable_values`, `tests/unit/test_admin.py::test_pause_cannot_be_toggled_through_the_config_endpoint`
@@ -0,0 +1,27 @@
# ADR-10 — I parametri del round sono fotografati all'apertura
- **Stato:** Accettata — implementazione da completare (B-95)
- **Area:** Configurazione e ambiente
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**I parametri del round sono fotografati all'apertura.**
Durata, pausa successiva, costo della scommessa (`bet_amount_sats`),
`fee_address` e `draw_confirmations` vengono copiati sulla riga del round
quando si apre; una modifica vale dal round successivo, mai per quello in
corso. La pausa fra due round è quella annunciata dal round appena chiuso.
Il fee rate resta letto dal vivo: riguarda la singola transazione, non le
regole del round.
- *Motivazione:* abbassare la durata a metà round lo chiudeva all'istante e
spostava il conto alla rovescia di tutti i client (B-61); cambiare costo o
`fee_address` a metà round creava poste diverse con la stessa probabilità
e deviava la commissione del round in corso (B-95).
- *Conseguenze:* il prelievo minimo ([ADR-20](ADR-20-prelievo-minimo-costo-corrente-scommessa.md)) segue il costo corrente della
configurazione, non quello del round in corso. Regole in
[ciclo-di-vita-del-round.md](../ciclo-di-vita-del-round.md#0--apertura) (B-95).
*Codice:* `app/rounds/service.py:open_new_round_if_needed` · `app/rounds/service.py:round_deadline` ·
*Test:* `tests/unit/test_rounds_service.py::test_a_new_round_snapshots_the_current_config_timing`, `tests/unit/test_scheduler.py::test_tick_ignores_a_config_duration_edited_mid_round`, `tests/unit/test_rounds_service.py::test_cooldown_comes_from_the_round_that_closed`
*Stato:* da implementare (B-95) · *Oggi:* sono fotografati solo durata e
pausa; costo, `fee_address` e fee rate sono letti dal vivo ([LIM-16]).
@@ -0,0 +1,31 @@
# ADR-11 — Il server rifiuta di partire con segreti inadeguati
- **Stato:** Accettata — implementazione da completare (B-91)
- **Area:** Configurazione e ambiente
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Il server rifiuta di partire con segreti inadeguati**:
`JWT_SECRET` sotto i 32 caratteri o `XPRV_ENCRYPTION_KEY` vuota fermano
l'avvio. Un `ADMIN_TOKEN` vuoto invece non è fatale: il pannello resta
chiuso a tutti. Il controllo è nel lifespan, non in un validatore di
`Settings`.
- *Motivazione:* evitare un container che sembra sano e si rompe al primo
utente reale; tenerlo fuori da `Settings` permette a import e test di
funzionare senza `.env`.
- *Alternative scartate:* validatore Pydantic su `Settings` (avrebbe fatto
fallire la raccolta dei test su un clone pulito, B-15).
- *Conseguenze:* lo stesso principio («rifiutare di servire piuttosto che
rompersi al primo uso») si estende alla master key decifrata e confrontata
con gli indirizzi già salvati (B-89) e al quorum minimo di server (B-84);
l'ordine dei controlli all'avvio è in
[architettura.md](../architettura.md#nel-lifespan).
*Codice:* `app/config.py:validate_runtime_secrets` · `app/main.py:lifespan` · `app/api/routes/admin.py:require_admin` ·
*Test:* `tests/unit/test_config.py`
*Stato:* da implementare (B-91) per la parte sulla chiave · *Oggi:* la
chiave Fernet arriva da `XPRV_ENCRYPTION_KEY` (variabile d'ambiente); dopo
B-91 arriva da un file (`XPRV_ENCRYPTION_KEY_FILE`,
[sicurezza.md](../sicurezza.md#sec-53) SEC-53) e il rifiuto riguarda un file
mancante o vuoto.
@@ -0,0 +1,23 @@
# ADR-12 — Il server gira solo in Docker, in sviluppo come in produzione
- **Stato:** Accettata — implementazione da completare (B-81)
- **Area:** Configurazione e ambiente
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Il server gira solo in Docker, in sviluppo come in
produzione**, dietro Caddy (TLS automatico, certificato autofirmato su
`localhost`). Il container rifiuta di partire senza il file della master
key, applica le migrazioni Alembic all'avvio e si riavvia da solo
(`restart: unless-stopped`). Il venv serve solo per test, migrazioni e
script della chiave.
- *Motivazione:* un solo modo di eseguire il server, identico ovunque.
- *Conseguenze:* dopo un crash ogni stato del round riprende da solo,
`drawing` compreso ([ADR-25](ADR-25-blocco-estrazione-fissato-altezza-successivo-chiusura.md), B-81). Procedure in
[operativita.md](../operativita.md).
*Codice:* `Dockerfile` · `docker-compose.yml` · `Caddyfile` ·
*Test:* `tests/unit/test_docs_no_bare_uvicorn.py`
*Stato:* da implementare (B-81) · *Oggi:* dopo un crash `closing` e
`paying_out` riprendono da soli, `drawing` no ([LIM-01]).
+22
View File
@@ -0,0 +1,22 @@
# ADR-13 — Un solo processo, un solo file SQLite
- **Stato:** Accettata
- **Area:** Configurazione e ambiente
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Un solo processo, un solo file SQLite** (modalità WAL con
`busy_timeout`, `synchronous=FULL`, `BEGIN IMMEDIATE` per ogni transazione
che sposta denaro, vedi [architettura.md](../architettura.md#database), B-88).
Canale SSE, blocchi per-utente, limitatori di tentativi e cache sono in
memoria.
- *Motivazione:* semplicità a scala di ~100 utenti concorrenti.
- *Alternative scartate:* Redis o un database con lock condivisi, da non
introdurre in via speculativa.
- *Conseguenze:* nessuna distribuzione su più worker ([LIM-18]). L'unico
invariante che non dipende dal processo singolo è «al più un round
attivo», garantito da un indice ([ADR-22](ADR-22-piu-round-attivo-come-invariante-database.md)).
*Codice:* `app/db/base.py:_register_sqlite_pragmas` · `app/db/base.py:begin_immediate` · `app/tx/locks.py:UserLocks` · `app/rounds/events.py:RoundEventBroadcaster` ·
*Test:* `tests/unit/test_db_base.py` · `tests/unit/test_sqlite_transactions.py`
@@ -0,0 +1,17 @@
# ADR-14 — Ripartizione fissa 70% al vincitore / 30% alla piattaforma
- **Stato:** Accettata
- **Area:** Economia del gioco
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Ripartizione fissa 70% al vincitore / 30% alla piattaforma**,
con l'arrotondamento a favore delle commissioni. È nel codice, non nella
configurazione: cambiarla è una modifica del software.
- *Motivazione:* una regola economica di fondo non deve poter cambiare con un
clic dal pannello. Un'unica funzione alimenta sia il montepremi mostrato sia
il pagamento, così i due non possono divergere.
*Codice:* `app/rounds/service.py:winner_share` · `app/rounds/scheduler.py:RoundScheduler._trigger_payout` · `app/api/routes/rounds.py:current_round` ·
*Test:* `tests/unit/test_payout_builder.py::test_payout_deducts_fee_only_from_winner_share`
@@ -0,0 +1,18 @@
# ADR-15 — Biglietto a prezzo fisso, una scommessa per utente per round, probabilità uguale per tutti
- **Stato:** Accettata
- **Area:** Economia del gioco
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Biglietto a prezzo fisso, una scommessa per utente per round,
probabilità uguale per tutti** indipendentemente dall'importo effettivo.
Nessun deposito minimo.
- *Conseguenze:* l'estrazione sceglie fra partecipanti, non pesa gli
importi. Il costo è fotografato all'apertura del round ([ADR-10](ADR-10-parametri-round-fotografati-all-apertura.md)), così
tutti i partecipanti di un round pagano la stessa posta (B-95; oggi è letto
dal vivo, [LIM-16]).
*Codice:* `app/bets/service.py:place_bet` · `app/rounds/draw.py:draw_winner` ·
*Test:* `tests/unit/test_bets.py::test_place_bet_rejects_second_bet_same_round`
@@ -0,0 +1,18 @@
# ADR-16 — La commissione di rete si toglie dall'importo che si muove
- **Stato:** Accettata
- **Area:** Economia del gioco
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**La commissione di rete si toglie dall'importo che si
muove**, non si aggiunge sopra: per una scommessa arriva al montepremi il
costo meno la commissione, per un prelievo arriva a destinazione l'importo
meno la commissione.
- *Conseguenze:* il montepremi si calcola sommando gli importi effettivi
delle scommesse, non moltiplicando il numero di giocatori per il costo
(B-11); il prelievo registra sia l'importo richiesto sia quello inviato.
*Codice:* `app/wallet/psbt_builder.py:build_signed_transaction` ·
*Test:* `tests/unit/test_psbt_builder.py::test_build_signed_transaction_deducts_fee_from_amount_not_change`
@@ -0,0 +1,35 @@
# ADR-17 — La commissione del pagamento esce dalla quota del vincitore; la riserva per l'RBF esce dalla quota della piattaforma
- **Stato:** Accettata — implementazione da completare (B-79)
- **Area:** Economia del gioco
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**La commissione del pagamento esce dalla quota del
vincitore; la riserva per l'RBF esce dalla quota della piattaforma.** Ogni
pagamento ha un'uscita di **riserva** di
`max(DUST_LIMIT_SATS, dimensione stimata × 10 sat/vB)` verso l'indirizzo di
riserva del montepremi ([ADR-03](ADR-03-ogni-round-ha-proprio-indirizzo-montepremi.md)); un'accelerazione riduce quell'uscita. La
commissione verso `fee_address` è quindi il 30% meno la riserva.
- *Motivazione:* il pagamento spende di norma tutte e sole le monete del
round, quindi non ha resto e non si potrebbe mai accelerare: un pagamento
fermo in mempool terrebbe il round in `paying_out` per sempre (B-79). La
riserva la paga la piattaforma perché è la piattaforma a scegliere il fee
rate.
- *Alternative scartate:* riserva presa dalla quota del vincitore (il
montepremi annunciato scenderebbe ancora); CPFP da un'uscita del vincitore
(richiede una seconda transazione e una moneta del vincitore); pagamento
senza riserva e abbandono dopo un timeout (vietato da [ADR-51](ADR-51-dubbio-liberano-mai-fondi.md)).
- *Conseguenze:* il montepremi annunciato (il 70% delle scommesse
confermate) supera di poco quanto il vincitore riceve davvero; la
differenza, la commissione del pagamento, non è nota finché il pagamento non
è costruito. [ADR-29](ADR-29-senza-fee-address-apre-nessun-round.md) rifiuta di aprire round con una configurazione in cui
un round da un partecipante non coprirebbe commissione del vincitore,
riserva e una commissione sopra la soglia di polvere. Regole in
[ciclo-di-vita-del-round.md](../ciclo-di-vita-del-round.md#4--pagamento) (B-79).
*Codice:* `app/wallet/psbt_builder.py:build_payout_transaction` ·
*Test:* `tests/unit/test_payout_builder.py::test_payout_deducts_fee_only_from_winner_share`
*Stato:* da implementare (B-79) · *Oggi:* nessuna riserva: il 30% va intero a
`fee_address` e, nel caso normale, il pagamento non ha resto.
@@ -0,0 +1,22 @@
# ADR-18 — L'accelerazione RBF la paga chi riceve il resto
- **Stato:** Accettata
- **Area:** Economia del gioco
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**L'accelerazione RBF la paga chi riceve il resto**: l'utente
per scommesse e prelievi, la piattaforma (tramite la riserva di [ADR-17](ADR-17-commissione-pagamento-esce-dalla-quota-vincitore.md)) per
i pagamenti. Le uscite verso la controparte non si toccano mai. La regola,
con i casi in cui il resto non basta, è di
[TX-11](../transazioni-e-riconciliazione.md#rbf-accelerare-una-transazione-lenta).
- *Motivazione:* chi riceve il resto è chi ha scelto di spendere; ridurre
l'uscita del destinatario cambierebbe l'importo che la controparte si
aspetta (B-17).
- *Conseguenze:* ogni transazione deve avere un'uscita che il mittente può
ridurre: da qui [ADR-19](ADR-19-ogni-transazione-utente-conserva-uscita-resto.md) per le transazioni utente e la riserva di
[ADR-17](ADR-17-commissione-pagamento-esce-dalla-quota-vincitore.md) per i pagamenti ([LIM-02]).
*Codice:* `app/tx/broadcast.py:bump_fee` · `app/tx/broadcast.py:_find_change_output` ·
*Test:* `tests/unit/test_broadcast.py`
@@ -0,0 +1,37 @@
# ADR-19 — Ogni transazione utente conserva un'uscita di resto verso l'utente, e un'accelerazione che porterebbe quel resto sotto `DUST_LIMIT_SATS` (294 sat) lo elimina
- **Stato:** Accettata — implementazione da completare (B-87)
- **Area:** Economia del gioco
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Ogni transazione utente conserva un'uscita di resto verso
l'utente, e un'accelerazione che porterebbe quel resto sotto
`DUST_LIMIT_SATS` (294 sat) lo elimina.** Le regole sono di
[BET-14](../scommesse-e-prelievi.md#cosa-succede) e
[WDR-09](../scommesse-e-prelievi.md#prelievo) (resto minimo alla costruzione)
e di [TX-11](../transazioni-e-riconciliazione.md#rbf-accelerare-una-transazione-lenta)
(resto eliminato all'accelerazione, B-87).
- *Motivazione:* un prelievo totale produceva una transazione a un'uscita
che nessun RBF poteva salvare (B-62); aggiungere monete non avrebbe
aiutato, perché la transazione le spendeva già tutte. Il resto minimo di
294 sat però **non basta a restare accelerabile**: il primo aumento
minimo (1 sat/vB sull'intera transazione, 141 sat per un ingresso e due
uscite) lo porta a 153 sat, sotto la soglia di polvere, e ogni sostituzione
successiva viene rifiutata dalle regole di inoltro (B-87). Garantisce
l'esistenza dell'uscita, non la capacità di assorbire aumenti.
- *Alternative scartate:* un resto minimo più grande (sottrae all'utente un
importo che deve comunque poter prelevare, e sposta solo la soglia);
aggiungere ingressi alla sostituzione (nel caso che conta, il prelievo
totale, non ce ne sono altri).
- *Conseguenze:* quando il resto scende sotto soglia, il suo valore va in
commissione e la sostituzione è l'ultima possibile per quella transazione;
l'utente perde al più 294 sat. **Il pagamento del round** non ha un resto
utente: la sua uscita riducibile è la riserva di [ADR-17](ADR-17-commissione-pagamento-esce-dalla-quota-vincitore.md).
*Codice:* `app/wallet/psbt_builder.py:build_signed_transaction` · `app/withdrawals/service.py:request_withdrawal` · `app/tx/broadcast.py:bump_fee` ·
*Test:* `tests/unit/test_psbt_builder.py::test_build_signed_transaction_refuses_an_amount_that_would_leave_no_change`, `tests/unit/test_withdrawals.py::test_full_balance_withdrawal_keeps_a_bumpable_change_output`, `tests/unit/test_withdrawals.py::test_a_bet_from_a_balance_equal_to_the_bet_is_refused`
*Stato:* da implementare (B-87) · *Oggi:* `bump_fee` richiede solo che il
resto superi l'aumento, e può lasciare un resto sotto soglia che nessun nodo
inoltra.
@@ -0,0 +1,16 @@
# ADR-20 — Il prelievo minimo è il costo corrente della scommessa
- **Stato:** Accettata
- **Area:** Economia del gioco
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Il prelievo minimo è il costo corrente della scommessa**, senza
un campo di configurazione separato.
- *Motivazione:* un parametro in meno da tenere coerente.
- *Conseguenze:* alzare il costo della scommessa alza anche il prelievo
minimo, con effetto immediato.
*Codice:* `app/withdrawals/service.py:request_withdrawal` ·
*Test:* `tests/unit/test_withdrawals.py::test_withdrawal_rejects_amount_below_minimum`
@@ -0,0 +1,33 @@
# ADR-21 — Tre limiti distinti sul numero di monete e di giocatori:
- **Stato:** Accettata
- **Area:** Economia del gioco
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Tre limiti distinti sul numero di monete e di giocatori:**
| Costante | Valore | Protegge da |
|---|---|---|
| `MAX_TX_INPUTS` | 50 | una transazione utente (scommessa, prelievo) che erode l'importo in commissioni per un indirizzo troppo frammentato; oltre, `too_many_inputs` |
| `MAX_PAYOUT_TX_INPUTS` | 500 | un pagamento troppo grande per le regole di inoltro (~1470 ingressi a 100 kvB); un terzo del margine |
| `MAX_PARTICIPANTS_PER_ROUND` | 400 | un round impagabile: il 401° giocatore è rifiutato con `round_full` **prima** che si muova denaro |
- *Motivazione:* il pagamento spende una moneta del montepremi per scommessa;
usare per esso il limite utente rendeva impagabile ogni round oltre ~50
giocatori e fermava la lotteria (B-52). Con un indirizzo per round
([ADR-03](ADR-03-ogni-round-ha-proprio-indirizzo-montepremi.md), B-80) il pagamento spende solo le monete del round, quindi i 100
di differenza fra 400 e 500 restano un margine fisso invece di consumarsi
con le monete avanzate dai round precedenti (come accade oggi con
l'indirizzo unico).
- *Conseguenze:* «ogni round si può pagare» è un invariante verificato
all'ingresso, non una scoperta al momento del pagamento. Il conteggio dei
partecipanti include quelli non ancora confermati (direzione prudente). Un
tetto opzionale al montepremi del round (`max_round_pool_sats`, 0 =
disattivato) rifiuta con `round_full` anche le scommesse oltre quel valore
(B-95); se e come legarlo al costo di un attacco al 51% è una decisione
non ancora presa ([LIM-24]).
*Codice:* `app/wallet/psbt_builder.py:select_utxos` · `app/bets/service.py:place_bet` · `app/wallet/psbt_builder.py:build_payout_transaction` ·
*Test:* `tests/unit/test_psbt_builder.py::test_select_utxos_never_exceeds_the_input_cap`, `tests/unit/test_bets.py::test_place_bet_rejects_the_bet_past_the_participant_cap`, `tests/unit/test_payout_builder.py::test_payout_at_the_participant_cap_stays_well_inside_relay_limits`
@@ -0,0 +1,19 @@
# ADR-22 — Al più un round attivo, come invariante del database
- **Stato:** Accettata
- **Area:** Round ed estrazione
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Al più un round attivo, come invariante del database.** Un
indice unico su un'espressione costante, limitato agli stati attivi, fa
fallire in modo pulito il secondo inserimento concorrente; chi perde adotta
il round del vincitore (al massimo 3 tentativi). I round non si
sovrappongono mai: il successivo si apre solo quando il precedente è
`closed`.
- *Alternative scartate:* rendere lo scheduler l'unico autore dei round (la
prima scommessa dopo una pausa non avrebbe potuto aprirne uno, B-09).
*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::test_the_database_refuses_a_second_active_round`, `tests/unit/test_rounds_service.py::test_losing_the_open_race_reuses_the_winning_round`
@@ -0,0 +1,22 @@
# ADR-23 — Il limite per scommettere è la scadenza del round stesso, non il suo stato nel database
- **Stato:** Accettata
- **Area:** Round ed estrazione
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Il limite per scommettere è la scadenza del round stesso, non
il suo stato nel database**, e la chiusura «a semaforo giallo» aspetta che
ogni scommessa già inviata sia confermata prima di estrarre. L'iscrizione è
salvata con un compare-and-set sulla riga del round.
- *Motivazione:* lo scheduler controlla ogni 5s, quindi lo stato può restare
`open` oltre la scadenza; senza il compare-and-set una scommessa poteva
finire nel montepremi ed essere esclusa dall'estrazione (B-53).
- *Conseguenze:* l'attesa in `closing` finisce solo quando ogni scommessa è
confermata o dimostrata morta ([ADR-51](ADR-51-dubbio-liberano-mai-fondi.md)); non ha un limite di tempo
([LIM-03]). Dettagli in
[ciclo-di-vita-del-round.md](../ciclo-di-vita-del-round.md#2--chiusura).
*Codice:* `app/rounds/service.py:round_accepts_bets` · `app/bets/service.py:place_bet` · `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
*Test:* `tests/unit/test_bets.py::test_place_bet_refuses_when_the_round_closed_between_the_check_and_the_commit`, `tests/unit/test_scheduler.py::test_close_and_draw_waits_when_a_bet_appears_after_the_tick_check`
@@ -0,0 +1,58 @@
# ADR-24 — L'estrazione è un commit-reveal fra il server e un blocco futuro
- **Stato:** Accettata
- **Area:** Round ed estrazione
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**L'estrazione è un commit-reveal fra il server e un blocco
futuro** (decisione del 2026-09-28). All'apertura del round il server genera
un segreto casuale di 32 byte (`server_seed`), lo salva e pubblica solo la
sua impronta `server_seed_hash = sha256(server_seed)`. All'ingresso in
`drawing` si fissano l'elenco dei partecipanti confermati, ordinato per txid
della scommessa crescente, la sua impronta `participants_hash` (sha256 delle
righe `txid:vout:indirizzo`) e l'altezza del blocco di estrazione
(`draw_height`, [ADR-25](ADR-25-blocco-estrazione-fissato-altezza-successivo-chiusura.md)). Il seme è
`sha256(server_seed || block_hash || participants_hash)` letto come intero,
l'indice del vincitore è seme modulo numero di partecipanti. Dopo il
salvataggio del vincitore il server rivela `server_seed` e pubblica la prova
completa (`GET /rounds/{id}/proof`), da cui chiunque ricalcola l'esito.
L'algoritmo resta un **componente sostituibile**: il resto del sistema non
va architettato attorno alla sua forma, ma ogni sostituto deve mantenere le
stesse quattro proprietà — impegno pubblicato prima delle scommesse, elenco
dei partecipanti fissato prima del blocco, esito ricalcolabile dai dati
pubblicati, esito non calcolabile da chi produce o trasmette i blocchi.
- *Motivazione:* il vincitore non deve essere calcolabile da chi controlla
la produzione dei blocchi: la potenza di calcolo di PLM (~22 TH/s) si può
affittare. Un minatore che non conosce `server_seed` non sa chi vincerebbe
con il suo blocco e quindi non ha motivo di scartarlo; l'operatore non
può cambiare `server_seed` dopo averne pubblicato l'impronta e non conosce
il blocco quando si impegna. L'ordine per txid e l'impronta dell'elenco
rendono l'esito riproducibile e impediscono di aggiungere o togliere
partecipanti dopo aver visto il blocco (B-73).
- *Alternative scartate:*
- *hash del solo blocco* (la forma precedente): un minatore con biglietti
in gioco trattiene i blocchi finché uno lo fa vincere, e il server
Electrum attivo sceglie quale blocco reale usare semplicemente non
annunciandone uno;
- *hash di più blocchi consecutivi*: chi produce l'ultimo blocco della
serie può ancora scartarlo e riprovare, quindi resta manipolabile;
- *segreti forniti dai giocatori* (commit-reveal fra partecipanti): chi non
rivela blocca o condiziona l'estrazione, e servirebbe un'azione in più a
ogni giocatore;
- *sorgente di casualità esterna* (beacon): una dipendenza di rete in più,
di cui fidarsi quanto del server.
- *Conseguenze:* l'operatore, che conosce `server_seed`, può calcolare
l'esito appena il blocco è noto: una collusione fra operatore e minatore
resta possibile ed è accettata ([LIM-25]), perché l'operatore è già
fidato come custode ([LIM-26]). `server_seed` non è esposto da nessun
endpoint prima della rivelazione, e nel database è cifrato con la chiave
della master xprv finché non viene rivelato
([sicurezza.md](../sicurezza.md#sec-56) SEC-56): una copia del database da
sola non basta a conoscerlo. Regole in
[ciclo-di-vita-del-round.md](../ciclo-di-vita-del-round.md#3--estrazione),
endpoint in [api.md](../api.md) (B-73).
*Codice:* `app/rounds/draw.py:draw_winner` · `app/rounds/scheduler.py:RoundScheduler._close_and_draw` · `app/rounds/scheduler.py:RoundScheduler._complete_draw` · `app/rounds/service.py:open_new_round_if_needed` · `app/api/routes/rounds.py:round_proof` ·
*Test:* `tests/unit/test_draw.py`, `tests/unit/test_draw_proof.py`
@@ -0,0 +1,37 @@
# ADR-25 — Il blocco di estrazione è fissato per altezza, è successivo alla chiusura, e si usa solo quando è confermato e corroborato
- **Stato:** Accettata — implementazione da completare (B-81)
- **Area:** Round ed estrazione
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Il blocco di estrazione è fissato per altezza, è successivo
alla chiusura, e si usa solo quando è confermato e corroborato.**
All'ingresso in `drawing` si salva `draw_height = tip_at_close + 1`, che non
cambia più. Si attende che quel blocco abbia `draw_confirmations` conferme
(3 per default, fotografato all'apertura, [ADR-10](ADR-10-parametri-round-fotografati-all-apertura.md)), poi si chiede a tutti i
server l'header *a quell'altezza*: serve l'accordo del quorum ([ADR-07](ADR-07-ogni-decisione-sposta-denaro-base-risposta.md)); in
caso di disaccordo si attende e si richiede la stessa altezza, mai un blocco
diverso. L'attesa non ha timeout (l'entropia dipende davvero da un blocco
futuro) ma è osservabile (`draw_stalled`, `draw_waiting_since`) e
riprendibile: `draw_height`, `participants_hash` e la posizione di ogni
partecipante sono salvati, e lo scheduler riprende un round in `drawing`
dopo un errore o un riavvio con lo stesso esito. Un'altezza `0` alla
chiusura significa «sconosciuta»: la prima altezza appresa fa da base.
- *Motivazione:* un hash già pubblico mentre le scommesse erano aperte
renderebbe il vincitore prevedibile (B-63); un header fabbricato
sceglierebbe il vincitore (B-28); un'altezza non fissata lascia al server
attivo la scelta di quale blocco reale usare, e passare a «un blocco
ulteriore» dopo una corroborazione fallita gli dà un secondo tentativo
(B-73). Le conferme sul blocco di estrazione evitano che una
riorganizzazione cambi il seme dopo l'estrazione. Uno stato tenuto solo in
memoria bloccava il round in `drawing` a ogni eccezione (B-81).
- *Alternative scartate:* timeout sull'attesa con ripiego su un altro blocco
(riaprirebbe la scelta del blocco).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_draw_block` · `app/rounds/scheduler.py:RoundScheduler._close_and_draw` · `app/rounds/scheduler.py:RoundScheduler._tick` ·
*Test:* `tests/unit/test_scheduler.py::test_a_block_relayer_cannot_choose_the_block_that_seeds_the_draw`, `tests/unit/test_scheduler.py::test_a_disagreement_asks_the_same_height_again_and_is_audited_once_per_hash`
*Stato:* da implementare (B-81) · *Oggi:* `draw_height`, `participants_hash` e le
posizioni sono salvati, ma `_tick` salta i round in `drawing`: dopo un errore
o un riavvio il round non riparte.
@@ -0,0 +1,35 @@
# ADR-26 — Validazione degli header concatenata, senza ricalcolo della difficoltà
- **Stato:** Accettata
- **Area:** Round ed estrazione
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Validazione degli header concatenata, senza ricalcolo della
difficoltà.** Un header deve dichiarare un bersaglio non più facile del
limite di rete (`powLimit`, `0x00000000ffff…`), rispettare quel bersaglio e
concatenarsi alla catena che teniamo: su un avanzamento di più blocchi si
scaricano gli header intermedi e si verifica tutta la catena. Il listener
tiene gli ultimi 10 header; un header che non si concatena alla punta ma a
uno di essi è una riorganizzazione da seguire ([ADR-52](ADR-52-riorganizzazioni-catena-contengono-invece-ignorarle.md)), non un server
ostile. Un header senza `hex` è ignorato senza chiudere la sessione. Regole
in [connessione-electrum.md](../connessione-electrum.md#4-header-validati-non-creduti)
(B-74, B-85).
- *Motivazione:* il controllo «rispetta il bersaglio che dichiara», da solo,
**non è una difesa**: il bersaglio lo sceglie chi produce l'header, e con
`bits=0x207fffff` un header passa senza lavoro. Un salto di più blocchi non
collegato alla punta permetteva di fissare un'altezza enorme, che non
regredisce mai, e congelare ogni estrazione (B-74). Trattare ogni
riorganizzazione di un blocco come un server ostile chiudeva la sessione
su tutti i server fino al blocco successivo.
- *Alternative scartate:* validazione completa della catena con le regole di
ricalcolo della difficoltà di PLM (fuori scopo: servirebbe la storia delle
difficoltà, e il commit-reveal di [ADR-24](ADR-24-l-estrazione-commit-reveal-fra-server.md) toglie a un header fabbricato il
potere di scegliere il vincitore).
- *Conseguenze:* un header a difficoltà minima costa ancora poco lavoro
([LIM-14]); a fermare una catena fabbricata sono la concatenazione, il
quorum ([ADR-07](ADR-07-ogni-decisione-sposta-denaro-base-risposta.md)) e il fatto che il seme dipende anche da `server_seed`.
*Codice:* `app/electrum/listener.py:ElectrumListener._apply_header` · `app/rounds/draw.py:header_meets_its_own_target` ·
*Test:* `tests/unit/test_electrum_listener.py::test_a_multi_block_jump_is_validated_by_fetching_the_headers_in_between`, `tests/unit/test_electrum_listener.py::test_a_fork_is_walked_back_and_followed_instead_of_ending_the_session`, `tests/unit/test_electrum_listener.py::test_a_competing_header_at_the_tip_height_is_a_reorg_to_follow`, `tests/unit/test_draw.py::test_a_header_below_the_pow_limit_is_rejected_even_if_it_meets_its_own_target`
@@ -0,0 +1,19 @@
# ADR-27 — Pausa di cortesia fra un round e l'altro
- **Stato:** Accettata
- **Area:** Round ed estrazione
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Pausa di cortesia fra un round e l'altro**
(`round_cooldown_seconds`, 30s), contata dalla **conferma del pagamento**, non
dall'inizio della chiusura, così i giocatori vedono l'esito. Le regole sono di
[RND-04](../ciclo-di-vita-del-round.md#0--apertura) (quando si apre il round
successivo) e [RND-28](../ciclo-di-vita-del-round.md#4--pagamento) (da quando
si conta).
- *Motivazione:* non è nel diagramma originale; senza pausa il round
successivo si apriva prima che i client avessero mostrato il risultato.
*Codice:* `app/rounds/confirmation.py:_on_payout_confirmed` · `app/rounds/service.py:open_new_round_if_needed` ·
*Test:* `tests/unit/test_rounds_service.py::test_withholds_new_round_during_cooldown`
@@ -0,0 +1,24 @@
# ADR-28 — La pausa per manutenzione ferma solo il round successivo
- **Stato:** Accettata
- **Area:** Round ed estrazione
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**La pausa per manutenzione ferma solo il round successivo.**
È un'azione esplicita dell'operatore con endpoint propri e registrati in
audit (`lottery_paused`, `lottery_resumed`), non un campo di configurazione;
il round in corso chiude, estrae e paga come qualunque altro round.
- *Motivazione:* sospendere a metà un round con denaro nel montepremi
creerebbe proprio lo stato bloccato che la pausa vuole evitare.
- *Conseguenze:* la stessa pausa è anche il modo in cui il sistema chiede
l'intervento dell'operatore, con un motivo (`paused_reason`): una
riorganizzazione profonda ([ADR-52](ADR-52-riorganizzazioni-catena-contengono-invece-ignorarle.md), B-85), un pagamento il cui vincitore
non ha più la scommessa in catena (B-82), una transazione abbandonata che
conferma in ritardo ([ADR-51](ADR-51-dubbio-liberano-mai-fondi.md), B-78), un avvio con `START_PAUSED=true` dopo
un ripristino (B-90). Solo l'operatore la toglie. Anche in questi casi il
round in corso prosegue, salvo il pagamento trattenuto di B-82.
*Codice:* `app/api/routes/admin.py:pause_lottery` · `app/api/routes/admin.py:resume_lottery` · `app/rounds/service.py:open_new_round_if_needed` ·
*Test:* `tests/unit/test_rounds_service.py::test_withholds_new_round_while_paused`, `tests/unit/test_rounds_service.py::test_pause_does_not_interrupt_a_round_in_progress`, `tests/unit/test_admin.py::test_admin_can_pause_and_resume_the_lottery`
@@ -0,0 +1,24 @@
# ADR-29 — Senza `fee_address` non si apre nessun round
- **Stato:** Accettata — implementazione da completare (B-79)
- **Area:** Round ed estrazione
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Senza `fee_address` non si apre nessun round.** Il campo non ha
valore predefinito: l'operatore deve impostare il proprio. Finché manca, nessun
round si apre (`lottery_configured = false` su `GET /rounds/current`, avviso
in `/admin`); un round già in corso invece chiude, estrae e paga anche se
l'indirizzo viene cancellato. Qualunque altra condizione che renderebbe un
round impagabile va aggiunta nello stesso punto.
- *Motivazione:* un round aperto senza `fee_address` raccoglieva scommesse e
solo al pagamento scopriva di non poter essere pagato (B-66).
- *Conseguenze:* nello stesso punto si aggiunge il controllo che un round
con un solo partecipante copra commissione del vincitore, riserva per
l'RBF e una commissione sopra la soglia di polvere ([ADR-17](ADR-17-commissione-pagamento-esce-dalla-quota-vincitore.md), B-79).
*Codice:* `app/rounds/service.py:rounds_can_open` · `app/rounds/config.py:get_round_config` ·
*Test:* `tests/unit/test_rounds_service.py::test_withholds_new_round_while_no_fee_address_is_configured`, `tests/unit/test_rounds_service.py::test_a_round_in_progress_survives_the_fee_address_being_cleared`, `tests/unit/test_rounds_route.py::test_lottery_configured_flags_a_missing_fee_address`
*Stato:* da implementare (B-79) · *Oggi:* `rounds_can_open` controlla solo
`fee_address`.
@@ -0,0 +1,20 @@
# ADR-30 — Il montepremi annunciato è quello che sarà pagato
- **Stato:** Accettata
- **Area:** Round ed estrazione
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Il montepremi annunciato è quello che sarà pagato**: il 70%
delle sole scommesse confermate, affiancato dai valori «in attesa» che
includono le scommesse in volo (valori inclusivi, non differenze).
- *Motivazione:* mai annunciare più di quanto l'estrazione e il pagamento
considereranno (B-65), senza nascondere al giocatore la propria scommessa
appena fatta.
- *Conseguenze:* se prima del pagamento una scommessa confermata risulta
sparita per una riorganizzazione, il partecipante esce dal calcolo
(`reorged_out`) e il pagato scende sotto l'annunciato ([ADR-52](ADR-52-riorganizzazioni-catena-contengono-invece-ignorarle.md), B-82).
*Codice:* `app/api/routes/rounds.py:current_round` ·
*Test:* `tests/unit/test_rounds_route.py::test_advertised_jackpot_covers_only_the_bets_that_will_be_paid`
@@ -0,0 +1,23 @@
# ADR-31 — Tutto ciò che spende denaro si scrive prima di inviarlo
- **Stato:** Accettata
- **Area:** Denaro in movimento
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Tutto ciò che spende denaro si scrive prima di inviarlo** (stato
`building`, monete già segnate come spese) e si risolve contro la catena
dopo; nessuna sessione del database resta aperta durante una chiamata di
rete. Vale anche per le sostituzioni RBF: la nuova versione si salva come
candidata prima dell'invio (B-77). Solo un **rifiuto esplicito** della rete
annulla tutto e risponde **502**; un invio dall'esito incerto (timeout,
connessione caduta dopo la scrittura) lascia la riga `building` al
riconciliatore e risponde **202** ([ADR-51](ADR-51-dubbio-liberano-mai-fondi.md)).
- *Motivazione:* un crash fra invio e salvataggio lasciava monete spese in
catena senza traccia (B-08, B-25). Dettagli in
[transazioni-e-riconciliazione.md](../transazioni-e-riconciliazione.md).
*Codice:* `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` · `app/tx/reconcile.py:reconcile_once` ·
*Test:* `tests/unit/test_bets.py::test_bet_is_persisted_before_it_is_broadcast`, `tests/unit/test_broadcast_outcome.py`, `tests/unit/test_scheduler.py::test_trigger_payout_persists_before_broadcasting`, `tests/unit/test_reconcile.py`
@@ -0,0 +1,15 @@
# ADR-32 — Il pagamento si ritenta da solo, mai due volte
- **Stato:** Accettata
- **Area:** Denaro in movimento
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Il pagamento si ritenta da solo, mai due volte**: un tentativo
ogni 60s, usando l'ultimo `payout_failed` in audit come orologio; prima di
costruire si rifiuta se esiste già un pagamento `building`/`pending` per il
round, e si escludono le monete impegnate da pagamenti non risolti.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._retry_payout_if_due` · `app/rounds/scheduler.py:_reserved_payout_outpoints` ·
*Test:* `tests/unit/test_scheduler.py::test_trigger_payout_skips_when_already_in_flight`, `tests/unit/test_scheduler.py::test_tick_throttles_retry_after_a_recent_payout_failure`, `tests/unit/test_scheduler.py::test_reserved_payout_outpoints_excludes_utxos_claimed_by_a_stale_payout`
@@ -0,0 +1,17 @@
# ADR-33 — Scommessa e prelievo si escludono solo tramite il blocco per-utente
- **Stato:** Accettata
- **Area:** Denaro in movimento
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Scommessa e prelievo si escludono solo tramite il blocco
per-utente** sulla *costruzione*: un prelievo è accettato anche mentre una
scommessa attende conferma, purché le monete confermate e libere lo coprano.
- *Motivazione:* il rischio è che scelgano la stessa moneta, già escluso dal
blocco e dal fatto che la selezione salta le monete segnate come spese;
congelare il resto del saldo non aggiungerebbe sicurezza (B-70).
*Codice:* `app/tx/locks.py:UserLocks` · `app/api/routes/bets.py:create_bet` · `app/api/routes/withdrawals.py:create_withdrawal` ·
*Test:* `tests/unit/test_withdrawals.py::test_withdrawal_is_allowed_while_a_bet_is_still_unconfirmed`
@@ -0,0 +1,17 @@
# ADR-34 — Saldo spendibile e saldo mostrato sono due numeri distinti
- **Stato:** Accettata
- **Area:** Denaro in movimento
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Saldo spendibile e saldo mostrato sono due numeri distinti.**
Si spende solo il confermato (`balance_sats`); si mostra quello che include i
resti ancora in volo (`pending_balance_sats`, in ambra finché non conferma).
Un prelievo coperto solo dal secondo riceve `balance_pending_confirmation`.
- *Motivazione:* la selezione a monete intere sottrae l'intera moneta al
saldo confermato già all'invio, molto più di quanto si stia spostando.
*Codice:* `app/wallet/balance.py:compute_pending_balance` · `app/wallet/balance.py:recompute_balance` · `app/api/routes/users.py:me` ·
*Test:* `tests/unit/test_balance.py`, `tests/unit/test_withdrawals.py::test_withdrawal_distinguishes_pending_from_truly_insufficient_balance`
@@ -0,0 +1,14 @@
# ADR-35 — Aritmetica solo in satoshi interi
- **Stato:** Accettata
- **Area:** Denaro in movimento
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Aritmetica solo in satoshi interi**, anche per i valori letti
dalla rete: l'importo di una moneta spesa si ricava dalla transazione grezza,
non dal valore decimale restituito dal server.
*Codice:* `app/tx/broadcast.py:_prevout_amount` · `app/wallet/psbt_builder.py:estimate_vsize` ·
*Test:* `tests/unit/test_broadcast.py::test_bump_fee_holds_no_session_open_during_network_calls`
@@ -0,0 +1,19 @@
# ADR-36 — Password con Argon2, sessioni con JWT HS256 da 24 ore, revocabili
- **Stato:** Accettata
- **Area:** Account, amministrazione e sicurezza
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Password con Argon2, sessioni con JWT HS256 da 24 ore,
revocabili.** Il token porta la versione dell'account (`tv`); cambio password
e reset admin la incrementano e invalidano tutte le sessioni precedenti. Un
token senza `tv` vale come versione 0, così il rilascio non ha disconnesso
nessuno. Argon2 gira fuori dall'event loop.
- *Motivazione:* un reset per account compromesso deve buttare fuori subito
l'attaccante (B-34); Argon2 inline bloccava l'intero processo, attività in
background comprese (B-55).
*Codice:* `app/auth/security.py:create_access_token` · `app/auth/security.py:decode_access_token` · `app/auth/dependencies.py:get_current_user` · `app/auth/security.py:verify_password_async` ·
*Test:* `tests/unit/test_security.py`, `tests/unit/test_users.py::test_change_password_invalidates_the_old_token_but_not_the_new_one`
@@ -0,0 +1,16 @@
# ADR-37 — Nessun recupero password, solo reset
- **Stato:** Accettata
- **Area:** Account, amministrazione e sicurezza
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Nessun recupero password, solo reset.** Non si raccoglie
nessuna email. L'utente autenticato può *cambiare* la password fornendo
quella attuale; chi l'ha persa si rivolge all'operatore, che con
`POST /admin/users/{id}/reset-password` ne genera una casuale, mostrata una
volta sola e registrata in audit (`admin_password_reset`).
*Codice:* `app/api/routes/users.py:change_password` · `app/api/routes/admin.py:reset_user_password` ·
*Test:* `tests/unit/test_users.py::test_change_password_requires_current_password`, `tests/unit/test_admin.py::test_admin_resets_user_password`
@@ -0,0 +1,20 @@
# ADR-38 — Gli username sono un unico spazio di nomi senza distinzione fra maiuscole e minuscole
- **Stato:** Accettata
- **Area:** Account, amministrazione e sicurezza
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Gli username sono un unico spazio di nomi senza distinzione fra
maiuscole e minuscole**, garantito da un indice unico su `lower(username)`;
il nome resta salvato come digitato (è ciò che mostrano `/admin` e l'audit).
Sono ammessi solo caratteri ASCII `[A-Za-z0-9_.-]`, 3–32. La migrazione si
rifiuta di partire se due account esistenti differiscono solo per le
maiuscole, invece di sceglierne uno da rinominare: entrambi potrebbero avere
fondi.
- *Motivazione:* «Bob» e «bob» erano due account che condividevano il
contatore dei tentativi e un comodo vettore di impersonazione (B-57).
*Codice:* `app/db/models.py:User` · `app/auth/routes.py:register` · `app/auth/routes.py:login` ·
*Test:* `tests/unit/test_auth.py::test_registration_refuses_a_username_differing_only_by_case`, `tests/unit/test_auth.py::test_the_database_itself_rejects_a_case_variant`
@@ -0,0 +1,16 @@
# ADR-39 — L'esportazione della chiave privata WIF di un utente è voluta, non una vulnerabilità
- **Stato:** Accettata
- **Area:** Account, amministrazione e sicurezza
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**L'esportazione della chiave privata WIF di un utente è
voluta, non una vulnerabilità.** Il server possiede già la master key:
l'endpoint espone via API solo ciò che un operatore potrebbe comunque
ottenere con uno script (ad esempio per recuperare fondi bloccati). Ogni
accesso scrive `admin_privkey_accessed`, e quella registrazione non va tolta.
*Codice:* `app/api/routes/admin.py:user_privkey` · `app/wallet/hd.py:derive_user_wif` ·
*Test:* `tests/unit/test_admin.py::test_admin_exports_user_privkey`
@@ -0,0 +1,18 @@
# ADR-40 — L'amministrazione usa un unico token condiviso
- **Stato:** Accettata
- **Area:** Account, amministrazione e sicurezza
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**L'amministrazione usa un unico token condiviso**
(`X-Admin-Token` confrontato a tempo costante sui byte UTF-8 con
`ADMIN_TOKEN`), non un login per operatore. `/admin` mostra una schermata di
inserimento del token, **non è collegato da `/`** (né `/` da `/admin`) ed è in
italiano, non tradotto.
- *Conseguenze:* l'audit registra *cosa* è cambiato, mai *chi* l'ha fatto
([LIM-06]).
*Codice:* `app/api/routes/admin.py:require_admin` · `app/main.py:admin_panel` · `app/static/admin.html` ·
*Test:* `tests/unit/test_admin.py::test_admin_requires_token`, `tests/unit/test_admin.py::test_admin_rejects_non_ascii_token_with_403_not_500`
@@ -0,0 +1,28 @@
# ADR-41 — Limitazione dei tentativi solo su login e registrazione
- **Stato:** Accettata — implementazione da completare (B-94)
- **Area:** Account, amministrazione e sicurezza
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Limitazione dei tentativi solo su login e registrazione**, in
memoria. Il login usa un ritardo esponenziale per username (dopo 5 errori) e
per IP (dopo 20, soglia più alta per non punire una rete condivisa); un
login riuscito azzera solo il contatore dello username. La registrazione usa
invece una **quota** di 5 account per IP all'ora, consumata solo dagli
account creati davvero. I contatori sono limitati in numero.
- *Motivazione:* indovinare una password e creare account in massa sono due
problemi diversi (B-33, B-58); il ritardo punisce i tentativi, la quota
limita la produzione.
- *Conseguenze:* nessun limite su scommesse, prelievi, admin ([LIM-07]).
Il cambio password (limitato e registrato come `password_changed`) e le
segnalazioni di bug (limitate per IP) si aggiungono con B-94; ogni campo
delle credenziali ha una lunghezza massima di 256 caratteri
([sicurezza.md](../sicurezza.md#limiti-di-frequenza), B-94).
*Codice:* `app/auth/rate_limit.py:AuthRateLimiters` · `app/auth/rate_limit.py:RateLimiter` · `app/auth/rate_limit.py:RollingQuota` · `app/auth/routes.py:login` · `app/api/routes/users.py:change_password` · `app/api/routes/bug_reports.py:create_bug_report` ·
*Test:* `tests/unit/test_auth.py`, `tests/unit/test_rate_limit.py`
*Stato:* da implementare (B-94) · *Oggi:* cambio password e segnalazioni di
bug non hanno limiti né lunghezze massime, e il cambio password non scrive
audit.
@@ -0,0 +1,16 @@
# ADR-42 — L'IP del client è l'ultimo elemento di `X-Forwarded-For`
- **Stato:** Accettata
- **Area:** Account, amministrazione e sicurezza
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**L'IP del client è l'ultimo elemento di `X-Forwarded-For`**, e
Caddy sovrascrive l'header con il vero indirizzo del peer. Un solo proxy
fidato sta davanti all'applicazione, che non è esposta direttamente.
- *Motivazione:* il primo elemento è scelto dal client; leggerlo rendeva
aggirabile ogni controllo per IP (B-54). Basta una delle due misure.
*Codice:* `app/api/client_ip.py:client_ip` · `Caddyfile` ·
*Test:* `tests/unit/test_client_ip.py`, `tests/unit/test_caddyfile_security_headers.py::test_forwarded_for_is_overwritten_with_the_real_peer`
@@ -0,0 +1,18 @@
# ADR-43 — Header di sicurezza nel proxy, con `'unsafe-inline'` accettato
- **Stato:** Accettata
- **Area:** Account, amministrazione e sicurezza
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Header di sicurezza nel proxy, con `'unsafe-inline'`
accettato**: HSTS, `nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy` e una
CSP `default-src 'self'` più Google Fonts. Script e stili inline restano
permessi perché entrambe le SPA usano `onclick` e `style=""`; rimuoverli è un
refactoring a parte. La documentazione automatica dell'API (`/docs`,
`/redoc`, `/openapi.json`) è spenta per default (`ENABLE_API_DOCS`).
- *Conseguenze:* [LIM-09].
*Codice:* `Caddyfile` · `app/main.py` · `app/config.py:Settings` ·
*Test:* `tests/unit/test_caddyfile_security_headers.py`, `tests/unit/test_docs_disabled.py`
@@ -0,0 +1,15 @@
# ADR-44 — `/qr/{address}` è pubblico ma limitato
- **Stato:** Accettata
- **Area:** Account, amministrazione e sicurezza
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**`/qr/{address}` è pubblico ma limitato**: nessuna
autenticazione (lo usa un `<img>`, che non può portare il token), ma
l'indirizzo è validato davvero, la lunghezza è limitata, la resa è in cache
(512 voci) e fuori dall'event loop.
*Codice:* `app/api/routes/qr.py:address_qr` ·
*Test:* `tests/unit/test_qr.py`
@@ -0,0 +1,16 @@
# ADR-45 — Segnalazioni di bug aperte a tutti, triage in admin
- **Stato:** Accettata
- **Area:** Account, amministrazione e sicurezza
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Segnalazioni di bug aperte a tutti, triage in admin.** Si può
inviare una segnalazione da autenticati (viene attribuita all'utente) o no;
il testo va scritto in inglese, e la pagina lo dice nella lingua del
visitatore. Gli stati sono `open` → `read` → `resolved`, e ogni cambio reale
di stato è registrato in audit.
*Codice:* `app/api/routes/bug_reports.py:create_bug_report` · `app/api/routes/admin.py:update_bug_report_status` ·
*Test:* `tests/unit/test_bug_reports.py`
@@ -0,0 +1,23 @@
# ADR-46 — Il canale SSE è un'aggiunta al polling, non un sostituto
- **Stato:** Accettata
- **Area:** Interfacce, API e lingue
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Il canale SSE è un'aggiunta al polling, non un sostituto.**
Nessun contenuto e nessuna autenticazione: è solo un «è cambiato qualcosa,
ricarica»; la personalizzazione resta negli endpoint REST autenticati. Un
unico segnale per tutti (non per utente), una coda da 1 elemento per client
così le notifiche ridondanti si fondono, tetto di 500 connessioni globali e 5
per IP (oltre, si chiude la connessione più vecchia dello stesso IP). Le
pagine ricaricano anche all'evento `open` di ogni riconnessione.
- *Alternative scartate:* canale per utente (servirebbe autenticazione sul
flusso e sapere a chi interessa ogni evento); Redis pub/sub (solo quando ci
saranno più processi).
- *Conseguenze:* se il canale cade o è bloccato, le pagine continuano a
funzionare con il solo polling.
*Codice:* `app/rounds/events.py:RoundEventBroadcaster` · `app/api/routes/rounds.py:round_stream` ·
*Test:* `tests/unit/test_round_events.py`
@@ -0,0 +1,19 @@
# ADR-47 — L'API parla una sola lingua e risponde con codici
- **Stato:** Accettata
- **Area:** Interfacce, API e lingue
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**L'API parla una sola lingua e risponde con codici.** Ogni
errore rivolto all'utente ha `detail = {code, message, params}`: `message` è
in inglese per chi non usa la dashboard, `code` è ciò che il frontend traduce
(`error.<code>`), `params` porta i valori (gli importi come `*_sats`). Anche
l'errore 500 generico ha questa forma (`internal_error`) e non espone il
testo dell'eccezione.
- *Conseguenze:* aggiungere un errore significa dargli un codice e
aggiungere `error.<code>` in tutte le 7 lingue (vedi [api.md](../api.md)).
*Codice:* `app/api/errors.py:ApiError` · `app/api/errors.py:http_error` · `app/main.py:log_unhandled_exception` ·
*Test:* `tests/unit/test_rounds_route.py::test_unhandled_errors_use_the_structured_detail_shape`
@@ -0,0 +1,20 @@
# ADR-48 — Le pagine per l'utente (`/` e `/report-bug`) sono in 7 lingue
- **Stato:** Accettata
- **Area:** Interfacce, API e lingue
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Le pagine per l'utente (`/` e `/report-bug`) sono in 7 lingue**
(en, it, es, fr, de, ru, zh) da un'unica tabella piatta, senza build né
download. Lingua scelta da `localStorage.plm_lang`, poi dal browser, poi
inglese; nessun'altra lingua di riserva oltre l'inglese. Il selettore di `/`
sta nella barra di stato della catena, non nella barra di navigazione
(nascosta prima del login). Un elemento è tradotto *o* dagli attributi
`data-i18n` *o* dal codice con `t()`, mai da entrambi. Tutte le lingue devono
avere esattamente le stesse chiavi.
- *Conseguenze:* la parità delle chiavi non è verificata da un test
([LIM-21]).
*Codice:* `app/static/i18n.js:t` · `app/static/i18n.js:applyStaticTranslations` · `app/static/i18n.js:setLanguage` · `app/static/app.js:onLanguageChange`
@@ -0,0 +1,12 @@
# ADR-49 — Il pannello `/admin` e la pagina `/guida` non sono tradotti
- **Stato:** Accettata
- **Area:** Interfacce, API e lingue
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Il pannello `/admin` e la pagina `/guida` non sono tradotti**
(sono in italiano, per l'operatore).
*Codice:* `app/static/admin.html` · `app/static/guida.html`
@@ -0,0 +1,20 @@
# ADR-50 — Frontend statici, senza framework né build
- **Stato:** Accettata — implementazione da completare (B-94)
- **Area:** Interfacce, API e lingue
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Frontend statici, senza framework né build**: due SPA servite
direttamente da FastAPI, che parlano con la stessa API JSON (nessuna
separazione fra API utente e admin oltre al controllo del token). Le pagine
HTML hanno `Cache-Control: no-store`, i file JS e CSS `Cache-Control:
no-cache` (il browser li riconvalida a ogni caricamento, così un
aggiornamento non lascia una pagina nuova con uno script vecchio;
[architettura.md](../architettura.md#allimport), B-94).
*Codice:* `app/main.py:index_page` · `app/main.py:admin_panel` · `app/static/app.js` · `app/static/admin.js`
*Stato:* da implementare (B-94) · *Oggi:* solo le quattro pagine HTML hanno
`Cache-Control` (`no-store`); JS e CSS, serviti da `StaticFiles`, non ne
hanno.
@@ -0,0 +1,39 @@
# ADR-51 — Nel dubbio non si liberano mai i fondi
- **Stato:** Accettata
- **Area:** Denaro in movimento
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Nel dubbio non si liberano mai i fondi** (decisione del
2026-09-28). Una riga che sposta denaro (scommessa, prelievo, pagamento) si
annulla, liberandone le monete, solo con una **prova**: un rifiuto esplicito
della rete all'invio, oppure i suoi ingressi spesi da un'altra transazione
confermata (corroborata dal quorum), oppure nessun server del quorum che
conosca alcun txid della riga *e* una ritrasmissione dell'ultima versione a
tutti i server rifiutata per ingressi mancanti o già spesi. Mai per un
timeout, per l'età della riga o per il silenzio di un solo server. Si
seguono tutti i txid che una riga ha avuto (ogni versione RBF): la conferma
di uno qualsiasi conferma la riga. Le righe `failed` restano sorvegliate per
14 giorni; una conferma tardiva scrive `pending_tx_resurrected` e mette in
pausa la lotteria ([ADR-28](ADR-28-pausa-manutenzione-ferma-round-successivo.md)). Regole in
[transazioni-e-riconciliazione.md](../transazioni-e-riconciliazione.md#riconciliazione)
(B-76, B-77, B-78).
- *Motivazione:* liberare le monete di una transazione che poi conferma è
l'errore peggiore possibile: la scommessa finisce nel montepremi senza
partecipante, il prelievo parte mentre la riga dice `failed`, il pagamento
viene ricostruito e il vincitore pagato due volte. Tutti e tre accadevano
con un invio andato in timeout (B-76), con la conferma di una versione RBF
precedente (B-77) o con un riavvio su un server che non aveva ancora visto
la transazione (B-78).
- *Alternative scartate:* abbandono a tempo (la regola precedente: 120s per
`building`, 6 ore per `pending`), che trasforma un ritardo di rete in una
perdita; abbandono sul parere del solo server attivo.
- *Conseguenze:* una transazione ferma ma viva non si abbandona mai: la si
accelera ([ADR-18](ADR-18-l-accelerazione-rbf-paga-chi-riceve.md)); un round può restare in `closing` o `paying_out`
finché la rete non decide ([LIM-02], [LIM-03]). Il denaro in dubbio resta
congelato e visibile, mai duplicato.
*Codice:* `app/tx/reconcile.py:reconcile_once` · `app/tx/reconcile.py:_is_due` · `app/bets/service.py:place_bet` · `app/withdrawals/service.py:request_withdrawal` · `app/tx/confirmation.py:poll_once` · `app/tx/broadcast.py:bump_fee` ·
*Test:* `tests/unit/test_broadcast_outcome.py`, `tests/unit/test_tx_versions.py`, `tests/unit/test_reconcile_proof.py`
@@ -0,0 +1,48 @@
# ADR-52 — Le riorganizzazioni della catena si contengono invece di ignorarle
- **Stato:** Accettata — implementazione da completare (B-82)
- **Area:** Conferme e fiducia nella rete
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Le riorganizzazioni della catena si contengono invece di
ignorarle** (decisione del 2026-09-28). Tre misure:
- *si rilevano*: il listener tiene gli ultimi 10 header e segue una
biforcazione fino al punto comune; ogni riorganizzazione scrive
`chain_reorg_detected` con profondità e altezze. Una biforcazione che non
trova il punto comune entro 10 header è trattata come un header non
valido (fine della sessione e rotazione, [ADR-26](ADR-26-validazione-degli-header-concatenata-senza-ricalcolo.md));
- *si fermano quelle profonde*: una profondità ≥ 2 mette in pausa la
lotteria (`paused_reason = 'reorg'`, [ADR-28](ADR-28-pausa-manutenzione-ferma-round-successivo.md)) finché l'operatore non la
riprende;
- *si paga solo ciò che è in catena*: prima di costruire un pagamento le
monete dell'indirizzo del round si verificano con il quorum; i
partecipanti la cui scommessa non c'è più diventano `reorged_out` e la
ripartizione 70/30 si calcola su ciò che resta. Se manca la scommessa del
vincitore, il pagamento è trattenuto (`payout_blocked`) e la lotteria va in
pausa.
Regole in [connessione-electrum.md](../connessione-electrum.md#4-header-validati-non-creduti)
e [ciclo-di-vita-del-round.md](../ciclo-di-vita-del-round.md#4--pagamento)
(B-82, B-85).
- *Motivazione:* la regola precedente («1 conferma, nessun rollback»)
presupponeva riorganizzazioni rare e innocue. Con la potenza di PLM in
affitto una riorganizzazione è un attacco possibile, e senza queste misure
una sola scommessa sparita rende il round impagabile per sempre (B-82),
mentre una riorganizzazione di un blocco, normale in qualunque catena,
veniva scambiata per un server ostile (B-74).
- *Alternative scartate:* ignorare le riorganizzazioni (la regola
precedente); un rollback completo (ricalcolare saldi già spesi e ripetere
estrazioni già rivelate non è sempre possibile e sposterebbe denaro senza
l'operatore); pausa anche per profondità 1 (una riorganizzazione di un
blocco è frequente e non tocca i depositi a 6 conferme, [ADR-06](ADR-06-depositi-richiedono-deposit-confirmations-conferme-6.md)).
- *Conseguenze:* un attacco al 51% resta possibile; queste misure lo
rendono visibile, fanno sì che non blocchi la lotteria in modo
irrecuperabile e limitano il danno a ciò che l'attaccante ha rimosso
([LIM-24]).
*Codice:* `app/electrum/listener.py:ElectrumListener._record_reorg` · `app/rounds/scheduler.py:RoundScheduler._trigger_payout` · `app/rounds/service.py:open_new_round_if_needed` ·
*Test:* `tests/unit/test_electrum_listener.py`
*Stato:* da implementare (B-82) · *Oggi:* il pagamento non verifica le monete
del round: le prime due misure (rilevare, fermare) sono attive.
@@ -0,0 +1,24 @@
# ADR-53 — Il registro di audit è in sola aggiunta e si scrive nella transazione che descrive
- **Stato:** Accettata
- **Area:** Account, amministrazione e sicurezza
- **Fonte di verità per:** la scelta di progetto descritta qui sotto; i requisiti (`PREFISSO-NN`) che la attuano stanno nei documenti di dominio, indicati nelle *Conseguenze*.
## Decisione
**Tutto ciò che muove denaro o cambia la configurazione lascia una riga in
`audit_log`; la riga nasce da un'unica funzione, è salvata nella stessa
transazione del cambiamento che descrive (tranne gli eventi puramente
osservativi) e non viene mai modificata né cancellata.**
- *Motivazione:* l'amministrazione ha un solo token condiviso senza identità
per singolo operatore ([ADR-40](ADR-40-l-amministrazione-usa-unico-token-condiviso.md)):
il registro è l'unica forma di responsabilità per le azioni dal pannello e il
primo posto dove ricostruire cosa è successo dopo un problema.
- *Conseguenze:* o si salvano insieme il cambiamento e la sua riga, o nessuno
dei due; il registro dice *cosa* è cambiato ma non *chi* (vedi
[ADR-40](ADR-40-l-amministrazione-usa-unico-token-condiviso.md)). Il
catalogo degli eventi e le regole di scrittura e lettura sono in
[audit-log.md](../audit-log.md) (`AUD-01` … `AUD-05`).
*Codice:* `app/audit/log.py:write_audit_log`
+132
View File
@@ -0,0 +1,132 @@
# Architecture Decision Records (ADR)
Una decisione di progetto = un file. Ogni ADR spiega **perché** una scelta è stata fatta (contesto, alternative scartate, conseguenze); le regole verificabili che la attuano restano nei documenti di dominio con il loro `PREFISSO-NN`. Così ogni informazione ha un solo proprietario: l'ADR possiede il *perché*, il requisito possiede il *cosa*, il codice il *come*. Regole: [processo-di-modifica.md](../processo-di-modifica.md). Modello per i nuovi: [TEMPLATE.md](TEMPLATE.md).
Gli identificativi `ADR-NN` sono stabili e non si riusano (i primi 52 coincidono con i vecchi `DEC-NN`). Un ADR superato non si cancella: passa a *Sostituita da ADR-MM*.
## Indice per area
### Custodia, chiavi e indirizzi
| ADR | Decisione |
|---|---|
| [ADR-01](ADR-01-piattaforma-custodiale-tutte-chiavi-generate-tenute.md) | La piattaforma è custodiale: tutte le chiavi sono generate e tenute dal server |
| [ADR-02](ADR-02-indirizzo-utente-permanente-tutti-usi.md) | Un indirizzo per utente, permanente, per tutti gli usi |
| [ADR-03](ADR-03-ogni-round-ha-proprio-indirizzo-montepremi.md) | Ogni round ha il proprio indirizzo del montepremi |
| [ADR-04](ADR-04-accesso-rete-via-protocollo-electrum.md) | Accesso alla rete solo via protocollo Electrum |
| [ADR-05](ADR-05-indirizzi-bech32-plm-plm1-come-destinazione.md) | Solo indirizzi bech32 PLM (`plm1…`) come destinazione |
### Conferme e fiducia nella rete
| ADR | Decisione |
|---|---|
| [ADR-06](ADR-06-depositi-richiedono-deposit-confirmations-conferme-6.md) | I depositi richiedono `deposit_confirmations` conferme (6 per default, configurabile in `round_config`), le uscite coinbase 120; ogni altra transazione ne richiede 1 |
| [ADR-07](ADR-07-ogni-decisione-sposta-denaro-base-risposta.md) | Ogni decisione che sposta denaro in base a una risposta di rete è corroborata da un quorum degli altri server configurati |
| [ADR-52](ADR-52-riorganizzazioni-catena-contengono-invece-ignorarle.md) | Le riorganizzazioni della catena si contengono invece di ignorarle |
### Configurazione e ambiente
| ADR | Decisione |
|---|---|
| [ADR-08](ADR-08-parametri-operativi-stanno-database-segreti-nell.md) | I parametri operativi stanno nel database, i segreti nell'ambiente |
| [ADR-09](ADR-09-modifiche-configurazione-validate-fidate.md) | Le modifiche di configurazione sono validate, non fidate |
| [ADR-10](ADR-10-parametri-round-fotografati-all-apertura.md) | I parametri del round sono fotografati all'apertura |
| [ADR-11](ADR-11-server-rifiuta-partire-segreti-inadeguati.md) | Il server rifiuta di partire con segreti inadeguati |
| [ADR-12](ADR-12-server-gira-docker-sviluppo-come-produzione.md) | Il server gira solo in Docker, in sviluppo come in produzione |
| [ADR-13](ADR-13-processo-file-sqlite.md) | Un solo processo, un solo file SQLite |
### Economia del gioco
| ADR | Decisione |
|---|---|
| [ADR-14](ADR-14-ripartizione-fissa-70-vincitore-30-piattaforma.md) | Ripartizione fissa 70% al vincitore / 30% alla piattaforma |
| [ADR-15](ADR-15-biglietto-prezzo-fisso-scommessa-utente-round.md) | Biglietto a prezzo fisso, una scommessa per utente per round, probabilità uguale per tutti |
| [ADR-16](ADR-16-commissione-rete-toglie-dall-importo-muove.md) | La commissione di rete si toglie dall'importo che si muove |
| [ADR-17](ADR-17-commissione-pagamento-esce-dalla-quota-vincitore.md) | La commissione del pagamento esce dalla quota del vincitore; la riserva per l'RBF esce dalla quota della piattaforma |
| [ADR-18](ADR-18-l-accelerazione-rbf-paga-chi-riceve.md) | L'accelerazione RBF la paga chi riceve il resto |
| [ADR-19](ADR-19-ogni-transazione-utente-conserva-uscita-resto.md) | Ogni transazione utente conserva un'uscita di resto verso l'utente, e un'accelerazione che porterebbe quel resto sotto `DUST_LIMIT_SATS` (294 sat) lo elimina |
| [ADR-20](ADR-20-prelievo-minimo-costo-corrente-scommessa.md) | Il prelievo minimo è il costo corrente della scommessa |
| [ADR-21](ADR-21-tre-limiti-distinti-sul-numero-monete.md) | Tre limiti distinti sul numero di monete e di giocatori: |
### Round ed estrazione
| ADR | Decisione |
|---|---|
| [ADR-22](ADR-22-piu-round-attivo-come-invariante-database.md) | Al più un round attivo, come invariante del database |
| [ADR-23](ADR-23-limite-scommettere-scadenza-round-stesso-suo.md) | Il limite per scommettere è la scadenza del round stesso, non il suo stato nel database |
| [ADR-24](ADR-24-l-estrazione-commit-reveal-fra-server.md) | L'estrazione è un commit-reveal fra il server e un blocco futuro |
| [ADR-25](ADR-25-blocco-estrazione-fissato-altezza-successivo-chiusura.md) | Il blocco di estrazione è fissato per altezza, è successivo alla chiusura, e si usa solo quando è confermato e corroborato |
| [ADR-26](ADR-26-validazione-degli-header-concatenata-senza-ricalcolo.md) | Validazione degli header concatenata, senza ricalcolo della difficoltà |
| [ADR-27](ADR-27-pausa-cortesia-fra-round-l-altro.md) | Pausa di cortesia fra un round e l'altro |
| [ADR-28](ADR-28-pausa-manutenzione-ferma-round-successivo.md) | La pausa per manutenzione ferma solo il round successivo |
| [ADR-29](ADR-29-senza-fee-address-apre-nessun-round.md) | Senza `fee_address` non si apre nessun round |
| [ADR-30](ADR-30-montepremi-annunciato-quello-sara-pagato.md) | Il montepremi annunciato è quello che sarà pagato |
### Denaro in movimento
| ADR | Decisione |
|---|---|
| [ADR-31](ADR-31-tutto-cio-spende-denaro-scrive-prima.md) | Tutto ciò che spende denaro si scrive prima di inviarlo |
| [ADR-32](ADR-32-pagamento-ritenta-mai-due-volte.md) | Il pagamento si ritenta da solo, mai due volte |
| [ADR-33](ADR-33-scommessa-prelievo-escludono-tramite-blocco-utente.md) | Scommessa e prelievo si escludono solo tramite il blocco per-utente |
| [ADR-34](ADR-34-saldo-spendibile-saldo-mostrato-due-numeri.md) | Saldo spendibile e saldo mostrato sono due numeri distinti |
| [ADR-35](ADR-35-aritmetica-satoshi-interi.md) | Aritmetica solo in satoshi interi |
| [ADR-51](ADR-51-dubbio-liberano-mai-fondi.md) | Nel dubbio non si liberano mai i fondi |
### Account, amministrazione e sicurezza
| ADR | Decisione |
|---|---|
| [ADR-36](ADR-36-password-argon2-sessioni-jwt-hs256-24.md) | Password con Argon2, sessioni con JWT HS256 da 24 ore, revocabili |
| [ADR-37](ADR-37-nessun-recupero-password-reset.md) | Nessun recupero password, solo reset |
| [ADR-38](ADR-38-username-unico-spazio-nomi-senza-distinzione.md) | Gli username sono un unico spazio di nomi senza distinzione fra maiuscole e minuscole |
| [ADR-39](ADR-39-l-esportazione-chiave-privata-wif-utente.md) | L'esportazione della chiave privata WIF di un utente è voluta, non una vulnerabilità |
| [ADR-40](ADR-40-l-amministrazione-usa-unico-token-condiviso.md) | L'amministrazione usa un unico token condiviso |
| [ADR-41](ADR-41-limitazione-tentativi-su-login-registrazione.md) | Limitazione dei tentativi solo su login e registrazione |
| [ADR-42](ADR-42-l-ip-client-l-ultimo-elemento.md) | L'IP del client è l'ultimo elemento di `X-Forwarded-For` |
| [ADR-43](ADR-43-header-sicurezza-proxy-unsafe-inline-accettato.md) | Header di sicurezza nel proxy, con `'unsafe-inline'` accettato |
| [ADR-44](ADR-44-qr-address-pubblico-limitato.md) | `/qr/{address}` è pubblico ma limitato |
| [ADR-45](ADR-45-segnalazioni-bug-aperte-tutti-triage-admin.md) | Segnalazioni di bug aperte a tutti, triage in admin |
| [ADR-53](ADR-53-registro-audit-solo-aggiunta-stessa-transazione.md) | Il registro di audit è in sola aggiunta e si scrive nella transazione che descrive |
### Interfacce, API e lingue
| ADR | Decisione |
|---|---|
| [ADR-46](ADR-46-canale-sse-aggiunta-polling-sostituto.md) | Il canale SSE è un'aggiunta al polling, non un sostituto |
| [ADR-47](ADR-47-l-api-parla-sola-lingua-risponde.md) | L'API parla una sola lingua e risponde con codici |
| [ADR-48](ADR-48-pagine-l-utente-report-bug-7.md) | Le pagine per l'utente (`/` e `/report-bug`) sono in 7 lingue |
| [ADR-49](ADR-49-pannello-admin-pagina-guida-tradotti.md) | Il pannello `/admin` e la pagina `/guida` non sono tradotti |
| [ADR-50](ADR-50-frontend-statici-senza-framework-ne-build.md) | Frontend statici, senza framework né build |
## Funzionalità → ADR
Per ogni funzionalità, gli ADR da leggere prima di toccarla.
| Funzionalità | Prefisso | Documento di dominio | ADR |
|---|---|---|---|
| Registrazione e account | `REG` | [registrazione-e-depositi.md](../registrazione-e-depositi.md) | 01, 02, 36, 37, 38 |
| Depositi e saldo | `DEP` | [registrazione-e-depositi.md](../registrazione-e-depositi.md) | 06, 07, 34, 35, 52 |
| Scommesse | `BET` | [scommesse-e-prelievi.md](../scommesse-e-prelievi.md) | 15, 16, 19, 21, 23, 33 |
| Prelievi | `WDR` | [scommesse-e-prelievi.md](../scommesse-e-prelievi.md) | 05, 18, 19, 20, 33 |
| Round, estrazione, pagamento | `RND` | [ciclo-di-vita-del-round.md](../ciclo-di-vita-del-round.md) | 03, 10, 14, 17, 21–30, 32 |
| Transazioni, RBF, riconciliazione | `TX` | [transazioni-e-riconciliazione.md](../transazioni-e-riconciliazione.md) | 17, 18, 31, 32, 51 |
| Connessione Electrum | `ELC` | [connessione-electrum.md](../connessione-electrum.md) | 04, 07, 26, 52 |
| Registro di audit | `AUD` | [audit-log.md](../audit-log.md) | 40, 53 |
| Amministrazione | `SEC`, `API` | [sicurezza.md](../sicurezza.md), [api.md](../api.md) | 09, 28, 29, 39, 40 |
| Sicurezza (limiti, header, QR) | `SEC` | [sicurezza.md](../sicurezza.md) | 41, 42, 43, 44 |
| Segnalazioni di bug | `API` | [api.md](../api.md) | 45 |
| Tempo reale (SSE) | `ARC` | [architettura.md](../architettura.md) | 46 |
| Interfacce e lingue | `ARC`, `API` | [architettura.md](../architettura.md) | 47, 48, 49, 50 |
| Configurazione e ambiente | `ARC`, `OPS` | [architettura.md](../architettura.md), [operativita.md](../operativita.md) | 08, 09, 10, 11, 12, 13 |
## Le decisioni del 2026-09-28
| Decisione | ADR | B-nn |
|---|---|---|
| Estrazione con commit-reveal | [ADR-24](ADR-24-l-estrazione-commit-reveal-fra-server.md), [ADR-25](ADR-25-blocco-estrazione-fissato-altezza-successivo-chiusura.md) | B-73, B-81 |
| Nel dubbio non si liberano mai i fondi | [ADR-51](ADR-51-dubbio-liberano-mai-fondi.md) | B-76, B-77, B-78 |
| Un indirizzo del montepremi per ogni round | [ADR-03](ADR-03-ogni-round-ha-proprio-indirizzo-montepremi.md) | B-80 |
| 6 conferme per i depositi, 1 per il resto | [ADR-06](ADR-06-depositi-richiedono-deposit-confirmations-conferme-6.md) | B-82 |
| Le riorganizzazioni della catena si contengono | [ADR-52](ADR-52-riorganizzazioni-catena-contengono-invece-ignorarle.md) | B-82, B-85 |
+26
View File
@@ -0,0 +1,26 @@
# ADR-NN — <la decisione, in una frase affermativa>
- **Stato:** Proposta | Accettata | Accettata — implementazione da completare (B-nn) | Sostituita da [ADR-MM](ADR-MM-slug.md) | Rifiutata
- **Area:** <una delle aree di [README.md](README.md)>
- **Funzionalità:** <prefisso/i dei requisiti coinvolti: REG, DEP, BET, WDR, RND, TX, ELC, AUD, …>
## Contesto
<Il problema e i vincoli. Che cosa succede oggi, perché non basta.>
## Decisione
**<La scelta, in grassetto, in una frase.>** <Dettagli indispensabili. Le regole
verificabili NON si scrivono qui: stanno nel documento di dominio con il loro
`PREFISSO-NN`; qui si rimanda a quegli ID.>
## Alternative scartate
- <alternativa> — <perché no>
## Conseguenze
- <effetti, rischi accettati, limiti `LIM-nn` che ne derivano, ADR collegati>
- Requisiti che la attuano: <`RND-11`, `BET-04` …> (nei documenti di dominio)
*Codice:* `percorso:funzione` · *Test:* `tests/unit/…`
+1080
View File
File diff suppressed because it is too large. Load diff
+991
View File
@@ -0,0 +1,991 @@
# Architettura
Come è fatto il software dall'interno: quali processi girano, come è
organizzato il codice, cosa succede all'avvio, quali attività lavorano in
background, dove sta la configurazione, come le pagine web restano
aggiornate e come è strutturata la suite di test.
Questo documento non descrive i flussi di dominio (scommesse, round,
depositi…): per quelli rimanda ai documenti che li possiedono, elencati in
[come-funziona.md](come-funziona.md). Le tabelle del database sono in
[modello-dati.md](modello-dati.md), gli endpoint in [api.md](api.md), le
difese di sicurezza in [sicurezza.md](sicurezza.md).
## Panoramica del deployment
```mermaid
flowchart LR
B["Browser<br/>(/, /admin, /report-bug)"] -- "HTTPS 443<br/>(80 → redirect)" --> C["Container caddy<br/>reverse proxy + TLS"]
C -- "HTTP app:8123<br/>(rete interna compose)" --> A["Container app<br/>1 processo uvicorn<br/>FastAPI + 6 task asyncio"]
A -- "aiosqlite" --> D[("./data/db/plm_lottery.db<br/>SQLite, WAL")]
A -- "legge" --> K["./data/keys/master.xprv.enc"]
A -- "scrive" --> L["./data/logs/app.log<br/>(e stdout, B-92)"]
A -- "Electrum (TCP/SSL)<br/>una connessione attiva" --> E["Server Electrum PLM<br/>primario + riserve"]
```
- **[ARC-01]** Il server gira sempre in Docker, con lo stesso
`docker-compose.yml` in sviluppo e in produzione: due container, `app`
(questo codice) e `caddy` (reverse proxy con TLS automatico). Cambia solo
`SITE_ADDRESS`, che sta in `.env` ed è obbligatorio: il compose lo legge
come `${SITE_ADDRESS:?}` e si rifiuta di partire se manca. `localhost`
produce un certificato autofirmato dalla CA interna di Caddy, un dominio un
certificato Let's Encrypt. Non esiste un modo supportato di lanciare
`uvicorn` fuori da Docker.
*Codice:* `docker-compose.yml` · `Caddyfile` ·
*Test:* `tests/unit/test_docs_no_bare_uvicorn.py`
*Stato:* da implementare (B-93) · *Oggi:* `SITE_ADDRESS` si passa sul
comando e non impostato vale `localhost`, quindi un `docker compose up`
senza variabile riporta un server di produzione su `localhost`.
- **[ARC-02]** Il container `app` esegue **un solo processo** uvicorn (nessun
`--workers`), in ascolto su `0.0.0.0:8123`, con `--proxy-headers` e
`--forwarded-allow-ips` limitato all'indirizzo di Caddy: la rete di compose
ha una sottorete fissa e Caddy un indirizzo IPv4 fisso in essa. Così il log
di accesso registra l'IP del client invece di quello di Caddy. Tutto lo
stato in memoria descritto in
[Assunzioni di processo singolo](#assunzioni-di-processo-singolo) dipende da
questo.
*Codice:* `Dockerfile` (`CMD`) · `docker-compose.yml`
*Stato:* da implementare (B-92) · *Oggi:* uvicorn non legge gli header del
proxy e il log di accesso registra l'IP di Caddy.
- **[ARC-03]** All'avvio il container `app`, nell'ordine: rifiuta di partire
se il file indicato da `MASTER_KEY_PATH` non esiste (stampando il comando
per generarlo), poi esegue `alembic upgrade head`, poi avvia uvicorn con
`exec`. Le migrazioni non si lanciano mai a mano. Il processo gira come
utente non root, su un'immagine di base fissata per digest e con dipendenze
installate da un file di lock con gli hash
([sicurezza.md](sicurezza.md#sec-51) SEC-51, SEC-52, SEC-53 (B-91)). I controlli che richiedono il codice
applicativo (chiave, quorum, ripristino) sono nel lifespan ([ARC-60]).
*Codice:* `Dockerfile` (`CMD`) · `migrations/env.py`
*Stato:* da implementare (B-91) · *Oggi:* il container gira come root,
`python:3.12-slim` non è fissato per digest e le dipendenze sono `>=`.
- **[ARC-04]** `app` è solo `expose`d sulla rete interna di compose (porta
8123), mai pubblicato sull'host: l'unico ingresso è Caddy, che pubblica 80 e
443. Su questo si basa la lettura dell'IP del client (vedi
[sicurezza.md](sicurezza.md)). Caddy non comprime `/rounds/stream`, perché
la compressione accumulerebbe gli eventi SSE invece di consegnarli subito.
*Codice:* `docker-compose.yml` · `Caddyfile` ·
*Test:* `tests/unit/test_caddyfile_security_headers.py`
- **[ARC-05]** I dati persistenti stanno in `./data/` sull'host, montata nel
container: `./data/db` → `/app/db_data`, `./data/keys` → `/app/key_data`,
`./data/logs` → `/app/logs`. Il compose sovrascrive `DATABASE_URL` e
`MASTER_KEY_PATH` perché puntino a quei percorsi; tutte le altre variabili
arrivano da `.env` (`env_file`). Entrambi i container hanno
`restart: unless-stopped`. La chiave di cifratura della master key è un
file a parte, `./secrets/xprv_encryption.key` (permessi `0600`, fuori da
`./data/` così un backup dei dati non la contiene), montato in sola lettura
come secret di compose in `/run/secrets/xprv_encryption_key` e indicato da
`XPRV_ENCRYPTION_KEY_FILE` ([ARC-30]). Le directory di `./data/` hanno
permessi `0700`, i file di chiave `0600`. Le immagini sono etichettate per
rilascio, così un rollback sa quale immagine rimettere
([operativita.md](operativita.md) (B-93)).
*Codice:* `docker-compose.yml`
*Stato:* da implementare (B-91, B-93) · *Oggi:* la chiave di cifratura è la
variabile `XPRV_ENCRYPTION_KEY` in `.env`, i permessi sono quelli di default
(`.env` e file di chiave leggibili da tutti) e l'immagine non ha etichetta.
- **[ARC-61]** **Salute del container.** Il container `app` ha un
`healthcheck` che interroga `http://127.0.0.1:8123/health/ready` ogni 30s
(timeout 5s, 3 tentativi, `start_period` 60s). `/health/ready` risponde 200
solo se la connessione Electrum è attiva, l'ultimo header è recente e lo
scheduler ha battuto da poco; le soglie sono di
[api.md](api.md#servizio) (B-92). Lo scheduler aggiorna il battito a ogni
giro **e** a ogni iterazione dell'attesa del blocco di estrazione, perché
quell'attesa gira dentro il giro ([ARC-27]) e dura più blocchi. Docker non
riavvia un container `unhealthy`: lo stato serve al monitoraggio
([operativita.md](operativita.md#segnali-da-tenere-docchio)), e il riavvio
resta affidato a `restart: unless-stopped` quando il processo esce.
*Codice:* `docker-compose.yml` · `app/main.py:health` ·
*Test:* —
*Stato:* da implementare (B-92) · *Oggi:* nessun `healthcheck`; esiste solo
`/health`, che risponde sempre `ok` ([ARC-17]).
### Database
- **[ARC-06]** Il database è SQLite, usato tramite SQLAlchemy 2 in modalità
asincrona (`create_async_engine` su `aiosqlite`). Una sola `engine` e una
sola fabbrica di sessioni (`AsyncSessionLocal`, con
`expire_on_commit=False`) servono sia le richieste HTTP (dipendenza
`get_session`) sia le attività in background, che aprono ciascuna le
proprie sessioni.
*Codice:* `app/db/base.py` · `app/db/session.py:get_session`
- **[ARC-07]** A ogni nuova connessione SQLite vengono impostati
`journal_mode=WAL`, `synchronous=FULL` e `busy_timeout=5000` ms: in WAL
lettori e scrittori non si bloccano a vicenda, uno scrittore che trova il
database occupato aspetta fino a 5 secondi invece di fallire subito, e
`FULL` fa sì che un commit riuscito sopravviva a una mancanza di corrente
(con `NORMAL` si potevano perdere gli ultimi commit, per esempio una
registrazione, riusandone poi l'indice di derivazione). Ogni transazione che
sposta denaro si apre con `BEGIN IMMEDIATE`, così le letture su cui decide
sono isolate e l'attesa del lock avviene all'inizio, non alla prima
scrittura; un `database is locked` dopo un invio è gestito esplicitamente
(la riga resta al riconciliatore). Con un dialetto diverso da SQLite le
pragma non vengono applicate.
*Codice:* `app/db/base.py:_register_sqlite_pragmas` ·
`app/db/base.py:begin_immediate` ·
*Test:* `tests/unit/test_db_base.py` · `tests/unit/test_sqlite_transactions.py`
- **[ARC-08]** Lo schema è definito in `app/db/models.py` ed evolve solo
tramite migrazioni Alembic in `migrations/versions/` (generate con
`alembic revision --autogenerate`); `migrations/env.py` prende l'URL del
database da `settings.database_url`. I campi delle tabelle sono descritti
in [modello-dati.md](modello-dati.md).
*Codice:* `migrations/env.py` · `app/db/models.py`
### Log
- **[ARC-09]** Tutti i log dell'applicazione e di uvicorn (`uvicorn.error`,
`uvicorn.access`) finiscono in `logs/app.log` (nel container
`/app/logs/app.log`, cioè `./data/logs/app.log` sull'host), a rotazione da
10 MB con 5 file di storico, livello `INFO`, **e anche su stdout**, così
`docker compose logs` li mostra senza entrare nel volume. La configurazione
avviene all'import di `app/main.py`, prima di qualunque altro modulo
applicativo.
*Codice:* `app/logging_config.py:setup_logging`
*Stato:* da implementare (B-92) · *Oggi:* i log dell'applicazione vanno solo
nel file; su console arrivano solo quelli di uvicorn, per la sua
configurazione predefinita.
## Mappa del codice
Ogni file sotto `app/`, raggruppato per pacchetto. I file `__init__.py`
sono vuoti e non sono elencati.
### Radice e infrastruttura
| File | Responsabilità |
|---|---|
| `app/main.py` | Punto d'ingresso: `lifespan` (validazione segreti, avvio e arresto dei sei task), inclusione dei router, gestore degli errori non previsti, pagine HTML, `/health`, mount dei file statici |
| `app/config.py` | `Settings` (variabili d'ambiente / `.env`), istanza `settings`, `validate_runtime_secrets`, `ConfigError` |
| `app/logging_config.py` | `setup_logging`: file di log a rotazione |
| `app/db/base.py` | `engine`, `AsyncSessionLocal`, pragma SQLite, `Base` dichiarativa |
| `app/db/session.py` | `get_session`, dipendenza FastAPI che apre una sessione per richiesta |
| `app/db/models.py` | Tutte le tabelle (`User`, `UtxoEvent`, `Round`, `RoundParticipant`, `RoundConfig`, `PendingTransaction`, `Withdrawal`, `BugReport`, `AuditLog`) e l'indice del round attivo unico — vedi [modello-dati.md](modello-dati.md) |
| `app/audit/log.py` | `write_audit_log`: aggiunge una riga al registro di audit nella sessione del chiamante (il commit resta al chiamante) — catalogo eventi in [audit-log.md](audit-log.md) |
### API HTTP
| File | Responsabilità |
|---|---|
| `app/api/errors.py` | `ApiError` (codice + messaggio inglese + parametri), `http_error`, `from_api_error`: il formato strutturato di `detail` — vedi [api.md](api.md) |
| `app/api/client_ip.py` | `client_ip`: IP reale del chiamante (ultimo elemento di `X-Forwarded-For`), usato da tutti i controlli basati sull'IP |
| `app/api/timeutil.py` | `isoformat_utc`: serializza le date come UTC esplicito (SQLite le restituisce senza fuso) |
| `app/api/routes/admin.py` | `/admin/*`: `require_admin` (token condiviso), configurazione, pausa/ripresa, utenti, export WIF, reset password, round, transazioni pendenti, audit log, bug report |
| `app/api/routes/bets.py` | `POST /bets`: controllo connessione, lock per utente, chiamata a `place_bet` |
| `app/api/routes/withdrawals.py` | `POST /withdrawals`: stessa struttura, chiama `request_withdrawal` |
| `app/api/routes/rounds.py` | `GET /rounds/current` e il canale SSE `GET /rounds/stream` |
| `app/api/routes/users.py` | `GET /users/me`, cambio password, `GET /users/me/last-round-result` |
| `app/api/routes/qr.py` | `GET /qr/{address}`: PNG del QR, indirizzo validato, rendering memorizzato e fuori dall'event loop |
| `app/api/routes/bug_reports.py` | `POST /bug-reports`, `GET /bug-reports/mine` |
### Autenticazione
| File | Responsabilità |
|---|---|
| `app/auth/routes.py` | `/auth/register`, `/auth/login`; notifica al listener il nuovo indirizzo da osservare |
| `app/auth/security.py` | Argon2 (versioni sincrone e `*_async` su threadpool), creazione e decodifica JWT, `MIN_PASSWORD_LENGTH` |
| `app/auth/dependencies.py` | `get_current_user`, `get_optional_user` (controllo del claim `tv`) |
| `app/auth/rate_limit.py` | `RateLimiter`, `RollingQuota`, `AuthRateLimiters` (tenuti su `app.state`) — vedi [sicurezza.md](sicurezza.md) |
### Wallet e chiavi
| File | Responsabilità |
|---|---|
| `app/wallet/plm_network.py` | Parametri della rete PLM per embit (`PLM_MAINNET`), coin type 746, `ACCOUNT_PATH` |
| `app/wallet/keystore.py` | Cifratura/decifratura Fernet della master xprv |
| `app/wallet/hd.py` | Generazione della master key, derivazione di indirizzi/chiavi utente (`0/i`), del montepremi di ogni round (`2/<round_id>`, B-80) e dell'indirizzo di riserva (`1/0`), `derive_round_pool_key` che sceglie la chiave che controlla l'indirizzo salvato sul round, export WIF; la chiave d'account decifrata resta in cache nel processo |
| `app/wallet/address.py` | `is_valid_plm_address`: checksum bech32 + HRP `plm` |
| `app/wallet/balance.py` | `recompute_balance` (saldo confermato), `compute_pending_balance` (saldo mostrato) — vedi [registrazione-e-depositi.md](registrazione-e-depositi.md) |
| `app/wallet/psbt_builder.py` | Selezione UTXO, costruzione e firma di scommessa, prelievo e pagamento; limiti `MAX_TX_INPUTS`, `MAX_PAYOUT_TX_INPUTS`, `MAX_PARTICIPANTS_PER_ROUND`, `DUST_LIMIT_SATS`. *Da implementare:* uscita di riserva per l'RBF sul pagamento (B-79) |
### Rete Electrum
| File | Responsabilità |
|---|---|
| `app/electrum/client.py` | `ElectrumClient` (JSON-RPC, timeout per richiesta), `ElectrumEndpoint`, `parse_endpoints`; limite di lettura di 16 MiB per riga, risposta troppo grande o malformata come errore della richiesta e non della connessione. *Da implementare:* pin del certificato per endpoint (B-84) |
| `app/electrum/listener.py` | `ElectrumListener`: l'unica connessione, rotazione, keepalive, validazione header, corroborazione, sottoscrizioni e accredito — vedi [connessione-electrum.md](connessione-electrum.md). Il docstring della classe cita un metodo `add_address` che non esiste: l'indirizzo di un nuovo utente si aggiunge con `address_for_new_user` |
| `app/electrum/scripthash.py` | `address_to_scripthash`: scripthash Electrum di un indirizzo |
### Dominio
| File | Responsabilità |
|---|---|
| `app/deposits/service.py` | Accredito dei depositi, UTXO spesi fuori piattaforma e loro ripristino |
| `app/deposits/reconcile.py` | `DepositReconciler`: ricontrollo periodico di tutti gli indirizzi |
| `app/bets/service.py` | `place_bet`, `BetError`, rilascio di una scommessa fallita |
| `app/bets/confirmation.py` | Gestore di conferma per il tipo `bet` |
| `app/withdrawals/service.py` | `request_withdrawal`, `WithdrawalError`, rilascio di un prelievo fallito |
| `app/withdrawals/confirmation.py` | Gestore di conferma per il tipo `withdrawal` |
| `app/rounds/service.py` | Round attivo, scadenza, accettazione scommesse, `rounds_can_open`, apertura del round, quota del vincitore |
| `app/rounds/scheduler.py` | `RoundScheduler`: chiusura, estrazione, pagamento e suoi tentativi |
| `app/rounds/draw.py` | Matematica degli header (hash, prev-hash, target) e scelta del vincitore. Seme commit-reveal e impronta dei partecipanti |
| `app/rounds/config.py` | `get_round_config`: la riga unica di `round_config`, creata se manca |
| `app/rounds/confirmation.py` | Gestore di conferma per il tipo `payout` |
| `app/rounds/events.py` | `RoundEventBroadcaster` e il singleton `broadcaster` (SSE) |
Flussi descritti in [scommesse-e-prelievi.md](scommesse-e-prelievi.md),
[ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md) e
[registrazione-e-depositi.md](registrazione-e-depositi.md).
### Transazioni
| File | Responsabilità |
|---|---|
| `app/tx/confirmation.py` | `ConfirmationPoller`, `poll_once`, registro dei gestori (`register_handler`) |
| `app/tx/broadcast.py` | `RbfBumper`, `should_bump`, `bump_fee` |
| `app/tx/reconcile.py` | `PendingTransactionReconciler`, `reconcile_once`: promozione o abbandono delle righe `building`/`pending` |
| `app/tx/pending_address.py` | `own_address_for`: indirizzo proprietario degli input di una transazione (utente o pool) |
| `app/tx/locks.py` | `UserLocks`: lock asincrono per utente |
Dettagli in [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md).
### Frontend statici
| File | Responsabilità |
|---|---|
| `app/static/index.html` | Pagina `/` per i giocatori |
| `app/static/app.js` | Logica di `/`: autenticazione, pannelli, polling, SSE, rivelazione del risultato |
| `app/static/style.css` | Stile di `/` (e di `/report-bug`) |
| `app/static/i18n.js` | Tabella `TRANSLATIONS` in 7 lingue, `t()`, `tOrNull()`, `setLanguage()`, `applyStaticTranslations()` |
| `app/static/report-bug.html` | Pagina `/report-bug`, con il proprio script inline |
| `app/static/admin.html` | Pannello `/admin` |
| `app/static/admin.js` | Logica del pannello: token, sezioni, polling dello stato catena, SSE |
| `app/static/admin.css` | Stile del pannello |
| `app/static/guida.html` | Pagina `/guida`, per ora un segnaposto |
### Dipendenze tra pacchetti
Il grafo riporta gli import tra i pacchetti di `app/` (a livello di pacchetto,
non di singolo modulo). `db` e `config` sono importati quasi ovunque e sono
omessi dalle frecce per leggibilità.
```mermaid
flowchart TD
main["main"] --> routes["api.routes"]
main --> auth
main --> tx
main --> rounds
main --> electrum
main --> deposits
main --> bets
main --> withdrawals
routes --> auth
routes --> bets
routes --> withdrawals
routes --> rounds
routes --> wallet
routes --> audit
routes --> apiutil["api (errors, client_ip, timeutil)"]
auth --> apiutil
auth --> wallet
bets --> apiutil
bets --> rounds
bets --> wallet
bets --> audit
bets -- "register_handler" --> tx
withdrawals --> apiutil
withdrawals --> rounds
withdrawals --> wallet
withdrawals --> audit
withdrawals -- "register_handler" --> tx
rounds --> electrum
rounds --> wallet
rounds --> audit
rounds -- "register_handler" --> tx
electrum --> deposits
electrum -- "draw (header math), events" --> rounds
deposits --> electrum
deposits --> wallet
deposits --> audit
deposits -- "events" --> rounds
tx --> wallet
tx --> electrum
tx --> audit
tx -- "events, config" --> rounds
```
- **[ARC-10]** Il poller delle conferme (`app/tx/confirmation.py`) non importa
i moduli di dominio: sono `app/bets/confirmation.py`,
`app/rounds/confirmation.py` e `app/withdrawals/confirmation.py` a
registrarsi con `register_handler(kind, handler)` al momento dell'import,
per i tipi `bet`, `payout` e `withdrawal`.
*Codice:* `app/tx/confirmation.py:register_handler` ·
`app/bets/confirmation.py` · `app/rounds/confirmation.py` ·
`app/withdrawals/confirmation.py` ·
*Test:* `tests/unit/test_confirmation.py`
- **[ARC-11]** Gli errori di dominio destinati all'utente sono sottoclassi di
`ApiError` (`BetError`, `WithdrawalError`) sollevate direttamente dai
servizi, con il codice che il frontend traduce; le route li convertono in
`HTTPException` scegliendo lo stato HTTP. Per questo `bets` e
`withdrawals` dipendono da `app/api/errors.py`.
*Codice:* `app/api/errors.py:ApiError` · `app/bets/service.py:BetError` ·
`app/withdrawals/service.py:WithdrawalError`
## Avvio del processo
`app/main.py` fa due cose distinte: **all'import** costruisce l'applicazione
FastAPI; **all'avvio del server** (il `lifespan`) prepara lo stato condiviso
e lancia le attività in background.
```mermaid
sequenceDiagram
participant U as uvicorn
participant M as app/main.py (import)
participant L as lifespan
U->>M: import app.main
M->>M: setup_logging()
M->>M: import dei gestori di conferma (bet, payout, withdrawal)
M->>M: FastAPI(...), include_router ×8, exception handler, route HTML, mount /
U->>L: startup
L->>L: validate_runtime_secrets()
L->>L: parse_endpoints(...)
L->>L: quorum minimo (validate_quorum_servers)
L->>L: verifica della master key (B-89, da implementare)
L->>L: START_PAUSED (B-90, da implementare)
L->>L: app.state.electrum_listener, app.state.user_locks
L->>L: create_task ×6
Note over L: il server serve richieste<br/>(controllo dei buchi di indici alla prima connessione, B-90)
U->>L: shutdown
L->>L: chiusura dei flussi SSE (B-93, da implementare)
L->>L: cancel() dei 6 task (e attesa della fine, B-93), chiusura del client Electrum
```
Il diagramma mostra il comportamento atteso; i passi marcati «da
implementare» non esistono ancora nel codice (vedi [ARC-60] e [ARC-22]).
### All'import
- **[ARC-12]** `setup_logging()` è chiamata come prima istruzione applicativa
di `app/main.py`, prima di importare qualunque altro modulo `app.*`, così
anche i log emessi durante gli import finiscono nel file.
*Codice:* `app/main.py` · `app/logging_config.py:setup_logging`
- **[ARC-13]** `app/main.py` importa `app.bets.confirmation`,
`app.rounds.confirmation` e `app.withdrawals.confirmation` **solo per il
loro effetto collaterale** (la registrazione del gestore, vedi
[ARC-10]). Questi import non vanno rimossi: senza gestore, il poller
segnerebbe comunque la `PendingTransaction` come `confirmed`, ma senza
aggiornare il partecipante, il round o il prelievo corrispondente.
*Codice:* `app/main.py` · `app/tx/confirmation.py:poll_once`
- **[ARC-14]** La documentazione automatica (`/docs`, `/redoc`,
`/openapi.json`) è disattivata a meno che `ENABLE_API_DOCS` sia vero.
*Codice:* `app/main.py` · *Test:* `tests/unit/test_docs_disabled.py`
- **[ARC-15]** I router vengono inclusi in quest'ordine: `auth`, `users`,
`bets`, `withdrawals`, `admin`, `bug_reports`, `qr`, `rounds`. Gli endpoint
sono in [api.md](api.md).
*Codice:* `app/main.py`
- **[ARC-16]** Qualunque eccezione non gestita produce una risposta 500 con
lo stesso formato degli errori voluti
(`{"detail": {"code": "internal_error", "message": "internal server error", "params": {}}}`);
il dettaglio dell'eccezione va solo nel log, mai nella risposta.
*Codice:* `app/main.py:log_unhandled_exception` ·
*Test:* `tests/unit/test_rounds_route.py`
- **[ARC-17]** `GET /health` risponde `{"status": "ok"}` senza toccare
database né rete: dice solo che il processo risponde (*liveness*). Se il
servizio è davvero in grado di lavorare lo dice `GET /health/ready`
([ARC-61], [api.md](api.md#servizio) (B-92)).
*Codice:* `app/main.py:health`
- **[ARC-18]** Le quattro pagine HTML hanno route esplicite che servono il
file con `Cache-Control: no-store`: `/` → `index.html`, `/admin` →
`admin.html`, `/guida` → `guida.html`, `/report-bug` → `report-bug.html`.
Per ultimo, l'intera cartella `app/static/` è montata su `/` con
`StaticFiles(html=True)`: JS, CSS e ogni altro file vi sono serviti con il
loro nome (`/app.js`, `/i18n.js`, `/admin.css`…), con
`Cache-Control: no-cache` (il browser li riconvalida a ogni caricamento).
I percorsi sono relativi alla directory di lavoro, che nel container è
`/app`.
*Codice:* `app/main.py:index_page` · `app/main.py:admin_panel` ·
`app/main.py:user_guide` · `app/main.py:report_bug_page`
*Stato:* da implementare (B-94) · *Oggi:* `Cache-Control` c'è **solo** sulle
quattro pagine HTML; i file serviti da `StaticFiles` (e `/index.html`
chiesto per nome) non ne hanno, e il browser può usare uno script vecchio
con una pagina nuova.
### Nel lifespan
- **[ARC-19]** Come primo passo, `validate_runtime_secrets()` fa rifiutare
l'avvio (solleva `ConfigError`) se `JWT_SECRET` è più corto di 32
caratteri o la chiave di cifratura della master key è vuota (il file
indicato da `XPRV_ENCRYPTION_KEY_FILE` manca o è vuoto), riportando tutti i
problemi insieme. `ADMIN_TOKEN` vuoto **non** blocca l'avvio: il pannello
resta semplicemente chiuso. Il controllo sta nel lifespan e non in un
validatore di `Settings`, così import e test non hanno bisogno di segreti
veri.
*Codice:* `app/config.py:validate_runtime_secrets` ·
*Test:* `tests/unit/test_config.py`
*Stato:* da implementare (B-91) · *Oggi:* si controlla che la variabile
`XPRV_ENCRYPTION_KEY` non sia vuota.
- **[ARC-20]** Gli endpoint Electrum vengono letti da `ELECTRUM_HOST`,
`ELECTRUM_PORT`, `ELECTRUM_USE_SSL` ed `ELECTRUM_FALLBACK_SERVERS`
(`host:porta[:notls][:pin=<sha256>]` separati da virgola, [ARC-30]); un
elenco di riserva malformato blocca l'avvio. L'ordine di rotazione viene
scritto nel log.
*Codice:* `app/electrum/client.py:parse_endpoints` ·
*Test:* `tests/unit/test_electrum_client.py`
- **[ARC-60]** **Controlli di avvio.** Dopo [ARC-19] e [ARC-20] e prima di
creare i task, il lifespan esegue nell'ordine, e ogni controllo fallito
impedisce di servire:
1. **quorum minimo**: almeno 2 server di riserva, salvo
`ALLOW_NO_QUORUM=true` (solo sviluppo, scritto nel log come
avvertimento) — regola in
[connessione-electrum.md](connessione-electrum.md#5-il-quorum) (B-84);
2. **master key**: la chiave viene decifrata e l'indirizzo di riserva del
montepremi e un campione degli indirizzi utente salvati vengono
ricalcolati e confrontati con il database — regola in
[sicurezza.md](sicurezza.md#regole-di-avvio) (B-89);
3. **avvio in pausa**: con `START_PAUSED=true` la lotteria viene messa in
pausa prima che lo scheduler parta — procedura in
[operativita.md](operativita.md#ripristino) (B-90).
Il controllo dei **buchi negli indici di derivazione** dopo un ripristino
(i 20 indici successivi al più alto assegnato, che non devono avere
cronologia in catena) ha bisogno della rete, quindi non può stare prima
dei task: gira alla prima connessione del listener, e finché non si è
concluso senza trovare cronologia la registrazione è rifiutata
([operativita.md](operativita.md#ripristino), B-90).
*Codice:* `app/main.py:lifespan` · `app/config.py:validate_runtime_secrets` · `app/config.py:validate_quorum_servers` ·
*Test:* `tests/unit/test_electrum_listener.py`
*Stato:* da implementare (B-89, B-90), per i controlli 2 e 3 · *Oggi:* dopo
i segreti, gli endpoint e il quorum il lifespan crea subito i task; la
chiave si decifra alla prima registrazione o al primo pagamento.
- **[ARC-21]** Lo stato condiviso con le route vive su `app.state`:
`electrum_listener` (l'`ElectrumListener`) e `user_locks` (un
`UserLocks`), creati nel lifespan; `auth_rate_limiters` viene invece creato
alla prima richiesta di registrazione o login che ne ha bisogno.
*Codice:* `app/main.py:lifespan` · `app/auth/routes.py:_rate_limiters`
- **[ARC-22]** Il lifespan crea esattamente sei task asyncio, nell'ordine
`ElectrumListener`, `RoundScheduler`, `ConfirmationPoller`, `RbfBumper`,
`PendingTransactionReconciler`, `DepositReconciler`. Allo spegnimento, in
quest'ordine: ogni flusso SSE aperto viene chiuso (altrimenti uvicorn
aspetta le connessioni aperte e Docker lo uccide), ciascun task riceve
`cancel()` e il lifespan **ne attende la fine**, poi il client Electrum, se
presente, viene chiuso. Il compose dà al container `stop_grace_period: 30s`
per completare questa sequenza prima del `SIGKILL`.
*Codice:* `app/main.py:lifespan` · `app/rounds/events.py:RoundEventBroadcaster` · `docker-compose.yml` ·
*Test:* `tests/unit/test_code_comments.py`
*Stato:* da implementare (B-93) · *Oggi:* i task ricevono `cancel()` senza
attesa, i flussi SSE restano aperti, e con uno stream collegato Docker uccide
il container dopo i 10s predefiniti.
## Attività in background
| Task | Costruito con | Cadenza | Ruolo |
|---|---|---|---|
| `ElectrumListener` | `_make_electrum_client`, `AsyncSessionLocal`, endpoint | ciclo di riconnessione; ping ogni 60s | L'unica connessione Electrum: header, sottoscrizioni, accredito depositi |
| `RoundScheduler` | `AsyncSessionLocal`, `listener` | 5s | Apre/chiude i round, estrae, avvia e ritenta i pagamenti |
| `ConfirmationPoller` | `AsyncSessionLocal`, `lambda: listener.client` | 10s | `pending` → `confirmed` e gestore per tipo |
| `RbfBumper` | `AsyncSessionLocal`, `lambda: listener.client` | 30s | Aumenta la commissione di ciò che è `pending` oltre `rbf_timeout_seconds` |
| `PendingTransactionReconciler` | `AsyncSessionLocal`, `lambda: listener.client` | subito, poi 120s | Promuove o abbandona le righe `building`/`pending` |
| `DepositReconciler` | `AsyncSessionLocal`, `listener` | 300s, attende prima del primo giro | `refresh_user` su ogni indirizzo |
- **[ARC-23]** **Accesso al client Electrum.** Nessun task tiene un
riferimento fisso al client: `ConfirmationPoller`, `RbfBumper` e
`PendingTransactionReconciler` ricevono `lambda: listener.client` e lo
rileggono a ogni giro; `RoundScheduler` e `DepositReconciler` ricevono il
listener intero e leggono `listener.client` (il secondo anche per chiamare
`refresh_user`). Così una riconnessione sostituisce il client sotto tutti.
Un client non nullo implica che l'altezza della catena sia già nota (vedi
[connessione-electrum.md](connessione-electrum.md)).
*Codice:* `app/main.py:lifespan`
- **[ARC-24]** **Client assente.** Quando `listener.client` è `None` ogni task
salta il giro e riprova alla cadenza successiva; `DepositReconciler`
interrompe anche una scansione in corso. Le route che devono trasmettere
(`POST /bets`, `POST /withdrawals`) rispondono invece `503`
`network_unavailable`.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick` ·
`app/tx/confirmation.py:ConfirmationPoller.run` ·
`app/tx/broadcast.py:RbfBumper.run` ·
`app/tx/reconcile.py:PendingTransactionReconciler.run` ·
`app/deposits/reconcile.py:DepositReconciler._sweep_once` ·
`app/api/routes/bets.py:create_bet` ·
`app/api/routes/withdrawals.py:create_withdrawal` ·
*Test:* `tests/unit/test_deposit_reconcile.py`
- **[ARC-25]** **Errori.** Ogni ciclo intercetta qualunque `Exception` di un
giro, la scrive nel log con lo stack e riprende alla cadenza successiva;
solo `CancelledError` (lo spegnimento) esce dal ciclo. All'interno di un
giro, poller, bumper, riconciliatore e `DepositReconciler` isolano anche il
singolo elemento: una transazione o un utente che fallisce non ferma gli
altri. Non esiste un supervisore: un task che terminasse non verrebbe
riavviato (l'unico caso previsto è il listener senza alcun endpoint, che
scrive un errore ed esce; `parse_endpoints` include però sempre il server
primario).
*Codice:* `app/rounds/scheduler.py:RoundScheduler.run` ·
`app/tx/confirmation.py:poll_once` · `app/tx/broadcast.py:RbfBumper._tick` ·
`app/tx/reconcile.py:reconcile_once` ·
`app/deposits/reconcile.py:DepositReconciler.run` ·
`app/electrum/listener.py:ElectrumListener.run` ·
*Test:* `tests/unit/test_confirmation.py` · `tests/unit/test_reconcile.py` ·
`tests/unit/test_deposit_reconcile.py`
- **[ARC-26]** **`ElectrumListener`.** Dopo ogni sessione terminata passa
subito al server successivo; l'attesa crescente (1s raddoppiando fino a 30s)
scatta solo quando tutti i server hanno fallito nello stesso giro.
Rotazione, keepalive, validazione e corroborazione sono in
[connessione-electrum.md](connessione-electrum.md). Tre cambiamenti di
struttura sono attesi dal piano, con le regole in quel documento:
- il listener conserva gli ultimi 10 header ricevuti; un salto di più
blocchi scarica e valida gli header intermedi, e un header che si
concatena a uno di quelli conservati ma non alla punta è una
riorganizzazione da seguire, non la fine della sessione;
- una sessione connessa la cui punta non avanza da 360s, mentre un altro
server ne riporta una più alta, viene chiusa e si passa al server
successivo (B-86);
- il client legge righe fino a 16 MiB, e una risposta oltre il limite o
malformata fa fallire la sola richiesta, non la connessione (B-75).
*Codice:* `app/electrum/listener.py:ElectrumListener.run` ·
`app/electrum/listener.py:ElectrumListener._apply_header` ·
`app/electrum/listener.py:ElectrumListener._check_not_stalled` ·
`app/electrum/client.py:ElectrumClient.connect` ·
*Test:* `tests/unit/test_electrum_listener.py`, `tests/unit/test_electrum_client.py`
- **[ARC-27]** **`RoundScheduler`.** A ogni giro (5s) chiama
`open_new_round_if_needed` e poi avanza il round attivo, in qualunque stato
sia, `drawing` compreso: per un round in `drawing` il giro rientra
nell'attesa del blocco di estrazione a partire da ciò che è salvato sulla
riga del round (`draw_height`, `participants_hash`, posizioni dei
partecipanti), in modo idempotente. L'attesa **resta dentro il giro**:
finché dura, lo scheduler non fa altro, il che è corretto perché nessun
altro round può aprirsi finché questo non è `closed`. Un'eccezione durante
l'attesa termina il giro ([ARC-25]) e il giro successivo riparte dallo stato
salvato, con lo stesso esito; lo stesso vale dopo un riavvio. Logica del
round in [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#3--estrazione).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick` ·
`app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
`app/rounds/scheduler.py:RoundScheduler._wait_for_draw_block` ·
*Test:* `tests/unit/test_scheduler.py`
*Stato:* da implementare (B-81) · *Oggi:* `_tick` salta i round in
`drawing`; `tip_at_close` e i partecipanti vivono solo nella chiamata a
`_close_and_draw`, quindi un'eccezione o un riavvio lasciano il round in
`drawing` per sempre
([LIM-01](limiti-noti.md#robustezza-del-ciclo-di-vita)).
- **[ARC-28]** **`ConfirmationPoller`** (10s), **`RbfBumper`** (30s) e
**`PendingTransactionReconciler`** (al primo giro subito, poi ogni 120s)
lavorano sulla tabella `pending_transactions` (e sulla tabella
di tutti i txid di ogni riga, `pending_transaction_txids`); il riconciliatore parte subito perché
un crash durante un invio lascia proprio una riga `building` da risolvere
al riavvio. Regole in
[transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md).
*Codice:* `app/tx/confirmation.py:ConfirmationPoller` ·
`app/tx/broadcast.py:RbfBumper` ·
`app/tx/reconcile.py:PendingTransactionReconciler` ·
*Test:* `tests/unit/test_confirmation.py` · `tests/unit/test_broadcast.py` ·
`tests/unit/test_reconcile.py`
- **[ARC-29]** **`DepositReconciler`** attende 300s, poi scorre tutti gli
utenti e chiama `listener.refresh_user` su ciascuno: lo stesso codice usato
dalle notifiche, così i due percorsi non possono divergere.
*Codice:* `app/deposits/reconcile.py:DepositReconciler._sweep_once` ·
*Test:* `tests/unit/test_deposit_reconcile.py`
## Configurazione
La configurazione è divisa in due posti con regole diverse.
- **[ARC-30]** **Segreti e collegamenti infrastrutturali** stanno nelle
variabili d'ambiente (file `.env`, letto da `Settings`; variabili sconosciute
ignorate). `settings` è costruito una volta all'import di `app/config.py`:
una modifica richiede il riavvio del container. I campi sono:
| Campo (`Settings`) | Variabile | Predefinito | Uso |
|---|---|---|---|
| `database_url` | `DATABASE_URL` | `sqlite+aiosqlite:///./plm_lottery.db` | URL SQLAlchemy (in Docker sovrascritto dal compose) |
| `electrum_host` | `ELECTRUM_HOST` | `santantonio.sytes.net` | Server Electrum primario |
| `electrum_port` | `ELECTRUM_PORT` | `50002` | Porta del primario |
| `electrum_use_ssl` | `ELECTRUM_USE_SSL` | `True` | TLS verso il primario |
| `electrum_fallback_servers` | `ELECTRUM_FALLBACK_SERVERS` | `""` | Riserve, `host:porta[:notls][:pin=<sha256>]` separati da virgola; almeno 2 ([ARC-60]) |
| `electrum_cert_pin` | `ELECTRUM_CERT_PIN` | `""` | SHA-256 del certificato DER del primario; vuoto = non fissato ([connessione-electrum.md](connessione-electrum.md) ELC-03) |
| `allow_no_quorum` | `ALLOW_NO_QUORUM` | `False` | Permette di partire con meno di 2 server di riserva; solo sviluppo ([ARC-60]) |
| `xprv_encryption_key_file` | `XPRV_ENCRYPTION_KEY_FILE` | `/run/secrets/xprv_encryption_key` | File con la chiave Fernet della master xprv (obbligatorio, [ARC-19]); sostituisce `XPRV_ENCRYPTION_KEY` |
| `start_paused` | `START_PAUSED` | `False` | Avvia con la lotteria in pausa, dopo un ripristino ([ARC-60]) |
| `master_key_path` | `MASTER_KEY_PATH` | `./master.xprv.enc` | File della master xprv cifrata (in Docker sovrascritto dal compose) |
| `jwt_secret` | `JWT_SECRET` | `""` | Chiave HS256 dei token (≥ 32 caratteri, [ARC-19]) |
| `jwt_algorithm` | `JWT_ALGORITHM` | `HS256` | Algoritmo JWT |
| `jwt_expire_minutes` | `JWT_EXPIRE_MINUTES` | `1440` (24h) | Durata del token |
| `admin_token` | `ADMIN_TOKEN` | `""` | Token del pannello `/admin`; vuoto = pannello chiuso |
| `enable_api_docs` | `ENABLE_API_DOCS` | `False` | Espone Swagger/ReDoc/OpenAPI ([ARC-14]) |
*Codice:* `app/config.py:Settings` · *Test:* `tests/unit/test_config.py`
*Stato:* da implementare (B-90, B-91) · *Oggi:* `START_PAUSED` e
`XPRV_ENCRYPTION_KEY_FILE` non esistono, la chiave Fernet è la variabile
`XPRV_ENCRYPTION_KEY`.
- **[ARC-31]** **Parametri operativi e di business** (costo della scommessa,
durata e pausa del round, animazione, commissione di rete, timeout RBF,
indirizzo commissioni, pausa di manutenzione e suo motivo, conferme dei
depositi `deposit_confirmations`, conferme del blocco di estrazione
`draw_confirmations`, tetto al montepremi `max_round_pool_sats`) stanno
nell'unica riga della tabella `round_config`, modificabile a caldo da
`/admin` senza riavvio. I valori iniziali sono i default delle colonne di
`RoundConfig`, non `app/config.py`. Se la riga manca, viene creata al primo
accesso con `fee_address` vuoto. Campi in [modello-dati.md](modello-dati.md),
effetti in [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md).
*Codice:* `app/rounds/config.py:get_round_config` ·
`app/db/models.py:RoundConfig`
*Stato:* da implementare (B-82, B-95) · *Oggi:* `deposit_confirmations` e
`max_round_pool_sats` non esistono.
- **[ARC-32]** Alcuni valori sono costanti nel codice e non configurabili:
la ripartizione 70/30, le conferme richieste per le transazioni della
piattaforma (1) e per le uscite coinbase (120), i limiti di input e di
partecipanti, le cadenze dei task. Si cambiano solo con una modifica al
codice (vedi [limiti-noti.md](limiti-noti.md)). Le conferme
dei depositi sono invece configurabili ([ARC-31]).
*Codice:* `app/rounds/service.py:winner_share` ·
`app/wallet/psbt_builder.py` · `app/tx/confirmation.py`
*Stato:* da implementare (B-82) · *Oggi:* 1 conferma per ogni moneta e
transazione, depositi e coinbase compresi.
## Aggiornamenti in tempo reale (SSE)
Le pagine si aggiornano da sole in due modi sovrapposti: il polling
periodico e, in più, un canale **Server-Sent Events** che le avvisa appena
qualcosa cambia.
```mermaid
flowchart LR
subgraph Processo
P1["round aperto / cambio di stato"] --> BR
P2["scommessa o prelievo inviato / annullato"] --> BR
P3["transazione confermata / abbandonata"] --> BR
P4["deposito accreditato / UTXO spesa o ripristinata"] --> BR
P5["nuovo header"] --> BR
BR["broadcaster.publish()"] --> Q1["coda client 1<br/>(maxsize 1)"]
BR --> Q2["coda client N"]
end
Q1 -- "event: update" --> S1["EventSource /"]
Q2 -- "event: update" --> S2["EventSource /admin"]
S1 -. "rifà le GET REST" .-> API["/rounds/current, /users/me, …"]
```
- **[ARC-33]** Il canale è pub/sub **in-process**: `broadcaster` è un unico
`RoundEventBroadcaster` per processo, con una `asyncio.Queue(maxsize=1)`
per client. `publish()` mette una notifica in ogni coda non piena; se la
coda è già piena la nuova notifica viene scartata, perché quella in attesa
basta già a far ricaricare tutto (notifiche ridondanti si fondono).
*Codice:* `app/rounds/events.py:RoundEventBroadcaster` ·
*Test:* `tests/unit/test_round_events.py`
- **[ARC-34]** Il messaggio non ha contenuto e lo stream non ha
autenticazione: è solo un segnale "è cambiato qualcosa, ricarica". Ogni
dato, compresa la personalizzazione (come `user_played`), arriva dagli
endpoint REST autenticati. Il segnale è globale: ogni client viene avvisato
di ogni evento, anche di quelli che non lo riguardano.
*Codice:* `app/api/routes/rounds.py:round_stream`
- **[ARC-35]** Limiti di sottoscrizione: al massimo `MAX_SUBSCRIBERS` (500)
stream in tutto, oltre i quali `GET /rounds/stream` risponde `503` e il
browser ricade sul polling; e al massimo `MAX_SUBSCRIBERS_PER_IP` (5) per
IP client, oltre i quali la connessione **più vecchia** di quello stesso IP
viene chiusa (le si invia il segnale `EVICTED`) invece di rifiutare la
nuova. L'IP è quello di `client_ip` (vedi [sicurezza.md](sicurezza.md)).
*Codice:* `app/rounds/events.py:RoundEventBroadcaster.subscribe` ·
`app/api/routes/rounds.py:round_stream` ·
*Test:* `tests/unit/test_round_events.py`
- **[ARC-36]** Lo stream invia `event: update` con `data: {}` per ogni
notifica. Da fermo controlla `request.is_disconnected()` ogni 5 secondi e
invia un commento `: keep-alive` ogni 20 secondi (4 controlli), così né un
client sparito senza chiudere né il timeout di inattività di un proxy lo
lasciano appeso. La risposta porta `Cache-Control: no-store` e
`X-Accel-Buffering: no`. Alla chiusura il client viene sempre rimosso.
*Codice:* `app/api/routes/rounds.py:round_stream`
- **[ARC-37]** `publish()` viene chiamato in questi punti, e ogni nuovo
cambiamento di stato visibile deve aggiungersi a questo elenco:
- apertura di un round — `app/rounds/service.py:open_new_round_if_needed`;
- ogni transizione di stato del round (`closing`, `closed` senza
partecipanti, `drawing`, `paying_out`) —
`app/rounds/scheduler.py:RoundScheduler._tick`,
`app/rounds/scheduler.py:RoundScheduler._close_and_draw`;
- scommessa inviata e scommessa annullata —
`app/bets/service.py:place_bet`, `app/bets/service.py:_release_failed_bet`;
- prelievo inviato e prelievo annullato —
`app/withdrawals/service.py:request_withdrawal`,
`app/withdrawals/service.py:_release_failed_withdrawal`;
- transazione confermata — `app/tx/confirmation.py:poll_once`;
- riga promossa o abbandonata dal riconciliatore —
`app/tx/reconcile.py:reconcile_once`. Oggi il riconciliatore pubblica per
**ogni** riga che ricontrolla, anche quando non cambia nulla; la
pubblicazione solo sui cambiamenti è in B-96;
- deposito accreditato, UTXO segnata come spesa fuori piattaforma, UTXO
ripristinata — `app/deposits/service.py:credit_confirmed_utxos`,
`app/deposits/service.py:mark_utxos_spent_externally`,
`app/deposits/service.py:reinstate_reappeared_utxos`;
- nuovo header ricevuto — `app/electrum/listener.py:ElectrumListener._consume_headers`.
*Test:* `tests/unit/test_bets.py` (verifica la notifica di una scommessa)
*Stato:* da implementare (B-96) · *Oggi:* il riconciliatore pubblica una
notifica per ogni riga ricontrollata, anche senza cambiamenti.
## Lock per utente
- **[ARC-38]** `UserLocks` tiene un `asyncio.Lock` per `user_id` (creato alla
prima richiesta di quell'utente e mai rimosso). `POST /bets` e
`POST /withdrawals` eseguono l'intera costruzione e trasmissione dentro
`app.state.user_locks.acquire(user.id)`: per lo stesso utente una scommessa
e un prelievo non sono mai in costruzione insieme, perché spendono dallo
stesso insieme di UTXO. È l'unica esclusione reciproca tra i due flussi;
cosa implica è in [scommesse-e-prelievi.md](scommesse-e-prelievi.md). Il
controllo "client connesso" avviene prima di acquisire il lock.
*Codice:* `app/tx/locks.py:UserLocks.acquire` ·
`app/api/routes/bets.py:create_bet` ·
`app/api/routes/withdrawals.py:create_withdrawal`
## Frontend
- **[ARC-39]** Le interfacce sono pagine statiche in `app/static/`, servite
direttamente da FastAPI ([ARC-18]): HTML, JavaScript e CSS scritti a mano,
senza passo di build, framework né bundler. Parlano tutte con la stessa API
JSON; l'unica separazione tra utente e amministratore è `require_admin` sul
lato server.
*Codice:* `app/main.py` · `app/static/`
### `/` — giocatori
- **[ARC-40]** **Polling.** Da non autenticati, la pagina interroga
`GET /rounds/current` ogni 15s solo per la barra di stato della catena. Da
autenticati: `refreshRound` ogni 15s, ogni 3s mentre il round è in
`closing`/`drawing`/`paying_out`; `checkLastRoundResult`
(`GET /users/me/last-round-result`) ogni 20s; il conto alla rovescia
locale ogni secondo. Quando la scheda torna visibile i dati si ricaricano
subito (i timer delle schede in background vengono rallentati dal
browser).
*Codice:* `app/static/app.js:startChainOnlyPolling` ·
`app/static/app.js:scheduleNextRoundPoll` ·
`app/static/app.js:showDashboard`
- **[ARC-41]** **Richieste.** Ogni chiamata API di `/` ha un timeout di 15s;
dopo 2 fallimenti consecutivi del polling la pagina mostra "connessione
persa". Una risposta `401` con codice `session_expired` riporta al login.
*Codice:* `app/static/app.js:call` · `app/static/app.js:noteFetchOutcome`
- **[ARC-42]** **SSE.** La pagina apre un solo `EventSource('/rounds/stream')`
e reagisce sia agli eventi `update` sia a `open` (che scatta alla prima
connessione e a ogni riconnessione automatica): da autenticati ricarica
round, profilo e ultimo risultato, altrimenti solo lo stato della catena.
Il polling resta attivo comunque: se lo stream cade o è bloccato la pagina
funziona come prima, solo senza l'avviso immediato.
*Codice:* `app/static/app.js:connectRoundEvents` ·
`app/static/app.js:onRoundServerEvent`
- **[ARC-43]** **Chiavi di `localStorage`** usate da `/`:
| Chiave | Contenuto |
|---|---|
| `plm_token` | JWT della sessione |
| `plm_username` | Nome utente mostrato |
| `plm_address` | Indirizzo di deposito |
| `plm_persisted_result` | Risultato del round rivelato (`round_id`, `won`, `amount_sats`), per ridisegnarlo dopo un ricaricamento |
| `plm_lang` | Lingua scelta (condivisa con `/report-bug`) |
Il logout svuota `localStorage` tranne `plm_lang`. La rimozione di
`plm_token` in una scheda riporta al login anche le altre schede aperte
(evento `storage`). La logica della rivelazione del risultato è in
[ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md).
*Codice:* `app/static/app.js:logout` · `app/static/app.js:persistResult` ·
`app/static/i18n.js:setLanguage`
### `/admin` — operatore
- **[ARC-44]** Il pannello chiede il token operatore, lo verifica con
`GET /admin/config` e lo conserva in `sessionStorage` (`plm_admin_token`,
quindi si perde chiudendo la scheda); ogni chiamata lo invia
nell'intestazione `X-Admin-Token`. Non è collegato da `/` né lo collega.
*Codice:* `app/static/admin.js:callAdmin`
- **[ARC-45]** Il pannello interroga `GET /rounds/current` ogni 15s per la
barra di stato (stato del round e altezza della catena). Le sezioni Utenti,
Round, Transazioni pendenti, Audit log e Bug report si caricano quando le
si apre e si ricaricano a ogni evento SSE (`update` o `open`) mentre sono
aperte; non hanno un polling periodico proprio, quindi se il canale SSE è
bloccato o caduto si aggiornano **solo** riaprendo la sezione. La sezione
Parametri non viene ricaricata dagli eventi. Il piano aggiunge al pannello
lo stato della connessione Electrum (endpoint, età dell'ultimo header) e i
filtri dell'audit log (B-86, B-92).
*Codice:* `app/static/admin.js:startChainStatusPolling` ·
`app/static/admin.js:connectAdminEvents` ·
`app/static/admin.js:onAdminServerEvent`
*Stato:* da implementare (B-86, B-92), solo per lo stato Electrum e i
filtri dell'audit · *Oggi:* il pannello mostra solo l'altezza della catena,
e l'audit log le ultime righe senza filtri.
### `/report-bug` e `/guida`
- **[ARC-46]** `/report-bug` è una pagina autonoma, raggiungibile con o senza
login: se in `localStorage` c'è `plm_token` lo usa per allegare l'autore e
per mostrare i propri report (`GET /bug-reports/mine`). Non usa SSE né
polling. Il flusso di triage è descritto in [api.md](api.md) e in
[guida-admin.md](guida-admin.md).
*Codice:* `app/static/report-bug.html`
- **[ARC-47]** `/guida` è un segnaposto statico in italiano ("la guida
completa sarà pubblicata qui a breve").
*Codice:* `app/static/guida.html`
## Internazionalizzazione
Riguarda `/` e `/report-bug`. `/admin` e `/guida` sono volutamente solo in
italiano.
- **[ARC-48]** Le lingue supportate sono sette: `en`, `it`, `es`, `fr`, `de`,
`ru`, `zh`. Tutte le stringhe stanno in un'unica tabella `TRANSLATIONS` in
`app/static/i18n.js`, caricato prima dello script della pagina; non ci sono
file separati né richieste di rete.
*Codice:* `app/static/i18n.js`
- **[ARC-49]** La lingua iniziale è, nell'ordine: il valore di
`localStorage.plm_lang` se supportato, le prime due lettere di
`navigator.language` se supportate, altrimenti `en`. `setLanguage` salva la
scelta in `plm_lang`, ritraduce la pagina e chiama `onLanguageChange` se la
pagina la definisce. Su `/` il selettore sta nella barra di stato della
catena, non nella barra di navigazione, perché quest'ultima è nascosta fino
al login.
*Codice:* `app/static/i18n.js:detectDefaultLang` ·
`app/static/i18n.js:setLanguage` · `app/static/index.html`
- **[ARC-50]** Il markup statico si traduce con attributi: `data-i18n`
(testo), `data-i18n-html`, `data-i18n-placeholder`, `data-i18n-title`,
`data-i18n-aria-label`, `data-i18n-alt`, applicati da
`applyStaticTranslations` al caricamento e a ogni cambio di lingua. Ciò che
nasce da dati del server usa `t(chiave, parametri)` e viene ridisegnato da
`onLanguageChange`. Un elemento usa **uno solo** dei due meccanismi, mai
entrambi (per esempio `#bet-btn` non ha `data-i18n`, perché la sua
etichetta contiene il costo configurabile).
*Codice:* `app/static/i18n.js:applyStaticTranslations` ·
`app/static/app.js:onLanguageChange` ·
`app/static/app.js:renderBetButton`
- **[ARC-51]** Ogni lingua ha **esattamente lo stesso insieme di chiavi**.
`t()` cerca la chiave nella lingua corrente, poi in `en`, e se manca anche
lì restituisce la chiave stessa; `tOrNull()` restituisce invece `null`,
così il chiamante può usare un testo di riserva. I parametri si
sostituiscono nei segnaposto `{nome}`.
*Codice:* `app/static/i18n.js:t` · `app/static/i18n.js:tOrNull`
- **[ARC-52]** L'API risponde in una sola lingua (inglese) con un `detail`
strutturato `{code, message, params}` (vedi [api.md](api.md)); la
traduzione spetta al client. Per un `detail` oggetto il frontend mostra
`error.<code>` nella lingua corrente, con i parametri; a ogni parametro
`*_sats` numerico affianca un `*_plm` già formattato; se il codice non ha
traduzione mostra `message`. Un `detail` stringa viene mostrato così com'è;
un `detail` lista (errore di validazione 422 di FastAPI) diventa
`error.invalid_request`. Aggiungere un errore rivolto all'utente significa
dargli un codice e aggiungere `error.<codice>` in tutte e sette le lingue.
*Codice:* `app/static/app.js:apiErrorMessage` ·
`app/static/app.js:errorParams` · `app/api/errors.py:ApiError`
- **[ARC-53]** Su `/report-bug` l'avviso `bugReport.englishNotice` è tradotto
in tutte le lingue, ma dice sempre di scrivere la segnalazione in inglese,
perché il pannello di triage non è tradotto.
*Codice:* `app/static/report-bug.html` · `app/static/i18n.js`
## Test
- **[ARC-54]** La suite è tutta in `tests/unit/` (351 test raccolti);
`tests/integration/` contiene solo `__init__.py`. Si esegue con
`python -m pytest` dal venv. `pyproject.toml` imposta `testpaths = ["tests"]`
e `asyncio_mode = "auto"`, quindi i test asincroni non richiedono
`@pytest.mark.asyncio`. Dipendenze di sviluppo: `pytest`, `pytest-asyncio`,
`httpx`.
*Codice:* `pyproject.toml` · *Test:* `tests/unit/test_docs_current.py`
- **[ARC-55]** Non esiste un `conftest.py`: ogni file definisce le proprie
fixture. Lo schema tipico di una fixture `session_factory` è: master key
generata in una directory temporanea con una chiave Fernet casuale (e
cache `hd._account_key` azzerata), engine SQLite in memoria con
`Base.metadata.create_all` (le migrazioni Alembic non vengono eseguite),
una riga `RoundConfig` con un `fee_address` valido dove serve aprire round.
I test HTTP costruiscono un'app FastAPI minima con i soli router
necessari, un `ElectrumListener` senza connessione su `app.state`, e la
interrogano con `httpx.AsyncClient` su `ASGITransport`: il `lifespan` di
`app/main.py` non viene eseguito.
*Test:* `tests/unit/test_bets.py` · `tests/unit/test_rounds_route.py`
- **[ARC-56]** La rete non viene mai contattata: al posto del client e del
listener Electrum ogni file usa classi finte locali, ad esempio
`FakeElectrumClient` (`test_bets.py`, `test_withdrawals.py`,
`test_balance.py`), `RejectingElectrumClient` (`test_bets.py`),
`FakeClient` e `ExplodingClient` (`test_confirmation.py`), `FakeClient`
(`test_broadcast.py`), `UnknownTxClient`, `KnownTxClient`, `BrokenClient`
(`test_reconcile.py`), `FakeListener`, `FakePayoutClient`,
`FakePayoutListener`, `CorroboratingListener`, `LateTipListener`,
`StallingListener` (`test_scheduler.py`), `FakeListener`
(`test_deposit_reconcile.py`), `FakeWriter` (`test_electrum_client.py`).
*Test:* i file citati
- **[ARC-57]** Alcuni test verificano file che non sono codice Python,
perché nessun altro test li eserciterebbe:
- `test_docs_current.py`: il numero di test dichiarato in `CLAUDE.md` e
`README.md` coincide con quello raccolto; `CLAUDE.md` non contiene
affermazioni superate note; la mappa del codice di `CLAUDE.md` cita
`rate_limit.py`, `client_ip.py` e `bug_reports`; i link relativi del
README e le ancore verso `CLAUDE.md` esistono;
- `test_docs_no_bare_uvicorn.py`: README e `docs/running-the-server.md`
non documentano un `uvicorn --reload` fuori da Docker;
- `test_code_comments.py`: alcuni commenti nel codice restano veri (per
esempio il numero di task avviati dal lifespan, sei, citato in
`app/db/base.py`);
- `test_caddyfile_security_headers.py`: il `Caddyfile` mantiene le
intestazioni di sicurezza e la sovrascrittura di `X-Forwarded-For`;
- `test_withdrawals.py::test_the_docs_no_longer_claim_bets_and_withdrawals_are_exclusive`:
[scommesse-e-prelievi.md](scommesse-e-prelievi.md) descrive correttamente
la convivenza di scommessa e prelievo.
Chi modifica questi file (compresi i documenti in `docs/`) deve tenerne
conto.
*Test:* `tests/unit/test_docs_current.py` ·
`tests/unit/test_docs_no_bare_uvicorn.py` ·
`tests/unit/test_code_comments.py` ·
`tests/unit/test_caddyfile_security_headers.py` ·
`tests/unit/test_withdrawals.py`
- **[ARC-58]** Ciò che la suite **non** copre oggi: nessun test contro una
connessione Electrum reale né contro guasti di rete realistici (ritardi,
cadute a metà richiesta, risposte enormi, catene divergenti); il `lifespan`
e l'avvio dei sei task; la route SSE `round_stream` (è testato solo il
broadcaster); `UserLocks` e la sua acquisizione nelle route di scommessa e
prelievo; il codice JavaScript dei frontend; la parità delle chiavi tra le
lingue di `i18n.js`; le migrazioni Alembic su dati esistenti (la catena è eseguita solo su un database vuoto, [ARC-62]; lo schema degli
altri test nasce da `Base.metadata.create_all`). Le verifiche dal vivo sono state manuali
(`scripts/electrum_smoke_test.py` e transazioni reali su mainnet; prelievo e
RBF mai trasmessi dal vivo, vedi [limiti-noti.md](limiti-noti.md)).
La revisione del 2026-09-28 ha osservato che nessuna delle sue falle
critiche sarebbe stata trovata da questa suite, che simula tutto: da qui
[ARC-62], [ARC-63] e [ARC-64].
- **[ARC-62]** **Test delle migrazioni.** Un test esegue `alembic upgrade head`
su un database vuoto e verifica che esistano gli indici su espressione
`ix_rounds_single_active` e `ix_users_username_lower`, che l'autogenerate
non vede e che `batch_alter_table` su SQLite elimina ricostruendo la
tabella con un solo avviso. Ogni migrazione batch su `rounds` o `users` li
ricrea esplicitamente.
*Codice:* `migrations/env.py` · `migrations/versions/` ·
*Test:* `tests/unit/test_migrations.py`
- **[ARC-63]** **Test di parità delle traduzioni.** Un test legge
`TRANSLATIONS` da `app/static/i18n.js` e fallisce se una delle sette lingue
ha un insieme di chiavi diverso da quello di `en` ([ARC-51]).
*Codice:* `app/static/i18n.js` ·
*Test:* —
*Stato:* da implementare (senza B-nn: chiude
[LIM-21](limiti-noti.md#prodotto-e-interfacce)) · *Oggi:* la parità è
verificata solo a mano.
- **[ARC-64]** **Strato di test di guasto e di integrazione**, in
`tests/integration/`, separato dalla suite unitaria: server Electrum
simulati a livello di socket che rispondono in ritardo, chiudono la
connessione dopo aver ricevuto un invio, mandano risposte oltre 16 MiB,
header a difficoltà minima o catene che si biforcano; più il database SQLite
su file con scrittori concorrenti. Non sostituisce la prova con denaro vero
e guasti provocati di
[operativita.md](operativita.md#prova-su-rete-reale), che resta obbligatoria
prima dell'apertura al pubblico.
*Codice:* `tests/integration/__init__.py` ·
*Test:* —
*Stato:* da implementare (fase 7 del
[piano](piano-correzioni.md#fase-7--prova-su-rete-reale)) · *Oggi:*
`tests/integration/` contiene solo `__init__.py`.
## Assunzioni di processo singolo
- **[ARC-59]** Diversi componenti tengono stato nella memoria del processo e
funzionano correttamente solo con un unico processo uvicorn ([ARC-02]):
- il canale SSE (`broadcaster`): un evento pubblicato in un processo non
raggiungerebbe i client collegati a un altro;
- i lock per utente (`UserLocks`): due processi potrebbero costruire
insieme una scommessa e un prelievo dello stesso utente;
- i limitatori di login e registrazione (`AuthRateLimiters` su
`app.state`): ogni processo conterebbe separatamente;
- l'`ElectrumListener` e i sei task: ogni processo aprirebbe la propria
connessione e il proprio scheduler, con due scheduler che avanzano lo
stesso round;
- le cache locali (chiave d'account decifrata in `app/wallet/hd.py`, QR
memorizzati in `app/api/routes/qr.py`), che sarebbero solo duplicate.
Un deployment multi-processo richiederebbe un canale condiviso (per
esempio Redis pub/sub) e un lock su database o Redis. Fa eccezione
l'invariante "al massimo un round attivo", garantita da un indice del
database e quindi valida anche con più processi (vedi
[modello-dati.md](modello-dati.md)). La scelta è discussa in
[limiti-noti.md](limiti-noti.md).
*Codice:* `app/rounds/events.py:RoundEventBroadcaster` ·
`app/tx/locks.py:UserLocks` · `app/auth/rate_limit.py:AuthRateLimiters` ·
`app/main.py:lifespan`
+725
View File
@@ -0,0 +1,725 @@
# 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]** Alcuni eventi sono **solo osservativi**: non accompagnano un
cambiamento di stato del database e vengono salvati in una transazione
propria, aperta apposta. Sono `draw_baseline_tip_unknown`,
`draw_header_corroboration_failed`, `draw_stalled`, `payout_failed`,
`rbf_bump_failed` ([AUD-40]), `restore_gap_detected` ([AUD-43]),
`closing_stalled` ([AUD-46]) e `chain_reorg_detected` di profondità 1
([AUD-38]; con profondità ≥ 2 accompagna la pausa e ne condivide la
transazione). 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_draw_block`,
`app/rounds/scheduler.py:RoundScheduler._close_and_draw`,
`app/rounds/scheduler.py:RoundScheduler._log_payout_failure`,
`app/tx/broadcast.py:RbfBumper._tick`, `app/main.py:lifespan`,
`app/rounds/scheduler.py:RoundScheduler._tick`,
`app/electrum/listener.py:ElectrumListener._record_reorg`
*Stato:* da implementare (B-87, B-90, B-96), per tre degli eventi
nuovi · *Oggi:* gli eventi osservativi sono solo i primi quattro e
`chain_reorg_detected`.
- **[AUD-04]** Il `payload` è un dizionario serializzato in JSON nella colonna
`payload_json`. `created_at` è impostato dall'applicazione, non dal
database: è il default ORM `utcnow` della colonna (`datetime.now(timezone.utc)`,
valutato quando la riga viene inserita), senza alcun `server_default`; una
riga inserita a mano nel database senza `created_at` è quindi rifiutata
(colonna non nulla). `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:utcnow`,
`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. I tipi aggiunti dalle correzioni
in corso ([AUD-37] … [AUD-46]) lo rispettano: il più lungo,
`participant_reorged_out`, ha 23 caratteri.
*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), al massimo `limit`
per richiesta (predefinito 200, minimo 1, massimo 500), filtrabili per tipo
di evento, `round_id`, `user_id` e intervallo di `created_at`, e a pagine
(`before_id`), così che ogni riga del registro sia raggiungibile dall'API.
Ogni elemento contiene `id`, `event_type`, `payload` (già decodificato da
JSON), `user_id`, `round_id` e `created_at` in ISO 8601 UTC. Parametri,
combinazione dei filtri ed errori sono definiti in
[api.md](api.md#get-adminaudit-log) (API-37), che ne è il proprietario.
*Codice:* `app/api/routes/admin.py:list_audit_log` ·
*Test:* `tests/unit/test_admin.py`
*Stato:* da implementare (B-92), per filtri e paginazione · *Oggi:* accetta
solo `limit`; le righe più vecchie delle ultime 500 si leggono solo
direttamente dal database.
- **[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]** Le logiche del programma che rileggono il registro sono
esattamente queste, e nessun'altra decisione dipende da esso:
- `_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;
- l'RBF cerca, prima di scrivere `rbf_bump_failed`, una riga dello stesso
tipo per la stessa transazione con lo stesso txid corrente e lo stesso
motivo; se esiste non ne scrive un'altra ([AUD-40]);
- lo scheduler usa la riga `closing_stalled` più recente del round come
orologio delle ripetizioni ([AUD-46]);
- lo scheduler scrive `draw_baseline_tip_unknown` solo se il round non ne
ha già una ([AUD-25]).
Leggere il registro, invece di tenere lo stato in memoria, fa sì che un
riavvio non ripeta né anticipi queste righe.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._retry_payout_if_due`,
`app/tx/broadcast.py:RbfBumper._tick`,
`app/rounds/scheduler.py:RoundScheduler._tick`,
`app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
*Test:* `tests/unit/test_scheduler.py` (solo `payout_failed`)
*Stato:* da implementare (B-87, B-96), per le ultime due letture ·
*Oggi:* le letture sono quelle di `payout_failed` e di
`draw_baseline_tip_unknown`.
## 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. Nel diagramma, gli eventi marcati con * sono da
implementare.
```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 Account["Account"]
user_registered["user_registered *"]
password_changed["password_changed *"]
restore_gap_detected["restore_gap_detected *"]
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
closing_stalled["closing_stalled *"]
draw_committed["draw_committed *"]
winner_drawn
draw_baseline_tip_unknown
draw_header_corroboration_failed
draw_stalled
participant_reorged_out["participant_reorged_out *"]
payout_blocked["payout_blocked *"]
payout_failed
payout_sent
end
subgraph Ricon["Riconciliazione"]
pending_tx_recovered
pending_tx_abandoned
pending_tx_resurrected["pending_tx_resurrected *"]
rbf_bump_failed["rbf_bump_failed *"]
end
subgraph Catena["Catena"]
chain_reorg_detected["chain_reorg_detected *"]
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`, `deposit_confirmations`,
`draw_confirmations`, `max_round_pool_sats`). 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`
*Stato:* da implementare (B-82, B-95), per gli ultimi due campi ·
*Oggi:* i campi sono i primi otto.
- **[AUD-11]** `lottery_paused` — la lotteria è stata messa in pausa, da
chiunque. Payload `{"reason"}`, più `"note"` quando l'operatore l'ha
indicata nel corpo di `POST /admin/pause`
([api.md](api.md#post-adminpause-e-post-adminresume), API-32). `reason` è
la causa di **questa** pausa, con uno di questi valori, gli stessi di
`paused_reason` ([modello-dati.md](modello-dati.md), DAT-69):
| `reason` | Chi scrive la riga | Evento che la accompagna, nella stessa transazione |
|---|---|---|
| `operator` | `POST /admin/pause`; l'avvio con `START_PAUSED=true` ([operativita.md](operativita.md), OPS-27) | — |
| `reorg` | il listener Electrum, per una riorganizzazione di profondità ≥ 2 | `chain_reorg_detected` ([AUD-38]) |
| `payout_blocked` | lo scheduler, quando la scommessa del vincitore non è più sulla catena | `payout_blocked` ([AUD-44]) |
| `resurrected_tx` | il riconciliatore, quando una riga `failed` risulta confermata | `pending_tx_resurrected` ([AUD-39]) |
Le pause automatiche (`reorg`, `payout_blocked`, `resurrected_tx`) sono
scritte dal sistema, senza alcuna richiesta al pannello. Una pausa
`operator` richiesta mentre è attivo un motivo automatico lascia
`paused_reason` com'era (DAT-69), ma la riga riporta comunque
`reason = "operator"`. `user_id` no, `round_id` no. La riga viene scritta a
ogni pausa, anche se la lotteria era già in pausa. Stessa transazione di
`paused = true`.
*Codice:* `app/api/routes/admin.py:pause_lottery`, `app/main.py:lifespan`,
`app/electrum/listener.py:ElectrumListener._record_reorg`,
`app/rounds/scheduler.py:RoundScheduler._trigger_payout`,
`app/tx/reconcile.py:reconcile_once` ·
*Test:* `tests/unit/test_pause_reason.py`, `tests/unit/test_electrum_listener.py`
*Stato:* da implementare (B-82, B-90) · *Oggi:* scritto da
`POST /admin/pause` (`operator`), dal riconciliatore (`resurrected_tx`) e dal
listener (`reorg`); `payout_blocked` e l'avvio con `START_PAUSED` non lo
scrivono ancora.
- **[AUD-12]** `lottery_resumed` — `POST /admin/resume`. Payload
`{"reason"}`: il `paused_reason` che la ripresa ha tolto (`null` se la
lotteria non era in pausa), così il registro dice che cosa l'operatore ha
accettato di riprendere (API-32). `user_id` no, `round_id` no. Scritto a
ogni chiamata, anche se la lotteria non era in pausa. Stessa transazione di
`paused = false`, `paused_reason = NULL` e dell'azzeramento di
`payout_blocked_at`.
*Codice:* `app/api/routes/admin.py:resume_lottery` ·
*Test:* `tests/unit/test_pause_reason.py`
*Stato:* da implementare (B-82), per l'azzeramento di `payout_blocked_at` ·
*Oggi:* `rounds.payout_blocked_at` non esiste ancora.
- **[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
[limiti-noti.md](limiti-noti.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`
### Account
- **[AUD-41]** `user_registered` — una registrazione è riuscita
([registrazione-e-depositi.md](registrazione-e-depositi.md#registrazione),
REG-16). Payload `{"derivation_index", "address"}`: l'indice di derivazione
e l'indirizzo assegnati. Lo username non compare (è nella tabella `users`).
`user_id` sì (il nuovo utente), `round_id` no. Stessa transazione che crea
l'utente. È ciò che, dopo un ripristino, permette di ricostruire quali
indici erano già assegnati. Nessuna logica rilegge la riga.
*Codice:* `app/auth/routes.py:register` · *Test:* —
*Stato:* da implementare (B-92) · *Oggi:* la registrazione non scrive alcun
evento.
- **[AUD-42]** `password_changed` — un utente ha cambiato la propria password
con `POST /users/me/change-password`
([registrazione-e-depositi.md](registrazione-e-depositi.md#sessione-e-password),
REG-12). Payload `{"user_id"}`; né la vecchia né la nuova password
compaiono. `user_id` sì, `round_id` no. Stessa transazione del nuovo hash e
dell'incremento di `token_version`. Un tentativo fallito (password attuale
sbagliata, nuova troppo corta) non scrive nulla. Nessuna logica rilegge la
riga.
*Codice:* `app/api/routes/users.py:change_password` · *Test:* —
*Stato:* da implementare (B-94) · *Oggi:* il cambio password non scrive
alcun evento.
- **[AUD-43]** `restore_gap_detected` — il controllo all'avvio ha trovato
cronologia sulla catena per almeno uno dei 20 indici di derivazione
successivi al massimo assegnato, cioè il database è probabilmente un backup
più vecchio della realtà
([registrazione-e-depositi.md](registrazione-e-depositi.md#registrazione),
REG-15). Payload `{"highest_assigned_index", "used"}`:
`highest_assigned_index` è il massimo indice presente in `users` (`null` se
non c'è alcun utente), `used` una lista di `{"derivation_index", "address"}`
per ogni indirizzo con cronologia. `user_id` no, `round_id` no. Una riga per
ogni avvio in cui il controllo trova indirizzi usati; transazione propria
([AUD-03]). La sospensione delle registrazioni che ne segue non dipende da
questa riga. Procedura in [operativita.md](operativita.md) (OPS-28).
*Codice:* `app/main.py:lifespan` · *Test:* —
*Stato:* da implementare (B-90) · *Oggi:* nessun controllo e nessun evento.
### 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, il quorum degli altri server lo ha
confermato non speso con lo stesso importo
([registrazione-e-depositi.md](registrazione-e-depositi.md#deposito), DEP-08)
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`, `tests/unit/test_confirmation_proof.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 **esplicitamente**
la transazione di una scommessa; gli UTXO sono stati liberati e il
partecipante rimosso. Un esito incerto (timeout, connessione caduta dopo
l'invio) non scrive questo evento: la riga resta `building` per il
riconciliatore
([scommesse-e-prelievi.md](scommesse-e-prelievi.md#cosa-succede), B-76).
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`, `tests/unit/test_broadcast_outcome.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
**esplicitamente** la transazione di un prelievo; gli UTXO sono stati
liberati e il prelievo segnato `failed`. Come per [AUD-20], un esito
incerto non scrive questo evento (B-76). 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:* `tests/unit/test_broadcast_outcome.py`
### 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-46]** `closing_stalled` — un round è in `closing` oltre la propria
scadenza da più di `CLOSING_STALL_THRESHOLD_SECONDS` (1800 s) perché
almeno una scommessa è ancora in volo. La regola, soglia e ripetizione
comprese, è
[TX-29](transazioni-e-riconciliazione.md#riconciliazione); qui c'è solo la
voce del catalogo. Payload `{"in_flight", "txids", "seconds_past_deadline"}`:
numero di scommesse in `building` o `broadcast`, lista dei loro txid
correnti, secondi trascorsi dalla scadenza. `user_id` no, `round_id` sì.
Transazione propria ([AUD-03]). La riga più recente del round è l'orologio
della ripetizione successiva, 1800 s dopo ([AUD-09]).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick` · *Test:* —
*Stato:* da implementare (B-96) · *Oggi:* l'attesa in `closing` non scrive
alcun evento.
- **[AUD-37]** `draw_committed` — il round è entrato in `drawing`: elenco dei
partecipanti e altezza del blocco di estrazione sono fissati
([ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md#2--chiusura),
RND-14, RND-33). Payload `{"participants_hash", "draw_height",
"participants", "server_seed_hash"}`: impronta dell'elenco ordinato,
altezza del blocco di estrazione, numero di partecipanti confermati,
impronta del segreto pubblicata all'apertura (RND-34). `server_seed` **non**
compare. `user_id` no, `round_id` sì. Stessa transazione che porta il round
a `drawing` e salva `draw_position`, `participants_hash` e `draw_height`.
Poiché la riga è salvata prima che il blocco a `draw_height` esista, il
registro prova che impronta e altezza erano fissate in anticipo. Nessuna
logica rilegge la riga: la ripresa dell'estrazione (RND-36) legge i valori
dal round.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
*Test:* `tests/unit/test_scheduler.py`
- **[AUD-24]** `winner_drawn` — il vincitore è stato estratto e salvato; in
questa riga il segreto del round viene **rivelato**. Payload
`{"winner_address", "pool_amount_sats", "block_height", "block_hash",
"participants", "draw_height", "participants_hash", "server_seed",
"seed"}`: indirizzo del vincitore, montepremi totale (somma delle puntate
nette), altezza e hash del blocco usato, numero di partecipanti, altezza del
blocco di estrazione fissata all'ingresso in `drawing` (uguale a
`block_height`), impronta dei partecipanti (uguale a quella di
`draw_committed`), `server_seed` in esadecimale (64 caratteri) e il seme
calcolato, in esadecimale (64 caratteri, lo stesso valore di `seed_int`:
come stringa, perché un intero di 256 bit perde precisione in JavaScript).
Con `draw_committed` e la catena, la riga basta a rifare il calcolo di
[RND-17](ciclo-di-vita-del-round.md#3--estrazione). `user_id` sì (il
vincitore), `round_id` sì. Stessa transazione che salva il vincitore sul
round e lo porta a `paying_out` ([RND-18](ciclo-di-vita-del-round.md#3--estrazione)):
`server_seed` non può quindi comparire nel registro prima che il vincitore
sia salvato.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._complete_draw` ·
*Test:* `tests/unit/test_draw_proof.py`
- **[AUD-25]** `draw_baseline_tip_unknown` — quando il round sarebbe pronto
per `drawing`, l'altezza della catena non era nota: il round resta in
`closing` e il passaggio si ritenta al passo successivo
([RND-19](ciclo-di-vita-del-round.md#3--estrazione)). Payload vuoto `{}`.
Una sola riga per round ([AUD-09]). `user_id` no, `round_id` sì.
Transazione propria ([AUD-03]). Dovrebbe essere irraggiungibile (lo
scheduler non lavora senza un'altezza nota).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
*Test:* `tests/unit/test_scheduler.py`
- **[AUD-26]** `draw_header_corroboration_failed` — raggiunte le conferme
richieste, il quorum dei server non concorda sull'header all'altezza
`draw_height`, o non risponde abbastanza
([RND-16](ciclo-di-vita-del-round.md#3--estrazione)); al passo successivo
si richiede la stessa altezza. Una riga per ogni tentativo fallito. Payload
`{"height", "reported_hash"}`: `height` è sempre `draw_height`,
`reported_hash` l'hash riportato dal server attivo. `user_id` no,
`round_id` sì. Transazione propria ([AUD-03]).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_draw_block` ·
*Test:* `tests/unit/test_scheduler.py`
- **[AUD-27]** `draw_stalled` — l'estrazione è in stallo secondo la regola di
[RND-20](ciclo-di-vita-del-round.md#3--estrazione), che ne è il
proprietario (soglia, condizioni e ripetizione); qui c'è solo la voce del
catalogo. Payload `{"draw_height", "current_tip_height",
"elapsed_seconds"}`: altezza del blocco di estrazione, altezza della catena
nota in quel momento, secondi da quando dura la condizione di RND-20.
`user_id` no, `round_id` sì. Transazione propria ([AUD-03]).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_draw_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`, e nemmeno un pagamento
trattenuto perché la scommessa del vincitore non è più sulla catena, che
scrive invece `payout_blocked` ([AUD-44]). L'elenco dei motivi è di
[RND-25](ciclo-di-vita-del-round.md#4--pagamento); la verifica senza
quorum di [RND-39](ciclo-di-vita-del-round.md#4--pagamento) termina anche
lei con `payout_failed`, motivo `pool verification unavailable` (B-82). 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`. Per un
pagamento promosso dal riconciliatore vale [AUD-30].
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
*Test:* `tests/unit/test_scheduler.py`
- **[AUD-45]** `participant_reorged_out` — la verifica prima del pagamento
ha trovato assente, secondo il quorum, l'uscita della scommessa di un
partecipante, che passa a `reorged_out` ed è escluso dal montepremi
([RND-39](ciclo-di-vita-del-round.md#4--pagamento), DAT-67). Una riga per
partecipante. Payload `{"txid", "vout", "amount_sats", "pool_amount_sats"}`:
l'uscita della scommessa sparita, il suo importo netto e il montepremi
riscritto dopo l'esclusione. `user_id` sì (il partecipante), `round_id` sì.
Stessa transazione del passaggio a `reorged_out` e della riscrittura di
`pool_amount_sats`. Nessuna logica rilegge la riga.
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
*Test:* —
*Stato:* da implementare (B-82) · *Oggi:* nessun partecipante viene mai
escluso; il pagamento fallisce con `insufficient pool UTXOs`.
- **[AUD-44]** `payout_blocked` — la verifica prima del pagamento ha trovato
assente la scommessa **del vincitore**: il pagamento non si costruisce, il
round resta in `paying_out` con `payout_blocked_at` e la lotteria va in
pausa automatica
([RND-39](ciclo-di-vita-del-round.md#4--pagamento), DAT-68). Payload
`{"txid", "vout", "amount_sats"}`: l'uscita della scommessa del vincitore.
`user_id` sì (il vincitore), `round_id` sì. Stessa transazione di
`payout_blocked_at`, della pausa e della riga `lottery_paused` con
`reason = "payout_blocked"` ([AUD-11]). Dopo `POST /admin/resume` la
verifica si ripete: se la scommessa è ancora assente si scrive una nuova
riga. Non è un `payout_failed` e non fa da orologio dei tentativi.
Procedura in [operativita.md](operativita.md) (OPS-30).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
*Test:* —
*Stato:* da implementare (B-82) · *Oggi:* il pagamento fallisce con
`insufficient pool UTXOs` a ogni tentativo, senza pausa.
### 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). Nella
stessa transazione della promozione si scrive anche l'evento che l'invio
riuscito avrebbe scritto — `bet_placed` ([AUD-19]), `withdrawal_sent`
([AUD-21]) o `payout_sent` ([AUD-29]) — con lo stesso payload
([TX-16](transazioni-e-riconciliazione.md#riconciliazione)).
*Codice:* `app/tx/reconcile.py:_promote` ·
*Test:* nessun test verifica la riga di audit.
*Stato:* da implementare (B-96), per il secondo evento · *Oggi:* si scrive
solo `pending_tx_recovered`.
- **[AUD-31]** `pending_tx_abandoned` — una transazione `building` o `pending`
è stata dichiarata persa **con una prova**
([TX-17](transazioni-e-riconciliazione.md#riconciliazione)): 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` uguale al `failure_reason` salvato sulla riga, che nomina la prova
([modello-dati.md](modello-dati.md), DAT-36), 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`, `tests/unit/test_reconcile_proof.py`
- **[AUD-39]** `pending_tx_resurrected` — una riga `failed` da meno di 14
giorni è risultata confermata: una transazione data per persa è arrivata in
un blocco
([TX-23](transazioni-e-riconciliazione.md#riconciliazione)). Payload
`{"pending_transaction_id", "kind", "txid", "block_height"}`: `txid` è la
versione confermata (una qualunque della catena di sostituzioni),
`block_height` l'altezza del blocco che la contiene. `user_id` e
`round_id` come in [AUD-30]. Una sola riga per transazione, perché la riga
passa a `confirmed` e non viene più sorvegliata. Stessa transazione del
passaggio a `confirmed`, della pausa e della riga `lottery_paused` con
`reason = "resurrected_tx"` ([AUD-11]). Le righe collegate non vengono
corrette: la procedura è in [operativita.md](operativita.md) (OPS-30).
*Codice:* `app/tx/reconcile.py:_resurrect` · *Test:* `tests/unit/test_reconcile_proof.py`
- **[AUD-40]** `rbf_bump_failed` — un aumento di commissione non è riuscito
([TX-24](transazioni-e-riconciliazione.md#rbf-accelerare-una-transazione-lenta)).
Payload `{"pending_transaction_id", "kind", "txid", "reason", "message"}`:
`txid` è il txid corrente della riga; `reason` è uno di
`change_too_small` (il resto non assorbe l'aumento, TX-11),
`max_fee_rate` (la riga è già a `MAX_FEE_RATE_SAT_VB`) o
`replacement_rejected` (la rete ha rifiutato esplicitamente la
sostituzione); `message` è il testo dell'errore, troncato a 200 caratteri.
`user_id` e `round_id` come in [AUD-30]. Transazione propria ([AUD-03]);
la riga `pending` non cambia. Si scrive **una volta per coppia (txid
corrente, `reason`)**, come fissato da TX-24: prima di scrivere si cerca
nel registro una riga uguale ([AUD-09]); un nuovo fallimento con la stessa
coppia va solo nei log, mentre un nuovo txid (dopo un aumento riuscito) o un
motivo diverso scrivono una riga nuova.
*Codice:* `app/tx/broadcast.py:RbfBumper._tick`, `app/tx/broadcast.py:bump_fee` ·
*Test:* —
*Stato:* da implementare (B-87) · *Oggi:* l'errore va solo nel log
(`could not bump pending_transaction N`), ogni 30 secondi.
### Catena
- **[AUD-38]** `chain_reorg_detected` — il listener ha seguito una
riorganizzazione della catena
([ELC-24](connessione-electrum.md#riorganizzazioni)). Payload
`{"depth", "fork_height", "old_tip_height", "old_tip_hash",
"new_tip_height", "new_tip_hash"}`: numero dei nostri blocchi sostituiti
(`old_tip_height − fork_height`), altezza del punto di biforcazione,
altezza e hash della punta prima e dopo. `user_id` no, `round_id` no. Con
`depth` 1 è solo osservativo (transazione propria, [AUD-03]); con `depth`
≥ 2 è salvato nella stessa transazione della pausa e della riga
`lottery_paused` con `reason = "reorg"` ([AUD-11]). Una biforcazione più
profonda di 10 header non viene seguita e non scrive questo evento (la
sessione si chiude). Nessuna logica rilegge la riga.
*Codice:* `app/electrum/listener.py:ElectrumListener._record_reorg` ·
*Test:* `tests/unit/test_electrum_listener.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;
- passaggio di stato del round a `closing`, 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 **riuscito** (solo il log
`bumped <tipo> pending_transaction N`);
- login, login falliti e blocchi per troppi tentativi, compresi i tentativi
falliti di cambio password;
- invio di una segnalazione di bug;
- accesso in lettura al pannello admin (elenchi utenti, round, audit).
Escono da questo elenco, perché diventano eventi del catalogo: l'ingresso
in `drawing` (`draw_committed`, [AUD-37]), ogni RBF impossibile o rifiutato
(`rbf_bump_failed`, [AUD-40]), la registrazione (`user_registered`,
[AUD-41]) e il cambio password riuscito (`password_changed`, [AUD-42]).
*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`
*Stato:* da implementare (B-87, B-92, B-94), per i tre fatti che escono
dall'elenco · *Oggi:* gli RBF impossibili, la registrazione e il cambio
password riuscito non producono alcuna riga.
## 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]** I messaggi dei moduli dell'applicazione (scheduler, listener,
riconciliatori) finiscono in `data/logs/app.log` **e** sull'output del
container, quindi `docker compose logs app` li mostra insieme all'output di
avvio del container (controllo della chiave, migrazioni Alembic). La regola
è di [ARC-09](architettura.md#log), che ne è il proprietario.
*Codice:* `app/logging_config.py:setup_logging`
*Stato:* da implementare (B-92) · *Oggi:* il logger radice ha solo
l'handler su file: `docker compose logs app` mostra solo l'output di avvio
del container e ciò che uvicorn scrive con la propria configurazione
(avvio, richieste).
- **[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]) |
+630
View File
@@ -0,0 +1,630 @@
# 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-79) · *Oggi:* `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) · *Oggi:* sono fotografate durata, pausa e
`draw_confirmations`; costo della scommessa e `fee_address` sono letti dalla
configurazione a ogni uso, `max_round_pool_sats` non esiste.
- **[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 **cifrato** con la chiave
della master xprv (`server_seed_enc`, [modello-dati.md](modello-dati.md)
DAT-64: il database non contiene mai il segreto in chiaro prima della
rivelazione) 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/rounds/draw.py:new_server_seed`, `app/wallet/keystore.py:encrypt_round_seed`, `app/api/routes/rounds.py:current_round` ·
*Test:* `tests/unit/test_rounds_service.py`, `tests/unit/test_draw_proof.py`
- **[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)) 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).
*Codice:* `app/rounds/service.py:open_new_round_if_needed`, `app/wallet/hd.py:derive_pool_key`, `app/wallet/hd.py:derive_round_pool_key` ·
*Test:* `tests/unit/test_round_pool_address.py`
## 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), `tests/unit/test_reconcile_proof.py`
- **[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`, `app/rounds/draw.py:participants_hash` ·
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_draw.py`, `tests/unit/test_draw_proof.py`
- **[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:* `tests/unit/test_scheduler.py`
## 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_draw_block` ·
*Test:* `tests/unit/test_scheduler.py`
*Stato:* da implementare (B-81) · *Oggi:* la condizione si controlla dentro
`_close_and_draw`, che resta in attesa per tutta la durata senza che
`_tick` la riprenda: dopo un errore o un riavvio non riparte.
- **[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. L'evento si scrive una volta per ogni hash diverso
riportato dal server attivo per quell'altezza, non a ogni richiesta, così
un disaccordo che dura non scrive una riga ogni 5 secondi; la durata
dell'attesa resta visibile tramite `draw_stalled` ([RND-20]).
*Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_draw_block`, `app/electrum/listener.py:ElectrumListener.agreed_block_hash` ·
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_electrum_listener.py`
- **[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_seed`, `app/rounds/draw.py:draw_index`, `app/rounds/draw.py:draw_winner`, `app/rounds/scheduler.py:RoundScheduler._complete_draw` ·
*Test:* `tests/unit/test_draw.py`, `tests/unit/test_draw_proof.py`
- **[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`, `draw_height`, `server_seed` e `seed`
in esadecimale, [audit-log.md](audit-log.md) AUD-24). `server_seed` entra
nel registro nella stessa transazione in cui il vincitore viene salvato, e
diventa pubblico tramite la prova ([RND-37]) solo dopo quel commit; 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._complete_draw` ·
*Test:* `tests/unit/test_draw_proof.py`
- **[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` ·
*Test:* `tests/unit/test_scheduler.py`
- **[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_draw_block`, `app/api/routes/rounds.py:current_round` ·
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_rounds_route.py`
- **[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._complete_draw` ·
*Test:* `tests/unit/test_draw_proof.py` (solo `_complete_draw`)
*Stato:* da implementare (B-81) · *Oggi:* tutto ciò che serve è nel database
e `_complete_draw` è idempotente, ma `_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:round_proof` ·
*Test:* `tests/unit/test_draw_proof.py`
### 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
[limiti-noti.md](adr/README.md#round-ed-estrazione) (B-73).
L'algoritmo resta un componente **sostituibile** (vedi
[limiti-noti.md](limiti-noti.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`, `tests/unit/test_round_pool_address.py`
*Stato:* da implementare (B-82) · *Oggi:* spende le monete confermate
dell'indirizzo del round (per un round vecchio, di quello condiviso) lette
dal solo server attivo, scelte dalla più grande fino a coprire il
montepremi, e non solo le uscite delle scommesse dei partecipanti: un'altra
moneta arrivata a quell'indirizzo verrebbe spesa.
- **[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`, e — *da implementare (B-82)* —
`pool verification unavailable` quando la verifica del montepremi prima del
pagamento ([RND-39]) non ottiene abbastanza risposte dal quorum. 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 non si potrebbe pagare, verificandola per
**n = 1** e per **n = `MAX_PARTICIPANTS_PER_ROUND`** partecipanti (i due
estremi: con uno solo la commissione è minima, con il massimo è massima la
riserva, che cresce con gli ingressi). Con `netto` = `bet_amount_sats −
estimate_vsize(MAX_TX_INPUTS, 2) × fee_rate_sat_vb` (la scommessa più piccola
che può arrivare al montepremi) e `montepremi = n × netto`, per entrambi i
valori di n devono valere:
- `winner_share(montepremi) − estimate_vsize(n, 3) × fee_rate_sat_vb ≥
DUST_LIMIT_SATS`;
- `montepremi − winner_share(montepremi) − riserva(n) ≥ DUST_LIMIT_SATS`,
con `riserva(n)` quella di [RND-38] calcolata su n ingressi.
La stessa verifica si applica a `PUT /admin/config`: una modifica di
`bet_amount_sats` o `fee_rate_sat_vb` che la farebbe fallire è rifiutata,
così un aumento della commissione di rete a round in corso non può rendere
impagabile il round (il pagamento legge `fee_rate_sat_vb` al momento della
costruzione).
*Codice:* `app/rounds/service.py:rounds_can_open`, `app/api/routes/admin.py` ·
*Test:* —
*Stato:* da implementare (B-79) · *Oggi:* `rounds_can_open` controlla solo
che `fee_address` non sia vuoto, e `PUT /admin/config` non fa verifiche di
pagabilità.
## 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.
+194
View File
@@ -0,0 +1,194 @@
# Come funziona PLM Lottery
Panoramica del funzionamento della piattaforma (l'indice completo della
documentazione è [README.md](README.md)). È 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 |
| [adr/](adr/README.md) | Le decisioni di progetto con le loro motivazioni, una per file (ADR) |
| [limiti-noti.md](limiti-noti.md) | 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 | 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)).
+348
View File
@@ -0,0 +1,348 @@
# 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 [limiti-noti.md](limiti-noti.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 (maiuscole accettate, conservate in
minuscolo); `pin=` può seguire anche `<modo>` con TLS, mai `notls`/`plain`
(non c'è un certificato da fissare). 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`
- **[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`, `app/electrum/client.py:ElectrumClient._check_pin`, `app/main.py:_make_electrum_client` ·
*Test:* `tests/unit/test_electrum_client.py`
- **[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_quorum_servers`, `app/main.py:lifespan` ·
*Test:* `tests/unit/test_electrum_listener.py`
## 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:* `tests/unit/test_electrum_client.py`
## 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`, `app/electrum/listener.py:ElectrumListener._check_not_stalled` ·
*Test:* `tests/unit/test_electrum_listener.py`
## 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
```
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].
- **[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`
- **[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/listener.py:ElectrumListener._fetch_headers`, `app/electrum/client.py:ElectrumClient.get_block_headers` ·
*Test:* `tests/unit/test_draw.py`, `tests/unit/test_electrum_listener.py`
- **[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._adopt_first_header`, `app/electrum/listener.py:ElectrumListener._extend_window` ·
*Test:* `tests/unit/test_electrum_listener.py`
### 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._follow_reorg` ·
*Test:* `tests/unit/test_electrum_listener.py`
- **[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.
L'evento è scritto **prima** che la finestra si sposti: se la scrittura
fallisce la sessione termina e la stessa biforcazione, annunciata dal server
successivo, viene registrata allora (nessuna riorganizzazione è seguita
senza traccia).
*Codice:* `app/electrum/listener.py:ElectrumListener._record_reorg`, `app/electrum/listener.py:ElectrumListener._follow_reorg`, `app/db/models.py:RoundConfig` ·
*Test:* `tests/unit/test_electrum_listener.py`
## 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ì per una sola decisione: la lettura delle monete del
montepremi per il pagamento
(`app/rounds/scheduler.py:RoundScheduler._trigger_payout`) si basa sul solo
server attivo, ed è la riga [ELC-27]. Le conferme delle transazioni
([ELC-26]), il reintegro di una moneta ricomparsa ([ELC-25]), l'abbandono
([ELC-28]) e l'invio ([TX-04], [TX-21]) usano già gli altri server.
- **[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`
| ID | Prima di… | Si verifica che… |
|---|---|---|
| **[ELC-15]** | usare un blocco per l'estrazione | l'header che ciascun server, **attivo compreso**, restituisce per l'altezza di estrazione (`blockchain.block.header`, 80 byte con lavoro valido) abbia lo stesso hash, con almeno 2 risposte dagli altri server e la maggioranza stretta di chi ha risposto; 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.agreed_block_hash`,
`app/electrum/listener.py:ElectrumListener.corroborate_utxo_spent`,
`app/electrum/listener.py:ElectrumListener.corroborate_utxo_credit`,
`app/electrum/listener.py:ElectrumListener.corroborate_utxo_reinstatement`,
`app/electrum/listener.py:ElectrumListener.confirmation_proven`,
`app/electrum/listener.py:ElectrumListener._corroborate_majority` ·
*Test:* `tests/unit/test_electrum_listener.py`, `tests/unit/test_confirmation_proof.py`
Stato delle righe della tabella:
- [ELC-17] — *Stato:* da implementare (B-82) · *Oggi:* basta un'altezza
maggiore di 0 (1 conferma).
- [ELC-27] — *Stato:* da implementare (B-82) · *Oggi:* il pagamento sceglie
fra le monete che il server attivo elenca per il montepremi.
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).
## 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.
+101 -35
View File
@@ -2,6 +2,8 @@
Come gestire la configurazione operativa di PLM Lottery. Presuppone che il
server sia già avviato — vedi [running-the-server.md](running-the-server.md).
Per il funzionamento interno (stati del round, riconciliazione delle
transazioni, connessione Electrum) vedi [come-funziona.md](come-funziona.md).
## Accesso
@@ -23,7 +25,16 @@ 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))
- **Segnalazioni bug** — segnalazioni inviate da `/report-bug`, da smistare `open` → `read` → `resolved`
Nella navbar, a destra, una pillola mostra lo stato del round ("In attesa
del prossimo round", "Round aperto", oppure "Estrazione in corso", che copre
chiusura, estrazione e pagamento) e l'altezza dell'ultimo blocco noto,
aggiornate ogni 15 secondi da `GET /rounds/current`. Non indica se la
connessione Electrum è attiva né a quale server: un'altezza che non sale per
parecchi minuti è il segnale da guardare (procedura in
[operativita.md](operativita.md), "Electrum irraggiungibile").
## Parametri
@@ -36,21 +47,25 @@ business — quelli si toccano solo da qui.
| Campo | Significato |
|---|---|
| **Fee address** | L'indirizzo PLM su cui finisce il 30% di ogni round (fee). Obbligatorio: finché è vuoto **non si apre nessun round** (il payout non sarebbe costruibile, quindi il round accetterebbe scommesse per poi restare bloccato con i soldi già nel montepremi). Il pannello lo segnala con un avviso in cima ai Parametri, e la pagina utente mostra un banner "lotteria non ancora pronta". Un round già in corso non viene interrotto se svuoti il campo: chiude, estrae e paga normalmente. |
| **Fee address** | L'indirizzo PLM su cui finisce il 30% di ogni round (fee). Obbligatorio: su un'istanza nuova è vuoto, e finché resta vuoto **non si apre nessun round** (il payout non sarebbe costruibile, quindi il round accetterebbe scommesse per poi restare bloccato con i soldi già nel montepremi). Il pannello lo segnala con un avviso in cima ai Parametri, e la pagina utente mostra un banner "lotteria non ancora pronta". Una volta impostato non si può più svuotare dal pannello: un valore vuoto non è un indirizzo `plm1...` valido e viene rifiutato. **Attenzione:** oggi il payout legge questo campo al momento in cui viene costruito, quindi cambiarlo mentre un round è in corso sposta anche la commissione di quel round sul nuovo indirizzo. |
| **Bet amount (PLM)** | Il costo fisso d'ingresso per round. È anche l'importo minimo prelevabile: un prelievo sotto questa soglia viene rifiutato (i depositi non hanno un controllo minimo lato server). |
| **Durata round (secondi)** | Quanto resta aperto un round prima di chiudersi ed estrarre il vincitore. Il taglio per le nuove giocate scatta esattamente allo scadere di questo tempo (verificato ad ogni bet, non dipende dal ciclo dello scheduler) — è un "semaforo giallo": nessuna nuova entrata, ma le bet già trasmesse prima dello scadere hanno comunque tempo di confermarsi prima che il round chiuda ed estragga. |
| **Pausa tra un round e il successivo (secondi)** | Cooldown dopo la chiusura di un round, prima che il successivo si apra — dà tempo ai giocatori di vedere l'esito. |
| **Durata animazione estrazione (secondi)** | Tempo minimo per cui la dashboard di ogni utente mostra l'animazione "Estrazione in corso" dopo la chiusura del round, prima di rivelare il vincitore. È solo un minimo: il processo reale aspetta più blocchi in sequenza (conferma dell'ultima bet in sospeso, il blocco dell'estrazione con le sue conferme, conferma del payout — un blocco ogni 2 minuti in media), quindi l'animazione può durare più a lungo di questo valore, mai meno. |
| **Conferme sul blocco di estrazione** | Da 1 a 20 (predefinito 3): quanti blocchi deve avere la catena a partire dal blocco di estrazione prima che il suo hash scelga il vincitore. Più conferme rendono l'estrazione più robusta a una riorganizzazione della catena e allungano l'attesa di circa 2 minuti per blocco. Si applica dal round successivo. |
| **Fee rate di rete (sat/vB)** | Fee per byte usata per costruire bet, payout e prelievi. |
| **Timeout prima del fee-bump RBF (secondi)** | Dopo quanto tempo senza conferma una transazione viene ritrasmessa con fee più alta. |
Durata e cooldown si applicano **dal round successivo**, non a quello già in
corso: ogni round si porta dietro i valori con cui è stato aperto, così
abbassare la durata mentre un round è a metà non lo chiude di colpo, e alzarla
non sposta il countdown che i giocatori stanno già guardando. Gli altri
parametri (bet amount, fee rate, RBF timeout) restano invece a effetto
immediato.
| **Durata animazione estrazione (secondi)** | Tempo minimo per cui la dashboard di ogni utente mostra l'animazione "Estrazione in corso" dopo la chiusura del round, prima di rivelare il vincitore. È solo un minimo: il processo reale aspetta fino a 3 blocchi confermati in sequenza (ultima bet in sospeso, estrazione, payout — ~2 minuti l'uno), quindi l'animazione può durare più a lungo di questo valore, mai meno. |
| **Fee rate di rete (sat/vB)** | Fee per byte usata per costruire bet, payout e prelievi. |
| **Timeout prima del fee-bump RBF (secondi)** | Dopo quanto tempo senza conferma una transazione viene ritrasmessa con fee più alta. |
non sposta il countdown che i giocatori stanno già guardando. Tutti gli altri
parametri sono invece a effetto immediato, anche sul round in corso: un nuovo
bet amount vale per le scommesse successive (il montepremi annunciato resta
calcolato su quanto è stato davvero puntato), fee rate e RBF timeout valgono
per le prossime transazioni costruite o accelerate, compreso il payout del
round in corso, e il fee address vale per il prossimo payout costruito (vedi
sopra).
Tutti gli importi in PLM vengono convertiti in sats (1 PLM = 100.000.000 sats)
solo nella chiamata API — il backend lavora sempre in sats.
@@ -71,27 +86,42 @@ sorprenderli con un'interruzione improvvisa.
- **"Interrompi dopo questo round"**: il round eventualmente in corso viene
**completato normalmente** — chiude, estrae il vincitore da un blocco
confermato, e paga il 70/30 come sempre. Solo l'apertura del **round
successivo** viene sospesa. Gli utenti vedono un avviso di manutenzione
sulla loro dashboard (e sulla home, anche da sloggati) finché la lotteria
resta in pausa.
successivo** viene sospesa. La pausa non ferma nemmeno le scommesse e i
prelievi sul round ancora aperto: il round prosegue fino alla sua scadenza.
Gli utenti vedono un avviso di manutenzione sulla loro dashboard (e sulla
home, anche da sloggati) finché la lotteria resta in pausa.
- **"Riprendi lotteria"**: annulla la pausa — al prossimo giro dello
scheduler (ogni 5 secondi) un nuovo round si apre normalmente (rispettando
comunque il cooldown se il precedente si è appena chiuso).
Ogni pausa/ripresa viene registrata nell'audit log (`lottery_paused` /
`lottery_resumed`), ma — come per il resto del pannello — non registra
*quale* operatore l'ha premuta (token condiviso, vedi limiti noti in
[CLAUDE.md](../CLAUDE.md)).
*quale* operatore l'ha premuta (token condiviso, vedi
[limiti-noti.md](limiti-noti.md)).
Prima di un riavvio o di un deploy la pausa da sola non basta: bisogna anche
aspettare che il round in corso sia `closed`, perché oggi un riavvio durante
l'estrazione blocca il round. La procedura è in
[running-the-server.md](running-the-server.md) e, completa, in
[operativita.md](operativita.md) (OPS-10).
**Chi paga il fee-bump RBF?** Quando una bet, un payout o un prelievo resta
troppo a lungo senza conferma (oltre il "Timeout prima del fee-bump RBF"), il
sistema lo ritrasmette con una fee più alta. Il costo aggiuntivo lo assorbe
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
il pool (si riduce il resto che torna all'indirizzo pool) — 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 (nel
log `could not bump pending_transaction N`, ripetuto ogni 30 secondi) e la
transazione resta in attesa. **Per i payout è il caso normale**: il pool di
un round contiene di solito esattamente le scommesse del round e il payout le
spende tutte, quindi non ha resto e non si può accelerare. Una transazione
ferma nel mempool non viene nemmeno abbandonata, perché il server la conosce:
se è un payout, il round resta in `paying_out` e nessun nuovo round si apre
finché non conferma. Cosa fare è in [operativita.md](operativita.md);
il funzionamento in
[transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md).
## Round
@@ -102,30 +132,39 @@ txid.
## Transazioni pendenti
`GET /admin/pending-transactions` elenca bet, payout e prelievi ancora senza
conferma: tipo, stato, txid corrente, fee rate usata, numero di tentativi
(si incrementa a ogni bump RBF) e orario dell'ultima trasmissione. Una riga
che resta qui a lungo, con `attempt_count` che sale, indica una transazione
in difficoltà — vedi "Limiti noti" sul fallback RBF.
`GET /admin/pending-transactions` elenca le ultime 50 transazioni tracciate
(bet, payout e prelievi), dalla più recente, **in qualunque stato**: non solo
quelle ancora `building` o `pending`, ma anche quelle già `confirmed` o
`failed` — per sapere cosa è davvero in sospeso si guarda la colonna Stato.
Per ogni riga: id, tipo, stato, txid corrente, fee rate usata, numero di
tentativi (si incrementa a ogni bump RBF) e orario del **primo** invio (non
cambia con i bump). Una riga che resta `pending` a lungo, con il numero di
tentativi che sale, indica una transazione in difficoltà; una che resta
`pending` con il numero di tentativi fermo è spesso un bump impossibile (vedi
sopra "Chi paga il fee-bump RBF?").
## Audit log
`GET /admin/audit-log` elenca gli ultimi 200 eventi registrati dal sistema
(tipo evento, payload JSON, utente/round coinvolti, timestamp): bet
piazzate, payout inviati, round chiusi, configurazione modificata, accessi
alle chiavi private, ecc. È il primo posto da controllare per ricostruire
cosa è successo dopo un problema.
piazzate, payout inviati, round chiusi senza partecipanti, configurazione
modificata, accessi alle chiavi private, ecc. È il primo posto da controllare
per ricostruire cosa è successo dopo un problema. La sezione non ha filtri né
ricerca, e l'endpoint accetta solo `limit` (al massimo 500): gli eventi più
vecchi si leggono solo direttamente dal database. Non tutto viene
registrato: per esempio registrazioni, cambi password fatti dagli utenti e
bump RBF non lasciano righe (elenco in [audit-log.md](audit-log.md)).
Eventi a cui vale la pena prestare attenzione:
| Evento | Significato |
|---|---|
| `config_updated` | Un parametro è stato modificato; il payload contiene valore precedente e nuovo per ogni campo cambiato. |
| `bet_broadcast_failed` / `withdrawal_broadcast_failed` | La rete ha rifiutato la transazione. Non è stato speso nulla: gli UTXO sono stati liberati e il saldo dell'utente è tornato come prima. |
| `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. |
| `bet_broadcast_failed` / `withdrawal_broadcast_failed` | L'invio della transazione non è riuscito: gli UTXO sono stati liberati e il saldo dell'utente è tornato come prima. Oggi l'evento viene scritto per **qualunque** errore d'invio, anche un timeout o una connessione caduta dopo l'invio, casi in cui la transazione potrebbe essere partita lo stesso: se il `reason` del payload non è un rifiuto esplicito della rete, controllare il `txid` con un explorer. |
| `pending_tx_abandoned` | Il sistema ha dichiarato persa una transazione: UTXO liberati, bet rimossa o prelievo segnato `failed`. Oggi basta che il server Electrum attivo non la conosca (dopo 120 secondi per una riga `building`, 6 ore per una `pending`): dopo un riavvio o un cambio di server può essere un falso allarme, con la transazione ancora viva o già confermata. Controllare sempre il txid del payload con un explorer — procedura in [operativita.md](operativita.md) ("Transazione abbandonata"). |
| `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
@@ -154,9 +193,6 @@ un'altra catena (per esempio `bc1...`) sarebbe formalmente valido come witness
program, e il 30% di commissione di ogni round finirebbe su uno script di cui
nessuno ha la chiave.
```bash
```
## Utenti, chiave privata e reset password
La card "Utenti" elenca id, username, indirizzo e saldo di ogni utente
@@ -182,11 +218,41 @@ 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)).
- Un riavvio mentre un round è in estrazione (`drawing`) lo blocca: prima
di ogni riavvio mettere in pausa e aspettare `closed` (vedi
"Manutenzione" sopra).
- Elenco completo dei limiti accettati: [limiti-noti.md](limiti-noti.md).
Per l'elenco completo dei gap noti vedi la sezione "Known gaps / TODO" in
`CLAUDE.md`.
## Cosa cambierà
La revisione del 2026-09-28 ha deciso delle correzioni non ancora
implementate; quelle che cambiano ciò che si vede da questo pannello sono
(dettaglio e ordine in [piano-correzioni.md](piano-correzioni.md)):
- **La pausa avrà un motivo.** Oltre a quella manuale, il sistema metterà in
pausa la lotteria da solo per una riorganizzazione profonda della catena,
per un payout bloccato o per una transazione data per persa e poi
confermata; il pannello mostrerà il motivo, e "Riprendi lotteria" resterà
l'unico modo di uscirne, dopo le verifiche di
[operativita.md](operativita.md) (OPS-30).
- **Payout bloccato.** Se la scommessa del vincitore sparisce dalla catena,
il payout non partirà (evento `payout_blocked`) e il round resterà in
`paying_out` fino alla ripresa; i partecipanti la cui scommessa è sparita
verranno esclusi dal montepremi (`participant_reorged_out`).
- **Stato Electrum.** Il pannello mostrerà se la connessione è attiva, il
server in uso e da quanto non arriva un blocco.
- **Audit log consultabile per intero**, con filtri per tipo di evento,
round, utente e intervallo di tempo, e a pagine; nuovi eventi come
`user_registered`, `password_changed`, `rbf_bump_failed`,
`closing_stalled` e `chain_reorg_detected` (catalogo in
[audit-log.md](audit-log.md)).
Loaded 100 of 146 files, more files were not shown because too many files have changed in this diff. Show more