Architecture Overview

#[contracttype]
pub enum DataKey {
    Admin,                          // Instance - admin address
    NextPlanId,                     // Instance - u64 counter
    NextSubId,                      // Instance - u64 counter
    Plan(u64),                      // Persistent - one per plan
    Sub(u64),                       // Persistent - one per subscription
    MerchantPlans(Address),         // Persistent - Vec<u64> of plan IDs
    SubscriberSubs(Address),        // Persistent - Vec<u64> of sub IDs
    PlanSubs(u64),                  // Persistent - Vec<u64> of sub IDs per plan
}

#[contracttype]
#[derive(Clone, Debug)]
pub struct Plan {
    pub id: u64,              // Unique auto-incremented identifier
    pub merchant: Address,    // Merchant who created the plan
    pub token: Address,       // SAC token address (e.g., USDC)
    pub amount: i128,         // Amount charged per period
    pub period: u64,          // Billing period in seconds
    pub trial_periods: u32,   // Number of free trial periods (0 = no trial)
    pub max_periods: u32,     // Maximum billing periods (0 = unlimited)
    pub grace_period: u64,    // Grace window in seconds after failed charge
    pub price_ceiling: i128,  // Maximum amount the merchant can ever set
    pub created_at: u64,      // Ledger timestamp at creation
    pub active: bool,         // Whether the plan accepts new subscribers
}

#[contracttype]
#[derive(Clone, Debug)]
pub struct Subscription {
    pub id: u64,                     // Unique auto-incremented identifier
    pub plan_id: u64,                // The plan this subscription belongs to
    pub subscriber: Address,         // Subscriber's wallet address
    pub status: SubscriptionStatus,  // Current lifecycle state
    pub created_at: u64,             // Ledger timestamp at creation
    pub periods_billed: u32,         // Number of periods successfully charged
    pub next_billing_time: u64,      // Timestamp when next charge is due
    pub failed_at: u64,              // Timestamp of last failed charge (0 = none)
    pub migration_target: u64,       // Target plan ID for pending migration (0 = none)
    pub cancelled_at: u64,           // Timestamp of cancellation (0 = not cancelled)
}

#[contracttype]
#[derive(Clone, Debug, PartialEq)]
pub enum SubscriptionStatus {
    Active,     // Subscription is live and billable
    Paused,     // Grace period expired - charge failed, awaiting resolution
    Cancelled,  // Permanently cancelled by subscriber or system
    Expired,    // Max periods reached - natural end of subscription
}