miracle_api/state/
metrics.rs

1use steel::*;
2
3use super::MiracleAccount;
4
5/// Metrics stores weekly community health data used for reward decay calculation.
6///
7/// This struct implements the Enhanced Community-Driven Decay model which adjusts daily rewards
8/// based on community health metrics. The community score is calculated using a weighted geometric
9/// mean approach combining weekly active users, weekly activity count, and weekly retention rate
10/// with dynamic weights based on community age.
11///
12/// ## Formula
13/// ```text
14/// user_score = min((weekly_active_users / TARGET_WEEKLY_USERS) * 10000, 10000)
15/// activity_score = min((weekly_activity_count / TARGET_WEEKLY_ACTIVITY) * 10000, 10000)
16/// retention_score = min((weekly_retention_rate / TARGET_RETENTION_RATE) * 10000, 10000)
17/// weights = oracle_provided_weights (no longer fixed phases)
18/// community_score = weighted_geometric_mean([user_score, activity_score, retention_score], weights)
19///
20/// decay_factor = smooth_function(community_score) // 0.5 + 0.5 * (1 - (score/10000)^2)
21/// daily_rewards = BASE_DAILY_REWARDS * decay_factor * time_decay / 100_000_000
22/// customer_pool = daily_rewards * customer_reward_share / 10000
23/// merchant_pool = daily_rewards * merchant_reward_share / 10000
24/// ```
25///
26/// ## Targets
27/// - TARGET_WEEKLY_USERS: 10,000 active users per week
28/// - TARGET_WEEKLY_ACTIVITY: 50,000 transactions per week (replaces volume-based target)
29/// - TARGET_RETENTION_RATE: 70% retention rate (7000 basis points)
30///
31/// ## Dynamic Weight Strategy (Oracle Configurable)
32/// - **Launch Phase**: [6000, 3000, 1000] - User focus, encourage activity
33/// - **Growth Phase**: [4000, 3500, 2500] - Balanced metrics
34/// - **Maturity Phase**: [3000, 3000, 4000] - Quality focus
35///
36/// ## Customer/Merchant Split
37/// - **Launch**: 70% customers, 30% merchants (drive adoption)
38/// - **Growth**: 60% customers, 40% merchants (balanced)
39/// - **Maturity**: 50% customers, 50% merchants (equal partnership)
40///
41/// ## Decay Factors
42/// - Smooth Decay: Gradual transition from 100% to 50% rewards based on community score
43/// - Time Decay: Linear decay over 5 years, reaching 10% minimum
44/// - Formula: 0.5 + 0.5 * (1 - (score/10000)^2)
45/// - No sharp thresholds, eliminates gaming incentives
46///
47/// ## Daily Rewards Impact
48/// - **Healthy Community** (score = 100%): 50,000 MIRACLE/day (50% of 100,000)
49/// - **Growing Community** (score = 50%): 87,500 MIRACLE/day (87.5% of 100,000)
50/// - **Struggling Community** (score = 0%): 100,000 MIRACLE/day (100% of 100,000)
51///
52/// ## Edge Cases
53/// - **Initial Launch** (score = 0%): 100,000 MIRACLE/day (100% of base rewards)
54/// - **Zero Activity** (no users/activity): 100,000 MIRACLE/day (100% of base rewards)
55/// - **Oracle Failure** (stale data): Uses last known community score
56/// - **New Project**: Full rewards encourage early adoption and community growth
57///
58/// ## Memory Layout
59/// Optimized for 8-byte alignment with explicit padding to ensure consistent
60/// cross-platform behavior and minimal account size (48 bytes total).
61#[repr(C)]
62#[derive(Clone, Copy, Debug, PartialEq, Pod, Zeroable)]
63pub struct Metrics {
64    /// Last update timestamp (Unix timestamp).
65    /// Tracks when the metrics were last updated by the oracle.
66    pub last_updated: i64,
67
68    /// Weekly active users count.
69    /// Used to calculate user score component of community health.
70    pub weekly_active_users: u32,
71
72    /// Weekly activity count (number of transactions, not amounts).
73    /// Used to calculate activity score component of community health.
74    /// Replaces volume-based counting for fair mediator platform rewards.
75    pub weekly_activity_count: u32,
76
77    /// Weekly retention rate in basis points (0-10000, 0-100%).
78    /// Percentage of users who return week-over-week.
79    pub weekly_retention_rate: u16,
80
81    /// Calculated community score (0-10000 basis points).
82    /// Represents overall community health as percentage (0-100%).
83    pub community_score: u16,
84
85    /// User weight in basis points (0-10000) for weighted geometric mean.
86    /// Determines importance of user count in community score calculation.
87    pub user_weight: u16,
88
89    /// Activity weight in basis points (0-10000) for weighted geometric mean.
90    /// Determines importance of transaction count in community score calculation.
91    pub activity_weight: u16,
92
93    /// Retention weight in basis points (0-10000) for weighted geometric mean.
94    /// Determines importance of retention rate in community score calculation.
95    pub retention_weight: u16,
96
97    /// Customer reward share in basis points (0-10000, 0-100%).
98    /// Percentage of daily rewards allocated to customers.
99    pub customer_reward_share: u16,
100
101    /// Merchant reward share in basis points (0-10000, 0-100%).
102    /// Percentage of daily rewards allocated to merchants.
103    /// Must sum to 10000 with customer_reward_share.
104    pub merchant_reward_share: u16,
105
106    /// Padding to ensure proper alignment (2 bytes to maintain 48-byte struct size)
107    pub _padding: [u8; 2],
108}
109
110account!(MiracleAccount, Metrics);
miracle_api/state/metrics.rs

miracle_api/state/
metrics.rs
