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
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

use steel::*;

// ===== PAYMENT-BASED REWARDS SYSTEM EVENTS =====

#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, Pod, Zeroable)]
pub struct SnapshotUpdatedEvent {
    pub epoch: u64,
    pub merkle_root: [u8; 32],
    pub timestamp: i64,
}

/// Event emitted when a customer claims rewards.
///
/// This event provides complete transparency for reward calculations,
/// allowing off-chain systems to verify that the on-chain calculation
/// matches the expected transparent formula.
///
/// ## Formula Verification
/// The event includes all data needed to verify the calculation:
/// reward = (activity_count * customer_reward_pool) / total_customer_activity
///
/// ## Usage
/// - Verify reward calculations match off-chain estimates
/// - Track reward distribution patterns
/// - Monitor claim activity and frequency
/// - Build reward transparency dashboards
/// - Audit reward distribution fairness
///
/// ## Memory Layout
/// 80 bytes total for complete transparency data.
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, Pod, Zeroable)]
pub struct RewardClaimedEvent {
    /// Customer wallet that claimed the reward.
    pub customer_wallet: Pubkey,

    /// Epoch number for the claim.
    pub epoch: u64,

    /// Final reward amount claimed in smallest token units.
    /// This is calculated on-chain using the transparent formula.
    pub reward_amount: u64,

    /// Customer reward pool for this epoch.
    /// Used in the calculation: reward = (activity_count * customer_reward_pool) / total_customer_activity
    pub customer_reward_pool: u64,

    /// Number of activities performed by the customer.
    /// This is extracted from the Merkle proof and used in reward calculation.
    pub activity_count: u32,

    /// Total customer activity for this epoch.
    /// Used in the calculation: reward = (activity_count * customer_reward_pool) / total_customer_activity
    pub total_customer_activity: u32,

    /// Merkle root used for proof verification.
    pub merkle_root: [u8; 32],

    /// Event timestamp (Unix timestamp).
    pub timestamp: i64,

    /// Participant type: 0 for customer, 1 for merchant.
    /// Used to distinguish between customer and merchant claims.
    pub participant_type: u8,

    /// Padding to ensure proper alignment (7 bytes to maintain 88-byte total size)
    pub _padding: [u8; 7],
}

/// Event emitted when community metrics are updated by the oracle.
///
/// This event is logged on-chain whenever the oracle updates community health metrics.
/// It provides transparency and allows off-chain systems to track community health
/// changes over time.
///
/// ## Usage
/// - Track community health trends
/// - Monitor oracle activity
/// - Analyze reward decay patterns
/// - Build community health dashboards
/// - Monitor dynamic weight changes
/// - Track community age progression
///
/// ## Memory Layout
/// Matches Enhanced Metrics struct layout for consistency (40 bytes total).
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, Pod, Zeroable)]
pub struct MetricsUpdatedEvent {
    /// Event timestamp (Unix timestamp).
    /// When the metrics were updated.
    pub timestamp: i64,

    /// Weekly active users count.
    /// Raw user count data as provided by the oracle.
    pub weekly_active_users: u32,

    /// Weekly activity count (number of transactions, not amounts).
    /// Used to calculate activity score component of community health.
    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).
    /// Final computed community health percentage.
    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.
    pub merchant_reward_share: u16,

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

event!(SnapshotUpdatedEvent);
event!(RewardClaimedEvent);
event!(MetricsUpdatedEvent);