Leaderboard System - GenLayer Points

Overview

The GenLayer Points leaderboard system provides transparent, category-specific rankings of all participants based on their contributions. Each category maintains its own independent leaderboard with unique scoring rules.

Leaderboard Types

The platform maintains four distinct leaderboards:

1. Validator Leaderboard

Eligibility: Participants with a Validator profile (graduated from waitlist) Scoring: Sum of all contributions in the Validator category

validator_points = sum(
    contribution.frozen_global_points
    for contribution in user.contributions.filter(
        contribution_type__category__slug='validator'
    )
)

Ranking: Highest points first, alphabetical tiebreaker

2. Builder Leaderboard

Eligibility: Participants with a Builder profile Scoring: Sum of all contributions in the Builder category

builder_points = sum(
    contribution.frozen_global_points
    for contribution in user.contributions.filter(
        contribution_type__category__slug='builder'
    )
)

Ranking: Highest points first, alphabetical tiebreaker

3. Validator Waitlist Leaderboard

Eligibility: Have validator-waitlist badge but no Validator profile (not yet graduated) Scoring: Validator contributions (excluding graduation) + referral bonuses

waitlist_points = (
    validator_contribution_points +
    referral_builder_points * 0.1 +
    referral_validator_points * 0.1
)

Ranking: Highest points first, alphabetical tiebreaker

4. Validator Waitlist Graduation Leaderboard

Eligibility: Graduated from waitlist to active validator Scoring: Frozen waitlist points at time of graduation Ranking: Most recent graduation date first (not by points)

The graduation leaderboard is a historical record. Points are frozen when you graduate and never change, preserving your pre-validator achievements.

Leaderboard Data Model

Leaderboard entries are stored in the database:

class LeaderboardEntry:
    user             # Participant
    type            # 'validator', 'builder', 'validator-waitlist', etc.
    total_points    # Sum of all relevant contributions
    rank            # Position on this leaderboard
    last_update     # When points were last recalculated
    graduation_date # Only for graduation leaderboard

Ranking Algorithm

Rankings are calculated using this process:

Filter Visible Users

Only users with visible=True are included in rankings

entries = LeaderboardEntry.objects.filter(
    type=leaderboard_type,
    user__visible=True
)

Sort by Criteria

For most leaderboards:

Primary: Total points (descending)
Tiebreaker: User name (alphabetical)

For graduation leaderboard:

Primary: Graduation date (most recent first)
Tiebreaker: User name (alphabetical)

Assign Consecutive Ranks

Users receive consecutive rank numbers (1, 2, 3…) even if tied on points

for i, entry in enumerate(sorted_entries, start=1):
    entry.rank = i

Null Ranks for Invisible Users

Non-visible users have their rank set to null but maintain their point totals

Ranking Example

User	Points	Name	Rank
Alice	1500	Alice	1
Bob	1200	Bob	2
Charlie	1200	Charlie	3
Diana	1200	Diana	4
Eve	900	Eve	5

Bob, Charlie, and Diana all have 1200 points but receive consecutive ranks (2, 3, 4) based on alphabetical order.

Leaderboard Updates

Leaderboards update automatically through Django signals:

Update Triggers

@receiver(post_save, sender=Contribution)
def update_leaderboard_on_contribution(sender, instance, **kwargs):
    # Update the user's leaderboard entries
    update_user_leaderboard_entries(instance.user)
    
    # Update referrer's points if applicable
    if instance.user.referred_by:
        update_referrer_points(instance)

Leaderboards update when:

A contribution is accepted (points added)
A referred user makes a contribution (referral bonus added)
A Builder or Validator profile is created (user joins leaderboard)
A user graduates from waitlist to validator (moved between leaderboards)

Update Process

Determine Qualified Leaderboards

Check which leaderboards the user qualifies for:

if hasattr(user, 'validator'):
    qualified.append('validator')
if hasattr(user, 'builder'):
    qualified.append('builder')
if has_waitlist_badge and not hasattr(user, 'validator'):
    qualified.append('validator-waitlist')

Recalculate Points

Update the user’s total points for each qualified leaderboard

Update All Ranks

Recalculate ranks for all users on affected leaderboards

Rank updates affect all users on a leaderboard, not just the user who made a contribution. If you move up, someone else moves down.

Viewing the Leaderboard

Web Interface

The leaderboard page displays:

