diff --git a/README.md b/README.md index cab48cc..d06fad5 100644 --- a/README.md +++ b/README.md @@ -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:///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).