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:
davideandClaude Sonnet 5.5 committed 2026-11-16 16:09:36 +01:00
1 parent f1d09075a1
commit 2acd4ccd1c
21 files changed
+1223 -49

No files matched your search

+185
View File
@@ -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)