Skip to content

docs: rewrite README for the current USDC bounty workflow #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
notjamyfriench wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: rewrite README for the current USDC bounty workflow #44

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a61c359
docs: rewrite README for USDC bounty workflow
notjamyfriench Feb 24, 2026
9550ca2
docs: add issue-40 acceptance checklist section
notjamyfriench Feb 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
235 changes: 104 additions & 131 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,180 +1,153 @@
# Collaborator
# Collaborators

Transform your GitHub work into on-chain rewards and reputation. Earn NFT badges and SOL tokens for your real contributions on GitHub.
Collaborators is a GitHub bounty marketplace where maintainers fund issues in USDC and contributors earn rewards by shipping merged pull requests.

## 🚀 What We've Built
The app connects GitHub identity with a Solana wallet using Privy, tracks bounty submissions, and keeps bounty status in sync with GitHub events.

Collaborators is a Web3 platform that automatically converts your GitHub activity into verifiable on-chain achievements. Every meaningful contribution mints NFT badges and earns SOL tokens, helping you build your on-chain reputation while getting rewarded for open-source collaboration.
## What Is Implemented Today

## ✨ Key Features
- Public bounty board with `ACTIVE`, `SOLVED`, `EXPIRED`, and `CANCELLED` states.
- Contributor dashboard tabs: `Bounties`, `My Issues`, `Solved Issues`, `My Bounties`.
- Bounty creation tied to a GitHub issue (`owner/repo/issue_number`).
- PR submission flow for solvers (`/api/bounties/submissions`).
- GitHub webhook endpoint for issue and pull request events (`/api/github/webhook`).
- Repository bot-installation tracking for bounty automation checks.
- Privy-based authentication with GitHub OAuth and embedded Solana wallets.

- **GitHub Integration**: Seamlessly connect your GitHub account to track contributions
- **Automatic Rewards**: Earn SOL tokens for commits, pull requests, reviews, and issue resolution
- **NFT Badges**: Unique digital credentials minted for your achievements
- **On-Chain Reputation**: Verifiable proof of your contributions stored on Solana blockchain
- **Real-Time Tracking**: Monitor your contribution activity with GitHub-style heatmaps
- **Secure Wallet Integration**: Support for Phantom, Solflare, and other Solana wallets
## Bounty Lifecycle

## 🎯 How It Works
### Maintainer flow

1. **Connect GitHub**: Log in with your GitHub account
2. **Link Wallet**: Connect your Solana wallet (Phantom, Solflare, etc.)
3. **Start Contributing**: Continue your normal GitHub workflow
4. **Get Rewarded**: Earn tokens and NFT badges automatically
1. Log in and open an issue from the `My Issues` tab.
2. Create a bounty amount in USDC for that issue.
3. Configure GitHub webhook for the repository.
4. Review submitted PRs and merge a valid solution.
5. Mark payout complete to the solver wallet.

## 🛠️ Technical Stack
### Solver flow

- **Frontend**: Next.js 14, React, TypeScript
- **Styling**: Tailwind CSS with custom design system
- **Blockchain**: Solana blockchain integration
- **Authentication**: NextAuth.js with GitHub OAuth
- **Database**: Prisma with PostgreSQL
- **Deployment**: Vercel-ready configuration
1. Pick an `ACTIVE` bounty with an open GitHub issue.
2. Implement the fix and open a PR in the target repository.
3. Submit PR URL in the dashboard (`Submit Solution`).
4. Wait for maintainer review and merge.
5. Receive USDC payout from the bounty poster.

## 🚀 Getting Started
Note: Current schema and UI indicate payout transfer is maintainer-managed after solver verification.

### Prerequisites

- Node.js 18+ and pnpm
- Solana wallet (Phantom, Solflare, etc.)
- GitHub account
- Some SOL for transaction fees
## Acceptance Checklist For Issue #40

### Development Setup
This README update is scoped to issue #40 ("Enhance README") and includes:

This project uses Git hooks to ensure code quality. When you clone the repository, the following will be automatically set up:
- clear project summary and architecture snapshot,
- explicit maintainer and solver bounty flows,
- webhook setup requirements tied to merge-based automation,
- API route inventory for quick evaluator verification,
- local setup and run commands for reproducibility.

- **Pre-commit hooks**: Automatically runs `pnpm lint` before each commit
- **Code formatting**: Ensures consistent code style across the project
The goal is to let maintainers verify README completeness quickly against current repository behavior.

The hooks are managed by Husky and will be installed automatically when you run `pnpm install`.
## Webhook Setup (Required for Automation)

### Installation
Configure a webhook in the target GitHub repository:

1. Clone the repository:

```bash
git clone https://github.com/yourusername/the-collaborator.git
cd the-collaborator
```
- Payload URL: `https://<your-domain>/api/github/webhook`
- Content type: `application/json`
- Events: `Issues` and `Pull requests`
- Secret: set `GITHUB_WEBHOOK_SECRET` in your environment (recommended)

2. Install dependencies:
When a linked PR is merged, webhook handlers can mark matching submissions as approved and move the bounty to `SOLVED`.

```bash
pnpm install
```
## API Overview

3. Set up environment variables:
- `GET /api/bounties` - list bounties by status.
- `POST /api/bounties` - create bounty (auth required).
- `GET /api/bounties/my` - list bounties created by current user.
- `GET /api/bounties/solved` - list solved bounties for current user.
- `POST /api/bounties/submissions` - submit PR for bounty.
- `GET /api/github/user/issues` - list current user GitHub issues.
- `GET/POST /api/github/bot/installation` - bot installation status and updates.
- `POST /api/github/webhook` - process GitHub webhook events.
- `GET /api/user/me` - current authenticated user profile.

