# Milestone v1.0: OpenFacilitator Rewards Program

**Status:** SHIPPED 2026-01-20
**Phases:** 1-11
**Total Plans:** 19

## Overview

This roadmap delivers a token rewards program where users earn $OPEN tokens for payment volume processed through OpenFacilitator. The journey starts with database foundation and auth integration, builds up address verification for both Solana and EVM chains, implements volume tracking and campaign systems, then delivers the claims flow with token distribution. With comprehensive depth (11 phases), each phase delivers a focused, verifiable capability that builds toward the complete rewards experience.

## Phases

### Phase 1: Database Foundation
**Goal**: Establish data layer for all rewards functionality
**Depends on**: Nothing (first phase)
**Requirements**: None (foundation enables all other requirements)
**Success Criteria** (what must be TRUE):
  1. Rewards-related tables exist in SQLite database (addresses, campaigns, claims, volume_snapshots)
  2. Schema supports all data relationships (user -> addresses, user -> claims, campaign -> claims)
  3. Migrations can be run idempotently without affecting existing tables
**Plans**: 1 plan

Plans:
- [x] 01-01-PLAN.md - Database schema and CRUD modules for rewards tables

### Phase 2: Auth Integration
**Goal**: Infrastructure for rewards program integrated with existing Better Auth
**Depends on**: Phase 1
**Requirements**: AUTH-02 (infrastructure), AUTH-05
**Success Criteria** (what must be TRUE):
  1. Admin users are correctly identified via ADMIN_USER_IDS config
  2. Rewards API endpoints exist (POST /enroll, GET /status) for Phase 3 consumption
  3. Dashboard displays admin badge and informational rewards banner
**Plans**: 2 plans

Plans:
- [x] 02-01-PLAN.md - Backend: admin middleware, enrollment helpers, rewards API routes
- [x] 02-02-PLAN.md - Frontend: admin badge, rewards info banner, status integration

### Phase 3: Solana Address Management
**Goal**: Users can register and prove ownership of Solana pay-to addresses
**Depends on**: Phase 2
**Requirements**: AUTH-01, AUTH-02, ADDR-01, ADDR-03
**Success Criteria** (what must be TRUE):
  1. User can add a Solana address to track for rewards (enrolls in program)
  2. User can verify Solana address ownership via message signature
  3. Unverified addresses are stored but marked as pending verification
  4. New/existing Better Auth users complete rewards enrollment by adding verified address
**Plans**: 2 plans

Plans:
- [x] 03-01-PLAN.md — Backend signature verification + Solana wallet adapter setup
- [x] 03-02-PLAN.md — Enrollment modal, address list UI, complete flow

### Phase 4: EVM Address Management
**Goal**: Users can register and prove ownership of EVM pay-to addresses
**Depends on**: Phase 2
**Requirements**: ADDR-02, ADDR-04
**Success Criteria** (what must be TRUE):
  1. User can add an EVM address to track for rewards
  2. User can verify EVM address ownership via message signature (EIP-191)
  3. Verification flow mirrors Solana experience for consistency
**Plans**: 1 plan

Plans:
- [x] 04-01-PLAN.md — EVM signature verification, wagmi provider, enrollment modal chain selector

### Phase 5: Address UI
**Goal**: Users can manage their portfolio of tracked addresses
**Depends on**: Phase 3, Phase 4
**Requirements**: ADDR-05, ADDR-06, ADDR-07
**Success Criteria** (what must be TRUE):
  1. User can view list of all tracked addresses with verification status
  2. User can remove a tracked address from their account
  3. User can track multiple addresses per account (both Solana and EVM)
  4. Address management interface is clear and usable
**Plans**: 2 plans

Plans:
- [x] 05-01-PLAN.md — Enhanced address cards with chain icons, grouping, and count display
- [x] 05-02-PLAN.md — Remove confirmation dialog and pending-only state handling

### Phase 6: Volume Tracking Engine
**Goal**: System accurately calculates qualifying volume for each user
**Depends on**: Phase 5
**Requirements**: VOL-01, VOL-02, VOL-03
**Success Criteria** (what must be TRUE):
  1. System aggregates volume from transaction logs for verified addresses only
  2. Self-transfers (same from/to address) are excluded from volume
  3. System tracks unique_payers metric per address for anti-gaming data
  4. Volume calculation is accurate and performant
**Plans**: 1 plan

Plans:
- [x] 06-01-PLAN.md — Volume aggregation service, snapshot job endpoint, user volume API

### Phase 7: Campaign System
**Goal**: Admins can create and manage reward campaigns with configurable rules
**Depends on**: Phase 6
**Requirements**: CAMP-01, CAMP-02, CAMP-03, CAMP-04, CAMP-05, CAMP-06
**Success Criteria** (what must be TRUE):
  1. System supports single active campaign at a time
  2. Campaign defines: name, pool amount, threshold, start/end dates, multiplier
  3. Admin can create new campaigns via admin interface
  4. Admin can edit campaigns before start date
  5. Users can view campaign rules explaining how rewards are calculated
  6. Users can view past campaign history with their participation stats
**Plans**: 2 plans

Plans:
- [x] 07-01-PLAN.md — Campaign data model updates, audit logging, admin/public API endpoints
- [x] 07-02-PLAN.md — Admin campaign management UI, user campaign rules display, history view

