davideandClaude Opus 5
c0314e2bf0
_apply_header's linkage check only fires on a single-block advance, so a header at the height we already held one for was applied on nothing but its own self-consistency — and that check, as header_meets_its_own_target's own docstring says, a server can satisfy with a self-declared easy target. So the one value the draw is seeded from could be replaced under us at the current height, by a reorg at the tip or by a single server disagreeing with the rest, with no check able to speak to it. Separately, a header carrying no hex set tip_header_hex back to None while advancing tip_height, leaving the two describing different blocks — the exact pairing that function exists to keep. Both are now refused without ending the session, unlike the fabrication cases above them: neither is evidence of a hostile server, and rotating away would cost us the one connection that also credits deposits and broadcasts transactions. - A same-height header is ignored (logged when it actually differs). The hash committed to for a height is not swapped under us; if ours turns out to be the orphan, corroborate_header already refuses to seed a draw from it and the draw waits for a further block. - A hex-less header is ignored outright: nothing to validate, nothing to draw from. A server that only ever pushed heights now freezes the draw — visibly, via B-36's draw_stalled — instead of costing us the connection. Because ignoring is not fatal, _run_once additionally refuses to publish the client when the initial header leaves the tip still unknown, so this cannot reopen B-63's window from the other side. The two _run_once tests are bounded with asyncio.wait_for: without their guard that call waits on session tasks nothing ends, and a regression must fail rather than hang the suite. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
PLM Lottery
A periodic-round lottery system built on PLM, a Bitcoin-like coin (mainnet). Each user gets a dedicated server-derived P2WPKH address; 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).
This is a custodial system: private keys are generated and held server-side, encrypted at rest. See CLAUDE.md for the full architecture, domain decisions, and known gaps before treating this as production-ready.
Quick start
The server always runs via Docker (app + Caddy reverse proxy with automatic
TLS) — in dev and production alike, with only SITE_ADDRESS differing
between the two. There's no supported way to run uvicorn directly; the
venv is only for local tooling (tests, Alembic migrations, the one-time key
scripts) — see CLAUDE.md.
cp .env.example .env # then fill in the generated secrets, see docs/setup.md
mkdir -p data/db data/keys data/logs
docker compose run --rm app python scripts/generate_master_key.py
docker compose up -d --build
Open https://localhost/ for the test UI, https://localhost/admin for the
admin dashboard (a self-signed-certificate warning on first visit is
expected in dev — accept it, or use curl -k). The interactive API docs at
/docs are disabled by default (they'd otherwise expose the whole API
surface, admin endpoints included) — set ENABLE_API_DOCS=true in .env to
enable them.
See docs/setup.md and docs/running-the-server.md for the full walkthrough (secrets, master key generation, production TLS with a real domain).
Documentation
- CLAUDE.md — architecture, commands, domain decisions, known gaps (for anyone/anything working on the code)
- flowchart.mmd — the source-of-truth flow diagram the implementation follows node-by-node
- docs/setup.md — one-time setup (secrets, master key, migrations)
- docs/running-the-server.md — how to launch it (local venv vs. Docker+Caddy, dev vs. production TLS)
- docs/guida-utente.md — end-user guide to the test UI (Italian)
- docs/guida-admin.md — admin dashboard guide (Italian)
Tech stack
Python (FastAPI, SQLAlchemy async + Alembic, Argon2 + JWT auth), Electrum protocol for PLM network access (no full node), Docker + Caddy for deployment. See CLAUDE.md for the complete list and the reasoning behind each choice.
Testing
python -m pytest # all tests
python -m pytest tests/unit/test_hd.py # one file
232 unit tests cover HD derivation, PSBT building, the Electrum client, bets, deposits, withdrawals, the round/draw engine, RBF fee-bumping, admin config, the pending-inclusive balance calculation, and the SSE push channel. No automated integration tests against a live Electrum connection — mainnet verification so far has been manual (see CLAUDE.md's "Project status").