davideandClaude Sonnet 5.5
a4b160e240
reconcile_once abandoned a row when the *active* server's history lacked its txid:
after 120s for `building` (which a restart onto a different server makes likely),
after 6h for `pending`, and all at once after a forward clock jump. It re-checked the
status but not the txid, so it raced the bumper, and a `failed` row was never looked at
again.
- The reconciler asks every server (ElectrumListener.get_histories, active + others) for
the history of the row's address and looks for every txid of the row. Present on any
server -> promoted (adopting the version found). Absent is only "no server of the
quorum knows it" and needs the active server plus the quorum minimum of the others to
have answered; even then nothing is released without proof:
(a) an input spent in a block by a transaction that is none of the row's versions,
agreed by a strict majority of a quorum of the other servers (confirmed_spender), or
(b) a rebroadcast of the latest raw tx to every server (rebroadcast_everywhere)
refused by all of them, explicitly, for missing/spent inputs.
Accepted or "already known" by any server means alive; a fee refusal is not proof
(`building` -> `pending` for the bumper, `pending` untouched); too few answers or
anything else leaves the row alone. failure_reason names the proof.
- The write re-reads status *and* current_txid under begin_immediate (TX-26).
- pending_transactions.failed_at (set by _abandon and _release_failed_withdrawal) starts
a 14-day watch: a failed row that a majority of the other servers (at least the quorum
minimum) list in a block becomes `confirmed`, writes pending_tx_resurrected once and
pauses the lottery with paused_reason `resurrected_tx`; linked rows are not corrected.
The confirmation is by quorum of histories for now; merkle proofs come with B-83.
- round_config.paused_reason (migration b7d2e41c9a05, with the failed_at one): `operator`
from POST /admin/pause (which accepts an optional `note` and never overwrites an
automatic reason), cleared by resume, which logs the reason it lifted; exposed on
/admin/config and GET /rounds/current. rounds/pause.py:pause_automatically is the
system's way in.
- PendingTransactionReconciler takes the listener as `network`; with none it can promote
but never abandon.
Tests changed because the spec changed: the three reconciler tests that expect an
abandonment (and the one in test_tx_versions) now supply a network that proves the
transaction is gone.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
70 lines
3.5 KiB
Markdown
70 lines
3.5 KiB
Markdown
# 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](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](CLAUDE.md#commands).
|
|
|
|
```bash
|
|
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](docs/setup.md) and
|
|
[docs/running-the-server.md](docs/running-the-server.md) for the full
|
|
walkthrough (secrets, master key generation, production TLS with a real
|
|
domain).
|
|
|
|
## Documentation
|
|
|
|
- [CLAUDE.md](CLAUDE.md) — architecture, commands, domain decisions, known gaps (for anyone/anything working on the code)
|
|
- [docs/README.md](docs/README.md) — **index of all documentation** (docs-first, single source of truth, one ADR per decision: [docs/adr/](docs/adr/README.md))
|
|
- [docs/come-funziona.md](docs/come-funziona.md) — the specification (Italian): how the platform works, with diagrams and traceable requirement IDs; it indexes every per-topic document (flows, architecture, data model, API, security, audit log, operations, decisions and limits, bug history). [docs/processo-di-modifica.md](docs/processo-di-modifica.md) describes how a change goes from the spec to the code
|
|
- [docs/setup.md](docs/setup.md) — one-time setup (secrets, master key, migrations)
|
|
- [docs/running-the-server.md](docs/running-the-server.md) — how to launch it with Docker+Caddy (dev vs. production TLS)
|
|
- [docs/guida-utente.md](docs/guida-utente.md) — end-user guide to the test UI (Italian)
|
|
- [docs/guida-admin.md](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](CLAUDE.md#tech-stack) for the complete list
|
|
and the reasoning behind each choice.
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
python -m pytest # all tests
|
|
python -m pytest tests/unit/test_hd.py # one file
|
|
```
|
|
|
|
516 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").
|