[Feature] Implement Tiered Dynamic Fee Schedule with Waivers, Sharing, and Cumulative Tracking

[KarenZita01]

Description

The asset.rs (16.5KB) implements the asset/token interface for the utility contract, handling token transfers, balance tracking, and asset registration. However, fees are hardcoded throughout the codebase rather than computed from a configurable fee schedule. The basket_stream.rs and streaming functions apply flat fees with no volume-based discounts. The velocity_limit.rs restricts transaction velocity but doesn't differentiate between fee-generating and non-fee-generating transactions.

Fee system gaps:

• No dynamic fee schedule with tiered pricing (volume discounts for high-usage users)
• FEE_RATE constants are hardcoded instead of stored in DataKey
• No fee_waiver capability for approved entities (e.g., grid operators, humanitarian aid)
• No fee_sharing mechanism for affiliate/referral programs
• No max_fee_per_transaction cap to protect users from excessive fees
• No cumulative_fee_tracking per user per billing period

Technical Context & Impact

• Affected Components/Files: contracts/utility_contracts/src/asset.rs, contracts/utility_contracts/src/basket_stream.rs, contracts/utility_contracts/src/velocity_limit.rs, contracts/utility_contracts/src/lib.rs
• Impact: Business Model Flexibility, User Experience, Revenue Optimization

Step-by-Step Implementation Guide

1. Create fee management module: src/fee_manager.rs with FeeSchedule { tier: Vec<FeeTier>, default_fee_bps: u32, max_fee_bps: u32 }
2. Implement tiered pricing: calculate_fee(amount, user_tier) -> fee_amount with tiers: Bronze (0-1000 tokens, 50bps), Silver (1001-10000, 30bps), Gold (10001+, 15bps)
3. Store fee schedule on-chain: DataKey::FeeSchedule, DataKey::UserFeeTier(user), admin functions set_fee_schedule, set_user_fee_tier
4. Add fee waiver: set_fee_waiver(entity, expiry_ledger) - approved entities pay zero fees until expiry
5. Implement fee sharing: set_referrer(user, referrer) stores referrer; on each fee collection, split (fee * REFERRER_BPS) / 10000 to referrer
6. Add per-transaction fee cap: fee = min(calculated_fee, MAX_FEE_PER_TX) stored in DataKey::MaxFeePerTx
7. Track cumulative fees: DataKey::CumulativeFees(user, billing_period) updated on each fee-collecting transaction

Verification & Testing Steps

1. Test tiered fee calculation: Bronze fee for 500 tokens -> 25bps; Gold fee for 500 tokens -> 7.5bps
2. Test fee waiver: set waiver for address -> address pays 0 fees -> verify fee collector doesn't receive funds
3. Test fee sharing: user with referrer pays fee -> verify referrer receives share
4. Test max fee cap: set cap to 100 tokens -> fee calculated at 200 tokens -> actual fee is 100
5. Test cumulative fee tracking: user does 10 transactions -> verify total tracked = sum of individual fees
6. Run full tests: cargo test --package utility_contracts