Epic: Crypto real-time split — organizer paid on-chain via mintTicket

[manoahLinks]

Tracking epic for settling crypto (USDC) ticket revenue on-chain, routed by isRefundable. Supersedes the accumulate-then-withdraw assumptions in #37 and the internal-transfer leg of #68.

Architecture (verified against the deployed Base Sepolia MarketplaceFacet)

Crypto checkout settles via the Diamond's mintTicket(ticketId, USDC, buyer), which splits on-chain by isRefundable:

• Non-refundable → organizer's cut (ticketFee) transferred instantly to the on-chain ticketAdmin (the organizer) in the mint tx; HostIT's 3% accrues to hostItBalance.
• Refundable → organizer's cut escrowed; claimRefund valid endTime..endTime+3d; withdrawTicketBalance releases it after the window (WithdrawPeriodNotReached gate is conditional on isRefundable).

The buyer never transacts on-chain — a HostIT settlement wallet holds the deposited USDC and signs mintTicket; only that wallet + user wallets need gas (Circle Gas Station).

Phase 1 — foundation ✅ (branch feat/crypto-onchain-split)

• executeContract accepts a signer walletId (default treasury)
• createTicket signed by the organizer → organizer is the on-chain ticketAdmin (payout target + mainAdmin + scanner-role holder)
• Publish configures on-chain fee as USDC (NGN→USDC 6-dp), replacing the ETH placeholder
• Fix stale FeeType map to the deployed Base enum (USDC=5, NATIVE=2, …)
• On-chain checkIn signed by the scanner's wallet (role holder), not treasury

Phase 2 — scanner delegation

• Organizer endpoint: grant/revoke ticketAdminRole to other HostIT users (organizer-signed addTicketAdmins / removeTicketAdmins)
• Check-in worker resolves delegated scanner wallets; handle admin-scanned check-ins (admins have no wallet today)

Phase 3 — crypto settlement + refunds

• Crypto checkout deposits into a HostIT settlement wallet (not the buyer's own)
• Inbound-USDC webhook settles via mintTicket (approve + execute) instead of the free mintFiatTicket
• Refundable withdraw leg (auto withdrawTicketBalance after window) — narrows Blockchain: Bull queue — payout (withdrawTicketBalance on-chain) #37
• claimRefund endpoint for refundable events (buyer-initiated, within window)
• Periodic withdrawHostItBalance → treasury (HostIT's 3%)
• External-wallet payout (Wallet: self-service USDC withdrawal to external address (any user) #68)

Ops prerequisite

• Circle Gas Station paymaster policy for the user wallet set (CIRCLE_WALLET_SET_ID) on Base-Sepolia + Base, funded — organizer-signed createTicket/checkIn fail without it.

Refs #37, #68

[manoahLinks]

Phase 3 — crypto settlement landed (branch feat/crypto-settlement, commit c704475)

Decisions locked in:

• Fee model: organizer-bears — buyer pays the face price in USDC on both rails; HostIT's 3% is backed out of ticketFee. Shared onchain-fees.ts helper is the single source of truth for the fee math + FeeType codes.
• Buyer-wallet-signs (not a shared settlement wallet) — the buyer's own gas-sponsored SCA wallet approves USDC + calls mintTicket, so there's no deposit-matching ambiguity and no extra fund movement.

Done:

• Crypto purchases route to paid mintTicket (buyer wallet: approve → mintTicket); contract splits by isRefundable; fiat keeps the free mintFiatTicket
• Deposit amount = on-chain totalFee × quantity (worker approves the authoritative on-chain getAllFees totalFee)
• CircleContractService.approveErc20 + non-persisting poll; mint worker crypto/fiat routing (unit-tested)

Still open (Phase 3 tail / Phase 2):

• Refundable withdraw leg — auto withdrawTicketBalance after endTime + 3d (narrows Blockchain: Bull queue — payout (withdrawTicketBalance on-chain) #37)
• claimRefund endpoint (buyer-initiated, within window)
• Periodic withdrawHostItBalance → treasury
• External-wallet payout (Wallet: self-service USDC withdrawal to external address (any user) #68)
• Scanner delegation endpoints (Phase 2)

Known edge: the off-chain deposit estimate can drift from the on-chain totalFee if USDC_NGN_RATE changes between publish and purchase. The worker reads the authoritative on-chain fee for the approve, so a short deposit fails safe (mint retries/dead-letters) rather than mis-settling. Hardening (store the fee at publish) is a follow-up.