feat: Implement DAO-Governed Protocol Fee Parameterization

[BarryArinze]

🧩 Overview

This PR replaces the hardcoded protocol fee with a DAO-governed configurable fee model.

The protocol fee can now be updated through an authorized DAO multi-sig via update_protocol_fee, enabling governance-driven adjustments over time while preserving merchant protections through hard caps and timelocked fee increases.

⚙️ Key Features

• Replaced static fee constant with persistent configurable protocol_fee_bps
• Added update_protocol_fee(new_fee_bps) restricted to DAO multi-sig
• Enforced maximum fee cap of 500 bps (5%)
• Immediate application for fee decreases
• 7-day timelock for any fee increase
• Added scheduled fee state with activation timestamp
• Updated all future subscription pulls to use active fee rate
• Recalculates merchant payout vs treasury share dynamically
• Emits governance transparency events

📢 Events Added

• ProtocolFeeUpdateScheduled(old_fee_bps, new_fee_bps, activate_at)
• ProtocolFeeUpdateExecuted(old_fee_bps, new_fee_bps)

🏗️ Implementation Details

Fee Update Logic

• If new_fee_bps <= current_fee_bps

  • apply immediately

• If new_fee_bps > current_fee_bps

  • store pending update
  • activate after 7 days

Pull Settlement Logic

For each subscription pull:

1. Resolve any matured pending fee update
2. Calculate treasury cut using current active fee
3. Route remaining amount to merchant
4. Prevent rounding inconsistencies / dust leakage

Example

For a pull of 100 XLM equivalent:

• Fee = 200 bps → treasury gets 2%
• Merchant receives 98%

If updated to 300 bps:

• Change becomes active after 7 days
• All pulls after activation use 3%

🔐 Security Considerations

• Only DAO multi-sig can update fees
• Hard cap prevents abusive pricing
• Timelock gives merchants time to react
• Safe arithmetic for basis point calculations
• Exact stroop-level rounding behavior validated
• No unintended truncation of merchant revenue

🧪 Testing

Added tests for:

• DAO authorized fee updates succeed
• Unauthorized callers revert
• Fee above 500 bps rejected
• Fee decrease applies immediately
• Fee increase delayed by 7 days
• Pending update activates after timelock
• Mid-cycle subscription pull uses correct fee before/after activation
• Exact merchant/treasury stroop distribution
• No fractional dust remains trapped

✅ Acceptance Criteria Covered

Acceptance 1

DAO can successfully adjust protocol fee model over time.

Acceptance 2

Caps + timelocks protect merchants from extortionate hikes.

Acceptance 3

Settlement math routes funds precisely without leftover dust.

🚀 Impact

• Introduces sustainable protocol governance
• Improves treasury flexibility
• Protects merchants through structural safeguards
• Future-proofs revenue configuration

🔗 Related Issue

Closes #116

🏷️ Labels

governance, economics, math

[drips-wave]

@BarryArinze 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