From 48605932eae8c3384bf78904872807e8373eabe6 Mon Sep 17 00:00:00 2001 From: arturstar992-eng Date: Sat, 8 Aug 2026 19:35:08 +0300 Subject: [PATCH 1/2] docs: replace outdated README with MVP guide Document the current bounty workflow, Privy setup, environment variables, GitHub webhooks, API routes, security guidance, and contributor checks. --- README.md | 305 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 177 insertions(+), 128 deletions(-) diff --git a/README.md b/README.md index cab48cc..2f0d84b 100644 --- a/README.md +++ b/README.md @@ -1,180 +1,229 @@ -# 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 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. -## 🚀 What We've Built +> **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. -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. +## How it works -## ✨ Key Features - -- **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 +```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"] +``` -## 🎯 How It Works +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 -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 +### Prerequisites -## 🛠️ Technical Stack +- 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 -- **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. Clone and install -## 🚀 Getting Started +```bash +git clone https://github.com/andr-drgm/collaborators.git +cd collaborators +pnpm install +``` -### Prerequisites +### 2. Configure Privy -- Node.js 18+ and pnpm -- Solana wallet (Phantom, Solflare, etc.) -- GitHub account -- Some SOL for transaction fees +In the [Privy dashboard](https://dashboard.privy.io/): -### Development Setup +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. -This project uses Git hooks to ensure code quality. When you clone the repository, the following will be automatically set up: +Privy's GitHub callback URL is: -- **Pre-commit hooks**: Automatically runs `pnpm lint` before each commit -- **Code formatting**: Ensures consistent code style across the project +```text +https://auth.privy.io/api/v1/oauth/github/callback +``` -The hooks are managed by Husky and will be installed automatically when you run `pnpm install`. +### 3. Add environment variables -### Installation +Create `.env.local` in the project root: -1. Clone the repository: +```dotenv +# PostgreSQL +DATABASE_URL="postgresql://postgres:postgres@localhost:5432/collaborators" -```bash -git clone https://github.com/yourusername/the-collaborator.git -cd the-collaborator -``` +# Privy +NEXT_PUBLIC_PRIVY_APP_ID="your-privy-app-id" +PRIVY_APP_SECRET="your-privy-app-secret" -2. Install dependencies: +# GitHub API access +GITHUB_TOKEN="your-github-token" -```bash -pnpm install +# Use the same value in the GitHub repository webhook settings +GITHUB_WEBHOOK_SECRET="replace-with-a-long-random-secret" ``` -3. Set up environment variables: +Optional configuration: -```bash -cp .env.example .env.local -``` +```dotenv +# Fallback token used by the personal-issues endpoint +GITHUB_ACCESS_TOKEN="your-github-token" -4. Configure your environment variables: +# 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" +``` -```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 - -- **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 +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 installation for the GitHub user who added the webhook | +| `issues` | Updates a matching bounty when its issue changes state | +| `pull_request` | Approves a pending submission and solves its bounty when the 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 +``` -### Trust & Security +## Main API routes -- **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 +| 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 pull request for an active bounty | +| `GET /api/github/search/issues` | Search public GitHub issues | +| `GET /api/github/user/issues` | List issues created by the signed-in GitHub user | +| `POST /api/github/webhook` | Process repository webhook events | +| `GET /api/user/me` | Verify the Privy token and sync the local user record | -## 🎨 Design System +Authenticated routes expect a Privy access token: -- **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 +```http +Authorization: Bearer +``` -## 🔮 Coming Soon +## Development checks -- **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 +Run a type check and lint the source before opening a pull request: -## 🤝 Contributing +```bash +pnpm exec tsc --noEmit +pnpm exec eslint . +``` -We welcome contributions! Please see our contributing guidelines for details on: +To verify a production build, provide the required environment variables and a reachable PostgreSQL database, then run: -- Code style and standards -- Testing requirements -- Pull request process -- Community guidelines +```bash +pnpm build +``` -## 📄 License +## Security notes -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +- 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. -## 🆘 Support +## Contributing -- **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 +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. -## 🌟 Acknowledgments +Bug reports and feature proposals are welcome in [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. From 66477ed8d46155e5e2586c1b446ed1dd3b808329 Mon Sep 17 00:00:00 2001 From: arturstar992-eng Date: Sat, 8 Aug 2026 20:15:54 +0300 Subject: [PATCH 2/2] docs: make README pass markdownlint Wrap long prose and shorten table cells without changing the documented behavior. --- README.md | 72 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 48 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 2f0d84b..4bf379c 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,13 @@ # 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. +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. +> **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 @@ -15,11 +20,15 @@ flowchart LR E --> F["Submission is approved and bounty is solved"] ``` -1. Sign in with GitHub. Privy handles authentication and creates an embedded Solana wallet for users who do not already have one. +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. +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 @@ -30,7 +39,8 @@ flowchart LR - 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 +- Separate views for active bounties, solved bounties, personal issues, and + bounties you posted - Responsive dark interface built with Tailwind CSS ## Technology @@ -68,7 +78,8 @@ pnpm install In the [Privy dashboard](https://dashboard.privy.io/): 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. +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. @@ -109,7 +120,8 @@ NEXT_PUBLIC_PRIVACY_URL="https://example.com/privacy" NEXT_PUBLIC_TERMS_URL="https://example.com/terms" ``` -Keep server secrets out of variables prefixed with `NEXT_PUBLIC_`, and never commit `.env.local`. +Keep server secrets out of variables prefixed with `NEXT_PUBLIC_`, and never +commit `.env.local`. ### 4. Prepare the database @@ -141,11 +153,12 @@ The endpoint handles these events: | Event | Result | | --- | --- | -| `ping` | Registers the repository installation for the GitHub user who added the webhook | +| `ping` | Registers the repository for the GitHub user | | `issues` | Updates a matching bounty when its issue changes state | -| `pull_request` | Approves a pending submission and solves its bounty when the submitted PR is merged | +| `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. +For local webhook testing, expose port `3000` through an HTTPS tunnel and use +the tunnel URL as the payload URL. ## Project structure @@ -175,9 +188,9 @@ src/ | `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 pull request for an active bounty | +| `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 issues created by the signed-in GitHub user | +| `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 | @@ -196,7 +209,8 @@ pnpm exec tsc --noEmit pnpm exec eslint . ``` -To verify a production build, provide the required environment variables and a reachable PostgreSQL database, then run: +To verify a production build, provide the required environment variables and a +reachable PostgreSQL database, then run: ```bash pnpm build @@ -204,26 +218,36 @@ pnpm build ## Security notes -- 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. +- 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. +- 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. ## Contributing 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. +4. Open a pull request that explains the behavior change and how it was + verified. -Bug reports and feature proposals are welcome in [GitHub Issues](https://github.com/andr-drgm/collaborators/issues). +Bug reports and feature proposals are welcome in [GitHub Issues]. + +[GitHub Issues]: https://github.com/andr-drgm/collaborators/issues ## 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. +- [`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. ## License -No license file is currently included in this repository. Until the maintainers add one, normal copyright rules apply. +No license file is currently included in this repository. Until the maintainers +add one, normal copyright rules apply.