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 <noreply@anthropic.com>
This commit is contained in:
1 parent
f1d09075a1
commit
2acd4ccd1c
21 files changed
+1223
-49
No files matched your search
@@ -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)
|
||||
Reference in new issue
Block a user