Grainzy - Grant Execution Infrastructure

Automated, verifiable payments for open-source contributions

Grainzy is a comprehensive grant execution layer that converts ecosystem funding into automated, verifiable payments for open-source contributions. Built on Stellar Soroban, it ensures transparent, escrow-backed payouts based on real GitHub activity.

🎯 The Problem

Open-source ecosystems face critical challenges:

• ❌ Grant money managed off-chain with no transparency
• ❌ Manual distribution of rewards by maintainers
• ❌ Delayed or subjective contributor payments
• ❌ No verifiable proof of how grants convert to real work
• ❌ Contributors must trust platforms or maintainers for fair payouts

✨ Our Solution

Grainzy bridges ecosystems and contributors with an automated, on-chain execution layer:

• ✅ Escrow-first: Funds locked in smart contracts before work begins
• ✅ Automated payouts: Triggered by verified GitHub activity
• ✅ Transparent impact: Every payment is verifiable on-chain
• ✅ GitHub-native: Works with existing workflows
• ✅ Privacy-safe: KYC handled off-chain

🏗 Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Ecosystem     │────▶│ Program Escrow  │────▶│    Project      │
│  (Stellar)      │     │   (Contract)    │     │  Maintainer     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         │   Fund (XLM/tokens)   │   Allocate funds      │   Create issues
         │──────────────────────▶│──────────────────────▶│──────────────
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Grainzy Backend                              │
│  • GitHub webhook integration  • Scoring engine                │
│  • Off-chain verification       • KYC management               │
│  • Payout orchestration         • Auditing                     │
└─────────────────────────────────────────────────────────────────┘
                               │
                               │ Auto-trigger
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                Bounty Escrow (Contract)                         │
│            • Hold individual bounty funds                        │
│            • Enforce max claimants                               │
│            • Platform fee collection                             │
└─────────────────────────────────────────────────────────────────┘
                               │
                               │ Release
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Contributor Wallet                            │
└─────────────────────────────────────────────────────────────────┘

📁 Repository Structure

grainzy/
├── packages/
│   ├── contracts/          # Soroban smart contracts (Rust)
│   │   ├── src/
│   │   │   ├── lib.rs                 # Main exports
│   │   │   ├── grainzy_core.rs        # Upgradeable contract
│   │   │   ├── program_escrow.rs      # Program-level escrow
│   │   │   └── bounty_escrow.rs       # Individual bounty escrow
│   │   ├── manifests/                 # Machine-readable manifests
│   │   │   ├── grainlify-core-manifest.json
│   │   │   ├── program-escrow-manifest.json
│   │   │   └── bounty-escrow-manifest.json
│   │   ├── Cargo.toml
│   │   └── scripts/validate-manifests.sh
│   └── ui/                 # Shared UI components
├── apps/
│   ├── backend/           # Express.js + TypeScript API
│   │   ├── src/
│   │   │   ├── models/           # Database models (Prisma)
│   │   │   ├── routes/           # API endpoints
│   │   │   ├── services/         # Business logic
│   │   │   │   ├── github.ts     # GitHub webhook handler
│   │   │   │   ├── scoring.ts    # Points calculation
│   │   │   │   ├── kyc.ts        # KYC orchestration
│   │   │   │   └── payout.ts     # Payout execution
│   │   │   ├── middleware/
│   │   │   └── utils/
│   │   └── package.json
│   └── webapp/            # Next.js frontend
│       ├── src/
│       │   ├── app/              # App Router pages
│       │   ├── components/       # React components
│       │   │   ├── HeroSection.tsx
│       │   │   ├── ProgramList.tsx
│       │   │   ├── HowItWorks.tsx
│       │   │   └── Navbar.tsx
│       │   ├── lib/             # Utilities
│       │   └── types/           # TypeScript definitions
│       └── package.json
├── package.json
├── turbo.json            # Turborepo configuration
└── tsconfig.json

🚀 Quick Start

Prerequisites

• Node.js 18+
• Rust 1.75+ (for contracts)
• PostgreSQL 14+
• Stellar CLI (for deployment)

Install Dependencies

# Install all workspaces
npm install

# Or install individually
npm --workspace=@grainzy/backend install
npm --workspace=@grainzy/webapp install

Set Up Environment

# Backend
cd apps/backend
cp .env.example .env
# Fill in your values

Run Development Servers

# Start all services (requires Turborepo)
npm run dev

# Or individually:
npm --workspace=@grainzy/backend run dev   # Backend on :3001
npm --workspace=@grainzy/webapp run dev    # Frontend on :3000

Build Smart Contracts

cd packages/contracts
cargo build --target wasm32-unknown-unknown --release

Validate Contract Manifests

cd packages/contracts
./scripts/validate-manifests.sh

🔧 Core Contracts

1. GrainzyContract (Upgrade Manager)

• Time-delayed upgrades (default 24h)
• Multisig governance (configurable threshold)
• Immutable upgrade history
• WASM hash verification

2. ProgramEscrowContract (Hackathon/Grant Programs)

• Locks program funds in escrow
• Allocates to projects
• Processes contributor payouts
• Emergency pause functionality

3. BountyEscrowContract (Individual Issues)

• Per-bounty escrow
• Multi-token support
• Platform fee collection
• Claim approval workflow

🔐 Security Model

• No on-chain identities: Only wallet addresses stored
• Off-chain KYC: Compliance handled separately
• Circuit breakers: Pause contracts during incidents
• Reentrancy protection: All state changes before external calls
• Time-locked upgrades: Prevent rapid malicious updates

📊 Scoring Algorithm

Points awarded based on:

1. Base points (assigned by maintainer)
2. Complexity multiplier (PR size)
3. Reputation bonus (contributor history)
4. Capped maximum per PR

Formula: FinalPoints = min(Base × Complexity × Reputation, MAX_PER_PR)

🔗 GitHub Integration

Webhooks received for:

• Issues → Sync bounty point assignments
• Pull Requests → Link to issues, track status
• Reviews → Auto-approval logic
• Pushes → Trigger merge detection

🌐 Deployment

Smart Contracts (Soroban)

# Deploy upgrade contract first
stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/grainzy_contracts.wasm \
  --source <admin-keypair> \
  --network testnet

# Then deploy Program Escrow
# Then deploy Bounty Escrow

Backend (Heroku/Railway/DigitalOcean)

cd apps/backend
npm run build
npm start

Frontend (Vercel/Netlify)

cd apps/webapp
npm run build
# Deploy output folder

🧪 Testing

# Run backend tests
npm --workspace=@grainzy/backend run test

# Run contract tests
npm run contracts:test

# End-to-end simulation (TODO)
npm run test:e2e

📖 Documentation

• Architecture Guide - System design
• API Reference - Backend endpoints
• Contract Interface - Smart contract API
• Deployment Guide - Go-live checklist
• Contributing - Development workflow

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

Development Workflow

1. Fork the repository
2. Create feature branch: git checkout -b feat/my-feature
3. Commit changes: git commit -am 'Add feature'
4. Push branch: git push origin feat/my-feature
5. Open a Pull Request

📜 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Stellar Development Foundation - Soroban platform
• OnlyDust - Grant coordination inspiration
• Open Source Community - The reason we do this

📞 Contact

• Twitter: @grainzy
• Discord: Join our community
• Email: hello@grainzy.org

---

Built with ❤️ for open source maintainers and contributors worldwide.