Category Tabs: Switch between Validator, Builder, and Waitlist leaderboards
Rank Column: Your position (1 is best)
Participant Column: Name or address, linked to profile
Points Column: Total points in this category
Contributions Column: Number of accepted contributions
Your Position Highlight: Your entry is highlighted if you’re logged in

Leaderboard Pagination

Leaderboards use pagination for large datasets:

GET /api/v1/leaderboard/?type=validator&page=1&page_size=50

Default page size: 50 entries per page

Leaderboard Statistics

The platform provides aggregate statistics:

Global Stats

GET /api/v1/leaderboard/stats/

// Response
{
  "total_participants": 1250,
  "total_points_awarded": 485000,
  "total_contributions": 3420,
  "validators_count": 320,
  "builders_count": 780,
  "waitlist_count": 150
}

Category Stats

Available on each leaderboard view:

Top Contributor: User with most points
Average Points: Mean points across all participants
Median Points: Middle value in point distribution
Active Contributors: Users with contributions in last 30 days

User-Specific Stats

GET /api/v1/leaderboard/user_stats/by-address/{address}/

// Response
{
  "validator": {
    "rank": 45,
    "total_points": 1250,
    "percentile": 85.5,
    "contributions_count": 12
  },
  "builder": {
    "rank": 102,
    "total_points": 3400,
    "percentile": 78.3,
    "contributions_count": 28
  },
  "referral_stats": {
    "referrals_count": 5,
    "builder_points": 340,
    "validator_points": 120
  }
}

Referral Impact on Rankings

Referrals affect waitlist leaderboard positioning:

Referral Point Calculation

class ReferralPoints:
    builder_points = int(referred_builder_contributions * 0.1)
    validator_points = int(referred_validator_contributions * 0.1)

Eligible Referrals

Only referrals with substantial contributions count:

eligible = referred_user.contributions.exclude(
    contribution_type__slug__in=['builder-welcome', 'validator-waitlist']
).exists()

Example Impact

Your waitlist score:

Your Contributions: 500 points
Referral #1 (Bob): 200 builder points → +20 bonus
Referral #2 (Alice): 300 validator points → +30 bonus
Total Waitlist Score: 550 points

Referring active contributors can significantly boost your waitlist ranking!

Graduation Effects

When graduating from waitlist to validator:

Freeze Waitlist Points

Your current waitlist score is permanently recorded:

graduation_points = (
    waitlist_contributions +
    referral_bonuses_up_to_graduation_date
)

Remove from Waitlist Leaderboard

You no longer appear on the active waitlist leaderboard

Add to Graduation Leaderboard

Create entry with frozen points and graduation date

Add to Validator Leaderboard

Start fresh on the active validator leaderboard (only post-graduation points count)

After graduation, your waitlist points are preserved on the graduation leaderboard, but don’t carry over to the active validator leaderboard.

Special Visibility Rules

Visible Users Only

Only users with visible=True appear on leaderboards:

user.visible = True  # Appears on leaderboards
user.visible = False # Hidden from leaderboards, rank set to null

This allows:

Test accounts to be hidden
Users to opt out of public rankings
Administrative accounts to be excluded

Staff Accounts

Staff members can be visible or hidden based on preference. Their contributions are tracked regardless.

Leaderboard Integrity

Validation Rules

The system enforces integrity:

# Users must be visible to have contributions
if not user.visible:
    raise ValidationError(
        "Cannot add contributions for invisible users"
    )

# Multipliers must exist for contribution dates
if not multiplier_exists:
    raise ValidationError(
        "No multiplier exists for this date"
    )

# Points must be within valid ranges
if points < min_points or points > max_points:
    raise ValidationError(
        "Points outside allowed range"
    )

Recalculation Function

Administrators can trigger full recalculation:

python manage.py shell
>>> from leaderboard.models import recalculate_all_leaderboards
>>> recalculate_all_leaderboards()

This:

Deletes all leaderboard entries
Recalculates points from contributions
Regenerates all rankings
Preserves graduation points

Recalculation is resource-intensive and should only be run during maintenance windows.

Comparing Leaderboards

Validator vs Builder

Aspect	Validator Leaderboard	Builder Leaderboard
Entry Requirement	Validator profile	Builder profile
Point Source	Validator contributions	Builder contributions
Typical Range	0-5000 points	0-10000 points
Update Frequency	On node activity	On contribution acceptance
Referral Bonus	No	No

