miracle_api/
event.rs

1use steel::*;
2
3// ===== PAYMENT-BASED REWARDS SYSTEM EVENTS =====
4
5#[repr(C)]
6#[derive(Clone, Copy, Debug, PartialEq, Pod, Zeroable)]
7pub struct SnapshotUpdatedEvent {
8    pub epoch: u64,
9    pub merkle_root: [u8; 32],
10    pub timestamp: i64,
11}
12
13/// Event emitted when a customer claims rewards.
14///
15/// This event provides complete transparency for reward calculations,
16/// allowing off-chain systems to verify that the on-chain calculation
17/// matches the expected transparent formula.
18///
19/// ## Formula Verification
20/// The event includes all data needed to verify the calculation:
21/// reward = (activity_count * customer_reward_pool) / total_customer_activity
22///
23/// ## Usage
24/// - Verify reward calculations match off-chain estimates
25/// - Track reward distribution patterns
26/// - Monitor claim activity and frequency
27/// - Build reward transparency dashboards
28/// - Audit reward distribution fairness
29///
30/// ## Memory Layout
31/// 80 bytes total for complete transparency data.
32#[repr(C)]
33#[derive(Clone, Copy, Debug, PartialEq, Pod, Zeroable)]
34pub struct RewardClaimedEvent {
35    /// Customer wallet that claimed the reward.
36    pub customer_wallet: Pubkey,
37
38    /// Epoch number for the claim.
39    pub epoch: u64,
40
41    /// Final reward amount claimed in smallest token units.
42    /// This is calculated on-chain using the transparent formula.
43    pub reward_amount: u64,
44
45    /// Customer reward pool for this epoch.
46    /// Used in the calculation: reward = (activity_count * customer_reward_pool) / total_customer_activity
47    pub customer_reward_pool: u64,
48
49    /// Number of activities performed by the customer.
50    /// This is extracted from the Merkle proof and used in reward calculation.
51    pub activity_count: u32,
52
53    /// Total customer activity for this epoch.
54    /// Used in the calculation: reward = (activity_count * customer_reward_pool) / total_customer_activity
55    pub total_customer_activity: u32,
56
57    /// Merkle root used for proof verification.
58    pub merkle_root: [u8; 32],
59
60    /// Event timestamp (Unix timestamp).
61    pub timestamp: i64,
62
63    /// Participant type: 0 for customer, 1 for merchant.
64    /// Used to distinguish between customer and merchant claims.
65    pub participant_type: u8,
66
67    /// Padding to ensure proper alignment (7 bytes to maintain 88-byte total size)
68    pub _padding: [u8; 7],
69}
70
71/// Event emitted when community metrics are updated by the oracle.
72///
73/// This event is logged on-chain whenever the oracle updates community health metrics.
74/// It provides transparency and allows off-chain systems to track community health
75/// changes over time.
76///
77/// ## Usage
78/// - Track community health trends
79/// - Monitor oracle activity
80/// - Analyze reward decay patterns
81/// - Build community health dashboards
82/// - Monitor dynamic weight changes
83/// - Track community age progression
84///
85/// ## Memory Layout
86/// Matches Enhanced Metrics struct layout for consistency (40 bytes total).
87#[repr(C)]
88#[derive(Clone, Copy, Debug, PartialEq, Pod, Zeroable)]
89pub struct MetricsUpdatedEvent {
90    /// Event timestamp (Unix timestamp).
91    /// When the metrics were updated.
92    pub timestamp: i64,
93
94    /// Weekly active users count.
95    /// Raw user count data as provided by the oracle.
96    pub weekly_active_users: u32,
97
98    /// Weekly activity count (number of transactions, not amounts).
99    /// Used to calculate activity score component of community health.
100    pub weekly_activity_count: u32,
101
102    /// Weekly retention rate in basis points (0-10000, 0-100%).
103    /// Percentage of users who return week-over-week.
104    pub weekly_retention_rate: u16,
105
106    /// Calculated community score (0-10000 basis points).
107    /// Final computed community health percentage.
108    pub community_score: u16,
109
110    /// User weight in basis points (0-10000) for weighted geometric mean.
111    /// Determines importance of user count in community score calculation.
112    pub user_weight: u16,
113
114    /// Activity weight in basis points (0-10000) for weighted geometric mean.
115    /// Determines importance of transaction count in community score calculation.
116    pub activity_weight: u16,
117
118    /// Retention weight in basis points (0-10000) for weighted geometric mean.
119    /// Determines importance of retention rate in community score calculation.
120    pub retention_weight: u16,
121
122    /// Customer reward share in basis points (0-10000, 0-100%).
123    /// Percentage of daily rewards allocated to customers.
124    pub customer_reward_share: u16,
125
126    /// Merchant reward share in basis points (0-10000, 0-100%).
127    /// Percentage of daily rewards allocated to merchants.
128    pub merchant_reward_share: u16,
129
130    /// Padding to ensure proper alignment (2 bytes to maintain 40-byte struct size)
131    pub _padding: [u8; 2],
132}
133
134event!(SnapshotUpdatedEvent);
135event!(RewardClaimedEvent);
136event!(MetricsUpdatedEvent);
miracle_api/event.rs

miracle_api/
event.rs