```bash
cp .env.example .env.local
```
## Tech Stack

4. Configure your environment variables:
- Next.js 15 + React 19 + TypeScript
- Tailwind CSS 4
- Prisma + PostgreSQL
- Privy (`@privy-io/react-auth`, `@privy-io/server-auth`)
- GitHub API integrations (Octokit + custom routes)

```env
# GitHub OAuth
GITHUB_ID=your_github_client_id
GITHUB_SECRET=your_github_client_secret
## Local Development

# NextAuth
NEXTAUTH_SECRET=your_nextauth_secret
NEXTAUTH_URL=http://localhost:3000
### Prerequisites

# Solana
REACT_APP_MINT_AUTHORITY_SECRET_KEY=your_mint_authority_key
```
- Node.js 18+
- pnpm
- PostgreSQL

5. Run the development server:
### 1) Install dependencies

```bash
pnpm dev
pnpm install
```

6. Open [http://localhost:3000](http://localhost:3000) in your browser

## 🔧 Configuration
### 2) Create `.env.local`

### GitHub OAuth Setup

1. Go to GitHub Developer Settings
2. Create a new OAuth App
3. Set the callback URL to `http://localhost:3000/api/auth/callback/github`
4. Copy the Client ID and Client Secret to your `.env.local`

### Solana Configuration

1. Set up a Solana wallet with some SOL
2. Configure your mint authority for token distribution
3. Update the mint address in the dashboard component

## 📱 User Experience Improvements

### For Newcomers

- **Clear Value Proposition**: "Transform GitHub work into on-chain rewards and reputation"
- **Key Terms Explained**: Hover tooltips for SOL tokens, NFT badges, and on-chain reputation
- **Simple Steps**: 3-step onboarding process clearly explained
- **Visual Flowchart**: Step-by-step process visualization

### For Web3 Developers

- **Advanced Features**: Detailed contribution tracking and analytics
- **Technical Details**: Comprehensive dashboard with GitHub-style heatmaps
- **Wallet Integration**: Seamless Solana wallet connection
- **Real-Time Updates**: Live contribution tracking and reward calculation
```env
DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/DB_NAME

### Trust & Security
NEXT_PUBLIC_PRIVY_APP_ID=your_privy_app_id
PRIVY_APP_SECRET=your_privy_app_secret

- **Security Information**: Clear explanations of data privacy and wallet security
- **FAQ Section**: Common questions about tracking, rewards, and supported wallets
- **Help Tooltips**: Contextual assistance throughout the platform
- **Onboarding Guidance**: Step-by-step help for wallet setup
# Optional but useful for server-side GitHub calls
GITHUB_TOKEN=your_github_token
GITHUB_ACCESS_TOKEN=your_github_access_token

## 🎨 Design System
# Optional webhook signature verification
GITHUB_WEBHOOK_SECRET=your_webhook_secret

- **Color Palette**: Cyan to teal gradients with dark theme
- **Typography**: Geist Sans and Geist Mono fonts
- **Components**: Consistent card designs with hover effects
- **Responsive**: Mobile-first design with desktop optimizations
- **Accessibility**: High contrast ratios and keyboard navigation
# Optional UI footer links
NEXT_PUBLIC_X_URL=https://x.com/collaborat0rs
NEXT_PUBLIC_PRIVACY_URL=https://example.com/privacy
NEXT_PUBLIC_TERMS_URL=https://example.com/terms
```

## 🔮 Coming Soon
### 3) Run database setup

- **Team Leaderboards**: Compete with your team and climb the ranks
- **Exclusive NFT Tiers**: Rare collectibles for top contributors
- **API Access**: Integrate rewards into your own applications
- **Multi-Chain Support**: Expand beyond Solana to other blockchains
```bash
pnpm prisma generate
pnpm prisma migrate dev
```

## 🤝 Contributing
### 4) Start the app

We welcome contributions! Please see our contributing guidelines for details on:
```bash
pnpm dev
```

- Code style and standards
- Testing requirements
- Pull request process
- Community guidelines
Open `http://localhost:3000`.

## 📄 License
## Useful Scripts

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
- `pnpm dev` - start local dev server (Turbopack).
- `pnpm build` - generate Prisma client and build production app.
- `pnpm start` - run production build.
- `pnpm lint` - run lint checks.

## 🆘 Support
## Repository Notes

- **Documentation**: Check this README and inline help tooltips
- **Issues**: Report bugs or feature requests via GitHub Issues
- **Discussions**: Join community discussions for help and ideas
- **Email**: Contact the team directly for urgent matters
- `src/app/api` contains server routes for bounties, GitHub integration, and auth.
- `prisma/schema.prisma` defines bounty, submission, user, and bot-installation models.
- `PRIVY_SETUP.md` contains step-by-step Privy setup details.

## 🌟 Acknowledgments
## Contributing

- Solana Foundation for blockchain infrastructure
- GitHub for developer platform integration
- Next.js team for the amazing framework
- Our community of contributors and testers
Contributions are welcome. If your change affects bounty logic or payout flow, include:

---
- API contract updates.
- Prisma migration notes.
- Webhook behavior changes.

**Collaborators** - Building the future of developer collaboration and rewards.
## License

_Transform your contributions. Build your reputation. Get rewarded._
MIT. See [LICENSE](LICENSE).