"""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 ) if settings.LEDGER_BACKEND == "chain": # DAT-60: this round's own address, from the public key from .chain import derive_pool_address round_.pool_address = derive_pool_address(round_.pk) round_.save(update_fields=["pool_address"]) 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