Skip to content

Enhance README for bounty marketplace #59

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
egoriklok wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Enhance README for bounty marketplace #59

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
280 changes: 163 additions & 117 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,180 +1,226 @@
# Collaborator
# Collaborators

Collaborators is a GitHub bounty marketplace for open source work. Users can
create USDC bounties for public GitHub issues, submit pull request solutions,
and track solved bounties through GitHub webhook events.

The app is built around a simple flow:

1. Log in with GitHub through Privy.
2. Use the embedded Solana wallet associated with the account.
3. Browse or create issue bounties.
4. Submit a pull request as the solution.
5. Let the GitHub webhook verify merged work and mark the bounty as solved.

## Features

- **GitHub authentication**: Users sign in with GitHub through Privy.
- **Embedded Solana wallet**: Privy provides the wallet identity used for
reward attribution.
- **Bounty marketplace**: Browse active bounties, filter them, and open the
linked GitHub issue.
- **Issue search**: Find public GitHub issues and create a bounty from the dashboard.
- **Solution submissions**: Submit a pull request URL and PR number for an
active bounty.
- **Webhook tracking**: GitHub webhook events can mark bounties as solved when
linked pull requests are merged.
- **Bounty management**: Bounty owners can edit or delete active bounties.

## Tech Stack

- **Framework**: Next.js 15, React 19, TypeScript
- **Auth and wallet**: Privy
- **Database**: Prisma with PostgreSQL
- **GitHub API**: Octokit
- **Styling**: Tailwind CSS 4
- **Deployment**: Vercel-ready configuration

Transform your GitHub work into on-chain rewards and reputation. Earn NFT badges and SOL tokens for your real contributions on GitHub.
## Getting Started

## 🚀 What We've Built
### Prerequisites

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.
- Node.js 20+
- pnpm
- PostgreSQL database
- GitHub account
- Privy application

## ✨ Key Features
### Installation

- **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
Clone the repository and install dependencies:

## 🎯 How It Works
```bash
git clone https://github.com/andr-drgm/collaborators.git
cd collaborators
pnpm install
```

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
Create a local environment file:

## 🛠️ Technical Stack
```bash
cp .env.example .env.local
```

- **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
If `.env.example` is not present in your checkout, create `.env.local` with the
variables listed below.

## 🚀 Getting Started
### Environment Variables

### Prerequisites
```env
# Database
DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE"

- Node.js 18+ and pnpm
- Solana wallet (Phantom, Solflare, etc.)
- GitHub account
- Some SOL for transaction fees
# Privy
NEXT_PUBLIC_PRIVY_APP_ID="your_privy_app_id"
PRIVY_APP_SECRET="your_privy_app_secret"

### Development Setup
# GitHub API fallback token for server-side issue lookups
GITHUB_TOKEN="your_github_token"
# or
GITHUB_ACCESS_TOKEN="your_github_access_token"

This project uses Git hooks to ensure code quality. When you clone the repository, the following will be automatically set up:
# GitHub webhook verification
GITHUB_WEBHOOK_SECRET="your_webhook_secret"

- **Pre-commit hooks**: Automatically runs `pnpm lint` before each commit
- **Code formatting**: Ensures consistent code style across the project
# Optional public 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"
```

The hooks are managed by Husky and will be installed automatically when you run `pnpm install`.
Never commit real secrets. Use Vercel environment variables, a local secret
manager, or another protected deployment secret store for production values.

### Installation
### Database Setup

1. Clone the repository:
Generate the Prisma client and apply your database migrations:

```bash
git clone https://github.com/yourusername/the-collaborator.git
cd the-collaborator
pnpm prisma generate
pnpm prisma migrate dev
```

2. Install dependencies:
For production, use your normal migration release process:

```bash
pnpm install
pnpm prisma migrate deploy
```

3. Set up environment variables:
### Run Locally

Start the development server:

```bash
cp .env.example .env.local
pnpm dev
```

4. Configure your environment variables:

