[GROWTH] Viral growth engine: referrals + quests + seasons + recurring campaigns

[joelpeace48-cell]

Growth initiative / consolidation. High-priority. Merges the engagement/virality features into one cohesive growth-loop initiative. Supersedes #602 (quests), #603 (referral economy), #604 (recurring campaigns), #606 (leaderboard seasons).

Why this matters (retention + virality)

Acquisition without retention leaks. The strongest crypto-native growth loop is: users earn → invite others to earn → climb a leaderboard → come back next season. Building these as one coherent growth engine (rather than scattered features) compounds retention and referral-driven acquisition.

Goal

Ship an integrated growth engine: on-chain referral rewards, multi-step quests, recurring/seasonal campaigns, and seasonal leaderboards — designed to reinforce each other into a viral retention loop.

Technical design

A cohesive loop where each piece feeds the next:

• Referral rewards (on-chain): configurable referrer bonus paid when a referee completes a qualifying action; anti-self/circular + per-referrer caps; sybil-gated. Attribution integrates with the partner/embed growth channel. (was feat: On-chain referral rewards economy #603)
• Quests / streaks: ordered multi-step objectives with on-chain completion + bonus; streaks across recurring campaigns feed reputation/badges. (was feat: Quest / streak system (multi-step campaign objectives) #602)
• Recurring/seasonal campaigns: cron-like scheduler clones campaign config into new windows (locked, idempotent), creating the cadence that makes streaks/seasons meaningful. (was feat: Recurring / seasonal campaign scheduling #604)
• Leaderboard seasons: season boundaries reset live ranks + archive past seasons (served from indexed rollups), giving users a reason to return each cycle. (was feat: Leaderboard seasons with reset & historical archive #606)

Edge cases

• Self/circular referral, sybil farming → blocked + caps + uniqueness gating.
• Quest replay/partial completion → idempotent, all-or-nothing bonus.
• Season boundary ties → deterministic snapshot; archives immutable.
• Recurring overlap/funding → guards + pre-funding alerts.

Task breakdown

• On-chain referral bonus payout + anti-abuse + attribution hooks.
• Quest/streak engine (on-chain progress + bonus) feeding reputation/badges.
• Recurring/seasonal scheduler (locked, idempotent) cloning config.
• Seasonal leaderboards (reset + immutable archive) over indexed rollups.
• Growth instrumentation: referral conversion, quest completion, season retention metrics.

Acceptance criteria

• A user can refer others for on-chain rewards, complete quests for bonuses, and compete in resettable seasons across recurring campaigns — with abuse/sybil protections — and the loop's growth metrics are measurable.

Verification

• Contract tests (referral abuse, quest idempotency, season boundary); scheduler clock-advance tests; growth-metric reconciliation vs indexed events.

Dependencies

• Indexed rollups (feat: Materialized analytics rollup tables from indexed events #559); reputation (feat: On-chain reputation score per address #598)/badges (feat: NFT achievement badges (Soroban NFT contract) #536)/soulbound (feat: Soulbound participation tokens (non-transferable proof) #601); partner attribution (G2); uniqueness gating.

Priority: high · Difficulty: hard · Effort: L · growth (retention + virality)

[annacodervibe]

I would like to work on this issue. I have experience with Rust and Soroban smart contract development. I will follow the acceptance criteria and add tests. Excited to contribute. Kindly assign.

[Menjay7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. Thank you!

[jaynomyaro]

Hi! I’m a full-stack developer with a strong blockchain background. I’d love to handle this issue and can deliver a clean, reliable solution. Kindly assign it to me.

[ZuLu0890]

I would love to work on this issue