CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Language

The user communicates in Italian in chat — reply to them in Italian. Everything written to the repository (code, comments, commit messages, docs, this file) must be in English. Reasoning/thinking should also be done in English.

Project status

This repository is at the specification stage, not yet implemented: it currently contains only flowchart.mmd, which is the source of truth for the project and describes the entire application flow. The tech stack is decided (see below) but no code, build system, or lint/test commands exist yet — once the project is scaffolded, this section must be updated with real commands (install, run, lint, test — including how to run a single test).

Before writing code, always read flowchart.mmd in full: every node in the diagram corresponds to a behavior that must be implemented exactly as described, including the labels on the edges (conditions, retries, loops).

Tech stack (MVP)

Backend language: Python.
PLM node access: Electrum protocol only (no full node/P2P). Bootstrap server for development: santantonio.sytes.net:50002 (SSL).
Auth: Argon2 password hashing + JWT sessions.
Secrets: master xprv encrypted at rest with a symmetric scheme (AES-GCM/Fernet); the encryption key itself lives in an env var, never in the DB or in git.
Operational config (fee/commission address, RBF fee-bump wallet, etc.): stored in a DB config table, not env vars — must be editable without a redeploy.
Round duration: configurable via env var, default 10 minutes (not hardcoded).

PLM network parameters

Source of truth: PalladiumWallet repo, ChainProfiles.cs and PalladiumNetworks.cs — always re-check that repo if a value is needed that isn't listed here, rather than guessing.

Mainnet:

BIP44/84 coin type: 746 (i.e. HD path m/84'/746'/0'/0/index)
Bech32 HRP: plm
P2PKH address version byte: 55 (addresses start with P)
P2SH address version byte: 5
WIF prefix: 0x80
Block time: 120s
BIP32 extended key headers (Legacy/native-segwit zprv/zpub etc.): see ExtKeyHeaders in ChainProfiles.cs

MVP business parameters

Fixed bet cost: 10 PLM per round.
Prize split: 70% winner / 30% fees (fee address configurable in DB).
Minimum deposit/withdrawal amount: 1 PLM (business-friendly floor, above the network's technical dust limit).
Confirmations required for all tx types (deposit, bet, payout, withdrawal): 1.

What is PLM Lottery

A periodic-round lottery system built on a Bitcoin-like coin (PLM, mainnet). Each user gets a dedicated P2WPKH address (server-side HD wallet); they deposit PLM to that address, place a fixed-cost bet to enter the current round, and when the round closes a winner is drawn who receives 70% of the prize pool (the remaining 30% goes to fees).

Architecture (from the flowchart subgraphs)

The flow is organized into 5 phases, each a subgraph in flowchart.mmd:

REG (Registration): on signup the server derives a new P2WPKH address via BIP84 (m/84'/coin'/0'/0/index, one index per user) from a master xprv encrypted at rest. This address is permanent and serves as both the deposit address and the address that receives winnings and withdrawals.
DEP (Balance top-up): an ElectrumClient/SPV subscribes to the user's address scripthash. Internal balance (DB) is credited after 1 confirmation only — the reorg risk at 1-conf is knowingly accepted in v1, with no rollback logic.
PLAY (Bet): fixed cost per round, at most one active bet per user at a time in v1. The server builds a PSBT user-address → pool-address for the fixed amount, with a change output back to the same user address (the user's balance must never exactly equal the bet amount). Fee minimized (~1 sat/vB), deducted from the bet amount. If the tx doesn't confirm within a timeout, fee-bump (RBF) and rebroadcast.
DRAW (Periodic draw): configurable timer (default 10 minutes). Round closing waits for all already-broadcast bets to confirm before proceeding (avoids losing bets at the round boundary). The next round only opens once the previous round's payout tx is confirmed — rounds never overlap in v1. v1 draw algorithm (deliberately simple, meant to be replaced later): wait for the first block confirmed after round closing, use its hash as seed, index = seed mod participant_count over the participant list ordered by broadcast timestamp (this is also the tie-break when two bets confirm in the same block). Every participant has equal probability regardless of bet amount (consistent with the fixed bet amount). The payout (70% winner / 30% fees) is signed with the pool address key; the payout fee is deducted from the winner's 70%, the 30% fee share stays intact. Same timeout → RBF → rebroadcast pattern here too.
WITHDRAW (Withdrawal): the only way to move funds out of the platform to an external address. PSBT user-address → external-address + change back to the user address, fee deducted from the withdrawn amount, same RBF retry pattern.

PLAY and WITHDRAW share a per-user DB lock: a user can never have a bet-build and a withdrawal-build in flight at the same time, since both would otherwise spend from the same UTXO set on the user's dedicated address.

Non-obvious domain decisions

These choices were made explicitly during design (not derivable from reading a single file) and must be respected in any implementation:

Private keys (xprv) are generated and held server-side — this is not a non-custodial system: the user never controls their own keys until they make an explicit withdrawal.
The user's personal deposit address always doubles as the winnings-receiving address: there is no separate "winner address".
1 confirmation is the chosen threshold for all tx types (deposits, bets, payouts, withdrawals): don't introduce different thresholds (e.g. 3 or 6 confirmations) without an explicit decision.
The draw algorithm (node R) is deliberately simple and should be treated as a replaceable/pluggable component, not the final design — don't architect around its current implementation.

6.3 KiB Raw Blame History