# USD Credits Refactor Completion Plan

## Executive Summary

The USD Credits system refactor is **75% complete** with major infrastructure in place, but **298 TFP references remain** in frontend templates and **169 in backend code**. This plan prioritizes user-facing fixes first, then backend consistency, followed by complete cleanup.

## Current State Analysis

### ✅ **Completed Successfully**
- Auto-topup system (service, API endpoints, routes)
- Buy Now functionality with auto-topup integration  
- Core currency service updated to USD default
- Main wallet UI updated to "USD Credits Wallet"
- TFP documentation converted to USD Credits documentation

### ❌ **Critical Issues Remaining**

#### Frontend Issues (298 TFP references)
- Dashboard wallet still shows "Buy TFP" buttons
- All marketplace pages show "Min Price (TFP)" filters
- Documentation overview still mentions "TFP system"
- Getting started guide references "TFP Wallet"
- Transaction displays show TFP amounts
- Charts titled "TFP Usage Trend"

#### Backend Issues (169 TFP references)
- API routes: `/wallet/buy-tfp`, `/wallet/sell-tfp`
- Transaction types: `TFPPurchase`, `TFPSale`
- Service methods: `convert_tfp_to_display_currency`
- Mock data hardcoded to TFP pricing
- Currency calculations assume TFP base

## Implementation Plan

### **PHASE 1: Critical User-Facing Fixes (Week 1)**

**Priority: IMMEDIATE - Fixes user confusion**

#### 1.1 Dashboard Wallet Page
**File**: `projectmycelium/src/views/dashboard/wallet.html`
**Changes**:
- Line 5: Change "TFP Wallet" → "Credits Wallet"
- Line 53-54: Change "Buy TFP" → "Buy Credits"
- Line 56-57: Change "Transfer TFP" → "Transfer Credits"
- Lines 217-252: Update modal titles and content
- All transaction displays: Remove "TFP" suffix

#### 1.2 Marketplace Price Filters
**Files**: All marketplace templates
**Changes**:
- `marketplace/gateways.html` lines 42, 47: "Min/Max Price (TFP)" → "Min/Max Price ($)"
- `marketplace/services.html` lines 53, 58: Same changes
- `marketplace/applications.html` lines 52, 57: Same changes
- `marketplace/three_nodes.html` lines 56, 61: Same changes
- `marketplace/compute_resources.html` lines 82: "Price Range (TFP)" → "Price Range ($)"

#### 1.3 Documentation Overview
**File**: `projectmycelium/src/views/docs/index.html`
**Changes**:
- Line 25: "TFP system" → "USD credits system"
- Line 45: "TFP transferred" → "Credits transferred"
- Lines 141-143: "Setup TFP Wallet" → "Setup Credits Wallet"
- All table entries: Replace TFP references

#### 1.4 Getting Started Guide
**File**: `projectmycelium/src/views/docs/getting_started.html`
**Changes**:
- Line 36: "Setup Your TFP Wallet" → "Setup Your Credits Wallet"
- Line 40: "ThreeFold Points (TFP)" → "USD Credits"
- Line 43: "TFP wallet" → "Credits wallet"
- Line 45: "Add TFP" → "Add Credits"

### **PHASE 2: Backend API Migration (Week 2)**

**Priority: HIGH - Ensures API consistency**

#### 2.1 Add New Credits API Endpoints
**File**: `projectmycelium/src/routes/mod.rs`
**Changes**:
```rust
// Add new credits endpoints
.route("/wallet/buy-credits", web::post().to(WalletController::buy_credits))
.route("/wallet/sell-credits", web::post().to(WalletController::sell_credits))
.route("/wallet/transfer-credits", web::post().to(WalletController::transfer_credits))

// Keep old endpoints for compatibility
.route("/wallet/buy-tfp", web::post().to(WalletController::buy_tfp)) // Deprecated
```

#### 2.2 Update Transaction Types
**File**: `projectmycelium/src/models/user.rs`
**Changes**:
```rust
// Add new transaction types
CreditsPurchase { payment_method: String },
CreditsSale { currency: String, exchange_rate: Decimal },
CreditsTransfer { to_user: String, note: Option<String> },

// Keep old types for data migration
#[deprecated]
TFPPurchase { payment_method: String },
```

