# Phase 12 — Referral System Report

## Completion status

Phase 12 is complete. The web runtime now provides immutable first-touch referral evidence, user referral list/summary/share-link APIs, verified-task activation, risk holds, permission-scoped Admin review/settings, and atomic ledger-backed rewards.

## Delivered components

- Migration `017_harden_referral_activation.sql` adds referral versions, source-completion evidence, append-only status history, review indexes, existing-attribution backfill, and the `referrals.settings.update` permission.
- New Telegram attributions write their initial history event in the same registration transaction.
- Public referral APIs expose only the authenticated user's relationships, safe identity fields, server-derived progress, counts, posted rewards, and opaque bot share link.
- Activation reads server settings and authoritative task completions; no client activation, amount, task count, account age, or balance field is accepted.
- The qualifying completion and activation/rewards use one transaction with row locks, optimistic state checks, unique event keys, balanced ledger entries, and wallet projection rebuilding.
- Referrer and referee reward amounts can independently be positive or zero. Zero creates no artificial ledger row.
- Account/referral restrictions, non-active users, inverse referral loops, shared devices, and existing risk state fail closed to `held` without a referral payout.
- Admins can list and inspect referral evidence, approve/hold/reject pending items, and update bounded settings with per-field versions and a reason.
- Admin review cannot change attribution identity or history. Approval re-runs current risk and eligibility checks before any activation.
- Public and Admin routes inherit authentication, CSRF, Admin IP allowlisting, permission checks, rate limiting, request validation, safe errors, and audit logging from the existing runtime.

## Security and financial boundaries

- First-touch attribution remains limited to a valid referral code during a genuinely new Telegram user registration; an existing user cannot replace it.
- The schema rejects self-referral and duplicate referee attribution.
- Referral status updates use a locked row plus an expected numeric version.
- Activation stores the exact task/account-age/reward configuration snapshot and source task completion.
- Every beneficiary has one unique reward event and one idempotent ledger request.
- Rewards debit only the server referral pool and credit the selected user's available account in integer minor units.
- Risk evidence is Admin-only; public responses exclude Telegram IDs, internal IDs, device hashes, bans, and ledger internals.
- Review and settings mutations require different least-privilege permissions.
- No paid chance, purchase requirement, stake, deposit, wagering, or age-restricted mechanism is added. The future Mystery Box remains permanently constrained to free-only access.

## Verification result

The complete automated suite passes **208 of 208 tests**. Phase 12 coverage includes settings normalization and bounds, authoritative threshold evaluation, account-age/restriction checks, shared-device holds, atomic two-beneficiary rewards, source evidence, public authentication, Admin CSRF/RBAC, transactional optimistic settings, stale-write rollback, Admin approval re-evaluation, review validation, SQL parameterization, migration invariants, task-transaction integration, and every previous phase regression.

The quality gate also runs linting, formatting checks, environment-template validation, database-schema verification, CSS builds, and project-layout verification. Dependency audit, secret scanning, and release archive integrity are performed during handoff.

## Operational boundary

No live MySQL database, Telegram account, Admin account, Redis deployment, advertising provider, payment provider, or real balance was accessed or modified. Migration application and production reward configuration remain explicit operator actions after backup and target verification.

**Phase 12 status: COMPLETE AND VERIFIED.**