A4: round lifecycle, commit-reveal draw and simulated chain (RND-41..44, ADR-57, ADR-59)

lifecycle.tick runs the round from open to closed one write-locked step at a
time, resumable from the database (an interrupted draw gives the same
winner). Draw primitives move to plm_engine.draw and are shared with the old
module. SimulatedChain and settle() stand in for blocks and confirmations;
the worker runs both every tick and opens the first round. The round secret
is stored encrypted and revealed with the winner; the proof exposes no
usernames. Mutation checks confirmed the wait for in-flight bets and the
txid ordering are caught by the tests.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
davideandClaude Sonnet 5.5 committed 2026-11-16 13:43:09 +01:00
1 parent eded058dbb
commit 1d4b53d778
17 files changed
+978 -67

No files matched your search

+2 -2
View File
@@ -8,7 +8,7 @@ The user communicates in Italian in chat — reply to them in Italian. Everythin
## Project status
All 10 stages of the original build order are code-complete and unit-tested — 884 tests, the old stack's under `tests/unit/` and the Django ones under `tests/django/` (`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.
All 10 stages of the original build order are code-complete and unit-tested — 912 tests, the old stack's under `tests/unit/` and the Django ones under `tests/django/` (`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.
Verified on mainnet with real money: registration + address derivation, deposit crediting (at the time, 1-conf; deposits now need `deposit_confirmations`), 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.
@@ -61,7 +61,7 @@ PYTHONPATH=. python scripts/decrypt_master_key.py # ops recovery: decrypt+pr
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 # all 884 tests
python -m pytest # all 912 tests
python -m pytest tests/unit/test_hd.py # one file
python -m pytest tests/unit/test_hd.py::test_derivation_is_deterministic # one test
```
+1
View File
@@ -14,6 +14,7 @@ RUN pip install --no-cache-dir --require-hashes --no-deps -r requirements.lock
COPY pyproject.toml manage.py ./
COPY config ./config
COPY apps ./apps
COPY plm_engine ./plm_engine
RUN pip install --no-cache-dir --no-deps . \
&& DJANGO_DEBUG=true python manage.py collectstatic --noinput \
+1 -1
View File
@@ -62,7 +62,7 @@ python -m pytest # all tests
python -m pytest tests/unit/test_hd.py # one file
```
884 unit tests cover HD derivation, PSBT building, the Electrum client, bets,
912 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
+11 -54
View File
@@ -1,5 +1,4 @@
import hashlib
import secrets
# Byte offsets of a standard 80-byte block header: version(4) + prev_block(32) +
# merkle_root(32) + timestamp(4) + bits(4) + nonce(4).
@@ -89,56 +88,14 @@ def header_meets_its_own_target(header_hex: str) -> bool:
return hash_int <= target
def sha256_hex(data: bytes) -> str:
return hashlib.sha256(data).hexdigest()
def new_server_seed() -> str:
"""B-73 (RND-34, DAT-64): a round's secret — 32 random bytes from the OS CSPRNG, as
64 lowercase hex characters."""
return secrets.token_bytes(32).hex()
def server_seed_commitment(server_seed_hex: str) -> str:
"""`server_seed_hash`: sha256 of the secret's 32 bytes, published from the opening of
the round so the operator cannot change the secret afterwards (RND-34)."""
return sha256_hex(bytes.fromhex(server_seed_hex))
def participants_hash(rows: list[tuple[str, int, str]]) -> str:
"""The fingerprint of the ordered draw list (RND-14): sha256 of one `txid:vout:address`
line per participant, in `draw_position` order, each line ending in `\n`, UTF-8. `txid`
is the bet transaction's, lowercase hex as explorers show it; `vout` is the output paying
the round's pool address, in decimal; `address` is the participant's own."""
text = "".join(f"{txid}:{vout}:{address}\n" for txid, vout, address in rows)
return sha256_hex(text.encode("utf-8"))
def draw_seed(server_seed_hex: str, block_hash_hex: str, participants_hash_hex: str) -> int:
"""RND-17: sha256 of the secret (32 bytes), the hash of the block at `draw_height` (32
bytes, in the order explorers show it) and `participants_hash` (32 bytes), read as an
unsigned big-endian integer. Nobody who lacks the secret can predict it, and the
operator, who knows the secret, cannot know the block when committing to the list."""
digest = hashlib.sha256(
bytes.fromhex(server_seed_hex) + bytes.fromhex(block_hash_hex) + bytes.fromhex(participants_hash_hex)
).digest()
return int.from_bytes(digest, "big")
def draw_index(seed: int, participant_count: int) -> int:
"""The winner's `draw_position`: seed modulo the number of participants. Every
participant holds exactly one position, so odds are equal whatever the amount."""
if participant_count <= 0:
raise ValueError("no participants to draw from")
return seed % participant_count
def draw_winner(participants: list[str], server_seed_hex: str, block_hash_hex: str, participants_hash_hex: str) -> str:
"""The v1 draw algorithm (docs/ciclo-di-vita-del-round.md RND-17), recomputable by anyone
from the public proof (GET /rounds/{id}/proof): `participants` are the entries in
`draw_position` order, the winner is the one at `draw_index(draw_seed(...), n)`. Deliberately
simple and replaceable."""
if not participants:
raise ValueError("no participants to draw from")
seed = draw_seed(server_seed_hex, block_hash_hex, participants_hash_hex)
return participants[draw_index(seed, len(participants))]
# The draw primitives live in `plm_engine.draw` (shared with the Django site); re-exported here so the
# old modules and their tests keep working until the old backend is removed (roadmap D1).
from plm_engine.draw import ( # noqa: E402,F401
draw_index,
draw_seed,
draw_winner,
new_server_seed,
participants_hash,
server_seed_commitment,
sha256_hex,
)
+11
View File
@@ -0,0 +1,11 @@
"""The address under which a participant appears in the public draw list (RND-14, DAT-65)."""
from django.conf import settings
from .simulation import simulated_address
def participant_address(user) -> str:
if settings.LEDGER_BACKEND == "simulated":
return simulated_address(user)
raise NotImplementedError("HD addresses arrive with phase B (roadmap B4)")
+236
View File
@@ -0,0 +1,236 @@
"""The life of a round, one step at a time (RND-01 .. RND-36, roadmap A4).
`tick` is what the worker runs every few seconds. It holds no state: everything it needs is in the
database (the secret, the ordered list with positions, its fingerprint, the draw height), so a round
found in any status after a crash or a restart is simply continued, and a draw that was interrupted
gives the same winner it would have given (RND-36). Each step is one write-locked transaction with its
audit row (ARC-77); a step that fails leaves the round exactly where it was.
open -> closing -> drawing -> paying_out -> closed
Rounds never overlap (ADR-22): the next one opens only when the previous is closed, its cooldown has
elapsed, and the lottery is not paused after the round in progress (ADR-57).
"""
import logging
from datetime import datetime, timedelta
from django.conf import settings
from django.db import IntegrityError, transaction
from django.utils import timezone
from plm_engine.draw import (
draw_index,
draw_seed,
new_server_seed,
participants_hash,
server_seed_commitment,
)
from . import audit
from .addresses import participant_address
from .ledger import Ledger, get_ledger
from .models import LotteryConfig, Participation, Round
from .rules import round_deadline
from .seedbox import decrypt_seed, encrypt_seed
from .simulation import SimulatedChain
logger = logging.getLogger(__name__)
WORKER = "worker"
_MAX_STEPS_PER_TICK = 8
# --- opening -----------------------------------------------------------------------------------
def rounds_can_open(config: LotteryConfig) -> bool:
"""A real round pays its commission to `fee_address`, so without one it would take bets and only
then discover it cannot be paid (ADR-29). The simulated ledger moves no coins and needs none."""
if settings.LEDGER_BACKEND == "simulated":
return True
return bool(config.fee_address.strip())
def get_active_round() -> Round | None:
return Round.objects.filter(status__in=Round.ACTIVE_STATUSES).first()
def open_new_round_if_needed(now: datetime | None = None) -> Round | None:
"""The active round if there is one; otherwise a fresh round, unless the cooldown of the last one has
not elapsed, the lottery is paused after the round in progress, or the instance cannot pay a winner.
The round copies its rules from the configuration *now* and keeps them (DAT-61, ADR-10)."""
now = now or timezone.now()
with transaction.atomic():
active = get_active_round()
if active is not None:
return active
config = LotteryConfig.get()
if config.pause_after_round or not rounds_can_open(config):
return None
last = Round.objects.filter(status=Round.Status.CLOSED).order_by("-id").first()
if last is not None and last.closed_at is not None:
# The gap the closed round announced is the one honoured, whatever the config says now.
if now < last.closed_at + timedelta(seconds=last.cooldown_seconds):
return None
seed = new_server_seed()
try:
with transaction.atomic():
round_ = Round.objects.create(
opened_at=now,
duration_seconds=config.round_duration_seconds,
cooldown_seconds=config.round_cooldown_seconds,
bet_amount_sats=config.bet_amount_sats,
fee_address=config.fee_address.strip(),
max_round_pool_sats=config.max_round_pool_sats,
draw_confirmations=config.draw_confirmations,
server_seed_hash=server_seed_commitment(seed), # public from now on (RND-34)
server_seed_enc=encrypt_seed(seed), # the secret itself stays hidden until the reveal
)
except IntegrityError: # another process opened one first (ADR-22): use theirs
return get_active_round()
audit.record("round_opened", actor_label=WORKER, subject_type="round", subject_id=round_.pk,
payload={"server_seed_hash": round_.server_seed_hash, "bet_amount_sats": round_.bet_amount_sats,
"duration_seconds": round_.duration_seconds})
return round_
# --- one tick ----------------------------------------------------------------------------------
def tick(*, now: datetime | None = None, chain: SimulatedChain | None = None, ledger: Ledger | None = None) -> int:
"""Advance the active round as far as it can go right now. Returns the number of steps taken."""
chain = chain or SimulatedChain()
ledger = ledger or get_ledger()
steps = 0
for _ in range(_MAX_STEPS_PER_TICK):
if not _step(now or timezone.now(), chain, ledger): # a fixed `now` is for tests; otherwise time moves on
break
steps += 1
return steps
def _step(now: datetime, chain, ledger: Ledger) -> bool:
round_ = get_active_round()
if round_ is None:
return open_new_round_if_needed(now) is not None
if round_.status == Round.Status.OPEN:
return _close_betting(round_, now)
if round_.status == Round.Status.CLOSING:
return _close_and_draw(round_, chain, now)
if round_.status == Round.Status.DRAWING:
return _complete_draw(round_, chain, now)
return _pay_out(round_, ledger, now)
def _close_betting(round_: Round, now: datetime) -> bool:
"""The deadline passed: from here on no bet is accepted, whatever the wait for in-flight bets takes."""
if now < round_deadline(round_):
return False
with transaction.atomic():
fresh = Round.objects.get(pk=round_.pk)
if fresh.status != Round.Status.OPEN:
return False
fresh.status = Round.Status.CLOSING
fresh.save(update_fields=["status"])
return True
def _close_and_draw(round_: Round, chain, now: datetime) -> bool:
"""Once no bet is in flight: close the round if nobody took part, otherwise commit to the draw — fix the
list, its fingerprint and the height, and enter `drawing` — all in one transaction (RND-13, RND-14)."""
with transaction.atomic():
fresh = Round.objects.get(pk=round_.pk)
if fresh.status != Round.Status.CLOSING:
return False
# "Yellow light": wait for every bet already placed to confirm, so none is lost at the boundary.
if Participation.objects.filter(round=fresh, status=Participation.Status.PENDING).exists():
return False
# The draw order is the bet txid, ascending: public data with no ties, which anyone can check
# (RND-14); never a server-side timestamp.
participants = list(
Participation.objects.filter(round=fresh, status=Participation.Status.CONFIRMED)
.select_related("user").order_by("bet_txid")
)
if not participants:
fresh.status, fresh.closed_at = Round.Status.CLOSED, now
fresh.server_seed = decrypt_seed(fresh.server_seed_enc) # nothing drawn: nothing left to protect
fresh.save(update_fields=["status", "closed_at", "server_seed"])
audit.record("round_closed", actor_label=WORKER, subject_type="round", subject_id=fresh.pk,
payload={"participants": 0})
return True
tip = chain.tip_height(now)
for position, participant in enumerate(participants):
participant.draw_position = position
participant.save(update_fields=["draw_position"])
fresh.participants_hash = participants_hash(
[(p.bet_txid, p.bet_vout, participant_address(p.user)) for p in participants]
)
fresh.draw_height = tip + 1 # a block that did not exist when the list was fixed (RND-19)
fresh.pool_amount_sats = sum(p.bet_amount_sats for p in participants)
fresh.status, fresh.drawing_started_at = Round.Status.DRAWING, now
fresh.save(update_fields=["participants_hash", "draw_height", "pool_amount_sats", "status", "drawing_started_at"])
audit.record("draw_committed", actor_label=WORKER, subject_type="round", subject_id=fresh.pk,
payload={"participants_hash": fresh.participants_hash, "draw_height": fresh.draw_height,
"participants": len(participants), "server_seed_hash": fresh.server_seed_hash})
return True
def _complete_draw(round_: Round, chain, now: datetime) -> bool:
"""The draw of a round in `drawing`, from nothing but what the database holds (RND-36): wait for the block at
`draw_height` to have its confirmations and to exist, compute the winner and reveal the secret in the same
transaction that stores it."""
required_tip = round_.draw_height + round_.draw_confirmations - 1
if chain.tip_height(now) < required_tip:
return False
block_hash = chain.agreed_block_hash(round_.draw_height, now)
if block_hash is None:
return False # asked again at the next tick — never another block (RND-16)
with transaction.atomic():
fresh = Round.objects.get(pk=round_.pk)
if fresh.status != Round.Status.DRAWING or fresh.winner_id is not None:
return False
server_seed = decrypt_seed(fresh.server_seed_enc)
if server_seed_commitment(server_seed) != fresh.server_seed_hash:
raise RuntimeError(f"round {fresh.pk}: the stored secret does not match its published commitment")
participants = list(
Participation.objects.filter(round=fresh, draw_position__isnull=False)
.select_related("user").order_by("draw_position")
)
rows = [(p.bet_txid, p.bet_vout, participant_address(p.user)) for p in participants]
if participants_hash(rows) != fresh.participants_hash:
raise RuntimeError(f"round {fresh.pk}: the draw list no longer matches its published fingerprint")
seed = draw_seed(server_seed, block_hash, fresh.participants_hash)
winner = participants[draw_index(seed, len(participants))]
fresh.draw_block_hash, fresh.winner = block_hash, winner.user
fresh.server_seed = server_seed # the reveal, in the same transaction as the winner (RND-18)
fresh.status = Round.Status.PAYING_OUT
fresh.save(update_fields=["draw_block_hash", "winner", "server_seed", "status"])
audit.record("winner_drawn", actor_label=WORKER, subject_type="round", subject_id=fresh.pk,
payload={"draw_height": fresh.draw_height, "block_hash": block_hash,
"participants": len(participants), "participants_hash": fresh.participants_hash,
"server_seed": server_seed, "seed": f"{seed:064x}",
"winner_position": winner.draw_position})
return True
def _pay_out(round_: Round, ledger: Ledger, now: datetime) -> bool:
"""Create the payout once (idempotent), and close the round when it has confirmed."""
changed = False
if round_.payout_transaction_id is None:
ledger.pay_winner(round_.pk)
changed = True
round_.refresh_from_db()
with transaction.atomic():
fresh = Round.objects.select_related("payout_transaction").get(pk=round_.pk)
if fresh.status != Round.Status.PAYING_OUT or fresh.payout_transaction.status != "confirmed":
return changed
fresh.status, fresh.closed_at = Round.Status.CLOSED, now
fresh.save(update_fields=["status", "closed_at"])
audit.record("round_closed", actor_label=WORKER, subject_type="round", subject_id=fresh.pk,
payload={"participants": fresh.participations.filter(status="confirmed").count(),
"pool_amount_sats": fresh.pool_amount_sats})
return True
+18 -6
View File
@@ -1,7 +1,7 @@
"""The background worker process (ADR-55).
A1 ships the process shell only: it starts, logs, stops cleanly on SIGTERM and shows up as a
compose service. The round scheduler (A4) and the chain tasks (Phase B) plug into `tick`.
"""The background worker process (ADR-55): runs the round lifecycle every few seconds and, on the
simulated ledger, settles the confirmations that a real chain would bring (roadmap A4). The chain tasks
of phase B plug into `tick` too. A step that fails is logged and retried at the next tick: the lifecycle
keeps no state outside the database.
"""
import logging
@@ -16,7 +16,14 @@ TICK_SECONDS = 5
def tick() -> None:
"""One pass over everything the worker is responsible for. Empty until A4."""
"""One pass over everything the worker is responsible for."""
from django.conf import settings
from apps.lottery import lifecycle, simulation
if settings.LEDGER_BACKEND == "simulated":
simulation.settle()
lifecycle.tick()
class Command(BaseCommand):
@@ -32,7 +39,12 @@ class Command(BaseCommand):
logger.info("worker started")
while not stop.is_set():
tick()
try:
tick()
except Exception: # a failed step leaves the round where it was; the next tick retries
logger.exception("worker tick failed")
if options["once"]:
raise
if options["once"]:
break
stop.wait(TICK_SECONDS)
+28
View File
@@ -0,0 +1,28 @@
"""A round's secret, encrypted at rest (DAT-64, RND-34).
The plaintext secret is written to the database only at the reveal; until then a copy of the database
alone must not tell who will win. Fernet with a key derived from `DJANGO_SECRET_KEY`. When the master
key file returns for the real engine (roadmap B4) this is where it plugs in.
"""
import base64
import hashlib
from cryptography.fernet import Fernet, InvalidToken
from django.conf import settings
def _fernet() -> Fernet:
key = hashlib.sha256(b"plm-lottery/round-seed/" + settings.SECRET_KEY.encode()).digest()
return Fernet(base64.urlsafe_b64encode(key))
def encrypt_seed(seed_hex: str) -> str:
return _fernet().encrypt(seed_hex.encode()).decode()
def decrypt_seed(token: str) -> str:
try:
return _fernet().decrypt(token.encode()).decode()
except InvalidToken as exc:
raise RuntimeError("the round secret cannot be decrypted with this key") from exc
+70
View File
@@ -0,0 +1,70 @@
"""The simulated chain and its confirmations (ADR-59, roadmap A4).
A chain that exists only in time: block `h` is the one produced `h` block-intervals after a fixed epoch,
and its hash is a pure function of `h`. Nothing is stored, so a restart changes nothing. Bets, deposits and
payouts of the simulated ledger confirm a few seconds after they are made (`settle`).
"""
import hashlib
from datetime import datetime, timedelta, timezone
from django.conf import settings
from django.utils import timezone as dj_timezone
from .models import ChainTransaction, Movement, Participation, Round
EPOCH = datetime(2026, 1, 1, tzinfo=timezone.utc)
BASE_HEIGHT = 1000
def simulated_block_hash(height: int) -> str:
return hashlib.sha256(f"simulated-block:{height}".encode()).hexdigest()
class SimulatedChain:
"""What the round engine asks of a chain: where the tip is, and the hash of a block at a height."""
def tip_height(self, now: datetime | None = None) -> int:
now = now or dj_timezone.now()
return BASE_HEIGHT + int((now - EPOCH).total_seconds() // settings.SIMULATED_BLOCK_SECONDS)
def agreed_block_hash(self, height: int, now: datetime | None = None) -> str | None:
"""The hash of the block at exactly `height`, or None while it does not exist yet (RND-16)."""
if height > self.tip_height(now):
return None
return simulated_block_hash(height)
def settle(now: datetime | None = None) -> int:
"""Confirm what has been waiting long enough. Returns how many operations were confirmed."""
from .ledger import SimulatedLedger
now = now or dj_timezone.now()
cutoff = now - timedelta(seconds=settings.SIMULATED_CONFIRM_SECONDS)
ledger, confirmed = SimulatedLedger(), 0
for movement in Movement.objects.filter(
kind=Movement.Kind.DEPOSIT, status=Movement.Status.PENDING, created_at__lte=cutoff
):
ledger.confirm_deposit(movement)
confirmed += 1
for chain_tx in ChainTransaction.objects.filter(
status=ChainTransaction.Status.PENDING, broadcast_at__lte=cutoff
):
if chain_tx.kind == ChainTransaction.Kind.BET:
participation = Participation.objects.filter(bet_txid=chain_tx.current_txid).first()
if participation is not None:
ledger.confirm_bet(participation)
confirmed += 1
elif chain_tx.kind == ChainTransaction.Kind.PAYOUT:
round_ = Round.objects.filter(payout_transaction=chain_tx).first()
if round_ is not None:
ledger.confirm_payout(round_.pk)
confirmed += 1
return confirmed
def simulated_address(user) -> str:
"""A stable, pseudonymous address for a participant in the public proof (WEB-12): derived from the
account id, it reveals no username. The real HD address replaces it in phase B (roadmap B4)."""
return "rplm1sim" + hashlib.sha256(f"simulated-address:{user.pk}".encode()).hexdigest()[:32]
+5
View File
@@ -154,3 +154,8 @@ if LEDGER_BACKEND not in ("simulated", "chain"):
raise ImproperlyConfigured(f"LEDGER_BACKEND must be 'simulated' or 'chain', not {LEDGER_BACKEND!r}")
if LEDGER_BACKEND == "simulated" and PLM_NETWORK == "mainnet":
raise ImproperlyConfigured("the simulated ledger cannot run on mainnet (ADR-59)")
# The simulated chain (ADR-59): a block every N seconds and a confirmation after M, so a whole round
# runs in a few minutes on localhost. Real chains ignore both.
SIMULATED_BLOCK_SECONDS = int(os.environ.get("SIMULATED_BLOCK_SECONDS", "20"))
SIMULATED_CONFIRM_SECONDS = int(os.environ.get("SIMULATED_CONFIRM_SECONDS", "5"))
+46
View File
@@ -585,3 +585,49 @@ Due livelli indipendenti:
- ~~[RND-32]~~ Assorbito da [RND-36]: nel comportamento atteso un round in
`drawing` riprende da solo dopo un riavvio o un errore (B-81).
## Il ciclo nel sito Django (migrazione in corso)
Il worker del nuovo sito ([ADR-55](adr/ADR-55-sqlite-wal-web-worker-processi-separati.md)) porta in `apps/lottery/lifecycle.py`
la stessa macchina a stati e le stesse regole di sopra, sul modello Django ([DAT-78]); finché il vecchio scheduler non
è rimosso (roadmap D1) il resto del documento resta lo stato storico. In particolare valgono, con questo codice:
apertura con parametri copiati ([RND-05], [DAT-61]), un solo round attivo ([RND-02]), scadenza propria del round
([RND-11], [ADR-23](adr/ADR-23-limite-scommettere-scadenza-round-stesso-suo.md)), attesa delle puntate in volo ([RND-13]),
elenco ordinato per txid con impronta e altezza fissati in una transazione ([RND-14], [RND-19], [DAT-65]), attesa delle
conferme del blocco e blocco mai sostituito ([RND-15], [RND-16]), vincitore ricalcolabile e rivelazione del segreto con
il vincitore ([RND-17], [RND-18]), ripresa dopo un errore con lo stesso vincitore ([RND-36]), pagamento 70/30 ([RND-21])
e pausa che ferma solo il round successivo ([ADR-57](adr/ADR-57-due-pause-distinte-dopo-round-e-incidente.md)).
*Codice:* `apps/lottery/lifecycle.py` · *Test:* `tests/django/test_lifecycle.py`. Aggiunte e differenze:
- **[RND-41]** **Un passo alla volta, senza stato in memoria.** `lifecycle.tick` esegue i passi che il round può fare
adesso (al massimo 8 per chiamata) e si ferma; ogni passo è una transazione con blocco di scrittura e la sua riga di
audit ([ARC-77]), e rilegge il round dentro la transazione. Un passo che fallisce lascia il round dov'era; il tick
successivo lo riprende da quello che il database contiene. Un tick che non cambia nulla non scrive nulla.
*Stato:* implementato (A4) ·
*Codice:* `apps/lottery/lifecycle.py:tick` ·
*Test:* `tests/django/test_lifecycle.py::test_an_interrupted_draw_gives_the_same_winner`, `test_a_tick_that_changes_nothing_writes_nothing`
- **[RND-42]** **Catena e conferme simulate.** Con `LEDGER_BACKEND=simulated` la catena esiste solo nel tempo: il blocco `h`
è prodotto `h` intervalli (`SIMULATED_BLOCK_SECONDS`, 20 s) dopo un'epoca fissa e il suo hash è una funzione di `h`;
non si memorizza nulla, quindi un riavvio non cambia niente. Una puntata, un deposito o un pagamento simulati si
confermano `SIMULATED_CONFIRM_SECONDS` (5 s) dopo l'invio. Il blocco di estrazione resta quello dell'altezza
fissata, mai un altro; un'altezza futura non ha hash ([RND-16]). Il worker esegue `settle` e `tick` a ogni giro.
*Stato:* implementato (A4); la catena reale con la Fase B ·
*Codice:* `apps/lottery/simulation.py`, `apps/lottery/management/commands/run_worker.py` ·
*Test:* `tests/django/test_lifecycle.py::test_a_whole_round_on_the_simulated_chain`, `test_settling_confirms_only_what_has_waited_long_enough`
- **[RND-43]** **Il segreto del round è cifrato a riposo.** Alla pubblicazione dell'impegno ([RND-34]) il segreto si
salva cifrato (Fernet, chiave derivata da `DJANGO_SECRET_KEY`); la colonna in chiaro resta vuota fino alla
rivelazione, quindi una copia del solo database non dice chi vincerà. Con un'altra chiave il segreto non si decifra.
*Stato:* implementato (A4); la chiave dedicata torna con la Fase B ·
*Codice:* `apps/lottery/seedbox.py` ·
*Test:* `tests/django/test_lifecycle.py::test_the_round_secret_needs_the_right_key`
- **[RND-44]** **La prova non espone gli account.** L'elenco di estrazione e la sua impronta contengono, per ogni
partecipante, il txid e l'uscita della sua scommessa e un indirizzo pseudonimo ([ADR-59](adr/ADR-59-motore-plm-pacchetto-senza-framework-ledger-simulato.md)):
nel pilota derivato dall'id dell'account senza rivelarlo, in Fase B l'indirizzo HD. Nessun username compare.
*Stato:* implementato (A4) ·
*Codice:* `apps/lottery/addresses.py`, `apps/lottery/simulation.py:simulated_address` ·
*Test:* `tests/django/test_lifecycle.py::test_the_proof_does_not_expose_usernames`
- **Differenze rispetto al vecchio scheduler.** `closed_at` è l'istante in cui il round si chiude del tutto (pagamento
confermato, o chiusura senza partecipanti) e da lì parte la pausa fra round; non si scrive all'ingresso in `closing`.
Gli eventi di stallo dell'estrazione (`draw_stalled`, `draw_baseline_tip_unknown`, `draw_header_corroboration_failed`) e
la verifica del montepremi sulla catena riguardano la catena reale e arrivano con la Fase B (B8). Senza `fee_address`
un round non si apre solo con il ledger reale ([ADR-29](adr/ADR-29-senza-fee-address-apre-nessun-round.md)).
+1
View File
@@ -0,0 +1 @@
"""PLM engine: framework-free building blocks (ADR-59)."""
+65
View File
@@ -0,0 +1,65 @@
"""The draw's pure primitives: no database, no framework (ADR-59, roadmap B1).
Commit-reveal (RND-14 .. RND-20): the round's secret is committed to (`server_seed_commitment`)
when it opens, the ordered list of participants is fixed and fingerprinted (`participants_hash`),
and the winner is `draw_index(draw_seed(secret, block_hash, participants_hash), n)` — a value
anyone can recompute from the public proof once the secret is revealed.
"""
import hashlib
import secrets
def sha256_hex(data: bytes) -> str:
return hashlib.sha256(data).hexdigest()
def new_server_seed() -> str:
"""B-73 (RND-34, DAT-64): a round's secret — 32 random bytes from the OS CSPRNG, as
64 lowercase hex characters."""
return secrets.token_bytes(32).hex()
def server_seed_commitment(server_seed_hex: str) -> str:
"""`server_seed_hash`: sha256 of the secret's 32 bytes, published from the opening of
the round so the operator cannot change the secret afterwards (RND-34)."""
return sha256_hex(bytes.fromhex(server_seed_hex))
def participants_hash(rows: list[tuple[str, int, str]]) -> str:
"""The fingerprint of the ordered draw list (RND-14): sha256 of one `txid:vout:address`
line per participant, in `draw_position` order, each line ending in `\n`, UTF-8. `txid`
is the bet transaction's, lowercase hex as explorers show it; `vout` is the output paying
the round's pool address, in decimal; `address` is the participant's own."""
text = "".join(f"{txid}:{vout}:{address}\n" for txid, vout, address in rows)
return sha256_hex(text.encode("utf-8"))
def draw_seed(server_seed_hex: str, block_hash_hex: str, participants_hash_hex: str) -> int:
"""RND-17: sha256 of the secret (32 bytes), the hash of the block at `draw_height` (32
bytes, in the order explorers show it) and `participants_hash` (32 bytes), read as an
unsigned big-endian integer. Nobody who lacks the secret can predict it, and the
operator, who knows the secret, cannot know the block when committing to the list."""
digest = hashlib.sha256(
bytes.fromhex(server_seed_hex) + bytes.fromhex(block_hash_hex) + bytes.fromhex(participants_hash_hex)
).digest()
return int.from_bytes(digest, "big")
def draw_index(seed: int, participant_count: int) -> int:
"""The winner's `draw_position`: seed modulo the number of participants. Every
participant holds exactly one position, so odds are equal whatever the amount."""
if participant_count <= 0:
raise ValueError("no participants to draw from")
return seed % participant_count
def draw_winner(participants: list[str], server_seed_hex: str, block_hash_hex: str, participants_hash_hex: str) -> str:
"""The v1 draw algorithm (docs/ciclo-di-vita-del-round.md RND-17), recomputable by anyone
from the public proof (GET /rounds/{id}/proof): `participants` are the entries in
`draw_position` order, the winner is the one at `draw_index(draw_seed(...), n)`. Deliberately
simple and replaceable."""
if not participants:
raise ValueError("no participants to draw from")
seed = draw_seed(server_seed_hex, block_hash_hex, participants_hash_hex)
return participants[draw_index(seed, len(participants))]
+1 -1
View File
@@ -33,4 +33,4 @@ testpaths = ["tests"]
DJANGO_SETTINGS_MODULE = "config.settings_test"
[tool.setuptools.packages.find]
include = ["app*", "config*", "apps*"]
include = ["app*", "config*", "apps*", "plm_engine*"]
+2 -2
View File
@@ -27,7 +27,7 @@ Uscita: un giocatore completa il round dimostrativo in `localhost`, l'operatore
- [x] **A1 · Scheletro Django.** Progetto Django 5.2 (`config/`, app `accounts`, `lottery`, `web`, `ops`), modello utente personalizzato prima delle migrazioni, impostazioni da ambiente (`SITE_ADDRESS`, `ALLOWED_HOSTS`, `CSRF_TRUSTED_ORIGINS`), SQLite WAL con `transaction_mode=IMMEDIATE`, servizi `web` e `worker` nel compose dietro Caddy. *Requisiti:* WEB-01, WEB-07, ARC. *Test:* `manage.py check`, avvio e risposta `200` su `/`.
- [x] **A2 · Modelli e vincoli.** Account, Round (parametri fotografati all'apertura), Partecipazione, Movimento, Transazione, Audit (solo aggiunta). Importi interi in unità minime; un solo round attivo e una sola puntata per utente e round come vincoli del database. *Requisiti:* WEB-04, DAT. *Test:* violazione di ogni vincolo.
- [x] **A3 · Ledger simulato.** Interfaccia dei servizi (deposito, puntata, pagamento) con implementazione simulata e **chiave di idempotenza**: un doppio invio produce una sola operazione. *Requisiti:* WEB-23, ADR-59. *Test:* doppio invio, saldo insufficiente, importi al limite.
- [ ] **A4 · Ciclo del round e worker.** Apertura, chiusura, estrazione e pagamento 70/30 nel worker (`manage.py run_worker`), con l'estrazione commit-reveal dello stesso algoritmo del motore. *Requisiti:* RND esistenti riletti sul modello nuovo. *Test:* round completo deterministico, ripresa dopo riavvio del worker.
- [x] **A4 · Ciclo del round e worker.** Apertura, chiusura, estrazione e pagamento 70/30 nel worker (`manage.py run_worker`), con l'estrazione commit-reveal dello stesso algoritmo del motore. *Requisiti:* RND esistenti riletti sul modello nuovo. *Test:* round completo deterministico, ripresa dopo riavvio del worker.
- [ ] **A5 · Autenticazione e base grafica.** `/registrati/`, `/accedi/`, `/app/profilo/` (password, logout), CSRF, cookie di sessione, ritorno alla destinazione interna (`next`) solo se interna, template base e CSS responsivo. *Requisiti:* WEB-02, WEB-06. *Test:* redirect aperto rifiutato, cookie, throttling dei tentativi.
- [ ] **A6 · Home pubblica.** `/` con quota, montepremi confermato, chiusura (ora server) e i sei stati, «Partecipa», aggiornamento a polling. *Requisiti:* WEB-05, WEB-10, WEB-11. *Test:* un test per stato, polling dell'endpoint.
- [ ] **A7 · Area giocatore.** `/app/` (puntata con conferma esplicita), `/app/portafoglio/` (saldo spendibile e in conferma, deposito simulato **solo fuori da mainnet**), `/app/movimenti/`. *Requisiti:* WEB-03, WEB-20, WEB-21, WEB-22. *Test:* isolamento tra utenti (404 su dati altrui), stato salvato dopo ricarica.
@@ -39,7 +39,7 @@ Uscita: un giocatore completa il round dimostrativo in `localhost`, l'operatore
Uscita: flusso completo su regtest; un riavvio durante il broadcast, due richieste concorrenti e una riorganizzazione simulata lasciano dati e fondi riconciliabili.
- [ ] **B1 · Pacchetto `plm_engine`.** Spostamento dei moduli senza database (derivazione HD, `psbt_builder`, client Electrum, `merkle`, `draw`) e dei loro test, senza cambiare il comportamento. *Requisiti:* ADR-59. *Test:* i test esistenti dei moduli passano invariati.
- [ ] **B1 · Pacchetto `plm_engine`** (le primitive dell'estrazione sono già state spostate in A4). Spostamento dei moduli senza database (derivazione HD, `psbt_builder`, client Electrum, `merkle`, `draw`) e dei loro test, senza cambiare il comportamento. *Requisiti:* ADR-59. *Test:* i test esistenti dei moduli passano invariati.
- [ ] **B2 · Profilo di rete.** `PLM_NETWORK=regtest|mainnet` (hrp, prefissi, genesis, powLimit), conferma esplicita per `mainnet`, validazione degli indirizzi con l'hrp del profilo. *Requisiti:* ADR-58, ELC-30. *Test:* indirizzi e genesis per ciascun profilo.
- [ ] **B3 · Ambiente regtest e fixture.** Compose con nodo e Fulcrum regtest (profilo `regtest`), script che genera blocchi e fondi, fixture di integrazione che si salta se il regtest non c'è. *Test:* smoke di connessione e generazione di un blocco.
- [ ] **B4 · Modelli di catena.** UTXO, transazioni con tutte le versioni TXID, depositi, assegnazione dell'indice HD; la chiave di firma è accessibile solo al processo worker. *Requisiti:* DAT, TX. *Test:* vincoli, derivazione identica a parità di input.
+475
View File
@@ -0,0 +1,475 @@
"""A4 — round lifecycle, commit-reveal draw and simulated chain: RND-13..RND-21, RND-33..RND-36, ADR-22,
ADR-23, ADR-24, ADR-29, ADR-57, ADR-59, DAT-61, DAT-64, DAT-65."""
import hashlib
from datetime import timedelta
from uuid import uuid4
import pytest
from django.contrib.auth import get_user_model
from django.utils import timezone
from plm_engine.draw import draw_index, draw_seed, participants_hash, server_seed_commitment
from apps.lottery import audit, lifecycle, simulation
from apps.lottery.addresses import participant_address
from apps.lottery.balances import balance_of
from apps.lottery.ledger import SimulatedLedger
from apps.lottery.models import AuditEntry, LotteryConfig, Movement, Participation, Round
from apps.lottery.seedbox import decrypt_seed, encrypt_seed
from apps.lottery.simulation import SimulatedChain, simulated_block_hash
PLM = 100_000_000
BET = 10 * PLM
pytestmark = pytest.mark.django_db
ledger = SimulatedLedger()
class FakeChain:
"""A chain the test drives by hand."""
def __init__(self, tip=1000):
self.tip, self.agree, self.hashes = tip, True, {}
def tip_height(self, now=None):
return self.tip
def agreed_block_hash(self, height, now=None):
if not self.agree or height > self.tip:
return None
return self.hashes.get(height, "ab" * 32)
def make_user(name):
return get_user_model().objects.create_user(name, password="x" * 12)
def players(round_, names, *, confirm=True):
"""Fund each player and place their bet; optionally confirm it."""
users = []
for name in names:
user = make_user(name)
ledger.deposit(user, round_.bet_amount_sats)
bet = ledger.place_bet(user, round_.pk, request_id=uuid4()).obj
if confirm:
ledger.confirm_bet(bet)
users.append(user)
return users
def actions():
return list(AuditEntry.objects.order_by("id").values_list("action", flat=True))
@pytest.fixture
def t0():
return timezone.now()
def deadline(round_):
return round_.opened_at + timedelta(seconds=round_.duration_seconds)
# --- opening -----------------------------------------------------------------------------------
def test_the_first_tick_opens_a_round_with_a_public_commitment(t0):
"""RND-34: the hash of the secret is public from the opening; the secret is not."""
round_ = lifecycle.open_new_round_if_needed(t0)
assert round_.status == "open" and round_.opened_at == t0
assert len(round_.server_seed_hash) == 64 and round_.server_seed is None
secret = decrypt_seed(round_.server_seed_enc)
assert server_seed_commitment(secret) == round_.server_seed_hash
assert secret not in round_.server_seed_enc
assert actions() == ["round_opened"]
def test_only_one_round_is_ever_open(t0):
first = lifecycle.open_new_round_if_needed(t0)
assert lifecycle.open_new_round_if_needed(t0).pk == first.pk
assert Round.objects.count() == 1
def test_a_round_copies_its_rules_when_it_opens(t0):
"""DAT-61, ADR-10: a later edit of the configuration applies from the next round."""
config = LotteryConfig.get()
config.bet_amount_sats, config.round_duration_seconds, config.max_round_pool_sats = 7 * PLM, 90, 100 * PLM
config.draw_confirmations, config.round_cooldown_seconds, config.fee_address = 5, 11, " rplm1fee "
config.save()
round_ = lifecycle.open_new_round_if_needed(t0)
config.bet_amount_sats, config.round_duration_seconds = 99 * PLM, 5
config.save()
round_.refresh_from_db()
assert (round_.bet_amount_sats, round_.duration_seconds, round_.max_round_pool_sats) == (7 * PLM, 90, 100 * PLM)
assert (round_.draw_confirmations, round_.cooldown_seconds, round_.fee_address) == (5, 11, "rplm1fee")
def test_a_real_ledger_needs_a_fee_address_to_open_a_round(settings, t0):
"""ADR-29: a round that cannot pay its commission is not opened. The simulated ledger needs none."""
assert lifecycle.rounds_can_open(LotteryConfig.get())
settings.LEDGER_BACKEND = "chain"
assert lifecycle.open_new_round_if_needed(t0) is None
config = LotteryConfig.get()
config.fee_address = "rplm1fee"
config.save()
assert lifecycle.open_new_round_if_needed(t0) is not None
def test_the_pause_after_the_round_stops_only_the_next_one(t0):
"""ADR-57: «Pausa dopo il round in corso»."""
config = LotteryConfig.get()
config.pause_after_round = True
config.save()
assert lifecycle.open_new_round_if_needed(t0) is None and Round.objects.count() == 0
# --- the betting window ------------------------------------------------------------------------
def test_the_round_closes_for_bets_at_its_own_deadline(t0):
"""ADR-23."""
round_ = lifecycle.open_new_round_if_needed(t0)
assert lifecycle.tick(now=deadline(round_) - timedelta(seconds=1), chain=FakeChain()) == 0
assert Round.objects.get().status == "open"
lifecycle.tick(now=deadline(round_), chain=FakeChain())
assert Round.objects.get().status in ("closing", "closed")
def test_the_deadline_is_the_rounds_own_not_the_live_config(t0):
round_ = lifecycle.open_new_round_if_needed(t0)
config = LotteryConfig.get()
config.round_duration_seconds = 1
config.save()
lifecycle.tick(now=t0 + timedelta(seconds=30), chain=FakeChain())
assert Round.objects.get(pk=round_.pk).status == "open"
def test_closing_waits_for_every_bet_in_flight(t0):
"""RND-13: a bet placed before the deadline is not lost because it confirmed after it."""
round_ = lifecycle.open_new_round_if_needed(t0)
(user,) = players(round_, ["a"], confirm=False)
at_deadline = deadline(round_)
lifecycle.tick(now=at_deadline, chain=FakeChain())
assert Round.objects.get().status == "closing" # still waiting: the bet is pending
ledger.confirm_bet(Participation.objects.get())
lifecycle.tick(now=at_deadline, chain=FakeChain())
assert Round.objects.get().status == "drawing"
def test_a_round_nobody_joined_closes_and_reveals_its_secret(t0):
"""DAT-64: with nothing drawn the secret has nothing left to protect."""
round_ = lifecycle.open_new_round_if_needed(t0)
lifecycle.tick(now=deadline(round_), chain=FakeChain())
round_.refresh_from_db()
assert round_.status == "closed" and round_.closed_at is not None
assert server_seed_commitment(round_.server_seed) == round_.server_seed_hash
assert actions() == ["round_opened", "round_closed"]
# --- committing to the draw --------------------------------------------------------------------
def committed_round(t0, names=("c", "a", "b"), tip=1000, reverse_txids=False):
round_ = lifecycle.open_new_round_if_needed(t0)
users = players(round_, list(names))
if reverse_txids: # first to bet gets the highest txid, so id order and txid order are opposite
for i, bet in enumerate(Participation.objects.order_by("id")):
Participation.objects.filter(pk=bet.pk).update(bet_txid=f"{len(names) - i:064x}")
chain = FakeChain(tip)
lifecycle.tick(now=deadline(round_), chain=chain)
round_.refresh_from_db()
return round_, users, chain
def test_the_list_is_ordered_by_bet_txid_and_fingerprinted(t0):
"""RND-14, DAT-65: public data, no ties, never a server-side timestamp."""
round_, users, _ = committed_round(t0, reverse_txids=True)
assert round_.status == "drawing"
ordered = list(Participation.objects.filter(round=round_).order_by("draw_position").select_related("user"))
assert [p.draw_position for p in ordered] == [0, 1, 2]
assert [p.bet_txid for p in ordered] == sorted(p.bet_txid for p in ordered)
assert [p.user.username for p in ordered] == ["b", "a", "c"] # last to bet, first in the list
expected = participants_hash([(p.bet_txid, p.bet_vout, participant_address(p.user)) for p in ordered])
assert round_.participants_hash == expected
assert round_.pool_amount_sats == 3 * BET
def test_the_draw_block_is_after_the_close(t0):
"""RND-19: `draw_height` is the height known at closing plus one — a block that did not exist yet."""
round_, _, _ = committed_round(t0, tip=1234)
assert round_.draw_height == 1235
audit_row = AuditEntry.objects.get(action="draw_committed")
assert audit_row.payload["draw_height"] == 1235 and audit_row.payload["participants"] == 3
def test_the_proof_does_not_expose_usernames(t0):
"""WEB-12: participants appear under a pseudonymous address only."""
round_, users, _ = committed_round(t0, names=("mariorossi", "lucia"))
for user in users:
assert user.username not in participant_address(user)
assert participant_address(user) == participant_address(user) # stable: the same player, the same entry
assert len({participant_address(u) for u in users}) == len(users)
published = AuditEntry.objects.get(action="draw_committed").payload
assert "mariorossi" not in str(published) and "lucia" not in str(published)
# --- the draw ----------------------------------------------------------------------------------
def test_the_draw_waits_for_the_confirmations_of_the_block(t0):
"""RND-15: the chain needs `draw_confirmations` blocks from `draw_height`."""
round_, _, chain = committed_round(t0, tip=1000) # draw_height 1001, 3 confirmations -> tip 1003
chain.tip = 1002
lifecycle.tick(now=deadline(round_), chain=chain)
assert Round.objects.get().status == "drawing"
chain.tip = 1003
lifecycle.tick(now=deadline(round_), chain=chain)
assert Round.objects.get().status in ("paying_out", "closed")
def test_a_block_that_is_not_agreed_is_asked_again_never_replaced(t0):
"""RND-16: nobody can pick another block to seed the draw; a missing agreement only delays it."""
round_, _, chain = committed_round(t0)
chain.tip, chain.agree = 1010, False
for _ in range(3):
assert lifecycle.tick(now=deadline(round_), chain=chain) == 0
assert Round.objects.get().winner_id is None
chain.agree = True
lifecycle.tick(now=deadline(round_), chain=chain)
round_.refresh_from_db()
assert round_.draw_height == 1001 and round_.draw_block_hash == "ab" * 32 # the same block as always
def test_the_winner_is_recomputable_from_the_public_proof(t0):
"""RND-17, RND-18: anyone can redo the draw once the secret is revealed."""
round_, users, chain = committed_round(t0)
chain.tip = 1003
chain.hashes[1001] = "cd" * 32
lifecycle.tick(now=deadline(round_), chain=chain)
round_.refresh_from_db()
ordered = list(Participation.objects.filter(round=round_).order_by("draw_position"))
seed = draw_seed(round_.server_seed, "cd" * 32, round_.participants_hash)
assert round_.winner_id == ordered[draw_index(seed, len(ordered))].user_id
assert server_seed_commitment(round_.server_seed) == round_.server_seed_hash
assert round_.draw_block_hash == "cd" * 32 and round_.status == "paying_out"
payload = AuditEntry.objects.get(action="winner_drawn").payload
assert payload["server_seed"] == round_.server_seed and payload["block_hash"] == "cd" * 32
def test_the_secret_is_revealed_only_with_the_winner(t0):
"""RND-18, DAT-64."""
round_, _, chain = committed_round(t0)
assert Round.objects.get().server_seed is None # committed, drawing, not yet revealed
chain.tip = 1003
lifecycle.tick(now=deadline(round_), chain=chain)
round_.refresh_from_db()
assert round_.server_seed and round_.winner_id
def test_an_interrupted_draw_gives_the_same_winner(t0, monkeypatch):
"""RND-36: a failure mid-draw leaves nothing behind, and the resumed draw picks the same winner."""
round_, _, chain = committed_round(t0)
chain.tip = 1003
def explode(action, **kwargs):
if action == "winner_drawn":
raise RuntimeError("database locked")
return real(action, **kwargs)
real = audit.record
monkeypatch.setattr(audit, "record", explode)
with pytest.raises(RuntimeError):
lifecycle.tick(now=deadline(round_), chain=chain)
interrupted = Round.objects.get()
assert (interrupted.status, interrupted.winner_id, interrupted.server_seed) == ("drawing", None, None)
monkeypatch.setattr(audit, "record", real)
lifecycle.tick(now=deadline(round_), chain=chain)
resumed = Round.objects.get()
ordered = list(Participation.objects.filter(round=resumed).order_by("draw_position"))
expected = ordered[draw_index(draw_seed(decrypt_seed(resumed.server_seed_enc), "ab" * 32,
resumed.participants_hash), len(ordered))]
assert resumed.winner_id == expected.user_id
def test_a_tampered_list_or_secret_is_refused(t0):
"""RND-14, RND-34: the list must match its fingerprint and the secret its commitment."""
round_, _, chain = committed_round(t0)
chain.tip = 1003
Round.objects.filter(pk=round_.pk).update(participants_hash="0" * 64)
with pytest.raises(RuntimeError, match="fingerprint"):
lifecycle.tick(now=deadline(round_), chain=chain)
Round.objects.filter(pk=round_.pk).update(participants_hash=round_.participants_hash, server_seed_hash="1" * 64)
with pytest.raises(RuntimeError, match="commitment"):
lifecycle.tick(now=deadline(round_), chain=chain)
assert Round.objects.get().winner_id is None
def test_a_tick_that_changes_nothing_writes_nothing(t0):
round_, _, chain = committed_round(t0)
before = AuditEntry.objects.count()
assert lifecycle.tick(now=deadline(round_), chain=chain) == 0 # still waiting for blocks
assert AuditEntry.objects.count() == before
# --- payout and cooldown -----------------------------------------------------------------------
def drawn_round(t0, names=("a", "b", "c", "d")):
round_ = lifecycle.open_new_round_if_needed(t0)
users = players(round_, list(names))
chain = FakeChain(1000)
lifecycle.tick(now=deadline(round_), chain=chain)
chain.tip = 1003
lifecycle.tick(now=deadline(round_), chain=chain)
round_.refresh_from_db()
return round_, users, chain
def test_the_winner_is_paid_70_percent_and_the_round_closes_when_it_confirms(t0):
"""RND-21: paying_out until the payout confirms, then closed."""
round_, users, chain = drawn_round(t0)
assert round_.status == "paying_out" and round_.payout_transaction_id is not None
assert (round_.winner_amount_sats, round_.fee_amount_sats) == (28 * PLM, 12 * PLM)
win = Movement.objects.get(kind="win")
assert win.user_id == round_.winner_id and win.status == "pending"
assert balance_of(round_.winner).incoming_sats == 28 * PLM
assert Round.objects.get().status == "paying_out"
done = deadline(round_) + timedelta(minutes=5)
simulation.settle(done)
lifecycle.tick(now=done, chain=chain)
round_.refresh_from_db()
assert round_.status == "closed" and round_.closed_at == done
assert balance_of(round_.winner).spendable_sats == 28 * PLM and balance_of(round_.winner).incoming_sats == 0
def test_the_next_round_opens_only_after_the_cooldown_it_announced(t0):
"""B-61: the gap of the closed round is the gap honoured, whatever the config says now."""
round_, _, chain = drawn_round(t0)
done = deadline(round_) + timedelta(minutes=5)
simulation.settle(done)
lifecycle.tick(now=done, chain=chain)
assert Round.objects.get().status == "closed"
config = LotteryConfig.get()
config.round_cooldown_seconds = 1
config.save()
lifecycle.tick(now=done + timedelta(seconds=29), chain=chain)
assert Round.objects.count() == 1
lifecycle.tick(now=done + timedelta(seconds=30), chain=chain)
assert Round.objects.count() == 2 and Round.objects.latest("id").status == "open"
def test_a_round_in_progress_finishes_even_if_the_lottery_is_paused(t0):
"""ADR-57: the pause after the round lets the current one close, draw and pay; no new one opens."""
round_ = lifecycle.open_new_round_if_needed(t0)
players(round_, ["a", "b"])
config = LotteryConfig.get()
config.pause_after_round = True
config.save()
chain = FakeChain(1000)
lifecycle.tick(now=deadline(round_), chain=chain)
chain.tip = 1003
lifecycle.tick(now=deadline(round_), chain=chain)
done = deadline(round_) + timedelta(minutes=5)
simulation.settle(done)
lifecycle.tick(now=done, chain=chain)
assert Round.objects.get().status == "closed"
lifecycle.tick(now=done + timedelta(hours=1), chain=chain)
assert Round.objects.count() == 1 # still paused
config.pause_after_round = False
config.save()
lifecycle.tick(now=done + timedelta(hours=1), chain=chain)
assert Round.objects.count() == 2
# --- the whole thing, on the simulated chain ---------------------------------------------------
def test_a_whole_round_on_the_simulated_chain(settings, t0):
"""The first milestone: open -> bets -> close -> draw -> payout -> closed, money conserved, audit in order."""
settings.SIMULATED_BLOCK_SECONDS, settings.SIMULATED_CONFIRM_SECONDS = 10, 2
chain = SimulatedChain()
lifecycle.tick(now=t0, chain=chain)
round_ = Round.objects.get()
users = players(round_, ["a", "b", "c"], confirm=False)
now = t0
for _ in range(400): # 400 steps of 5 simulated seconds: far more than a round needs
now += timedelta(seconds=5)
simulation.settle(now)
lifecycle.tick(now=now, chain=chain)
if Round.objects.filter(status="open").exclude(pk=round_.pk).exists():
break
round_.refresh_from_db()
assert round_.status == "closed"
assert Round.objects.filter(status="open").exclude(pk=round_.pk).exists() # the next one opened
# the winner is exactly what the public proof says
ordered = list(Participation.objects.filter(round=round_).order_by("draw_position"))
seed = draw_seed(round_.server_seed, simulated_block_hash(round_.draw_height), round_.participants_hash)
assert round_.winner_id == ordered[draw_index(seed, 3)].user_id
assert round_.draw_height > simulation.BASE_HEIGHT
# money: what players deposited is what they hold plus the platform's share
held = sum(balance_of(u).spendable_sats for u in users)
deposited = sum(Movement.objects.filter(kind="deposit").values_list("amount_sats", flat=True))
assert held + round_.fee_amount_sats == deposited
assert round_.winner_amount_sats == 21 * PLM and round_.fee_amount_sats == 9 * PLM
interesting = [a for a in actions() if a in ("round_opened", "draw_committed", "winner_drawn",
"payout_created", "payout_confirmed", "round_closed")]
assert interesting == ["round_opened", "draw_committed", "winner_drawn", "payout_created",
"payout_confirmed", "round_closed", "round_opened"]
# --- the simulated chain and its confirmations -------------------------------------------------
def test_the_simulated_chain_grows_with_time(settings, t0):
settings.SIMULATED_BLOCK_SECONDS = 20
chain = SimulatedChain()
later = chain.tip_height(t0 + timedelta(seconds=40))
assert later - chain.tip_height(t0) in (2,) # a block every 20 simulated seconds
assert chain.tip_height(t0 + timedelta(seconds=19)) - chain.tip_height(t0) in (0, 1)
def test_a_future_block_has_no_hash_and_a_past_one_always_the_same(t0):
chain = SimulatedChain()
tip = chain.tip_height(t0)
assert chain.agreed_block_hash(tip + 1, t0) is None
assert chain.agreed_block_hash(tip, t0) == simulated_block_hash(tip) == chain.agreed_block_hash(tip, t0)
assert simulated_block_hash(tip) != simulated_block_hash(tip - 1)
def test_settling_confirms_only_what_has_waited_long_enough(settings):
settings.SIMULATED_CONFIRM_SECONDS = 5
round_ = Round.objects.create()
(user,) = players(round_, ["a"], confirm=False)
pending_deposit = ledger.deposit(make_user("b"), PLM, confirmed=False).obj
now = timezone.now()
assert simulation.settle(now + timedelta(seconds=4)) == 0
assert Participation.objects.get().status == "pending"
assert simulation.settle(now + timedelta(seconds=6)) == 2
assert Participation.objects.get().status == "confirmed"
pending_deposit.refresh_from_db()
assert pending_deposit.status == "confirmed"
def test_the_round_secret_needs_the_right_key(settings):
token = encrypt_seed("ab" * 32)
assert decrypt_seed(token) == "ab" * 32
settings.SECRET_KEY = "another-key-" + "y" * 50
with pytest.raises(RuntimeError):
decrypt_seed(token)
def test_the_old_draw_module_and_the_engine_share_one_implementation():
"""ADR-59: the primitives live once, in `plm_engine.draw`; the old module re-exports them."""
import plm_engine.draw as engine
from app.rounds import draw as old
for name in ("draw_seed", "draw_index", "draw_winner", "participants_hash", "new_server_seed",
"server_seed_commitment", "sha256_hex"):
assert getattr(old, name) is getattr(engine, name)
assert engine.sha256_hex(b"x") == hashlib.sha256(b"x").hexdigest()
+5 -1
View File
@@ -178,9 +178,13 @@ def test_passwords_use_argon2_outside_tests():
# --- ADR-55: the worker is its own process -----------------------------------------------------
@pytest.mark.django_db
def test_worker_runs_one_tick_and_exits():
"""ARC-71: `manage.py run_worker --once` starts, ticks and stops."""
"""ARC-71: `manage.py run_worker --once` starts, ticks (opening the first round) and stops."""
from apps.lottery.models import Round
call_command("run_worker", "--once")
assert Round.objects.filter(status="open").count() == 1
@pytest.mark.django_db