Persist the payout before broadcasting it (B-25)
_trigger_payout used to broadcast the payout transaction and only afterwards write payout_txid and its PendingTransaction. A crash in that window (docker-compose.yml auto-restarts on crash) left a payout on-chain with zero record: the round stuck in paying_out, nothing for the reconciler to resolve, and a manual retry that would have paid the winner a second time. This mirrors B-08, which already fixed the same gap for place_bet/request_withdrawal. _trigger_payout now has four phases: read, build (network read only, no write), persist the intent as a PendingTransaction(kind="payout", status="building") and commit, then broadcast and promote to "pending". A rejected broadcast now leaves that "building" row for tx/reconcile.py to resolve — its existing building/pending handling already covers a payout kind correctly, including clearing payout_txid on abandonment, so reconcile.py needed no changes. Since pool UTXOs aren't tracked in utxo_events and so can never be reserved/released the way a user's own UTXOs are, two guards go along with the two-phase write: _trigger_payout now refuses to build a second payout for a round that already has a non-terminal PendingTransaction, and the payout builder excludes any UTXO already referenced by any non-terminal payout transaction (_reserved_payout_outpoints) so a stale payout from an earlier round the reconciler hasn't abandoned yet can't be double-spent by a fresh attempt. This makes a payout retry safe; making one happen automatically is B-26, still open. BUGS.md moves B-25 to "Previously fixed" with the fix description; the suite grows from 139 to 143 tests. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
43d2321e0f
commit
f13f6850b7
3 files changed
+342
-57
No files matched your search
@@ -1,20 +1,21 @@
|
||||
# Known bugs
|
||||
|
||||
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
|
||||
is green, so none of these are caught by existing coverage — every fix should land with a
|
||||
regression test.
|
||||
7 medium, 8 low), listed below as B-25 … B-49. B-25 is fixed as of 2026-07-27; the other 24
|
||||
are open. 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 (B-25's four tests brought the
|
||||
suite to 143).
|
||||
|
||||
The recurring pattern across B-25, B-26, B-27, B-29 and B-36 is worth stating once: the code
|
||||
is rigorous about the failure modes that have actually been hit, and silent about the ones
|
||||
that have not. Outgoing transactions reconcile; deposits do not. Bets and withdrawals write
|
||||
their intent before broadcasting; the payout does not. Broadcast failures are audit-logged;
|
||||
*pre*-broadcast failures (no client, insufficient pool funds) are not.
|
||||
The recurring pattern across B-26, B-27, B-29 and B-36 is worth stating once: the code is
|
||||
rigorous about the failure modes that have actually been hit, and silent about the ones that
|
||||
have not. Outgoing transactions reconcile; deposits do not. Broadcast failures are
|
||||
audit-logged; *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.
|
||||
**Highest remaining priority: make `paying_out` fully recoverable, not just idempotent.**
|
||||
B-25 made a payout retry *safe* (persisted before broadcast, guarded against double-spend);
|
||||
B-26 is what would make a retry actually *happen* automatically. Together with the
|
||||
already-known "scheduler doesn't resume" gap, that's 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,
|
||||
single-process assumptions, no user-facing history, etc.), see "Known gaps / TODO" in
|
||||
@@ -24,27 +25,6 @@ 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
|
||||
@@ -383,6 +363,42 @@ already does.
|
||||
|
||||
## Previously fixed
|
||||
|
||||
### B-25 — The payout has no two-phase write, unlike bets and withdrawals
|
||||
|
||||
`rounds/scheduler.py` used to broadcast the payout and only afterwards write `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 — left a payout on-chain
|
||||
with **no record at all**: the round stuck in `paying_out`, the reconciler with nothing to
|
||||
resolve, and a manual retry that would pay the winner a second time (pool UTXOs are not
|
||||
tracked in `utxo_events`, so nothing reserved them).
|
||||
|
||||
This was exactly what B-08 fixed for `place_bet`/`request_withdrawal`; the same fix had never
|
||||
been applied to the path that moves the most money.
|
||||
|
||||
**Fixed:** `_trigger_payout` (`rounds/scheduler.py`) now has four phases instead of three —
|
||||
read, *build* (network read only, no write), *persist the intent as `PendingTransaction(kind=
|
||||
"payout", status="building")` and commit*, then broadcast and promote to `"pending"`. A
|
||||
broadcast rejection now leaves that `"building"` row behind for the existing reconciler
|
||||
(`tx/reconcile.py`) to resolve — its generic `building`/`pending` handling already covered a
|
||||
`payout` kind correctly (including clearing `payout_txid` on abandonment), so no changes were
|
||||
needed there.
|
||||
|
||||
Two guards were added alongside the two-phase write, since pool UTXOs are invisible to
|
||||
`utxo_events` and so can never be released/reserved the way a user's own UTXOs are:
|
||||
`_trigger_payout` now refuses to build a second payout for a round that already has a
|
||||
non-terminal `PendingTransaction(kind="payout")`, and the payout builder excludes any UTXO
|
||||
already referenced by *any* non-terminal payout transaction (`_reserved_payout_outpoints`) —
|
||||
not just this round's — so a stale payout from an earlier round that the reconciler hasn't
|
||||
abandoned yet can't be double-spent by a fresh attempt. `should_bump`/reconciler retry timing
|
||||
around a fee-bumped payout is unaffected by this fix (see B-27, still open).
|
||||
|
||||
This makes a payout retry *safe*; it does not yet make one *automatic* — that is B-26, still
|
||||
open. Regression tests: `tests/unit/test_scheduler.py`
|
||||
(`test_trigger_payout_persists_before_broadcasting`,
|
||||
`test_trigger_payout_broadcast_failure_leaves_a_recoverable_row`,
|
||||
`test_trigger_payout_skips_when_already_in_flight`,
|
||||
`test_reserved_payout_outpoints_excludes_utxos_claimed_by_a_stale_payout`).
|
||||
|
||||
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,
|
||||
7 high, 7 medium, 5 low. All 24 were fixed and verified against the current code on
|
||||
|
||||
Reference in new issue
Block a user