miracle-api 0.6.0

Miracle is a pay2e protocol for sovereign individuals living in Mirascape Horizon.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

use steel::*;

use super::MiracleAccount;

/// Metrics stores weekly community health data used for reward decay calculation.
///
/// This struct implements the Enhanced Community-Driven Decay model which adjusts daily rewards
/// based on community health metrics. The community score is calculated using a weighted geometric
/// mean approach combining weekly active users, weekly activity count, and weekly retention rate
/// with dynamic weights based on community age.
///
/// ## Formula
/// ```text
/// user_score = min((weekly_active_users / TARGET_WEEKLY_USERS) * 10000, 10000)
/// activity_score = min((weekly_activity_count / TARGET_WEEKLY_ACTIVITY) * 10000, 10000)
/// retention_score = min((weekly_retention_rate / TARGET_RETENTION_RATE) * 10000, 10000)
/// weights = oracle_provided_weights (no longer fixed phases)
/// community_score = weighted_geometric_mean([user_score, activity_score, retention_score], weights)
///
/// decay_factor = smooth_function(community_score) // 0.5 + 0.5 * (1 - (score/10000)^2)
/// daily_rewards = BASE_DAILY_REWARDS * decay_factor * time_decay / 100_000_000
/// customer_pool = daily_rewards * customer_reward_share / 10000
/// merchant_pool = daily_rewards * merchant_reward_share / 10000
/// ```
///
/// ## Targets
/// - TARGET_WEEKLY_USERS: 10,000 active users per week
/// - TARGET_WEEKLY_ACTIVITY: 50,000 transactions per week (replaces volume-based target)
/// - TARGET_RETENTION_RATE: 70% retention rate (7000 basis points)
///
/// ## Dynamic Weight Strategy (Oracle Configurable)
/// - **Launch Phase**: [6000, 3000, 1000] - User focus, encourage activity
/// - **Growth Phase**: [4000, 3500, 2500] - Balanced metrics
/// - **Maturity Phase**: [3000, 3000, 4000] - Quality focus
///
/// ## Customer/Merchant Split
/// - **Launch**: 70% customers, 30% merchants (drive adoption)
/// - **Growth**: 60% customers, 40% merchants (balanced)
/// - **Maturity**: 50% customers, 50% merchants (equal partnership)
///
/// ## Decay Factors
/// - Smooth Decay: Gradual transition from 100% to 50% rewards based on community score
/// - Time Decay: Linear decay over 5 years, reaching 10% minimum
/// - Formula: 0.5 + 0.5 * (1 - (score/10000)^2)
/// - No sharp thresholds, eliminates gaming incentives
///
/// ## Daily Rewards Impact
/// - **Healthy Community** (score = 100%): 50,000 MIRACLE/day (50% of 100,000)
/// - **Growing Community** (score = 50%): 87,500 MIRACLE/day (87.5% of 100,000)
/// - **Struggling Community** (score = 0%): 100,000 MIRACLE/day (100% of 100,000)
///
/// ## Edge Cases
/// - **Initial Launch** (score = 0%): 100,000 MIRACLE/day (100% of base rewards)
/// - **Zero Activity** (no users/activity): 100,000 MIRACLE/day (100% of base rewards)
/// - **Oracle Failure** (stale data): Uses last known community score
/// - **New Project**: Full rewards encourage early adoption and community growth
///
/// ## Memory Layout
/// Optimized for 8-byte alignment with explicit padding to ensure consistent
/// cross-platform behavior and minimal account size (48 bytes total).
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, Pod, Zeroable)]
pub struct Metrics {
    /// Last update timestamp (Unix timestamp).
    /// Tracks when the metrics were last updated by the oracle.
    pub last_updated: i64,

    /// Weekly active users count.
    /// Used to calculate user score component of community health.
    pub weekly_active_users: u32,

    /// Weekly activity count (number of transactions, not amounts).
    /// Used to calculate activity score component of community health.
    /// Replaces volume-based counting for fair mediator platform rewards.
    pub weekly_activity_count: u32,

    /// Weekly retention rate in basis points (0-10000, 0-100%).
    /// Percentage of users who return week-over-week.
    pub weekly_retention_rate: u16,

    /// Calculated community score (0-10000 basis points).
    /// Represents overall community health as percentage (0-100%).
    pub community_score: u16,

    /// User weight in basis points (0-10000) for weighted geometric mean.
    /// Determines importance of user count in community score calculation.
    pub user_weight: u16,

    /// Activity weight in basis points (0-10000) for weighted geometric mean.
    /// Determines importance of transaction count in community score calculation.
    pub activity_weight: u16,

    /// Retention weight in basis points (0-10000) for weighted geometric mean.
    /// Determines importance of retention rate in community score calculation.
    pub retention_weight: u16,

    /// Customer reward share in basis points (0-10000, 0-100%).
    /// Percentage of daily rewards allocated to customers.
    pub customer_reward_share: u16,

    /// Merchant reward share in basis points (0-10000, 0-100%).
    /// Percentage of daily rewards allocated to merchants.
    /// Must sum to 10000 with customer_reward_share.
    pub merchant_reward_share: u16,

    /// Padding to ensure proper alignment (2 bytes to maintain 48-byte struct size)
    pub _padding: [u8; 2],
}

account!(MiracleAccount, Metrics);