miracle_api/

lib.rs

pub mod calculations;
pub mod consts;
pub mod dmt;
pub mod error;
pub mod event;
pub mod instruction;
pub mod loaders;
pub mod sdk;
pub mod state;
pub mod utils;

// Re-export helper functions for easier access
pub use consts::{calculate_daily_rewards, BASE_DAILY_REWARDS};

pub use calculations::{
    calculate_community_score, calculate_smooth_community_decay, calculate_time_decay,
    calculate_weighted_geometric_mean,
};

pub mod prelude {
    // Core modules
    pub use crate::dmt::*;
    pub use crate::error::*;
    pub use crate::event::*;
    pub use crate::instruction::*;
    pub use crate::loaders::*;
    pub use crate::state::*;

    // SDK functions (primary source for user-facing functions)
    pub use crate::sdk::*;

    // Merkle tree types and helpers for off-chain processors
    pub use crate::sdk::{
        create_participant_from_wallet, find_participant_by_wallet, find_participant_index,
        generate_proof_for_wallet, sort_participants_by_id, wallet_to_participant_id, MerkleProof,
        MerkleTree,
    };

    // Consts functions (only the ones not duplicated in SDK)
    pub use crate::consts::{
        calculate_daily_rewards, calculate_daily_rewards_split, BASE_DAILY_REWARDS, BASIS_POINTS,
        EPOCH_DURATION, MAX_PAYMENT_PROOF_LENGTH, MAX_SEAL_PROOF_LENGTH, MAX_SUPPLY, ONE_MIRACLE,
        TEN_MIRACLE,
    };

    // Calculations functions
    pub use crate::calculations::{
        calculate_community_score, calculate_smooth_community_decay, calculate_time_decay,
        calculate_weighted_geometric_mean,
    };

    // Utility functions for data conversion and validation
    pub use crate::utils::*;
}

use steel::*;

// // Mainnet Formal Miracle Program ID
// declare_id!("mp2ept1LF9cBM5z2wBn45xF1BjX2haSEiu3LQhAksYz");

// Devnet Test Program ID
// 0_rnd
// declare_id!("FiVwirA2beubPcFPGGZMYju8qgKwg6V8QtNSU8acwGvy");
// 1_rnd
declare_id!("1stNeamE9aWAxA1bvN6h659hYZP6BKPZuLirNUwPcPD");

#[cfg(test)]
mod tests {
    use super::*;
    use crate::calculations::{
        calculate_community_score, calculate_smooth_community_decay, calculate_time_decay,
        calculate_weighted_geometric_mean,
    };
    use crate::consts::{calculate_daily_rewards, BASE_DAILY_REWARDS};
    use crate::state::{ActivityLimits, CommunityTargets, Config, SocialMarketingConfig};

    // Helper function to create a test config
    fn create_test_config() -> Config {
        Config {
            last_reset_at: 0,
            // evolver: solana_program::pubkey::Pubkey::default(),
            // evolvable: 0,
            claim_rewards_threshold: BASE_DAILY_REWARDS,
            oracle_authority: solana_program::pubkey::Pubkey::default(),
            community_targets: CommunityTargets {
                target_weekly_users: 10000,
                target_weekly_activity: 50000,
                target_retention_rate: 7000,
                _padding: [0u8; 6],
            },
            activity_limits: ActivityLimits {
                max_customer_activity_per_epoch: 5,
                max_merchant_activity_per_epoch: 50,
                activity_cap_enabled: 1,
                claim_cap_enabled: 1,
                _padding: [0u8; 6],
            },
            social_marketing: SocialMarketingConfig {
                rewards_pool: 9_000_000_000_000,  // Initial value
                daily_limit_per_user: 1,          // Simple rule: 1 social claim per epoch per user
                base_reward_per_post: 10_000_000, // Initial value
                oracle_authority: solana_program::pubkey::Pubkey::default(),
                // _padding: [0u8; 0],
            },
            // Note: Pool tracking fields removed from Config - now tracked in Snapshot and Treasury
        }
    }

    #[test]
    fn test_id() {
        assert_eq!(id(), ID);
    }

