projectmycelium/docs/dev/design/mc-base-currency-implementation.md

MC Base Currency Implementation Plan

Overview

Switch the Mycelium marketplace from USD to MC (Mycelium Credit) as the base currency while preserving identical UX for USD users through 1:1 exchange rate.

Critical Requirements

• MC as Base: All internal calculations use MC as reference currency
• USD UX Preservation: Users selecting USD get identical experience to current system
• 1:1 Exchange Rate: 1 MC = 1 USD to maintain UX equivalence
• Backward Compatibility: No breaking changes for existing functionality

Implementation Phases

Phase 1: Core Currency Service Overhaul

• Update CurrencyService::get_supported_currencies() to make MC base currency
• Change MC is_base_currency: true and exchange_rate_to_base: dec!(1.0)
• Update USD is_base_currency: false and exchange_rate_to_base: dec!(1.0)
• Recalculate all other currency rates relative to MC (not USD)
• Update CurrencyService::get_base_currency() to return MC
• Update convert_amount() method to use MC as base reference
• Update get_exchange_rate_to_base() to use MC as base
• Update get_all_exchange_rates() to use MC as base
• Update get_currency_stats() base currency reporting

Phase 2: System-Wide Defaults Update

• Change CurrencyService default_display_currency from "USD" to "MC"
• Update user preference defaults in UserPersistentData from "USD" to "MC"
• Update model builders default currency from "USD" to "MC"
• Update controller response defaults from "USD" to "MC"
• Update template fallback values from "USD" to "MC"
• Update navbar service defaults from "USD" to "MC"

Phase 3: Service Layer Updates

• Update UserPersistence default display_currency from "USD" to "MC"
• Update AutoTopUpService USD references to use base currency
• Update InstantPurchaseService USD references to use base currency
• Update OrderService base currency references
• Update ProductService base currency handling
• Update Wallet service currency defaults
• Update PoolService token references from "USD" to base currency
• Update ResourceProvider base currency references

Phase 4: Controller Updates

• Update CurrencyController base currency responses
• Update DashboardController currency defaults and responses
• Update WalletController currency handling
• Update OrderController currency processing
• Update MarketplaceController currency defaults
• Update PoolController currency references
• Update all hardcoded "USD" strings in controller responses

Phase 5: Model Updates

• Update MarketplaceCurrencyConfig base_currency default
• Update Product model base_currency defaults
• Update Order model base currency references
• Update Transaction model currency defaults
• Update builder patterns to use MC as default
• Update all model default values from "USD" to "MC"

Phase 6: Template Updates

• Update hardcoded currency defaults in HTML templates
• Update JavaScript currency handling
• Update template variables and fallbacks
• Ensure dynamic currency selectors work with MC base

Phase 7: Testing & Validation

• Update unit tests to expect MC as base currency
• Update integration tests for currency conversions
• Test USD user experience preservation
• Validate all currency conversion accuracy
• Test edge cases and error handling
• Performance test currency operations

Phase 8: Documentation & Migration

• Update code comments referencing USD as base
• Update API documentation
• Create migration guide for existing data
• Update configuration examples
• Document exchange rate change process

UX Preservation Validation Checklist

• USD users see identical prices to current system
• Currency conversion works bidirectionally
• All formatting remains consistent
• User preferences persist correctly
• Wallet balances display correctly
• Transaction history shows correct values
• Checkout process works identically

Risk Mitigation

• Data Migration: Ensure existing user data migrates correctly
• API Compatibility: Maintain backward compatibility
• Performance: Monitor currency conversion performance
• Error Handling: Comprehensive error handling for edge cases
• Rollback Plan: Ability to rollback if issues arise

Success Criteria

• MC is the internal base currency for all calculations
• USD users experience no functional differences
• All currency conversions work accurately
• System performance remains acceptable
• All tests pass
• Documentation is updated
• No breaking changes for existing integrations

Future Considerations

• Exchange rate flexibility for future changes (1 MC = 10 USD, etc.)
• Additional currency support
• Multi-currency wallet support
• Advanced currency conversion features