feat(invite): invite/refer-a-friend + tiered referral reward payout

[islandbitcoin]

Invite / refer-a-friend + tiered referral reward payout

The full invite/refer-a-friend feature, rebased onto current main, with the reward payout implemented, comprehensive tests, and regenerated SDL. This is the backend half; the mobile client is flash-mobile#feat/invite, and an ops monitoring page is frappe-flash-admin#feat/referral-rewards-page.

Referral system (create / redeem / preview + admin)

• Public GraphQL: createInvite, redeemInvite mutations, invitePreview query. Admin: invitesList, inviteById + AdminInvite type.
• Domain + validation (src/domain/invite/), app layer (src/app/invite/), mongoose Invite model, notifications, invite-code hashing, rate limits (create + per-target).

Reward payout (this is the new part)

Pays a tiered USD reward to both the inviter and the invitee, funded from a dedicated rewards account role.

• Trigger: the invitee's Bridge KYC approval (once-only CAS transition in the Bridge KYC webhook) — they must have a US account before anything pays.
• Tiered by an atomic global counter: referrals 1–100 → $5, 101–600 → $2.50, 601+ → $1 (per party). Ops-tunable via the new referralReward config block.
• Idempotent + fail-closed: atomic claim on the invite (rewardStatus) + per-party inviter/inviteeRewardedAt. Never double-pays; the IBEX send path has no idempotency key, so the guard is at the record level. A failed/partial payout is recorded for reconciliation and never throws into or blocks KYC approval.
• Admin visibility: rewardStatus / rewardAmountCents / rewardedAt on AdminInvite.

Safety / rollout

• referralReward.enabled defaults to false — nothing pays until ops assigns a rewards wallet and flips it on. See activation steps below.
• New rewards account role added to AccountRoles, the mongoose enum, and AdminRole.

Tests

• 103 unit tests (fully mocked, no infra): 80 for the invite system (domain validation, hashing, create/redeem/rate-limits/queries/admin) + 23 for the reward payout (tier boundaries, idempotency, partial/failed, disabled, never-throw).
• tsc-check clean across the backend; admin + public GraphQL SDL regenerated.
• Not covered (follow-up): GraphQL resolver + Redis-backed rate-limiter integration tests (need test/flash/integration infra).

Activation (post-deploy, when ready to go live)

1. db.accounts.updateOne({ _id: ObjectId("<accountId>") }, { $set: { role: "rewards" } }) on the funding account (enum now permits it).
2. Fund that account's USDT wallet (the active cash wallet — payouts prefer USDT and fall back to USD; recipients are paid in the funding wallet's currency). Each top-tier referral costs $10 ($5 × 2 parties).
3. Set referralReward.enabled: true in the yaml config (tiers tunable there).
4. Mobile HTTPS invite links additionally require the getflash.io/invite landing redirect (see flash-mobile#679).

Deploy note

The new unique partial index on invites.redeemedById builds via syncIndexes() at boot. On any environment that somehow already holds two invites with the same redeemedById (none should — the feature has never shipped), the index build would fail and block startup: sweep duplicates first. Fresh/empty environments are unaffected.

Post-review hardening (Simon review, addressed)

• A crash after the payout claim can no longer strand an invisible processing row: the claim stamps rewardClaimedAt and any post-claim throw downgrades to failed with a rewardError (sweep-discoverable).
• IBEX Pending sends are now a distinct non-terminal pending status (timestamps still set — fail-closed, never double-pays) for ops re-checks instead of being counted as paid.
• Payouts resolve the USDT-first active cash wallet with strict sender/recipient currency matching.
• A tier schedule missing its unbounded sentinel now pays 0 past the last bound instead of silently over-paying forever.

🤖 Generated with Claude Code

https://claude.ai/code/session_01C7z7o9J18BWbUnYJcemMtg

[islandbitcoin]

🎤 Simon Review — backend: referral system + reward payout

Adversarial senior review. Findings traced against the actual code paths, not the diff alone.

Verdict: ACCEPTABLE

The money core is genuinely sound — no reachable double-pay, correct cents units, idempotency layered three deep (webhook event_id lock → CAS status transition → per-invite atomic claim), enabled:false default holds, and the tests assert real amounts at tier edges. It's mergeable because it ships disabled — but do not flip it on until the Should-fix items are closed, because they're all about what happens when money moves and something goes sideways.

Blocking

None.

Should fix

1. src/app/invite/award-referral-reward.ts:57 (claim) vs :178 (catch) — a crash/throw after the claim leaves the invite rewardStatus:"processing" forever, silently unpaid, and invisible to reconciliation. If nextReferralRewardSeq(), wallet resolution, or a repo call throws after the claim (or the pod is OOM-killed mid-payout), the catch only logs; the re-selection query {rewardStatus:{$exists:false}} never picks it up again, and it isn't marked failed, so ops queries for failed/partial miss it. Both parties silently never paid. Stamp rewardClaimedAt in the claim and add a sweep (or on-catch revert) that flips stale processing → failed with a rewardError. This post-claim-throw path is untested.
2. award-referral-reward.ts:139 — PaymentSendStatus.Pending is counted as paid and is terminal. IBEX returns Pending; if it later resolves to Failure, the money never lands but the invite says paid and nothing reconciles it. Treat Pending as a distinct non-terminal status a sweep re-checks, not paid.
3. award-referral-reward.ts:14 findUsdWalletId pays the legacy currency==="USD" wallet, not the user's active USDT cash wallet — and the mirror risk: if ops funds the rewards account's USDT wallet, every reward records failed: rewards account has no USD wallet. Flash is USDT-forward; recipients may never see the credit, and the runbook's "fund the USD/USDT wallet" is ambiguous enough to break every payout. Resolve to the active cash wallet (intraledgerPaymentSendWalletIdForUsdWallet already supports includeUsdt), and make the runbook explicit about which wallet.

Notes

• src/domain/invite/referral-reward.ts:20 — a tier config missing the upToCount:0 sentinel silently pays the top-tier amount forever past the last bound. Shipped default is correct; validate "last tier unbounded" at config load.
• The global seq is consumed by failed/partial/zero payouts, so "first 100 referrals" is really "first 100 approval attempts." Accounting drift, not a bug — but the ops page (Add telemetry data to the Ibex client #57) inherits it in its "Referrals Paid" tile.
• Verified non-issues: amount unit is cents (correct); redeemInvite in the unauthed block is not exploitable (resolver hard-guards on domainAccount); enabled:false can't be flipped by ajv defaults.

---

🤖 Simon-style adversarial review generated with Claude Code. Findings are advisory — verify before acting.