    #[test]
    fn test_community_metrics_size() {
        use state::Metrics;
        assert_eq!(std::mem::size_of::<Metrics>(), 32);
    }

    #[test]
    fn test_community_metrics_event_size() {
        use event::MetricsUpdatedEvent;
        assert_eq!(std::mem::size_of::<MetricsUpdatedEvent>(), 32);
    }

    // ===== ENHANCED SMOOTH DECAY TESTS =====

    #[test]
    fn test_smooth_community_decay() {
        // Test boundary conditions
        assert_eq!(calculate_smooth_community_decay(0), 10000); // 100% rewards (struggling)
        assert_eq!(calculate_smooth_community_decay(10000), 5000); // 50% rewards (healthy)

        // Test middle values
        let mid_decay = calculate_smooth_community_decay(5000);
        assert!(mid_decay >= 5000 && mid_decay <= 10000); // Between 50% and 100%

        // Test smoothness (no sharp cliffs)
        let decay_7999 = calculate_smooth_community_decay(7999);
        let decay_8000 = calculate_smooth_community_decay(8000);
        let decay_8001 = calculate_smooth_community_decay(8001);

        // Should be smooth, not binary (allow for integer rounding)
        assert!(decay_7999 >= decay_8000);
        assert!(decay_8000 >= decay_8001);
        assert!(decay_7999 - decay_8000 <= 10); // Very small difference due to integer math
        assert!(decay_8000 - decay_8001 <= 10); // Very small difference due to integer math
    }

    #[test]
    fn test_daily_rewards() {
        let base_rewards = BASE_DAILY_REWARDS; // 100,000 MIRACLE

        // Test boundary conditions
        let expected_0 = (base_rewards as u128)
            .saturating_mul(calculate_smooth_community_decay(0) as u128)
            .saturating_mul(calculate_time_decay(0) as u128)
            .saturating_div(100_000_000u128) as u64;
        assert_eq!(calculate_daily_rewards(0, 0), expected_0); // 100% rewards

        let expected_100 = (base_rewards as u128)
            .saturating_mul(calculate_smooth_community_decay(10000) as u128)
            .saturating_mul(calculate_time_decay(0) as u128)
            .saturating_div(100_000_000u128) as u64;
        assert_eq!(calculate_daily_rewards(10000, 0), expected_100); // 60% rewards

        // Test middle values
        let mid_rewards = calculate_daily_rewards(5000, 0);
        assert!(mid_rewards > expected_100); // More than 60%
        assert!(mid_rewards <= base_rewards); // Less than or equal to 100%

        // Test smoothness compared to legacy
        let rewards_7999 = calculate_daily_rewards(7999, 0);
        let rewards_8000 = calculate_daily_rewards(8000, 0);

        // New function should be smooth, not binary (allow for integer rounding)
        assert!(rewards_7999 >= rewards_8000); // Smooth transition
    }

    #[test]
    fn test_smooth_decay_formula_verification() {
        // Verify the smooth decay formula works as expected
        // Formula: 0.5 + 0.5 * (1 - (score/10000)^2)

        // At score = 0: 0.5 + 0.5 * (1 - 0) = 1.0
        assert_eq!(calculate_smooth_community_decay(0), 10000);

        // At score = 10000: 0.5 + 0.5 * (1 - 1) = 0.5
        assert_eq!(calculate_smooth_community_decay(10000), 5000);

        // At score = 5000: 0.5 + 0.5 * (1 - 0.25) = 0.5 + 0.5 * 0.75 = 0.875
        let expected_5000 = (0.875 * 10000.0) as u64;
        let actual_5000 = calculate_smooth_community_decay(5000);
        assert!(actual_5000 >= expected_5000 - 100 && actual_5000 <= expected_5000 + 100);

        // Verify the formula step by step for score = 5000
        let score = 5000u64;
        let score_squared = score * score; // 25,000,000
        let score_ratio_squared_in_bps = score_squared / 10000; // 2,500
        let quadratic_component = 10000 - score_ratio_squared_in_bps; // 7,500
        let decay_component = quadratic_component * 5000 / 10000; // 3,750
        let expected = 5000 + decay_component; // 8,750
        let actual = calculate_smooth_community_decay(5000);
        assert_eq!(actual, expected);

        // Verify the formula step by step for score = 3000
        let score = 3000u64;
        let score_squared = score * score; // 9,000,000
        let score_ratio_squared_in_bps = score_squared / 10000; // 900
        let quadratic_component = 10000 - score_ratio_squared_in_bps; // 9,100
        let decay_component = quadratic_component * 5000 / 10000; // 4,550
        let expected = 5000 + decay_component; // 9,550
        let actual = calculate_smooth_community_decay(3000);
        assert_eq!(actual, expected);
    }

