Stellar Ajo - Decentralized Savings Circle

A full-stack decentralized savings circle application built on the Stellar Network. Enables groups of people to pool money, take turns receiving lump sums, vote on governance decisions, and manage contributions with full transparency through smart contracts.

Table of Contents

• Overview
• Features
• Technology Stack
• Project Structure
• Setup Instructions
• API Documentation
• Smart Contract
• Deployment

Overview

Ajo (or Esusu in West African cultures) is a traditional savings circle where members pool money and take turns receiving the total amount. Stellar Ajo brings this ancient concept to Web3 using:

• Smart Contracts (Soroban): Secure fund management and automation
• Stellar Network: Fast, low-cost transactions
• Decentralized Governance: Community voting on circle rules
• Full Transparency: All transactions on-chain

Features

Core Features

• ✅ Circle Management: Create and manage savings circles
• ✅ Member Contributions: Track contributions from all members
• ✅ Rotation Payouts: Automated payout distribution in rounds
• ✅ Contribution Scheduling: Set up recurring contribution schedules
• ✅ Governance Voting: Members vote on circle decisions
• ✅ Partial Withdrawals: Emergency access to funds with penalties
• ✅ User Accounts: Email/password authentication with JWT
• ✅ Wallet Integration: Connect Stellar wallets (Freighter, Lobstr)

Dashboard Features

• Circle creation and management
• Member management
• Contribution tracking
• Transaction history
• Real-time circle statistics
• Governance proposal voting

Technology Stack

Frontend

• Framework: Next.js 16 (App Router)
• UI Components: shadcn/ui
• Styling: Tailwind CSS 4
• State Management: SWR (for data fetching)
• Wallet Connection: Freighter / Stellar Wallets Kit

Backend

• Runtime: Node.js (Next.js API Routes)
• Database: SQLite (development) / PostgreSQL (production)
• ORM: Prisma
• Authentication: JWT + Password Hashing (bcryptjs)

Blockchain

• Network: Stellar Network (Testnet/Mainnet)
• Smart Contracts: Soroban (Rust)
• Contract Deployment: Stellar SDK
• RPC: Soroban RPC Server

Development

• Language: TypeScript
• Package Manager: pnpm
• Deployment: Vercel

Project Structure

.
├── app/
│   ├── api/                    # Next.js API routes
│   │   ├── auth/              # Authentication endpoints
│   │   └── circles/           # Circle management APIs
│   ├── auth/                  # Authentication pages
│   │   ├── login/
│   │   └── register/
│   ├── circles/               # Circle pages
│   │   ├── create/
│   │   └── [id]/
│   ├── globals.css            # Global styles
│   ├── layout.tsx             # Root layout
│   └── page.tsx               # Home page
├── components/
│   ├── ui/                    # shadcn/ui components
│   └── wallet-button.tsx      # Wallet connection component
├── contracts/
│   └── ajo-circle/            # Soroban smart contract
│       ├── src/
│       │   └── lib.rs         # Contract implementation
│       └── Cargo.toml
├── lib/
│   ├── auth.ts                # Authentication utilities
│   ├── prisma.ts              # Prisma client
│   ├── stellar-config.ts      # Stellar SDK configuration
│   └── wallet-context.tsx     # Wallet context provider
├── prisma/
│   └── schema.prisma          # Database schema
├── public/                    # Static assets
└── scripts/                   # Utility scripts

Setup Instructions

Prerequisites

• Node.js 18+ or compatible version
• pnpm (recommended) or npm
• Freighter wallet extension (for wallet integration)
• Vercel account (for deployment)

1. Clone and Install

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env.local

2. Configure Environment Variables

Edit .env.local with your configuration:

# Stellar Network (use testnet for development)
NEXT_PUBLIC_STELLAR_NETWORK=testnet
NEXT_PUBLIC_STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
NEXT_PUBLIC_STELLAR_NETWORK_PASSPHRASE=Test SDF Network ; September 2015

# Soroban RPC
NEXT_PUBLIC_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_AJO_CONTRACT_ADDRESS=<your-contract-address>

# Database
DATABASE_URL=file:./dev.db

# JWT Secret (change for production!)
JWT_SECRET=your-super-secret-jwt-key-change-this

