OAuth claim flow

OAuth claim flow

The recipient front door is identity-first. A recipient proves the social account before choosing the wallet that will receive this and future boons.

Flow

Recipient ──▶ /claim
                │ "Connect GitHub" or "Connect X"
                ▼
        Worker /auth/{github,x}/start  (OAuth, PKCE for X)
                │
                ▼
        Provider redirect → Worker callback
                │ normalizes handle → canonical (github:alice / x:bob)
                │ reads Boon.linkNonce + Boon.linkedWallet from Base RPC
                │ refuses (409) if already linked
                ▼
        Worker signs EIP-712 Link voucher
                │ returns to app via URL fragment
                ▼
        App: user picks receiving wallet (Coinbase / MetaMask / WalletConnect)
                │
                ▼
        link() (or linkEscrowed for already-funded handles)
                │ submitted by hosted relayer if BOON_RELAYER_KEY enabled,
                │ otherwise UI fails closed
                ▼
        claim(handleHash) — permissionless; funds go only to linkedWallet
                ▼
        USDC arrives in recipient wallet on Base

Flow

1. The user opens /claim.
2. The app starts GitHub or X OAuth through the Worker.
3. The provider redirects back to the Worker callback.
4. The Worker normalizes the proven handle and creates a claim session for the app.
5. After the recipient chooses a wallet, the Worker reads live linkNonce and linkedWallet from Base and refuses if the handle is already linked.
6. The Worker signs an EIP-712 Link voucher for the chosen recipient wallet.
7. The claim UI submits link() or linkEscrowed() and then claim() through the hosted relayer when enabled.

Voucher fields

The Link voucher signs:

providerHash
handleHash
recipient
nonce
deadline

The contract domain is Boon, version 1, chain 8453, and the deployed Boon contract as verifyingContract.

Recovery boundary

The live contract includes relink() for operator-assisted recovery. Relinking can change where future boons push; it cannot move USDC already pushed to the old wallet. The public claim Worker still treats ordinary already-linked claims as a conflict.

Recipient cost

Boon does not charge recipients to view, link, or claim. If the relayer is enabled, Boon pays Base gas for link/claim. If it is not enabled, the UI should fail closed instead of asking recipients to guess at manual gas steps.