    #[test]
    fn test_weighted_geometric_mean() {
        let scores = [5000u16, 7000u16, 9000u16]; // 50%, 70%, 90%

        // Test equal weights
        let equal_weights = [3333u16, 3333u16, 3334u16]; // ~33.33% each
        let result = calculate_weighted_geometric_mean(scores, equal_weights);
        // Geometric mean: ∛(5000 × 7000 × 9000) ≈ 6805
        assert!(result >= 6800 && result <= 6810);

        // Test zero weights
        let zero_weights = [0u16, 0u16, 0u16];
        let result_zero = calculate_weighted_geometric_mean(scores, zero_weights);
        assert_eq!(result_zero, 0);

        // Test single weight
        let single_weight = [10000u16, 0u16, 0u16];
        let result_single = calculate_weighted_geometric_mean(scores, single_weight);
        assert_eq!(result_single, 5000);

        // Test zero scores (geometric mean of zero is zero)
        let zero_scores = [0u16, 7000u16, 9000u16];
        let result_zero_score = calculate_weighted_geometric_mean(zero_scores, equal_weights);
        assert_eq!(result_zero_score, 0);

        // Test geometric mean vs arithmetic mean behavior
        let mixed_scores = [1000u16, 5000u16, 9000u16]; // Poor, medium, good
        let arithmetic_result = (1000 + 5000 + 9000) / 3; // = 5000
        let geometric_result = calculate_weighted_geometric_mean(mixed_scores, equal_weights);
        // Geometric mean should be lower than arithmetic mean for mixed scores
        assert!(geometric_result < arithmetic_result);
    }

    #[test]
    fn test_geometric_vs_arithmetic_mean_behavior() {
        // Test case 1: Balanced scores (should be similar)
        let balanced_scores = [6000u16, 7000u16, 8000u16];
        let equal_weights = [3333u16, 3333u16, 3334u16];

        let _arithmetic_mean = (6000 + 7000 + 8000) / 3; // = 7000
        let geometric_mean = calculate_weighted_geometric_mean(balanced_scores, equal_weights);

        // For balanced scores, geometric mean should be close to arithmetic mean
        assert!(geometric_mean >= 6900 && geometric_mean <= 7100);

        // Test case 2: Mixed scores (geometric mean should be lower)
        let mixed_scores = [1000u16, 5000u16, 9000u16]; // Poor, medium, good
        let arithmetic_mean_mixed = (1000 + 5000 + 9000) / 3; // = 5000
        let geometric_mean_mixed = calculate_weighted_geometric_mean(mixed_scores, equal_weights);

        // Geometric mean should be significantly lower than arithmetic mean
        assert!(geometric_mean_mixed < arithmetic_mean_mixed);
        assert!(geometric_mean_mixed >= 2000 && geometric_mean_mixed <= 4000);

        // Test case 3: Very poor performance in one metric
        let poor_performance = [500u16, 8000u16, 9000u16]; // Very poor, good, good
        let arithmetic_mean_poor = (500 + 8000 + 9000) / 3; // = 5833
        let geometric_mean_poor =
            calculate_weighted_geometric_mean(poor_performance, equal_weights);

        // Geometric mean should heavily penalize the poor performance
        assert!(geometric_mean_poor < arithmetic_mean_poor);
        assert!(geometric_mean_poor < 4000); // Should be much lower

        // Test case 4: Zero score (should return zero)
        let zero_score = [0u16, 8000u16, 9000u16];
        let geometric_mean_zero = calculate_weighted_geometric_mean(zero_score, equal_weights);
        assert_eq!(geometric_mean_zero, 0);
    }

