# MyRxWallet Rewards UX Specification
## Sign-Up Bonus + Influencer Portal (Pre-Build)

> **STATUS: DESIGN-ONLY — HOLD PENDING CC LEGAL CLEARANCE**  
> Do NOT deploy any component of this spec to live environment until explicit CC LEGAL clearance is received.  
> All copy referencing MRT value, bonus amounts, and earning rates are PLACEHOLDER pending economic model finalization.

**Spec version:** 1.0  
**Date:** 2026-05-09  
**Compliance refs:** R22 (token disclosure), R23 (incentive program guardrails), R32 (influencer / WOMM standards), R10 (QA gate)  
**Author:** CC BUILD  

---

## Table of Contents

1. [NFT Wallet Onboarding — Welcome MRT Bonus](#1-nft-wallet-onboarding--welcome-mrt-bonus)
2. [Influencer Portal](#2-influencer-portal)
3. [Referral Attribution Flow](#3-referral-attribution-flow)
4. [Legal Hold Checklist](#4-legal-hold-checklist)
5. [Implementation Notes](#5-implementation-notes)

---

## 1. NFT Wallet Onboarding — Welcome MRT Bonus

### 1.1 Trigger

**When:** Smart contract emits `MintSuccess` event for new patient NFT wallet.  
**Actor:** New patient who has completed NFT identity credential mint.  
**Precondition:** Wallet address has never received a welcome MRT issuance (on-chain check via `welcomeBonusIssued` mapping).

---

### 1.2 Smart Contract Interface (Placeholder Spec)

```solidity
function issueWelcomeBonus(address wallet) external onlyMinter {
    require(!welcomeBonusIssued[wallet], "already issued");
    welcomeBonusIssued[wallet] = true;
    uint256 amount = WELCOME_BONUS_MRT;   // placeholder: 100 MRT (18 decimals)
    _mint(wallet, amount);
    emit WelcomeBonusIssued(wallet, amount, block.timestamp);
}
```

**Events to listen for on frontend:**
- `WelcomeBonusIssued(address indexed wallet, uint256 amount, uint256 timestamp)`

**HOLD:** WELCOME_BONUS_MRT constant TBD by economic model. Placeholder: 100 MRT.

---

### 1.3 Reveal Animation — Screen Flow

#### Step A: Mint Confirmation (existing flow — no change)

```
+-------------------------------------+
|  OK  Identity Credential Created    |
|                                     |
|  Your MyRxWallet NFT has been       |
|  minted to your wallet.             |
|                                     |
|  [View on Chain]    [Continue]      |
+-------------------------------------+
```

#### Step B: Bonus Reveal Overlay (NEW — fires after MintSuccess)

Full-screen overlay, centered, dark scrim background. Animated entry: scale from 0.8 to 1.0 + fade in (300ms cubic-bezier). Particle effect (teal + gold dots) behind the card.

```
+-----------------------------------------+
|                                         |
|     * Welcome to MyRxWallet *           |
|                                         |
|   +-----------------------------------+ |
|   |                                   | |
|   |   You've Earned                   | |
|   |                                   | |
|   |      [ counter animates ]         | |
|   |         100 MRT                   | |
|   |      ($X.XX ecosystem value)      | |  <- value PLACEHOLDER
|   |                                   | |
|   |   Added to your wallet            | |
|   |                                   | |
|   +-----------------------------------+ |
|                                         |
|   [What can I do with MRT?]             |  <- opens explainer modal
|   [Start Earning More]                  |  <- proceeds to onboarding
|                                         |
+-----------------------------------------+
```

**Animation spec:**
- MRT counter: rolls up from 0 to 100 over 1.8s (ease-out)
- Dollar value: fades in at end of counter roll
- Particle burst: 40 particles, teal (#00d5d5) + gold (#facc15), 1.2s duration
- Card: drop-shadow pulse 2x after appear

**Copy (placeholder — legal to approve):**
> **"Welcome — you've earned 100 MRT"**  
> Your MyRxWallet Rewards Token has been added to your identity wallet. MRT is a closed-loop ecosystem token redeemable for prescription savings, wellness benefits, and platform services.

**CMP / Medicare-Medicaid cap notice (conditional):**

If `patient.insuranceType` in `['Medicare', 'Medicaid', 'Dual-Eligible']` during onboarding:

```
+-----------------------------------------+
|   (i)  Benefit Cap Notice               |
|                                         |
|   As a Medicare or Medicaid             |
|   beneficiary, your annual MRT          |
|   incentive aggregate is capped at      |
|   $75/year per CMP guidelines.          |
|                                         |
|   Your current balance is within        |
|   this limit.                           |
|                                         |
|   [Learn More]                [OK]      |
+-----------------------------------------+
```

**HOLD:** $75/year CMP cap is a legal placeholder. CC LEGAL to define exact mechanics, carve-outs, and disclosure language before this notice goes live.

---

### 1.4 Onboarding Explainer Modal ("What can I do with MRT?")

Three-card horizontal scroll layout:

```
  +--------------+  +--------------+  +--------------+
  |  Prescription|  |  Wellness    |  |  Transfer    |
  |  Savings     |  |  Benefits    |  |  & Share     |
  |              |  |              |  |              |
  |  Redeem MRT  |  |  Apply MRT   |  |  Send MRT to |
  |  at partner  |  |  toward      |  |  family      |
  |  pharmacies  |  |  services    |  |  members     |
  |              |  |              |  |              |
  +--------------+  +--------------+  +--------------+
```

Footer of modal: `[Visit /redeem to see all redemption options]`

**Redemption link target:** `https://myrxwallet.io/redeem` (page TBD — link activated when redemption surface is live)

---

## 2. Influencer Portal

### 2.1 Access Gate

**Eligibility:** NFT Tier 3 Ambassador status (on-chain: `ambassador.tier >= 3`).  
**Entry point:** `https://myrxwallet.io/ambassador` (new route — HOLD, not live).  
**Auth:** Same NFT wallet auth as patient portal.

If wallet does not meet Tier 3: show upgrade path card, not a 403.

```
+-----------------------------------------------------+
|  Ambassador Portal — Tier 3 Required                |
|                                                     |
|  You are currently Tier [X].                        |
|  Tier 3 unlocks the full Ambassador dashboard,      |
|  referral link generation, and earnings tracking.   |
|                                                     |
|  [See Tier Requirements]                            |
+-----------------------------------------------------+
```

---

### 2.2 Dashboard Layout

Full-page layout. Desktop: sidebar + main panel. Mobile: bottom tab bar.

```
+----------------------------------------------------------------------+
|  MyRxWallet  [Ambassador Portal]                    [Wallet addr]   |
+------------+---------------------------------------------------------+
|            |                                                         |
| NAVIGATION |  Dashboard                                              |
| ---------  |  ----------------------------------------------         |
| Dashboard  |                                                         |
| Referrals  |  +-------------+  +-------------+  +-------------+    |
| Earnings   |  |  Total       |  |  MRT         |  |  Residuals  |   |
| 1099-NEC   |  |  Referrals  |  |  Earned      |  |  Accruing   |   |
| Assets     |  |             |  |              |  |             |   |
| Withdraw   |  |     247     |  |   4,820 MRT  |  |  +18 MRT/mo |   |
| Tax Docs   |  |  +12 this mo|  |  ($XX.XX)    |  |  (growing)  |   |
|            |  +-------------+  +-------------+  +-------------+    |
|            |                                                         |
|            |  -- Recent Activity ----------------------------        |
|            |  2026-05-09  @patient_handle signed up via your link   |
|            |  2026-05-08  Residual credit: +2.4 MRT                 |
|            |  2026-05-07  @patient_handle activated consent         |
|            |                                                         |
+------------+---------------------------------------------------------+
```

**Data model — dashboard stats (backend fields):**

| Field | Type | Source |
|-------|------|--------|
| `totalReferrals` | int | off-chain DB: `referrals` table, count by referrer_wallet |
| `mrtEarned` | uint256 | on-chain: cumulative MRT minted to wallet via referral events |
| `residualsAccruing` | decimal | off-chain: sum of open residual_ledger entries per month |
| `residualsLifetime` | decimal | off-chain: sum of all settled residual_ledger entries |
| `ytdEarnings` | decimal (USD equiv) | off-chain: aggregated for 1099-NEC |
| `recentActivity` | array | off-chain: webhook events from referral + consent + data-license flows |

---

### 2.3 Referral Link Generation

**Route:** `/ambassador/link`

```
+---------------------------------------------------------------------+
|  Your Referral Link                                                 |
|                                                                     |
|  +------------------------------------------------------------+    |
|  |  https://myrxwallet.io/ref/[WALLET_SHORT_CODE]             |    |
|  +------------------------------------------------------------+    |
|                                                                     |
|  Share:  [Twitter/X]  [LinkedIn]  [Copy Link]  [QR Code]          |
|                                                                     |
|  -- FTC Disclosure Templates -----------------------------------    |
|                                                                     |
|  Required: Add one of these disclosures to every post.             |
|                                                                     |
|  Short:  #ad #MyRxWallet — I earn rewards when you sign up.        |
|  Long:   As a MyRxWallet Ambassador, I receive MRT rewards         |
|          when you create an account through my link. #ad           |
|                                                                     |
|  [Copy Short]  [Copy Long]                                         |
|                                                                     |
|  FTC guidelines for endorsements: ftc.gov/endorsements             |
+---------------------------------------------------------------------+
```

**Link structure:** `https://myrxwallet.io/ref/{SHORT_CODE}`  
**SHORT_CODE:** base58-encoded first 8 bytes of referrer wallet address (deterministic, no DB lookup for decode)  
**Attribution cookie:** `mrx_ref={wallet_address}`, 30-day expiry, SameSite=Lax  
**On mint:** referrer wallet address written to NFT metadata field `referredBy` (immutable)

---

### 2.4 Earnings Tab

```
+---------------------------------------------------------------------+
|  Earnings                                                           |
|                                                                     |
|  -- Sign-Up Commissions -----------------------------------------  |
|  Per referral who completes NFT mint:        [XX MRT]  PLACEHOLDER |
|  Per referral who activates consent:         [XX MRT]  PLACEHOLDER |
|  Per referral first data licensing event:    [XX MRT]  PLACEHOLDER |
|                                                                     |
|  -- Residual Stream ---------------------------------------------   |
|  Per active referred patient data event:  [X% of license fee]      |
|  Accrual frequency:                       Monthly settlement        |
|  Accrual ceiling per patient per year:    CC LEGAL HOLD            |
|                                                                     |
|  -- YTD Earnings (2026) -----------------------------------------  |
|  Total MRT earned:           4,820 MRT                              |
|  USD equivalent (est.):      $XXX.XX  <- PLACEHOLDER rate          |
|  1099-NEC threshold:         $600                                   |
|  Current YTD vs threshold:   ######....  [XX%]                     |
|                                                                     |
|  If YTD earnings exceed $600 USD equivalent, a 1099-NEC            |
|  will be issued by Jan 31 of the following tax year.               |
+---------------------------------------------------------------------+
```

---

### 2.5 1099-NEC Year-to-Date Tracker

```
+---------------------------------------------------------------------+
|  1099-NEC Tracker                                                   |
|                                                                     |
|  Tax Year: [2026]                                                   |
|                                                                     |
|  +-----------+----------+----------+-------------+------------+    |
|  |  Month    |  Events  |  MRT     |  USD Equiv  |  Cumulative|    |
|  +-----------+----------+----------+-------------+------------+    |
|  |  Jan 2026 |     12   |  480 MRT |   $XX.XX    |   $XX.XX   |    |
|  |  Feb 2026 |      9   |  360 MRT |   $XX.XX    |   $XX.XX   |    |
|  |  Mar 2026 |     18   |  720 MRT |   $XX.XX    |   $XX.XX   |    |
|  |  Apr 2026 |     22   |  880 MRT |   $XX.XX    |   $XX.XX   |    |
|  |  May 2026 |      6   |  240 MRT |   $XX.XX    |   $XX.XX   |    |
|  +-----------+----------+----------+-------------+------------+    |
|                                                                     |
|  MRT to USD conversion rate: Determined at settlement date          |
|  [Download YTD Statement PDF]    [Download Prior Year 1099-NEC]    |
+---------------------------------------------------------------------+
```

**1099-NEC PDF fields required:**
- Box 1: Nonemployee compensation (USD equivalent of MRT, at settlement rate)
- Payer: MyRxWallet North America Corporation, EIN: [HOLD — legal to confirm]
- Recipient: Ambassador legal name + SSN/TIN (collected at Tier 3 upgrade KYC gate)
- Tax Year, issue date

**HOLD:** MRT to USD conversion rate methodology requires CC LEGAL approval (fair market value vs. internal rate vs. date-of-receipt rate per IRS guidance).

---

### 2.6 Brand Asset Library

```
+---------------------------------------------------------------------+
|  Brand Assets                                                       |
|                                                                     |
|  -- Approved for Ambassador Use ---------------------------------   |
|                                                                     |
|  Logo Variations                                                    |
|  [Full Color]  [Dark Mode]  [Light Mode]  [Icon Only]              |
|                                                                     |
|  Story / Square Templates (pre-branded with #ad)                   |
|  [Instagram Story]  [Twitter Card]  [LinkedIn]                     |
|                                                                     |
|  Approved Copy Blocks                                               |
|  [Patient Benefits]  [Security Copy]  [Feature Copy]               |
|                                                                     |
|  All assets carry embedded metadata. Do not crop, alter            |
|  colors, or combine with non-approved imagery. FTC disclosure       |
|  must accompany every post featuring these assets.                  |
+---------------------------------------------------------------------+
```

Asset file locations (to be populated): `/opt/myrxwallet_home/assets/ambassador/`  
Formats: PNG (2x), SVG, PDF (print), social JSON templates

---

### 2.7 Withdrawal / Transfer

```
+---------------------------------------------------------------------+
|  Transfer MRT                                                       |
|                                                                     |
|  Available balance:  4,820 MRT                                      |
|  Transferable to:    Ecosystem participants only                    |
|                                                                     |
|  Recipient wallet address:  [__________________________]           |
|  Amount:                    [__________________________] MRT        |
|                                                                     |
|  -- Eligible recipient types ------------------------------------   |
|  OK  Other MyRxWallet patient wallets                               |
|  OK  Provider wallets (within ecosystem)                            |
|  OK  Pharmacy partner wallets (for Rx savings redemption)           |
|  NO  External wallets / exchanges (closed-loop restriction)         |
|                                                                     |
|  [Preview Transfer]  [Cancel]                                       |
|                                                                     |
|  MRT is a closed-loop ecosystem token. Transfer to external         |
|  wallets or conversion to fiat is not supported.                   |
|  Contact: support@myrxwallet.io                                     |
+---------------------------------------------------------------------+
```

**Closed-loop enforcement (backend):**
- Transfer recipient must be registered wallet in `myrx_wallets` table
- Smart contract `transfer()` override: whitelist-only recipient check via `isEcosystemWallet(address)` mapping
- Any transfer outside ecosystem reverts with `TransferRestrictedToEcosystem` error

---

## 3. Referral Attribution Flow

### 3.1 On-Chain Attribution

**NFT Mint Metadata Schema (additions):**

```json
{
  "name": "MyRxWallet Identity Credential",
  "wallet_address": "0x...",
  "mint_timestamp": 1746777600,
  "referredBy": "0x...",
  "referralCode": "mrx_ref_XXXXXXXX",
  "bonusIssued": true,
  "bonusAmount": "100000000000000000000"
}
```

Notes:
- `referredBy`: referrer wallet address (0x000...000 if organic)
- `bonusAmount`: 100 MRT in wei (18 decimals)
- `referredBy` written at mint time, cannot be changed after — immutable proof of attribution

---

### 3.2 Off-Chain Attribution Events

**Backend event ledger table (`referral_events`):**

```sql
CREATE TABLE referral_events (
    id              BIGSERIAL PRIMARY KEY,
    referrer_wallet VARCHAR(42) NOT NULL,
    referee_wallet  VARCHAR(42) NOT NULL,
    event_type      VARCHAR(64) NOT NULL,
    -- event_type values: signup, nft_mint, consent_activated,
    --   data_license_first, data_license_recurring
    event_ts        TIMESTAMPTZ DEFAULT NOW(),
    mrt_credited    NUMERIC(28,8),
    usd_equiv       NUMERIC(10,4),
    tx_hash         VARCHAR(66),
    settled         BOOLEAN DEFAULT FALSE,
    settlement_ts   TIMESTAMPTZ
);

CREATE INDEX ON referral_events(referrer_wallet);
CREATE INDEX ON referral_events(referee_wallet);
CREATE INDEX ON referral_events(event_type, settled);
```

**Event triggers:**
1. `signup` — patient creates account with `?ref=` param in URL
2. `nft_mint` — patient NFT minted, `referredBy` populated
3. `consent_activated` — patient completes data consent form
4. `data_license_first` — first data licensing royalty event fires for patient
5. `data_license_recurring` — monthly data licensing events (residual stream)

---

### 3.3 Anti-Sybil Measures

| Layer | Method | Implementation |
|-------|--------|----------------|
| IP check | Same-IP self-referral block | At `/ref/{code}` resolution: log IP; if referrer IP == referee signup IP, require CAPTCHA and flag |
| KYC dedup | Identity match check | At Tier 3 upgrade KYC: cross-check referrer name/DOB/address against referee; flag if 2+ fields match |
| Wallet dedup | One bonus per wallet | Smart contract `welcomeBonusIssued[wallet]` mapping; `referee_wallet` UNIQUE constraint in referral_events |
| Velocity cap | Max referrals per day | Rate limit: no more than 50 referral attributions per referrer wallet per 24h window |
| Delay gate | Prevent instant circular referral | Commission credited only after referee completes 30-day active period |

---

### 3.4 Residual Calculation Model (Placeholder)

**HOLD:** Exact residual rates TBD by economic model + CC LEGAL clearance.

**Placeholder model (for spec purposes only):**

```
residual_per_event = data_license_fee_received
                   x [RESIDUAL_RATE_PCT]         <- CC LEGAL to define
                   x (1 - platform_take_rate)    <- economics model to define
                   x decay_factor(years_since_referral)

decay_factor:
  years 0-2:  1.0  (full rate)
  years 3-5:  0.5  (half rate)
  after year 5: 0  (or flat — CC LEGAL to decide)
```

Monthly settlement: residual_ledger entries aggregated on 1st of each month, MRT minted to referrer wallet, event marked settled.

---

## 4. Legal Hold Checklist

All items below require CC LEGAL sign-off before any component goes live:

- [ ] Welcome MRT bonus amount — economic model to set WELCOME_BONUS_MRT constant
- [ ] Dollar value disclosure — MRT ecosystem value methodology (not a securities representation)
- [ ] CMP cap mechanics — $75/year aggregate cap exact definition, carve-outs, disclosure language
- [ ] Residual rate structure — exact percentages, decay schedule, CMP implications
- [ ] 1099-NEC methodology — MRT to USD FMV conversion method per IRS guidance
- [ ] EIN for 1099 payer — confirm legal entity and EIN for 1099-NEC issuance
- [ ] FTC disclosure templates — legal review of copy before ambassador use
- [ ] Closed-loop definition — legal definition of "ecosystem" for transfer whitelist
- [ ] Ambassador agreement — T&C for Tier 3 ambassadors before portal access
- [ ] Anti-Sybil policy — written policy on referral fraud consequences
- [ ] KYC at Tier 3 gate — SSN/TIN collection flow, data retention policy
- [ ] State-by-state compliance — referral/WOMM restrictions vary by state (healthcare context)

---

## 5. Implementation Notes

### 5.1 File / Route Map (pre-build targets)

| Surface | Route | File | Status |
|---------|-------|------|--------|
| Referral landing | `/ref/{code}` | `/opt/myrxwallet_home/ref.html` + nginx redirect rule | HOLD |
| Redemption page | `/redeem` | `/opt/myrxwallet_home/redeem.html` | HOLD |
| Ambassador portal | `/ambassador` | `/opt/myrxwallet_home/ambassador.html` | HOLD |
| Ambassador referrals | `/ambassador/link` | Section of ambassador.html | HOLD |
| Ambassador earnings | `/ambassador/earnings` | Section of ambassador.html | HOLD |
| Ambassador 1099 | `/ambassador/tax` | Section of ambassador.html | HOLD |
| Ambassador assets | `/ambassador/assets` | Section of ambassador.html | HOLD |
| Onboarding modal | (patient portal component) | `portal_sections/RewardsBonusModal.py` | HOLD |

### 5.2 Backend Endpoints (to be built)

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `/api/rewards/welcome-status` | GET | wallet JWT | Returns welcome bonus status + amount |
| `/api/rewards/referral-link` | GET | wallet JWT + Tier 3 | Returns referral short code |
| `/api/rewards/dashboard` | GET | wallet JWT + Tier 3 | Returns all dashboard stats |
| `/api/rewards/referral-events` | GET | wallet JWT + Tier 3 | Paginated event ledger |
| `/api/rewards/transfer` | POST | wallet JWT + sig | Initiates MRT transfer (ecosystem-only) |
| `/api/rewards/1099/ytd` | GET | wallet JWT + Tier 3 | YTD earnings data |
| `/api/rewards/1099/pdf/{year}` | GET | wallet JWT + Tier 3 | 1099-NEC PDF download |
| `/api/ref/{code}` | GET | none | Resolve referral code, set attribution cookie |

### 5.3 Dependencies

- Chaincode: MRT token contract with `issueWelcomeBonus()`, `isEcosystemWallet()`, transfer whitelist override
- Patient portal: `RewardsBonusModal` section (new portal section, added via `add_section.py`)
- KYC: Tier 3 upgrade gate with SSN/TIN collection (separate CC LEGAL clearance required)
- PDF generation: wkhtmltopdf or ReportLab for 1099-NEC (VPS Python env already available)
- Anti-Sybil: IP logging middleware + KYC cross-check service

### 5.4 Compliance Notes (R22 / R23 / R32 / R10)

- **R22 (Token disclosure):** All MRT value representations labeled "ecosystem value" with explicit non-securities disclaimer. USD equivalents labeled as estimates, not guarantees.
- **R23 (Incentive guardrails):** CMP cap check required at every bonus issuance. Backend must verify aggregate annual incentive does not exceed CC LEGAL threshold for CMS beneficiaries before minting.
- **R32 (WOMM / influencer standards):** FTC disclosure templates mandatory for all ambassador-generated content. Templates pre-populated in portal; ambassador must acknowledge disclosure before any referral link share action.
- **R10 (QA gate):** Full QA pass required before any production deployment — mobile + desktop, dark + light mode, wallet connected + disconnected states, Tier 3 and non-Tier 3 wallet access paths.

---

*End of spec — DESIGN ONLY — CC LEGAL clearance required before any live deployment*