ROSCA-Guard 🛡️

Privacy-preserving identity verification for decentralized Rotating Savings and Credit Associations (ROSCAs) powered by Self Protocol and PYUSD.

🌟 Overview

ROSCA-Guard revolutionizes traditional rotating savings circles by combining blockchain technology with zero-knowledge identity verification. Built for the Self Protocol hackathon, this platform enables verified users to participate in automated savings circles while maintaining complete privacy.

Key Features

🔐 Zero-Knowledge KYC: Identity verification using Self Protocol (Passport & Aadhaar support)
💰 PYUSD Integration: Stablecoin-based automated payments and payouts
⛓️ Cross-Chain Architecture: KYC on Celo, ROSCA operations on Ethereum
📊 Smart Contract Automation: No manual coordination required
🎯 Reputation System: Merit-based payout selection
📈 DeFi Yield: Earn additional returns on pooled funds
🌍 Global Access: Support for region-specific and international circles

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    Frontend (React)                      │
│  - RainbowKit Wallet Connection                         │
│  - Self Protocol QR Code Integration                    │
│  - ROSCA Circle Management UI                           │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│              Backend (Express.js + TypeScript)           │
│  - Self Protocol Backend Verifier                       │
│  - Cross-Chain Bridge Service                           │
│  - API Gateway                                          │
└──────┬─────────────────────────────┬────────────────────┘
       │                             │
       ▼                             ▼
┌─────────────────┐          ┌─────────────────┐
│   Celo Testnet  │          │ Ethereum Sepolia│
│                 │          │                 │
│  KYC Verifier   │          │  ROSCA Factory  │
│  (Self Protocol)│          │  ROSCA Circles  │
│                 │          │  PYUSD Token    │
└─────────────────┘          └─────────────────┘

🚀 Quick Start

Prerequisites

Node.js >= 18.0.0
npm >= 8.0.0
MetaMask or compatible Web3 wallet
Self Protocol mobile app (iOS / Android)

Installation

Clone the repository

git clone https://github.com/anumukul/ROSCA-Guard.git
cd ROSCA-Guard

Install Backend Dependencies

cd backend
npm install

Configure Backend Environment

cp .env.example .env

Edit .env with your configuration:

NODE_ENV=development
PORT=3001

# Blockchain RPCs
CELO_RPC_URL=https://alfajores-forno.celo-testnet.org
ETHEREUM_RPC_URL=https://sepolia.infura.io/v3/YOUR_INFURA_KEY

# Contract Addresses
KYC_VERIFIER_ADDRESS=0xAE8d27497451A252815B86898CDAd029be1417e9
ROSCA_FACTORY_ADDRESS=0x9F01d0beE74AC0aF15a390cF5bd54E28EF4BbBac

# Self Protocol
SELF_CONFIG_ID=0x766466f264a44af31cd388cd05801bcc5dfff4980ee97503579db8b3d0742a7e

# Frontend URL
FRONTEND_URL=http://localhost:3000

Start Backend

npm run dev

Install Frontend Dependencies

cd ../frontend
npm install --legacy-peer-deps

Configure Frontend Environment

cp .env.example .env

Edit .env:

VITE_API_URL=http://localhost:3001
VITE_SELF_CONFIG_ID=0x766466f264a44af31cd388cd05801bcc5dfff4980ee97503579db8b3d0742a7e

Start Frontend

npm run dev

Visit http://localhost:3000 🎉

📱 Usage

For Users

Verify Identity
- Connect your Web3 wallet
- Choose verification method (Passport or Aadhaar)
- Scan QR code with Self Protocol app
- Complete zero-knowledge verification
Create or Join ROSCA Circle
- Browse available circles or create new one
- Set monthly contribution amount in PYUSD
- Define circle parameters (size, duration, eligibility)
Participate in Circles
- Make monthly PYUSD contributions automatically
- Receive payouts when it's your turn
- Earn yield on pooled funds
- Build reputation through consistent participation

For Developers

Deploy Smart Contracts

cd contracts

# Install dependencies
npm install
forge install

# Configure deployment
cp .env.example .env
# Edit .env with your private key and RPC URLs

# Deploy KYC Verifier on Celo
forge script script/DeployKYC.s.sol --rpc-url $CELO_RPC_URL --broadcast --verify

# Deploy ROSCA Factory on Ethereum
forge script script/DeployFactory.s.sol --rpc-url $ETHEREUM_RPC_URL --broadcast --verify

Run Tests

# Backend tests
cd backend
npm test

# Smart contract tests
cd contracts
forge test

# Frontend tests
cd frontend
npm test

