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

+5
View File
@@ -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=<sha256>],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=
+1 -1
View File
@@ -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.
+1 -1
View File
@@ -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
+24 -1
View File
@@ -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})
+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)
+224
View File
@@ -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
@@ -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()
@@ -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'),
),
]
+7
View File
@@ -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
+22
View File
@@ -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", "")
+12
View File
@@ -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=<sha256>]`); 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`
+2 -2
View File
@@ -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
```
+1 -1
View File
@@ -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
+32
View File
@@ -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`
+50 -38
View File
@@ -42,6 +42,54 @@ def normalize_pin(raw: str, entry: str) -> str:
return pin
_SYNTAX = "expected host:port[:notls][:pin=<sha256>]"
def parse_endpoint(entry: str) -> ElectrumEndpoint:
"""One `host:port[:notls|ssl|tls][:pin=<sha256>]`, 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=<sha256>]"
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)
+1 -1
View File
@@ -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.
+259
View File
@@ -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
+261
View File
@@ -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("<I", 1) + bytes(32) + merkle_root_internal + struct.pack("<II", 0, 0x207FFFFF) + struct.pack("<I", nonce)).hex()
if header_meets_its_own_target(header, POW):
return header
raise AssertionError("no header mined")
TX_ROOT = bytes.fromhex(OUTPOINT[0])[::-1] # a block with that one transaction: the root is the txid
HEADER = mined_header(TX_ROOT)
COINBASE_HEADER = mined_header(bytes.fromhex(COINBASE_TXID)[::-1])
class FakeServer:
"""What one server says. Fields are set per test."""
def __init__(self, name, *, up=True, genesis=REGTEST.genesis_hash, height=1000, header=HEADER,
coins=None, proof="valid", silent_on=()):
self.name, self.up, self.genesis, self.height, self.header = name, up, genesis, height, header
self.coins = [{"tx_hash": OUTPOINT[0], "tx_pos": 0, "value": 500_000_000, "height": 990}] if coins is None else coins
self.proof, self.silent_on, self.raw_tx = proof, set(silent_on), ORDINARY_RAW
class FakeClient:
def __init__(self, server):
self.s = server
self.closed = False
async def connect(self):
if not self.s.up:
raise OSError("down")
if self.s.genesis != REGTEST.genesis_hash:
raise ElectrumError("not on the PLM chain")
async def close(self):
self.closed = True
async def subscribe_headers(self):
return {"height": self.s.height, "hex": self.s.header}
async def get_block_header(self, height):
if "header" in self.s.silent_on:
raise OSError("timeout")
return self.s.header
async def listunspent(self, scripthash):
if "listunspent" in self.s.silent_on:
raise OSError("timeout")
assert scripthash == SCRIPTHASH
return self.s.coins
async def get_merkle(self, txid, height):
if "merkle" in self.s.silent_on:
raise OSError("timeout")
if self.s.proof == "valid":
return {"block_height": height, "merkle": [], "pos": 0}
return {"block_height": height, "merkle": ["00" * 32], "pos": 0}
async def get_transaction(self, txid, verbose=False):
return COINBASE_RAW if txid == COINBASE_TXID else self.s.raw_tx
def chain_of(servers, allow_no_quorum=False):
by_endpoint = {ElectrumEndpoint(s.name, 1, False): s for s in servers}
return ElectrumChain(list(by_endpoint), REGTEST, allow_no_quorum, lambda e: FakeClient(by_endpoint[e]))
def policy(deposit_confirmations=6, own=frozenset(), credited=frozenset(), waiting=None):
return Policy((ADDRESS,), own, deposit_confirmations, credited, waiting or {})
async def observe(servers, allow_no_quorum=False, **kw):
return await chain_of(servers, allow_no_quorum).observe(policy(**kw))
def three(**overrides):
return [FakeServer(name, **overrides.get(name, {})) for name in "abc"]
def four(**overrides):
return [FakeServer(name, **overrides.get(name, {})) for name in "abcd"]
# --- servers --------------------------------------------------------------------------------------------
def test_the_server_list_is_parsed_in_order():
endpoints = parse_server_list("a.example:50002, b.example:50001:notls ,a.example:50002")
assert [(e.host, e.port, e.use_ssl) for e in endpoints] == [("a.example", 50002, True), ("b.example", 50001, False)]
with pytest.raises(ValueError):
parse_server_list("no-port")
async def test_the_first_usable_server_is_active_and_a_dead_one_is_skipped():
result = await observe(four(a={"up": False})) # b is active; c and d answer: a quorum of two
assert result.tip == 1000 and result.addresses[ADDRESS].entries[0].value == 500_000_000
async def test_a_server_on_another_chain_is_never_used():
result = await observe(three(a={"genesis": MAINNET.genesis_hash}, b={"genesis": MAINNET.genesis_hash}))
# only c is usable, and it cannot be corroborated by anyone: no tip, nothing concluded
assert result.tip is None and result.addresses == {}
async def test_with_no_server_at_all_nothing_is_concluded():
result = await observe(three(a={"up": False}, b={"up": False}, c={"up": False}))
assert result.tip is None
# --- quorum (ELC-14) ---------------------------------------------------------------------------------------
@pytest.mark.parametrize("answers,expected", [
([True, True], True), ([True, False], False), ([True, None], False), ([None, None], False),
([True, True, False], True), ([True, False, False], False), ([], False), ([True], False),
])
def test_the_quorum_needs_two_answers_and_a_strict_majority(answers, expected):
assert chain_of(three()).majority(answers) is expected
@pytest.mark.parametrize("answers,expected", [([True], True), ([False], False), ([None], False), ([True, False], False)])
def test_the_development_exception_accepts_one_agreeing_answer(answers, expected):
assert chain_of(three(), allow_no_quorum=True).majority(answers) is expected
def test_the_development_exception_with_a_single_server_passes():
assert chain_of([FakeServer("only")], allow_no_quorum=True).majority([]) is True
assert chain_of([FakeServer("only")], allow_no_quorum=False).majority([]) is False
# --- tip -----------------------------------------------------------------------------------------------------
async def test_a_tip_without_valid_work_is_refused():
fake_header = struct.pack("<I", 1).hex() + "00" * 72 # bits 0: no target
result = await observe(three(a={"header": fake_header}, b={"header": fake_header}, c={"header": fake_header}))
assert result.tip is None
async def test_a_tip_the_others_do_not_confirm_is_refused():
other = mined_header(bytes(32), 50_000)
assert other != HEADER
result = await observe(three(b={"header": other}, c={"header": other}))
assert result.tip is None
# --- credit (ELC-17, ELC-26) ----------------------------------------------------------------------------------
async def test_a_deep_enough_coin_corroborated_with_a_proof_is_verified():
observation = (await observe(three())).addresses[ADDRESS]
assert OUTPOINT in observation.verified
async def test_a_coin_that_is_too_shallow_is_not_verified():
result = await observe(three(), deposit_confirmations=20) # 11 confirmations
assert OUTPOINT not in result.addresses[ADDRESS].verified
async def test_a_coin_the_others_do_not_list_is_not_verified():
result = await observe(three(b={"coins": []}, c={"coins": []}))
assert OUTPOINT not in result.addresses[ADDRESS].verified
async def test_a_coin_with_another_value_at_the_others_is_not_verified():
cheat = [{"tx_hash": OUTPOINT[0], "tx_pos": 0, "value": 1, "height": 990}]
result = await observe(three(b={"coins": cheat}, c={"coins": cheat}))
assert OUTPOINT not in result.addresses[ADDRESS].verified
async def test_a_wrong_merkle_proof_is_not_accepted():
result = await observe(three(b={"proof": "wrong"}, c={"proof": "wrong"}))
assert OUTPOINT not in result.addresses[ADDRESS].verified
async def test_one_silent_server_out_of_four_still_leaves_a_quorum():
result = await observe(four(d={"up": False}))
assert OUTPOINT in result.addresses[ADDRESS].verified
async def test_with_only_one_other_server_answering_nothing_is_concluded():
"""Three configured, one down: the active server plus one answer is not a quorum (ELC-14)."""
result = await observe(three(c={"up": False}))
assert result.tip is None and result.addresses == {}
async def test_silence_on_a_corroboration_does_not_count_as_agreement():
result = await observe(four(c={"silent_on": ["merkle"]}, d={"silent_on": ["merkle"]}))
assert OUTPOINT not in result.addresses[ADDRESS].verified
# --- coinbase (DEP-21) ---------------------------------------------------------------------------------------
async def test_a_coinbase_is_recognised_and_needs_120():
coin = [{"tx_hash": COINBASE_TXID, "tx_pos": 0, "value": 500_000_000, "height": 990}]
result = await observe(three(a={"coins": coin, "header": COINBASE_HEADER}, b={"coins": coin, "header": COINBASE_HEADER},
c={"coins": coin, "header": COINBASE_HEADER}))
observation = result.addresses[ADDRESS]
assert COINBASE_TXID in observation.coinbase and (COINBASE_TXID, 0) not in observation.verified # 11 < 120
async def test_an_unreadable_transaction_is_not_credited_as_an_ordinary_deposit():
servers = three()
for server in servers:
server.raw_tx = "zz"
result = await observe(servers)
assert OUTPOINT not in result.addresses[ADDRESS].verified
async def test_our_own_transaction_is_not_checked_for_coinbase():
own = frozenset({OUTPOINT[0]})
servers = three()
for server in servers:
server.raw_tx = "zz" # would block an ordinary deposit; irrelevant for our own
result = await chain_of(servers).observe(policy(own=own))
assert OUTPOINT in result.addresses[ADDRESS].verified
# --- vanished waiting deposits ----------------------------------------------------------------------------------
async def test_a_vanished_waiting_deposit_needs_the_others_to_agree():
result = await observe(three(a={"coins": []}), waiting={ADDRESS: frozenset({OUTPOINT})})
# a (active) lists nothing, b and c still list it: not confirmed absent
assert OUTPOINT not in result.addresses[ADDRESS].absent_confirmed
result = await observe(three(a={"coins": []}, b={"coins": []}, c={"coins": []}), waiting={ADDRESS: frozenset({OUTPOINT})})
assert OUTPOINT in result.addresses[ADDRESS].absent_confirmed
+2 -1
View File
@@ -407,7 +407,8 @@ def test_the_simulated_ledger_cannot_run_on_mainnet():
"""ADR-59; a real ledger on mainnet also needs the explicit confirmation (ADR-58, B2)."""
result = _run_settings(PLM_NETWORK="mainnet", PLM_MAINNET_CONFIRMED="yes")
assert result.returncode != 0 and "simulated ledger" in result.stderr
assert _run_settings(PLM_NETWORK="mainnet", LEDGER_BACKEND="chain", PLM_MAINNET_CONFIRMED="yes").returncode == 0
assert _run_settings(PLM_NETWORK="mainnet", LEDGER_BACKEND="chain", PLM_MAINNET_CONFIRMED="yes",
ELECTRUM_SERVERS="a:1,b:1,c:1").returncode == 0
assert _run_settings().returncode == 0 # the default: regtest + simulated
+3 -3
View File
@@ -112,11 +112,11 @@ def test_regtest_is_the_default_and_the_profile_is_exposed():
def test_mainnet_needs_an_explicit_confirmation():
refused = settings_import(PLM_NETWORK="mainnet", LEDGER_BACKEND="chain")
refused = settings_import(PLM_NETWORK="mainnet", LEDGER_BACKEND="chain", ELECTRUM_SERVERS="a:1,b:1,c:1")
assert refused.returncode != 0 and "PLM_MAINNET_CONFIRMED" in refused.stderr
wrong = settings_import(PLM_NETWORK="mainnet", LEDGER_BACKEND="chain", PLM_MAINNET_CONFIRMED="true")
wrong = settings_import(PLM_NETWORK="mainnet", LEDGER_BACKEND="chain", ELECTRUM_SERVERS="a:1,b:1,c:1", PLM_MAINNET_CONFIRMED="true")
assert wrong.returncode != 0
confirmed = settings_import(PLM_NETWORK="mainnet", LEDGER_BACKEND="chain", PLM_MAINNET_CONFIRMED="yes")
confirmed = settings_import(PLM_NETWORK="mainnet", LEDGER_BACKEND="chain", ELECTRUM_SERVERS="a:1,b:1,c:1", PLM_MAINNET_CONFIRMED="yes")
assert confirmed.returncode == 0 and confirmed.stdout.strip() == "mainnet"
@@ -0,0 +1,84 @@
"""B5 — a real deposit on the local regtest, end to end: fund an address derived from our public key, watch it wait,
and see it credited at the configured threshold (DEP-20..DEP-23, ELC-31)."""
import pytest
from django.contrib.auth import get_user_model
from apps.lottery import chain, deposits, keys
from apps.lottery.balances import balance_of
from apps.lottery.electrum_chain import ElectrumChain
from apps.lottery.models import Deposit, LotteryConfig
from plm_engine.electrum.client import ElectrumEndpoint
from plm_engine.network import REGTEST
pytestmark = pytest.mark.django_db
PLM = 100_000_000
@pytest.fixture
def deposit_address(settings, tmp_path):
settings.PLM_ACCOUNT_XPUB = keys.generate_keys(tmp_path / "keys", settings.PLM_PROFILE)
user = get_user_model().objects.create_user("giocatore", password="x" * 12)
return user, chain.assign_deposit_address(user).address
def scan(electrum_endpoint):
host, port = electrum_endpoint
# one Fulcrum: the development exception of ELC-14 applies, as ELECTRUM_ALLOW_NO_QUORUM would say
return deposits.scan_deposits(ElectrumChain([ElectrumEndpoint(host, port, False)], REGTEST, allow_no_quorum=True))
def wait_for_fulcrum(regtest_node, electrum_endpoint):
"""Fulcrum indexes a moment after the node: scan until it has seen the tip."""
import time
for _ in range(60):
scan(electrum_endpoint)
if Deposit.objects.exists():
return
time.sleep(0.25)
def test_a_deposit_waits_and_is_credited_at_the_configured_threshold(regtest_node, electrum_endpoint, deposit_address):
user, address = deposit_address
regtest_node.fund(address, 2.5) # mined once: one confirmation
wait_for_fulcrum(regtest_node, electrum_endpoint)
waiting = balance_of(user)
assert (waiting.spendable_sats, waiting.incoming_sats) == (0, 250_000_000)
for _ in range(4): # 2 .. 5 confirmations: still waiting
regtest_node.mine(1)
import time
time.sleep(0.5)
scan(electrum_endpoint)
assert balance_of(user).spendable_sats == 0
regtest_node.mine(1) # the sixth
for _ in range(60):
scan(electrum_endpoint)
if balance_of(user).spendable_sats:
break
import time
time.sleep(0.25)
assert balance_of(user).spendable_sats == 250_000_000
assert Deposit.objects.get().status == "credited"
assert scan(electrum_endpoint) == {"detected": 0, "credited": 0, "orphaned": 0, "reinstated": 0} # once
def test_the_operator_can_lower_the_threshold(regtest_node, electrum_endpoint, deposit_address):
user, address = deposit_address
config = LotteryConfig.get()
config.deposit_confirmations = 2
config.save()
regtest_node.fund(address, 1.0)
regtest_node.mine(1) # two confirmations
import time
for _ in range(60):
scan(electrum_endpoint)
if balance_of(user).spendable_sats:
break
time.sleep(0.25)
assert balance_of(user).spendable_sats == PLM