# Milestone v1.2: Subscription Wallet Overhaul

**Status:** SHIPPED 2026-01-23
**Phases:** 17-21
**Total Plans:** 13

## Overview

Replace confusing legacy embedded wallet with a dedicated Subscriptions section supporting dual-chain (Base + Solana) recurring payments.

## Phases

### Phase 17: UI Cleanup & Subscriptions Section

**Goal:** Users see a clean header without legacy wallet and can access a new Subscriptions section in the dashboard.

**Dependencies:** None (foundation phase)

**Requirements:** UICL-01, UICL-02, UICL-03, SUBD-01, SUBD-02, SUBD-03, SUBD-04, SUBD-05

**Plans:** 3 plans

Plans:
- [x] 17-01-PLAN.md — Replace WalletDropdown with UserMenu in header
- [x] 17-02-PLAN.md — Add payment history API endpoint
- [x] 17-03-PLAN.md — Create Subscriptions page with status, billing, and history

**Success Criteria:**

1. User sees header without any wallet connection button or embedded wallet UI
2. User can navigate to Subscriptions tab in dashboard sidebar
3. User sees their subscription status (active/inactive/pending) on the Subscriptions page
4. User sees next billing date, subscription tier, and pricing information
5. User can view payment history with date, amount, chain, and transaction hash

---

### Phase 18: Multi-Chain Wallet Infrastructure

**Goal:** Users have both Base and Solana wallets available for subscription payments with visible addresses for funding.

**Dependencies:** Phase 17 (Subscriptions section exists)

**Requirements:** WALL-01, WALL-02, WALL-03, WALL-04

**Plans:** 2 plans

Plans:
- [x] 18-01-PLAN.md — Backend multi-wallet infrastructure (DB + API endpoints)
- [x] 18-02-PLAN.md — Frontend wallet cards UI with balance, copy, refresh

**Success Criteria:**

1. User sees both a Base wallet and Solana wallet in the Subscriptions section
2. Each wallet displays current balance with chain identifier (Base/Solana)
3. User can copy wallet addresses directly for external funding
4. User sees balance update in real-time after funding a wallet

---

### Phase 19: Chain Preference Logic

**Goal:** Users can set their preferred payment chain with intelligent defaults and fallback behavior.

**Dependencies:** Phase 18 (Multi-chain wallets exist)

**Requirements:** PREF-01, PREF-02, PREF-03

**Plans:** 2 plans

Plans:
- [x] 19-01-PLAN.md — Backend preference storage, API endpoints, default calculation
- [x] 19-02-PLAN.md — Toggle UI with optimistic updates, WalletCards integration

**Success Criteria:**

1. User who initially paid via Base sees Base as default preferred chain
2. User can toggle between Base and Solana preference via prominent switch in Subscriptions section
3. When preferred chain has insufficient balance, system attempts alternate chain before failing

---

### Phase 20: Recurring Payment Engine

**Goal:** Subscriptions auto-renew daily with graceful handling of insufficient funds.

**Dependencies:** Phase 18 (Wallets), Phase 19 (Chain preference)

**Requirements:** RECR-01, RECR-02, RECR-03, RECR-04, RECR-05, RECR-06

**Plans:** 4 plans

Plans:
- [x] 20-01-PLAN.md — Payment database layer and billing service with fallback logic
- [x] 20-02-PLAN.md — Billing cron endpoint and grace period management
- [x] 20-03-PLAN.md — Frontend grace period UI, CSV export, enhanced payment history
- [x] 20-04-PLAN.md — Base chain x402 payment support (gap closure)

**Success Criteria:**

1. User with sufficient balance sees subscription auto-renewed daily without manual action
2. User with insufficient preferred chain balance sees payment attempted from alternate chain
3. User with insufficient funds on both chains enters 7-day grace period before service suspension
4. User sees payment status as "pending" when both wallets have insufficient funds
5. User can view all subscription payments in history with transaction details and chain used

---

### Phase 21: Notifications & Edge Cases

**Goal:** Users receive timely notifications about payment status and subscription health.

**Dependencies:** Phase 20 (Payment engine generates events)

**Requirements:** NOTF-01, NOTF-02, NOTF-03, NOTF-04

**Plans:** 2 plans

Plans:
- [x] 21-01-PLAN.md — Backend notification infrastructure (DB, API, billing integration)
- [x] 21-02-PLAN.md — Frontend notification center (bell icon, popover, components)

**Success Criteria:**

1. User sees confirmation notification when subscription payment succeeds
2. User sees low balance warning when balance drops below 2x subscription cost
3. User sees alert when payment fails due to insufficient funds
4. User receives reminder notification 3 days before subscription expires

---

## Milestone Summary

**Key Decisions:**

- Show wallet addresses directly (power user friendly)
- 7-day grace period (industry standard)
- Pre-fund any amount (user flexibility)
- No mid-cycle refunds (simplicity)
- Prominent chain preference toggle (discoverability)
- Four subscription states: active (green), pending (amber), inactive (red), never (gray)
- Side-by-side wallet cards (Base first, Solana second)
- Manual balance refresh only (no auto-polling)
- Default preference calculation: payment history > wallet balance > solana
- Blue for Base toggle, purple for Solana toggle (chain branding)
- Optimistic UI updates with rollback on error (responsive feel)
- Log all payment attempts (not just successes) for debugging
- Billing cron uses x-cron-secret header (matches rewards.ts pattern)
- NotificationType enum covers 6 event types
- Low balance threshold: $10 (2x subscription cost)
- Duplicate notification prevention: 24h/72h windows

**Issues Resolved:**

- Legacy wallet confusion eliminated
- Multi-chain payment support added
- Graceful degradation for insufficient funds

**Technical Debt Incurred:**

- node-cron runs in-process (consider external scheduler for scale)
- pino-pretty warning from WalletConnect (cosmetic)

---

*For current project status, see .planning/ROADMAP.md*
*Archived: 2026-01-23 as part of v1.2 milestone completion*
