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

use solana_program::pubkey::Pubkey;
use steel::*;

use super::MiracleAccount;

/// Config is a singleton account which manages program global variables.
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, Pod, Zeroable)]
pub struct Config {
    /// The timestamp of the last reset.
    pub last_reset_at: i64,

    /// Risk threshold for a rewareds claim request
    pub claim_rewards_threshold: u64,

    /// The oracle authority with permission to update daily snapshots.
    /// The oracle provides payment data and merkle roots for reward distribution.
    pub oracle_authority: Pubkey,

    /// Community health targets for sustainable reward distribution.
    /// These targets determine what constitutes "healthy" vs "struggling" communities.
    pub community_targets: CommunityTargets,

    /// Activity limits configuration to prevent gaming and ensure fair distribution.
    /// These limits cap the maximum effective activity count per epoch per participant.
    pub activity_limits: ActivityLimits,

    /// Social marketing rewards configuration for community building and organic growth.
    /// This pool provides rewards for social media engagement while maintaining payment-first philosophy.
    pub social_marketing: SocialMarketingConfig,
}

/// Community health targets for sustainable reward distribution.
/// These targets determine what constitutes "healthy" vs "struggling" communities.
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, Pod, Zeroable)]
pub struct CommunityTargets {
    /// Target weekly active users for sustainable rewards (default: 10,000).
    pub target_weekly_users: u32,

    /// Target weekly activity count for sustainable rewards (default: 50,000).
    pub target_weekly_activity: u32,

    /// Target weekly retention rate for sustainable rewards (default: 7,000 = 70%).
    pub target_retention_rate: u16,

    /// Padding to ensure proper alignment (6 bytes to reach 16-byte boundary).
    pub _padding: [u8; 6],
}

/// Activity limits configuration to prevent payment splitting for more activities.
/// This prevents gaming by capping the maximum effective activity count per epoch.
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, Pod, Zeroable)]
pub struct ActivityLimits {
    /// Maximum customer activity count per epoch (prevents payment splitting).
    /// If a customer's activity count exceeds this limit, it will be capped.
    pub max_customer_activity_per_epoch: u32,

    /// Maximum merchant activity count per epoch (prevents payment splitting).
    /// If a merchant's activity count exceeds this limit, it will be capped.
    pub max_merchant_activity_per_epoch: u32,

    /// Whether activity capping is enabled (1=enabled, 0=disabled).
    /// When disabled, no activity limits are applied.
    pub activity_cap_enabled: u8,

    /// Whether claim capping is enabled (1=enabled, 0=disabled).
    /// When disabled, no claim count limits per epoch are applied, used for devnet(test)
    /// When enabled, only 1 claim is allowd per epoch, used for mainnet(production)
    pub claim_cap_enabled: u8,

    /// Padding to ensure proper alignment (6 bytes to reach 16-byte boundary).
    pub _padding: [u8; 6],
}

/// Social marketing rewards configuration for community building and organic growth.
/// This pool provides rewards for social media engagement while maintaining payment-first philosophy.
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, Pod, Zeroable)]
pub struct SocialMarketingConfig {
    /// Remaining social marketing rewards pool (initial: 9M MIRACLE).
    /// This pool is separate from payment rewards and dedicated to social marketing.
    pub rewards_pool: u64,

    /// Maximum social claims per user per day (default: 1).
    /// This prevents spam posting and ensures quality engagement.
    pub daily_limit_per_user: u32,

    /// Base reward for each verified social media post (default: 10 MIRACLE).
    /// This is the minimum reward for any valid social media engagement.
    pub base_reward_per_post: u32,

    /// Oracle authority with permission to verify social media posts.
    /// This authority signs verification data for social media claims.
    pub oracle_authority: Pubkey,
    // Padding to ensure proper alignment (0 bytes - exact size).
    // pub _padding: [u8; 0],
}

account!(MiracleAccount, Config);