Struct DailyParticipantData 

#[repr(C)]
pub struct DailyParticipantData {
    pub participant_id: [u8; 32],
    pub first_payment_timestamp: i64,
    pub last_payment_timestamp: i64,
    pub first_payment_tx_sig_short: [u8; 8],
    pub last_payment_tx_sig_short: [u8; 8],
    pub payment_count: u32,
    pub participant_type: u8,
    pub _padding: [u8; 3],
}

DailyParticipantData represents aggregated payment data for a single participant in a daily epoch.

This structure is used off-chain by the oracle to build Merkle trees for daily payment snapshots. It aggregates all payments for a single participant (customer or merchant) within a 24-hour epoch.

Key Features

• Aggregation: Combines multiple payments per participant per day
• Fair Rewards: Uses transaction count and total amount for reward calculation
• Efficient Storage: Off-chain only, reduces on-chain storage costs
• Flexible: Supports both customer and merchant participants
• Simple Design: Only necessary fields included (Simple is Best)
• Transaction Verification: Includes short transaction signatures for on-chain verification

Data Structure

• participant_id: Unique identifier for the participant (customer/merchant)
• first_payment_timestamp: Timestamp of first payment in the day
• last_payment_timestamp: Timestamp of last payment in the day
• first_payment_tx_sig_short: First 8 characters of first payment transaction signature
• last_payment_tx_sig_short: First 8 characters of last payment transaction signature
• first_payment_tx_sig_short: First 8 characters of first payment transaction signature
• last_payment_tx_sig_short: First 8 characters of last payment transaction signature
• payment_count: Number of transactions for the day
• participant_type: Whether this is a customer (0) or merchant (1)

Merkle Leaf Construction

The Merkle leaf hash is computed as:

use miracle_api::prelude::DailyParticipantData;

let participant_data = DailyParticipantData::new(
    [0u8; 32],           // participant_id
    1723680000,         // first_payment_timestamp
    1723766400,         // last_payment_timestamp
    [0u8; 8],           // first_payment_tx_sig_short
    [0u8; 8],           // last_payment_tx_sig_short
    5,                  // payment_count
    0,                   // participant_type (customer)
);
let leaf_hash = participant_data.compute_leaf_hash();

Security Features

• Timestamp Range: Provides audit trail and prevents stale data
• Participant Type: Distinguishes between customers and merchants for fair allocation
• Aggregation: Reduces Merkle tree size while maintaining fairness
• Uniqueness: participant_id + daily timestamps provide natural uniqueness
• Deployment Isolation: Handled by program ID, not data structure
• Transaction Verification: Short signatures enable on-chain payment verification
• Transaction Verification: Short signatures enable on-chain verification of payment authenticity

Fields

participant_id: [u8; 32]

Unique identifier for the participant (customer or merchant). This should be a deterministic identifier that can be reproduced by both the oracle and the claiming user.

first_payment_timestamp: i64

Timestamp of the first payment in the daily epoch (Unix timestamp). Used for audit trail and to prevent stale data replay.

last_payment_timestamp: i64

Timestamp of the last payment in the daily epoch (Unix timestamp). Used for audit trail and to ensure data freshness.

first_payment_tx_sig_short: [u8; 8]

First 8 characters of the first payment transaction signature. Used for on-chain verification of payment authenticity. Provides cost-effective verification without storing full signatures.

last_payment_tx_sig_short: [u8; 8]

First 8 characters of the last payment transaction signature. Used for on-chain verification of payment authenticity. Provides cost-effective verification without storing full signatures.

payment_count: u32

Number of transactions for this participant in the daily epoch. Used for activity-based reward calculation and community metrics.

participant_type: u8

Participant type: 0 for customer, 1 for merchant. Used to determine reward allocation between customer and merchant pools.

_padding: [u8; 3]

Padding for future extensibility.

Implementations

impl DailyParticipantData

pub fn new( participant_id: [u8; 32], first_payment_timestamp: i64, last_payment_timestamp: i64, first_payment_tx_sig_short: [u8; 8], last_payment_tx_sig_short: [u8; 8], payment_count: u32, participant_type: u8, ) -> Self

Create a new DailyParticipantData instance.

Parameters

