From 37fb12ae4f3632bf76a0322b96936ccf0f6b940e Mon Sep 17 00:00:00 2001 From: Nico Vale Date: Wed, 13 May 2026 15:33:30 +0000 Subject: [PATCH] docs: improve README for bounty workflow --- README.md | 294 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 185 insertions(+), 109 deletions(-) diff --git a/README.md b/README.md index cab48cc..8b83003 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,103 @@ -# 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 for open-source work. Project owners attach USDC rewards to public GitHub issues, contributors submit pull requests, and rewards are released when the linked PR is merged and verified. -## 🚀 What We've Built +The app combines GitHub issue discovery, Privy authentication, Solana wallet support, and bounty/submission tracking in a Next.js dashboard. -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 you can do -## ✨ Key Features +### For contributors -- **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 +- Browse open GitHub issues with active USDC rewards. +- Connect with GitHub through Privy authentication. +- Link a Solana wallet for reward payouts. +- Submit a pull request URL as proof of work. +- Track pending, verified, and solved bounty submissions. -## 🎯 How It Works +### For bounty posters -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 +- Add funded rewards to public GitHub issues. +- Monitor submitted PRs from contributors. +- Use GitHub bot installation status to support verification flows. +- Keep bounty status and solver history in one dashboard. -## 🛠️ Technical Stack +## How it works -- **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 +```mermaid +flowchart LR + A[Poster selects a GitHub issue] --> B[Poster creates a USDC bounty] + B --> C[Contributor finds the bounty] + C --> D[Contributor opens a pull request] + D --> E[Contributor submits the PR URL] + E --> F[Bot / reviewer verifies merge] + F --> G[Reward is released to contributor wallet] +``` -## 🚀 Getting Started +1. **Authenticate** — users sign in with GitHub through Privy. +2. **Discover or create bounties** — the dashboard lists bounty-backed GitHub issues and user-owned issues. +3. **Build the fix** — contributors work directly in GitHub using the normal fork/branch/PR workflow. +4. **Submit proof** — contributors paste the merged or review-ready PR URL into Collaborators. +5. **Verify and pay** — the platform tracks PR status and releases the bounty when the solution is accepted. + +## Tech stack + +| Area | Technology | +| --- | --- | +| Framework | Next.js 15, React 19, TypeScript | +| Auth | Privy with GitHub login | +| Wallets | Privy embedded Solana wallets + external wallet support | +| Database | Prisma + PostgreSQL | +| GitHub integration | Octokit / GitHub APIs | +| Styling | Tailwind CSS | +| Deployment | Vercel-ready | + +## Repository structure + +```text +. +├── prisma/ # Prisma schema and database models +├── public/ # Static assets and app icons +├── src/app/ # Next.js app routes and API handlers +├── src/components/ # Reusable UI and dashboard components +├── src/hooks/ # Privy/auth helper hooks +├── src/services/ # GitHub and app service helpers +├── src/utils/ # Shared constants and utility functions +└── package.json # Scripts and dependencies +``` -### Prerequisites +## Prerequisites -- Node.js 18+ and pnpm -- Solana wallet (Phantom, Solflare, etc.) -- GitHub account -- Some SOL for transaction fees +- Node.js 18+ +- pnpm +- PostgreSQL database +- Privy app ID / credentials +- GitHub OAuth app credentials +- Solana wallet configuration for payouts -### Development Setup +## Environment variables -This project uses Git hooks to ensure code quality. When you clone the repository, the following will be automatically set up: +Create `.env.local` from your local secret store or deployment environment. -- **Pre-commit hooks**: Automatically runs `pnpm lint` before each commit -- **Code formatting**: Ensures consistent code style across the project +| Variable | Required | Purpose | +| --- | --- | --- | +| `NEXT_PUBLIC_PRIVY_APP_ID` | Yes | Privy client app ID used by the frontend provider. | +| `PRIVY_APP_SECRET` | Yes | Server-side Privy verification secret, if used by API routes. | +| `DATABASE_URL` | Yes | PostgreSQL connection string for Prisma. | +| `GITHUB_ID` | Yes | GitHub OAuth app client ID. | +| `GITHUB_SECRET` | Yes | GitHub OAuth app client secret. | +| `NEXTAUTH_SECRET` | If using NextAuth routes | Secret for auth session signing. | +| `NEXTAUTH_URL` | If using NextAuth routes | Local or deployed application URL. | +| `REACT_APP_MINT_AUTHORITY_SECRET_KEY` | If minting/reward flows require it | Solana mint authority key for token operations. | -The hooks are managed by Husky and will be installed automatically when you run `pnpm install`. +> Never commit `.env.local`, private keys, OAuth secrets, or wallet seed material. -### Installation +## Local development 1. Clone the repository: ```bash -git clone https://github.com/yourusername/the-collaborator.git -cd the-collaborator +git clone https://github.com/andr-drgm/collaborators.git +cd collaborators ``` 2. Install dependencies: @@ -64,117 +106,151 @@ cd the-collaborator pnpm install ``` -3. Set up environment variables: +3. Configure environment variables: ```bash -cp .env.example .env.local +touch .env.local +# then fill in the required values from the table above ``` -4. Configure your environment variables: +4. Generate Prisma client: -```env -# GitHub OAuth -GITHUB_ID=your_github_client_id -GITHUB_SECRET=your_github_client_secret +```bash +pnpm prisma generate +``` -# NextAuth -NEXTAUTH_SECRET=your_nextauth_secret -NEXTAUTH_URL=http://localhost:3000 +5. Run database migrations or sync your schema, depending on your environment: -# Solana -REACT_APP_MINT_AUTHORITY_SECRET_KEY=your_mint_authority_key +```bash +pnpm prisma migrate dev +# or: pnpm prisma db push ``` -5. Run the development server: +6. Start the development server: ```bash pnpm dev ``` -6. Open [http://localhost:3000](http://localhost:3000) in your browser +7. Open [http://localhost:3000](http://localhost:3000). + +## Useful scripts + +| Command | Description | +| --- | --- | +| `pnpm dev` | Start the local Next.js development server. | +| `pnpm build` | Generate Prisma client and create a production build. | +| `pnpm start` | Start the production server after building. | +| `pnpm lint` | Run the configured lint command. | +| `pnpm postinstall` | Generate Prisma client after install. | +| `pnpm prepare` | Install Husky git hooks. | + +## GitHub OAuth setup + +1. Open GitHub Developer Settings. +2. Create a new OAuth App. +3. For local development, set the callback URL to: + +```text +http://localhost:3000/api/auth/callback/github +``` + +4. For production, set the callback URL to your deployed domain. +5. Copy the client ID and client secret into your environment variables. + +## Privy setup -## 🔧 Configuration +1. Create a Privy app. +2. Enable GitHub as a login method. +3. Configure Solana embedded wallets if you want wallet creation on login. +4. Add your local and production domains to the allowed app URLs. +5. Set `NEXT_PUBLIC_PRIVY_APP_ID` and any server-side Privy secrets in your environment. -### GitHub OAuth Setup +## Solana configuration -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` +The app is configured for Solana wallet support through Privy. Review `src/app/PrivyProviders.tsx` before changing network behavior. -### Solana Configuration +Current provider defaults include: -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 +- Solana Mainnet +- Solana Devnet +- Devnet as the default chain for development flows -## 📱 User Experience Improvements +Use devnet while testing wallet and payout flows. Switch to mainnet only after confirming reward funding, verification, and payout behavior end to end. -### For Newcomers +## Contributor workflow -- **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. Pick an active bounty from the dashboard. +2. Open the linked GitHub issue. +3. Fork the target repository and create a focused branch. +4. Implement the fix with tests or documentation updates where appropriate. +5. Open a pull request that references the issue. +6. Submit the PR URL in Collaborators. +7. Track the submission status from the dashboard. -### For Web3 Developers +## Bounty poster workflow -- **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 +1. Sign in with GitHub. +2. Choose one of your public GitHub issues. +3. Create a bounty with the reward amount and description. +4. Install or verify the GitHub bot where required. +5. Review submitted pull requests. +6. Accept the solution and complete reward release once the PR is merged. -### Trust & Security +## Deployment checklist -- **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 +Before deploying to production: -## 🎨 Design System +- [ ] Production database is provisioned and migrated. +- [ ] Privy production app URL is configured. +- [ ] GitHub OAuth production callback URL is configured. +- [ ] Solana network and wallet settings are reviewed. +- [ ] Secret variables are set in the hosting provider. +- [ ] `pnpm build` passes. +- [ ] Bounty creation, PR submission, verification, and payout flows are tested on devnet or a staging environment. -- **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 +## Troubleshooting -## 🔮 Coming Soon +### GitHub login fails -- **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 +- Check `GITHUB_ID` and `GITHUB_SECRET`. +- Confirm the callback URL exactly matches the app URL. +- Verify the GitHub OAuth app is not restricted to the wrong domain. -## 🤝 Contributing +### Wallet is not created or connected -We welcome contributions! Please see our contributing guidelines for details on: +- Confirm the Privy app ID is correct. +- Check that Solana embedded wallets are enabled in Privy. +- Reload the session after changing Privy settings. -- Code style and standards -- Testing requirements -- Pull request process -- Community guidelines +### Prisma client errors -## 📄 License +- Run `pnpm prisma generate`. +- Confirm `DATABASE_URL` is set. +- Apply migrations or run `pnpm prisma db push` for local development. -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +### Build fails after dependency changes -## 🆘 Support +- Delete `node_modules` and reinstall with `pnpm install`. +- Confirm your Node.js version is 18 or newer. +- Re-run `pnpm prisma generate` before building. -- **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 +## Security notes -## 🌟 Acknowledgments +- Do not commit OAuth secrets, wallet private keys, or database credentials. +- Use devnet for payout testing until the full reward flow is verified. +- Keep reward-release logic server-side and validate all submitted PR URLs. +- Treat GitHub webhook payloads and client-submitted PR URLs as untrusted input. +- Log verification decisions enough to debug payouts without exposing secrets. -- Solana Foundation for blockchain infrastructure -- GitHub for developer platform integration -- Next.js team for the amazing framework -- Our community of contributors and testers +## Roadmap ideas ---- +- Automated PR merge verification through GitHub webhooks. +- Richer bounty filters by language, reward size, and repository. +- Contributor reputation pages. +- Bounty escrow status and payout history. +- Team and organization dashboards. -**Collaborators** - Building the future of developer collaboration and rewards. +## License -_Transform your contributions. Build your reputation. Get rewarded._ +This project is licensed under the MIT License. See the repository license file for details.