    #[test]
    fn test_community_score_with_weights() {
        let config = create_test_config();

        // Test with oracle-provided weights
        let score = calculate_community_score(&config, 5000, 25000, 5000, 6000, 3000, 1000);
        assert!(score > 0 && score <= 10000);

        // Test with different weight combinations
        let score = calculate_community_score(&config, 5000, 25000, 5000, 4000, 3500, 2500);
        assert!(score > 0 && score <= 10000);

        // Test with maturity weights
        let score = calculate_community_score(&config, 5000, 25000, 5000, 3000, 3000, 4000);
        assert!(score > 0 && score <= 10000);
    }

    #[test]
    fn test_time_decay() {
        // 0 years since launch: 100%
        assert_eq!(calculate_time_decay(0), 10000);
        // 1 year: 82%
        assert_eq!(calculate_time_decay(1), 8200);
        // 3 years: 46%
        assert_eq!(calculate_time_decay(3), 4600);
        // 5 years: 10%
        assert_eq!(calculate_time_decay(5), 1000);
        // 10 years: 10% (minimum)
        assert_eq!(calculate_time_decay(10), 1000);
    }

    #[test]
    fn test_daily_rewards_with_time_decay() {
        let base = BASE_DAILY_REWARDS;
        // 100% community, 0 years: 30% * 100% = 30%
        let r1 = calculate_daily_rewards(10000, 0);
        let expected1 = (base as u128)
            .saturating_mul(calculate_smooth_community_decay(10000) as u128)
            .saturating_mul(calculate_time_decay(0) as u128)
            .saturating_div(100_000_000u128) as u64;
        assert_eq!(r1, expected1);
        // 100% community, 5 years: 30% * 10% = 3%
        let r2 = calculate_daily_rewards(10000, 5);
        let expected2 = (base as u128)
            .saturating_mul(calculate_smooth_community_decay(10000) as u128)
            .saturating_mul(calculate_time_decay(5) as u128)
            .saturating_div(100_000_000u128) as u64;
        assert_eq!(r2, expected2);
        // 50% community, 3 years: ~82.5% * 46% = ~37.95%
        let r3 = calculate_daily_rewards(5000, 3);
        let expected3 = (base as u128)
            .saturating_mul(calculate_smooth_community_decay(5000) as u128)
            .saturating_mul(calculate_time_decay(3) as u128)
            .saturating_div(100_000_000u128) as u64;
        assert!((r3 as i64 - expected3 as i64).abs() < 10_000_000); // allow rounding error
    }

    // ===== ENHANCED VALIDATION TESTS =====

    #[test]
    fn test_validate_community_metrics_success() {
        // Valid parameters
        let result = sdk::validate_community_metrics(
            5000,   // weekly_active_users
            7500,   // weekly_retention_rate
            4000,   // user_weight
            3500,   // activity_weight
            2500,   // retention_weight
            50_000, // weekly_activity_count
            7000,   // customer_reward_share
            3000,   // merchant_reward_share
        );
        assert!(result.is_ok());
    }

    #[test]
    fn test_validate_community_metrics_invalid_weights() {
        // Weights don't sum to 10000
        let result = sdk::validate_community_metrics(
            5000,   // weekly_active_users
            7500,   // weekly_retention_rate
            4000,   // user_weight
            3500,   // activity_weight
            2000,   // retention_weight (sum = 9500, should be 10000)
            50_000, // weekly_activity_count
            7000,   // customer_reward_share
            3000,   // merchant_reward_share
        );
        assert!(result.is_err());
        assert_eq!(result.unwrap_err(), error::MiracleError::InvalidWeights);
    }

    #[test]
    fn test_validate_community_metrics_invalid_retention_rate() {
        // Retention rate > 10000
        let result = sdk::validate_community_metrics(
            5000,   // weekly_active_users
            15000,  // weekly_retention_rate (should be <= 10000)
            4000,   // user_weight
            3500,   // activity_weight
            2500,   // retention_weight
            50_000, // weekly_activity_count
            7000,   // customer_reward_share
            3000,   // merchant_reward_share
        );
        assert!(result.is_err());
        assert_eq!(
            result.unwrap_err(),
            error::MiracleError::InvalidRetentionRate
        );
    }

