185 lines
8.4 KiB
Python
185 lines
8.4 KiB
Python
"""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)
|