Merge pull request #379 from Macnelson9/feat/fee-tier-system

feat: Fee Tier System — tier query functions (#218)

Author: Mystery-CLI

contract/src/lib.rs

@@ -24,6 +24,10 @@ pub use analytics::{
 };
 pub use errors::ContractError;
 pub use types::{
+    ArbitrationConfig, ArbitratorReputation, ArbitratorVote, DisclosureGrant, DisputeResolution,
+    InsurancePolicy, MultiSigConfig, Proposal, ProposalAction, ProposalStatus, Subscription,
+    SubscriptionTier, TierConfig, TierStatus, TierThresholds, TemplateTerms, TemplateVersion,
+    Trade, TradePrivacy, TradeStatus, TradeTemplate, UserTier, UserTierInfo, VotingSummary,
     ArbitrationConfig, CrossChainInfo, DisputeResolution, InsurancePolicy, KycStatus,
     OptionalMetadata, Trade, TradeStatus, UserCompliance, MAX_INSURANCE_PREMIUM_BPS,
     MAX_METADATA_SIZE,
@@ -1000,6 +1004,80 @@ impl StellarEscrowContract {
         Ok(())
     }
 
+    /// Query a user's current tier info.
+    pub fn get_user_tier(env: Env, user: Address) -> Option<UserTierInfo> {
+        storage::get_user_tier(&env, &user)
+    }
+
+    /// Query the current tier fee configuration.
+    pub fn get_tier_config(env: Env) -> Option<TierConfig> {
+        storage::get_tier_config(&env)
+    }
+
+    /// Query the effective fee bps for a user's next trade.
+    pub fn get_effective_fee_bps(env: Env, user: Address) -> Result<u32, ContractError> {
+        let base = get_fee_bps(&env)?;
+        Ok(tiers::effective_fee_bps(&env, &user, base))
+    }
+
+    /// Query the volume thresholds required to reach Silver and Gold tiers.
+    pub fn get_tier_thresholds(_env: Env) -> TierThresholds {
+        tiers::get_tier_thresholds()
+    }
+
+    /// Query additional trading volume a user needs to reach the next tier.
+    /// Returns 0 if the user is already at Gold or has a custom fee.
+    pub fn get_volume_to_next_tier(env: Env, user: Address) -> u64 {
+        let info = storage::get_user_tier(&env, &user).unwrap_or(UserTierInfo {
+            tier: UserTier::Bronze,
+            total_volume: 0,
+            custom_fee_bps: None,
+        });
+        tiers::volume_to_next_tier(&info)
+    }
+
+    /// Query a complete tier status snapshot for a user: current tier, cumulative
+    /// volume, volume needed to reach the next tier, and effective fee bps.
+    pub fn get_user_tier_status(env: Env, user: Address) -> Result<TierStatus, ContractError> {
+        require_initialized(&env)?;
+        tiers::get_tier_status(&env, &user)
+    }
+
+    // -------------------------------------------------------------------------
+    // Trade Templates
+    // -------------------------------------------------------------------------
+
+    /// Create a reusable trade template (owner = seller).
+    pub fn create_template(
+        env: Env,
+        owner: Address,
+        name: soroban_sdk::String,
+        terms: TemplateTerms,
+    ) -> Result<u64, ContractError> {
+        require_initialized(&env)?;
+        owner.require_auth();
+        templates::create_template(&env, &owner, name, terms)
+    }
+
+    /// Update a template with new terms, bumping its version.
+    pub fn update_template(
+        env: Env,
+        caller: Address,
+        template_id: u64,
+        name: soroban_sdk::String,
+        terms: TemplateTerms,
+    ) -> Result<(), ContractError> {
+        require_initialized(&env)?;
+        caller.require_auth();
+        templates::update_template(&env, &caller, template_id, name, terms)
+    }
+
+    /// Deactivate a template so it can no longer be used to create trades.
+    pub fn deactivate_template(
+        env: Env,
+        caller: Address,
+        template_id: u64,
+    ) -> Result<(), ContractError> {
     pub fn set_bridge_oracle(env: Env, oracle: Address) -> Result<(), ContractError> {
         require_initialized(&env)?;
         storage::get_admin(&env)?.require_auth();

contract/src/tiers.rs

@@ -2,8 +2,11 @@ use soroban_sdk::{Address, Env};
 
 use crate::errors::ContractError;
 use crate::events;
-use crate::storage::{get_tier_config, get_user_tier, save_user_tier};
-use crate::types::{TierConfig, UserTier, UserTierInfo, TIER_GOLD_THRESHOLD, TIER_SILVER_THRESHOLD};
+use crate::storage::{get_fee_bps, get_tier_config, get_user_tier, save_user_tier};
+use crate::types::{
+    TierConfig, TierStatus, TierThresholds, UserTier, UserTierInfo,
+    TIER_GOLD_THRESHOLD, TIER_SILVER_THRESHOLD,
+};
 
 pub fn effective_fee_bps(env: &Env, user: &Address, base_fee_bps: u32) -> u32 {
     let info = match get_user_tier(env, user) {
@@ -112,3 +115,42 @@ pub fn remove_custom_fee(env: &Env, user: &Address) {
     info.tier = volume_tier(info.total_volume);
     save_user_tier(env, user, &info);
 }
+
+/// Returns the configured volume thresholds for Silver and Gold tiers.
+pub fn get_tier_thresholds() -> TierThresholds {
+    TierThresholds {
+        silver_threshold: TIER_SILVER_THRESHOLD,
+        gold_threshold: TIER_GOLD_THRESHOLD,
+    }
+}
+
+/// Returns how much additional trading volume is needed to reach the next tier.
+/// Returns 0 if the user is already at Gold tier or has a Custom fee.
+pub fn volume_to_next_tier(info: &UserTierInfo) -> u64 {
+    match info.tier {
+        UserTier::Bronze => TIER_SILVER_THRESHOLD.saturating_sub(info.total_volume),
+        UserTier::Silver => TIER_GOLD_THRESHOLD.saturating_sub(info.total_volume),
+        UserTier::Gold | UserTier::Custom => 0,
+    }
+}
+
+/// Returns a full tier status snapshot for a user, including their current tier,
+/// cumulative volume, volume needed for the next upgrade, and effective fee bps.
+pub fn get_tier_status(env: &Env, user: &Address) -> Result<TierStatus, ContractError> {
+    let base_fee_bps = get_fee_bps(env)?;
+    let info = get_user_tier(env, user).unwrap_or(UserTierInfo {
+        tier: UserTier::Bronze,
+        total_volume: 0,
+        custom_fee_bps: None,
+    });
+    let to_next = volume_to_next_tier(&info);
+    let fee_bps = effective_fee_bps(env, user, base_fee_bps);
+    let has_custom = info.custom_fee_bps.is_some();
+    Ok(TierStatus {
+        current_tier: info.tier,
+        total_volume: info.total_volume,
+        volume_to_next_tier: to_next,
+        effective_fee_bps: fee_bps,
+        has_custom_fee: has_custom,
+    })
+}

contract/src/types.rs

@@ -10,6 +10,32 @@ pub enum OptionalMetadata {
     Some(String),
 }
 
+/// Volume thresholds required to reach each tier.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct TierThresholds {
+    /// Minimum cumulative trade volume (in token units) to reach Silver tier
+    pub silver_threshold: u64,
+    /// Minimum cumulative trade volume (in token units) to reach Gold tier
+    pub gold_threshold: u64,
+}
+
+/// A snapshot of a user's current tier standing, including progress toward the next tier.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct TierStatus {
+    /// The user's current tier
+    pub current_tier: UserTier,
+    /// Total cumulative trading volume recorded for this user
+    pub total_volume: u64,
+    /// Additional volume needed to reach the next tier (0 if already at Gold or Custom)
+    pub volume_to_next_tier: u64,
+    /// The effective fee in basis points for the user's next trade
+    pub effective_fee_bps: u32,
+    /// Whether the user has a custom fee rate assigned
+    pub has_custom_fee: bool,
+}
+
 #[contracttype]
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub enum TradeStatus {