65 lines
3.2 KiB
Python
65 lines
3.2 KiB
Python
"""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))]
|