QF Donations Core Service

Core service for Quadratic Funding donations platform built with NestJS, Prisma, and GraphQL.

Features

• ✅ NestJS modular architecture
• ✅ Prisma ORM with PostgreSQL
• ✅ GraphQL API with Apollo Server
• ✅ Multi-wallet support per user
• ✅ Semantic search with pg_trgm
• ✅ Redis caching and rate limiting
• ✅ AdminJS dashboard
• ✅ Multi-chain EVM support
• ✅ Integration with Blockchain verification service
• ✅ JWT authentication via SIWE
• ✅ Automated donation verification cronjobs
• ✅ Runtime configuration system with Discord bot integration

Prerequisites

• Node.js >= 18.x
• Docker and Docker Compose
• pnpm

Quick Start

1. Clone and Install

cd giveth-v6-core
pnpm install

2. Start Infrastructure

# Start PostgreSQL, Redis, and admin tools
docker-compose up -d

# Wait for services to be healthy
docker-compose ps

3. Setup Database

# Generate Prisma client
npm run prisma:generate

# Run migrations
npm run prisma:migrate

# Seed database
npm run prisma:seed

4. Configure Environment

Copy .env.example to .env and update the values:

cp .env.example .env

Key variables to configure:

• DATABASE_URL: PostgreSQL connection string
• JWT_SECRET: Secret for JWT tokens
• BLOCKCHAIN_INTEGRATION_SERVICE_URL: URL for blockchain verification service
• SIWE_AUTH_SERVICE_URL: URL for SIWE authentication service
• NOTIFICATION_CENTER_URL: URL for notification service
• NOTIFICATION_CENTER_USERNAME / NOTIFICATION_CENTER_PASSWORD: basic auth for notification center
• PINATA_API_KEY / PINATA_SECRET_KEY: credentials for Pinata uploads
• PINATA_GATEWAY: gateway base URL (defaults to https://gateway.pinata.cloud)

5. Start Development Server

npm run start:dev

The service will be available at:

• API: http://localhost:3000
• GraphQL Playground: http://localhost:3000/graphql
• Admin Dashboard: http://localhost:3000/admin
• Health Check: http://localhost:3000/health
• pgAdmin: http://localhost:5050 (admin@giveth.io / admin)
• Redis Commander: http://localhost:8081

Available Services

When running docker-compose up -d, the following services are started:

• PostgreSQL: localhost:5432
• Redis: localhost:6379
• pgAdmin: http://localhost:5050 (admin@giveth.io / admin)
• Redis Commander: http://localhost:8081

Scripts

# Development
npm run start:dev          # Start with hot reload
npm run start:debug        # Start in debug mode

# Build
npm run build              # Build for production
npm run start:prod         # Run production build

# Database
npm run prisma:generate    # Generate Prisma client
npm run prisma:migrate     # Run migrations
npm run prisma:studio      # Open Prisma Studio
npm run prisma:seed        # Seed database

# Code Quality
npm run lint               # Run ESLint
npm run format             # Format with Prettier

# Testing
npm run test               # Run unit tests
npm run test:watch         # Run tests in watch mode
npm run test:cov           # Run tests with coverage
npm run test:e2e           # Run e2e tests

Project Structure

src/
├── modules/              # Domain modules
│   ├── user/            # User management
│   ├── project/         # Project management
│   ├── donation/        # Donation handling
│   ├── qf-round/        # QF round management
│   ├── category/        # Categories
│   └── token/           # Token management
├── common/              # Shared utilities
│   ├── decorators/      # Custom decorators
│   ├── guards/          # Auth guards
│   ├── filters/         # Exception filters
│   ├── pipes/           # Validation pipes
│   └── interceptors/    # Interceptors
├── config/              # Configuration
├── database/            # Prisma and migrations
├── integrations/        # External service clients
└── cronjobs/            # Scheduled tasks

Architecture

Database

• ORM: Prisma with PostgreSQL
• Read/Write Separation: Automatic routing to read replicas
• Semantic Search: pg_trgm extension for fuzzy text search
• Connection Pooling: Built-in Prisma connection pooling

Authentication

• Method: Sign-In with Ethereum (SIWE)
• Integration: SiweAuthMicroservice
• Tokens: JWT with configurable expiration
• Multi-wallet: Each user can have multiple wallet addresses

Caching

• Layer: Redis
• Strategy: GraphQL query result caching with TTL (projects, donations, users, categories, tokens, QF rounds)
• TTL: 1–60 minutes depending on query type (e.g. projects 3m, categories 60m)
• Opt-out: @SkipCache() decorator on resolvers that handle personalized data
• Invalidation: Event-based cache invalidation plus TTL fallback

External Services

1. Blockchain Integration Service: Transaction verification
2. SIWE Auth Microservice: Authentication and JWT generation
3. Notification Center: Email and push notifications
4. Matching Service: QF matching calculations (Python, to be implemented)

Adding New Chains

To add a new EVM-compatible chain, simply add it to src/config/chains.config.ts:

export const CHAINS: Record<number, ChainConfig> = {
  // ... existing chains
  
  // Your new chain
  12345: {
    id: 12345,
    name: 'Your Chain',
    nativeCurrency: {
      name: 'Token',
      symbol: 'TKN',
      decimals: 18,
    },
    rpcUrls: [process.env.YOUR_CHAIN_RPC_URL || 'https://rpc.yourchain.com'],
    blockExplorerUrls: ['https://explorer.yourchain.com'],
    isTestnet: false,
    isActive: true,
  },
};

Runtime Configuration

This project includes a runtime configuration system that allows you to change operational parameters without code changes or redeployment.

Features

• Store configs in database with caching
• Discord bot for managing configs
• AdminJS interface for viewing/editing
• Type-safe parsing (string, number, boolean, JSON)
• Audit trail (who/when updated)

Quick Setup

Add to your .env:

DISCORD_BOT_ENABLED=true
DISCORD_BOT_TOKEN=your_bot_token_here
DISCORD_ALLOWED_ROLE_IDS=admin_role_id_1,admin_role_id_2
DISCORD_ALLOWED_USER_IDS=user_id_1,user_id_2

Discord Commands

!config help                                           # Show help
!config list core                                      # List all configs for a service
!config get blockchain-integration timeout-seconds     # Get a config value
!config set blockchain-integration timeout-seconds 45  # Set a config value
!config delete core test-key                           # Delete a config
!config refresh blockchain-integration                 # Refresh cache

For full documentation, see docs/RUNTIME_CONFIG.md.

Admin Authentication

This project uses a database-based authentication system for the AdminJS panel, allowing multiple admin users with secure password storage.

Quick Setup

# Generate password hash
pnpm admin:generate-password --interactive

# Add admin via Discord
!admin add admin@giveth.io $2b$10$your_hash_here

# Or during seed (for local development)
# Add to .env:
ADMIN_EMAIL=admin@localhost
ADMIN_PASSWORD=DevPassword123!
pnpm prisma:seed

Discord Commands

!admin help                                    # Show help
!admin list                                    # List all admin users
!admin add admin@giveth.io $2b$10$hash...      # Add/update admin user
!admin delete admin@giveth.io                  # Delete admin user

For full documentation, see:

• Admin Authentication Guide - Complete documentation
• Admin Quick Start - Quick setup guide

Development Workflow

Creating a Donation

1. Frontend creates pending donation via GraphQL mutation
2. User completes transaction on blockchain
3. Frontend calls verify donation mutation with tx hash
4. Core service verifies with Blockchain Integration Service
5. Donation status updated to "verified"
6. Cronjob periodically checks and verifies pending donations

QF Round Management

1. Admin creates QF round via AdminJS
2. Projects are assigned to the round
3. Donations during round period are tracked
4. Matching calculations provided by Matching Service
5. Admin exports results at round end

Testing

# Run all tests
npm test

# Run specific test suite
npm test -- user.service.spec.ts

# Run with coverage
npm run test:cov

# E2E tests
npm run test:e2e

Deployment

Production Build

npm run build
npm run start:prod

Docker

# Build image
docker build -t qf-donations-core .

# Run container
docker run -p 3000:3000 --env-file .env qf-donations-core

Contributing

1. Create feature branch
2. Make changes
3. Run tests and linting
4. Submit pull request

License

ISC

Support

For issues and questions, please open an issue on GitHub or contact the Giveth team.