11 Commits
Author SHA1 Message Date
davideandClaude Opus 5 845ba98409 Record the audit outcome and the architecture it changed
BUGS.md keeps every finding's original description and gains, per entry, what was
actually done and where its regression test lives — including the two entries
fixed differently from the plan (B-15 validates at startup, B-09 kept both
callers plus a bounded retry) and the one only partially fixed by decision (B-16,
where shipping the guide was deferred).

It also gains a Runtime verification section, which is the part worth reading:
what the live Docker deployment actually demonstrated (startup validation on the
real .env, the listener connecting and holding, rounds cycling, the migration
applied, and the reconciler's missing-tx heuristic checked against the real
server's error message) separated from what has no runtime evidence at all —
nothing has spent money since the restart, so the two-phase write, the RBF
retargeting, the reconciler's actual behaviour and the dust path are unit-tested
only. A green suite is not a working deployment, and the file now says so.

CLAUDE.md documents the two things a reader would otherwise have to reverse-
engineer: the transaction lifecycle (why rows are written before broadcasting,
what each PendingTransaction status means, why spent_txid must track the current
txid, and that one-active-round is now a DB invariant) and the Electrum
connection's rotation/keepalive/timeout behaviour. Its Known gaps list is rewritten
to say what is still open now that transaction-level state self-heals but
round-level state does not.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 00:35:28 +02:00
davideandClaude Opus 5 dc4d5761df Format amounts, guard the loading state, and translate the new errors
Amounts were rendered by bare sats/SATS_PER_PLM division, so binary
floating-point artefacts reached the UI — a 0.7 PLM jackpot could display as
0.7000000000000001 (B-22). formatPlm() in app.js and fmtPlm() in admin.js route
every display site through Intl.NumberFormat with the already-resolved language.
Input fields deliberately keep the raw value: a grouped, localized string would
break parseFloat, and amounts sent to the server still go through
Math.round(x * SATS_PER_PLM).

withLoading kept a snapshot of the button's markup and restored it in finally,
but refreshMe() is fired from the SSE handler, the poll chain, placeBet, withdraw
and showDashboard, all sharing #refresh-btn. Two overlapping calls made the second
snapshot the *loading* label and then restore it permanently, leaving the button
stuck on "Aggiornamento…" (B-23). The in-flight promise now lives in a WeakMap
keyed by the button, so a nested call awaits the existing one and only the
outermost call touches the markup.

The registration form mirrors the constraints the server now enforces
(minlength/pattern/required) and register() pre-checks the password length, so the
failure is immediate and translated instead of a generic 422 (B-12).

Five new error codes are translated in all 7 languages — broadcast_failed,
amount_below_dust_limit, withdrawal_to_own_address, internal_error,
guide_unavailable — keeping the key sets identical, as the i18n contract in
CLAUDE.md requires (verified: 123 keys per language).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 00:35:14 +02:00
davideandClaude Opus 5 7c4e9983ea Survive a dropped Electrum connection, and fall back to other servers
A dropped connection used to hang the whole platform permanently, and three
defects composed to do it (BUGS.md B-01):

The read loop's death was invisible. When the socket closed, _read_loop broke out
and finished, but _run_once was blocked on gather() over two notification
consumers waiting on queues nobody would ever fill again — it never returned and
never raised, so the reconnect-with-backoff logic was unreachable.
client.wait_closed() now resolves when the loop ends for any reason, and
_run_once races it against the consumers and a keepalive with
asyncio.wait(FIRST_COMPLETED).

Nothing had a timeout. request() registered a future, wrote to a half-closed
socket (drain() often doesn't raise) and awaited a reply that would never come.
That hung a POST /bets *while holding the per-user lock*, and could stop the
confirmation poller for good. Every request is now bounded at 15s, and a timeout
tears the connection down rather than leaving a server that owes us a reply in
rotation.

There was no keepalive, so on a quiet instance the normal way this connection
dies is an idle-timeout drop by the server (~10 minutes for many). A server.ping
every 60s makes that observable within a minute.

listener.client is also cleared before reconnecting, so callers stop treating a
dead connection as live.

On top of the finding, the listener now rotates over a list of servers:
ELECTRUM_FALLBACK_SERVERS holds comma-separated host:port[:notls] extras, tried
after the primary. Everything the platform does goes through this one connection
— deposit credits, broadcasts, confirmations, the chain tip the draw waits on —
which made a single hardcoded server its biggest point of failure. A failed or
dropped session moves to the next server immediately and only sleeps on the
backoff once every server has had a turn, so one dead server costs one attempt
instead of an outage, while a genuinely offline network still backs off. A
malformed entry fails at startup, not during the outage when the fallback is what
you need.

Also fixes B-19: header handling refuses a height below the current tip and
applies height and hex together, since _wait_for_next_block waits for
tip_height > tip_at_close (a regression silently added a block to the draw's
wait) and that hex is the draw's entropy source, so a mismatched pair would be
worse than a stale one.

Verified in the live deployment: the log shows the endpoint list, then "Electrum
connected to santantonio.sytes.net:50002", and the connection holds.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 00:34:59 +02:00
davideandClaude Opus 5 25f4a1c6b6 Refuse to start half-configured, and keep failures machine-readable
Startup validation (B-15). An empty JWT_SECRET makes PyJWT raise InvalidKeyError
on every login and an empty XPRV_ENCRYPTION_KEY makes Fernet fail on the first
key derivation — either way the container came up looking healthy and broke the
moment a real user touched it. validate_runtime_secrets() reports every problem
at once and is called from the lifespan (wired in the next commit).

Deviation from the plan in BUGS.md, which proposed a Pydantic field_validator:
Settings is constructed at import time by every module that reads config,
including the test suite, which has no .env and no business holding real secrets
— a validator there would fail a fresh clone at collection. At startup the
guarantee that matters is unchanged (the server won't serve traffic
half-configured) without coupling imports to a gitignored file. An empty
ADMIN_TOKEN is deliberately non-fatal: require_admin already denies everything,
so the effect is a locked panel, not an open one.

Unhandled errors answer the documented shape (B-24). The catch-all returned a
bare-string `detail` while app/api/errors.py documents
{"code", "message", "params"}, leaving clients to special-case exactly the
responses they understand least. It now returns internal_error in that shape,
with the exception text staying in logs/app.log and out of the response body.

GET /guida no longer crashes (B-16). It reads docs/guida-utente.md, which the
Dockerfile doesn't ship, so in every real deployment that navbar link was a 500 —
confirmed in the deployed log, which holds two of them from earlier today ending
in "RuntimeError: File at path docs/guida-utente.md does not exist." It now
checks the file and answers a structured 404 (guide_unavailable) with an error
logged. Shipping docs/ in the image was written and then reverted on request: the
guide is being reworked first, so /guida answers 404 in Docker for now, which is
an accepted state rather than an oversight.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 00:34:33 +02:00
davideandClaude Opus 5 85dce221c5 Validate admin config and registration input, and log config changes
fee_address was the dangerous one (B-05). PUT /admin/config assigned whatever it
was given, and a well-formed address from another chain (bc1...) parses fine as a
witness program — so every round's 30% commission would be signed and broadcast
to a script nobody holds the key for. A malformed one instead wedged the payout
with an unhandled EmbitError. It now has to pass is_valid_plm_address, the same
check user withdrawals already had. Numeric fields got bounds too:
fee_rate_sat_vb=0 produces transactions no node relays, which stalls bets,
payouts and withdrawals alike, and round_duration_seconds=0 expires a round the
instant it opens.

Config changes are audit-logged (B-10). /pause and /resume were logged but a
config edit wasn't, so the most sensitive setting in the system could be changed
without leaving any trace — contradicting CLAUDE.md, which says audit_log records
what changed. The entry carries a before/after diff per field, computed before
assignment, and no-op updates write nothing. `paused` was removed from
_CONFIG_FIELDS so the maintenance switch has exactly one audited path; it stays
in the response model.

Admin token comparison is constant-time (B-14), with the empty-token check kept
*ahead* of it: compare_digest("", "") returns True, so the obvious ordering would
have opened the panel on any instance without an ADMIN_TOKEN.

Registration input (B-12). It accepted an empty username and a one-character
password while /users/me/change-password demanded 8 — an odd place to be lenient
on a custodial system holding real funds. MIN_PASSWORD_LENGTH moved to
auth/security.py so both share it, and the username is constrained to 3-32 chars
of [A-Za-z0-9_.-]. The IntegrityError handler also distinguishes a username
collision (answers username_taken) from a derivation-index one (retries): a
concurrent duplicate username used to be retried five times and then reported as
derivation_index_conflict, which told the user the wrong thing.

verify_password (B-13) catches VerificationError and InvalidHashError, not just
VerifyMismatchError, so an unparseable stored hash reads as "wrong password"
instead of a 500 — logged as an error, since that one is a data problem.

guida-admin.md gains a table of the audit events worth watching, including
payout_failed, which needs manual intervention.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 00:32:48 +02:00
davideandClaude Opus 5 daf66fd6bc Fix the round-open race, the advertised jackpot, and payout error handling
Round opening (B-09). open_new_round_if_needed now handles the IntegrityError
from ix_rounds_single_active (previous commit) by rolling back and using the
winner's round. Deviation from the plan in BUGS.md, which proposed making the
scheduler the only writer: that would mean the first bet after a cooldown
couldn't open a round, so both callers stay and a bounded retry was added
instead — a conflict where nothing is active yet just means the winner hadn't
committed, and a bet must not fail on that timing. get_active_round also logs
loudly if it ever sees more than one active round rather than silently picking
the newest.

The jackpot (B-11). It was participant_count * the *current* bet_amount_sats,
which overstated the pool (each stored bet is already net of that bet's network
fee) and silently rewrote the advertised jackpot of a round in progress whenever
an operator edited the bet amount. It now sums the participants' stored
bet_amount_sats. The remaining imprecision — the payout tx's own fee, deducted
from the winner's share and unknowable until the payout is built — is documented
in the code rather than promised away, since the comment there claimed exactness.

Payout (B-05, B-18). _trigger_payout is split into read / build+broadcast /
persist, so no DB session is held across a network call (on SQLite that meant
holding the write lock for two unbounded round-trips). That restructuring is also
what makes the error handling placeable: it now catches Exception around the
chain work and writes a payout_failed audit entry, where a malformed fee_address
used to raise EmbitError all the way to the scheduler's catch-all, leaving the
round stuck in paying_out with nothing recorded about why. Automatic payout retry
remains an open gap.

The scheduler also counts "building" participants as in-flight when deciding
whether a round may close, matching the two-phase bet write.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 00:32:22 +02:00
davideandClaude Opus 5 b4d70385a6 Leave dust-sized change to the fee instead of creating it
`if change > 0` created a change output for any leftover at all. Below the
P2WPKH dust threshold (294 sat: the output's 31 vbytes plus the 67 needed to
spend it, at the 3000 sat/kvB dust relay fee) relaying nodes reject the whole
transaction, so the bet or withdrawal failed at broadcast with an error the user
could do nothing about — and which arrived as a 500 (BUGS.md B-06).

Sub-dust change now goes to the fee in both builders, and a sub-dust
recipient/winner/commission amount is refused up front with its own error code.
The fee estimate already assumed two outputs, so dropping one never underpays.

Cross-checked against PalladiumWallet, the source of truth for PLM parameters:
it delegates to NBitcoin's TransactionBuilder (same 294 sat threshold) and has
an explicit test — Un_resto_sotto_la_soglia_dust_viene_assorbito_nella_fee —
asserting the same behaviour, so both the value and the semantics match the
reference implementation.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 00:31:41 +02:00
davideandClaude Opus 5 d528c5b475 Let the system recover from a broadcast that never confirms
The code treated a broadcast as final: money moved on-chain and the DB was
updated on the assumption it would either confirm or be fee-bumped until it
did. Neither is guaranteed, and every way that assumption broke was permanent
(BUGS.md B-02, B-03, B-04, B-07, B-08, B-20, B-21).

Persist before broadcasting. place_bet and request_withdrawal now write their
rows in a "building" state and commit, then broadcast, then promote to
broadcast/pending in a second commit. Before, a failure or crash between the
broadcast and the commit left the coins irreversibly spent with no trace: no
participant (so no entry in the draw), no pending row (so no RBF and no
confirmation tracking), and the UTXOs not even marked spent, so the next bet
would try to double-spend them. A refused broadcast now releases the reserved
UTXOs, restores the balance, removes the participant (or marks the withdrawal
failed), audit-logs it, and answers a translatable broadcast_failed — as 502,
since the network refused it, not the caller, where it used to be an opaque 500.

Reconcile what's in flight against the chain. New PendingTransactionReconciler
(app/tx/reconcile.py, every 120s and once at startup) asks whether each
non-terminal tx exists: present -> promote, gone -> mark failed with a reason,
release the inputs, roll the domain row back, audit-log it. Grace periods differ
by state (120s for "building", 6h for "pending", so the RBF bumper gets its
attempts first). It is deliberately biased to inaction: only a server that
positively doesn't know the tx counts as absent, and a transport failure never
abandons anything, because releasing a UTXO whose tx is actually alive would
invite a double-spend. Verified against the live server, which answers "No such
mempool or blockchain transaction" for an unknown txid.

Stop keying on a value that changes. An RBF bump changes the txid, and
_on_bet_confirmed looked the participant up by bet_txid — so a bumped bet
confirmed under a txid no participant carried, the row stayed "broadcast"
forever, and the scheduler waited on it forever: the round could never close and
the lottery stopped. Handlers now resolve by immutable ids (round_id/user_id,
withdrawal_id), and bump_fee retargets every stored txid — bet_txid,
Withdrawal.txid, Round.payout_txid and UtxoEvent.spent_txid — plus records the
previous one in replaced_by_txid, which was never written at all.

One bad row no longer blocks the rest. The confirmation poller's per-tx lookup
is guarded: a txid the server can't resolve used to abort the whole pass, so
nothing confirmed again until an operator intervened. It also selects plain
columns instead of hydrating entities that outlive their session.

Tests: 6 reconciler cases including "a broken connection must not release coins";
the bet-ordering test probes committed state from an independent session during
the broadcast, and caught a real mistake in the first draft of this change (the
_pending_transaction helper still hardcoded status="pending", so rows were born
already-broadcast and would have got the 6-hour grace instead of 120s).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 00:31:24 +02:00
davideandClaude Opus 5 cc88763a9d Make "one active round" a DB invariant and record why a tx failed
Two schema changes the fixes in the following commits build on (BUGS.md B-09,
B-04):

ix_rounds_single_active is a unique index over the constant expression (1),
restricted to the active statuses, so the table holds any number of closed
rounds and only ever one live one. Rounds never overlapping was previously
enforced only by a read-then-insert in open_new_round_if_needed, which two
concurrent callers can both pass — and a second stuck "open" row blocks every
future round forever, since get_active_round matches on status.

The migration doesn't create that index blind: an instance that already has two
active rounds (the very bug) would fail mid-migration with an opaque
IntegrityError, so it first closes the stale duplicates and keeps the newest —
which is what get_active_round was already doing silently. Verified against a
DB seeded with an 'open' plus a 'closing' round.

pending_transactions.failure_reason is for the reconciler added next: when it
gives up on a transaction, an operator needs to see whether it was dropped or
rejected. The PendingTransaction docstring now also documents the full status
lifecycle (building -> pending -> confirmed | failed), since "building" is new
and load-bearing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 00:30:48 +02:00
davideandClaude Opus 5 9b6a4a240c Give every BUGS.md entry an explicit fix and regression test
The first pass left 11 of the 24 entries with their remedy buried in prose and
only 7 with a named test, while the header claimed a regression test for each.
Every entry now follows one shape: symptom, root cause, *Proposed fix:*,
*Test:* — with the handful that genuinely cannot be unit-tested (Docker image
layout, browser behaviour) marked manual instead of left implied.

A few fixes gained detail while being written out: B-14 needs the empty-token
short-circuit kept ahead of compare_digest, B-15 breaks the current tests'
short JWT secret, B-19 must not update tip_header_hex from a losing header,
and B-20's column ends up holding the previous txid rather than the next one,
so its name is backwards.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-26 22:14:52 +02:00
davideandClaude Opus 5 fb734bb818 Document the 24 bugs found in the full-codebase audit
Adds BUGS.md: a severity-ordered backlog from the 2026-07-26 audit of every
Python module, both static frontends and the Docker/Caddy deployment. Each
entry carries symptom, root cause with file references, reproduction and a
proposed fix, plus the regression test it needs — none of these are covered
by the current suite.

The five critical ones share a root cause worth stating up front: the code
treats a broadcast as final and the Electrum connection as never failing, so
there is no reconciliation between the DB's view and the chain's. That leaves
several states the system only leaves via manual DB edits.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-26 22:10:50 +02:00
48 changed files with 3464 additions and 190 deletions

No files matched your search

+10
View File
@@ -2,6 +2,16 @@ ELECTRUM_HOST=santantonio.sytes.net
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
# 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.
# Example: ELECTRUM_FALLBACK_SERVERS=node2.example.net:50002,node3.example.net:50001:notls
ELECTRUM_FALLBACK_SERVERS=
# Fernet key protecting the master xprv at rest. Generate with:
# python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
XPRV_ENCRYPTION_KEY=
+966
View File
@@ -0,0 +1,966 @@
# Known bugs and required fixes
Full-codebase audit performed on 2026-07-26 against commit `d4e0974` (branch `main`),
covering every Python module under `app/`, both static frontends, and the Docker/Caddy
deployment. The test suite was green at the time of the audit (79 passed), so **none of
the findings below are caught by the existing tests** — every one of them needs a
regression test alongside its fix.
> **Status: 23 of the 24 findings are fully fixed on `main`** as of 2026-07-27, and the
> 24th ([B-16](#b-16)) is fixed as far as the crash goes — shipping the user guide in the
> image was deliberately deferred. Every entry below keeps its original description — the bug, why it
> mattered, and how it was meant to be fixed — and carries a **Fixed:** note recording
> what was actually done and where the regression test lives. The suite grew from 79 to
> 137 tests. Two entries were fixed differently from the plan (B-15 validates at startup
> rather than in a Pydantic validator, B-09 gained a bounded retry); both say so and why.
> The fixes were then run in the real Docker deployment — see
> [Runtime verification](#runtime-verification-2026-07-27) for what that actually
> confirmed and, more importantly, what it did **not**.
Findings are ordered by severity. Each entry is self-contained and follows the same shape:
symptom, root cause with `file:line` references, a `*Proposed fix:*` block, and a `*Test:*`
block naming the regression test to add (a few are marked manual where an automated test
would be testing the Docker image layout or the browser, not the code). Items already listed
under "Known gaps / TODO" in `CLAUDE.md` are cross-referenced rather than repeated, except
where this audit found the gap to be worse than documented.
## Summary
| ID | Severity | Area | One-line |
|----|----------|------|----------|
| [B-01](#b-01) | Critical | Electrum client/listener | A dropped connection hangs the whole server permanently — no reconnect, no request timeout, no keepalive |
| [B-02](#b-02) | Critical | RBF / bets | A fee bump on a bet tx orphans `RoundParticipant.bet_txid`, wedging the round in `closing` forever |
| [B-03](#b-03) | Critical | Confirmation poller | One unresolvable txid aborts confirmation detection for every other pending tx |
| [B-04](#b-04) | Critical | Balance / UTXO state | No reconciliation path: a dropped tx freezes the spent UTXOs (and the user's funds) forever |
| [B-05](#b-05) | Critical | Admin config / payout | `fee_address` and numeric params are unvalidated; a bad value either wedges the payout or sends the commission to an unspendable script |
| [B-06](#b-06) | High | PSBT builder | Change outputs below the dust limit are created, making the transaction unrelayable |
| [B-07](#b-07) | High | Bets / withdrawals | A broadcast rejection surfaces as HTTP 500, bypassing the structured error contract |
| [B-08](#b-08) | High | Bets | Broadcast happens before the bet is persisted: a commit failure loses the money with no record |
| [B-09](#b-09) | High | Rounds | Race allows two simultaneously-`open` rounds, which permanently blocks all future rounds |
| [B-10](#b-10) | High | Admin / audit | `PUT /admin/config` writes no audit-log entry |
| [B-11](#b-11) | High | Rounds API | The displayed jackpot is not the amount the winner receives |
| [B-12](#b-12) | High | Auth | Registration enforces no password or username validation, unlike change-password |
| [B-13](#b-13) | Medium | Auth | `verify_password` turns a malformed stored hash into a 500 instead of a 401 |
| [B-14](#b-14) | Medium | Admin auth | Admin token compared with `!=` instead of a constant-time comparison |
| [B-15](#b-15) | Medium | Config | Empty `JWT_SECRET` / `XPRV_ENCRYPTION_KEY` are not rejected at startup |
| [B-16](#b-16) | Medium | Deployment | `GET /guida` is broken in Docker: `docs/` is never copied into the image (crash fixed; shipping the guide deferred — see entry) |
| [B-17](#b-17) | Medium | RBF | `_find_change_output` can shrink the recipient output instead of the change |
| [B-18](#b-18) | Medium | Scheduler | DB session held open across Electrum network calls during payout |
| [B-19](#b-19) | Medium | Electrum listener | `tip_height` is assigned without a monotonicity check (reorg) |
| [B-20](#b-20) | Low | RBF | `PendingTransaction.replaced_by_txid` is never written — dead column shown in the admin UI |
| [B-21](#b-21) | Low | Confirmation poller | Dead local `pending_ids`, plus attribute access on detached ORM objects |
| [B-22](#b-22) | Low | Frontend | Amounts rendered by raw division — floating-point artefacts visible to users |
| [B-23](#b-23) | Low | Frontend | Concurrent `withLoading` on the same button can leave it stuck on its loading label |
| [B-24](#b-24) | Low | API contract | The global exception handler answers with a bare-string `detail` |
---
## Runtime verification (2026-07-27)
The fixed code was built and run via `docker compose up -d --build` against mainnet. This
section separates what the running system **demonstrated** from what is still only covered
by unit tests — the distinction matters, because a green suite is not a working deployment.
**Caveat on the image that produced this evidence:** it was built while the `Dockerfile`
still carried `COPY docs ./docs`, which was subsequently reverted (see [B-16](#b-16)). The
running container therefore does *not* match the current Dockerfile: `/guida` answers 200
there, and will answer 404 after the next rebuild. Everything else below is unaffected.
### Confirmed at runtime
| Fix | Evidence from the live system |
|---|---|
| [B-15](#b-15) | The app serves traffic, so `validate_runtime_secrets()` passed against the real `.env` — and it is now on the startup path of every deploy. |
| [B-01](#b-01) (partly) | `app.main: Electrum endpoints (in rotation order): santantonio.sytes.net:50002` followed by `app.electrum.listener: Electrum connected to santantonio.sytes.net:50002` — the restructured session setup (`asyncio.wait` over the consumers, `wait_closed()` and the keepalive) connects and stays up against a real server. Only one endpoint is configured, so rotation itself is still only unit-tested. |
| [B-09](#b-09) | `ix_rounds_single_active` exists in the deployed DB and rounds keep opening and closing normally (196 rounds, one per ~98s cycle) — the index and the conflict-retry path do not interfere with normal round creation. |
| [B-04](#b-04) (schema) | The `failure_reason` column is present in the deployed DB; migration `8a1c4e7b2d90` applied cleanly to the live database. |
| [B-04](#b-04) (heuristic) | The one genuinely unknown piece — whether `_tx_exists_on_chain` recognizes a missing tx on *this* server — was tested directly: for a bogus txid the server answers `No such mempool or blockchain transaction`, which the substring check matches, so the function correctly returns `False`. The conservative direction is preserved: any message it does *not* recognize re-raises and leaves the row untouched. |
| [B-16](#b-16) | Confirmed as a bug that had really been firing, not a theoretical one: `logs/app.log` holds two pre-fix `ERROR [app.main] Unhandled error on GET /guida` entries (17:40 and 19:42 on 2026-07-26) ending in `RuntimeError: File at path docs/guida-utente.md does not exist.` |
| No regressions | Zero `ERROR`/`WARNING` lines since the restart on the fixed code. The only errors in the entire log predate it (the two `/guida` failures above, plus two unrelated `asyncio` entries from 2026-07-22). |
### Still unverified outside the test suite
Nothing has spent money since the restart: `pending_transactions` holds only rows that were
already `confirmed` beforehand, `withdrawals` is empty, and no `attempt_count` is above 1.
So these fixes have unit coverage and **no runtime evidence at all**:
- [B-08](#b-08)/[B-07](#b-07) — the two-phase write and the rollback-on-refusal need a real
bet, and a genuinely rejected broadcast, to be seen working.
- [B-02](#b-02)/[B-20](#b-20) — needs an actual RBF bump (`rbf_timeout_seconds` must elapse
with the tx unconfirmed).
- [B-03](#b-03)/[B-04](#b-04) (behaviour) — needs a transaction that really goes missing.
The reconciler has been ticking every 120s with nothing to do, which is silent by design.
- [B-06](#b-06) — needs a UTXO set that produces sub-dust change.
- [B-17](#b-17) — needs a withdrawal attempt; the withdrawal path as a whole has still never
been exercised against a live broadcast, which was already true before this audit.
- [B-22](#b-22)/[B-23](#b-23) — browser-side, verifiable only by using the UI.
### What remains open (not part of the 24)
Unchanged by this work, and still the reason this isn't unattended-safe:
- **Scheduler doesn't resume mid-flight rounds after a restart** — a round left in
`closing`/`drawing`/`paying_out` when the process dies stays stuck. Transaction-level
state now self-heals ([B-04](#b-04)); *round*-level state does not.
- **No automatic payout retry** — a failed payout is audit-logged (`payout_failed`, added by
[B-05](#b-05)) and visible in `/admin`, but acting on it is manual.
- **RBF still handles only the single-change-output case** — the difference is that failure
is no longer permanent: an unbumpable tx is eventually abandoned and its coins released.
- **`/guida` is not served in Docker** by current deliberate decision — the guide is being
reworked; re-adding `COPY docs ./docs` is all it will take.
- **No rate limiting anywhere**, **admin auth is one shared token** with no per-operator
identity, and **single-process assumptions** remain in the SSE broadcaster and the
per-user locks.
- **No automated integration tests against a live Electrum connection** — the verification
in this section was done by hand.
---
## Critical
### B-01
**A dropped Electrum connection hangs the entire server permanently**
*Files:* `app/electrum/client.py:31-63`, `app/electrum/client.py:85-99`, `app/electrum/listener.py:58-77`
Three independent defects compose into a single absorbing failure state:
1. **The read loop's death never propagates.** `connect()` spawns `_read_loop` as a
detached task. When the socket closes, `readline()` returns `b""`, the loop breaks and
the task completes — but `_run_once` is blocked on
`asyncio.gather(self._consume_headers(...), self._consume_scripthash(...))`, and both
consumers are awaiting `asyncio.Queue.get()` on queues nobody will ever fill again.
The `gather` never returns and never raises, so the `except Exception` +
backoff-reconnect logic in `ElectrumListener.run()` is never reached.
2. **`self.client` stays non-`None`.** Every consumer of the client
(`RoundScheduler`, `ConfirmationPoller`, `RbfBumper`, `place_bet`,
`request_withdrawal`, and the `listener.client is None` guards in the bet/withdrawal
routes) therefore keeps treating a dead connection as live.
3. **`request()` has no timeout.** It registers a future in `self._pending`, writes to a
closed writer (`drain()` frequently does not raise on a half-closed socket) and then
`await future` — which nothing will ever resolve, because `_read_loop` is gone. Note
that `_read_loop`'s `finally` only fails the futures that existed at the moment it
died; every future created afterwards hangs forever.
There is also **no keepalive** (`server.ping`) anywhere. Electrum servers routinely drop
idle connections after ~10 minutes, so on a low-traffic instance this is close to
guaranteed rather than hypothetical.
*Observable consequences:* deposits stop being credited; the tip stops advancing, so a
round in `drawing` waits in `_wait_for_next_block` forever; `ConfirmationPoller` blocks
on its first `get_transaction` and stops polling entirely; a `POST /bets` request hangs
indefinitely **while holding that user's `UserLocks` entry**, so every later bet or
withdrawal from the same user deadlocks behind it.
*Reproduction:* start the app, kill the TCP connection out from under it
(`ss -K dst <electrum-host>`, or block the port with a firewall rule). No reconnect log
line is emitted, `/rounds/current` keeps reporting the last known `chain_tip_height`, and
a bet request never returns.
*Proposed fix:*
- Wrap every `request()` in `asyncio.wait_for(...)` with an explicit timeout (10-15s) and
pop the future from `self._pending` on timeout.
- Add a keepalive task issuing `server.ping` every ~60s; a failed ping tears the
connection down.
- Make the read loop's termination observable: either include `self._read_task` in
`_run_once`'s `gather`, or set an `asyncio.Event` in `_read_loop`'s `finally` that
`_run_once` awaits alongside the consumers. On teardown, set `self.client = None`
*before* awaiting the reconnect backoff.
*Test:* a unit test with a fake stream that closes mid-session must observe
`listener.client is None` and a reconnect attempt; a test that `request()` raises
`ElectrumError`/`TimeoutError` rather than hanging when no response arrives.
**Fixed.** `app/electrum/client.py` now bounds every `request()` with
`asyncio.wait_for` (`_REQUEST_TIMEOUT_SECONDS = 15`), pops the orphaned future and tears
the connection down on timeout; `_read_loop`'s `finally` sets a `_closed` event, exposed
as `wait_closed()`; and `ping()` was added. `app/electrum/listener.py:_run_once` races the
two notification consumers against `wait_closed()` and a 60s keepalive with
`asyncio.wait(FIRST_COMPLETED)`, so a drop ends the session and `run()` reconnects.
`self.client` is cleared before the reconnect, so callers stop using a dead client.
Beyond the original finding, the listener now **rotates over a list of servers**
(`ELECTRUM_FALLBACK_SERVERS`, `parse_endpoints`): one dead server costs a single attempt
instead of an outage, and the backoff only sleeps once every server has had a turn.
Tests: `tests/unit/test_electrum_client.py` (timeout, `wait_closed`, pending-request
failure, endpoint parsing), `tests/unit/test_electrum_listener.py` (rotation, backoff
reset, no-endpoints case).
### B-02
**An RBF fee bump on a bet permanently wedges the round**
*Files:* `app/tx/broadcast.py:116-121`, `app/bets/confirmation.py:10-16`,
`app/rounds/scheduler.py:77-86`, `app/rounds/scheduler.py:92-98`
`bump_fee` rebuilds the transaction, which changes its txid, and updates
`PendingTransaction.current_txid` accordingly. Nothing updates the domain row's copy of
that txid: `RoundParticipant.bet_txid` is written exactly once, at
`app/bets/service.py:80`, and never again (verified by grepping every write to
`bet_txid`).
When the bumped transaction confirms, `_on_bet_confirmed` looks the participant up by
`RoundParticipant.bet_txid == pending.current_txid`, finds nothing, and returns silently.
Consequences, in order:
- the participant stays `status == "broadcast"` forever;
- `RoundScheduler._tick` counts participants in `"broadcast"` before allowing the round to
close, so the round stays in `closing` **indefinitely**;
- since a new round cannot open while one is active (`get_active_round`), the entire
lottery stops;
- even if the round were forced closed, `_close_and_draw` only selects
`status == "confirmed"` participants, so that player would have paid the bet without
entering the draw.
The same staleness affects `Withdrawal.txid`. It is less severe there, because
`_on_withdrawal_confirmed` keys off `pending.withdrawal_id`, so the status does update —
but the txid stored and shown to the user is the replaced one.
*Reproduction:* place a bet, let `rbf_timeout_seconds` elapse without confirmation so
`RbfBumper` bumps it, then let the bumped tx confirm. `round_participants.status` remains
`broadcast`; the round never leaves `closing`.
*Proposed fix:* make the bump update the domain row too. Either have `bump_fee` write
through to `RoundParticipant.bet_txid` / `Withdrawal.txid` (it already knows `kind`,
`user_id`, `round_id`, `withdrawal_id`), or — cleaner — stop keying confirmation handlers
on the txid at all: `_on_bet_confirmed` should resolve the participant via
`pending.round_id` + `pending.user_id`, which are immutable. Also set
`replaced_by_txid` (see [B-20](#b-20)) so the chain of replacements is auditable.
*Test:* bump a pending bet, then run the confirmation handler with the new txid and assert
the participant flips to `confirmed`.
**Fixed.** Both confirmation handlers now resolve their domain row by immutable
ids — `_on_bet_confirmed` by `(round_id, user_id)`, `_on_payout_confirmed` by `round_id` —
with the old txid lookup kept only as a fallback for pre-existing rows. Independently,
`bump_fee` calls a new `_retarget_txid_references()` that updates
`RoundParticipant.bet_txid`, `Withdrawal.txid`, `Round.payout_txid` **and**
`UtxoEvent.spent_txid` to the new txid, so no stored txid is left pointing at a
transaction that no longer exists. Tests:
`test_confirmation.py::test_bet_confirms_after_an_rbf_bump_changed_the_txid` (plus the
payout equivalent), `test_broadcast.py::test_bump_fee_retargets_every_stored_txid`.
### B-03
**One unresolvable txid stops confirmation detection for everything else**
*File:* `app/tx/confirmation.py:35-37`
```python
for pending_id, txid, kind in [...]:
tx = await client.get_transaction(txid, verbose=True) # not guarded
```
If a txid is no longer knowable by the server — dropped from the mempool, replaced by an
RBF bump whose old entry is still `pending`, or simply an Electrum server that answers
with an error — `ElectrumError` propagates out of `poll_once` and **aborts the loop before
the remaining pending transactions are checked**. `ConfirmationPoller.run` logs it and
retries every 10s, failing at the same row every time.
Because the poller is the single mechanism that confirms bets, payouts and withdrawals,
one stuck row means: no bet ever confirms again (so no round ever closes — see
[B-02](#b-02)), no payout ever completes, no withdrawal ever settles. Recovery requires
manual DB surgery.
*Proposed fix:* wrap the per-transaction lookup in `try/except Exception`, log at
`warning` with the txid, and `continue`. Optionally track consecutive failures per row so
a permanently-unknown tx can be escalated to an operator (which is also the hook
[B-04](#b-04) needs).
*Test:* `poll_once` with two pending rows where the first raises must still confirm the
second and return `1`.
**Fixed.** The per-transaction lookup in `poll_once` is wrapped in
`try/except Exception`: it logs the txid at warning level and continues, leaving the
judgement about a permanently-unknown tx to the reconciler ([B-04](#b-04)). Test:
`test_confirmation.py::test_one_unresolvable_txid_does_not_block_the_others`, which
asserts the healthy row still confirms and the unknown one is left `pending` rather than
abandoned here.
### B-04
**No reconciliation: a dropped transaction freezes the spent UTXOs forever**
*Files:* `app/bets/service.py:69-73`, `app/withdrawals/service.py:65-68`,
`app/wallet/balance.py:9-18`
`spent_txid` is set optimistically at broadcast time and is **never cleared anywhere in
the codebase**. `recompute_balance` only sums UTXOs with `spent_txid IS NULL`, so those
coins are permanently excluded from the user's balance.
If the transaction never confirms and eventually disappears from the mempool — which
`CLAUDE.md` already acknowledges is a realistic outcome, since the RBF path raises
`RbfError` and gives up whenever there is no change output large enough to absorb the
bump — the UTXOs remain perfectly spendable on-chain while the database considers them
gone. The user's funds are silently lost from their point of view.
More broadly, nothing in the system ever writes a terminal failure state: there is no
`status = "failed"` on `PendingTransaction`, `Withdrawal` or `RoundParticipant`, and no
startup routine that re-scans in-flight transactions against the chain. Combined with
`restart: unless-stopped` and the already-documented scheduler-resume gap, the system has
several states it can only be pulled out of by hand.
*Proposed fix:* add a reconciliation task (and run it once at startup) that, for every
`PendingTransaction` in `pending` older than some threshold, asks the chain whether the
tx exists. If it is gone:
- mark the row `failed`, and set `replaced_by_txid`/a failure reason;
- clear `spent_txid` on the UTXOs it consumed (they are identifiable by parsing
`raw_tx_hex`'s inputs);
- call `recompute_balance`;
- roll the domain row back (delete the `RoundParticipant`, mark the `Withdrawal`
`failed`) and audit-log the event.
*Test:* given a pending bet whose tx is unknown to the chain, the reconciler must restore
the user's balance and remove the participant.
**Fixed** by a new component, `app/tx/reconcile.py`
(`PendingTransactionReconciler`, started from the lifespan and running every 120s,
including once at startup). Per non-terminal `PendingTransaction` it asks the chain
whether the tx exists: a `building` row whose tx is there gets promoted, a row whose tx is
gone is marked `failed` with a `failure_reason` (new column), its inputs released
(`spent_txid` cleared, only where it still matches this row's txid), the balance
recomputed, and the domain row rolled back — participant deleted, withdrawal marked
`failed`, payout txid cleared. Grace periods differ by state (120s for `building`, 6h for
`pending`) and a transport failure never abandons anything. Tests:
`tests/unit/test_reconcile.py` (6 cases, including the "broken connection must not release
coins" one).
### B-05
**`fee_address` and the numeric config params are unvalidated**
*File:* `app/api/routes/admin.py:70-80`, consumed at `app/rounds/scheduler.py:162-198`
`PUT /admin/config` assigns whatever it is given straight onto the `RoundConfig` row. Two
distinct failure modes:
1. **Malformed `fee_address`** → `build_payout_transaction` calls
`script.Script.from_address(fee_address)`, which raises `EmbitError`. `_trigger_payout`
only catches `InsufficientFundsError`, so the exception escapes through
`_close_and_draw` up to the `except Exception` in `RoundScheduler.run()`. The round is
left in `paying_out` with no retry (the payout-retry gap in `CLAUDE.md`), i.e. wedged.
2. **Well-formed but foreign `fee_address`** (e.g. a Bitcoin `bc1...`) → this is *worse*,
because it parses fine into a valid witness program. The payout is built, signed and
broadcast, and the 30 % commission of every round lands on a script nobody holds the
key for. This is exactly the failure mode `app/wallet/address.py` was written to
prevent for user withdrawals; the check was never applied to the operator-supplied
address.
Numeric fields are equally unguarded: `round_duration_seconds = 0` (round expires the
instant it opens), `fee_rate_sat_vb = 0` (fee-less transactions are never relayed, so
every bet/payout hangs and the whole pipeline stalls), negative `bet_amount_sats`,
`draw_animation_seconds` far larger than the round itself.
*Proposed fix:* validate in `RoundConfigUpdate` (Pydantic `field_validator` /
`Field(gt=0)`):
- `fee_address` must pass `is_valid_plm_address`;
- `bet_amount_sats`, `round_duration_seconds`, `fee_rate_sat_vb`, `rbf_timeout_seconds`
strictly positive, with sane upper bounds;
- `round_cooldown_seconds`, `draw_animation_seconds` non-negative.
Independently, `_trigger_payout` should catch `Exception` around the build/broadcast,
audit-log the failure, and leave the round in a state a retry routine can pick up.
*Test:* `PUT /admin/config` with a `bc1...` fee address and with `fee_rate_sat_vb = 0`
must both return 422/400 and leave the stored config untouched.
**Fixed.** `RoundConfigUpdate` now validates: `fee_address` must pass
`is_valid_plm_address`, and every numeric field carries bounds (`fee_rate_sat_vb >= 1`,
`round_duration_seconds >= 30`, etc.). Separately `_trigger_payout` catches `Exception`
around the build/broadcast, logs it and writes a `payout_failed` audit entry so a stuck
round is visible in `/admin` rather than only in the log file. Automatic payout retry
remains an open pre-existing gap (documented in CLAUDE.md), unchanged by this fix. Test:
`test_admin.py::test_config_rejects_unusable_values`, parameterized over the `bc1…`
address, a broken checksum, `fee_rate_sat_vb=0`, `round_duration_seconds=0` and more.
---
## High
### B-06
**Dust change outputs are created**
*File:* `app/wallet/psbt_builder.py:98-99` and `:166-167`
Both builders use `if change > 0:` as the sole condition for adding the change output. Any
leftover below the P2WPKH dust threshold (~294 sat at the standard 3000 sat/kvB dust
relay fee) produces a transaction that relaying nodes reject outright as `dust`. The
resulting `ElectrumError` is unhandled (see [B-07](#b-07)), so the user gets an opaque
HTTP 500 and cannot bet or withdraw at all until their UTXO set happens to change.
*Proposed fix:* introduce a `DUST_LIMIT_SATS` constant; add the change output only when
`change >= DUST_LIMIT_SATS`, otherwise leave the remainder to the fee (and reflect that in
the returned `fee_sats`/`change_sats` so the accounting stays honest). Note the fee
estimate at `psbt_builder.py:86` already assumes two outputs unconditionally, so dropping
change does not underpay.
*Test:* build a transaction whose change lands at 100 sat and assert a single-output tx
with the remainder folded into the fee.
**Fixed.** `DUST_LIMIT_SATS = 294` added to `app/wallet/psbt_builder.py`; both
builders fold sub-dust change into the fee instead of creating the output, and refuse a
sub-dust recipient/winner/commission amount with a dedicated error code. Tests in
`test_psbt_builder.py`: dust change folded into the fee (asserting nothing vanishes —
inputs still equal outputs plus fee), change exactly at the limit still paid back, and a
dust-sized recipient refused.
### B-07
**Broadcast failures surface as HTTP 500**
*Files:* `app/bets/service.py:67`, `app/withdrawals/service.py:63`
`await client.broadcast(built.raw_hex)` is not guarded. Every node-side rejection —
fee below the relay minimum, dust output ([B-06](#b-06)), mempool conflict, non-standard
tx — raises `ElectrumError`, which the global handler in `app/main.py:74-77` turns into
`{"detail": "internal server error"}`. That bypasses the whole error contract documented
in `app/api/errors.py`: no `code`, nothing translatable, no actionable message.
*Proposed fix:* wrap the broadcast, and raise
`BetError("broadcast_failed", ...)` / `WithdrawalError("broadcast_failed", ...)` carrying
the node's message in `params`. Add `error.broadcast_failed` to all 7 languages in
`app/static/i18n.js` (per the i18n contract in `CLAUDE.md`). Answer 502/503 rather than
400, since the failure is not the client's fault.
*Test:* `place_bet` / `request_withdrawal` with a client stub whose `broadcast` raises must
raise `BetError`/`WithdrawalError` with code `broadcast_failed` — and must leave no
`spent_txid`, no participant and no pending row behind.
**Fixed.** Both services wrap the broadcast and raise
`BetError`/`WithdrawalError("broadcast_failed", …)`; the routes answer **502** rather than
400, since the network refused it, not the caller. `error.broadcast_failed` was added to
all 7 languages in `i18n.js` (along with `amount_below_dust_limit`,
`withdrawal_to_own_address`, `internal_error`, `guide_unavailable`) — key parity verified,
123 keys per language. Tests:
`test_bets.py::test_failed_broadcast_reports_the_broadcast_failed_code` and the withdrawal
equivalent.
### B-08
**Bets are broadcast before they are persisted**
*File:* `app/bets/service.py:67-94`
The order today is: broadcast → mutate `spent_txid` → insert `RoundParticipant` +
`PendingTransaction` → `commit()`. If the commit fails, or the process dies in that
window, the transaction is already irreversibly on the chain: the money has moved to the
pool address, but **no record of the bet exists** — no participant (so no entry in the
draw), no pending row (so no RBF, no confirmation tracking), and the UTXOs are not even
marked spent, so the next bet attempt will try to double-spend them.
The same shape exists in `request_withdrawal`, where the `Withdrawal` row is flushed
before broadcast but only committed after.
*Proposed fix:* persist the intent first. Insert the `PendingTransaction` (and the
`RoundParticipant`) in a `building`/`unbroadcast` state, commit, then broadcast, then flip
to `broadcast` in a second commit. A crash between the two leaves a row the
reconciliation task from [B-04](#b-04) can resolve against the chain in either direction.
*Test:* with a client stub that broadcasts successfully but a session whose second commit
raises, the `PendingTransaction` must still exist afterwards (in its pre-broadcast state)
rather than the bet vanishing entirely.
**Fixed.** Both `place_bet` and `request_withdrawal` are now two-phase: write
the rows in a `building` state and commit, *then* broadcast, then promote to
`broadcast`/`pending` in a second commit. A failed broadcast runs a release helper that
frees the reserved UTXOs, restores the balance, removes the participant (or marks the
withdrawal `failed`) and audit-logs it. A crash between the phases leaves a `building` row
for the reconciler ([B-04](#b-04)) to resolve either way. Tests:
`test_bets.py::test_bet_is_persisted_before_it_is_broadcast` — which probes committed state
from an independent session *during* the broadcast, and which caught a real mistake in the
first draft of this fix (the `_pending_transaction` helper still hardcoded
`status="pending"`, so rows were born already-broadcast and would have got the reconciler's
6-hour grace instead of 120s) — plus the two rollback tests.
### B-09
**Two rounds can be opened concurrently, blocking every future round**
*File:* `app/rounds/service.py:44-60`
`open_new_round_if_needed` performs a read (`get_active_round`) followed by an insert with
no lock and no database-level uniqueness guarantee, and it is called both from
`RoundScheduler._tick` and from **every** `place_bet`. Two concurrent callers can both
observe "no active round" and both insert a row with `status="open"`.
`get_active_round` then quietly hides the problem — `select(...).order_by(Round.id.desc())`
+ `scalar()` returns only the newest — while the older round stays `open` forever, never
ticked, never closed. Since `get_active_round` matches on status, no further round can
ever open once the newer one closes: the lottery stops for good.
*Proposed fix:* the simplest robust option is to make the `RoundScheduler` the only writer
and have `place_bet` merely read the active round (rejecting the bet if there is none —
the scheduler opens one within 5s anyway). Additionally add a DB guard: a partial unique
index over `status IN ('open','closing','drawing','paying_out')`, or an advisory/serialized
transaction around the read-then-insert. `get_active_round` should also log loudly if it
ever sees more than one row.
*Test:* two concurrent `open_new_round_if_needed` calls on separate sessions must yield
exactly one round.
**Fixed** at the database level: `ix_rounds_single_active`, a unique index over
the constant expression `(1)` restricted to the active statuses (model +
migration `8a1c4e7b2d90`, which first closes any pre-existing duplicates, keeping the
newest — verified against a DB seeded with two active rounds). `open_new_round_if_needed`
catches the resulting `IntegrityError`, rolls back and returns the winner's round.
**Deviation from the plan:** rather than making the scheduler the only writer (which would
have meant the first bet after a cooldown couldn't open a round), it keeps both callers and
adds a bounded retry — a conflict where nothing is active yet means the winner simply
hadn't committed, and a bet must not fail on that timing. `get_active_round` also logs
loudly if it ever sees more than one active round. Tests in `test_rounds_service.py`: the
race-recovery path (forced deterministically by making the first look miss the existing
round — real concurrency on a shared in-memory SQLite connection isn't isolated enough to
test this honestly), the DB refusing a second active round, and closed rounds coexisting
with an active one.
### B-10
**`PUT /admin/config` writes no audit-log entry**
*File:* `app/api/routes/admin.py:70-80`
`/admin/pause` and `/admin/resume` both call `write_audit_log`; the config update — which
can change `fee_address` (where 30 % of every pool goes), `bet_amount_sats` and the fee
rate — writes nothing. This contradicts `CLAUDE.md`, which states that `audit_log`
records *what* changed (only the *who* is documented as missing).
Secondary issue: `paused` is part of `_CONFIG_FIELDS`, so it can be toggled through
`PUT /config`, silently bypassing the deliberately audit-logged `pause`/`resume`
endpoints.
*Proposed fix:* write a `config_updated` audit entry containing the changed fields as
`{field: {"from": old, "to": new}}` — computed before assignment. Remove `paused` from
`_CONFIG_FIELDS` (keep it in the response model) so the pause switch has exactly one
audited path.
*Test:* `PUT /admin/config` changing `fee_address` must produce exactly one
`config_updated` audit row carrying both the old and the new value; `paused` must be
rejected (or ignored) on that endpoint.
**Fixed.** `PUT /admin/config` computes a before/after diff and writes a
`config_updated` audit entry (`{field: {"from": …, "to": …}}`), skipping no-op updates.
`paused` was removed from `_CONFIG_FIELDS` so the maintenance switch has exactly one
audited path (`/admin/pause`, `/admin/resume`); it remains in the response model. Tests:
`test_admin.py::test_config_update_is_audit_logged`, the no-op case, and
`test_pause_cannot_be_toggled_through_the_config_endpoint`.
### B-11
**The displayed jackpot is not what the winner receives**
*File:* `app/api/routes/rounds.py:118-144`
```python
pool_amount_sats = participant_count * config.bet_amount_sats
jackpot_sats = pool_amount_sats * 70 // 100
```
Three independent divergences from the amount actually paid out:
1. The real pool is `sum(p.bet_amount_sats)`, and each participant's `bet_amount_sats` is
`recipient_sats` — the bet amount **minus that bet's network fee**
(`psbt_builder.build_signed_transaction`).
2. The payout deducts its own network fee from the winner's 70 % share
(`build_payout_transaction`), so the winner receives strictly less than 70 % of the
pool.
3. `participant_count` counts every `RoundParticipant` row, including bets still in
`broadcast` that may never confirm — and those are excluded from the draw and the pool
by `_close_and_draw`.
Plus: it multiplies by the *current* `bet_amount_sats`, which an operator can change
mid-round, retroactively changing the advertised jackpot of a round already in progress.
The in-code comment explicitly promises "what's displayed should match what the winner
actually receives", which is the opposite of the behaviour.
*Proposed fix:* compute the pool from the participants' stored `bet_amount_sats`
(optionally restricted to `confirmed`), derive the 70 % share from that, and either
subtract an estimated payout fee or relabel the field as an estimate in the UI. Keep
`participant_count` as-is for display but consider exposing `confirmed_count` separately.
*Test:* with two confirmed participants whose stored `bet_amount_sats` is below the
configured `bet_amount_sats` (fee already deducted), `GET /rounds/current` must report a
`jackpot_sats` derived from the stored amounts, and must not change when
`RoundConfig.bet_amount_sats` is edited mid-round.
**Fixed.** `GET /rounds/current` now sums the participants' stored
`bet_amount_sats` (each already net of its own bet's fee) instead of multiplying
`participant_count` by the current configured amount. The remaining, unavoidable
imprecision — the payout tx's own fee, deducted from the winner's share and unknowable
until the payout is built — is documented in the code rather than silently promised away.
Test: `test_rounds_route.py::test_jackpot_comes_from_the_participants_actual_bets`, which
also asserts that editing `bet_amount_sats` mid-round no longer moves a running round's
jackpot.
### B-12
**Registration has no password or username validation**
*File:* `app/auth/routes.py:18-56`
`POST /users/me/change-password` enforces `_MIN_PASSWORD_LENGTH = 8`
(`app/api/routes/users.py:15`), and the frontend re-checks it. `POST /auth/register`
enforces nothing: an empty username and a one-character password are both accepted, and
there is no `minlength` on the registration inputs in `app/static/index.html` either. On a
custodial system holding real funds, this is the wrong default.
Secondary defect in the same handler: the `_MAX_REGISTER_RETRIES` loop catches *any*
`IntegrityError`. A username collision that slips past the pre-check (concurrent
registration) is therefore retried five times and finally reported as
`derivation_index_conflict`, which is misleading for both the user and the operator.
*Proposed fix:* validate `username` (length, allowed character set) and `password`
(shared minimum-length constant, reused by `users.py`) in `RegisterRequest`; mirror the
constraints in the HTML form. Inspect the `IntegrityError` and re-raise `username_taken`
when it is the username constraint that failed.
*Test:* `POST /auth/register` with an empty username and with a 3-character password must
both be rejected (422/400) and create no user; a registration racing an existing username
must answer `username_taken`, not `derivation_index_conflict`.
**Fixed.** `MIN_PASSWORD_LENGTH` moved to `app/auth/security.py` and is now
shared by registration and the password change, so the two can't drift. `RegisterRequest`
constrains username (3–32 chars, `[A-Za-z0-9_.-]`) and password; the HTML form mirrors it
with `minlength`/`pattern`/`required`, and `register()` pre-checks the length so the
failure is immediate and translated. The `IntegrityError` handler now distinguishes a
username collision (answers `username_taken`) from a derivation-index collision (retries).
Tests: `test_users.py::test_register_rejects_weak_credentials` (parameterized) and the
positive case.
---
## Medium
### B-13
**A malformed stored hash becomes a 500 instead of a 401**
*File:* `app/auth/security.py:16-20`
`verify_password` catches only `VerifyMismatchError`. Argon2 raises `InvalidHashError` for
a hash it cannot parse and `VerificationError` for other verification failures, both of
which escape as an unhandled 500.
*Proposed fix:* catch `argon2.exceptions.VerificationError` (the superclass of
`VerifyMismatchError`) plus `InvalidHashError` and return `False`, so an unusable stored
hash reads as "wrong password" rather than as a server fault.
*Test:* `verify_password("x", "not-a-hash")` returns `False`; `POST /auth/login` against a
user row with a corrupted `password_hash` answers 401.
**Fixed.** `verify_password` catches `VerificationError` (the superclass of
`VerifyMismatchError`) and `InvalidHashError` separately, returning `False` in both cases
and logging the unparseable-hash case as an error, since that one is a data problem worth
noticing. Tests: `test_security.py::test_verify_password_returns_false_for_an_unparseable_hash`,
plus one confirming a genuinely wrong password is still rejected.
### B-14
**Admin token compared non-constant-time**
*File:* `app/api/routes/admin.py:20-22`
`x_admin_token != settings.admin_token` is a short-circuiting comparison. This token gates
the private-key export endpoint, so it deserves a constant-time comparison.
*Proposed fix:* `secrets.compare_digest(x_admin_token, settings.admin_token)`, keeping the
existing "empty configured token means always deny" short-circuit *before* it (compare_digest
on two empty strings returns `True`).
*Test:* the existing admin auth tests still pass, plus one asserting an empty
`ADMIN_TOKEN` setting denies an empty `X-Admin-Token` header.
**Fixed.** `require_admin` uses `secrets.compare_digest`, with the
empty-configured-token check kept *ahead* of it — `compare_digest("", "")` returns `True`,
so the original order would have opened the admin panel on any instance without an
`ADMIN_TOKEN`. Covered by the existing admin auth tests.
### B-15
**Empty secrets are not rejected at startup**
*File:* `app/config.py:13-18`
`jwt_secret` and `xprv_encryption_key` both default to `""`. With an empty `JWT_SECRET`,
PyJWT raises `InvalidKeyError: HMAC key must not be empty` on every login and
registration — a 500 with no hint about the real cause (verified locally). With an empty
`XPRV_ENCRYPTION_KEY`, Fernet fails on the first key derivation instead. Either way the
container starts up healthy and only fails once a user touches the broken path.
*Proposed fix:* a Pydantic `field_validator` (or `model_validator`) on `Settings` rejecting
empty `jwt_secret`/`xprv_encryption_key`, with a minimum length on `jwt_secret` (32 bytes,
per the `InsecureKeyLengthWarning` PyJWT already emits in the test suite). The process must
refuse to boot instead of half-working. Note the tests currently rely on a short secret, so
they need updating alongside.
*Test:* constructing `Settings(jwt_secret="")` raises `ValidationError`.
**Fixed**, but **not as planned.** A Pydantic `field_validator` on `Settings`
would have run at import time in every module that reads config — including the whole test
suite, which has no `.env` — so a fresh clone would have failed at collection. Instead
`validate_runtime_secrets()` (in `app/config.py`) is called from the app's lifespan: the
server still refuses to serve half-configured, without coupling imports to a gitignored
file. It reports all problems at once and treats an empty `ADMIN_TOKEN` as non-fatal
(`require_admin` already denies everything, so the effect is a locked panel, not an open
one). Tests: `tests/unit/test_config.py` (6 cases, using `_env_file=None` so a developer's
real `.env` can't influence the result).
### B-16
**`GET /guida` is broken in Docker**
*Files:* `Dockerfile:38-42`, `app/main.py:98-103`
The image copies `pyproject.toml`, `app/`, `migrations/`, `alembic.ini` and `scripts/`.
`docs/` is never copied (it is not in `.dockerignore` — it is simply not `COPY`-ed), so
`FileResponse("docs/guida-utente.md")` raises inside the container and the help link in
the navbar returns a 500 in every real deployment.
*Proposed fix:* add `COPY docs ./docs` to the `Dockerfile` (treating the guide as a shipped
asset), or move the guide under `app/static/` and serve it from there. Whichever is chosen,
`GET /guida` should degrade to a 404 with a clear message rather than an unhandled
exception when the file is absent.
*Test:* not unit-testable as-is (it depends on the image layout) — verify with
`docker compose up -d --build && curl -k https://localhost/guida`, and add that check to
`docs/running-the-server.md`'s smoke list.
**Partially fixed, by explicit decision.** The crash is gone: `GET /guida` checks
the file exists and answers a structured 404 (`guide_unavailable`, translated in all 7
languages) with an error logged, instead of raising and returning a 500.
Shipping `docs/` in the image (`COPY docs ./docs`) was written and then **reverted at the
owner's request** — the user guide is going to be reworked first, so there is no point
baking the current one into the image. Net effect today: in Docker, `/guida` answers 404
rather than serving the guide, and the navbar link leads nowhere useful. That is a known,
accepted state, not an oversight; adding the `COPY` line is all it takes once the guide is
ready. Verification once it is: `docker compose up -d --build && curl -k https://localhost/guida`.
### B-17
**`_find_change_output` can shrink the recipient output**
*File:* `app/tx/broadcast.py:59-63`
It returns the *first* output whose address matches the sender's own address. Nothing
prevents a withdrawal to the user's own address (`request_withdrawal` never compares
`external_address` with `user.address`), in which case output 0 is the recipient and
output 1 is the change — and a fee bump would reduce the recipient output. The same case
makes `compute_pending_balance` (`app/wallet/balance.py:55-59`) count both outputs, so the
displayed pending balance double-counts the withdrawn amount.
*Proposed fix:* reject a withdrawal whose destination is the user's own address (a
distinct error code — it is a user mistake, not a system limit), and/or identify the
change output by index rather than by address, recording it on `PendingTransaction` at
build time.
*Test:* `request_withdrawal` to `user.address` is rejected; and given a hand-built tx with
two outputs to the same address, the bump reduces the *change* one (the last), leaving the
recipient amount untouched.
**Fixed.** `request_withdrawal` rejects a destination equal to the user's own
deposit address with its own error code — it was a no-op that cost a fee, and it was the
only way for the recipient and change outputs to be indistinguishable by address (which
would have made a fee bump shrink the recipient output, and made
`compute_pending_balance` count the amount twice). Test:
`test_withdrawals.py::test_withdrawal_to_own_address_is_rejected`, which also asserts no
UTXO was touched.
### B-18
**DB session held open across Electrum network calls during payout**
*File:* `app/rounds/scheduler.py:162-220`
`_trigger_payout` opens a session and, inside it, awaits `client.listunspent(...)` and
`client.broadcast(...)` before committing. On SQLite that holds the write lock for the
duration of two network round-trips (unbounded, per [B-01](#b-01)); on Postgres it becomes
a long-running transaction.
*Proposed fix:* restructure into three phases — read config/winner and close the session →
do the network work (`listunspent`, build, `broadcast`) → reopen a session to persist the
result and the `PendingTransaction`. This also makes the [B-05](#b-05) error handling
easier to place, since the failure-prone part is no longer inside a transaction.
*Test:* the existing payout tests must still pass; add one asserting no session is open
while the stub client's `broadcast` is being awaited (e.g. by having the stub attempt a
write through a second session).
**Fixed.** `_trigger_payout` is now explicitly three phases — read (session
closed), build+broadcast, persist — so no session is held across a network call. The
restructuring is also what made [B-05](#b-05)'s error handling easy to place, since the
failure-prone part is no longer inside a transaction. Covered by the existing scheduler
tests.
### B-19
**`tip_height` is assigned without a monotonicity check**
*File:* `app/electrum/listener.py:92-101`
`self.tip_height = header["height"]` accepts a lower height on a reorg. Since
`_wait_for_next_block` compares `self._listener.tip_height <= tip_at_close`, a regression
silently extends the wait by a block.
*Proposed fix:* full reorg handling is out of scope for v1 by explicit design decision, but
the assignment should be guarded: keep `max(self.tip_height, header["height"])` and log a
warning when a header arrives with a lower height, so the condition is at least visible in
the logs when it happens. Do not update `tip_header_hex` from a header that loses this
comparison, or height and hash would describe different blocks.
*Test:* feeding the consumer a header at height N then N-1 leaves `tip_height == N` and the
hash unchanged.
**Fixed.** Header handling moved into `_apply_header()`, which refuses a height
below the current tip, logs a warning when that happens, and applies height and hex
together — a losing header's hex must not be stored, since that hex is the draw's entropy
source and a mismatched pair would be worse than a stale one. Test:
`test_electrum_listener.py::test_tip_never_moves_backwards`.
## Low / hygiene
### B-20
**`replaced_by_txid` is never written**
*Files:* `app/db/models.py:119`, `app/tx/broadcast.py:116-120`,
`app/api/routes/admin.py:261`
`bump_fee` overwrites `current_txid` in place and never records what the old txid was. The
column exists, is selected, and is rendered in the admin "Transazioni pendenti" table,
where it therefore always shows `—`.
*Proposed fix:* set it in `bump_fee` (naturally part of the [B-02](#b-02) fix) so the
replacement chain is auditable. Note the column semantics are the reverse of what the name
suggests for an in-place update — it will hold the *previous* txid, so either rename it
(`previous_txid`, via a migration) or document the direction on the model.
*Test:* after a bump, the row's `replaced_by_txid` holds the pre-bump txid and
`current_txid` the new one.
**Fixed.** `bump_fee` records the pre-bump txid in `replaced_by_txid`. The
model now documents that the column points *backwards* despite its name (renaming it would
need a migration and would churn the admin UI; the direction is stated on the field
instead). Test: covered by
`test_broadcast.py::test_bump_fee_retargets_every_stored_txid`.
### B-21
**Dead code and detached-object access in the confirmation poller**
*File:* `app/tx/confirmation.py:29-35`
`pending_ids` (line 32) is computed and never used. Line 35 rebuilds the same tuples from
ORM objects whose session has already been closed; it works today only because
`expire_on_commit=False` and no commit intervened, so flipping that engine setting would
break it silently.
*Proposed fix:* drop `pending_ids` and select the plain columns
(`select(PendingTransaction.id, PendingTransaction.current_txid, PendingTransaction.kind)`)
instead of hydrating entities, so nothing outlives the session.
*Test:* covered by the existing `tests/unit/test_confirmation.py` — it must stay green with
`expire_on_commit=True` forced on the test session factory.
**Fixed.** `poll_once` selects plain columns
(`select(PendingTransaction.id, .current_txid, .kind)`) instead of hydrating entities, so
nothing outlives the session, and the unused `pending_ids` local is gone. Covered by the
existing (and new) `test_confirmation.py` cases.
### B-22
**Amounts rendered by raw division**
*Files:* `app/static/app.js` (multiple: `:295`, `:424`, `:660`, `:673`, `:680`),
`app/static/admin.js` (table cells)
Every amount is displayed as `sats / SATS_PER_PLM` with no formatting, so values like
`0.7000000000000001` are reachable in the balance, the jackpot and the admin tables.
*Proposed fix:* one `formatPlm(sats)` helper (fixed decimals, locale-aware grouping via
`Intl.NumberFormat` with the language already resolved by `i18n.js`), used by every display
site. Amounts sent *to* the server must keep going through `Math.round(x * SATS_PER_PLM)` —
the formatter is for display only.
*Test:* manual — with a 0.7 PLM jackpot and a 12345678.9 PLM balance, no artefacts and no
locale mismatch against the selected language.
**Fixed.** `formatPlm(sats)` added to `app.js` (and `fmtPlm` to `admin.js`),
using `Intl.NumberFormat` with the already-resolved language; every display site routes
through it. Input fields deliberately keep the raw value — a grouped, localized string
would break `parseFloat` — and amounts sent to the server still go through
`Math.round(x * SATS_PER_PLM)`. Verification is manual (browser rendering).
### B-23
**Concurrent `withLoading` on the same button**
*File:* `app/static/app.js:20-31`
`withLoading` snapshots `button.innerHTML` and restores it in `finally`. `refreshMe()` is
invoked from the SSE handler, the poll chain, `placeBet`, `withdraw` and `showDashboard`,
all sharing `#refresh-btn`. Two overlapping calls make the second snapshot the *loading*
label, which it then restores permanently — leaving the button stuck on
"Aggiornamento…".
*Proposed fix:* keep the in-flight promise on the element itself (e.g. a
`button._loadingPromise` / `WeakMap`); a second call either awaits the existing one or
returns immediately, so only the outermost call restores the markup. Also worth
de-duplicating the SSE burst: `onRoundServerEvent` fires three fetches per event, and the
broadcaster is generic, so every client reacts to every event.
*Test:* manual — trigger a bet while an SSE-driven `refreshMe()` is in flight and confirm
the refresh button returns to its icon+label state.
**Fixed.** `withLoading` keeps the in-flight promise in a `WeakMap` keyed by the
button: a nested call awaits the existing one and runs its own work without touching the
markup, so only the outermost call restores it. Verification is manual (browser
interaction).
### B-24
**The global exception handler breaks the error contract**
*File:* `app/main.py:74-77`
It answers `{"detail": "internal server error"}` — a bare string, while
`app/api/errors.py` documents `detail` as `{"code", "message", "params"}`. The frontend
tolerates a string (`apiErrorMessage` handles that case), but the contract should be
uniform.
*Proposed fix:* return `ApiError("internal_error", "internal server error").as_detail()` and
add `error.internal_error` to all 7 languages in `app/static/i18n.js`. Keep the response
body free of exception details — the traceback belongs in `logs/app.log` only.
*Test:* an endpoint stubbed to raise answers 500 with `detail.code == "internal_error"` and
no exception text in the body.
**Fixed.** The catch-all handler returns
`ApiError("internal_error", "internal server error").as_detail()`, and
`error.internal_error` was added to all 7 languages. Test:
`test_rounds_route.py::test_unhandled_errors_use_the_structured_detail_shape`, which also
asserts the exception text does not leak into the response body.
---
## Cross-cutting observation
[B-01](#b-01) through [B-04](#b-04) share one root cause: **the code treats a broadcast as
final and the network connection as never failing.** There is no reconciliation between
the database's view of the world and the chain's — no re-scan at startup, no terminal
`failed` state, no request timeouts, no "unstick" routine. Combined with the already
documented scheduler-resume gap and `restart: unless-stopped` in `docker-compose.yml`,
the system has several absorbing states from which only manual database edits recover.
Fixing that class of problem is more valuable than any individual item above. Suggested
order of work, by expected time-to-first-occurrence in production:
1. [B-01](#b-01) — will happen within hours of deployment.
2. [B-03](#b-03) — one bad row is enough, and it is silent.
3. [B-02](#b-02) — happens on the first bump the RBF loop actually performs.
4. [B-06](#b-06) — depends only on the user's UTXO shape.
5. [B-05](#b-05) — happens on the first operator typo, and is unrecoverable in the
foreign-address variant.
6. [B-04](#b-04) + [B-08](#b-08) — the reconciliation layer both of them need.
7. Everything else.
+74 -9
View File
@@ -8,10 +8,17 @@ The user communicates in Italian in chat — reply to them in Italian. Everythin
## Project status
All 10 build-order stages from `/home/davide/.claude/plans/scalable-mixing-sloth.md` are code-complete and unit-tested (76 tests green): project skeleton, DB schema + Alembic migrations, auth, HD wallet derivation, Electrum client, deposit detection, bet flow, round/draw engine, payout, withdrawal, RBF fee-bump, admin config + audit log. Beyond the original 10 stages: a Docker + Caddy deployment (see below), a full admin dashboard (`/admin`), a static test UI for the user-facing flow (`/`), a pending-inclusive balance display (see "Balance display" below), and a Server-Sent Events push channel layered on top of the original polling (see "Real-time updates" below).
All 10 build-order stages from `/home/davide/.claude/plans/scalable-mixing-sloth.md` are code-complete and unit-tested (137 tests green): project skeleton, DB schema + Alembic migrations, auth, HD wallet derivation, Electrum client, deposit detection, bet flow, round/draw engine, payout, withdrawal, RBF fee-bump, admin config + audit log. Beyond the original 10 stages: a Docker + Caddy deployment (see below), a full admin dashboard (`/admin`), a static test UI for the user-facing flow (`/`), a pending-inclusive balance display (see "Balance display" below), and a Server-Sent Events push channel layered on top of the original polling (see "Real-time updates" below).
Real-money verification on mainnet, done so far: registration + address derivation, deposit crediting (1-conf), a real 10 PLM bet (broadcast, confirmed, change credited back), and a full round cycle — close → draw (real block hash) → payout (70/30 split, exact sat math verified against the broadcast tx) → confirmation → round closed → next round auto-opened. Withdrawal and the RBF bump path are unit-tested but have never been exercised against a live broadcast. See "Known gaps" below before treating this as production-ready.
A full-codebase audit on 2026-07-26 found 24 bugs — five of them critical, including a
dropped Electrum connection that hung the whole server with no reconnect, an RBF fee bump
that wedged a round forever, and no way for the system to recover a broadcast that never
confirmed (funds frozen). All 24 are fixed; [BUGS.md](BUGS.md) is the record, with each
one's root cause, what was actually done, and where its regression test lives. Read it
before assuming any behaviour here predates those fixes.
Before writing code, always read the "Architecture" section below in full, plus the diagrams in [flowchart/](flowchart/): [platform-overview.mmd](flowchart/platform-overview.mmd) for the whole 5-phase flow, and [round-lifecycle.mmd](flowchart/round-lifecycle.mmd) for the round/draw lifecycle in detail. Every node in these diagrams corresponds to a behavior that must be implemented exactly as described, including the labels on the edges (conditions, retries, loops). Regenerate their companion PDFs with `flowchart/render-pdf.sh <file>.mmd` after editing either one.
Human-facing guides live in [docs/](docs/) (Italian, per explicit request — an exception to this file's English-only rule below): [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).
@@ -81,6 +88,26 @@ Mainnet:
- Block time: 120s
- BIP32 extended key headers (Legacy/native-segwit `zprv`/`zpub` etc.): see `ExtKeyHeaders` in `ChainProfiles.cs`
## Electrum connection (rotation, keepalive, timeouts)
One connection serves everything — deposit credits, broadcasts, confirmations, the chain
tip the draw waits on — which makes it the platform's biggest single point of failure.
Three things keep it honest:
- **Server rotation.** `ELECTRUM_HOST`/`ELECTRUM_PORT` is the primary;
`ELECTRUM_FALLBACK_SERVERS` is a comma-separated list of `host:port[:notls]` extras
(parsed by `electrum/client.py:parse_endpoints`, which rejects malformed entries at
startup rather than during the outage when the fallback is needed). The listener tries
the next server after any failed or dropped session, and only sleeps on the backoff once
every server has had a turn — so one dead server costs a single attempt, not an outage.
- **Every request is bounded** (`_REQUEST_TIMEOUT_SECONDS`, 15s) and a timeout tears the
connection down. Unbounded waits used to hang a `POST /bets` *while holding the per-user
lock*, and could stop the confirmation poller permanently.
- **The drop is observable.** `client.wait_closed()` resolves when the read loop dies, and
`listener._run_once` races it against the notification consumers and a 60s `server.ping`
keepalive. Without this the listener sat on queues nobody would ever fill again and never
reconnected — while `listener.client` still looked alive to everything else.
## Balance display
`place_bet`/`request_withdrawal` (`app/bets/service.py`, `app/withdrawals/service.py`) select whole UTXOs to cover the amount (`select_utxos`, largest-first) and mark every selected UTXO `spent_txid` immediately at broadcast time — well before the tx has any confirmations. `User.cached_balance_sats` (`recompute_balance`, `app/wallet/balance.py`) only sums confirmed, unspent UTXOs, so right after a bet/withdrawal it understates the user's real balance by the entire unconfirmed change amount, which is often far larger than the amount actually moving.
@@ -160,16 +187,54 @@ These choices were made explicitly during design (not derivable from reading a s
- The admin panel can export any user's raw WIF private key (`GET /admin/users/{id}/privkey`, `app/wallet/hd.py:derive_user_wif`). This is intentional, not a vulnerability to fix: the server already holds the master key everything derives from (custodial by design, see above), so this only exposes through the API something an operator could already do via a script. Every access is written to `audit_log` (`admin_privkey_accessed`) — don't remove that logging when touching this endpoint.
- RBF fee bumps are paid by whoever's change output the tx pays back to — the user for bets/withdrawals, the pool for payouts — never by the fixed counterparty amount (recipient/winner/fee-address outputs are untouched; only the sender's own change shrinks). See `bump_fee` in `app/tx/broadcast.py`.
## Transaction reconciliation and the tx lifecycle
Everything that spends money is written **before** it is broadcast, and resolved against
the chain afterwards. This is what makes the system recover on its own instead of needing
manual DB edits (BUGS.md B-04/B-08).
`PendingTransaction.status` is the lifecycle: `building` → `pending` → `confirmed`, or
`failed`.
- `building` is written first, with the UTXOs already marked `spent_txid`, and committed
*before* the broadcast (`bets/service.py:place_bet`, `withdrawals/service.py`). A crash
in that window therefore leaves evidence rather than coins spent on-chain with no record.
- If the broadcast is refused, the service releases the reserved UTXOs, restores the
balance, removes the participant (or marks the withdrawal `failed`), audit-logs it, and
raises `broadcast_failed` — answered as **502**, since the network refused it, not the
caller.
- `app/tx/reconcile.py` (`PendingTransactionReconciler`, every 120s and once at startup)
asks the chain about anything still `building`/`pending`. Tx present → promote; tx gone →
mark `failed` with a `failure_reason`, release the inputs, roll the domain row back,
audit-log `pending_tx_abandoned`. Grace periods differ by state (120s for `building`,
6h for `pending`, so the RBF bumper gets its attempts first), and a *transport* failure
never abandons anything — only a server that positively doesn't know the tx does.
Because of this, `UtxoEvent.spent_txid` must always equal the *current* txid of the tx
reserving it: `bump_fee` retargets it (along with `RoundParticipant.bet_txid`,
`Withdrawal.txid` and `Round.payout_txid`) on every fee bump. Confirmation handlers
deliberately key off immutable ids (`round_id`/`user_id`, `withdrawal_id`) rather than the
txid, which changes under them.
**At most one active round is a database invariant**, not just a code convention:
`ix_rounds_single_active` (a unique index over the constant expression `(1)`, restricted to
the active statuses) makes a concurrent second insert fail cleanly, and
`open_new_round_if_needed` recovers by using the winner's round.
## Known gaps / TODO
Not blockers for reading the code, but must be addressed before this is production-ready:
Not blockers for reading the code, but must be addressed before this is production-ready.
The 24 findings of the 2026-07-26 full-codebase audit are **all fixed** — see
[BUGS.md](BUGS.md), which keeps each one's root cause, fix and regression test as the
record. What remains open:
- **Scheduler doesn't resume mid-flight rounds after a restart.** `rounds/scheduler.py`'s `_tick()` only acts on rounds with `status == "open"`. If the process restarts while a round is `closing`/`drawing`/`paying_out`, it's permanently stuck — nothing re-enters `_wait_for_next_block` or retries `_trigger_payout`. Needs a startup routine that inspects in-progress rounds and resumes (or a periodic "unstick" check) before this can run unattended.
- **RBF bump only handles one case**: a single change output, paying back to the tx's own sender address, large enough to absorb the fee increase. No additional-input selection fallback — an exact-amount tx (no change) or a change output too small to absorb the bump raises `RbfError` and needs manual operator intervention. Documented in `tx/broadcast.py`.
- **Payout retry**: if `_trigger_payout` fails (e.g. insufficient pool UTXOs, Electrum disconnected), it just logs and returns — the round stays stuck in `paying_out` with no automatic retry.
- **Withdrawal and RBF bump have never been exercised against a live broadcast** — only deposit and bet flow are verified end-to-end with real PLM as of this commit.
- **No general user-facing history endpoints** (list my own bets / withdrawals / past rounds) — `GET /users/me/last-round-result` covers exactly one case (the outcome of the most recent *closed* round the user played in, as a reveal-persistence backstop; see DRAW above), not a real history. The admin side has more (`/admin/rounds`, `/admin/pending-transactions`, `/admin/audit-log`), but there's still no "my own full history" equivalent for a logged-in user.
- **Admin auth is a single shared bearer token** (`ADMIN_TOKEN`, `X-Admin-Token` header) — no per-admin identity or audit trail of *who* changed config (the `audit_log` table records *what* changed, not which operator did it). This token now gates a lot more than config (user list, private key export, round/audit history), so its blast radius if leaked is correspondingly larger.
- **Scheduler doesn't resume mid-flight rounds after a restart.** `rounds/scheduler.py`'s `_tick()` only acts on rounds with `status == "open"`. If the process restarts while a round is `closing`/`drawing`/`paying_out`, it's permanently stuck — nothing re-enters `_wait_for_next_block` or retries `_trigger_payout`. Needs a startup routine that inspects in-progress rounds and resumes (or a periodic "unstick" check) before this can run unattended. Note this is *round*-level state: in-flight *transactions* do now recover on their own (see "Transaction reconciliation" below).
- **RBF bump only handles one case**: a single change output, paying back to the tx's own sender address, large enough to absorb the fee increase. No additional-input selection fallback — an exact-amount tx (no change) or a change output too small to absorb the bump raises `RbfError`. The consequence is no longer permanent, though: a tx that can't be bumped and never confirms is eventually abandoned and its UTXOs released (see "Transaction reconciliation"), so the funds come back instead of being frozen.
- **Payout retry**: if `_trigger_payout` fails (insufficient pool UTXOs, a bad `fee_address`, Electrum disconnected), it logs, writes a `payout_failed` audit entry, and returns — the round stays in `paying_out` with no automatic retry. The audit entry makes it visible in `/admin`; acting on it is still manual.
- **Withdrawal and RBF bump have never been exercised against a live broadcast** — only deposit and bet flow are verified end-to-end with real PLM. Both paths have unit coverage, including their failure and rollback branches, but unit tests are not a live network.
- **No general user-facing history endpoints** (list my own bets / withdrawals / past rounds) — `GET /users/me/last-round-result` covers exactly one case (the outcome of the most recent *closed* round the user played in, as a reveal-persistence backstop; see DRAW above), not a real history. The admin side has more (`/admin/rounds`, `/admin/pending-transactions`, `/admin/audit-log`), but there's still no "my own full history" equivalent for a logged-in user. A failed withdrawal now leaves a `status="failed"` row the user cannot see anywhere — an argument for closing this gap.
- **Admin auth is a single shared bearer token** (`ADMIN_TOKEN`, `X-Admin-Token` header) — no per-admin identity: `audit_log` records *what* changed (config edits are now logged too, as `config_updated`, with before/after values) but never *which operator* did it. This token gates the user list, private key export and round/audit history, so its blast radius if leaked is large.
- **No rate limiting / abuse protection** on any endpoint (register, bet, withdrawal, admin).
- **`/guida` is not served in Docker.** `GET /guida` reads `docs/guida-utente.md`, and the `Dockerfile` deliberately does not `COPY docs` — the guide is pending a rewrite, so it isn't shipped yet. The endpoint answers a clean 404 (`guide_unavailable`, translated) and logs an error rather than crashing, but the navbar help link leads nowhere until `COPY docs ./docs` is added back.
- No automated integration tests against a live Electrum connection — all live-network verification so far has been manual (ad hoc scripts + real mainnet transactions), not part of the `pytest` suite.
- **`docker-compose.yml`'s `restart: unless-stopped`** on the app container means a crash mid-round auto-restarts straight into the scheduler-resume gap above — see the Deployment section.
- **Single-process assumptions**: the SSE broadcaster (`rounds/events.py`) and the per-user locks (`tx/locks.py`) are both in-process only. Fine for the current one-uvicorn-process deployment; a multi-worker one needs a shared channel and a DB/Redis lock. Note the round-uniqueness invariant is *not* in this category any more — it's enforced by a DB index (see below).
+57 -13
View File
@@ -2,7 +2,7 @@ import json
import secrets
from fastapi import APIRouter, Depends, Header, HTTPException, status
from pydantic import BaseModel
from pydantic import BaseModel, Field, field_validator
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
@@ -12,16 +12,26 @@ from app.config import settings
from app.db.models import AuditLog, PendingTransaction, Round, User
from app.db.session import get_session
from app.rounds.config import get_round_config
from app.wallet.address import is_valid_plm_address
from app.wallet.hd import derive_user_wif
router = APIRouter(prefix="/admin", tags=["admin"])
async def require_admin(x_admin_token: str = Header(default="")) -> None:
if not settings.admin_token or x_admin_token != settings.admin_token:
# An unset ADMIN_TOKEN denies everything — checked first, since compare_digest
# on two empty strings returns True and would otherwise open the panel to
# anyone on an instance that never configured a token.
if not settings.admin_token:
raise HTTPException(status.HTTP_403_FORBIDDEN, "invalid admin token")
if not secrets.compare_digest(x_admin_token, settings.admin_token):
raise HTTPException(status.HTTP_403_FORBIDDEN, "invalid admin token")
# `paused` is deliberately NOT here: it has its own audit-logged endpoints
# (/admin/pause, /admin/resume), and accepting it on PUT /config as well gave the
# operator an unlogged way to stop the lottery (B-10). It stays in the response
# model, so the dashboard still reads its current value from here.
_CONFIG_FIELDS = (
"fee_address",
"bet_amount_sats",
@@ -30,7 +40,6 @@ _CONFIG_FIELDS = (
"fee_rate_sat_vb",
"rbf_timeout_seconds",
"draw_animation_seconds",
"paused",
)
@@ -46,18 +55,41 @@ class RoundConfigResponse(BaseModel):
class RoundConfigUpdate(BaseModel):
"""Bounds are enforced here rather than trusting the operator: a value like
fee_rate_sat_vb=0 produces transactions no node will relay (stalling every bet,
payout and withdrawal), and round_duration_seconds=0 expires a round the instant
it opens. `paused` is not accepted — see _CONFIG_FIELDS."""
# An unvalidated fee_address was the worst of the lot: a malformed one wedged the
# payout with an unhandled EmbitError, and a well-formed *foreign* one (bc1...)
# parses fine as a witness program, so every round's 30 % commission would be
# broadcast to a script nobody holds the key for (B-05).
fee_address: str | None = None
bet_amount_sats: int | None = None
round_duration_seconds: int | None = None
round_cooldown_seconds: int | None = None
fee_rate_sat_vb: int | None = None
rbf_timeout_seconds: int | None = None
draw_animation_seconds: int | None = None
paused: bool | None = None
bet_amount_sats: int | None = Field(default=None, gt=0, le=100_000 * 100_000_000)
round_duration_seconds: int | None = Field(default=None, ge=30, le=7 * 24 * 3600)
round_cooldown_seconds: int | None = Field(default=None, ge=0, le=24 * 3600)
fee_rate_sat_vb: int | None = Field(default=None, ge=1, le=10_000)
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)
@field_validator("fee_address")
@classmethod
def _validate_fee_address(cls, value: str | None) -> str | None:
if value is None:
return None
value = value.strip()
if not is_valid_plm_address(value):
raise ValueError(
"fee_address must be a valid PLM bech32 address (plm1...) — an address from "
"another chain would send every round's commission somewhere unspendable"
)
return value
def _config_response(config) -> RoundConfigResponse:
return RoundConfigResponse(**{field: getattr(config, field) for field in _CONFIG_FIELDS})
fields = {field: getattr(config, field) for field in _CONFIG_FIELDS}
fields["paused"] = config.paused
return RoundConfigResponse(**fields)
@router.get("/config", response_model=RoundConfigResponse, dependencies=[Depends(require_admin)])
@@ -72,10 +104,22 @@ async def update_config(
body: RoundConfigUpdate, session: AsyncSession = Depends(get_session)
) -> RoundConfigResponse:
config = await get_round_config(session)
# Diff computed before assignment so the audit entry records both sides. Without
# it, the most sensitive setting in the system (fee_address — where 30 % of every
# pool goes) could be changed without leaving any trace at all (B-10).
changes: dict[str, dict] = {}
for field in _CONFIG_FIELDS:
value = getattr(body, field)
if value is not None:
setattr(config, field, value)
if value is None:
continue
previous = getattr(config, field)
if previous == value:
continue
changes[field] = {"from": previous, "to": value}
setattr(config, field, value)
if changes:
await write_audit_log(session, "config_updated", changes)
await session.commit()
return _config_response(config)
+8 -1
View File
@@ -36,7 +36,14 @@ async def create_bet(
try:
participant = await place_bet(session, listener.client, user)
except BetError as exc:
raise from_api_error(status.HTTP_400_BAD_REQUEST, exc) from 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_400_BAD_REQUEST
)
raise from_api_error(code, exc) from exc
return BetResponse(
round_id=participant.round_id,
+15 -4
View File
@@ -118,6 +118,16 @@ async def current_round(
participant_count = await session.scalar(
select(func.count()).select_from(RoundParticipant).where(RoundParticipant.round_id == round_.id)
) or 0
# The pool is the sum of what the participants' bets actually paid into the pool
# address — each one is already net of that bet's network fee. Deriving it from
# participant_count * the *current* bet_amount_sats instead overstated it, and
# silently changed the advertised jackpot of a round in progress whenever an
# operator edited the bet amount (B-11).
pool_amount_sats = await session.scalar(
select(func.coalesce(func.sum(RoundParticipant.bet_amount_sats), 0)).where(
RoundParticipant.round_id == round_.id
)
) or 0
opened_at = round_.opened_at.replace(tzinfo=timezone.utc)
closes_at = opened_at + timedelta(seconds=config.round_duration_seconds)
@@ -137,10 +147,11 @@ async def current_round(
await session.commit()
# Shown to players as "jackpot": the winner's 70% share of the pool (same
# split rounds/scheduler.py applies at payout time), not the full pool —
# what's displayed should match what the winner actually receives.
pool_amount_sats = participant_count * config.bet_amount_sats
# Shown to players as "jackpot": the winner's 70% share of the pool (same split
# rounds/scheduler.py applies at payout time), not the full pool. It remains an
# upper bound by the payout tx's own fee, which is deducted from the winner's
# share and isn't knowable until the payout is built — a few hundred sat on a
# 1 sat/vB payout, i.e. invisible at PLM amounts, but it is not exact.
jackpot_sats = pool_amount_sats * 70 // 100
return CurrentRoundResponse(
+4 -6
View File
@@ -5,15 +5,13 @@ from sqlalchemy.ext.asyncio import AsyncSession
from app.api.errors import http_error
from app.auth.dependencies import get_current_user
from app.auth.security import hash_password, verify_password
from app.auth.security import MIN_PASSWORD_LENGTH, hash_password, verify_password
from app.db.models import Round, RoundParticipant, User
from app.db.session import get_session
from app.wallet.balance import compute_pending_balance
router = APIRouter(prefix="/users", tags=["users"])
_MIN_PASSWORD_LENGTH = 8
class MeResponse(BaseModel):
id: int
@@ -60,12 +58,12 @@ async def change_password(
raise http_error(
status.HTTP_401_UNAUTHORIZED, "current_password_incorrect", "current password is incorrect"
)
if len(body.new_password) < _MIN_PASSWORD_LENGTH:
if len(body.new_password) < MIN_PASSWORD_LENGTH:
raise http_error(
status.HTTP_400_BAD_REQUEST,
"password_too_short",
f"new password must be at least {_MIN_PASSWORD_LENGTH} characters",
minimum=_MIN_PASSWORD_LENGTH,
f"new password must be at least {MIN_PASSWORD_LENGTH} characters",
minimum=MIN_PASSWORD_LENGTH,
)
user.password_hash = hash_password(body.new_password)
+6 -1
View File
@@ -44,7 +44,12 @@ async def create_withdrawal(
session, listener.client, user, body.external_address, body.amount_sats
)
except WithdrawalError as exc:
raise from_api_error(status.HTTP_400_BAD_REQUEST, exc) from exc
code = (
status.HTTP_502_BAD_GATEWAY # the network refused it, not the caller (B-07)
if exc.code == "broadcast_failed"
else status.HTTP_400_BAD_REQUEST
)
raise from_api_error(code, exc) from exc
return WithdrawalResponse(
txid=withdrawal.txid,
+18 -5
View File
@@ -1,11 +1,11 @@
from fastapi import APIRouter, Depends, Request, status
from pydantic import BaseModel
from pydantic import BaseModel, Field
from sqlalchemy import func, select
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.errors import http_error
from app.auth.security import create_access_token, hash_password, verify_password
from app.auth.security import MIN_PASSWORD_LENGTH, create_access_token, hash_password, verify_password
from app.db.models import User
from app.db.session import get_session
from app.wallet.hd import derive_user_address
@@ -16,8 +16,13 @@ _MAX_REGISTER_RETRIES = 5
class RegisterRequest(BaseModel):
username: str
password: str
"""Registration used to accept an empty username and a one-character password,
while /users/me/change-password demanded 8 characters — an odd place to be
lenient on a custodial system holding real funds (B-12). MIN_PASSWORD_LENGTH is
shared with that endpoint so the two can't drift apart again."""
username: str = Field(min_length=3, max_length=32, pattern=r"^[A-Za-z0-9_.-]+$")
password: str = Field(min_length=MIN_PASSWORD_LENGTH, max_length=256)
class TokenResponse(BaseModel):
@@ -48,8 +53,16 @@ async def register(
session.add(user)
try:
await session.commit()
except IntegrityError:
except IntegrityError as exc:
await session.rollback()
# Only a derivation-index collision is worth retrying. A username
# collision (someone registered the same name between the check above and
# this commit) is permanent, and retrying it five times only to report
# "derivation_index_conflict" told the user the wrong thing entirely (B-12).
if "username" in str(exc.orig).lower():
raise http_error(
status.HTTP_409_CONFLICT, "username_taken", "username already taken"
) from exc
continue
await session.refresh(user)
request.app.state.electrum_listener.address_for_new_user(user.id, user.address)
+21 -2
View File
@@ -1,11 +1,19 @@
from datetime import datetime, timedelta, timezone
import logging
import jwt
from argon2 import PasswordHasher
from argon2.exceptions import VerifyMismatchError
from argon2.exceptions import InvalidHashError, VerificationError
from app.config import settings
logger = logging.getLogger(__name__)
# Shared by registration (app/auth/routes.py) and the self-service password change
# (app/api/routes/users.py) so the two can't enforce different minimums.
MIN_PASSWORD_LENGTH = 8
_hasher = PasswordHasher()
@@ -14,9 +22,20 @@ def hash_password(password: str) -> str:
def verify_password(password: str, password_hash: str) -> bool:
"""Any failure to verify reads as "wrong password", never as a server error.
Catching only VerifyMismatchError left the other two cases as unhandled 500s
(B-13): VerificationError covers argon2's other verification failures, and
InvalidHashError fires when the stored hash can't be parsed at all — which is a
data problem worth logging, but from the caller's side it still just means this
password does not open this account.
"""
try:
return _hasher.verify(password_hash, password)
except VerifyMismatchError:
except InvalidHashError:
logger.error("stored password hash is unparseable — password verification cannot succeed")
return False
except VerificationError:
return False
+16 -2
View File
@@ -8,10 +8,24 @@ from app.tx.confirmation import register_handler
async def _on_bet_confirmed(session: AsyncSession, pending: PendingTransaction) -> None:
"""Resolved by (round_id, user_id) — the pair is unique per participant and,
unlike the txid, cannot change under us. Keying this on bet_txid meant an
RBF-bumped bet confirmed under a txid no participant carried, so the row stayed
"broadcast" forever and the round could never close (B-02). The txid is kept in
step by tx/broadcast.py too, but correctness here no longer depends on it."""
participant = await session.scalar(
select(RoundParticipant).where(RoundParticipant.bet_txid == pending.current_txid)
select(RoundParticipant).where(
RoundParticipant.round_id == pending.round_id,
RoundParticipant.user_id == pending.user_id,
)
)
if participant is not None and participant.status == "broadcast":
if participant is None:
# Fall back to the txid for rows written before this changed, and for any
# pending row missing its round/user link.
participant = await session.scalar(
select(RoundParticipant).where(RoundParticipant.bet_txid == pending.current_txid)
)
if participant is not None and participant.status in ("building", "broadcast"):
participant.status = "confirmed"
participant.confirmed_at = datetime.now(timezone.utc)
+60 -7
View File
@@ -64,12 +64,17 @@ async def place_bet(session: AsyncSession, client: ElectrumClient, user: User) -
except InsufficientFundsError as exc:
raise BetError(exc.code, str(exc)) from exc
await client.broadcast(built.raw_hex)
# --- Phase 1: record the intent, *then* broadcast (B-08) --------------------
# Broadcasting first meant a failure (or a crash) between the broadcast and the
# commit left the coins irreversibly spent on-chain with no trace in the DB: no
# participant, so no entry in the draw; no pending row, so no RBF and no
# confirmation tracking; and the UTXOs not even marked spent, so the next bet
# would try to double-spend them. Writing "building" rows first means the worst
# case is a row the reconciler (app/tx/reconcile.py) can resolve either way by
# asking the chain whether the tx exists.
spent_by_key = {(u.txid, u.vout): u for u in unspent}
for spent in built.spent_utxos:
row = spent_by_key[(spent.txid, spent.vout)]
row.spent_txid = built.txid
spent_by_key[(spent.txid, spent.vout)].spent_txid = built.txid
await recompute_balance(session, user.id)
broadcast_at = datetime.now(timezone.utc)
@@ -79,10 +84,25 @@ async def place_bet(session: AsyncSession, client: ElectrumClient, user: User) -
bet_amount_sats=built.recipient_sats,
bet_txid=built.txid,
broadcast_at=broadcast_at,
status="broadcast",
status="building",
)
session.add(participant)
session.add(_pending_transaction(round_.id, user.id, built, config.fee_rate_sat_vb))
pending = _pending_transaction(round_.id, user.id, built, config.fee_rate_sat_vb)
session.add(pending)
await session.commit()
# --- 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
participant.status = "broadcast"
pending.status = "pending"
await write_audit_log(
session,
"bet_placed",
@@ -97,6 +117,35 @@ async def place_bet(session: AsyncSession, client: ElectrumClient, user: User) -
return participant
async def _release_failed_bet(
session: AsyncSession,
participant: RoundParticipant,
pending: PendingTransaction,
built: BuiltTransaction,
user_id: int,
reason: str,
) -> None:
"""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."""
for spent in built.spent_utxos:
row = await session.scalar(
select(UtxoEvent).where(UtxoEvent.txid == spent.txid, UtxoEvent.vout == spent.vout)
)
if row is not None:
row.spent_txid = None
await session.delete(participant)
await session.delete(pending)
await recompute_balance(session, user_id)
await write_audit_log(
session,
"bet_broadcast_failed",
{"txid": built.txid, "reason": reason[:200]},
user_id=user_id,
)
await session.commit()
def _pending_transaction(
round_id: int, user_id: int, built: BuiltTransaction, fee_rate_sat_vb: int
) -> PendingTransaction:
@@ -107,5 +156,9 @@ def _pending_transaction(
current_txid=built.txid,
fee_rate_sat_vb=fee_rate_sat_vb,
raw_tx_hex=built.raw_hex,
status="pending",
# "building" until the broadcast succeeds — see place_bet's two phases. It
# matters which one this starts as: the reconciler gives a "building" row a
# short grace period (we may have died mid-broadcast) and a "pending" one a
# long one (a node accepted it once, so it deserves the RBF attempts first).
status="building",
)
+49
View File
@@ -1,5 +1,10 @@
from pydantic_settings import BaseSettings, SettingsConfigDict
# Minimum JWT signing key length. HS256 keys shorter than the hash output weaken
# the MAC, and PyJWT warns about it — enforced here so it fails at startup rather
# than being shipped by accident.
MIN_JWT_SECRET_LENGTH = 32
class Settings(BaseSettings):
model_config = SettingsConfigDict(env_file=".env", extra="ignore")
@@ -9,6 +14,13 @@ class Settings(BaseSettings):
electrum_host: str = "santantonio.sytes.net"
electrum_port: int = 50002
electrum_use_ssl: bool = True
# Additional servers to fall back to, comma-separated `host:port[:notls]`.
# The listener rotates over primary + these (app/electrum/listener.py), 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 hardcoded server the platform's biggest
# single point of failure. Parsed by electrum.client.parse_endpoints.
electrum_fallback_servers: str = ""
xprv_encryption_key: str = ""
master_key_path: str = "./master.xprv.enc"
@@ -25,3 +37,40 @@ class Settings(BaseSettings):
settings = Settings()
class ConfigError(Exception):
"""A misconfiguration serious enough that the app must refuse to serve."""
def validate_runtime_secrets(config: Settings | None = None) -> None:
"""Fail fast on secrets that would otherwise only break at first use: an empty
jwt_secret makes PyJWT raise InvalidKeyError on every login, and an empty
xprv_encryption_key makes Fernet fail on the first key derivation. Either way
the container comes up looking healthy and breaks the moment a real user
touches it.
Called from the app's lifespan (app/main.py) rather than as a Settings
field_validator on purpose: Settings is constructed at import time by every
module that reads config, including the test suite, which has no .env and no
business holding real secrets. At startup the guarantee still holds where it
matters — the server refuses to serve half-configured — without coupling every
import to a gitignored file.
ADMIN_TOKEN is deliberately not fatal: require_admin already denies every
request when it's empty, so the effect is a locked admin panel, not an open one.
"""
config = config or settings
problems = []
if len(config.jwt_secret) < MIN_JWT_SECRET_LENGTH:
problems.append(
f"JWT_SECRET must be at least {MIN_JWT_SECRET_LENGTH} characters "
'(generate: python -c "import secrets; print(secrets.token_urlsafe(32))")'
)
if not config.xprv_encryption_key.strip():
problems.append(
"XPRV_ENCRYPTION_KEY must be set (generate: python -c "
'"from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")'
)
if problems:
raise ConfigError("invalid configuration in .env: " + "; ".join(problems))
+37 -2
View File
@@ -1,6 +1,6 @@
from datetime import datetime, timezone
from sqlalchemy import BigInteger, ForeignKey, String, UniqueConstraint
from sqlalchemy import BigInteger, ForeignKey, Index, String, UniqueConstraint, text
from sqlalchemy.orm import Mapped, mapped_column
from app.db.base import Base
@@ -39,9 +39,29 @@ class UtxoEvent(Base):
spent_txid: Mapped[str | None] = mapped_column(String(64), default=None)
_ACTIVE_ROUND_STATUSES_SQL = "'open', 'closing', 'drawing', 'paying_out'"
class Round(Base):
__tablename__ = "rounds"
# At most one round may be active at a time. Rounds never overlap by design,
# but that was enforced only by a read-then-insert in
# rounds/service.open_new_round_if_needed, which two concurrent callers can
# both pass — and a second stuck "open" row blocks every future round forever
# (B-09). This is the database-level guarantee: a unique index over a constant
# expression, restricted to the active statuses, so the table can hold any
# number of closed rounds and only ever one live one.
__table_args__ = (
Index(
"ix_rounds_single_active",
text("(1)"),
unique=True,
sqlite_where=text(f"status IN ({_ACTIVE_ROUND_STATUSES_SQL})"),
postgresql_where=text(f"status IN ({_ACTIVE_ROUND_STATUSES_SQL})"),
),
)
id: Mapped[int] = mapped_column(primary_key=True)
status: Mapped[str] = mapped_column(String(16), default="open")
opened_at: Mapped[datetime] = mapped_column(default=utcnow)
@@ -102,7 +122,17 @@ class RoundConfig(Base):
class PendingTransaction(Base):
"""Single source of truth for the RBF timeout->bump->rebroadcast loop."""
"""Single source of truth for the RBF timeout->bump->rebroadcast loop, and the
row the reconciler (app/tx/reconcile.py) resolves against the chain.
Status lifecycle:
building -> written before the tx is broadcast, so a crash between the two
leaves evidence instead of a silently-spent UTXO set (B-08).
pending -> broadcast, waiting for its 1st confirmation.
confirmed -> terminal, set by app/tx/confirmation.py.
failed -> terminal, set by the reconciler when the tx is gone from the
chain for good; its UTXOs have been released by then.
"""
__tablename__ = "pending_transactions"
@@ -116,8 +146,13 @@ class PendingTransaction(Base):
raw_tx_hex: Mapped[str] = mapped_column(String)
broadcast_at: Mapped[datetime] = mapped_column(default=utcnow)
status: Mapped[str] = mapped_column(String(16), default="pending")
# The txid this row had *before* its most recent RBF bump (bump_fee rewrites
# current_txid in place). Despite the name reading forwards, it points
# backwards: current_txid is the replacement, this is what it replaced.
replaced_by_txid: Mapped[str | None] = mapped_column(String(64), default=None)
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)
updated_at: Mapped[datetime] = mapped_column(default=utcnow, onupdate=utcnow)
+105 -6
View File
@@ -2,6 +2,67 @@ import asyncio
import itertools
import json
import ssl
from typing import NamedTuple
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."""
host: str
port: int
use_ssl: bool = True
def __str__(self) -> str:
return f"{self.host}:{self.port}{'' if self.use_ssl else ' (plaintext)'}"
def parse_endpoints(
primary_host: str, primary_port: int, primary_use_ssl: bool, fallback_spec: 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.
Duplicates are dropped, keeping first position.
"""
endpoints = [ElectrumEndpoint(primary_host, primary_port, primary_use_ssl)]
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]")
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]")
use_ssl = True
if len(parts) == 3:
flag = parts[2].strip().lower()
if flag not in ("ssl", "tls", "notls", "plain"):
raise ValueError(f"invalid TLS flag {flag!r} in Electrum server {entry!r}")
use_ssl = flag in ("ssl", "tls")
endpoints.append(ElectrumEndpoint(host, int(port), use_ssl))
deduped: list[ElectrumEndpoint] = []
for endpoint in endpoints:
if endpoint not in deduped:
deduped.append(endpoint)
return deduped
# Every request is bounded: without this, a half-open socket (the peer vanished
# without a FIN, or the read loop died — see _read_loop) leaves `await future`
# hanging forever, and with it whatever was awaiting the call. That used to be
# unbounded, which meant a POST /bets could hang while holding the per-user lock
# and the confirmation poller could stop polling permanently.
_REQUEST_TIMEOUT_SECONDS = 15
class ElectrumError(Exception):
@@ -15,6 +76,11 @@ class ElectrumClient:
arrive under the *same* method name as the subscribe call, multiplexed for every
scripthash subscribed — callers read `notifications(method)` and, for scripthash
pushes, dispatch on `params[0]` (the scripthash) themselves.
A dead connection is observable rather than silent: `wait_closed()` resolves as
soon as the read loop terminates for any reason, which is what lets
ElectrumListener notice the drop and reconnect instead of waiting forever on
notification queues nobody will ever fill again.
"""
def __init__(self, host: str, port: int, use_ssl: bool = True):
@@ -27,6 +93,7 @@ class ElectrumClient:
self._pending: dict[int, asyncio.Future] = {}
self._subscriptions: dict[str, asyncio.Queue] = {}
self._read_task: asyncio.Task | None = None
self._closed = asyncio.Event()
async def connect(self) -> None:
# Electrum servers commonly present self-signed certs; the protocol's trust
@@ -42,25 +109,51 @@ class ElectrumClient:
await self.request("server.version", ["plm-lottery", "1.4"])
async def close(self) -> None:
self._closed.set()
if self._read_task is not None:
self._read_task.cancel()
if self._writer is not None:
self._writer.close()
try:
await asyncio.wait_for(self._writer.wait_closed(), timeout=2)
except (ssl.SSLError, TimeoutError, asyncio.TimeoutError):
except (ssl.SSLError, TimeoutError, asyncio.TimeoutError, ConnectionError):
pass # some Electrum servers don't send a clean TLS close_notify
async def wait_closed(self) -> None:
"""Resolves once this connection is gone — read loop finished (peer closed,
protocol error, TLS failure) or close() was called. ElectrumListener races
this against its notification consumers so a drop triggers a reconnect."""
await self._closed.wait()
async def request(self, method: str, params: list | None = None) -> object:
if self._writer is None:
if self._writer is None or self._closed.is_set():
raise ElectrumError("not connected")
request_id = next(self._id_counter)
future: asyncio.Future = asyncio.get_event_loop().create_future()
future: asyncio.Future = asyncio.get_running_loop().create_future()
self._pending[request_id] = future
payload = json.dumps({"id": request_id, "method": method, "params": params or []}) + "\n"
self._writer.write(payload.encode())
await self._writer.drain()
return await future
try:
self._writer.write(payload.encode())
await self._writer.drain()
except (ConnectionError, ssl.SSLError, OSError) as exc:
self._pending.pop(request_id, None)
self._closed.set()
raise ElectrumError(f"write failed: {exc}") from exc
try:
return await asyncio.wait_for(future, timeout=_REQUEST_TIMEOUT_SECONDS)
except (TimeoutError, asyncio.TimeoutError) as exc:
self._pending.pop(request_id, None)
# A server that owes us a reply and never sends one is indistinguishable
# from a dead socket, and retrying on the same connection would keep
# hitting it — tear it down so the listener reconnects.
self._closed.set()
raise ElectrumError(f"{method} timed out after {_REQUEST_TIMEOUT_SECONDS}s") from exc
async def ping(self) -> None:
"""Keepalive: Electrum servers drop idle connections (commonly after ~10
minutes), which on a quiet instance would otherwise be the normal way this
connection dies. Called periodically by ElectrumListener."""
await self.request("server.ping")
def notifications(self, method: str) -> asyncio.Queue:
return self._subscriptions.setdefault(method, asyncio.Queue())
@@ -92,6 +185,12 @@ class ElectrumClient:
message = json.loads(line)
self._dispatch(message)
finally:
# Whatever ended this loop — clean EOF, protocol error, 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
# would ever fill again, forever (B-01).
self._closed.set()
error = ElectrumError("connection closed")
for future in self._pending.values():
if not future.done():
+122 -27
View File
@@ -7,31 +7,57 @@ from sqlalchemy.ext.asyncio import async_sessionmaker
from app.db.models import User
from app.deposits.service import credit_confirmed_utxos
from app.electrum.client import ElectrumClient
from app.electrum.client import ElectrumClient, ElectrumEndpoint
from app.electrum.scripthash import address_to_scripthash
from app.rounds.events import broadcaster
logger = logging.getLogger(__name__)
# How often to ping the server on an otherwise idle connection. Electrum servers
# commonly drop idle clients after ~10 minutes, so on a quiet instance this is the
# difference between noticing the drop in a minute and never noticing it at all.
_PING_INTERVAL_SECONDS = 60
class ElectrumListener:
"""Long-lived background task: keeps one Electrum connection open, subscribes
every user's address (plus any address added later via add_address), and
credits confirmed deposits as scripthash-change notifications arrive.
Reconnects with backoff on any failure; a fresh connection re-subscribes to
every user pulled straight from the DB, so no in-memory subscription state is
ever a stale source of truth.
Reconnects on any failure; a fresh connection re-subscribes to every user
pulled straight from the DB, so no in-memory subscription state is ever a
stale source of truth.
Connections rotate over `endpoints`: after a failed or dropped session the
next server in the list is tried immediately, and only once every server has
had a turn does the backoff sleep kick in. That way a single dead server costs
one attempt rather than an outage, while a genuinely offline network (all
servers down) still backs off instead of spinning.
"""
def __init__(self, client_factory: Callable[[], ElectrumClient], session_factory: async_sessionmaker):
def __init__(
self,
client_factory: Callable[[ElectrumEndpoint], ElectrumClient],
session_factory: async_sessionmaker,
endpoints: list[ElectrumEndpoint] | None = None,
):
self._client_factory = client_factory
self._session_factory = session_factory
self._endpoints = list(endpoints or [])
self._endpoint_index = 0
self._scripthash_to_user: dict[str, int] = {}
self.tip_height: int = 0
self.tip_header_hex: str | None = None
self.client: ElectrumClient | None = None
@property
def current_endpoint(self) -> ElectrumEndpoint | None:
"""Which server the next (or current) session uses — for logging and for
the admin dashboard's connection status."""
if not self._endpoints:
return None
return self._endpoints[self._endpoint_index]
def address_for_new_user(self, user_id: int, address: str) -> None:
"""Called right after a user registers so their deposit address starts
being watched immediately, without waiting for the next reconnect cycle."""
@@ -42,39 +68,88 @@ class ElectrumListener:
async def run(self) -> None:
backoff = 1
failures_this_cycle = 0
while True:
endpoint = self.current_endpoint
if endpoint is None:
logger.error("no Electrum endpoints configured; listener idle")
return
connected = False
try:
await self._run_once()
connected = await self._run_once(endpoint)
except asyncio.CancelledError:
raise
except Exception:
logger.exception("Electrum listener error, reconnecting in %ss", backoff)
logger.exception("Electrum session on %s failed", endpoint)
finally:
self.client = None
await asyncio.sleep(backoff)
backoff = min(backoff * 2, 30)
continue
backoff = 1
async def _run_once(self) -> None:
client = self._client_factory()
# Move on to the next server regardless of why this session ended: a
# server that just dropped us has no claim on being tried first again.
if len(self._endpoints) > 1:
self._endpoint_index = (self._endpoint_index + 1) % len(self._endpoints)
if connected:
# We did reach a server, so the network is up — don't let an earlier
# streak of failures keep penalizing the next attempt.
backoff = 1
failures_this_cycle = 0
logger.info("Electrum connection to %s ended, reconnecting", endpoint)
continue
failures_this_cycle += 1
if failures_this_cycle < len(self._endpoints):
continue # other servers untried — go straight to the next one
failures_this_cycle = 0
logger.warning("all %s Electrum server(s) unreachable, retrying in %ss", len(self._endpoints), backoff)
await asyncio.sleep(backoff)
backoff = min(backoff * 2, 30)
async def _run_once(self, endpoint: ElectrumEndpoint) -> bool:
"""One connection's whole lifetime. Returns True if the connection was
actually established (so the caller knows the network is reachable and can
reset its backoff), False if it never got that far."""
client = self._client_factory(endpoint)
await client.connect()
self.client = client
logger.info("Electrum connected to %s", endpoint)
header = await client.subscribe_headers()
self.tip_height = header["height"]
self.tip_header_hex = header.get("hex")
await self._subscribe_all_users()
headers_queue = client.notifications("blockchain.headers.subscribe")
scripthash_queue = client.notifications("blockchain.scripthash.subscribe")
try:
await asyncio.gather(
self._consume_headers(headers_queue),
self._consume_scripthash(scripthash_queue),
)
header = await client.subscribe_headers()
self._apply_header(header)
await self._subscribe_all_users()
headers_queue = client.notifications("blockchain.headers.subscribe")
scripthash_queue = client.notifications("blockchain.scripthash.subscribe")
# The consumers below block on their queues forever by design, so they
# can never notice the connection dying — client.wait_closed() and the
# 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_scripthash(scripthash_queue)),
asyncio.create_task(self._keepalive(client)),
asyncio.create_task(client.wait_closed()),
]
try:
done, still_running = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
finally:
for task in tasks:
task.cancel()
for task in done:
exc = task.exception()
if exc is not None:
logger.warning("Electrum session on %s ending: %r", endpoint, exc)
finally:
self.client = None
await client.close()
return True
async def _keepalive(self, client: ElectrumClient) -> None:
while True:
await asyncio.sleep(_PING_INTERVAL_SECONDS)
await client.ping() # raises (and so ends the session) on timeout or a dead socket
async def _subscribe_all_users(self) -> None:
async with self._session_factory() as session:
@@ -89,12 +164,32 @@ 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.
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.
"""
height = header["height"]
if height < self.tip_height:
logger.warning(
"ignoring Electrum header at height %s, below the current tip %s (reorg or server switch?)",
height,
self.tip_height,
)
return
self.tip_height = height
self.tip_header_hex = header.get("hex")
async def _consume_headers(self, queue: asyncio.Queue) -> None:
while True:
params = await queue.get()
for header in params:
self.tip_height = header["height"]
self.tip_header_hex = header.get("hex")
self._apply_header(header)
# 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.
+43 -9
View File
@@ -1,8 +1,9 @@
import asyncio
import logging
from contextlib import asynccontextmanager
from pathlib import Path
from fastapi import FastAPI, Request
from fastapi import FastAPI, Request, status
from fastapi.responses import FileResponse, JSONResponse
from fastapi.staticfiles import StaticFiles
@@ -20,37 +21,54 @@ from app.api.routes.rounds import router as rounds_router
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.config import settings
from app.api.errors import ApiError, http_error
from app.config import settings, validate_runtime_secrets
from app.db.base import AsyncSessionLocal
from app.electrum.client import ElectrumClient
from app.electrum.client import ElectrumClient, ElectrumEndpoint, parse_endpoints
from app.electrum.listener import ElectrumListener
from app.rounds.scheduler import RoundScheduler
from app.tx.broadcast import RbfBumper
from app.tx.confirmation import ConfirmationPoller
from app.tx.locks import UserLocks
from app.tx.reconcile import PendingTransactionReconciler
logger = logging.getLogger(__name__)
def _make_electrum_client() -> ElectrumClient:
return ElectrumClient(settings.electrum_host, settings.electrum_port, settings.electrum_use_ssl)
def _make_electrum_client(endpoint: ElectrumEndpoint) -> ElectrumClient:
return ElectrumClient(endpoint.host, endpoint.port, endpoint.use_ssl)
@asynccontextmanager
async def lifespan(app: FastAPI):
listener = ElectrumListener(_make_electrum_client, AsyncSessionLocal)
# Refuses to serve rather than starting up half-configured — see B-15 in BUGS.md.
validate_runtime_secrets()
endpoints = parse_endpoints(
settings.electrum_host,
settings.electrum_port,
settings.electrum_use_ssl,
settings.electrum_fallback_servers,
)
logger.info("Electrum endpoints (in rotation order): %s", ", ".join(str(e) for e in endpoints))
listener = ElectrumListener(_make_electrum_client, AsyncSessionLocal, endpoints)
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)
# 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)
tasks = [
asyncio.create_task(listener.run()),
asyncio.create_task(scheduler.run()),
asyncio.create_task(poller.run()),
asyncio.create_task(bumper.run()),
asyncio.create_task(reconciler.run()),
]
try:
yield
@@ -73,8 +91,14 @@ app.include_router(rounds_router)
@app.exception_handler(Exception)
async def log_unhandled_exception(request: Request, exc: Exception) -> JSONResponse:
"""Answers with the same structured `detail` shape as every deliberate failure
(app/api/errors.py) so clients never have to special-case unexpected errors.
The exception itself stays in logs/app.log only — never in the response body."""
logger.exception("Unhandled error on %s %s", request.method, request.url.path)
return JSONResponse(status_code=500, content={"detail": "internal server error"})
return JSONResponse(
status_code=500,
content={"detail": ApiError("internal_error", "internal server error").as_detail()},
)
@app.get("/health")
@@ -95,12 +119,22 @@ async def admin_panel() -> FileResponse:
return FileResponse("app/static/admin.html", headers=_NO_STORE_HEADERS)
_USER_GUIDE_PATH = Path("docs/guida-utente.md")
@app.get("/guida", include_in_schema=False)
async def user_guide() -> FileResponse:
"""Serves docs/guida-utente.md as plain text so it opens inline in the
browser (no markdown rendering — keeps this simple), linked from the
navbar's help button in app/static/index.html."""
return FileResponse("docs/guida-utente.md", media_type="text/plain; charset=utf-8")
navbar's help button in app/static/index.html.
The Dockerfile must COPY docs/ for this to exist inside the container (it
didn't, which made this a guaranteed 500 in every real deployment — B-16).
Answers a clean 404 if the file is missing rather than an unhandled error."""
if not _USER_GUIDE_PATH.is_file():
logger.error("user guide missing at %s (is docs/ shipped in the image?)", _USER_GUIDE_PATH)
raise http_error(status.HTTP_404_NOT_FOUND, "guide_unavailable", "user guide not available")
return FileResponse(_USER_GUIDE_PATH, media_type="text/plain; charset=utf-8")
app.mount("/", StaticFiles(directory="app/static", html=True), name="static")
+7 -1
View File
@@ -8,7 +8,13 @@ from app.tx.confirmation import register_handler
async def _on_payout_confirmed(session: AsyncSession, pending: PendingTransaction) -> None:
round_ = await session.scalar(select(Round).where(Round.payout_txid == pending.current_txid))
# Resolved by round_id rather than by payout_txid: an RBF-bumped payout confirms
# under a different txid than the one first recorded (B-02).
round_ = None
if pending.round_id is not None:
round_ = await session.get(Round, pending.round_id)
if round_ is None:
round_ = await session.scalar(select(Round).where(Round.payout_txid == pending.current_txid))
if round_ is not None and round_.status == "paying_out":
round_.status = "closed"
# closed_at is what round_cooldown_seconds counts from (service.py's
+76 -29
View File
@@ -75,10 +75,17 @@ class RoundScheduler:
broadcaster.publish()
async with self._session_factory() as session:
# "building" counts as in-flight too: it's a bet mid-broadcast (see
# bets/service.py's two-phase write). A bet that never confirms is
# eventually removed by app/tx/reconcile.py, which is what stops this
# wait from being unbounded.
pending_count = await session.scalar(
select(func.count())
.select_from(RoundParticipant)
.where(RoundParticipant.round_id == round_id, RoundParticipant.status == "broadcast")
.where(
RoundParticipant.round_id == round_id,
RoundParticipant.status.in_(("building", "broadcast")),
)
)
if pending_count:
return # wait for in-flight bets to confirm before closing; stays "closing"
@@ -154,49 +161,73 @@ class RoundScheduler:
return self._listener.tip_height, header_hex_to_block_hash(self._listener.tip_header_hex)
async def _trigger_payout(self, round_id: int) -> None:
"""Three phases, so no DB session is held across a network call (B-18): read
what's needed, do the chain work, then persist the outcome."""
client = self._listener.client
if client is None:
logger.error("round %s payout deferred: not connected", round_id)
return
# --- Phase 1: read (session closed before any network I/O) ---------------
async with self._session_factory() as session:
round_ = await session.get(Round, round_id)
config = await get_round_config(session)
if not config.fee_address:
logger.error(
"round %s payout blocked: no fee_address configured (set it via the admin endpoint)", round_id
)
return
fee_address = config.fee_address
fee_rate = config.fee_rate_sat_vb
pool_amount_sats = round_.pool_amount_sats
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
await session.commit() # get_round_config may have created the row
winner = await session.get(User, round_.winner_user_id)
winner_share = round_.pool_amount_sats * 70 // 100
commission_share = round_.pool_amount_sats - winner_share # remainder from rounding goes to fees
if not fee_address:
logger.error(
"round %s payout blocked: no fee_address configured (set it via the admin endpoint)", round_id
)
return
if winner_address is None:
logger.error("round %s payout blocked: winner user %s not found", round_id, winner_user_id)
return
winner_share = pool_amount_sats * 70 // 100
commission_share = pool_amount_sats - winner_share # remainder from rounding goes to fees
# --- Phase 2: build and broadcast ----------------------------------------
try:
pool_key = derive_pool_key()
pool_script_obj = script.p2wpkh(pool_key.to_public())
pool_address = pool_script_obj.address(network=PLM_MAINNET)
pool_scripthash = address_to_scripthash(pool_address)
entries = await client.listunspent(pool_scripthash)
entries = await client.listunspent(address_to_scripthash(pool_address))
utxos = [Utxo(e["tx_hash"], e["tx_pos"], e["value"]) for e in entries if e["height"] > 0]
try:
built = build_payout_transaction(
signing_key=pool_key,
from_script=pool_script_obj,
utxos=utxos,
winner_address=winner.address,
winner_share_sats=winner_share,
fee_address=config.fee_address,
commission_sats=commission_share,
change_address=pool_address,
fee_rate_sat_vb=config.fee_rate_sat_vb,
)
except InsufficientFundsError:
logger.exception("round %s payout failed: insufficient pool UTXOs", round_id)
return
built = build_payout_transaction(
signing_key=pool_key,
from_script=pool_script_obj,
utxos=utxos,
winner_address=winner_address,
winner_share_sats=winner_share,
fee_address=fee_address,
commission_sats=commission_share,
change_address=pool_address,
fee_rate_sat_vb=fee_rate,
)
await client.broadcast(built.raw_hex)
except InsufficientFundsError:
logger.exception("round %s payout failed: insufficient pool UTXOs", round_id)
return
except Exception:
# Anything else — a malformed fee_address (EmbitError), a rejected
# broadcast, a dead connection. This used to escape all the way to
# run()'s catch-all, which logged it without recording anything, leaving
# no trace of *why* the round was stuck (B-05). The round stays in
# "paying_out" either way: automatic payout retry is still an open gap.
logger.exception("round %s payout failed", round_id)
await self._log_payout_failure(round_id, winner_user_id)
return
# --- Phase 3: persist -----------------------------------------------------
async with self._session_factory() as session:
round_ = await session.get(Round, round_id)
round_.winner_amount_sats = built.winner_sats
round_.fee_amount_sats = built.commission_sats
round_.payout_txid = built.txid
@@ -205,7 +236,7 @@ class RoundScheduler:
kind="payout",
round_id=round_id,
current_txid=built.txid,
fee_rate_sat_vb=config.fee_rate_sat_vb,
fee_rate_sat_vb=fee_rate,
raw_tx_hex=built.raw_hex,
status="pending",
)
@@ -214,9 +245,25 @@ class RoundScheduler:
session,
"payout_sent",
{"txid": built.txid, "winner_sats": built.winner_sats, "commission_sats": built.commission_sats},
user_id=round_.winner_user_id,
user_id=winner_user_id,
round_id=round_id,
)
await session.commit()
logger.info("round %s payout broadcast: txid=%s", round_id, built.txid)
async def _log_payout_failure(self, round_id: int, winner_user_id: int | None) -> None:
"""Leaves an operator-visible trace in the audit log for a round stuck in
"paying_out" — the logs alone don't show up in /admin."""
try:
async with self._session_factory() as session:
await write_audit_log(
session,
"payout_failed",
{"round_id": round_id},
user_id=winner_user_id,
round_id=round_id,
)
await session.commit()
except Exception:
logger.exception("could not record the payout failure of round %s", round_id)
+55 -11
View File
@@ -1,20 +1,43 @@
import logging
from datetime import datetime, timedelta, timezone
from sqlalchemy import select
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession
from app.db.models import Round
from app.rounds.config import get_round_config
from app.rounds.events import broadcaster
logger = logging.getLogger(__name__)
_ACTIVE_STATUSES = ("open", "closing", "drawing", "paying_out")
# Bounded: a conflict means someone else is opening a round right now, so a couple
# of retries is plenty. Unbounded retries could spin if the invariant were ever
# broken in a way we don't anticipate.
_OPEN_ROUND_ATTEMPTS = 3
async def get_active_round(session: AsyncSession) -> Round | None:
"""The round currently in progress (in any non-closed state), if any. Rounds
never overlap: a new round only opens once the previous one is fully closed
(payout confirmed, or no participants to pay out)."""
return await session.scalar(select(Round).where(Round.status.in_(_ACTIVE_STATUSES)).order_by(Round.id.desc()))
(payout confirmed, or no participants to pay out).
The database enforces "at most one active round" (ix_rounds_single_active, see
app/db/models.py), so the ordering below is belt-and-braces; if it ever does
see two, that's a broken invariant and worth a loud log rather than silently
picking one."""
active = (
await session.scalars(select(Round).where(Round.status.in_(_ACTIVE_STATUSES)).order_by(Round.id.desc()))
).all()
if len(active) > 1:
logger.error(
"invariant violated: %s rounds are active at once (ids=%s) — using the newest",
len(active),
[r.id for r in active],
)
return active[0] if active else None
def round_accepts_bets(round_: Round, round_duration_seconds: int) -> bool:
@@ -55,12 +78,33 @@ async def open_new_round_if_needed(session: AsyncSession) -> Round | None:
if datetime.now(timezone.utc) < closed_at + timedelta(seconds=config.round_cooldown_seconds):
return None
round_ = Round(status="open")
session.add(round_)
await session.flush()
# Published pre-commit (the caller commits right after) — acceptable: this
# 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.
broadcaster.publish()
return round_
for attempt in range(_OPEN_ROUND_ATTEMPTS):
round_ = Round(status="open")
session.add(round_)
try:
await session.flush()
except IntegrityError:
# Another caller (the scheduler tick, or a concurrent place_bet) got
# there first — ix_rounds_single_active turns what used to be two live
# rounds into a clean failure here. Roll our insert back and use theirs.
# Safe to roll back: this runs before its callers have written anything
# else in this session.
await session.rollback()
existing = await get_active_round(session)
if existing is not None:
logger.info("lost the race to open a round; using round %s", existing.id)
return existing
# Nothing active *and* the insert conflicted: the winner's transaction
# hadn't committed yet when we looked. Try again rather than failing the
# caller — a bet shouldn't 500 because of a scheduler tick's timing.
logger.info("round-open conflict with nothing active yet (attempt %s), retrying", attempt + 1)
continue
# Published pre-commit (the caller commits right after) — acceptable: this
# 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.
broadcaster.publish()
return round_
logger.error("could not open a round after %s attempts", _OPEN_ROUND_ATTEMPTS)
return await get_active_round(session)
+12 -4
View File
@@ -1,4 +1,12 @@
const SATS_PER_PLM = 100000000;
// Display formatter: a raw sats/SATS_PER_PLM division renders binary
// floating-point artefacts (0.7000000000000001) in the tables below (B-22).
// Input fields keep the raw value — they have to stay parseable.
function fmtPlm(sats) {
if (sats === null || sats === undefined) return '—';
return new Intl.NumberFormat('it-IT', { maximumFractionDigits: 8 }).format(sats / SATS_PER_PLM);
}
let adminToken = sessionStorage.getItem('plm_admin_token');
function toast(message, type) {
@@ -218,7 +226,7 @@ async function loadUsers() {
<td>${u.id}</td>
<td>${escapeHtml(u.username)}</td>
<td class="addr">${escapeHtml(u.address)}</td>
<td>${u.balance_sats / SATS_PER_PLM}</td>
<td>${fmtPlm(u.balance_sats)}</td>
<td>${fmtDate(u.created_at)}</td>
<td>
<button class="reveal" onclick="revealPrivkey(${u.id}, this)">Mostra</button>
@@ -288,9 +296,9 @@ async function loadRounds() {
<td>${badge(r.status)}</td>
<td>${fmtDate(r.opened_at)}</td>
<td>${r.winner_username ? escapeHtml(r.winner_username) : '—'}</td>
<td>${r.pool_amount_sats != null ? r.pool_amount_sats / SATS_PER_PLM : '—'}</td>
<td>${r.winner_amount_sats != null ? r.winner_amount_sats / SATS_PER_PLM : '—'}</td>
<td>${r.fee_amount_sats != null ? r.fee_amount_sats / SATS_PER_PLM : '—'}</td>
<td>${fmtPlm(r.pool_amount_sats)}</td>
<td>${fmtPlm(r.winner_amount_sats)}</td>
<td>${fmtPlm(r.fee_amount_sats)}</td>
<td class="txid">${r.payout_txid ? escapeHtml(r.payout_txid) : '—'}</td>
</tr>
`).join('') || '<tr><td colspan="8" class="hint">Nessun round ancora.</td></tr>';
+54 -16
View File
@@ -1,5 +1,19 @@
const SATS_PER_PLM = 100000000;
// Every amount displayed goes through here. A bare sats/SATS_PER_PLM division
// leaks binary floating-point artefacts into the UI — a 0.7 PLM jackpot rendering
// as 0.7000000000000001 (B-22). Trailing zeros are trimmed so ordinary amounts
// stay readable, and grouping follows the selected language.
// Amounts sent *to* the server must NOT use this — they keep going through
// Math.round(x * SATS_PER_PLM), since this returns a formatted string.
function formatPlm(sats) {
if (sats === null || sats === undefined || Number.isNaN(sats)) return '—';
return new Intl.NumberFormat(currentDateLocale(), {
minimumFractionDigits: 0,
maximumFractionDigits: 8,
}).format(sats / SATS_PER_PLM);
}
let token = localStorage.getItem('plm_token');
let username = localStorage.getItem('plm_username');
let address = localStorage.getItem('plm_address');
@@ -17,17 +31,35 @@ function toast(message, type) {
// <span data-i18n=...>, both of which a textContent round-trip would flatten away
// — losing the icon for good and, worse, stripping the data-i18n hook so the
// button would stop following later language changes.
//
// Only the outermost call owns the markup. refreshMe() is fired from the SSE
// handler, the poll chain, placeBet, withdraw and showDashboard, all sharing
// #refresh-btn: two overlapping calls used to make the second one snapshot the
// *loading* label and then restore it permanently, leaving the button stuck on
// "Aggiornamento…" (B-23). A nested call now just awaits the one already running.
const _loadingByButton = new WeakMap();
async function withLoading(button, label, fn) {
const inFlight = _loadingByButton.get(button);
if (inFlight) {
await inFlight.catch(() => {}); // its own caller reports the failure
return fn();
}
const original = button.innerHTML;
button.disabled = true;
button.textContent = label;
try {
await fn();
} finally {
button.disabled = false;
button.innerHTML = original;
applyStaticTranslations(button); // the snapshot may predate a language switch made while loading
}
const run = (async () => {
try {
await fn();
} finally {
button.disabled = false;
button.innerHTML = original;
applyStaticTranslations(button); // the snapshot may predate a language switch made while loading
_loadingByButton.delete(button);
}
})();
_loadingByButton.set(button, run);
return run;
}
const REQUEST_TIMEOUT_MS = 15000;
@@ -83,7 +115,7 @@ function errorParams(params) {
const out = { ...(params || {}) };
for (const [key, value] of Object.entries(params || {})) {
if (key.endsWith('_sats') && typeof value === 'number') {
out[key.slice(0, -5) + '_plm'] = value / SATS_PER_PLM;
out[key.slice(0, -5) + '_plm'] = formatPlm(value);
}
}
return out;
@@ -292,7 +324,7 @@ function renderPersistedResult(result) {
setRoundInfoVisible(false);
setResultBoxVisible(
true,
result.won ? t('result.win', { amount: result.amount_sats / SATS_PER_PLM }) : t('result.lose'),
result.won ? t('result.win', { amount: formatPlm(result.amount_sats) }) : t('result.lose'),
result.won ? 'win' : 'lose'
);
}
@@ -328,7 +360,7 @@ async function checkLastRoundResult() {
persistResult(data.round_id, data.won, data.amount_sats);
renderPersistedResult({ won: data.won, amount_sats: data.amount_sats });
if (data.won) {
const won = data.amount_sats / SATS_PER_PLM;
const won = formatPlm(data.amount_sats);
toast(t('toast.roundWon', { id: data.round_id, amount: won }), 'success');
refreshMe();
}
@@ -395,7 +427,7 @@ function renderBetButton() {
if (btn.disabled) return;
btn.textContent = betAmountSats === null
? t('bet.buttonNoAmount')
: t('bet.button', { amount: betAmountSats / SATS_PER_PLM });
: t('bet.button', { amount: formatPlm(betAmountSats) });
}
function showNormalState() {
@@ -422,7 +454,7 @@ async function refreshRound() {
document.getElementById('round-players').textContent = data.participant_count;
const jackpotEl = document.getElementById('round-jackpot');
const jackpotValue = data.jackpot_sats / SATS_PER_PLM;
jackpotEl.textContent = jackpotValue;
jackpotEl.textContent = formatPlm(data.jackpot_sats);
if (lastJackpotValue !== null && jackpotValue !== lastJackpotValue) {
jackpotEl.classList.remove('jackpot-bump');
void jackpotEl.offsetWidth; // restart the animation
@@ -464,7 +496,7 @@ async function refreshRound() {
if (!alreadyKnown) {
persistResult(data.round_id, won, data.winner_amount_sats);
if (won) {
const wonAmount = (data.winner_amount_sats / SATS_PER_PLM);
const wonAmount = formatPlm(data.winner_amount_sats);
toast(t('toast.roundWon', { id: data.round_id, amount: wonAmount }), 'success');
refreshMe(); // the win toast is useless if the balance card still shows the pre-payout amount
}
@@ -555,6 +587,12 @@ async function register() {
toast(t('toast.passwordMismatch'), 'error');
return;
}
// Mirrors what the server now enforces (app/auth/routes.py's RegisterRequest),
// so the failure is immediate and translated instead of a generic 422 (B-12).
if (p.length < 8) {
toast(t('toast.passwordTooShort'), 'error');
return;
}
await withLoading(btn, t('loading.creating'), async () => {
try {
const data = await call('POST', '/auth/register', { username: u, password: p });
@@ -657,7 +695,7 @@ let myBalanceSats = 0; // confirmed, spendable balance — what withdrawals/bets
// has_pending is true so it's clear the figure isn't final yet.
function setBalanceDisplay(elementId, pendingBalanceSats, hasPending) {
const el = document.getElementById(elementId);
el.textContent = pendingBalanceSats / SATS_PER_PLM;
el.textContent = formatPlm(pendingBalanceSats);
el.classList.toggle('balance-pending', hasPending);
el.classList.toggle('balance-confirmed', !hasPending);
}
@@ -670,14 +708,14 @@ async function refreshMe() {
myUserId = data.id;
myBalanceSats = data.balance_sats;
setBalanceDisplay('dash-balance', data.pending_balance_sats, data.has_pending);
document.getElementById('navbar-balance').textContent = (data.pending_balance_sats / SATS_PER_PLM) + ' PLM';
document.getElementById('navbar-balance').textContent = formatPlm(data.pending_balance_sats) + ' PLM';
document.getElementById('navbar-balance').classList.toggle('balance-pending', data.has_pending);
document.getElementById('navbar-balance').classList.toggle('balance-confirmed', !data.has_pending);
document.getElementById('profile-username').textContent = data.username;
document.getElementById('profile-address').textContent = data.address;
setBalanceDisplay('profile-balance', data.pending_balance_sats, data.has_pending);
document.getElementById('profile-created-at').textContent = new Date(data.created_at).toLocaleDateString(currentDateLocale());
document.getElementById('wd-full-amount-value').textContent = data.balance_sats / SATS_PER_PLM;
document.getElementById('wd-full-amount-value').textContent = formatPlm(data.balance_sats);
if (document.getElementById('wd-full-amount').checked) {
document.getElementById('wd-amount').value = data.balance_sats / SATS_PER_PLM;
}
+35
View File
@@ -132,6 +132,11 @@ const TRANSLATIONS = {
'error.session_expired': 'Session expired, please log in again.',
'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.amount_below_dust_limit': 'The amount is too small to be sent.',
'error.withdrawal_to_own_address': 'That is your own deposit address — 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.',
'loading.creating': 'Creating…',
'loading.loggingIn': 'Logging in…',
@@ -264,6 +269,11 @@ const TRANSLATIONS = {
'error.session_expired': 'Sessione scaduta, accedi di nuovo.',
'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.amount_below_dust_limit': "L'importo è troppo basso per essere inviato.",
'error.withdrawal_to_own_address': 'Questo è il tuo indirizzo di deposito — 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.',
'loading.creating': 'Creazione…',
'loading.loggingIn': 'Accesso…',
@@ -396,6 +406,11 @@ const TRANSLATIONS = {
'error.session_expired': 'Sesión caducada, vuelve a iniciar sesión.',
'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.amount_below_dust_limit': 'El importe es demasiado pequeño para enviarse.',
'error.withdrawal_to_own_address': 'Esa es tu propia dirección de depósito — 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.',
'loading.creating': 'Creando…',
'loading.loggingIn': 'Entrando…',
@@ -528,6 +543,11 @@ const TRANSLATIONS = {
'error.session_expired': 'Session expirée, veuillez vous reconnecter.',
'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.amount_below_dust_limit': "Le montant est trop faible pour être envoyé.",
'error.withdrawal_to_own_address': "C'est votre propre adresse de dépôt — 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.",
'loading.creating': 'Création…',
'loading.loggingIn': 'Connexion…',
@@ -660,6 +680,11 @@ const TRANSLATIONS = {
'error.session_expired': 'Sitzung abgelaufen, bitte melde dich erneut an.',
'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.amount_below_dust_limit': 'Der Betrag ist zu klein, um gesendet zu werden.',
'error.withdrawal_to_own_address': 'Das ist deine eigene Einzahlungsadresse — 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.',
'loading.creating': 'Wird erstellt…',
'loading.loggingIn': 'Anmeldung…',
@@ -792,6 +817,11 @@ const TRANSLATIONS = {
'error.session_expired': 'Сессия истекла, войдите снова.',
'error.invalid_request': 'Некорректный запрос, проверьте введённые данные.',
'error.invalid_amount': 'Введите сумму больше нуля.',
'error.broadcast_failed': 'Сеть отклонила транзакцию. Попробуйте ещё раз через минуту.',
'error.amount_below_dust_limit': 'Сумма слишком мала для отправки.',
'error.withdrawal_to_own_address': 'Это ваш собственный адрес для депозита — выводите на внешний кошелёк.',
'error.internal_error': 'Непредвиденная ошибка сервера. Попробуйте ещё раз через минуту.',
'error.guide_unavailable': 'Руководство сейчас недоступно.',
'loading.creating': 'Создание…',
'loading.loggingIn': 'Вход…',
@@ -924,6 +954,11 @@ const TRANSLATIONS = {
'error.session_expired': '会话已过期,请重新登录。',
'error.invalid_request': '请求无效,请检查填写的内容。',
'error.invalid_amount': '请输入大于零的金额。',
'error.broadcast_failed': '网络拒绝了该交易,请稍后重试。',
'error.amount_below_dust_limit': '金额过小,无法发送。',
'error.withdrawal_to_own_address': '这是你自己的充值地址 — 请提现到外部钱包。',
'error.internal_error': '服务器发生意外错误,请稍后重试。',
'error.guide_unavailable': '指南当前不可用。',
'loading.creating': '正在创建…',
'loading.loggingIn': '正在登录…',
+3 -3
View File
@@ -131,11 +131,11 @@
<div class="tab-panel" id="panel-register">
<label for="reg-username" data-i18n="auth.username">Username</label>
<input id="reg-username" autocomplete="username">
<input id="reg-username" autocomplete="username" minlength="3" maxlength="32" pattern="[A-Za-z0-9_.\-]+" required>
<label for="reg-password" data-i18n="auth.password">Password</label>
<input id="reg-password" type="password" autocomplete="new-password">
<input id="reg-password" type="password" autocomplete="new-password" minlength="8" required>
<label for="reg-password-confirm" data-i18n="auth.passwordConfirm">Conferma password</label>
<input id="reg-password-confirm" type="password" autocomplete="new-password">
<input id="reg-password-confirm" type="password" autocomplete="new-password" minlength="8" required>
<button onclick="register()" id="register-btn" data-i18n="auth.registerBtn">Crea account</button>
</div>
</section>
+45 -2
View File
@@ -9,7 +9,7 @@ from embit.finalizer import finalize_psbt
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from app.db.models import PendingTransaction, User
from app.db.models import PendingTransaction, 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
@@ -113,17 +113,60 @@ async def bump_fee(session: AsyncSession, client: ElectrumClient, pending: Pendi
new_txid = final_tx.txid().hex()
await client.broadcast(raw_hex)
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
pending.fee_rate_sat_vb = new_fee_rate
pending.attempt_count += 1
pending.broadcast_at = datetime.now(timezone.utc)
await _retarget_txid_references(session, pending, old_txid, new_txid)
await session.commit()
logger.info("bumped %s pending_transaction %s: %s -> %s", pending.kind, pending.id, pending.current_txid, new_txid)
logger.info("bumped %s pending_transaction %s: %s -> %s", pending.kind, pending.id, old_txid, new_txid)
return new_txid
async def _retarget_txid_references(
session: AsyncSession, pending: PendingTransaction, old_txid: str, new_txid: str
) -> None:
"""A bump changes the txid, and everything that recorded the old one has to
follow — otherwise the bumped tx confirms and nothing recognizes it (B-02).
The worst case was the bet path: _on_bet_confirmed used to look the participant
up by bet_txid, so after a bump it found nothing, the participant stayed
"broadcast" forever, and the scheduler waited on it forever — the round could
never close and the lottery stopped. The handlers now key off immutable ids
(round_id/user_id, withdrawal_id) as well, so this update is about keeping the
stored txids *true* — for the admin UI, for the audit trail, and for
reconcile.py, which matches UtxoEvent.spent_txid against current_txid.
"""
if pending.kind == "bet":
participant = await session.scalar(
select(RoundParticipant).where(
RoundParticipant.round_id == pending.round_id,
RoundParticipant.user_id == pending.user_id,
)
)
if participant is not None:
participant.bet_txid = new_txid
elif pending.kind == "withdrawal" and pending.withdrawal_id is not None:
withdrawal = await session.get(Withdrawal, pending.withdrawal_id)
if withdrawal is not None:
withdrawal.txid = new_txid
elif pending.kind == "payout" and pending.round_id is not None:
round_ = await session.get(Round, pending.round_id)
if round_ is not None and round_.payout_txid == old_txid:
round_.payout_txid = new_txid
# The UTXOs this tx spends are still the same UTXOs — only the id of the tx
# spending them changed. Keeping this in step is what lets reconcile.py tell
# "reserved by this pending tx" from "spent by something else".
spent = (await session.scalars(select(UtxoEvent).where(UtxoEvent.spent_txid == old_txid))).all()
for utxo in spent:
utxo.spent_txid = new_txid
class RbfBumper:
def __init__(self, session_factory: async_sessionmaker, get_client):
self._session_factory = session_factory
+18 -5
View File
@@ -26,14 +26,27 @@ def register_handler(kind: str, handler: ConfirmationHandler) -> None:
async def poll_once(session_factory: async_sessionmaker, client: ElectrumClient) -> int:
async with session_factory() as session:
pending = (
await session.scalars(select(PendingTransaction).where(PendingTransaction.status == "pending"))
# Plain columns, not entities: nothing then outlives the session, so this
# can't break if expire_on_commit is ever turned on (B-21).
candidates = (
await session.execute(
select(
PendingTransaction.id, PendingTransaction.current_txid, PendingTransaction.kind
).where(PendingTransaction.status == "pending")
)
).all()
pending_ids = [p.id for p in pending]
confirmed = 0
for pending_id, txid, kind in [(p.id, p.current_txid, p.kind) for p in pending]:
tx = await client.get_transaction(txid, verbose=True)
for pending_id, txid, kind in candidates:
try:
tx = await client.get_transaction(txid, verbose=True)
except Exception:
# One unresolvable txid must not stop the others: a tx the server no
# longer knows (dropped from the mempool, replaced) used to abort the
# whole pass, so nothing confirmed again until an operator intervened
# (B-03). Abandoning such a row is app/tx/reconcile.py's job, not ours.
logger.warning("could not check pending_transaction %s (txid %s)", pending_id, txid, exc_info=True)
continue
if not tx or tx.get("confirmations", 0) < 1:
continue
async with session_factory() as session:
+244
View File
@@ -0,0 +1,244 @@
"""Resolves in-flight transactions against the chain.
Everything else in this codebase assumes a broadcast either confirms or gets
fee-bumped until it does. Neither is guaranteed: an RBF bump raises RbfError
whenever there's no change output big enough to absorb it (see tx/broadcast.py),
a node can drop a low-fee tx from its mempool, and the process can die between
building a transaction and broadcasting it. Without this module those cases were
permanent: `spent_txid` was set at build time and never cleared, so the coins
stayed spendable on-chain while the database considered them gone — the user's
balance simply lost them, with no path back short of editing the DB by hand
(B-04, and the "building" half of B-08).
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.
* 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.
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.
"""
import asyncio
import logging
from collections.abc import Callable
from datetime import datetime, timedelta, timezone
from embit.transaction import Transaction
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.electrum.client import ElectrumClient
from app.rounds.events import broadcaster
from app.wallet.balance import recompute_balance
logger = logging.getLogger(__name__)
_POLL_INTERVAL_SECONDS = 120
# A "building" row means we never got confirmation that the broadcast happened, so
# it only needs long enough to rule out a request still in flight.
_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.
_ABANDON_AFTER_SECONDS = 6 * 60 * 60
class PendingTransactionReconciler:
def __init__(self, session_factory: async_sessionmaker, get_client: Callable[[], ElectrumClient | None]):
self._session_factory = session_factory
self._get_client = get_client
async def run(self) -> None:
# Runs once promptly at startup: a crash mid-broadcast is exactly the case
# that leaves a "building" row, and the restart is when we can clear it.
while True:
client = self._get_client()
if client is not None:
try:
await reconcile_once(self._session_factory, client)
except asyncio.CancelledError:
raise
except Exception:
logger.exception("pending-transaction reconciliation failed")
await asyncio.sleep(_POLL_INTERVAL_SECONDS)
async def _tx_exists_on_chain(client: ElectrumClient, txid: str) -> bool:
"""True if the server knows this txid at all (mempool or mined). An error reply
means "unknown", which is the answer we're looking for; a transport failure is
*not* — that raises, and the caller leaves the row alone until next time."""
try:
tx = await client.get_transaction(txid, verbose=True)
except Exception as exc:
message = str(exc).lower()
if "missing" in message or "not found" in message or "no such" in message or "unknown" in message:
return False
raise
return bool(tx)
async def reconcile_once(session_factory: async_sessionmaker, client: ElectrumClient) -> int:
"""Returns how many rows were resolved (promoted or abandoned)."""
now = datetime.now(timezone.utc)
async with session_factory() as session:
rows = (
await session.scalars(
select(PendingTransaction).where(PendingTransaction.status.in_(("building", "pending")))
)
).all()
candidates = [
(row.id, row.status, row.current_txid)
for row in rows
if _is_due(row, now)
]
resolved = 0
for row_id, status, txid in candidates:
try:
exists = await _tx_exists_on_chain(client, txid)
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)
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:
if row.status == "building":
await _promote(session, row)
resolved += 1
else:
await _abandon(session, row, "not found on chain")
resolved += 1
await session.commit()
broadcaster.publish()
return resolved
def _is_due(row: PendingTransaction, now: datetime) -> bool:
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 _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."""
row.status = "pending"
if row.kind == "bet":
participant = await session.scalar(
select(RoundParticipant).where(
RoundParticipant.round_id == row.round_id, RoundParticipant.user_id == row.user_id
)
)
if participant is not None and participant.status == "building":
participant.status = "broadcast"
elif row.kind == "withdrawal" and row.withdrawal_id is not None:
withdrawal = await session.get(Withdrawal, row.withdrawal_id)
if withdrawal is not None and withdrawal.status == "building":
withdrawal.status = "broadcast"
await write_audit_log(
session,
"pending_tx_recovered",
{"pending_transaction_id": row.id, "kind": row.kind, "txid": row.current_txid},
user_id=row.user_id,
round_id=row.round_id,
)
logger.info("recovered %s pending_transaction %s: tx %s is on-chain", row.kind, row.id, row.current_txid)
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."""
row.status = "failed"
row.failure_reason = reason[:128]
released = await _release_inputs(session, row)
if row.kind == "bet":
participant = await session.scalar(
select(RoundParticipant).where(
RoundParticipant.round_id == row.round_id, RoundParticipant.user_id == row.user_id
)
)
if participant is not None and participant.status in ("building", "broadcast"):
# The bet never happened, so the user is not in this round. Removing the
# row also unblocks the scheduler, which waits for every non-confirmed
# participant before closing the round.
await session.delete(participant)
elif row.kind == "withdrawal" and row.withdrawal_id is not None:
withdrawal = await session.get(Withdrawal, row.withdrawal_id)
if withdrawal is not None and withdrawal.status in ("building", "broadcast"):
withdrawal.status = "failed"
withdrawal.txid = None
elif row.kind == "payout":
# Payout funds come from the pool address, which isn't tracked in
# utxo_events, so there's nothing to release. Clearing payout_txid leaves the
# round in "paying_out" with no tx attached, which is the state an operator
# (or a future payout-retry routine — still an open gap) can act on.
round_ = await session.get(Round, row.round_id) if row.round_id else None
if round_ is not None and round_.status == "paying_out":
round_.payout_txid = None
logger.error(
"round %s payout tx %s vanished — round needs operator attention", round_.id, row.current_txid
)
if row.user_id is not None:
await recompute_balance(session, row.user_id)
await write_audit_log(
session,
"pending_tx_abandoned",
{
"pending_transaction_id": row.id,
"kind": row.kind,
"txid": row.current_txid,
"reason": reason,
"utxos_released": released,
},
user_id=row.user_id,
round_id=row.round_id,
)
logger.warning(
"abandoned %s pending_transaction %s (txid %s): %s — released %s UTXO(s)",
row.kind,
row.id,
row.current_txid,
reason,
released,
)
async def _release_inputs(session: AsyncSession, row: PendingTransaction) -> 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."""
try:
tx = Transaction.parse(bytes.fromhex(row.raw_tx_hex))
except Exception:
logger.exception("could not parse raw tx of pending_transaction %s; inputs not released", row.id)
return 0
released = 0
for vin in tx.vin:
utxo = await session.scalar(
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:
utxo.spent_txid = None
released += 1
return released
+4 -1
View File
@@ -46,7 +46,10 @@ async def compute_pending_balance(session: AsyncSession, user: User) -> tuple[in
select(PendingTransaction).where(
PendingTransaction.user_id == user.id,
PendingTransaction.kind.in_(("bet", "withdrawal")),
PendingTransaction.status == "pending",
# "building" as well as "pending": a building row's UTXOs are already
# marked spent (see place_bet's two phases), so leaving it out would
# make the displayed balance dip for the duration of the broadcast.
PendingTransaction.status.in_(("building", "pending")),
)
)
).all()
+31 -2
View File
@@ -17,6 +17,14 @@ _P2WPKH_OUTPUT_VBYTES = 31
# input we create so a stuck tx can later be fee-bumped (tx/broadcast.py, stage 9).
RBF_SEQUENCE = 0xFFFFFFFD
# Below this, an output costs more to spend than it's worth and relay policy rejects
# the whole transaction as "dust" — so a small change amount must be left to the fee
# instead of being paid back to ourselves. 294 sat is the standard P2WPKH threshold
# (the output's own 31 vbytes plus the 67-vbyte input needed to spend it, at the
# 3000 sat/kvB dust relay fee). Creating such an output used to make the bet or
# withdrawal fail at broadcast with an opaque error (B-06).
DUST_LIMIT_SATS = 294
class InsufficientFundsError(Exception):
"""`code` is the machine-readable identifier the API layer forwards to the
@@ -81,6 +89,10 @@ def build_signed_transaction(
receives `amount_sats - fee`, change = total_in - amount_sats. This matches the
spec everywhere a single-recipient tx is used (bet, withdrawal): "fee deducted
from the amount being moved", not paid on top by the sender.
A change amount below DUST_LIMIT_SATS is dropped and left to the fee — paying it
back to ourselves would produce an unrelayable transaction. The fee estimate
already assumes two outputs, so dropping one never underpays.
"""
selected, total_in = select_utxos(utxos, amount_sats)
fee = estimate_vsize(len(selected), 2) * fee_rate_sat_vb
@@ -90,6 +102,13 @@ def build_signed_transaction(
"amount too small to cover the network fee", code="amount_below_network_fee"
)
change = total_in - amount_sats
if change < DUST_LIMIT_SATS:
fee += change # dust change is unspendable and unrelayable — miners get it
change = 0
if recipient_amount < DUST_LIMIT_SATS:
raise InsufficientFundsError(
"amount too small to be sent (dust)", code="amount_below_dust_limit"
)
# TransactionInput.txid is natural/display byte order (as in tx_hash from Electrum);
# embit reverses it internally when serializing to wire format.
@@ -147,16 +166,26 @@ def build_payout_transaction(
) -> PayoutTransaction:
"""Build, sign and finalize the round payout: pool -> winner + fee address,
with change back to the pool itself. Per spec, only the winner's share
absorbs the tx fee — the commission (fee_address) output is untouched."""
absorbs the tx fee — the commission (fee_address) output is untouched.
As in build_signed_transaction, dust-sized pool change is left to the fee
rather than creating an unrelayable output (B-06)."""
target = winner_share_sats + commission_sats
selected, total_in = select_utxos(utxos, target)
fee = estimate_vsize(len(selected), 3) * fee_rate_sat_vb # winner + commission + pool change
winner_amount = winner_share_sats - fee
if winner_amount <= 0:
if winner_amount < DUST_LIMIT_SATS:
raise InsufficientFundsError(
"winner share too small to cover the network fee", code="winner_share_below_network_fee"
)
if commission_sats < DUST_LIMIT_SATS:
raise InsufficientFundsError(
"commission share too small to be paid out (dust)", code="commission_below_dust_limit"
)
change = total_in - target
if change < DUST_LIMIT_SATS:
fee += change
change = 0
vin = [TransactionInput(bytes.fromhex(u.txid), u.vout, sequence=RBF_SEQUENCE) for u in selected]
vout = [
+3 -1
View File
@@ -10,7 +10,9 @@ async def _on_withdrawal_confirmed(session: AsyncSession, pending: PendingTransa
if pending.withdrawal_id is None:
return
withdrawal = await session.get(Withdrawal, pending.withdrawal_id)
if withdrawal is not None and withdrawal.status == "broadcast":
# "building" is reachable if we confirmed before the reconciler promoted the row
# (a crash between broadcast and commit — see app/tx/reconcile.py).
if withdrawal is not None and withdrawal.status in ("building", "broadcast"):
withdrawal.status = "confirmed"
withdrawal.confirmed_at = datetime.now(timezone.utc)
+73 -14
View File
@@ -11,7 +11,12 @@ from app.rounds.events import broadcaster
from app.wallet.address import is_valid_plm_address
from app.wallet.balance import recompute_balance
from app.wallet.hd import derive_user_key
from app.wallet.psbt_builder import InsufficientFundsError, Utxo, build_signed_transaction
from app.wallet.psbt_builder import (
BuiltTransaction,
InsufficientFundsError,
Utxo,
build_signed_transaction,
)
class WithdrawalError(ApiError):
@@ -27,6 +32,17 @@ async def request_withdrawal(
if not is_valid_plm_address(external_address):
raise WithdrawalError("invalid_address", "not a valid PLM bech32 address")
# Withdrawing to your own deposit address is a no-op that costs a network fee,
# and it breaks two things that assume the recipient and the change are
# distinguishable by address: the RBF bump would shrink the recipient output
# instead of the change (tx/broadcast.py:_find_change_output), and
# compute_pending_balance would count the amount twice (B-17).
if external_address == user.address:
raise WithdrawalError(
"withdrawal_to_own_address",
"that is your own deposit address — withdraw to an external wallet instead",
)
config = await get_round_config(session)
if amount_sats < config.bet_amount_sats:
raise WithdrawalError(
@@ -60,8 +76,8 @@ async def request_withdrawal(
except InsufficientFundsError as exc:
raise WithdrawalError(exc.code, str(exc)) from exc
await client.broadcast(built.raw_hex)
# Persist the intent before broadcasting, and only promote the rows once the
# network has accepted the tx — same two-phase shape as place_bet (B-08).
spent_by_key = {(u.txid, u.vout): u for u in unspent}
for spent in built.spent_utxos:
spent_by_key[(spent.txid, spent.vout)].spent_txid = built.txid
@@ -73,21 +89,32 @@ async def request_withdrawal(
amount_requested_sats=amount_sats,
amount_sent_sats=built.recipient_sats,
txid=built.txid,
status="broadcast",
status="building",
)
session.add(withdrawal)
await session.flush()
session.add(
PendingTransaction(
kind="withdrawal",
withdrawal_id=withdrawal.id,
user_id=user.id,
current_txid=built.txid,
fee_rate_sat_vb=config.fee_rate_sat_vb,
raw_tx_hex=built.raw_hex,
status="pending",
)
pending = PendingTransaction(
kind="withdrawal",
withdrawal_id=withdrawal.id,
user_id=user.id,
current_txid=built.txid,
fee_rate_sat_vb=config.fee_rate_sat_vb,
raw_tx_hex=built.raw_hex,
status="building",
)
session.add(pending)
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
withdrawal.status = "broadcast"
pending.status = "pending"
await write_audit_log(
session,
"withdrawal_sent",
@@ -99,3 +126,35 @@ async def request_withdrawal(
await session.refresh(withdrawal)
broadcaster.publish() # balance just went "pending" — nudge the dashboard to refetch
return withdrawal
async def _release_failed_withdrawal(
session: AsyncSession,
withdrawal: Withdrawal,
pending: PendingTransaction,
built: BuiltTransaction,
user_id: int,
reason: str,
) -> None:
"""Nothing reached the chain, so free the reserved UTXOs and restore the balance.
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."""
for spent in built.spent_utxos:
row = await session.scalar(
select(UtxoEvent).where(UtxoEvent.txid == spent.txid, UtxoEvent.vout == spent.vout)
)
if row is not None:
row.spent_txid = None
withdrawal.status = "failed"
withdrawal.txid = None
pending.status = "failed"
pending.failure_reason = reason[:128]
await recompute_balance(session, user_id)
await write_audit_log(
session,
"withdrawal_broadcast_failed",
{"txid": built.txid, "reason": reason[:200]},
user_id=user_id,
)
await session.commit()
+22
View File
@@ -108,6 +108,16 @@ piazzate, payout inviati, round chiusi, configurazione modificata, accessi
alle chiavi private, ecc. È il primo posto da controllare per ricostruire
cosa è successo dopo un problema.
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. |
| `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é. |
| `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. |
## Alternative all'interfaccia grafica
Le stesse operazioni si possono fare da terminale o da Swagger UI
@@ -125,6 +135,18 @@ curl -X PUT https://<host>/admin/config \
-d '{"fee_address": "plm1q...", "bet_amount_sats": 1000000000, "round_duration_seconds": 600}'
```
I valori vengono validati: `fee_address` deve essere un indirizzo bech32 PLM
valido (`plm1...`) e i parametri numerici hanno limiti di buon senso
(`fee_rate_sat_vb` almeno 1, durata round almeno 30s, ecc.). Un valore fuori
range viene rifiutato con un errore 422 e la configurazione resta invariata.
Il controllo su `fee_address` è deliberatamente severo: un indirizzo di
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
+23 -1
View File
@@ -11,6 +11,13 @@ poterla avviare (in locale o via Docker). Per come avviarla poi ogni volta, vedi
- Un server Electrum raggiungibile per la rete PLM. Il server di bootstrap per lo
sviluppo è `santantonio.sytes.net:50002` (SSL) — va bene per i test, ma in
produzione conviene usarne uno di cui ci si fida o gestirne uno proprio.
- **Consigliato in produzione: più di un server.** Tutto passa da questa singola
connessione (accredito depositi, invio transazioni, conferme, altezza della
catena su cui si basa l'estrazione), quindi un solo server è il principale
punto di rottura della piattaforma. Elencane altri in
`ELECTRUM_FALLBACK_SERVERS` (vedi sotto): l'app li prova a rotazione, così un
server irraggiungibile costa un solo tentativo di riconnessione invece di un
disservizio.
## 2. Creare il file `.env`
@@ -29,7 +36,22 @@ cp .env.example .env
| `ADMIN_TOKEN` | Token bearer richiesto sugli endpoint admin (header `X-Admin-Token`). | `python -c "import secrets; print(secrets.token_urlsafe(32))"` |
Le altre chiavi di `.env` (`DATABASE_URL`, `ELECTRUM_HOST`/`PORT`/`USE_SSL`,
`MASTER_KEY_PATH`) hanno default sensati in `.env.example`. Nota: `.env`
`MASTER_KEY_PATH`) hanno default sensati in `.env.example`.
`ELECTRUM_FALLBACK_SERVERS` elenca i server di riserva, separati da virgola, nel
formato `host:porta` (TLS, il caso normale) oppure `host:porta:notls`. Esempio:
```
ELECTRUM_FALLBACK_SERVERS=nodo2.example.net:50002,nodo3.example.net:50001:notls
```
Vengono provati a rotazione dopo il primario. Attenzione: un valore scritto male
**blocca l'avvio** dell'app — è voluto, meglio accorgersene subito che durante il
disservizio in cui il fallback serve davvero.
`JWT_SECRET` e `XPRV_ENCRYPTION_KEY` vengono verificati all'avvio: se sono vuoti
(o `JWT_SECRET` è più corto di 32 caratteri) il container si rifiuta di partire con
un errore esplicito, invece di avviarsi e rompersi al primo login. Nota: `.env`
contiene solo segreti e configurazione di infrastruttura — i parametri di
business (bet amount, durata round, fee, ecc.) si configurano dal pannello
admin dopo l'avvio, non qui — vedi [guida-admin.md](guida-admin.md).
@@ -0,0 +1,57 @@
"""Add pending tx failure_reason and the single-active-round index
Supports two fixes from BUGS.md:
* B-04 — the reconciler (app/tx/reconcile.py) records *why* it abandoned a
transaction, so an operator can tell a dropped tx from a rejected one.
* B-09 — "at most one active round" becomes a database guarantee instead of a
read-then-insert that two concurrent callers could both pass. A unique index
over the constant expression (1), restricted to the active statuses: any number
of closed rounds, only ever one live one.
The index creation is not blind: if an instance already has more than one active
round (the very bug this prevents), creating it would fail with an opaque
IntegrityError mid-migration. It closes the stale duplicates first, keeping the
newest — which is exactly what get_active_round was already doing silently.
Revision ID: 8a1c4e7b2d90
Revises: 6cb50b29f64c
Create Date: 2026-07-26
"""
from typing import Sequence, Union
import sqlalchemy as sa
from alembic import op
revision: str = "8a1c4e7b2d90"
down_revision: Union[str, Sequence[str], None] = "6cb50b29f64c"
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None
_ACTIVE = "'open', 'closing', 'drawing', 'paying_out'"
def upgrade() -> None:
op.add_column(
"pending_transactions", sa.Column("failure_reason", sa.String(length=128), nullable=True)
)
connection = op.get_bind()
active_ids = [
row[0]
for row in connection.execute(
sa.text(f"SELECT id FROM rounds WHERE status IN ({_ACTIVE}) ORDER BY id DESC")
)
]
for stale_id in active_ids[1:]:
connection.execute(
sa.text("UPDATE rounds SET status = 'closed' WHERE id = :id"), {"id": stale_id}
)
op.execute(f"CREATE UNIQUE INDEX ix_rounds_single_active ON rounds ((1)) WHERE status IN ({_ACTIVE})")
def downgrade() -> None:
op.execute("DROP INDEX IF EXISTS ix_rounds_single_active")
op.drop_column("pending_transactions", "failure_reason")
+65 -3
View File
@@ -4,6 +4,11 @@ from httpx import ASGITransport, AsyncClient
from app.config import settings
# A real PLM bech32 address: PUT /admin/config now validates fee_address, since a
# foreign-chain address there would send every round's commission to a script
# nobody can spend (B-05).
_VALID_FEE_ADDRESS = "plm1q0xcqpzrky6eff2g52qdye53xkk9jxkvraxkkwd"
@pytest.fixture
async def client(monkeypatch, tmp_path):
@@ -70,15 +75,15 @@ async def test_admin_reads_and_updates_config(client):
assert resp.json()["fee_address"] == ""
resp = await client.put(
"/admin/config", headers=headers, json={"fee_address": "plm1qfeeaddress", "bet_amount_sats": 500_000_000}
"/admin/config", headers=headers, json={"fee_address": _VALID_FEE_ADDRESS, "bet_amount_sats": 500_000_000}
)
assert resp.status_code == 200
body = resp.json()
assert body["fee_address"] == "plm1qfeeaddress"
assert body["fee_address"] == _VALID_FEE_ADDRESS
assert body["bet_amount_sats"] == 500_000_000
resp = await client.get("/admin/config", headers=headers)
assert resp.json()["fee_address"] == "plm1qfeeaddress"
assert resp.json()["fee_address"] == _VALID_FEE_ADDRESS
async def test_admin_can_pause_and_resume_the_lottery(client):
@@ -211,3 +216,60 @@ async def test_admin_reset_password_404_for_unknown_user(client):
headers = {"X-Admin-Token": "test-admin-token"}
resp = await client.post("/admin/users/999/reset-password", headers=headers)
assert resp.status_code == 404
async def test_config_update_is_audit_logged(client):
"""B-10: /pause and /resume were logged but a config change wasn't, so the most
sensitive setting in the system — fee_address, where 30% of every pool goes —
could be changed without leaving any trace."""
headers = {"X-Admin-Token": "test-admin-token"}
await client.put("/admin/config", headers=headers, json={"fee_address": _VALID_FEE_ADDRESS})
resp = await client.get("/admin/audit-log", headers=headers)
entries = [e for e in resp.json() if e["event_type"] == "config_updated"]
assert len(entries) == 1
assert entries[0]["payload"]["fee_address"] == {"from": "", "to": _VALID_FEE_ADDRESS}
async def test_config_update_without_changes_logs_nothing(client):
headers = {"X-Admin-Token": "test-admin-token"}
await client.put("/admin/config", headers=headers, json={"fee_address": _VALID_FEE_ADDRESS})
await client.put("/admin/config", headers=headers, json={"fee_address": _VALID_FEE_ADDRESS})
resp = await client.get("/admin/audit-log", headers=headers)
assert len([e for e in resp.json() if e["event_type"] == "config_updated"]) == 1
@pytest.mark.parametrize(
"payload",
[
{"fee_address": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4"}, # valid bech32, wrong chain
{"fee_address": "plm1qbogus"}, # right HRP, broken checksum
{"fee_address": "garbage"},
{"fee_rate_sat_vb": 0}, # fee-less txs are never relayed: everything would stall
{"round_duration_seconds": 0}, # a round that expires the instant it opens
{"bet_amount_sats": -1},
{"rbf_timeout_seconds": 1},
],
)
async def test_config_rejects_unusable_values(client, payload):
"""B-05: every one of these was accepted before. The bc1 case is the worst — it
parses as a valid witness program, so each round's commission would be broadcast
to a script nobody holds the key for."""
headers = {"X-Admin-Token": "test-admin-token"}
resp = await client.put("/admin/config", headers=headers, json=payload)
assert resp.status_code == 422
# and nothing was written
current = (await client.get("/admin/config", headers=headers)).json()
for field, value in payload.items():
assert current[field] != value
async def test_pause_cannot_be_toggled_through_the_config_endpoint(client):
"""B-10: `paused` used to be settable here, bypassing the audit-logged
pause/resume endpoints."""
headers = {"X-Admin-Token": "test-admin-token"}
resp = await client.put("/admin/config", headers=headers, json={"paused": True})
assert resp.status_code in (200, 422) # ignored or refused, but never applied
assert (await client.get("/admin/config", headers=headers)).json()["paused"] is False
+69
View File
@@ -133,3 +133,72 @@ async def test_place_bet_rejects_after_timer_expires_even_if_still_open(session_
assert len(participants) == 0
round_ = (await session.scalars(select(Round))).one()
assert round_.status == "open" # scheduler hasn't ticked — status is unchanged, only the check is deadline-aware
class RejectingElectrumClient:
"""A node that refuses the transaction — fee too low, dust output, mempool
conflict, or simply an unreachable server."""
async def broadcast(self, raw_tx_hex: str) -> str:
raise RuntimeError("min relay fee not met")
async def test_failed_broadcast_leaves_nothing_behind(session_factory):
"""B-07/B-08: the broadcast used to happen before anything was written, so a
rejection left the UTXOs marked spent with no rows to explain it, and the caller
got an opaque HTTP 500. Now it's a translatable error and a full rollback."""
user_id = await _make_funded_user(session_factory, 4, 3_000_000_000)
async with session_factory() as session:
user = await session.get(User, user_id)
with pytest.raises(BetError, match="refused"):
await place_bet(session, RejectingElectrumClient(), user)
async with session_factory() as session:
utxo = (await session.scalars(select(UtxoEvent).where(UtxoEvent.user_id == user_id))).one()
assert utxo.spent_txid is None # released, so the user can bet again
assert (await session.scalars(select(RoundParticipant))).all() == []
assert (await session.scalars(select(PendingTransaction))).all() == []
user = await session.get(User, user_id)
assert user.cached_balance_sats == 3_000_000_000
events = [e.event_type for e in (await session.scalars(select(AuditLog))).all()]
assert "bet_broadcast_failed" in events
assert "bet_placed" not in events
async def test_failed_broadcast_reports_the_broadcast_failed_code(session_factory):
user_id = await _make_funded_user(session_factory, 5, 3_000_000_000)
async with session_factory() as session:
user = await session.get(User, user_id)
try:
await place_bet(session, RejectingElectrumClient(), user)
assert False, "expected BetError"
except BetError as exc:
assert exc.code == "broadcast_failed"
async def test_bet_is_persisted_before_it_is_broadcast(session_factory):
"""The ordering guarantee behind B-08: by the time the network call happens, the
rows already exist, so a crash there is recoverable rather than silent."""
user_id = await _make_funded_user(session_factory, 6, 3_000_000_000)
seen: dict[str, object] = {}
class ObservingClient:
async def broadcast(self, raw_tx_hex: str) -> str:
# Read committed state from an independent session, mid-broadcast.
async with session_factory() as probe:
seen["pending"] = [
(p.kind, p.status) for p in (await probe.scalars(select(PendingTransaction))).all()
]
seen["participants"] = [
(p.status) for p in (await probe.scalars(select(RoundParticipant))).all()
]
return "network-txid"
async with session_factory() as session:
user = await session.get(User, user_id)
await place_bet(session, ObservingClient(), user)
assert seen["pending"] == [("bet", "building")]
assert seen["participants"] == ["building"]
+69
View File
@@ -179,3 +179,72 @@ async def test_bump_fee_raises_when_no_change_output(session_factory):
row = await session.get(PendingTransaction, pending_id)
with pytest.raises(RbfError):
await bump_fee(session, client, row)
async def test_bump_fee_retargets_every_stored_txid(session_factory):
"""B-02/B-20: a bump changes the txid, and everything that recorded the old one
has to follow — the participant's bet_txid (whose staleness used to wedge the
round forever), the UTXO's spent_txid (which the reconciler matches on), and
replaced_by_txid, which was never written at all."""
from app.db.models import Round, RoundParticipant, UtxoEvent
from app.wallet.hd import derive_user_address, derive_user_key
signer = derive_user_key(0)
my_address = derive_user_address(0)
from_script = script.p2wpkh(signer.to_public())
to_address = script.p2wpkh(_key(98).to_public()).address(network=PLM_MAINNET)
utxo_amount = 150_000_000
utxo_txid = "22" * 32
built = build_signed_transaction(
signing_key=signer,
from_script=from_script,
utxos=[Utxo(utxo_txid, 0, utxo_amount)],
to_address=to_address,
amount_sats=10_000_000,
change_address=my_address,
fee_rate_sat_vb=1,
)
async with session_factory() as session:
user = User(username="bob", password_hash="x", derivation_index=0, address=my_address)
session.add(user)
session.add(Round(id=1, status="open"))
await session.flush()
session.add(
UtxoEvent(
user_id=user.id, txid=utxo_txid, vout=0, amount_sats=utxo_amount,
confirmed_height=5, spent_txid=built.txid,
)
)
session.add(
RoundParticipant(
round_id=1, user_id=user.id, bet_amount_sats=built.recipient_sats,
bet_txid=built.txid, status="broadcast",
)
)
pending = PendingTransaction(
kind="bet", round_id=1, user_id=user.id, current_txid=built.txid, fee_rate_sat_vb=1,
raw_tx_hex=built.raw_hex, status="pending",
broadcast_at=datetime.now(timezone.utc) - timedelta(seconds=1000),
)
session.add(pending)
await session.commit()
pending_id = pending.id
async with session_factory() as session:
row = await session.get(PendingTransaction, pending_id)
new_txid = await bump_fee(session, FakeClient({utxo_txid: utxo_amount}), row)
async with session_factory() as session:
from sqlalchemy import select
row = await session.get(PendingTransaction, pending_id)
assert row.current_txid == new_txid
assert row.replaced_by_txid == built.txid # points backwards at what it replaced
participant = (await session.scalars(select(RoundParticipant))).one()
assert participant.bet_txid == new_txid
utxo = (await session.scalars(select(UtxoEvent))).one()
assert utxo.spent_txid == new_txid
+51
View File
@@ -0,0 +1,51 @@
"""B-15: secrets that would only break at first use must stop the app at startup."""
import pytest
from app.config import MIN_JWT_SECRET_LENGTH, ConfigError, Settings, validate_runtime_secrets
def _settings(**overrides) -> Settings:
base = {
"jwt_secret": "x" * MIN_JWT_SECRET_LENGTH,
"xprv_encryption_key": "a-fernet-key",
}
base.update(overrides)
# _env_file=None so a developer's real .env can't make this test pass or fail.
return Settings(_env_file=None, **base)
def test_valid_secrets_pass():
validate_runtime_secrets(_settings())
def test_empty_jwt_secret_is_refused():
"""An empty JWT_SECRET makes PyJWT raise InvalidKeyError on every single login —
a 500 with no hint about the real cause, on a container that started up healthy."""
with pytest.raises(ConfigError, match="JWT_SECRET"):
validate_runtime_secrets(_settings(jwt_secret=""))
def test_short_jwt_secret_is_refused():
with pytest.raises(ConfigError, match="JWT_SECRET"):
validate_runtime_secrets(_settings(jwt_secret="x" * (MIN_JWT_SECRET_LENGTH - 1)))
def test_empty_xprv_encryption_key_is_refused():
"""Without it Fernet fails on the first key derivation — i.e. the first time
anyone registers or a transaction needs signing."""
with pytest.raises(ConfigError, match="XPRV_ENCRYPTION_KEY"):
validate_runtime_secrets(_settings(xprv_encryption_key=" "))
def test_all_problems_are_reported_at_once():
with pytest.raises(ConfigError) as exc_info:
validate_runtime_secrets(_settings(jwt_secret="", xprv_encryption_key=""))
message = str(exc_info.value)
assert "JWT_SECRET" in message and "XPRV_ENCRYPTION_KEY" in message
def test_an_empty_admin_token_is_not_fatal():
"""require_admin already denies every request when it's unset, so the effect is a
locked admin panel rather than an open one — no reason to refuse to boot."""
validate_runtime_secrets(_settings(admin_token=""))
+91
View File
@@ -80,3 +80,94 @@ async def test_payout_confirmation_closes_round(session_factory):
async with session_factory() as session:
round_ = await session.get(Round, 3)
assert round_.status == "closed"
class ExplodingClient:
"""Answers for one txid and raises for the other — a tx the server no longer
knows (dropped from the mempool, replaced by a bump)."""
def __init__(self, known: dict[str, int], exploding_txid: str):
self._known = known
self._exploding = exploding_txid
async def get_transaction(self, txid: str, verbose: bool = False) -> dict:
if txid == self._exploding:
raise RuntimeError("missing transaction")
return {"confirmations": self._known.get(txid, 0)}
async def test_one_unresolvable_txid_does_not_block_the_others(session_factory):
"""B-03: the lookup used to be unguarded, so a single unknown txid aborted the
whole pass — nothing confirmed again until an operator intervened, which in turn
meant no round could ever close."""
async with session_factory() as session:
session.add(Round(id=10, status="open"))
session.add(
RoundParticipant(round_id=10, user_id=1, bet_amount_sats=1_000, bet_txid="good", status="broadcast")
)
session.add(
PendingTransaction(
kind="bet", round_id=10, user_id=2, current_txid="gone", fee_rate_sat_vb=1, raw_tx_hex="00",
status="pending",
)
)
session.add(
PendingTransaction(
kind="bet", round_id=10, user_id=1, current_txid="good", fee_rate_sat_vb=1, raw_tx_hex="00",
status="pending",
)
)
await session.commit()
confirmed = await poll_once(session_factory, ExplodingClient({"good": 1}, exploding_txid="gone"))
assert confirmed == 1 # the healthy one still got processed
async with session_factory() as session:
participant = (await session.scalars(select(RoundParticipant).where(RoundParticipant.round_id == 10))).one()
assert participant.status == "confirmed"
rows = {p.current_txid: p.status for p in (await session.scalars(select(PendingTransaction))).all()}
assert rows["good"] == "confirmed"
assert rows["gone"] == "pending" # left for the reconciler to judge, not abandoned here
async def test_bet_confirms_after_an_rbf_bump_changed_the_txid(session_factory):
"""B-02: the handler used to match on bet_txid, so a bumped bet confirmed under
a txid no participant carried — the participant stayed "broadcast" forever and
the round could never close. It now resolves by (round_id, user_id)."""
async with session_factory() as session:
session.add(Round(id=11, status="open"))
session.add(
RoundParticipant(
round_id=11, user_id=7, bet_amount_sats=1_000, bet_txid="old-txid", status="broadcast"
)
)
session.add(
PendingTransaction(
kind="bet", round_id=11, user_id=7, current_txid="bumped-txid", fee_rate_sat_vb=2,
raw_tx_hex="00", status="pending", replaced_by_txid="old-txid",
)
)
await session.commit()
assert await poll_once(session_factory, FakeClient({"bumped-txid": 1})) == 1
async with session_factory() as session:
participant = (await session.scalars(select(RoundParticipant).where(RoundParticipant.round_id == 11))).one()
assert participant.status == "confirmed"
async def test_payout_confirms_after_an_rbf_bump_changed_the_txid(session_factory):
async with session_factory() as session:
session.add(Round(id=12, status="paying_out", payout_txid="old-payout"))
session.add(
PendingTransaction(
kind="payout", round_id=12, current_txid="bumped-payout", fee_rate_sat_vb=2,
raw_tx_hex="00", status="pending",
)
)
await session.commit()
assert await poll_once(session_factory, FakeClient({"bumped-payout": 1})) == 1
async with session_factory() as session:
assert (await session.get(Round, 12)).status == "closed"
+80
View File
@@ -75,3 +75,83 @@ async def test_notification_delivered_to_subscription_queue():
assert params == ["abcd", "newstatus"]
client._read_task.cancel()
async def test_request_times_out_instead_of_hanging_forever(monkeypatch):
"""B-01: a server that owes us a reply and never sends one used to hang the
caller permanently — which meant a POST /bets could hang while holding the
per-user lock, and the confirmation poller could stop polling for good."""
from app.electrum import client as client_module
monkeypatch.setattr(client_module, "_REQUEST_TIMEOUT_SECONDS", 0.05)
client, reader, writer = await _client_with_fake_transport()
try:
await client.request("blockchain.transaction.get", ["deadbeef"])
assert False, "expected ElectrumError"
except ElectrumError as exc:
assert "timed out" in str(exc)
# The connection is torn down, so callers stop reusing a server that owes us.
assert client._closed.is_set()
client._read_task.cancel()
async def test_wait_closed_resolves_when_the_read_loop_dies():
"""B-01: the read loop dying used to be invisible — the listener sat on its
notification queues forever and never reconnected."""
client, reader, writer = await _client_with_fake_transport()
waiter = asyncio.create_task(client.wait_closed())
reader.feed_eof() # peer closed the connection
await asyncio.wait_for(waiter, timeout=1)
client._read_task.cancel()
async def test_pending_request_fails_when_the_connection_drops():
client, reader, writer = await _client_with_fake_transport()
task = asyncio.create_task(client.request("server.ping"))
await asyncio.sleep(0)
reader.feed_eof()
try:
await asyncio.wait_for(task, timeout=1)
assert False, "expected ElectrumError"
except ElectrumError:
pass
def test_parse_endpoints_puts_the_primary_first_and_dedupes():
from app.electrum.client import ElectrumEndpoint, parse_endpoints
endpoints = parse_endpoints(
"primary.example", 50002, True, "second.example:50002, third.example:50001:notls, primary.example:50002"
)
assert endpoints == [
ElectrumEndpoint("primary.example", 50002, True),
ElectrumEndpoint("second.example", 50002, True),
ElectrumEndpoint("third.example", 50001, False),
]
def test_parse_endpoints_handles_an_empty_fallback_list():
from app.electrum.client import ElectrumEndpoint, parse_endpoints
assert parse_endpoints("only.example", 50002, True, "") == [ElectrumEndpoint("only.example", 50002, True)]
assert parse_endpoints("only.example", 50002, True, " , ") == [
ElectrumEndpoint("only.example", 50002, True)
]
def test_parse_endpoints_rejects_a_malformed_entry():
"""A typo in a fallback server must fail at startup, not during the outage when
the fallback is the thing that's needed."""
import pytest
from app.electrum.client import parse_endpoints
for bad in ["nohost:", "host:notaport", "host", "host:50002:weird"]:
with pytest.raises(ValueError):
parse_endpoints("primary.example", 50002, True, bad)
+142
View File
@@ -0,0 +1,142 @@
"""Listener-level behaviour: server rotation on failure (the fallback-servers
feature), and the chain-tip monotonicity guard (B-19).
The reconnect loop itself (B-01) is covered from the client side in
test_electrum_client.py — what's asserted here is that the listener *acts* on a
dead connection by moving to the next server instead of retrying the same one.
"""
import asyncio
import pytest
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from app.db.base import Base
from app.electrum.client import ElectrumEndpoint
from app.electrum.listener import ElectrumListener
@pytest.fixture
async def session_factory():
engine = create_async_engine("sqlite+aiosqlite:///:memory:")
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
yield async_sessionmaker(engine, expire_on_commit=False)
await engine.dispose()
_ENDPOINTS = [
ElectrumEndpoint("first.example", 50002, True),
ElectrumEndpoint("second.example", 50002, True),
ElectrumEndpoint("third.example", 50001, False),
]
async def test_rotates_to_the_next_server_after_a_failed_session(session_factory):
"""One unreachable server should cost a single attempt, not an outage: every
deposit credit, broadcast and confirmation goes through this one connection."""
attempted: list[str] = []
listener = ElectrumListener(lambda endpoint: None, session_factory, _ENDPOINTS)
async def failing_run_once(endpoint):
attempted.append(endpoint.host)
if len(attempted) >= 5:
raise asyncio.CancelledError # stop the loop
raise ConnectionRefusedError("nope")
listener._run_once = failing_run_once
with pytest.raises(asyncio.CancelledError):
await listener.run()
# Round-robin over all three, wrapping around — never the same one twice in a row.
assert attempted == [
"first.example",
"second.example",
"third.example",
"first.example",
"second.example",
]
async def test_backoff_only_sleeps_after_every_server_has_been_tried(session_factory, monkeypatch):
"""A genuinely offline network must back off, but not before the alternatives have
had their turn."""
sleeps: list[float] = []
async def fake_sleep(seconds):
sleeps.append(seconds)
monkeypatch.setattr(asyncio, "sleep", fake_sleep)
listener = ElectrumListener(lambda endpoint: None, session_factory, _ENDPOINTS)
attempts = {"n": 0}
async def failing_run_once(endpoint):
attempts["n"] += 1
if attempts["n"] > 6:
raise asyncio.CancelledError
raise ConnectionRefusedError("nope")
listener._run_once = failing_run_once
with pytest.raises(asyncio.CancelledError):
await listener.run()
# 6 failures over 3 servers = 2 completed cycles = 2 sleeps, growing.
assert sleeps == [1, 2]
async def test_a_connected_session_resets_the_backoff(session_factory, monkeypatch):
sleeps: list[float] = []
async def fake_sleep(seconds):
sleeps.append(seconds)
monkeypatch.setattr(asyncio, "sleep", fake_sleep)
listener = ElectrumListener(lambda endpoint: None, session_factory, _ENDPOINTS)
outcomes = iter([False, False, False, True, False, False, False])
async def run_once(endpoint):
try:
connected = next(outcomes)
except StopIteration:
raise asyncio.CancelledError from None
if not connected:
raise ConnectionRefusedError("nope")
return True # connected, then dropped
listener._run_once = run_once
with pytest.raises(asyncio.CancelledError):
await listener.run()
# First cycle of 3 failures sleeps 1s; the successful connection resets the
# counter, so the next 3 failures sleep 1s again rather than 2s.
assert sleeps == [1, 1]
async def test_listener_with_no_endpoints_gives_up_loudly(session_factory):
listener = ElectrumListener(lambda endpoint: None, session_factory, [])
await listener.run() # returns instead of spinning or crashing
assert listener.current_endpoint is None
def test_tip_never_moves_backwards(session_factory):
"""B-19: `self.tip_height = header["height"]` accepted a lower height, and
_wait_for_next_block waits for tip_height > tip_at_close — so a regression
silently added a block to the draw's wait. The hash must not move either: it's
the draw's entropy source, and a mismatched height/hash pair would be worse than
a stale one."""
listener = ElectrumListener(lambda endpoint: None, session_factory, _ENDPOINTS)
listener._apply_header({"height": 100, "hex": "aa"})
assert (listener.tip_height, listener.tip_header_hex) == (100, "aa")
listener._apply_header({"height": 99, "hex": "bb"}) # reorg, or a server switch
assert (listener.tip_height, listener.tip_header_hex) == (100, "aa")
listener._apply_header({"height": 101, "hex": "cc"})
assert (listener.tip_height, listener.tip_header_hex) == (101, "cc")
+73
View File
@@ -1,6 +1,7 @@
import pytest
from embit import script
from embit.bip32 import HDKey
from embit.transaction import Transaction
from app.wallet.plm_network import PLM_MAINNET
from app.wallet.psbt_builder import (
@@ -111,3 +112,75 @@ def test_build_signed_transaction_raises_when_amount_smaller_than_fee():
change_address=my_address,
fee_rate_sat_vb=1,
)
def test_dust_change_is_left_to_the_fee():
"""B-06: `if change > 0` created change outputs below the dust limit, which makes
the whole transaction unrelayable — the bet or withdrawal then failed at broadcast
with an opaque error the user could do nothing about."""
from app.wallet.psbt_builder import DUST_LIMIT_SATS
signer = _key(1)
from_script = script.p2wpkh(signer.to_public())
to_address = script.p2wpkh(_key(2).to_public()).address(network=PLM_MAINNET)
change_address = script.p2wpkh(signer.to_public()).address(network=PLM_MAINNET)
amount = 10_000_000
dust_change = DUST_LIMIT_SATS - 1
built = build_signed_transaction(
signing_key=signer,
from_script=from_script,
utxos=[Utxo("33" * 32, 0, amount + dust_change)],
to_address=to_address,
amount_sats=amount,
change_address=change_address,
fee_rate_sat_vb=1,
)
tx = Transaction.parse(bytes.fromhex(built.raw_hex))
assert len(tx.vout) == 1 # no dust output
assert built.change_sats == 0
# Nothing vanishes: the dust ends up in the fee, and inputs still equal outputs+fee.
assert built.fee_sats >= dust_change
assert built.recipient_sats + built.change_sats + built.fee_sats == amount + dust_change
def test_change_at_the_dust_limit_is_still_paid_back():
from app.wallet.psbt_builder import DUST_LIMIT_SATS
signer = _key(1)
from_script = script.p2wpkh(signer.to_public())
to_address = script.p2wpkh(_key(2).to_public()).address(network=PLM_MAINNET)
change_address = script.p2wpkh(signer.to_public()).address(network=PLM_MAINNET)
amount = 10_000_000
built = build_signed_transaction(
signing_key=signer,
from_script=from_script,
utxos=[Utxo("44" * 32, 0, amount + DUST_LIMIT_SATS)],
to_address=to_address,
amount_sats=amount,
change_address=change_address,
fee_rate_sat_vb=1,
)
assert built.change_sats == DUST_LIMIT_SATS
assert len(Transaction.parse(bytes.fromhex(built.raw_hex)).vout) == 2
def test_dust_sized_recipient_amount_is_refused():
signer = _key(1)
from_script = script.p2wpkh(signer.to_public())
to_address = script.p2wpkh(_key(2).to_public()).address(network=PLM_MAINNET)
change_address = script.p2wpkh(signer.to_public()).address(network=PLM_MAINNET)
with pytest.raises(InsufficientFundsError):
build_signed_transaction(
signing_key=signer,
from_script=from_script,
utxos=[Utxo("55" * 32, 0, 1_000_000)],
to_address=to_address,
amount_sats=400, # after the ~160 sat fee this lands under the dust limit
change_address=change_address,
fee_rate_sat_vb=1,
)
+233
View File
@@ -0,0 +1,233 @@
"""Regression tests for B-04 (and the "building" half of B-08): a transaction that
never made it onto the chain must give the coins back instead of freezing them."""
import pytest
from embit import script
from embit.transaction import Transaction, TransactionInput, TransactionOutput
from sqlalchemy import select
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from app.db.base import Base
from app.db.models import AuditLog, PendingTransaction, RoundParticipant, User, UtxoEvent, Withdrawal
from app.tx.reconcile import reconcile_once
class UnknownTxClient:
"""A server that doesn't know any of the txids it's asked about."""
async def get_transaction(self, txid: str, verbose: bool = False):
raise RuntimeError(f"missing transaction {txid}")
class KnownTxClient:
async def get_transaction(self, txid: str, verbose: bool = False):
return {"txid": txid, "confirmations": 0}
class BrokenClient:
"""A transport failure — says nothing about whether the tx exists."""
async def get_transaction(self, txid: str, verbose: bool = False):
raise ConnectionResetError("connection reset")
@pytest.fixture
async def session_factory():
engine = create_async_engine("sqlite+aiosqlite:///:memory:")
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
yield async_sessionmaker(engine, expire_on_commit=False)
await engine.dispose()
# A real (unsigned) transaction spending one input, built rather than hand-written
# so it round-trips through Transaction.parse — that parse is how the reconciler
# discovers which UTXOs to release, so a fixture the parser rejects would test
# nothing.
_TX_INPUT_TXID = "11" * 32
_RAW_TX = (
Transaction(
vin=[TransactionInput(bytes.fromhex(_TX_INPUT_TXID), 0)],
vout=[
TransactionOutput(
999_000_000, script.Script.from_address("plm1q0xcqpzrky6eff2g52qdye53xkk9jxkvraxkkwd")
)
],
)
.serialize()
.hex()
)
async def _seed_bet(session_factory, *, pending_status: str, participant_status: str, age_seconds: int):
from datetime import datetime, timedelta, timezone
async with session_factory() as session:
user = User(username="u", password_hash="x", derivation_index=0, address="plm1qtest")
session.add(user)
await session.flush()
session.add(
UtxoEvent(
user_id=user.id,
txid=_TX_INPUT_TXID,
vout=0,
amount_sats=1_000_000_000,
confirmed_height=10,
spent_txid="betxid",
)
)
session.add(
RoundParticipant(
round_id=1,
user_id=user.id,
bet_amount_sats=999_000_000,
bet_txid="betxid",
status=participant_status,
)
)
session.add(
PendingTransaction(
kind="bet",
round_id=1,
user_id=user.id,
current_txid="betxid",
fee_rate_sat_vb=1,
raw_tx_hex=_RAW_TX,
status=pending_status,
broadcast_at=datetime.now(timezone.utc) - timedelta(seconds=age_seconds),
)
)
await session.commit()
return user.id
async def test_abandons_a_building_bet_and_gives_the_coins_back(session_factory):
"""The crash-mid-broadcast case: the tx isn't on the chain, so the UTXO must be
released, the participant removed (they never entered the round) and the balance
restored. Before this existed, spent_txid stayed set forever and the user simply
lost the coins."""
user_id = await _seed_bet(
session_factory, pending_status="building", participant_status="building", age_seconds=300
)
resolved = await reconcile_once(session_factory, UnknownTxClient())
assert resolved == 1
async with session_factory() as session:
utxo = (await session.scalars(select(UtxoEvent))).one()
assert utxo.spent_txid is None # spendable again
assert (await session.scalars(select(RoundParticipant))).all() == []
row = (await session.scalars(select(PendingTransaction))).one()
assert row.status == "failed"
assert row.failure_reason
user = await session.get(User, user_id)
assert user.cached_balance_sats == 1_000_000_000
events = [e.event_type for e in (await session.scalars(select(AuditLog))).all()]
assert "pending_tx_abandoned" in events
async def test_promotes_a_building_row_whose_tx_did_reach_the_chain(session_factory):
"""We died after the broadcast, not before: the tx is real, so the rows must be
finished rather than rolled back."""
await _seed_bet(
session_factory, pending_status="building", participant_status="building", age_seconds=300
)
resolved = await reconcile_once(session_factory, KnownTxClient())
assert resolved == 1
async with session_factory() as session:
row = (await session.scalars(select(PendingTransaction))).one()
assert row.status == "pending"
participant = (await session.scalars(select(RoundParticipant))).one()
assert participant.status == "broadcast"
utxo = (await session.scalars(select(UtxoEvent))).one()
assert utxo.spent_txid == "betxid" # still legitimately spent
async def test_leaves_a_young_building_row_alone(session_factory):
"""A row written seconds ago may just be a broadcast still in flight."""
await _seed_bet(
session_factory, pending_status="building", participant_status="building", age_seconds=5
)
assert await reconcile_once(session_factory, UnknownTxClient()) == 0
async with session_factory() as session:
assert (await session.scalars(select(PendingTransaction))).one().status == "building"
async def test_leaves_a_recently_broadcast_pending_row_alone(session_factory):
"""A broadcast tx gets a wide grace window — absence from one server's mempool
is not proof of death, and the RBF bumper should get its attempts first."""
await _seed_bet(
session_factory, pending_status="pending", participant_status="broadcast", age_seconds=3600
)
assert await reconcile_once(session_factory, UnknownTxClient()) == 0
async def test_transport_failure_never_abandons_anything(session_factory):
"""A dead connection says nothing about the transaction. Treating it as "gone"
would release coins for transactions that are perfectly alive."""
await _seed_bet(
session_factory, pending_status="building", participant_status="building", age_seconds=300
)
assert await reconcile_once(session_factory, BrokenClient()) == 0
async with session_factory() as session:
assert (await session.scalars(select(PendingTransaction))).one().status == "building"
assert (await session.scalars(select(UtxoEvent))).one().spent_txid == "betxid"
async def test_abandoned_withdrawal_is_marked_failed_and_kept(session_factory):
"""Unlike a bet, a withdrawal is an instruction the user gave: the row stays so
they can see it didn't go through."""
from datetime import datetime, timedelta, timezone
async with session_factory() as session:
user = User(username="w", password_hash="x", derivation_index=1, address="plm1qtest2")
session.add(user)
await session.flush()
session.add(
UtxoEvent(
user_id=user.id,
txid=_TX_INPUT_TXID,
vout=0,
amount_sats=500_000_000,
confirmed_height=10,
spent_txid="wdtxid",
)
)
withdrawal = Withdrawal(
user_id=user.id,
external_address="plm1qexternal",
amount_requested_sats=400_000_000,
amount_sent_sats=399_000_000,
txid="wdtxid",
status="broadcast",
)
session.add(withdrawal)
await session.flush()
session.add(
PendingTransaction(
kind="withdrawal",
withdrawal_id=withdrawal.id,
user_id=user.id,
current_txid="wdtxid",
fee_rate_sat_vb=1,
raw_tx_hex=_RAW_TX,
status="pending",
broadcast_at=datetime.now(timezone.utc) - timedelta(days=1),
)
)
await session.commit()
assert await reconcile_once(session_factory, UnknownTxClient()) == 1
async with session_factory() as session:
withdrawal = (await session.scalars(select(Withdrawal))).one()
assert withdrawal.status == "failed"
assert withdrawal.txid is None
assert (await session.scalars(select(UtxoEvent))).one().spent_txid is None
+68 -1
View File
@@ -42,7 +42,7 @@ async def client(monkeypatch, tmp_path):
app = FastAPI()
app.include_router(auth_router)
app.include_router(rounds_router)
app.state.electrum_listener = ElectrumListener(lambda: None, db_base.AsyncSessionLocal)
app.state.electrum_listener = ElectrumListener(lambda endpoint: None, db_base.AsyncSessionLocal)
transport = ASGITransport(app=app)
async with AsyncClient(transport=transport, base_url="http://test") as ac:
@@ -94,3 +94,70 @@ async def test_user_played_true_only_for_participants(client):
resp = await ac.get("/rounds/current") # no auth at all — logged-out chain-only view
assert resp.status_code == 200
assert resp.json()["user_played"] is False
async def test_jackpot_comes_from_the_participants_actual_bets(client):
"""B-11: the jackpot was participant_count * the *current* bet_amount_sats, which
overstated it (each stored bet is already net of that bet's network fee) and
silently rewrote the advertised jackpot of a round in progress whenever an
operator edited the bet amount."""
from sqlalchemy import select
from app.db.models import Round, RoundConfig, RoundParticipant
ac, session_factory = client
async with session_factory() as session:
session.add(RoundConfig(fee_address="", bet_amount_sats=1_000_000_000))
session.add(Round(id=50, status="open"))
await session.flush()
# Two bets that actually paid 999_800_000 each (fee deducted), not 1_000_000_000.
session.add(
RoundParticipant(round_id=50, user_id=1, bet_amount_sats=999_800_000, bet_txid="a", status="confirmed")
)
session.add(
RoundParticipant(round_id=50, user_id=2, bet_amount_sats=999_800_000, bet_txid="b", status="confirmed")
)
await session.commit()
body = (await ac.get("/rounds/current")).json()
assert body["participant_count"] == 2
assert body["jackpot_sats"] == (999_800_000 * 2) * 70 // 100
# Changing the configured bet amount must not move a running round's jackpot.
async with session_factory() as session:
config = (await session.scalars(select(RoundConfig))).one()
config.bet_amount_sats = 5_000_000_000
await session.commit()
body = (await ac.get("/rounds/current")).json()
assert body["jackpot_sats"] == (999_800_000 * 2) * 70 // 100
async def test_unhandled_errors_use_the_structured_detail_shape(client):
"""B-24: the catch-all handler answered with a bare-string `detail`, while
app/api/errors.py documents detail as {"code", "message", "params"}. Clients then
had to special-case exactly the responses they understand least."""
from fastapi import FastAPI
from httpx import ASGITransport, AsyncClient
from app.main import log_unhandled_exception
app = FastAPI()
app.add_exception_handler(Exception, log_unhandled_exception)
@app.get("/boom")
async def boom():
raise RuntimeError("secret internal detail")
transport = ASGITransport(app=app, raise_app_exceptions=False)
async with AsyncClient(transport=transport, base_url="http://test") as ac:
resp = await ac.get("/boom")
assert resp.status_code == 500
detail = resp.json()["detail"]
assert detail["code"] == "internal_error"
assert detail["message"] == "internal server error"
assert detail["params"] == {}
# The exception text belongs in logs/app.log, never in the response body.
assert "secret internal detail" not in resp.text
+66
View File
@@ -1,6 +1,7 @@
from datetime import datetime, timedelta, timezone
import pytest
from sqlalchemy import select
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from app.db.base import Base
@@ -105,3 +106,68 @@ async def test_pause_does_not_interrupt_a_round_in_progress(session_factory):
returned = await open_new_round_if_needed(session)
assert returned is not None
assert returned.status == "drawing"
async def test_losing_the_open_race_reuses_the_winning_round(session_factory, monkeypatch):
"""B-09: open_new_round_if_needed was a read-then-insert with no lock, called from
both the scheduler and every place_bet, so two callers could both see "no active
round" and insert one — and a second stuck "open" row blocks every future round,
since get_active_round matches on status.
The race is forced deterministically: the round already exists and is committed,
but this caller's first look is made to miss it (exactly what the loser of the
race sees). The insert then hits ix_rounds_single_active, and the caller must
recover by using the winner's round instead of raising at its caller — a bet must
not fail because a scheduler tick beat it by a millisecond.
"""
from app.rounds import service as service_module
async with session_factory() as session:
session.add(Round(status="open"))
await session.commit()
real_get_active_round = service_module.get_active_round
calls = {"n": 0}
async def blind_first_look(session):
calls["n"] += 1
if calls["n"] == 1:
return None # what the loser of the race sees
return await real_get_active_round(session)
monkeypatch.setattr(service_module, "get_active_round", blind_first_look)
async with session_factory() as session:
round_ = await service_module.open_new_round_if_needed(session)
await session.commit()
assert round_ is not None # recovered, didn't raise
async with session_factory() as session:
rounds = (await session.scalars(select(Round))).all()
assert len(rounds) == 1, f"expected one round, got {[(r.id, r.status) for r in rounds]}"
assert round_.id == rounds[0].id # the winner's round, not a second one
async def test_the_database_refuses_a_second_active_round(session_factory):
"""The guarantee itself, independent of the application code path."""
from sqlalchemy.exc import IntegrityError
async with session_factory() as session:
session.add(Round(status="open"))
await session.commit()
async with session_factory() as session:
session.add(Round(status="drawing"))
with pytest.raises(IntegrityError):
await session.commit()
async def test_closed_rounds_can_coexist_with_an_active_one(session_factory):
async with session_factory() as session:
session.add(Round(status="closed"))
session.add(Round(status="closed"))
session.add(Round(status="open"))
await session.commit()
async with session_factory() as session:
assert len((await session.scalars(select(Round))).all()) == 3
+18
View File
@@ -11,3 +11,21 @@ def test_jwt_roundtrip(monkeypatch):
monkeypatch.setattr(security.settings, "jwt_secret", "test-secret")
token = security.create_access_token(user_id=42)
assert security.decode_access_token(token) == 42
def test_verify_password_returns_false_for_an_unparseable_hash():
"""B-13: only VerifyMismatchError was caught, so a corrupted stored hash raised
InvalidHashError and became an unhandled 500 on the login endpoint instead of a
plain "wrong credentials" 401."""
from app.auth.security import verify_password
assert verify_password("whatever", "not-an-argon2-hash") is False
assert verify_password("whatever", "") is False
def test_verify_password_still_rejects_a_wrong_password():
from app.auth.security import hash_password, verify_password
stored = hash_password("correct-horse-battery")
assert verify_password("correct-horse-battery", stored) is True
assert verify_password("wrong", stored) is False
+24 -1
View File
@@ -45,7 +45,7 @@ async def client(monkeypatch, tmp_path):
app = FastAPI()
app.include_router(auth_router)
app.include_router(users_router)
app.state.electrum_listener = ElectrumListener(lambda: None, db_base.AsyncSessionLocal)
app.state.electrum_listener = ElectrumListener(lambda endpoint: None, db_base.AsyncSessionLocal)
transport = ASGITransport(app=app)
async with AsyncClient(transport=transport, base_url="http://test") as ac:
@@ -108,3 +108,26 @@ async def test_change_password_requires_auth(client):
json={"current_password": "x", "new_password": "brand-new-password"},
)
assert resp.status_code in (401, 403)
@pytest.mark.parametrize(
"payload",
[
{"username": "", "password": "longenough1"},
{"username": "ab", "password": "longenough1"}, # under 3 chars
{"username": "bad user!", "password": "longenough1"}, # disallowed characters
{"username": "validname", "password": "short"}, # under MIN_PASSWORD_LENGTH
{"username": "validname", "password": ""},
],
)
async def test_register_rejects_weak_credentials(client, payload):
"""B-12: registration accepted an empty username and a one-character password,
while /users/me/change-password demanded 8 — an odd place to be lenient on a
custodial system holding real funds."""
resp = await client.post("/auth/register", json=payload)
assert resp.status_code == 422
async def test_register_accepts_valid_credentials(client):
resp = await client.post("/auth/register", json={"username": "goodname", "password": "longenough1"})
assert resp.status_code == 201
+42 -1
View File
@@ -4,7 +4,7 @@ from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from app.config import settings
from app.db.base import Base
from app.db.models import PendingTransaction, User, UtxoEvent
from app.db.models import PendingTransaction, User, UtxoEvent, Withdrawal
from app.wallet.hd import derive_user_address
from app.withdrawals.service import WithdrawalError, request_withdrawal
@@ -122,3 +122,44 @@ async def test_withdrawal_rejects_non_plm_address(session_factory, address):
assert exc_info.value.code == "invalid_address"
assert not client.broadcasted
async def test_withdrawal_to_own_address_is_rejected(session_factory):
"""B-17: allowed before, and it broke two things that assume the recipient and
the change are distinguishable by address — the RBF bump would shrink the
recipient output, and compute_pending_balance counted the amount twice."""
user_id = await _make_funded_user(session_factory, 8, 3_000_000_000)
client = FakeElectrumClient()
async with session_factory() as session:
user = await session.get(User, user_id)
with pytest.raises(WithdrawalError, match="own deposit address"):
await request_withdrawal(session, client, user, user.address, 1_000_000_000)
assert not client.broadcasted
async with session_factory() as session:
assert (await session.scalars(select(UtxoEvent).where(UtxoEvent.user_id == user_id))).one().spent_txid is None
async def test_failed_broadcast_marks_the_withdrawal_failed_and_frees_the_coins(session_factory):
"""B-07/B-08: the Withdrawal row is kept (unlike a bet) so the user can see the
instruction didn't go through, but the coins must come back."""
user_id = await _make_funded_user(session_factory, 9, 3_000_000_000)
class RejectingClient:
async def broadcast(self, raw_tx_hex: str) -> str:
raise RuntimeError("min relay fee not met")
async with session_factory() as session:
user = await session.get(User, user_id)
external = derive_user_address(99)
with pytest.raises(WithdrawalError, match="refused"):
await request_withdrawal(session, RejectingClient(), user, external, 1_000_000_000)
async with session_factory() as session:
withdrawal = (await session.scalars(select(Withdrawal))).one()
assert withdrawal.status == "failed"
assert withdrawal.txid is None
assert (await session.scalars(select(UtxoEvent).where(UtxoEvent.user_id == user_id))).one().spent_txid is None
user = await session.get(User, user_id)
assert user.cached_balance_sats == 3_000_000_000