🟢 Issue #284 (Dispute Resolution and Arbitration System) has been implemented and resolved via PRs. This repository now includes filing, voting, and admin arbitration features.
A blockchain-based savings group platform built on Stellar/Soroban, enabling communities to create and manage traditional "Ajo" or "Rotating Savings and Credit Associations" (ROSCAs) with full transparency and security.
Interactive documentation site: Run npm run dev:docs and visit http://localhost:3000
- Getting Started Guide
- API Reference - Interactive Swagger UI
- Architecture Overview
- Smart Contracts
drips_maintener/
├── frontend/ # Next.js web application
│ └── src/
│ ├── app/ # Next.js pages (App Router)
│ ├── components/
│ ├── hooks/
│ └── services/
├── backend/ # Node.js/Express API server
│ └── src/
│ ├── routes/ # API routes
│ ├── controllers/
│ ├── services/ # Soroban integration
│ └── middleware/
├── contracts/ # Soroban smart contracts (Rust)
│ └── ajo/ # Main Ajo contract
├── documentation/ # All project documentation
└── package.json # Monorepo root config
- Node.js 20+
- Rust 1.70+
- Stellar CLI
- Git
# Clone repository
git clone <repo-url>
cd drips_maintener
# Install all dependencies (frontend + backend)
npm run install:all
# Or install individually:
npm install # Root dependencies
cd frontend && npm install
cd ../backend && npm installcd contracts/ajo
# Build contract
stellar contract build
# Run tests
cargo test
# Deploy (with Stellar CLI configured)
stellar contract deploy --wasm target/wasm32-unknown-unknown/release/ajo.wasmUse the helper script to deploy the contract to Stellar testnet:
# From repo root
scripts/deploy_testnet.shWhat it does:
- Ensures Soroban CLI, Rust, and testnet network config exist
- Generates a
deployeridentity (if missing) and prompts you to fund it via friendbot - Builds and optimizes the contract
- Deploys to testnet and writes the contract ID to
contract-id.txt - Prints next steps and an explorer link
See the full walkthrough in demo/demo-script.md.
Troubleshooting
- If deployment fails with funding errors: fund the deployer shown in the script output via
https://friendbot.stellar.org?addr=<address>, then re-run. - If
sorobancan't findtestnet: the script re-adds it, or you can run
soroban network add --global testnet --rpc-url https://soroban-testnet.stellar.org:443 --network-passphrase "Test SDF Network ; September 2015".
cd backend
# Set up environment
cp .env.example .env
# Edit .env with your Stellar RPC URL and contract ID
# Run development server
npm run devRuns on http://localhost:3001
cd frontend
# Set up environment
cp .env.example .env.local
# Edit .env.local with your configuration
# Run development server
npm run devVisit http://localhost:3000
# From root directory
npm run devThis starts both frontend and backend concurrently.
Comprehensive documentation is available in the documentation/ folder:
- Documentation Index - Complete documentation guide
- Project Structure - Detailed project structure
- Architecture - System design
- Guides - Step-by-step guides
- Development - Development workflows
- API Documentation - Interactive Swagger UI (when backend is running)
- Frontend README - Next.js setup and development
- Backend README - API server setup and endpoints
- Contributing Guidelines - How to contribute
- Refactoring Plan - Code quality improvements
- Blockchain: Stellar (Soroban)
- Language: Rust
- Testing: Rust test framework
- Runtime: Node.js 20+
- Framework: Express.js 4.18
- Language: TypeScript 5.2
- Blockchain SDK: Stellar SDK 12.0
- Security: Helmet, CORS
- Validation: Zod
- Framework: Next.js 14 (App Router)
- Language: TypeScript 5.2
- Styling: Tailwind CSS 3.3
- State: React Query + Zustand
- Blockchain SDK: Stellar SDK 12.0
- Charts: Recharts
- ✅ Create savings groups with custom rules
- ✅ Member onboarding and management
- ✅ Scheduled contributions tracking
- ✅ Transparent fund distribution
- ✅ Transaction history on-chain
- ✅ Group analytics and insights
- ✅ Wallet integration (Freighter)
- Node.js 20+
- Rust 1.70+
- Stellar CLI
- Git
# Clone repository
git clone <repo-url>
cd drips_maintener
# Install all dependencies
npm run install:all
# Set up contracts
cd contracts/ajo
cargo build
# Set up backend
cd ../../backend
cp .env.example .env
# Edit .env
# Set up frontend
cd ../frontend
cp .env.example .env.local
# Edit .env.local# From root - run everything
npm run dev
# Or run individually:
npm run dev:frontend # Next.js on :3000
npm run dev:backend # Express on :3001
# Build everything
npm run build
# Run tests
npm run test:contracts # Rust tests
npm run type-check # TypeScript checks
npm run lint # ESLintNODE_ENV=development
PORT=3001
FRONTEND_URL=http://localhost:3000
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
SOROBAN_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
SOROBAN_CONTRACT_ID=<your_contract_id>NEXT_PUBLIC_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_SOROBAN_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
NEXT_PUBLIC_SOROBAN_CONTRACT_ID=<your_contract_id>
NEXT_PUBLIC_API_URL=http://localhost:3001cd contracts/ajo
cargo testcd backend
npm run type-check
npm run lint
npm test # (when tests are added)cd frontend
npm run type-check
npm run lint# From root
npm run type-check
npm run lint
npm run test:contractsDeploy to Stellar testnet/mainnet using Stellar CLI:
cd contracts/ajo
stellar contract build
stellar contract deploy --wasm target/wasm32-unknown-unknown/release/ajo.wasm --network testnetDeploy to Railway, Render, Heroku, or any Node.js hosting:
cd backend
npm run build
npm startRecommended platforms:
- Railway (easiest)
- Render
- DigitalOcean App Platform
- Heroku
- AWS/GCP/Azure
Deploy to Vercel (recommended for Next.js):
cd frontend
npm run build
npm startOr one-click deploy:
- Vercel (recommended)
- Netlify
- Cloudflare Pages
Remember to set all required environment variables in your hosting platform.
See CONTRIBUTING.md for guidelines.
See LICENSE file.
For questions and support, please open an issue on GitHub.