Kinetic

Kinetic is a meritocratic funding platform purpose-built for Open Source contributors. It replaces vanity "green square" metrics with a mathematically rigorous scoring engine

Comment

Kinetic

Stack License Hackathon

Kinetic is a meritocratic funding platform purpose-built for Open Source contributors. It replaces vanity "green square" metrics with a mathematically rigorous scoring engine that measures the true engineering complexity and ecosystem impact of open-source work.

The Problem

Traditional bounty systems are "first-come, first-served" or based on simplistic commit counts. This leads to micro-PR farming, code bloat, and reputation dominance, where new, high-quality contributors struggle to compete against established "elites."

The Solution - KINETIC

Kinetic triangulates six independent signal layers using its MSTS engine to determine a contributor's final value. It incentivizes high-leverage engineering, cross-repo collaboration, and production-grade reliability.

Table of Contents

Architecture Overview

Kinetic is organized as a monorepo consisting of three principal layers, achieving a seamless transition from code contribution to on-chain payout.

sequenceDiagram
    participant GH as GitHub (Webhooks)
    participant KB as Kinetic Backend
    participant DB as MongoDB
    participant BC as Flow Blockchain (Cadence)

    GH->>KB: PR Merged / Review Submitted
    KB->>GH: Query GitHub Actions (Proof-of-Build)
    KB->>KB: Calculate MSTS (Multi-Signal Score)
    KB->>DB: Persist Contribution Data
    KB->>BC: Propose Payout (Transaction)
    BC-->>BC: Multi-Sig Approval Cycle
    BC->>BC: Execute Payout (FLOW Disbursement)
Layer Technology Purpose
Frontend Next.js 16, React 19, Tailwind CSS 4, GSAP High-fidelity dashboard for organizations and contributors.
Backend Node.js, Express, MongoDB, Passport (OAuth) Scoring engine, DID management, and webhook orchestration.
Blockchain Flow Testnet, Cadence, FCL Secure, transparent treasury management and multi-sig distributions.

How to Run the Project

Prerequisites

Ensure the following tools are installed on your system before proceeding:

  • Node.js v20 or later
  • npm v9 or later
  • MongoDB (local instance or a hosted service such as MongoDB Atlas)
  • Git
  • Flow CLI (required only for smart contract development and deployment)

You will also need the following external accounts and credentials:

  • A GitHub OAuth Application (Client ID and Client Secret)
  • A MongoDB connection string
  • A Flow Testnet account (for blockchain interactions)

Backend Setup

  1. Clone the repository and navigate to the backend directory:
   git clone <repository-url>
   cd kinetic/backend
  1. Install dependencies:
   npm install
  1. Create a .env file in the backend/ directory with the following variables:
   PORT=5000
   MONGODB_URI=<your-mongodb-connection-string>
   GITHUB_CLIENT_ID=<your-github-oauth-client-id>
   GITHUB_CLIENT_SECRET=<your-github-oauth-client-secret>
   SESSION_SECRET=<a-secure-random-string>
   JWT_SECRET=<a-secure-random-string>
   FRONTEND_URL=http://localhost:3000
   FLOW_ADDRESS=<your-flow-testnet-account-address>
   FLOW_PRIVATE_KEY=<your-flow-testnet-private-key>
  1. Start the development server:
   npm run dev

The API will be available at http://localhost:5000. A health check endpoint is accessible at http://localhost:5000/health.

Frontend Setup

  1. Navigate to the frontend directory:
   cd kinetic/frontend
  1. Install dependencies:
   npm install
  1. Create a .env file in the frontend/ directory with the following variables:
   NEXT_PUBLIC_FLOW_ADDRESS=<your-flow-testnet-contract-address>
   NEXT_PUBLIC_FLOW_NETWORK=testnet
  1. Start the development server:
   npm run dev

The application will be available at http://localhost:3000.

Flow Blockchain Setup

The smart contract layer uses Cadence, the native language for the Flow blockchain. To deploy or modify contracts:

  1. Navigate to the Flow directory:
   cd kinetic/backend/flow
  1. To deploy the KineticPayout contract to the Flow Testnet:
   flow project deploy --network=testnet
  1. To run Cadence scripts (read-only operations):
   flow scripts execute cadence/scripts/get_balance.cdc --network=testnet
  1. To submit transactions (state-changing operations):
   flow transactions send cadence/transactions/propose_payout.cdc --network=testnet

Refer to the Flow CLI Documentation for additional commands and configuration options.

Features

The Contribution Scoring Engine

Kinetic moves beyond "vanity metrics" (like commit counts or lines of code) by employing a multi-staged algorithmic pipeline. This engine ensures that payouts are mathematically proportional to the actual engineering value delivered.

1. The Verification Gate: Proof-of-Build

