# EventlyProfiles.sol v1.3

**Address:** `0x9F0708145BCCD1F5B16F610cB8a75A63fA4A9a24` **Version:** v1.3

***

## Constants

| Constant                        | Value      | Description                    |
| ------------------------------- | ---------- | ------------------------------ |
| `MIN_USERNAME_LENGTH`           | 3          | Min username chars             |
| `MAX_USERNAME_LENGTH`           | 20         | Max username chars             |
| `LEADERBOARD_SIZE`              | 10         | Top N tracked onchain          |
| `REFERRAL_ACTIVATION_THRESHOLD` | 0.01 ETH   | Min spend to activate referral |
| `SWAP_POINTS_PER_USD_CENT`      | 5          | Points per $0.01 swapped       |
| `SWAP_COOLDOWN`                 | 30 seconds | Min delay between swap records |

***

## Profile Struct

```solidity
struct Profile {
    string username;
    uint256 totalSpent;
    uint256 totalClicks;
    uint256 gamesWon;
    uint256 totalWinnings;
    bool exists;
    bool isWhale;
    bool hasUsedFreeClick;
    bool promoFreeClick;
    uint256 swapVolumeUsd;
    uint256 swapPoints;
}
```

***

## Profile Creation

| Function                                                | Cost | Description                                    |
| ------------------------------------------------------- | ---- | ---------------------------------------------- |
| `createProfile(username, referrerUsername)`             | Free | Standard profile creation                      |
| `createProfileWithPromo(username, referrer, promoCode)` | Free | Valid community code grants a free click bonus |

Profiles are **free for everyone**. Community codes grant a bonus free click via `promoFreeClick = true`.

Referrers are passed by **username** (not address). If the username doesn't resolve, it is silently ignored — no revert.

***

## Key Functions

### Called by Game Contract

| Function                                           | Description                          |
| -------------------------------------------------- | ------------------------------------ |
| `updateClickStats(address, points, ethSpent)`      | Increments totalClicks, totalSpent   |
| `updateWinStats(address, prize)`                   | Increments gamesWon, totalWinnings   |
| `setWhaleStatus(address)`                          | Sets isWhale = true                  |
| `markFreeClickUsed(address)`                       | Marks free click consumed            |
| `creditReferral(address referred, uint256 amount)` | Credits referrer balance             |
| `hasFreeClick(address)`                            | Returns true if free click available |
| `referrerOf(address)`                              | Returns referrer address             |

### User-Facing

| Function                     | Description                                             |
| ---------------------------- | ------------------------------------------------------- |
| `claimReferral()`            | Withdraw referral earnings                              |
| `recordSwap(volumeUsdCents)` | Log swap volume, award points (authorized callers only) |
| `getProfile(address)`        | View profile data                                       |
| `getLeaderboard()`           | Returns top 10 addresses + scores                       |

### Admin

| Function                             | Description                      |
| ------------------------------------ | -------------------------------- |
| `setGameContract(address)`           | Authorize game contract          |
| `addPromoCode(code, maxUses)`        | Create community code            |
| `removePromoCode(code)`              | Invalidate a code                |
| `setAuthorizedCaller(address, bool)` | Authorize address for recordSwap |
| `withdrawFees()`                     | Withdraw accumulated fees        |

***

## Events

| Event                | Trigger                          |
| -------------------- | -------------------------------- |
| `ProfileCreated`     | Profile created                  |
| `ReferralRewarded`   | Referral balance credited        |
| `ReferralClaimed`    | User withdraws referral earnings |
| `SwapRecorded`       | Swap volume logged               |
| `WhaleStatusUpdated` | Player marked as whale           |
| `PromoCodeUsed`      | Community code redeemed          |