# API
NEXT_PUBLIC_API_URL=http://localhost:3000/api

3. Set Up Database

# Generate Prisma client
pnpm prisma generate

# Create database and run migrations
pnpm prisma migrate dev

# Seed database (optional)
pnpm prisma db seed

4. Deploy Smart Contract

# Install Soroban CLI
# See: https://developers.stellar.org/docs/smart-contracts/getting-started/setup

# Build the contract
cd contracts/ajo-circle
cargo build --target wasm32-unknown-unknown --release

# Deploy to testnet (requires Stellar account with XLM)
# Follow Soroban deployment guide with the compiled WASM

# Update NEXT_PUBLIC_AJO_CONTRACT_ADDRESS in .env.local

5. Run Development Server

pnpm dev

Open http://localhost:3000 to view the app.

API Documentation

Authentication

Register

POST /api/auth/register
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "SecurePassword123!",
  "firstName": "John",
  "lastName": "Doe"
}

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "SecurePassword123!"
}

Circles

Create Circle

POST /api/circles
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Office Savings Circle",
  "description": "Monthly savings circle for office team",
  "contributionAmount": 100.50,
  "contributionFrequencyDays": 7,
  "maxRounds": 12
}

Get All Circles

GET /api/circles
Authorization: Bearer <token>

Get Circle Details

GET /api/circles/:id
Authorization: Bearer <token>

Make Contribution

POST /api/circles/:id/contribute
Authorization: Bearer <token>
Content-Type: application/json

{
  "amount": 100.50
}

Smart Contract

Soroban Contract Features

The Soroban smart contract (contracts/ajo-circle/src/lib.rs) implements:

Functions

• initialize_circle() - Create a new circle
• add_member() - Add member to circle
• contribute() - Record member contribution
• claim_payout() - Claim payout when it's member's turn
• partial_withdraw() - Withdraw portion with penalty
• get_circle_state() - Query current circle status
• get_member_balance() - Query member details
• get_members() - List all members

Contract State

• Circle metadata (organizer, amounts, frequency, rounds)
• Member records (contributions, withdrawals, payout status)
• Contribution tracking

Building the Contract

cd contracts/ajo-circle

# Build WASM
cargo build --target wasm32-unknown-unknown --release

# The compiled WASM will be in:
# target/wasm32-unknown-unknown/release/ajo_circle.wasm

Deployment

Deploy to Vercel

1. Push code to GitHub:

git add .
git commit -m "Initial commit"
git push origin main

2. Deploy to Vercel:
   • Connect your GitHub repository at vercel.com
   • Set environment variables in Vercel dashboard
   • Deploy!

Stellar Network Deployment

Testnet (Recommended for Testing)

• Network: Test SDF Network ; September 2015
• Horizon: https://horizon-testnet.stellar.org
• Soroban RPC: https://soroban-testnet.stellar.org

Mainnet (Production)

• Network: Public Global Stellar Network ; September 2015
• Horizon: https://horizon.stellar.org
• Soroban RPC: https://soroban.stellar.org

Security Checklist

Before mainnet deployment:

• Change JWT_SECRET to a secure random string
• Enable HTTPS on production
• Set up rate limiting on API routes
• Implement input validation on all endpoints
• Audit smart contract code
• Set up database backups
• Enable wallet signature verification
• Implement proper error handling

Database Schema

The application uses Prisma ORM with the following main tables:

• User: User accounts and profiles
• Circle: Savings circles
• CircleMember: Circle membership and rotation tracking
• Contribution: Contribution transactions
• PaymentSchedule: Payout schedule tracking
• GovernanceProposal: Voting proposals
• GovernanceVote: Vote records
• Withdrawal: Partial withdrawal requests
• Session: Authentication sessions

See prisma/schema.prisma for complete schema details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source and available under the MIT License.

Support

For issues, questions, or suggestions, please open an issue on GitHub.

Acknowledgments

• Stellar Development Foundation - For the incredible Stellar Network and Soroban
• Vercel - For deployment infrastructure
• shadcn/ui - For beautiful UI components
• Traditional Ajo/Esusu communities - For inspiring this project

---

Built with ❤️ for communities saving together.