Merge pull request #825 from opratem/feat/dynamic-fee

Feat/dynamic fee

Author: Utilitycoder

contracts/payment-stream/src/lib.rs

@@ -32,6 +32,10 @@ pub enum DataKey {
     Dispute(u64),
     /// The id of the currently active (unresolved) dispute for a stream, if any.
     ActiveDispute(u64),
+    /// Configured fee-tier list for volume-based protocol fee discounts (instance storage).
+    FeeTiers,
+    /// Cumulative escrowed volume for a sender address, used for fee-tier eligibility (persistent storage).
+    SenderVolume(Address),
 }
 
 /// Stream status enum
@@ -103,18 +107,17 @@ pub struct ProtocolMetrics {
     pub total_delegations: u64,       // Total number of delegations across all streams
 }
 
-/// Fee tier threshold and fee rate pair.
+/// Fee tier configuration for volume-based protocol fee discounts.
 ///
-/// Represents: "if the donor's cumulative volume is `>= threshold`, apply
-/// `fee_rate`".  The tier list is sorted by strictly increasing thresholds;
-/// the first tier must have a threshold of `0` so every donor is covered, and
-/// fee rates must be monotonically non-increasing across tiers.
+/// Tiers are stored sorted ascending by `min_volume`.  The highest tier
+/// whose `min_volume` is <= the sender's cumulative stream volume determines
+/// their protocol fee rate at withdrawal time.
 #[contracttype]
 #[derive(Clone)]
 pub struct FeeTier {
-    /// Minimum cumulative volume to qualify for this tier.
-    pub threshold: i128,
-    /// Fee rate in basis points applied for this tier (e.g., 250 = 2.5 %).
+    /// Minimum cumulative stream volume (token units) required for this tier
+    pub min_volume: i128,
+    /// Protocol fee rate in basis points (e.g., 30 = 0.3%, max 500 = 5%)
     pub fee_rate: u32,
 }
 
@@ -309,11 +312,16 @@ pub enum Error {
     InvalidTierConfiguration = 32,
     /// Fee rates across tiers are not monotonically non-increasing
     TierFeeNotMonotonic = 33,
+    /// A tier configuration was invalid (rate exceeds max, bad sort order, etc.)
+    InvalidTier = 34,
+    /// More than MAX_TIERS entries were supplied
+    TooManyTiers = 35,
 }
 
 // Constants
 const MAX_FEE: u32 = 500; // 5% in basis points
 const MAX_STREAMS_PER_BATCH: u32 = 50; // max streams per create_batch_streams call
+const MAX_TIERS: u32 = 10; // max configurable fee tiers
 const LEDGER_THRESHOLD: u32 = 518400; // ~30 days at 5s/ledger
 const LEDGER_BUMP: u32 = 535680; // ~31 days
 const DISPUTE_TIMELOCK_DELAY: u64 = 172800; // 48 hours in seconds