```env
# GitHub OAuth
GITHUB_ID=your_github_client_id
GITHUB_SECRET=your_github_client_secret
Open [http://localhost:3000](http://localhost:3000).

# NextAuth
NEXTAUTH_SECRET=your_nextauth_secret
NEXTAUTH_URL=http://localhost:3000
## GitHub Webhook Setup

# Solana
REACT_APP_MINT_AUTHORITY_SECRET_KEY=your_mint_authority_key
```
GitHub webhooks are used to keep bounty status in sync with repository activity.

5. Run the development server:
1. Open the GitHub repository that should be tracked.
2. Go to **Settings -> Webhooks -> Add webhook**.
3. Set the payload URL to:

```bash
pnpm dev
```text
https://YOUR_DOMAIN/api/github/webhook
```

6. Open [http://localhost:3000](http://localhost:3000) in your browser
After the URL is set:

## 🔧 Configuration
1. Set the content type to `application/json`.
2. Add the same secret used in `GITHUB_WEBHOOK_SECRET`.
3. Select issue and pull request events.
4. Save the webhook.

### GitHub OAuth Setup
The webhook handler can:

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`
- react to issue events for bounty-related issues;
- detect pull request activity;
- mark submitted bounties as solved after relevant merged PR events.

### Solana Configuration
## Bounty Workflow

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
### For bounty creators

## 📱 User Experience Improvements
1. Log in with GitHub.
2. Search for a public GitHub issue.
3. Create a bounty with a USDC amount.
4. Install or verify the repository webhook.
5. Review submitted pull request solutions.

### For Newcomers
### For contributors

- **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
1. Browse active bounties on the dashboard.
2. Open the GitHub issue.
3. Implement the fix in a pull request.
4. Submit the PR URL and number through the bounty card.
5. Wait for merge and webhook verification.

### For Web3 Developers
## Available Scripts

- **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

### Trust & Security
```bash
pnpm dev # Start the local development server
pnpm build # Generate Prisma client and build the Next.js app
pnpm start # Start the production server
pnpm lint # Run linting
```

- **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
The repository also installs Husky hooks through the `prepare` script.

## 🎨 Design System
## Project Structure

- **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
```text
src/app/ Next.js routes and API handlers
src/app/dashboard/ Dashboard UI
src/app/api/bounties/ Bounty and submission endpoints
src/app/api/github/ GitHub search, issue, webhook, and commit routes
src/components/ Shared UI components
src/components/dashboard Dashboard bounty and issue cards
src/lib/ Privy and webhook helpers
src/services/ GitHub service functions
prisma/schema.prisma Database schema
```

## 🔮 Coming Soon
## Security Notes

- **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
- Do not expose Privy secrets, GitHub tokens, database URLs, or webhook secrets
in client-side code.
- Keep `GITHUB_WEBHOOK_SECRET` enabled in production.
- Store production environment variables in the deployment platform secret store.
- Review webhook permissions before connecting repositories.
- Validate PR URLs and bounty ownership before accepting submissions.

## 🤝 Contributing
## Deployment

We welcome contributions! Please see our contributing guidelines for details on:
The project is configured for Vercel.

- Code style and standards
- Testing requirements
- Pull request process
- Community guidelines
Before deploying, configure:

## 📄 License
- `DATABASE_URL`
- `NEXT_PUBLIC_PRIVY_APP_ID`
- `PRIVY_APP_SECRET`
- `GITHUB_TOKEN` or `GITHUB_ACCESS_TOKEN`
- `GITHUB_WEBHOOK_SECRET`
- optional public URL variables

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Then build the app:

## 🆘 Support
```bash
pnpm build
```

- **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
## Documentation

## 🌟 Acknowledgments
- [Privy setup guide](./PRIVY_SETUP.md)
- [Migration summary](./MIGRATION_SUMMARY.md)

- Solana Foundation for blockchain infrastructure
- GitHub for developer platform integration
- Next.js team for the amazing framework
- Our community of contributors and testers
## License

---
Add the project license file before publishing license-specific claims.

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

_Transform your contributions. Build your reputation. Get rewarded._
Use GitHub Issues for bug reports, feature requests, and bounty discussions.