Before any analysis occurs, every contribution must pass the Proof-of-Build gate. Kinetic queries the GitHub Actions API to verify that the specific commit hash successfully passed all CI/CD integration tests.

[!IMPORTANT] Merged code without a corresponding successful build trace receives a final score of zero.

2. The Algorithmic Pipeline

graph TD
    A[Merged PR] --> B{Proof-of-Build}
    B -- Fail --> C[Score: 0]
    B -- Pass --> D[Anti-Gaming Filters]
    D -- Spam/Low Quality --> C
    D -- Valid --> E[Base Scoring Engine]
    E --> F[Reputation Multiplier]
    F --> G[Post-Adjustment Filters]
    G --> H[Final Payout Allocation]

3. Core Scoring Components

Layer Component Description
Filter Anti-Gaming Hard cutoffs for quality (<0.3) and impact (<0.2) to prevent "micro-PR" farming.
Base Impact & Complexity Log-scaled complexity calculation log(lines + 1) / log(max + 1) prevents reward for "code bloat".
Base Review Depth Maintainer review scores and comment density; rewards "consensus-building" code.
Incentive Reputation (1.5x) A capped 1.5x multiplier based on historical consistency and "Code Survival Rate".
Stability Diminishing Returns Applies a penalty factor 1 / (1 + 0.1*(k-1)) for high-frequency PR spamming.

4. The Math Behind the Meritocracy

The final score for any contribution $i$ is calculated as: $$FinalScore_i = \left( \sum w_n \cdot Metric_{ni} \right) \times \left( 1 + \lambda \cdot \log(Reputation_i + 1) \right) \times Penalty_{spam}$$

This dual-layered approach balances objective PR metrics with long-term ecosystem health.

Decentralized Identity

Contributors authenticate via GitHub OAuth. Upon first login, Kinetic mints a Decentralized Identifier (DID) using the key-did-provider-ed25519 standard from the Ceramic / Protocol Labs stack. DID documents are stored on an in-process Helia IPFS node. This cryptographic identity binds a contributor's commits, pull requests, and issues as verifiable credentials.

Autonomous FLOW Payouts

Payout distribution is handled entirely on-chain through the KineticPayout Cadence smart contract deployed on the Flow Testnet. The contract supports:

  • Treasury Management -- Organizations deposit FLOW tokens into a managed treasury vault.
  • Payout Proposals -- Authorized signers submit payout batches specifying recipient addresses and amounts.
  • Multi-Signature Approvals -- Payouts require a configurable threshold of approvals from authorized signers before execution.
  • Direct Execution -- Once the approval threshold is met, funds are disbursed directly to contributor wallets.

The frontend integrates with the Flow Client Library (FCL) for wallet authentication, balance queries, and transaction signing. Contributors can connect their Flow wallet, view pending payouts, and approve or execute distributions directly from the dashboard.

Project Structure

kinetic/
  backend/
    config/             # Database connection and Passport OAuth configuration
    flow/
      cadence/
        contracts/      # KineticPayout.cdc smart contract
        scripts/        # Read-only Cadence scripts
        transactions/   # State-changing Cadence transactions
        tests/          # Cadence integration tests
      flow.json         # Flow project configuration
    models/             # Mongoose data models
    routes/             # Express route handlers (auth, contribution, kinetic, repo, webhook)
    services/           # Core business logic (contribution scoring, DID, Flow, kinetic mechanisms)
    server.js           # Application entry point
  frontend/
    src/
      app/              # Next.js App Router pages (dashboard, bounties, docs, voting, onboarding)
      components/       # Reusable UI components (PillNav, LogoLoop, OrbitingEcosystem, etc.)
      lib/              # Shared utilities and Flow blockchain client (flow.ts)
  contribution_algo.md  # Detailed specification of the contribution scoring algorithm
  readme.md             # This file

API Reference

The backend exposes the following primary endpoints:

Method Endpoint Description
GET /api/auth/github Initiate GitHub OAuth authentication flow
GET /api/auth/github/callback OAuth callback; creates DID on first login
GET /api/auth/me Retrieve current user profile (JWT required)
GET /api/auth/did/:username Resolve a DID by GitHub username (public)
GET /api/auth/did-resolve/self Re-resolve the authenticated user's DID (JWT required)
PUT /api/auth/wallet Link a Flow wallet address to the authenticated account (JWT required)
GET /api/auth/logout Terminate the current session
GET /health Health check endpoint

Additional routes are available under /api/contribution, /api/kinetic, /api/org, and /api/webhook for contribution scoring, kinetic mechanism queries, organization repository management, and GitHub webhook processing, respectively.

License

This project is licensed under the ISC License. See the repository for details.

Built With

Share this project:

Updates