Stellar ROSCA

Decentralized savings circles (ROSCAs) built on Stellar and Soroban.

Overview • Features • Quick Start • API • Smart Contract • Contributing • Roadmap

---

📋 Table of Contents

• Overview
• Features
• Architecture
• Tech Stack
• Quick Start
• Project Structure
• Smart Contract
• API Reference
• Testing
• Deployment
• Contributing
• Roadmap
• FAQ
• License

---

🌍 Overview

Stellar ROSCA is a decentralized implementation of the Rotating Savings and Credit Association — a group savings model where members contribute a fixed amount each cycle and one member receives the entire pool, rotating until everyone has been paid out.

Known as Chamas in Kenya, Susus in West Africa, and Tontines across the diaspora, ROSCAs are a vital financial tool for millions of people worldwide. Traditional ROSCAs rely on trust and physical proximity. This project puts the logic on-chain.

Why Stellar ROSCA?

• 🔒 Trustless — contribution rules and payout logic enforced by a Soroban smart contract, not a person
• 🏦 Multisig treasury — group funds held in a Stellar multisig account; no single member can drain it
• 🌐 Globally accessible — anyone with a Stellar wallet can participate
• ⚡ Fast and cheap — Stellar settles in ~5 seconds at a fraction of a cent per transaction
• 📖 Transparent — every contribution and payout is an immutable on-chain record

---

✨ Features

Smart Contract

• ✅ Create ROSCA groups with configurable members, contribution amount, and cycle length
• ✅ Deterministic recipient queue shuffled at group creation
• ✅ Per-cycle contribution tracking with duplicate prevention
• ✅ Token escrow — funds held in contract until payout is triggered
• ✅ Automated payout to next recipient when all members have contributed
• ✅ Cycle advancement and group completion detection
• ✅ On-chain events for every state change

Backend API

• ✅ Group creation with Stellar multisig treasury provisioning
• ✅ Contribution submission — builds and signs Stellar payment transactions
• ✅ All-contributed detection per cycle
• ✅ RESTful JSON API with proper error codes

Frontend (in progress)

• 🚧 Group dashboard
• 🚧 Contribution tracking UI
• 🚧 Cycle progress visualization
• 🚧 Wallet integration

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                  Frontend (Next.js / React)                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  Group Card  │  │Cycle Progress│  │  Dashboard   │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  Backend API (Node.js / Express)             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Group Routes │  │ Contribution │  │Stellar Client│      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  Stellar Network (Soroban)                   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              ROSCA Contract (Rust)                   │   │
│  │  - create_group()       - trigger_payout()           │   │
│  │  - contribute()         - get_group_status()         │   │
│  │  - get_current_recipient()                           │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Contribution + Payout Flow

Member 1        Member 2        Member 3        Backend         Contract
   │               │               │               │               │
   ├─POST /contribute──────────────►               │               │
   │               │               │  recordContribution()         │
   │               │               │               ├─token.transfer►
   │               │               │               ◄─Contrib event─┤
   ◄─{ txHash, allContributed: false }─────────────┤               │
   │               │               │               │               │
   │               ├─POST /contribute──────────────►               │
   │               │               │               ├─token.transfer►
   │               │               │               ◄─Contrib event─┤
   │               ◄─{ txHash, allContributed: false }─────────────┤
   │               │               │               │               │
   │               │               ├─POST /contribute──────────────►
   │               │               │               ├─token.transfer►
   │               │               │               ◄─AllCtrb event─┤
   │               │               ◄─{ txHash, allContributed: true }
   │               │               │               │               │
   │               │               │  POST /payout │               │
   │               │               │               ├─trigger_payout►
   │               │               │               │  verify + pay │
   │               │               │               ◄─Payout event──┤
   │               │               │               │  cycle++      │

---

🛠️ Tech Stack

Smart Contract

Technology	Version	Purpose
Rust	2021	Contract language
Soroban SDK	20.0.0	Stellar smart contract framework

Backend

