projectmycelium/docs/dev/design/archive/credits_refactor_completion_plan.md

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:

// 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:

// 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:

// 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.