Compare commits
10
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
17c557b8a3 | ||
|
|
fe5639a037 | ||
|
|
12df04178e | ||
|
|
63df38d30b | ||
|
|
e8fdea0389 | ||
|
|
0ce0562fd7 | ||
|
|
7224ca0e66 | ||
|
|
933760e948 | ||
|
|
50a43ae3ca | ||
|
|
f13f6850b7 |
No files matched your search
@@ -1,20 +1,16 @@
|
|||||||
# Known bugs
|
# Known bugs
|
||||||
|
|
||||||
A second full-codebase audit on 2026-07-27 found **25 further issues** (4 critical, 6 high,
|
A second full-codebase audit on 2026-07-27 found **25 further issues** (4 critical, 6 high,
|
||||||
7 medium, 8 low), listed below as B-25 … B-49. **All of them are open.** The 139-test suite
|
7 medium, 8 low), listed below as B-33 … B-49. B-25 through B-32 are fixed (see "Previously
|
||||||
is green, so none of these are caught by existing coverage — every fix should land with a
|
fixed" below) — no Critical-severity finding remains open; the other 17 are High/Medium/Low.
|
||||||
regression test.
|
The 139-test suite was green at the time of the audit, so none of these were caught by existing
|
||||||
|
coverage — every fix lands with a regression test (the eight fixes so far brought the suite
|
||||||
|
from 139 to 187).
|
||||||
|
|
||||||
The recurring pattern across B-25, B-26, B-27, B-29 and B-36 is worth stating once: the code
|
The recurring pattern across the open findings is worth stating once: the code is rigorous
|
||||||
is rigorous about the failure modes that have actually been hit, and silent about the ones
|
about the failure modes that have actually been hit, and silent about the ones that have not.
|
||||||
that have not. Outgoing transactions reconcile; deposits do not. Bets and withdrawals write
|
The payout phase is now fully recoverable; the "drawing" phase (waiting on a block) still has
|
||||||
their intent before broadcasting; the payout does not. Broadcast failures are audit-logged;
|
no equivalent resume-after-restart or stall visibility (B-36).
|
||||||
*pre*-broadcast failures (no client, insufficient pool funds) are not.
|
|
||||||
|
|
||||||
**Single highest priority: make `paying_out` a recoverable, idempotent state** (record before
|
|
||||||
broadcast + startup resume + retry). That closes B-25, B-26 and half of the already-known
|
|
||||||
"scheduler doesn't resume" gap — i.e. every way the lottery currently stops and cannot
|
|
||||||
restart on its own.
|
|
||||||
|
|
||||||
For limitations that are accepted by design rather than bugs (single-shared-token admin auth,
|
For limitations that are accepted by design rather than bugs (single-shared-token admin auth,
|
||||||
single-process assumptions, no user-facing history, etc.), see "Known gaps / TODO" in
|
single-process assumptions, no user-facing history, etc.), see "Known gaps / TODO" in
|
||||||
@@ -22,168 +18,8 @@ single-process assumptions, no user-facing history, etc.), see "Known gaps / TOD
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Critical
|
|
||||||
|
|
||||||
### B-25 — The payout has no two-phase write, unlike bets and withdrawals
|
|
||||||
|
|
||||||
`rounds/scheduler.py:214` broadcasts, and only afterwards (`:229-251`) writes `payout_txid`
|
|
||||||
and the `PendingTransaction`. A crash in that window — and `docker-compose.yml` sets
|
|
||||||
`restart: unless-stopped`, so a crash means an automatic restart — leaves a payout on-chain
|
|
||||||
with **no record at all**: the round is stuck in `paying_out`, the reconciler has nothing to
|
|
||||||
resolve, and a manual retry would pay the winner a second time (pool UTXOs are not tracked in
|
|
||||||
`utxo_events`, so nothing reserves them).
|
|
||||||
|
|
||||||
This is exactly what B-08 fixed for `place_bet`/`request_withdrawal`; the same fix was never
|
|
||||||
applied to the path that moves the most money.
|
|
||||||
|
|
||||||
**Proposed fix.** Mirror the bet path: write `Round.payout_txid` plus a
|
|
||||||
`PendingTransaction(kind="payout", status="building")` and commit *before*
|
|
||||||
`client.broadcast()`, then promote to `"pending"` after. Teach
|
|
||||||
`reconcile.py:_promote`/`_abandon` to handle a `building` payout (promote if the tx is on
|
|
||||||
chain, otherwise clear `payout_txid` and leave the round for the retry routine). Since pool
|
|
||||||
UTXOs are invisible to `utxo_events`, `_abandon` cannot release them — so the payout builder
|
|
||||||
must additionally refuse to spend an outpoint already referenced by a non-terminal payout
|
|
||||||
`PendingTransaction`, which is what makes a retry safe against double-paying.
|
|
||||||
|
|
||||||
### B-26 — A transient failure at payout time wedges the lottery permanently
|
|
||||||
|
|
||||||
`rounds/scheduler.py:166-169`: if `listener.client is None` when `_trigger_payout` starts, it
|
|
||||||
returns. `_trigger_payout` is called exactly once, from `_close_and_draw`, and `_tick`
|
|
||||||
ignores any round not in `open`/`closing` (`:58`). The round stays in `paying_out`, no new
|
|
||||||
round can open, and — unlike the `except Exception` branch — nothing is written to
|
|
||||||
`audit_log`, so `/admin` shows a stalled state with no explanation.
|
|
||||||
|
|
||||||
The payout runs immediately after a ~2-minute wait on a block, so an Electrum drop in that
|
|
||||||
window is entirely plausible. Same shape at `:215-217`: `InsufficientFundsError` returns
|
|
||||||
without calling `_log_payout_failure`.
|
|
||||||
|
|
||||||
CLAUDE.md lists "payout retry" as an accepted gap, but treats it as an operational
|
|
||||||
inconvenience; in practice it is a single point of failure that stops the whole platform.
|
|
||||||
|
|
||||||
**Proposed fix.** (a) Call `_log_payout_failure` on *every* early return, with a reason in the
|
|
||||||
payload, so the operator sees it. (b) Make `_tick` handle `paying_out`: if the round has no
|
|
||||||
non-terminal payout `PendingTransaction`, re-run `_trigger_payout`. That turns every early
|
|
||||||
return into a retry rather than a dead end, and — combined with B-25's idempotency guard —
|
|
||||||
also covers the process-restart case.
|
|
||||||
|
|
||||||
### B-27 — Every RBF bump resets the reconciler's abandon clock, so it never fires
|
|
||||||
|
|
||||||
`tx/broadcast.py:122` sets `pending.broadcast_at = now` on each bump, but
|
|
||||||
`tx/reconcile.py:133` computes the 6-hour abandon deadline **from that same field**.
|
|
||||||
|
|
||||||
With the default `rbf_timeout_seconds = 900`, a transaction that is successfully bumped every
|
|
||||||
15 minutes but never mined resets the counter long before it can reach 6 hours: it is **never
|
|
||||||
abandoned**, its UTXOs never return to the user, and if it is a bet the round stays in
|
|
||||||
`closing` indefinitely (`scheduler.py:90-91`). `reconcile.py` exists precisely to prevent
|
|
||||||
this, and the bumper disarms it.
|
|
||||||
|
|
||||||
**Proposed fix.** Split the field: keep `broadcast_at` as the *first* broadcast (never
|
|
||||||
rewritten — it is what `_is_due` must use) and add `last_broadcast_at`, updated by
|
|
||||||
`bump_fee` and used by `should_bump`. Alembic migration backfilling `last_broadcast_at =
|
|
||||||
broadcast_at`.
|
|
||||||
|
|
||||||
### B-28 — A hostile Electrum server (or a MITM) can choose the winner
|
|
||||||
|
|
||||||
`electrum/listener.py:167-186` accepts any header whose `height >= tip_height`: no
|
|
||||||
proof-of-work check, no linkage to the previous block hash. That header is the **sole source
|
|
||||||
of entropy for the draw** (`scheduler.py:129`).
|
|
||||||
|
|
||||||
In parallel, `electrum/client.py:104-106` sets `check_hostname = False` and
|
|
||||||
`verify_mode = CERT_NONE`. The comment justifies this with "the protocol's trust model is
|
|
||||||
server consensus" — but there is no consensus here: one server at a time, rotated over a list
|
|
||||||
of arbitrary third parties. So a hostile server, or anyone able to MITM a connection that
|
|
||||||
validates no certificate, can fabricate a header and thereby decide who wins every round.
|
|
||||||
|
|
||||||
**Proposed fix, in order of value.** (1) Validate headers before accepting them: check the
|
|
||||||
PoW against the claimed target and that `prev_block` matches the current tip; reject anything
|
|
||||||
that fails. (2) Do not trust one server for the draw — fetch the header for
|
|
||||||
`draw_block_height` from *several* endpoints in the rotation and require agreement before
|
|
||||||
using it as the seed. (3) Pin certificates (or verify hostnames) for the configured servers
|
|
||||||
rather than disabling verification wholesale. Longer term this is the argument for replacing
|
|
||||||
the v1 draw algorithm — CLAUDE.md already calls it a replaceable component — with a scheme
|
|
||||||
that does not depend on a single unauthenticated data source.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## High
|
## High
|
||||||
|
|
||||||
### B-29 — `detect_external_spends` is irreversible and trusts a single response
|
|
||||||
|
|
||||||
`deposits/service.py:87` marks `spent_txid = "external-spend"` for any UTXO missing from the
|
|
||||||
current `listunspent`. There is **no path to undo it**: `credit_confirmed_utxos` skips
|
|
||||||
`(txid, vout)` keys that already exist, regardless of their spent status (`:19-31`).
|
|
||||||
|
|
||||||
One incomplete `listunspent` — a rotated-to server that is broken or behind, an empty reply on
|
|
||||||
error, or a reorg — permanently and silently zeroes a user's balance, recoverable only by
|
|
||||||
editing the database. Crediting is idempotent and conservative; debiting is neither, and it
|
|
||||||
acts on a single reply from a single unauthenticated server.
|
|
||||||
|
|
||||||
**Proposed fix.** Treat a missing outpoint as *evidence*, not proof. Require the same UTXO to
|
|
||||||
be absent across N consecutive refreshes (or confirm the spend by looking up the outpoint's
|
|
||||||
spending tx) before marking it, and skip the whole pass when `listunspent` returns empty for
|
|
||||||
an address the DB believes is funded. Make the mark reversible: re-crediting should clear
|
|
||||||
`spent_txid` when the sentinel value is present and the outpoint reappears as unspent.
|
|
||||||
|
|
||||||
### B-30 — No deposit-side reconciler: one missed subscription means deposits are never credited
|
|
||||||
|
|
||||||
`electrum/listener.py:61-67` (`address_for_new_user`) fires `asyncio.create_task(...)` without
|
|
||||||
retaining the reference and without handling exceptions. If `self.client` becomes `None`
|
|
||||||
between the check and the task running, the `assert` at `:163` raises inside an orphan task
|
|
||||||
and the exception is swallowed.
|
|
||||||
|
|
||||||
What makes this serious is what happens next: deposits are credited **exclusively** by
|
|
||||||
scripthash notifications. There is no periodic routine reconciling balances against the chain
|
|
||||||
(the reconciler only covers outgoing transactions). On a healthy keepalive'd connection there
|
|
||||||
are no reconnects, so a lost subscription is never recovered and that user **never sees their
|
|
||||||
deposits**, indefinitely.
|
|
||||||
|
|
||||||
**Proposed fix.** Two parts. (a) Make the subscription reliable: retain the task, log its
|
|
||||||
exceptions, and retry with backoff instead of relying on a reconnect. (b) Add the missing
|
|
||||||
safety net — a periodic sweep (say every few minutes, similar in shape to
|
|
||||||
`PendingTransactionReconciler`) that re-runs `_refresh_user` for users whose scripthash is not
|
|
||||||
in `_scripthash_to_user`, or simply round-robins over all users so a missed notification is
|
|
||||||
always eventually caught.
|
|
||||||
|
|
||||||
### B-31 — Reconnect costs O(users) sequential round-trips and stalls the draw
|
|
||||||
|
|
||||||
In `_run_once` the order is: subscribe headers → `_subscribe_all_users()` → *then* start the
|
|
||||||
consumer tasks (`electrum/listener.py:118-134`). `_subscribe_all_users` iterates users
|
|
||||||
**sequentially**, and each iteration is a subscribe plus a `listunspent` plus a DB write
|
|
||||||
(`:154-165`).
|
|
||||||
|
|
||||||
At 5.000 users that is 10.000 serialized round-trips (15s timeout each). Throughout,
|
|
||||||
`_consume_headers` is not running, so `tip_height` is frozen and `_wait_for_next_block` makes
|
|
||||||
no progress: **a reconnect stalls an in-flight draw** for the entire resubscribe. And since
|
|
||||||
registration has no rate limiting, the user count is attacker-controlled.
|
|
||||||
|
|
||||||
**Proposed fix.** Start the consumer tasks (headers especially) *before* resubscribing, so tip
|
|
||||||
updates keep flowing during the sweep. Batch the resubscribe with bounded concurrency
|
|
||||||
(e.g. `asyncio.Semaphore(20)` over `asyncio.gather`) instead of a serial loop, and decouple
|
|
||||||
the `listunspent` refresh from the subscribe so the initial refresh can proceed in the
|
|
||||||
background.
|
|
||||||
|
|
||||||
### B-32 — `bump_fee` can loop forever on rebroadcasts the node always rejects
|
|
||||||
|
|
||||||
`tx/broadcast.py:87-88` forces `fee_delta = 1` when `fee_delta <= 0`. A **one-satoshi** total
|
|
||||||
fee increase violates BIP125 rule 4 (a replacement must pay at least the incremental relay fee
|
|
||||||
times its own size), so the node rejects it. `bump_fee` raises before updating `pending`, so
|
|
||||||
`fee_rate_sat_vb` never advances and the next tick **retries with identical parameters, every
|
|
||||||
30 seconds, forever**.
|
|
||||||
|
|
||||||
This triggers whenever the real fee exceeds the estimate — i.e. whenever dust change was
|
|
||||||
absorbed into the fee, which is an explicitly supported path
|
|
||||||
(`wallet/psbt_builder.py:105-107`).
|
|
||||||
|
|
||||||
Related, same function: `new_fee_rate = pending.fee_rate_sat_vb + 1` on every bump, with **no
|
|
||||||
ceiling**. A transaction stuck for a day reaches ~96 sat/vB, eating the user's change, and it
|
|
||||||
ignores the `le=10_000` bound the admin panel enforces on the config field.
|
|
||||||
|
|
||||||
**Proposed fix.** Compute the delta from the actual replacement vsize
|
|
||||||
(`fee_delta = max(new_fee - old_fee, ceil(vsize * incremental_relay_rate))`) so the bump is
|
|
||||||
always relay-valid. Cap `new_fee_rate` at the configured maximum and raise `RbfError` once
|
|
||||||
reached, so the transaction falls through to the reconciler (which needs B-27 fixed to
|
|
||||||
actually act on it) rather than being retried indefinitely.
|
|
||||||
|
|
||||||
### B-33 — No brute-force protection on a custodial wallet
|
### B-33 — No brute-force protection on a custodial wallet
|
||||||
|
|
||||||
`POST /auth/login` (`auth/routes.py:83`) has no rate limiting, no lockout, no delay and no
|
`POST /auth/login` (`auth/routes.py:83`) has no rate limiting, no lockout, no delay and no
|
||||||
@@ -383,6 +219,18 @@ already does.
|
|||||||
|
|
||||||
## Previously fixed
|
## Previously fixed
|
||||||
|
|
||||||
|
- **B-25** — the payout had no two-phase write, unlike bets and withdrawals
|
||||||
|
- **B-26** — a payout failure or a process restart could wedge a round in `paying_out` forever
|
||||||
|
- **B-27** — an RBF bump reset the reconciler's own abandon clock, so a repeatedly-bumped tx was never abandoned
|
||||||
|
- **B-28** — a hostile Electrum server (or a MITM) could single-handedly pick the round's winner
|
||||||
|
- **B-29** — a UTXO absent from one server's `listunspent` was marked spent immediately, irreversibly, on a single unauthenticated reply
|
||||||
|
- **B-30** — a lost scripthash subscription meant a user's deposits were never credited, with no periodic safety net
|
||||||
|
- **B-31** — resubscribing on reconnect ran serially before anything else started, freezing the chain tip (and so an in-flight draw) for the whole sweep
|
||||||
|
- **B-32** — an RBF bump's fee delta could fall below BIP125's relay-mandated minimum, so the node rejected it and the same tick retried identically forever; also had no ceiling on how high the fee rate could climb
|
||||||
|
|
||||||
|
See git history for the fix-by-fix breakdown (commits `f13f685`, `50a43ae`, `933760e`, and the
|
||||||
|
B-28/B-29/B-30/B-31/B-32 fixes). Suite grew from 139 to 187 tests over the eight.
|
||||||
|
|
||||||
A full-codebase audit on 2026-07-26 (commit `d4e0974`) found 24 bugs across every Python
|
A full-codebase audit on 2026-07-26 (commit `d4e0974`) found 24 bugs across every Python
|
||||||
module under `app/`, both static frontends, and the Docker/Caddy deployment — 5 critical,
|
module under `app/`, both static frontends, and the Docker/Caddy deployment — 5 critical,
|
||||||
7 high, 7 medium, 5 low. All 24 were fixed and verified against the current code on
|
7 high, 7 medium, 5 low. All 24 were fixed and verified against the current code on
|
||||||
|
|||||||
@@ -8,233 +8,239 @@ The user communicates in Italian in chat — reply to them in Italian. Everythin
|
|||||||
|
|
||||||
## Project status
|
## 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 — 185 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
|
**Read [BUGS.md](BUGS.md) before trusting any behaviour here.** Two audits: 2026-07-26 found 24 bugs (5 critical), all fixed; 2026-07-27 found 25 more (B-32 … B-49), of which **18 are still open** — no Critical, but High covers an RBF bump that can loop forever on a replacement the node always rejects (B-32), no brute-force protection on login (B-33), and password change/reset not invalidating existing JWTs (B-34). BUGS.md is the live open list with a proposed fix per finding; "Known gaps" at the end of this file is for limitations accepted **by design** instead. Don't fix a BUGS.md item silently as a side effect of other work — each fix lands with its own regression test.
|
||||||
dropped Electrum connection that hung the whole server with no reconnect, an RBF fee bump
|
|
||||||
that wedged a round forever, and no way for the system to recover a broadcast that never
|
|
||||||
confirmed (funds frozen). All 24 are fixed; [BUGS.md](BUGS.md) is the record, with each
|
|
||||||
one's root cause, what was actually done, and where its regression test lives. Read it
|
|
||||||
before assuming any behaviour here predates those fixes.
|
|
||||||
|
|
||||||
Before writing code, always read the "Architecture" section below in full, plus the diagrams in [flowchart/](flowchart/): [platform-overview.mmd](flowchart/platform-overview.mmd) for the whole 5-phase flow, and [round-lifecycle.mmd](flowchart/round-lifecycle.mmd) for the round/draw lifecycle in detail. Every node in these diagrams corresponds to a behavior that must be implemented exactly as described, including the labels on the edges (conditions, retries, loops). Regenerate their companion PDFs with `flowchart/render-pdf.sh <file>.mmd` after editing either one.
|
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.md](README.md)'s Quick start is stale** (bare `uvicorn --reload`, `docker compose run … generate_master_key.py` — neither is supported; B-44); this file and `docs/setup.md` are authoritative.
|
||||||
|
|
||||||
## Commands
|
## 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
|
```bash
|
||||||
source .venv/bin/activate # venv already created at .venv/
|
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/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 the existing master xprv (asks for confirmation first)
|
PYTHONPATH=. python scripts/decrypt_master_key.py # ops recovery: decrypt+print it (asks for confirmation)
|
||||||
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/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 # all 185 tests
|
||||||
python -m pytest tests/unit/test_hd.py # run one test file
|
python -m pytest tests/unit/test_hd.py # one file
|
||||||
python -m pytest tests/unit/test_hd.py::test_derivation_is_deterministic # run a single test
|
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)
|
## 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
|
```bash
|
||||||
mkdir -p data/db data/keys data/logs # one-time: host dirs bind-mounted into the app container
|
mkdir -p data/db data/keys data/logs # one-time
|
||||||
|
docker compose up -d --build # dev and prod alike
|
||||||
# one-time: generate the master key via the venv script above (scripts/generate_master_key.py),
|
docker compose logs -f app # also written to ./data/logs/app.log
|
||||||
# not via `docker compose run` — MASTER_KEY_PATH in .env already points at ./data/keys/
|
docker compose down
|
||||||
|
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Caddy's site address comes from `SITE_ADDRESS` (env var on the host, read by `docker-compose.yml`):
|
`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).
|
||||||
- **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.
|
|
||||||
|
|
||||||
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` sets **no** security headers — no CSP, HSTS or `X-Frame-Options` (B-43). `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.
|
- Python 3.12+, FastAPI, SQLAlchemy 2 async + Alembic, SQLite via aiosqlite, `embit` for keys/PSBT/tx parsing.
|
||||||
- **PLM node access**: Electrum protocol only (no full node/P2P). Bootstrap server for development: `santantonio.sytes.net:50002` (SSL).
|
- **PLM access via the Electrum protocol only** (no full node/P2P). Dev bootstrap server: `santantonio.sytes.net:50002` (SSL).
|
||||||
- **Auth**: Argon2 password hashing + JWT sessions.
|
- Auth: Argon2 hashing + JWT (HS256, 24h, **no revocation** — B-34).
|
||||||
- **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.
|
- 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**: 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.
|
- **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.
|
||||||
- **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.
|
|
||||||
|
|
||||||
## 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`
|
| BIP44/84 coin type | `746` → `m/84'/746'/0'/0/index` |
|
||||||
- P2PKH address version byte: `55` (addresses start with `P`)
|
| Bech32 HRP | `plm` |
|
||||||
- P2SH address version byte: `5`
|
| P2PKH / P2SH version byte | `55` (addresses start with `P`) / `5` |
|
||||||
- WIF prefix: `0x80`
|
| WIF prefix | `0x80` |
|
||||||
- Block time: 120s
|
| Block time | 120s |
|
||||||
- BIP32 extended key headers (Legacy/native-segwit `zprv`/`zpub` etc.): see `ExtKeyHeaders` in `ChainProfiles.cs`
|
| 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
|
| Parameter | Value | Where |
|
||||||
tip the draw waits on — which makes it the platform's biggest single point of failure.
|
|---|---|---|
|
||||||
Three things keep it honest:
|
| 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` |
|
||||||
|
|
||||||
- **Server rotation.** `ELECTRUM_HOST`/`ELECTRUM_PORT` is the primary;
|
`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).
|
||||||
`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
|
**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.
|
||||||
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
|
**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.
|
||||||
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
|
## Code map
|
||||||
connection down. Unbounded waits used to hang a `POST /bets` *while holding the per-user
|
|
||||||
lock*, and could stop the confirmation poller permanently.
|
| Package | Contents |
|
||||||
- **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`
|
| `app/main.py` | entry point: lifespan starts the six background tasks, mounts the routers and `app/static/` |
|
||||||
keepalive. Without this the listener sat on queues nobody would ever fill again and never
|
| `app/api/routes/` | `admin`, `bets`, `withdrawals`, `rounds` (incl. SSE), `users`, `qr`; `app/api/errors.py` holds the error contract |
|
||||||
reconnected — while `listener.client` still looked alive to everything else.
|
| `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
|
## 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). The gap is user-visible and currently under-explained in errors (B-37).
|
||||||
|
|
||||||
## Real-time updates (SSE)
|
## 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). Rollback paths are the known exception (B-49).
|
||||||
|
|
||||||
Deliberate scope decisions, not oversights:
|
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).
|
||||||
- **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).
|
|
||||||
|
|
||||||
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.
|
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`.
|
||||||
- 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.
|
|
||||||
|
|
||||||
## 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.
|
## Frontends
|
||||||
- **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.
|
|
||||||
|
|
||||||
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:
|
- **`/`** — 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.
|
||||||
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.
|
- **`/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.
|
||||||
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.
|
|
||||||
|
|
||||||
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).
|
- 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`, and a missing key renders as the raw key string.
|
- **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 **not** translated (operator-facing, Italian only), and neither is `/guida` (serves `docs/guida-utente.md`).
|
- `/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.
|
**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.
|
||||||
|
|
||||||
## 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.
|
|
||||||
|
|
||||||
## Non-obvious domain decisions
|
## 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.
|
- Keys are generated and held **server-side**: this is **custodial**. The user controls nothing until they withdraw.
|
||||||
- The user's personal deposit address always doubles as the winnings-receiving address: there is no separate "winner address".
|
- The deposit address *is* the winnings 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.
|
- **1 confirmation** for every tx kind. Don't introduce differing thresholds (3, 6, …) 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 draw algorithm is a **replaceable component**, not the final design — don't architect around its current form.
|
||||||
- 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.
|
- `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.
|
||||||
- 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`.
|
- 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`).
|
||||||
## Transaction reconciliation and the tx lifecycle
|
|
||||||
|
|
||||||
Everything that spends money is written **before** it is broadcast, and resolved against
|
|
||||||
the chain afterwards. This is what makes the system recover on its own instead of needing
|
|
||||||
manual DB edits (BUGS.md B-04/B-08).
|
|
||||||
|
|
||||||
`PendingTransaction.status` is the lifecycle: `building` → `pending` → `confirmed`, or
|
|
||||||
`failed`.
|
|
||||||
|
|
||||||
- `building` is written first, with the UTXOs already marked `spent_txid`, and committed
|
|
||||||
*before* the broadcast (`bets/service.py:place_bet`, `withdrawals/service.py`). A crash
|
|
||||||
in that window therefore leaves evidence rather than coins spent on-chain with no record.
|
|
||||||
- If the broadcast is refused, the service releases the reserved UTXOs, restores the
|
|
||||||
balance, removes the participant (or marks the withdrawal `failed`), audit-logs it, and
|
|
||||||
raises `broadcast_failed` — answered as **502**, since the network refused it, not the
|
|
||||||
caller.
|
|
||||||
- `app/tx/reconcile.py` (`PendingTransactionReconciler`, every 120s and once at startup)
|
|
||||||
asks the chain about anything still `building`/`pending`. Tx present → promote; tx gone →
|
|
||||||
mark `failed` with a `failure_reason`, release the inputs, roll the domain row back,
|
|
||||||
audit-log `pending_tx_abandoned`. Grace periods differ by state (120s for `building`,
|
|
||||||
6h for `pending`, so the RBF bumper gets its attempts first), and a *transport* failure
|
|
||||||
never abandons anything — only a server that positively doesn't know the tx does.
|
|
||||||
|
|
||||||
Because of this, `UtxoEvent.spent_txid` must always equal the *current* txid of the tx
|
|
||||||
reserving it: `bump_fee` retargets it (along with `RoundParticipant.bet_txid`,
|
|
||||||
`Withdrawal.txid` and `Round.payout_txid`) on every fee bump. Confirmation handlers
|
|
||||||
deliberately key off immutable ids (`round_id`/`user_id`, `withdrawal_id`) rather than the
|
|
||||||
txid, which changes under them.
|
|
||||||
|
|
||||||
**At most one active round is a database invariant**, not just a code convention:
|
|
||||||
`ix_rounds_single_active` (a unique index over the constant expression `(1)`, restricted to
|
|
||||||
the active statuses) makes a concurrent second insert fail cleanly, and
|
|
||||||
`open_new_round_if_needed` recovers by using the winner's round.
|
|
||||||
|
|
||||||
## Known gaps / TODO
|
## Known gaps / TODO
|
||||||
|
|
||||||
Not blockers for reading the code, but must be addressed before this is production-ready.
|
Accepted **by design**. For actual bugs see [BUGS.md](BUGS.md) (18 open) — not duplicated here.
|
||||||
The 24 findings of the 2026-07-26 full-codebase audit are **all fixed** — see
|
|
||||||
[BUGS.md](BUGS.md), which keeps each one's root cause, fix and regression test as the
|
|
||||||
record. What remains open:
|
|
||||||
|
|
||||||
- **Scheduler doesn't resume mid-flight rounds after a restart.** `rounds/scheduler.py`'s `_tick()` only acts on rounds with `status == "open"`. If the process restarts while a round is `closing`/`drawing`/`paying_out`, it's permanently stuck — nothing re-enters `_wait_for_next_block` or retries `_trigger_payout`. Needs a startup routine that inspects in-progress rounds and resumes (or a periodic "unstick" check) before this can run unattended. Note this is *round*-level state: in-flight *transactions* do now recover on their own (see "Transaction reconciliation" 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`. That wait is also unbounded and invisible in `/admin` (B-36) — the last prerequisite for running unattended.
|
||||||
- **RBF bump only handles one case**: a single change output, paying back to the tx's own sender address, large enough to absorb the fee increase. No additional-input selection fallback — an exact-amount tx (no change) or a change output too small to absorb the bump raises `RbfError`. 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.
|
- **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.
|
||||||
- **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 are unit-tested but never live-broadcast** (failure and rollback branches included — still not a real network).
|
||||||
- **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 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.
|
||||||
- **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 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.
|
||||||
- **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 anywhere** (register, bet, withdrawal, admin, SSE). For login this is a blocker, not a gap — tracked as B-33.
|
||||||
- **No rate limiting / abuse protection** on any endpoint (register, bet, withdrawal, admin).
|
- **`/guida` and `/report-bug` are placeholders** (`app/static/guida.html`, `report-bug.html`) — links work, content is "coming soon".
|
||||||
- **`/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 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).
|
||||||
- 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 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.
|
||||||
- **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).
|
|
||||||
@@ -14,6 +14,7 @@ from app.db.session import get_session
|
|||||||
from app.rounds.config import get_round_config
|
from app.rounds.config import get_round_config
|
||||||
from app.wallet.address import is_valid_plm_address
|
from app.wallet.address import is_valid_plm_address
|
||||||
from app.wallet.hd import derive_user_wif
|
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"])
|
router = APIRouter(prefix="/admin", tags=["admin"])
|
||||||
|
|
||||||
@@ -68,7 +69,7 @@ class RoundConfigUpdate(BaseModel):
|
|||||||
bet_amount_sats: int | None = Field(default=None, gt=0, le=100_000 * 100_000_000)
|
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_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)
|
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)
|
rbf_timeout_seconds: int | None = Field(default=None, ge=60, le=7 * 24 * 3600)
|
||||||
draw_animation_seconds: int | None = Field(default=None, ge=0, le=600)
|
draw_animation_seconds: int | None = Field(default=None, ge=0, le=600)
|
||||||
|
|
||||||
|
|||||||
@@ -144,7 +144,14 @@ class PendingTransaction(Base):
|
|||||||
current_txid: Mapped[str] = mapped_column(String(64))
|
current_txid: Mapped[str] = mapped_column(String(64))
|
||||||
fee_rate_sat_vb: Mapped[int]
|
fee_rate_sat_vb: Mapped[int]
|
||||||
raw_tx_hex: Mapped[str] = mapped_column(String)
|
raw_tx_hex: Mapped[str] = mapped_column(String)
|
||||||
|
# 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)
|
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")
|
status: Mapped[str] = mapped_column(String(16), default="pending")
|
||||||
# The txid this row had *before* its most recent RBF bump (bump_fee rewrites
|
# 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
|
# current_txid in place). Despite the name reading forwards, it points
|
||||||
|
|||||||
@@ -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)
|
||||||
+90
-17
@@ -1,3 +1,5 @@
|
|||||||
|
import logging
|
||||||
|
|
||||||
from sqlalchemy import select
|
from sqlalchemy import select
|
||||||
from sqlalchemy.ext.asyncio import AsyncSession
|
from sqlalchemy.ext.asyncio import AsyncSession
|
||||||
|
|
||||||
@@ -6,6 +8,8 @@ from app.db.models import UtxoEvent
|
|||||||
from app.rounds.events import broadcaster
|
from app.rounds.events import broadcaster
|
||||||
from app.wallet.balance import recompute_balance
|
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:
|
async def credit_confirmed_utxos(session: AsyncSession, user_id: int, entries: list[dict]) -> int:
|
||||||
"""Insert utxo_events for newly-confirmed entries from an Electrum
|
"""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"
|
_EXTERNAL_SPEND_SENTINEL = "external-spend"
|
||||||
|
|
||||||
|
|
||||||
async def detect_external_spends(session: AsyncSession, user_id: int, entries: list[dict]) -> int:
|
async def reinstate_reappeared_utxos(session: AsyncSession, user_id: int, entries: list[dict]) -> int:
|
||||||
"""Mirror of credit_confirmed_utxos: catches a UTXO leaving the address
|
"""The reverse of a mark applied by find_utxos_missing_from/
|
||||||
through a transaction this platform never built (e.g. someone spending it
|
mark_utxos_spent_externally (B-29): if an outpoint we'd previously flagged as
|
||||||
directly with the raw privkey, bypassing /withdrawals entirely).
|
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
|
marked_rows = (
|
||||||
spent_txid at broadcast time, before the tx ever reaches the chain — so by
|
await session.scalars(
|
||||||
the time an Electrum refresh runs, an outpoint still marked unspent in our
|
select(UtxoEvent).where(
|
||||||
own DB that Electrum no longer reports as unspent was never on our radar.
|
UtxoEvent.user_id == user_id, UtxoEvent.spent_txid == _EXTERNAL_SPEND_SENTINEL
|
||||||
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.
|
).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}
|
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()
|
).all()
|
||||||
|
|
||||||
newly_spent = 0
|
if not entries and unspent_rows:
|
||||||
for row in unspent_rows:
|
logger.warning(
|
||||||
if (row.txid, row.vout) in current_keys:
|
"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
|
continue
|
||||||
row.spent_txid = _EXTERNAL_SPEND_SENTINEL
|
row.spent_txid = _EXTERNAL_SPEND_SENTINEL
|
||||||
await write_audit_log(
|
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},
|
{"txid": row.txid, "vout": row.vout, "amount_sats": row.amount_sats},
|
||||||
user_id=user_id,
|
user_id=user_id,
|
||||||
)
|
)
|
||||||
newly_spent += 1
|
marked += 1
|
||||||
|
|
||||||
if newly_spent:
|
if marked:
|
||||||
await session.flush()
|
await session.flush()
|
||||||
await recompute_balance(session, user_id)
|
await recompute_balance(session, user_id)
|
||||||
await session.commit()
|
await session.commit()
|
||||||
broadcaster.publish()
|
broadcaster.publish()
|
||||||
|
|
||||||
return newly_spent
|
return marked
|
||||||
+231
-12
@@ -6,9 +6,20 @@ from sqlalchemy import select
|
|||||||
from sqlalchemy.ext.asyncio import async_sessionmaker
|
from sqlalchemy.ext.asyncio import async_sessionmaker
|
||||||
|
|
||||||
from app.db.models import User
|
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.client import ElectrumClient, ElectrumEndpoint
|
||||||
from app.electrum.scripthash import address_to_scripthash
|
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
|
from app.rounds.events import broadcaster
|
||||||
|
|
||||||
logger = logging.getLogger(__name__)
|
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.
|
# difference between noticing the drop in a minute and never noticing it at all.
|
||||||
_PING_INTERVAL_SECONDS = 60
|
_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:
|
class ElectrumListener:
|
||||||
"""Long-lived background task: keeps one Electrum connection open, subscribes
|
"""Long-lived background task: keeps one Electrum connection open, subscribes
|
||||||
@@ -46,6 +68,11 @@ class ElectrumListener:
|
|||||||
self._endpoints = list(endpoints or [])
|
self._endpoints = list(endpoints or [])
|
||||||
self._endpoint_index = 0
|
self._endpoint_index = 0
|
||||||
self._scripthash_to_user: dict[str, int] = {}
|
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_height: int = 0
|
||||||
self.tip_header_hex: str | None = None
|
self.tip_header_hex: str | None = None
|
||||||
self.client: ElectrumClient | 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:
|
def address_for_new_user(self, user_id: int, address: str) -> None:
|
||||||
"""Called right after a user registers so their deposit address starts
|
"""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)
|
scripthash = address_to_scripthash(address)
|
||||||
self._scripthash_to_user[scripthash] = user_id
|
self._scripthash_to_user[scripthash] = user_id
|
||||||
if self.client is not None:
|
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:
|
async def run(self) -> None:
|
||||||
backoff = 1
|
backoff = 1
|
||||||
@@ -118,8 +166,6 @@ class ElectrumListener:
|
|||||||
header = await client.subscribe_headers()
|
header = await client.subscribe_headers()
|
||||||
self._apply_header(header)
|
self._apply_header(header)
|
||||||
|
|
||||||
await self._subscribe_all_users()
|
|
||||||
|
|
||||||
headers_queue = client.notifications("blockchain.headers.subscribe")
|
headers_queue = client.notifications("blockchain.headers.subscribe")
|
||||||
scripthash_queue = client.notifications("blockchain.scripthash.subscribe")
|
scripthash_queue = client.notifications("blockchain.scripthash.subscribe")
|
||||||
# The consumers below block on their queues forever by design, so they
|
# 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(self._keepalive(client)),
|
||||||
asyncio.create_task(client.wait_closed()),
|
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:
|
try:
|
||||||
done, still_running = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
|
done, still_running = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
|
||||||
finally:
|
finally:
|
||||||
|
subscribe_task.cancel()
|
||||||
for task in tasks:
|
for task in tasks:
|
||||||
task.cancel()
|
task.cancel()
|
||||||
for task in done:
|
for task in done:
|
||||||
@@ -146,23 +208,45 @@ class ElectrumListener:
|
|||||||
await client.close()
|
await client.close()
|
||||||
return True
|
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:
|
async def _keepalive(self, client: ElectrumClient) -> None:
|
||||||
while True:
|
while True:
|
||||||
await asyncio.sleep(_PING_INTERVAL_SECONDS)
|
await asyncio.sleep(_PING_INTERVAL_SECONDS)
|
||||||
await client.ping() # raises (and so ends the session) on timeout or a dead socket
|
await client.ping() # raises (and so ends the session) on timeout or a dead socket
|
||||||
|
|
||||||
async def _subscribe_all_users(self) -> None:
|
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:
|
async with self._session_factory() as session:
|
||||||
users = (await session.scalars(select(User))).all()
|
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)
|
scripthash = address_to_scripthash(user.address)
|
||||||
self._scripthash_to_user[scripthash] = user.id
|
self._scripthash_to_user[scripthash] = user.id
|
||||||
await self._subscribe_and_refresh(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:
|
async def _subscribe_and_refresh(self, scripthash: str, user_id: int) -> None:
|
||||||
assert self.client is not None
|
assert self.client is not None
|
||||||
await self.client.subscribe_scripthash(scripthash)
|
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:
|
def _apply_header(self, header: dict) -> None:
|
||||||
"""Record a new chain tip, refusing to move backwards.
|
"""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 —
|
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
|
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.
|
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"]
|
height = header["height"]
|
||||||
|
header_hex = header.get("hex")
|
||||||
if height < self.tip_height:
|
if height < self.tip_height:
|
||||||
logger.warning(
|
logger.warning(
|
||||||
"ignoring Electrum header at height %s, below the current tip %s (reorg or server switch?)",
|
"ignoring Electrum header at height %s, below the current tip %s (reorg or server switch?)",
|
||||||
@@ -182,8 +277,109 @@ class ElectrumListener:
|
|||||||
self.tip_height,
|
self.tip_height,
|
||||||
)
|
)
|
||||||
return
|
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_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:
|
async def _consume_headers(self, queue: asyncio.Queue) -> None:
|
||||||
while True:
|
while True:
|
||||||
@@ -200,15 +396,38 @@ class ElectrumListener:
|
|||||||
scripthash, _status = await queue.get()
|
scripthash, _status = await queue.get()
|
||||||
user_id = self._scripthash_to_user.get(scripthash)
|
user_id = self._scripthash_to_user.get(scripthash)
|
||||||
if user_id is not None:
|
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
|
assert self.client is not None
|
||||||
entries = await self.client.listunspent(scripthash)
|
entries = await self.client.listunspent(scripthash)
|
||||||
|
|
||||||
async with self._session_factory() as session:
|
async with self._session_factory() as session:
|
||||||
credited = await credit_confirmed_utxos(session, user_id, entries)
|
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:
|
if credited:
|
||||||
logger.info("credited %s new UTXO(s) for user_id=%s", credited, user_id)
|
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:
|
if spent_externally:
|
||||||
logger.warning("%s UTXO(s) spent outside the platform for user_id=%s", spent_externally, user_id)
|
logger.warning("%s UTXO(s) spent outside the platform for user_id=%s", spent_externally, user_id)
|
||||||
@@ -23,6 +23,7 @@ from app.auth.routes import router as auth_router
|
|||||||
from app.api.errors import ApiError
|
from app.api.errors import ApiError
|
||||||
from app.config import settings, validate_runtime_secrets
|
from app.config import settings, validate_runtime_secrets
|
||||||
from app.db.base import AsyncSessionLocal
|
from app.db.base import AsyncSessionLocal
|
||||||
|
from app.deposits.reconcile import DepositReconciler
|
||||||
from app.electrum.client import ElectrumClient, ElectrumEndpoint, parse_endpoints
|
from app.electrum.client import ElectrumClient, ElectrumEndpoint, parse_endpoints
|
||||||
from app.electrum.listener import ElectrumListener
|
from app.electrum.listener import ElectrumListener
|
||||||
from app.rounds.scheduler import RoundScheduler
|
from app.rounds.scheduler import RoundScheduler
|
||||||
@@ -61,6 +62,10 @@ async def lifespan(app: FastAPI):
|
|||||||
# Resolves in-flight transactions against the chain — the piece that lets the
|
# 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).
|
# system recover on its own from a broadcast that never confirmed (B-04/B-08).
|
||||||
reconciler = PendingTransactionReconciler(AsyncSessionLocal, lambda: listener.client)
|
reconciler = PendingTransactionReconciler(AsyncSessionLocal, lambda: listener.client)
|
||||||
|
# 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 = [
|
tasks = [
|
||||||
asyncio.create_task(listener.run()),
|
asyncio.create_task(listener.run()),
|
||||||
@@ -68,6 +73,7 @@ async def lifespan(app: FastAPI):
|
|||||||
asyncio.create_task(poller.run()),
|
asyncio.create_task(poller.run()),
|
||||||
asyncio.create_task(bumper.run()),
|
asyncio.create_task(bumper.run()),
|
||||||
asyncio.create_task(reconciler.run()),
|
asyncio.create_task(reconciler.run()),
|
||||||
|
asyncio.create_task(deposit_reconciler.run()),
|
||||||
]
|
]
|
||||||
try:
|
try:
|
||||||
yield
|
yield
|
||||||
|
|||||||
@@ -1,5 +1,22 @@
|
|||||||
import hashlib
|
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:
|
def header_hex_to_block_hash(header_hex: str) -> str:
|
||||||
"""Block hash from a raw Electrum header: sha256d, byte-reversed, hex.
|
"""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()
|
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:
|
def draw_winner(participants: list[str], block_hash_hex: str) -> str:
|
||||||
"""v1 draw algorithm (flowchart.mmd, node R): seed = block hash as an integer,
|
"""v1 draw algorithm (flowchart.mmd, node R): seed = block hash as an integer,
|
||||||
index = seed mod participant_count, winner = participants[index]. Anyone can
|
index = seed mod participant_count, winner = participants[index]. Anyone can
|
||||||
|
|||||||
+185
-33
@@ -3,11 +3,12 @@ import logging
|
|||||||
from datetime import datetime, timedelta, timezone
|
from datetime import datetime, timedelta, timezone
|
||||||
|
|
||||||
from embit import script
|
from embit import script
|
||||||
|
from embit.transaction import Transaction
|
||||||
from sqlalchemy import func, select
|
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.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.listener import ElectrumListener
|
||||||
from app.electrum.scripthash import address_to_scripthash
|
from app.electrum.scripthash import address_to_scripthash
|
||||||
from app.rounds.config import get_round_config
|
from app.rounds.config import get_round_config
|
||||||
@@ -22,6 +23,13 @@ logger = logging.getLogger(__name__)
|
|||||||
|
|
||||||
_TICK_INTERVAL_SECONDS = 5
|
_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
|
||||||
|
|
||||||
|
|
||||||
class RoundScheduler:
|
class RoundScheduler:
|
||||||
"""Background task implementing flowchart.mmd's DRAW subgraph: closes the
|
"""Background task implementing flowchart.mmd's DRAW subgraph: closes the
|
||||||
@@ -55,8 +63,17 @@ class RoundScheduler:
|
|||||||
round_id, status, opened_at = round_.id, round_.status, round_.opened_at
|
round_id, status, opened_at = round_.id, round_.status, round_.opened_at
|
||||||
round_duration_seconds = (await get_round_config(session)).round_duration_seconds
|
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"):
|
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":
|
if status == "open":
|
||||||
opened_at = opened_at.replace(tzinfo=timezone.utc)
|
opened_at = opened_at.replace(tzinfo=timezone.utc)
|
||||||
@@ -125,7 +142,7 @@ class RoundScheduler:
|
|||||||
broadcaster.publish()
|
broadcaster.publish()
|
||||||
|
|
||||||
tip_at_close = self._listener.tip_height
|
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)
|
||||||
winner_address = draw_winner(addresses, block_hash)
|
winner_address = draw_winner(addresses, block_hash)
|
||||||
|
|
||||||
async with self._session_factory() as session:
|
async with self._session_factory() as session:
|
||||||
@@ -155,22 +172,106 @@ class RoundScheduler:
|
|||||||
logger.info("round %s: winner=%s pool=%s", round_id, winner_address, pool_amount)
|
logger.info("round %s: winner=%s pool=%s", round_id, winner_address, pool_amount)
|
||||||
await self._trigger_payout(round_id)
|
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) -> tuple[int, str]:
|
||||||
while self._listener.tip_height <= tip_at_close or not self._listener.tip_header_hex:
|
"""Waits for a block after tip_at_close and, before handing it back as the
|
||||||
await asyncio.sleep(_TICK_INTERVAL_SECONDS)
|
draw's entropy source, requires it to be corroborated by the other
|
||||||
return self._listener.tip_height, header_hex_to_block_hash(self._listener.tip_header_hex)
|
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."""
|
||||||
|
while True:
|
||||||
|
while self._listener.tip_height <= tip_at_close or not self._listener.tip_header_hex:
|
||||||
|
await asyncio.sleep(_TICK_INTERVAL_SECONDS)
|
||||||
|
height = self._listener.tip_height
|
||||||
|
block_hash = header_hex_to_block_hash(self._listener.tip_header_hex)
|
||||||
|
if await self._listener.corroborate_header(height, block_hash):
|
||||||
|
return height, block_hash
|
||||||
|
logger.error(
|
||||||
|
"round %s: block %s header %s could not be corroborated by other Electrum servers; "
|
||||||
|
"waiting for a further block",
|
||||||
|
round_id,
|
||||||
|
height,
|
||||||
|
block_hash,
|
||||||
|
)
|
||||||
|
async with self._session_factory() as session:
|
||||||
|
await write_audit_log(
|
||||||
|
session,
|
||||||
|
"draw_header_corroboration_failed",
|
||||||
|
{"height": height, "reported_hash": block_hash},
|
||||||
|
round_id=round_id,
|
||||||
|
)
|
||||||
|
await session.commit()
|
||||||
|
tip_at_close = height
|
||||||
|
|
||||||
|
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:
|
async def _trigger_payout(self, round_id: int) -> None:
|
||||||
"""Three phases, so no DB session is held across a network call (B-18): read
|
"""Four 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."""
|
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
|
client = self._listener.client
|
||||||
if client is None:
|
if client is None:
|
||||||
logger.error("round %s payout deferred: not connected", round_id)
|
logger.error("round %s payout deferred: not connected", round_id)
|
||||||
|
await self._log_payout_failure(round_id, None, "electrum client not connected")
|
||||||
return
|
return
|
||||||
|
|
||||||
# --- Phase 1: read (session closed before any network I/O) ---------------
|
# --- Phase 1: read (session closed before any network I/O) ---------------
|
||||||
async with self._session_factory() as session:
|
async with self._session_factory() as session:
|
||||||
round_ = await session.get(Round, round_id)
|
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)
|
config = await get_round_config(session)
|
||||||
fee_address = config.fee_address
|
fee_address = config.fee_address
|
||||||
fee_rate = config.fee_rate_sat_vb
|
fee_rate = config.fee_rate_sat_vb
|
||||||
@@ -184,21 +285,27 @@ class RoundScheduler:
|
|||||||
logger.error(
|
logger.error(
|
||||||
"round %s payout blocked: no fee_address configured (set it via the admin endpoint)", round_id
|
"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
|
return
|
||||||
if winner_address is None:
|
if winner_address is None:
|
||||||
logger.error("round %s payout blocked: winner user %s not found", round_id, winner_user_id)
|
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
|
return
|
||||||
|
|
||||||
winner_share = pool_amount_sats * 70 // 100
|
winner_share = pool_amount_sats * 70 // 100
|
||||||
commission_share = pool_amount_sats - winner_share # remainder from rounding goes to fees
|
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:
|
try:
|
||||||
pool_key = derive_pool_key()
|
pool_key = derive_pool_key()
|
||||||
pool_script_obj = script.p2wpkh(pool_key.to_public())
|
pool_script_obj = script.p2wpkh(pool_key.to_public())
|
||||||
pool_address = pool_script_obj.address(network=PLM_MAINNET)
|
pool_address = pool_script_obj.address(network=PLM_MAINNET)
|
||||||
entries = await client.listunspent(address_to_scripthash(pool_address))
|
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(
|
built = build_payout_transaction(
|
||||||
signing_key=pool_key,
|
signing_key=pool_key,
|
||||||
@@ -211,36 +318,55 @@ class RoundScheduler:
|
|||||||
change_address=pool_address,
|
change_address=pool_address,
|
||||||
fee_rate_sat_vb=fee_rate,
|
fee_rate_sat_vb=fee_rate,
|
||||||
)
|
)
|
||||||
await client.broadcast(built.raw_hex)
|
|
||||||
except InsufficientFundsError:
|
except InsufficientFundsError:
|
||||||
logger.exception("round %s payout failed: insufficient pool UTXOs", round_id)
|
logger.exception("round %s payout failed: insufficient pool UTXOs", round_id)
|
||||||
|
await self._log_payout_failure(round_id, winner_user_id, "insufficient pool UTXOs")
|
||||||
return
|
return
|
||||||
except Exception:
|
except Exception:
|
||||||
# Anything else — a malformed fee_address (EmbitError), a rejected
|
# Anything else — a malformed fee_address (EmbitError) or similar. This
|
||||||
# broadcast, a dead connection. This used to escape all the way to
|
# used to escape all the way to run()'s catch-all, which logged it
|
||||||
# run()'s catch-all, which logged it without recording anything, leaving
|
# without recording anything, leaving no trace of *why* the round was
|
||||||
# no trace of *why* the round was stuck (B-05). The round stays in
|
# stuck (B-05). _retry_payout_if_due (B-26) is what turns this recorded
|
||||||
# "paying_out" either way: automatic payout retry is still an open gap.
|
# failure into an automatic retry instead of a dead end.
|
||||||
logger.exception("round %s payout failed", round_id)
|
logger.exception("round %s payout build failed", round_id)
|
||||||
await self._log_payout_failure(round_id, winner_user_id)
|
await self._log_payout_failure(round_id, winner_user_id, "payout build failed")
|
||||||
return
|
return
|
||||||
|
|
||||||
# --- Phase 3: persist -----------------------------------------------------
|
# --- Phase 3: persist the intent, *then* broadcast (B-25) -----------------
|
||||||
async with self._session_factory() as session:
|
async with self._session_factory() as session:
|
||||||
round_ = await session.get(Round, round_id)
|
round_ = await session.get(Round, round_id)
|
||||||
round_.winner_amount_sats = built.winner_sats
|
round_.winner_amount_sats = built.winner_sats
|
||||||
round_.fee_amount_sats = built.commission_sats
|
round_.fee_amount_sats = built.commission_sats
|
||||||
round_.payout_txid = built.txid
|
round_.payout_txid = built.txid
|
||||||
session.add(
|
pending = PendingTransaction(
|
||||||
PendingTransaction(
|
kind="payout",
|
||||||
kind="payout",
|
round_id=round_id,
|
||||||
round_id=round_id,
|
current_txid=built.txid,
|
||||||
current_txid=built.txid,
|
fee_rate_sat_vb=fee_rate,
|
||||||
fee_rate_sat_vb=fee_rate,
|
raw_tx_hex=built.raw_hex,
|
||||||
raw_tx_hex=built.raw_hex,
|
# "building" until the broadcast succeeds, exactly like place_bet's
|
||||||
status="pending",
|
# 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(
|
await write_audit_log(
|
||||||
session,
|
session,
|
||||||
"payout_sent",
|
"payout_sent",
|
||||||
@@ -252,18 +378,44 @@ class RoundScheduler:
|
|||||||
|
|
||||||
logger.info("round %s payout broadcast: txid=%s", round_id, built.txid)
|
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
|
"""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:
|
try:
|
||||||
async with self._session_factory() as session:
|
async with self._session_factory() as session:
|
||||||
await write_audit_log(
|
await write_audit_log(
|
||||||
session,
|
session,
|
||||||
"payout_failed",
|
"payout_failed",
|
||||||
{"round_id": round_id},
|
{"round_id": round_id, "reason": reason},
|
||||||
user_id=winner_user_id,
|
user_id=winner_user_id,
|
||||||
round_id=round_id,
|
round_id=round_id,
|
||||||
)
|
)
|
||||||
await session.commit()
|
await session.commit()
|
||||||
except Exception:
|
except Exception:
|
||||||
logger.exception("could not record the payout failure of round %s", round_id)
|
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
|
||||||
+53
-14
@@ -14,12 +14,18 @@ from app.electrum.client import ElectrumClient
|
|||||||
from app.rounds.config import get_round_config
|
from app.rounds.config import get_round_config
|
||||||
from app.wallet.hd import derive_pool_key, derive_user_key
|
from app.wallet.hd import derive_pool_key, derive_user_key
|
||||||
from app.wallet.plm_network import PLM_MAINNET
|
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__)
|
logger = logging.getLogger(__name__)
|
||||||
|
|
||||||
_POLL_INTERVAL_SECONDS = 30
|
_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):
|
class RbfError(Exception):
|
||||||
@@ -27,12 +33,19 @@ class RbfError(Exception):
|
|||||||
|
|
||||||
|
|
||||||
def should_bump(pending: PendingTransaction, now: datetime, timeout_seconds: int) -> bool:
|
def should_bump(pending: PendingTransaction, now: datetime, timeout_seconds: int) -> bool:
|
||||||
"""Pure decision: has this pending tx been unconfirmed for longer than the
|
"""Pure decision: has this pending tx gone unconfirmed for longer than the
|
||||||
configured timeout (RoundConfig.rbf_timeout_seconds)? Kept separate from the
|
configured timeout (RoundConfig.rbf_timeout_seconds) *since it was last
|
||||||
I/O-heavy bump_fee() so it's trivially unit-testable."""
|
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":
|
if pending.status != "pending":
|
||||||
return False
|
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, pending: PendingTransaction) -> tuple:
|
||||||
@@ -72,20 +85,38 @@ async def bump_fee(session: AsyncSession, client: ElectrumClient, pending: Pendi
|
|||||||
tx's own sender address, large enough to absorb the increase. If there's no
|
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 —
|
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
|
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 `pending` 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.
|
||||||
"""
|
"""
|
||||||
|
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"
|
||||||
|
)
|
||||||
|
|
||||||
old_tx = Transaction.parse(bytes.fromhex(pending.raw_tx_hex))
|
old_tx = Transaction.parse(bytes.fromhex(pending.raw_tx_hex))
|
||||||
signing_key, own_script, own_address = await _signing_context(session, pending)
|
signing_key, own_script, own_address = await _signing_context(session, pending)
|
||||||
|
|
||||||
input_amounts = [await _prevout_amount(client, vin) for vin in old_tx.vin]
|
input_amounts = [await _prevout_amount(client, vin) for vin in old_tx.vin]
|
||||||
total_in = sum(input_amounts)
|
total_in = sum(input_amounts)
|
||||||
old_fee = total_in - sum(o.value for o in old_tx.vout)
|
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
|
target_fee_rate = min(pending.fee_rate_sat_vb + _FEE_RATE_INCREMENT, MAX_FEE_RATE_SAT_VB)
|
||||||
new_fee = estimate_vsize(len(old_tx.vin), len(old_tx.vout)) * new_fee_rate
|
target_fee = vsize * target_fee_rate
|
||||||
fee_delta = new_fee - old_fee
|
# BIP125 rule 4's minimum, in absolute sats for this tx's size — the floor
|
||||||
if fee_delta <= 0:
|
# `fee_delta` must never go below, no matter what `target_fee - old_fee` comes
|
||||||
fee_delta = _FEE_RATE_INCREMENT # already above the new target vsize*rate; bump by a token amount
|
# 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)
|
change_index = _find_change_output(old_tx, own_address)
|
||||||
if change_index is None or old_tx.vout[change_index].value <= fee_delta:
|
if change_index is None or old_tx.vout[change_index].value <= fee_delta:
|
||||||
@@ -117,9 +148,17 @@ async def bump_fee(session: AsyncSession, client: ElectrumClient, pending: Pendi
|
|||||||
pending.replaced_by_txid = old_txid # points backwards: what current_txid replaced
|
pending.replaced_by_txid = old_txid # points backwards: what current_txid replaced
|
||||||
pending.current_txid = new_txid
|
pending.current_txid = new_txid
|
||||||
pending.raw_tx_hex = raw_hex
|
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.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 _retarget_txid_references(session, pending, old_txid, new_txid)
|
||||||
await session.commit()
|
await session.commit()
|
||||||
|
|
||||||
|
|||||||
@@ -129,6 +129,12 @@ async def reconcile_once(session_factory: async_sessionmaker, client: ElectrumCl
|
|||||||
|
|
||||||
|
|
||||||
def _is_due(row: PendingTransaction, now: datetime) -> bool:
|
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
|
grace = _BUILDING_GRACE_SECONDS if row.status == "building" else _ABANDON_AFTER_SECONDS
|
||||||
return now >= row.broadcast_at.replace(tzinfo=timezone.utc) + timedelta(seconds=grace)
|
return now >= row.broadcast_at.replace(tzinfo=timezone.utc) + timedelta(seconds=grace)
|
||||||
|
|
||||||
|
|||||||
@@ -25,6 +25,14 @@ RBF_SEQUENCE = 0xFFFFFFFD
|
|||||||
# withdrawal fail at broadcast with an opaque error (B-06).
|
# withdrawal fail at broadcast with an opaque error (B-06).
|
||||||
DUST_LIMIT_SATS = 294
|
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
|
||||||
|
|
||||||
|
|
||||||
class InsufficientFundsError(Exception):
|
class InsufficientFundsError(Exception):
|
||||||
"""`code` is the machine-readable identifier the API layer forwards to the
|
"""`code` is the machine-readable identifier the API layer forwards to the
|
||||||
|
|||||||
@@ -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')
|
||||||
@@ -11,7 +11,7 @@ from app.db.base import Base
|
|||||||
from app.db.models import PendingTransaction, User
|
from app.db.models import PendingTransaction, User
|
||||||
from app.tx.broadcast import RbfError, bump_fee, should_bump
|
from app.tx.broadcast import RbfError, bump_fee, should_bump
|
||||||
from app.wallet.plm_network import PLM_MAINNET
|
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:
|
def _key(seed_byte: int) -> HDKey:
|
||||||
@@ -22,7 +22,7 @@ def _key(seed_byte: int) -> HDKey:
|
|||||||
def test_should_bump_false_before_timeout():
|
def test_should_bump_false_before_timeout():
|
||||||
pending = PendingTransaction(
|
pending = PendingTransaction(
|
||||||
kind="bet", current_txid="x", fee_rate_sat_vb=1, raw_tx_hex="00", status="pending",
|
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
|
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(
|
pending = PendingTransaction(
|
||||||
kind="bet", current_txid="x", fee_rate_sat_vb=1, raw_tx_hex="00", status="pending",
|
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),
|
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
|
assert should_bump(pending, datetime.now(timezone.utc), timeout_seconds=900) is True
|
||||||
|
|
||||||
@@ -39,6 +40,19 @@ def test_should_bump_false_when_not_pending():
|
|||||||
pending = PendingTransaction(
|
pending = PendingTransaction(
|
||||||
kind="bet", current_txid="x", fee_rate_sat_vb=1, raw_tx_hex="00", status="confirmed",
|
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),
|
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
|
assert should_bump(pending, datetime.now(timezone.utc), timeout_seconds=900) is False
|
||||||
|
|
||||||
@@ -136,6 +150,63 @@ async def test_bump_fee_shrinks_change_and_rebroadcasts(session_factory):
|
|||||||
assert row.attempt_count == 2
|
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)
|
||||||
|
|
||||||
|
async with session_factory() as session:
|
||||||
|
row = await session.get(PendingTransaction, pending_id)
|
||||||
|
await bump_fee(session, client, row)
|
||||||
|
|
||||||
|
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):
|
async def test_bump_fee_raises_when_no_change_output(session_factory):
|
||||||
from app.wallet.hd import derive_user_address, derive_user_key
|
from app.wallet.hd import derive_user_address, derive_user_key
|
||||||
|
|
||||||
@@ -248,3 +319,132 @@ async def test_bump_fee_retargets_every_stored_txid(session_factory):
|
|||||||
|
|
||||||
utxo = (await session.scalars(select(UtxoEvent))).one()
|
utxo = (await session.scalars(select(UtxoEvent))).one()
|
||||||
assert utxo.spent_txid == new_txid
|
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})
|
||||||
|
|
||||||
|
async with session_factory() as session:
|
||||||
|
row = await session.get(PendingTransaction, pending_id)
|
||||||
|
new_txid = await bump_fee(session, client, row)
|
||||||
|
|
||||||
|
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})
|
||||||
|
|
||||||
|
async with session_factory() as session:
|
||||||
|
row = await session.get(PendingTransaction, pending_id)
|
||||||
|
with pytest.raises(RbfError):
|
||||||
|
await bump_fee(session, client, row)
|
||||||
|
|
||||||
|
assert not client.broadcasted
|
||||||
@@ -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 == []
|
||||||
+111
-10
@@ -4,7 +4,12 @@ from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
|
|||||||
|
|
||||||
from app.db.base import Base
|
from app.db.base import Base
|
||||||
from app.db.models import AuditLog, User, UtxoEvent
|
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
|
@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
|
assert user.cached_balance_sats == 7_000_000
|
||||||
|
|
||||||
|
|
||||||
async def test_external_spend_marks_utxo_spent_and_corrects_balance(session_factory, user_id):
|
# --- B-29: detecting a UTXO spent outside the platform is now a three-step,
|
||||||
entries = [{"tx_hash": "dd" * 32, "tx_pos": 0, "height": 100, "value": 20_000_000}]
|
# 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:
|
async with session_factory() as session:
|
||||||
await credit_confirmed_utxos(session, user_id, entries)
|
await credit_confirmed_utxos(session, user_id, entries)
|
||||||
|
|
||||||
async with session_factory() as session:
|
async with session_factory() as session:
|
||||||
spent = await detect_external_spends(session, user_id, [])
|
candidates = await find_utxos_missing_from(session, user_id, entries)
|
||||||
assert spent == 1
|
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)
|
user = await session.get(User, user_id)
|
||||||
assert user.cached_balance_sats == 0
|
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)
|
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}]
|
entries = [{"tx_hash": "ee" * 32, "tx_pos": 0, "height": 100, "value": 3_000_000}]
|
||||||
async with session_factory() as session:
|
async with session_factory() as session:
|
||||||
await credit_confirmed_utxos(session, user_id, entries)
|
await credit_confirmed_utxos(session, user_id, entries)
|
||||||
|
|
||||||
async with session_factory() as session:
|
async with session_factory() as session:
|
||||||
spent = await detect_external_spends(session, user_id, entries)
|
reinstated = await reinstate_reappeared_utxos(session, user_id, entries)
|
||||||
assert spent == 0
|
assert reinstated == 0
|
||||||
user = await session.get(User, user_id)
|
|
||||||
assert user.cached_balance_sats == 3_000_000
|
|
||||||
+41
-10
@@ -1,19 +1,50 @@
|
|||||||
import pytest
|
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,
|
||||||
|
)
|
||||||
|
|
||||||
|
# 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():
|
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 = (
|
|
||||||
"0020ed30fbc39ee45200d10214f5107c5f36e7bf753032fd1d3279810c170000000000"
|
|
||||||
"009a4ea723f732be4c538f3a2490837dd6560103d73ece606aa7d578a66700447b28875"
|
|
||||||
"e6a47a61b1ad8012582"
|
|
||||||
)
|
|
||||||
known_block_hash = "00000000000008788b55ade13b74d54ceffda9e54315b802411be1ca65064e86"
|
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():
|
def test_draw_winner_is_deterministic_and_within_range():
|
||||||
|
|||||||
@@ -1,5 +1,8 @@
|
|||||||
"""Listener-level behaviour: server rotation on failure (the fallback-servers
|
"""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
|
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
|
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 asyncio
|
||||||
|
import logging
|
||||||
|
import struct
|
||||||
|
|
||||||
import pytest
|
import pytest
|
||||||
|
from sqlalchemy import select
|
||||||
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
|
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
|
||||||
|
|
||||||
from app.db.base import Base
|
from app.db.base import Base
|
||||||
|
from app.db.models import User, UtxoEvent
|
||||||
from app.electrum.client import ElectrumEndpoint
|
from app.electrum.client import ElectrumEndpoint
|
||||||
from app.electrum.listener import ElectrumListener
|
from app.electrum.listener import ElectrumListener
|
||||||
|
from app.rounds.draw import HeaderValidationError, header_hex_to_block_hash, header_meets_its_own_target
|
||||||
|
|
||||||
|
|
||||||
@pytest.fixture
|
@pytest.fixture
|
||||||
@@ -31,6 +39,34 @@ _ENDPOINTS = [
|
|||||||
ElectrumEndpoint("third.example", 50001, False),
|
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):
|
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
|
"""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
|
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):
|
def test_tip_never_moves_backwards(session_factory):
|
||||||
"""B-19: `self.tip_height = header["height"]` accepted a lower height, and
|
"""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
|
_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."""
|
a stale one."""
|
||||||
listener = ElectrumListener(lambda endpoint: None, session_factory, _ENDPOINTS)
|
listener = ElectrumListener(lambda endpoint: None, session_factory, _ENDPOINTS)
|
||||||
|
|
||||||
listener._apply_header({"height": 100, "hex": "aa"})
|
header_100 = _mine_header("00" * 32)
|
||||||
assert (listener.tip_height, listener.tip_header_hex) == (100, "aa")
|
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
|
# A lower height is ignored purely on height, before any header validation even
|
||||||
assert (listener.tip_height, listener.tip_header_hex) == (100, "aa")
|
# 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"})
|
header_101 = _mine_header(header_hex_to_block_hash(header_100))
|
||||||
assert (listener.tip_height, listener.tip_header_hex) == (101, "cc")
|
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
|
||||||
@@ -59,7 +59,14 @@ _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,
|
||||||
|
):
|
||||||
from datetime import datetime, timedelta, timezone
|
from datetime import datetime, timedelta, timezone
|
||||||
|
|
||||||
async with session_factory() as session:
|
async with session_factory() as session:
|
||||||
@@ -85,6 +92,10 @@ async def _seed_bet(session_factory, *, pending_status: str, participant_status:
|
|||||||
status=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(
|
session.add(
|
||||||
PendingTransaction(
|
PendingTransaction(
|
||||||
kind="bet",
|
kind="bet",
|
||||||
@@ -95,6 +106,7 @@ async def _seed_bet(session_factory, *, pending_status: str, participant_status:
|
|||||||
raw_tx_hex=_RAW_TX,
|
raw_tx_hex=_RAW_TX,
|
||||||
status=pending_status,
|
status=pending_status,
|
||||||
broadcast_at=datetime.now(timezone.utc) - timedelta(seconds=age_seconds),
|
broadcast_at=datetime.now(timezone.utc) - timedelta(seconds=age_seconds),
|
||||||
|
last_broadcast_at=datetime.now(timezone.utc) - timedelta(seconds=last_age),
|
||||||
)
|
)
|
||||||
)
|
)
|
||||||
await session.commit()
|
await session.commit()
|
||||||
@@ -167,6 +179,27 @@ async def test_leaves_a_recently_broadcast_pending_row_alone(session_factory):
|
|||||||
assert await reconcile_once(session_factory, UnknownTxClient()) == 0
|
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):
|
async def test_transport_failure_never_abandons_anything(session_factory):
|
||||||
"""A dead connection says nothing about the transaction. Treating it as "gone"
|
"""A dead connection says nothing about the transaction. Treating it as "gone"
|
||||||
would release coins for transactions that are perfectly alive."""
|
would release coins for transactions that are perfectly alive."""
|
||||||
|
|||||||
@@ -4,9 +4,10 @@ import pytest
|
|||||||
from sqlalchemy import select
|
from sqlalchemy import select
|
||||||
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
|
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
|
||||||
|
|
||||||
|
from app.config import settings
|
||||||
from app.db.base import Base
|
from app.db.base import Base
|
||||||
from app.db.models import Round, RoundConfig
|
from app.db.models import AuditLog, PendingTransaction, Round, RoundConfig, User
|
||||||
from app.rounds.scheduler import RoundScheduler
|
from app.rounds.scheduler import RoundScheduler, _reserved_payout_outpoints
|
||||||
|
|
||||||
|
|
||||||
class FakeListener:
|
class FakeListener:
|
||||||
@@ -52,3 +53,353 @@ async def test_tick_closes_round_with_no_participants_once_due(session_factory,
|
|||||||
async with session_factory() as session:
|
async with session_factory() as session:
|
||||||
round_ = (await session.scalars(select(Round))).one()
|
round_ = (await session.scalars(select(Round))).one()
|
||||||
assert round_.status == "closed"
|
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)
|
||||||
|
|
||||||
|
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)
|
||||||
|
|
||||||
|
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"]
|
||||||
Reference in new issue
Block a user