B4: chain tables, HD index assignment and signing key reserved to the worker (DAT-81..84, ARC-78)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
davideandClaude Sonnet 5.5 committed 2026-11-16 15:53:50 +01:00
1 parent 0092596b07
commit f1d09075a1
18 files changed
+741 -8

No files matched your search

+4
View File
@@ -69,6 +69,10 @@ DJANGO_SECRET_KEY=
# phase C are closed and also needs PLM_MAINNET_CONFIRMED=yes; the simulated ledger can never run on it.
PLM_NETWORK=regtest
PLM_MAINNET_CONFIRMED=
# ARC-78: the web process knows only the PUBLIC account key. Create the keys once with
# docker compose run --rm worker python manage.py init_keys /app/db_data/keys (move them out of there afterwards)
# and paste the PLM_ACCOUNT_XPUB line it prints. The private files are for the worker alone (mounted from B6).
PLM_ACCOUNT_XPUB=
# Optional extras when serving a domain; SITE_ADDRESS itself is always allowed.
DJANGO_ALLOWED_HOSTS=
DJANGO_CSRF_TRUSTED_ORIGINS=
+1 -1
View File
@@ -8,7 +8,7 @@ The user communicates in Italian in chat — reply to them in Italian. Everythin
## Project status
The migration from FastAPI to Django is in progress on branch `django-migration` (plan: [roadmap.md](roadmap.md), steps A1–A10, B1–B3 done). The suite has 1187 tests: the old stack's under `tests/unit/`, the Django ones under `tests/django/` (`tests/integration/` needs the local regtest node and skips itself without it). Open defects of the old stack are in [BUGS.md](BUGS.md); accepted limits in [docs/limiti-noti.md](docs/limiti-noti.md); every closed `B-nn` is in [docs/storico-bug.md](docs/storico-bug.md) (`git log --all --grep 'B-nn'` finds its commit).
The migration from FastAPI to Django is in progress on branch `django-migration` (plan: [roadmap.md](roadmap.md), steps A1–A10, B1–B4 done). The suite has 1211 tests: the old stack's under `tests/unit/`, the Django ones under `tests/django/` (`tests/integration/` needs the local regtest node and skips itself without it). Open defects of the old stack are in [BUGS.md](BUGS.md); accepted limits in [docs/limiti-noti.md](docs/limiti-noti.md); every closed `B-nn` is in [docs/storico-bug.md](docs/storico-bug.md) (`git log --all --grep 'B-nn'` finds its commit).
**[docs/](docs/README.md) is the specification, and it is authoritative.** Every verifiable rule there has a stable requirement ID (`RND-04`, `BET-02`, …) with `*Codice:*`/`*Test:*` pointers to what implements it; the index is [docs/come-funziona.md](docs/come-funziona.md) and the ID convention and change workflow are in [docs/processo-di-modifica.md](docs/processo-di-modifica.md). A behaviour change starts in the spec: edit or add the requirement, implement it, cite the ID in the test docstring and the commit message, and ship spec + code + test in one commit. If this file and the spec disagree, the spec wins and this file is the one to fix. Before writing code, read the relevant spec documents and the "Architecture" section below.
+1 -1
View File
@@ -62,7 +62,7 @@ python -m pytest # all tests
python -m pytest tests/unit/test_hd.py # one file
```
1187 unit tests cover HD derivation, PSBT building, the Electrum client, bets,
1211 unit tests cover HD derivation, PSBT building, the Electrum client, bets,
deposits, withdrawals, the round/draw engine, RBF fee-bumping, admin config,
the pending-inclusive balance calculation, and the SSE push channel. No
automated integration tests against a live Electrum connection — mainnet
+3 -1
View File
@@ -9,7 +9,9 @@ from .simulation import simulated_address
def participant_address(user) -> str:
if settings.LEDGER_BACKEND == "simulated":
return simulated_address(user)
raise NotImplementedError("HD addresses arrive with phase B (roadmap B4)")
from .chain import assign_deposit_address
return assign_deposit_address(user).address
def is_valid_address(address: str) -> bool:
+62
View File
@@ -0,0 +1,62 @@
"""Services over the chain tables (roadmap B4): the HD index of a deposit address (DAT-81) and the versions of a
transaction (DAT-83). Uniqueness is decided by the database, never by a read followed by a write (ARC-72)."""
from django.conf import settings
from django.db import IntegrityError, transaction
from django.db.models import Max
from plm_engine import hd
from . import keys
from .models import ChainTransaction, DepositAddress, TransactionVersion
_ATTEMPTS = 20
class TxidConflict(Exception):
"""The txid already belongs to another platform transaction (DAT-83)."""
def derive_deposit_address(index: int) -> str:
"""The address for an HD index: a pure function of the public key, the index and the network."""
return hd.user_address(keys.public_account_key(), index, settings.PLM_PROFILE)
def assign_deposit_address(user) -> DepositAddress:
"""The player's deposit address; created on first use, the same one ever after (DAT-81). The index is the
next after the highest assigned; if a concurrent assignment takes it first the unique index refuses ours
and we take the next one."""
existing = DepositAddress.objects.filter(user=user).first()
if existing is not None:
return existing
for _ in range(_ATTEMPTS):
try:
with transaction.atomic():
top = DepositAddress.objects.aggregate(top=Max("derivation_index"))["top"]
index = 0 if top is None else top + 1
return DepositAddress.objects.create(
user=user, derivation_index=index, address=derive_deposit_address(index), network=settings.PLM_NETWORK
)
except IntegrityError:
raced = DepositAddress.objects.filter(user=user).first() # the same player assigned twice at once
if raced is not None:
return raced
raise RuntimeError("could not assign a deposit address: too many concurrent assignments")
def register_version(tx: ChainTransaction, txid: str, raw_hex: str = "") -> TransactionVersion:
"""Record a txid of `tx` and make it the current one (DAT-83, TX-19). Idempotent for the same pair; a txid of
another transaction is refused. One database transaction, so the version and `current_txid` agree."""
with transaction.atomic():
existing = TransactionVersion.objects.filter(txid=txid).first()
if existing is not None:
if existing.transaction_id != tx.pk:
raise TxidConflict(f"{txid} belongs to transaction {existing.transaction_id}")
version = existing
else:
version = TransactionVersion.objects.create(transaction=tx, txid=txid, raw_hex=raw_hex)
if tx.current_txid != txid:
tx.current_txid = txid
if raw_hex:
tx.raw_hex = raw_hex
tx.save(update_fields=["current_txid", "raw_hex"])
return version
+66
View File
@@ -0,0 +1,66 @@
"""Who may hold which key (ARC-78, roadmap B4).
The web process knows only the **public** account key (`PLM_ACCOUNT_XPUB`): it is enough to derive every deposit
and pool address. The private side — the master xprv, encrypted, and the key that encrypts it, two separate files —
is loaded only by the worker (`PROCESS_ROLE=worker`) and only when both files are there. Anywhere else the loader
refuses, whatever the files, so a bug in a view cannot reach the signing key.
"""
import os
from pathlib import Path
from cryptography.fernet import Fernet, InvalidToken
from django.conf import settings
from embit.bip32 import HDKey
from plm_engine.network import Profile
class SigningKeyUnavailable(Exception):
pass
def public_account_key() -> HDKey:
"""The account's public key, from configuration: derives addresses, signs nothing."""
xpub = settings.PLM_ACCOUNT_XPUB
if not xpub:
raise SigningKeyUnavailable("PLM_ACCOUNT_XPUB is not set: run `manage.py init_keys` and put the public key in .env")
return HDKey.from_base58(xpub)
def signing_account_key() -> HDKey:
"""The private account key. Only the worker can have it."""
if settings.PROCESS_ROLE != "worker":
raise SigningKeyUnavailable("the signing key is only available to the worker process")
master_file, key_file = settings.PLM_MASTER_KEY_FILE, settings.PLM_KEY_ENCRYPTION_KEY_FILE
if not (master_file and key_file):
raise SigningKeyUnavailable("PLM_MASTER_KEY_FILE and PLM_KEY_ENCRYPTION_KEY_FILE are not set")
try:
token = Path(master_file).read_bytes()
fernet = Fernet(Path(key_file).read_bytes().strip())
master = HDKey.from_base58(fernet.decrypt(token).decode())
except (OSError, InvalidToken, ValueError) as exc:
raise SigningKeyUnavailable(f"the signing key cannot be loaded: {exc.__class__.__name__}") from exc
return master.derive(settings.PLM_PROFILE.account_path)
def _write_private(path: Path, data: bytes) -> None:
"""`0600` from the start, never through a wider mode (SEC-50)."""
fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, "wb") as handle:
os.fchmod(handle.fileno(), 0o600)
handle.write(data)
def generate_keys(directory: Path, profile: Profile) -> str:
"""Create a master key and its encryption key under `directory` (refuses to overwrite) and return the
account's public key, to be put in `PLM_ACCOUNT_XPUB`."""
directory.mkdir(parents=True, exist_ok=True, mode=0o700)
master_path, key_path = directory / "master.key", directory / "master.encryption.key"
if master_path.exists() or key_path.exists():
raise FileExistsError(f"{directory} already holds keys: refusing to overwrite them")
master = HDKey.from_seed(os.urandom(32), version=profile.embit["xprv"])
encryption_key = Fernet.generate_key()
_write_private(key_path, encryption_key)
_write_private(master_path, Fernet(encryption_key).encrypt(master.to_base58(version=profile.embit["xprv"]).encode()))
account = master.derive(profile.account_path).to_public()
return account.to_base58(version=profile.embit["xpub"])
@@ -0,0 +1,22 @@
from pathlib import Path
from django.conf import settings
from django.core.management.base import BaseCommand, CommandError
from apps.lottery.keys import generate_keys
class Command(BaseCommand):
help = "One-off: create the master key and its encryption key (0600) and print the account's public key (ARC-78)."
def add_arguments(self, parser):
parser.add_argument("directory", help="where to write master.key and master.encryption.key")
def handle(self, *args, **options):
try:
xpub = generate_keys(Path(options["directory"]), settings.PLM_PROFILE)
except FileExistsError as error:
raise CommandError(str(error)) from error
self.stdout.write(f"Keys written to {options['directory']} for {settings.PLM_NETWORK}.")
self.stdout.write("Put this public key in .env (the web process needs nothing else):")
self.stdout.write(f"PLM_ACCOUNT_XPUB={xpub}")
@@ -0,0 +1,110 @@
# Generated by Django 5.2.19 on 2026-11-16 14:50
import django.db.models.deletion
import django.db.models.functions.text
import django.db.models.lookups
import django.utils.timezone
from django.conf import settings
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
('lottery', '0003_console_and_reports'),
migrations.swappable_dependency(settings.AUTH_USER_MODEL),
]
operations = [
migrations.CreateModel(
name='Utxo',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('txid', models.CharField(max_length=64)),
('vout', models.PositiveIntegerField()),
('amount_sats', models.BigIntegerField()),
('address', models.CharField(max_length=128)),
('confirmed_height', models.PositiveIntegerField(blank=True, null=True)),
('spent_txid', models.CharField(blank=True, max_length=64, null=True)),
('created_at', models.DateTimeField(default=django.utils.timezone.now)),
('reserved_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='reserved_utxos', to='lottery.chaintransaction')),
('round', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='utxos', to='lottery.round')),
('user', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='utxos', to=settings.AUTH_USER_MODEL)),
],
),
migrations.CreateModel(
name='Deposit',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('status', models.CharField(choices=[('detected', 'Detected'), ('credited', 'Credited'), ('orphaned', 'Orphaned')], default='detected', max_length=16)),
('detected_at', models.DateTimeField(default=django.utils.timezone.now)),
('credited_at', models.DateTimeField(blank=True, null=True)),
('movement', models.OneToOneField(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='deposit', to='lottery.movement')),
('user', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='deposits', to=settings.AUTH_USER_MODEL)),
('utxo', models.OneToOneField(on_delete=django.db.models.deletion.PROTECT, related_name='deposit', to='lottery.utxo')),
],
),
migrations.CreateModel(
name='DepositAddress',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('derivation_index', models.PositiveIntegerField(unique=True)),
('address', models.CharField(max_length=128, unique=True)),
('network', models.CharField(max_length=16)),
('created_at', models.DateTimeField(default=django.utils.timezone.now)),
('user', models.OneToOneField(on_delete=django.db.models.deletion.PROTECT, related_name='deposit_address', to=settings.AUTH_USER_MODEL)),
],
options={
'constraints': [models.CheckConstraint(condition=models.Q(('network__in', ['mainnet', 'regtest'])), name='lottery_depositaddress_network_valid')],
},
),
migrations.CreateModel(
name='TransactionVersion',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('txid', models.CharField(max_length=64, unique=True)),
('raw_hex', models.TextField(blank=True, default='')),
('created_at', models.DateTimeField(default=django.utils.timezone.now)),
('transaction', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='versions', to='lottery.chaintransaction')),
],
options={
'constraints': [models.CheckConstraint(condition=django.db.models.lookups.Exact(django.db.models.functions.text.Length('txid'), 64), name='lottery_txversion_txid_length')],
},
),
migrations.AddIndex(
model_name='utxo',
index=models.Index(fields=['address'], name='lottery_utx_address_daa4dd_idx'),
),
migrations.AddIndex(
model_name='utxo',
index=models.Index(fields=['user'], name='lottery_utx_user_id_2ccdc9_idx'),
),
migrations.AddConstraint(
model_name='utxo',
constraint=models.UniqueConstraint(fields=('txid', 'vout'), name='lottery_utxo_outpoint_unique'),
),
migrations.AddConstraint(
model_name='utxo',
constraint=models.CheckConstraint(condition=models.Q(('amount_sats__gt', 0)), name='lottery_utxo_amount_positive'),
),
migrations.AddConstraint(
model_name='utxo',
constraint=models.CheckConstraint(condition=django.db.models.lookups.Exact(django.db.models.functions.text.Length('txid'), 64), name='lottery_utxo_txid_length'),
),
migrations.AddConstraint(
model_name='utxo',
constraint=models.CheckConstraint(condition=models.Q(('spent_txid__isnull', True), django.db.models.lookups.Exact(django.db.models.functions.text.Length('spent_txid'), 64), _connector='OR'), name='lottery_utxo_spent_txid_length'),
),
migrations.AddConstraint(
model_name='utxo',
constraint=models.CheckConstraint(condition=models.Q(('user__isnull', True), ('round__isnull', True), _connector='OR'), name='lottery_utxo_user_or_round'),
),
migrations.AddConstraint(
model_name='deposit',
constraint=models.CheckConstraint(condition=models.Q(('status__in', ['detected', 'credited', 'orphaned'])), name='lottery_deposit_status_valid'),
),
migrations.AddConstraint(
model_name='deposit',
constraint=models.CheckConstraint(condition=models.Q(models.Q(('status', 'credited'), _negated=True), models.Q(('movement__isnull', False), ('credited_at__isnull', False)), _connector='OR'), name='lottery_deposit_credited_has_movement'),
),
]
@@ -0,0 +1,20 @@
"""Transaction versions are append-only in the database too (DAT-83): a raw `UPDATE` or `DELETE` is refused.
SQLite syntax, like the audit triggers (ADR-55)."""
from django.db import migrations
CREATE = [
"""CREATE TRIGGER lottery_txversion_no_update BEFORE UPDATE ON lottery_transactionversion
BEGIN SELECT RAISE(ABORT, 'transaction versions are append-only'); END""",
"""CREATE TRIGGER lottery_txversion_no_delete BEFORE DELETE ON lottery_transactionversion
BEGIN SELECT RAISE(ABORT, 'transaction versions are append-only'); END""",
]
DROP = [
"DROP TRIGGER IF EXISTS lottery_txversion_no_update",
"DROP TRIGGER IF EXISTS lottery_txversion_no_delete",
]
class Migration(migrations.Migration):
dependencies = [("lottery", "0004_chain_tables")]
operations = [migrations.RunSQL(sql=CREATE, reverse_sql=DROP)]
+123
View File
@@ -11,6 +11,8 @@ Rows that carry money are never deleted: every foreign key is PROTECT (DAT-76).
from django.conf import settings
from django.db import models
from django.db.models import F, Q, Value
from django.db.models.functions import Length
from django.db.models.lookups import Exact
from django.utils import timezone
SATS_PER_PLM = 100_000_000
@@ -420,3 +422,124 @@ class Report(models.Model):
def __str__(self) -> str:
return f"Report {self.pk} ({self.status})"
# --- chain tables (roadmap B4, DAT-81..DAT-84) ---------------------------------------------------
class DepositAddress(models.Model):
"""A player's one deposit address and the HD index it comes from (DAT-81)."""
user = models.OneToOneField(settings.AUTH_USER_MODEL, on_delete=models.PROTECT, related_name="deposit_address")
derivation_index = models.PositiveIntegerField(unique=True)
address = models.CharField(max_length=128, unique=True)
network = models.CharField(max_length=16) # the profile it was derived for (ADR-58)
created_at = models.DateTimeField(default=timezone.now)
class Meta:
constraints = [
models.CheckConstraint(condition=Q(network__in=["mainnet", "regtest"]), name="lottery_depositaddress_network_valid"),
]
def __str__(self) -> str:
return f"{self.address} (index {self.derivation_index})"
class Utxo(models.Model):
"""An output the platform controls (DAT-82): a player's deposit or a round's pool money."""
txid = models.CharField(max_length=64)
vout = models.PositiveIntegerField()
amount_sats = models.BigIntegerField()
address = models.CharField(max_length=128)
user = models.ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True, on_delete=models.PROTECT, related_name="utxos")
round = models.ForeignKey(Round, null=True, blank=True, on_delete=models.PROTECT, related_name="utxos")
confirmed_height = models.PositiveIntegerField(null=True, blank=True)
spent_txid = models.CharField(max_length=64, null=True, blank=True)
# ARC-72: the transaction that is spending it. Taken atomically in the database, never in memory (B6).
reserved_by = models.ForeignKey(
ChainTransaction, null=True, blank=True, on_delete=models.PROTECT, related_name="reserved_utxos"
)
created_at = models.DateTimeField(default=timezone.now)
class Meta:
indexes = [models.Index(fields=["address"]), models.Index(fields=["user"])]
constraints = [
models.UniqueConstraint(fields=["txid", "vout"], name="lottery_utxo_outpoint_unique"),
models.CheckConstraint(condition=Q(amount_sats__gt=0), name="lottery_utxo_amount_positive"),
models.CheckConstraint(condition=Exact(Length("txid"), 64), name="lottery_utxo_txid_length"),
models.CheckConstraint(
condition=Q(spent_txid__isnull=True) | Q(Exact(Length("spent_txid"), 64)), name="lottery_utxo_spent_txid_length"
),
models.CheckConstraint(condition=Q(user__isnull=True) | Q(round__isnull=True), name="lottery_utxo_user_or_round"),
]
def __str__(self) -> str:
return f"{self.txid[:12]}:{self.vout}"
class TransactionVersionImmutable(Exception):
"""An attempt to change or delete a transaction version (DAT-83)."""
class TransactionVersionQuerySet(models.QuerySet):
def update(self, **kwargs):
raise TransactionVersionImmutable("transaction versions are append-only")
def delete(self):
raise TransactionVersionImmutable("transaction versions are append-only")
class TransactionVersion(models.Model):
"""Every txid a platform transaction has ever had (TX-19, DAT-83): the network may confirm any of them."""
transaction = models.ForeignKey(ChainTransaction, on_delete=models.PROTECT, related_name="versions")
txid = models.CharField(max_length=64, unique=True)
raw_hex = models.TextField(blank=True, default="")
created_at = models.DateTimeField(default=timezone.now)
objects = TransactionVersionQuerySet.as_manager()
class Meta:
constraints = [models.CheckConstraint(condition=Exact(Length("txid"), 64), name="lottery_txversion_txid_length")]
def save(self, *args, **kwargs):
if not self._state.adding:
raise TransactionVersionImmutable("transaction versions are append-only")
super().save(*args, **kwargs)
def delete(self, *args, **kwargs):
raise TransactionVersionImmutable("transaction versions are append-only")
def __str__(self) -> str:
return self.txid
class Deposit(models.Model):
"""An output that paid a player's deposit address (DAT-84)."""
class Status(models.TextChoices):
DETECTED = "detected"
CREDITED = "credited"
ORPHANED = "orphaned"
user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.PROTECT, related_name="deposits")
utxo = models.OneToOneField(Utxo, on_delete=models.PROTECT, related_name="deposit")
movement = models.OneToOneField(Movement, null=True, blank=True, on_delete=models.PROTECT, related_name="deposit")
status = models.CharField(max_length=16, choices=Status.choices, default=Status.DETECTED)
detected_at = models.DateTimeField(default=timezone.now)
credited_at = models.DateTimeField(null=True, blank=True)
class Meta:
constraints = [
models.CheckConstraint(
condition=Q(status__in=["detected", "credited", "orphaned"]), name="lottery_deposit_status_valid"
),
models.CheckConstraint(
condition=~Q(status="credited") | (Q(movement__isnull=False) & Q(credited_at__isnull=False)),
name="lottery_deposit_credited_has_movement",
),
]
def __str__(self) -> str:
return f"Deposit {self.pk} ({self.status})"
+6
View File
@@ -166,6 +166,12 @@ if PLM_NETWORK == "mainnet" and os.environ.get("PLM_MAINNET_CONFIRMED", "") != "
raise ImproperlyConfigured("PLM_NETWORK=mainnet needs PLM_MAINNET_CONFIRMED=yes (ADR-58): real funds are at stake")
PLM_PROFILE = network_profile(PLM_NETWORK)
# ARC-78: the web process knows only the public account key; the signing key is the worker's alone.
PROCESS_ROLE = os.environ.get("PROCESS_ROLE", "web")
PLM_ACCOUNT_XPUB = os.environ.get("PLM_ACCOUNT_XPUB", "")
PLM_MASTER_KEY_FILE = os.environ.get("PLM_MASTER_KEY_FILE", "")
PLM_KEY_ENCRYPTION_KEY_FILE = os.environ.get("PLM_KEY_ENCRYPTION_KEY_FILE", "")
# The simulated chain (ADR-59): a block every N seconds and a confirmation after M, so a whole round
# runs in a few minutes on localhost. Real chains ignore both.
SIMULATED_BLOCK_SECONDS = int(os.environ.get("SIMULATED_BLOCK_SECONDS", "20"))
+1
View File
@@ -53,6 +53,7 @@ services:
env_file: .env
environment:
- DJANGO_DB_PATH=/app/db_data/site.sqlite3
- PROCESS_ROLE=worker
command: ["/bin/sh", "-c", "umask 077; exec python manage.py run_worker"]
volumes:
- ./data/db:/app/db_data
+9
View File
@@ -981,6 +981,15 @@ non è rimosso le sezioni precedenti descrivono lo stato storico. Scelte: [ADR-5
- **[ARC-72]** **Nessuna coordinazione in memoria fra web e worker.** Esclusione reciproca e unicità si
ottengono con vincoli e transazioni del database, mai con blocchi o code in memoria.
*Stato:* da implementare (A2 per i vincoli, B6 per la prenotazione degli UTXO).
- **[ARC-78]** **La chiave di firma è del solo worker.** Il processo web conosce soltanto la chiave **pubblica** dell'account
(`PLM_ACCOUNT_XPUB`): basta a derivare gli indirizzi di deposito e dei round ([DAT-81]). La chiave privata (la master xprv
cifrata e la chiave che la cifra, due file diversi) si carica solo se `PROCESS_ROLE=worker` e i file sono montati; in
qualunque altro processo `signing_account_key()` fallisce con `SigningKeyUnavailable`, anche se i file ci fossero.
`manage.py init_keys` crea le chiavi una tantum, scrive i file con modo `0600` e stampa la sola chiave pubblica.
*Stato:* implementato (B4); il montaggio dei file nel solo servizio `worker` arriva con B6, quando il worker firma ·
*Codice:* `apps/lottery/keys.py`, `apps/lottery/management/commands/init_keys.py` ·
*Test:* `tests/django/test_chain_models.py::test_the_web_process_cannot_load_the_signing_key`, `test_the_worker_can_and_the_files_are_private`
- **[ARC-73]** **Liveness.** `GET /health/live` risponde `200 {"status": "ok"}` se il processo risponde e il
database si apre, `503` altrimenti; il compose lo usa come healthcheck del servizio `web`.
*Stato:* implementato (A1) ·
+2 -2
View File
@@ -4,7 +4,7 @@
## Project status (old stack)
All 10 stages of the original build order are code-complete and unit-tested — 1187 tests, the old stack's under `tests/unit/` and the Django ones under `tests/django/` (`tests/integration/` needs the local regtest node and skips itself without it). Beyond them: Docker + Caddy deployment, admin dashboard (`/admin`), static test UI (`/`), pending-inclusive balance display, an SSE push channel layered over the original polling, self-service password change + admin password reset, and the reconciliation/corroboration machinery below.
All 10 stages of the original build order are code-complete and unit-tested — 1211 tests, the old stack's under `tests/unit/` and the Django ones under `tests/django/` (`tests/integration/` needs the local regtest node and skips itself without it). Beyond them: Docker + Caddy deployment, admin dashboard (`/admin`), static test UI (`/`), pending-inclusive balance display, an SSE push channel layered over the original polling, self-service password change + admin password reset, and the reconciliation/corroboration machinery below.
Verified on mainnet with real money: registration + address derivation, deposit crediting (at the time, 1-conf; deposits now need `deposit_confirmations`), a real 10 PLM bet (broadcast → confirmed → change credited back), and one full round cycle (close → draw on a real block hash → 70/30 payout with sat math checked against the broadcast tx → confirmation → close → next round auto-opened). **Withdrawal and the RBF bump path have never been exercised against a live broadcast** — unit-tested only.
@@ -30,7 +30,7 @@ PYTHONPATH=. python scripts/decrypt_master_key.py # ops recovery: decrypt+pr
PYTHONPATH=. python scripts/encrypt_master_key.py # ops bootstrap: import an externally-generated xprv (--overwrite to replace)
PYTHONPATH=. python scripts/electrum_smoke_test.py # manual check: connect, handshake, subscribe to headers, print the tip
python -m pytest # all 1187 tests
python -m pytest # all 1211 tests
python -m pytest tests/unit/test_hd.py # one file
python -m pytest tests/unit/test_hd.py::test_derivation_is_deterministic # one test
```
+28 -1
View File
@@ -1493,7 +1493,7 @@ scrive la stringa vuota).
Lo schema del sito Django (`apps/lottery/models.py`, `apps/accounts/models.py`) sostituisce quello
SQLAlchemy descritto sopra (roadmap A2–D1); fino ad allora il resto del documento è lo stato storico.
Le regole che devono valere comunque sono **vincoli del database**, non convenzioni ([ARC-72]).
Le tabelle di catena (UTXO, versioni delle transazioni, depositi, indici HD) arrivano con la Fase B (B4).
Le tabelle di catena (UTXO, versioni delle transazioni, depositi, indici HD) sono la Fase B (B4: [DAT-81]…[DAT-84]).
- **[DAT-76]** **Il denaro non si cancella.** Ogni chiave esterna delle tabelle `lottery_*` verso utenti, round,
partecipazioni e transazioni è `PROTECT`: un utente, un round o una transazione con righe collegate non
@@ -1531,3 +1531,30 @@ Le tabelle di catena (UTXO, versioni delle transazioni, depositi, indici HD) arr
accanto alle righe, quindi non può divergere da esse.
*Stato:* implementato (A3) · *Codice:* `apps/lottery/balances.py:balance_of` ·
*Test:* `tests/django/test_ledger.py::test_a_pending_deposit_is_incoming_not_spendable`, `test_a_whole_round_conserves_the_money`
- **[DAT-81]** **Indirizzo di deposito e indice HD.** Ogni giocatore ha **un solo** indirizzo di deposito
(`DepositAddress`): l'indice di derivazione (`0/<indice>` sotto l'account del profilo di rete, [ADR-58](adr/ADR-58-alfa-su-regtest-profilo-di-rete-configurabile.md))
è **unico** e l'indirizzo è unico; l'indice è il successivo al massimo assegnato e due assegnazioni
concorrenti non possono avere lo stesso, perché è il vincolo del database a deciderlo (chi perde riprova).
L'assegnazione è idempotente: lo stesso utente riceve sempre lo stesso indirizzo, e a parità di chiave e indice
l'indirizzo è sempre lo stesso. Si deriva dalla sola chiave **pubblica** dell'account ([ARC-78]).
*Stato:* implementato (B4) · *Codice:* `apps/lottery/models.py:DepositAddress`, `apps/lottery/chain.py:assign_deposit_address` ·
*Test:* `tests/django/test_chain_models.py::test_a_player_gets_one_address_and_always_the_same`, `test_derivation_is_identical_for_the_same_input`, `test_two_players_never_share_an_index`
- **[DAT-82]** **UTXO.** `Utxo` è un output che la piattaforma controlla: `(txid, vout)` unico, importo positivo, indirizzo,
a chi appartiene (un giocatore, per un deposito, oppure un round, per il suo montepremi; mai entrambi),
altezza di conferma (vuota finché non è confermato), `spent_txid` (vuoto finché non è speso) e la prenotazione
`reserved_by` verso la transazione della piattaforma che lo sta spendendo ([ARC-72], B6). Un `txid` ha sempre 64 caratteri.
*Stato:* implementato (B4); la prenotazione atomica è B6 · *Codice:* `apps/lottery/models.py:Utxo` ·
*Test:* `tests/django/test_chain_models.py::test_an_outpoint_is_stored_once`, `test_a_utxo_belongs_to_a_player_or_a_round_never_both`, `test_amounts_and_txids_are_checked_by_the_database`
- **[DAT-83]** **Tutte le versioni di una transazione** ([TX-19]). `TransactionVersion` registra ogni txid che una
`ChainTransaction` ha avuto (la prima, ogni sostituzione RBF, ogni candidata scritta prima del bump) con la
transazione grezza; il `txid` è **unico in tutta la tabella** (appartiene a una sola transazione) e le righe sono
**in sola aggiunta** (il modello e il database rifiutano modifiche e cancellazioni). `register_version` è
idempotente e aggiorna `current_txid` nella stessa transazione del database.
*Stato:* implementato (B4) · *Codice:* `apps/lottery/models.py:TransactionVersion`, `apps/lottery/chain.py:register_version` ·
*Test:* `tests/django/test_chain_models.py::test_every_version_of_a_transaction_is_kept`, `test_a_txid_belongs_to_one_transaction`, `test_versions_cannot_be_changed_or_deleted`
- **[DAT-84]** **Depositi.** `Deposit` lega un `Utxo` a un giocatore: stati `detected` (visto sulla catena),
`credited` (accreditato con un `Movement` di tipo `deposit`) e `orphaned` (sparito per una riorganizzazione).
Un output è un solo deposito e un `credited` ha sempre il movimento e la data di accredito.
*Stato:* tabella implementata (B4); il listener e l'accredito sono B5 · *Codice:* `apps/lottery/models.py:Deposit` ·
*Test:* `tests/django/test_chain_models.py::test_a_credited_deposit_has_its_movement_and_date`, `test_an_output_is_one_deposit`
+2 -1
View File
@@ -22,7 +22,8 @@ def user_key(account: HDKey, derivation_index: int) -> HDKey:
def address_of(key: HDKey, profile: Profile = MAINNET) -> str:
return script.p2wpkh(key.to_public()).address(network=profile.embit)
public = key.to_public() if key.is_private else key # a key derived from an xpub is already public
return script.p2wpkh(public).address(network=profile.embit)
def user_address(account: HDKey, derivation_index: int, profile: Profile = MAINNET) -> str:
+1 -1
View File
@@ -42,7 +42,7 @@ Uscita: flusso completo su regtest; un riavvio durante il broadcast, due richies
- [x] **B1 · Pacchetto `plm_engine`** (le primitive dell'estrazione sono già state spostate in A4). Spostamento dei moduli senza database (derivazione HD, `psbt_builder`, client Electrum, `merkle`, `draw`) e dei loro test, senza cambiare il comportamento. *Requisiti:* ADR-59. *Test:* i test esistenti dei moduli passano invariati.
- [x] **B2 · Profilo di rete.** `PLM_NETWORK=regtest|mainnet` (hrp, prefissi, genesis, powLimit), conferma esplicita per `mainnet`, validazione degli indirizzi con l'hrp del profilo. *Requisiti:* ADR-58, ELC-30. *Test:* indirizzi e genesis per ciascun profilo.
- [x] **B3 · Ambiente regtest e fixture.** Il nodo (`palladiumcore` in `-regtest`) e Fulcrum sono quelli della cartella `plm-regtest` accanto al repository (`docker compose up -d` lì): non si duplicano nel compose del sito, ci si aggancia. `plm_engine/regtest.py` (client RPC con rifiuto di toccare una catena diversa da regtest), `scripts/regtest.py` (`status`, `mine`, `fund`) e le fixture di `tests/integration/`, che si saltano se il nodo o Fulcrum non rispondono. *Test:* `tests/integration/test_regtest_smoke.py` (blocco minato, indirizzi e genesis del profilo, tip di Fulcrum, fondi visti via Electrum).
- [ ] **B4 · Modelli di catena.** UTXO, transazioni con tutte le versioni TXID, depositi, assegnazione dell'indice HD; la chiave di firma è accessibile solo al processo worker. *Requisiti:* DAT, TX. *Test:* vincoli, derivazione identica a parità di input.
- [x] **B4 · Modelli di catena.** UTXO, transazioni con tutte le versioni TXID, depositi, assegnazione dell'indice HD; la chiave di firma è accessibile solo al processo worker. *Requisiti:* DAT, TX. *Test:* vincoli, derivazione identica a parità di input.
- [ ] **B5 · Listener e depositi reali.** Listener Electrum sull'ORM con rotazione, header validati, quorum e soglie di conferma al posto del deposito simulato. *Requisiti:* DEP, ELC. *Test:* unit con server finto + integrazione su regtest.
- [ ] **B6 · Prenotazione UTXO e puntata reale.** Prenotazione atomica degli UTXO nel database, identificativo idempotente, «salva operazione e transazione firmata prima del broadcast», verdetto del broadcast (accettato, rifiutato, incerto). *Requisiti:* BET, TX-26. *Test:* due richieste concorrenti non spendono gli stessi input; timeout ambiguo riconciliato.
- [ ] **B7 · Conferme, riconciliazione e RBF.** Poller, riconciliatore e bumper sull'ORM con tutte le versioni TXID e adozione della versione confermata. *Requisiti:* TX. *Test:* conferma di una versione RBF precedente, ripresa dopo riavvio.
+280
View File
@@ -0,0 +1,280 @@
"""B4 — chain tables and who holds the keys: DAT-81..DAT-84, TX-19, ARC-72, ARC-78, ADR-58."""
import json
import os
import stat
import subprocess
import sys
from pathlib import Path
import pytest
from django.contrib.auth import get_user_model
from django.core.management import call_command
from django.db import IntegrityError, connection, transaction
from embit.bip32 import HDKey
from plm_engine import hd
from plm_engine.network import MAINNET, REGTEST
from apps.lottery import chain, keys
from apps.lottery.addresses import participant_address
from apps.lottery.models import (
ChainTransaction,
Deposit,
DepositAddress,
Movement,
Round,
TransactionVersion,
TransactionVersionImmutable,
Utxo,
)
ROOT = Path(__file__).resolve().parents[2]
User = get_user_model()
TXID = "ab" * 32
OTHER = "cd" * 32
@pytest.fixture
def xpub(settings, tmp_path):
"""A fresh master key, its public account key configured as the web process would have it."""
settings.PLM_ACCOUNT_XPUB = keys.generate_keys(tmp_path / "keys", settings.PLM_PROFILE)
return settings.PLM_ACCOUNT_XPUB
def make_user(name="mario"):
return User.objects.create_user(name, password="x" * 12)
def make_tx(user=None):
return ChainTransaction.objects.create(kind="bet", user=user or make_user("tx-owner"))
# --- DAT-81: addresses and HD indexes ------------------------------------------------------------
@pytest.mark.django_db
def test_a_player_gets_one_address_and_always_the_same(xpub, settings):
user = make_user()
first = chain.assign_deposit_address(user)
assert first.derivation_index == 0 and first.address.startswith(settings.PLM_PROFILE.hrp + "1")
assert chain.assign_deposit_address(user) == first and DepositAddress.objects.count() == 1
@pytest.mark.django_db
def test_two_players_never_share_an_index(xpub):
a, b = chain.assign_deposit_address(make_user("a")), chain.assign_deposit_address(make_user("b"))
assert (a.derivation_index, b.derivation_index) == (0, 1) and a.address != b.address
with pytest.raises(IntegrityError), transaction.atomic(): # the database decides, not the code
DepositAddress.objects.create(user=make_user("c"), derivation_index=1, address="rplm1other", network="regtest")
_ASSIGN = """
import django, json, sys
django.setup()
from django.contrib.auth import get_user_model
from apps.lottery.chain import assign_deposit_address
user = get_user_model().objects.get(username=sys.argv[1])
print(json.dumps(assign_deposit_address(user).derivation_index))
"""
def test_concurrent_assignments_all_get_distinct_indexes(tmp_path, settings):
"""ARC-72, DAT-81: six processes ask for an address at once on one database file; six different indexes."""
env = {"PATH": os.environ["PATH"], "PYTHONPATH": str(ROOT), "DJANGO_SECRET_KEY": "k" * 60,
"DJANGO_DB_PATH": str(tmp_path / "site.sqlite3"), "DJANGO_SETTINGS_MODULE": "config.settings",
"PLM_ACCOUNT_XPUB": keys.generate_keys(tmp_path / "keys", settings.PLM_PROFILE)}
subprocess.run([sys.executable, "manage.py", "migrate", "--noinput", "-v", "0"], cwd=ROOT, env=env, check=True)
names = [f"p{i}" for i in range(6)]
setup = "import django; django.setup()\nfrom django.contrib.auth import get_user_model as g\n" + "".join(
f"g().objects.create_user({n!r}, password='x'*12)\n" for n in names)
subprocess.run([sys.executable, "-c", setup], cwd=ROOT, env=env, check=True)
procs = [subprocess.Popen([sys.executable, "-c", _ASSIGN, n], cwd=ROOT, env=env, stdout=subprocess.PIPE,
stderr=subprocess.PIPE, text=True) for n in names]
outputs = [p.communicate(timeout=120) for p in procs]
assert all(p.returncode == 0 for p in procs), [o[1] for o in outputs]
assert sorted(json.loads(o[0].strip().splitlines()[-1]) for o in outputs) == list(range(6))
def test_derivation_is_identical_for_the_same_input():
master = HDKey.from_seed(bytes(range(32)), version=REGTEST.embit["xprv"])
private = hd.account_key(master, REGTEST)
public = HDKey.from_base58(private.to_public().to_base58(version=REGTEST.embit["xpub"]))
for index in (0, 1, 41):
assert hd.user_address(public, index, REGTEST) == hd.user_address(private, index, REGTEST)
assert hd.user_address(public, index, REGTEST) == hd.user_address(public, index, REGTEST)
assert hd.pool_address(public, 7, REGTEST) == hd.pool_address(private, 7, REGTEST)
assert hd.user_address(public, 0, REGTEST) != hd.user_address(public, 1, REGTEST)
@pytest.mark.django_db
def test_the_participant_address_on_a_real_ledger_is_the_deposit_address(xpub, settings):
settings.LEDGER_BACKEND = "chain"
user = make_user()
assert participant_address(user) == chain.assign_deposit_address(user).address
@pytest.mark.django_db
def test_assigning_without_a_public_key_fails_loudly(settings):
settings.PLM_ACCOUNT_XPUB = ""
with pytest.raises(keys.SigningKeyUnavailable):
chain.assign_deposit_address(make_user())
assert not DepositAddress.objects.exists()
# --- DAT-82: UTXO ----------------------------------------------------------------------------------
@pytest.mark.django_db
def test_an_outpoint_is_stored_once():
Utxo.objects.create(txid=TXID, vout=0, amount_sats=5, address="rplm1a")
Utxo.objects.create(txid=TXID, vout=1, amount_sats=5, address="rplm1a")
with pytest.raises(IntegrityError), transaction.atomic():
Utxo.objects.create(txid=TXID, vout=0, amount_sats=7, address="rplm1a")
@pytest.mark.django_db
def test_a_utxo_belongs_to_a_player_or_a_round_never_both():
Utxo.objects.create(txid=TXID, vout=0, amount_sats=5, address="a", user=make_user())
round_ = Round.objects.create()
Utxo.objects.create(txid=TXID, vout=1, amount_sats=5, address="a", round=round_)
with pytest.raises(IntegrityError), transaction.atomic():
Utxo.objects.create(txid=TXID, vout=2, amount_sats=5, address="a", user=make_user("x"), round=round_)
@pytest.mark.django_db
@pytest.mark.parametrize("fields", [{"amount_sats": 0}, {"amount_sats": -1}, {"txid": "ab" * 31}, {"spent_txid": "short"}])
def test_amounts_and_txids_are_checked_by_the_database(fields):
data = {"txid": TXID, "vout": 0, "amount_sats": 5, "address": "a", **fields}
with pytest.raises(IntegrityError), transaction.atomic():
Utxo.objects.create(**data)
@pytest.mark.django_db
def test_a_utxo_can_be_reserved_by_a_transaction_and_the_transaction_is_protected():
tx = make_tx()
Utxo.objects.create(txid=TXID, vout=0, amount_sats=5, address="a", reserved_by=tx)
from django.db.models import ProtectedError
with pytest.raises(ProtectedError):
tx.delete()
# --- DAT-83: versions ---------------------------------------------------------------------------------
@pytest.mark.django_db
def test_every_version_of_a_transaction_is_kept():
tx = make_tx()
chain.register_version(tx, TXID, "00aa")
chain.register_version(tx, OTHER, "00bb") # an RBF replacement
tx.refresh_from_db()
assert tx.current_txid == OTHER and tx.raw_hex == "00bb"
assert set(tx.versions.values_list("txid", flat=True)) == {TXID, OTHER}
@pytest.mark.django_db
def test_registering_a_version_twice_is_one_version():
tx = make_tx()
chain.register_version(tx, TXID, "00aa")
chain.register_version(tx, TXID, "00aa")
assert tx.versions.count() == 1
@pytest.mark.django_db
def test_a_txid_belongs_to_one_transaction():
chain.register_version(make_tx(), TXID, "00aa")
with pytest.raises(chain.TxidConflict):
chain.register_version(make_tx(make_user("other")), TXID, "00aa")
@pytest.mark.django_db
def test_versions_cannot_be_changed_or_deleted():
version = chain.register_version(make_tx(), TXID, "00aa")
with pytest.raises(TransactionVersionImmutable):
version.raw_hex = "ff"
version.save()
with pytest.raises(TransactionVersionImmutable):
version.delete()
with pytest.raises(TransactionVersionImmutable):
TransactionVersion.objects.all().update(raw_hex="")
with pytest.raises(Exception, match="append-only"), transaction.atomic(): # and so does the database
with connection.cursor() as cursor:
cursor.execute("UPDATE lottery_transactionversion SET raw_hex = 'x'")
with pytest.raises(Exception, match="append-only"), transaction.atomic():
with connection.cursor() as cursor:
cursor.execute("DELETE FROM lottery_transactionversion")
# --- DAT-84: deposits -------------------------------------------------------------------------------------
def make_utxo(user, vout=0):
return Utxo.objects.create(txid=TXID, vout=vout, amount_sats=100, address="a", user=user)
@pytest.mark.django_db
def test_an_output_is_one_deposit():
user = make_user()
utxo = make_utxo(user)
Deposit.objects.create(user=user, utxo=utxo)
with pytest.raises(IntegrityError), transaction.atomic():
Deposit.objects.create(user=user, utxo=utxo)
@pytest.mark.django_db
def test_a_credited_deposit_has_its_movement_and_date():
from django.utils import timezone
user = make_user()
with pytest.raises(IntegrityError), transaction.atomic():
Deposit.objects.create(user=user, utxo=make_utxo(user), status="credited")
movement = Movement.objects.create(user=user, kind="deposit", status="confirmed", amount_sats=100, confirmed_at=timezone.now())
ok = Deposit.objects.create(user=user, utxo=make_utxo(user, 1), status="credited", movement=movement, credited_at=timezone.now())
assert ok.movement == movement
# --- ARC-78: who holds the keys ---------------------------------------------------------------------------
def test_the_web_process_cannot_load_the_signing_key(settings, tmp_path):
keys.generate_keys(tmp_path / "keys", settings.PLM_PROFILE)
settings.PLM_MASTER_KEY_FILE = str(tmp_path / "keys" / "master.key")
settings.PLM_KEY_ENCRYPTION_KEY_FILE = str(tmp_path / "keys" / "master.encryption.key")
settings.PROCESS_ROLE = "web" # the files are there, and it still refuses
with pytest.raises(keys.SigningKeyUnavailable):
keys.signing_account_key()
def test_the_worker_can_and_the_files_are_private(settings, tmp_path):
xpub = keys.generate_keys(tmp_path / "keys", settings.PLM_PROFILE)
for name in ("master.key", "master.encryption.key"):
assert stat.S_IMODE(os.stat(tmp_path / "keys" / name).st_mode) == 0o600
settings.PLM_MASTER_KEY_FILE = str(tmp_path / "keys" / "master.key")
settings.PLM_KEY_ENCRYPTION_KEY_FILE = str(tmp_path / "keys" / "master.encryption.key")
settings.PROCESS_ROLE = "worker"
private = keys.signing_account_key()
# the private key and the published public key are the same account
public = HDKey.from_base58(xpub)
assert hd.user_address(private, 3, settings.PLM_PROFILE) == hd.user_address(public, 3, settings.PLM_PROFILE)
def test_a_wrong_encryption_key_does_not_load(settings, tmp_path):
keys.generate_keys(tmp_path / "a", settings.PLM_PROFILE)
keys.generate_keys(tmp_path / "b", settings.PLM_PROFILE)
settings.PLM_MASTER_KEY_FILE = str(tmp_path / "a" / "master.key")
settings.PLM_KEY_ENCRYPTION_KEY_FILE = str(tmp_path / "b" / "master.encryption.key")
settings.PROCESS_ROLE = "worker"
with pytest.raises(keys.SigningKeyUnavailable):
keys.signing_account_key()
def test_keys_are_never_overwritten(settings, tmp_path):
keys.generate_keys(tmp_path / "keys", settings.PLM_PROFILE)
with pytest.raises(FileExistsError):
keys.generate_keys(tmp_path / "keys", settings.PLM_PROFILE)
def test_init_keys_prints_only_the_public_key(settings, tmp_path, capsys):
call_command("init_keys", str(tmp_path / "k"))
out = capsys.readouterr().out
assert "PLM_ACCOUNT_XPUB=tpub" in out and "xprv" not in out and "tprv" not in out