371 lines
20 KiB
Python
371 lines
20 KiB
Python
"""How money moves: one interface, a simulated implementation (ADR-59, roadmap A3).
|
|
|
|
Views and the worker talk to `Ledger`. Phase A runs `SimulatedLedger`; phase B adds the
|
|
implementation that builds, signs and broadcasts real transactions behind the same methods, so
|
|
nothing above this module changes.
|
|
|
|
Every operation is one database transaction (`transaction.atomic()` takes the write lock up front,
|
|
ADR-55): the checks and the writes cannot be interleaved with another request's, and the audit row
|
|
commits or rolls back with the change (ADR-53). A request carries an idempotency key (WEB-23): the
|
|
same key from the same player is the same operation, and sending it again returns the first
|
|
outcome instead of doing it twice.
|
|
"""
|
|
|
|
import hashlib
|
|
import uuid
|
|
from abc import ABC, abstractmethod
|
|
from dataclasses import dataclass
|
|
from typing import Any
|
|
from uuid import UUID
|
|
|
|
from django.conf import settings
|
|
from django.db import IntegrityError, transaction
|
|
from django.utils import timezone
|
|
|
|
from . import audit
|
|
from .balances import balance_of
|
|
from .errors import LedgerError
|
|
from .models import ChainTransaction, LotteryConfig, Movement, Participation, Round
|
|
from .rules import MAX_PARTICIPANTS_PER_ROUND, round_accepts_bets, winner_share
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class Result:
|
|
"""What an operation produced, and whether it was a replay of an earlier identical request."""
|
|
|
|
obj: Any
|
|
replayed: bool = False
|
|
|
|
|
|
class Ledger(ABC):
|
|
@abstractmethod
|
|
def deposit(self, user, amount_sats: int, *, request_id: UUID | None = None, confirmed: bool = True) -> Result: ...
|
|
|
|
@abstractmethod
|
|
def confirm_deposit(self, movement: Movement) -> Movement: ...
|
|
|
|
@abstractmethod
|
|
def place_bet(self, user, round_id: int, *, request_id: UUID) -> Result: ...
|
|
|
|
@abstractmethod
|
|
def confirm_bet(self, participation: Participation) -> Participation: ...
|
|
|
|
@abstractmethod
|
|
def reject_bet(self, participation: Participation, reason: str) -> Participation: ...
|
|
|
|
@abstractmethod
|
|
def exclude_bet(self, participation: Participation, reason: str) -> Participation: ...
|
|
|
|
@abstractmethod
|
|
def pay_winner(self, round_id: int) -> Result: ...
|
|
|
|
@abstractmethod
|
|
def confirm_payout(self, round_id: int) -> Round: ...
|
|
|
|
|
|
def _simulated_txid(kind: str) -> str:
|
|
return hashlib.sha256(f"simulated:{kind}:{uuid.uuid4()}".encode()).hexdigest()
|
|
|
|
|
|
def _admit_bet(ledger: "Ledger", user, round_id: int, request_id: UUID):
|
|
"""The checks every bet passes, whatever the ledger (WEB-22, BET-07): a replay of the same request, an open
|
|
round, no suspension, no second bet, room in the round, and a balance that covers the quota. Returns a
|
|
`Result` for a replay, else `(round, amount)`. Call inside `transaction.atomic()`."""
|
|
if not isinstance(request_id, UUID):
|
|
raise LedgerError("missing_request_id", "a bet needs the idempotency key of its request")
|
|
round_ = Round.objects.filter(pk=round_id).first()
|
|
replay = ledger._replay(user, request_id, Movement.Kind.BET, None)
|
|
if replay is not None:
|
|
if replay.round_id != round_id:
|
|
raise LedgerError("idempotency_conflict", "this request key was used for another round")
|
|
return Result(replay.participation, replayed=True)
|
|
if round_ is None or round_.status == Round.Status.CLOSED:
|
|
raise LedgerError("no_round_open", "no round open right now, please try again shortly")
|
|
if LotteryConfig.get().new_bets_suspended:
|
|
raise LedgerError("bets_suspended", "new bets are suspended")
|
|
if not round_accepts_bets(round_):
|
|
raise LedgerError("round_closing", "the current round is closing, please try again shortly")
|
|
if Participation.objects.filter(round=round_, user=user).exists():
|
|
raise LedgerError("already_betting", "you already have an active bet in the current round")
|
|
SimulatedLedger._check_round_capacity(round_)
|
|
amount = round_.bet_amount_sats
|
|
balance = balance_of(user)
|
|
if balance.spendable_sats < amount:
|
|
# BET-07: a balance on screen that includes funds in confirmation must say "wait", not a flat "insufficient".
|
|
if balance.total_sats >= amount:
|
|
raise LedgerError("balance_pending_confirmation",
|
|
"the bet cost is covered by your pending balance, which has not confirmed yet",
|
|
pending_sats=balance.incoming_sats)
|
|
raise LedgerError("insufficient_balance", "insufficient balance", required_sats=amount)
|
|
return round_, amount
|
|
|
|
|
|
class SimulatedLedger(Ledger):
|
|
"""Funds that exist only in the database. Confirmation is a method call, not a block."""
|
|
|
|
# -- deposits ---------------------------------------------------------------------------
|
|
|
|
def deposit(self, user, amount_sats: int, *, request_id: UUID | None = None, confirmed: bool = True) -> Result:
|
|
if not isinstance(amount_sats, int) or isinstance(amount_sats, bool) or amount_sats <= 0:
|
|
raise LedgerError("invalid_amount", "the amount must be a positive whole number of satoshi")
|
|
with transaction.atomic():
|
|
replay = self._replay(user, request_id, Movement.Kind.DEPOSIT, amount_sats)
|
|
if replay is not None:
|
|
return Result(replay, replayed=True)
|
|
now = timezone.now()
|
|
movement = Movement.objects.create(
|
|
user=user, kind=Movement.Kind.DEPOSIT, amount_sats=amount_sats, request_id=request_id,
|
|
status=Movement.Status.CONFIRMED if confirmed else Movement.Status.PENDING,
|
|
confirmed_at=now if confirmed else None,
|
|
)
|
|
audit.record("deposit_credited" if confirmed else "deposit_pending", actor=user,
|
|
subject_type="movement", subject_id=movement.pk, payload={"amount_sats": amount_sats})
|
|
return Result(movement)
|
|
|
|
def confirm_deposit(self, movement: Movement) -> Movement:
|
|
with transaction.atomic():
|
|
movement = Movement.objects.get(pk=movement.pk)
|
|
if movement.kind != Movement.Kind.DEPOSIT:
|
|
raise LedgerError("not_a_deposit", "only a deposit can be confirmed here")
|
|
if movement.status == Movement.Status.CONFIRMED:
|
|
return movement
|
|
if movement.status != Movement.Status.PENDING:
|
|
raise LedgerError("invalid_state", f"a {movement.status} deposit cannot be confirmed")
|
|
movement.status, movement.confirmed_at = Movement.Status.CONFIRMED, timezone.now()
|
|
movement.save(update_fields=["status", "confirmed_at"])
|
|
audit.record("deposit_credited", subject_type="movement", subject_id=movement.pk,
|
|
payload={"amount_sats": movement.amount_sats})
|
|
return movement
|
|
|
|
# -- bets -------------------------------------------------------------------------------
|
|
|
|
def place_bet(self, user, round_id: int, *, request_id: UUID) -> Result:
|
|
"""WEB-22: the server decides — round, quota, limits and funds are all checked here."""
|
|
with transaction.atomic():
|
|
admitted = _admit_bet(self, user, round_id, request_id)
|
|
if isinstance(admitted, Result):
|
|
return admitted
|
|
round_, amount = admitted
|
|
|
|
txid = _simulated_txid("bet")
|
|
chain_tx = ChainTransaction.objects.create(
|
|
kind=ChainTransaction.Kind.BET, status=ChainTransaction.Status.PENDING, user=user, round=round_,
|
|
current_txid=txid, broadcast_at=timezone.now(),
|
|
)
|
|
try:
|
|
with transaction.atomic():
|
|
participation = Participation.objects.create(
|
|
round=round_, user=user, bet_amount_sats=amount, bet_txid=txid
|
|
)
|
|
except IntegrityError: # unreachable under the write lock; the constraint is the backstop
|
|
raise LedgerError("already_betting", "you already have an active bet in the current round") from None
|
|
Movement.objects.create(
|
|
user=user, kind=Movement.Kind.BET, amount_sats=-amount, status=Movement.Status.PENDING,
|
|
round=round_, participation=participation, chain_transaction=chain_tx, request_id=request_id,
|
|
)
|
|
audit.record("bet_placed", actor=user, subject_type="participation", subject_id=participation.pk,
|
|
payload={"round_id": round_.pk, "amount_sats": amount})
|
|
return Result(participation)
|
|
|
|
@staticmethod
|
|
def _check_round_capacity(round_: Round) -> None:
|
|
participants = Participation.objects.filter(round=round_)
|
|
if participants.count() >= MAX_PARTICIPANTS_PER_ROUND:
|
|
raise LedgerError("round_full", f"this round already has its maximum of {MAX_PARTICIPANTS_PER_ROUND} players",
|
|
max_participants=MAX_PARTICIPANTS_PER_ROUND)
|
|
if round_.max_round_pool_sats:
|
|
# BET-20: refused once the sum has *reached* the cap; every row counts, in-flight included.
|
|
pool = sum(participants.values_list("bet_amount_sats", flat=True))
|
|
if pool >= round_.max_round_pool_sats:
|
|
raise LedgerError("round_full", "this round has reached its limit",
|
|
max_round_pool_sats=round_.max_round_pool_sats)
|
|
|
|
def confirm_bet(self, participation: Participation) -> Participation:
|
|
with transaction.atomic():
|
|
participation = Participation.objects.select_related("round").get(pk=participation.pk)
|
|
if participation.status == Participation.Status.CONFIRMED:
|
|
return participation
|
|
if participation.status != Participation.Status.PENDING:
|
|
raise LedgerError("invalid_state", f"a {participation.status} bet cannot be confirmed")
|
|
now = timezone.now()
|
|
participation.status, participation.confirmed_at = Participation.Status.CONFIRMED, now
|
|
participation.save(update_fields=["status", "confirmed_at"])
|
|
ChainTransaction.objects.filter(current_txid=participation.bet_txid).update(
|
|
status=ChainTransaction.Status.CONFIRMED, confirmed_at=now)
|
|
Movement.objects.filter(participation=participation, kind=Movement.Kind.BET).update(
|
|
status=Movement.Status.CONFIRMED, confirmed_at=now)
|
|
audit.record("bet_confirmed", subject_type="participation", subject_id=participation.pk)
|
|
return participation
|
|
|
|
def reject_bet(self, participation: Participation, reason: str) -> Participation:
|
|
"""A bet that never took part: it stops reserving funds and nothing else is owed."""
|
|
self._require_reason(reason)
|
|
with transaction.atomic():
|
|
participation = Participation.objects.get(pk=participation.pk)
|
|
if participation.status == Participation.Status.REJECTED:
|
|
return participation
|
|
if participation.status != Participation.Status.PENDING:
|
|
raise LedgerError("invalid_state", f"a {participation.status} bet cannot be rejected")
|
|
now = timezone.now()
|
|
participation.status = Participation.Status.REJECTED
|
|
participation.save(update_fields=["status"])
|
|
ChainTransaction.objects.filter(current_txid=participation.bet_txid).update(
|
|
status=ChainTransaction.Status.FAILED, failed_at=now, failure_reason=reason)
|
|
Movement.objects.filter(participation=participation, kind=Movement.Kind.BET).update(
|
|
status=Movement.Status.FAILED)
|
|
audit.record("bet_rejected", reason=reason, subject_type="participation", subject_id=participation.pk)
|
|
return participation
|
|
|
|
def exclude_bet(self, participation: Participation, reason: str) -> Participation:
|
|
"""A confirmed bet left out of the draw: its amount goes back as a refund line."""
|
|
self._require_reason(reason)
|
|
with transaction.atomic():
|
|
participation = Participation.objects.get(pk=participation.pk)
|
|
if participation.status == Participation.Status.EXCLUDED:
|
|
return participation
|
|
if participation.status != Participation.Status.CONFIRMED:
|
|
raise LedgerError("invalid_state", f"a {participation.status} bet cannot be excluded")
|
|
now = timezone.now()
|
|
participation.status, participation.draw_position = Participation.Status.EXCLUDED, None
|
|
participation.save(update_fields=["status", "draw_position"])
|
|
Movement.objects.create(
|
|
user=participation.user, kind=Movement.Kind.REFUND, amount_sats=participation.bet_amount_sats,
|
|
status=Movement.Status.CONFIRMED, confirmed_at=now, round=participation.round,
|
|
participation=participation,
|
|
)
|
|
audit.record("bet_excluded", reason=reason, subject_type="participation", subject_id=participation.pk,
|
|
payload={"refund_sats": participation.bet_amount_sats})
|
|
return participation
|
|
|
|
@staticmethod
|
|
def _require_reason(reason: str) -> None:
|
|
if not reason.strip():
|
|
raise LedgerError("reason_required", "a reason is required")
|
|
|
|
# -- payout -----------------------------------------------------------------------------
|
|
|
|
def pay_winner(self, round_id: int) -> Result:
|
|
"""Split the pool 70/30 and credit the winner (RND-21). The same round is paid once."""
|
|
with transaction.atomic():
|
|
round_ = Round.objects.get(pk=round_id)
|
|
if round_.payout_transaction_id is not None:
|
|
return Result(round_.payout_transaction, replayed=True)
|
|
if round_.status != Round.Status.PAYING_OUT:
|
|
raise LedgerError("round_not_paying_out", "only a round that is paying out can be paid")
|
|
confirmed = Participation.objects.filter(round=round_, status=Participation.Status.CONFIRMED)
|
|
winner_participation = confirmed.filter(user=round_.winner_id).first() if round_.winner_id else None
|
|
if winner_participation is None:
|
|
raise LedgerError("winner_not_a_participant", "the winner is not a confirmed participant of the round")
|
|
pool = sum(confirmed.values_list("bet_amount_sats", flat=True))
|
|
winner_amount = winner_share(pool)
|
|
fee_amount = pool - winner_amount # the rounding remainder goes to the platform
|
|
if winner_amount <= 0:
|
|
raise LedgerError("nothing_to_pay", "the pool is too small to pay a winner")
|
|
|
|
chain_tx = ChainTransaction.objects.create(
|
|
kind=ChainTransaction.Kind.PAYOUT, status=ChainTransaction.Status.PENDING, round=round_,
|
|
current_txid=_simulated_txid("payout"), broadcast_at=timezone.now(),
|
|
)
|
|
Movement.objects.create(
|
|
user=round_.winner, kind=Movement.Kind.WIN, amount_sats=winner_amount,
|
|
status=Movement.Status.PENDING, round=round_, chain_transaction=chain_tx,
|
|
)
|
|
round_.pool_amount_sats, round_.winner_amount_sats, round_.fee_amount_sats = pool, winner_amount, fee_amount
|
|
round_.payout_transaction = chain_tx
|
|
round_.save(update_fields=["pool_amount_sats", "winner_amount_sats", "fee_amount_sats", "payout_transaction"])
|
|
audit.record("payout_created", subject_type="round", subject_id=round_.pk,
|
|
payload={"pool_sats": pool, "winner_sats": winner_amount, "fee_sats": fee_amount})
|
|
return Result(chain_tx)
|
|
|
|
def confirm_payout(self, round_id: int) -> Round:
|
|
with transaction.atomic():
|
|
round_ = Round.objects.select_related("payout_transaction").get(pk=round_id)
|
|
chain_tx = round_.payout_transaction
|
|
if chain_tx is None:
|
|
raise LedgerError("no_payout", "the round has no payout to confirm")
|
|
if chain_tx.status == ChainTransaction.Status.CONFIRMED:
|
|
return round_
|
|
now = timezone.now()
|
|
chain_tx.status, chain_tx.confirmed_at = ChainTransaction.Status.CONFIRMED, now
|
|
chain_tx.save(update_fields=["status", "confirmed_at"])
|
|
Movement.objects.filter(chain_transaction=chain_tx, kind=Movement.Kind.WIN).update(
|
|
status=Movement.Status.CONFIRMED, confirmed_at=now)
|
|
audit.record("payout_confirmed", subject_type="round", subject_id=round_.pk)
|
|
return round_
|
|
|
|
# -- idempotency ------------------------------------------------------------------------
|
|
|
|
@staticmethod
|
|
def _replay(user, request_id: UUID | None, kind: str, amount_sats: int | None) -> Movement | None:
|
|
"""The earlier operation with this key, if any. A key reused for something else is an error,
|
|
not a replay (WEB-23)."""
|
|
if request_id is None:
|
|
return None
|
|
existing = Movement.objects.filter(user=user, request_id=request_id).select_related("participation").first()
|
|
if existing is None:
|
|
return None
|
|
if existing.kind != kind or (amount_sats is not None and existing.amount_sats != amount_sats):
|
|
raise LedgerError("idempotency_conflict", "this request key was already used for a different operation")
|
|
return existing
|
|
|
|
|
|
class ChainLedger(SimulatedLedger):
|
|
"""Real coins (roadmap B6). The web process admits and *reserves*; it never signs (ARC-78) — the worker does,
|
|
from `apps/lottery/bets.py`. What belongs to later steps refuses loudly instead of pretending: confirmation,
|
|
refusal and exclusion of a bet and the payout are B7/B8, withdrawals B9. Deposits arrive from the chain
|
|
(`deposits.scan_deposits`), never by a call."""
|
|
|
|
def place_bet(self, user, round_id: int, *, request_id: UUID) -> Result:
|
|
from . import reservation
|
|
from plm_engine.psbt_builder import InsufficientFundsError
|
|
|
|
with transaction.atomic():
|
|
admitted = _admit_bet(self, user, round_id, request_id)
|
|
if isinstance(admitted, Result):
|
|
return admitted
|
|
round_, amount = admitted
|
|
chain_tx = ChainTransaction.objects.create(
|
|
kind=ChainTransaction.Kind.BET, status=ChainTransaction.Status.BUILDING, user=user, round=round_
|
|
)
|
|
try:
|
|
coins = reservation.reserve_for(user, amount, chain_tx)
|
|
except InsufficientFundsError as error:
|
|
raise LedgerError(error.code, str(error), **error.params) from error
|
|
except reservation.CoinsTaken as error:
|
|
raise LedgerError("busy", "please try again in a moment") from error
|
|
participation = Participation.objects.create(round=round_, user=user, bet_amount_sats=amount)
|
|
Movement.objects.create(
|
|
user=user, kind=Movement.Kind.BET, amount_sats=-amount, status=Movement.Status.PENDING,
|
|
round=round_, participation=participation, chain_transaction=chain_tx, request_id=request_id,
|
|
)
|
|
audit.record("bet_placed", actor=user, subject_type="participation", subject_id=participation.pk,
|
|
payload={"round_id": round_.pk, "amount_sats": amount, "coins": len(coins)})
|
|
return Result(participation)
|
|
|
|
def deposit(self, user, amount_sats: int, *, request_id: UUID | None = None, confirmed: bool = True) -> Result:
|
|
raise LedgerError("not_available", "deposits on a real ledger come from the chain, not from a call")
|
|
|
|
def confirm_deposit(self, movement: Movement) -> Movement:
|
|
raise LedgerError("not_available", "deposits on a real ledger come from the chain, not from a call")
|
|
|
|
def confirm_bet(self, participation: Participation) -> Participation:
|
|
raise NotImplementedError("the confirmation of a real bet arrives with roadmap B7")
|
|
|
|
def reject_bet(self, participation: Participation, reason: str) -> Participation:
|
|
raise NotImplementedError("the refusal of a real bet after the fact arrives with roadmap B7")
|
|
|
|
def exclude_bet(self, participation: Participation, reason: str) -> Participation:
|
|
raise NotImplementedError("the exclusion of a real bet arrives with roadmap B7")
|
|
|
|
def pay_winner(self, round_id: int) -> Result:
|
|
raise NotImplementedError("the real payout arrives with roadmap B8")
|
|
|
|
def confirm_payout(self, round_id: int) -> Round:
|
|
raise NotImplementedError("the real payout arrives with roadmap B8")
|
|
|
|
|
|
def get_ledger() -> Ledger:
|
|
if settings.LEDGER_BACKEND == "simulated":
|
|
return SimulatedLedger()
|
|
return ChainLedger()
|