A decentralized application (dApp) for creating and managing Osusu groups (rotating savings and credit associations) on the Solana blockchain. Built with Anchor framework and Next.js.

Osusu is a traditional West African savings system where a group of people contribute a fixed amount of money at regular intervals. Each cycle, one member receives the entire pot, rotating until everyone has received a payout. This smart contract brings this time-tested financial practice to Web3.

• Create Osusu Groups: Set up rotating savings pools with customizable contribution amounts
• Member Management: Automatically includes creator as member with ability to add multiple participants
• Contribution System: Members contribute fixed SOL amounts per cycle
• Automated Payouts: Authority triggers payouts to members in rotation order
• Group Dashboard: View all groups where you're a member or authority
• Real-time Balance Tracking: Monitor vault balances and total contributions
• Wallet Integration: Seamless Solana wallet connection and management

This dApp contains:

• Solana Program: Written in Rust using the Anchor framework
• Frontend: Next.js app with React and TypeScript
• Styling: Tailwind CSS with custom UI components
• Wallet Support: Integration with @solana/web3.js and Solana Wallet Adapter

• Node.js 16+ and npm installed
• Solana CLI tools installed (Installation Guide)
• Anchor framework installed (Installation Guide)
• A Solana wallet with devnet SOL

Clone the repository and install dependencies:

git clone <repository-url>
cd osusu
npm install

1. Build the Solana program:

   npm anchor-build

2. Deploy to Devnet:

   anchor deploy --provider.cluster devnet

3. Start the frontend:

   npm dev

4. Open your browser: Navigate to http://localhost:3000 and connect your Solana wallet.

osusu/
├── anchor/                   # Solana program
│   ├── programs/osusu/      # Smart contract source code
│   │   └── src/lib.rs       # Main program logic
│   ├── tests/               # Program tests
│   └── Anchor.toml          # Anchor configuration
├── src/
│   ├── app/                 # Next.js app directory
│   ├── components/          # React components
│   │   ├── osusu/          # Osusu-specific components
│   │   ├── cluster/        # Network cluster management
│   │   └── solana/         # Wallet provider components
│   └── lib/                # Utility functions
└── package.json

This is a Solana program written in Rust using the Anchor framework.

You can use any normal anchor commands. Either move to the anchor directory and run the anchor command or prefix the command with npm, eg: npm anchor.

Running this command will create a new keypair in the anchor/target/deploy directory and save the address to the Anchor config file and update the declare_id! macro in the ./src/lib.rs file of the program.

You will manually need to update the constant in anchor/lib/counter-exports.ts to match the new program id.

npm anchor keys sync

npm anchor-build

npm anchor-localnet

npm anchor-test

npm anchor deploy --provider.cluster devnet

This is a React app that uses the Anchor generated client to interact with the Solana program.

Start the web app

npm dev

Build the web app

npm build

The Osusu smart contract was built in progressive phases:

• Basic group initialization with members and contribution amounts
• Member contribution mechanism (transfer SOL to group vault)
• Payout system with rotation logic
• Authority-based payout trigger
• PDA (Program Derived Address) vault for secure fund storage

Ideas for extending the current implementation:

• Add group size limits (min/max members)
• Implement contribution deadlines
• Add emergency pause mechanism
• Member verification before contributions
• Slashing mechanism for missed contributions

• Time-based contribution windows
• Automated payout scheduling using Clockwork
• Missed contribution penalties
• Grace period for late contributions

• Democratic voting for rule changes
• Multi-signature authority for large groups
• Dispute resolution mechanism
• Member removal/replacement voting

1. Contribution History

   • Track individual member contribution records
   • Display contribution timestamps
   • Add contribution counter per member

2. Group Status Indicators

   • Active/Inactive/Completed status
   • Visual progress tracking
   • Cycle completion percentage

3. Member Profiles

   • On-chain reputation scores
   • Contribution reliability metrics
   • Participation badges/NFTs

4. Basic Notifications

   • Event logs for contributions
   • Payout completion events
   • New member joining events

5. Flexible Contribution Amounts

   • Allow variable contributions (weighted payouts)
   • Bonus contributions for early payers
   • Minimum/maximum contribution limits per cycle

6. Multiple Payout Strategies

   • Lottery-based selection (random winner)
   • Bidding system (highest bidder gets payout first)
   • Need-based priority system
   • Auction mechanism for rotation order

7. Savings Goals

   • Set group financial targets
   • Track progress towards goals
   • Milestone celebrations/rewards
   • Goal-based group completion

8. Group Templates

   • Pre-configured group types (weekly, monthly, etc.)
   • Default rules and settings
   • Quick setup for common use cases

9. Contribution Reminders

   • On-chain deadline tracking
   • Integration with notification services
   • Automated reminder system

10. Interest/Yield Integration

    • Stake idle funds in lending protocols
    • Distribute earned interest among members
    • Integration with DeFi protocols (Marinade, Jupiter)

11. Cross-Chain Support

    • Support multiple tokens (USDC, USDT, custom SPL tokens)
    • Token swap integration
    • Multi-currency groups

12. Insurance Fund

    • Optional insurance pool for defaults
    • Risk assessment mechanism
    • Claim process for affected members

13. Credit Scoring System

    • On-chain credit history
    • Reputation-based group matching
    • Defaulter tracking and penalties

14. Automated Market Maker (AMM) Integration

    • Allow early payout requests (with fee)
    • Secondary market for payout positions
    • Liquidity provision for emergency withdrawals

15. DAO Governance

    • Token-based voting system
    • Proposal submission and voting
    • Treasury management
    • Protocol fee distribution

16. Advanced Security Features

    • Time-locked funds
    • Multi-signature payouts
    • Gradual payout release (vesting)
    • Smart contract upgradability with governance

17. Social Features

    • Group chat integration (using Dialect)
    • Member discovery and matching
    • Public/Private group options
    • Invite-only groups with verification

18. Analytics Dashboard

    • Group performance metrics
    • Member participation statistics
    • Historical data visualization
    • Predictive analytics for contributions

19. Compliance & KYC

    • Optional identity verification
    • Regulatory compliance features
    • Transaction limits and reporting
    • Geographic restrictions

20. Mobile App Integration

    • Mobile-first wallet connection
    • Push notifications
    • QR code payments
    • Biometric authentication

• Anchor Framework Documentation
• Solana Cookbook
• Solana Program Library
• Solana Web3.js Documentation

This project is designed for educational purposes. Students are encouraged to:

1. Fork the repository
2. Implement additional features from the suggestions above
3. Test thoroughly on devnet
4. Document your changes
5. Share your improvements with the community

This project is open source and available for educational use.

This is an educational project. Do not use in production without proper security audits and testing. Always test on devnet/testnet before considering mainnet deployment.