Architecture
How Mvua is built
Mvua is five Soroban contracts on Stellar plus a thin web layer. Funds, policy terms, data intake, the index decision and payout are separate concerns with separate contracts, so a defect in one cannot silently corrupt another.
The five contracts
Capital
risk-poolHolds premiums and liquidity provider capital in USDC, split across a junior tranche that takes first loss and a senior tranche that is protected. It moves a season through Open, Active, Closed and Settled, collects premiums against a capped protocol fee and applies an asymmetric settlement waterfall. Solvency is an enforced invariant, checked on chain, not a promise. Everything financial starts here.
Terms
policyMints a non fungible certificate for each purchase, carrying the coverage amount, region, coverage window and severity curve. A policy moves forward through a fixed state machine: Active to Triggered to Paid on a claim, Active to Expired after the window, or Active to Cancelled before it opens. The contract holds no value itself: premiums flow into the risk pool and refunds flow back out. Off chain metadata is kept as an opaque pointer, so no personally identifying information is ever stored on chain.
Data
oracle-adapterThe protocol's trust boundary for external weather data. Independent publishers submit signed observations; the adapter verifies each ed25519 signature directly, so a weather station never needs an on chain account. It returns only a median over fresh, unchallenged observations from at least two distinct publishers; anything less is reported as stale. The trigger engine consumes only this trusted median, never a raw single submission.
Decision
trigger-engineEvaluates index definitions deterministically. All math is integer only, because Soroban has no floating point; every division states its rounding direction. The contract reads the median series and an immutable index definition and produces a severity in basis points. The rule is fixed before the season starts, so the same inputs always produce the same outcome.
Settlement
payout-vaultReleases payouts as resumable batches into Stellar claimable balances, so a farmer never needs XLM to receive money. It holds no funds of its own and makes no decisions: it pays exactly what the trigger engine reports, in a batch small enough to stay within the network's instruction limits, resumable if a batch is larger than one transaction.
Two flows: buying cover and getting paid
Purchase flow
- 01
Deposit into the pool
A liquidity provider funds a regional risk pool. The junior tranche takes first loss and earns more; the senior tranche is protected and earns less.
- 02
Quote
A buyer or a cooperative requests a quote for a region, window and coverage amount. The price comes from the pool's premium curve.
- 03
Mint
The purchase re-quotes, checks the price against the buyer's maximum, collects the premium into the risk pool and mints an Active certificate.
- 04
Batch purchase
A cooperative funds a bounded list of policies in one atomic call, each owned by its own farmer, split across calls if the group is large.
Payout flow
- 01
Observe
Through the season, publishers submit signed daily rainfall readings for the region, straight to the oracle adapter.
- 02
Aggregate and challenge
The adapter builds a median series. Guardians have a challenge window to exclude a bad reading before it is trusted.
- 03
Evaluate
At window end the trigger engine reads the median series against the policy's index definition and computes a severity in basis points.
- 04
Pay
If the index qualifies, the payout vault releases each policy's payout into a claimable balance. No claim is filed and no adjuster is involved.
The trust model
The protocol is designed so that every money decision is a function of public inputs: the signed rainfall readings, the index definition and the policy terms. This section names exactly where trust is required and how it is bounded.
The app holds no funds
The web interface reads state and submits signed transactions. Capital lives in the on chain pool and vault, under the rules the contracts enforce. A compromised app can annoy users; it cannot move their money.
No single reading decides
The median requires at least two distinct publishers. One bad or dishonest publisher cannot move the index; a forged signature fails verification outright.
Terms are fixed, then immutable
An index definition cannot change once policies reference it. Changing the maths means a new index id behind a timelock, so a sold policy keeps the terms it was sold under.
Fresh or nothing
A day whose data is older than the staleness bound, or backed by fewer than the minimum publishers, is reported as stale. A stale index blocks a trigger; it never fires one.
A window to object
After a reading is submitted, guardians can challenge it and exclude it from the median. This gives honest parties time to catch and remove a bad reading before it settles.
A window to cancel
Adding a publisher's key sits behind a timelock, so if a key is compromised there is a cancellation window before it can publish. Removing a key deactivates it, so past observations keep a resolvable author.
What remains trusted
Two things are still trusted and named openly. First, the guardians, who hold the ability to challenge readings, pause and propose publishers; the design limits what they can do; it gives the community a cancellation window, but it does not pretend the role is empty. Second, the data sources themselves. Mvua reads rainfall from public feeds and from the publisher service; the median and challenge window reduce reliance on any one source, but they cannot make a wrong world record right.
Index science
The index is the contract. Mvua starts with two definitions, both integer only and both fixed before the season. A trigger is not all or nothing: a severity curve scales the payout from zero at the trigger point to full at the exhaustion point, which softens the edge where a season barely fails and reduces basis risk.
Index 1: rainfall shortfall
Fires when cumulative rainfall over the coverage window falls far enough below the historical baseline for that window.
| Parameter | Meaning | Provisional value |
|---|---|---|
| baseline | Historical seasonal rainfall for this region and window | fixed per region and window |
| trigger_ratio | Fires when actual is below this share of baseline | 7,500 bps (75 percent) |
| exhaustion_ratio | Full payout at or below this share of baseline | 4,000 bps (40 percent) |
Index 2: consecutive dry days
Fires when the longest run of consecutive dry days within the window reaches a threshold. A day counts as dry when its median rainfall is at or below a small floor, provisionally 1.0 mm. The trigger is a run of 21 days; full payout is reached at 35 days.
How severity becomes a payout
Once triggered, severity scales linearly from zero to full. The per policy payout is the coverage multiplied by the severity fraction, rounded down to favor the pool. The curve is monotonic: a worse index never yields a smaller payout and severity is clamped, so a payout can never exceed the coverage a policy bought.
Golden test vectors
These fixed cases pin the maths. They are the source of truth for the trigger engine's unit tests, so the on chain behaviour can never drift from the specification without a failing test.
| Case | Index | Inputs | Expected |
|---|---|---|---|
| G1 | Rainfall shortfall | baseline 800, actual 800 | ratio 10,000, not triggered |
| G2 | Rainfall shortfall | baseline 800, actual 600 | ratio 7,500, not triggered (boundary) |
| G3 | Rainfall shortfall | baseline 800, actual 520 | ratio 6,500, triggered, severity 2,857 bps |
| G4 | Rainfall shortfall | baseline 800, actual 320 | ratio 4,000, triggered, severity 10,000 bps |
| G5 | Consecutive dry days | longest run 20 | not triggered |
| G6 | Consecutive dry days | longest run 21 | triggered, severity 0 bps (boundary) |
| G7 | Consecutive dry days | longest run 28 | triggered, severity 5,000 bps |
| G8 | Consecutive dry days | longest run 35 | triggered, severity 10,000 bps |
G2 is the boundary: the trigger test is strict, so exactly 75 percent does not fire. G6 is the other edge, a triggered index at zero severity, which is intentional and documents the lower end of the curve.
Basis risk, stated honestly
An index can disagree with any single farm's real outcome. Rain may fall on a neighbouring field and miss yours. Mvua's mitigation is regional granularity, index design that is documented openly and a severity curve rather than a cliff. This is a real limitation of parametric insurance, not a defect specific to Mvua; it is the main reason the index parameters are backtested before any pool relies on them.