Technology	Version	Purpose
Node.js	18+	Runtime
Express	4.19	HTTP framework
@stellar/stellar-sdk	11.3	Stellar network interaction
Jest	29	Testing

Frontend

Technology	Version	Purpose
Next.js	14	React framework
React	18	UI
TailwindCSS	3.4	Styling

---

🚀 Quick Start

Prerequisites: Node.js 18+ · Rust · Stellar CLI

1. Clone and configure

git clone https://github.com/cybermax4200/stellar-rosca.git
cd stellar-rosca
cp backend/.env.example backend/.env
# Edit backend/.env — set STELLAR_NETWORK, HORIZON_URL, etc.

2. Install dependencies

cd backend && npm install && cd ..
cd frontend && npm install && cd ..

3. Start the backend

cd backend && npm run dev

Verify it's running:

curl http://localhost:3000/health
# { "status": "ok", "network": "testnet" }

4. Start the frontend (optional)

cd frontend && npm run dev
# http://localhost:3001

---

📁 Project Structure

stellar-rosca/
├── contracts/
│   └── rosca/
│       ├── src/
│       │   └── lib.rs          # Contract logic — create_group, contribute, trigger_payout
│       └── Cargo.toml
├── backend/
│   ├── src/
│   │   ├── index.js            # Express server entry point
│   │   ├── group.js            # Group creation + in-memory store
│   │   ├── contribution.js     # Contribution recording + Stellar tx submission
│   │   ├── stellar.js          # Horizon client, multisig account helpers
│   │   └── routes/
│   │       └── groups.js       # REST route handlers
│   ├── tests/
│   │   ├── group.test.js
│   │   └── contribution.test.js
│   └── package.json
├── frontend/
│   ├── components/             # React components
│   ├── pages/                  # Next.js pages
│   └── styles/
├── docs/
│   ├── architecture.md         # Full system design + security model
│   └── api.md                  # Complete API reference
├── .github/
│   └── ISSUE_TEMPLATE/
│       ├── bug_report.md
│       └── feature_request.md
└── CONTRIBUTING.md

---

📜 Smart Contract

The rosca Soroban contract is the on-chain source of truth. It handles authorization, token escrow, and payout logic. Written in Rust, compiled to WASM.

Contract Functions

create_group

Creates a new ROSCA group and shuffles the recipient queue.

pub fn create_group(
    env: Env,
    admin: Address,       // group administrator
    token: Address,       // token contract for contributions
    members: Vec<Address>,
    contribution_amount: i128,
    cycle_duration_days: u32,
) -> u32                  // returns group_id

contribute

Transfers tokens from a member to the contract escrow and records the contribution.

pub fn contribute(
    env: Env,
    group_id: u32,
    member: Address,
    amount: i128,
)

trigger_payout

Verifies all members have contributed, transfers the full pot to the next recipient, and advances the cycle.

pub fn trigger_payout(env: Env, group_id: u32)

get_current_recipient

Returns the address of the member scheduled to receive the payout this cycle.

pub fn get_current_recipient(env: Env, group_id: u32) -> Address

get_group_status

Returns the full group state.

pub fn get_group_status(env: Env, group_id: u32) -> Group

Error Codes

Code	Error	Description
GroupNotFound	Group does not exist in storage
NotAMember	Caller is not a member of the group
AlreadyContributed	Member has already contributed this cycle
NotAllContributed	Payout attempted before all members contributed
GroupCompleted	All cycles have finished

Events

Topic	Data	Emitted when
(GroupCrtd, group_id)	(admin, group_id)	Group created
(Contrib, group_id)	(member, cycle, amount)	Member contributes
(AllCtrb, group_id)	(group_id, cycle)	All members contributed
(Payout, group_id)	(recipient, cycle, amount)	Payout sent

Build and Deploy

# Build
cd contracts/rosca
stellar contract build

# Deploy to testnet
stellar contract deploy \
  --wasm target/wasm32v1-none/release/rosca.wasm \
  --source <YOUR_SECRET_KEY> \
  --network testnet

