SafiGuard Smart Contracts

Soroban smart contracts powering the SafiGuard parametric micro-insurance platform on Stellar.

Overview

SafiGuard provides automated crop and weather insurance for underserved agricultural communities in Africa and Latin America. These smart contracts handle policy management, risk pooling, automated payouts, oracle data consumption, and on-chain governance.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    SafiGuard Contracts                    │
├──────────────┬──────────────┬──────────────┬────────────┤
│              │              │              │            │
│  Weather     │  Risk        │  Payout      │  Oracle    │
│  Policy      │  Pool        │  Engine      │  Consumer  │
│              │              │              │            │
│  - Purchase  │  - Deposit   │  - Process   │  - Submit  │
│  - Premium   │  - Withdraw  │  - Graduated │  - Median  │
│  - Trigger   │  - Shares    │  - Batch     │  - Verify  │
│  - Cancel    │  - APY       │  - Severity  │  - Stale   │
│  - Expire    │  - Reserve   │    levels    │    detect  │
│              │              │              │            │
├──────────────┴──────────────┴──────────────┴────────────┤
│                      Governance                          │
│           Proposals  ·  Voting  ·  Execution             │
└─────────────────────────────────────────────────────────┘
                            │
                    Stellar Network

Contracts

Contract	Description	Key Functions
weather-policy	Manages insurance policies for weather events	purchase_policy, calculate_premium, trigger_payout, cancel_policy
risk-pool	Liquidity pool for underwriting policies	deposit, withdraw, receive_premium, release_payout, calculate_apy
payout-engine	Processes graduated payouts based on severity	process_payout, calculate_multiplier, batch_process
oracle-consumer	Aggregates weather data from multiple operators	submit_data, get_latest_report, register_operator
governance	On-chain governance for protocol parameters	create_proposal, vote, finalize_proposal

Graduated Payout Schedule

Severity Level	Severity Range	Payout Percentage
Low	0% - 25%	25% of coverage
Medium	25% - 50%	50% of coverage
High	50% - 75%	75% of coverage
Critical	75% - 100%	100% of coverage

Premium Calculation

Premium = Coverage × BaseRate × RiskMultiplier × SeasonFactor × LoadingFactor

Where:
  BaseRate        = 5.00% (configurable via governance)
  RiskMultiplier  = 1.00x (varies by region and coverage type)
  SeasonFactor    = 1.00x (varies by growing season)
  LoadingFactor   = 1.05x (5% operational loading)

Prerequisites

• Rust (stable toolchain)
• Soroban CLI
• wasm32-unknown-unknown target: rustup target add wasm32-unknown-unknown

Build

# Build all contracts
cargo build --release --target wasm32-unknown-unknown

# Build a specific contract
cargo build --release --target wasm32-unknown-unknown -p safiguard-weather-policy

Test

# Run all tests
cargo test --workspace

# Run tests for a specific contract
cargo test -p safiguard-weather-policy

# Run with output
cargo test --workspace -- --nocapture

# Run the full test suite with linting
./scripts/test.sh

Deploy

# Deploy to testnet
./scripts/deploy.sh testnet

# Deploy to mainnet
./scripts/deploy.sh mainnet

Contract Interaction Examples

# Initialize weather policy contract
stellar contract invoke \
  --id $WEATHER_POLICY_ID \
  --source deployer \
  --network testnet \
  -- initialize \
  --admin $ADMIN_ADDRESS \
  --oracle_contract $ORACLE_ID \
  --risk_pool_contract $RISK_POOL_ID \
  --payout_engine_contract $PAYOUT_ENGINE_ID

# Calculate premium for a policy
stellar contract invoke \
  --id $WEATHER_POLICY_ID \
  --source deployer \
  --network testnet \
  -- calculate_premium \
  --coverage_amount 10000000000 \
  --region_id 1 \
  --coverage_type 0

# Submit oracle weather data
stellar contract invoke \
  --id $ORACLE_ID \
  --source operator1 \
  --network testnet \
  -- submit_data \
  --operator $OPERATOR_ADDRESS \
  --region_id 1 \
  --temperature 2800 \
  --rainfall 4500 \
  --humidity 6500 \
  --wind_speed 1200

Project Structure

safiguard-contracts/
├── Cargo.toml                    # Workspace configuration
├── contracts/
│   ├── weather-policy/
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs            # Contract entry point
│   │       ├── types.rs          # Data types and storage keys
│   │       ├── errors.rs         # Error definitions
│   │       ├── events.rs         # Event emission helpers
│   │       └── test.rs           # Unit tests
│   ├── risk-pool/
│   │   └── src/ ...
│   ├── payout-engine/
│   │   └── src/ ...
│   ├── oracle-consumer/
│   │   └── src/ ...
│   └── governance/
│       └── src/ ...
├── scripts/
│   ├── deploy.sh                 # Deployment script
│   └── test.sh                   # Test runner
├── .github/
│   ├── workflows/ci.yml          # CI pipeline
│   ├── ISSUE_TEMPLATE/
│   └── PULL_REQUEST_TEMPLATE.md
├── CONTRIBUTING.md
├── LICENSE
└── CODE_OF_CONDUCT.md

Weather Trigger Conditions

Coverage Type	Trigger Condition	Measurement
Drought	Rainfall < 50mm/month	Monthly cumulative rainfall
Flood	Rainfall > 200mm/day	24-hour rainfall
Frost	Temperature < 2°C	Minimum daily temperature
Excessive Rain	Rainfall > 150mm/day	24-hour rainfall

Oracle Consensus

The oracle system uses a 2-of-3 multi-operator consensus mechanism:

• At least 2 operators must submit data within the staleness window
• Values are aggregated using median calculation to resist outliers
• Data sources: Open-Meteo API, CHIRPS satellite data, NASA POWER

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see LICENSE for details.

Links

• SafiGuard Frontend
• SafiGuard Backend
• SafiGuard SDK
• SafiGuard Documentation