davide/plm-lottery
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Merge audit-2026-07-27: fix all 25 findings of the second audit

Browse Source 
B-25 … B-49, each in its own commit with its own regression test — the suite
went from 139 to 253 tests. Also on this branch: Docker + Caddy security
headers, the API docs gate, admin endpoint limits, and the SSE gaps.
This commit is contained in:
davide
2026-07-27 23:37:12 +02:00
parent f1a1145cda 0d2fef6502
commit 5cfe2d6f95
66 changed files with 4305 additions and 1466 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.env.example
+5
View File
@@ -30,3 +30,8 @@ ADMIN_TOKEN=
# Every business/round parameter (bet amount, round duration/cooldown, min
# amount, fee rate, RBF timeout, fee address) is configured live from the
# admin panel (/admin) instead of here — see docs/guida-admin.md.
# Swagger/ReDoc/the raw OpenAPI JSON expose the entire API surface — admin
# endpoints included — to anyone who requests them. Off by default; set to
# true only for local development, never in production.
ENABLE_API_DOCS=false
BUGS.md
-966
View File
@@ -1,966 +0,0 @@
# 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.
CLAUDE.md
+174 -167
View File
@@ -8,233 +8,240 @@ 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 (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).
All 10 stages of the original build order are code-complete and unit-tested — 253 tests, all under `tests/unit/` (`tests/integration/` is an empty package). Beyond them: Docker + Caddy deployment, admin dashboard (`/admin`), static test UI (`/`), pending-inclusive balance display, an SSE push channel layered over the original polling, self-service password change + admin password reset, and the reconciliation/corroboration machinery below.
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.
Verified on mainnet with real money: registration + address derivation, deposit crediting (1-conf), a real 10 PLM bet (broadcast → confirmed → change credited back), and one full round cycle (close → draw on a real block hash → 70/30 payout with sat math checked against the broadcast tx → confirmation → close → next round auto-opened). **Withdrawal and the RBF bump path have never been exercised against a live broadcast** — unit-tested only.
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.
Two full-codebase audits — 2026-07-26 (24 findings, 5 critical) and 2026-07-27 (25 more, B-25 … B-49) — are **all fixed** as of 2026-07-27, each with its own regression test. They were tracked in a `BUGS.md` that was deleted once the list emptied, so the ~276 `B-nn` markers left in comments across the code are pointers into git history (`git log --all --grep 'B-nn'` finds the commit that fixed one, and `git show f1a1145:BUGS.md`-style the file as it stood). A closed list is not the same as no bugs: the suite is unit-only (`tests/integration/` is empty), and withdrawal and the RBF bump have never been live-broadcast. "Known gaps" at the end of this file is for limitations accepted **by design** instead. A new finding gets the next B-nn, in its own commit with its own regression test.
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.
Before writing code, read the "Architecture" section below in full plus the diagrams in [flowchart/](flowchart/): [platform-overview.mmd](flowchart/platform-overview.mmd) (the 5-phase flow) and [round-lifecycle.mmd](flowchart/round-lifecycle.mmd) (the round/draw lifecycle). Every node **and edge label** (conditions, retries, loops) is a behaviour that must be implemented as described. Regenerate the companion PDFs with `flowchart/render-pdf.sh <file>.mmd` after editing either.
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).
Human-facing guides are in [docs/](docs/), in Italian by explicit request (an exception to the English-only rule): [setup.md](docs/setup.md), [running-the-server.md](docs/running-the-server.md), [guida-utente.md](docs/guida-utente.md), [guida-admin.md](docs/guida-admin.md). README's Quick start and `docs/running-the-server.md` are Docker-only, matching this file — a bare `uvicorn --reload` workflow was removed from both (B-44).
## Commands
The server itself — in development and in production alike — always runs via Docker (see "Deployment" below); there is no supported way to run `uvicorn` directly against this codebase. The venv (`.venv/`) is only for local tooling: running tests, authoring Alembic migrations, and running the one-time scripts that generate the secrets/key material that end up referenced from `.env`.
The server always runs via Docker, in dev and prod alike — there is no supported way to run `uvicorn` directly. The venv (`.venv/`) is only for local tooling: tests, Alembic migrations, and the one-time key/secret scripts.
```bash
source .venv/bin/activate # venv already created at .venv/
pip install -e ".[dev]" # install/update deps
pip install -e ".[dev]"
alembic revision --autogenerate -m "message" # generate a new migration after editing app/db/models.py (applied automatically by the container's startup command — see Deployment — never run `alembic upgrade head` manually)
alembic revision --autogenerate -m "message" # after editing app/db/models.py; the container applies it at startup — never run `alembic upgrade head` by hand
PYTHONPATH=. python scripts/generate_master_key.py # one-time: create+encrypt the server's master xprv (requires XPRV_ENCRYPTION_KEY in .env; see Deployment for where MASTER_KEY_PATH should point)
PYTHONPATH=. python scripts/decrypt_master_key.py # ops recovery: decrypt+print the existing master xprv (asks for confirmation first)
PYTHONPATH=. python scripts/encrypt_master_key.py # ops bootstrap: bring your own externally-generated xprv instead of generating one (getpass prompt, --overwrite to replace)
PYTHONPATH=. python scripts/generate_master_key.py # one-time: create+encrypt the master xprv (needs XPRV_ENCRYPTION_KEY in .env)
PYTHONPATH=. python scripts/decrypt_master_key.py # ops recovery: decrypt+print it (asks for confirmation)
PYTHONPATH=. python scripts/encrypt_master_key.py # ops bootstrap: import an externally-generated xprv (--overwrite to replace)
PYTHONPATH=. python scripts/electrum_smoke_test.py # manual check: connect, handshake, subscribe to headers, print the tip
python -m pytest # run all tests
python -m pytest tests/unit/test_hd.py # run one test file
python -m pytest tests/unit/test_hd.py::test_derivation_is_deterministic # run a single test
python -m pytest # all 253 tests
python -m pytest tests/unit/test_hd.py # one file
python -m pytest tests/unit/test_hd.py::test_derivation_is_deterministic # one test
```
`.env` (gitignored) holds real secrets for local dev; `.env.example` documents the required keys and how to generate them.
`asyncio_mode = "auto"` (`pyproject.toml`), so async tests need no `@pytest.mark.asyncio`.
`.env` (gitignored) holds the real secrets; `.env.example` documents the required keys and how to generate each. Note it does **not** list `DATABASE_URL` or `MASTER_KEY_PATH`, which the real `.env` does set.
## Deployment (Docker + Caddy)
The app is always run via Docker — dev and prod alike use the same `docker-compose.yml`, just with a different `SITE_ADDRESS` (see below); there's no separate dev-mode compose file or bare-`uvicorn` workflow. `docker-compose.yml` runs two containers: `app` (this codebase, built by `Dockerfile`, runs `alembic upgrade head` then `uvicorn`) and `caddy` (reverse proxy + automatic TLS). `.env` holds the app secrets; `docker-compose.yml` overrides `DATABASE_URL`/`MASTER_KEY_PATH` inside the container to point at the bind-mounted `./data/` (db, encrypted master key, logs — all gitignored, persist across container restarts). Set `MASTER_KEY_PATH` in `.env` itself to the host-side equivalent, `./data/keys/master.xprv.enc`, so the venv-run key-generation scripts above (see "Commands") write to the exact same file the container reads — one source of truth for the key, whichever way it was generated.
Same `docker-compose.yml` for dev and prod — only `SITE_ADDRESS` differs. Two containers: `app` (this codebase; its startup command refuses to start if the master key file is missing, then runs `alembic upgrade head` and `uvicorn`) and `caddy` (reverse proxy + automatic TLS). The compose file overrides `DATABASE_URL`/`MASTER_KEY_PATH` inside the container to point at the bind-mounted `./data/` (db, encrypted key, logs — gitignored, survive restarts). Set `MASTER_KEY_PATH` in `.env` to the host-side `./data/keys/master.xprv.enc` so the venv scripts write the exact file the container reads — one source of truth for the key.
```bash
mkdir -p data/db data/keys data/logs # one-time: host dirs bind-mounted into the app container
# one-time: generate the master key via the venv script above (scripts/generate_master_key.py),
# not via `docker compose run` — MASTER_KEY_PATH in .env already points at ./data/keys/
docker compose up -d --build # build + start app and caddy — same command for dev and prod
docker compose logs -f app # tail app logs (also written to ./data/logs/app.log)
docker compose down # stop
mkdir -p data/db data/keys data/logs # one-time
docker compose up -d --build # dev and prod alike
docker compose logs -f app # also written to ./data/logs/app.log
docker compose down
```
Caddy's site address comes from `SITE_ADDRESS` (env var on the host, read by `docker-compose.yml`):
- **Dev, no domain**: leave it unset (defaults to `localhost`). Caddy detects it isn't a public hostname and issues a self-signed cert from its own internal CA — browsers will warn on first visit, expected for local testing (`curl -k` or click through).
- **Production, with a domain**: `SITE_ADDRESS=lottery.example.com docker compose up -d` (DNS must already point at the server, ports 80+443 reachable). Caddy automatically requests and renews a real Let's Encrypt certificate — no other config needed.
`SITE_ADDRESS` unset → `localhost`, Caddy issues a self-signed cert from its internal CA (browser warning on first visit is expected; `curl -k`). `SITE_ADDRESS=lottery.example.com docker compose up -d` → real Let's Encrypt cert, automatically renewed (needs DNS pointing here and ports 80+443 reachable).
Known risk: `docker-compose.yml` sets `restart: unless-stopped` on `app`, so a crash mid-round auto-restarts the container — which hits the scheduler-resume gap below (a round stuck in `closing`/`drawing`/`paying_out` at restart stays stuck). Don't treat this as unattended-safe until that gap is closed.
The `Caddyfile` sends baseline security headers — HSTS, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy`, and a CSP scoped to `default-src 'self'` plus the Google Fonts `@import` in `style.css`/`admin.css`. `script-src`/`style-src` need `'unsafe-inline'` because both SPAs use inline `onclick` handlers and `style=""` attributes throughout — removing those is a separate, larger refactor, not a header change. `restart: unless-stopped` on `app` means a mid-round crash auto-restarts: `closing` and `paying_out` resume on their own, `drawing` does not (see Known gaps).
## Tech stack (MVP)
## Tech stack
- **Backend language**: Python.
- **PLM node access**: Electrum protocol only (no full node/P2P). Bootstrap server for development: `santantonio.sytes.net:50002` (SSL).
- **Auth**: Argon2 password hashing + JWT sessions.
- **Secrets**: master xprv encrypted at rest with a symmetric scheme (AES-GCM/Fernet); the encryption key itself lives in an env var, never in the DB or in git.
- **Operational config**: every business/round parameter (fee address, bet amount, round duration, round cooldown, draw animation duration, minimum amount, network fee rate, RBF timeout) lives in the `round_config` DB table (single row, `app/rounds/config.py`) and is only editable live via the admin dashboard (`/admin`) or its API — no env var involved at all, no redeploy or restart needed. Defaults for a brand-new instance are hardcoded column defaults on the `RoundConfig` model (`app/db/models.py`), not `app/config.py`. Secrets and infra wiring (master key, JWT secret, Electrum host, admin token, database URL) stay env-var-driven in `.env` since those genuinely need a restart.
- **Round cooldown**: `round_cooldown_seconds` — gap after a round closes before the next one opens, so players have time to see the outcome (default 30s). Not in the original flowchart; added afterwards as an explicit design decision.
- **Maintenance pause**: `RoundConfig.paused` (default `false`), toggled via `POST /admin/pause` / `POST /admin/resume` (a dedicated "Manutenzione" card in `/admin`'s Parametri section, not a plain config field — it's a deliberate operator action, audit-logged as `lottery_paused`/`lottery_resumed`). When set, `rounds/service.py:open_new_round_if_needed` stops opening a *next* round once the current one closes — it never interrupts a round already in progress (that one still closes, draws, and pays out its winner normally). `GET /rounds/current` exposes it as `lottery_paused` so the user-facing page (`/`) shows a maintenance banner.
- Python 3.12+, FastAPI, SQLAlchemy 2 async + Alembic, SQLite via aiosqlite, `embit` for keys/PSBT/tx parsing.
- **PLM access via the Electrum protocol only** (no full node/P2P). Dev bootstrap server: `santantonio.sytes.net:50002` (SSL).
- Auth: Argon2 hashing + JWT (HS256, 24h, **no revocation** — B-34).
- Secrets: master xprv Fernet-encrypted at rest, encryption key in an env var (never in the DB or git). `validate_runtime_secrets()` (`app/config.py`, called from the lifespan — deliberately *not* a `Settings` validator, so imports and tests need no real secrets) makes the server **refuse to serve** if `JWT_SECRET` < 32 chars or `XPRV_ENCRYPTION_KEY` is empty. An empty `ADMIN_TOKEN` is deliberately non-fatal: `require_admin` then denies everything, i.e. a locked panel, not an open one.
- **Operational config lives in the DB, not in env vars**: every business/round parameter is one row of `round_config` (`app/rounds/config.py`), editable live from `/admin` — no redeploy, no restart. Defaults for a fresh instance are column defaults on `RoundConfig` (`app/db/models.py`), *not* `app/config.py`. Only secrets and infra wiring (master key, JWT secret, Electrum hosts, admin token, DB URL) stay in `.env`, since those need a restart anyway.
## PLM network parameters
## PLM network parameters (mainnet)
Source of truth: `PalladiumWallet` repo, [ChainProfiles.cs](../PalladiumWallet/src/Core/Chain/ChainProfiles.cs) and [PalladiumNetworks.cs](../PalladiumWallet/src/Core/Chain/PalladiumNetworks.cs) — always re-check that repo if a value is needed that isn't listed here, rather than guessing.
Source of truth: the `PalladiumWallet` repo — [ChainProfiles.cs](../PalladiumWallet/src/Core/Chain/ChainProfiles.cs), [PalladiumNetworks.cs](../PalladiumWallet/src/Core/Chain/PalladiumNetworks.cs). Re-check there for anything not listed here rather than guessing; its `ChainProfiles.Mainnet.BootstrapServers` is also where `.env.example`'s suggested `ELECTRUM_FALLBACK_SERVERS` come from.
Mainnet:
- BIP44/84 coin type: `746` (i.e. HD path `m/84'/746'/0'/0/index`)
- Bech32 HRP: `plm`
- P2PKH address version byte: `55` (addresses start with `P`)
- P2SH address version byte: `5`
- WIF prefix: `0x80`
- Block time: 120s
- BIP32 extended key headers (Legacy/native-segwit `zprv`/`zpub` etc.): see `ExtKeyHeaders` in `ChainProfiles.cs`
| | |
|---|---|
| BIP44/84 coin type | `746` → `m/84'/746'/0'/0/index` |
| Bech32 HRP | `plm` |
| P2PKH / P2SH version byte | `55` (addresses start with `P`) / `5` |
| WIF prefix | `0x80` |
| Block time | 120s |
| BIP32 ext-key headers | see `ExtKeyHeaders` in `ChainProfiles.cs` |
## Electrum connection (rotation, keepalive, timeouts)
## Business parameters
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:
| Parameter | Value | Where |
|---|---|---|
| Bet cost | 10 PLM (`bet_amount_sats = 1_000_000_000`) | `RoundConfig`, admin-editable |
| Prize split | **70% winner / 30% fees**, rounding remainder to fees | **hardcoded** in `rounds/scheduler.py` — a code change, not an admin edit |
| Round duration / cooldown | 600s / 30s | `RoundConfig` |
| Draw animation | 20s (cosmetic frontend minimum only) | `RoundConfig` |
| Fee rate / RBF timeout | 1 sat/vB / 900s | `RoundConfig` |
| Min withdrawal | = current `bet_amount_sats` (no separate field) | `withdrawals/service.py` |
| Min deposit | none | — |
| Min password length | 8 | `auth/security.py:MIN_PASSWORD_LENGTH` |
| Confirmations, every tx kind | **1** | hardcoded in `tx/confirmation.py` |
| Max inputs per tx | 50 (`MAX_TX_INPUTS`, B-48) — over it the build fails with `too_many_inputs`, it never spends more | hardcoded in `wallet/psbt_builder.py` |
- **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.
`GET /rounds/current`'s `jackpot_sats` is the winner's 70% share, not the whole pool, and the pool is summed from the participants' actual `bet_amount_sats` (each already net of its own bet fee) rather than `count × current bet amount` — editing the bet amount mid-round must not move an in-progress round's advertised jackpot (B-11).
**Round cooldown** (`round_cooldown_seconds`, not in the original flowchart): gap after a round closes before the next opens, so players can see the outcome.
**Maintenance pause** (`RoundConfig.paused`): toggled by `POST /admin/pause` / `POST /admin/resume` — a deliberate operator action with its own "Manutenzione" card in `/admin`, audit-logged `lottery_paused`/`lottery_resumed`, not a plain config field. It only stops the *next* round from opening (`rounds/service.py:open_new_round_if_needed`); a round in progress still closes, draws and pays its winner. Exposed as `lottery_paused` so `/` can show a banner.
## Code map
| Package | Contents |
|---|---|
| `app/main.py` | entry point: lifespan starts the six background tasks, mounts the routers and `app/static/` |
| `app/api/routes/` | `admin`, `bets`, `withdrawals`, `rounds` (incl. SSE), `users`, `qr`; `app/api/errors.py` holds the error contract |
| `app/auth/` | routes (register/login), Argon2 + JWT (`security.py`), `get_current_user`/`get_optional_user` |
| `app/db/` | `models.py` (all tables + the active-round index), engine/session factories |
| `app/wallet/` | HD derivation + WIF export (`hd.py`), PLM network constants, address/scripthash, balance math, `psbt_builder.py` (build/sign bet, withdrawal, payout; `select_utxos`) |
| `app/electrum/` | `client.py` (JSON-RPC, endpoint parsing, timeouts), `listener.py` (the one connection: rotation, keepalive, header validation, corroboration, deposit crediting) |
| `app/deposits/` | crediting / external-spend detection / reinstatement (`service.py`), periodic sweep (`reconcile.py`) |
| `app/bets/`, `app/withdrawals/` | build+broadcast services and their confirmation handlers |
| `app/rounds/` | `scheduler.py` (close/draw/payout), `service.py` (open/active-round rules), `draw.py` (header math + winner pick), `config.py`, `events.py` (SSE pub/sub) |
| `app/tx/` | `broadcast.py` (RBF bumper), `confirmation.py` (poller + handler registry), `reconcile.py`, `locks.py` (per-user locks) |
| `app/static/` | the two SPAs (`index.html`/`app.js`/`style.css`, `admin.html`/`admin.js`/`admin.css`) + `i18n.js` |
## Background tasks
`app/main.py`'s lifespan starts six long-lived asyncio tasks and cancels them on shutdown. Their cadences determine how fast anything self-heals.
| Task | File | Cadence | Role |
| --- | --- | --- | --- |
| `ElectrumListener` | `electrum/listener.py` | reconnect loop, 60s keepalive | the single connection; subscribes headers + every user's scripthash, credits deposits |
| `RoundScheduler` | `rounds/scheduler.py` | 5s | opens/closes rounds, draws, triggers and retries payouts |
| `ConfirmationPoller` | `tx/confirmation.py` | 10s | `pending` → `confirmed` via per-kind handlers registered by `app/{bets,rounds,withdrawals}/confirmation.py` — imported for that side effect in `main.py`, **don't "clean up" those imports** |
| `RbfBumper` | `tx/broadcast.py` | 30s | fee-bumps anything past `rbf_timeout_seconds` |
| `PendingTransactionReconciler` | `tx/reconcile.py` | at startup, then 120s | resolves `building`/`pending` rows against the chain |
| `DepositReconciler` | `deposits/reconcile.py` | 300s (sleeps first) | re-`refresh_user`s every address, catching a silently-lost subscription (B-30) |
Chain access goes through `listener.client`, passed as `lambda: listener.client` so a reconnect swaps the client under its consumers; a task finding it `None` skips that cycle instead of failing. `DepositReconciler` takes the whole listener instead, reusing `refresh_user` so the periodic and notification-driven paths can't diverge.
## Electrum connection
One connection serves everything — deposit credits, broadcasts, confirmations, the tip the draw waits on — so it's both the biggest single point of failure and, with a hostile server on the other end, the biggest integrity risk. Five defences:
- **Rotation.** `ELECTRUM_HOST`/`PORT` is primary, `ELECTRUM_FALLBACK_SERVERS` a comma-separated `host:port[:notls]` list (`client.py:parse_endpoints` rejects malformed entries at startup, not during the outage when the fallback is needed). After any failed or dropped session the next server is tried immediately; the backoff (1s doubling to 30s) only kicks in once every server has had a turn.
- **Bounded requests** (`_REQUEST_TIMEOUT_SECONDS` = 15s); a timeout tears the connection down. Unbounded waits used to hang `POST /bets` *while holding the per-user lock*, and could stall the confirmation poller permanently.
- **The drop is observable**: `client.wait_closed()` resolves when the read loop dies, and `_run_once` races it against the notification consumers and a 60s `server.ping`. Without it the listener sat on queues nobody would ever fill while `listener.client` still looked alive.
- **Headers are validated, not trusted** (`_apply_header`): the tip never regresses, a header must meet the difficulty target it claims, and a single-block advance must chain from the current tip's hash. Failure raises `HeaderValidationError`, which ends the session like a dropped connection and rotates away — that header is the draw's only entropy, so a fabricated one picks the winner.
- **A quorum corroborates the two money-moving decisions** (`_corroborate_majority`, 10s per server, asking only the *other* endpoints — never the active one, which is what a MITM controls): `corroborate_header` before a block seeds the draw (B-28), `corroborate_utxo_spent` before a UTXO missing from one `listunspent` is written off as externally spent (B-29). No fallbacks configured → returns True (the accepted risk of an empty `ELECTRUM_FALLBACK_SERVERS`); nobody answers → returns **False**, since an unreachable network proves nothing.
On reconnect `_subscribe_all_users` runs as its own task with bounded concurrency (`_RESUBSCRIBE_CONCURRENCY` = 20) rather than inline and serially — otherwise a large user base froze `tip_height`, and with it an in-flight draw, for the whole sweep (B-31); one user's failure is logged and skipped. `address_for_new_user` (called right after registration) is best-effort by design: on failure that address stays unsubscribed until the next reconnect or `DepositReconciler` sweep.
## Architecture — the 5 phases
Diagrams: [platform-overview.mmd](flowchart/platform-overview.mmd), [round-lifecycle.mmd](flowchart/round-lifecycle.mmd).
**REG** — on signup the server derives a P2WPKH address via BIP84 (`m/84'/coin'/0'/0/index`, one index per user) from the encrypted master xprv. Permanent, and doubles as deposit address, winnings address and withdrawal change address.
**DEP** — the listener subscribes to the user's scripthash; balance is credited after **1 confirmation**, with the 1-conf reorg risk knowingly accepted and no rollback logic. `deposits/service.py` also detects UTXOs that vanished (spent outside the platform — corroborated per B-29 first) and *reinstates* ones that reappear.
**PLAY** — fixed cost, **at most one active bet per user**. PSBT user-address → pool-address, always with a **change output back to the same user address** (a user's balance must never exactly equal the bet). Fee ~1 sat/vB, **deducted from the bet amount**. No confirmation within the timeout → RBF bump and rebroadcast.
**DRAW** — configurable timer (default 600s):
- *Bet cutoff is the round's own deadline* (`opened_at + round_duration_seconds`), **not** the DB status: `place_bet` calls `rounds/service.round_accepts_bets`, which rejects once the deadline passes even while `status` is still `"open"` (the 5s scheduler tick can lag behind it). Once a round leaves `open`, no new bets either, and no new round opens until this one is fully `closed`.
- *"Yellow light":* closing **waits for every already-broadcast bet to confirm** before drawing, so a bet in flight at the boundary isn't lost (`building` counts as in-flight; what bounds the wait is the reconciler eventually abandoning a bet that never confirms).
- *Algorithm* (deliberately simple, meant to be replaced): first block confirmed after closing — corroborated by the other servers first, and on failure the draw waits for a *further* block and writes a `draw_header_corroboration_failed` audit entry rather than stalling silently — hash as seed, `index = seed mod participant_count` over participants ordered by **broadcast timestamp** (also the tie-break when two bets land in the same block). Equal probability for everyone, regardless of amount.
- *Payout* is signed with the pool key; its **fee comes out of the winner's 70%**, leaving the 30% fee share intact. Same timeout → RBF → rebroadcast pattern.
- *UI, two independent layers.* A generic phase box ("Pagamento al vincitore in corso…") shows to **every** viewer for the whole closing/drawing/paying_out span — pure cosmetic text driven by `status`. **Additively**, a personalized "Hai vinto!/Non hai vinto" box appears only where `user_played` is true (computed via `get_optional_user`, since the endpoint is reachable logged-out) — nobody else has anything to reveal.
- *Reveal timing.* Delayed by at least `draw_animation_seconds`, anchored to the server's `closes_at` so a reload can't reset the countdown, and decoupled from the real (~block-time) wait for `winner_user_id`. Once revealed it's persisted in `localStorage.plm_persisted_result`, surviving the move to `closed` — at which point `get_active_round` stops returning the round and `winner_user_id` disappears from `GET /rounds/current`. `GET /users/me/last-round-result` is the durable DB-backed backstop for a device that missed the live window entirely. Full logic: `refreshRound`/`checkLastRoundResult` in `app/static/app.js`.
**WITHDRAW** — the only way out to an external address: PSBT user-address → external + change back to the user, fee deducted from the withdrawn amount, same RBF pattern.
PLAY and WITHDRAW share a **per-user lock** (`tx/locks.py`): a bet-build and a withdrawal-build can never be in flight at once, since both spend the same UTXO set.
**Three separate on-chain confirmations sit between the timer hitting zero and the payout landing** — a common point of confusion:
1. **Last bet's confirmation** — the round doesn't even flip to `"closing"` until every broadcast bet has 1 conf (`_tick`'s `pending_count` check). May already have happened before the deadline.
2. **The draw block** — `_wait_for_next_block` waits for `tip_height > tip_at_close`, recorded only once step 1 is done, so this is necessarily a later block.
3. **Payout confirmation** — built only after step 2's winner is known, so it needs yet another block; the generic `ConfirmationPoller` tracks it.
At 120s blocks that's ~4–6 min worst case (last bet confirms right at the deadline), ~2–4 min best case — independent of `draw_animation_seconds`.
## 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.
`place_bet`/`request_withdrawal` select whole UTXOs (`select_utxos`, largest-first) and mark each `spent_txid` at broadcast time, long before any confirmation. `cached_balance_sats` (`recompute_balance`) sums only confirmed, unspent UTXOs, so right after a bet it understates the real balance by the whole unconfirmed change — often far more than the amount actually moving.
`compute_pending_balance` (`app/wallet/balance.py`) fixes the *displayed* number without touching what's actually spendable: it decodes the raw tx of every in-flight (`status="pending"`) bet/withdrawal `PendingTransaction` belonging to the user and sums whichever outputs pay back to the user's own address, adding that to `cached_balance_sats`. `GET /users/me` returns both `balance_sats` (confirmed-only — still what withdrawal-max and internal spend logic use, since only confirmed UTXOs are actually spendable) and `pending_balance_sats` + `has_pending` (what the frontend displays, colored green when settled and amber while `has_pending` is true).
`compute_pending_balance` (`app/wallet/balance.py`) fixes the *displayed* number without changing what's spendable: it decodes the raw tx of every in-flight (`pending`) bet/withdrawal for the user and adds back the outputs paying to the user's own address. `GET /users/me` returns both — `balance_sats` (confirmed only; still what withdrawal-max and spend logic use, since only confirmed UTXOs are spendable) and `pending_balance_sats` + `has_pending` (what the UI shows: green when settled, amber while pending). A withdrawal whose amount is covered by the pending-inclusive balance but not the confirmed one gets `balance_pending_confirmation` instead of a flat `insufficient_balance` (B-37), so the error doesn't contradict what the user is looking at.
## Real-time updates (SSE)
`GET /rounds/stream` (`app/api/routes/rounds.py`) is a Server-Sent Events channel layered *on top of* the original polling loops in `app/static/index.html`/`admin.html` — polling is the fallback, not replaced, so a blocked/dropped SSE connection just degrades to the pre-existing behavior. The channel carries no payload and needs no auth: it's purely a "something changed, go refetch" ping; personalization (e.g. `user_played` below) still lives entirely in the normal per-user REST endpoints.
`GET /rounds/stream` is **additive to** the polling loops in the two SPAs, not a replacement — a blocked or dropped stream just degrades to the old behaviour. No payload, no auth: it's a "something changed, go refetch" ping, with all personalization (e.g. `user_played`) staying in the authenticated REST endpoints. The generator re-checks `request.is_disconnected()` every 5s and sends a keep-alive comment every 20s, so neither a client that vanished without a clean close nor a proxy idle timeout breaks it silently.
`app/rounds/events.py`'s `RoundEventBroadcaster` (module-level singleton `broadcaster`) is a simple in-process pub/sub — one `asyncio.Queue` (maxsize 1, so redundant notifications coalesce) per connected SSE client. `broadcaster.publish()` is called from every point that changes something a dashboard would want to know about: a new round opening (`rounds/service.py`), every round status transition (`rounds/scheduler.py`: closing/drawing/paying_out/closed), a bet or withdrawal broadcast (`bets/service.py`, `withdrawals/service.py`), any pending tx confirming — bet/withdrawal/payout (`tx/confirmation.py`), a deposit credited (`deposits/service.py`), and a new block tip arriving (`electrum/listener.py` — the exact moment the "drawing" phase is waiting on).
`rounds/events.py`'s `RoundEventBroadcaster` (singleton `broadcaster`) is in-process pub/sub, one `asyncio.Queue(maxsize=1)` per client so redundant notifications coalesce. `publish()` is called on: a round opening (`rounds/service.py`), every status transition (`scheduler.py`), a bet or withdrawal broadcast, any pending tx confirming (`tx/confirmation.py`), a deposit credited (`deposits/service.py`), and a new tip arriving (`electrum/listener.py` — exactly what the drawing phase waits on). The rollback paths (`_release_failed_bet`, `_release_failed_withdrawal`, the reconciler's abandon) publish too — a rollback moves as much state as the success path, so it must ping the dashboards the same way (B-49).
Deliberate scope decisions, not oversights:
- **Single-process only, no cross-worker fan-out.** Fine for the current deployment (one uvicorn process, see `docker-compose.yml`). A multi-worker/multi-container deployment would need a shared channel (e.g. Redis pub/sub) instead — don't add that speculatively before it's actually needed.
- **Generic broadcast, not a per-user channel.** Every connected client refetches on every event, even ones irrelevant to them. Acceptable at the expected scale (~100 concurrent users); a targeted per-user channel would need auth on the SSE endpoint and server-side knowledge of who's affected by each event — real engineering work, only worth it well past current expected concurrency.
- `MAX_SUBSCRIBERS` (default 500, `app/rounds/events.py`) is a defensive cap only — past it, `GET /rounds/stream` returns 503 instead of opening a stream, and the client's `EventSource` just falls back to polling. Not a substitute for the app-wide "no rate limiting anywhere" gap (see Known gaps).
Deliberate scope limits, not oversights: **single-process only** (fine for one uvicorn process; a multi-worker deployment needs e.g. Redis pub/sub — don't add it speculatively); **generic broadcast, not per-user** (everyone refetches on every event; acceptable at ~100 concurrent users, and a targeted channel would need auth on the stream plus server-side knowledge of who each event affects); `MAX_SUBSCRIBERS` (500) is defensive only — past it the endpoint returns 503 and `EventSource` falls back to polling, which being global and unauthenticated makes the cap itself a cheap DoS of the realtime feature (B-38).
Frontend: both `index.html` and `admin.html` open an `EventSource('/rounds/stream')` and, on an `update` message *or* on `open` (which fires on the initial connection and every automatic reconnect), immediately re-run the same refresh calls polling would eventually do — this matters most right after a dropped connection reconnects, closing most of the "missed while disconnected" gap.
Both SPAs refresh on an `update` message *or* on `open` — the latter fires on every automatic reconnect, closing most of the "missed while disconnected" gap.
## MVP business parameters
## Transaction lifecycle and reconciliation
- Bet cost per round: **10 PLM** by default, admin-configurable (`RoundConfig.bet_amount_sats`) — not a fixed constant.
- Prize split: **70% winner / 30% fees**, hardcoded in `rounds/scheduler.py` (`winner_share = pool_amount_sats * 70 // 100`) — unlike bet amount, this ratio is not in `RoundConfig` and would need a code change, not an admin-panel edit.
- Minimum withdrawal amount: equal to the current bet amount (`RoundConfig.bet_amount_sats`), enforced in `app/withdrawals/service.py` — not a separate admin-configurable field. Deposits have no server-side minimum check.
- Confirmations required for all tx types (deposit, bet, payout, withdrawal): **1**, hardcoded in `tx/confirmation.py` — not configurable, per the design decision below.
Everything that spends money is written **before** it is broadcast and resolved against the chain afterwards; this is what makes the system recover without manual DB edits. `PendingTransaction.status`: `building` → `pending` → `confirmed`, or `failed`.
## What is PLM Lottery
- `building` is written first, UTXOs already marked `spent_txid`, and committed *before* the broadcast (`bets/service.py`, `withdrawals/service.py`, and `scheduler.py:_trigger_payout` — the same shape in four phases, so no DB session is ever held across a network call). A crash in that window leaves evidence, not coins spent on-chain with no record.
- A refused broadcast releases the UTXOs, restores the balance, removes the participant (or marks the withdrawal `failed`), audit-logs, and raises `broadcast_failed` → **502**, since the network refused it, not the caller.
- `tx/reconcile.py` asks the chain about anything still `building`/`pending`: present → promote; positively unknown → `failed` with a `failure_reason`, inputs released, domain row rolled back, `pending_tx_abandoned` logged. Grace differs by state (120s `building`, 6h `pending`, so the bumper gets its attempts first). A *transport* failure never abandons anything — only a server that positively doesn't know the tx, currently inferred by substring-matching the error text (fragile — B-41).
A periodic-round lottery system built on a Bitcoin-like coin (PLM, mainnet). Each user gets a dedicated P2WPKH address (server-side HD wallet); they deposit PLM to that address, place a fixed-cost bet to enter the current round, and when the round closes a winner is drawn who receives 70% of the prize pool (the remaining 30% goes to fees).
`UtxoEvent.spent_txid` must always equal the tx's *current* txid, so `bump_fee` retargets it along with `RoundParticipant.bet_txid`, `Withdrawal.txid` and `Round.payout_txid` on every bump. `broadcast_at` is the *first* broadcast and is never rewritten (the reconciler's abandon clock measures from it); `last_broadcast_at` is what a bump updates and `should_bump` reads. Confirmation handlers key off immutable ids (`round_id`/`user_id`, `withdrawal_id`), never the txid, which changes under them.
## Architecture (from the flowchart subgraphs)
**Payouts retry, and are guarded against paying twice.** Every tick re-examines a `paying_out` round: `_retry_payout_if_due` throttles to one attempt per 60s using the latest `payout_failed` audit entry as its clock (a build failure leaves no DB row to throttle on), and every early return in `_trigger_payout` writes one, so `/admin` shows *why* a round is stuck. Before building, `_trigger_payout` refuses if a `building`/`pending` payout already exists for the round, and `_reserved_payout_outpoints` excludes pool UTXOs claimed by any unresolved payout — without both, a retry would pay the winner twice.
The flow is organized into 5 phases (see [flowchart/platform-overview.mmd](flowchart/platform-overview.mmd) for the full-platform diagram, and [flowchart/round-lifecycle.mmd](flowchart/round-lifecycle.mmd) for the round/draw phase in detail):
**"At most one active round" is a DB invariant**, not a convention: `ix_rounds_single_active` (unique index over the constant `(1)`, restricted to the active statuses) makes a concurrent second insert fail cleanly, and `open_new_round_if_needed` recovers by adopting the winner's round (max 3 attempts).
- **REG (Registration)**: on signup the server derives a new P2WPKH address via BIP84 (`m/84'/coin'/0'/0/index`, one index per user) from a master xprv **encrypted at rest**. This address is permanent and serves as both the deposit address and the address that receives winnings and withdrawals.
- **DEP (Balance top-up)**: an ElectrumClient/SPV subscribes to the user's address scripthash. Internal balance (DB) is credited after **1 confirmation only** — the reorg risk at 1-conf is knowingly accepted in v1, with no rollback logic.
- **PLAY (Bet)**: fixed cost per round, **at most one active bet per user at a time** in v1. The server builds a PSBT user-address → pool-address for the fixed amount, with a **change output back to the same user address** (the user's balance must never exactly equal the bet amount). Fee minimized (~1 sat/vB), **deducted from the bet amount**. If the tx doesn't confirm within a timeout, fee-bump (RBF) and rebroadcast.
- **DRAW (Periodic draw)**: configurable timer (default 10 minutes). The round's own deadline (`opened_at + round_duration_seconds`) is the authoritative "yellow light" cutoff for new bets — **not** the DB status transition. `place_bet` (`app/bets/service.py`) calls `rounds/service.round_accepts_bets(round_, round_duration_seconds)`, which rejects the bet once the deadline has passed even if `status` is still `"open"` in the DB (the `RoundScheduler` tick that flips it to `"closing"` runs every `_TICK_INTERVAL_SECONDS` = 5s and can lag a few seconds behind the deadline). This closes the race where a bet placed in that lag window would otherwise still be accepted. Once a round leaves `open` (closing/drawing/paying_out), **no new bets are accepted** for it either, and a new round can't open until the current one is fully `closed` (see round cooldown below). Round closing **waits for all already-broadcast bets to confirm** before proceeding (avoids losing bets at the round boundary) — this is the "yellow light" behavior: no new entries once the timer hits zero, but bets already in flight are still given time to confirm before the round actually closes and draws. The **next round only opens once the previous round's payout tx is confirmed** — rounds never overlap in v1. v1 draw algorithm (deliberately simple, meant to be replaced later): wait for the first block confirmed after round closing, use its hash as seed, `index = seed mod participant_count` over the participant list ordered by **broadcast timestamp** (this is also the tie-break when two bets confirm in the same block). Every participant has **equal probability regardless of bet amount** (consistent with the fixed bet amount). The payout (70% winner / 30% fees) is signed with the pool address key; the **payout fee is deducted from the winner's 70%**, the 30% fee share stays intact. Same timeout → RBF → rebroadcast pattern here too. The frontend shows a generic "drawing" status box (phase label, e.g. "Pagamento al vincitore in corso…") to **every** viewer on every dashboard for the whole closing/drawing/paying_out phase — this one is purely cosmetic status text, driven directly by `status`, no gating. Independently and *additively* (not instead of it), a personalized "Hai vinto!/Non hai vinto" box appears only for users where `GET /rounds/current`'s `user_played` field is true (computed via `app/auth/dependencies.py:get_optional_user`, since this endpoint is reachable logged-out too) — everyone else has nothing to reveal and never sees it. That reveal is additionally delayed by at least `draw_animation_seconds` (admin-configurable, default 20s) for cosmetic suspense, anchored to the round's server-provided `closes_at` timestamp rather than a client-side "first seen" time (so reloading the page can't reset the countdown), and decoupled from the real (and much longer, ~block-time) wait for `winner_user_id` to actually be set. Once revealed, the result is persisted in the browser's `localStorage` (`plm_persisted_result`) so it survives a page refresh even after the round moves past `paying_out` into `closed` — at which point `get_active_round` stops returning that round at all and `winner_user_id` disappears from `GET /rounds/current` entirely. `GET /users/me/last-round-result` (`app/api/routes/users.py`) is a durable, DB-backed backstop for a user who reloads on a browser/device that missed the live reveal window completely: it looks up the most recent *closed* round the user has a `RoundParticipant` row in. See `app/static/index.html`'s `refreshRound`/`checkLastRoundResult` for the full reveal logic.
- **WITHDRAW (Withdrawal)**: the only way to move funds out of the platform to an external address. PSBT user-address → external-address + change back to the user address, fee deducted from the withdrawn amount, same RBF retry pattern.
## Frontends
PLAY and WITHDRAW share a **per-user DB lock**: a user can never have a bet-build and a withdrawal-build in flight at the same time, since both would otherwise spend from the same UTXO set on the user's dedicated address.
Two static SPAs served directly by FastAPI (`main.py` mounts `app/static/` and adds routes for `/admin`, `/guida`, `/report-bug`) — no build step, no framework, no bundler, `Cache-Control: no-store`.
**Three separate on-chain confirmations, not one, between the timer hitting zero and the payout landing** — a common point of confusion, worth spelling out explicitly:
1. **Last bet's confirmation** (`scheduler.py`'s `_tick`, the `pending_count` check before `_close_and_draw`) — the round doesn't even flip to `"closing"` until every already-broadcast bet has its 1st confirmation. This can already have happened before the timer expired; it's the earliest of the three and not necessarily tied to the deadline at all.
2. **The draw block** (`_wait_for_next_block`, waits for `tip_height > tip_at_close`, where `tip_at_close` is recorded only once step 1 is done) — by construction this must be a **later, different block** than whichever one confirmed the last bet in step 1.
3. **Payout confirmation** — `_trigger_payout` broadcasts only after step 2's block is known, then registers a `PendingTransaction(kind="payout")` that the same generic `ConfirmationPoller` (`app/tx/confirmation.py`) waits on independently — this needs **yet another, later block** than step 2's, since the payout can't be built before the winner is known.
- **`/`** — end-user test UI: register/login, then a navbar dashboard with four panels (Deposito with a QR from `GET /qr/{address}`, Bet, Prelievo, Profilo — account info + self-service password change via `POST /users/me/change-password`), above a persistent round-status card and the chain-status bar with the language switcher.
- **`/admin`** — gated by a token screen (not a login: just `X-Admin-Token` vs `ADMIN_TOKEN`), then five sections each backed by its own `/admin/*` endpoint: Parametri (`RoundConfig` + the Manutenzione card), Utenti (list, WIF privkey export, password reset — both audit-logged), Round, Transazioni pendenti, Audit log; plus a live Electrum/tip-height pill. **Deliberately not linked from `/`** in either direction.
So worst case (last bet confirms right at the deadline) is ~3 block times end-to-end; best case (all bets already confirmed before the timer hit zero) is ~2 (draw block + payout block). At PLM's 120s block time that's roughly 4–6 minutes worst case, 2–4 minutes best case — independent of `draw_animation_seconds`, which only sets a cosmetic minimum for the frontend animation.
Both talk to the same JSON API; there's no admin/user API split beyond `require_admin`.
## Internationalization (user-facing page only)
## Internationalization (`/` only)
`app/static/i18n.js` holds every user-facing string of `/` in 7 languages (en, it, es, fr, de, ru, zh) as one flat `TRANSLATIONS` table — no build step, no fetch, loaded before `app.js` so `t()` is available everywhere. Language comes from `localStorage.plm_lang`, falling back to `navigator.language`, falling back to `en`; the switcher lives in the **chain-bar, not the navbar**, deliberately — the navbar is hidden until login, which would leave the landing page and the login form untranslatable for exactly the users who need the switch.
`app/static/i18n.js` holds every user-facing string of `/` in 7 languages (en, it, es, fr, de, ru, zh) as one flat `TRANSLATIONS` table — no build step, no fetch, loaded before `app.js` so `t()` is always available. Language: `localStorage.plm_lang` → `navigator.language` → `en`. The switcher sits in the **chain-bar, not the navbar**, deliberately: the navbar is hidden until login, which would leave the landing page and login form untranslatable for exactly the users who need it.
- Static markup is translated by attribute (`data-i18n`, plus `-html`, `-placeholder`, `-title`, `-aria-label`, `-alt`), applied by `applyStaticTranslations(root?)` on `DOMContentLoaded` and on every switch. Anything rendered from server data is built with `t()` in `app.js` instead, and re-rendered by `onLanguageChange()` — an element must be in one camp or the other, never both, or the two mechanisms overwrite each other (this is why `#bet-btn` has no `data-i18n`: its label carries the admin-configurable bet amount, so `renderBetButton()` owns it).
- **Every language must have exactly the same key set.** There is no fallback beyond `en`, and a missing key renders as the raw key string.
- `/admin` is intentionally **not** translated (operator-facing, Italian only), and neither is `/guida` (serves `docs/guida-utente.md`).
- Static markup is translated by attribute (`data-i18n`, plus `-html`, `-placeholder`, `-title`, `-aria-label`, `-alt`) via `applyStaticTranslations(root?)`; anything rendered from server data uses `t()` in `app.js` and is re-rendered by `onLanguageChange()`. An element belongs to one camp or the other, **never both**, or the two mechanisms overwrite each other — that's why `#bet-btn` has no `data-i18n`: its label carries the configurable bet amount, so `renderBetButton()` owns it.
- **Every language must have exactly the same key set.** There is no fallback beyond `en`; a missing key renders as the raw key string.
- `/admin` is intentionally untranslated (operator-facing, Italian), as is `/guida`.
**API error contract** (`app/api/errors.py`): the API is single-language by design. User-facing failures answer with a structured `detail` — `{"code", "message", "params"}` — where `message` is English for non-dashboard consumers and `code` is what the frontend maps onto `error.<code>` in `i18n.js` (falling back to `message` for an unknown code). Domain exceptions (`BetError`, `WithdrawalError`) subclass `ApiError` and carry the code from where the failure actually happens; `str(exc)` is still the English message. When adding a user-facing error: give it a code, add `error.<code>` to all 7 languages, and pass interpolated values through `params` (amounts as `*_sats` — the frontend derives a `*_plm` sibling automatically) rather than baking them into the English text.
## Admin dashboard and test UI
Two static single-page apps, served directly by FastAPI (`app/main.py` mounts `app/static/` and adds a dedicated `GET /admin` route) — no build step, no framework. Each page's HTML/CSS/JS are separate files (`index.html`/`style.css`/`app.js`, `admin.html`/`admin.css`/`admin.js`), served as plain static files (no bundler):
- **`/` (`app/static/index.html`)**: the end-user test UI. Register/login, then a menu-driven dashboard (Deposito with a QR code of the address via `GET /qr/{address}`, Bet, Prelievo) with a persistent round-status card (`GET /rounds/current`: id/status/timer/participant count/jackpot) above the menu.
- **`/admin` (`app/static/admin.html`)**: gated by a token screen (not a real login — just checks `X-Admin-Token` against `ADMIN_TOKEN` from `.env`), then a navbar-driven dashboard with five sections, each backed by its own `/admin/*` endpoint (`app/api/routes/admin.py`): Parametri (`RoundConfig` CRUD), Utenti (list + per-user WIF privkey export, audit-logged), Round (history), Transazioni pendenti (in-flight RBF candidates), Audit log. **`/admin` is deliberately not linked from `/`** in either direction — reachable only by knowing the URL.
Both pages talk to the same JSON API everything else uses; there's no separate "admin API" vs "user API" boundary beyond the `require_admin` dependency.
**API error contract** (`app/api/errors.py`) — the API is single-language by design. Failures answer with a structured `detail`: `{"code", "message", "params"}`, where `message` is English for non-dashboard consumers and `code` is what the frontend maps to `error.<code>` in `i18n.js` (falling back to `message` for an unknown code). `BetError`/`WithdrawalError` subclass `ApiError` and carry the code from where the failure happens. Even the catch-all 500 handler answers in that shape (`internal_error`), so clients never special-case unexpected errors, and the exception text stays in `logs/app.log`. Adding a user-facing error: give it a code, add `error.<code>` to all 7 languages, and pass values through `params` (amounts as `*_sats` — the frontend derives a `*_plm` sibling) instead of baking them into English text.
## Non-obvious domain decisions
These choices were made explicitly during design (not derivable from reading a single file) and must be respected in any implementation:
Explicit design choices, not derivable from any single file — respect them:
- Private keys (xprv) are generated and held **server-side** — this is not a non-custodial system: the user never controls their own keys until they make an explicit withdrawal.
- The user's personal deposit address always doubles as the winnings-receiving address: there is no separate "winner address".
- 1 confirmation is the chosen threshold for all tx types (deposits, bets, payouts, withdrawals): don't introduce different thresholds (e.g. 3 or 6 confirmations) without an explicit decision.
- The draw algorithm (node R) is deliberately simple and should be treated as a replaceable/pluggable component, not the final design — don't architect around its current implementation.
- 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.
- Keys are generated and held **server-side**: this is **custodial**. The user controls nothing until they withdraw.
- The deposit address *is* the winnings address — there is no separate "winner address".
- **1 confirmation** for every tx kind. Don't introduce differing thresholds (3, 6, …) without an explicit decision.
- The draw algorithm is a **replaceable component**, not the final design — don't architect around its current form.
- `GET /admin/users/{id}/privkey` exporting a raw WIF is **intentional**, not a vulnerability: the server already holds the master key, so this only exposes via API what an operator could script anyway. Every access writes `admin_privkey_accessed` — don't remove that logging.
- Argon2 hashing means **no password recovery, only reset**: `POST /admin/users/{id}/reset-password` sets a new random password, returns it once for the operator to relay, and logs `admin_password_reset`. No self-service reset exists (no email is ever collected); a logged-in user can only *change* their password by supplying the current one.
- RBF bumps are paid by whoever's change the tx pays back to — the user for bets/withdrawals, the pool for payouts. Counterparty outputs (recipient, winner, fee address) are never touched; only the sender's own change shrinks (`bump_fee`).
## Known gaps / TODO
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:
Accepted **by design** — distinct from the audit findings above (all fixed), which are not duplicated here.
- **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.
- **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).
- **`drawing` doesn't resume after a restart.** `_tick()` handles `open`, `closing` and `paying_out` (the last via `_retry_payout_if_due`); nothing re-enters `_wait_for_next_block` after a crash. That wait is unbounded by design (the draw's entropy genuinely depends on a future block) but no longer silent — past `_DRAW_STALL_THRESHOLD_SECONDS` it logs progress and writes a `draw_stalled` audit entry, and `GET /rounds/current`'s `draw_waiting_since` surfaces it live (B-36). Restart-resumption itself remains the last prerequisite for running unattended.
- **RBF handles one shape only**: a single change output, back to the tx's own sender, big enough to absorb the increase. No extra-input fallback — an exact-amount tx or too-small change raises `RbfError`. Not permanent, though: an unbumpable tx that never confirms is eventually abandoned and its UTXOs released.
- **Withdrawal and RBF bump are unit-tested but never live-broadcast** (failure and rollback branches included — still not a real network).
- **No user-facing history.** `GET /users/me/last-round-result` covers exactly one case (the reveal backstop above). Admin has `/admin/rounds`, `/admin/pending-transactions`, `/admin/audit-log`; a user has no equivalent — a failed withdrawal leaves a `failed` row they can never see, which argues for closing this.
- **Admin auth is one shared bearer token** (`ADMIN_TOKEN`) with no per-admin identity: `audit_log` records *what* changed (config edits as `config_updated`, with before/after) but never *who* did it. It gates the user list, privkey export, password resets and history, so a leak is high-blast-radius.
- **No rate limiting anywhere** (register, bet, withdrawal, admin, SSE). For login this is a blocker, not a gap — tracked as B-33.
- **`/guida` and `/report-bug` are placeholders** (`app/static/guida.html`, `report-bug.html`) — links work, content is "coming soon".
- **No integration tests against a live Electrum connection.** `tests/integration/` is empty; live verification has all been manual (`scripts/electrum_smoke_test.py`, ad hoc scripts, real mainnet txs).
- **Single-process assumptions**: the SSE broadcaster and the per-user locks are in-process only. A multi-worker deployment needs a shared channel and a DB/Redis lock. The round-uniqueness invariant is *not* in this category — it's a DB index.
Caddyfile
+16
View File
@@ -13,5 +13,21 @@
not path /rounds/stream
}
encode @not_sse gzip
# B-43: Caddy adds none of these on its own. The JWT lives in
# localStorage, so any XSS exfiltrates it — CSP is the main mitigation.
# script-src/style-src need 'unsafe-inline' because both SPAs
# (app/static/index.html, admin.html) use inline onclick handlers and
# style="" attributes throughout; removing those is a separate,
# larger refactor, not a header change. fonts.googleapis.com/gstatic.com
# are the one external asset (the Google Fonts @import in style.css/admin.css).
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
X-Frame-Options "DENY"
Referrer-Policy "strict-origin-when-cross-origin"
Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self'; connect-src 'self'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'; object-src 'none'"
}
reverse_proxy app:8123
}
README.md
+16 -17
View File
@@ -13,31 +13,30 @@ production-ready.
## Quick start
The server always runs via Docker (app + Caddy reverse proxy with automatic
TLS) — in dev and production alike, with only `SITE_ADDRESS` differing
between the two. There's no supported way to run `uvicorn` directly; the
venv is only for local tooling (tests, Alembic migrations, the one-time key
scripts) — see [CLAUDE.md](CLAUDE.md#commands).
```bash
cp .env.example .env # then fill in the generated secrets, see docs/setup.md
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
PYTHONPATH=. python scripts/generate_master_key.py
alembic upgrade head
uvicorn app.main:app --reload --port 8123
```
Open `http://127.0.0.1:8123/` for the test UI, `http://127.0.0.1:8123/admin`
for the admin dashboard, `http://127.0.0.1:8123/docs` for the interactive API
docs.
Or run the whole stack (app + Caddy reverse proxy with automatic TLS) via
Docker:
```bash
mkdir -p data/db data/keys data/logs
docker compose run --rm app python scripts/generate_master_key.py
docker compose up -d --build
```
Open `https://localhost/` for the test UI, `https://localhost/admin` for the
admin dashboard (a self-signed-certificate warning on first visit is
expected in dev — accept it, or use `curl -k`). The interactive API docs at
`/docs` are disabled by default (they'd otherwise expose the whole API
surface, admin endpoints included) — set `ENABLE_API_DOCS=true` in `.env` to
enable them.
See [docs/setup.md](docs/setup.md) and
[docs/running-the-server.md](docs/running-the-server.md) for the full
walkthrough (both workflows, dev vs. production TLS).
walkthrough (secrets, master key generation, production TLS with a real
domain).
## Documentation
@@ -62,7 +61,7 @@ python -m pytest # all tests
python -m pytest tests/unit/test_hd.py # one file
```
76 unit tests cover HD derivation, PSBT building, the Electrum client, bets,
232 unit tests cover HD derivation, PSBT building, the Electrum client, bets,
deposits, withdrawals, the round/draw engine, RBF fee-bumping, admin config,
the pending-inclusive balance calculation, and the SSE push channel. No
automated integration tests against a live Electrum connection — mainnet
app/api/client_ip.py
+17
View File
@@ -0,0 +1,17 @@
from fastapi import Request
def client_ip(request: Request) -> str:
"""The caller's real IP, from Caddy's X-Forwarded-For (see Caddyfile) —
request.client.host would otherwise be the reverse proxy's own address, not
the caller's. Falls back to request.client.host only if the header is
somehow missing (e.g. the app container hit directly, bypassing Caddy).
Shared by the login/registration throttles (B-33) and the SSE per-IP
subscriber cap (B-38) so the two can't drift into different notions of
"the client's IP".
"""
forwarded = request.headers.get("x-forwarded-for")
if forwarded:
return forwarded.split(",")[0].strip()
return request.client.host if request.client else "unknown"
app/api/routes/admin.py
+27 -13
View File
@@ -1,11 +1,12 @@
import json
import secrets
from fastapi import APIRouter, Depends, Header, HTTPException, status
from fastapi import APIRouter, Depends, Header, HTTPException, Query, status
from pydantic import BaseModel, Field, field_validator
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.timeutil import isoformat_utc
from app.audit.log import write_audit_log
from app.auth.security import hash_password
from app.config import settings
@@ -14,6 +15,7 @@ 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
from app.wallet.psbt_builder import MAX_FEE_RATE_SAT_VB
router = APIRouter(prefix="/admin", tags=["admin"])
@@ -24,7 +26,9 @@ async def require_admin(x_admin_token: str = Header(default="")) -> None:
# 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):
# compare_digest raises TypeError on a str containing non-ASCII characters
# (B-46) -- comparing the UTF-8 bytes instead accepts any input safely.
if not secrets.compare_digest(x_admin_token.encode(), settings.admin_token.encode()):
raise HTTPException(status.HTTP_403_FORBIDDEN, "invalid admin token")
@@ -68,7 +72,7 @@ class RoundConfigUpdate(BaseModel):
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)
fee_rate_sat_vb: int | None = Field(default=None, ge=1, le=MAX_FEE_RATE_SAT_VB)
rbf_timeout_seconds: int | None = Field(default=None, ge=60, le=7 * 24 * 3600)
draw_animation_seconds: int | None = Field(default=None, ge=0, le=600)
@@ -162,7 +166,7 @@ async def list_users(session: AsyncSession = Depends(get_session)) -> list[Admin
username=u.username,
address=u.address,
balance_sats=u.cached_balance_sats,
created_at=u.created_at.isoformat(),
created_at=isoformat_utc(u.created_at),
)
for u in users
]
@@ -214,6 +218,11 @@ async def reset_user_password(
new_password = secrets.token_urlsafe(12)
user.password_hash = hash_password(new_password)
# B-34: this endpoint exists precisely for the "account compromised" case —
# without bumping token_version, whoever was already logged in (the
# attacker, if that's who prompted the reset) stayed logged in on their
# existing token until it naturally expired, unaffected by the reset.
user.token_version += 1
await write_audit_log(session, "admin_password_reset", {"user_id": user_id}, user_id=user_id)
await session.commit()
return AdminPasswordResetResponse(username=user.username, new_password=new_password)
@@ -235,7 +244,9 @@ class AdminRoundResponse(BaseModel):
@router.get("/rounds", response_model=list[AdminRoundResponse], dependencies=[Depends(require_admin)])
async def list_rounds(session: AsyncSession = Depends(get_session), limit: int = 50) -> list[AdminRoundResponse]:
async def list_rounds(
session: AsyncSession = Depends(get_session), limit: int = Query(default=50, ge=1, le=500)
) -> list[AdminRoundResponse]:
rounds = (await session.scalars(select(Round).order_by(Round.id.desc()).limit(limit))).all()
winner_ids = {r.winner_user_id for r in rounds if r.winner_user_id is not None}
winners = {}
@@ -247,8 +258,8 @@ async def list_rounds(session: AsyncSession = Depends(get_session), limit: int =
AdminRoundResponse(
id=r.id,
status=r.status,
opened_at=r.opened_at.isoformat(),
closed_at=r.closed_at.isoformat() if r.closed_at else None,
opened_at=isoformat_utc(r.opened_at),
closed_at=isoformat_utc(r.closed_at),
draw_block_height=r.draw_block_height,
draw_block_hash=r.draw_block_hash,
winner_user_id=r.winner_user_id,
@@ -275,7 +286,7 @@ class AdminAuditLogResponse(BaseModel):
"/audit-log", response_model=list[AdminAuditLogResponse], dependencies=[Depends(require_admin)]
)
async def list_audit_log(
session: AsyncSession = Depends(get_session), limit: int = 200
session: AsyncSession = Depends(get_session), limit: int = Query(default=200, ge=1, le=500)
) -> list[AdminAuditLogResponse]:
entries = (await session.scalars(select(AuditLog).order_by(AuditLog.id.desc()).limit(limit))).all()
return [
@@ -285,7 +296,7 @@ async def list_audit_log(
payload=json.loads(e.payload_json),
user_id=e.user_id,
round_id=e.round_id,
created_at=e.created_at.isoformat(),
created_at=isoformat_utc(e.created_at),
)
for e in entries
]
@@ -312,10 +323,13 @@ class AdminPendingTransactionResponse(BaseModel):
)
async def list_pending_transactions(
session: AsyncSession = Depends(get_session),
limit: int = Query(default=50, ge=1, le=500),
status_filter: str | None = Query(default=None, alias="status"),
) -> list[AdminPendingTransactionResponse]:
entries = (
await session.scalars(select(PendingTransaction).order_by(PendingTransaction.id.desc()))
).all()
query = select(PendingTransaction).order_by(PendingTransaction.id.desc())
if status_filter is not None:
query = query.where(PendingTransaction.status == status_filter)
entries = (await session.scalars(query.limit(limit))).all()
return [
AdminPendingTransactionResponse(
id=p.id,
@@ -327,7 +341,7 @@ async def list_pending_transactions(
current_txid=p.current_txid,
fee_rate_sat_vb=p.fee_rate_sat_vb,
attempt_count=p.attempt_count,
broadcast_at=p.broadcast_at.isoformat(),
broadcast_at=isoformat_utc(p.broadcast_at),
replaced_by_txid=p.replaced_by_txid,
)
for p in entries
app/api/routes/rounds.py
+17 -3
View File
@@ -8,11 +8,13 @@ from pydantic import BaseModel
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.client_ip import client_ip
from app.api.timeutil import isoformat_utc
from app.auth.dependencies import get_optional_user
from app.db.models import RoundParticipant, User
from app.db.session import get_session
from app.rounds.config import get_round_config
from app.rounds.events import RoundEventCapacityError, broadcaster
from app.rounds.events import EVICTED, RoundEventCapacityError, broadcaster
from app.rounds.service import get_active_round
router = APIRouter(prefix="/rounds", tags=["rounds"])
@@ -45,9 +47,14 @@ async def round_stream(request: Request) -> Response:
That's also what happens past MAX_SUBSCRIBERS (app/rounds/events.py): this
returns 503 rather than opening a stream, and the browser's EventSource
just retries later while the frontend keeps working off polling meanwhile.
Concurrent streams are additionally capped per client IP (B-38): past
MAX_SUBSCRIBERS_PER_IP, opening one more evicts that IP's own oldest
connection rather than refusing the new one or letting a single source
exhaust the global cap and degrade every other user.
"""
try:
queue = broadcaster.subscribe()
queue = broadcaster.subscribe(client_ip(request))
except RoundEventCapacityError:
return JSONResponse(status_code=503, content={"detail": "too many concurrent update streams"})
@@ -58,7 +65,9 @@ async def round_stream(request: Request) -> Response:
if await request.is_disconnected():
break
try:
await asyncio.wait_for(queue.get(), timeout=_SSE_DISCONNECT_CHECK_SECONDS)
item = await asyncio.wait_for(queue.get(), timeout=_SSE_DISCONNECT_CHECK_SECONDS)
if item is EVICTED:
break # this IP opened another stream past its per-IP cap
yield "event: update\ndata: {}\n\n".format(json.dumps({}))
ticks_since_keepalive = 0
except asyncio.TimeoutError:
@@ -90,6 +99,10 @@ class CurrentRoundResponse(BaseModel):
winner_amount_sats: int | None = None
draw_block_height: int | None = None
draw_block_hash: str | None = None
# B-36: set only while status == "drawing", so the frontend can show "still
# waiting for a block" rather than a countdown implying a bounded wait — this
# phase has no timeout, only draw_animation_seconds' cosmetic minimum.
draw_waiting_since: str | None = None
chain_tip_height: int | None = None
lottery_paused: bool = False
user_played: bool = False
@@ -168,6 +181,7 @@ async def current_round(
winner_amount_sats=round_.winner_amount_sats,
draw_block_height=round_.draw_block_height,
draw_block_hash=round_.draw_block_hash,
draw_waiting_since=isoformat_utc(round_.drawing_started_at) if round_.status == "drawing" else None,
chain_tip_height=chain_tip_height,
lottery_paused=config.paused,
user_played=user_played,
app/api/routes/users.py
+17 -4
View File
@@ -4,8 +4,9 @@ from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.errors import http_error
from app.api.timeutil import isoformat_utc
from app.auth.dependencies import get_current_user
from app.auth.security import MIN_PASSWORD_LENGTH, hash_password, verify_password
from app.auth.security import MIN_PASSWORD_LENGTH, create_access_token, 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
@@ -36,7 +37,7 @@ async def me(
balance_sats=user.cached_balance_sats,
pending_balance_sats=pending_balance_sats,
has_pending=has_pending,
created_at=user.created_at.isoformat(),
created_at=isoformat_utc(user.created_at),
)
@@ -45,12 +46,16 @@ class ChangePasswordRequest(BaseModel):
new_password: str
@router.post("/me/change-password", status_code=status.HTTP_204_NO_CONTENT)
class ChangePasswordResponse(BaseModel):
access_token: str
@router.post("/me/change-password", response_model=ChangePasswordResponse)
async def change_password(
body: ChangePasswordRequest,
user: User = Depends(get_current_user),
session: AsyncSession = Depends(get_session),
) -> None:
) -> ChangePasswordResponse:
"""Self-service password change — requires the current password, unlike the
admin-only /admin/users/{id}/reset-password (which is for a user who's
actually locked out and can't provide it)."""
@@ -67,7 +72,15 @@ async def change_password(
)
user.password_hash = hash_password(body.new_password)
# B-34: bumping token_version invalidates every token issued before this
# point — including this very request's own bearer token, and any an
# attacker who knew the old password might be holding. A fresh token is
# handed back so *this* session keeps working without forcing a re-login;
# every other open session (this user's other devices, or an attacker's)
# gets "session_expired" on its next request.
user.token_version += 1
await session.commit()
return ChangePasswordResponse(access_token=create_access_token(user.id, user.token_version))
class LastRoundResultResponse(BaseModel):
app/api/timeutil.py
+17
View File
@@ -0,0 +1,17 @@
from datetime import datetime, timezone
def isoformat_utc(dt: datetime | None) -> str | None:
"""Serialize a datetime for API responses, stamping it UTC first.
Every DateTime column is written via app.db.models.utcnow() but SQLite/aiosqlite
round-trips it as a naive datetime, so a bare .isoformat() drops the "Z"/offset
and JavaScript's `new Date()` on the frontend parses the result as local time
instead of UTC (B-35). All stored values are UTC in practice, so a naive value
can be safely stamped rather than converted.
"""
if dt is None:
return None
if dt.tzinfo is None:
dt = dt.replace(tzinfo=timezone.utc)
return dt.isoformat()
app/auth/dependencies.py
+12 -3
View File
@@ -16,13 +16,19 @@ async def get_current_user(
session: AsyncSession = Depends(get_session),
) -> User:
try:
user_id = decode_access_token(credentials.credentials)
user_id, token_version = decode_access_token(credentials.credentials)
except Exception as exc:
raise http_error(status.HTTP_401_UNAUTHORIZED, "session_expired", "invalid token") from exc
user = await session.scalar(select(User).where(User.id == user_id))
if user is None:
raise http_error(status.HTTP_401_UNAUTHORIZED, "session_expired", "user not found")
if user.token_version != token_version:
# B-34: a password change (self-service or admin reset) bumps
# token_version, so a token issued before it — including one an
# attacker who had the old password is still holding — reads as
# expired rather than staying valid until it naturally times out.
raise http_error(status.HTTP_401_UNAUTHORIZED, "session_expired", "token has been superseded")
return user
@@ -37,7 +43,10 @@ async def get_optional_user(
if not auth_header.startswith("Bearer "):
return None
try:
user_id = decode_access_token(auth_header.removeprefix("Bearer "))
user_id, token_version = decode_access_token(auth_header.removeprefix("Bearer "))
except Exception:
return None
return await session.scalar(select(User).where(User.id == user_id))
user = await session.scalar(select(User).where(User.id == user_id))
if user is None or user.token_version != token_version:
return None
return user
app/auth/rate_limit.py
+75
View File
@@ -0,0 +1,75 @@
import time
from dataclasses import dataclass
@dataclass
class _Bucket:
failures: int = 0
locked_until: float = 0.0
last_failure_at: float = 0.0
class RateLimiter:
"""In-process failed-attempt throttle with exponential backoff, keyed by an
arbitrary string (username, IP...). Single-process-only, like UserLocks
(app/tx/locks.py) — an accepted MVP constraint; a multi-worker deployment
would need a shared store (Redis) instead (B-33).
Brute-forcing a login here isn't a spammy client to be capped at N req/s —
it's an attempt to withdraw someone else's funds — so failures are
penalized with a delay that doubles each time past `threshold` free
attempts, rather than a flat rate cap. `decay_seconds` ages a bucket back
to zero once failures stop, so a shared/NAT IP isn't punished forever for
someone else's earlier mistakes.
"""
def __init__(
self,
threshold: int = 5,
base_delay: float = 2.0,
max_delay: float = 300.0,
decay_seconds: float = 900.0,
) -> None:
self._threshold = threshold
self._base_delay = base_delay
self._max_delay = max_delay
self._decay_seconds = decay_seconds
self._buckets: dict[str, _Bucket] = {}
def retry_after(self, key: str) -> float:
bucket = self._buckets.get(key)
if bucket is None:
return 0.0
remaining = bucket.locked_until - time.monotonic()
return remaining if remaining > 0 else 0.0
def record_failure(self, key: str) -> None:
now = time.monotonic()
bucket = self._buckets.setdefault(key, _Bucket())
if bucket.failures and now - bucket.last_failure_at > self._decay_seconds:
bucket.failures = 0
bucket.failures += 1
bucket.last_failure_at = now
if bucket.failures >= self._threshold:
delay = min(self._max_delay, self._base_delay * 2 ** (bucket.failures - self._threshold))
bucket.locked_until = now + delay
def record_success(self, key: str) -> None:
self._buckets.pop(key, None)
class AuthRateLimiters:
"""The three throttles B-33 needs, bundled so they can live on `app.state`
(like `UserLocks`, see app/tx/locks.py) rather than as module globals.
A module global would persist for the lifetime of the process — fine in
production (one app instance), but wrong in the test suite, where every
test builds its own FastAPI app against a fresh in-memory DB and expects a
clean slate; a shared global would leak failure counts between unrelated
tests. Per-`app.state` state gets a fresh instance per app automatically.
"""
def __init__(self) -> None:
self.login = RateLimiter(threshold=5, base_delay=2.0, max_delay=300.0)
self.login_ip = RateLimiter(threshold=20, base_delay=2.0, max_delay=300.0)
self.register_ip = RateLimiter(threshold=5, base_delay=5.0, max_delay=600.0)
app/auth/routes.py
+61 -3
View File
@@ -4,7 +4,9 @@ from sqlalchemy import func, select
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.client_ip import client_ip as _client_ip
from app.api.errors import http_error
from app.auth.rate_limit import AuthRateLimiters
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
@@ -15,6 +17,33 @@ router = APIRouter(prefix="/auth", tags=["auth"])
_MAX_REGISTER_RETRIES = 5
def _rate_limiters(request: Request) -> AuthRateLimiters:
# B-33: no rate limiting on login was a brute-forceable path to withdrawing
# someone else's funds. Keyed per-username *and* per-IP so an attacker can't
# dodge the throttle by spraying one password across many accounts, nor by
# routing one account's guesses through many IPs alone (the username key
# still catches that). The IP limiter's threshold is deliberately higher
# than the username one: a single account should lock out fast, but a
# shared/NAT IP hosting several genuine users shouldn't be punished for one
# of them mistyping a password a few times. Registration gets its own,
# coarser limiter, IP-only — no username exists yet to key on — mainly to
# bound how many accounts one IP can spin up (B-31), not to protect a
# secret. Lives on app.state (see AuthRateLimiters) rather than a module
# global so each app instance gets its own, isolated throttle state.
if not hasattr(request.app.state, "auth_rate_limiters"):
request.app.state.auth_rate_limiters = AuthRateLimiters()
return request.app.state.auth_rate_limiters
def _rate_limited_error(retry_after: float):
return http_error(
status.HTTP_429_TOO_MANY_REQUESTS,
"rate_limited",
"too many attempts, try again later",
retry_after_seconds=int(retry_after) + 1,
)
class RegisterRequest(BaseModel):
"""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
@@ -34,6 +63,13 @@ class TokenResponse(BaseModel):
async def register(
body: RegisterRequest, request: Request, session: AsyncSession = Depends(get_session)
) -> TokenResponse:
limiters = _rate_limiters(request)
ip_key = f"ip:{_client_ip(request)}"
retry_after = limiters.register_ip.retry_after(ip_key)
if retry_after > 0:
raise _rate_limited_error(retry_after)
limiters.register_ip.record_failure(ip_key)
existing = await session.scalar(select(User).where(User.username == body.username))
if existing is not None:
raise http_error(status.HTTP_409_CONFLICT, "username_taken", "username already taken")
@@ -66,7 +102,9 @@ async def register(
continue
await session.refresh(user)
request.app.state.electrum_listener.address_for_new_user(user.id, user.address)
return TokenResponse(access_token=create_access_token(user.id), address=user.address)
return TokenResponse(
access_token=create_access_token(user.id, user.token_version), address=user.address
)
raise http_error(
status.HTTP_409_CONFLICT,
@@ -81,8 +119,28 @@ class LoginRequest(BaseModel):
@router.post("/login", response_model=TokenResponse)
async def login(body: LoginRequest, session: AsyncSession = Depends(get_session)) -> TokenResponse:
async def login(
body: LoginRequest, request: Request, session: AsyncSession = Depends(get_session)
) -> TokenResponse:
limiters = _rate_limiters(request)
username_key = f"user:{body.username.lower()}"
ip_key = f"ip:{_client_ip(request)}"
retry_after = max(limiters.login.retry_after(username_key), limiters.login_ip.retry_after(ip_key))
if retry_after > 0:
raise _rate_limited_error(retry_after)
user = await session.scalar(select(User).where(User.username == body.username))
if user is None or not verify_password(body.password, user.password_hash):
# Same code path (and therefore the same response) whether the username
# doesn't exist or the password is wrong — no enumeration oracle here.
limiters.login.record_failure(username_key)
limiters.login_ip.record_failure(ip_key)
raise http_error(status.HTTP_401_UNAUTHORIZED, "invalid_credentials", "invalid credentials")
return TokenResponse(access_token=create_access_token(user.id), address=user.address)
# Only the username bucket resets on success — the IP bucket is left to decay
# on its own, so one correct login can't be used to wipe out an IP's failure
# count while it's mid-attack against other accounts.
limiters.login.record_success(username_key)
return TokenResponse(
access_token=create_access_token(user.id, user.token_version), address=user.address
)
app/auth/security.py
+12 -4
View File
@@ -39,12 +39,20 @@ def verify_password(password: str, password_hash: str) -> bool:
return False
def create_access_token(user_id: int) -> str:
def create_access_token(user_id: int, token_version: int = 0) -> str:
expires_at = datetime.now(timezone.utc) + timedelta(minutes=settings.jwt_expire_minutes)
payload = {"sub": str(user_id), "exp": expires_at}
# "tv" lets get_current_user (app/auth/dependencies.py) reject a token issued
# before the account's password was last changed (B-34): change-password and
# the admin reset both bump User.token_version, so every token that still
# carries the old value stops working immediately instead of staying valid
# for up to jwt_expire_minutes after a compromise is supposedly handled.
payload = {"sub": str(user_id), "tv": token_version, "exp": expires_at}
return jwt.encode(payload, settings.jwt_secret, algorithm=settings.jwt_algorithm)
def decode_access_token(token: str) -> int:
def decode_access_token(token: str) -> tuple[int, int]:
payload = jwt.decode(token, settings.jwt_secret, algorithms=[settings.jwt_algorithm])
return int(payload["sub"])
# .get(..., 0) covers tokens issued before "tv" existed (pre-B-34 deploy) —
# they carry no claim at all, and 0 is what a freshly migrated user's
# token_version starts at, so those sessions keep working across the deploy.
return int(payload["sub"]), int(payload.get("tv", 0))
app/bets/service.py
+6 -1
View File
@@ -62,7 +62,7 @@ async def place_bet(session: AsyncSession, client: ElectrumClient, user: User) -
fee_rate_sat_vb=config.fee_rate_sat_vb,
)
except InsufficientFundsError as exc:
raise BetError(exc.code, str(exc)) from exc
raise BetError(exc.code, str(exc), **exc.params) from exc
# --- Phase 1: record the intent, *then* broadcast (B-08) --------------------
# Broadcasting first meant a failure (or a crash) between the broadcast and the
@@ -144,6 +144,11 @@ async def _release_failed_bet(
user_id=user_id,
)
await session.commit()
# The rollback moved as much state as the successful path did — the balance is
# back, the participant is gone, so participant_count and jackpot shrank again.
# Without this the dashboards kept showing the phantom bet until their next poll
# (B-49); the reconciler's own abandon path has always published here.
broadcaster.publish()
def _pending_transaction(
app/config.py
+5
View File
@@ -29,6 +29,11 @@ class Settings(BaseSettings):
jwt_expire_minutes: int = 60 * 24
admin_token: str = ""
# Swagger/ReDoc/OpenAPI JSON expose the entire API surface (admin endpoints
# included) to anyone who requests them. Off by default (B-42) — set to true
# only for local development, never in production.
enable_api_docs: bool = False
# Every business/round parameter (bet amount, round duration/cooldown,
# min amount, fee rate, RBF timeout, fee address) lives in the round_config
# DB table instead (app/db/models.py RoundConfig, app/rounds/config.py) —
app/db/base.py
+36 -1
View File
@@ -1,9 +1,44 @@
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from sqlalchemy import event
from sqlalchemy.ext.asyncio import AsyncEngine, async_sessionmaker, create_async_engine
from sqlalchemy.orm import DeclarativeBase
from app.config import settings
# How long a writer waits for a lock held by another writer before SQLite raises
# "database is locked" (B-39). A few seconds is enough to ride out this app's own
# five concurrent background tasks (scheduler, confirmation poller, RBF bumper,
# two reconcilers) plus HTTP handlers briefly overlapping a write.
_SQLITE_BUSY_TIMEOUT_MS = 5000
def _register_sqlite_pragmas(target_engine: AsyncEngine) -> None:
"""Without WAL, SQLite's default (rollback-journal) mode lets a writer block
every reader for the duration of its transaction, and a second writer arriving
while one is already active fails immediately rather than waiting at all —
realistic under this app's concurrency, and nothing previously handled it.
WAL lets readers and writers proceed without blocking each other, and
busy_timeout gives a second writer a real window to wait for the first
instead of an instant `OperationalError`.
No-op for any dialect other than sqlite (e.g. a future PostgreSQL
DATABASE_URL), which neither needs nor understands these pragmas.
"""
if target_engine.dialect.name != "sqlite":
return
@event.listens_for(target_engine.sync_engine, "connect")
def _set_sqlite_pragmas(dbapi_connection, connection_record) -> None:
cursor = dbapi_connection.cursor()
try:
cursor.execute("PRAGMA journal_mode=WAL")
cursor.execute("PRAGMA synchronous=NORMAL")
cursor.execute(f"PRAGMA busy_timeout={_SQLITE_BUSY_TIMEOUT_MS}")
finally:
cursor.close()
engine = create_async_engine(settings.database_url)
_register_sqlite_pragmas(engine)
AsyncSessionLocal = async_sessionmaker(engine, expire_on_commit=False)
app/db/models.py
+21 -3
View File
@@ -1,6 +1,6 @@
from datetime import datetime, timezone
from sqlalchemy import BigInteger, ForeignKey, Index, String, UniqueConstraint, text
from sqlalchemy import BigInteger, ForeignKey, Index, String, Text, UniqueConstraint, text
from sqlalchemy.orm import Mapped, mapped_column
from app.db.base import Base
@@ -21,6 +21,12 @@ class User(Base):
# Read cache only; must always be written in the same transaction as the
# utxo_events rows it summarizes. Source of truth is utxo_events.
cached_balance_sats: Mapped[int] = mapped_column(BigInteger, default=0)
# Embedded in every issued JWT (app/auth/security.py) and checked on every
# request (app/auth/dependencies.py:get_current_user). Bumped on a
# self-service or admin password change so every token issued before that
# point stops working immediately, instead of staying valid for up to
# jwt_expire_minutes after a compromised account's password is reset (B-34).
token_version: Mapped[int] = mapped_column(default=0, server_default="0")
created_at: Mapped[datetime] = mapped_column(default=utcnow)
@@ -66,6 +72,11 @@ class Round(Base):
status: Mapped[str] = mapped_column(String(16), default="open")
opened_at: Mapped[datetime] = mapped_column(default=utcnow)
closed_at: Mapped[datetime | None] = mapped_column(default=None)
# Set once, when status flips to "drawing" (rounds/scheduler.py:_close_and_draw).
# Lets both the audit log (B-36's draw_stalled entries) and GET /rounds/current
# (draw_waiting_since) measure how long a round has been waiting on a block,
# since that wait has no timeout of its own — see _wait_for_next_block.
drawing_started_at: Mapped[datetime | None] = mapped_column(default=None)
draw_block_height: Mapped[int | None] = mapped_column(default=None)
draw_block_hash: Mapped[str | None] = mapped_column(String(64), default=None)
seed_int: Mapped[str | None] = mapped_column(String(128), default=None)
@@ -143,8 +154,15 @@ class PendingTransaction(Base):
user_id: Mapped[int | None] = mapped_column(ForeignKey("users.id"), default=None)
current_txid: Mapped[str] = mapped_column(String(64))
fee_rate_sat_vb: Mapped[int]
raw_tx_hex: Mapped[str] = mapped_column(String)
raw_tx_hex: Mapped[str] = mapped_column(Text)
# The *first* broadcast — never rewritten by a bump — since this is what the
# reconciler's abandon-after-N-hours grace period (app/tx/reconcile.py) measures
# from. Bumping used to overwrite this field, which reset that clock on every
# bump and meant a repeatedly-bumped-but-never-mined tx was never abandoned
# (B-27). last_broadcast_at is the one bump_fee updates, and the one should_bump
# (app/tx/broadcast.py) reads to decide whether another bump is due.
broadcast_at: Mapped[datetime] = mapped_column(default=utcnow)
last_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
@@ -175,7 +193,7 @@ class AuditLog(Base):
id: Mapped[int] = mapped_column(primary_key=True)
event_type: Mapped[str] = mapped_column(String(32))
payload_json: Mapped[str] = mapped_column(String)
payload_json: Mapped[str] = mapped_column(Text)
user_id: Mapped[int | None] = mapped_column(ForeignKey("users.id"), default=None)
round_id: Mapped[int | None] = mapped_column(ForeignKey("rounds.id"), default=None)
created_at: Mapped[datetime] = mapped_column(default=utcnow)
app/deposits/reconcile.py
+69
View File
@@ -0,0 +1,69 @@
"""Periodic safety net for deposit crediting and external-spend detection (B-30),
independent of scripthash-change notifications.
Those notifications are the fast path, but nothing else re-verifies a user's
balance against the chain if one is ever silently lost: `address_for_new_user`'s
subscribe is best-effort (its own failure just logs, see electrum/listener.py),
and on an otherwise healthy, long-lived connection there may be no reconnect for
days — the only other event that re-subscribes everyone from scratch. Without
this, a single lost subscription meant that user's deposits were never credited,
indefinitely.
This mirrors app/tx/reconcile.py's shape (a periodic sweep gated on the Electrum
client being connected) but reuses ElectrumListener.refresh_user directly rather
than re-implementing crediting/spend-detection, so the notification-driven and
periodic paths can never behave differently from each other.
"""
import asyncio
import logging
from sqlalchemy import select
from sqlalchemy.ext.asyncio import async_sessionmaker
from app.db.models import User
from app.electrum.listener import ElectrumListener
from app.electrum.scripthash import address_to_scripthash
logger = logging.getLogger(__name__)
_SWEEP_INTERVAL_SECONDS = 300
class DepositReconciler:
def __init__(self, session_factory: async_sessionmaker, listener: ElectrumListener):
self._session_factory = session_factory
self._listener = listener
async def run(self) -> None:
while True:
await asyncio.sleep(_SWEEP_INTERVAL_SECONDS)
if self._listener.client is None:
continue
try:
await self._sweep_once()
except asyncio.CancelledError:
raise
except Exception:
logger.exception("deposit reconciliation sweep failed")
async def _sweep_once(self) -> None:
"""Round-robins over every user's address rather than only ones missing
from the listener's in-memory `_scripthash_to_user` map: that map can't
tell "never subscribed" apart from "subscribed, but this server silently
stopped delivering notifications for it" — exactly the failure mode this
exists to catch. One user failing (a transient network hiccup) must not
stop the sweep from reaching the rest, mirroring poll_once's per-item
isolation in tx/confirmation.py.
"""
async with self._session_factory() as session:
users = (await session.scalars(select(User))).all()
for user in users:
if self._listener.client is None:
return # connection dropped mid-sweep; the next reconnect's own _subscribe_all_users covers everyone
scripthash = address_to_scripthash(user.address)
try:
await self._listener.refresh_user(user.id, scripthash)
except Exception:
logger.exception("deposit reconciliation failed for user_id=%s", user.id)
app/deposits/service.py
+90 -17
View File
@@ -1,3 +1,5 @@
import logging
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
@@ -6,6 +8,8 @@ from app.db.models import UtxoEvent
from app.rounds.events import broadcaster
from app.wallet.balance import recompute_balance
logger = logging.getLogger(__name__)
async def credit_confirmed_utxos(session: AsyncSession, user_id: int, entries: list[dict]) -> int:
"""Insert utxo_events for newly-confirmed entries from an Electrum
@@ -59,18 +63,64 @@ async def credit_confirmed_utxos(session: AsyncSession, user_id: int, entries: l
_EXTERNAL_SPEND_SENTINEL = "external-spend"
async def detect_external_spends(session: AsyncSession, user_id: int, entries: list[dict]) -> int:
"""Mirror of credit_confirmed_utxos: catches a UTXO leaving the address
through a transaction this platform never built (e.g. someone spending it
directly with the raw privkey, bypassing /withdrawals entirely).
async def reinstate_reappeared_utxos(session: AsyncSession, user_id: int, entries: list[dict]) -> int:
"""The reverse of a mark applied by find_utxos_missing_from/
mark_utxos_spent_externally (B-29): if an outpoint we'd previously flagged as
spent outside the platform reappears as unspent in a later listunspent, undo
the mark instead of leaving it permanent no matter what the chain says
afterwards. Cheap and purely DB-side — always safe to run on every refresh.
"""
current_keys = {(entry["tx_hash"], entry["tx_pos"]) for entry in entries}
Everything the platform itself spends (bets, withdrawals, payouts) sets
spent_txid at broadcast time, before the tx ever reaches the chain — so by
the time an Electrum refresh runs, an outpoint still marked unspent in our
own DB that Electrum no longer reports as unspent was never on our radar.
entries is this address's current `listunspent`; anything in our unspent
set but missing from it left the address some other way. Returns the
number of UTXOs newly marked spent.
marked_rows = (
await session.scalars(
select(UtxoEvent).where(
UtxoEvent.user_id == user_id, UtxoEvent.spent_txid == _EXTERNAL_SPEND_SENTINEL
)
)
).all()
reinstated = 0
for row in marked_rows:
if (row.txid, row.vout) not in current_keys:
continue
row.spent_txid = None
await write_audit_log(
session,
"utxo_external_spend_reinstated",
{"txid": row.txid, "vout": row.vout, "amount_sats": row.amount_sats},
user_id=user_id,
)
reinstated += 1
if reinstated:
await session.flush()
await recompute_balance(session, user_id)
await session.commit()
broadcaster.publish()
return reinstated
async def find_utxos_missing_from(session: AsyncSession, user_id: int, entries: list[dict]) -> list[UtxoEvent]:
"""Candidates for an external spend (B-29): unspent UTXOs the DB believes this
user still holds that are absent from `entries`, this address's current
listunspent. Everything the platform itself spends (bets, withdrawals,
payouts) sets spent_txid at broadcast time, before the tx ever reaches the
chain — so an outpoint still marked unspent in our own DB that Electrum no
longer reports as unspent was never on our own radar.
Returning a row here is *not* proof it was actually spent — only that this one
server's reply no longer lists it. A single broken, behind, or malicious
server could otherwise zero a user's balance on one bad reply, which is why
the caller (electrum/listener.py:refresh_user) must independently
corroborate each candidate against other configured servers before treating
it as genuine, rather than this function marking anything itself.
An entirely empty `entries` for an address the DB believes is funded returns
no candidates at all: it would otherwise flag every one of this user's UTXOs
as missing from a single reply, which is a strong sign of an incomplete or
broken response rather than N independent spends landing in the same refresh.
"""
current_keys = {(entry["tx_hash"], entry["tx_pos"]) for entry in entries}
@@ -80,9 +130,32 @@ async def detect_external_spends(session: AsyncSession, user_id: int, entries: l
)
).all()
newly_spent = 0
for row in unspent_rows:
if (row.txid, row.vout) in current_keys:
if not entries and unspent_rows:
logger.warning(
"listunspent for user_id=%s returned no entries at all while %s UTXO(s) are still recorded "
"unspent — treating this as an incomplete response rather than a full external sweep",
user_id,
len(unspent_rows),
)
return []
return [row for row in unspent_rows if (row.txid, row.vout) not in current_keys]
async def mark_utxos_spent_externally(session: AsyncSession, user_id: int, utxo_ids: list[int]) -> int:
"""Applies the external-spend sentinel to UTXOs the caller has already
corroborated against other servers (B-29) — this function does no
verification of its own, only persistence, so it never runs with a session
held open across the network calls that verification needs.
Re-checks each row is still unspent before applying the mark: something else
may have resolved it (a legitimate platform spend, or a prior refresh) between
when the caller read the candidate list and finished corroborating it.
"""
marked = 0
for utxo_id in utxo_ids:
row = await session.get(UtxoEvent, utxo_id)
if row is None or row.spent_txid is not None:
continue
row.spent_txid = _EXTERNAL_SPEND_SENTINEL
await write_audit_log(
@@ -91,12 +164,12 @@ async def detect_external_spends(session: AsyncSession, user_id: int, entries: l
{"txid": row.txid, "vout": row.vout, "amount_sats": row.amount_sats},
user_id=user_id,
)
newly_spent += 1
marked += 1
if newly_spent:
if marked:
await session.flush()
await recompute_balance(session, user_id)
await session.commit()
broadcaster.publish()
return newly_spent
return marked
app/electrum/client.py
+11
View File
@@ -169,6 +169,17 @@ class ElectrumClient:
async def listunspent(self, scripthash: str) -> list[dict]:
return await self.request("blockchain.scripthash.listunspent", [scripthash])
async def get_history(self, scripthash: str) -> list[dict]:
"""Every transaction touching `scripthash`, each as {"tx_hash", "height"} —
height > 0 means confirmed at that height, height <= 0 means still in the
mempool. Used instead of blockchain.transaction.get's verbose=True mode
for confirmation/existence checks (B-41): several Electrum server
implementations and versions reject the verbose flag outright ("verbose
transactions are currently unsupported"), while get_history is a plain,
universally-supported method every server must implement.
"""
return await self.request("blockchain.scripthash.get_history", [scripthash])
async def broadcast(self, raw_tx_hex: str) -> str:
return await self.request("blockchain.transaction.broadcast", [raw_tx_hex])
app/electrum/listener.py
+230 -11
View File
@@ -6,9 +6,20 @@ from sqlalchemy import select
from sqlalchemy.ext.asyncio import async_sessionmaker
from app.db.models import User
from app.deposits.service import credit_confirmed_utxos, detect_external_spends
from app.deposits.service import (
credit_confirmed_utxos,
find_utxos_missing_from,
mark_utxos_spent_externally,
reinstate_reappeared_utxos,
)
from app.electrum.client import ElectrumClient, ElectrumEndpoint
from app.electrum.scripthash import address_to_scripthash
from app.rounds.draw import (
HeaderValidationError,
header_hex_to_block_hash,
header_meets_its_own_target,
header_prev_hash,
)
from app.rounds.events import broadcaster
logger = logging.getLogger(__name__)
@@ -18,6 +29,17 @@ logger = logging.getLogger(__name__)
# difference between noticing the drop in a minute and never noticing it at all.
_PING_INTERVAL_SECONDS = 60
# How long to wait for any *one* other server's answer when corroborating the
# draw's block header (B-28) or a candidate external spend (B-29). Shorter than
# the standard request timeout since this is a supplementary check across several
# servers at once — a single slow fallback shouldn't hold up the others.
_CORROBORATION_TIMEOUT_SECONDS = 10
# How many users to resubscribe at once on reconnect (B-31), instead of one at a
# time. Bounded rather than unlimited so a huge user base doesn't open thousands
# of simultaneous in-flight requests against the one active connection.
_RESUBSCRIBE_CONCURRENCY = 20
class ElectrumListener:
"""Long-lived background task: keeps one Electrum connection open, subscribes
@@ -46,6 +68,11 @@ class ElectrumListener:
self._endpoints = list(endpoints or [])
self._endpoint_index = 0
self._scripthash_to_user: dict[str, int] = {}
# Retains address_for_new_user's fire-and-forget subscribe task so it
# can't be garbage-collected mid-flight, and so its exception (if any) is
# actually observed instead of only reaching asyncio's default "Task
# exception was never retrieved" handler (B-30).
self._background_tasks: set[asyncio.Task] = set()
self.tip_height: int = 0
self.tip_header_hex: str | None = None
self.client: ElectrumClient | None = None
@@ -60,11 +87,32 @@ class ElectrumListener:
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."""
being watched immediately, without waiting for the next reconnect cycle.
Best-effort, not retried on its own: `self.client` can still become None
between the check below and the task actually running (the connection
drops in between), which used to raise an AssertionError inside an
untracked task and vanish silently (B-30). The exception is now logged
instead, and — since a failure here just means this one address stays
unsubscribed until the next reconnect's `_subscribe_all_users` or the
periodic `DepositReconciler` sweep (also B-30) catches it — that's an
acceptable, self-healing outcome rather than something worth its own
retry/backoff loop.
"""
scripthash = address_to_scripthash(address)
self._scripthash_to_user[scripthash] = user_id
if self.client is not None:
asyncio.create_task(self._subscribe_and_refresh(scripthash, user_id))
task = asyncio.create_task(self._subscribe_and_refresh(scripthash, user_id))
self._background_tasks.add(task)
task.add_done_callback(self._background_tasks.discard)
task.add_done_callback(self._log_subscribe_task_failure)
def _log_subscribe_task_failure(self, task: asyncio.Task) -> None:
if task.cancelled():
return
exc = task.exception()
if exc is not None:
logger.warning("could not subscribe a newly-registered user's address: %r", exc)
async def run(self) -> None:
backoff = 1
@@ -118,8 +166,6 @@ class ElectrumListener:
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
@@ -132,9 +178,25 @@ class ElectrumListener:
asyncio.create_task(self._keepalive(client)),
asyncio.create_task(client.wait_closed()),
]
# B-31: resubscribing every user is O(users) sequential round-trips —
# at thousands of users that's minutes during which, previously,
# nothing above had started yet: tip_height was frozen and an
# in-flight draw's _wait_for_next_block made zero progress for the
# entire resubscribe. Running it as its own background task instead
# of awaiting it inline here means tip updates (and notifications for
# whichever users are already subscribed) keep flowing throughout.
# It's deliberately not one of the raced `tasks` above: unlike those,
# it's expected to finish normally, and its own completion must not
# look like the session ending. Any failure partway through is
# logged the same way address_for_new_user's background task is
# (B-30), and it's cancelled below along with everything else once
# the session actually does end.
subscribe_task = asyncio.create_task(self._subscribe_all_users())
subscribe_task.add_done_callback(self._log_subscribe_all_users_failure)
try:
done, still_running = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
finally:
subscribe_task.cancel()
for task in tasks:
task.cancel()
for task in done:
@@ -146,23 +208,45 @@ class ElectrumListener:
await client.close()
return True
def _log_subscribe_all_users_failure(self, task: asyncio.Task) -> None:
if task.cancelled():
return
exc = task.exception()
if exc is not None:
logger.warning("resubscribing all users failed partway through: %r", exc)
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:
"""B-31: subscribes with bounded concurrency (_RESUBSCRIBE_CONCURRENCY at
a time) instead of one user at a time — at thousands of users a serial
loop meant thousands of sequential round-trips. One user's failure (a
single slow or briefly-erroring request) must not stop the rest from
being subscribed, mirroring the same per-item isolation used elsewhere
(e.g. tx/confirmation.py's poll_once, deposits/reconcile.py's sweep)."""
async with self._session_factory() as session:
users = (await session.scalars(select(User))).all()
for user in users:
semaphore = asyncio.Semaphore(_RESUBSCRIBE_CONCURRENCY)
async def _subscribe_one(user: User) -> None:
scripthash = address_to_scripthash(user.address)
self._scripthash_to_user[scripthash] = user.id
async with semaphore:
try:
await self._subscribe_and_refresh(scripthash, user.id)
except Exception:
logger.exception("failed to resubscribe user_id=%s", user.id)
await asyncio.gather(*(_subscribe_one(user) for user in users))
async def _subscribe_and_refresh(self, scripthash: str, user_id: int) -> None:
assert self.client is not None
await self.client.subscribe_scripthash(scripthash)
await self._refresh_user(user_id, scripthash)
await self.refresh_user(user_id, scripthash)
def _apply_header(self, header: dict) -> None:
"""Record a new chain tip, refusing to move backwards.
@@ -173,8 +257,19 @@ class ElectrumListener:
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.
Two validation checks guard against a hostile or MITM'd server simply
fabricating a header (B-28), since that header is the draw's sole source of
entropy: it must satisfy the difficulty target it claims for itself, and —
when it's a direct single-block advance from our own current tip, the only
case we can check without a full header chain — it must chain from that
tip's hash. Either failure raises HeaderValidationError rather than
silently ignoring the header, which (via _consume_headers/_run_once) ends
this session the same way a dropped connection would, so run() rotates to
the next configured server instead of continuing to trust this one.
"""
height = header["height"]
header_hex = header.get("hex")
if height < self.tip_height:
logger.warning(
"ignoring Electrum header at height %s, below the current tip %s (reorg or server switch?)",
@@ -182,8 +277,109 @@ class ElectrumListener:
self.tip_height,
)
return
if header_hex:
if not header_meets_its_own_target(header_hex):
raise HeaderValidationError(
f"header at height {height} does not satisfy its own claimed difficulty target"
)
if (
self.tip_header_hex
and height == self.tip_height + 1
and header_prev_hash(header_hex) != header_hex_to_block_hash(self.tip_header_hex)
):
raise HeaderValidationError(
f"header at height {height} does not chain from the current tip (height {self.tip_height})"
)
self.tip_height = height
self.tip_header_hex = header.get("hex")
self.tip_header_hex = header_hex
async def _corroborate_majority(
self,
ask: Callable[[ElectrumEndpoint], "asyncio.Future"],
agrees: Callable[[object], bool],
description: str,
) -> bool:
"""Shared quorum logic behind corroborate_header (B-28) and
corroborate_utxo_spent (B-29): ask every *other* configured server (never
the currently active one — that's exactly what a hostile server or a MITM
would control) and require a strict majority of the ones that actually
answer to agree, via `agrees`, with what our own connection reported.
Returns True with no other servers configured — nothing to corroborate
against, a risk accepted when ELECTRUM_FALLBACK_SERVERS was left empty
(see CLAUDE.md). Returns False (never silently "passes") if none of the
others could be reached, since an unreachable network proves nothing
either way.
"""
others = [endpoint for endpoint in self._endpoints if endpoint != self.current_endpoint]
if not others:
return True
results = await asyncio.gather(*(ask(endpoint) for endpoint in others))
responded = [result for result in results if result is not None]
if not responded:
logger.warning(
"could not corroborate %s with any of %s other configured server(s)", description, len(others)
)
return False
agreements = sum(1 for result in responded if agrees(result))
return agreements * 2 > len(responded)
async def corroborate_header(self, height: int, expected_hash: str) -> bool:
"""B-28: is `expected_hash` — the header our own active connection
reported for `height` — corroborated by other configured servers before
the draw (rounds/scheduler.py:_wait_for_next_block) treats it as
trustworthy entropy? Without this, a single hostile server (or a MITM on
the one active connection) can single-handedly decide who wins every
round; this raises the bar to controlling a majority of the configured
servers. See _corroborate_majority for the shared quorum logic.
"""
async def _ask(endpoint: ElectrumEndpoint) -> str | None:
client = self._client_factory(endpoint)
try:
await asyncio.wait_for(client.connect(), timeout=_CORROBORATION_TIMEOUT_SECONDS)
result = await asyncio.wait_for(
client.request("blockchain.block.header", [height]),
timeout=_CORROBORATION_TIMEOUT_SECONDS,
)
if not isinstance(result, str):
return None
return header_hex_to_block_hash(result)
except Exception:
return None
finally:
await client.close()
return await self._corroborate_majority(_ask, lambda block_hash: block_hash == expected_hash, f"block {height} header")
async def corroborate_utxo_spent(self, scripthash: str, txid: str, vout: int) -> bool:
"""B-29: before deposits/service.py's find_utxos_missing_from candidates
are treated as genuinely spent outside the platform, ask the other
configured servers whether *they* also no longer report this outpoint as
unspent. A single broken, behind, or malicious server could otherwise zero
a user's balance on one incomplete listunspent reply. See
_corroborate_majority for the shared quorum logic.
"""
async def _ask(endpoint: ElectrumEndpoint) -> bool | None:
client = self._client_factory(endpoint)
try:
await asyncio.wait_for(client.connect(), timeout=_CORROBORATION_TIMEOUT_SECONDS)
entries = await asyncio.wait_for(
client.listunspent(scripthash), timeout=_CORROBORATION_TIMEOUT_SECONDS
)
still_unspent = any(e.get("tx_hash") == txid and e.get("tx_pos") == vout for e in entries)
return not still_unspent # True = this server agrees the outpoint is gone
except Exception:
return None
finally:
await client.close()
return await self._corroborate_majority(_ask, lambda agrees: agrees, f"outpoint {txid}:{vout}")
async def _consume_headers(self, queue: asyncio.Queue) -> None:
while True:
@@ -200,15 +396,38 @@ class ElectrumListener:
scripthash, _status = await queue.get()
user_id = self._scripthash_to_user.get(scripthash)
if user_id is not None:
await self._refresh_user(user_id, scripthash)
await self.refresh_user(user_id, scripthash)
async def _refresh_user(self, user_id: int, scripthash: str) -> None:
async def refresh_user(self, user_id: int, scripthash: str) -> None:
"""Three phases, so no DB session is held across a network call (B-18),
same shape as _trigger_payout: read what's needed, corroborate any
candidate external spends against other servers (B-29), then persist.
"""
assert self.client is not None
entries = await self.client.listunspent(scripthash)
async with self._session_factory() as session:
credited = await credit_confirmed_utxos(session, user_id, entries)
spent_externally = await detect_external_spends(session, user_id, entries)
reinstated = await reinstate_reappeared_utxos(session, user_id, entries)
candidates = [
(row.id, row.txid, row.vout)
for row in await find_utxos_missing_from(session, user_id, entries)
]
confirmed_ids = [
utxo_id
for utxo_id, txid, vout in candidates
if await self.corroborate_utxo_spent(scripthash, txid, vout)
]
spent_externally = 0
if confirmed_ids:
async with self._session_factory() as session:
spent_externally = await mark_utxos_spent_externally(session, user_id, confirmed_ids)
if credited:
logger.info("credited %s new UTXO(s) for user_id=%s", credited, user_id)
if reinstated:
logger.info("reinstated %s previously-flagged UTXO(s) for user_id=%s", reinstated, user_id)
if spent_externally:
logger.warning("%s UTXO(s) spent outside the platform for user_id=%s", spent_externally, user_id)
app/main.py
+17 -2
View File
@@ -23,6 +23,7 @@ from app.auth.routes import router as auth_router
from app.api.errors import ApiError
from app.config import settings, validate_runtime_secrets
from app.db.base import AsyncSessionLocal
from app.deposits.reconcile import DepositReconciler
from app.electrum.client import ElectrumClient, ElectrumEndpoint, parse_endpoints
from app.electrum.listener import ElectrumListener
from app.rounds.scheduler import RoundScheduler
@@ -40,7 +41,7 @@ def _make_electrum_client(endpoint: ElectrumEndpoint) -> ElectrumClient:
@asynccontextmanager
async def lifespan(app: FastAPI):
# Refuses to serve rather than starting up half-configured — see B-15 in BUGS.md.
# Refuses to serve rather than starting up half-configured (B-15).
validate_runtime_secrets()
endpoints = parse_endpoints(
@@ -61,6 +62,10 @@ async def lifespan(app: FastAPI):
# 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)
# Periodic safety net for deposit crediting/external-spend detection,
# independent of scripthash-change notifications — catches a subscription
# silently lost on an otherwise healthy connection (B-30).
deposit_reconciler = DepositReconciler(AsyncSessionLocal, listener)
tasks = [
asyncio.create_task(listener.run()),
@@ -68,6 +73,7 @@ async def lifespan(app: FastAPI):
asyncio.create_task(poller.run()),
asyncio.create_task(bumper.run()),
asyncio.create_task(reconciler.run()),
asyncio.create_task(deposit_reconciler.run()),
]
try:
yield
@@ -78,7 +84,16 @@ async def lifespan(app: FastAPI):
await listener.client.close()
app = FastAPI(title="PLM Lottery", lifespan=lifespan)
# Swagger/ReDoc/the raw OpenAPI JSON enumerate the entire API surface, admin
# endpoints included, to anyone who requests them (B-42) — disabled unless
# ENABLE_API_DOCS is explicitly set, which should only happen in development.
app = FastAPI(
title="PLM Lottery",
lifespan=lifespan,
docs_url="/docs" if settings.enable_api_docs else None,
redoc_url="/redoc" if settings.enable_api_docs else None,
openapi_url="/openapi.json" if settings.enable_api_docs else None,
)
app.include_router(auth_router)
app.include_router(users_router)
app.include_router(bets_router)
app/rounds/draw.py
+67
View File
@@ -1,5 +1,22 @@
import hashlib
# Byte offsets of a standard 80-byte block header: version(4) + prev_block(32) +
# merkle_root(32) + timestamp(4) + bits(4) + nonce(4).
_HEADER_LENGTH_BYTES = 80
_PREV_BLOCK_OFFSET = 4
_PREV_BLOCK_LENGTH = 32
_BITS_OFFSET = 72
_BITS_LENGTH = 4
class HeaderValidationError(Exception):
"""Raised by ElectrumListener._apply_header (B-28) when a header either doesn't
satisfy the difficulty target it claims for itself, or doesn't chain from the
previously accepted tip. Letting this propagate out of the header-consuming
task ends the current Electrum session the same way a dropped connection would
(see ElectrumListener._run_once), so the listener rotates to the next
configured server instead of trusting a header a server just forged."""
def header_hex_to_block_hash(header_hex: str) -> str:
"""Block hash from a raw Electrum header: sha256d, byte-reversed, hex.
@@ -10,6 +27,56 @@ def header_hex_to_block_hash(header_hex: str) -> str:
return digest[::-1].hex()
def header_prev_hash(header_hex: str) -> str:
"""The header's `prev_block` field, byte-reversed to the same conventional
(display) order as header_hex_to_block_hash's return value, so the two can be
compared directly to check that one header actually chains from another."""
header_bytes = bytes.fromhex(header_hex)
prev = header_bytes[_PREV_BLOCK_OFFSET : _PREV_BLOCK_OFFSET + _PREV_BLOCK_LENGTH]
return prev[::-1].hex()
def _target_from_bits(bits: int) -> int:
"""Decompress Bitcoin-style compact `nBits` difficulty encoding into the full
256-bit target a valid header's hash must be less than or equal to."""
exponent = bits >> 24
mantissa = bits & 0xFFFFFF
if exponent <= 3:
return mantissa >> (8 * (3 - exponent))
return mantissa << (8 * (exponent - 3))
def header_meets_its_own_target(header_hex: str) -> bool:
"""Whether this header's hash satisfies the difficulty target *it claims for
itself* (the `bits` field). Rejects a header that was never actually mined —
e.g. one fabricated wholesale by a hostile or MITM'd Electrum server (B-28),
since satisfying a self-chosen target still requires real proof-of-work.
This does NOT — and, short of downloading and validating the full header
chain's difficulty-retarget history, cannot — catch a header honestly mined at
a real but implausibly low self-chosen difficulty: a server could still declare
an easy target and grind it out with modest hardware. That residual risk is why
the draw additionally requires the winning block's header to be corroborated by
the *other* configured servers before using it as the seed (see
ElectrumListener.corroborate_header and rounds/scheduler.py:_wait_for_next_block)
rather than relying on this check alone.
"""
header_bytes = bytes.fromhex(header_hex)
if len(header_bytes) != _HEADER_LENGTH_BYTES:
return False
bits = int.from_bytes(header_bytes[_BITS_OFFSET : _BITS_OFFSET + _BITS_LENGTH], "little")
target = _target_from_bits(bits)
if target <= 0:
return False
digest = hashlib.sha256(hashlib.sha256(header_bytes).digest()).digest()
# The hash as the integer comparable against `target`: this is the same digest
# header_hex_to_block_hash reverses into the conventional display hex, so
# reading it byte-reversed as a big-endian int is equivalent to reading the
# original digest bytes as little-endian — both give the same integer.
hash_int = int.from_bytes(digest, "little")
return hash_int <= target
def draw_winner(participants: list[str], block_hash_hex: str) -> str:
"""v1 draw algorithm (flowchart.mmd, node R): seed = block hash as an integer,
index = seed mod participant_count, winner = participants[index]. Anyone can
app/rounds/events.py
+54 -14
View File
@@ -1,16 +1,31 @@
import asyncio
from collections import defaultdict
# Defensive cap on concurrent SSE subscribers. Expected load is on the order of
# ~100 concurrent users; this is set well above that so it never engages under
# normal use — it exists purely so a runaway/DoS-y number of open connections
# degrades (new connections fall back to polling, see round_stream()) instead
# of growing the in-memory subscriber set without bound. Revisit this number if
# expected concurrency grows well past it.
# Defensive backstop on concurrent SSE subscribers overall, regardless of source
# — expected load is on the order of ~100 concurrent users, so this is set well
# above that. The real defense against a single abusive source is the per-IP cap
# below (B-38): a global-only cap was trivially exhausted by one client opening
# MAX_SUBSCRIBERS connections, degrading every other user to polling — the
# comment used to call it "defensive"; it was actually the vector.
MAX_SUBSCRIBERS = 500
# How many concurrent streams a single client IP may hold. Deliberately small —
# a real browser tab needs at most one, occasionally two briefly across a
# reload — since this bounds one source's share of the global capacity, not a
# legitimate per-user concurrency limit.
MAX_SUBSCRIBERS_PER_IP = 5
# Put on a to-be-evicted subscriber's queue (B-38) to wake its generator
# (app/api/routes/rounds.py:round_stream) promptly so it closes the connection
# instead of lingering, silently uncounted, until the client's own network
# timeout or the next keep-alive tick.
EVICTED = object()
class RoundEventCapacityError(Exception):
"""Raised by subscribe() when MAX_SUBSCRIBERS is already reached."""
"""Raised by subscribe() when MAX_SUBSCRIBERS — the global backstop — is
already reached. The per-IP cap never raises this; it evicts instead (see
subscribe())."""
class RoundEventBroadcaster:
@@ -26,22 +41,47 @@ class RoundEventBroadcaster:
would need a shared channel (e.g. Redis pub/sub) instead.
"""
def __init__(self, max_subscribers: int = MAX_SUBSCRIBERS):
self._subscribers: set[asyncio.Queue] = set()
def __init__(self, max_subscribers: int = MAX_SUBSCRIBERS, max_per_ip: int = MAX_SUBSCRIBERS_PER_IP):
self._ip_by_queue: dict[asyncio.Queue, str] = {}
self._queues_by_ip: dict[str, list[asyncio.Queue]] = defaultdict(list)
self.max_subscribers = max_subscribers
self.max_per_ip = max_per_ip
def subscribe(self) -> asyncio.Queue:
if len(self._subscribers) >= self.max_subscribers:
def subscribe(self, client_ip: str = "unknown") -> asyncio.Queue:
if len(self._ip_by_queue) >= self.max_subscribers:
raise RoundEventCapacityError(f"already at the {self.max_subscribers}-subscriber cap")
ip_queues = self._queues_by_ip[client_ip]
if len(ip_queues) >= self.max_per_ip:
# B-38: evict this IP's own oldest connection rather than refusing
# the new one — bounds one source's footprint without turning a
# legitimate reconnect storm (a flaky network retrying EventSource)
# into an outright block, and without letting one abusive IP crowd
# out unrelated clients the way the old global-only cap did.
oldest = ip_queues.pop(0)
self._ip_by_queue.pop(oldest, None)
if not oldest.full():
oldest.put_nowait(EVICTED)
queue: asyncio.Queue = asyncio.Queue(maxsize=1)
self._subscribers.add(queue)
self._ip_by_queue[queue] = client_ip
ip_queues.append(queue)
return queue
def unsubscribe(self, queue: asyncio.Queue) -> None:
self._subscribers.discard(queue)
client_ip = self._ip_by_queue.pop(queue, None)
if client_ip is None:
return
ip_queues = self._queues_by_ip.get(client_ip)
if ip_queues is None:
return
if queue in ip_queues:
ip_queues.remove(queue)
if not ip_queues:
self._queues_by_ip.pop(client_ip, None)
def publish(self) -> None:
for queue in self._subscribers:
for queue in self._ip_by_queue:
if queue.full():
continue # a not-yet-delivered notification already covers this one
queue.put_nowait(None)
app/rounds/scheduler.py
+229 -28
View File
@@ -3,11 +3,12 @@ import logging
from datetime import datetime, timedelta, timezone
from embit import script
from embit.transaction import Transaction
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import async_sessionmaker
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from app.audit.log import write_audit_log
from app.db.models import PendingTransaction, Round, RoundParticipant, User
from app.db.models import AuditLog, PendingTransaction, Round, RoundParticipant, User
from app.electrum.listener import ElectrumListener
from app.electrum.scripthash import address_to_scripthash
from app.rounds.config import get_round_config
@@ -22,6 +23,20 @@ logger = logging.getLogger(__name__)
_TICK_INTERVAL_SECONDS = 5
# B-26: how long to wait after a payout failure before automatically retrying it.
# Long enough that a persistently-broken payout (misconfigured fee_address,
# insufficient pool UTXOs) doesn't re-attempt — and re-write a payout_failed audit
# entry — every _TICK_INTERVAL_SECONDS; short enough that a transient failure
# (a dropped Electrum connection, a momentarily-empty pool) self-heals quickly.
_PAYOUT_RETRY_INTERVAL_SECONDS = 60
# B-36: _wait_for_next_block has no timeout of its own — a round can legitimately
# wait several PLM blocks (120s each) for its draw entropy, and re-waits on a
# corroboration failure. These only make an already-long wait *observable*, they
# never cut it short.
_DRAW_PROGRESS_LOG_INTERVAL_SECONDS = 60
_DRAW_STALL_THRESHOLD_SECONDS = 360 # a few multiples of PLM's 120s block time
class RoundScheduler:
"""Background task implementing flowchart.mmd's DRAW subgraph: closes the
@@ -55,8 +70,17 @@ class RoundScheduler:
round_id, status, opened_at = round_.id, round_.status, round_.opened_at
round_duration_seconds = (await get_round_config(session)).round_duration_seconds
if status == "paying_out":
# B-26: _trigger_payout used to run exactly once, from _close_and_draw —
# any failure after that (no Electrum client, insufficient pool UTXOs, a
# rejected broadcast) or a process restart while paying_out left the round
# wedged here forever. Every tick now re-checks and retries, throttled by
# _retry_payout_if_due so a persistent failure doesn't retry on every tick.
await self._retry_payout_if_due(round_id)
return
if status not in ("open", "closing"):
return # already drawing/paying_out; progress happens elsewhere
return # "drawing" — progress happens inside the in-flight _close_and_draw call
if status == "open":
opened_at = opened_at.replace(tzinfo=timezone.utc)
@@ -121,11 +145,13 @@ class RoundScheduler:
user_by_address[user.address] = user.id
round_.status = "drawing"
drawing_started_at = datetime.now(timezone.utc)
round_.drawing_started_at = drawing_started_at
await session.commit()
broadcaster.publish()
tip_at_close = self._listener.tip_height
block_height, block_hash = await self._wait_for_next_block(tip_at_close)
block_height, block_hash = await self._wait_for_next_block(round_id, tip_at_close, drawing_started_at)
winner_address = draw_winner(addresses, block_hash)
async with self._session_factory() as session:
@@ -155,22 +181,143 @@ class RoundScheduler:
logger.info("round %s: winner=%s pool=%s", round_id, winner_address, pool_amount)
await self._trigger_payout(round_id)
async def _wait_for_next_block(self, tip_at_close: int) -> tuple[int, str]:
async def _wait_for_next_block(
self, round_id: int, tip_at_close: int, waiting_since: datetime
) -> tuple[int, str]:
"""Waits for a block after tip_at_close and, before handing it back as the
draw's entropy source, requires it to be corroborated by the other
configured Electrum servers (B-28) — our own active connection is exactly
the thing a hostile server or a MITM would control, so its header alone is
not enough to seed a payout. A candidate that fails corroboration is never
used: this keeps waiting for a further block and tries corroborating that
one instead, logging why every time so a stuck draw is visible in
/admin's audit log rather than a silent, unexplained wait.
This wait has no timeout — it can't, since the draw's entropy genuinely
depends on a future block. B-36: what it lacked was *visibility*, so a
connection that stopped advancing the tip left the round silently frozen
in "drawing" with nothing in the logs or /admin to explain why. Progress
is now logged periodically, and past _DRAW_STALL_THRESHOLD_SECONDS a
draw_stalled audit entry is written (and re-written every threshold
interval for as long as the stall continues) so the wait shows up next
to the draw_header_corroboration_failed entries above.
"""
next_progress_log_at = waiting_since + timedelta(seconds=_DRAW_PROGRESS_LOG_INTERVAL_SECONDS)
next_stall_audit_at = waiting_since + timedelta(seconds=_DRAW_STALL_THRESHOLD_SECONDS)
while True:
while self._listener.tip_height <= tip_at_close or not self._listener.tip_header_hex:
now = datetime.now(timezone.utc)
if now >= next_progress_log_at:
logger.info(
"round %s: still waiting for a block past height %s (%.0fs since drawing started)",
round_id,
tip_at_close,
(now - waiting_since).total_seconds(),
)
next_progress_log_at = now + timedelta(seconds=_DRAW_PROGRESS_LOG_INTERVAL_SECONDS)
if now >= next_stall_audit_at:
async with self._session_factory() as session:
await write_audit_log(
session,
"draw_stalled",
{
"tip_at_close": tip_at_close,
"current_tip_height": self._listener.tip_height,
"elapsed_seconds": int((now - waiting_since).total_seconds()),
},
round_id=round_id,
)
await session.commit()
next_stall_audit_at = now + timedelta(seconds=_DRAW_STALL_THRESHOLD_SECONDS)
await asyncio.sleep(_TICK_INTERVAL_SECONDS)
return self._listener.tip_height, header_hex_to_block_hash(self._listener.tip_header_hex)
height = self._listener.tip_height
block_hash = header_hex_to_block_hash(self._listener.tip_header_hex)
if await self._listener.corroborate_header(height, block_hash):
return height, block_hash
logger.error(
"round %s: block %s header %s could not be corroborated by other Electrum servers; "
"waiting for a further block",
round_id,
height,
block_hash,
)
async with self._session_factory() as session:
await write_audit_log(
session,
"draw_header_corroboration_failed",
{"height": height, "reported_hash": block_hash},
round_id=round_id,
)
await session.commit()
tip_at_close = height
async def _retry_payout_if_due(self, round_id: int) -> None:
"""B-26: whether a "paying_out" round is due for another payout attempt.
Throttled by the most recent payout_failed audit entry for this round
(written by _log_payout_failure on every early return in _trigger_payout,
including ones that used to fail silently) rather than by any new DB state,
since a failed attempt doesn't necessarily leave a PendingTransaction behind
(a build failure like a missing fee_address never gets that far). No entry
yet means this round hasn't failed before — either it's a fresh "paying_out"
(the very first call already happened from _close_and_draw and hasn't had a
chance to fail yet) or the process restarted before ever recording one —
either way it's due immediately.
"""
async with self._session_factory() as session:
last_failure_at = await session.scalar(
select(AuditLog.created_at)
.where(AuditLog.event_type == "payout_failed", AuditLog.round_id == round_id)
.order_by(AuditLog.id.desc())
.limit(1)
)
if last_failure_at is not None:
last_failure_at = last_failure_at.replace(tzinfo=timezone.utc)
if datetime.now(timezone.utc) < last_failure_at + timedelta(seconds=_PAYOUT_RETRY_INTERVAL_SECONDS):
return # too soon — avoid hammering a persistently-broken payout
await self._trigger_payout(round_id)
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."""
"""Four phases, so no DB session is held across a network call (B-18): read
what's needed, build the tx, persist the intent, then broadcast.
The persist happens *before* the broadcast (B-25) — the same two-phase shape
as place_bet/request_withdrawal (B-08): a crash between building the payout
and recording it used to leave money on-chain with zero trace in the DB (no
payout_txid, no PendingTransaction), so a manual retry would have paid the
winner a second time. Now the worst case is a "building" PendingTransaction
the reconciler (app/tx/reconcile.py) can resolve either way by asking the
chain whether the tx exists, exactly like it already does for bets and
withdrawals.
"""
client = self._listener.client
if client is None:
logger.error("round %s payout deferred: not connected", round_id)
await self._log_payout_failure(round_id, None, "electrum client not connected")
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)
already_in_flight = await session.scalar(
select(PendingTransaction).where(
PendingTransaction.round_id == round_id,
PendingTransaction.kind == "payout",
PendingTransaction.status.in_(("building", "pending")),
)
)
if already_in_flight is not None:
# A payout for this round is already building or broadcast — this
# must not build a second one, or a retry (manual, or a future
# automatic one) would pay the winner twice. Confirmation/
# reconciliation already owns resolving that row.
logger.info(
"round %s payout already in flight (pending_transaction %s), skipping",
round_id,
already_in_flight.id,
)
return
reserved_outpoints = await _reserved_payout_outpoints(session)
config = await get_round_config(session)
fee_address = config.fee_address
fee_rate = config.fee_rate_sat_vb
@@ -184,21 +331,27 @@ class RoundScheduler:
logger.error(
"round %s payout blocked: no fee_address configured (set it via the admin endpoint)", round_id
)
await self._log_payout_failure(round_id, winner_user_id, "no fee_address configured")
return
if winner_address is None:
logger.error("round %s payout blocked: winner user %s not found", round_id, winner_user_id)
await self._log_payout_failure(round_id, winner_user_id, "winner user not found")
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 ----------------------------------------
# --- Phase 2: build (network read only, no DB write yet) -----------------
try:
pool_key = derive_pool_key()
pool_script_obj = script.p2wpkh(pool_key.to_public())
pool_address = pool_script_obj.address(network=PLM_MAINNET)
entries = await client.listunspent(address_to_scripthash(pool_address))
utxos = [Utxo(e["tx_hash"], e["tx_pos"], e["value"]) for e in entries if e["height"] > 0]
utxos = [
Utxo(e["tx_hash"], e["tx_pos"], e["value"])
for e in entries
if e["height"] > 0 and (e["tx_hash"], e["tx_pos"]) not in reserved_outpoints
]
built = build_payout_transaction(
signing_key=pool_key,
@@ -211,36 +364,58 @@ class RoundScheduler:
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)
except InsufficientFundsError as exc:
# Includes the B-48 "too_many_inputs" case: the pool holds enough, but spread
# over more UTXOs than one transaction may spend, so /admin has to say which.
reason = "insufficient pool UTXOs" if exc.code == "insufficient_balance" else exc.code
logger.exception("round %s payout failed: %s", round_id, reason)
await self._log_payout_failure(round_id, winner_user_id, reason)
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)
# Anything else — a malformed fee_address (EmbitError) or similar. 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). _retry_payout_if_due (B-26) is what turns this recorded
# failure into an automatic retry instead of a dead end.
logger.exception("round %s payout build failed", round_id)
await self._log_payout_failure(round_id, winner_user_id, "payout build failed")
return
# --- Phase 3: persist -----------------------------------------------------
# --- Phase 3: persist the intent, *then* broadcast (B-25) -----------------
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
session.add(
PendingTransaction(
pending = PendingTransaction(
kind="payout",
round_id=round_id,
current_txid=built.txid,
fee_rate_sat_vb=fee_rate,
raw_tx_hex=built.raw_hex,
status="pending",
)
# "building" until the broadcast succeeds, exactly like place_bet's
# two phases — see the reconciler, which gives this a short grace
# period before asking the chain whether it made it out after all.
status="building",
)
session.add(pending)
await session.commit()
pending_id = pending.id
# --- Phase 4: broadcast, then promote the pending row --------------------
try:
await client.broadcast(built.raw_hex)
except Exception:
# The row stays "building": the reconciler will ask the chain about it
# and, finding nothing, abandon it and clear payout_txid (B-25) — instead
# of the round being stuck with a payout_txid that never went anywhere.
logger.exception("round %s payout broadcast failed", round_id)
await self._log_payout_failure(round_id, winner_user_id, "broadcast rejected")
return
async with self._session_factory() as session:
pending = await session.get(PendingTransaction, pending_id)
pending.status = "pending"
await write_audit_log(
session,
"payout_sent",
@@ -252,18 +427,44 @@ class RoundScheduler:
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:
async def _log_payout_failure(self, round_id: int, winner_user_id: int | None, reason: str) -> 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."""
"paying_out" — the logs alone don't show up in /admin. Called from every
early return in _trigger_payout (B-26), not just the generic exception
branch as before, so _retry_payout_if_due always has an entry to throttle
against and /admin always shows *why* a round is stuck rather than just
that it is."""
try:
async with self._session_factory() as session:
await write_audit_log(
session,
"payout_failed",
{"round_id": round_id},
{"round_id": round_id, "reason": reason},
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)
async def _reserved_payout_outpoints(session: AsyncSession) -> set[tuple[str, int]]:
"""Pool UTXOs already claimed by a payout that hasn't resolved yet — this
round's own in-flight payout (guarded against separately in _trigger_payout) or
a stale one from an earlier round the reconciler hasn't abandoned yet (B-25).
These must be excluded from selection, or a retry would double-spend the same
coins into two payouts before the reconciler gets a chance to release them."""
rows = (
await session.scalars(
select(PendingTransaction).where(
PendingTransaction.kind == "payout",
PendingTransaction.status.in_(("building", "pending")),
)
)
).all()
reserved: set[tuple[str, int]] = set()
for row in rows:
tx = Transaction.parse(bytes.fromhex(row.raw_tx_hex))
for vin in tx.vin:
reserved.add((vin.txid.hex(), vin.vout))
return reserved
app/static/app.js
+6 -1
View File
@@ -749,10 +749,15 @@ async function changePassword() {
await withLoading(btn, t('loading.updating'), async () => {
try {
await call('POST', '/users/me/change-password', {
const data = await call('POST', '/users/me/change-password', {
current_password: currentPassword,
new_password: newPassword,
});
// The server just invalidated every previously issued token (B-34) —
// including the one this very request was authenticated with — and
// handed back a fresh one so this tab doesn't get logged out too.
token = data.access_token;
localStorage.setItem('plm_token', token);
document.getElementById('settings-current-password').value = '';
document.getElementById('settings-new-password').value = '';
document.getElementById('settings-new-password-confirm').value = '';
app/static/i18n.js
+21
View File
@@ -121,6 +121,7 @@ const TRANSLATIONS = {
'error.round_closing': 'The current round is closing, please try again shortly.',
'error.already_betting': 'You already have an active bet in the current round.',
'error.insufficient_balance': 'Insufficient balance.',
'error.balance_pending_confirmation': 'You have {pending_plm} PLM pending confirmation — it is not spendable yet.',
'error.amount_below_network_fee': 'The amount is too small to cover the network fee.',
'error.invalid_address': 'Not a valid PLM address (it must start with plm1q…).',
'error.amount_below_minimum': 'The minimum withdrawal amount is {minimum_plm} PLM.',
@@ -134,9 +135,11 @@ const TRANSLATIONS = {
'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.too_many_inputs': 'Your balance is split across too many small deposits to be spent in a single transaction (max {max_inputs}). Please contact support to consolidate it.',
'error.withdrawal_to_own_address': 'That is your own deposit address — withdraw to an external wallet.',
'error.internal_error': 'Unexpected server error. Please try again shortly.',
'error.guide_unavailable': 'The guide is not available right now.',
'error.rate_limited': 'Too many attempts, please try again in {retry_after_seconds} seconds.',
'loading.creating': 'Creating…',
'loading.loggingIn': 'Logging in…',
@@ -258,6 +261,7 @@ const TRANSLATIONS = {
'error.round_closing': 'Il round corrente si sta chiudendo, riprova tra poco.',
'error.already_betting': 'Hai già una bet attiva nel round corrente.',
'error.insufficient_balance': 'Saldo insufficiente.',
'error.balance_pending_confirmation': 'Hai {pending_plm} PLM in attesa di conferma — non ancora disponibili per la spesa.',
'error.amount_below_network_fee': "L'importo è troppo basso per coprire la fee di rete.",
'error.invalid_address': 'Indirizzo PLM non valido (deve iniziare con plm1q…).',
'error.amount_below_minimum': "L'importo minimo di prelievo è {minimum_plm} PLM.",
@@ -271,9 +275,11 @@ const TRANSLATIONS = {
'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.too_many_inputs': 'Il tuo saldo è suddiviso in troppi piccoli depositi per essere speso in una sola transazione (max {max_inputs}). Contatta l\'assistenza per consolidarlo.',
'error.withdrawal_to_own_address': 'Questo è il tuo indirizzo di deposito — preleva verso un wallet esterno.',
'error.internal_error': 'Errore inatteso del server. Riprova tra poco.',
'error.guide_unavailable': 'La guida non è disponibile in questo momento.',
'error.rate_limited': 'Troppi tentativi, riprova tra {retry_after_seconds} secondi.',
'loading.creating': 'Creazione…',
'loading.loggingIn': 'Accesso…',
@@ -395,6 +401,7 @@ const TRANSLATIONS = {
'error.round_closing': 'La ronda actual se está cerrando, inténtalo de nuevo en un momento.',
'error.already_betting': 'Ya tienes una apuesta activa en la ronda actual.',
'error.insufficient_balance': 'Saldo insuficiente.',
'error.balance_pending_confirmation': 'Tienes {pending_plm} PLM pendientes de confirmación — todavía no se pueden gastar.',
'error.amount_below_network_fee': 'El importe es demasiado pequeño para cubrir la comisión de red.',
'error.invalid_address': 'Dirección PLM no válida (debe empezar por plm1q…).',
'error.amount_below_minimum': 'El importe mínimo de retiro es {minimum_plm} PLM.',
@@ -408,9 +415,11 @@ const TRANSLATIONS = {
'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.too_many_inputs': 'Tu saldo está repartido en demasiados depósitos pequeños para gastarse en una sola transacción (máx. {max_inputs}). Contacta con soporte para consolidarlo.',
'error.withdrawal_to_own_address': 'Esa es tu propia dirección de depósito — retira a una cartera externa.',
'error.internal_error': 'Error inesperado del servidor. Inténtalo de nuevo en un momento.',
'error.guide_unavailable': 'La guía no está disponible en este momento.',
'error.rate_limited': 'Demasiados intentos, inténtalo de nuevo en {retry_after_seconds} segundos.',
'loading.creating': 'Creando…',
'loading.loggingIn': 'Entrando…',
@@ -532,6 +541,7 @@ const TRANSLATIONS = {
'error.round_closing': 'Le round en cours est en train de se fermer, réessayez dans un instant.',
'error.already_betting': 'Vous avez déjà une mise active dans le round en cours.',
'error.insufficient_balance': 'Solde insuffisant.',
'error.balance_pending_confirmation': 'Vous avez {pending_plm} PLM en attente de confirmation — pas encore disponibles.',
'error.amount_below_network_fee': 'Le montant est trop faible pour couvrir les frais de réseau.',
'error.invalid_address': 'Adresse PLM invalide (elle doit commencer par plm1q…).',
'error.amount_below_minimum': 'Le montant minimum de retrait est de {minimum_plm} PLM.',
@@ -545,9 +555,11 @@ const TRANSLATIONS = {
'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.too_many_inputs': 'Votre solde est réparti sur trop de petits dépôts pour être dépensé en une seule transaction (max {max_inputs}). Contactez le support pour le consolider.',
'error.withdrawal_to_own_address': "C'est votre propre adresse de dépôt — retirez vers un portefeuille externe.",
'error.internal_error': 'Erreur inattendue du serveur. Veuillez réessayer dans un instant.',
'error.guide_unavailable': "Le guide n'est pas disponible pour le moment.",
'error.rate_limited': 'Trop de tentatives, réessayez dans {retry_after_seconds} secondes.',
'loading.creating': 'Création…',
'loading.loggingIn': 'Connexion…',
@@ -669,6 +681,7 @@ const TRANSLATIONS = {
'error.round_closing': 'Die laufende Runde wird gerade geschlossen, bitte versuche es gleich erneut.',
'error.already_betting': 'Du hast bereits eine aktive Wette in der laufenden Runde.',
'error.insufficient_balance': 'Nicht genügend Guthaben.',
'error.balance_pending_confirmation': 'Sie haben {pending_plm} PLM, die noch auf Bestätigung warten — noch nicht verfügbar.',
'error.amount_below_network_fee': 'Der Betrag ist zu klein, um die Netzwerkgebühr zu decken.',
'error.invalid_address': 'Keine gültige PLM-Adresse (sie muss mit plm1q… beginnen).',
'error.amount_below_minimum': 'Der Mindestauszahlungsbetrag beträgt {minimum_plm} PLM.',
@@ -682,9 +695,11 @@ const TRANSLATIONS = {
'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.too_many_inputs': 'Ihr Guthaben ist auf zu viele kleine Einzahlungen verteilt, um in einer einzigen Transaktion ausgegeben zu werden (max. {max_inputs}). Bitte wenden Sie sich an den Support, um es zusammenzufassen.',
'error.withdrawal_to_own_address': 'Das ist deine eigene Einzahlungsadresse — zahle auf eine externe Wallet aus.',
'error.internal_error': 'Unerwarteter Serverfehler. Bitte versuche es in Kürze erneut.',
'error.guide_unavailable': 'Die Anleitung ist derzeit nicht verfügbar.',
'error.rate_limited': 'Zu viele Versuche, bitte versuche es in {retry_after_seconds} Sekunden erneut.',
'loading.creating': 'Wird erstellt…',
'loading.loggingIn': 'Anmeldung…',
@@ -806,6 +821,7 @@ const TRANSLATIONS = {
'error.round_closing': 'Текущий раунд закрывается, повторите попытку чуть позже.',
'error.already_betting': 'У вас уже есть активная ставка в текущем раунде.',
'error.insufficient_balance': 'Недостаточно средств.',
'error.balance_pending_confirmation': 'У вас есть {pending_plm} PLM, ожидающих подтверждения — они пока недоступны для расходования.',
'error.amount_below_network_fee': 'Сумма слишком мала, чтобы покрыть комиссию сети.',
'error.invalid_address': 'Некорректный адрес PLM (он должен начинаться с plm1q…).',
'error.amount_below_minimum': 'Минимальная сумма вывода — {minimum_plm} PLM.',
@@ -819,9 +835,11 @@ const TRANSLATIONS = {
'error.invalid_amount': 'Введите сумму больше нуля.',
'error.broadcast_failed': 'Сеть отклонила транзакцию. Попробуйте ещё раз через минуту.',
'error.amount_below_dust_limit': 'Сумма слишком мала для отправки.',
'error.too_many_inputs': 'Ваш баланс разбит на слишком много мелких депозитов, чтобы потратить его одной транзакцией (максимум {max_inputs}). Обратитесь в поддержку для консолидации.',
'error.withdrawal_to_own_address': 'Это ваш собственный адрес для депозита — выводите на внешний кошелёк.',
'error.internal_error': 'Непредвиденная ошибка сервера. Попробуйте ещё раз через минуту.',
'error.guide_unavailable': 'Руководство сейчас недоступно.',
'error.rate_limited': 'Слишком много попыток, повторите через {retry_after_seconds} сек.',
'loading.creating': 'Создание…',
'loading.loggingIn': 'Вход…',
@@ -943,6 +961,7 @@ const TRANSLATIONS = {
'error.round_closing': '当前回合正在结束，请稍后重试。',
'error.already_betting': '你在当前回合已有一笔有效下注。',
'error.insufficient_balance': '余额不足。',
'error.balance_pending_confirmation': '您有 {pending_plm} PLM 待确认 —— 尚不可用于支出。',
'error.amount_below_network_fee': '金额太小，不足以支付网络手续费。',
'error.invalid_address': 'PLM 地址无效（必须以 plm1q… 开头）。',
'error.amount_below_minimum': '最低提现金额为 {minimum_plm} PLM。',
@@ -956,9 +975,11 @@ const TRANSLATIONS = {
'error.invalid_amount': '请输入大于零的金额。',
'error.broadcast_failed': '网络拒绝了该交易，请稍后重试。',
'error.amount_below_dust_limit': '金额过小，无法发送。',
'error.too_many_inputs': '您的余额分散在过多的小额存款中，无法在一笔交易中花费（最多 {max_inputs} 笔）。请联系客服进行归集。',
'error.withdrawal_to_own_address': '这是你自己的充值地址 — 请提现到外部钱包。',
'error.internal_error': '服务器发生意外错误，请稍后重试。',
'error.guide_unavailable': '指南当前不可用。',
'error.rate_limited': '尝试次数过多，请在 {retry_after_seconds} 秒后重试。',
'loading.creating': '正在创建…',
'loading.loggingIn': '正在登录…',
app/tx/broadcast.py
+104 -37
View File
@@ -14,12 +14,18 @@ from app.electrum.client import ElectrumClient
from app.rounds.config import get_round_config
from app.wallet.hd import derive_pool_key, derive_user_key
from app.wallet.plm_network import PLM_MAINNET
from app.wallet.psbt_builder import RBF_SEQUENCE, estimate_vsize
from app.wallet.psbt_builder import MAX_FEE_RATE_SAT_VB, RBF_SEQUENCE, estimate_vsize
logger = logging.getLogger(__name__)
_POLL_INTERVAL_SECONDS = 30
_FEE_RATE_INCREMENT = 1 # minimum relay-policy-friendly bump per BIP125
_FEE_RATE_INCREMENT = 1 # how much pending.fee_rate_sat_vb's *target* rises by per bump
# BIP125 rule 4: a replacement transaction must pay at least this much more, in
# total, per vbyte of its own size, than the transaction it replaces — Bitcoin
# Core's default incremental relay fee. bump_fee's delta must never fall below
# this regardless of what the target-rate arithmetic comes out to (B-32).
_INCREMENTAL_RELAY_FEE_RATE_SAT_VB = 1
class RbfError(Exception):
@@ -27,22 +33,29 @@ class RbfError(Exception):
def should_bump(pending: PendingTransaction, now: datetime, timeout_seconds: int) -> bool:
"""Pure decision: has this pending tx been unconfirmed for longer than the
configured timeout (RoundConfig.rbf_timeout_seconds)? Kept separate from the
I/O-heavy bump_fee() so it's trivially unit-testable."""
"""Pure decision: has this pending tx gone unconfirmed for longer than the
configured timeout (RoundConfig.rbf_timeout_seconds) *since it was last
broadcast*? Kept separate from the I/O-heavy bump_fee() so it's trivially
unit-testable.
Deliberately measured from last_broadcast_at, not broadcast_at: this decides
whether *another* bump is due, which should reset after every bump (a tx just
rebroadcast at a higher fee deserves the same grace period again) — unlike
reconcile.py's abandon check, which must measure from the *first* broadcast so
repeated bumping can't indefinitely postpone ever giving up on a tx (B-27)."""
if pending.status != "pending":
return False
return now >= pending.broadcast_at.replace(tzinfo=timezone.utc) + timedelta(seconds=timeout_seconds)
return now >= pending.last_broadcast_at.replace(tzinfo=timezone.utc) + timedelta(seconds=timeout_seconds)
async def _signing_context(session: AsyncSession, pending: PendingTransaction) -> tuple:
async def _signing_context(session: AsyncSession, kind: str, user_id: int | None) -> tuple:
"""Returns (signing_key, own_script, own_address) for the single sender that
controls every input of this tx — a user for bet/withdrawal, the pool for
payout. All our builders only ever spend one address's UTXOs per tx."""
if pending.kind == "payout":
if kind == "payout":
key = derive_pool_key()
else:
user = await session.get(User, pending.user_id)
user = await session.get(User, user_id)
key = derive_user_key(user.derivation_index)
own_script = script.p2wpkh(key.to_public())
own_address = own_script.address(network=PLM_MAINNET)
@@ -50,10 +63,19 @@ async def _signing_context(session: AsyncSession, pending: PendingTransaction) -
async def _prevout_amount(client: ElectrumClient, vin: TransactionInput) -> int:
"""The exact integer satoshi value of the output this input spends.
Parsed directly from the raw transaction via embit rather than asking the
server for its own float, whole-coin-denominated "value" field (verbose=True)
and converting with `* 100_000_000` — embit's TransactionOutput.value is
already an integer number of satoshis straight from the tx's binary
encoding, so this never touches floating point in a codebase that is
otherwise strictly integer-satoshi (B-40).
"""
txid_hex = vin.txid.hex()
tx = await client.get_transaction(txid_hex, verbose=True)
value_coins = tx["vout"][vin.vout]["value"]
return round(value_coins * 100_000_000)
raw_hex = await client.get_transaction(txid_hex, verbose=False)
prevout_tx = Transaction.parse(bytes.fromhex(raw_hex))
return prevout_tx.vout[vin.vout].value
def _find_change_output(tx: Transaction, change_address: str) -> int | None:
@@ -63,33 +85,71 @@ def _find_change_output(tx: Transaction, change_address: str) -> int | None:
return None
async def bump_fee(session: AsyncSession, client: ElectrumClient, pending: PendingTransaction) -> str:
"""Rebuild `pending`'s transaction with a higher fee (same inputs, same
recipient outputs, the extra fee taken from the change output) and
rebroadcast. Returns the new txid.
async def bump_fee(
session_factory: async_sessionmaker, client: ElectrumClient, pending_id: int
) -> str | None:
"""Rebuild pending_transaction `pending_id`'s transaction with a higher fee
(same inputs, same recipient outputs, the extra fee taken from the change
output) and rebroadcast. Returns the new txid, or None if there was nothing
to do (the row is gone or already left "pending" — a normal race with
confirmation, not an error).
Three phases, so no DB session is held across the network calls this needs
(one get_transaction per input, then a broadcast) — the same shape used
elsewhere for exactly this reason (B-18, rounds/scheduler.py:_trigger_payout;
B-31, electrum/listener.py:refresh_user) and now here too (B-40): read what's
needed and close the session, do the chain work, then reopen to persist.
Only handles the common case: exactly one change output paying back to the
tx's own sender address, large enough to absorb the increase. If there's no
such output (e.g. an exact-amount bet with no change), this raises RbfError —
bumping such a tx would require selecting additional inputs, which isn't
implemented for the MVP; it needs manual operator intervention.
implemented for the MVP; it needs manual operator intervention. Also raises
RbfError, rather than bumping, once the row is already at MAX_FEE_RATE_SAT_VB
(B-32) — the reconciler abandons it if it never confirms (B-27), instead of
this retrying an ever-higher fee forever.
"""
old_tx = Transaction.parse(bytes.fromhex(pending.raw_tx_hex))
signing_key, own_script, own_address = await _signing_context(session, pending)
# --- Phase 1: read what's needed, close the session before any network call ---
async with session_factory() as session:
pending = await session.get(PendingTransaction, pending_id)
if pending is None or pending.status != "pending":
logger.info("pending_transaction %s no longer pending; skipping bump", pending_id)
return None
if pending.fee_rate_sat_vb >= MAX_FEE_RATE_SAT_VB:
raise RbfError(
f"pending_transaction {pending_id}: already at the maximum fee rate "
f"({MAX_FEE_RATE_SAT_VB} sat/vB) — refusing to bump further"
)
kind = pending.kind
current_fee_rate = pending.fee_rate_sat_vb
raw_tx_hex = pending.raw_tx_hex
signing_key, own_script, own_address = await _signing_context(session, kind, pending.user_id)
# --- Phase 2: chain reads, signing, and the broadcast — no DB session open ----
old_tx = Transaction.parse(bytes.fromhex(raw_tx_hex))
input_amounts = [await _prevout_amount(client, vin) for vin in old_tx.vin]
total_in = sum(input_amounts)
old_fee = total_in - sum(o.value for o in old_tx.vout)
vsize = estimate_vsize(len(old_tx.vin), len(old_tx.vout))
new_fee_rate = pending.fee_rate_sat_vb + _FEE_RATE_INCREMENT
new_fee = estimate_vsize(len(old_tx.vin), len(old_tx.vout)) * new_fee_rate
fee_delta = new_fee - old_fee
if fee_delta <= 0:
fee_delta = _FEE_RATE_INCREMENT # already above the new target vsize*rate; bump by a token amount
target_fee_rate = min(current_fee_rate + _FEE_RATE_INCREMENT, MAX_FEE_RATE_SAT_VB)
target_fee = vsize * target_fee_rate
# BIP125 rule 4's minimum, in absolute sats for this tx's size — the floor
# `fee_delta` must never go below, no matter what `target_fee - old_fee` comes
# out to. That naive difference used to go to zero or negative whenever
# old_fee already exceeded target_fee (e.g. a dust change amount folded into
# the original fee — wallet/psbt_builder.py's DUST_LIMIT_SATS handling), and
# the previous fallback — a flat 1-satoshi total bump — was nowhere near this
# relay-mandated minimum, so the node rejected it every time. Because bump_fee
# raised before touching `pending`, the next tick retried with identical
# parameters every 30 seconds, forever (B-32).
min_valid_delta = vsize * _INCREMENTAL_RELAY_FEE_RATE_SAT_VB
fee_delta = max(target_fee - old_fee, min_valid_delta)
change_index = _find_change_output(old_tx, own_address)
if change_index is None or old_tx.vout[change_index].value <= fee_delta:
raise RbfError(f"pending_transaction {pending.id}: no change output large enough to absorb a fee bump")
raise RbfError(f"pending_transaction {pending_id}: no change output large enough to absorb a fee bump")
new_vout = list(old_tx.vout)
bumped_change = new_vout[change_index].value - fee_delta
@@ -113,17 +173,28 @@ async def bump_fee(session: AsyncSession, client: ElectrumClient, pending: Pendi
new_txid = final_tx.txid().hex()
await client.broadcast(raw_hex)
# --- Phase 3: persist the outcome ----------------------------------------------
async with session_factory() as session:
pending = await session.get(PendingTransaction, pending_id)
old_txid = pending.current_txid
pending.replaced_by_txid = old_txid # points backwards: what current_txid replaced
pending.current_txid = new_txid
pending.raw_tx_hex = raw_hex
pending.fee_rate_sat_vb = new_fee_rate
# The *actual* resulting rate, not target_fee_rate: when the BIP125-minimum
# floor above raised fee_delta past the naive target, the tx now pays more
# than target_fee_rate implied. Recording the true rate keeps the next bump's
# arithmetic honest instead of drifting from what's really being paid.
pending.fee_rate_sat_vb = (old_fee + fee_delta) // vsize
pending.attempt_count += 1
pending.broadcast_at = datetime.now(timezone.utc)
# last_broadcast_at, not broadcast_at (B-27): broadcast_at must stay the *first*
# broadcast, since reconcile.py's abandon-after-N-hours grace period is measured
# from it — overwriting it here used to reset that clock on every bump, so a
# repeatedly-bumped-but-never-mined tx was never abandoned.
pending.last_broadcast_at = datetime.now(timezone.utc)
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, old_txid, new_txid)
logger.info("bumped %s pending_transaction %s: %s -> %s", kind, pending_id, old_txid, new_txid)
return new_txid
@@ -191,16 +262,12 @@ class RbfBumper:
candidates = (
await session.scalars(select(PendingTransaction).where(PendingTransaction.status == "pending"))
).all()
due = [p for p in candidates if should_bump(p, now, timeout_seconds=timeout_seconds)]
due_ids = [p.id for p in candidates if should_bump(p, now, timeout_seconds=timeout_seconds)]
for pending in due:
async with self._session_factory() as session:
row = await session.get(PendingTransaction, pending.id)
if row is None or row.status != "pending":
continue
for pending_id in due_ids:
try:
await bump_fee(session, client, row)
await bump_fee(self._session_factory, client, pending_id)
except RbfError:
logger.exception("could not bump pending_transaction %s", row.id)
logger.exception("could not bump pending_transaction %s", pending_id)
except Exception:
logger.exception("unexpected error bumping pending_transaction %s", row.id)
logger.exception("unexpected error bumping pending_transaction %s", pending_id)
app/tx/confirmation.py
+40 -10
View File
@@ -7,7 +7,9 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from app.db.models import PendingTransaction
from app.electrum.client import ElectrumClient
from app.electrum.scripthash import address_to_scripthash
from app.rounds.events import broadcaster
from app.tx.pending_address import own_address_for
logger = logging.getLogger(__name__)
@@ -31,24 +33,52 @@ async def poll_once(session_factory: async_sessionmaker, client: ElectrumClient)
candidates = (
await session.execute(
select(
PendingTransaction.id, PendingTransaction.current_txid, PendingTransaction.kind
PendingTransaction.id,
PendingTransaction.current_txid,
PendingTransaction.kind,
PendingTransaction.user_id,
).where(PendingTransaction.status == "pending")
)
).all()
confirmed = 0
for pending_id, txid, kind in candidates:
# Resolved once per candidate while the session is still open, and cached
# by scripthash below — every "payout" row shares the same pool address,
# so this also avoids asking the server the same history twice per tick.
scripthash_by_id: dict[int, str] = {}
for pending_id, _txid, kind, user_id in candidates:
try:
tx = await client.get_transaction(txid, verbose=True)
address = await own_address_for(session, kind, user_id)
scripthash_by_id[pending_id] = address_to_scripthash(address)
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)
logger.exception("could not derive the address for pending_transaction %s", pending_id)
confirmed = 0
history_cache: dict[str, list[dict]] = {}
for pending_id, txid, kind, _user_id in candidates:
scripthash = scripthash_by_id.get(pending_id)
if scripthash is None:
continue # address derivation failed above; already logged
try:
if scripthash not in history_cache:
history_cache[scripthash] = await client.get_history(scripthash)
except Exception:
# One unresolvable scripthash must not stop the others: a tx the server
# no longer knows about (dropped from the mempool, replaced) used to
# abort the whole pass via a verbose blockchain.transaction.get call
# that some servers reject outright (B-41), 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 fetch history for pending_transaction %s (txid %s)", pending_id, txid, exc_info=True)
continue
if not tx or tx.get("confirmations", 0) < 1:
entry = next((e for e in history_cache[scripthash] if e.get("tx_hash") == txid), None)
# height > 0 means confirmed at that height; 0 or absent means still in
# the mempool (or the server doesn't know this txid at all yet) — either
# way, not confirmed, so keep waiting.
if entry is None or entry.get("height", 0) <= 0:
continue
async with session_factory() as session:
row = await session.get(PendingTransaction, pending_id)
if row is None or row.status != "pending":
app/tx/pending_address.py
+22
View File
@@ -0,0 +1,22 @@
from sqlalchemy.ext.asyncio import AsyncSession
from app.db.models import User
from app.wallet.hd import derive_pool_address, derive_user_address
async def own_address_for(session: AsyncSession, kind: str, user_id: int | None) -> str:
"""The address that owns every input of a PendingTransaction of this kind —
a user's own address for a bet/withdrawal, the pool address for a payout.
All our builders only ever spend one address's UTXOs per tx (see
tx/broadcast.py:_signing_context, which derives the same address alongside
the signing key it also needs).
Shared by tx/confirmation.py and tx/reconcile.py (B-41): both now check
blockchain.scripthash.get_history for this address instead of asking
blockchain.transaction.get for a verbose reply, so the two can't derive
different addresses for the same row.
"""
if kind == "payout":
return derive_pool_address()
user = await session.get(User, user_id)
return derive_user_address(user.derivation_index)
app/tx/reconcile.py
+38 -22
View File
@@ -36,7 +36,9 @@ 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.electrum.scripthash import address_to_scripthash
from app.rounds.events import broadcaster
from app.tx.pending_address import own_address_for
from app.wallet.balance import recompute_balance
logger = logging.getLogger(__name__)
@@ -72,22 +74,21 @@ class PendingTransactionReconciler:
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)."""
"""Returns how many rows were resolved (promoted or abandoned).
Existence is decided by checking whether a row's own address's history
(blockchain.scripthash.get_history) includes its txid at all — mempool or
mined — rather than asking blockchain.transaction.get for a verbose reply
(B-41): several Electrum server implementations and versions reject the
verbose flag outright, and the previous substring-matching on the error
text (looking for "missing", "not found", ...) was fragile as the basis for
a decision that releases funds. A transport failure fetching history still
raises and leaves the row alone until next time — get_history not
returning our txid is the only thing that means "gone". History is cached
per scripthash within one pass, since every "payout" row shares the same
pool address.
"""
now = datetime.now(timezone.utc)
async with session_factory() as session:
rows = (
@@ -95,16 +96,25 @@ async def reconcile_once(session_factory: async_sessionmaker, client: ElectrumCl
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)
]
candidates = []
for row in rows:
if not _is_due(row, now):
continue
try:
address = await own_address_for(session, row.kind, row.user_id)
scripthash = address_to_scripthash(address)
except Exception:
logger.exception("could not derive the address for pending_transaction %s", row.id)
continue
candidates.append((row.id, row.status, row.current_txid, scripthash))
resolved = 0
for row_id, status, txid in candidates:
history_cache: dict[str, list[dict]] = {}
for row_id, status, txid, scripthash in candidates:
try:
exists = await _tx_exists_on_chain(client, txid)
if scripthash not in history_cache:
history_cache[scripthash] = await client.get_history(scripthash)
exists = any(entry.get("tx_hash") == txid for entry in history_cache[scripthash])
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.
@@ -129,6 +139,12 @@ async def reconcile_once(session_factory: async_sessionmaker, client: ElectrumCl
def _is_due(row: PendingTransaction, now: datetime) -> bool:
# Deliberately broadcast_at (the *first* broadcast), not last_broadcast_at: an
# RBF bump used to overwrite this same field, which reset this grace period on
# every bump and meant a repeatedly-bumped-but-never-mined tx was never
# abandoned (B-27). tx/broadcast.py:bump_fee now only ever touches
# last_broadcast_at, so this keeps measuring from when the tx first appeared,
# no matter how many times it's since been bumped.
grace = _BUILDING_GRACE_SECONDS if row.status == "building" else _ABANDON_AFTER_SECONDS
return now >= row.broadcast_at.replace(tzinfo=timezone.utc) + timedelta(seconds=grace)
app/wallet/psbt_builder.py
+37 -3
View File
@@ -25,15 +25,38 @@ RBF_SEQUENCE = 0xFFFFFFFD
# withdrawal fail at broadcast with an opaque error (B-06).
DUST_LIMIT_SATS = 294
# Sanity ceiling on any transaction's fee rate — shared by RoundConfig.fee_rate_sat_vb's
# admin-facing bound (app/api/routes/admin.py, so the two can't drift apart, the same
# reason MIN_PASSWORD_LENGTH is shared in auth/security.py) and tx/broadcast.py's RBF
# bump escalation, which refuses to bump a pending_transaction past this rate (B-32) —
# without a ceiling, a stuck transaction's fee climbed by 1 sat/vB every bump forever,
# eating further and further into the sender's change with no limit.
MAX_FEE_RATE_SAT_VB = 10_000
# Ceiling on how many UTXOs one transaction may spend (B-48). Every extra input costs
# ~68 vbytes of fee, and that fee comes out of the amount being moved — so an address
# fragmented into hundreds of small deposits would silently erode its own bet (shrinking
# the user's share of the pool) or withdrawal, and past a few hundred inputs the tx also
# stops being standard and gets refused at broadcast. Failing the build with a
# translatable error is the honest outcome; consolidating the address is the way out.
MAX_TX_INPUTS = 50
class InsufficientFundsError(Exception):
"""`code` is the machine-readable identifier the API layer forwards to the
client so it can translate the failure (see app/api/errors.py); the message
itself stays English."""
itself stays English, and `params` carries the values it interpolates so the
translation can place them wherever its own grammar needs them."""
def __init__(self, message: str, code: str = "insufficient_balance") -> None:
def __init__(
self,
message: str,
code: str = "insufficient_balance",
**params: int | str,
) -> None:
super().__init__(message)
self.code = code
self.params = params
@dataclass
@@ -60,11 +83,22 @@ def estimate_vsize(n_inputs: int, n_outputs: int) -> int:
def select_utxos(utxos: list[Utxo], target_sats: int) -> tuple[list[Utxo], int]:
"""Greedily select UTXOs (largest first, to minimize input count) covering
target_sats — the amount deducted from the sender's balance. The fee is paid
out of target_sats (see build_signed_transaction), not added on top of it."""
out of target_sats (see build_signed_transaction), not added on top of it.
At most MAX_TX_INPUTS are ever selected (B-48): if the largest MAX_TX_INPUTS
UTXOs don't cover the target, the balance is there but too fragmented to spend
in one transaction, which is a different failure from having no funds at all
and gets its own code."""
ordered = sorted(utxos, key=lambda u: u.amount_sats, reverse=True)
selected: list[Utxo] = []
total = 0
for utxo in ordered:
if len(selected) == MAX_TX_INPUTS:
raise InsufficientFundsError(
f"balance too fragmented: more than {MAX_TX_INPUTS} inputs would be needed",
code="too_many_inputs",
max_inputs=MAX_TX_INPUTS,
)
selected.append(utxo)
total += utxo.amount_sats
if total >= target_sats:
app/withdrawals/service.py
+19 -3
View File
@@ -9,7 +9,7 @@ from app.electrum.client import ElectrumClient
from app.rounds.config import get_round_config
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.balance import compute_pending_balance, recompute_balance
from app.wallet.hd import derive_user_key
from app.wallet.psbt_builder import (
BuiltTransaction,
@@ -56,7 +56,22 @@ async def request_withdrawal(
select(UtxoEvent).where(UtxoEvent.user_id == user.id, UtxoEvent.spent_txid.is_(None))
)
).all()
if sum(u.amount_sats for u in unspent) < amount_sats:
confirmed_sats = sum(u.amount_sats for u in unspent)
if confirmed_sats < amount_sats:
# B-37: cached_balance_sats (== confirmed_sats here) can understate the real
# balance by a whole unconfirmed change output right after a bet/withdrawal —
# the UI shows pending_balance_sats instead (compute_pending_balance), which
# can cover an amount this check would otherwise reject as flatly
# "insufficient". Distinguish "you don't have the money" from "your money
# hasn't confirmed yet" so the error doesn't contradict what the user is
# looking at on screen.
pending_inclusive_sats, has_pending = await compute_pending_balance(session, user)
if has_pending and pending_inclusive_sats >= amount_sats:
raise WithdrawalError(
"balance_pending_confirmation",
"the requested amount is covered by your pending balance, which has not confirmed yet",
pending_sats=pending_inclusive_sats - confirmed_sats,
)
raise WithdrawalError("insufficient_balance", "insufficient balance", required_sats=amount_sats)
user_key = derive_user_key(user.derivation_index)
@@ -74,7 +89,7 @@ async def request_withdrawal(
fee_rate_sat_vb=config.fee_rate_sat_vb,
)
except InsufficientFundsError as exc:
raise WithdrawalError(exc.code, str(exc)) from exc
raise WithdrawalError(exc.code, str(exc), **exc.params) from exc
# 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).
@@ -158,3 +173,4 @@ async def _release_failed_withdrawal(
user_id=user_id,
)
await session.commit()
broadcaster.publish() # the reserved UTXOs are spendable again — refetch the balance (B-49)
docs/guida-admin.md
+3 -2
View File
@@ -121,8 +121,9 @@ Eventi a cui vale la pena prestare attenzione:
## Alternative all'interfaccia grafica
Le stesse operazioni si possono fare da terminale o da Swagger UI
(`https://<host>/docs`, sezione `admin`), sempre passando `ADMIN_TOKEN`
nell'header `X-Admin-Token`:
(`https://<host>/docs`, sezione `admin` — disponibile solo se `ENABLE_API_DOCS=true`
è impostato in `.env`, disattivata di default perché espone l'intera API),
sempre passando `ADMIN_TOKEN` nell'header `X-Admin-Token`:
```bash
# leggere la configurazione
docs/running-the-server.md
+7 -17
View File
@@ -3,24 +3,14 @@
Presuppone che [setup.md](setup.md) sia già stato completato (`.env` pronto,
master key generata, migrazioni applicate).
## Locale / venv (sviluppo rapido)
Il server gira sempre via Docker, in sviluppo e in produzione allo stesso
modo — non esiste un modo supportato per lanciare `uvicorn` direttamente.
Il venv locale (`.venv/`) serve solo per i test, per scrivere le migrazioni
Alembic e per gli script una tantum di generazione chiavi (vedi
[setup.md](setup.md) e la sezione "Commands" di
[CLAUDE.md](../CLAUDE.md#commands)).
```bash
source .venv/bin/activate
uvicorn app.main:app --reload --port 8123
```
- App su `http://127.0.0.1:8123/`
- Pannello admin su `http://127.0.0.1:8123/admin`
- Log applicativi in `logs/app.log` (rotante, 10MB × 5 backup)
- Nessun TLS, nessun reverse proxy — solo per test locali sulla tua macchina.
Per fermarlo: `Ctrl+C`, oppure se lanciato in background con `nohup`:
```bash
pkill -f "uvicorn app.main:app"
```
## Docker + Caddy (consigliato, anche per i test con dominio/TLS)
## Docker + Caddy (unico workflow supportato)
```bash
mkdir -p data/db data/keys data/logs # una tantum, se non già presenti
docs/setup.md
+5
View File
@@ -38,6 +38,11 @@ cp .env.example .env
Le altre chiavi di `.env` (`DATABASE_URL`, `ELECTRUM_HOST`/`PORT`/`USE_SSL`,
`MASTER_KEY_PATH`) hanno default sensati in `.env.example`.
`ENABLE_API_DOCS` (default `false`) controlla Swagger/ReDoc/l'OpenAPI JSON grezzo
su `/docs`, `/redoc` e `/openapi.json`: espongono l'intera superficie dell'API,
endpoint admin inclusi, quindi restano disattivati a meno di non impostarlo
esplicitamente a `true` — utile in locale, da evitare in produzione.
`ELECTRUM_FALLBACK_SERVERS` elenca i server di riserva, separati da virgola, nel
formato `host:porta` (TLS, il caso normale) oppure `host:porta:notls`. Esempio:
migrations/versions/861e76aaf34c_add_last_broadcast_at_to_pending_.py
+41
View File
@@ -0,0 +1,41 @@
"""add last_broadcast_at to pending_transactions
Fixes B-27: bump_fee used to overwrite broadcast_at on every RBF bump, but
tx/reconcile.py's abandon-after-N-hours grace period is measured from that same
column — so a transaction bumped repeatedly but never mined reset that clock on
every bump and was never abandoned. broadcast_at now stays the *first* broadcast
(what the reconciler measures from); last_broadcast_at is the new column bump_fee
updates and should_bump reads to decide whether another bump is due.
Backfilled from the existing broadcast_at (the best available approximation for
rows written before this column existed — for a row never bumped it's exact)
before the NOT NULL constraint is applied, so this is safe against any existing
data.
Revision ID: 861e76aaf34c
Revises: 8a1c4e7b2d90
Create Date: 2026-07-27
"""
from typing import Sequence, Union
from alembic import op
import sqlalchemy as sa
# revision identifiers, used by Alembic.
revision: str = '861e76aaf34c'
down_revision: Union[str, Sequence[str], None] = '8a1c4e7b2d90'
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None
def upgrade() -> None:
op.add_column('pending_transactions', sa.Column('last_broadcast_at', sa.DateTime(), nullable=True))
op.execute('UPDATE pending_transactions SET last_broadcast_at = broadcast_at')
with op.batch_alter_table('pending_transactions') as batch_op:
batch_op.alter_column('last_broadcast_at', nullable=False)
def downgrade() -> None:
op.drop_column('pending_transactions', 'last_broadcast_at')
migrations/versions/87a0c640355c_widen_raw_tx_hex_and_payload_json_to_.py
+38
View File
@@ -0,0 +1,38 @@
"""widen raw_tx_hex and payload_json to Text
Fixes B-47: both columns held arbitrary-length data (a raw signed transaction
hex, and a JSON audit payload) in an unbounded `String`, which SQLAlchemy
compiles to `VARCHAR` with no length. That's accepted by SQLite and
PostgreSQL but rejected by other backends (e.g. MySQL requires a length on
VARCHAR) — `Text` is the portable type for both.
Revision ID: 87a0c640355c
Revises: 9ef6a51509f7
Create Date: 2026-07-27
"""
from typing import Sequence, Union
from alembic import op
import sqlalchemy as sa
# revision identifiers, used by Alembic.
revision: str = '87a0c640355c'
down_revision: Union[str, Sequence[str], None] = '9ef6a51509f7'
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None
def upgrade() -> None:
with op.batch_alter_table('audit_log') as batch_op:
batch_op.alter_column('payload_json', existing_type=sa.VARCHAR(), type_=sa.Text(), existing_nullable=False)
with op.batch_alter_table('pending_transactions') as batch_op:
batch_op.alter_column('raw_tx_hex', existing_type=sa.VARCHAR(), type_=sa.Text(), existing_nullable=False)
def downgrade() -> None:
with op.batch_alter_table('pending_transactions') as batch_op:
batch_op.alter_column('raw_tx_hex', existing_type=sa.Text(), type_=sa.VARCHAR(), existing_nullable=False)
with op.batch_alter_table('audit_log') as batch_op:
batch_op.alter_column('payload_json', existing_type=sa.Text(), type_=sa.VARCHAR(), existing_nullable=False)
migrations/versions/943dbd74d983_add_token_version_to_users.py
+40
View File
@@ -0,0 +1,40 @@
"""add token_version to users
Revision ID: 943dbd74d983
Revises: 861e76aaf34c
Create Date: 2026-07-27
"""
from typing import Sequence, Union
from alembic import op
import sqlalchemy as sa
# revision identifiers, used by Alembic.
revision: str = '943dbd74d983'
down_revision: Union[str, Sequence[str], None] = '861e76aaf34c'
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None
def upgrade() -> None:
"""Upgrade schema."""
# server_default backfills every existing user to 0 (their current sessions
# stay valid, since 0 also matches what already-issued tokens carry
# implicitly — see the "sub"-only tokens issued before this migration);
# dropped right after so new rows go through the ORM default instead of a
# stale constant.
op.add_column(
'users', sa.Column('token_version', sa.Integer(), nullable=False, server_default='0')
)
with op.batch_alter_table('users') as batch_op:
batch_op.alter_column('token_version', server_default=None)
# ### end Alembic commands ###
def downgrade() -> None:
"""Downgrade schema."""
# ### commands auto generated by Alembic - please adjust! ###
op.drop_column('users', 'token_version')
# ### end Alembic commands ###
migrations/versions/9ef6a51509f7_add_drawing_started_at_to_rounds.py
+32
View File
@@ -0,0 +1,32 @@
"""add drawing_started_at to rounds
Revision ID: 9ef6a51509f7
Revises: 943dbd74d983
Create Date: 2026-07-27 12:31:09.907682
"""
from typing import Sequence, Union
from alembic import op
import sqlalchemy as sa
# revision identifiers, used by Alembic.
revision: str = '9ef6a51509f7'
down_revision: Union[str, Sequence[str], None] = '943dbd74d983'
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None
def upgrade() -> None:
"""Upgrade schema."""
# ### commands auto generated by Alembic - please adjust! ###
op.add_column('rounds', sa.Column('drawing_started_at', sa.DateTime(), nullable=True))
# ### end Alembic commands ###
def downgrade() -> None:
"""Downgrade schema."""
# ### commands auto generated by Alembic - please adjust! ###
op.drop_column('rounds', 'drawing_started_at')
# ### end Alembic commands ###
tests/unit/test_admin.py
+100
View File
@@ -67,6 +67,15 @@ async def test_admin_rejects_wrong_token(client):
assert resp.status_code == 403
async def test_admin_rejects_non_ascii_token_with_403_not_500(client):
"""B-46: secrets.compare_digest raises TypeError on a non-ASCII str, which
used to bubble up as a 500 instead of the expected 403. httpx encodes str
header values as ASCII client-side, so the raw UTF-8 bytes are passed
directly to reproduce what a real non-ASCII header on the wire looks like."""
resp = await client.get("/admin/config", headers={"X-Admin-Token": "café".encode("utf-8")})
assert resp.status_code == 403
async def test_admin_reads_and_updates_config(client):
headers = {"X-Admin-Token": "test-admin-token"}
@@ -205,6 +214,10 @@ async def test_admin_resets_user_password(client):
assert refreshed.password_hash != old_hash
assert verify_password(new_password, refreshed.password_hash)
assert not verify_password("original-password", refreshed.password_hash)
# B-34: the reset must bump token_version so a session opened before
# the reset (e.g. an attacker who had the old password) is evicted
# immediately rather than staying valid until the JWT naturally expires.
assert refreshed.token_version == 1
async def test_admin_reset_password_requires_token(client):
@@ -273,3 +286,90 @@ async def test_pause_cannot_be_toggled_through_the_config_endpoint(client):
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
@pytest.mark.parametrize("endpoint", ["/admin/rounds", "/admin/audit-log", "/admin/pending-transactions"])
@pytest.mark.parametrize("bad_limit", [0, -1, 501])
async def test_admin_list_endpoints_reject_out_of_range_limit(client, endpoint, bad_limit):
"""B-45: `limit` had no bounds — `-1` means "everything" on SQLite, so an
unvalidated limit could dump the entire table in one response."""
headers = {"X-Admin-Token": "test-admin-token"}
resp = await client.get(endpoint, headers=headers, params={"limit": bad_limit})
assert resp.status_code == 422
async def test_admin_list_rounds_respects_limit(client):
from app.db import base as db_base
from app.db.models import Round
async with db_base.AsyncSessionLocal() as session:
session.add_all([Round(status="closed") for _ in range(3)])
await session.commit()
headers = {"X-Admin-Token": "test-admin-token"}
resp = await client.get("/admin/rounds", headers=headers, params={"limit": 2})
assert resp.status_code == 200
assert len(resp.json()) == 2
async def test_admin_audit_log_respects_limit(client):
from app.db import base as db_base
from app.audit.log import write_audit_log
async with db_base.AsyncSessionLocal() as session:
for _ in range(3):
await write_audit_log(session, "test_event", {})
await session.commit()
headers = {"X-Admin-Token": "test-admin-token"}
resp = await client.get("/admin/audit-log", headers=headers, params={"limit": 2})
assert resp.status_code == 200
assert len(resp.json()) == 2
async def _make_pending_transaction(session, *, kind="bet", status="pending"):
from app.db.models import PendingTransaction
import secrets as _secrets
tx = PendingTransaction(
kind=kind,
current_txid=_secrets.token_hex(32),
fee_rate_sat_vb=1,
raw_tx_hex="00",
status=status,
)
session.add(tx)
return tx
async def test_admin_pending_transactions_respects_limit(client):
from app.db import base as db_base
async with db_base.AsyncSessionLocal() as session:
for _ in range(3):
await _make_pending_transaction(session)
await session.commit()
headers = {"X-Admin-Token": "test-admin-token"}
resp = await client.get("/admin/pending-transactions", headers=headers, params={"limit": 2})
assert resp.status_code == 200
assert len(resp.json()) == 2
async def test_admin_pending_transactions_status_filter(client):
from app.db import base as db_base
async with db_base.AsyncSessionLocal() as session:
await _make_pending_transaction(session, status="pending")
await _make_pending_transaction(session, status="confirmed")
await _make_pending_transaction(session, status="failed")
await session.commit()
headers = {"X-Admin-Token": "test-admin-token"}
resp = await client.get(
"/admin/pending-transactions", headers=headers, params={"status": "confirmed"}
)
assert resp.status_code == 200
entries = resp.json()
assert len(entries) == 1
assert entries[0]["status"] == "confirmed"
tests/unit/test_api_timeutil.py
+21
View File
@@ -0,0 +1,21 @@
from datetime import datetime, timezone
from app.api.timeutil import isoformat_utc
def test_naive_datetime_is_stamped_utc():
# SQLite/aiosqlite round-trips DateTime columns as naive even though every
# value written is UTC (app.db.models.utcnow) — this is the exact shape
# returned by the ORM after a read (B-35).
naive = datetime(2026, 7, 27, 6, 56, 47, 489110)
result = isoformat_utc(naive)
assert result == "2026-07-27T06:56:47.489110+00:00"
def test_aware_datetime_is_left_unchanged():
aware = datetime(2026, 7, 27, 6, 56, 47, tzinfo=timezone.utc)
assert isoformat_utc(aware) == aware.isoformat()
def test_none_passes_through():
assert isoformat_utc(None) is None
tests/unit/test_auth.py
+126
View File
@@ -0,0 +1,126 @@
import pytest
from cryptography.fernet import Fernet
from httpx import ASGITransport, AsyncClient
from app.config import settings
@pytest.fixture
async def client(monkeypatch, tmp_path):
monkeypatch.setattr(settings, "database_url", f"sqlite+aiosqlite:///{tmp_path}/test.db")
monkeypatch.setattr(settings, "jwt_secret", "test-jwt-secret")
monkeypatch.setattr(settings, "xprv_encryption_key", Fernet.generate_key().decode())
monkeypatch.setattr(settings, "master_key_path", str(tmp_path / "master.xprv.enc"))
import app.wallet.hd as hd
hd._account_key = None
hd.generate_master_key()
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from app.db import base as db_base
import app.db.models # noqa: F401
db_base.engine = create_async_engine(settings.database_url)
db_base.AsyncSessionLocal = async_sessionmaker(db_base.engine, expire_on_commit=False)
from app.db import session as db_session
db_session.AsyncSessionLocal = db_base.AsyncSessionLocal
async with db_base.engine.begin() as conn:
await conn.run_sync(db_base.Base.metadata.create_all)
from fastapi import FastAPI
from app.auth.routes import router as auth_router
from app.electrum.listener import ElectrumListener
app = FastAPI()
app.include_router(auth_router)
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:
yield ac
await db_base.engine.dispose()
async def _register(client, username="alice", password="original-password"):
resp = await client.post("/auth/register", json={"username": username, "password": password})
assert resp.status_code == 201
return resp.json()["access_token"]
async def test_login_locks_out_after_repeated_failures(client):
await _register(client)
for _ in range(5):
resp = await client.post("/auth/login", json={"username": "alice", "password": "wrong"})
assert resp.status_code == 401
resp = await client.post("/auth/login", json={"username": "alice", "password": "wrong"})
assert resp.status_code == 429
assert resp.json()["detail"]["code"] == "rate_limited"
# Even the *correct* password is refused while locked out — the throttle
# protects against a lucky guess landing inside the backoff window too.
resp = await client.post("/auth/login", json={"username": "alice", "password": "original-password"})
assert resp.status_code == 429
async def test_unknown_username_and_wrong_password_share_a_bucket_and_response(client):
await _register(client, username="bob")
for _ in range(5):
resp = await client.post("/auth/login", json={"username": "nobody", "password": "wrong"})
assert resp.status_code == 401
assert resp.json()["detail"]["code"] == "invalid_credentials"
resp = await client.post("/auth/login", json={"username": "nobody", "password": "wrong"})
assert resp.status_code == 429
async def test_login_failures_against_one_account_do_not_lock_out_another(client):
await _register(client, username="alice")
await _register(client, username="carol", password="carols-password")
for _ in range(6):
await client.post("/auth/login", json={"username": "alice", "password": "wrong"})
# Different username, but same IP (the test client always looks the same) —
# only the per-username bucket should be exhausted, not the whole IP, since
# the per-username threshold (5) is hit well before the shared IP bucket's.
resp = await client.post("/auth/login", json={"username": "carol", "password": "carols-password"})
assert resp.status_code == 200
async def test_successful_login_resets_the_username_bucket(client):
await _register(client)
for _ in range(4):
resp = await client.post("/auth/login", json={"username": "alice", "password": "wrong"})
assert resp.status_code == 401
resp = await client.post("/auth/login", json={"username": "alice", "password": "original-password"})
assert resp.status_code == 200
resp = await client.post("/auth/login", json={"username": "alice", "password": "original-password"})
assert resp.status_code == 200
async def test_registration_is_rate_limited_per_ip(client):
for i in range(5):
resp = await client.post(
"/auth/register", json={"username": f"user{i}", "password": "a-strong-password"}
)
assert resp.status_code == 201
resp = await client.post(
"/auth/register", json={"username": "user5", "password": "a-strong-password"}
)
assert resp.status_code == 429
assert resp.json()["detail"]["code"] == "rate_limited"
tests/unit/test_bets.py
+58
View File
@@ -8,8 +8,10 @@ from app.bets.service import BetError, place_bet
from app.config import settings
from app.db.base import Base
from app.db.models import AuditLog, PendingTransaction, Round, RoundConfig, RoundParticipant, User, UtxoEvent
from app.rounds.events import broadcaster
from app.rounds.service import open_new_round_if_needed
from app.wallet.hd import derive_user_address
from app.wallet.psbt_builder import MAX_TX_INPUTS
class FakeElectrumClient:
@@ -91,6 +93,35 @@ async def test_place_bet_rejects_insufficient_balance(session_factory):
await place_bet(session, client, user)
async def test_place_bet_reports_a_too_fragmented_balance_distinctly(session_factory): # B-48
# 100 x 0.15 PLM = 15 PLM, plenty for a 10 PLM bet, but the 50 largest inputs
# only add up to 7.5 PLM — so the build must fail with its own code, not with
# the "you have no funds" one, and must carry the cap for the translation.
user_id = await _make_funded_user(session_factory, 20, 15_000_000)
async with session_factory() as session:
for i in range(99):
session.add(
UtxoEvent(
user_id=user_id,
txid=f"{i:064x}",
vout=0,
amount_sats=15_000_000,
confirmed_height=100,
)
)
await session.commit()
client = FakeElectrumClient()
async with session_factory() as session:
user = await session.get(User, user_id)
with pytest.raises(BetError) as excinfo:
await place_bet(session, client, user)
assert excinfo.value.code == "too_many_inputs"
assert excinfo.value.params == {"max_inputs": MAX_TX_INPUTS}
assert not client.broadcasted
async def test_place_bet_rejects_second_bet_same_round(session_factory):
user_id = await _make_funded_user(session_factory, 2, 3_000_000_000)
client = FakeElectrumClient()
@@ -166,6 +197,33 @@ async def test_failed_broadcast_leaves_nothing_behind(session_factory):
assert "bet_placed" not in events
async def test_failed_broadcast_publishes_an_sse_update(session_factory): # B-49
"""The rollback moves as much state as the successful path does, so it must ping
the dashboards the same way — otherwise the phantom bet stays on screen until the
next poll."""
user_id = await _make_funded_user(session_factory, 21, 3_000_000_000)
async with session_factory() as session:
# Open the round up front: place_bet would otherwise open it itself, and that
# publish() would satisfy the assertion below whether or not the rollback ever
# published one of its own.
await open_new_round_if_needed(session)
await session.commit()
queue = broadcaster.subscribe()
try:
while not queue.empty():
queue.get_nowait()
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)
assert not queue.empty()
finally:
broadcaster.unsubscribe(queue)
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)
tests/unit/test_broadcast.py
+330 -14
View File
@@ -3,7 +3,7 @@ from datetime import datetime, timedelta, timezone
import pytest
from embit import script
from embit.bip32 import HDKey
from embit.transaction import Transaction
from embit.transaction import Transaction, TransactionInput, TransactionOutput
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from app.config import settings
@@ -11,7 +11,7 @@ from app.db.base import Base
from app.db.models import PendingTransaction, User
from app.tx.broadcast import RbfError, bump_fee, should_bump
from app.wallet.plm_network import PLM_MAINNET
from app.wallet.psbt_builder import Utxo, build_signed_transaction
from app.wallet.psbt_builder import MAX_FEE_RATE_SAT_VB, Utxo, build_signed_transaction, estimate_vsize
def _key(seed_byte: int) -> HDKey:
@@ -22,7 +22,7 @@ def _key(seed_byte: int) -> HDKey:
def test_should_bump_false_before_timeout():
pending = PendingTransaction(
kind="bet", current_txid="x", fee_rate_sat_vb=1, raw_tx_hex="00", status="pending",
broadcast_at=datetime.now(timezone.utc),
broadcast_at=datetime.now(timezone.utc), last_broadcast_at=datetime.now(timezone.utc),
)
assert should_bump(pending, datetime.now(timezone.utc), timeout_seconds=900) is False
@@ -31,6 +31,7 @@ def test_should_bump_true_after_timeout():
pending = PendingTransaction(
kind="bet", current_txid="x", fee_rate_sat_vb=1, raw_tx_hex="00", status="pending",
broadcast_at=datetime.now(timezone.utc) - timedelta(seconds=1000),
last_broadcast_at=datetime.now(timezone.utc) - timedelta(seconds=1000),
)
assert should_bump(pending, datetime.now(timezone.utc), timeout_seconds=900) is True
@@ -39,17 +40,41 @@ def test_should_bump_false_when_not_pending():
pending = PendingTransaction(
kind="bet", current_txid="x", fee_rate_sat_vb=1, raw_tx_hex="00", status="confirmed",
broadcast_at=datetime.now(timezone.utc) - timedelta(seconds=1000),
last_broadcast_at=datetime.now(timezone.utc) - timedelta(seconds=1000),
)
assert should_bump(pending, datetime.now(timezone.utc), timeout_seconds=900) is False
def test_should_bump_measures_from_last_broadcast_not_first(monkeypatch):
"""B-27 regression: a tx first broadcast long ago, but bumped recently, must not
be due for another bump yet — should_bump has to look at last_broadcast_at, not
the original broadcast_at, or every tick would try to re-bump it."""
pending = PendingTransaction(
kind="bet", current_txid="x", fee_rate_sat_vb=1, raw_tx_hex="00", status="pending",
broadcast_at=datetime.now(timezone.utc) - timedelta(seconds=10_000),
last_broadcast_at=datetime.now(timezone.utc),
)
assert should_bump(pending, datetime.now(timezone.utc), timeout_seconds=900) is False
class FakeClient:
"""B-40: _prevout_amount now asks for the raw (non-verbose) transaction and
reads its output value as an integer via embit, rather than a verbose reply's
float "value" field — so this fake must hand back a real, parseable raw tx
whose vout[0] carries the requested amount (every test here spends vout 0 of
its fixture UTXO)."""
def __init__(self, prevout_values: dict[str, int]):
self._prevout_values = prevout_values
self.broadcasted: list[str] = []
async def get_transaction(self, txid: str, verbose: bool = False) -> dict:
return {"vout": {0: {"value": self._prevout_values[txid] / 100_000_000}}}
async def get_transaction(self, txid: str, verbose: bool = False) -> str:
assert verbose is False
fake_prevout_tx = Transaction(
vin=[TransactionInput(b"\x00" * 32, 0)],
vout=[TransactionOutput(self._prevout_values[txid], script.Script(b"\x00\x14" + b"\x00" * 20))],
)
return fake_prevout_tx.serialize().hex()
async def broadcast(self, raw_tx_hex: str) -> str:
self.broadcasted.append(raw_tx_hex)
@@ -116,9 +141,7 @@ async def test_bump_fee_shrinks_change_and_rebroadcasts(session_factory):
client = FakeClient({utxo_txid: utxo_amount})
async with session_factory() as session:
row = await session.get(PendingTransaction, pending_id)
new_txid = await bump_fee(session, client, row)
new_txid = await bump_fee(session_factory, client, pending_id)
assert client.broadcasted
assert new_txid != built.txid
@@ -136,6 +159,61 @@ async def test_bump_fee_shrinks_change_and_rebroadcasts(session_factory):
assert row.attempt_count == 2
async def test_bump_fee_leaves_broadcast_at_untouched(session_factory):
"""B-27 regression: bump_fee must only ever update last_broadcast_at. Before
this, it overwrote broadcast_at on every bump — the same field
tx/reconcile.py's abandon-after-N-hours grace period measures from — so a
repeatedly-bumped-but-never-mined tx reset that clock forever and was never
abandoned."""
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(97).to_public()).address(network=PLM_MAINNET)
utxo_amount = 150_000_000
utxo_txid = "33" * 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,
)
original_broadcast_at = datetime.now(timezone.utc) - timedelta(days=1)
async with session_factory() as session:
user = User(username="carol", password_hash="x", derivation_index=0, address=my_address)
session.add(user)
await session.commit()
pending = PendingTransaction(
kind="bet",
user_id=user.id,
current_txid=built.txid,
fee_rate_sat_vb=1,
raw_tx_hex=built.raw_hex,
status="pending",
broadcast_at=original_broadcast_at,
last_broadcast_at=original_broadcast_at,
)
session.add(pending)
await session.commit()
pending_id = pending.id
client = FakeClient({utxo_txid: utxo_amount})
before_bump = datetime.now(timezone.utc)
await bump_fee(session_factory, client, pending_id)
async with session_factory() as session:
row = await session.get(PendingTransaction, pending_id)
assert row.broadcast_at.replace(tzinfo=timezone.utc) == original_broadcast_at
assert row.last_broadcast_at.replace(tzinfo=timezone.utc) >= before_bump
async def test_bump_fee_raises_when_no_change_output(session_factory):
from app.wallet.hd import derive_user_address, derive_user_key
@@ -175,10 +253,8 @@ async def test_bump_fee_raises_when_no_change_output(session_factory):
client = FakeClient({utxo_txid: utxo_amount})
async with session_factory() as session:
row = await session.get(PendingTransaction, pending_id)
with pytest.raises(RbfError):
await bump_fee(session, client, row)
await bump_fee(session_factory, client, pending_id)
async def test_bump_fee_retargets_every_stored_txid(session_factory):
@@ -232,9 +308,7 @@ async def test_bump_fee_retargets_every_stored_txid(session_factory):
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)
new_txid = await bump_fee(session_factory, FakeClient({utxo_txid: utxo_amount}), pending_id)
async with session_factory() as session:
from sqlalchemy import select
@@ -248,3 +322,245 @@ async def test_bump_fee_retargets_every_stored_txid(session_factory):
utxo = (await session.scalars(select(UtxoEvent))).one()
assert utxo.spent_txid == new_txid
# --- B-32: the bump delta must always meet BIP125's relay-mandated minimum, and
# escalation must stop at a ceiling instead of retrying forever. ------------------
async def test_bump_fee_meets_bip125_minimum_when_old_fee_already_exceeds_target(session_factory):
"""old_fee (as bump_fee computes it from the actual prevout amounts) can end
up higher than vsize * target_fee_rate — e.g. because dust change was folded
into the original fee (wallet/psbt_builder.py's DUST_LIMIT_SATS handling).
The naive `target_fee - old_fee` goes negative in that case; the previous
fallback was a flat 1-satoshi total bump, nowhere near BIP125 rule 4's
required minimum, so the node rejected it every time and — since bump_fee
raised before touching `pending` — the next tick retried identically every
30 seconds, forever. Simulated here by reporting a prevout inflated beyond
what was actually spent, which has the same effect on old_fee as dust
absorption would."""
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(96).to_public()).address(network=PLM_MAINNET)
utxo_amount = 150_000_000
utxo_txid = "55" * 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="dave", password_hash="x", derivation_index=0, address=my_address)
session.add(user)
await session.commit()
pending = PendingTransaction(
kind="bet",
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
# Reports a prevout inflated well beyond what was actually spent — has the
# same effect on old_fee as dust absorption would have: old_fee ends up far
# above vsize * target_fee_rate (target_fee_rate = 2 here).
inflated_excess = 50_000
client = FakeClient({utxo_txid: utxo_amount + inflated_excess})
new_txid = await bump_fee(session_factory, client, pending_id)
assert client.broadcasted
new_tx = Transaction.parse(bytes.fromhex(client.broadcasted[0]))
old_tx = Transaction.parse(bytes.fromhex(built.raw_hex))
old_change = next(o.value for o in old_tx.vout if o.script_pubkey.address(network=PLM_MAINNET) == my_address)
new_change = next(o.value for o in new_tx.vout if o.script_pubkey.address(network=PLM_MAINNET) == my_address)
vsize = estimate_vsize(len(old_tx.vin), len(old_tx.vout))
min_valid_delta = vsize * 1 # BIP125 rule 4's floor at a 1 sat/vB incremental relay fee
assert min_valid_delta > 1 # meaningfully more than the old flat "1 satoshi" fallback
assert old_change - new_change == min_valid_delta
async with session_factory() as session:
row = await session.get(PendingTransaction, pending_id)
old_fee_as_bump_fee_computed_it = built.fee_sats + inflated_excess
expected_rate = (old_fee_as_bump_fee_computed_it + min_valid_delta) // vsize
assert row.fee_rate_sat_vb == expected_rate
assert row.fee_rate_sat_vb > 2 # the actual rate, not the naive (and too-low) target
async def test_bump_fee_refuses_once_at_the_max_fee_rate(session_factory):
"""Without a ceiling, a stuck transaction's fee rate climbed by 1 sat/vB every
30 seconds forever, eating further and further into the user's change."""
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(95).to_public()).address(network=PLM_MAINNET)
utxo_amount = 150_000_000
utxo_txid = "66" * 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="erin", password_hash="x", derivation_index=0, address=my_address)
session.add(user)
await session.commit()
pending = PendingTransaction(
kind="bet",
user_id=user.id,
current_txid=built.txid,
fee_rate_sat_vb=MAX_FEE_RATE_SAT_VB,
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
client = FakeClient({utxo_txid: utxo_amount})
with pytest.raises(RbfError):
await bump_fee(session_factory, client, pending_id)
assert not client.broadcasted
# --- B-40: bump_fee must not hold a DB session open across its network calls,
# and a row that's no longer pending by the time it runs is a quiet no-op. -------
async def test_bump_fee_holds_no_session_open_during_network_calls(session_factory):
"""The get_transaction-per-input reads and the broadcast must happen with no
DB session held open — the same shape used elsewhere for this reason (B-18,
electrum/listener.py's refresh_user for B-31) — otherwise a session sits
idle in the pool for the whole duration of what can be several slow network
round-trips."""
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(94).to_public()).address(network=PLM_MAINNET)
utxo_amount = 150_000_000
utxo_txid = "77" * 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="frank", password_hash="x", derivation_index=0, address=my_address)
session.add(user)
await session.commit()
pending = PendingTransaction(
kind="bet",
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
open_count = {"n": 0}
class _TrackedSession:
def __init__(self, inner):
self._inner = inner
async def __aenter__(self):
result = await self._inner.__aenter__()
open_count["n"] += 1
return result
async def __aexit__(self, *exc):
open_count["n"] -= 1
return await self._inner.__aexit__(*exc)
def tracking_session_factory():
return _TrackedSession(session_factory())
class TrackingClient(FakeClient):
async def get_transaction(self, txid, verbose=False):
assert open_count["n"] == 0, "a session was held open during a network call"
return await super().get_transaction(txid, verbose)
async def broadcast(self, raw_tx_hex):
assert open_count["n"] == 0, "a session was held open during the broadcast"
return await super().broadcast(raw_tx_hex)
client = TrackingClient({utxo_txid: utxo_amount})
await bump_fee(tracking_session_factory, client, pending_id)
assert client.broadcasted
assert open_count["n"] == 0 # nothing left open afterwards either
async def test_bump_fee_is_a_noop_when_no_longer_pending(session_factory):
"""A row can legitimately confirm (or otherwise leave "pending") between
being read as due and RbfBumper actually attempting the bump — a normal
race, not an error. Must return quietly rather than raising or touching
the network."""
async with session_factory() as session:
user = User(username="grace", password_hash="x", derivation_index=0, address="plm1qxxx")
session.add(user)
await session.commit()
pending = PendingTransaction(
kind="bet",
user_id=user.id,
current_txid="already-confirmed-txid",
fee_rate_sat_vb=1,
raw_tx_hex="00",
status="confirmed",
broadcast_at=datetime.now(timezone.utc) - timedelta(seconds=1000),
)
session.add(pending)
await session.commit()
pending_id = pending.id
client = FakeClient({})
result = await bump_fee(session_factory, client, pending_id)
assert result is None
assert not client.broadcasted
async def test_bump_fee_is_a_noop_when_the_row_is_gone(session_factory):
client = FakeClient({})
result = await bump_fee(session_factory, client, 999_999)
assert result is None
assert not client.broadcasted
tests/unit/test_caddyfile_security_headers.py
+35
View File
@@ -0,0 +1,35 @@
"""B-43: the Caddyfile must keep sending baseline security headers. Caddy adds
none of these on its own, and the JWT lives in localStorage, so a regression
here silently reopens an XSS/clickjacking exposure with no test ever failing
in the Python suite (the Caddyfile isn't imported/exercised by anything else)."""
from pathlib import Path
CADDYFILE = (Path(__file__).parent.parent.parent / "Caddyfile").read_text()
def test_header_block_present():
assert "header {" in CADDYFILE
def test_hsts_is_set():
assert "Strict-Transport-Security" in CADDYFILE
assert "max-age=" in CADDYFILE
def test_nosniff_is_set():
assert 'X-Content-Type-Options "nosniff"' in CADDYFILE
def test_frame_ancestors_are_blocked():
assert 'X-Frame-Options "DENY"' in CADDYFILE
assert "frame-ancestors 'none'" in CADDYFILE
def test_referrer_policy_is_set():
assert "Referrer-Policy" in CADDYFILE
def test_csp_default_src_is_self():
assert "Content-Security-Policy" in CADDYFILE
assert "default-src 'self'" in CADDYFILE
tests/unit/test_client_ip.py
+43
View File
@@ -0,0 +1,43 @@
"""app.api.client_ip is shared by the login/registration throttles (B-33) and
the SSE per-IP subscriber cap (B-38) — both depend on it correctly preferring
X-Forwarded-For (Caddy reverse-proxies every request, see Caddyfile) over
request.client.host, which would otherwise be the proxy's own address."""
from starlette.requests import Request
from app.api.client_ip import client_ip
def _request(*, forwarded: str | None = None, client_host: str | None = "127.0.0.1") -> Request:
headers = [(b"x-forwarded-for", forwarded.encode())] if forwarded else []
scope = {
"type": "http",
"headers": headers,
"client": (client_host, 12345) if client_host else None,
}
return Request(scope)
def test_client_ip_prefers_x_forwarded_for():
request = _request(forwarded="5.6.7.8", client_host="10.0.0.1")
assert client_ip(request) == "5.6.7.8"
def test_client_ip_takes_the_first_hop_of_a_forwarded_chain():
request = _request(forwarded="5.6.7.8, 10.0.0.1, 172.17.0.1")
assert client_ip(request) == "5.6.7.8"
def test_client_ip_strips_whitespace():
request = _request(forwarded=" 5.6.7.8 , 10.0.0.1")
assert client_ip(request) == "5.6.7.8"
def test_client_ip_falls_back_to_request_client_without_the_header():
request = _request(forwarded=None, client_host="10.0.0.1")
assert client_ip(request) == "10.0.0.1"
def test_client_ip_falls_back_to_unknown_with_neither():
request = _request(forwarded=None, client_host=None)
assert client_ip(request) == "unknown"
tests/unit/test_confirmation.py
+132 -36
View File
@@ -1,41 +1,83 @@
import pytest
from sqlalchemy import select
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
import app.bets.confirmation # noqa: F401 (registers the "bet" handler)
import app.rounds.confirmation # noqa: F401 (registers the "payout" handler)
from sqlalchemy import select
from app.config import settings
from app.db.base import Base
from app.db.models import PendingTransaction, Round, RoundParticipant
from app.db.models import PendingTransaction, Round, RoundParticipant, User
from app.electrum.scripthash import address_to_scripthash
from app.tx.confirmation import poll_once
from app.wallet.hd import derive_user_address
class FakeClient:
def __init__(self, confirmations_by_txid: dict[str, int]):
self._confirmations = confirmations_by_txid
"""B-41: poll_once now asks blockchain.scripthash.get_history rather than a
verbose blockchain.transaction.get, so this hands back a flat history —
height > 0 means confirmed at that height, 0 (or absent) means still in the
mempool. The scripthash argument is ignored: every candidate's derived
address is looked up against the same known universe of txids, which is
fine since matching happens on tx_hash, not on which address asked."""
async def get_transaction(self, txid: str, verbose: bool = False) -> dict:
return {"confirmations": self._confirmations.get(txid, 0)}
def __init__(self, heights_by_txid: dict[str, int]):
self._heights = heights_by_txid
async def get_history(self, scripthash: str) -> list[dict]:
return [{"tx_hash": txid, "height": height} for txid, height in self._heights.items()]
@pytest.fixture
async def session_factory():
async def session_factory(tmp_path, monkeypatch):
# own_address_for (B-41) derives each row's address via the HD wallet, so
# poll_once now needs a real master key — same bootstrap test_broadcast.py
# and test_reconcile.py use.
monkeypatch.setattr(settings, "master_key_path", str(tmp_path / "master.xprv.enc"))
monkeypatch.setattr(
settings,
"xprv_encryption_key",
__import__("cryptography.fernet", fromlist=["Fernet"]).Fernet.generate_key().decode(),
)
from app.wallet import hd
hd._account_key = None
hd.generate_master_key()
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()
hd._account_key = None
async def _make_user(session, derivation_index: int) -> User:
user = User(
username=f"user{derivation_index}",
password_hash="x",
derivation_index=derivation_index,
address=derive_user_address(derivation_index),
)
session.add(user)
await session.flush()
return user
async def test_bet_confirmation_marks_participant_confirmed(session_factory):
async with session_factory() as session:
user = await _make_user(session, 0)
session.add(Round(id=1, status="open"))
session.add(
RoundParticipant(
round_id=1, user_id=1, bet_amount_sats=1_000, bet_txid="tx1", status="broadcast"
round_id=1, user_id=user.id, bet_amount_sats=1_000, bet_txid="tx1", status="broadcast"
)
)
session.add(
PendingTransaction(kind="bet", round_id=1, user_id=1, current_txid="tx1", fee_rate_sat_vb=1, raw_tx_hex="00", status="pending")
PendingTransaction(
kind="bet", round_id=1, user_id=user.id, current_txid="tx1", fee_rate_sat_vb=1,
raw_tx_hex="00", status="pending",
)
)
await session.commit()
@@ -53,9 +95,17 @@ async def test_bet_confirmation_marks_participant_confirmed(session_factory):
async def test_unconfirmed_tx_is_left_pending(session_factory):
async with session_factory() as session:
user = await _make_user(session, 0)
session.add(Round(id=2, status="open"))
session.add(RoundParticipant(round_id=2, user_id=1, bet_amount_sats=1_000, bet_txid="tx2", status="broadcast"))
session.add(PendingTransaction(kind="bet", round_id=2, user_id=1, current_txid="tx2", fee_rate_sat_vb=1, raw_tx_hex="00", status="pending"))
session.add(
RoundParticipant(round_id=2, user_id=user.id, bet_amount_sats=1_000, bet_txid="tx2", status="broadcast")
)
session.add(
PendingTransaction(
kind="bet", round_id=2, user_id=user.id, current_txid="tx2", fee_rate_sat_vb=1,
raw_tx_hex="00", status="pending",
)
)
await session.commit()
client = FakeClient({"tx2": 0})
@@ -70,7 +120,11 @@ async def test_unconfirmed_tx_is_left_pending(session_factory):
async def test_payout_confirmation_closes_round(session_factory):
async with session_factory() as session:
session.add(Round(id=3, status="paying_out", payout_txid="tx3"))
session.add(PendingTransaction(kind="payout", round_id=3, current_txid="tx3", fee_rate_sat_vb=1, raw_tx_hex="00", status="pending"))
session.add(
PendingTransaction(
kind="payout", round_id=3, current_txid="tx3", fee_rate_sat_vb=1, raw_tx_hex="00", status="pending"
)
)
await session.commit()
client = FakeClient({"tx3": 2})
@@ -83,43 +137,52 @@ async def test_payout_confirmation_closes_round(session_factory):
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)."""
"""Answers for one address's history and raises for the other's — the
get_history equivalent of a server that no longer knows a particular tx
(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
def __init__(self, heights_by_txid: dict[str, int], exploding_scripthash: str):
self._heights = heights_by_txid
self._exploding = exploding_scripthash
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 get_history(self, scripthash: str) -> list[dict]:
if scripthash == self._exploding:
raise RuntimeError("server error")
return [{"tx_hash": txid, "height": height} for txid, height in self._heights.items()]
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 def test_one_unresolvable_candidate_does_not_block_the_others(session_factory):
"""B-03: the lookup used to be unguarded, so a single failing candidate aborted
the whole pass — nothing confirmed again until an operator intervened, which in
turn meant no round could ever close. B-41 changed the failure unit from "one
txid" to "one address's history", but the isolation guarantee is the same."""
async with session_factory() as session:
good_user = await _make_user(session, 0)
gone_user = await _make_user(session, 1)
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",
RoundParticipant(
round_id=10, user_id=good_user.id, bet_amount_sats=1_000, bet_txid="good", status="broadcast"
)
)
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",
kind="bet", round_id=10, user_id=gone_user.id, current_txid="gone", fee_rate_sat_vb=1,
raw_tx_hex="00", status="pending",
)
)
session.add(
PendingTransaction(
kind="bet", round_id=10, user_id=good_user.id, 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"))
exploding_scripthash = address_to_scripthash(derive_user_address(1))
confirmed = await poll_once(
session_factory, ExplodingClient({"good": 1}, exploding_scripthash=exploding_scripthash)
)
assert confirmed == 1 # the healthy one still got processed
async with session_factory() as session:
@@ -135,15 +198,16 @@ async def test_bet_confirms_after_an_rbf_bump_changed_the_txid(session_factory):
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:
user = await _make_user(session, 0)
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"
round_id=11, user_id=user.id, 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,
kind="bet", round_id=11, user_id=user.id, current_txid="bumped-txid", fee_rate_sat_vb=2,
raw_tx_hex="00", status="pending", replaced_by_txid="old-txid",
)
)
@@ -171,3 +235,35 @@ async def test_payout_confirms_after_an_rbf_bump_changed_the_txid(session_factor
async with session_factory() as session:
assert (await session.get(Round, 12)).status == "closed"
async def test_poll_once_caches_history_per_scripthash(session_factory):
"""Two pending bets from the same user share one address — fetching its
history twice in one pass would be wasteful."""
async with session_factory() as session:
user = await _make_user(session, 0)
session.add(Round(id=20, status="open"))
session.add(
PendingTransaction(
kind="bet", round_id=20, user_id=user.id, current_txid="tx-a", fee_rate_sat_vb=1,
raw_tx_hex="00", status="pending",
)
)
session.add(
PendingTransaction(
kind="withdrawal", user_id=user.id, current_txid="tx-b", fee_rate_sat_vb=1,
raw_tx_hex="00", status="pending",
)
)
await session.commit()
call_count = {"n": 0}
class CountingClient:
async def get_history(self, scripthash: str) -> list[dict]:
call_count["n"] += 1
return [{"tx_hash": "tx-a", "height": 0}, {"tx_hash": "tx-b", "height": 0}]
await poll_once(session_factory, CountingClient())
assert call_count["n"] == 1
tests/unit/test_db_base.py
+61
View File
@@ -0,0 +1,61 @@
"""Regression tests for B-39: SQLite must run in WAL mode with a busy_timeout,
since this app has five concurrent background tasks plus every HTTP handler
sharing one database file, and the default rollback-journal mode lets a writer
block every reader and fails a second writer immediately instead of waiting."""
import pytest
from sqlalchemy.ext.asyncio import create_async_engine
from app.db.base import _SQLITE_BUSY_TIMEOUT_MS, _register_sqlite_pragmas
@pytest.fixture
async def sqlite_engine(tmp_path):
# WAL needs a real file (it writes a companion -wal/-shm file alongside it) —
# ":memory:" wouldn't exercise the same path.
engine = create_async_engine(f"sqlite+aiosqlite:///{tmp_path}/test.db")
yield engine
await engine.dispose()
async def _pragma(engine, name: str):
async with engine.connect() as conn:
result = await conn.exec_driver_sql(f"PRAGMA {name}")
return result.fetchone()[0]
async def test_register_sqlite_pragmas_enables_wal_and_busy_timeout(sqlite_engine):
_register_sqlite_pragmas(sqlite_engine)
assert (await _pragma(sqlite_engine, "journal_mode")).lower() == "wal"
assert await _pragma(sqlite_engine, "busy_timeout") == _SQLITE_BUSY_TIMEOUT_MS
assert await _pragma(sqlite_engine, "synchronous") == 1 # NORMAL
async def test_register_sqlite_pragmas_applies_to_every_new_connection(sqlite_engine):
"""The pool can open more than one underlying DBAPI connection over the
engine's lifetime — the pragmas must be re-applied to each one, not just
the first, or a later connection would silently fall back to SQLite's
defaults."""
_register_sqlite_pragmas(sqlite_engine)
async with sqlite_engine.connect() as first:
await first.exec_driver_sql("PRAGMA journal_mode")
async with sqlite_engine.connect() as second:
result = await second.exec_driver_sql("PRAGMA busy_timeout")
assert result.fetchone()[0] == _SQLITE_BUSY_TIMEOUT_MS
def test_register_sqlite_pragmas_is_a_noop_for_other_dialects():
"""Must not touch (or crash on) a non-sqlite engine — e.g. a future
PostgreSQL DATABASE_URL, which neither needs nor understands these
pragmas."""
class _FakeDialect:
name = "postgresql"
class _FakeEngine:
dialect = _FakeDialect()
_register_sqlite_pragmas(_FakeEngine()) # must not raise
tests/unit/test_deposit_reconcile.py
+98
View File
@@ -0,0 +1,98 @@
"""Regression tests for B-30: a periodic sweep must catch a deposit whose
scripthash notification was silently lost, independent of whatever the
notification-driven path (electrum/listener.py:refresh_user) is doing."""
import pytest
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from app.db.base import Base
from app.db.models import User
from app.deposits.reconcile import DepositReconciler
@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()
async def _seed_users(session_factory, addresses: list[str]) -> list[int]:
async with session_factory() as session:
ids = []
for i, address in enumerate(addresses):
user = User(username=f"user{i}", password_hash="x", derivation_index=i, address=address)
session.add(user)
await session.flush()
ids.append(user.id)
await session.commit()
return ids
# Real, decodable PLM bech32 addresses (address_to_scripthash actually parses
# them) — arbitrary otherwise.
_ADDRESSES = [
"plm1q0xcqpzrky6eff2g52qdye53xkk9jxkvraxkkwd",
"plm1q5x25wd6q463mfhckjraaedgjg0lyu73qfcj43n",
"plm1qqph9qup2mp7w7g5nlsdhdc9m2pp44ampzw0ctx",
]
class FakeListener:
def __init__(self, *, fail_for: set[int] | None = None, disconnect_after: int | None = None):
self.client = object() # truthy: "connected"
self.refreshed: list[int] = []
self._fail_for = fail_for or set()
self._disconnect_after = disconnect_after
async def refresh_user(self, user_id: int, scripthash: str) -> None:
self.refreshed.append(user_id)
if self._disconnect_after is not None and len(self.refreshed) >= self._disconnect_after:
self.client = None
if user_id in self._fail_for:
raise RuntimeError(f"listunspent failed for user {user_id}")
async def test_sweep_once_refreshes_every_user(session_factory):
user_ids = await _seed_users(session_factory, _ADDRESSES)
listener = FakeListener()
reconciler = DepositReconciler(session_factory, listener)
await reconciler._sweep_once()
assert listener.refreshed == user_ids
async def test_sweep_once_continues_past_a_failing_user(session_factory):
"""One user's refresh failing (a transient network hiccup) must not stop the
sweep from reaching the rest — mirrors poll_once's per-item isolation."""
user_ids = await _seed_users(session_factory, _ADDRESSES)
listener = FakeListener(fail_for={user_ids[1]})
reconciler = DepositReconciler(session_factory, listener)
await reconciler._sweep_once()
assert listener.refreshed == user_ids
async def test_sweep_once_stops_when_the_connection_drops_mid_sweep(session_factory):
"""No point continuing once the connection is gone — the next reconnect's own
_subscribe_all_users will cover everyone anyway."""
user_ids = await _seed_users(session_factory, _ADDRESSES)
listener = FakeListener(disconnect_after=1)
reconciler = DepositReconciler(session_factory, listener)
await reconciler._sweep_once()
assert listener.refreshed == user_ids[:1]
async def test_sweep_once_does_nothing_with_no_users(session_factory):
listener = FakeListener()
reconciler = DepositReconciler(session_factory, listener)
await reconciler._sweep_once() # must not raise
assert listener.refreshed == []
tests/unit/test_deposits.py
+111 -10
View File
@@ -4,7 +4,12 @@ from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from app.db.base import Base
from app.db.models import AuditLog, User, UtxoEvent
from app.deposits.service import credit_confirmed_utxos, detect_external_spends
from app.deposits.service import (
credit_confirmed_utxos,
find_utxos_missing_from,
mark_utxos_spent_externally,
reinstate_reappeared_utxos,
)
@pytest.fixture
@@ -55,14 +60,66 @@ async def test_idempotent_on_repeated_notification(session_factory, user_id):
assert user.cached_balance_sats == 7_000_000
async def test_external_spend_marks_utxo_spent_and_corrects_balance(session_factory, user_id):
entries = [{"tx_hash": "dd" * 32, "tx_pos": 0, "height": 100, "value": 20_000_000}]
# --- B-29: detecting a UTXO spent outside the platform is now a three-step,
# corroborate-before-you-mark process, split across find_utxos_missing_from
# (read-only candidate detection), the caller's own corroboration against other
# servers (electrum/listener.py, not exercised here), and mark_utxos_spent_
# externally (persistence only, once a candidate is already confirmed). ---------
async def test_find_utxos_missing_from_returns_the_missing_candidate(session_factory, user_id):
async with session_factory() as session:
await credit_confirmed_utxos(
session, user_id, [{"tx_hash": "dd" * 32, "tx_pos": 0, "height": 100, "value": 20_000_000}]
)
# A different outpoint present in this refresh — our own tracked one is
# genuinely absent from it, not just from an entirely empty reply.
other_entries = [{"tx_hash": "99" * 32, "tx_pos": 0, "height": 100, "value": 1_000_000}]
async with session_factory() as session:
candidates = await find_utxos_missing_from(session, user_id, other_entries)
assert len(candidates) == 1
assert candidates[0].txid == "dd" * 32
assert candidates[0].spent_txid is None # read-only: nothing is marked yet
async def test_find_utxos_missing_from_returns_nothing_when_present(session_factory, user_id):
entries = [{"tx_hash": "ee" * 32, "tx_pos": 0, "height": 100, "value": 3_000_000}]
async with session_factory() as session:
await credit_confirmed_utxos(session, user_id, entries)
async with session_factory() as session:
spent = await detect_external_spends(session, user_id, [])
assert spent == 1
candidates = await find_utxos_missing_from(session, user_id, entries)
assert candidates == []
user = await session.get(User, user_id)
assert user.cached_balance_sats == 3_000_000
async def test_find_utxos_missing_from_skips_a_totally_empty_response(session_factory, user_id):
"""B-29: an entirely empty listunspent for a funded address reads as an
incomplete/broken response, not proof of a full external sweep — it would
otherwise flag every UTXO of this user as missing from one bad reply."""
async with session_factory() as session:
await credit_confirmed_utxos(
session, user_id, [{"tx_hash": "dd" * 32, "tx_pos": 0, "height": 100, "value": 20_000_000}]
)
async with session_factory() as session:
candidates = await find_utxos_missing_from(session, user_id, [])
assert candidates == []
async def test_mark_utxos_spent_externally_marks_and_corrects_balance(session_factory, user_id):
async with session_factory() as session:
await credit_confirmed_utxos(
session, user_id, [{"tx_hash": "dd" * 32, "tx_pos": 0, "height": 100, "value": 20_000_000}]
)
async with session_factory() as session:
utxo = (await session.scalars(select(UtxoEvent).where(UtxoEvent.user_id == user_id))).one()
marked = await mark_utxos_spent_externally(session, user_id, [utxo.id])
assert marked == 1
user = await session.get(User, user_id)
assert user.cached_balance_sats == 0
@@ -73,13 +130,57 @@ async def test_external_spend_marks_utxo_spent_and_corrects_balance(session_fact
assert any(e.event_type == "utxo_spent_externally" for e in audit_events)
async def test_no_spend_detected_when_utxo_still_unspent(session_factory, user_id):
async def test_mark_utxos_spent_externally_skips_an_already_resolved_row(session_factory, user_id):
"""Something else (a legitimate platform spend, or a prior refresh) may have
resolved the row between the caller reading the candidate list and finishing
corroboration — mark_utxos_spent_externally must not clobber that."""
async with session_factory() as session:
await credit_confirmed_utxos(
session, user_id, [{"tx_hash": "dd" * 32, "tx_pos": 0, "height": 100, "value": 20_000_000}]
)
utxo = (await session.scalars(select(UtxoEvent).where(UtxoEvent.user_id == user_id))).one()
utxo_id = utxo.id
utxo.spent_txid = "some-real-platform-txid"
await session.commit()
async with session_factory() as session:
marked = await mark_utxos_spent_externally(session, user_id, [utxo_id])
assert marked == 0
utxo = await session.get(UtxoEvent, utxo_id)
assert utxo.spent_txid == "some-real-platform-txid" # untouched
async def test_reinstate_reappeared_utxos_clears_the_mark_and_restores_balance(session_factory, user_id):
async with session_factory() as session:
await credit_confirmed_utxos(
session, user_id, [{"tx_hash": "dd" * 32, "tx_pos": 0, "height": 100, "value": 20_000_000}]
)
utxo_id = (await session.scalars(select(UtxoEvent).where(UtxoEvent.user_id == user_id))).one().id
async with session_factory() as session:
await mark_utxos_spent_externally(session, user_id, [utxo_id])
# The outpoint reappears as unspent in a later refresh.
entries = [{"tx_hash": "dd" * 32, "tx_pos": 0, "height": 100, "value": 20_000_000}]
async with session_factory() as session:
reinstated = await reinstate_reappeared_utxos(session, user_id, entries)
assert reinstated == 1
user = await session.get(User, user_id)
assert user.cached_balance_sats == 20_000_000
utxo = await session.get(UtxoEvent, utxo_id)
assert utxo.spent_txid is None
audit_events = [e.event_type for e in (await session.scalars(select(AuditLog))).all()]
assert "utxo_external_spend_reinstated" in audit_events
async def test_reinstate_reappeared_utxos_ignores_unmarked_rows(session_factory, user_id):
entries = [{"tx_hash": "ee" * 32, "tx_pos": 0, "height": 100, "value": 3_000_000}]
async with session_factory() as session:
await credit_confirmed_utxos(session, user_id, entries)
async with session_factory() as session:
spent = await detect_external_spends(session, user_id, entries)
assert spent == 0
user = await session.get(User, user_id)
assert user.cached_balance_sats == 3_000_000
reinstated = await reinstate_reappeared_utxos(session, user_id, entries)
assert reinstated == 0
tests/unit/test_docs_disabled.py
+28
View File
@@ -0,0 +1,28 @@
"""B-42: Swagger/ReDoc/OpenAPI JSON must not be reachable unless explicitly enabled —
they enumerate the whole API surface, admin endpoints included."""
import importlib
from app.config import settings
def _reload_main():
import app.main
return importlib.reload(app.main)
def test_docs_disabled_by_default(monkeypatch):
monkeypatch.setattr(settings, "enable_api_docs", False)
main = _reload_main()
assert main.app.docs_url is None
assert main.app.redoc_url is None
assert main.app.openapi_url is None
def test_docs_enabled_when_configured(monkeypatch):
monkeypatch.setattr(settings, "enable_api_docs", True)
main = _reload_main()
assert main.app.docs_url == "/docs"
assert main.app.redoc_url == "/redoc"
assert main.app.openapi_url == "/openapi.json"
tests/unit/test_docs_no_bare_uvicorn.py
+18
View File
@@ -0,0 +1,18 @@
"""B-44: README and docs/running-the-server.md must not document a bare
`uvicorn --reload` workflow — the server always runs via Docker, in dev and
production alike (CLAUDE.md's "Commands" section), and the two files had
drifted back to contradicting that policy."""
from pathlib import Path
REPO_ROOT = Path(__file__).parent.parent.parent
def test_readme_has_no_bare_uvicorn_command():
readme = (REPO_ROOT / "README.md").read_text()
assert "uvicorn app.main:app --reload" not in readme
def test_running_the_server_doc_has_no_bare_uvicorn_command():
doc = (REPO_ROOT / "docs" / "running-the-server.md").read_text()
assert "uvicorn app.main:app --reload" not in doc
tests/unit/test_draw.py
+40 -9
View File
@@ -1,19 +1,50 @@
import pytest
from app.rounds.draw import draw_winner, header_hex_to_block_hash
from app.rounds.draw import (
draw_winner,
header_hex_to_block_hash,
header_meets_its_own_target,
header_prev_hash,
)
def test_header_hex_to_block_hash_matches_known_mainnet_block():
# Real PLM mainnet block 477486: header from blockchain.block.header, hash
# cross-checked against the blockhash reported by blockchain.transaction.get
# for a tx confirmed in that block.
header_hex = (
# Real PLM mainnet block 477486: header from blockchain.block.header, hash
# cross-checked against the blockhash reported by blockchain.transaction.get for a
# tx confirmed in that block.
_REAL_HEADER_HEX = (
"0020ed30fbc39ee45200d10214f5107c5f36e7bf753032fd1d3279810c170000000000"
"009a4ea723f732be4c538f3a2490837dd6560103d73ece606aa7d578a66700447b28875"
"e6a47a61b1ad8012582"
)
)
def test_header_hex_to_block_hash_matches_known_mainnet_block():
known_block_hash = "00000000000008788b55ade13b74d54ceffda9e54315b802411be1ca65064e86"
assert header_hex_to_block_hash(header_hex) == known_block_hash
assert header_hex_to_block_hash(_REAL_HEADER_HEX) == known_block_hash
def test_header_meets_its_own_target_accepts_a_real_mined_header():
"""B-28: a genuinely mined mainnet header must pass its own self-consistency
check — this isn't just a synthetic-header property."""
assert header_meets_its_own_target(_REAL_HEADER_HEX) is True
def test_header_meets_its_own_target_rejects_a_tampered_header():
"""Flipping a single nonce bit changes the hash completely (avalanche effect)
without changing the claimed difficulty, so a tampered-but-otherwise-real
header should almost certainly fail — this is what would catch a
hostile/MITM'd server replaying a real header with a doctored field."""
tampered = bytearray(bytes.fromhex(_REAL_HEADER_HEX))
tampered[-1] ^= 0xFF # flip the last byte of the nonce
assert header_meets_its_own_target(tampered.hex()) is False
def test_header_meets_its_own_target_rejects_wrong_length():
assert header_meets_its_own_target("aa" * 10) is False
def test_header_prev_hash_matches_the_known_previous_block():
# Block 477486's predecessor, 477485 — independently known from the same chain.
assert header_prev_hash(_REAL_HEADER_HEX) == "000000000000170c8179321dfd323075bfe7365f7c10f51402d10052e49ec3fb"
def test_draw_winner_is_deterministic_and_within_range():
tests/unit/test_electrum_listener.py
+497 -7
View File
@@ -1,5 +1,8 @@
"""Listener-level behaviour: server rotation on failure (the fallback-servers
feature), and the chain-tip monotonicity guard (B-19).
feature), the chain-tip monotonicity guard (B-19), header validation and
multi-server corroboration (B-28), the new-user subscribe task's retention and
error logging (B-30), and bounded-concurrency, non-blocking resubscribe on
reconnect (B-31).
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
@@ -7,13 +10,18 @@ dead connection by moving to the next server instead of retrying the same one.
"""
import asyncio
import logging
import struct
import pytest
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 User, UtxoEvent
from app.electrum.client import ElectrumEndpoint
from app.electrum.listener import ElectrumListener
from app.rounds.draw import HeaderValidationError, header_hex_to_block_hash, header_meets_its_own_target
@pytest.fixture
@@ -31,6 +39,34 @@ _ENDPOINTS = [
ElectrumEndpoint("third.example", 50001, False),
]
# A regtest-style trivial difficulty target (~50% of hashes satisfy it), so mining
# a real, self-consistent test header takes a handful of nonce attempts rather than
# needing actual mainnet-grade hashpower. Not a valid PLM mainnet difficulty —
# irrelevant here, since header_meets_its_own_target only checks self-consistency.
_EASY_BITS = 0x207FFFFF
def _build_header(prev_hash_hex: str, nonce: int, *, bits: int = _EASY_BITS) -> str:
return (
struct.pack("<I", 1) # version
+ bytes.fromhex(prev_hash_hex)[::-1]
+ bytes.fromhex("00" * 32) # merkle_root, irrelevant to the checks under test
+ struct.pack("<I", 0) # timestamp
+ struct.pack("<I", bits)
+ struct.pack("<I", nonce)
).hex()
def _mine_header(prev_hash_hex: str, *, bits: int = _EASY_BITS) -> str:
"""A real header that satisfies its own claimed target — good enough to
exercise header_meets_its_own_target/_apply_header for real, without needing
genuine PLM-mainnet-grade hashpower."""
for nonce in range(100_000):
header_hex = _build_header(prev_hash_hex, nonce, bits=bits)
if header_meets_its_own_target(header_hex):
return header_hex
raise RuntimeError("failed to mine a test header within the attempt budget")
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
@@ -124,6 +160,40 @@ async def test_listener_with_no_endpoints_gives_up_loudly(session_factory):
assert listener.current_endpoint is None
# --- B-30: address_for_new_user's subscribe task must be retained (not fire-and-
# forget) and its failure must be observable, not silently swallowed. -------------
async def test_address_for_new_user_does_nothing_without_a_connection(session_factory):
listener = ElectrumListener(lambda endpoint: None, session_factory, _ENDPOINTS)
listener.address_for_new_user(1, "plm1q0xcqpzrky6eff2g52qdye53xkk9jxkvraxkkwd") # listener.client is None
assert listener._background_tasks == set()
async def test_address_for_new_user_retains_and_logs_a_failed_subscribe_task(session_factory, caplog):
"""Before B-30, this task was fire-and-forget: an AssertionError (self.client
turning None mid-flight) or any other failure vanished into asyncio's default
unretrieved-exception handler instead of being logged anywhere the operator
could see, and nothing kept the task alive in the meantime."""
class FailingClient:
async def subscribe_scripthash(self, scripthash):
raise ConnectionResetError("dropped mid-subscribe")
listener = ElectrumListener(lambda endpoint: None, session_factory, _ENDPOINTS)
listener.client = FailingClient()
listener.address_for_new_user(1, "plm1q0xcqpzrky6eff2g52qdye53xkk9jxkvraxkkwd")
assert len(listener._background_tasks) == 1 # retained while in flight
with caplog.at_level(logging.WARNING):
await asyncio.gather(*list(listener._background_tasks), return_exceptions=True)
await asyncio.sleep(0) # let the done_callbacks (scheduled via call_soon) run
assert listener._background_tasks == set() # discarded once done
assert "could not subscribe" in caplog.text
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
@@ -132,11 +202,431 @@ def test_tip_never_moves_backwards(session_factory):
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")
header_100 = _mine_header("00" * 32)
listener._apply_header({"height": 100, "hex": header_100})
assert (listener.tip_height, listener.tip_header_hex) == (100, header_100)
listener._apply_header({"height": 99, "hex": "bb"}) # reorg, or a server switch
assert (listener.tip_height, listener.tip_header_hex) == (100, "aa")
# A lower height is ignored purely on height, before any header validation even
# runs — reorg or server switch, not a real advance.
listener._apply_header({"height": 99, "hex": "bb"})
assert (listener.tip_height, listener.tip_header_hex) == (100, header_100)
listener._apply_header({"height": 101, "hex": "cc"})
assert (listener.tip_height, listener.tip_header_hex) == (101, "cc")
header_101 = _mine_header(header_hex_to_block_hash(header_100))
listener._apply_header({"height": 101, "hex": header_101})
assert (listener.tip_height, listener.tip_header_hex) == (101, header_101)
# --- B-28: a hostile or MITM'd server can no longer single-handedly decide the
# draw's entropy — header self-consistency/linkage checks, and multi-server
# corroboration for the block the draw actually uses. ---------------------------
def test_apply_header_rejects_one_that_fails_its_own_pow_target(session_factory):
listener = ElectrumListener(lambda endpoint: None, session_factory, _ENDPOINTS)
# Real mainnet-grade difficulty (genesis-era Bitcoin bits): satisfying it by
# chance is astronomically unlikely, so this header is self-inconsistent.
forged = _build_header("00" * 32, nonce=0, bits=0x1D00FFFF)
with pytest.raises(HeaderValidationError):
listener._apply_header({"height": 100, "hex": forged})
assert (listener.tip_height, listener.tip_header_hex) == (0, None) # untouched
def test_apply_header_rejects_one_that_does_not_chain_from_the_tip(session_factory):
listener = ElectrumListener(lambda endpoint: None, session_factory, _ENDPOINTS)
header_100 = _mine_header("00" * 32)
listener._apply_header({"height": 100, "hex": header_100})
# A single-block advance (101 = 100 + 1) whose prev_block claims an unrelated
# chain — well-formed and self-consistently mined, but not actually built on
# top of our current tip.
disconnected = _mine_header("ff" * 32)
with pytest.raises(HeaderValidationError):
listener._apply_header({"height": 101, "hex": disconnected})
assert (listener.tip_height, listener.tip_header_hex) == (100, header_100) # untouched
def test_apply_header_skips_linkage_check_across_a_height_gap(session_factory):
"""A reconnect (or the very first header of a session) hands us whatever the
server's current tip is — which is legitimately not a single-block advance
from whatever we last saw. There's no full header chain to check linkage
against in that case, so only self-consistency is enforced."""
listener = ElectrumListener(lambda endpoint: None, session_factory, _ENDPOINTS)
header_100 = _mine_header("00" * 32)
listener._apply_header({"height": 100, "hex": header_100})
header_150 = _mine_header("ff" * 32) # unrelated prev_block, height jumps by 50
listener._apply_header({"height": 150, "hex": header_150}) # must not raise
assert (listener.tip_height, listener.tip_header_hex) == (150, header_150)
async def _endpoint_client_factory(responses: dict[str, object]):
"""Builds a client_factory whose fake clients answer blockchain.block.header
per-endpoint according to `responses`: a header hex string to agree/disagree
with, `None` to simulate an unreachable server, or an Exception instance to
simulate a request failure."""
class _FakeClient:
def __init__(self, answer):
self._answer = answer
self.closed = False
async def connect(self):
if isinstance(self._answer, Exception):
raise self._answer
async def request(self, method, params):
assert method == "blockchain.block.header"
if self._answer is None:
raise ConnectionRefusedError("unreachable")
return self._answer
async def close(self):
self.closed = True
def factory(endpoint):
return _FakeClient(responses[endpoint.host])
return factory
async def test_corroborate_header_true_with_no_other_servers_configured(session_factory):
single = [ElectrumEndpoint("only.example", 50002, True)]
listener = ElectrumListener(lambda endpoint: None, session_factory, single)
assert await listener.corroborate_header(100, "deadbeef") is True
async def test_corroborate_header_true_when_others_agree(session_factory):
header_hex = _mine_header("00" * 32)
expected_hash = header_hex_to_block_hash(header_hex)
factory = await _endpoint_client_factory(
{"first.example": header_hex, "second.example": header_hex, "third.example": header_hex}
)
listener = ElectrumListener(factory, session_factory, _ENDPOINTS)
assert await listener.corroborate_header(100, expected_hash) is True
async def test_corroborate_header_never_asks_the_currently_active_endpoint(session_factory):
"""The active connection is exactly what a hostile server or a MITM would
control — corroborating against it too would defeat the point."""
header_hex = _mine_header("00" * 32)
expected_hash = header_hex_to_block_hash(header_hex)
# first.example (the active endpoint) would raise if ever queried.
factory = await _endpoint_client_factory(
{"first.example": RuntimeError("must not be called"), "second.example": header_hex, "third.example": header_hex}
)
listener = ElectrumListener(factory, session_factory, _ENDPOINTS)
assert listener.current_endpoint.host == "first.example"
assert await listener.corroborate_header(100, expected_hash) is True
async def test_corroborate_header_false_when_majority_disagrees(session_factory):
header_hex = _mine_header("00" * 32)
expected_hash = header_hex_to_block_hash(header_hex)
disagreeing_hex = _mine_header("11" * 32)
factory = await _endpoint_client_factory(
{"first.example": header_hex, "second.example": disagreeing_hex, "third.example": disagreeing_hex}
)
listener = ElectrumListener(factory, session_factory, _ENDPOINTS)
assert await listener.corroborate_header(100, expected_hash) is False
async def test_corroborate_header_false_when_nobody_responds(session_factory):
factory = await _endpoint_client_factory(
{"first.example": "irrelevant", "second.example": None, "third.example": ConnectionRefusedError("down")}
)
listener = ElectrumListener(factory, session_factory, _ENDPOINTS)
assert await listener.corroborate_header(100, "deadbeef") is False
# --- B-29: a UTXO absent from our own connection's listunspent must be
# corroborated by other configured servers before it's treated as genuinely spent
# outside the platform. ------------------------------------------------------------
async def _listunspent_client_factory(responses: dict[str, object]):
"""Builds a client_factory whose fake clients answer listunspent per-endpoint:
a list of entries to report as unspent, `None` to simulate an unreachable
server (fails at listunspent), or an Exception instance to simulate a connect
failure."""
class _FakeClient:
def __init__(self, answer):
self._answer = answer
async def connect(self):
if isinstance(self._answer, Exception):
raise self._answer
async def listunspent(self, scripthash):
if self._answer is None:
raise ConnectionRefusedError("unreachable")
return self._answer
async def close(self):
pass
def factory(endpoint):
return _FakeClient(responses[endpoint.host])
return factory
async def test_corroborate_utxo_spent_true_with_no_other_servers_configured(session_factory):
single = [ElectrumEndpoint("only.example", 50002, True)]
listener = ElectrumListener(lambda endpoint: None, session_factory, single)
assert await listener.corroborate_utxo_spent("scripthash", "dd" * 32, 0) is True
async def test_corroborate_utxo_spent_true_when_others_agree_its_gone(session_factory):
factory = await _listunspent_client_factory({"first.example": [], "second.example": [], "third.example": []})
listener = ElectrumListener(factory, session_factory, _ENDPOINTS)
assert await listener.corroborate_utxo_spent("scripthash", "dd" * 32, 0) is True
async def test_corroborate_utxo_spent_false_when_majority_still_see_it_unspent(session_factory):
still_there = [{"tx_hash": "dd" * 32, "tx_pos": 0}]
factory = await _listunspent_client_factory(
{"first.example": [], "second.example": still_there, "third.example": still_there}
)
listener = ElectrumListener(factory, session_factory, _ENDPOINTS)
assert await listener.corroborate_utxo_spent("scripthash", "dd" * 32, 0) is False
async def test_corroborate_utxo_spent_false_when_nobody_responds(session_factory):
factory = await _listunspent_client_factory(
{"first.example": [], "second.example": None, "third.example": ConnectionRefusedError("down")}
)
listener = ElectrumListener(factory, session_factory, _ENDPOINTS)
assert await listener.corroborate_utxo_spent("scripthash", "dd" * 32, 0) is False
class _ActiveClient:
"""Stands in for `self.client`, the listener's one active connection —
refresh_user only ever calls listunspent on it."""
def __init__(self, entries: list[dict]):
self._entries = entries
async def listunspent(self, scripthash):
return self._entries
async def _seed_funded_user(session_factory, *, username: str, address: str) -> int:
from app.wallet.balance import recompute_balance
async with session_factory() as session:
user = User(username=username, password_hash="x", derivation_index=0, address=address)
session.add(user)
await session.commit()
session.add(
UtxoEvent(user_id=user.id, txid="dd" * 32, vout=0, amount_sats=20_000_000, confirmed_height=100)
)
await recompute_balance(session, user.id)
await session.commit()
return user.id
# An unrelated outpoint present alongside our own connection's listunspent reply —
# keeps `entries` non-empty so find_utxos_missing_from's "entirely empty response"
# guard doesn't swallow these tests; our own tracked UTXO is still genuinely
# absent from it.
_UNRELATED_ENTRY = [{"tx_hash": "99" * 32, "tx_pos": 0, "height": 100, "value": 1_000_000}]
async def test_refresh_user_marks_a_utxo_spent_once_others_corroborate_it(session_factory):
user_id = await _seed_funded_user(session_factory, username="bob", address="plm1q0xcqpzrky6eff2g52qdye53xkk9jxkvraxkkwd")
others_factory = await _listunspent_client_factory(
{"first.example": [], "second.example": [], "third.example": []}
)
listener = ElectrumListener(others_factory, session_factory, _ENDPOINTS)
listener.client = _ActiveClient(_UNRELATED_ENTRY) # our own connection no longer sees the UTXO either
await listener.refresh_user(user_id, "scripthash")
async with session_factory() as session:
utxo = (
await session.scalars(select(UtxoEvent).where(UtxoEvent.user_id == user_id, UtxoEvent.txid == "dd" * 32))
).one()
assert utxo.spent_txid == "external-spend"
user = await session.get(User, user_id)
# The original 20_000_000 is spent; the unrelated entry the "active"
# connection also reported gets freshly credited alongside it.
assert user.cached_balance_sats == 1_000_000
async def test_refresh_user_does_not_mark_when_corroboration_fails(session_factory):
"""The single most important case: our own connection alone reporting the
UTXO missing must not be enough — before B-29 this zeroed the balance on one
bad reply."""
user_id = await _seed_funded_user(session_factory, username="carol", address="plm1qtest2")
still_there = [{"tx_hash": "dd" * 32, "tx_pos": 0}]
others_factory = await _listunspent_client_factory(
{"first.example": [], "second.example": still_there, "third.example": still_there}
)
listener = ElectrumListener(others_factory, session_factory, _ENDPOINTS)
listener.client = _ActiveClient(_UNRELATED_ENTRY)
await listener.refresh_user(user_id, "scripthash")
async with session_factory() as session:
utxo = (
await session.scalars(select(UtxoEvent).where(UtxoEvent.user_id == user_id, UtxoEvent.txid == "dd" * 32))
).one()
assert utxo.spent_txid is None
user = await session.get(User, user_id)
# Untouched, plus the unrelated entry credited alongside it.
assert user.cached_balance_sats == 21_000_000
# --- B-31: resubscribing on reconnect must be bounded-concurrency and must not
# block tip updates (and so an in-flight draw) for its entire duration. -----------
def _fake_address(i: int) -> str:
"""A real, decodable PLM bech32 P2WPKH address (address_to_scripthash
actually parses it) — distinct per index, since User.address is unique."""
from embit import script
from app.wallet.plm_network import PLM_MAINNET
payload = (i + 1).to_bytes(20, "big")
return script.Script(b"\x00\x14" + payload).address(network=PLM_MAINNET)
async def _seed_users(session_factory, count: int) -> None:
async with session_factory() as session:
for i in range(count):
session.add(
User(username=f"user{i}", password_hash="x", derivation_index=i, address=_fake_address(i))
)
await session.commit()
async def test_subscribe_all_users_bounds_concurrency(session_factory):
"""B-31: at thousands of users, subscribing one at a time meant thousands of
sequential round-trips. Concurrency must be bounded (not unlimited either —
a huge user base shouldn't open thousands of simultaneous requests)."""
user_count = 45
await _seed_users(session_factory, user_count)
listener = ElectrumListener(lambda endpoint: None, session_factory, _ENDPOINTS)
in_flight = 0
max_in_flight = 0
calls = []
async def fake_subscribe_and_refresh(scripthash, user_id):
nonlocal in_flight, max_in_flight
in_flight += 1
max_in_flight = max(max_in_flight, in_flight)
calls.append(user_id)
await asyncio.sleep(0) # yield, so genuinely-concurrent calls interleave
in_flight -= 1
listener._subscribe_and_refresh = fake_subscribe_and_refresh
await listener._subscribe_all_users()
assert len(calls) == user_count
assert 1 < max_in_flight <= 20 # bounded, and actually concurrent (not serial)
async def test_subscribe_all_users_continues_past_a_failing_user(session_factory):
await _seed_users(session_factory, 5)
listener = ElectrumListener(lambda endpoint: None, session_factory, _ENDPOINTS)
succeeded = []
async def flaky_subscribe_and_refresh(scripthash, user_id):
if user_id == 3:
raise ConnectionResetError("dropped mid-subscribe")
succeeded.append(user_id)
listener._subscribe_and_refresh = flaky_subscribe_and_refresh
await listener._subscribe_all_users() # must not raise
assert succeeded == [1, 2, 4, 5]
class _FakeConnectClient:
"""A minimally-real ElectrumClient double: enough of connect/subscribe/notify/
ping/wait_closed/close to drive ElectrumListener._run_once end-to-end."""
def __init__(self, header: dict):
self._header = header
self._queues: dict[str, asyncio.Queue] = {}
self._closed = asyncio.Event()
async def connect(self):
pass
async def subscribe_headers(self):
return self._header
def notifications(self, method: str) -> asyncio.Queue:
return self._queues.setdefault(method, asyncio.Queue())
async def ping(self):
pass
async def wait_closed(self):
await self._closed.wait()
async def close(self):
self._closed.set()
async def _wait_until(predicate, *, timeout: float = 2.0, interval: float = 0.01) -> None:
async def _poll():
while not predicate():
await asyncio.sleep(interval)
await asyncio.wait_for(_poll(), timeout=timeout)
async def test_run_once_keeps_consuming_headers_while_resubscribing(session_factory):
"""The core B-31 fix: before this, _subscribe_all_users ran to completion
*before* the header-consuming task even started, so a reconnect with many
users froze tip_height — and so _wait_for_next_block's draw wait — for the
entire resubscribe. It must now keep advancing while resubscribing is still
in flight."""
await _seed_users(session_factory, 3)
header_hex = _mine_header("00" * 32)
client = _FakeConnectClient({"height": 100, "hex": header_hex})
listener = ElectrumListener(lambda endpoint: client, session_factory, _ENDPOINTS)
subscribe_started = asyncio.Event()
async def blocked_subscribe_and_refresh(scripthash, user_id):
subscribe_started.set()
await asyncio.sleep(3600) # simulates a slow sweep; cancelled on cleanup
listener._subscribe_and_refresh = blocked_subscribe_and_refresh
run_once_task = asyncio.create_task(listener._run_once(_ENDPOINTS[0]))
try:
await asyncio.wait_for(subscribe_started.wait(), timeout=2)
# Resubscribing is still stuck mid-flight — but a new tip must still be
# processed, proving the header consumer isn't blocked behind it.
headers_queue = client.notifications("blockchain.headers.subscribe")
next_header_hex = _mine_header(header_hex_to_block_hash(header_hex))
await headers_queue.put([{"height": 101, "hex": next_header_hex}])
await _wait_until(lambda: listener.tip_height == 101)
assert listener.tip_header_hex == next_header_hex
finally:
await client.close()
await run_once_task
tests/unit/test_models_text_columns.py
+16
View File
@@ -0,0 +1,16 @@
"""B-47: raw_tx_hex (a full raw signed transaction hex) and payload_json (an
arbitrary audit payload) must stay `Text`, not a bare `String`/`VARCHAR` with
no length -- SQLite and PostgreSQL accept that, but other backends (e.g.
MySQL) require a length on VARCHAR and would reject it."""
from sqlalchemy import Text
from app.db.models import AuditLog, PendingTransaction
def test_pending_transaction_raw_tx_hex_is_text():
assert isinstance(PendingTransaction.__table__.c.raw_tx_hex.type, Text)
def test_audit_log_payload_json_is_text():
assert isinstance(AuditLog.__table__.c.payload_json.type, Text)
tests/unit/test_pending_address.py
+55
View File
@@ -0,0 +1,55 @@
"""B-41: own_address_for is the single place tx/confirmation.py and
tx/reconcile.py derive a PendingTransaction's own address from — a payout's
address must always be the pool's, everything else the actual user's."""
import pytest
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 User
from app.tx.pending_address import own_address_for
@pytest.fixture
async def session_factory(tmp_path, monkeypatch):
monkeypatch.setattr(settings, "master_key_path", str(tmp_path / "master.xprv.enc"))
monkeypatch.setattr(
settings,
"xprv_encryption_key",
__import__("cryptography.fernet", fromlist=["Fernet"]).Fernet.generate_key().decode(),
)
from app.wallet import hd
hd._account_key = None
hd.generate_master_key()
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()
hd._account_key = None
async def test_payout_uses_the_pool_address_regardless_of_user_id(session_factory):
from app.wallet.hd import derive_pool_address
async with session_factory() as session:
address = await own_address_for(session, "payout", None)
assert address == derive_pool_address()
@pytest.mark.parametrize("kind", ["bet", "withdrawal"])
async def test_bet_and_withdrawal_use_the_users_own_address(session_factory, kind):
from app.wallet.hd import derive_user_address
async with session_factory() as session:
user = User(username="alice", password_hash="x", derivation_index=3, address=derive_user_address(3))
session.add(user)
await session.flush()
address = await own_address_for(session, kind, user.id)
assert address == derive_user_address(3)
tests/unit/test_psbt_builder.py
+17
View File
@@ -5,6 +5,7 @@ from embit.transaction import Transaction
from app.wallet.plm_network import PLM_MAINNET
from app.wallet.psbt_builder import (
MAX_TX_INPUTS,
InsufficientFundsError,
Utxo,
build_signed_transaction,
@@ -36,6 +37,22 @@ def test_select_utxos_raises_when_insufficient():
select_utxos(utxos, target_sats=10_000_000)
def test_select_utxos_never_exceeds_the_input_cap(): # B-48
# 200 dust-ish UTXOs that together cover the target, but only past the cap.
utxos = [Utxo(f"{i:064x}", 0, 100_000) for i in range(200)]
with pytest.raises(InsufficientFundsError) as excinfo:
select_utxos(utxos, target_sats=100_000 * MAX_TX_INPUTS + 1)
assert excinfo.value.code == "too_many_inputs"
assert excinfo.value.params == {"max_inputs": MAX_TX_INPUTS}
def test_select_utxos_allows_exactly_the_input_cap():
utxos = [Utxo(f"{i:064x}", 0, 100_000) for i in range(200)]
selected, total = select_utxos(utxos, target_sats=100_000 * MAX_TX_INPUTS)
assert len(selected) == MAX_TX_INPUTS
assert total == 100_000 * MAX_TX_INPUTS
def test_build_signed_transaction_deducts_fee_from_amount_not_change():
signer = _key(1)
from_script = script.p2wpkh(signer.to_public())
tests/unit/test_reconcile.py
+122 -12
View File
@@ -1,5 +1,10 @@
"""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."""
never made it onto the chain must give the coins back instead of freezing them.
Also covers B-41: existence/reconciliation checks go through
blockchain.scripthash.get_history rather than a verbose blockchain.transaction.get
reply, so the fake clients below implement get_history.
"""
import pytest
from embit import script
@@ -7,37 +12,60 @@ from embit.transaction import Transaction, TransactionInput, TransactionOutput
from sqlalchemy import select
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 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."""
"""A server whose history for any address never includes our txid."""
async def get_transaction(self, txid: str, verbose: bool = False):
raise RuntimeError(f"missing transaction {txid}")
async def get_history(self, scripthash: str) -> list[dict]:
return []
class KnownTxClient:
async def get_transaction(self, txid: str, verbose: bool = False):
return {"txid": txid, "confirmations": 0}
"""A server whose history for the address includes our txid — mined or
still in the mempool doesn't matter for existence, only for confirmation
(which is tx/confirmation.py's concern, not reconcile.py's)."""
def __init__(self, txid: str = "betxid"):
self._txid = txid
async def get_history(self, scripthash: str) -> list[dict]:
return [{"tx_hash": self._txid, "height": 100}]
class BrokenClient:
"""A transport failure — says nothing about whether the tx exists."""
async def get_transaction(self, txid: str, verbose: bool = False):
async def get_history(self, scripthash: str) -> list[dict]:
raise ConnectionResetError("connection reset")
@pytest.fixture
async def session_factory():
async def session_factory(tmp_path, monkeypatch):
# own_address_for (B-41) derives each row's address via the HD wallet rather
# than trusting the DB's address column, so reconcile_once now needs a real
# master key set up — same bootstrap test_broadcast.py uses.
monkeypatch.setattr(settings, "master_key_path", str(tmp_path / "master.xprv.enc"))
monkeypatch.setattr(
settings,
"xprv_encryption_key",
__import__("cryptography.fernet", fromlist=["Fernet"]).Fernet.generate_key().decode(),
)
from app.wallet import hd
hd._account_key = None
hd.generate_master_key()
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()
hd._account_key = None
# A real (unsigned) transaction spending one input, built rather than hand-written
@@ -59,11 +87,26 @@ _RAW_TX = (
)
async def _seed_bet(session_factory, *, pending_status: str, participant_status: str, age_seconds: int):
async def _seed_bet(
session_factory,
*,
pending_status: str,
participant_status: str,
age_seconds: int,
last_broadcast_age_seconds: int | None = None,
derivation_index: int = 0,
):
from datetime import datetime, timedelta, timezone
from app.wallet.hd import derive_user_address
async with session_factory() as session:
user = User(username="u", password_hash="x", derivation_index=0, address="plm1qtest")
user = User(
username="u",
password_hash="x",
derivation_index=derivation_index,
address=derive_user_address(derivation_index),
)
session.add(user)
await session.flush()
session.add(
@@ -85,6 +128,10 @@ async def _seed_bet(session_factory, *, pending_status: str, participant_status:
status=participant_status,
)
)
# last_broadcast_age_seconds defaults to age_seconds (never bumped): the two
# timestamps only diverge in the B-27 regression test below, which simulates
# a tx that's been bumped recently but first appeared long ago.
last_age = age_seconds if last_broadcast_age_seconds is None else last_broadcast_age_seconds
session.add(
PendingTransaction(
kind="bet",
@@ -95,6 +142,7 @@ async def _seed_bet(session_factory, *, pending_status: str, participant_status:
raw_tx_hex=_RAW_TX,
status=pending_status,
broadcast_at=datetime.now(timezone.utc) - timedelta(seconds=age_seconds),
last_broadcast_at=datetime.now(timezone.utc) - timedelta(seconds=last_age),
)
)
await session.commit()
@@ -133,7 +181,7 @@ async def test_promotes_a_building_row_whose_tx_did_reach_the_chain(session_fact
session_factory, pending_status="building", participant_status="building", age_seconds=300
)
resolved = await reconcile_once(session_factory, KnownTxClient())
resolved = await reconcile_once(session_factory, KnownTxClient("betxid"))
assert resolved == 1
async with session_factory() as session:
@@ -167,6 +215,27 @@ async def test_leaves_a_recently_broadcast_pending_row_alone(session_factory):
assert await reconcile_once(session_factory, UnknownTxClient()) == 0
async def test_abandons_a_repeatedly_bumped_tx_despite_a_recent_last_broadcast(session_factory):
"""B-27 regression: before last_broadcast_at existed, bump_fee overwrote
broadcast_at on every bump, which is the same field the abandon grace period is
measured from — so a tx first seen long ago but bumped minutes ago (exactly what
a stuck-but-repeatedly-bumped tx looks like) reset its own clock forever and was
never abandoned. The reconciler must still abandon it based on when it *first*
appeared, ignoring how recently it was last bumped."""
await _seed_bet(
session_factory,
pending_status="pending",
participant_status="broadcast",
age_seconds=7 * 3600, # first broadcast 7h ago — past the 6h abandon window
last_broadcast_age_seconds=60, # bumped a minute ago
)
assert await reconcile_once(session_factory, UnknownTxClient()) == 1
async with session_factory() as session:
assert (await session.scalars(select(PendingTransaction))).one().status == "failed"
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."""
@@ -186,8 +255,10 @@ async def test_abandoned_withdrawal_is_marked_failed_and_kept(session_factory):
they can see it didn't go through."""
from datetime import datetime, timedelta, timezone
from app.wallet.hd import derive_user_address
async with session_factory() as session:
user = User(username="w", password_hash="x", derivation_index=1, address="plm1qtest2")
user = User(username="w", password_hash="x", derivation_index=1, address=derive_user_address(1))
session.add(user)
await session.flush()
session.add(
@@ -231,3 +302,42 @@ async def test_abandoned_withdrawal_is_marked_failed_and_kept(session_factory):
assert withdrawal.status == "failed"
assert withdrawal.txid is None
assert (await session.scalars(select(UtxoEvent))).one().spent_txid is None
# --- B-41: existence checks now use get_history and share it across candidates
# sharing the same address, instead of a per-tx verbose blockchain.transaction.get. --
async def test_reconcile_once_caches_history_per_scripthash(session_factory):
"""Two payout PendingTransaction rows always share the same pool address —
fetching its history twice in one pass would be wasteful and, at scale
across many candidates on one address, needlessly slow the whole tick."""
from datetime import datetime, timedelta, timezone
async with session_factory() as session:
old = datetime.now(timezone.utc) - timedelta(hours=7)
session.add(
PendingTransaction(
kind="payout", round_id=1, current_txid="payout-a", fee_rate_sat_vb=1,
raw_tx_hex=_RAW_TX, status="pending", broadcast_at=old, last_broadcast_at=old,
)
)
session.add(
PendingTransaction(
kind="payout", round_id=2, current_txid="payout-b", fee_rate_sat_vb=1,
raw_tx_hex=_RAW_TX, status="pending", broadcast_at=old, last_broadcast_at=old,
)
)
await session.commit()
call_count = {"n": 0}
class CountingClient:
async def get_history(self, scripthash: str) -> list[dict]:
call_count["n"] += 1
return [{"tx_hash": "payout-a", "height": 100}, {"tx_hash": "payout-b", "height": 100}]
resolved = await reconcile_once(session_factory, CountingClient())
assert resolved == 0 # both exist — nothing to abandon or promote (already "pending")
assert call_count["n"] == 1 # one call covered both rows sharing the pool address
tests/unit/test_round_events.py
+69 -1
View File
@@ -2,7 +2,7 @@ import asyncio
import pytest
from app.rounds.events import RoundEventBroadcaster, RoundEventCapacityError
from app.rounds.events import EVICTED, RoundEventBroadcaster, RoundEventCapacityError
async def test_publish_wakes_up_subscriber():
@@ -60,3 +60,71 @@ async def test_unsubscribe_frees_a_capacity_slot():
broadcaster.unsubscribe(queue)
broadcaster.subscribe() # no longer at capacity
# --- B-38: a single IP must not be able to exhaust the global cap and degrade
# every other user to polling. ----------------------------------------------------
async def test_subscribe_evicts_the_same_ips_oldest_connection_past_its_cap():
"""Past MAX_SUBSCRIBERS_PER_IP, one more stream from the *same* IP evicts
that IP's own oldest connection rather than being refused — bounds one
source's footprint without an outright block."""
broadcaster = RoundEventBroadcaster(max_subscribers=100, max_per_ip=2)
first = broadcaster.subscribe("1.2.3.4")
second = broadcaster.subscribe("1.2.3.4")
third = broadcaster.subscribe("1.2.3.4") # past the per-IP cap of 2
assert await asyncio.wait_for(first.get(), timeout=1) is EVICTED
assert second.empty() # untouched — only the oldest was evicted
assert third is not None
async def test_subscribe_does_not_evict_across_different_ips():
"""A different IP hitting its own cap must never evict an unrelated IP's
connection — that would let one abusive source crowd out real users, which
is exactly what the global-only cap used to allow."""
broadcaster = RoundEventBroadcaster(max_subscribers=100, max_per_ip=1)
other_ip_queue = broadcaster.subscribe("9.9.9.9")
broadcaster.subscribe("1.2.3.4")
broadcaster.subscribe("1.2.3.4") # evicts 1.2.3.4's own oldest, not 9.9.9.9's
assert other_ip_queue.empty()
async def test_subscribe_still_enforces_the_global_cap_across_many_ips():
"""The per-IP cap doesn't replace the global backstop — spreading across
enough distinct IPs must still eventually hit MAX_SUBSCRIBERS."""
broadcaster = RoundEventBroadcaster(max_subscribers=3, max_per_ip=1)
broadcaster.subscribe("1.1.1.1")
broadcaster.subscribe("2.2.2.2")
broadcaster.subscribe("3.3.3.3")
with pytest.raises(RoundEventCapacityError):
broadcaster.subscribe("4.4.4.4")
async def test_unsubscribe_clears_the_per_ip_tracking_too():
"""Regression guard: unsubscribe must forget the queue's IP association, or
a churned-through connection would keep counting against that IP's cap
forever."""
broadcaster = RoundEventBroadcaster(max_subscribers=100, max_per_ip=1)
queue = broadcaster.subscribe("1.2.3.4")
broadcaster.unsubscribe(queue)
broadcaster.subscribe("1.2.3.4") # must not evict anything — nothing left to evict
assert queue.empty()
async def test_subscribe_defaults_to_a_shared_ip_when_none_given():
"""Existing callers (and most tests) that don't care about IP isolation
still share one implicit bucket rather than needing every call updated."""
broadcaster = RoundEventBroadcaster(max_subscribers=100, max_per_ip=2)
first = broadcaster.subscribe()
broadcaster.subscribe()
broadcaster.subscribe() # past the default bucket's cap of 2 — evicts, doesn't raise
assert await asyncio.wait_for(first.get(), timeout=1) is EVICTED
tests/unit/test_rounds_route.py
+30
View File
@@ -134,6 +134,36 @@ async def test_jackpot_comes_from_the_participants_actual_bets(client):
assert body["jackpot_sats"] == (999_800_000 * 2) * 70 // 100
async def test_draw_waiting_since_is_exposed_only_while_drawing(client):
"""B-36: the "drawing" wait on a future block has no timeout, so the frontend
needs draw_waiting_since to show "still waiting" instead of implying a bounded
countdown. It must not leak for any other status, where it's meaningless."""
from datetime import datetime, timezone
from app.db.models import Round, RoundConfig
ac, session_factory = client
started_at = datetime(2026, 7, 27, 10, 0, 0)
async with session_factory() as session:
session.add(RoundConfig(fee_address=""))
session.add(Round(id=60, status="drawing", drawing_started_at=started_at))
await session.commit()
body = (await ac.get("/rounds/current")).json()
assert body["draw_waiting_since"] == "2026-07-27T10:00:00+00:00"
async with session_factory() as session:
from sqlalchemy import select
round_ = (await session.scalars(select(Round).where(Round.id == 60))).one()
round_.status = "paying_out"
await session.commit()
body = (await ac.get("/rounds/current")).json()
assert body["draw_waiting_since"] is None
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
tests/unit/test_scheduler.py
+407 -2
View File
@@ -4,9 +4,10 @@ import pytest
from sqlalchemy import select
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 Round, RoundConfig
from app.rounds.scheduler import RoundScheduler
from app.db.models import AuditLog, PendingTransaction, Round, RoundConfig, User
from app.rounds.scheduler import RoundScheduler, _reserved_payout_outpoints
class FakeListener:
@@ -52,3 +53,407 @@ async def test_tick_closes_round_with_no_participants_once_due(session_factory,
async with session_factory() as session:
round_ = (await session.scalars(select(Round))).one()
assert round_.status == "closed"
# --- B-25: the payout must be persisted before it is broadcast, like bets/withdrawals ---
# A real, reusable PLM bech32 address so build_payout_transaction's
# script.Script.from_address(...) succeeds — this is not a value the scheduler
# validates itself (that's the admin panel's job for fee_address), it just needs to
# actually decode.
_WINNER_ADDRESS = "plm1q0xcqpzrky6eff2g52qdye53xkk9jxkvraxkkwd"
_FEE_ADDRESS = "plm1q5x25wd6q463mfhckjraaedgjg0lyu73qfcj43n"
_POOL_AMOUNT_SATS = 10_000_000_000 # 100 PLM
class FakePayoutClient:
def __init__(self, entries, *, fail_broadcast=False):
self._entries = entries
self._fail_broadcast = fail_broadcast
self.broadcasted: list[str] = []
async def listunspent(self, scripthash):
return self._entries
async def broadcast(self, raw_tx_hex):
if self._fail_broadcast:
raise RuntimeError("node rejected the transaction")
self.broadcasted.append(raw_tx_hex)
return "network-txid"
class FakePayoutListener:
def __init__(self, client):
self.client = client
@pytest.fixture
async def payout_session_factory(tmp_path, monkeypatch):
"""Same master-key bootstrap as test_broadcast.py's fixture: _trigger_payout
needs a real pool key to sign with."""
monkeypatch.setattr(settings, "master_key_path", str(tmp_path / "master.xprv.enc"))
monkeypatch.setattr(
settings,
"xprv_encryption_key",
__import__("cryptography.fernet", fromlist=["Fernet"]).Fernet.generate_key().decode(),
)
from app.wallet import hd
hd._account_key = None
hd.generate_master_key()
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()
hd._account_key = None
async def _seed_paying_out_round(session_factory, round_id: int = 1) -> int:
async with session_factory() as session:
winner = User(username="winner", password_hash="x", derivation_index=0, address=_WINNER_ADDRESS)
session.add(winner)
await session.flush()
session.add(RoundConfig(fee_address=_FEE_ADDRESS, fee_rate_sat_vb=1))
session.add(
Round(
id=round_id,
status="paying_out",
pool_amount_sats=_POOL_AMOUNT_SATS,
winner_user_id=winner.id,
)
)
await session.commit()
return winner.id
async def test_trigger_payout_persists_before_broadcasting(payout_session_factory):
"""The happy path: payout_txid and a PendingTransaction must exist once the
broadcast succeeds, promoted from "building" to "pending" — the two-phase write
that used to be missing entirely (B-25)."""
await _seed_paying_out_round(payout_session_factory)
entries = [{"tx_hash": "33" * 32, "tx_pos": 0, "height": 10, "value": _POOL_AMOUNT_SATS + 100_000}]
client = FakePayoutClient(entries)
scheduler = RoundScheduler(payout_session_factory, FakePayoutListener(client))
await scheduler._trigger_payout(1)
assert client.broadcasted
async with payout_session_factory() as session:
round_ = await session.get(Round, 1)
assert round_.payout_txid is not None
assert round_.winner_amount_sats and round_.fee_amount_sats
pending = (await session.scalars(select(PendingTransaction))).one()
assert pending.kind == "payout"
assert pending.status == "pending"
assert pending.current_txid == round_.payout_txid
events = [e.event_type for e in (await session.scalars(select(AuditLog))).all()]
assert "payout_sent" in events
async def test_trigger_payout_broadcast_failure_leaves_a_recoverable_row(payout_session_factory):
"""Before B-25, a broadcast rejection here left nothing behind — no payout_txid,
no PendingTransaction — because everything was persisted only after the
broadcast. Now the intent is already durable, so the reconciler has something to
resolve instead of the round being stuck with zero trace of what was attempted."""
await _seed_paying_out_round(payout_session_factory)
entries = [{"tx_hash": "44" * 32, "tx_pos": 0, "height": 10, "value": _POOL_AMOUNT_SATS + 100_000}]
client = FakePayoutClient(entries, fail_broadcast=True)
scheduler = RoundScheduler(payout_session_factory, FakePayoutListener(client))
await scheduler._trigger_payout(1)
assert not client.broadcasted
async with payout_session_factory() as session:
round_ = await session.get(Round, 1)
assert round_.payout_txid is not None # durable, even though the broadcast failed
pending = (await session.scalars(select(PendingTransaction))).one()
assert pending.kind == "payout"
assert pending.status == "building" # not lost — the reconciler resolves this
assert pending.current_txid == round_.payout_txid
events = [e.event_type for e in (await session.scalars(select(AuditLog))).all()]
assert "payout_failed" in events
async def test_trigger_payout_skips_when_already_in_flight(payout_session_factory):
"""A second call for a round that already has a non-terminal payout
PendingTransaction must not build (and broadcast) another one — that would pay
the winner twice."""
winner_id = await _seed_paying_out_round(payout_session_factory)
async with payout_session_factory() as session:
round_ = await session.get(Round, 1)
round_.payout_txid = "already-sent-txid"
session.add(
PendingTransaction(
kind="payout",
round_id=1,
current_txid="already-sent-txid",
fee_rate_sat_vb=1,
raw_tx_hex="00",
status="pending",
)
)
await session.commit()
entries = [{"tx_hash": "55" * 32, "tx_pos": 0, "height": 10, "value": _POOL_AMOUNT_SATS + 100_000}]
client = FakePayoutClient(entries)
scheduler = RoundScheduler(payout_session_factory, FakePayoutListener(client))
await scheduler._trigger_payout(1)
assert not client.broadcasted
async with payout_session_factory() as session:
assert (await session.scalars(select(PendingTransaction))).all() # still just the one seeded
rows = (await session.scalars(select(PendingTransaction))).all()
assert len(rows) == 1
assert rows[0].current_txid == "already-sent-txid"
async def test_reserved_payout_outpoints_excludes_utxos_claimed_by_a_stale_payout(payout_session_factory):
"""A payout still "building"/"pending" for some round — most plausibly a stale
one the reconciler hasn't abandoned yet — must keep its inputs off the table for
a fresh payout attempt, or the same pool coins could be spent twice."""
from embit import script
from embit.transaction import Transaction, TransactionInput, TransactionOutput
reserved_txid = "66" * 32
raw_tx = (
Transaction(
vin=[TransactionInput(bytes.fromhex(reserved_txid), 2)],
vout=[TransactionOutput(1_000_000, script.Script.from_address(_WINNER_ADDRESS))],
)
.serialize()
.hex()
)
async with payout_session_factory() as session:
session.add(
PendingTransaction(
kind="payout",
round_id=99,
current_txid="stale-payout-txid",
fee_rate_sat_vb=1,
raw_tx_hex=raw_tx,
status="building",
)
)
await session.commit()
reserved = await _reserved_payout_outpoints(session)
assert reserved == {(reserved_txid, 2)}
# --- B-26: a "paying_out" round must retry its payout automatically ---------------
async def test_trigger_payout_logs_a_failure_when_not_connected(payout_session_factory):
"""Before B-26, this early return logged nothing beyond a log line — invisible
in /admin and unusable as a signal for an automatic retry."""
await _seed_paying_out_round(payout_session_factory)
scheduler = RoundScheduler(payout_session_factory, FakePayoutListener(client=None))
await scheduler._trigger_payout(1)
async with payout_session_factory() as session:
entries = (await session.scalars(select(AuditLog).where(AuditLog.event_type == "payout_failed"))).all()
assert len(entries) == 1
assert entries[0].payload_json.count("electrum client not connected") == 1
async def test_trigger_payout_logs_a_failure_when_fee_address_missing(payout_session_factory):
winner_id = await _seed_paying_out_round(payout_session_factory)
async with payout_session_factory() as session:
config = (await session.scalars(select(RoundConfig))).one()
config.fee_address = ""
await session.commit()
entries = [{"tx_hash": "77" * 32, "tx_pos": 0, "height": 10, "value": _POOL_AMOUNT_SATS + 100_000}]
scheduler = RoundScheduler(payout_session_factory, FakePayoutListener(FakePayoutClient(entries)))
await scheduler._trigger_payout(1)
async with payout_session_factory() as session:
entry = (await session.scalars(select(AuditLog).where(AuditLog.event_type == "payout_failed"))).one()
assert "no fee_address configured" in entry.payload_json
assert entry.user_id == winner_id
async def test_tick_retries_a_stuck_paying_out_round_with_no_recent_failure(payout_session_factory):
"""The scenario B-26 exists for: a round stuck in "paying_out" (a prior failure,
or a process restart mid-payout) with no non-terminal PendingTransaction. A
fresh tick must retry rather than leaving it wedged forever."""
await _seed_paying_out_round(payout_session_factory)
entries = [{"tx_hash": "88" * 32, "tx_pos": 0, "height": 10, "value": _POOL_AMOUNT_SATS + 100_000}]
client = FakePayoutClient(entries)
scheduler = RoundScheduler(payout_session_factory, FakePayoutListener(client))
await scheduler._tick()
assert client.broadcasted
async with payout_session_factory() as session:
round_ = await session.get(Round, 1)
assert round_.payout_txid is not None
pending = (await session.scalars(select(PendingTransaction))).one()
assert pending.status == "pending"
async def test_tick_throttles_retry_after_a_recent_payout_failure(payout_session_factory):
"""A payout that just failed must not be retried on the very next tick, or a
persistently-broken payout (e.g. no fee_address) would spam a retry — and a
fresh payout_failed audit entry — every _TICK_INTERVAL_SECONDS."""
await _seed_paying_out_round(payout_session_factory)
async with payout_session_factory() as session:
session.add(
AuditLog(
event_type="payout_failed",
payload_json='{"round_id": 1, "reason": "insufficient pool UTXOs"}',
round_id=1,
created_at=datetime.now(timezone.utc),
)
)
await session.commit()
entries = [{"tx_hash": "99" * 32, "tx_pos": 0, "height": 10, "value": _POOL_AMOUNT_SATS + 100_000}]
client = FakePayoutClient(entries)
scheduler = RoundScheduler(payout_session_factory, FakePayoutListener(client))
await scheduler._tick()
assert not client.broadcasted
async with payout_session_factory() as session:
assert (await session.scalars(select(PendingTransaction))).all() == []
async def test_tick_retries_once_the_throttle_window_has_elapsed(payout_session_factory):
await _seed_paying_out_round(payout_session_factory)
async with payout_session_factory() as session:
session.add(
AuditLog(
event_type="payout_failed",
payload_json='{"round_id": 1, "reason": "insufficient pool UTXOs"}',
round_id=1,
created_at=datetime.now(timezone.utc) - timedelta(seconds=120),
)
)
await session.commit()
entries = [{"tx_hash": "aa" * 32, "tx_pos": 0, "height": 10, "value": _POOL_AMOUNT_SATS + 100_000}]
client = FakePayoutClient(entries)
scheduler = RoundScheduler(payout_session_factory, FakePayoutListener(client))
await scheduler._tick()
assert client.broadcasted
async with payout_session_factory() as session:
pending = (await session.scalars(select(PendingTransaction))).one()
assert pending.status == "pending"
# --- B-28: the draw must not seed itself from an uncorroborated header -----------
class CorroboratingListener:
"""A fake listener whose tip advances the moment a corroboration attempt
fails, simulating a further block arriving — lets tests drive
_wait_for_next_block's retry loop deterministically without real sleeps."""
def __init__(self, *, responses: dict[int, bool], advance_to: dict[int, tuple[int, str]] | None = None):
self.tip_height, self.tip_header_hex = next(iter(responses)), "aa"
self._responses = dict(responses)
self._advance_to = advance_to or {}
self.corroboration_calls: list[int] = []
async def corroborate_header(self, height: int, expected_hash: str) -> bool:
self.corroboration_calls.append(height)
result = self._responses[height]
if not result and height in self._advance_to:
self.tip_height, self.tip_header_hex = self._advance_to[height]
return result
async def test_wait_for_next_block_accepts_an_immediately_corroborated_block(session_factory):
listener = CorroboratingListener(responses={101: True})
scheduler = RoundScheduler(session_factory, listener)
height, block_hash = await scheduler._wait_for_next_block(
round_id=1, tip_at_close=100, waiting_since=datetime.now(timezone.utc)
)
assert height == 101
assert listener.corroboration_calls == [101]
async def test_wait_for_next_block_retries_after_a_failed_corroboration(session_factory):
"""B-28: an uncorroborated header must never be used — the wait keeps going
until a later block's header *is* corroborated, logging why each time."""
listener = CorroboratingListener(
responses={101: False, 102: True}, advance_to={101: (102, "bb")}
)
scheduler = RoundScheduler(session_factory, listener)
height, block_hash = await scheduler._wait_for_next_block(
round_id=1, tip_at_close=100, waiting_since=datetime.now(timezone.utc)
)
assert height == 102
assert listener.corroboration_calls == [101, 102]
async with session_factory() as session:
events = [e.event_type for e in (await session.scalars(select(AuditLog))).all()]
assert events == ["draw_header_corroboration_failed"]
# --- B-36: a stalled draw must be visible, not a silent frozen wait --------------
class StallingListener:
"""A tip that never advances until the test decides it should — used to drive
_wait_for_next_block's stall-detection past _DRAW_STALL_THRESHOLD_SECONDS
without a real 6-minute wait."""
def __init__(self):
self.tip_height = 100
self.tip_header_hex = None
async def corroborate_header(self, height: int, expected_hash: str) -> bool:
return True
async def test_wait_for_next_block_logs_a_stall_audit_entry_past_the_threshold(session_factory, monkeypatch):
import app.rounds.scheduler as scheduler_module
listener = StallingListener()
scheduler = RoundScheduler(session_factory, listener)
start = datetime.now(timezone.utc)
class _FakeClock:
now = start
def fake_now(tz=None):
return _FakeClock.now
async def fake_sleep(seconds: float) -> None:
_FakeClock.now += timedelta(seconds=seconds)
# Past the stall threshold, but before it would repeat: unblock the wait
# by making a (corroborated) block appear, so the test terminates.
if _FakeClock.now >= start + timedelta(seconds=scheduler_module._DRAW_STALL_THRESHOLD_SECONDS + 30):
listener.tip_height = 101
listener.tip_header_hex = "aa"
monkeypatch.setattr(scheduler_module, "datetime", type("_D", (), {"now": staticmethod(fake_now)}))
monkeypatch.setattr(scheduler_module.asyncio, "sleep", fake_sleep)
height, block_hash = await scheduler._wait_for_next_block(round_id=1, tip_at_close=100, waiting_since=start)
assert height == 101
async with session_factory() as session:
entries = (await session.scalars(select(AuditLog).where(AuditLog.event_type == "draw_stalled"))).all()
assert len(entries) == 1
assert entries[0].round_id == 1
tests/unit/test_security.py
+15 -2
View File
@@ -9,8 +9,21 @@ def test_password_hash_roundtrip():
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
token = security.create_access_token(user_id=42, token_version=3)
assert security.decode_access_token(token) == (42, 3)
def test_jwt_decode_defaults_token_version_for_tokens_issued_before_it_existed(monkeypatch):
"""B-34: a token minted before the "tv" claim existed has no such key at
all. It must still decode — as token_version 0, matching a freshly
migrated user's starting value — rather than raising or being treated as
permanently stale."""
import jwt as pyjwt
monkeypatch.setattr(security.settings, "jwt_secret", "test-secret")
payload = {"sub": "42"}
token = pyjwt.encode(payload, "test-secret", algorithm=security.settings.jwt_algorithm)
assert security.decode_access_token(token) == (42, 0)
def test_verify_password_returns_false_for_an_unparseable_hash():
tests/unit/test_users.py
+46 -1
View File
@@ -81,7 +81,8 @@ async def test_change_password_updates_login(client):
headers=headers,
json={"current_password": "original-password", "new_password": "brand-new-password"},
)
assert resp.status_code == 204
assert resp.status_code == 200
assert resp.json()["access_token"]
resp = await client.post("/auth/login", json={"username": "alice", "password": "original-password"})
assert resp.status_code == 401
@@ -90,6 +91,36 @@ async def test_change_password_updates_login(client):
assert resp.status_code == 200
async def test_change_password_invalidates_the_old_token_but_not_the_new_one(client):
"""B-34: neither self-service change-password nor the admin reset used to
invalidate already-issued JWTs, so a stolen token (or an attacker who
already had the old password) stayed logged in until the token's natural
24h expiry — even past a password change meant to lock them out."""
old_token = await _register(client)
old_headers = {"Authorization": f"Bearer {old_token}"}
resp = await client.post(
"/users/me/change-password",
headers=old_headers,
json={"current_password": "original-password", "new_password": "brand-new-password"},
)
assert resp.status_code == 200
new_token = resp.json()["access_token"]
assert new_token != old_token
# The old token (what an attacker holding the old password would still
# have) is now rejected...
resp = await client.get("/users/me", headers=old_headers)
assert resp.status_code == 401
assert resp.json()["detail"]["code"] == "session_expired"
# ...but the freshly issued one keeps this same session working, so the
# user who just changed their own password isn't logged out too.
new_headers = {"Authorization": f"Bearer {new_token}"}
resp = await client.get("/users/me", headers=new_headers)
assert resp.status_code == 200
async def test_change_password_rejects_too_short(client):
token = await _register(client)
headers = {"Authorization": f"Bearer {token}"}
@@ -131,3 +162,17 @@ async def test_register_rejects_weak_credentials(client, payload):
async def test_register_accepts_valid_credentials(client):
resp = await client.post("/auth/register", json={"username": "goodname", "password": "longenough1"})
assert resp.status_code == 201
async def test_me_created_at_is_utc_stamped(client):
"""B-35: SQLite/aiosqlite returns DateTime columns as naive, even though every
value written is UTC (app.db.models.utcnow). A bare .isoformat() on that naive
value has no "Z"/offset, and JavaScript's `new Date()` then parses it as local
time instead of UTC."""
token = await _register(client)
headers = {"Authorization": f"Bearer {token}"}
resp = await client.get("/users/me", headers=headers)
assert resp.status_code == 200
created_at = resp.json()["created_at"]
assert created_at.endswith("+00:00") or created_at.endswith("Z")
tests/unit/test_withdrawals.py
+56
View File
@@ -2,9 +2,11 @@ import pytest
from sqlalchemy import select
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from app.bets.service import place_bet
from app.config import settings
from app.db.base import Base
from app.db.models import PendingTransaction, User, UtxoEvent, Withdrawal
from app.rounds.events import broadcaster
from app.wallet.hd import derive_user_address
from app.withdrawals.service import WithdrawalError, request_withdrawal
@@ -99,6 +101,35 @@ async def test_withdrawal_rejects_insufficient_balance(session_factory):
await request_withdrawal(session, client, user, EXTERNAL_ADDRESS, BET_AMOUNT_SATS)
async def test_withdrawal_distinguishes_pending_from_truly_insufficient_balance(session_factory):
"""B-37: right after a bet, cached_balance_sats is ~0 because the whole funding
UTXO was spent as input and the change hasn't confirmed yet — but the UI shows
the pending-inclusive balance (compute_pending_balance), which does cover a
withdrawal of this size. The error must say "not confirmed yet", not flatly
"insufficient balance", or it contradicts what the user is looking at."""
user_id = await _make_funded_user(session_factory, 4, 3_000_000_000)
bet_client = FakeElectrumClient()
async with session_factory() as session:
user = await session.get(User, user_id)
await place_bet(session, bet_client, user)
async with session_factory() as session:
user = await session.get(User, user_id)
assert user.cached_balance_sats == 0 # the whole funding UTXO was spent as input
withdraw_client = FakeElectrumClient()
with pytest.raises(WithdrawalError) as exc_info:
# Above the withdrawal minimum (BET_AMOUNT_SATS) and covered by the
# unconfirmed change (~1_999_800_000 sats), but not by the (zero)
# confirmed balance.
await request_withdrawal(session, withdraw_client, user, EXTERNAL_ADDRESS, 1_500_000_000)
assert exc_info.value.code == "balance_pending_confirmation"
assert exc_info.value.params["pending_sats"] > 0
assert not withdraw_client.broadcasted
@pytest.mark.parametrize(
"address",
[
@@ -141,6 +172,31 @@ async def test_withdrawal_to_own_address_is_rejected(session_factory):
assert (await session.scalars(select(UtxoEvent).where(UtxoEvent.user_id == user_id))).one().spent_txid is None
async def test_failed_broadcast_publishes_an_sse_update(session_factory): # B-49
"""The released UTXOs are spendable again and the balance changed back, so the
rollback must nudge the dashboard to refetch instead of leaving it stale until
its next poll."""
user_id = await _make_funded_user(session_factory, 10, 3_000_000_000)
class RejectingClient:
async def broadcast(self, raw_tx_hex: str) -> str:
raise RuntimeError("min relay fee not met")
queue = broadcaster.subscribe()
try:
while not queue.empty():
queue.get_nowait()
async with session_factory() as session:
user = await session.get(User, user_id)
with pytest.raises(WithdrawalError, match="refused"):
await request_withdrawal(session, RejectingClient(), user, derive_user_address(98), 1_000_000_000)
assert not queue.empty()
finally:
broadcaster.unsubscribe(queue)
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."""