Skip to main content

​
Overview

The backend is a Django 4.2+ REST API that handles:
  • User authentication with Sign-In With Ethereum (SIWE)
  • Contribution tracking and validation
  • Leaderboard calculations with dynamic multipliers
  • Category-based user profiles (Validators, Builders, Stewards)

​
Installation

1

Navigate to backend directory

cd backend
2

Create virtual environment

python -m venv env
3

Activate virtual environment

source env/bin/activate
4

Install dependencies

pip install -r requirements.txt
5

Setup Node.js environment

This installs Node.js within the Python virtual environment:
nodeenv -p
6

Configure environment variables

Create a .env file in the backend/ directory:
cp .env.example .env
Edit the .env file with your configuration. See Environment Variables for details.
7

Run database migrations

python manage.py migrate
8

Create a superuser

python manage.py createsuperuser
Enter an email and password when prompted.
9

Start development server

python manage.py runserver
The API will be available at http://localhost:8000

​
Dependencies

Key packages from requirements.txt: 
Django>=4.2.0                      # Web framework
djangorestframework>=3.14.0        # REST API toolkit
django-cors-headers>=4.1.0         # CORS support
djangorestframework-simplejwt>=5.2.2  # JWT authentication
django-filter>=23.2                # API filtering
psycopg2-binary>=2.9.7            # PostgreSQL adapter
siwe>=2.2.0                        # Sign-In With Ethereum
eth-account>=0.11.0                # Ethereum utilities
web3>=6.13.0                       # Web3 integration
python-dotenv>=1.0.0              # Environment variables
whitenoise>=6.5.0                 # Static file serving
gunicorn>=21.2.0                  # WSGI server
dj-database-url>=2.1.0            # Database URL parsing
django-recaptcha>=4.0.0           # reCAPTCHA integration
genlayer-py>=0.1.0                # GenLayer SDK

​
Django Apps Structure

The backend is organized into several Django apps:

​
Core Apps

Location: backend/api/Handles authentication endpoints:
  • /api/auth/nonce/ - Get nonce for SIWE
  • /api/auth/login/ - Verify signed message and login
  • /api/auth/verify/ - Check authentication status
  • /api/auth/logout/ - End session
Location: backend/users/Custom user model with:
  • Email-based authentication
  • Ethereum wallet address linkage
  • Profile fields (name, bio, social links)
  • GitHub OAuth integration
  • Referral system
Key model fields:
email = EmailField(unique=True)  # Primary identifier
address = CharField(max_length=42)  # Ethereum address
name = CharField(max_length=255)
visible = BooleanField(default=True)
referral_code = CharField(max_length=8)
referred_by = ForeignKey('self')
Location: backend/contributions/Manages all contribution types and submissions:
  • ContributionType: Categories of contributions (slug-based)
  • Contribution: Actual contribution records with frozen points
  • SubmittedContribution: User submissions pending review
  • Evidence: URLs and descriptions (no file uploads)
  • Mission: Featured time-limited missions
  • ContributionHighlight: Featured contributions
Supports reCAPTCHA v2 validation on submissions.
Location: backend/leaderboard/Point calculation and ranking system:
  • LeaderboardEntry: User rankings per category
  • GlobalLeaderboardMultiplier: Time-based point multipliers
  • ReferralPoints: 10% of referred users’ points
Leaderboard types:
  • validator - Active validators
  • builder - Active builders
  • validator-waitlist - Waitlist participants
  • validator-waitlist-graduation - Graduated validators (frozen points)
Location: backend/validators/Validator-specific functionality:
  • Node version tracking
  • Blockchain integration
  • Validator contract interaction
Location: backend/builders/Builder-specific features:
  • Project tracking
  • Builder journey completion
Location: backend/stewards/Steward role and permissions:
  • Submission review workflow
  • Proposal system
  • CRM notes
Location: backend/utils/BaseModel with timestamp fields:
class BaseModel(models.Model):
    created_at = DateTimeField(auto_now_add=True)
    updated_at = DateTimeField(auto_now=True)
    
    class Meta:
        abstract = True

​
Database Configuration

​
SQLite (Development)

Default configuration in settings.py: 
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}

​
PostgreSQL (Production)

Set DATABASE_URL in your .env file: 
DATABASE_URL=postgresql://username:password@localhost:5432/points_db
The app will automatically use PostgreSQL when DATABASE_URL is set.

​
Common Commands

source env/bin/activate

​
API Endpoints

All API endpoints are prefixed with /api/v1/ except authentication:

​
Authentication (no v1 prefix)

  • GET /api/auth/nonce/ - Get nonce for signing
  • POST /api/auth/login/ - Login with signed message
  • GET /api/auth/verify/ - Verify authentication
  • POST /api/auth/logout/ - Logout

​
Users

  • GET /api/v1/users/ - List users
  • GET /api/v1/users/me/ - Get current user (auth required)
  • PATCH /api/v1/users/me/ - Update profile (auth required)
  • GET /api/v1/users/by-address/{address}/ - Get user by address

​
Contributions

  • GET /api/v1/contributions/ - List contributions
  • POST /api/v1/contributions/ - Submit contribution (auth required, reCAPTCHA)
  • GET /api/v1/contributions/{id}/ - Get contribution details
  • PATCH /api/v1/contributions/{id}/ - Edit submission (auth required)

​
Contribution Types

  • GET /api/v1/contribution-types/ - List types
  • GET /api/v1/contribution-types/{id}/ - Get type details
  • GET /api/v1/contribution-types/statistics/ - Type statistics

​
Leaderboard

  • GET /api/v1/leaderboard/ - Get rankings
  • GET /api/v1/leaderboard/stats/ - Global statistics
  • GET /api/v1/leaderboard/user_stats/by-address/{address}/ - User stats

​
Testing

​
Run All Tests

python manage.py test

​
Run Specific Tests

# Test a specific app
python manage.py test contributions

# Test a specific file
python manage.py test contributions.tests.test_models

# Test a specific class
python manage.py test contributions.tests.test_models.ContributionTestCase

​
Test Organization

Use the {app}/tests/ folder structure for better organization:
  • Create {app}/tests/__init__.py
  • Separate files: test_models.py, test_views.py, test_serializers.py

​
Admin Panel

Access the Django admin at http://localhost:8000/admin Features:
  • User management
  • Contribution type configuration
  • Manual contribution creation
  • Multiplier management
  • Submission review

​
Performance Optimization

The project uses context-aware serialization:
  • Light serializers for list views (minimal fields)
  • Full serializers for detail views (complete data)
  • select_related() for ForeignKey/OneToOne
  • prefetch_related() for reverse/ManyToMany
Example from users/serializers.py: 
class LightUserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ['id', 'email', 'name', 'address']

class UserSerializer(serializers.ModelSerializer):
    # Full serializer with all relationships
    ...

​
Next Steps

Frontend Setup

Set up the Svelte 5 frontend

Data Model

Understand the database structure

Authentication Flow

Learn the SIWE auth process

Environment Variables

Configure your environment

Build docs developers (and LLMs) love

Get started for freeTalk to us