Rewards contract

The Rewards contract manages token distribution for user participation in the Humanity Protocol ecosystem, including genesis, daily, and referral rewards.

Contract Address

Testnet: 0x4cb300c38B97F601D5f3887DF421C568Dc89777f

Overview

The Rewards contract issues tokens to users based on their participation and referral activity. It uses a time-based epoch system to track daily claims and implements a sophisticated referral reward mechanism.

Key Features

• Multiple reward types: Genesis, daily, and referral rewards

• Time-based epochs: Claims tracked on a daily basis

• Adaptive reward scaling: Rewards decrease as total user count increases

• Referral buffering: Holds pending referral rewards for claiming

• Contract lifecycle management: Admin can start/stop rewards distribution

Architecture

Core Data Structures

enum RewardType {
    GENESIS,    // One-time reward for new users
    DAILY,      // Daily reward for verified users
    REFERRAL    // Reward from referral activity
}

struct UserClaim {
    bool claimStatus;   // Whether user has claimed for a specific epoch
    uint256 buffer;     // Pending buffer amount for this epoch
}

Key State Variables

• _contractActive: Whether the contract is currently distributing rewards

• _cycleStartTimestamp: When the current reward cycle started

• _previousCycleLastEpochID: The last epoch ID before contract was stopped

• _userClaims: Tracks per-user claim status for each epoch

• _genesisClaims: Tracks whether users have claimed their genesis reward

• _userBuffers: Stores buffered referral rewards for each user

Key Functions

Viewing Functions

// Returns the current epoch ID
function currentEpoch() external view returns (uint256)

// Returns the timestamp when the contract was last started
function cycleStartTimestamp() external view returns (uint256)

// Returns the buffered reward amount for a user
function userBuffer(address user) external view returns (uint256)

// Returns claim status for a user at specific epoch
function userClaimStatus(address user, uint256 epochID) external view returns (UserClaim memory)

// Returns whether user has claimed their genesis reward
function userGenesisClaimStatus(address user) external view returns (bool)

Administrative Functions

// Activates the contract from a specified timestamp (requires DEFAULT_ADMIN_ROLE)
function start(uint256 startTimestamp) external

// Deactivates the contract (requires DEFAULT_ADMIN_ROLE)
function stop() external

User Functions

// Claims buffered referral rewards
function claimBuffer() external

// Claims genesis or daily reward
function claimReward() external

Events

// Emitted when any type of reward is claimed
event RewardClaimed(address user, RewardType rewardType, uint256 amount)

// Emitted when a referral reward is buffered for later claiming
event ReferralRewardBuffered(address from, address to, uint256 amount, bool bufferSafe)

Reward Distribution Logic

Genesis Reward Calculation

Genesis rewards are one-time rewards when a user is verified. The amount scales based on total users:

≤ 10,000 users:         10,000 tokens
10,001 - 100,000:       1,000 tokens
100,001 - 1,000,000:    250 tokens
1,000,001 - 10M:        120 tokens
10M - 100M:             60 tokens
100M - 1B:              30 tokens
> 1B:                   10 tokens

Daily Reward Calculation

Daily rewards can be claimed once per epoch (day):

≤ 10,000 users:         100 tokens
10,001 - 100,000:       50 tokens
100,001 - 1,000,000:    25 tokens
1,000,001 - 10M:        12 tokens
10M - 100M:             6 tokens
100M - 1B:              3 tokens
> 1B:                   1 token

Referral Reward Distribution

When a user claims a reward, referral rewards are buffered for their referrers:

1. The first referrer receives 50% of the claimed amount

2. Each subsequent referrer receives half of the previous referrer's amount

3. Rewards are only buffered if the referrer claimed their own reward in the previous epoch

Sequence Flows

Reward Claiming Flow

1. User calls claimReward()

2. Contract checks:

   • Contract is active

   • User is verified (via VC contract)

   • User hasn't already claimed for current epoch

3. If this is the user's first claim, they receive a genesis reward

4. Otherwise, they receive a daily reward based on total user count

5. Referral rewards are buffered for the user's referrers

6. A RewardClaimed event is emitted

Buffer Claiming Flow

1. User calls claimBuffer()

2. Contract checks:

   • Contract is active

   • User is verified (via VC contract)

   • User has a non-zero buffer amount

3. The buffered amount is transferred to the user

4. User's buffer is reset to zero

5. A RewardClaimed event with RewardType.REFERRAL is emitted