diff --git a/README.md b/README.md index cab48cc..968fccb 100644 --- a/README.md +++ b/README.md @@ -1,180 +1,206 @@ -# 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 that connects open-source work to on-chain rewards and reputation. Sponsors can attach USDC-denominated bounties to GitHub issues, contributors can submit pull requests as solutions, and the app tracks bounty status from issue discovery through PR submission and verification. -## 🚀 What We've Built +## What you can do -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. +- Browse active bounties across public GitHub repositories. +- Search GitHub issues and create a bounty for an issue you want solved. +- Submit a pull request URL as your solution to an active bounty. +- Track your posted bounties, submitted solutions, and solved bounties from one dashboard. +- Link GitHub identity and a wallet through Privy so accepted work can be associated with the right contributor. +- Install or track the GitHub bot/webhook flow needed to verify repository activity. -## ✨ Key Features +## How the bounty flow works -- **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 +### For sponsors -## 🎯 How It Works +1. Sign in with Privy and link GitHub. +2. Search for a GitHub issue or select one of your own issues. +3. Create a bounty with an amount, title, description, issue URL, and repository metadata. +4. The bounty appears in the active bounty feed with `bounty` and `usdc-reward` metadata. +5. Review submitted pull requests. +6. When a winning PR is merged, the webhook flow marks the submission approved and the bounty solved. -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 +### For contributors -## 🛠️ Technical Stack +1. Sign in with Privy and link GitHub. +2. Link or use the wallet created by Privy. +3. Pick an active bounty from the dashboard. +4. Open a pull request that solves the linked GitHub issue. +5. Submit the PR URL through the bounty card. +6. If the PR is merged and the bounty is still active, the app verifies the submission and records the solver. -- **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 - -## 🚀 Getting Started - -### Prerequisites +## Current product areas -- Node.js 18+ and pnpm -- Solana wallet (Phantom, Solflare, etc.) -- GitHub account -- Some SOL for transaction fees +The dashboard is the main application surface and is organized around these views: -### Development Setup +- **Active Bounties**: Browse open bounty opportunities and submit PR solutions. +- **My Issues**: Load GitHub issues for the authenticated user. +- **Solved Issues**: Review bounties solved by the current user. +- **My Bounties**: Manage bounties created by the current user. -This project uses Git hooks to ensure code quality. When you clone the repository, the following will be automatically set up: +The legacy contribution-tracking and NFT badge components are archived under `src/components/dashboard/archive`, `src/hooks/archive`, and `src/utils/archive` so they can be recovered later without confusing the current bounty marketplace MVP. -- **Pre-commit hooks**: Automatically runs `pnpm lint` before each commit -- **Code formatting**: Ensures consistent code style across the project +## Tech stack -The hooks are managed by Husky and will be installed automatically when you run `pnpm install`. +- **Framework**: Next.js 15, React 19, TypeScript +- **Auth and wallet**: Privy with GitHub OAuth and Solana wallet support +- **Database**: Prisma with PostgreSQL +- **GitHub integration**: Octokit, GitHub search APIs, issue metadata, pull request webhook handling +- **Styling**: Tailwind CSS 4 with custom UI components +- **Deployment target**: Vercel or any Node-compatible host that supports Next.js and PostgreSQL + +## Repository structure + +```text +src/app/page.tsx Landing page +src/app/dashboard/page.tsx Main bounty dashboard +src/app/api/bounties/route.ts List and create bounties +src/app/api/bounties/[id]/route.ts Update/delete individual bounties +src/app/api/bounties/submissions/route.ts Submit and list PR solutions +src/app/api/bounties/solved/route.ts Solved bounty lookups +src/app/api/github/* GitHub issue, search, webhook, and bot endpoints +src/components/dashboard/BountyCard.tsx Bounty display and PR submission UI +src/components/dashboard/IssueCard.tsx GitHub issue display and bounty creation UI +src/components/dashboard/WalletConnect.tsx Wallet status UI +src/lib/privy.ts Privy token verification and user sync +src/lib/github-webhook.ts GitHub webhook signature verification +prisma/schema.prisma User, bounty, submission, and bot models +``` -### Installation +## Local development -1. Clone the repository: +### Prerequisites -```bash -git clone https://github.com/yourusername/the-collaborator.git -cd the-collaborator -``` +- Node.js 18 or newer +- pnpm +- PostgreSQL database +- Privy app with GitHub OAuth enabled +- GitHub personal access token or OAuth token for repository and issue lookups -2. Install dependencies: +### Install dependencies ```bash pnpm install ``` -3. Set up environment variables: +`postinstall` runs `prisma generate`, and `prepare` installs Husky hooks. -```bash -cp .env.example .env.local -``` +### Configure environment variables -4. Configure your environment variables: +Create `.env.local` and set the values used by the app: ```env -# GitHub OAuth -GITHUB_ID=your_github_client_id -GITHUB_SECRET=your_github_client_secret +# Database +DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE" + +# Privy +NEXT_PUBLIC_PRIVY_APP_ID="your-privy-app-id" +PRIVY_APP_SECRET="your-privy-app-secret" + +# GitHub API fallback tokens +GITHUB_TOKEN="github_pat_or_classic_pat" +GITHUB_ACCESS_TOKEN="optional_alternate_github_token" +GITHUB_WEBHOOK_SECRET="optional_webhook_secret" + +# Public links used by the landing page +NEXT_PUBLIC_X_URL="https://x.com/collaborat0rs" +NEXT_PUBLIC_PRIVACY_URL="https://example.com/privacy" +NEXT_PUBLIC_TERMS_URL="https://example.com/terms" +``` + +Privy setup notes live in [`PRIVY_SETUP.md`](./PRIVY_SETUP.md). In the Privy dashboard, enable GitHub OAuth and turn on **Return OAuth tokens** so GitHub API calls can use the authenticated user's GitHub access token. -# NextAuth -NEXTAUTH_SECRET=your_nextauth_secret -NEXTAUTH_URL=http://localhost:3000 +### Prepare the database -# Solana -REACT_APP_MINT_AUTHORITY_SECRET_KEY=your_mint_authority_key +```bash +pnpm prisma generate +pnpm prisma migrate dev ``` -5. Run the development server: +### Run the app ```bash pnpm dev ``` -6. Open [http://localhost:3000](http://localhost:3000) in your browser - -## 🔧 Configuration - -### GitHub OAuth Setup +Open and sign in through the Privy modal. -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` +## GitHub webhook setup -### Solana Configuration +The webhook endpoint is: -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 +```text +POST /api/github/webhook +``` -### For Web3 Developers +Configure your GitHub app or repository webhook to send at least these events: -- **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 +- `ping` +- `issues` +- `pull_request` -### Trust & Security +If `GITHUB_WEBHOOK_SECRET` is set, the app verifies `x-hub-signature-256` before processing events. In development the route logs signature mismatches instead of hard-failing so local testing is easier. -- **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 +## Important data models -## 🎨 Design System +- `User`: Privy identity, GitHub username, wallet address, and relationships. +- `Bounty`: GitHub issue metadata, amount, status, poster, labels, and solved state. +- `BountySubmission`: contributor PR URL, PR number, status, and verification state. +- `BotInstallation`: repository-level bot installation tracking. -- **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 +## API overview -## 🔮 Coming Soon +### Public -- **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 +- `GET /api/bounties?status=ACTIVE&limit=50` — list bounties by status. -## 🤝 Contributing +### Authenticated with `Authorization: Bearer ` -We welcome contributions! Please see our contributing guidelines for details on: +- `POST /api/bounties` — create a bounty for a GitHub issue. +- `GET /api/bounties/my` — list bounties created by the current user. +- `PATCH /api/bounties/[id]` — update a bounty amount/status. +- `DELETE /api/bounties/[id]` — cancel/delete a bounty. +- `POST /api/bounties/submissions` — submit a PR URL for a bounty. +- `GET /api/bounties/submissions` — list the current user's submissions or a bounty's submissions. +- `GET /api/bounties/solved` — list solved bounties for the current user. +- `GET /api/github/user/issues` — fetch issues for the authenticated GitHub user. -- Code style and standards -- Testing requirements -- Pull request process -- Community guidelines +## Security and operations notes -## 📄 License +- Keep `PRIVY_APP_SECRET`, `DATABASE_URL`, GitHub tokens, and webhook secrets server-side only. +- Never expose GitHub access tokens to the client; use Privy access tokens for app authentication. +- Use GitHub webhook signatures in production. +- Store wallet addresses, not private keys. +- Confirm payout and settlement logic before handling high-value bounties. +- The archived token-claiming code references legacy mint-authority environment variables and should not be re-enabled without a fresh security review. -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +## Roadmap ideas -## 🆘 Support +- Fully automated GitHub label creation when a bounty is posted. +- On-chain escrow and settlement integration for funded bounties. +- Better submission ranking and review workflow for maintainers. +- Contributor reputation pages and public solved-bounty history. +- Notifications for PR submission, approval, rejection, and payout events. +- Public API access for external bounty aggregators and agent workflows. -- **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 +## Contributing -## 🌟 Acknowledgments +1. Fork the repository. +2. Create a focused branch. +3. Keep changes small and tied to a single issue. +4. Run the relevant checks before opening a PR. +5. Reference the issue in your PR description. -- Solana Foundation for blockchain infrastructure -- GitHub for developer platform integration -- Next.js team for the amazing framework -- Our community of contributors and testers +Example: ---- +```text +Closes #40 +``` -**Collaborators** - Building the future of developer collaboration and rewards. +## Support -_Transform your contributions. Build your reputation. Get rewarded._ +- Use GitHub Issues for bugs and feature requests. +- Review [`PRIVY_SETUP.md`](./PRIVY_SETUP.md) for authentication and wallet setup details. +- Check `MIGRATION_SUMMARY.md` for context on the dashboard migration from the legacy contribution tracker to the current bounty marketplace MVP.