feat: add 7-day free trial before paid stream billing

README.md

@@ -9,6 +9,7 @@ If the fan dislikes the content, they can cancel instantly and get their remaini
 ## Key Logic
 
 - **subscribe**: User deposits a buffer (e.g., 50 XLM) and sets a rate.
+- **7-day free trial**: Streams accrue zero charges for the first 7 days, then automatically charge at the configured paid rate.
 - **collect**: Creator triggers the withdrawal of accumulated seconds.
 - **cancel**: Subscriber stops the stream and refunds unspent tokens (after minimum duration).
 - **pause_channel / unpause_channel**: Creator can pause their channel to stop charges across all active incoming streams during hiatus.

contracts/substream_contracts/src/lib.rs

@@ -7,6 +7,7 @@ use soroban_sdk::{
 
 // Minimum flow duration: 24 hours in seconds (24 * 60 * 60 = 86400)
 const MINIMUM_FLOW_DURATION: u64 = 86400;
+const FREE_TRIAL_DURATION: u64 = 7 * 24 * 60 * 60;
 
 #[contracttype]
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -18,11 +19,18 @@ pub enum DataKey {
     ChannelPaused(Address),          // creator -> bool
 }
 
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct Tier {
+    pub rate_per_second: i128,
+    pub trial_duration: u64,
+}
+
 #[contracttype]
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct Stream {
     pub token: Address,
-    pub rate_per_second: i128,
+    pub tier: Tier,
     pub balance: i128,
     pub last_collected: u64,
     pub start_time: u64,
@@ -147,7 +155,10 @@ fn subscribe_internal(
     let now = env.ledger().timestamp();
     let stream = Stream {
         token: token.clone(),
-        rate_per_second,
+        tier: Tier {
+            rate_per_second,
+            trial_duration: FREE_TRIAL_DURATION,
+        },
         balance: amount,
         last_collected: now,
         start_time: now,
@@ -185,6 +196,23 @@ fn distribute_and_collect(
         }
     }
 
+    let trial_end = stream
+        .start_time
+        .saturating_add(stream.tier.trial_duration);
+    let charge_start = if stream.last_collected > trial_end {
+        stream.last_collected
+    } else {
+        trial_end
+    };
+
+    if now <= charge_start {
+        return 0;
+    }
+
+    let elapsed = (now - charge_start) as i128;
+    let mut amount_to_collect = elapsed
+        .checked_mul(stream.tier.rate_per_second)
+
     let elapsed = (now - stream.last_collected) as i128;
     let mut amount_to_collect = elapsed
         .checked_mul(stream.rate_per_second)
@@ -455,7 +483,7 @@ impl SubStreamContract {
         }
 
         let stream_before: Stream = env.storage().persistent().get(&key).unwrap();
-        let old_rate = stream_before.rate_per_second;
+        let old_rate = stream_before.tier.rate_per_second;
 
         distribute_and_collect(&env, &subscriber, &creator, Some(&creator));
 
@@ -476,7 +504,7 @@ impl SubStreamContract {
             }
         }
 
-        stream.rate_per_second = new_rate_per_second;
+        stream.tier.rate_per_second = new_rate_per_second;
         stream.balance = balance;
 
         if additional_deposit > 0 {

contracts/substream_contracts/src/test.rs

@@ -6,6 +6,9 @@ use soroban_sdk::{
     token, vec, Address, Env,
 };
 
+const DAY: u64 = 24 * 60 * 60;
+const WEEK: u64 = 7 * DAY;
+
 fn create_token_contract<'a>(env: &Env, admin: &Address) -> token::Client<'a> {
     let sac = env.register_stellar_asset_contract_v2(admin.clone());
     token::Client::new(env, &sac.address())
@@ -27,18 +30,29 @@ fn test_subscribe_and_collect() {
     let contract_id = env.register(SubStreamContract, ());
     let client = SubStreamContractClient::new(&env, &contract_id);
 
+    let start = 100u64;
+    env.ledger().set_timestamp(start);
     env.ledger().set_timestamp(100);
     client.subscribe(&subscriber, &creator, &token.address, &100, &2);
 
     assert_eq!(token.balance(&subscriber), 900);
     assert_eq!(token.balance(&contract_id), 100);
 
+    // Still inside trial: no charges.
+    env.ledger().set_timestamp(start + 10);
+    client.collect(&subscriber, &creator);
+    assert_eq!(token.balance(&creator), 0);
+
+    // 10 paid seconds after trial.
+    env.ledger().set_timestamp(start + WEEK + 10);
     env.ledger().set_timestamp(110);
     client.collect(&subscriber, &creator);
 
     assert_eq!(token.balance(&creator), 20);
     assert_eq!(token.balance(&contract_id), 80);
 
+    // Additional 50 paid seconds, capped by remaining balance.
+    env.ledger().set_timestamp(start + WEEK + 60);
     env.ledger().set_timestamp(160);
     client.collect(&subscriber, &creator);
 
@@ -47,6 +61,37 @@ fn test_subscribe_and_collect() {
     assert_eq!(client.get_total_streamed(&subscriber, &creator), 100);
 }
 
+#[test]
+fn test_free_trial_ignores_claims_within_first_week() {
+#[should_panic(expected = "cannot cancel stream: minimum duration not met")]
+fn test_cancel_before_minimum_duration() {
+    let env = Env::default();
+    env.mock_all_auths();
+
+    let subscriber = Address::generate(&env);
+    let creator = Address::generate(&env);
+    let admin = Address::generate(&env);
+
+    let token = create_token_contract(&env, &admin);
+    let token_admin = token::StellarAssetClient::new(&env, &token.address);
+    token_admin.mint(&subscriber, &1000);
+
+    let contract_id = env.register(SubStreamContract, ());
+    let client = SubStreamContractClient::new(&env, &contract_id);
+
+    let start = 100u64;
+    env.ledger().set_timestamp(start);
+    client.subscribe(&subscriber, &creator, &token.address, &300, &3);
+
+    env.ledger().set_timestamp(start + WEEK - 1);
+    client.collect(&subscriber, &creator);
+    assert_eq!(token.balance(&creator), 0);
+
+    env.ledger().set_timestamp(start + WEEK + 9);
+    client.collect(&subscriber, &creator);
+    assert_eq!(token.balance(&creator), 27);
+}
+
 #[test]
 #[should_panic(expected = "cannot cancel stream: minimum duration not met")]
 fn test_cancel_before_minimum_duration() {
@@ -87,6 +132,16 @@ fn test_cancel_after_minimum_duration() {
     let contract_id = env.register(SubStreamContract, ());
     let client = SubStreamContractClient::new(&env, &contract_id);
 
+    let start = 100u64;
+    env.ledger().set_timestamp(start);
+    client.subscribe(&subscriber, &creator, &token.address, &100, &1);
+
+    // Minimum duration has passed, but still inside free trial.
+    env.ledger().set_timestamp(start + DAY + 10);
+    client.cancel(&subscriber, &creator);
+
+    assert_eq!(token.balance(&creator), 0);
+    assert_eq!(token.balance(&subscriber), 1000);
     env.ledger().set_timestamp(100);
     client.subscribe(&subscriber, &creator, &token.address, &100, &1);
 
@@ -118,6 +173,7 @@ fn test_top_up() {
     client.subscribe(&subscriber, &creator, &token.address, &100, &1);
     client.top_up(&subscriber, &creator, &50);
 
+    env.ledger().set_timestamp(WEEK + 120);
     env.ledger().set_timestamp(120);
     client.collect(&subscriber, &creator);
 
@@ -156,6 +212,8 @@ fn test_group_subscribe_and_collect_split() {
     ];
     let percentages = vec![&env, 40u32, 25u32, 15u32, 10u32, 10u32];
 
+    let start = 100u64;
+    env.ledger().set_timestamp(start);
     env.ledger().set_timestamp(100);
     client.subscribe_group(
         &subscriber,
@@ -167,6 +225,7 @@ fn test_group_subscribe_and_collect_split() {
         &percentages,
     );
 
+    env.ledger().set_timestamp(start + WEEK + 10);
     env.ledger().set_timestamp(110);
     client.collect_group(&subscriber, &channel_id);
 
@@ -235,6 +294,21 @@ fn test_pause_channel_blocks_charges_and_unpause_resumes() {
     let contract_id = env.register(SubStreamContract, ());
     let client = SubStreamContractClient::new(&env, &contract_id);
 
+    let start = 100u64;
+    env.ledger().set_timestamp(start);
+    client.subscribe(&subscriber, &creator, &token.address, &300, &2);
+
+    env.ledger().set_timestamp(start + WEEK + 10);
+    client.collect(&subscriber, &creator);
+    assert_eq!(token.balance(&creator), 20);
+
+    env.ledger().set_timestamp(start + WEEK + 20);
+    client.pause_channel(&creator);
+    assert!(client.is_channel_paused(&creator));
+    assert_eq!(token.balance(&creator), 40);
+
+    env.ledger().set_timestamp(start + WEEK + 100);
+    client.collect(&subscriber, &creator);
     env.ledger().set_timestamp(100);
     client.subscribe(&subscriber, &creator, &token.address, &300, &2);
 
@@ -256,6 +330,7 @@ fn test_pause_channel_blocks_charges_and_unpause_resumes() {
     client.unpause_channel(&creator);
     assert!(!client.is_channel_paused(&creator));
 
+    env.ledger().set_timestamp(start + WEEK + 110);
     env.ledger().set_timestamp(210);
     client.collect(&subscriber, &creator);
     assert_eq!(token.balance(&creator), 60);
@@ -280,6 +355,21 @@ fn test_pause_channel_applies_to_all_subscribers() {
     let contract_id = env.register(SubStreamContract, ());
     let client = SubStreamContractClient::new(&env, &contract_id);
 
+    let start = 100u64;
+    env.ledger().set_timestamp(start);
+    client.subscribe(&subscriber_1, &creator, &token.address, &200, &1);
+    client.subscribe(&subscriber_2, &creator, &token.address, &200, &1);
+
+    env.ledger().set_timestamp(start + WEEK + 30);
+    client.pause_channel(&creator);
+    assert_eq!(token.balance(&creator), 60);
+
+    env.ledger().set_timestamp(start + WEEK + 130);
+    client.unpause_channel(&creator);
+
+    env.ledger().set_timestamp(start + WEEK + 140);
+    let total = client.withdraw_all(&creator, &10);
+
     env.ledger().set_timestamp(100);
     client.subscribe(&subscriber_1, &creator, &token.address, &200, &1);
     client.subscribe(&subscriber_2, &creator, &token.address, &200, &1);
@@ -318,6 +408,12 @@ fn test_cliff_threshold_access() {
 
     client.set_cliff_threshold(&creator, &50);
 
+    let start = 100u64;
+    env.ledger().set_timestamp(start);
+    client.subscribe(&subscriber, &creator, &token.address, &100, &1);
+
+    env.ledger().set_timestamp(start + WEEK + 30);
+
     env.ledger().set_timestamp(100);
     client.subscribe(&subscriber, &creator, &token.address, &100, &1);
 
@@ -326,12 +422,38 @@ fn test_cliff_threshold_access() {
     assert!(!client.has_unlocked_access(&subscriber, &creator));
     assert_eq!(client.get_access_tier(&subscriber, &creator), 0);
 
+    env.ledger().set_timestamp(start + WEEK + 50);
     env.ledger().set_timestamp(150);
     client.collect(&subscriber, &creator);
     assert!(client.has_unlocked_access(&subscriber, &creator));
     assert_eq!(client.get_access_tier(&subscriber, &creator), 1);
 }
 
+#[test]
+fn test_migrate_tier_downgrade_prorates_refund() {
+    let env = Env::default();
+    env.mock_all_auths();
+
+    let subscriber = Address::generate(&env);
+    let creator = Address::generate(&env);
+    let admin = Address::generate(&env);
+
+    let token = create_token_contract(&env, &admin);
+    let token_admin = token::StellarAssetClient::new(&env, &token.address);
+    token_admin.mint(&subscriber, &1000);
+
+    let contract_id = env.register(SubStreamContract, ());
+    let client = SubStreamContractClient::new(&env, &contract_id);
+
+    let start = 100u64;
+    env.ledger().set_timestamp(start);
+    client.subscribe(&subscriber, &creator, &token.address, &100, &10);
+
+    env.ledger().set_timestamp(start + WEEK + 5);
+    client.migrate_tier(&subscriber, &creator, &5, &0);
+
+    assert_eq!(token.balance(&creator), 50);
+
 #[test]
 fn test_migrate_tier_downgrade_prorates_refund() {
     let env = Env::default();