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

+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"