A trustless Rotating Savings and Credit Association (ROSCA) built on Stellar Soroban.
- Overview & Deployment
- Protocol Overview
- Savings Group Lifecycle
- Public Function Signatures
- Core Features
- Risk Management & Security
- Governance & Voting
- Analytics & Reputation Engines
- Developer & Maintainer Guide
- Testing & Verification
- Network: Stellar Mainnet
- Contract ID: CAH65U2KXQ34G7AT7QMWP6WUFYWAV6RPJRSDOB4KID6TP3OORS3BQHCX
- Create savings circles with fixed contribution amounts
- Join existing circles with optimized state management
- Deposit USDC/XLM securely
- Automated payouts with randomized or fixed order
- Immutable audit log for sensitive actions
- Integrated Buddy System for social security
SoroSusu supports randomized payout queues to ensure fairness and prevent circular collusion.
- Random Queue: Uses Soroban's Pseudo-Random Number Generator (
env.prng().shuffle()) to reorder member addresses. - Finalization: Circle transition logic ensures the payout order is locked once the circle is active.
The protocol allows circles to persist across multiple rounds without redeployment, resetting internal round counters while preserving the member list.
The diagram below shows the full lifecycle of a savings group, from creation through to final payout.
stateDiagram-v2
[*] --> Open : create_circle()
Open --> Active : join_circle()\n[max members met]
Open --> Open : join_circle()\n[still filling]
Active --> CollectionPhase : deposit()\n[contributions pending]
CollectionPhase --> CollectionPhase : deposit()\n[rounds pending]
CollectionPhase --> PayoutPhase : deposit()\n[round cycle ends]
PayoutPhase --> CollectionPhase : deposit()\n[more rounds remain]
PayoutPhase --> Completed : deposit()\n[final member paid]
Completed --> [*]
| State | Description |
|---|---|
| Open | The circle has been created and is accepting new members. |
| Active | All required members have joined; the circle is confirmed and ready to begin rounds. |
| Collection Phase | Members are depositing their fixed contribution for the current round. |
| Payout Phase | Contributions for the round are complete; funds are disbursed to the recipient. |
| Completed | Every member has received a payout. |
Initializes the contract with a global administrator and a default penalty fee (in basis points).
create_circle(env: Env, creator: Address, amount: u64, max_members: u32, token: Address, cycle_duration: u64, bond_amount: u64) -> u64
Creates a new savings circle with a mandatory bond deposit from the creator.
Adds a member to an existing circle.
Batch deposit for one or more rounds.
Sets a social buddy for security and recovery purposes.
Deposits collateral into a circle's safety buffer.
register_anchor(env: Env, admin: Address, anchor_address: Address, name: Symbol, sep_version: Symbol, kyc_required: bool, supported_tokens: Vec<Address>, max_deposit_amount: u64, daily_deposit_limit: u64)
Registers a new SEP-24 anchor for fiat conversions.
set_payout_preference(env: Env, user: Address, circle_id: u64, payout_method: PayoutMethod, anchor_config: Option<AnchorDepositConfig>)
Sets user's payout preference for a circle (Direct Token vs Direct-to-Bank).
Retrieves user's payout preference for a circle.
Read-only partner adapter that returns true only when the user's Reliability Index is greater than 900 and they have zero defaults. It emits no events and reveals no private group membership data.
deposit_for_user(env: Env, anchor_address: Address, user_address: Address, circle_id: u64, amount: u64, token: Address, fiat_reference: Symbol)
Deposits funds on behalf of a user via an anchor (for SEP-24 integration).
process_anchor_payout(env: Env, anchor_address: Address, user_address: Address, circle_id: u64, amount: u64, token: Address) -> Result<u64, u32>
Processes a payout to an anchor for fiat conversion.
Members participate at different contribution levels (1x or 2x), with payouts adjusted according to their share weight.
Enables members to contribute using any Stellar asset, automatically swapped to the circle's base currency via Soroban's native swap capabilities.
- Anchor Integration: Users can choose to receive payouts as fiat currency directly to their bank accounts or mobile money wallets (e.g., M-Pesa).
- Automatic Conversion: Contract automatically routes payouts to designated SEP-24 anchors for crypto-to-fiat conversion.
- Fallback Safety: If anchor processing fails, system automatically falls back to direct token payouts.
- KYC Support: Optional KYC verification for enhanced security and compliance.
- Mobile Money Support: Supports popular mobile money providers across African markets.
- Buddy Assignment: Every member is paired with a "Buddy" responsible for social vouching.
- Safety Fallback: Safety deposits can cover a buddy's missed payment to prevent group default.
- Bond Staking: Creators must stake a bond to disincentivize fraudulent circle creation.
- Slashing: Defaulting members can have their bond or safety deposits slashed by the admin.
- Nuclear Option: A majority-voted mechanism to halt operations and return funds in case of emergency.
- Social Recovery: Allows members to recover participation access via consensus from their designated buddies.
A tiered cooldown system prevents spam joining or malicious circle creation within rapid succession.
Reduces plutocracy by making subsequent votes exponentially more expensive (Cost = Votes²).
A specialized voting mechanism to grant extensions to members in distress, preventing immediate penalties.
Integrates on-chain and off-chain data to calculate a "DeFi Credit Score" based on contribution history.
Partner protocols can call is_reputable_user(address) as a high-frequency VIP gate for under-collateralized lending, fee discounts, or other premium DeFi features. Archived or missing reputation records resolve to false.
Detailed technical documentation is available in RELIABILITY_INDEX_WHITEPAPER.md, explaining how the RI is calculated, how fees are discounted, and how inactivity decay and identity gating are enforced.
Produces cryptographic proof of participation, enabling users to prove the legitimacy of savings to off-chain institutions.
cargo build --target wasm32-unknown-unknown --release- Protected Main: Requires a passing integration test suite.
- Audit Labels: Logic changes require
audit-requiredtags.
- Hyper-Inflation: Validates protocol against extreme volumes (1e27 stroops).
- Graceful Exit: Ensures members can exit circles midway if a replacement is found.
- Liquidity Buffers: Validates reputation-based advance requests for early payouts.