### Phase 8: Rewards Dashboard
**Goal**: Users can see their progress toward earning rewards
**Depends on**: Phase 7
**Requirements**: VOL-04, VOL-05, VOL-06, UI-03
**Success Criteria** (what must be TRUE):
  1. Dashboard displays current volume vs threshold as progress bar
  2. Dashboard displays estimated rewards based on current volume and pool share
  3. Dashboard displays days remaining in current campaign period
  4. Progress view shows volume, threshold, estimated rewards, and multiplier status
**Plans**: 1 plan

Plans:
- [x] 08-01-PLAN.md — Progress dashboard with hero progress bar, reward estimates, address breakdown

### Phase 9: Wallet Connection
**Goal**: Users can connect Solana wallet at claim time for receiving $OPEN tokens
**Depends on**: Phase 8
**Requirements**: AUTH-03
**Success Criteria** (what must be TRUE):
  1. User can connect Solana wallet (Phantom, etc.) for claiming tokens
  2. Wallet connection is ephemeral - specified per-claim, not stored permanently
  3. Claim wallet is stored on claim record for history tracking
  4. Wallet connection uses standard adapter patterns (wallet-adapter-react)
**Plans**: 1 plan

Plans:
- [x] 09-01-PLAN.md — ClaimModal, ClaimButton, initiateClaim API endpoint

### Phase 10: Claims Engine
**Goal**: Users can claim earned $OPEN tokens when eligible
**Depends on**: Phase 9
**Requirements**: CLAIM-01, CLAIM-02, CLAIM-03, CLAIM-04, CLAIM-05, CLAIM-06
**Success Criteria** (what must be TRUE):
  1. Claim button activates when threshold met AND campaign period ended
  2. System calculates proportional share of pool based on weighted volume
  3. Facilitator owners receive 2x multiplier automatically applied
  4. System executes SPL token transfer from rewards wallet on claim
  5. Dashboard shows transaction confirmation with Solana explorer link
  6. User can view claim history with status and transaction signatures
**Plans**: 3 plans

Plans:
- [x] 10-01-PLAN.md — Claim eligibility service, reward calculation, eligibility API endpoint
- [x] 10-02-PLAN.md — SPL token transfer service, execute claim endpoint, status updates
- [x] 10-03-PLAN.md — Confetti celebration, Twitter share, claim history display

### Phase 11: Dashboard Integration
**Goal**: Seamlessly integrate rewards into existing dashboard with navigation entry point, landing page for new users, and tabbed interface for enrolled users
**Depends on**: Phase 10
**Requirements**: UI-01, UI-02, UI-04, UI-05, UI-06
**Success Criteria** (what must be TRUE):
  1. Rewards tab/section added to existing dashboard navigation
  2. Landing page explains program and shows clear sign-up CTA
  3. Address management view accessible for adding/verifying/removing addresses
  4. Claim view shows amount and confirms transaction clearly
  5. History view shows past campaigns and claims with full detail
**Plans**: 3 plans

Plans:
- [x] 11-01-PLAN.md — Navigation foundation: Tabs UI component, Rewards link in WalletDropdown with claimable badge
- [x] 11-02-PLAN.md — Landing page for non-enrolled users, tabbed dashboard container for enrolled users
- [x] 11-03-PLAN.md — Tab content components (Progress, Addresses, History) wired into dashboard

## Progress

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Database Foundation | 1/1 | Complete | 2026-01-19 |
| 2. Auth Integration | 2/2 | Complete | 2026-01-19 |
| 3. Solana Address Management | 2/2 | Complete | 2026-01-20 |
| 4. EVM Address Management | 1/1 | Complete | 2026-01-19 |
| 5. Address UI | 2/2 | Complete | 2026-01-19 |
| 6. Volume Tracking Engine | 1/1 | Complete | 2026-01-20 |
| 7. Campaign System | 2/2 | Complete | 2026-01-20 |
| 8. Rewards Dashboard | 1/1 | Complete | 2026-01-20 |
| 9. Wallet Connection | 1/1 | Complete | 2026-01-20 |
| 10. Claims Engine | 3/3 | Complete | 2026-01-20 |
| 11. Dashboard Integration | 3/3 | Complete | 2026-01-20 |

## Milestone Summary

**Key Decisions:**
- D-01-01-001: Store monetary amounts as TEXT strings for precision
- D-01-01-002: Normalize EVM addresses lowercase, preserve Solana case
- D-03-01-001: 5 address limit per user
- D-06-01-001: Volume aggregation uses snapshot + live delta pattern
- D-07-01-001: Campaign status flow: draft -> published -> active -> ended
- D-09-01-001: Ephemeral wallet connection - disconnect on modal close
- D-10-02-001: Combined initiate + execute into single atomic endpoint

**Issues Resolved:**
- Wallet adapter context errors during SSR (dynamic imports with ssr: false)
- WalletNotSelectedError (separate select() and connect() calls with effect)
- Volume attribution for facilitator owners vs address-based tracking

**Technical Debt Incurred:**
- None identified in milestone audit

---
*Archived: 2026-01-20*
*For current project status, see .planning/ROADMAP.md*
