Wallet: self-service USDC withdrawal to external address (any user)

[manoahLinks]

Summary

Self-service USDC withdrawal: let any HostIT user move their custodial USDC balance out to an external on-chain address of their choosing (full balance or a specified amount).

This replaces the original "accumulate-then-pay-organizer-out" framing. Under the real-time split (#96), USDC lands directly in a user's custodial Circle wallet:

• Organizers — non-refundable ticket cuts arrive instantly on-chain via mintTicket; refundable cuts arrive after withdrawTicketBalance releases the escrow (see Blockchain: Bull queue — payout (withdrawTicketBalance on-chain) #37 / Epic: Crypto real-time split — organizer paid on-chain via mintTicket #96 Phase 3).
• Attendees — refunded amounts (claimRefund) and any leftover custodial balance from the "deposit only the shortfall" checkout flow.

Both cases leave a spendable USDC balance in the user's Circle wallet. This issue covers letting them sweep it to an external wallet.

Scope

• Endpoint: POST /api/wallet/withdraw (JWT — any authenticated user)
  • Body: { toAddress: string, amount?: string } — amount omitted ⇒ withdraw the entire available balance.
  • Validate toAddress (EVM checksum, non-zero); reject if balance is 0 or amount > available.
• Service CircleWalletService.withdraw(userId, toAddress, amount?):
  • Source: the user's own custodial Circle wallet (user.circleWalletId).
  • Transfer via Circle developer-controlled wallet USDC transfer (Base). Gas sponsored by Circle Gas Station (same policy the epic requires).
  • Idempotency: use WithdrawalRecord.id as the Circle transfer refId.
  • Persist WithdrawalRecord { userId, toAddress, amount, fee, status, circleTransferId, txHash }.
• Status updated from the Circle webhook (Webhooks: Circle webhook handler (/webhooks/circle) #65), not by polling.
• "Withdraw all" resolves the on-chain balance at request time and transfers the full amount (account for any gas/fee handling).

Out of scope (tracked elsewhere)

• Instant on-chain organizer settlement — Epic: Crypto real-time split — organizer paid on-chain via mintTicket #96.
• Refund claim endpoint (claimRefund) — Epic: Crypto real-time split — organizer paid on-chain via mintTicket #96 Phase 3.
• NGN fiat bank payouts — organizer bank flow / Blockradar (Payments: Blockradar provider (NGN virtual accounts only) #29, Webhooks: Blockradar webhook handler (NGN virtual account deposits only) #32).

Acceptance criteria

• User can withdraw a specified USDC amount to an external address, end-to-end
• User can withdraw their entire balance (no amount given)
• Invalid/zero address and over-balance requests rejected with clear errors
• Withdrawal status reconciled from the Circle webhook (Webhooks: Circle webhook handler (/webhooks/circle) #65)
• Idempotent — retrying the same WithdrawalRecord never double-sends
• Audit log captures source wallet, destination, amount, fee, tx hash
• Dry-run mode for staging (skips the actual transfer)

Depends on

• Webhooks: Circle webhook handler (/webhooks/circle) #65 (webhook for status reconciliation)
• Circle Gas Station policy funded for the user wallet set (CIRCLE_WALLET_SET_ID) — see Epic: Crypto real-time split — organizer paid on-chain via mintTicket #96 ops prerequisite

Refs #96, #37

[manoahLinks]

Scope update (per the crypto on-chain split decision):

The treasury → organizer internal USDC transfer leg is superseded. Organizers are now paid directly on-chain by the Diamond at mint time:

• Non-refundable events: mintTicket transfers the organizer's cut straight to their wallet (the on-chain ticketAdmin) in the mint tx — instant, no transfer service.
• Refundable events: the cut is escrowed and released via withdrawTicketBalance after endTime + 3d.

This issue stays open, narrowed to external-wallet payout: let organizers withdraw their USDC balance to an external address of their choosing from the app (CircleTransferService internal-wallet → external-address, whitelisted at KYC).

Foundational on-chain admin/publish changes landed on branch feat/crypto-onchain-split (organizer becomes the on-chain ticketAdmin; publish configures USDC fees). See the epic for the phased plan.

[arjunkshah12345-hash]

For this payout path, make the withdrawal record the durable state machine and let Circle/on-chain evidence advance it:

requested -> submitted -> pending -> succeeded | failed, with idempotency_key = withdrawal_record.id and a unique constraint on (user_id, idempotency_key). Resolve “withdraw all” to an integer base-unit amount inside the same balance reservation transaction; never recompute it after the Circle transfer is submitted.

Before submission, validate checksum/non-zero destination, chain/network, available balance, and any KYC allow-list. Persist a redacted audit row with source wallet id, destination, amount, fee, and request id; do not log tokens or full provider payloads. The webhook consumer should verify the provider signature, dedupe by provider event id, reject impossible status regressions, and attach the tx hash only after the provider marks the transfer complete.

The highest-risk tests are: retry after a timeout with the same record id (one transfer), duplicate webhook delivery (one state transition), late success after a local timeout, insufficient balance while another withdrawal is pending, and a dry-run that exercises validation/reservation without a provider call. Those tests cover the exact double-send and “withdraw all” races in the scope.