XP Farming System

Modular on-chain XP infrastructure for Demeter — a financial hackathon DAO. The system rewards early adopters and product users with soulbound XP points, preparing the governance token distribution at launch.

---

Overview

XP is earned through two distinct activities:

• Hackathons — a fixed XP amount per rank, distributed to all team members equally at hackathon close.
• Products — a time-weighted, square-root TVL reward: duration × sqrt(amount) × rate.
• Boost System — Hackathon wins grant "Boost Capacity" which doubles product rewards but decays with a 3-month half-life and is consumed upon use.

Earned XP feeds directly into governance token allocation at launch via a merkle-based distributor: a guaranteed floor (1000 XP = N tokens) plus a proportional bonus pool. An early adopter with six months of activity cannot be caught up in a week.

After launch, XP emission continues for DeFi retention. A veTokenHook interface slot is reserved on XPToken — wired when tokenomics governance is decided, without redeploying core contracts.

---

Architecture

Hackathon Contract ──▶ HackathonReporter ──┐
                                            ├──▶ XPRouter ──▶ [Pipeline] ──▶ XPToken.mint()
Vault Contract ──────▶ ProductReporter ────┘

All contracts read parameters from a single source of truth: XPConfig.

Contracts

Contract	Role
XPConfig	Central configuration — rank XP tables, product templates, epoch duration
XPToken	Soulbound ERC20 — transfer/transferFrom/approve revert; MINTER_ROLE held by XPRouter only
XPRouter	Pipeline orchestrator — iterates multiplier modules then cap, calls mint; try/catch per module so a faulty contract cannot block issuance
HackathonReporter	Receives (hackathonId, winners[], ranks[]), resolves XP from config, calls router; supports equal team splits
ProductReporter	Tracks (amount, depositTime) per product per user; lazy epoch claim computes duration × TVL × templateMultiplier
StreakModule	×1.5 if last activity < 30 days
OGModule	×1.2 permanent for wallets marked OG pre-launch
TierBonusModule	+0–20% based on tier snapshot at epoch start (T1→T5 thresholds: 1k / 5k / 20k / 50k XP)
CapModule	Hard ceiling per source per period — always last in pipeline; cap == 0 means uncapped

Pipeline order

StreakModule → OGModule → TierBonusModule → CapModule → XPToken.mint()

The order is immutable without a governance vote + timelock. ICapModule is intentionally separated from IMultiplierModule — a cap can only equal or reduce, never amplify.

Access control

Role	Holder	Scope
MINTER_ROLE	XPRouter	XPToken
REPORTER_ROLE	HackathonReporter, ProductReporter	XPRouter
CALLER_ROLE	Hackathon contract	HackathonReporter
CALLER_ROLE	Vault/product contract	ProductReporter
DEFAULT_ADMIN_ROLE	Multisig	All contracts

---

Deployment order

1.  XPConfig.deploy(MULTISIG)
2.  XPToken.deploy(MULTISIG)
3.  StreakModule.deploy(xpConfig)
4.  OGModule.deploy(MULTISIG)
5.  TierBonusModule.deploy(xpToken, xpConfig)
6.  CapModule.deploy(xpConfig)
7.  XPRouter.deploy(MULTISIG, xpToken, [streak, og, tierBonus, cap])
8.  HackathonReporter.deploy(MULTISIG, xpConfig, xpRouter)
9.  ProductReporter.deploy(MULTISIG, xpConfig, xpRouter)

# Grants
XPToken.grantRole(MINTER_ROLE,    xpRouter)
XPRouter.grantRole(REPORTER_ROLE, hackathonReporter)
XPRouter.grantRole(REPORTER_ROLE, productReporter)

See script/Deploy.s.sol for the full Foundry deployment script.

---

Anti-gaming

• Sybil — XP is proportional to TVL deposited. 100 wallets at $1 do not beat one wallet at $10,000. Gas costs add further friction.
• Farm cap — CapModule enforces a hard ceiling per source per period, regardless of multipliers.
• Permanent XP — no decay. XP rewards the past, not current activity, making retroactive farming worthless.

---

Build & test

forge build
forge test -v

9 tests cover: deployment wiring, OG multiplier, TVL-weighted product XP, cap blocking, streak active/inactive, soulbound transfer revert, broken-module isolation, team XP split, tier snapshot bonus.

---

Open decisions

Topic	Status
veTokenHook	Interface slot ready — wired when governance tokenomics decided
DAO product boost vote	Planned phase 2 — XPConfig already stores templateId
On-chain hackathon scoring	IScoringStrategy interface planned — multisig first, DAO vote later
Subgraph	To be specified — indexes all XPRouter + reporter events
Fee sharing	Out of scope for XP system