A decentralized community savings platform built on Stellar, enabling trusted groups to automate contributions, payouts, and transparency using Soroban smart contracts.
🚀 https://joint-save.vercel.app
📹 Demo Video: Watch Full MVP Functionality
Across the world, millions of people rely on informal savings groups to pool money and support one another. While these systems foster trust and cooperation, they often face problems like missed payments, fraud, and lack of transparency.
JointSave solves this by putting savings groups on-chain — on Stellar. Funds are managed by Soroban smart contracts, ensuring automation, transparency, and fairness for everyone.
- 🔄 Rotational Mode – Members take turns receiving the full pool payout
- 🎯 Target Pool Mode – Groups save toward a shared goal with automatic unlock
- 💰 Flexible Pool Mode – Members deposit anytime with optional yield distribution
- 🏭 Inter-Contract Architecture – Factory contract coordinates all pool contracts on-chain
- 🔒 Trustless Escrow – Every group is governed by a Soroban smart contract
- 📊 Complete Transparency – Every transaction is verifiable on Stellar
- ⚡ Automated Enforcement – Smart contracts handle payouts, penalties, and deadlines
- 📱 Mobile-First Design – Fully responsive interface optimized for all devices
JointSave uses a light on-chain / off-chain split:
- Factory contract – trusted registry that spawns pools and installs them by WASM hash
- Pool contracts – Rotational (fixed deposits, rotating payouts), Target (goal + deadline), Flexible (variable deposits with yield options)
- Supporting contracts – Reputation (on-chain trust scores), Microloan (P2P lending), Governance (vote-weighted proposals), Yield Strategy (yield routing)
- Frontend – Next.js 16 (App Router) + Tailwind + shadcn/ui, connecting to Stellar via Stellar SDK and Wallets Kit
- Off-chain – Supabase (Postgres) for user metadata, pool titles, notifications, and reusable views, with Row-Level Security
- Safeguards – incident response / pause-authorization flows, pool archival, and dispute resolution (see docs/INCIDENT_RESPONSE.md)
A full technical walkthrough — contract layer, flows, and database schema — lives in ARCHITECTURE.md.
- On-chain: factory + Rotational/Target/Flexible WASMs deployed to Stellar Testnet (see Deployed Contracts). Governance, Microloan, and Yield Strategy have no recorded deployment yet – they are feature-gated via env vars.
- Frontend:
joint-save.vercel.appis hosted on Vercel; the project needs re-linking from the personal fork toJointSave-org/Joint_Save(org admin pending) before auto-deploys onmain. - CI/CD: 4 GitHub Actions workflows – contracts build/test, frontend lint + format + build + component tests, Node unit tests, Playwright E2E (pull requests), plus a manual contract-deploy dispatcher.
- Known gaps under active work: the admin emergency-withdrawal flow is still awaiting contract execution support (#263); the admin incident-review UI is in progress (#261).
- Rust with Soroban SDK for smart contract development
- WebAssembly (WASM) compilation for efficient execution
- Stellar Testnet for secure, low-cost transactions
- Next.js 16 with App Router for modern React development
- TypeScript for type-safe development
- Tailwind CSS for responsive, mobile-first styling
- shadcn/ui for consistent component library
- Stellar SDK for blockchain interactions
- Stellar Wallets Kit for multi-wallet support
- Vercel for frontend deployment and hosting
- Supabase for off-chain metadata and user data
- GitHub Actions for automated CI/CD pipeline
The codebase ships an 8-contract Soroban suite. The following are deployed/uploaded on Stellar Testnet:
| Contract | Address |
|---|---|
| Factory | CBZNGP52FLFZ4BOGC265FUAMP5KFMAYPQK3KTI5UHMYVMM3QCST3IMRI |
| Rotational WASM | d350a325d8734263a3d7150c875555d8956e13a527fb3497d5141b8b3f3d2c74 |
| Target WASM | 133a62226501fc5443e70007d79deeeb0b33fdf8c85c7fcd3cf16293bb5c7292 |
| Flexible WASM | df6ff088fd79f13d8d03e72160434517fdb4a83b8c7bfdd887be4369805e0d6b |
Deployed on April 16, 2026 — see smartcontract/deployments/stellar-testnet.json for the source of truth.
The full suite also includes governance, microloan, reputation, and yield-strategy contracts. Reputation is deployed by smartcontract/scripts/deploy.sh; governance, microloan, and yield-strategy have no testnet deployment recorded yet. Microloan and reputation are feature-gated through the NEXT_PUBLIC_MICROLOAN_CONTRACT_ID / NEXT_PUBLIC_REPUTATION_CONTRACT_ID env vars (leave blank to disable).
For complete API documentation — functions, events, storage keys, error conditions, and CLI examples — see docs/contract-api.md.
- Node.js 22+ (required for the test runner's glob patterns) and pnpm (the repo's
packageManagerfield pins the exact pnpm version) - Rust toolchain with
wasm32-unknown-unknowntarget - Stellar CLI
- A Stellar wallet (Freighter, xBull, Albedo, or Lobstr)
-
Clone the repository
git clone https://github.com/JointSave-org/Joint_Save.git cd Joint_Save -
Set up the frontend
cd frontend pnpm install cp .env.example .env.local -
Configure environment variables Use the inline comments in
frontend/.env.exampleas the source of truth for each value. The frontend validates required variables during startup, so missing values fail fast with a clearMissing required env var: ...error.NEXT_PUBLIC_SUPABASE_URL=your_supabase_url NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_key NEXT_PUBLIC_STELLAR_RPC_URL=https://soroban-testnet.stellar.org NEXT_PUBLIC_STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org NEXT_PUBLIC_FACTORY_CONTRACT_ID=CBZNGP52FLFZ4BOGC265FUAMP5KFMAYPQK3KTI5UHMYVMM3QCST3IMRI NEXT_PUBLIC_TOKEN_CONTRACT_ID=native
-
Start the development server
pnpm dev
-
Access the application Open http://localhost:3000 in your browser
The frontend has a Playwright end-to-end suite covering the critical user flows (create pool, deposit, wallet connect, navigation, responsive layout).
cd frontend
pnpm install
pnpm exec playwright install chromium # one-time browser download
pnpm test:e2e # headless run (Playwright starts the dev server)
pnpm test:e2e:ui # interactive UI modeThe suite is fully deterministic — it mocks the /api/pools boundary and uses a
test-gated wallet/RPC seam (NEXT_PUBLIC_E2E), so it needs no live Soroban
network, wallet extension, or Supabase project. It runs on every PR via
.github/workflows/e2e.yml. See
frontend/e2e/README.md for the design, the flaky-test
policy, and details.
To work with the smart contracts:
cd smartcontract
# Install Rust target for WASM
rustup target add wasm32-unknown-unknown
# Build all contracts
stellar contract build
# Deploy to testnet (requires funded account)
./scripts/deploy.sh- Connect Wallet – Use any supported Stellar wallet
- Create or Join Group – Set up a savings pool with friends or colleagues
- Make Contributions – Deposit funds according to your group's schedule
- Receive Payouts – Get funds automatically when it's your turn or goal is reached
- Track Progress – Monitor your group's activity and balances in real-time
JointSave demonstrates several advanced Soroban patterns:
- Factory Pattern – Central registry for contract discovery
- Inter-Contract Calls – Contracts communicating with each other
- Hybrid Architecture – Combining on-chain logic with off-chain metadata
- Multi-Wallet Integration – Supporting various Stellar wallets
- Real-Time State – Live balance updates from blockchain
Automated testing and deployment
Filter by date, pool, or activity type — then export to CSV
- ✅ Core savings pool functionality (Rotational, Target, Flexible)
- ✅ Multi-wallet Stellar integration
- ✅ Factory contract for pool discovery
- ✅ Mobile-responsive web interface
- ✅ Real-time on-chain state synchronization
- ✅ Automated CI/CD pipeline (contract, frontend unit, Playwright E2E)
- ✅ Reputation system – on-chain trust scores from participation
- ✅ Microloan marketplace – peer-to-peer lending against the pool
- ✅ DAO-style governance voting (merged
governancecontract) - ✅ USDC / multi-token (SEP-41) deposits with Circle CCTP bridge
- ✅ Flexible contribution scheduling & recurring reminders
- ✅ Push notifications (Web Push / VAPID)
- ✅ Pool health scoring, archival, disputes & incident-response safety rails
- DeFi Integration – Connect flexible pools to Stellar DeFi protocols for yield (yield-strategy contract scaffolded; wire liquidity paths)
- Advanced Analytics – Protocol-wide analytics dashboard (telemetry + insights beyond per-pool health)
- Group Communication – In-app messaging and notifications
- Mainnet Hardening – Deploy the 8-contract suite to Stellar mainnet (governance, microloan, yield-strategy still have no testnet deployment recorded)
- Admin Emergency Console – Self-service pause/resume/emergency-withdraw UI with SEP-53 proof (backend exists; UI on the way)
- Fiat Integration – Direct bank transfers and credit card support
- Social Features – Friend invitations and community building
- Native Mobile App – iOS and Android applications
We welcome contributions from the community! Here's how you can help:
- 🐛 Bug Reports – Found an issue? Open an issue
- 💡 Feature Requests – Have an idea? We'd love to hear it
- 🔧 Code Contributions – Submit pull requests for improvements
- 📖 Documentation – Help improve our docs and guides
- 🧪 Testnet Testing – Try the app and report issues
- 📱 Device Testing – Test on different devices and browsers
- 🔍 Security Review – Help audit smart contracts and frontend code
- 💬 Discussions – Join conversations in GitHub Discussions
- 🌟 Spread the Word – Share JointSave with your network
- 🎓 Education – Help others learn about decentralized savings
- Architecture Guide – Detailed technical documentation
- Smart Contract API – Contract interfaces and usage
- Deployment Guide – How to deploy contracts
- Frontend Setup – Development environment setup
Please refer to SECURITY.md for our security policy, in-scope components, known limitations, and instructions on how to report vulnerabilities.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: Contact the team
This project is licensed under the MIT License - see the LICENSE file for details.