    #[test]
    fn test_validate_community_metrics_invalid_reward_split() {
        // Reward shares don't sum to 10000
        let result = sdk::validate_community_metrics(
            5000,   // weekly_active_users
            7500,   // weekly_retention_rate
            4000,   // user_weight
            3500,   // activity_weight
            2500,   // retention_weight
            50_000, // weekly_activity_count
            7000,   // customer_reward_share
            2000,   // merchant_reward_share (sum = 9000, should be 10000)
        );
        assert!(result.is_err());
        assert_eq!(result.unwrap_err(), error::MiracleError::InvalidRewardSplit);
    }

    #[test]
    fn test_validate_community_metrics_invalid_activity_count() {
        // Activity count > 1M
        let result = sdk::validate_community_metrics(
            5000,      // weekly_active_users
            7500,      // weekly_retention_rate
            4000,      // user_weight
            3500,      // activity_weight
            2500,      // retention_weight
            2_000_000, // weekly_activity_count (should be <= 1M)
            7000,      // customer_reward_share
            3000,      // merchant_reward_share
        );
        assert!(result.is_err());
        assert_eq!(
            result.unwrap_err(),
            error::MiracleError::InvalidActivityCount
        );
    }

    // ===== NEW PAYMENT PLATFORM TESTS =====

    #[test]
    fn test_activity_based_rewards() {
        let config = create_test_config();

        // Test that activity count (not volume) is used for rewards
        let score_low_activity = calculate_community_score(
            &config, 5000,   // weekly_active_users
            10_000, // low activity count
            5000,   // weekly_retention_rate
            4000,   // user_weight
            3500,   // activity_weight
            2500,   // retention_weight
        );

        let score_high_activity = calculate_community_score(
            &config, 5000,    // weekly_active_users
            100_000, // high activity count
            5000,    // weekly_retention_rate
            4000,    // user_weight
            3500,    // activity_weight
            2500,    // retention_weight
        );

        // Higher activity should result in higher score
        assert!(score_high_activity > score_low_activity);
    }

    #[test]
    fn test_customer_merchant_split() {
        // Test customer/merchant reward split calculation
        let (customer_pool, merchant_pool) = consts::calculate_daily_rewards_split(
            5000, // community_score
            1,    // years_since_launch
            7000, // customer_reward_share (70%)
            3000, // merchant_reward_share (30%)
        );

        // Both pools should be positive
        assert!(customer_pool > 0);
        assert!(merchant_pool > 0);

        // Customer pool should be larger than merchant pool (70% vs 30%)
        assert!(customer_pool > merchant_pool);

        // Total should equal the base daily rewards for this community score
        let total_rewards = calculate_daily_rewards(5000, 1);
        let total_split = customer_pool + merchant_pool;
        assert!((total_split as i64 - total_rewards as i64).abs() < 1000); // Allow small rounding error
    }

    #[test]
    fn test_boundary_conditions() {
        let config = create_test_config();

        // Test minimum values
        let _score_min = calculate_community_score(
            &config, 1,     // minimum users
            1,     // minimum activity
            0,     // minimum retention
            10000, // user_weight (100%)
            0,     // activity_weight
            0,     // retention_weight
        );
        // score_min is always >= 0 due to u16 type

        // Test maximum values
        let score_max = calculate_community_score(
            &config, 1_000_000, // maximum users
            1_000_000, // maximum activity
            10000,     // maximum retention (100%)
            3333,      // user_weight
            3333,      // activity_weight
            3334,      // retention_weight
        );
        assert!(score_max <= 10000);

        // Test zero values (should handle gracefully)
        let _score_zero = calculate_community_score(
            &config, 0,    // zero users
            0,    // zero activity
            0,    // zero retention
            3333, // user_weight
            3333, // activity_weight
            3334, // retention_weight
        );
        // score_zero is always >= 0 due to u16 type
    }

