Parametric insurance protocol on Stellar with automated payouts
____ _ _ _ ___
/ ___|| |_ ___| | | __ _ _ _|_ _|_ __ ___ _ _ _ __ ___
\___ \| __/ _ \ | |/ _` | '__| || '_ \/ __| | | | '__/ _ \
___) | || __/ | | (_| | | | || | | \__ \ |_| | | | __/
|____/ \__\___|_|_|\__,_|_| |___|_| |_|___/\__,_|_| \___|
Traditional insurance has fundamental issues:
- Slow Claims Processing: Takes weeks or months for payouts
- Trust Issues: Insurers can deny claims arbitrarily
- High Overhead: Administrative costs eat into premiums
- Limited Access: Many people excluded from coverage
- Lack of Transparency: Opaque processes and fine print
StellarInsure is a parametric insurance protocol where:
- Payouts are automatic based on verifiable events
- Smart contracts eliminate trust requirements
- Transparent on-chain policy terms
- Fast claims processed in minutes, not weeks
- Low fees with minimal overhead
Unlike traditional insurance that requires claim assessment, parametric insurance pays out automatically when predefined conditions are met:
Traditional Insurance:
Event → File Claim → Investigation → Assessment → (Maybe) Payout
Time: Weeks to months
Parametric Insurance:
Event → Oracle Verification → Automatic Payout
Time: Minutes to hours
| Type | Trigger Example | Use Case |
|---|---|---|
| Weather Insurance | Temperature < 0°C or Rainfall > 100mm | Crop protection, event cancellation |
| Flight Delay Insurance | Flight delayed > 2 hours | Travel protection |
| Smart Contract Insurance | Contract exploit detected | DeFi protocol coverage |
| Asset Insurance | Asset price drops > 20% | Portfolio protection |
| Health Events | Hospital admission | Medical expense coverage |
| Feature | Description |
|---|---|
| Parametric Policies | Create policies with automated trigger conditions |
| Oracle Integration | Verify real-world events via decentralized oracles |
| Instant Payouts | Automatic claims processing when conditions met |
| Risk Pools | Liquidity providers earn premiums from underwriting |
| Multi-Asset Support | Insure various assets and events |
| Transparent Terms | All conditions encoded on-chain |
┌─────────────────────────────────────────────────────────────────┐
│ FRONTEND (Next.js) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Create │ │ Browse │ │ Submit │ │Dashboard │ │
│ │ Policy │ │ Policies │ │ Claim │ │ │ │
│ └────┬─────┘ └─────┬────┘ └─────┬────┘ └────┬─────┘ │
└───────┼──────────────┼─────────────┼────────────┼──────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ SOROBAN SMART CONTRACTS │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ StellarInsure Protocol │ │
│ │ • create_policy() • pay_premium() │ │
│ │ • submit_claim() • process_claim() │ │
│ │ • cancel_policy() • get_policy() │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Risk Pools │ │
│ │ • deposit() • withdraw() • distribute_premium() │ │
│ │ • payout() • get_balance() • calculate_yield() │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ ORACLE NETWORK │
│ ┌────────────┐ ┌─────────────┐ ┌──────────────┐ │
│ │ Weather │ │ Flight │ │ Smart Contract│ │
│ │ Data │ │ Data │ │ Monitoring │ │
│ └─────┬──────┘ └──────┬──────┘ └──────┬───────┘ │
│ └─────────────────┴────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ BACKEND SERVICES │
│ ┌────────────┐ ┌─────────────┐ ┌──────────────┐ │
│ │ Event │ │ REST API │ │ Oracle │ │
│ │ Indexer │ │ (FastAPI) │ │ Relayer │ │
│ └─────┬──────┘ └──────┬──────┘ └──────┬───────┘ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ PostgreSQL + Redis Cache │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Policy: Protect crop yield against drought
Trigger: Rainfall < 50mm in growing season
Coverage: 10,000 XLM
Premium: 500 XLM
Payout: Automatic when oracle confirms low rainfall
Policy: Flight delay protection
Trigger: Flight delayed > 2 hours
Coverage: 200 XLM
Premium: 10 XLM
Payout: Automatic using flight tracking API
Policy: Protocol exploit protection
Trigger: Security incident detected
Coverage: 100,000 XLM
Premium: 5,000 XLM
Payout: Compensates users for losses
Policy: Protect against stablecoin de-pegging
Trigger: USDC price < $0.95
Coverage: 50,000 XLM
Premium: 1,000 XLM
Payout: Automatic when price oracle confirms
| Layer | Technology |
|---|---|
| Blockchain | Stellar Soroban (Rust) |
| Frontend | Next.js 14, TypeScript, Tailwind CSS |
| Wallet | Freighter Wallet Integration |
| Backend | FastAPI (Python), PostgreSQL, Redis |
| Oracles | Chainlink (future), Custom Oracle Network |
| Infrastructure | Docker, Kubernetes |
- Node.js v18+
- Rust & Cargo
- Soroban CLI
- Docker & Docker Compose
- Freighter Wallet Extension
# Clone the repository
git clone https://github.com/faithorji/StellarInsure.git
cd StellarInsure
# Setup Smart Contracts
cd smartcontract
cargo build --release --target wasm32-unknown-unknown
# Deploy to testnet
soroban contract deploy \
--wasm target/wasm32-unknown-unknown/release/stellarinsure.wasm \
--network testnet
# Setup Frontend
cd ../frontend
npm install
npm run dev
# Setup Backend
cd ../backend
pip install -r requirements.txt
python src/main.py
### Using Docker (Recommended for Development)
A `docker-compose.yml` file is provided to quickly spin up the frontend, backend, PostgreSQL database, and Redis.
```bash
# Create a .env.docker file (or modify the provided template if necessary)
# then run:
docker-compose up --buildThis will start:
- Frontend on
http://localhost:3000 - Backend on
http://localhost:8000 - PostgreSQL & Redis locally for backend connections
---
## Kubernetes Deployment
Production-ready Kubernetes manifests are available under [`k8s/`](./k8s):
- `k8s/base`: backend/frontend deployments and services, PostgreSQL and Redis statefulsets, ingress with TLS, config and secret templates, and backend HPA.
- `k8s/overlays/staging`: staging-specific hostnames, image tags, and feature flags.
- `k8s/overlays/production`: production overlay.
Example apply commands:
```bash
kubectl apply -k k8s/overlays/staging
kubectl apply -k k8s/overlays/production
# Create weather insurance policy
soroban contract invoke \
--id <CONTRACT_ID> \
--network testnet \
-- create_policy \
--policyholder <ADDRESS> \
--policy-type Weather \
--coverage-amount 1000000000 \
--premium 50000000 \
--duration 2592000 \
--trigger-condition "rainfall < 50mm"- Connect Freighter Wallet
- Click "Create Policy"
- Select insurance type
- Set coverage amount and premium
- Define trigger conditions
- Submit and pay premium
Weather Insurance
- Temperature thresholds
- Rainfall/snowfall measurements
- Wind speed limits
- Natural disaster events
Flight Insurance
- Delay duration
- Cancellation events
- Route changes
- Airline-specific policies
Smart Contract Insurance
- Exploit detection
- Unusual transaction patterns
- Oracle manipulation
- Protocol failures
Premiums are calculated based on:
Premium = Base Rate × Risk Multiplier × Coverage Amount × Duration
Factors affecting premium:
- Historical event frequency
- Coverage duration
- Payout amount
- Oracle reliability
- Event Occurs: Real-world trigger condition met
- Oracle Verification: Decentralized oracles confirm event
- Automatic Processing: Smart contract validates claim
- Instant Payout: Funds transferred to policyholder
- Architecture Guide
- Smart Contract Documentation
- Oracle Integration Guide
- API Reference
- Frontend Guide
- Kubernetes Deployment Guide
- Staging Environment Guide
The Soroban contracts emit structured events for policy creation, premium payments, claim submission and processing, policy cancellation, and risk-pool liquidity activity. See Smart Contract Documentation for the full event list.
- Smart contracts pending audit before mainnet
- Oracle network independently verified
- Risk pool mechanics reviewed by actuaries
- Policies limited to prevent pool depletion
- Multi-oracle verification reduces manipulation
- Time delays on large payouts for safety
- Coming soon: Bug bounty program
- Report vulnerabilities: security@stellarinsure.io
- Core insurance smart contracts
- Policy creation and management
- Basic claim processing
- Oracle network integration
- Risk pool liquidity management
- Frontend MVP
- Testnet launch
- Actuarial risk modeling
- Mainnet launch
- Mobile app
- Advanced policy types
- DAO governance
We welcome contributions! See CONTRIBUTING.md for guidelines.
Areas Needing Help:
- Oracle integrations (Chainlink, custom)
- Actuarial modeling and risk assessment
- Frontend UX improvements
- Documentation and tutorials
- Policy type expansions
MIT License - see LICENSE for details.
StellarInsure is experimental software under active development. This is not financial advice. Insurance policies are subject to terms and oracle verification. Use at your own risk.
Building trustless, automated insurance for the Stellar ecosystem