davideandClaude Sonnet 5.5
ccd15807ed
`bump_fee` only required `change > fee delta`. A change at the 294 sat minimum (a full-balance
withdrawal) shrank to ~153 sat after the very first minimum bump, relay policy refuses a
replacement with a sub-dust output, and the bumper tried again every 30 seconds for ever, with
nothing but a log line to show for it.
- When what would be left of the reducible output (the user's change, a payout's bump
reserve) is under DUST_LIMIT_SATS the output is dropped and its whole value goes to the fee:
that replacement is valid and the last one possible. If the output does not exist, or even
its whole value is below BIP125's minimum increase (vsize x 1 sat/vB), RbfError. The
recorded fee rate uses the replacement's own, smaller, size.
- RbfError now carries a `reason` (`change_too_small`, `max_fee_rate`, `replacement_rejected`);
RbfBumper._record_failure writes one `rbf_bump_failed` row {pending_transaction_id, kind,
txid, reason, message[:200]} with the row's user_id/round_id, in a transaction of its own,
once per (current txid, reason) - the audit log is the dedupe clock (AUD-09) - and the pending
row is untouched. A new txid or a new reason writes a new row.
- bump_fee's docstring no longer cites the "bet without change" case that B-62 removed.
No existing test changed (all bumps they make leave a change well above dust). New
tests/unit/test_rbf_dust.py: the 294 sat case end to end (recipient untouched, whole change to
the fee, last bump impossible), the exact boundary (leaves 294 kept / leaves 293 dropped), a
change under the minimum increase, a payout's reserve dropped with the winner and fee outputs
byte-identical, and the audit rows for each reason, once per pair, new row on a new txid or
reason, round/user attribution. Mutation-checked: the dust test of the output and the
once-per-pair check each fail tests.
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
|
|
```
|
|
|
|
681 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").
|