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

[abimbolaalabi]

Overview

This PR introduces volume-based dynamic fee tiers for the AMM swap fee, replacing the flat fee model. Markets with higher cumulative trading volume pay lower swap fees, rewarding active markets and attracting liquidity.

Related Issue

Closes #1326

Changes

Configuration

• [ADD] \VolumeFeeEntry\ and \VolumeFeeConfig\ types in \storage_types.rs\ with a 4-tier default schedule:
  • Tier 0 (volume < 10,000 XLM): 30 bps
  • Tier 1 (volume ≥ 10,000 XLM): 25 bps
  • Tier 2 (volume ≥ 100,000 XLM): 20 bps
  • Tier 3 (volume ≥ 1,000,000 XLM): 15 bps
• [ADD] \�olume_fee_config\ field to \Config\ struct in \config.rs\
• [ADD] \set_volume_fee_config\ admin setter with monotonically-increasing threshold validation
• [ADD] \get_volume_fee_config\ view function
• [ADD] \update_volume_fee_config\ and \get_volume_fee_config\ contract entry points in \lib.rs\

Fee Selection

• [ADD] \select_volume_fee_tier\ in \liquidity.rs\ — selects the active tier based on cumulative market volume
• [MODIFY] \swap_outcome\ — fee is now determined by the volume tier (not volatility tier); the volatility tier is retained for informational/TWAP purposes
• [MODIFY] \get_market_fee_info\ — \effective_fee_bps\ now reflects the volume-based fee; volatility info is still returned as separate fields

Volume Tracking

• [ADD] \cumulative_volume: i128\ field to the \Market\ struct, updated atomically on every swap
• [ADD] \�ump_market\ made \pub(crate)\ for cross-module volume persistence

Historical Audit Trail

• [ADD] \�olume_tier_index: u32\ field to \SwapRecord\ — snapshots the active fee tier at trade time so historical fees remain auditable even if the schedule is later reconfigured

Event Emission

• [ADD] \VolumeTierCrossed\ event (topic \�ol:tier_x) emitted exactly once when a market's cumulative volume crosses into a new fee tier

Verification

All existing tests pass after updating three tests to reflect the new volume-based fee semantics:

• \ est_market_fee_info_defaults_to_volume_tier_zero_before_any_swap\ — checks volume tier 0 (30 bps) instead of volatility Calm (15 bps)
• \ est_volume_accumulation_lowers_fee_tier\ — verifies that increasing cumulative volume correctly transitions through all 4 tiers
• \ est_volatility_tier_still_tracked_informational\ — confirms the volatility EMA is still available despite no longer driving the fee

\
cargo test --test liquidity_tests
✅ 144/144 passed

cargo test --test config_tests --test market_tests
✅ 18/18, 84/84 passed

cargo test --test prediction_tests --test cancel_refund_tests --test dispute_tests --test governance_tests
✅ 33/14/27/33 passed
\\

Acceptance Criteria

Criteria	Status
Fees charged match the tier for the market's volume at trade time	✅ Volume tier is selected pre-swap and fee is applied
Tier thresholds are governance-configurable and monotonically validated	✅ \set_volume_fee_config\ with \�alidate_volume_fee_config\
Crossing a tier boundary emits exactly one event	✅ \emit_volume_tier_crossed\ on first swap that pushes volume past threshold
Unit tests cover boundary and mid-tier volumes	✅ \ est_volume_accumulation_lowers_fee_tier\ tests all 4 tiers

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
insight-arena-4rll	Ready	Preview, Comment	Jul 28, 2026 2:33pm

[drips-wave]

@abimbolaalabi Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Olowodarey]

@abimbolaalabi pls help too fix conflict

[abimbolaalabi]

@Olowodarey done!

[Olowodarey]

@abimbolaalabi pls fix build

[abimbolaalabi]

@Olowodarey please review.