Feature: Implement a Referral Commission System With Circular-Chain Detection

[Emmyt24]

Overview

Add a referral and affiliate tracking system: users register a referrer when creating a token, and a configurable commission (in basis points, suggest 500 bps / 5% as a default) of the deployment fee is credited to the referrer's earned balance. The factory admin can update the commission rate and trigger payouts of accumulated commissions.

Requirements:

• Commission is calculated on the fee_payment passed to create_token.
• Commissions accumulate in storage; the admin triggers payouts explicitly (pull/push-by-admin model, not auto-transfer).
• A referrer cannot refer themselves.
• Circular referral chains must be detected and rejected at registration time.

Scope: contract only. No backend or frontend integration is required for this feature.

Integration points

• New module file contracts/token-factory/src/referral.rs, declared via mod referral; in lib.rs
• Public #[contractimpl] entry points added to the TokenFactory impl block in lib.rs — suggested names for consistency with the rest of the API: register_referral, get_referral, get_referral_earned, get_commission_rate, set_commission_rate, payout_commission
• create_token updated to accept an optional referrer parameter and route commission accrual through this module — check the current create_token signature and fee flow before wiring this in
• New DataKey variants added to types.rs for referral records/earned-commission state — do not reuse existing discriminants
• New Error variants added to types.rs starting at 133 (current highest in-use code is 132), with matching entries added to Error::name()
• Storage getters/setters added in storage.rs following the existing pattern
• Events emitted via events.rs using short symbol_short! topic names (Soroban's 9-character limit)

Acceptance criteria

• referral.rs implemented under contracts/token-factory/src/, wired into lib.rs
• create_token accepts and processes an optional referrer
• DataKey/Error additions follow the checklist above
• Storage and events wired following existing patterns
• Unit tests in referral_test.rs covering: registration + commission accrual on token creation, self-referral rejection, circular-chain rejection, admin commission-rate updates, payout accounting
• cargo check --lib and cargo test --lib clean in contracts/token-factory
• cargo build --target wasm32v1-none --release --lib succeeds

Notes for implementers

• Circular-referral detection needs a bounded walk (don't let it become an unbounded loop / gas grief vector) — cap the chain-walk depth explicitly and reject registrations that would exceed it.

[Markodiba6399]

Hi, I'd like to take this.

The spec is thorough, so rather than restate it, here are the decisions I'd want settled before writing code, since each one changes the implementation shape.

create_token signature change. Adding an optional referrer changes a public entry point, which is a breaking change for any existing caller. Soroban has no overloading, so the options are widening the existing signature and accepting the break, or adding a separate create_token_with_referral. I'd lean toward widening with an Option

since a parallel entry point duplicates the fee flow and they drift, but that's the maintainers' call given whatever is already deployed.

Circular detection bound. The note asks for a capped walk, and I'd suggest the cap is defensive rather than primary. Walking the chain at registration is O(depth) storage reads paid by the registrant, which is the right party, but it still scales with an attacker-controlled structure. The cheaper invariant: a referral edge can only be added if the referrer is already registered or is a root, which makes the graph a forest by construction and reduces the check to a bounded ancestor walk. I'd still cap it, around 10, and add an explicit error rather than silently truncating. Worth confirming you want depth capped rather than chains structurally prevented.

Commission rounding and the fee flow. fee_payment * rate / 10_000 truncates, so small fees credit zero. Fine, but worth deciding deliberately rather than discovering it in a test. More importantly, I need to check whether the fee is already transferred to the factory before commission is computed, since the accrued balance is only solvent if the contract actually holds those funds at payout time. If the fee flow routes elsewhere, payout has no backing and that's a design problem, not an implementation one.

Payout accounting. Pull model triggered by admin. I'd zero the earned balance before the token transfer, not after, and confirm the token client call pattern matches how the factory handles fees elsewhere. Partial payouts, whether the admin can pay a subset, is unspecified. I'd implement full payout per referrer unless you want otherwise.

Rate bounds. set_commission_rate should reject anything above 10_000, and probably well below it. Is there a maximum you want enforced, or just the arithmetic ceiling?

Plan once those are settled: referral.rs with the registration and accrual logic, DataKey and Error additions per the checklist starting at 133, storage and events following existing patterns, then referral_test.rs covering the five listed cases plus rounding-to-zero and the depth cap boundary. I'd verify Error::name() entries and the symbol_short! topics stay inside 9 characters, since that one bites at build time rather than review time.

Happy to start on any of the above defaults if you'd rather I proceed and flag decisions in the PR instead.

[grantfox-oss]

🦊 GrantFox — @Markodiba6399 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #1762)
2. Your PR will be reviewed by the nova-launch01 maintainers

Good luck! Track your progress on GrantFox.