@@ -359,12 +367,12 @@ impl PaymentStreamContract {
         // Tier 2 (500,000+):       100 bps (1.0 %)
         let default_tiers: Vec<FeeTier> = {
             let mut v = Vec::new(&env);
-            v.push_back(FeeTier { threshold: 0, fee_rate: 500 });
-            v.push_back(FeeTier { threshold: 50_000, fee_rate: 250 });
-            v.push_back(FeeTier { threshold: 500_000, fee_rate: 100 });
+            v.push_back(FeeTier { min_volume: 0, fee_rate: 500 });
+            v.push_back(FeeTier { min_volume: 50_000, fee_rate: 250 });
+            v.push_back(FeeTier { min_volume: 500_000, fee_rate: 100 });
             v
         };
-        env.storage().instance().set(&Symbol::new(&env, "fee_tiers"), &default_tiers);
+        env.storage().instance().set(&DataKey::FeeTiers, &default_tiers);
 
         // Initialize protocol metrics
         let initial_metrics = ProtocolMetrics {
@@ -392,6 +400,63 @@ impl PaymentStreamContract {
         }
     }
 
+    /// Resolve the applicable fee rate for a sender based on their cumulative
+    /// stream volume and the configured fee tiers.
+    ///
+    /// Tiers are walked in ascending order of `min_volume`; the last qualifying
+    /// entry wins. Falls back to the flat `FeeRate` when no tiers are configured
+    /// or when the sender's volume is below all tier thresholds.
+    fn get_applicable_fee_rate_internal(env: &Env, sender: &Address) -> u32 {
+        let general_rate: u32 = env.storage().instance()
+            .get(&DataKey::FeeRate)
+            .unwrap_or(0);
+
+        let tiers: Vec<FeeTier> = env.storage().instance()
+            .get(&DataKey::FeeTiers)
+            .unwrap_or_else(|| Vec::new(env));
+
+        if tiers.is_empty() {
+            return general_rate;
+        }
+
+        let sender_vol_key = DataKey::SenderVolume(sender.clone());
+        let volume: i128 = env.storage().persistent()
+            .get(&sender_vol_key)
+            .unwrap_or(0);
+        if volume > 0 {
+            env.storage().persistent().extend_ttl(&sender_vol_key, LEDGER_THRESHOLD, LEDGER_BUMP);
+        }
+
+        // Start with the general rate; upgrade to each qualifying tier
+        let mut applicable_rate = general_rate;
+        let len = tiers.len();
+        for i in 0..len {
+            let tier = tiers.get(i).unwrap();
+            if volume >= tier.min_volume {
+                applicable_rate = tier.fee_rate;
+            }
+        }
+        applicable_rate
+    }
+
+    /// Calculate the protocol fee for a withdrawal amount.
+    ///
+    /// Uses the sender's cumulative stream volume to select the applicable
+    /// fee tier, rewarding high-volume ecosystem donors with lower fees.
+    fn calculate_protocol_fee(env: &Env, amount: i128, sender: &Address) -> i128 {
+        let fee_rate = Self::get_applicable_fee_rate_internal(env, sender);
+
+        if fee_rate == 0 {
+            return 0;
+        }
+
+        // fee = (amount * fee_rate) / 10000
+        // Split to avoid i128 overflow while preserving precision
+        let rate = fee_rate as i128;
+        let fee = (amount / 10000) * rate + ((amount % 10000) * rate) / 10000;
+        fee.max(0)
+    }
+
     /// Activate the global emergency pause switch.
     ///
     /// When active, all calls to `create_stream`, `deposit`, `withdraw`, and
@@ -735,13 +800,17 @@ impl PaymentStreamContract {
         env.storage().persistent().extend_ttl(&DataKey::Stream(stream_id), LEDGER_THRESHOLD, LEDGER_BUMP);
         env.storage().persistent().extend_ttl(&DataKey::Metrics(stream_id), LEDGER_THRESHOLD, LEDGER_BUMP);
 
-        // Update donor cumulative volume for fee tier calculation
-        let donor_volume_key = (Symbol::new(&env, "donor_volume"), sender.clone());
-        let current_volume: i128 = env.storage().persistent().get(&donor_volume_key).unwrap_or(0);
-        let new_volume = current_volume.checked_add(total_amount)
-            .unwrap_or_else(|| panic_with_error!(&env, Error::ArithmeticOverflow));
-        env.storage().persistent().set(&donor_volume_key, &new_volume);
-        env.storage().persistent().extend_ttl(&donor_volume_key, LEDGER_THRESHOLD, LEDGER_BUMP);
+        // Track sender's cumulative escrowed volume for fee tier eligibility.
+        // Only funds actually escrowed (initial_amount) are counted here to
+        // prevent tier-gaming via zero-deposit streams.  Additional deposits
+        // via deposit() also increment this counter.
+        let sender_vol_key = DataKey::SenderVolume(sender.clone());
+        let current_vol: i128 = env.storage().persistent()
+            .get(&sender_vol_key)
+            .unwrap_or(0);
+        let new_vol = current_vol.saturating_add(initial_amount);
+        env.storage().persistent().set(&sender_vol_key, &new_vol);
+        env.storage().persistent().extend_ttl(&sender_vol_key, LEDGER_THRESHOLD, LEDGER_BUMP);
 
         // Update protocol metrics
         let mut protocol_metrics: ProtocolMetrics = env.storage().instance()
@@ -813,6 +882,18 @@ impl PaymentStreamContract {
         env.storage().persistent().set(&DataKey::Metrics(stream_id), &metrics);
         env.storage().persistent().extend_ttl(&DataKey::Metrics(stream_id), LEDGER_THRESHOLD, LEDGER_BUMP);
 
+        // Update sender's cumulative volume for fee tier eligibility.
+        // deposit() actually moves tokens into escrow, so each deposited
+        // amount counts toward the sender's volume just as initial_amount
+        // does at stream creation.
+        let sender_vol_key = DataKey::SenderVolume(stream.sender.clone());
+        let current_vol: i128 = env.storage().persistent()
+            .get(&sender_vol_key)
+            .unwrap_or(0);
+        let new_vol = current_vol.saturating_add(amount);
+        env.storage().persistent().set(&sender_vol_key, &new_vol);
+        env.storage().persistent().extend_ttl(&sender_vol_key, LEDGER_THRESHOLD, LEDGER_BUMP);
+
         // Emit StreamDeposit event
         StreamDepositEvent { stream_id, amount }.publish(&env);
     }
@@ -1156,48 +1237,6 @@ impl PaymentStreamContract {
         env.storage().persistent().get(&DataKey::Delegate(stream_id))
     }
 
-    /// Calculate the protocol fee for a given withdrawal based on the
-    /// donor's cumulative volume and the configured fee tiers.
-    ///
-    /// Falls back to the flat `FeeRate` if no tier list has been configured
-    /// (should not happen after `initialize`).
-    fn calculate_protocol_fee(env: &Env, donor: &Address, amount: i128) -> i128 {
-        if amount <= 0 {
-            return 0;
-        }
-
-        // Get donor's cumulative volume
-        let donor_volume_key = (Symbol::new(env, "donor_volume"), donor.clone());
-        let cumulative_volume: i128 = env.storage().persistent().get(&donor_volume_key).unwrap_or(0);
-
-        // Get fee tiers (fallback to flat fee if tiers not configured)
-        let tiers: Vec<FeeTier> = match env.storage().instance().get(&Symbol::new(env, "fee_tiers")) {
-            Some(tiers) => tiers,
-            None => {
-                // Fallback: use general fee rate if tiers not set up
-                let fee_rate: u32 = env.storage().instance().get(&DataKey::FeeRate).unwrap_or(0);
-                let rate = fee_rate as i128;
-                return (amount / 10000) * rate + ((amount % 10000) * rate) / 10000;
-            }
-        };
-
-        // Determine applicable tier
-        let mut applicable_fee_rate: u32 = 0;
-        for tier in tiers.iter() {
-            if cumulative_volume >= tier.threshold {
-                applicable_fee_rate = tier.fee_rate;
-            }
-        }
-
-        // Calculate fee with the determined rate
-        if applicable_fee_rate == 0 {
-            return 0;
-        }
-
-        let rate = applicable_fee_rate as i128;
-        let fee = (amount / 10000) * rate + ((amount % 10000) * rate) / 10000;
-        fee.max(0)
-    }
 
     /// Calculate withdrawable amount for a stream
     pub fn withdrawable_amount(env: Env, stream_id: u64) -> i128 {
@@ -1263,7 +1302,7 @@ impl PaymentStreamContract {
         }
 
         // Calculate protocol fee based on donor's cumulative volume
-        let fee = Self::calculate_protocol_fee(&env, &stream.sender, amount);
+        let fee = Self::calculate_protocol_fee(&env, amount, &stream.sender);
         let net_amount = amount - fee;
 
         stream.withdrawn_amount += amount;
@@ -1465,6 +1504,11 @@ impl PaymentStreamContract {
     }
 
     /// Set the protocol fee rate
+    ///
+    /// # Errors
+    /// * [`Error::FeeTooHigh`] — `new_fee_rate > MAX_FEE`.
+    /// * [`Error::InvalidTier`] — `new_fee_rate` is below the first configured
+    ///   tier's fee_rate (would violate the non-increasing invariant).
     pub fn set_protocol_fee_rate(env: Env, new_fee_rate: u32) {
         let admin: Address = env.storage().instance().get(&DataKey::Admin).unwrap();
         admin.require_auth();
@@ -1473,6 +1517,20 @@ impl PaymentStreamContract {
             panic_with_error!(&env, Error::FeeTooHigh);
         }
 
+        // Preserve the non-increasing fee-rate invariant: the general rate must
+        // be >= every configured tier rate.  The first tier has the highest
+        // fee_rate among all tiers (since tiers are stored non-increasing), so
+        // checking only the first tier is sufficient.
+        let tiers: Vec<FeeTier> = env.storage().instance()
+            .get(&DataKey::FeeTiers)
+            .unwrap_or_else(|| Vec::new(&env));
+        if !tiers.is_empty() {
+            let first_tier = tiers.get(0).unwrap();
+            if new_fee_rate < first_tier.fee_rate {
+                panic_with_error!(&env, Error::InvalidTier);
+            }
+        }
+
         env.storage().instance().set(&DataKey::FeeRate, &new_fee_rate);
         env.storage().instance().extend_ttl(LEDGER_THRESHOLD, LEDGER_BUMP);
     }
@@ -1496,17 +1554,18 @@ impl PaymentStreamContract {
         env.storage().instance().get(&DataKey::FeeCollector).unwrap()
     }
 
-    /// Replace the fee-tier configuration (admin only).
+    /// Set fee tiers for volume-based protocol fee discounts (admin only).
     ///
-    /// `tiers` must be a non-empty list whose first entry has a threshold of
-    /// `0`, whose thresholds are strictly increasing, and whose fee rates are
-    /// monotonically non-increasing and at most [`MAX_FEE`].
+    /// `tiers` must be sorted in **strictly ascending** order by `min_volume`.
+    /// Each tier's `fee_rate` must not exceed `MAX_FEE` (500 bps = 5%).
+    /// Pass an empty Vec to clear all tiers and revert to the flat `FeeRate`.
     ///
     /// # Errors
-    /// * [`Error::InvalidTierConfiguration`] — empty list, first threshold not
-    ///   zero, or thresholds not strictly increasing.
-    /// * [`Error::TierFeeNotMonotonic`]     — fee rates increase across tiers.
-    /// * [`Error::FeeTooHigh`]              — a tier fee rate exceeds 500 bps.
+    /// * [`Error::Unauthorized`] — caller is not the contract admin.
+    /// * [`Error::TooManyTiers`] — `tiers.len() > MAX_TIERS` (10).
+    /// * [`Error::InvalidTier`] — a tier's `fee_rate` exceeds `MAX_FEE`, or tiers
+    ///   are not strictly sorted ascending by `min_volume`, or fee rates are
+    ///   not monotonically non-increasing.
     pub fn set_fee_tiers(env: Env, tiers: Vec<FeeTier>) {
         let admin: Address = env
             .storage()
@@ -1515,56 +1574,60 @@ impl PaymentStreamContract {
             .unwrap_or_else(|| panic_with_error!(&env, Error::NotInitialized));
         admin.require_auth();
 
-        // Validate that tiers is not empty
-        if tiers.is_empty() {
-            panic_with_error!(&env, Error::InvalidTierConfiguration);
-        }
-
-        // Validate first tier has threshold 0
-        if let Some(first_tier) = tiers.first() {
-            if first_tier.threshold != 0 {
-                panic_with_error!(&env, Error::InvalidTierConfiguration);
-            }
+        if tiers.len() > MAX_TIERS {
+            panic_with_error!(&env, Error::TooManyTiers);
         }
 
-        // Validate thresholds are strictly increasing
-        let mut prev_threshold: i128 = -1;
-        for tier in tiers.iter() {
-            if tier.threshold <= prev_threshold {
-                panic_with_error!(&env, Error::InvalidTierConfiguration);
+        let general_rate: u32 = env.storage().instance()
+            .get(&DataKey::FeeRate)
+            .unwrap_or(0);
+        let mut prev_min_volume: i128 = -1_i128;
+        let mut prev_fee_rate: u32 = general_rate;
+        let len = tiers.len();
+        for i in 0..len {
+            let tier = tiers.get(i).unwrap();
+            if tier.fee_rate > MAX_FEE {
+                panic_with_error!(&env, Error::InvalidTier);
             }
-            prev_threshold = tier.threshold;
-        }
-
-        // Validate fee rates are monotonically non-increasing and within MAX_FEE
-        let mut prev_fee_rate: u32 = u32::MAX;
-        for tier in tiers.iter() {
             if tier.fee_rate > prev_fee_rate {
-                panic_with_error!(&env, Error::TierFeeNotMonotonic);
+                panic_with_error!(&env, Error::InvalidTier);
             }
-            if tier.fee_rate > MAX_FEE {
-                panic_with_error!(&env, Error::FeeTooHigh);
+            if tier.min_volume <= prev_min_volume {
+                panic_with_error!(&env, Error::InvalidTier);
             }
+            prev_min_volume = tier.min_volume;
             prev_fee_rate = tier.fee_rate;
         }
 
-        // Store the new tier configuration
-        env.storage().instance().set(&Symbol::new(&env, "fee_tiers"), &tiers);
+        env.storage().instance().set(&DataKey::FeeTiers, &tiers);
         env.storage().instance().extend_ttl(LEDGER_THRESHOLD, LEDGER_BUMP);
+
+        env.events().publish(("FeeTiersUpdated",), ());
     }
 
-    /// Get the current fee-tier configuration.
+    /// Return the currently configured fee tiers.
+    /// Returns an empty Vec when no tiers have been configured.
     pub fn get_fee_tiers(env: Env) -> Vec<FeeTier> {
-        match env.storage().instance().get(&Symbol::new(&env, "fee_tiers")) {
-            Some(tiers) => tiers,
-            None => Vec::new(&env),
-        }
+        env.storage().instance()
+            .get(&DataKey::FeeTiers)
+            .unwrap_or_else(|| Vec::new(&env))
+    }
+
+    /// Return the cumulative escrowed volume for a sender address.
+    ///
+    /// This is the sum of all tokens the sender has actually transferred into
+    /// escrow: the `initial_amount` at stream creation plus any subsequent
+    /// `deposit()` calls.  It determines their position in the fee tier
+    /// hierarchy and cannot be gamed by declaring a large `total_amount`
+    /// without depositing funds.
+    pub fn get_sender_volume(env: Env, sender: Address) -> i128 {
+        let sender_vol_key = DataKey::SenderVolume(sender);
+        env.storage().persistent().get(&sender_vol_key).unwrap_or(0)
     }
 
-    /// Get a donor's cumulative streamed volume, used to select their fee tier.
-    pub fn get_donor_cumulative_volume(env: Env, donor: Address) -> i128 {
-        let donor_volume_key = (Symbol::new(&env, "donor_volume"), donor);
-        env.storage().persistent().get(&donor_volume_key).unwrap_or(0)
+    /// Return the applicable fee rate for a sender given their current volume.
+    pub fn get_applicable_fee_rate(env: Env, sender: Address) -> u32 {
+        Self::get_applicable_fee_rate_internal(&env, &sender)
     }
 
     /// Get stream-specific metrics