Merge pull request #1491 from abimbolaalabi/fix/1326-volume-based-dynamic-fee-tiers

[Contract] — Volume-Based Dynamic Fee Tiers #1326

Author: Olowodarey

contracts/open-market/src/config.rs

@@ -8,7 +8,7 @@ pub enum ReputationDecayMode {
 }
 
 use crate::errors::InsightArenaError;
-use crate::storage_types::DataKey;
+use crate::storage_types::{DataKey, VolumeFeeConfig};
 
 // ── TTL constants ─────────────────────────────────────────────────────────────
 // Assuming ~5 s per ledger:
@@ -244,6 +244,11 @@ pub struct Config {
     /// via `ProposalType::UpdateQuorum` (timelocked governance path). Defaults
     /// to `1000` (10%) at initialization.
     pub governance_quorum_bps: u32,
+/// Volume-based fee tier schedule. Governs the swap fee charged by every
+    /// market's AMM pool based on its cumulative trading volume.
+    /// Governance-configurable via `set_volume_fee_config` (admin, immediate).
+    /// Defaults to [`VolumeFeeConfig::default_config`] at initialization.
+    pub volume_fee_config: VolumeFeeConfig,
     /// Stake (stroops) an oracle must lock via
     /// `dispute::submit_resolution_with_stake` when submitting a market
     /// resolution. Held through the market's dispute window; slashed if a
@@ -399,6 +404,7 @@ pub fn initialize(
         arbiter_slash_bps: 1000,  // 10% of stake slashed for a missed vote
         arbiter_voting_period_seconds: 172_800, // ~2 days
         governance_quorum_bps: 1000, // 10% of registered users must participate
+volume_fee_config: VolumeFeeConfig::default_config(env),
         oracle_stake_amount: 100_000_000, // 10 XLM expressed in stroops
         oracle_reward_bps: 500, // 5% of stake paid as a reward when resolution stands
         vesting_tranche_count: 4,
@@ -1104,6 +1110,83 @@ fn emit_governance_quorum_updated(env: &Env, old_quorum_bps: u32, new_quorum_bps
     );
 }
 
+// ── Volume Fee Config ──────────────────────────────────────────────────────────
+
+fn validate_volume_fee_config(config: &VolumeFeeConfig) -> Result<(), InsightArenaError> {
+    if config.tiers.is_empty() {
+        return Err(InsightArenaError::InvalidInput);
+    }
+
+    // Tier 0 must have threshold 0.
+    let first = config.tiers.get(0).unwrap();
+    if first.volume_threshold != 0 {
+        return Err(InsightArenaError::InvalidInput);
+    }
+
+    // Thresholds must be monotonically increasing.
+    let mut prev_threshold = first.volume_threshold;
+    for i in 1..config.tiers.len() {
+        let entry = config.tiers.get(i).unwrap();
+        if entry.volume_threshold <= prev_threshold {
+            return Err(InsightArenaError::InvalidInput);
+        }
+        prev_threshold = entry.volume_threshold;
+    }
+
+    Ok(())
+}
+
+/// Update the volume-based fee tier schedule. Caller must be the stored admin.
+///
+/// The new schedule must have at least one tier, with tier 0's threshold at `0`,
+/// and monotonically increasing thresholds thereafter. All fee rates must be
+/// ≤ 10_000 bps.
+pub fn set_volume_fee_config(
+    env: &Env,
+    admin: Address,
+    new_config: VolumeFeeConfig,
+) -> Result<(), InsightArenaError> {
+    let mut config = load_config(env)?;
+
+    admin.require_auth();
+    if admin != config.admin {
+        return Err(InsightArenaError::Unauthorized);
+    }
+
+    validate_volume_fee_config(&new_config)?;
+
+    let old_config = config.volume_fee_config.clone();
+    config.volume_fee_config = new_config;
+    env.storage().persistent().set(&DataKey::Config, &config);
+    bump_config(env);
+
+    emit_volume_fee_config_updated(env, &old_config, &config.volume_fee_config);
+
+    Ok(())
+}
+
+fn emit_volume_fee_config_updated(
+    env: &Env,
+    old_config: &VolumeFeeConfig,
+    new_config: &VolumeFeeConfig,
+) {
+    env.events().publish(
+        (symbol_short!("cfg"), symbol_short!("vfc_upd")),
+        (old_config.clone(), new_config.clone()),
+    );
+}
+
+/// Return the current volume-based fee tier schedule. Extends the Config TTL.
+pub fn get_volume_fee_config(env: &Env) -> VolumeFeeConfig {
+    match load_config(env) {
+        Ok(config) => {
+            bump_config(env);
+            config.volume_fee_config
+        }
+        Err(_) => VolumeFeeConfig::default_config(env),
+    }
+}
+
 fn validate_oracle_stake_config(stake_amount: i128, reward_bps: u32) -> Result<(), InsightArenaError> {
     if stake_amount <= 0 {
         return Err(InsightArenaError::InvalidInput);

contracts/open-market/src/lib.rs

@@ -1194,4 +1194,20 @@ impl InsightArenaContract {
     ) -> Result<(), InsightArenaError> {
         liquidity::set_fee_tier_config(&env, admin, new_config)
     }
+
+    // ── Volume-Based Fee Tiers (#1326) ──────────────────────────────────────────
+
+    /// Return the current volume-based fee tier schedule.
+    pub fn get_volume_fee_config(env: Env) -> crate::storage_types::VolumeFeeConfig {
+        config::get_volume_fee_config(&env)
+    }
+
+    /// Update the volume-based fee tier schedule. Caller must be the platform admin.
+    pub fn update_volume_fee_config(
+        env: Env,
+        admin: Address,
+        new_config: crate::storage_types::VolumeFeeConfig,
+    ) -> Result<(), InsightArenaError> {
+        config::set_volume_fee_config(&env, admin, new_config)
+    }
 }

contracts/open-market/src/liquidity.rs

@@ -6,7 +6,7 @@ use crate::escrow;
 use crate::market;
 use crate::storage_types::{
     DataKey, FeeTier, FeeTierConfig, LPPosition, LiquidityPool, Market, MarketFeeInfo,
-    PriceAccumulator, PriceObservation, SwapRecord, VolatilityState,
+    PriceAccumulator, PriceObservation, SwapRecord, VolatilityState, VolumeFeeConfig,
 };
 
 // ── Constants ─────────────────────────────────────────────────────────────────
@@ -142,6 +142,29 @@ pub fn fee_bps_for_tier(tier: &FeeTier, cfg: &FeeTierConfig) -> u32 {
     }
 }
 
+/// Select the volume-based fee tier for a market given its cumulative volume.
+/// Returns the index into `VolumeFeeConfig::tiers` and the corresponding fee bps.
+/// The last tier whose threshold is ≤ `cumulative_volume` is chosen.
+pub fn select_volume_fee_tier(
+    cumulative_volume: i128,
+    config: &VolumeFeeConfig,
+) -> (u32, u32) {
+    let mut active_idx: u32 = 0;
+    let mut active_fee_bps = config.tiers.get(0).map(|t| t.fee_bps).unwrap_or(30);
+
+    for i in 1..config.tiers.len() {
+        let entry = config.tiers.get(i).unwrap();
+        if cumulative_volume >= entry.volume_threshold {
+            active_idx = i;
+            active_fee_bps = entry.fee_bps;
+        } else {
+            break;
+        }
+    }
+
+    (active_idx, active_fee_bps)
+}
+
 fn validate_fee_tier_config(cfg: &FeeTierConfig) -> Result<(), InsightArenaError> {
     if cfg.calm_threshold_bps >= cfg.volatile_threshold_bps {
         return Err(InsightArenaError::InvalidInput);
@@ -265,20 +288,28 @@ fn update_volatility_state(
     Ok(state)
 }
 
-/// Return the current dynamic fee tier and effective swap fee for a market.
+/// Return the current dynamic fee state for a market.
+/// `effective_fee_bps` reflects the volume-based fee tier active for this
+/// market's cumulative volume. Volatility-tier info (`tier`, `volatility_ema_bps`)
+/// is provided for informational / off-chain analysis.
 pub fn get_market_fee_info(env: &Env, market_id: u64) -> Result<MarketFeeInfo, InsightArenaError> {
-    market::get_market(env, market_id)?;
+    let mkt = market::get_market(env, market_id)?;
 
     let tier_config = get_fee_tier_config(env);
     let volatility = get_volatility_state(env, market_id);
     let tier = determine_fee_tier(volatility.ema_bps, &tier_config);
-    let effective_fee_bps = fee_bps_for_tier(&tier, &tier_config);
+
+    let cfg = config::get_config(env)?;
+    let (volume_tier_index, effective_fee_bps) =
+        select_volume_fee_tier(mkt.cumulative_volume, &cfg.volume_fee_config);
 
     Ok(MarketFeeInfo {
         market_id,
         tier,
         effective_fee_bps,
         volatility_ema_bps: volatility.ema_bps,
+        volume_tier_index,
+        volume_tier_fee_bps: effective_fee_bps,
     })
 }
 
@@ -962,12 +993,17 @@ pub fn swap_outcome(
         .get(to_outcome.clone())
         .ok_or(InsightArenaError::InvalidOutcome)?;
 
-    // Fee tier is derived from volatility observed *before* this swap, so a
-    // trade cannot influence the fee rate it itself pays.
+    // ── Volume-based fee tier selection ────────────────────────────────────
+    // The fee is derived from the market's cumulative volume *before* this
+    // swap, so a trade cannot influence the fee rate it itself pays.
+    let cfg = config::get_config(env)?;
+    let volume_before = mkt.cumulative_volume;
+    let (volume_tier_before, effective_fee_bps) =
+        select_volume_fee_tier(volume_before, &cfg.volume_fee_config);
+
+    // Volatility state is still tracked (for informational purposes / TWAP).
     let tier_config = get_fee_tier_config(env);
     let volatility_before = get_volatility_state(env, market_id);
-    let tier = determine_fee_tier(volatility_before.ema_bps, &tier_config);
-    let effective_fee_bps = fee_bps_for_tier(&tier, &tier_config);
 
     let amount_out = calculate_swap_output(amount_in, from_reserve, to_reserve, effective_fee_bps)?;
 
@@ -984,6 +1020,7 @@ pub fn swap_outcome(
     // Split the fee between the protocol treasury and liquidity providers.
     // `lp_fee_share` is derived by subtraction so the two shares always sum
     // to `fee_amount` exactly, with no stroop lost or double-counted.
+    // Protocol share bps is read from the volatility-based FeeTierConfig.
     let protocol_fee_share = fee_amount
         .checked_mul(tier_config.protocol_share_bps as i128)
         .ok_or(InsightArenaError::Overflow)?
@@ -1027,7 +1064,6 @@ pub fn swap_outcome(
     // default `treasury_split_bps == 10_000`, so the entire protocol fee
     // share keeps flowing to the treasury exactly as it did before this
     // split was introduced.
-    let cfg = config::get_config(env)?;
     let treasury_amount = protocol_fee_share
         .checked_mul(cfg.treasury_split_bps as i128)
         .ok_or(InsightArenaError::Overflow)?
@@ -1054,6 +1090,26 @@ pub fn swap_outcome(
         total_lp_share,
     );
 
+    // ── Update cumulative market volume and detect tier crossing ─────────────
+    let new_volume = volume_before
+        .checked_add(amount_in)
+        .ok_or(InsightArenaError::Overflow)?;
+
+    let (volume_tier_after, _) =
+        select_volume_fee_tier(new_volume, &cfg.volume_fee_config);
+
+    if volume_tier_after > volume_tier_before {
+        emit_volume_tier_crossed(env, market_id, volume_tier_before, volume_tier_after, new_volume);
+    }
+
+    let mut mkt = mkt;
+    mkt.cumulative_volume = new_volume;
+    env.storage()
+        .persistent()
+        .set(&DataKey::Market(market_id), &mkt);
+    market::bump_market(env, market_id);
+
+    // ── Record swap with volume tier snapshot ────────────────────────────────
     let record = SwapRecord::new(
         trader,
         market_id,
@@ -1063,6 +1119,7 @@ pub fn swap_outcome(
         amount_out,
         fee_amount,
         env.ledger().timestamp(),
+        volume_tier_before,
     );
 
     let mut history: Vec<SwapRecord> = env
@@ -1080,6 +1137,19 @@ pub fn swap_outcome(
     Ok(amount_out)
 }
 
+fn emit_volume_tier_crossed(
+    env: &Env,
+    market_id: u64,
+    from_tier: u32,
+    to_tier: u32,
+    cumulative_volume: i128,
+) {
+    env.events().publish(
+        (symbol_short!("vol"), symbol_short!("tier_x")),
+        (market_id, from_tier, to_tier, cumulative_volume),
+    );
+}
+
 /// Emit an event recording exactly how a swap's collected fee was split
 /// between the protocol treasury and liquidity providers. Published on every
 /// swap that reaches the fee-collection step, including zero-fee swaps (in

contracts/open-market/src/market.rs

@@ -33,7 +33,7 @@ pub struct CreateMarketParams {
 
 // ── TTL helpers ───────────────────────────────────────────────────────────────
 
-fn bump_market(env: &Env, market_id: u64) {
+pub(crate) fn bump_market(env: &Env, market_id: u64) {
     config::extend_market_ttl(env, market_id);
 }