diff --git a/README.md b/README.md index cab48cc..4bf379c 100644 --- a/README.md +++ b/README.md @@ -1,180 +1,253 @@ -# Collaborator - -Transform your GitHub work into on-chain rewards and reputation. Earn NFT badges and SOL tokens for your real contributions on GitHub. - -## 🚀 What We've Built - -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. +# Collaborators + +Collaborators is a GitHub bounty marketplace for funding open-source work and +rewarding accepted pull requests in USDC. Maintainers attach bounties to GitHub +issues, contributors submit a pull request as their solution, and repository +webhooks keep the bounty status in sync when the work is merged. + +> **Project status:** this repository contains the bounty-focused MVP. Parts of +> the original contribution-tracking product remain under `archive/` +> directories, but they are not part of the active dashboard. + +## How it works + +```mermaid +flowchart LR + A["Maintainer selects a GitHub issue"] --> B["Creates a USDC bounty"] + B --> C["Contributor opens a pull request"] + C --> D["Contributor submits the PR URL"] + D --> E["Repository webhook observes the merge"] + E --> F["Submission is approved and bounty is solved"] +``` -## ✨ Key Features +1. Sign in with GitHub. Privy handles authentication and creates an embedded + Solana wallet for users who do not already have one. +2. Search public GitHub issues or browse the issues you created. +3. Add a USDC-denominated bounty to an issue and configure the repository + webhook. +4. A contributor solves the issue and submits the pull request URL from the + bounty card. +5. When GitHub reports that the pull request was merged, Collaborators approves + the matching submission and marks the bounty as solved. + +## Features + +- GitHub OAuth through Privy +- Embedded Solana wallet creation on first login +- Public GitHub issue search and personal issue discovery +- USDC-denominated bounty creation, editing, filtering, and deletion +- Pull request solution submissions +- GitHub webhook tracking for issues and pull requests +- Automatic submission verification after a matching pull request is merged +- Separate views for active bounties, solved bounties, personal issues, and + bounties you posted +- Responsive dark interface built with Tailwind CSS + +## Technology + +| Area | Implementation | +| --- | --- | +| Web application | Next.js 15 App Router, React 19, TypeScript | +| Styling | Tailwind CSS 4 | +| Authentication | Privy with GitHub OAuth | +| Wallets | Privy embedded Solana wallets, Solana Web3.js | +| GitHub integration | Octokit and GitHub webhooks | +| Data | PostgreSQL with Prisma 6 | +| Deployment | Vercel configuration included | + +## Local development -- **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 +### Prerequisites -## 🎯 How It Works +- Node.js 20 or newer +- pnpm +- PostgreSQL +- A Privy application with GitHub login and Solana embedded wallets enabled +- A GitHub token for issue search and label operations -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. Clone and install -## 🛠️ Technical Stack +```bash +git clone https://github.com/andr-drgm/collaborators.git +cd collaborators +pnpm install +``` -- **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 +### 2. Configure Privy -## 🚀 Getting Started +In the [Privy dashboard](https://dashboard.privy.io/): -### Prerequisites +1. Enable GitHub as a login method. +2. Enable **Return OAuth tokens** for GitHub. The personal-issues view needs the + returned token to call the GitHub API for the signed-in user. +3. Enable Solana embedded wallets and create them for users without wallets. +4. Add `http://localhost:3000` to the allowed application domains. -- Node.js 18+ and pnpm -- Solana wallet (Phantom, Solflare, etc.) -- GitHub account -- Some SOL for transaction fees +Privy's GitHub callback URL is: -### Development Setup +```text +https://auth.privy.io/api/v1/oauth/github/callback +``` -This project uses Git hooks to ensure code quality. When you clone the repository, the following will be automatically set up: +### 3. Add environment variables -- **Pre-commit hooks**: Automatically runs `pnpm lint` before each commit -- **Code formatting**: Ensures consistent code style across the project +Create `.env.local` in the project root: -The hooks are managed by Husky and will be installed automatically when you run `pnpm install`. +```dotenv +# PostgreSQL +DATABASE_URL="postgresql://postgres:postgres@localhost:5432/collaborators" -### Installation +# Privy +NEXT_PUBLIC_PRIVY_APP_ID="your-privy-app-id" +PRIVY_APP_SECRET="your-privy-app-secret" -1. Clone the repository: +# GitHub API access +GITHUB_TOKEN="your-github-token" -```bash -git clone https://github.com/yourusername/the-collaborator.git -cd the-collaborator +# Use the same value in the GitHub repository webhook settings +GITHUB_WEBHOOK_SECRET="replace-with-a-long-random-secret" ``` -2. Install dependencies: - -```bash -pnpm install -``` +Optional configuration: -3. Set up environment variables: +```dotenv +# Fallback token used by the personal-issues endpoint +GITHUB_ACCESS_TOKEN="your-github-token" -```bash -cp .env.example .env.local +# 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" ``` -4. Configure your environment variables: - -```env -# GitHub OAuth -GITHUB_ID=your_github_client_id -GITHUB_SECRET=your_github_client_secret +Keep server secrets out of variables prefixed with `NEXT_PUBLIC_`, and never +commit `.env.local`. -# NextAuth -NEXTAUTH_SECRET=your_nextauth_secret -NEXTAUTH_URL=http://localhost:3000 +### 4. Prepare the database -# Solana -REACT_APP_MINT_AUTHORITY_SECRET_KEY=your_mint_authority_key +```bash +pnpm prisma generate +pnpm prisma db push ``` -5. Run the development server: +### 5. Start the app ```bash pnpm dev ``` -6. Open [http://localhost:3000](http://localhost:3000) in your browser - -## 🔧 Configuration - -### 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 +Open [http://localhost:3000](http://localhost:3000). + +## GitHub webhook setup + +Each repository that uses bounty automation needs a webhook: + +1. Open the repository's **Settings → Webhooks → Add webhook** page. +2. Set **Payload URL** to `https://your-domain.example/api/github/webhook`. +3. Choose `application/json` as the content type. +4. Enter the same secret as `GITHUB_WEBHOOK_SECRET`. +5. Select individual events and enable **Issues** and **Pull requests**. +6. Keep the webhook active and add it. + +The endpoint handles these events: + +| Event | Result | +| --- | --- | +| `ping` | Registers the repository for the GitHub user | +| `issues` | Updates a matching bounty when its issue changes state | +| `pull_request` | Solves a bounty when its submitted PR is merged | + +For local webhook testing, expose port `3000` through an HTTPS tunnel and use +the tunnel URL as the payload URL. + +## Project structure + +```text +prisma/ +├── schema.prisma # PostgreSQL data model +└── migrations/ # Database changes +src/ +├── app/ +│ ├── api/ +│ │ ├── bounties/ # Bounty CRUD and submissions +│ │ ├── github/ # Issue search, labels, and webhooks +│ │ └── user/ # Authenticated user sync +│ ├── dashboard/ # Marketplace dashboard +│ └── PrivyProviders.tsx # Privy and embedded-wallet config +├── components/ # Landing page and dashboard UI +├── hooks/usePrivyAuth.ts # Client authentication state +├── lib/ # Privy and webhook helpers +└── services/github.ts # Client-side GitHub API helpers +``` -- **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 +## Main API routes -### Trust & Security +| Route | Purpose | +| --- | --- | +| `GET /api/bounties` | List and filter bounties | +| `POST /api/bounties` | Create a bounty for a GitHub issue | +| `PATCH /api/bounties/:id` | Update a bounty you posted | +| `DELETE /api/bounties/:id` | Delete a bounty you posted | +| `POST /api/bounties/submissions` | Submit a PR for an active bounty | +| `GET /api/github/search/issues` | Search public GitHub issues | +| `GET /api/github/user/issues` | List the signed-in user's issues | +| `POST /api/github/webhook` | Process repository webhook events | +| `GET /api/user/me` | Verify the Privy token and sync the local user record | -- **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 +Authenticated routes expect a Privy access token: -## 🎨 Design System +```http +Authorization: Bearer +``` -- **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 +## Development checks -## 🔮 Coming Soon +Run a type check and lint the source before opening a pull request: -- **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 exec tsc --noEmit +pnpm exec eslint . +``` -## 🤝 Contributing +To verify a production build, provide the required environment variables and a +reachable PostgreSQL database, then run: -We welcome contributions! Please see our contributing guidelines for details on: +```bash +pnpm build +``` -- Code style and standards -- Testing requirements -- Pull request process -- Community guidelines +## Security notes -## 📄 License +- Give GitHub tokens only the permissions required by the repositories and + operations you use. +- Store `PRIVY_APP_SECRET`, GitHub tokens, database credentials, and the webhook + secret only in server-side secret storage. +- Always configure a unique webhook secret for production deployments. +- Review OAuth permissions before authorizing the application, especially when + private repositories are accessible to the selected GitHub account. +- Do not put wallet private keys or mint authority secrets in client-exposed + environment variables. -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +## Contributing -## 🆘 Support +1. Fork the repository and create a focused branch. +2. Keep changes scoped and document any new environment variables or migrations. +3. Run the development checks above. +4. Open a pull request that explains the behavior change and how it was + verified. -- **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 +Bug reports and feature proposals are welcome in [GitHub Issues]. -## 🌟 Acknowledgments +[GitHub Issues]: https://github.com/andr-drgm/collaborators/issues -- Solana Foundation for blockchain infrastructure -- GitHub for developer platform integration -- Next.js team for the amazing framework -- Our community of contributors and testers +## Additional documentation ---- +- [`PRIVY_SETUP.md`](PRIVY_SETUP.md) explains the authentication and + embedded-wallet configuration in more detail. +- [`MIGRATION_SUMMARY.md`](MIGRATION_SUMMARY.md) describes the shift from + contribution tracking to the current bounty marketplace MVP. -**Collaborators** - Building the future of developer collaboration and rewards. +## License -_Transform your contributions. Build your reputation. Get rewarded._ +No license file is currently included in this repository. Until the maintainers +add one, normal copyright rules apply.