feat(crowdfund): implement affiliate links and referral tracking (#349)

[Ebenezer199914]

Summary

Closes #349

Implements a complete affiliate links and referral tracking system for the crowdfund contract. Campaign organizers can register named affiliate partners, track contributions made through referral codes, and automatically accrue commission per contribution.

---

Changes

contracts/crowdfund/src/errors.rs

Five new error variants:

Variant	Code	When
InvalidAffiliateCode	28	Empty or >32-byte code
AffiliateNotFound	29	Code not registered
AffiliateAlreadyExists	30	Duplicate registration
InvalidCommissionBps	31	Rate outside 1–10 000 bps
UnauthorizedAffiliate	32	Reserved for future ACL

---

contracts/crowdfund/src/lib.rs

Data types

• AffiliateInfo — stores wallet, commission_bps, total_referred_amount, total_commission_earned, referral_count
• ReferralRecord — per-contributor first-touch snapshot: affiliate_code, amount, timestamp

New DataKey variants

• Affiliate(String) — AffiliateInfo keyed by code
• AffiliateList — Vec<String> of all registered codes
• ContributorReferral(Address) — first-touch referral per contributor
• AffiliateCommission(String) — accumulated commission per code

Events

• AffiliateRegisteredEvent — emitted on register_affiliate
• AffiliateContributionEvent — emitted on every contribute_with_referral
• AffiliateCommissionEvent — emitted when commission > 0

New public methods

Method	Auth	Description
register_affiliate(code, wallet, commission_bps)	organizer	Register a new affiliate code
contribute_with_referral(contributor, amount, code)	contributor	Full contribute flow + referral tracking
get_affiliate(code)	—	Fetch affiliate stats
get_affiliate_commission(code)	—	Total accrued commission
get_affiliate_codes()	—	Enumerate all codes
get_contributor_referral(contributor)	—	Query contributor's referral record

Design decisions

• Commission is calculated on the raw contribution before sponsor matching, preventing inflated payouts.
• Referral count uses first-touch attribution — repeated contributions from the same address do not re-increment the counter.
• contribute_with_referral is fully compatible with the existing matching pool, stretch goals, and batch refund flows.

---

contracts/crowdfund/src/test.rs

25 new tests across 5 categories:

1. Registration — success, duplicate, empty code, commission edge cases (0 bps, >10 000, exact 10 000)
2. Contributions with referral — raised amount, referral record persisted, commission math, multi-contributor dedup, accumulation
3. Matching pool compatibility — commission calculated on raw amount only
4. Error cases — unknown code, zero amount, after-deadline contribution
5. Integration — referred contributors included in batch refund; organizer auth guard

---

Testing

cargo test -p crowdfund

Result: 82 passed, 0 failed (57 pre-existing + 25 new)

Pre-existing compile errors in ticketing and some shade test files are unrelated to this PR and were present before these changes.

---

Checklist

• New error codes do not conflict with existing ones (28–32)
• All new DataKey variants are non-overlapping
• commission_bps validated on registration (1–10 000)
• Affiliate code length validated (1–32 bytes)
• First-touch attribution prevents referral count inflation
• Commission calculated pre-match to avoid inflated payouts
• All existing tests continue to pass
• 25 new tests cover happy paths and all error cases

[drips-wave]

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