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

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