The command prints the contract ID — save it in backend/.env as CONTRACT_ID.

---

📡 API Reference

Base URL: http://localhost:3000/api · All amounts in stroops (1 XLM = 10,000,000 stroops)

Method	Endpoint	Status	Description
GET	/health	✅ Live	Server health check
POST	/groups/create	✅ Live	Create group + multisig treasury
POST	/groups/:id/contribute	✅ Live	Submit member contribution
GET	/groups/:id/status	🚧 Stub	Get group state
POST	/groups/:id/payout	🚧 Stub	Trigger cycle payout
GET	/groups/:id/members	🚧 Stub	List group members

Full docs with typed request/response bodies and curl examples: docs/api.md

Quick Examples

Create a group

curl -X POST http://localhost:3000/api/groups/create \
  -H "Content-Type: application/json" \
  -d '{
    "adminSecret": "SADMIN...",
    "members": ["GMEMBER1...", "GMEMBER2...", "GMEMBER3..."],
    "contributionAmount": 10000000,
    "cycleDurationDays": 7
  }'

Contribute

curl -X POST http://localhost:3000/api/groups/<id>/contribute \
  -H "Content-Type: application/json" \
  -d '{ "memberSecret": "SMEMBER...", "amount": 10000000 }'

---

🧪 Testing

# Backend — Jest with mocked Stellar SDK
cd backend && npm test

# Contract — Rust
cd contracts/rosca && cargo test

Current: 8 passing tests across group creation and contribution flows.

---

🚢 Deployment

See CONTRIBUTING.md for the full deploy walkthrough. Quick reference:

cd contracts/rosca
stellar contract build
stellar contract deploy \
  --wasm target/wasm32v1-none/release/rosca.wasm \
  --source <YOUR_SECRET_KEY> \
  --network testnet

For frontend deployment, run npm run build inside /frontend and deploy the .next output to Vercel or any Node-compatible host.

---

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md for full setup, test, and deploy instructions.

How to contribute

1. Fork the repo
2. Create a branch: git checkout -b feature/your-feature
3. Make your changes and write tests
4. Ensure everything passes: npm test / cargo test
5. Commit using Conventional Commits: feat: add your feature
6. Open a PR referencing the relevant issue: Closes #42

Branch naming

Type	Pattern
Feature	feature/short-description
Bug fix	fix/short-description
Docs	docs/short-description

---

🗺️ Roadmap

Phase 1 — Smart Contract Core ✅

• create_group, contribute, trigger_payout
• Token escrow and multisig treasury
• On-chain events

Phase 2 — Backend API ✅

• Group creation endpoint
• Contribution endpoint with Stellar tx submission
• Jest test suite with mocked SDK

Phase 3 — Frontend Dashboard (in progress)

• Group management UI
• Contribution tracking and cycle progress
• Wallet integration

Phase 4 — Persistence

• Replace in-memory store with PostgreSQL or MongoDB
• Transaction history and audit log

Phase 5 — Mainnet

• Security audit
• Mainnet deployment
• Verifiable randomness for recipient queue (Pyth Entropy)

---

❓ FAQ

What is a ROSCA? A group savings model where members contribute a fixed amount each cycle and one member receives the full pool, rotating until everyone has been paid out.

Do I need to write code to use this? To run a group today you interact via the API or frontend. No Rust or Solidity knowledge needed.

Which network is supported? Stellar testnet for development. Mainnet deployment is planned for Phase 5 after a security audit.

What happens if a member doesn't contribute? The contract blocks the payout until all members have contributed. A deadline + slash mechanism is planned for Phase 4.

Why is the recipient queue not truly random? True randomness isn't available on-chain — every validator must reproduce the same result. The queue is shuffled using a deterministic LCG seeded from the ledger timestamp. A production deployment will use a verifiable randomness oracle.

Where are group funds held? In the Soroban contract as escrow until trigger_payout is called. The multisig treasury account adds a second layer — no single member can move funds unilaterally.

---

📄 License

MIT