Protocol Fee Distributor Contract with Automatic Reward Splitting

[elizabetheonoja-art]

Problem Statement / Feature Objective

Protocol fees (settlement fees, oracle fees, late payment penalties) must be distributed to multiple stakeholders (protocol treasury, stakers, oracle operators, insurance pool). A fee distributor contract must be built that collects all protocol fees, splits them according to configurable ratios, and distributes to recipient contracts via pull-based claiming (users claim their share via Merkle proof), minimizing gas costs for the distribution operation.

Technical Invariants & Bounds

• Fee sources: settlement fee (0.1% of minted tokens), oracle fee (0.05%), late payment penalty (2%).
• Split ratios: treasury 40%, stakers 30%, oracle operators 20%, insurance pool 10%. Configurable via governance vote.
• Distribution period: daily; fees accumulated in a holding contract, distributed at period boundary.
• Claim model: Merkle tree root of (recipient, amount) published each period; recipients claim via claim(period, index, proof, amount).
• Unclaimed: unclaimed fees after 90 days are swept back to the treasury.
• Gas target: distribution (computing root + storing) < 50K gas; individual claim < 30K gas.

Codebase Navigation Guide

• contracts/fees/FeeCollector.sol — accumulates fees from all sources.
• contracts/fees/FeeDistributor.sol — period-based distribution with Merkle claims.
• contracts/fees/SplitConfig.sol — configurable split ratios with governance control.
• contracts/fees/SweepHandler.sol — unclaimed fee sweep after 90 days.

Implementation Blueprint

1. Implement FeeCollector: deposit(source, amount) called by settlement contract; tracks per-period accumulation.
2. Implement FeeDistributor: at period boundary, compute splits, build Merkle tree of (recipient, amount), store root.
3. Implement claim(period, index, proof, recipient, amount): verify proof, transfer tokens, mark claimed.
4. Implement SweepHandler: after 90 days, any unclaimed amounts are sent to treasury.
5. Foundry test: collect 1000 tokens in fees, distribute with 40/30/20/10 split, claim all, verify final balances match ratios.

[JamesEjembi]

i would like to work on this issue

[grantfox-oss]

🦊 GrantFox — @JamesEjembi has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #62)
2. Your PR will be reviewed by the Utility-Protocol maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@JamesEjembi's PR #120 was approved and merged by @elizabetheonoja-art.

🏆 @JamesEjembi: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (519 total points). Track your full progress on GrantFox.

👏 Great work, @JamesEjembi! Keep contributing to Utility-Protocol.