🔧 Technology Stack

Frontend

Framework: React 18 + TypeScript
Build Tool: Vite
Styling: Tailwind CSS
Web3: RainbowKit + wagmi + viem
Identity: Self Protocol SDK (@selfxyz/core, @selfxyz/qrcode)
State Management: React Query
Routing: React Router v6

Backend

Runtime: Node.js + Express.js
Language: TypeScript
Identity Verification: Self Protocol Backend Verifier
Blockchain Interaction: ethers.js v5
Security: Helmet, CORS, Rate Limiting
Validation: express-validator

Smart Contracts

Language: Solidity 0.8.28
Framework: Foundry
Identity: Self Protocol Verification Root
Standards: ERC-20 (PYUSD), Custom ROSCA logic
Networks: Celo (KYC), Ethereum (ROSCAs)

DevOps

Backend Hosting: Render
Frontend Hosting: Vercel
Version Control: Git + GitHub
CI/CD: GitHub Actions (optional)

📊 Smart Contracts

Deployed Contracts

Celo Alfajores Testnet

KYC Verifier: 0xAE8d27497451A252815B86898CDAd029be1417e9
Network: Celo Alfajores
Explorer: View on CeloScan

Ethereum Sepolia Testnet

ROSCA Factory: 0x9F01d0beE74AC0aF15a390cF5bd54E28EF4BbBac
ROSCA Analytics: 0x45Fdf95185922b91627F0B340AFA3DF0fED650E7
Mock PYUSD: 0x1e4e7e50E176A66BBEFC61331898F5ffdE49DBd6
Network: Ethereum Sepolia
Explorer: View on Etherscan

Key Contracts

KYCVerifier.sol

Extends Self Protocol's SelfVerificationRoot for on-chain identity verification.

function isEligibleForROSCA(
    address user,
    string memory requiredCountry,
    uint256 circleMinAge,
    uint256 circleMaxAge
) external view returns (bool eligible, string memory reason);

ROSCAFactory.sol

Factory pattern for creating and managing ROSCA circles.

function createCircle(
    uint256 monthlyAmount,
    uint256 maxMembers,
    uint256 duration,
    string memory country,
    uint256 minAge,
    uint256 maxAge
) external returns (uint256 circleId);

ROSCACircle.sol

Individual ROSCA circle with automated payment cycles and reputation tracking.

function joinCircle() external onlyKYCVerified;
function makeContribution() external onlyMember;
function distributePayout() external onlyOwner;

🔐 Self Protocol Integration

Backend Verification

import { SelfBackendVerifier, AllIds, DefaultConfigStore } from "@selfxyz/core";

const verifier = new SelfBackendVerifier(
  "rosca-guard-v1",
  "https://rosca-guard.onrender.com/api/self/verify-self",
  false, // production mode
  AllIds,
  new DefaultConfigStore({
    minimumAge: 18,
    excludedCountries: [],
    ofac: true,
  }),
  "uuid"
);

const result = await verifier.verify(
  attestationId,
  proof,
  publicSignals,
  userContextData
);

Contract Verification

contract KYCVerifier is SelfVerificationRoot {
    function customVerificationHook(
        ISelfVerificationRoot.GenericDiscloseOutputV2 memory output,
        bytes memory userData
    ) internal override {
        // Store verified user data on-chain
        verifiedUsers[userAddress] = VerifiedUser({
            nationality: output.nationality,
            age: calculatedAge,
            verificationTimestamp: block.timestamp,
            isVerified: true
        });
    }
}

🌐 API Documentation

Base URL

Production: https://rosca-guard.onrender.com
Development: http://localhost:3001

Endpoints

Health Check

GET /health

Verify Identity (Self Protocol)

POST /api/self/verify-self
Content-Type: application/json

{
  "attestationId": "1",
  "proof": {...},
  "publicSignals": {...},
  "userContextData": "..."
}

Get KYC Status

GET /api/self/kyc-status/:address

Check ROSCA Eligibility

POST /api/self/check-eligibility
Content-Type: application/json

{
  "userAddress": "0x...",
  "circleId": 1
}

Get Platform Statistics

GET /api/bridge/stats

Create ROSCA Circle

POST /api/bridge/create-circle
Content-Type: application/json

{
  "monthlyAmount": 100,
  "maxMembers": 5,
  "duration": 12,
  "country": "IN",
  "minAge": 18,
  "maxAge": 65
}

For complete API documentation, see API.md

🧪 Testing

Get Testnet Tokens

Celo Alfajores (for KYC transactions)