Waitlist vs Graduation

Aspect	Waitlist Leaderboard	Graduation Leaderboard
Eligibility	Pre-validator	Post-graduation
Ranking Criteria	Total points	Graduation date
Point Updates	Real-time	Frozen
Referral Bonus	Yes	Frozen at graduation
Purpose	Active competition	Historical record

API Access

Access leaderboards programmatically:

Get Leaderboard

GET /api/v1/leaderboard/?type=validator&page=1

Response:
{
  "count": 320,
  "next": "...",
  "previous": null,
  "results": [
    {
      "rank": 1,
      "user": {
        "address": "0x123...",
        "name": "Alice"
      },
      "total_points": 4500,
      "last_update": "2026-03-03T10:30:00Z"
    },
    ...
  ]
}

Get Your Stats

GET /api/v1/leaderboard/user_stats/by-address/0x123.../

See API Reference for full documentation.

Tips for Climbing the Leaderboard

Consistent Contributions

Regular contributions compound over time. Set a goal for monthly submissions.

High-Value Contributions

Focus on contribution types with higher point ranges (e.g., smart contracts vs. comments).

Leverage Multipliers

Submit during periods with elevated multipliers for maximum points.

Refer Active Users

Your referral bonuses grow as your referrals contribute more.

Quality Evidence

Well-documented contributions earn higher point values within their range.

Multi-Category Participation

Participate as both Validator and Builder to maximize total points.

Common Questions

How often do rankings update?

Rankings update immediately when contributions are accepted. There’s no delay or batch processing.

Why did my rank drop even though my points didn't change?

Other users’ contributions increased their points, moving them above you. Rankings are relative to all participants.

Can I see historical leaderboard snapshots?

Currently, only the graduation leaderboard preserves historical data. Real-time leaderboards don’t maintain snapshots.

What happens to my rank if I become invisible?

Your rank becomes null and you’re hidden from the leaderboard. Your points are preserved and your rank will be recalculated if you become visible again.

Do graduated validators lose their waitlist rank?

You’re removed from the active waitlist leaderboard, but your waitlist rank is preserved on the graduation leaderboard with frozen points.

How are ties broken?

Users with equal points receive consecutive ranks (not the same rank) based on alphabetical order of their name or address.

Get Started

Core Concepts

​Overview

​Leaderboard Types

​1. Validator Leaderboard

​2. Builder Leaderboard

​3. Validator Waitlist Leaderboard

​4. Validator Waitlist Graduation Leaderboard

​Leaderboard Data Model

​Ranking Algorithm

​Ranking Example

​Leaderboard Updates

​Update Triggers

​Update Process

​Viewing the Leaderboard

​Web Interface

​Leaderboard Pagination

​Leaderboard Statistics

​Global Stats

​Category Stats

​User-Specific Stats

​Referral Impact on Rankings

​Referral Point Calculation

​Eligible Referrals

​Example Impact

​Graduation Effects

​Special Visibility Rules

​Visible Users Only

​Staff Accounts

​Leaderboard Integrity

​Validation Rules

​Recalculation Function

​Comparing Leaderboards

​Validator vs Builder

​Waitlist vs Graduation

​API Access

​Get Leaderboard

​Get Your Stats

​Tips for Climbing the Leaderboard

Consistent Contributions

High-Value Contributions

Leverage Multipliers

Refer Active Users

Quality Evidence

Multi-Category Participation

​Common Questions

Build docs developers (and LLMs) love

Overview

Leaderboard Types

1. Validator Leaderboard

2. Builder Leaderboard

3. Validator Waitlist Leaderboard

4. Validator Waitlist Graduation Leaderboard

Leaderboard Data Model

Ranking Algorithm

Ranking Example

Leaderboard Updates

Update Triggers

Update Process

Viewing the Leaderboard

Web Interface

Leaderboard Pagination

Leaderboard Statistics

Global Stats

Category Stats

User-Specific Stats

Referral Impact on Rankings

Referral Point Calculation

Eligible Referrals

Example Impact

Graduation Effects

Special Visibility Rules

Visible Users Only

Staff Accounts

Leaderboard Integrity

Validation Rules

Recalculation Function

Comparing Leaderboards

Validator vs Builder

Waitlist vs Graduation

API Access

Get Leaderboard

Get Your Stats

Tips for Climbing the Leaderboard

Common Questions