Implement full MVP: auth, HD wallet, Electrum client, deposits, bets, round/draw engine, payout, withdrawals, RBF, admin+audit

All 10 build-order stages complete and unit-tested (49 tests). Verified live on
mainnet: registration/address derivation, deposit crediting, a real 10 PLM bet
(broadcast + confirmed + change credited). A full round close->draw->payout
cycle was triggered live and was in progress at commit time. Withdrawal and RBF
bump are unit-tested but not yet exercised against a live broadcast. Known gaps
(scheduler doesn't resume mid-flight rounds after restart, payout has no retry,
no deployment setup, etc.) are documented in CLAUDE.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

app/api/routes/admin.py

@@ -0,0 +1,44 @@
+from fastapi import APIRouter, Depends, Header, HTTPException, status
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import settings
+from app.db.session import get_session
+from app.rounds.config import get_round_config
+
+router = APIRouter(prefix="/admin", tags=["admin"])
+
+
+async def require_admin(x_admin_token: str = Header(default="")) -> None:
+    if not settings.admin_token or x_admin_token != settings.admin_token:
+        raise HTTPException(status.HTTP_403_FORBIDDEN, "invalid admin token")
+
+
+class RoundConfigResponse(BaseModel):
+    fee_address: str
+    bet_amount_sats: int
+
+
+class RoundConfigUpdate(BaseModel):
+    fee_address: str | None = None
+    bet_amount_sats: int | None = None
+
+
+@router.get("/config", response_model=RoundConfigResponse, dependencies=[Depends(require_admin)])
+async def read_config(session: AsyncSession = Depends(get_session)) -> RoundConfigResponse:
+    config = await get_round_config(session)
+    await session.commit()
+    return RoundConfigResponse(fee_address=config.fee_address, bet_amount_sats=config.bet_amount_sats)
+
+
+@router.put("/config", response_model=RoundConfigResponse, dependencies=[Depends(require_admin)])
+async def update_config(
+    body: RoundConfigUpdate, session: AsyncSession = Depends(get_session)
+) -> RoundConfigResponse:
+    config = await get_round_config(session)
+    if body.fee_address is not None:
+        config.fee_address = body.fee_address
+    if body.bet_amount_sats is not None:
+        config.bet_amount_sats = body.bet_amount_sats
+    await session.commit()
+    return RoundConfigResponse(fee_address=config.fee_address, bet_amount_sats=config.bet_amount_sats)

app/api/routes/bets.py

@@ -0,0 +1,41 @@
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.auth.dependencies import get_current_user
+from app.bets.service import BetError, place_bet
+from app.db.models import User
+from app.db.session import get_session
+
+router = APIRouter(prefix="/bets", tags=["bets"])
+
+
+class BetResponse(BaseModel):
+    round_id: int
+    bet_txid: str
+    bet_amount_sats: int
+    status: str
+
+
+@router.post("", response_model=BetResponse, status_code=status.HTTP_201_CREATED)
+async def create_bet(
+    request: Request,
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_session),
+) -> BetResponse:
+    listener = request.app.state.electrum_listener
+    if listener.client is None:
+        raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, "not connected to the network, try again shortly")
+
+    async with request.app.state.user_locks.acquire(user.id):
+        try:
+            participant = await place_bet(session, listener.client, user)
+        except BetError as exc:
+            raise HTTPException(status.HTTP_400_BAD_REQUEST, str(exc)) from exc
+
+    return BetResponse(
+        round_id=participant.round_id,
+        bet_txid=participant.bet_txid,
+        bet_amount_sats=participant.bet_amount_sats,
+        status=participant.status,
+    )

app/api/routes/users.py

@@ -0,0 +1,18 @@
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+
+from app.auth.dependencies import get_current_user
+from app.db.models import User
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+
+class MeResponse(BaseModel):
+    username: str
+    address: str
+    balance_sats: int
+
+
+@router.get("/me", response_model=MeResponse)
+async def me(user: User = Depends(get_current_user)) -> MeResponse:
+    return MeResponse(username=user.username, address=user.address, balance_sats=user.cached_balance_sats)

app/api/routes/withdrawals.py

@@ -0,0 +1,49 @@
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.auth.dependencies import get_current_user
+from app.db.models import User
+from app.db.session import get_session
+from app.withdrawals.service import WithdrawalError, request_withdrawal
+
+router = APIRouter(prefix="/withdrawals", tags=["withdrawals"])
+
+
+class WithdrawalRequest(BaseModel):
+    external_address: str
+    amount_sats: int
+
+
+class WithdrawalResponse(BaseModel):
+    txid: str
+    amount_requested_sats: int
+    amount_sent_sats: int
+    status: str
+
+
+@router.post("", response_model=WithdrawalResponse, status_code=status.HTTP_201_CREATED)
+async def create_withdrawal(
+    body: WithdrawalRequest,
+    request: Request,
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_session),
+) -> WithdrawalResponse:
+    listener = request.app.state.electrum_listener
+    if listener.client is None:
+        raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, "not connected to the network, try again shortly")
+
+    async with request.app.state.user_locks.acquire(user.id):
+        try:
+            withdrawal = await request_withdrawal(
+                session, listener.client, user, body.external_address, body.amount_sats
+            )
+        except WithdrawalError as exc:
+            raise HTTPException(status.HTTP_400_BAD_REQUEST, str(exc)) from exc
+
+    return WithdrawalResponse(
+        txid=withdrawal.txid,
+        amount_requested_sats=withdrawal.amount_requested_sats,
+        amount_sent_sats=withdrawal.amount_sent_sats,
+        status=withdrawal.status,
+    )