"""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))]