Faucet: https://faucet.celo.org/celo-sepolia
Request: 0.5 CELO per day

Ethereum Sepolia (for ROSCA operations)

Faucet: https://sepoliafaucet.com
Request: 0.5 ETH per day

Mock PYUSD

Use the faucet function in the deployed contract
Or call faucet(amount) to mint test tokens

Test Self Protocol Verification

Install Self Protocol app on your mobile device
Set up test passport in the app (staging mode)
Run the frontend locally
Scan QR code to initiate verification
Complete the verification flow

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 Project Structure

ROSCA-Guard/
├── backend/
│   ├── src/
│   │   ├── api/              # API routes
│   │   │   ├── bridgeRoutes.ts
│   │   │   └── selfRoutes.ts
│   │   ├── services/         # Business logic
│   │   │   ├── CrossChainBridge.ts
│   │   │   └── SelfVerificationService.ts
│   │   └── app.ts           # Express app
│   ├── package.json
│   └── tsconfig.json
├── contracts/
│   ├── src/
│   │   ├── KYCVerifier.sol
│   │   ├── ROSCAFactory.sol
│   │   ├── ROSCACircle.sol
│   │   ├── ROSCAAnalytics.sol
│   │   ├── YieldManager.sol
│   │   └── DateParser.sol
│   ├── script/              # Deployment scripts
│   ├── test/                # Contract tests
│   └── foundry.toml
├── frontend/
│   ├── src/
│   │   ├── components/      # React components
│   │   ├── pages/           # Page components
│   │   ├── hooks/           # Custom hooks
│   │   ├── services/        # API services
│   │   ├── config/          # Configuration
│   │   └── App.tsx
│   ├── package.json
│   └── vite.config.ts
└── README.md

🏆 Hackathon Submission

Self Protocol Integration

Backend SDK: SelfBackendVerifier for proof verification
Smart Contracts: SelfVerificationRoot integration
Zero-Knowledge Proofs: Privacy-preserving identity verification
Multi-Document Support: Passport and Aadhaar verification

PYUSD Integration

Primary Currency: All ROSCA contributions in PYUSD
Smart Contract Integration: ERC-20 standard implementation
Automated Payments: Monthly contributions and payouts
Yield Generation: DeFi integration for returns

Innovation

Cross-Chain Architecture: KYC on Celo, operations on Ethereum
Reputation System: Merit-based payout selection
Sybil Resistance: Identity verification prevents fake accounts
Financial Inclusion: Accessible global savings circles

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Self Protocol for zero-knowledge identity verification
PayPal/Paxos for PYUSD stablecoin
Celo Foundation for affordable blockchain infrastructure
Ethereum Foundation for smart contract platform
ETHGlobal for hosting hackathons and fostering innovation

📞 Contact & Links

Live Demo: [Frontend URL] (Coming soon on Vercel)
Backend API: https://rosca-guard.onrender.com
GitHub: https://github.com/anumukul/ROSCA-Guard
Demo Video: [YouTube Link] (Coming soon)

Team

Developer: Anumukul
Email: anumukul009@gmail.com
Twitter: @anumukul
GitHub: @anumukul

🚧 Roadmap

Built with ❤️ for the EthGlobal New-Delhi Hackathon

Empowering financial inclusion through privacy-preserving identity verification

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
backend		backend
contracts		contracts
frontend		frontend
Readme.MD		Readme.MD

Folders and files

Latest commit

History

Repository files navigation

ROSCA-Guard 🛡️

🌟 Overview

Key Features

🏗️ Architecture

🚀 Quick Start

Prerequisites

Installation

📱 Usage

For Users

For Developers

Deploy Smart Contracts

Run Tests

🔧 Technology Stack

Frontend

Backend

Smart Contracts

DevOps

📊 Smart Contracts

Deployed Contracts

Celo Alfajores Testnet

Ethereum Sepolia Testnet

Key Contracts

KYCVerifier.sol

ROSCAFactory.sol

ROSCACircle.sol

🔐 Self Protocol Integration

Backend Verification

Contract Verification

🌐 API Documentation

Base URL

Endpoints

Health Check

Verify Identity (Self Protocol)

Get KYC Status

Check ROSCA Eligibility

Get Platform Statistics

Create ROSCA Circle

🧪 Testing

Get Testnet Tokens

Test Self Protocol Verification

🤝 Contributing

Development Workflow

📝 Project Structure

🏆 Hackathon Submission

Self Protocol Integration

PYUSD Integration

Innovation

📄 License

🙏 Acknowledgments

📞 Contact & Links

Team

🚧 Roadmap

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages