Files
plm-lottery/tests/django/test_ledger.py
T
davideandClaude Sonnet 5.5 eded058dbb A3: simulated ledger with idempotency (WEB-22, WEB-23, ADR-59, ARC-75..77, DAT-80)
One Ledger interface (deposit, bet, confirm, reject, exclude, payout) with a
simulated implementation chosen by LEDGER_BACKEND, refused on mainnet. Every
operation is a single write-locked transaction with its audit row; the same
request key is the same operation, a key reused for something else is an
error. The server validates round, deadline, the round's own quota, limits and
funds. The balance is derived from the ledger. Tests include six processes
racing on one SQLite file; the idempotency tests were checked to fail when
the replay is removed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-16 13:23:29 +01:00

487 lines
20 KiB
Python

"""A3 — simulated ledger with idempotency: WEB-22, WEB-23, ADR-59, ARC-72, DAT-78, RND-21, BET-07, BET-20."""
import json
import os
import subprocess
import sys
from datetime import timedelta
from pathlib import Path
from uuid import uuid4
import pytest
from django.contrib.auth import get_user_model
from django.utils import timezone
from apps.lottery import ledger as ledger_module
from apps.lottery.balances import balance_of
from apps.lottery.errors import LedgerError
from apps.lottery.ledger import SimulatedLedger, get_ledger
from apps.lottery.models import (
AuditEntry,
ChainTransaction,
LotteryConfig,
Movement,
Participation,
Round,
)
from apps.lottery.rules import winner_share
ROOT = Path(__file__).resolve().parents[2]
PLM = 100_000_000
BET = 10 * PLM
pytestmark = pytest.mark.django_db
ledger = SimulatedLedger()
def make_user(name="mario"):
return get_user_model().objects.create_user(name, password="x" * 12)
def open_round(**kwargs):
return Round.objects.create(**kwargs)
def funded(name="mario", amount=BET):
user = make_user(name)
ledger.deposit(user, amount)
return user
def code_of(call) -> str:
with pytest.raises(LedgerError) as caught:
call()
return caught.value.code
def audit_actions():
return list(AuditEntry.objects.order_by("id").values_list("action", flat=True))
# --- deposits ----------------------------------------------------------------------------------
def test_a_confirmed_deposit_is_spendable():
user = make_user()
result = ledger.deposit(user, 25 * PLM)
assert not result.replayed
assert balance_of(user).spendable_sats == 25 * PLM and balance_of(user).incoming_sats == 0
assert audit_actions() == ["deposit_credited"]
def test_a_pending_deposit_is_incoming_not_spendable():
"""WEB-21: funds in confirmation are shown apart and cannot be spent."""
user = make_user()
movement = ledger.deposit(user, BET, confirmed=False).obj
assert (balance_of(user).spendable_sats, balance_of(user).incoming_sats) == (0, BET)
ledger.confirm_deposit(movement)
assert (balance_of(user).spendable_sats, balance_of(user).incoming_sats) == (BET, 0)
ledger.confirm_deposit(movement) # again: nothing changes
assert balance_of(user).spendable_sats == BET
@pytest.mark.parametrize("amount", [0, -5, 1.5, "10", True, None])
def test_deposit_refuses_a_bad_amount(amount):
assert code_of(lambda: ledger.deposit(make_user(), amount)) == "invalid_amount"
def test_the_same_deposit_request_is_one_deposit():
"""WEB-23."""
user, key = make_user(), uuid4()
first = ledger.deposit(user, BET, request_id=key)
second = ledger.deposit(user, BET, request_id=key)
assert (first.replayed, second.replayed) == (False, True) and first.obj.pk == second.obj.pk
assert Movement.objects.count() == 1 and balance_of(user).spendable_sats == BET
assert audit_actions() == ["deposit_credited"] # the replay left no second trace
def test_a_deposit_key_reused_for_a_different_amount_is_an_error():
user, key = make_user(), uuid4()
ledger.deposit(user, BET, request_id=key)
assert code_of(lambda: ledger.deposit(user, BET + 1, request_id=key)) == "idempotency_conflict"
assert Movement.objects.count() == 1
def test_a_failed_operation_leaves_nothing_behind():
"""ARC-72: the write and its audit row commit together or not at all."""
user = make_user()
assert code_of(lambda: ledger.deposit(user, 0)) == "invalid_amount"
assert Movement.objects.count() == 0 and AuditEntry.objects.count() == 0
# --- placing a bet -----------------------------------------------------------------------------
def test_a_bet_reserves_the_funds_and_waits_for_confirmation():
user, round_ = funded(), open_round()
result = ledger.place_bet(user, round_.pk, request_id=uuid4())
bet = result.obj
assert not result.replayed
assert (bet.status, bet.bet_amount_sats, bet.round_id) == ("pending", BET, round_.pk)
movement = Movement.objects.get(kind="bet")
assert (movement.amount_sats, movement.status, movement.participation_id) == (-BET, "pending", bet.pk)
chain = ChainTransaction.objects.get(kind="bet")
assert chain.status == "pending" and len(chain.current_txid) == 64 and bet.bet_txid == chain.current_txid
assert balance_of(user).spendable_sats == 0 # reserved at once
assert audit_actions() == ["deposit_credited", "bet_placed"]
def test_the_same_bet_request_is_one_bet():
"""WEB-23: a double send is one logical operation, charged once."""
user, round_, key = funded(), open_round(), uuid4()
first = ledger.place_bet(user, round_.pk, request_id=key)
second = ledger.place_bet(user, round_.pk, request_id=key)
assert (first.replayed, second.replayed) == (False, True) and first.obj.pk == second.obj.pk
assert Participation.objects.count() == 1 and Movement.objects.filter(kind="bet").count() == 1
assert ChainTransaction.objects.count() == 1
assert audit_actions().count("bet_placed") == 1
def test_a_replay_still_answers_after_the_round_has_closed_for_bets():
user, round_, key = funded(), open_round(), uuid4()
first = ledger.place_bet(user, round_.pk, request_id=key)
Round.objects.filter(pk=round_.pk).update(status="closing")
assert ledger.place_bet(user, round_.pk, request_id=key).obj.pk == first.obj.pk
def test_a_bet_key_reused_for_another_round_or_kind_is_an_error():
user, key = funded(amount=2 * BET), uuid4()
first = open_round()
ledger.place_bet(user, first.pk, request_id=key)
first.status, first.closed_at = "closed", timezone.now()
first.save()
second = open_round()
assert code_of(lambda: ledger.place_bet(user, second.pk, request_id=key)) == "idempotency_conflict"
deposit_key = uuid4()
ledger.deposit(user, PLM, request_id=deposit_key)
assert code_of(lambda: ledger.place_bet(user, second.pk, request_id=deposit_key)) == "idempotency_conflict"
def test_a_bet_needs_an_idempotency_key():
user, round_ = funded(), open_round()
assert code_of(lambda: ledger.place_bet(user, round_.pk, request_id=None)) == "missing_request_id"
assert code_of(lambda: ledger.place_bet(user, round_.pk, request_id="not-a-uuid")) == "missing_request_id"
def test_the_server_charges_the_rounds_own_quota():
"""ADR-10: an edit of the config after the round opened does not change what it costs."""
user, round_ = funded(amount=BET), open_round(bet_amount_sats=BET)
config = LotteryConfig.get()
config.bet_amount_sats = 20 * PLM
config.save()
assert ledger.place_bet(user, round_.pk, request_id=uuid4()).obj.bet_amount_sats == BET
def test_insufficient_funds_are_refused_with_the_required_amount():
user, round_ = funded(amount=BET - 1), open_round()
with pytest.raises(LedgerError) as caught:
ledger.place_bet(user, round_.pk, request_id=uuid4())
assert caught.value.code == "insufficient_balance" and caught.value.params == {"required_sats": BET}
assert Participation.objects.count() == 0
def test_funds_still_in_confirmation_ask_to_wait():
"""BET-07: the balance on screen covers the bet, but it is not confirmed yet."""
user, round_ = make_user(), open_round()
ledger.deposit(user, BET, confirmed=False)
with pytest.raises(LedgerError) as caught:
ledger.place_bet(user, round_.pk, request_id=uuid4())
assert caught.value.code == "balance_pending_confirmation" and caught.value.params == {"pending_sats": BET}
def test_one_bet_per_player_per_round_even_with_another_key():
user, round_ = funded(amount=2 * BET), open_round()
ledger.place_bet(user, round_.pk, request_id=uuid4())
assert code_of(lambda: ledger.place_bet(user, round_.pk, request_id=uuid4())) == "already_betting"
assert balance_of(user).spendable_sats == BET # charged once
def test_bets_are_refused_from_the_rounds_own_deadline():
"""ADR-23: the deadline decides, not the status the scheduler has not flipped yet."""
user = funded()
late = open_round(opened_at=timezone.now() - timedelta(seconds=601), duration_seconds=600)
assert code_of(lambda: ledger.place_bet(user, late.pk, request_id=uuid4())) == "round_closing"
@pytest.mark.parametrize("status", ["closing", "drawing", "paying_out"])
def test_bets_are_refused_once_the_round_leaves_open(status):
user, round_ = funded(), open_round(status=status)
assert code_of(lambda: ledger.place_bet(user, round_.pk, request_id=uuid4())) == "round_closing"
def test_no_round_open():
user = funded()
closed = open_round(status="closed", closed_at=timezone.now())
assert code_of(lambda: ledger.place_bet(user, closed.pk, request_id=uuid4())) == "no_round_open"
assert code_of(lambda: ledger.place_bet(user, 99999, request_id=uuid4())) == "no_round_open"
def test_suspended_bets_are_refused():
"""ADR-57: «Sospendi nuove puntate»."""
user, round_ = funded(), open_round()
config = LotteryConfig.get()
config.new_bets_suspended = True
config.save()
assert code_of(lambda: ledger.place_bet(user, round_.pk, request_id=uuid4())) == "bets_suspended"
def test_a_round_has_a_maximum_of_players(monkeypatch):
"""B-52, BET-20: refused before any money moves."""
monkeypatch.setattr(ledger_module, "MAX_PARTICIPANTS_PER_ROUND", 2)
round_ = open_round()
for name in ("a", "b"):
ledger.place_bet(funded(name), round_.pk, request_id=uuid4())
late = funded("c")
assert code_of(lambda: ledger.place_bet(late, round_.pk, request_id=uuid4())) == "round_full"
assert balance_of(late).spendable_sats == BET
def test_a_round_stops_at_its_pool_cap():
"""BET-20: refused once the pool has reached the cap — it may exceed it by at most one bet."""
round_ = open_round(max_round_pool_sats=BET + 1)
ledger.place_bet(funded("a"), round_.pk, request_id=uuid4()) # pool 10 < cap
ledger.place_bet(funded("b"), round_.pk, request_id=uuid4()) # pool 20 >= cap now
assert code_of(lambda: ledger.place_bet(funded("c"), round_.pk, request_id=uuid4())) == "round_full"
# --- what happens to a bet afterwards ----------------------------------------------------------
def placed(name="mario"):
user, round_ = funded(name), Round.objects.filter(status="open").first() or open_round()
return user, ledger.place_bet(user, round_.pk, request_id=uuid4()).obj
def test_confirming_a_bet_confirms_its_transaction_and_movement():
user, bet = placed()
confirmed = ledger.confirm_bet(bet)
assert confirmed.status == "confirmed" and confirmed.confirmed_at is not None
assert ChainTransaction.objects.get(kind="bet").status == "confirmed"
assert Movement.objects.get(kind="bet").status == "confirmed"
assert balance_of(user).spendable_sats == 0
ledger.confirm_bet(bet) # idempotent
assert audit_actions().count("bet_confirmed") == 1
def test_a_rejected_bet_returns_the_funds_and_keeps_the_reason():
user, bet = placed()
ledger.reject_bet(bet, "refused by the network")
assert Participation.objects.get().status == "rejected"
chain = ChainTransaction.objects.get(kind="bet")
assert (chain.status, chain.failure_reason) == ("failed", "refused by the network")
assert balance_of(user).spendable_sats == BET
assert code_of(lambda: ledger.confirm_bet(bet)) == "invalid_state"
entry = AuditEntry.objects.get(action="bet_rejected")
assert entry.reason == "refused by the network"
def test_rejecting_or_excluding_needs_a_reason():
_, bet = placed()
assert code_of(lambda: ledger.reject_bet(bet, " ")) == "reason_required"
ledger.confirm_bet(bet)
assert code_of(lambda: ledger.exclude_bet(bet, "")) == "reason_required"
def test_a_confirmed_bet_cannot_be_rejected_and_a_pending_one_cannot_be_excluded():
_, first = placed("a")
assert code_of(lambda: ledger.exclude_bet(first, "gone")) == "invalid_state"
ledger.confirm_bet(first)
assert code_of(lambda: ledger.reject_bet(first, "late")) == "invalid_state"
def test_an_excluded_bet_is_refunded_once():
user, bet = placed()
ledger.confirm_bet(bet)
Participation.objects.filter(pk=bet.pk).update(draw_position=0)
ledger.exclude_bet(bet, "the bet is no longer on the chain")
excluded = Participation.objects.get()
assert (excluded.status, excluded.draw_position) == ("excluded", None)
assert balance_of(user).spendable_sats == BET
ledger.exclude_bet(bet, "again") # idempotent: no second refund
assert Movement.objects.filter(kind="refund").count() == 1 and balance_of(user).spendable_sats == BET
# --- the payout --------------------------------------------------------------------------------
def paying_round(bets=3, bet_amount=BET):
"""A round in `paying_out` with `bets` confirmed participants; the first one won."""
round_ = open_round(bet_amount_sats=bet_amount)
users = []
for i in range(bets):
user = funded(f"p{i}", bet_amount)
users.append(user)
ledger.confirm_bet(ledger.place_bet(user, round_.pk, request_id=uuid4()).obj)
round_.status, round_.winner = Round.Status.PAYING_OUT, users[0]
round_.save()
return round_, users
def test_the_pool_is_split_70_30_and_the_winner_is_credited():
"""RND-21."""
round_, users = paying_round(bets=3)
result = ledger.pay_winner(round_.pk)
round_.refresh_from_db()
assert (round_.pool_amount_sats, round_.winner_amount_sats, round_.fee_amount_sats) == (3 * BET, 21 * PLM, 9 * PLM)
assert round_.payout_transaction_id == result.obj.pk and result.obj.kind == "payout"
win = Movement.objects.get(kind="win")
assert (win.user, win.amount_sats, win.status) == (users[0], 21 * PLM, "pending")
assert balance_of(users[0]).incoming_sats == 21 * PLM # in confirmation, not spendable yet
ledger.confirm_payout(round_.pk)
assert balance_of(users[0]).spendable_sats == 21 * PLM and balance_of(users[0]).incoming_sats == 0
assert balance_of(users[1]).spendable_sats == 0
@pytest.mark.parametrize("pool", [1, 3, 10, 11, 99, 1000, 123_456_789])
def test_the_split_never_loses_or_invents_a_satoshi(pool):
"""RND-21: the rounding remainder goes to the platform; winner + fee == pool."""
winner = winner_share(pool)
assert winner == pool * 70 // 100 and 0 <= winner <= pool
assert winner + (pool - winner) == pool
def test_the_rounding_remainder_goes_to_the_platform():
round_, _ = paying_round(bets=1, bet_amount=11)
ledger.pay_winner(round_.pk)
round_.refresh_from_db()
assert (round_.winner_amount_sats, round_.fee_amount_sats) == (7, 4) # 70% of 11 = 7.7 -> 7
def test_a_round_is_paid_once():
round_, users = paying_round()
first, second = ledger.pay_winner(round_.pk), ledger.pay_winner(round_.pk)
assert (first.replayed, second.replayed) == (False, True) and first.obj.pk == second.obj.pk
assert Movement.objects.filter(kind="win").count() == 1
assert audit_actions().count("payout_created") == 1
ledger.confirm_payout(round_.pk)
ledger.confirm_payout(round_.pk)
assert audit_actions().count("payout_confirmed") == 1
assert balance_of(users[0]).spendable_sats == 21 * PLM
def test_only_a_round_that_is_paying_out_can_be_paid():
round_, _ = paying_round()
Round.objects.filter(pk=round_.pk).update(status="drawing")
assert code_of(lambda: ledger.pay_winner(round_.pk)) == "round_not_paying_out"
def test_the_winner_must_be_a_confirmed_participant():
round_, _ = paying_round()
outsider = make_user("outsider")
Round.objects.filter(pk=round_.pk).update(winner=outsider)
assert code_of(lambda: ledger.pay_winner(round_.pk)) == "winner_not_a_participant"
Round.objects.filter(pk=round_.pk).update(winner=None)
assert code_of(lambda: ledger.pay_winner(round_.pk)) == "winner_not_a_participant"
assert Movement.objects.filter(kind="win").count() == 0
def test_a_payout_without_a_transaction_cannot_be_confirmed():
round_, _ = paying_round()
assert code_of(lambda: ledger.confirm_payout(round_.pk)) == "no_payout"
# --- conservation ------------------------------------------------------------------------------
def test_a_whole_round_conserves_the_money():
"""Deposits in == balances + the platform's share, after a full round."""
round_, users = paying_round(bets=4)
ledger.pay_winner(round_.pk)
ledger.confirm_payout(round_.pk)
round_.refresh_from_db()
held = sum(balance_of(u).spendable_sats for u in users)
deposited = sum(Movement.objects.filter(kind="deposit").values_list("amount_sats", flat=True))
assert held + round_.fee_amount_sats == deposited # nothing lost, nothing invented
# --- configuration -----------------------------------------------------------------------------
def _run_settings(**env):
clean = {"PATH": os.environ["PATH"], "PYTHONPATH": str(ROOT), "DJANGO_SECRET_KEY": "k" * 60, **env}
return subprocess.run([sys.executable, "-c", "import config.settings"], cwd=ROOT, env=clean,
capture_output=True, text=True)
def test_the_simulated_ledger_cannot_run_on_mainnet():
"""ADR-59."""
result = _run_settings(PLM_NETWORK="mainnet")
assert result.returncode != 0 and "simulated ledger" in result.stderr
assert _run_settings(PLM_NETWORK="mainnet", LEDGER_BACKEND="chain").returncode == 0
assert _run_settings().returncode == 0 # the default: regtest + simulated
@pytest.mark.parametrize("env", [{"PLM_NETWORK": "testnet"}, {"LEDGER_BACKEND": "magic"}])
def test_unknown_network_or_ledger_is_refused(env):
assert _run_settings(**env).returncode != 0
def test_get_ledger_follows_the_configuration(settings):
assert isinstance(get_ledger(), SimulatedLedger)
settings.LEDGER_BACKEND = "chain"
with pytest.raises(NotImplementedError):
get_ledger()
# --- real concurrency: separate processes on one SQLite file -----------------------------------
_WORKER = """
import json, os, sys, uuid
import django
django.setup()
from django.contrib.auth import get_user_model
from apps.lottery.errors import LedgerError
from apps.lottery.ledger import get_ledger
user = get_user_model().objects.get(username=sys.argv[1])
try:
result = get_ledger().place_bet(user, int(sys.argv[2]), request_id=uuid.UUID(sys.argv[3]))
print(json.dumps({"ok": result.obj.pk, "replayed": result.replayed}))
except LedgerError as exc:
print(json.dumps({"err": exc.code}))
"""
_SETUP = """
import django
django.setup()
from django.contrib.auth import get_user_model
from apps.lottery.ledger import get_ledger
from apps.lottery.models import Round
user = get_user_model().objects.create_user("mario", password="x" * 12)
get_ledger().deposit(user, 10 * 10**8)
print(Round.objects.create().pk)
"""
@pytest.fixture
def shared_db(tmp_path):
env = {"PATH": os.environ["PATH"], "PYTHONPATH": str(ROOT), "DJANGO_SECRET_KEY": "k" * 60,
"DJANGO_DB_PATH": str(tmp_path / "site.sqlite3"), "DJANGO_SETTINGS_MODULE": "config.settings"}
subprocess.run([sys.executable, "manage.py", "migrate", "--noinput", "-v", "0"], cwd=ROOT, env=env, check=True)
round_id = subprocess.run([sys.executable, "-c", _SETUP], cwd=ROOT, env=env, check=True,
capture_output=True, text=True).stdout.strip()
return env, int(round_id)
def _race(env, round_id, keys):
procs = [subprocess.Popen([sys.executable, "-c", _WORKER, "mario", str(round_id), key], cwd=ROOT, env=env,
stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True) for key in keys]
outputs = [p.communicate(timeout=120) for p in procs]
assert all(p.returncode == 0 for p in procs), [o[1] for o in outputs]
return [json.loads(o[0].strip().splitlines()[-1]) for o in outputs]
def test_concurrent_requests_with_the_same_key_make_one_bet(shared_db):
"""ARC-72, WEB-23: six processes send the same request at once; one bet, one charge."""
env, round_id = shared_db
results = _race(env, round_id, ["3f1c6a52-0000-4000-8000-000000000001"] * 6)
assert all("ok" in r for r in results) and len({r["ok"] for r in results}) == 1
assert sorted(r["replayed"] for r in results) == [False] + [True] * 5
def test_concurrent_requests_with_different_keys_make_one_bet(shared_db):
"""ARC-72: six different requests from one player race for one place; exactly one wins."""
env, round_id = shared_db
results = _race(env, round_id, [str(uuid4()) for _ in range(6)])
assert sum("ok" in r for r in results) == 1
assert [r["err"] for r in results if "err" in r] == ["already_betting"] * 5