Skip to content

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-pool

Holds 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

policy

Mints 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-adapter

The 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-engine

Evaluates 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-vault

Releases 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

  1. 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.

  2. 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.

  3. 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.

  4. 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

  1. 01

    Observe

    Through the season, publishers submit signed daily rainfall readings for the region, straight to the oracle adapter.

  2. 02

    Aggregate and challenge

    The adapter builds a median series. Guardians have a challenge window to exclude a bad reading before it is trusted.

  3. 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.

  4. 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.

ParameterMeaningProvisional value
baselineHistorical seasonal rainfall for this region and windowfixed per region and window
trigger_ratioFires when actual is below this share of baseline7,500 bps (75 percent)
exhaustion_ratioFull payout at or below this share of baseline4,000 bps (40 percent)
Provisional values
Every value marked provisional is a placeholder. A first calibration from 34 years of rainfall history in four candidate regions has been run through the real contracts, and it stays a proposal until a pool adopts it. The values are shown here so the mechanism is readable, not so they can be relied on as final.

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.

Worked example
Baseline seasonal rainfall 800 mm. Actual rainfall over the window 520 mm. The realized ratio is 520 / 800 = 6,500 bps, which is below the 7,500 bps trigger, so the index fires. Severity = (7,500 - 6,500) x 10,000 / (7,500 - 4,000) = 2,857 bps, rounding down. On a 100 USDC policy that is a payout of 28 USDC. At 400 mm the ratio is 4,000 bps, severity reaches 10,000 bps and the policy pays in full.

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.

CaseIndexInputsExpected
G1Rainfall shortfallbaseline 800, actual 800ratio 10,000, not triggered
G2Rainfall shortfallbaseline 800, actual 600ratio 7,500, not triggered (boundary)
G3Rainfall shortfallbaseline 800, actual 520ratio 6,500, triggered, severity 2,857 bps
G4Rainfall shortfallbaseline 800, actual 320ratio 4,000, triggered, severity 10,000 bps
G5Consecutive dry dayslongest run 20not triggered
G6Consecutive dry dayslongest run 21triggered, severity 0 bps (boundary)
G7Consecutive dry dayslongest run 28triggered, severity 5,000 bps
G8Consecutive dry dayslongest run 35triggered, 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.