• participant_id: Unique identifier for the participant
• first_payment_timestamp: Timestamp of first payment
• last_payment_timestamp: Timestamp of last payment
• first_payment_tx_sig_short: First 8 characters of first payment transaction signature
• last_payment_tx_sig_short: First 8 characters of last payment transaction signature
• payment_count: Number of transactions
• participant_type: 0 for customer, 1 for merchant

Returns

• New DailyParticipantData instance

Examples found in repository

examples/claim_instruction_example.rs (lines 130-138)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🔍 Miracle API Utils Example: Building Claim Instructions");
    println!("========================================================");

    // ===== SCENARIO 1: Converting Database Hex Strings =====
    println!("\n📊 Scenario 1: Converting Database Hex Strings");
    println!("------------------------------------------------");

    // Simulate database query output (hex strings from SQL function)
    let db_customer_reward_pool = "0x1234567890abcdef";
    let db_merchant_reward_pool = "0xfedcba0987654321";
    let db_total_customer_activity = "0x0000000000000064"; // 100 in decimal
    let db_total_merchant_activity = "0x00000000000000c8"; // 200 in decimal

    println!("Database hex strings:");
    println!("  customer_reward_pool: {}", db_customer_reward_pool);
    println!("  merchant_reward_pool: {}", db_merchant_reward_pool);
    println!("  total_customer_activity: {}", db_total_customer_activity);
    println!("  total_merchant_activity: {}", db_total_merchant_activity);

    // Convert hex strings to EpochClaimData using utils
    let epoch_data = claim::epoch_claim_data_from_hex(
        db_customer_reward_pool,
        db_merchant_reward_pool,
        db_total_customer_activity,
        db_total_merchant_activity,
    )?;

    println!("\n✅ Converted to EpochClaimData:");
    println!(
        "  customer_reward_pool bytes: {:?}",
        epoch_data.customer_reward_pool
    );
    println!(
        "  merchant_reward_pool bytes: {:?}",
        epoch_data.merchant_reward_pool
    );
    println!(
        "  total_customer_activity bytes: {:?}",
        epoch_data.total_customer_activity
    );
    println!(
        "  total_merchant_activity bytes: {:?}",
        epoch_data.total_merchant_activity
    );

    // ===== SCENARIO 2: Converting Native u64 Values =====
    println!("\n📊 Scenario 2: Converting Native u64 Values");
    println!("---------------------------------------------");

    let native_customer_reward_pool = 1234567890u64;
    let native_merchant_reward_pool = 9876543210u64;
    let native_total_customer_activity = 100u64;
    let native_total_merchant_activity = 200u64;

    println!("Native u64 values:");
    println!("  customer_reward_pool: {}", native_customer_reward_pool);
    println!("  merchant_reward_pool: {}", native_merchant_reward_pool);
    println!(
        "  total_customer_activity: {}",
        native_total_customer_activity
    );
    println!(
        "  total_merchant_activity: {}",
        native_total_merchant_activity
    );

    // Convert u64 values to EpochClaimData using utils
    let epoch_data_u64 = claim::epoch_claim_data_from_u64(
        native_customer_reward_pool,
        native_merchant_reward_pool,
        native_total_customer_activity,
        native_total_merchant_activity,
    );

    println!("\n✅ Converted to EpochClaimData:");
    println!(
        "  customer_reward_pool bytes: {:?}",
        epoch_data_u64.customer_reward_pool
    );
    println!(
        "  merchant_reward_pool bytes: {:?}",
        epoch_data_u64.merchant_reward_pool
    );
    println!(
        "  total_customer_activity bytes: {:?}",
        epoch_data_u64.total_customer_activity
    );
    println!(
        "  total_merchant_activity bytes: {:?}",
        epoch_data_u64.total_merchant_activity
    );

    // ===== SCENARIO 3: Individual Hex Conversions =====
    println!("\n📊 Scenario 3: Individual Hex Conversions");
    println!("-------------------------------------------");

    // Convert individual hex strings to byte arrays
    let reward_pool_bytes = hex::hex_string_to_u64_bytes("0x1234567890abcdef")?;
    let hash_bytes = hex::hex_string_to_hash_bytes(
        "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    )?;

    println!("Individual conversions:");
    println!("  reward_pool (8 bytes): {:?}", reward_pool_bytes);
    println!("  hash (32 bytes): {:?}", hash_bytes);

    // Convert bytes back to hex strings
    let reward_pool_hex = hex::bytes_to_hex_string(&reward_pool_bytes);
    println!("  reward_pool back to hex: {}", reward_pool_hex);

    // ===== SCENARIO 4: Building Claim Instruction =====
    println!("\n📊 Scenario 4: Building Claim Instruction");
    println!("------------------------------------------");

    // Create sample participant data
    let participant_data = DailyParticipantData::new(
        [1u8; 32],  // participant_id
        1723680000, // first_payment_timestamp
        1723766400, // last_payment_timestamp
        [1u8; 8],   // first_payment_tx_sig_short
        [2u8; 8],   // last_payment_tx_sig_short
        5,          // payment_count
        0,          // participant_type (customer)
    );

    // Create payment proof (empty for this example)
    let payment_proof = vec![[3u8; 32]];
    let payment_indices = vec![true];

    // Create seal proof (empty for this example)
    let seal_proof = vec![[4u8; 32]];
    let seal_indices = vec![false];

    // Payment root (32 bytes)
    let payment_root = [5u8; 32];

    // Build claim instruction using the converted epoch_data
    let claim_instruction = claim(
        Pubkey::new_from_array([6u8; 32]), // signer (placeholder)
        Pubkey::new_from_array([7u8; 32]), // beneficiary (placeholder)
        0,                                 // epoch
        participant_data,
        payment_proof,
        payment_indices,
        seal_proof,
        seal_indices,
        payment_root,
        epoch_data, // Using the converted epoch_data
        0,          // participant_type
        None,       // social_data
    );

    println!("✅ Claim instruction built successfully!");
    println!(
        "  Instruction data length: {} bytes",
        claim_instruction.data.len()
    );
    println!("  Number of accounts: {}", claim_instruction.accounts.len());

    // ===== SUMMARY =====
    println!("\n🎯 Summary");
    println!("===========");
    println!("✅ Successfully converted database hex strings to EpochClaimData");
    println!("✅ Successfully converted native u64 values to EpochClaimData");
    println!("✅ Successfully built claim instruction with converted data");
    println!("✅ All data type conversions working correctly");

    println!("\n🚀 The utils module successfully bridges the gap between:");
    println!("   - Database hex string output (from SQL functions)");
    println!("   - On-chain byte array requirements (for EpochClaimData)");
    println!("   - Claim instruction construction");

    Ok(())
}