#### 2.3 Update Currency Service Methods
**File**: `projectmycelium/src/services/currency.rs`
**Changes**:
```rust
// Rename methods
pub fn convert_credits_to_display_currency(...) // was convert_tfp_to_display_currency
pub fn convert_display_currency_to_credits(...) // was convert_display_currency_to_tfp
```

#### 2.4 Update Controller Methods
**File**: `projectmycelium/src/controllers/wallet.rs`
**Changes**:
- Add `buy_credits()`, `sell_credits()`, `transfer_credits()` methods
- Update request/response structs to use "credits" terminology
- Maintain backward compatibility with existing TFP endpoints

### **PHASE 3: Complete Cleanup (Week 3)**

**Priority: MEDIUM - Removes all remaining inconsistencies**

#### 3.1 All Documentation Files
**Files**: All `projectmycelium/src/views/docs/*.html`
**Changes**:
- Replace all "TFP" references with "Credits" or "USD Credits"
- Update pricing examples to show dollar amounts
- Fix all navigation links and references

#### 3.2 Legal Documents
**Files**: `projectmycelium/src/views/legal/*.html`
**Changes**:
- Update terms to reference "USD Credits" instead of TFP
- Maintain legal accuracy while updating terminology
- Update exchange rate references

#### 3.3 Dashboard and Statistics
**Files**: All dashboard templates
**Changes**:
- Chart titles: "TFP Usage" → "Credits Usage"
- Earnings displays: "TFP/month" → "$/month"
- Balance displays: Remove "TFP" suffixes
- Staking interfaces: Update to credits terminology

#### 3.4 Mock Data and Services
**Files**: `projectmycelium/src/services/mock_data.rs`, pricing services
**Changes**:
- Update hardcoded currency references
- Change default pricing to USD
- Update service pricing calculations

## Testing Strategy

### **Phase 1 Testing**
- [ ] User registration and wallet setup flow
- [ ] Marketplace browsing and price display
- [ ] Documentation navigation and clarity
- [ ] New user onboarding experience

### **Phase 2 Testing**
- [ ] API endpoint functionality (both old and new)
- [ ] Transaction creation and display
- [ ] Currency conversion accuracy
- [ ] Backward compatibility with existing data

### **Phase 3 Testing**
- [ ] Complete user journey from signup to purchase
- [ ] All documentation links and references
- [ ] Legal document accuracy
- [ ] Performance impact of changes

## Risk Mitigation

### **High Risk: User Confusion**
- **Mitigation**: Implement Phase 1 fixes immediately
- **Monitoring**: Track support tickets for TFP/Credits confusion
- **Rollback**: Maintain ability to revert terminology changes

### **Medium Risk: API Breaking Changes**
- **Mitigation**: Maintain old endpoints during transition
- **Versioning**: Add API version headers for new endpoints
- **Documentation**: Clear migration guide for API consumers

### **Low Risk: Data Migration**
- **Mitigation**: Gradual migration of transaction types
- **Backup**: Full database backup before changes
- **Validation**: Automated tests for data integrity

## Success Metrics

### **Phase 1 Success**
- Zero TFP references in user-facing wallet interface
- All marketplace prices display in USD format
- Documentation consistently uses "Credits" terminology
- User onboarding flow mentions only Credits

### **Phase 2 Success**
- New Credits API endpoints functional
- Old TFP endpoints marked deprecated but working
- All new transactions use Credits types
- Currency service methods renamed

### **Phase 3 Success**
- Zero TFP references in entire codebase
- All documentation updated and consistent
- Legal documents accurate and current
- Performance maintained or improved

## Timeline

### **Week 1: User-Facing Fixes**
- Day 1-2: Dashboard wallet updates
- Day 3-4: Marketplace price filters
- Day 5-6: Documentation overview and getting started
- Day 7: Testing and refinement

### **Week 2: Backend Migration**
- Day 8-9: New API endpoints
- Day 10-11: Transaction type updates
- Day 12-13: Currency service refactoring
- Day 14: Integration testing

### **Week 3: Complete Cleanup**
- Day 15-17: All documentation updates
- Day 18-19: Legal document updates
- Day 20-21: Dashboard and statistics cleanup
- Day 22: Final testing and deployment

## Conclusion

This plan addresses the most critical user-facing issues first while maintaining system stability. The phased approach allows for testing and validation at each stage, reducing risk while ensuring a complete transition to the USD Credits system.

The refactor is substantial but manageable, with clear priorities and measurable success criteria. Once complete, users will have a consistent, intuitive experience with clear USD pricing throughout the platform.