Name: Kolo
Type: WhatsApp-Native Savings & Payments Platform
Platform: WhatsApp + Node.js Backend + Stellar Blockchain + Soroban Smart Contracts
Objective: Enable individuals, families, and community savings groups to create, manage, and participate in digital savings circles directly through WhatsApp, with transparent contributions and automated payouts powered by Stellar.
Target Users:
- Ajo/Esusu groups
- Community cooperatives
- Family savings groups
- Students
- Informal financial associations
- Small business contribution clubs
- Register using WhatsApp phone number
- Automatically create Stellar wallet
- Check wallet balance
- Send and receive USDC
- View transaction history
- Receive payment notifications
- Create savings groups
- Invite members through WhatsApp
- Join groups via invitation
- Define contribution amount
- Define contribution frequency
- Track member contributions
- View group savings progress
- Automated contribution reminders
- Automated payout distribution
- Monitor platform activity
- View active groups
- Manage users
- Review transaction logs
- Handle dispute reports
- Monitor smart contract performance
Provides user interaction through:
- Commands
- Interactive buttons
- Notifications
- Group invitations
Handles:
- Message delivery
- User communication
- Event webhooks
Responsible for:
- User management
- Wallet management
- Group management
- Transaction processing
- Smart contract interaction
Handles:
- Savings group creation
- Contribution tracking
- Payout execution
- Group state management
Provides:
- Settlement layer
- USDC transfers
- Transaction validation
Stores:
- User profiles
- Group metadata
- Transaction records
- Contribution history
graph TD
A[User sends message on WhatsApp] --> B[WhatsApp Business API receives request]
B --> C[Node.js backend processes command]
C --> D[Backend interacts with Soroban smart contract]
D --> E[Soroban updates group state]
E --> F[Stellar executes transaction]
F --> G[Backend returns confirmation to WhatsApp]
G --> H[User receives notification]
graph TD
A[Group Creator creates group] --> B[Members receive invitations]
B --> C[Members join group]
C --> D[Members contribute USDC]
D --> E[Contributions recorded in contract]
E --> F[Contribution status updated]
F --> G[Payout date reached]
G --> H[Soroban contract triggers payout]
H --> I[Recipient receives funds]
I --> J[Group records updated]
- WhatsApp Business Platform
- WhatsApp Cloud API
- Node.js
- Express.js
- TypeScript
- PostgreSQL
- Stellar Network
- Soroban Smart Contracts
- Rust
- soroban-sdk
- Stellar SDK
- WhatsApp Cloud API Webhooks
- Node.js >= 18.x
- PostgreSQL >= 14.x
- Redis (for BullMQ queue)
- npm or yarn
git clone https://github.com/Tobi-8/Kolo-Backend.git
cd Kolo-Backend
npm installCreate a .env file in the project root:
PORT=3000
WHATSAPP_TOKEN=your_whatsapp_token
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
WHATSAPP_APP_SECRET=your_app_secret
VERIFY_TOKEN=kolo_verify_token
DATABASE_URL=postgresql://user:password@localhost:5432/kolo_db
STELLAR_NETWORK=TESTNET
REDIS_URL=redis://localhost:6379
ENCRYPTION_KEY=your_32_byte_hex_string# Create PostgreSQL database
createdb kolo_db
# Run Prisma migrations
npx prisma migrate deploy
# (Optional) Seed initial data
npx prisma db seed# Development
npm run dev
# Production
npm start- WhatsApp onboarding
- Wallet creation
- Balance inquiry
- Transaction history
- Create group
- Join group
- Invite members
- Contribution tracking
- USDC transfers
- Automated payouts
- Contribution reminders
- Payout confirmations
- Rotational savings pools (Ajo/Esusu)
- Goal-based savings
- Emergency funds
- Community lending
- Merchant payments
- Bill payments
- Airtime purchases
- Utility payments
- Referral rewards
- Group leaderboards
- Savings achievements
- Multiple stablecoins
- Local currency on/off ramps
- Cross-border remittances
- Encrypted wallet storage
- Secure webhook validation
- Transaction signing verification
- Smart contract validation
- Keep wallet generation out of logs and minimize secret lifetime in memory
When deploying wallet-generation code in production:
- Disable core dumps with
ulimit -c 0 - Disable crash dump collection in the container runtime or host OS
- Prefer an isolated key-management service for final wallet custody
- Never log
secretvalues or derived wallet payloads - Review memory-dump settings after OS, container, and base-image upgrades
- Phone number verification
- KYC integration (future phase)
- AML monitoring (future phase)
- Transaction audit logs
- Cache frequently accessed group data
- Optimize Soroban contract storage
- Queue transaction processing
- Implement webhook retry mechanisms
- Monitor Stellar network fees
- Response time < 3 seconds
- Payment settlement < 5 seconds
- Support 10,000+ users
- Support 1,000+ active savings groups
- Unit tests for APIs
- Wallet service tests
- Group management tests
- Soroban contract unit tests
- Contribution validation tests
- Payout execution tests
Full workflow:
User Registration
↓
Wallet Creation
↓
Group Creation
↓
Member Contribution
↓
Automated Payout
↓
Transaction Verification
- Concurrent user activity
- High-volume contribution periods
- Group payout events
Deploy on:
- AWS
- DigitalOcean
- Railway
- PostgreSQL Managed Service
- Stellar Testnet (Development)
- Stellar Mainnet (Production)
Deploy Soroban contracts:
- Testnet
- Mainnet
- WhatsApp Cloud API
- Webhook Infrastructure
- Application Logs
- Stellar Transaction Monitoring
- Smart Contract Monitoring
- Error Tracking
- Registered users
- Active users
- Retention rate
- Groups created
- Active groups
- Average members per group
- Total savings volume
- Total contribution volume
- Total payouts processed
- Transaction success rate
- Smart contract execution success rate
- Average response time
BALANCE
HISTORY
PROFILE
SEND 10 @john
REQUEST 20 @mary
CREATE GROUP
JOIN GROUP
INVITE MEMBER
GROUP STATUS
CONTRIBUTE
WITHDRAW
HELP
SUPPORT