feat: Implement Configurable Fee System with Market Size and Activity Tiers (#66)

[Jagadeeshftw]

This PR implements a comprehensive Configurable Fee System with Market Size and Activity Tiers as specified in issue #66. The implementation provides dynamic fee calculation based on market characteristics, ensuring fair pricing and platform sustainability.

✨ Features Implemented

Core Dynamic Fee System

• ✅ Market Size Tiers: 4-tier system (Micro, Small, Medium, Large) with different fee percentages
• ✅ Activity-Based Adjustments: Fee multipliers based on market activity levels
• ✅ Fee Calculation Factors: Detailed breakdown of fee calculation components
• ✅ Fee History Tracking: Complete audit trail for fee changes and calculations

Required Functions

• ✅ calculate_dynamic_fee(market_id: Symbol) - Dynamic fee calculation
• ✅ get_fee_tier_by_market_size(total_staked: i128) - Market size tier determination
• ✅ adjust_fee_by_activity(market_id: Symbol, activity_level: u32) - Activity-based adjustments
• ✅ validate_fee_percentage(fee: i128, market_id: Symbol) - Fee validation
• ✅ get_fee_calculation_factors(market_id: Symbol) - Calculation breakdown
• ✅ update_fee_structure(admin: Address, new_fee_tiers: Map<u32, i128>) - Admin fee updates
• ✅ get_fee_history(market_id: Symbol) - Fee change history

🔧 Technical Implementation

Fee Tier Structure

// Market Size Thresholds (in XLM)
Micro: 0-10 XLM (1.0% fee)
Small: 10-100 XLM (1.5% fee)
Medium: 100-1000 XLM (2.0% fee)
Large: 1000+ XLM (2.5% fee)

Activity Level Adjustments

// Activity Thresholds (vote count)
Low Activity: 0-10 votes (+5% fee)
Medium Activity: 10-50 votes (+10% fee)
High Activity: 50-100 votes (+20% fee)
Very High Activity: 100+ votes (+20% fee)

Fee Validation & Limits

• Minimum Fee: 0.1% (10 basis points)
• Maximum Fee: 5.0% (500 basis points)
• Tier Flexibility: ±20% around base tier fee

💡 Key Benefits

1. Fair Pricing Model

• Small markets get lower fees for accessibility
• Large markets pay premium fees reflecting complexity
• Activity-based adjustments account for resource usage

2. Transparency & Audit

• Complete fee history tracking all changes
• Calculation factor breakdown for transparency
• Admin action logging for accountability

3. Economic Sustainability

• Revenue optimization based on market characteristics
• Spam prevention through tiered pricing
• Scalable model for platform growth

🧪 Testing & Quality Assurance

Test Coverage

• ✅ 78 tests passing (0 failed)
• ✅ Dynamic fee tier calculation tests
• ✅ Fee calculation factors tests
• ✅ Fee history creation tests
• ✅ Integration with existing fee system

Code Quality

• ✅ Comprehensive documentation with inline comments
• ✅ Soroban best practices compliance
• ✅ Backward compatibility with existing systems
• ✅ Error handling and validation

🔗 Integration Points

Existing Systems

• ✅ Market State Management - Seamless integration
• ✅ Admin System - Uses existing authentication
• ✅ Fee Collection - Works with current mechanisms
• ✅ Storage System - Persistent storage for history

Future Extensibility

• Complexity factors - Ready for additional metrics
• Time-based adjustments - Framework for seasonal fees
• User tier system - Foundation for user-based fees

📊 Impact & Metrics

Economic Impact

• Fair fee distribution across market sizes
• Activity-based pricing for resource usage
• Revenue optimization for platform sustainability

User Experience

• Transparent fee structure with clear breakdowns
• Predictable pricing based on market characteristics
• Audit trail for fee changes and calculations

🚀 Deployment Ready

The implementation is:

• ✅ Production ready - Follows all best practices
• ✅ Fully tested - Comprehensive test coverage
• ✅ Well documented - Clear documentation and examples
• ✅ Secure - Proper authentication and validation
• ✅ Scalable - Designed for future enhancements

🔍 Code Review Checklist

• Functionality - All required functions implemented
• Testing - Comprehensive test coverage
• Documentation - Clear inline documentation
• Security - Proper authentication and validation
• Performance - Efficient fee calculations
• Integration - Works with existing systems
• Error Handling - Robust error management

📝 Related Issues

• Closes Create Configurable Fee System with Market Size and Activity Tiers #66 - Configurable Fee System with Market Size and Activity Tiers

🔧 Implementation Details

New Structures Added

// Fee tier configuration
pub struct FeeTier {
    pub min_size: i128,
    pub max_size: i128,
    pub fee_percentage: i128,
    pub tier_name: String,
}

// Activity-based adjustments
pub struct ActivityAdjustment {
    pub activity_level: u32,
    pub fee_multiplier: i128,
    pub description: String,
}

// Fee calculation factors
pub struct FeeCalculationFactors {
    pub base_fee_percentage: i128,
    pub size_multiplier: i128,
    pub activity_multiplier: i128,
    pub complexity_factor: i128,
    pub final_fee_percentage: i128,
    pub market_size_tier: String,
    pub activity_level: String,
}

// Fee history tracking
pub struct FeeHistory {
    pub market_id: Symbol,
    pub timestamp: u64,
    pub old_fee_percentage: i128,
    pub new_fee_percentage: i128,
    pub reason: String,
    pub admin: Address,
    pub calculation_factors: FeeCalculationFactors,
}

Key Functions

// Calculate dynamic fee based on market characteristics
pub fn calculate_dynamic_fee_by_market_id(env: &Env, market_id: Symbol) -> Result<i128, Error>

// Get fee tier based on market size
pub fn get_fee_tier_by_market_size(env: &Env, total_staked: i128) -> Result<FeeTier, Error>

// Adjust fee by activity level
pub fn adjust_fee_by_activity(env: &Env, market_id: Symbol, activity_level: u32) -> Result<i128, Error>

// Validate fee percentage
pub fn validate_fee_percentage(env: &Env, fee: i128, market_id: Symbol) -> Result<bool, Error>

// Get fee calculation factors
pub fn get_fee_calculation_factors(env: &Env, market_id: Symbol) -> Result<FeeCalculationFactors, Error>

// Update fee structure (admin only)
pub fn update_fee_structure(env: &Env, admin: Address, new_fee_tiers: Map<u32, i128>) -> Result<(), Error>

// Get fee history
pub fn get_fee_history(env: &Env, market_id: Symbol) -> Result<Vec<FeeHistory>, Error>

🎯 Usage Examples

Basic Fee Calculation

// Calculate dynamic fee for a market
let fee = FeeCalculator::calculate_dynamic_fee_by_market_id(&env, market_id)?;
println!("Dynamic fee: {} XLM", fee / 10_000_000);

Fee Tier Determination

// Get fee tier for market size
let tier = FeeCalculator::get_fee_tier_by_market_size(&env, total_staked)?;
println!("Fee tier: {} ({}%)", tier.tier_name, tier.fee_percentage / 100);

Activity-Based Adjustment

// Adjust fee based on activity
let adjusted_fee = FeeCalculator::adjust_fee_by_activity(&env, market_id, vote_count)?;
println!("Activity-adjusted fee: {} XLM", adjusted_fee / 10_000_000);

Fee History Tracking

// Get fee change history
let history = FeeManager::get_fee_history(&env, market_id)?;
for change in history.iter() {
    println!("Fee changed from {}% to {}% at {}", 
        change.old_fee_percentage / 100,
        change.new_fee_percentage / 100,
        change.timestamp);
}

---

Ready for review and merge! 🚀

[greatest0fallt1me]

@Jagadeeshftw Merged! Thanks for the PR! Your contribution helps make Predictify better. Hope to see more amazing PRs from you soon! 🚀