Decentralized-Ajo

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

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:

Features

Core Features

Dashboard Features

Technology Stack

Frontend

Backend

Blockchain

Development

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

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": "user@example.com",
  "password": "SecurePassword123!",
  "firstName": "John",
  "lastName": "Doe"
}

Login

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

{
  "email": "user@example.com",
  "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

Contract State

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

Mainnet (Production)

Security Checklist

Before mainnet deployment:

Database Schema

The application uses Prisma ORM with the following main tables:

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

Built with ❤️ for communities saving together.