feat(referral): implement referral tier upgrade contract for volume-based reward increases (#1034)

[Sensei-Victor]

Summary

Extends the referral contract with a tier system that increases referral reward rates as a referrer's cumulative referred trade volume crosses configured thresholds.

Resolves #1034

Scope & Implementation Details

• Referral Tiers (ReferralTier):

  • Bronze (0): default baseline tier, 500 bps (5.00%) reward rate, threshold: 0
  • Silver (1): 1,000 bps (10.00%) reward rate, threshold: 100,000
  • Gold (2): 1,500 bps (15.00%) reward rate, threshold: 1,000,000
  • Fully configurable via set_tier_config by authorized admin, with canonical fallback defaults.

• Cumulative Referred Trade Volume & Tier Calculation:

  • record_trade / record_trade_volume: increments a referrer's cumulative referred volume and checks for threshold crossing.
  • compute_tier_from_volume: dynamically resolves the tier based on cumulative volume and configured thresholds.

• Ratchet-Only Guarantee:

  • Tiers never downgrade regardless of subsequent volume drops or trade adjustments (adjust_volume).
  • Active tier is stored in persistent storage and only ratchets upward upon crossing higher thresholds.

• View Function (get_referral_tier):

  • Returns ReferralTierInfo { tier, volume, next_threshold }.
  • Accurately reports current ratcheted tier, cumulative volume, and next threshold (Some(silver_threshold) for Bronze, Some(gold_threshold) for Silver, None for Gold).

• Reward Accrual (accrue_reward / accrue_referral_reward):

  • Calculates rewards proportional to the referrer's earned tier rate: (fee_amount * reward_rate_bps) / 10_000.
  • Accrues rewards into persistent storage and supports withdrawal via claim_referral_rewards.

• Event Emission:

  • Emits ReferralTierUpgraded event on topic (Symbol("tier_upg"), referrer) containing referrer, old_tier, new_tier, volume, and reward_rate_bps.
  • Added event definition and indexer topic helper to creator-keys/src/events.rs and documented in docs/contract-event-conventions.md.

Acceptance Criteria Validation

• Tier computed correctly from cumulative referred volume
• Reward rate applied correctly per tier on accrual
• Tier upgrade triggers correctly at each threshold
• Tiers never downgrade regardless of volume drop
• ReferralTierUpgraded event emitted with correct tier data

Testing Performed

All 13 unit and integration tests in referral-contract pass cleanly:

cargo test -p referral-contract --lib
running 13 tests
test test::test_default_tier_is_bronze ... ok
test test::test_input_validations ... ok
test test::test_initialisation ... ok
test test::test_double_initialisation ... ok
test test::test_record_first_trade ... ok
test test::test_tier_direct_jump_from_bronze_to_gold ... ok
test test::test_claim_referral_rewards ... ok
test test::test_tier_computed_from_cumulative_volume ... ok
test test::test_accrue_referral_reward_combined_flow ... ok
test test::test_reward_rate_applied_correctly_per_tier_on_accrual ... ok
test test::test_tier_upgrade_emits_event ... ok
test test::test_tiers_never_downgrade_regardless_of_volume_drop ... ok
test test::test_custom_tier_configuration ... ok

test result: ok. 13 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Quality and formatting checks:

• cargo fmt --all -- --check passed
• cargo clippy -p referral-contract -p creator-keys --lib -- -D warnings passed (0 warnings)
• cargo check --workspace passed

[drips-wave]

@Sensei-Victor 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