    #[test]
    fn test_weight_combinations() {
        // Test different weight combinations
        let test_cases = vec![
            (6000, 3000, 1000), // Launch weights
            (4000, 3500, 2500), // Growth weights
            (3000, 3000, 4000), // Maturity weights
            (5000, 5000, 0),    // No retention
            (0, 0, 10000),      // Only retention
        ];

        let config = create_test_config();
        for (user_w, activity_w, retention_w) in test_cases {
            let score = calculate_community_score(
                &config,
                5000,        // weekly_active_users
                50_000,      // weekly_activity_count
                5000,        // weekly_retention_rate
                user_w,      // user_weight
                activity_w,  // activity_weight
                retention_w, // retention_weight
            );
            assert!(score <= 10000); // score is always >= 0 due to u16 type
        }
    }
}

#[cfg(test)]
mod date_epoch_tests {
    use super::*;
    use crate::consts::{EPOCH_DURATION, START_AT};

    #[test]
    fn test_timestamp_to_epoch() {
        // Test START_AT timestamp returns epoch 0
        assert_eq!(sdk::timestamp_to_epoch(START_AT), 0);

        // Test timestamp before START_AT returns epoch 0
        assert_eq!(sdk::timestamp_to_epoch(START_AT - 1), 0);

        // Test START_AT + 24 hours returns epoch 1
        assert_eq!(sdk::timestamp_to_epoch(START_AT + EPOCH_DURATION), 1);

        // Test START_AT + 48 hours returns epoch 2
        assert_eq!(sdk::timestamp_to_epoch(START_AT + 2 * EPOCH_DURATION), 2);
    }

    #[test]
    fn test_epoch_to_timestamp() {
        // Calculate the start of the UTC day containing START_AT
        let start_day_beginning = (START_AT / EPOCH_DURATION) * EPOCH_DURATION;

        // Test epoch 0 returns start of UTC day containing START_AT
        assert_eq!(sdk::epoch_to_timestamp(0), start_day_beginning);

        // Test epoch 1 returns start_day_beginning + EPOCH_DURATION
        assert_eq!(
            sdk::epoch_to_timestamp(1),
            start_day_beginning + EPOCH_DURATION
        );

        // Test epoch 2 returns start_day_beginning + 2 * EPOCH_DURATION
        assert_eq!(
            sdk::epoch_to_timestamp(2),
            start_day_beginning + 2 * EPOCH_DURATION
        );
    }

    #[test]
    fn test_date_range_to_epochs() {
        // Test single day (same start and end date)
        let epochs: Vec<u64> = sdk::date_range_to_epochs(START_AT, START_AT);
        assert_eq!(epochs, vec![0u64]);

        // Test two days
        let epochs: Vec<u64> = sdk::date_range_to_epochs(START_AT, START_AT + EPOCH_DURATION);
        assert_eq!(epochs, vec![0u64, 1u64]);

        // Test three days
        let epochs: Vec<u64> = sdk::date_range_to_epochs(START_AT, START_AT + 2 * EPOCH_DURATION);
        assert_eq!(epochs, vec![0u64, 1u64, 2u64]);

        // Test invalid range (start > end)
        let epochs: Vec<u64> = sdk::date_range_to_epochs(START_AT + EPOCH_DURATION, START_AT);
        assert_eq!(epochs, vec![] as Vec<u64>);
    }

    #[test]
    fn test_round_trip_conversion() {
        // Test round trip: timestamp -> epoch -> timestamp
        // Use a timestamp that aligns with the new epoch boundary
        let start_day_beginning = (START_AT / EPOCH_DURATION) * EPOCH_DURATION;
        let original_timestamp = start_day_beginning + 5 * EPOCH_DURATION;
        let epoch = sdk::timestamp_to_epoch(original_timestamp);
        let converted_timestamp = sdk::epoch_to_timestamp(epoch);
        assert_eq!(original_timestamp, converted_timestamp);

        // Test round trip: epoch -> timestamp -> epoch
        let original_epoch = 10;
        let timestamp = sdk::epoch_to_timestamp(original_epoch);
        let converted_epoch = sdk::timestamp_to_epoch(timestamp);
        assert_eq!(original_epoch, converted_epoch);
    }
}

#[cfg(test)]
mod alignment_tests {
    // Note: History struct alignment test removed since History account no longer exists
    // The History account was completely removed to save storage costs
    // Historical data is embedded in SealProof structures for verification
}