feat: holding cap, early access whitelist, referral rewards, key factory

[harystyleseze]

Summary

Adds a thin, additive layer for four related features on top of existing code, without reworking existing functions.

Changes

• Holding cap (Add maximum wallet holding cap per creator key #903): reuses the existing per-wallet MaxKeysPerWallet cap that buy_key already enforces. Adds set_holding_cap (creator, bounded by an admin value set via set_holding_cap_bound), get_holding_cap, and HoldingCapUpdated (old and new cap). transfer_keys and batch_transfer_keys now reject a recipient exceeding the cap.
• Early access whitelist (Add whitelist mechanism for restricting early key access before public launch #901): thin wrappers over the existing whitelist flag and entries. set_early_access_mode and update_whitelist (creator or admin), WhitelistUpdated event, and get_wallet_whitelist_status(creator, wallet). Named differently because get_whitelist_status(creator) already exists.
• Referral rewards (Build referral reward contract for tracking and distributing referral fees #900): register_referral, get_referrer, set_referral_fee_bps (admin, default 50% of protocol fee), claim_referral_rewards, plus ReferralRegistered, ReferralRewardAllocated and ReferralRewardsClaimed events. buy_key_with_referrer resolves the registered referrer once (first referred trade only) and pays the configured share; explicit-referrer behaviour is unchanged. Claim resets the earnings balance and returns the amount (the contract keeps internal accounting for all fee balances).
• Key factory (Implement key factory contract for deploying new creator key instances #902): new workspace crate creator-keys-factory with initialise, set_creator_allowed, deploy_key (admin or allowed creators, emits key_depl with key and creator) and get_registry.
• Tests added for holding cap, early access mode and referral flows, and for factory authorization.

Issues

Resolves #903
Resolves #901
Resolves #900
Resolves #902

Verification

Manual code review only. cargo build and cargo test were not run; rustfmt --check was run on the changed Rust files. Residual risks:

• All new code and tests are unrun and may need compile or test fixes.
• Referral: "first trade" means the first buy after registration; registration is not blocked by earlier trades. Only buy_key_with_referrer (and so buy_key) uses registered referrals, not buy_keys_with_referrer.
• Open PR Feat/issue 862 update holder cap #865 (holder cap update) touches lib.rs and events.rs and may need a rebase.

[drips-wave]

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