pub fn compute_leaf_hash(&self) -> [u8; 32]

Compute the Merkle leaf hash for this participant data.

Returns

• 32-byte hash that will be used as a leaf in the Merkle tree

Security

This hash includes all fields to ensure data integrity and prevent replay attacks across different epochs. The short transaction signatures are included to enable on-chain verification of payment authenticity.

Implementation

Uses Solana’s standard hashv function with SHA-256 for cryptographic security. All fields are included in the hash to prevent any data manipulation.

pub fn validate(&self) -> Result<(), &'static str>

Validate the participant data for consistency.

Returns

• Ok(()) if data is valid
• Err(&str) with error message if validation fails

Validation Rules

• Participant type must be 0 or 1
• Payment count must be greater than 0
• First timestamp must be before or equal to last timestamp
• Short signatures must not be all zeros (basic validation)

pub fn is_customer(&self) -> bool

Check if this participant is a customer.

Returns

• true if participant_type is 0 (customer)
• false if participant_type is 1 (merchant)

pub fn is_merchant(&self) -> bool

Check if this participant is a merchant.

Returns

• true if participant_type is 1 (merchant)
• false if participant_type is 0 (customer)

pub fn from_bytes(data: &[u8]) -> Result<Self, &'static str>

Deserialize from bytes manually

Trait Implementations

impl Clone for DailyParticipantData

fn clone(&self) -> DailyParticipantData

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DailyParticipantData

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for DailyParticipantData

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for DailyParticipantData

fn eq(&self, other: &DailyParticipantData) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for DailyParticipantData

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Zeroable for DailyParticipantData

fn zeroed() -> Self

Calls zeroed.

impl Copy for DailyParticipantData

impl Pod for DailyParticipantData

impl StructuralPartialEq for DailyParticipantData