[NF-12] [CONTRACT] On-Chain Referral Reward Accounting

Overview

The still-open growth/retention issue (#55, GF-23) only ever scoped referral tracking as a frontend localStorage/cookie mock — there is no on-chain settlement of referral rewards anywhere. This issue adds the actual on-chain accounting layer.

Problem

Nothing in any deployed contract knows about referrers. VaultRouter.deposit(user, tier, amount) has no referrer parameter, and no contract credits any bonus for bringing in a new depositor. Any referral reward promised by the frontend today would have to be paid out manually/off-chain, which doesn't scale and isn't verifiable by users.

Proposed Solution

• Extend VaultRouter.deposit(user: Address, tier: Tier, amount: i128, referrer: Option<Address>).
• On a user's first ever deposit (checked via a new DataKey::HasDeposited(Address) flag) with a non-empty referrer that isn't the depositor themselves, credit the referrer with bonus share-units in the depositor's chosen tier vault, equal to a governance-settable referral_bonus_bps (e.g. 50 bps) of the referee's deposit amount.
• Bonus shares are minted into the referrer's own position in that same tier vault (creating one if they don't already have one there), so the reward compounds like any other position.
• referral_bonus_bps is settable only via Governance.
• Emit a ReferralCredited event (referrer, referee, tier, bonus amount) for the frontend to display.

Acceptance Criteria

• A referrer receives bonus shares only on the referee's first-ever deposit, not on subsequent ones
• Self-referral (referrer == user) is rejected/ignored
• Bonus amount matches referral_bonus_bps of the referee's deposit at time of deposit
• referral_bonus_bps is Governance-gated
• Unit tests cover: first-deposit referral credit, no credit on second deposit from the same user, self-referral rejection, bonus share calculation accuracy

Start at the VaultRouter.deposit entry point and trace the existing DataKey and tier-vault position accounting before deciding where first-deposit state and Governance-controlled referral settings belong. Review the contract's existing event and unit-test patterns. Done means referral credit is limited to eligible first deposits, self-referrals are rejected or ignored, bonus shares use the configured basis points, and the listed unit tests pass.