A full-stack application with a backend API (REST + GraphQL) and a frontend client.
- Getting Started
- Backend Service Map
- API Reference — external REST/GraphQL reference, versioning and deprecation policy
- Contracts
The external API reference for the backend REST and GraphQL endpoints is published under docs/api/. It is generated from the existing backend route and schema definitions and includes the versioning and deprecation policy for external consumers.
Not every top-level directory is built the same way. The table below records the maintenance status of directories whose role is not obvious from the build scripts.
| Directory | Status | Notes |
|---|---|---|
zk/ |
Experimental | Zero-knowledge proof subsystem. Not built in root CI. Open HIGH-priority audit items in zk/CIRCUIT_AUDIT.md tracked by issue #1327. Keep in place until the audit closes. |
mobile/quarantine/ |
Active | Triage list for flaky Maestro E2E flows. Read by mobile/scripts/run-tests.sh; do not archive. See mobile/quarantine/README.md. |
Archived work, if any, lives under docs/archive/ with a status
note explaining why it was parked.
The Stellar-Save system consists of four main layers that work together to provide a decentralized ROSCA experience:
- User Layer: Users interact with the system through Stellar wallets (Freighter, Lobstr, Albedo)
- Frontend Layer: React + TypeScript SPA with Vite, Material-UI components, and React Query for state management
- Blockchain Layer: Stellar network with Soroban smart contracts managing groups, contributions, and payouts
- Data Layer: On-chain storage, Stellar Horizon API for transaction history, and Soroban events for real-time updates
- Group Creation: User → Frontend → Contract → On-chain Storage → Events → UI Update
- Contribution: User → Frontend → Contract → Escrow → Storage → Events → UI Update
- Payout: User → Frontend → Contract → Escrow → Recipient → Storage → Events → UI Update
For detailed architecture documentation, see docs/architecture.md.
- Create Groups: Set contribution amount, cycle duration, and max members
- Join & Participate: Members join and contribute each cycle
- Automatic Payouts: When all members contribute, payout executes automatically to the next recipient
- Native XLM Support: Built-in support for Stellar Lumens (XLM)
- Token Ready: Architecture supports custom Stellar tokens (roadmap item)
- Transparent: All contributions and payouts are verifiable on-chain
To get started quickly, follow the dedicated setup guides for each component of the Stellar-Save monorepo:
- 🚀 Smart Contracts: See contracts/stellar-save/src/lib.rs and the QUICK_REFERENCE.md for smart contract API documentation.
- 💻 Frontend Web App: See frontend/README.md for React/TypeScript setup, environment configuration (
VITE_*), MUI theme tokens, and local development commands. - 📱 Mobile Application: See mobile/README.md for Expo React Native setup, iOS/Android emulator instructions, and mobile architecture.
- 🛠️ Scripts & Tooling: See scripts/README.md for build (
build.sh), test (test.sh), and deployment (deploy_testnet.sh,deploy_mainnet.sh) scripts. - ⚙️ Backend Service: See backend/README.md for server setup, environment variables schema, and indexer configuration.
# Clone the repository
git clone https://github.com/Xoulomon/Stellar-Save.git
cd Stellar-Save
# Install workspace dependencies & git hooks (pnpm is the only supported package manager)
corepack enable
pnpm install
# Build Soroban smart contracts
./scripts/build.sh
# Run all test suites across smart contracts and web frontend
./scripts/test.sh
create_group(contribution_amount, cycle_duration, max_members) -> u64
get_group(group_id) -> Group
list_members(group_id) -> Vec<Address>
join_group(group_id)
is_member(group_id, address) -> bool
contribute(group_id, member, amount)
get_contribution_status(group_id, cycle_number) -> Vec<(Address, bool)>
execute_payout(group_id)
is_complete(group_id) -> bool
pause_group(group_id, caller) // Creator-only: halt contributions & payouts
unpause_group(group_id, caller) // Creator-only: resume contributions & payouts