"""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__) WAITING = ("detected", "orphaned") # deposit statuses that are still being watched 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.exclude(deposit__status__in=WAITING).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=WAITING) 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) if entry.txid in policy.own_txids: # The change of one of our own transactions is spendable money, not a deposit: it was already taken # from the player's balance when the transaction was placed (BET-30), so no movement is written. with transaction.atomic(): Utxo.objects.get_or_create(txid=entry.txid, vout=entry.vout, defaults=dict( amount_sats=entry.value, address=owner.address, user=owner.user, confirmed_height=entry.height, created_at=now)) return 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)