Add withdrawal flow

Builds and broadcasts a user->external-address PSBT with change back to
the user's own address, fee deducted from the withdrawn amount, and
registers the confirmation handler that marks the withdrawal confirmed.
Shares the per-user lock with bets so a build never races a spend from
the same UTXO set.

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

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,
+    )

app/withdrawals/confirmation.py

@@ -0,0 +1,18 @@
+from datetime import datetime, timezone
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models import PendingTransaction, Withdrawal
+from app.tx.confirmation import register_handler
+
+
+async def _on_withdrawal_confirmed(session: AsyncSession, pending: PendingTransaction) -> None:
+    if pending.withdrawal_id is None:
+        return
+    withdrawal = await session.get(Withdrawal, pending.withdrawal_id)
+    if withdrawal is not None and withdrawal.status == "broadcast":
+        withdrawal.status = "confirmed"
+        withdrawal.confirmed_at = datetime.now(timezone.utc)
+
+
+register_handler("withdrawal", _on_withdrawal_confirmed)

app/withdrawals/service.py

@@ -0,0 +1,86 @@
+from embit import script
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.audit.log import write_audit_log
+from app.config import settings
+from app.db.models import PendingTransaction, User, UtxoEvent, Withdrawal
+from app.electrum.client import ElectrumClient
+from app.wallet.balance import recompute_balance
+from app.wallet.hd import derive_user_key
+from app.wallet.psbt_builder import InsufficientFundsError, Utxo, build_signed_transaction
+
+
+class WithdrawalError(Exception):
+    pass
+
+
+async def request_withdrawal(
+    session: AsyncSession, client: ElectrumClient, user: User, external_address: str, amount_sats: int
+) -> Withdrawal:
+    if amount_sats < settings.min_amount_sats:
+        raise WithdrawalError(f"amount below the minimum of {settings.min_amount_sats} sats")
+
+    unspent = (
+        await session.scalars(
+            select(UtxoEvent).where(UtxoEvent.user_id == user.id, UtxoEvent.spent_txid.is_(None))
+        )
+    ).all()
+    if sum(u.amount_sats for u in unspent) < amount_sats:
+        raise WithdrawalError("insufficient balance")
+
+    user_key = derive_user_key(user.derivation_index)
+    from_script = script.p2wpkh(user_key.to_public())
+    utxos = [Utxo(u.txid, u.vout, u.amount_sats) for u in unspent]
+
+    try:
+        built = build_signed_transaction(
+            signing_key=user_key,
+            from_script=from_script,
+            utxos=utxos,
+            to_address=external_address,
+            amount_sats=amount_sats,
+            change_address=user.address,
+            fee_rate_sat_vb=settings.fee_rate_sat_vb,
+        )
+    except InsufficientFundsError as exc:
+        raise WithdrawalError(str(exc)) from exc
+
+    await client.broadcast(built.raw_hex)
+
+    spent_by_key = {(u.txid, u.vout): u for u in unspent}
+    for spent in built.spent_utxos:
+        spent_by_key[(spent.txid, spent.vout)].spent_txid = built.txid
+    await recompute_balance(session, user.id)
+
+    withdrawal = Withdrawal(
+        user_id=user.id,
+        external_address=external_address,
+        amount_requested_sats=amount_sats,
+        amount_sent_sats=built.recipient_sats,
+        txid=built.txid,
+        status="broadcast",
+    )
+    session.add(withdrawal)
+    await session.flush()
+    session.add(
+        PendingTransaction(
+            kind="withdrawal",
+            withdrawal_id=withdrawal.id,
+            user_id=user.id,
+            current_txid=built.txid,
+            fee_rate_sat_vb=settings.fee_rate_sat_vb,
+            raw_tx_hex=built.raw_hex,
+            status="pending",
+        )
+    )
+    await write_audit_log(
+        session,
+        "withdrawal_sent",
+        {"txid": built.txid, "amount_sent_sats": built.recipient_sats, "external_address": external_address},
+        user_id=user.id,
+    )
+
+    await session.commit()
+    await session.refresh(withdrawal)
+    return withdrawal