Wavefront Sybil Defense API

A high-performance backend API designed to aggregate, analyze, and flag suspicious repository contribution patterns. Built with Node.js, Express.js, and PostgreSQL, this service provides essential telemetry for Web3 ecosystems to detect automated bot activity and duplicate accounts during grant distribution cycles.

Table of Contents

• Features
• Drips Wave Program
• Active Issues & Point Matrix
• Global Acceptance Criteria
• Local Development Setup
• Project Structure
• License

Features

• Webhook Telemetry Ingestion — Ingest and normalize contribution events from GitHub and other sources in real time.
• Sybil Flagging Engine — Detect bot-like behavior, duplicate accounts, and anomalous contribution patterns using configurable heuristics.
• Role-Based Access Control — Supabase RBAC middleware ensures only authorized ecosystem_admin roles can access sensitive endpoints.
• Pagination & Input Sanitization — All telemetry endpoints enforce strict integer casting, boundary limits, and SQL injection prevention.
• Concurrent PostgreSQL Pooling — Production-grade connection pooling with pg-pool and ACID-compliant transaction rollbacks.
• High-Throughput Ready — Capable of handling 5,000+ concurrent requests without connection exhaustion.

🌊 Drips Wave Program: Maintainer Guidelines

This repository participates in recurring Drips Wave sprints. Contributors earn points that translate directly to on-chain rewards. We strictly enforce the "Fix, Merge, Earn" workflow.

1. Pick an open issue from the wave board.
2. Fork the repository and implement the fix or feature.
3. Submit a PR passing all CI checks (ESLint, test coverage, migration validation).
4. Once merged, points are awarded and redeemable for on-chain rewards.

🎯 Active Wave Issues & Point Matrix

🔴 High Complexity — 200 Points

Issue #11: Concurrent PostgreSQL Connection Pooling & ACID Transactions

Design the database insertion logic to handle massive spikes in webhook telemetry during the final hours of a Wave sprint. Implement pg-pool with strict transaction rollbacks to ensure no partial Sybil flags are recorded if the connection drops.

Requirements:

• Provide a load-testing script demonstrating the API can handle 5,000 concurrent requests without throwing connection exhaustion errors.

---

🟡 Medium Complexity — 150 Points

Issue #16: Implement Supabase Role-Based Access Control (RBAC) Middleware

Create an Express middleware that validates incoming JWTs from Supabase. The middleware must ensure that only authenticated addresses with the ecosystem_admin role can trigger the /api/v1/ban-hammer endpoint.

Requirements:

• Write unit tests mocking valid, invalid, and expired tokens.

---

🟢 Trivial Complexity — 100 Points

Issue #24: Sanitize Pagination Inputs for Telemetry Endpoints

Update the /api/v1/telemetry/logs route to enforce strict integer casting and boundary limits (maximum 100 results per page) on the limit and offset query parameters.

Requirements:

• Prevent potential SQL injection vectors by ensuring raw query parameters are never concatenated directly into the PostgreSQL query strings.

✅ Global Acceptance Criteria

• Test Coverage: 95% test coverage using Jest or Mocha/Chai.
• Database Migrations: Any modifications to the PostgreSQL schema must be accompanied by raw SQL migration files in the /migrations directory.
• Code Quality: All PRs must pass the standard ESLint configuration (npm run lint:fix) before the CI pipeline will allow a merge.

🛠️ Local Development Setup

Prerequisites

• Node.js v18+
• PostgreSQL v14+
• Supabase instance

1. Clone & Install

git clone https://github.com/levi-soromto/wavefront-sybil-defense.git
cd wavefront-sybil-defense
npm install

2. Configure Environment

Rename .env.example to .env and provide your local PostgreSQL connection string and Supabase API keys.

3. Run Server

npm run dev

Project Structure

wavefront-sybil-defense/
├── src/
│   ├── middleware/        # Express middleware (RBAC, validation, error handling)
│   ├── routes/            # API route definitions
│   ├── services/          # Business logic and Sybil detection engine
│   ├── db/                # Database client, connection pool, queries
│   └── utils/             # Helpers and utilities
├── migrations/            # Raw SQL migration files
├── tests/                 # Jest/Mocha test suites
├── scripts/               # Load-testing and automation scripts
├── .env.example           # Environment variable template
├── package.json
└── README.md

License

This project is licensed under the MIT License.