Loading data from network...
# Cosave — Autonomous Savings Circles
Cosave automates African rotating savings groups (Ajo/Esusu/Susu) using Celo Sepolia testnet stablecoins, smart contracts, and an AI coordination agent.
## What’s Included
- React + Vite frontend with TailwindCSS v3
- Wallet connection (Privy + wagmi + viem)
- AjoPool + AjoFactory smart contracts (Solidity + Hardhat)
- AI orchestration server (Express + OpenAI API)
- Group dashboard, contribution flow, and AI chat UI
## Project Structure
```
contracts/
AjoPool.sol
AjoFactory.sol
scripts/
deploy.js
server/
index.js
src/
components/
ChatAgent.jsx
ContributionPanel.jsx
CreateGroupForm.jsx
GroupCard.jsx
Privy.jsx
hooks/
useAjoContract.js
useGroups.js
useWallet.js
pages/
Dashboard.jsx
GroupDetails.jsx
Home.jsx
services/
aiAgent.js
blockchain.js
utils/
constants.js
helpers.js
```
## Setup
1. Install dependencies
```
yarn
```
2. Configure environment variables
```
cp .env.example .env
```
Update values for:
- `VITE_PRIVY_APP_ID`
- RPC URLs and `PRIVATE_KEY` for Hardhat
- `OPENAI_API_KEY`
- Stablecoin contract address for your target network
- Deployed factory address
3. Run the frontend + AI server
```
yarn dev:all
```
Frontend: `http://localhost:5173`
AI Server: `http://localhost:5050`
## Smart Contract Deployment
Compile and deploy the AjoFactory contract (one-time) with Hardhat:
```
yarn hardhat compile
STABLECOIN_ADDRESS=0x... yarn deploy:celo-sepolia
```
Copy the deployed factory address and paste it into `VITE_FACTORY_ADDRESS` in your `.env`.
## Demo Flow
1. Connect a wallet on Celo Sepolia
2. Deploy the AjoFactory contract (one-time)
3. Create a group in the dashboard (factory deploys a pool automatically)
4. Invite other wallets to join and contribute USDm
5. Execute payouts via the dashboard or AI chat agent
## AI Agent Notes
The AI endpoint converts natural language commands into structured JSON (create, join, contribute, check payouts). Use the floating assistant to test sample prompts.
## Deployment
- Frontend: `yarn build` and deploy the `dist/` folder to Vercel, Netlify, or a static host.
- Backend: Deploy `server/index.js` to a Node host (Render, Railway, Fly.io) with `OPENAI_API_KEY` set.
- Smart contracts: Deploy via Hardhat using a funded Celo Sepolia wallet.
## Security & Production Notes
- Always verify stablecoin addresses for each testnet.
- Use a dedicated deployer wallet with minimal funds.
- For production, move AI orchestration to a secure backend and add request authentication.
---
Built for the Cosave hackathon MVP.
\n## Demo Mode (No Keys Needed)\nSet VITE_DEMO_MODE=true in your .env to run the UI without Privy, RPC, or OpenAI keys. The app will simulate wallet balance and on-chain actions for demo purposes.\n
\n## Privy Setup\nCreate a Privy app and copy the App ID into VITE_PRIVY_APP_ID in your .env.\n