From 2acd4ccd1c2538c188215c330a3182a6e7af14d4 Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Mon, 16 Nov 2026 16:09:36 +0100 Subject: [PATCH] B5: real deposits on the ORM, Electrum scan with quorum and merkle proof, configurable threshold (DEP-20..23, ELC-31) Co-Authored-By: Claude Sonnet 5.5 --- .env.example | 5 + CLAUDE.md | 2 +- README.md | 2 +- apps/lottery/admin.py | 25 +- apps/lottery/deposits.py | 185 +++++++++++++ apps/lottery/electrum_chain.py | 224 +++++++++++++++ .../lottery/management/commands/run_worker.py | 25 ++ .../migrations/0006_deposit_confirmations.py | 22 ++ apps/lottery/models.py | 7 + config/settings.py | 22 ++ docs/connessione-electrum.md | 12 + docs/legacy-fastapi-notes.md | 4 +- docs/modello-dati.md | 2 +- docs/registrazione-e-depositi.md | 32 +++ plm_engine/electrum/client.py | 88 +++--- roadmap.md | 2 +- tests/django/test_deposits.py | 259 +++++++++++++++++ tests/django/test_electrum_chain.py | 261 ++++++++++++++++++ tests/django/test_ledger.py | 3 +- tests/django/test_network_profile.py | 6 +- tests/integration/test_deposits_regtest.py | 84 ++++++ 21 files changed, 1223 insertions(+), 49 deletions(-) create mode 100644 apps/lottery/deposits.py create mode 100644 apps/lottery/electrum_chain.py create mode 100644 apps/lottery/migrations/0006_deposit_confirmations.py create mode 100644 tests/django/test_deposits.py create mode 100644 tests/django/test_electrum_chain.py create mode 100644 tests/integration/test_deposits_regtest.py diff --git a/.env.example b/.env.example index e432af5..dde4afa 100644 --- a/.env.example +++ b/.env.example @@ -73,6 +73,11 @@ PLM_MAINNET_CONFIRMED= # 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= +# Electrum servers of a real ledger (LEDGER_BACKEND=chain), first = preferred, at least three for a quorum: +# host:port[:notls][:pin=],host:port,... +# ELECTRUM_ALLOW_NO_QUORUM=true is for development with a single server and is refused on mainnet. +ELECTRUM_SERVERS= +ELECTRUM_ALLOW_NO_QUORUM= # Optional extras when serving a domain; SITE_ADDRESS itself is always allowed. DJANGO_ALLOWED_HOSTS= DJANGO_CSRF_TRUSTED_ORIGINS= diff --git a/CLAUDE.md b/CLAUDE.md index 1587800..9fa087b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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–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). +The migration from FastAPI to Django is in progress on branch `django-migration` (plan: [roadmap.md](roadmap.md), steps A1–A10, B1–B5 done). The suite has 1263 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. diff --git a/README.md b/README.md index 3e24d4d..3a75e1a 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ python -m pytest # all tests python -m pytest tests/unit/test_hd.py # one file ``` -1211 unit tests cover HD derivation, PSBT building, the Electrum client, bets, +1263 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 diff --git a/apps/lottery/admin.py b/apps/lottery/admin.py index c4dc586..ff69676 100644 --- a/apps/lottery/admin.py +++ b/apps/lottery/admin.py @@ -5,7 +5,7 @@ from django.contrib import admin from django.db import transaction from . import audit -from .models import AuditEntry, ChainTransaction, Movement, Participation, Report, Round +from .models import AuditEntry, ChainTransaction, LotteryConfig, Movement, Participation, Report, Round class ReadOnlyAdmin(admin.ModelAdmin): @@ -75,3 +75,26 @@ class ReportAdmin(admin.ModelAdmin): obj.save(update_fields=["status", "status_changed_at"]) audit.record("report_status_changed", actor=request.user, subject_type="report", subject_id=obj.pk, payload={"from": before, "to": obj.status}) + + +@admin.register(LotteryConfig) +class LotteryConfigAdmin(admin.ModelAdmin): + """The operational parameters (DAT-77). The three pause switches are not here: they go through the console's + commands, which ask for a reason (WEB-43). A change is audited with what changed.""" + + fields = ("fee_address", "bet_amount_sats", "round_duration_seconds", "round_cooldown_seconds", + "draw_confirmations", "deposit_confirmations", "max_round_pool_sats") + + def has_add_permission(self, request): + return False + + def has_delete_permission(self, request, obj=None): + return False + + def save_model(self, request, obj, form, change): + changes = {name: [form.initial.get(name), getattr(obj, name)] for name in form.changed_data} + with transaction.atomic(): + super().save_model(request, obj, form, change) + if changes: + audit.record("config_changed", actor=request.user, subject_type="config", subject_id=obj.pk, + payload={"changed": changes}) diff --git a/apps/lottery/deposits.py b/apps/lottery/deposits.py new file mode 100644 index 0000000..434075f --- /dev/null +++ b/apps/lottery/deposits.py @@ -0,0 +1,185 @@ +"""Real deposits on the Django site (roadmap B5, DEP-20..DEP-23). + +A scan is three phases (DEP-20): `plan` reads the database, `ElectrumChain.observe` asks the servers with no +database open, `apply_observations` writes only what was verified, re-checking each coin as it saves. What +happens after a credit — coins spent elsewhere, reorgs deeper than the threshold — is B7. +""" + +import logging +from dataclasses import dataclass, field +from datetime import datetime + +from django.db import transaction +from django.utils import timezone +from plm_engine.psbt_builder import DUST_LIMIT_SATS + +from . import audit +from .models import Deposit, DepositAddress, LotteryConfig, Movement, TransactionVersion, Utxo + +logger = logging.getLogger(__name__) + +COINBASE_MATURITY = 120 # DEP-21: PLM coinbase maturity (palladiumcore consensus.h) + + +@dataclass(frozen=True) +class Policy: + """What phase 1 hands to the network phase.""" + + addresses: tuple[str, ...] + own_txids: frozenset[str] + deposit_confirmations: int + credited: frozenset[tuple[str, int]] # outpoints already credited: never looked at again + waiting: dict[str, frozenset[tuple[str, int]]] # per address, the deposits seen but not yet credited + + +@dataclass(frozen=True) +class Seen: + """An unspent output as the servers list it.""" + + txid: str + vout: int + value: int + height: int # 0 = mempool + + +@dataclass +class Observation: + """What phase 2 found at one address. `entries` is None when no server gave a usable answer: nothing is + concluded from silence. `verified` holds the outpoints whose credit the other servers corroborated and whose + merkle proof held; `absent_confirmed` those the other servers also do not list any more.""" + + entries: list[Seen] | None + verified: set[tuple[str, int]] = field(default_factory=set) + absent_confirmed: set[tuple[str, int]] = field(default_factory=set) + coinbase: set[str] = field(default_factory=set) + + +@dataclass +class ScanResult: + tip: int | None + addresses: dict[str, Observation] + + +def threshold_for(txid: str, policy: Policy, coinbase: set[str]) -> int: + """DEP-21: 1 for the platform's own transactions, 120 for a coinbase, else the configured threshold.""" + if txid in policy.own_txids: + return 1 + if txid in coinbase: + return COINBASE_MATURITY + return policy.deposit_confirmations + + +def plan() -> Policy: + """Phase 1: everything the network phase needs, read in one go.""" + return Policy( + addresses=tuple(DepositAddress.objects.order_by("derivation_index").values_list("address", flat=True)), + own_txids=frozenset(TransactionVersion.objects.values_list("txid", flat=True)), + deposit_confirmations=LotteryConfig.get().deposit_confirmations, + credited=frozenset(Utxo.objects.filter(deposit__status=Deposit.Status.CREDITED).values_list("txid", "vout")), + waiting=_waiting_by_address(), + ) + + +def _waiting_by_address() -> dict[str, frozenset[tuple[str, int]]]: + grouped: dict[str, set[tuple[str, int]]] = {} + rows = Utxo.objects.filter(deposit__status__in=[Deposit.Status.DETECTED, Deposit.Status.ORPHANED]) + for address, txid, vout in rows.values_list("address", "txid", "vout"): + grouped.setdefault(address, set()).add((txid, vout)) + return {address: frozenset(outpoints) for address, outpoints in grouped.items()} + + +def confirmations(tip: int, height: int) -> int: + return tip - height + 1 + + +def apply_observations(result: ScanResult, policy: Policy, now: datetime | None = None) -> dict[str, int]: + """Phase 3: write what was verified. Returns counters (`detected`, `credited`, `orphaned`, `reinstated`).""" + now = now or timezone.now() + done = {"detected": 0, "credited": 0, "orphaned": 0, "reinstated": 0} + if result.tip is None: + return done + for address, observation in result.addresses.items(): + if observation.entries is None: + continue + owner = DepositAddress.objects.filter(address=address).select_related("user").first() + if owner is None: + continue + listed = {(e.txid, e.vout): e for e in observation.entries} + for entry in observation.entries: + if entry.value < DUST_LIMIT_SATS or entry.height <= 0: + continue # DEP-21 + _apply_entry(owner, entry, result.tip, policy, observation, now, done) + # DEP-23: a waiting deposit that the servers agree is gone + for deposit in Deposit.objects.filter(utxo__address=address, status=Deposit.Status.DETECTED).select_related("utxo"): + outpoint = (deposit.utxo.txid, deposit.utxo.vout) + if outpoint not in listed and outpoint in observation.absent_confirmed: + _orphan(deposit, done) + return done + + +def _apply_entry(owner, entry: Seen, tip: int, policy: Policy, observation: Observation, now, done) -> None: + outpoint = (entry.txid, entry.vout) + have = confirmations(tip, entry.height) + need = threshold_for(entry.txid, policy, observation.coinbase) + ready = have >= need and outpoint in observation.verified + with transaction.atomic(): + utxo = Utxo.objects.filter(txid=entry.txid, vout=entry.vout).first() + deposit = Deposit.objects.select_for_update().filter(utxo=utxo).first() if utxo is not None else None + if deposit is None: + if utxo is not None: + return # an output that is not a deposit (e.g. one of our own): not this module's business + utxo = Utxo.objects.create(txid=entry.txid, vout=entry.vout, amount_sats=entry.value, address=owner.address, + user=owner.user, confirmed_height=entry.height, created_at=now) + movement = Movement.objects.create(user=owner.user, kind=Movement.Kind.DEPOSIT, status=Movement.Status.PENDING, + amount_sats=entry.value, created_at=now) + deposit = Deposit.objects.create(user=owner.user, utxo=utxo, movement=movement, detected_at=now) + done["detected"] += 1 + elif deposit.status == Deposit.Status.ORPHANED: + deposit.status = Deposit.Status.DETECTED + deposit.save(update_fields=["status"]) + Movement.objects.filter(pk=deposit.movement_id).update(status=Movement.Status.PENDING) + done["reinstated"] += 1 + if deposit.status == Deposit.Status.CREDITED: + return + if utxo.confirmed_height != entry.height: # the coin moved to another block: it counts from there + utxo.confirmed_height = entry.height + utxo.save(update_fields=["confirmed_height"]) + if not ready: + return + movement = deposit.movement + movement.status, movement.confirmed_at = Movement.Status.CONFIRMED, now + movement.save(update_fields=["status", "confirmed_at"]) + deposit.status, deposit.credited_at = Deposit.Status.CREDITED, now + deposit.save(update_fields=["status", "credited_at"]) + audit.record("deposit_credited", actor_label="worker", subject_type="deposit", subject_id=deposit.pk, + payload={"txid": entry.txid, "vout": entry.vout, "amount_sats": entry.value, + "height": entry.height, "confirmations": have, "threshold": need}) + done["credited"] += 1 + + +def _orphan(deposit: Deposit, done) -> None: + with transaction.atomic(): + fresh = Deposit.objects.select_for_update().get(pk=deposit.pk) + if fresh.status != Deposit.Status.DETECTED: + return # credited or orphaned meanwhile + fresh.status = Deposit.Status.ORPHANED + fresh.save(update_fields=["status"]) + Movement.objects.filter(pk=fresh.movement_id).update(status=Movement.Status.FAILED) + audit.record("deposit_orphaned", actor_label="worker", subject_type="deposit", subject_id=fresh.pk, + payload={"txid": fresh.utxo.txid, "vout": fresh.utxo.vout}) + done["orphaned"] += 1 + + +def scan_deposits(chain, now: datetime | None = None) -> dict[str, int]: + """One scan. `chain.observe(policy)` is a coroutine function (`ElectrumChain`) or any object whose `observe` + returns a `ScanResult` — the tests use the latter.""" + import asyncio + import inspect + + policy = plan() + if not policy.addresses: + return {"detected": 0, "credited": 0, "orphaned": 0, "reinstated": 0} + result = chain.observe(policy) + if inspect.isawaitable(result): + result = asyncio.run(result) + return apply_observations(result, policy, now) diff --git a/apps/lottery/electrum_chain.py b/apps/lottery/electrum_chain.py new file mode 100644 index 0000000..b564d32 --- /dev/null +++ b/apps/lottery/electrum_chain.py @@ -0,0 +1,224 @@ +"""The network phase of a deposit scan (roadmap B5, DEP-20, ELC-14, ELC-17, ELC-26, ELC-31). + +Nothing here touches the database. `observe` takes the `Policy` read in phase 1 and returns what the servers +say, already corroborated: the active server is the first one that answers *and* has the genesis of the network +profile; every other configured server is asked, over a fresh connection with its own time limit, whether it +agrees. Silence is never an answer (ELC-14): a server that does not respond does not count. +""" + +import asyncio +import hashlib +import logging +from collections.abc import Awaitable, Callable + +from embit.transaction import Transaction +from plm_engine.electrum.client import ElectrumClient, ElectrumEndpoint +from plm_engine.electrum.merkle import proof_matches_header +from plm_engine.electrum.scripthash import address_to_scripthash +from plm_engine.headers import header_meets_its_own_target +from plm_engine.network import Profile +from plm_engine.psbt_builder import DUST_LIMIT_SATS + +from .deposits import Observation, Policy, ScanResult, Seen, confirmations, threshold_for + +logger = logging.getLogger(__name__) + +CONNECT_TIMEOUT = 10.0 +ANSWER_TIMEOUT = 10.0 + + +def _seen(raw: dict) -> Seen | None: + try: + return Seen(txid=str(raw["tx_hash"]), vout=int(raw["tx_pos"]), value=int(raw["value"]), height=int(raw["height"])) + except (KeyError, TypeError, ValueError): + return None + + +class ElectrumChain: + def __init__( + self, + endpoints: list[ElectrumEndpoint], + profile: Profile, + allow_no_quorum: bool = False, + client_factory: Callable[[ElectrumEndpoint], ElectrumClient] | None = None, + ): + self.endpoints = endpoints + self.profile = profile + self.allow_no_quorum = allow_no_quorum + self._factory = client_factory or ( + lambda e: ElectrumClient(e.host, e.port, e.use_ssl, e.pin, genesis_hash=profile.genesis_hash) + ) + self.active_endpoint: ElectrumEndpoint | None = None + + # -- connections ------------------------------------------------------------------------------ + + async def _open(self, endpoint: ElectrumEndpoint) -> ElectrumClient | None: + client = self._factory(endpoint) + try: + await asyncio.wait_for(client.connect(), CONNECT_TIMEOUT) + except Exception as error: # unreachable, wrong chain, bad pin: all are "this server is not usable now" + logger.warning("electrum %s unusable: %s", endpoint, error) + return None + return client + + async def _connect_active(self) -> ElectrumClient | None: + for endpoint in self.endpoints: # rotation: the first usable one in configuration order + client = await self._open(endpoint) + if client is not None: + self.active_endpoint = endpoint + return client + return None + + async def _ask_others(self, ask: Callable[[ElectrumClient], Awaitable]) -> list: + """`ask` on every server but the active one, concurrently, each over a fresh connection. `None` = no answer.""" + + async def one(endpoint: ElectrumEndpoint): + client = await self._open(endpoint) + if client is None: + return None + try: + return await asyncio.wait_for(ask(client), ANSWER_TIMEOUT) + except Exception as error: + logger.warning("electrum %s did not answer: %s", endpoint, error) + return None + finally: + await client.close() + + others = [e for e in self.endpoints if e != self.active_endpoint] + return list(await asyncio.gather(*(one(e) for e in others))) + + def majority(self, answers: list) -> bool: + """ELC-14. Answers are True (agrees), False (disagrees) or None (silent). At least two answered and a strict + majority of those agrees; with the development exception, no other server at all passes and any strict majority + of even one answer does.""" + answered = [a for a in answers if a is not None] + if self.allow_no_quorum: + if not self.endpoints or len(self.endpoints) == 1: + return True + return bool(answered) and sum(bool(a) for a in answered) * 2 > len(answered) + return len(answered) >= 2 and sum(bool(a) for a in answered) * 2 > len(answered) + + # -- what is asked ------------------------------------------------------------------------------ + + async def _tip(self, active: ElectrumClient) -> tuple[int, str] | None: + """The active server's tip, accepted only with work valid for the profile and agreed by the others.""" + reply = await active.subscribe_headers() + try: + height, header = int(reply["height"]), str(reply["hex"]) + except (KeyError, TypeError, ValueError): + return None + if not header_meets_its_own_target(header, self.profile.pow_limit): + logger.warning("the tip header of %s has no valid work", self.active_endpoint) + return None + + async def same_header(client: ElectrumClient) -> bool: + return await client.get_block_header(height) == header + + if not self.majority(await self._ask_others(same_header)): + return None + return height, header + + async def _unspent(self, client: ElectrumClient, address: str) -> list[Seen] | None: + try: + raw = await asyncio.wait_for(client.listunspent(address_to_scripthash(address)), ANSWER_TIMEOUT) + except Exception as error: + logger.warning("listunspent for %s failed: %s", address, error) + return None + if not isinstance(raw, list): + return None + seen = [_seen(item) for item in raw if isinstance(item, dict)] + return None if any(item is None for item in seen) else seen + + async def is_coinbase(self, client: ElectrumClient, txid: str) -> bool | None: + """From the raw transaction, accepted only if its hash is the txid (DEP-21); None = could not tell.""" + try: + raw = await asyncio.wait_for(client.get_transaction(txid), ANSWER_TIMEOUT) + tx = Transaction.parse(bytes.fromhex(str(raw))) + if tx.txid().hex() != txid: + return None + except Exception as error: + logger.warning("cannot read transaction %s: %s", txid, error) + return None + return len(tx.vin) == 1 and tx.vin[0].txid == bytes(32) + + async def _credit_verified(self, active: ElectrumClient, address: str, entry: Seen, tip: int, need: int) -> bool: + """ELC-17 (the others list the coin, same value, deep enough) and ELC-26 (a merkle proof from the others + matches a header of the active server that has valid work).""" + scripthash = address_to_scripthash(address) + deepest = tip - need + 1 + + async def lists_it(client: ElectrumClient) -> bool: + for raw in await client.listunspent(scripthash): + other = _seen(raw) if isinstance(raw, dict) else None + if other and (other.txid, other.vout) == (entry.txid, entry.vout): + return other.value == entry.value and 0 < other.height <= deepest + return False + + if not self.majority(await self._ask_others(lists_it)): + return False + try: + header = await asyncio.wait_for(active.get_block_header(entry.height), ANSWER_TIMEOUT) + except Exception: + return False + if not header_meets_its_own_target(str(header), self.profile.pow_limit): + return False + + async def proves_it(client: ElectrumClient) -> bool: + return proof_matches_header(entry.txid, entry.height, await client.get_merkle(entry.txid, entry.height), str(header)) + + return self.majority(await self._ask_others(proves_it)) + + async def _absent_confirmed(self, address: str, outpoint: tuple[str, int]) -> bool: + scripthash = address_to_scripthash(address) + + async def lacks_it(client: ElectrumClient) -> bool: + listed = {(r.get("tx_hash"), r.get("tx_pos")) for r in await client.listunspent(scripthash) if isinstance(r, dict)} + return outpoint not in listed + + return self.majority(await self._ask_others(lacks_it)) + + # -- the scan ---------------------------------------------------------------------------------------- + + async def observe(self, policy: Policy) -> ScanResult: + active = await self._connect_active() + if active is None: + return ScanResult(None, {}) + try: + tip = await self._tip(active) + if tip is None: + return ScanResult(None, {}) + result = ScanResult(tip[0], {}) + for address in policy.addresses: + result.addresses[address] = await self._observe_address(active, address, tip[0], policy) + return result + except Exception: # a scan that fails writes nothing; the next one starts again + logger.exception("deposit scan failed") + return ScanResult(None, {}) + finally: + await active.close() + + async def _observe_address(self, active: ElectrumClient, address: str, tip: int, policy: Policy) -> Observation: + entries = await self._unspent(active, address) + observation = Observation(entries) + if entries is None: + return observation + listed = {(e.txid, e.vout) for e in entries} + for entry in entries: + outpoint = (entry.txid, entry.vout) + if entry.value < DUST_LIMIT_SATS or entry.height <= 0 or outpoint in policy.credited: + continue + have = confirmations(tip, entry.height) + if have >= policy.deposit_confirmations and entry.txid not in policy.own_txids: + coinbase = await self.is_coinbase(active, entry.txid) + if coinbase is None: + continue # unreadable: it cannot be credited as an ordinary deposit by mistake + if coinbase: + observation.coinbase.add(entry.txid) + need = threshold_for(entry.txid, policy, observation.coinbase) + if have >= need and await self._credit_verified(active, address, entry, tip, need): + observation.verified.add(outpoint) + for outpoint in policy.waiting.get(address, frozenset()) - listed: + if await self._absent_confirmed(address, outpoint): + observation.absent_confirmed.add(outpoint) + return observation + diff --git a/apps/lottery/management/commands/run_worker.py b/apps/lottery/management/commands/run_worker.py index 2af3f61..13c49a3 100644 --- a/apps/lottery/management/commands/run_worker.py +++ b/apps/lottery/management/commands/run_worker.py @@ -15,6 +15,29 @@ logger = logging.getLogger(__name__) TICK_SECONDS = 5 +_last_scan = 0.0 +SCAN_SECONDS = 10 + + +def scan_chain_deposits() -> None: + """DEP-20: every few seconds, on a real ledger only.""" + import time + + from django.conf import settings + + from apps.lottery import deposits + from apps.lottery.electrum_chain import ElectrumChain + + global _last_scan + if time.monotonic() - _last_scan < SCAN_SECONDS: + return + _last_scan = time.monotonic() + chain = ElectrumChain(settings.ELECTRUM_ENDPOINTS, settings.PLM_PROFILE, settings.ELECTRUM_ALLOW_NO_QUORUM) + done = deposits.scan_deposits(chain) + if any(done.values()): + logger.info("deposit scan: %s", done) + + def tick() -> None: """One pass over everything the worker is responsible for.""" from django.conf import settings @@ -24,6 +47,8 @@ def tick() -> None: console.beat() # WEB-31: proof of life, before the work that might fail if settings.LEDGER_BACKEND == "simulated": simulation.settle() + else: + scan_chain_deposits() # B5 lifecycle.tick() diff --git a/apps/lottery/migrations/0006_deposit_confirmations.py b/apps/lottery/migrations/0006_deposit_confirmations.py new file mode 100644 index 0000000..ec835ba --- /dev/null +++ b/apps/lottery/migrations/0006_deposit_confirmations.py @@ -0,0 +1,22 @@ +# Generated by Django 5.2.19 on 2026-11-16 14:58 + +from django.db import migrations, models + + +class Migration(migrations.Migration): + + dependencies = [ + ('lottery', '0005_transaction_versions_append_only'), + ] + + operations = [ + migrations.AddField( + model_name='lotteryconfig', + name='deposit_confirmations', + field=models.PositiveSmallIntegerField(default=6), + ), + migrations.AddConstraint( + model_name='lotteryconfig', + constraint=models.CheckConstraint(condition=models.Q(('deposit_confirmations__gte', 1), ('deposit_confirmations__lte', 100)), name='lottery_config_deposit_confirmations_range'), + ), + ] diff --git a/apps/lottery/models.py b/apps/lottery/models.py index 6059451..1f8b9c3 100644 --- a/apps/lottery/models.py +++ b/apps/lottery/models.py @@ -31,6 +31,9 @@ class LotteryConfig(models.Model): round_duration_seconds = models.PositiveIntegerField(default=600) round_cooldown_seconds = models.PositiveIntegerField(default=30) draw_confirmations = models.PositiveSmallIntegerField(default=3) + # DAT-62, DEP-21: confirmations a deposit needs before it is credited; read at every scan, so a change + # applies at once to the credits that follow. + deposit_confirmations = models.PositiveSmallIntegerField(default=6) max_round_pool_sats = models.BigIntegerField(default=0) # 0 = no cap # ADR-57: three distinct commands. @@ -60,6 +63,10 @@ class LotteryConfig(models.Model): condition=Q(draw_confirmations__gte=1, draw_confirmations__lte=20), name="lottery_config_draw_confirmations_range", ), + models.CheckConstraint( + condition=Q(deposit_confirmations__gte=1, deposit_confirmations__lte=100), + name="lottery_config_deposit_confirmations_range", + ), ] @classmethod diff --git a/config/settings.py b/config/settings.py index f25aaea..7c30d86 100644 --- a/config/settings.py +++ b/config/settings.py @@ -169,6 +169,28 @@ 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", "") + +# ELC-31: the Electrum servers of a real ledger, first = preferred. Rotation and quorum need at least three; +# ELECTRUM_ALLOW_NO_QUORUM relaxes that for development only, never on mainnet. +ELECTRUM_SERVERS = os.environ.get("ELECTRUM_SERVERS", "") +ELECTRUM_ALLOW_NO_QUORUM = os.environ.get("ELECTRUM_ALLOW_NO_QUORUM", "").lower() == "true" +if ELECTRUM_ALLOW_NO_QUORUM and PLM_NETWORK == "mainnet": + raise ImproperlyConfigured("ELECTRUM_ALLOW_NO_QUORUM is for development: it cannot be set on mainnet (ELC-31)") +if LEDGER_BACKEND == "chain": + from plm_engine.electrum.client import parse_server_list + + try: + ELECTRUM_ENDPOINTS = parse_server_list(ELECTRUM_SERVERS) + except ValueError as error: + raise ImproperlyConfigured(f"ELECTRUM_SERVERS: {error}") from error + if not ELECTRUM_ENDPOINTS: + raise ImproperlyConfigured("LEDGER_BACKEND=chain needs ELECTRUM_SERVERS (ELC-31)") + if len(ELECTRUM_ENDPOINTS) < 3 and not ELECTRUM_ALLOW_NO_QUORUM: + raise ImproperlyConfigured( + "ELECTRUM_SERVERS needs at least three servers for a quorum (ELC-31); ELECTRUM_ALLOW_NO_QUORUM=true is development only" + ) +else: + ELECTRUM_ENDPOINTS = [] PLM_MASTER_KEY_FILE = os.environ.get("PLM_MASTER_KEY_FILE", "") PLM_KEY_ENCRYPTION_KEY_FILE = os.environ.get("PLM_KEY_ENCRYPTION_KEY_FILE", "") diff --git a/docs/connessione-electrum.md b/docs/connessione-electrum.md index f155dbc..47d410e 100644 --- a/docs/connessione-electrum.md +++ b/docs/connessione-electrum.md @@ -356,3 +356,15 @@ B-83). corrente resta visibile anche nella barra di stato della catena di `/` (da `chain_tip_height` di `GET /rounds/current`). *Codice:* `app/electrum/listener.py:ElectrumListener.current_endpoint`, `app/main.py:health` · *Test:* `tests/unit/test_observability.py` + +## Server del sito Django (B5) + +- **[ELC-31]** **Elenco dei server.** `ELECTRUM_SERVERS` elenca i server separati da virgola, nel formato di [ELC-19] + (`host:porta[:notls][:pin=]`); il primo è il preferito, gli altri la rotazione e il quorum. Il giro dei depositi usa il + primo che risponde **e** ha il genesis del profilo di rete ([ELC-30]); gli altri sono interrogati per la corroborazione con + la regola di [ELC-14]. Con `LEDGER_BACKEND=chain` il sito rifiuta di partire senza server o con meno di tre, + salvo `ELECTRUM_ALLOW_NO_QUORUM=true`, che vale **solo fuori da `mainnet`** (regola ridotta di [ELC-14]). + *Stato:* implementato (B5) · *Codice:* `config/settings.py` (`ELECTRUM_SERVERS`), `plm_engine/electrum/client.py:parse_server_list`, + `apps/lottery/electrum_chain.py:ElectrumChain` · + *Test:* `tests/django/test_electrum_chain.py`, `tests/django/test_network_profile.py` + diff --git a/docs/legacy-fastapi-notes.md b/docs/legacy-fastapi-notes.md index b57dcbd..133db02 100644 --- a/docs/legacy-fastapi-notes.md +++ b/docs/legacy-fastapi-notes.md @@ -4,7 +4,7 @@ ## Project status (old stack) -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. +All 10 stages of the original build order are code-complete and unit-tested — 1263 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 1211 tests +python -m pytest # all 1263 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 ``` diff --git a/docs/modello-dati.md b/docs/modello-dati.md index e1389b2..7dcaad4 100644 --- a/docs/modello-dati.md +++ b/docs/modello-dati.md @@ -1500,7 +1500,7 @@ Le tabelle di catena (UTXO, versioni delle transazioni, depositi, indici HD) son si elimina. Ogni importo è un intero in unità minime ([DAT-01]) e ogni timestamp è in UTC con fuso ([DAT-02]). *Stato:* implementato (A2) · *Codice:* `apps/lottery/models.py` · *Test:* `tests/django/test_models.py::test_rows_that_carry_money_cannot_be_deleted_with_their_owner` - **[DAT-77]** **Parametri e pause: `LotteryConfig`.** Una sola riga (`id = 1`, vincolo) con quota (10 PLM), - durata (600 s), pausa fra round (30 s), conferme del blocco di estrazione (1–20, default 3), tetto del + durata (600 s), pausa fra round (30 s), conferme richieste a un deposito (1–100, default 6, [DAT-62]; si cambia da `/admin/` con audit e vale subito per gli accrediti successivi), conferme del blocco di estrazione (1–20, default 3), tetto del montepremi (0 = nessuno) e i tre interruttori di [ADR-57](adr/ADR-57-due-pause-distinte-dopo-round-e-incidente.md): `pause_after_round`, `new_bets_suspended`, `withdrawals_suspended`. Valori non positivi o fuori intervallo sono rifiutati dal database. I parametri si **copiano su `Round` all'apertura** ([DAT-61]); la copia la fa il diff --git a/docs/registrazione-e-depositi.md b/docs/registrazione-e-depositi.md index 2c5e991..a6bf978 100644 --- a/docs/registrazione-e-depositi.md +++ b/docs/registrazione-e-depositi.md @@ -393,3 +393,35 @@ corso (`has_pending`). la scommessa [scommesse-e-prelievi.md](scommesse-e-prelievi.md), B-96). *Codice:* `app/withdrawals/service.py:request_withdrawal`, `app/bets/service.py:place_bet` · *Test:* `tests/unit/test_withdrawals.py` + +## Depositi sul sito Django (B5) + +Il sito Django riscrive i depositi sull'ORM con lo stesso comportamento di [DEP-01]…[DEP-08] dove non diversamente detto. +Le parti dopo l'accredito (monete spese altrove, reintegro, riorganizzazioni oltre la soglia: [DEP-06]…[DEP-08]) sono B7. + +- **[DEP-20]** **Tre fasi, il database mai aperto durante la rete.** Un giro del worker (`scan_deposits`) **legge** dal database + indirizzi di deposito, monete note, txid della piattaforma e soglie; **interroga** i server Electrum senza alcuna + transazione aperta; **scrive** solo i casi verificati, ricontrollando lo stato di ogni moneta al salvataggio. Un + server che non risponde non produce scritture: l'indirizzo si riprova al giro dopo. Il giro gira solo con `LEDGER_BACKEND=chain`. + *Stato:* implementato (B5) · *Codice:* `apps/lottery/deposits.py:scan_deposits`, `apps/lottery/electrum_chain.py:ElectrumChain.observe` · + *Test:* `tests/django/test_deposits.py`, `tests/integration/test_deposits_regtest.py` +- **[DEP-21]** **Soglie.** Una moneta sotto `DUST_LIMIT_SATS` (294) o ancora in mempool (altezza 0) è ignorata. Le conferme sono + `punta − altezza + 1`. La soglia è **1** per una transazione della piattaforma (uno qualunque dei suoi txid, + [DAT-83]), **120** per una coinbase (stabilita dalla transazione grezza, accettata solo se il suo hash è il txid), + altrimenti **`deposit_confirmations`** di `LotteryConfig` ([DAT-77]), letta a ogni giro. + *Stato:* implementato (B5) · *Codice:* `apps/lottery/deposits.py:threshold_for`, `apps/lottery/electrum_chain.py:ElectrumChain.is_coinbase` · + *Test:* `tests/django/test_deposits.py::test_a_deposit_is_credited_exactly_at_its_threshold`, `test_the_threshold_is_the_configured_one`, `test_a_coinbase_needs_120`, `test_our_own_transactions_need_one`, `test_dust_and_mempool_coins_are_ignored` +- **[DEP-22]** **Accredito verificato e idempotente.** Una moneta sopra la soglia è accreditata solo se la corroborano gli altri + server ([ELC-14], [ELC-17]) **e** una prova merkle verificata contro un header che ha lavoro valido per il profilo di rete + la colloca nel blocco indicato ([ELC-26]). L'accredito è un solo `Movement` di tipo `deposit` che passa da `pending` a + `confirmed`, il `Deposit` passa a `credited` e l'audit scrive `deposit_credited`, nella stessa transazione. Una moneta già + accreditata non si accredita mai due volte (unicità dell'outpoint, [DAT-82]). Se la verifica non riesce, l'accredito è + rimandato al giro dopo, non perso. + *Stato:* implementato (B5) · *Codice:* `apps/lottery/deposits.py:apply_observations` · + *Test:* `tests/django/test_deposits.py::test_an_unverified_deposit_is_deferred_not_lost`, `test_scanning_twice_credits_once`, `test_the_credit_is_audited` +- **[DEP-23]** **Depositi in attesa e sparizione prima dell'accredito.** Una moneta confermata ma sotto soglia è un `Deposit` + `detected` con un `Movement` `pending` (il giocatore la vede «in conferma», [WEB-21]). Se sparisce dall'elenco, e gli + altri server confermano che non c'è più, il deposito diventa `orphaned` e il movimento `failed`; se ricompare torna `detected`. + *Stato:* implementato (B5) · *Codice:* `apps/lottery/deposits.py:apply_observations` · + *Test:* `tests/django/test_deposits.py::test_a_waiting_deposit_shows_as_incoming`, `test_a_vanished_waiting_deposit_is_orphaned_and_can_return` + diff --git a/plm_engine/electrum/client.py b/plm_engine/electrum/client.py index c5ea2ac..0f6b157 100644 --- a/plm_engine/electrum/client.py +++ b/plm_engine/electrum/client.py @@ -42,6 +42,54 @@ def normalize_pin(raw: str, entry: str) -> str: return pin +_SYNTAX = "expected host:port[:notls][:pin=]" + + +def parse_endpoint(entry: str) -> ElectrumEndpoint: + """One `host:port[:notls|ssl|tls][:pin=]`, or ValueError (see `parse_endpoints`).""" + entry = entry.strip() + parts = entry.split(":") + if not 2 <= len(parts) <= 4: + raise ValueError(f"invalid Electrum server {entry!r}: {_SYNTAX}") + host, port = parts[0].strip(), parts[1].strip() + if not host or not port.isdigit(): + raise ValueError(f"invalid Electrum server {entry!r}: {_SYNTAX}") + use_ssl = True + pin = None + mode_seen = False + for extra in parts[2:]: + extra = extra.strip() + if extra.lower().startswith("pin="): + if pin is not None: + raise ValueError(f"invalid Electrum server {entry!r}: more than one pin") + pin = normalize_pin(extra[4:], entry) + continue + flag = extra.lower() + if mode_seen or flag not in ("ssl", "tls", "notls", "plain"): + raise ValueError(f"invalid TLS flag {flag!r} in Electrum server {entry!r}") + mode_seen = True + use_ssl = flag in ("ssl", "tls") + if pin and not use_ssl: + raise ValueError(f"invalid Electrum server {entry!r}: a pin needs TLS") + return ElectrumEndpoint(host, int(port), use_ssl, pin) + + +def _dedupe(endpoints: list[ElectrumEndpoint]) -> list[ElectrumEndpoint]: + deduped: list[ElectrumEndpoint] = [] + seen: set[tuple] = set() + for endpoint in endpoints: + key = (endpoint.host, endpoint.port, endpoint.use_ssl) + if key not in seen: + seen.add(key) + deduped.append(endpoint) + return deduped + + +def parse_server_list(spec: str) -> list[ElectrumEndpoint]: + """A comma-separated list of servers, first = preferred; malformed entries raise (ELC-31).""" + return _dedupe([parse_endpoint(raw) for raw in spec.split(",") if raw.strip()]) + + def parse_endpoints( primary_host: str, primary_port: int, @@ -61,48 +109,12 @@ def parse_endpoints( startup, not to discover during an outage, when the fallback is what's needed. Duplicates are dropped, keeping first position. """ - syntax = "expected host:port[:notls][:pin=]" pin = normalize_pin(primary_pin, "ELECTRUM_CERT_PIN") if primary_pin.strip() else None if pin and not primary_use_ssl: raise ValueError("ELECTRUM_CERT_PIN needs TLS: ELECTRUM_USE_SSL is off") endpoints = [ElectrumEndpoint(primary_host, primary_port, primary_use_ssl, pin)] - for raw in fallback_spec.split(","): - entry = raw.strip() - if not entry: - continue - parts = entry.split(":") - if not 2 <= len(parts) <= 4: - raise ValueError(f"invalid Electrum server {entry!r}: {syntax}") - host, port = parts[0].strip(), parts[1].strip() - if not host or not port.isdigit(): - raise ValueError(f"invalid Electrum server {entry!r}: {syntax}") - use_ssl = True - pin = None - mode_seen = False - for extra in parts[2:]: - extra = extra.strip() - if extra.lower().startswith("pin="): - if pin is not None: - raise ValueError(f"invalid Electrum server {entry!r}: more than one pin") - pin = normalize_pin(extra[4:], entry) - continue - flag = extra.lower() - if mode_seen or flag not in ("ssl", "tls", "notls", "plain"): - raise ValueError(f"invalid TLS flag {flag!r} in Electrum server {entry!r}") - mode_seen = True - use_ssl = flag in ("ssl", "tls") - if pin and not use_ssl: - raise ValueError(f"invalid Electrum server {entry!r}: a pin needs TLS") - endpoints.append(ElectrumEndpoint(host, int(port), use_ssl, pin)) - - deduped: list[ElectrumEndpoint] = [] - seen: set[tuple] = set() - for endpoint in endpoints: - key = (endpoint.host, endpoint.port, endpoint.use_ssl) - if key not in seen: - seen.add(key) - deduped.append(endpoint) - return deduped + endpoints += [parse_endpoint(raw) for raw in fallback_spec.split(",") if raw.strip()] + return _dedupe(endpoints) diff --git a/roadmap.md b/roadmap.md index fd849b4..d48ea40 100644 --- a/roadmap.md +++ b/roadmap.md @@ -43,7 +43,7 @@ Uscita: flusso completo su regtest; un riavvio durante il broadcast, due richies - [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). - [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. +- [x] **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. - [ ] **B8 · Estrazione e pagamento reali.** Commit-reveal con blocco a quorum, verifica del montepremi, pagamento 70/30 con riserva per l'RBF, pausa automatica sui casi bloccanti. *Requisiti:* RND. *Test:* round completo su regtest, riorganizzazione simulata. diff --git a/tests/django/test_deposits.py b/tests/django/test_deposits.py new file mode 100644 index 0000000..6c22501 --- /dev/null +++ b/tests/django/test_deposits.py @@ -0,0 +1,259 @@ +"""B5 — real deposits on the ORM: DEP-20..DEP-23, DAT-62, DAT-77, DAT-82, DAT-84.""" + +import pytest +from django.contrib.auth import get_user_model +from django.db import IntegrityError, transaction + +from apps.lottery import chain, deposits, keys +from apps.lottery.balances import balance_of +from apps.lottery.deposits import Observation, ScanResult, Seen +from apps.lottery.models import AuditEntry, Deposit, LotteryConfig, Movement, TransactionVersion, Utxo, ChainTransaction + +pytestmark = pytest.mark.django_db +User = get_user_model() +PLM = 100_000_000 +TXID = "ab" * 32 +OTHER = "cd" * 32 + + +class FakeChain: + """The network phase, scripted: a tip, what each address lists, and which coins the 'servers' corroborate.""" + + def __init__(self, tip=1000): + self.tip, self.entries, self.verified, self.coinbase, self.absent, self.silent = tip, {}, set(), set(), set(), set() + self.policies = [] + + def observe(self, policy): + self.policies.append(policy) + result = ScanResult(self.tip, {}) + for address in policy.addresses: + if address in self.silent: + result.addresses[address] = Observation(None) + continue + entries = self.entries.get(address, []) + result.addresses[address] = Observation( + entries, {o for o in self.verified}, {o for o in self.absent}, set(self.coinbase)) + return result + + +@pytest.fixture +def player(settings, tmp_path): + settings.PLM_ACCOUNT_XPUB = keys.generate_keys(tmp_path / "keys", settings.PLM_PROFILE) + user = User.objects.create_user("mario", password="x" * 12) + return user, chain.assign_deposit_address(user).address + + +def coin(txid=TXID, vout=0, value=5 * PLM, height=995): + return Seen(txid, vout, value, height) + + +def scan(fake): + return deposits.scan_deposits(fake) + + +# --- DEP-21: thresholds ------------------------------------------------------------------------------ + + +def test_a_deposit_is_credited_exactly_at_its_threshold(player): + user, address = player + fake = FakeChain() + fake.entries[address] = [coin(height=1000 - 5 + 1)] # 5 confirmations, the threshold is 6 + fake.verified = {(TXID, 0)} + assert scan(fake) == {"detected": 1, "credited": 0, "orphaned": 0, "reinstated": 0} + assert balance_of(user).spendable_sats == 0 + fake.tip = 1001 # 6 confirmations + assert scan(fake)["credited"] == 1 + assert balance_of(user).spendable_sats == 5 * PLM + + +def test_the_threshold_is_the_configured_one(player): + """DAT-77: the operator changes it and the next scan uses it.""" + user, address = player + config = LotteryConfig.get() + config.deposit_confirmations = 2 + config.save() + fake = FakeChain() + fake.entries[address] = [coin(height=999)] # 2 confirmations + fake.verified = {(TXID, 0)} + assert scan(fake)["credited"] == 1 + + +def test_a_coinbase_needs_120(player): + user, address = player + fake = FakeChain(tip=2000) + fake.coinbase = {TXID} + fake.verified = {(TXID, 0)} + fake.entries[address] = [coin(height=2000 - 118)] # 119 confirmations + assert scan(fake)["credited"] == 0 + fake.tip = 2001 # 120 + assert scan(fake)["credited"] == 1 + + +def test_our_own_transactions_need_one(player): + user, address = player + tx = ChainTransaction.objects.create(kind="withdrawal", user=user) + chain.register_version(tx, TXID, "00") + fake = FakeChain() + fake.entries[address] = [coin(height=1000)] # one confirmation + fake.verified = {(TXID, 0)} + assert scan(fake)["credited"] == 1 + + +def test_dust_and_mempool_coins_are_ignored(player): + user, address = player + fake = FakeChain() + fake.entries[address] = [coin(vout=0, value=293), coin(vout=1, height=0), coin(vout=2, height=-1)] + assert scan(fake) == {"detected": 0, "credited": 0, "orphaned": 0, "reinstated": 0} + assert not Utxo.objects.exists() and not Movement.objects.exists() + + +# --- DEP-22: verified, idempotent ------------------------------------------------------------------------ + + +def test_an_unverified_deposit_is_deferred_not_lost(player): + user, address = player + fake = FakeChain() + fake.entries[address] = [coin(height=900)] # deep enough, but nobody corroborated it + scan(fake) + assert balance_of(user).spendable_sats == 0 and Deposit.objects.get().status == "detected" + fake.verified = {(TXID, 0)} + assert scan(fake)["credited"] == 1 + + +def test_scanning_twice_credits_once(player): + user, address = player + fake = FakeChain() + fake.entries[address] = [coin(height=900)] + fake.verified = {(TXID, 0)} + assert scan(fake)["credited"] == 1 + assert scan(fake) == {"detected": 0, "credited": 0, "orphaned": 0, "reinstated": 0} + assert Movement.objects.filter(kind="deposit").count() == 1 and balance_of(user).spendable_sats == 5 * PLM + + +def test_the_credit_is_audited(player): + user, address = player + fake = FakeChain() + fake.entries[address] = [coin(height=900)] + fake.verified = {(TXID, 0)} + scan(fake) + entry = AuditEntry.objects.get(action="deposit_credited") + assert entry.actor_label == "worker" and entry.payload["amount_sats"] == 5 * PLM and entry.payload["threshold"] == 6 + + +def test_the_database_refuses_a_second_deposit_for_the_same_output(player): + user, address = player + fake = FakeChain() + fake.entries[address] = [coin(height=900)] + scan(fake) + with pytest.raises(IntegrityError), transaction.atomic(): + Utxo.objects.create(txid=TXID, vout=0, amount_sats=1, address=address) + + +def test_silence_concludes_nothing(player): + user, address = player + fake = FakeChain() + fake.entries[address] = [coin(height=900)] + fake.silent = {address} + assert scan(fake) == {"detected": 0, "credited": 0, "orphaned": 0, "reinstated": 0} + result = ScanResult(None, {address: Observation([coin(height=900)])}) # no usable tip: nothing is written either + assert deposits.apply_observations(result, deposits.plan())["detected"] == 0 + + +# --- DEP-23: waiting deposits ------------------------------------------------------------------------------ + + +def test_a_waiting_deposit_shows_as_incoming(player): + user, address = player + fake = FakeChain() + fake.entries[address] = [coin(height=999)] + scan(fake) + balance = balance_of(user) + assert (balance.spendable_sats, balance.incoming_sats) == (0, 5 * PLM) + + +def test_a_vanished_waiting_deposit_is_orphaned_and_can_return(player): + user, address = player + fake = FakeChain() + fake.entries[address] = [coin(height=999)] + scan(fake) + fake.entries[address] = [] + scan(fake) # gone, but the others did not confirm that: nothing changes + assert Deposit.objects.get().status == "detected" + fake.absent = {(TXID, 0)} + assert scan(fake)["orphaned"] == 1 + assert Deposit.objects.get().status == "orphaned" and balance_of(user).incoming_sats == 0 + fake.entries[address], fake.absent = [coin(height=999)], set() + assert scan(fake)["reinstated"] == 1 + assert balance_of(user).incoming_sats == 5 * PLM + + +def test_a_credited_deposit_is_left_alone_by_this_module(player): + """What happens to a credited coin that later disappears is B7.""" + user, address = player + fake = FakeChain() + fake.entries[address] = [coin(height=900)] + fake.verified = {(TXID, 0)} + scan(fake) + fake.entries[address], fake.absent = [], {(TXID, 0)} + assert scan(fake)["orphaned"] == 0 and Deposit.objects.get().status == "credited" + + +def test_the_policy_names_what_the_network_phase_needs(player): + user, address = player + fake = FakeChain() + fake.entries[address] = [coin(height=999)] + scan(fake) + scan(fake) # the second scan reads what the first one wrote + policy = fake.policies[-1] + assert policy.addresses == (address,) and policy.deposit_confirmations == 6 + assert policy.waiting == {address: frozenset({(TXID, 0)})} + + +# --- configuration (DAT-77, ELC-31) ---------------------------------------------------------------------- + + +def test_the_operator_changes_the_threshold_from_the_admin_and_it_is_audited(client): + admin = User.objects.create_superuser("boss", password="x" * 12) + client.force_login(admin) + config = LotteryConfig.get() + data = {f: getattr(config, f) for f in ("fee_address", "bet_amount_sats", "round_duration_seconds", "round_cooldown_seconds", + "draw_confirmations", "deposit_confirmations", "max_round_pool_sats")} + data["deposit_confirmations"] = 3 + assert client.post("/admin/lottery/lotteryconfig/1/change/", data).status_code == 302 + assert LotteryConfig.get().deposit_confirmations == 3 + entry = AuditEntry.objects.get(action="config_changed") + assert entry.actor == admin and entry.payload == {"changed": {"deposit_confirmations": [6, 3]}} + + +@pytest.mark.parametrize("value", [0, 101]) +def test_the_database_refuses_a_threshold_out_of_range(value): + config = LotteryConfig.get() + config.deposit_confirmations = value + with pytest.raises(IntegrityError), transaction.atomic(): + config.save() + + +def _settings_import(**env): + import os + import subprocess + import sys + from pathlib import Path + + clean = {"PATH": os.environ["PATH"], "PYTHONPATH": str(Path(__file__).resolve().parents[2]), + "DJANGO_SECRET_KEY": "k" * 60, "LEDGER_BACKEND": "chain", **env} + return subprocess.run([sys.executable, "-c", "import config.settings as s; print(len(s.ELECTRUM_ENDPOINTS))"], + cwd=Path(__file__).resolve().parents[2], env=clean, capture_output=True, text=True) + + +def test_a_real_ledger_needs_servers_and_a_quorum(): + assert "ELECTRUM_SERVERS" in _settings_import().stderr + assert "three servers" in _settings_import(ELECTRUM_SERVERS="a:1,b:1").stderr + assert _settings_import(ELECTRUM_SERVERS="a:1,b:1,c:1").stdout.strip() == "3" + assert _settings_import(ELECTRUM_SERVERS="a:1", ELECTRUM_ALLOW_NO_QUORUM="true").stdout.strip() == "1" + assert _settings_import(ELECTRUM_SERVERS="bad").returncode != 0 + + +def test_no_quorum_is_refused_on_mainnet(): + result = _settings_import(PLM_NETWORK="mainnet", PLM_MAINNET_CONFIRMED="yes", ELECTRUM_SERVERS="a:1", + ELECTRUM_ALLOW_NO_QUORUM="true") + assert result.returncode != 0 and "mainnet" in result.stderr diff --git a/tests/django/test_electrum_chain.py b/tests/django/test_electrum_chain.py new file mode 100644 index 0000000..153280e --- /dev/null +++ b/tests/django/test_electrum_chain.py @@ -0,0 +1,261 @@ +"""B5 — the network phase with scripted servers: rotation, genesis, quorum, corroboration, merkle proof, coinbase +(ELC-14, ELC-17, ELC-26, ELC-30, ELC-31, DEP-21, DEP-22).""" + +import hashlib +import struct + +import pytest +from embit.transaction import Transaction +from plm_engine.electrum.client import ElectrumEndpoint, ElectrumError, parse_server_list +from plm_engine.electrum.scripthash import address_to_scripthash +from plm_engine.headers import header_meets_its_own_target +from plm_engine.network import MAINNET, REGTEST + +from apps.lottery.deposits import Policy +from apps.lottery.electrum_chain import ElectrumChain + +ADDRESS = "rplm1qz3r3xc0dxx470c9dhv78dmvlr0cd34vw3vvmsx" +SCRIPTHASH = address_to_scripthash(ADDRESS) +POW = REGTEST.pow_limit + + +def raw_tx(prevout: bytes) -> str: + """A one-input one-output transaction: `prevout` all zero makes it a coinbase.""" + return ("01000000" + "01" + prevout.hex() + "ffffffff" + "00" + "ffffffff" + "01" + "00ca9a3b00000000" + "00" + "00000000") + + +ORDINARY_RAW = raw_tx(bytes.fromhex("11" * 32)) +COINBASE_RAW = raw_tx(bytes(32)) +ORDINARY_TXID = Transaction.parse(bytes.fromhex(ORDINARY_RAW)).txid().hex() +COINBASE_TXID = Transaction.parse(bytes.fromhex(COINBASE_RAW)).txid().hex() +OUTPOINT = (ORDINARY_TXID, 0) + + +def mined_header(merkle_root_internal: bytes = bytes(32), nonce_from: int = 0) -> str: + for nonce in range(nonce_from, nonce_from + 10_000): + header = (struct.pack("