Soroban smart contracts powering the Stellar Trust Circles platform — a decentralized rotating savings group protocol built on Stellar.

🚀 Live Demo

Rotating savings groups — known as ajo in Nigeria, chama in Kenya, tanda in Latin America, and susu in the Caribbean — are one of the oldest and most trusted forms of community finance. A fixed group of people contribute a set amount on a schedule; each cycle, one member receives the full pooled amount, rotating until everyone has received once.

Stellar Trust Circles replaces the trusted human treasurer at the center of these groups with a Soroban smart contract:

• Members contribute USDC (or another Stellar asset) on a schedule
• Payouts rotate automatically, enforced by the contract — not a person
• Every contribution and payout is permanently recorded on-chain
• Members build an on-chain reputation score across every circle they join
• Newcomers are admitted via social vouching from trusted members
• Circle rules can be changed through on-chain governance votes
• No bank, no middleman, no missed payouts

This is not three unrelated projects — it's one protocol, split across three repositories by concern: the contract, the interface, and the documentation. This README is the map connecting all three.

1. A circle creator calls create_circle() with a member list, a contribution amount, and a cycle length.
2. Each member calls contribute() before the cycle deadline — funds are escrowed in the contract. Members can contribute in USDC directly, in another Stellar asset via a path payment, or (for unbanked members) via a phone-number invite through the Stellar Disbursement Platform.
3. At the end of the cycle, release_payout() sends the full pot to the next member in the rotation.
4. Missed contributions are recorded on-chain and reduce the member's reputation score; on-time contributions increase it.
5. Once every member has received a payout, the circle closes — or an admin can restart_circle() for another rotation.
6. If a circle opted in to clawback-based dispute resolution, a designated authority can raise and resolve disputes with a permanent on-chain audit trail.

None of these are cosmetic integrations. Each one makes non-negotiable use of Stellar infrastructure that has no cheap equivalent on other chains — see each repo's own README for the detailed "why this needed Stellar specifically" breakdown.

Every member has an on-chain reputation score, tracked across every circle they've participated in:

                        ┌───────────────────────────────────────┐
                        │              Stellar Network            │
                        │                                        │
                        │  ┌──────────────────────────────────┐  │
                        │  │      Soroban Smart Contract       │  │
                        │  │   (STC-smart-contracts repo)      │  │
                        │  │                                    │  │
                        │  │  Core: circle state, escrow,       │  │
                        │  │  rotation, reputation, vouching,   │  │
                        │  │  governance                         │  │
                        │  │                                    │  │
                        │  │  Extensions: multi-asset (path      │  │
                        │  │  payments), SDP onboarding,         │  │
                        │  │  Reflector oracle pricing,          │  │
                        │  │  clawback dispute resolution        │  │
                        │  └───────────────┬────────────────────┘  │
                        │                  │ Horizon API /          │
                        │                  │ Soroban RPC             │
                        └──────────────────┼─────────────────────────┘
                                           │
                    ┌──────────────────────┼──────────────────────┐
                    │                                              │
        ┌───────────▼────────────┐                    ┌────────────▼───────────┐
        │  Frontend (React/TS)    │                    │  External protocols     │
        │  (frontend repo)        │◄──────────────────►│  Freighter wallet,      │
        │                         │                    │  Stellar Disbursement   │
        │  UI for every core +    │                    │  Platform, SEP-24       │
        │  extension flow above   │                    │  anchors (MoneyGram,    │
        └─────────────────────────┘                    │  Cowrie), Reflector      │
                                                         └─────────────────────────┘

        ┌─────────────────────────────────────────────────────────┐
        │      Documentation, SDKs, CLI (documents repo)             │
        │   JavaScript SDK · Python SDK · CLI · Integration guide    │
        │   User guide · Architecture · Security · Examples          │
        └─────────────────────────────────────────────────────────┘

Stellar Trust Circles is split into three repositories, each with its own README covering its part in full detail.

The Soroban smart contract — the actual protocol. One contract deployment equals one circle. Contains:

• contracts/trust_circle/src/lib.rs — core contract logic
• multi_asset.rs, sdp_onboarding.rs, oracle.rs, clawback.rs, reputation_zk.rs — the Stellar-native extension modules
• test.rs and integration tests covering both core and extension flows
• CI pipeline (build, test, cargo clippy -- -D warnings)

The React + TypeScript web interface. Connects to the deployed contract via Freighter. Contains:

• Core views: dashboard, circle list, circle creation, wallet, profile
• src/lib/ and src/components/ for every extension: multi-asset contribution, wallet-free member invites, NGN/GHS/KES pricing display, anchor-based fiat funding, clawback settings, and a roadmap-stage private-reputation UI

Documentation, SDKs, CLI tool, and runnable examples. Contains:

• USER_GUIDE.md, ARCHITECTURE.md, INTEGRATION.md, INTEGRATION_ADDENDUM.md, SECURITY.md, TROUBLESHOOTING.md, glossary.md
• sdks/javascript/ and sdks/python/ — installable client SDKs
• sdks/cli/ — command-line interface
• examples/ — runnable TypeScript and Python code samples

Each repository has its own full setup instructions. In short:

To run or modify the contract:

git clone https://github.com/Stellar-trust-circles/STC-smart-contracts
cd STC-smart-contracts
stellar contract build
cargo test

To run the web app locally:

git clone https://github.com/Stellar-trust-circles/Stellar-trust-circles-frontend
cd Stellar-trust-circles-frontend
npm install
cp .env.example .env   # fill in contract ID, RPC URL, Reflector/SDP config
npm run dev

To use the SDK or CLI:

npm install @stellar-trust-circles/sdk
# or
pip install stellar-trust-circles

Full prerequisites, environment variables, and troubleshooting live in each repo's own README and in Stellar-trust-circles-documents.

• Core contract: create circle, contribute, rotate payout
• On-chain contribution history and reputation scores
• Social vouching system
• On-chain governance voting
• Testnet deployment
• GitHub Actions CI
• Multi-asset contributions via path payments
• Unbanked member onboarding via Stellar Disbursement Platform
• Local-currency (NGN/GHS/KES) denominated circles via Reflector
• Fiat on/off-ramp via SEP-6/SEP-24 anchors
• Clawback-based dispute resolution
• Private reputation proofs via Protocol 25 ZK primitives
• Third-party security audit
• Mainnet deployment
• Cross-circle reputation aggregation
• Circle discovery marketplace

Each repository maintains its own CONTRIBUTING.md with setup instructions and review checklists. Across all three repos, issues tagged good first issue are scoped to a single function or file, with complete acceptance criteria and a suggested branch name — a good place to start regardless of which part of the stack you want to work in.

MIT — see LICENSE