FairCircles

FairCircles brings the centuries-old tradition of Rotating Savings and Credit Associations (ROSCAs) to Solana's decentralized finance ecosystem, powered by FairScale reputation scoring.

Comment

Inspiration

FairCircles started with ROSCAs (Rotating Savings and Credit Associations), a financial tradition used by over 1 billion people, chit funds in India, tandas in Latin America, susus in West Africa, and hui in China. These groups pool contributions and rotate payouts, but they rely on social trust and local networks.

I wanted to bring ROSCAs to Web3: trustless, transparent, and global. Solana’s speed and low fees fit well, and FairScale’s reputation scoring enables risk management and access control.

What I Learned

Solana & Anchor

  • PDA derivation and account management
  • Rust for on-chain logic
  • Anchor’s IDL for type-safe client integration
  • State management with fixed-size arrays (10 members max)
  • Escrow PDAs for secure fund holding

Full-Stack Architecture

  • React 19 with Zustand for state
  • Express.js backend as a FairScale API proxy
  • TypeScript across the stack
  • Wallet adapter integration (Phantom, Solflare)

Reputation-Based Design

  • Using FairScore for access gating, payout ordering, and risk mitigation
  • Higher reputation → earlier payout
  • Lower reputation → contribute first to prove commitment

How I Built It

Phase 1: Smart Contract (Anchor/Rust)

  • Designed the Circle account (~550 bytes) with fixed arrays for members, scores, and contributions
  • Implemented 6 instructions: create_circle, join_circle, start_circle, contribute, claim_payout, update_fair_score
  • Used two PDAs: Circle (state) and Escrow (funds)
  • Implemented a state machine: Forming → Active → Completed

Phase 2: Backend (Express.js)

  • Built a proxy for FairScale API calls
  • Added score normalization (0-100 → 0-1000 for UI)
  • Implemented batch processing for multiple wallets
  • Added error handling for rate limits and network issues

Phase 3: Frontend (React + TypeScript)

  • Created components: Dashboard, CircleCard, CircleDetail, CreateCircleForm, FairScoreCard
  • Built hooks: useCircleProgram (Solana interactions), useFairScore (API with 5-minute cache)
  • Integrated Solana Wallet Adapter for wallet connections
  • Implemented Zustand for global state (circles, FairScore cache, notifications)

Phase 4: Integration & Polish

  • Connected all three layers with proper error handling
  • Added transaction notifications and loading states
  • Implemented FairScore validation before circle joins
  • Created a landing page and responsive UI

Challenges Faced

1. Solana Account Size Limits

  • Challenge: Storing member data, scores, and contribution history in a single account
  • Solution: Used fixed-size arrays ([Pubkey; 10], [[bool; 10]; 10]) and optimized the account structure to fit within Solana’s constraints

2. FairScore Integration Complexity

  • Challenge: Different scales (API: 0-100, UI: 0-1000, Solana: u8 0-255) and caching needs
  • Solution: Normalization layer in the backend, frontend caching with TTL, and validation on-chain

3. State Synchronization

  • Challenge: Keeping frontend state in sync with on-chain data
  • Solution: On-demand fetching with Zustand, manual refresh triggers, and optimistic UI updates

4. Transaction Flow Complexity

  • Challenge: Multi-step flows (create → join → start → contribute → claim) with proper validation
  • Solution: Clear state machine, frontend validation before transactions, and error handling with user-friendly messages

5. PDA Derivation

  • Challenge: Deriving Circle and Escrow PDAs consistently across frontend and program
  • Solution: Standardized seed patterns (["circle", creator, name] and ["escrow", creator, name]) and helper functions in the frontend hook

6. Rate Limiting

  • Challenge: FairScale API rate limits affecting user experience
  • Solution: Backend caching, 5-minute TTL in frontend, graceful degradation with cached data fallback

Key Achievements

Full-stack dApp with Solana smart contracts
Reputation-based access control and payout ordering
Trustless ROSCA execution on-chain
Clean architecture with separation of concerns
Production-ready error handling and user feedback
Comprehensive documentation and architecture diagrams

Future Vision

FairCircles can evolve into a platform for:

  • Multi-token support (SPL tokens beyond SOL)
  • Default tracking and slashing mechanisms
  • Governance features for circle parameters
  • Mobile app for broader accessibility
  • Integration with other DeFi protocols

This project demonstrates how traditional financial primitives can be reimagined on blockchain with reputation systems, making finance more accessible, transparent, and trustless.

Built With

Share this project:

Updates