Parametrix — Oracle-Driven Parametric Risk Pools on Cardano

Parametrix is a decentralized RealFi protocol for hedging real-world economic risks, where measurable events are resolved via Charli3 → enabling instant, trustless payouts.

Flow: Create → Subscribe → Oracle Resolve → Deterministic Settlement

---

Architecture (High-Level)

• Contracts (Aiken) → on-chain validation via Aiken
• Offchain CLI (Deno + Mesh) → tx orchestration (subscribe / settle)
• Oracle Updater (FastAPI) → fetches, aggregates, submits oracle updates
• Frontend (Next.js) → pool creation + interaction via Next.js

---

Demo Video

▶️ https://youtu.be/L75BTf7UHl4

---

Repository Structure

.
├── contracts
│   ├── aiken        # on-chain validators
│   └── meshjs       # tx building / integration
├── oracle-updater   # FastAPI oracle refresh service
└── parametrix-fe    # Next.js frontend dApp

---

⚠️ Configuration Checklist

Before running the project, ensure the following files are correctly configured:

contracts/meshjs/blockchainProvider.ts
contracts/meshjs/<wallet>.json
charli3-meshjs/.env.test
parametrix-fe/lib/blockchainProvider.ts

Verify the following

• Blockfrost / network configuration is correct
• Wallet JSON contains valid keys and is funded (ADA + DJED)
• Environment variables in .env.test are properly set
• Frontend and backend providers point to the same network (e.g., preprod)

Ensure plutus.json is built and copied to all required import locations (e.g., frontend lib/) before running, otherwise contract interactions will fail.

---

End-to-End Run (Sequential)

Technical setup for dapp

flowchart LR

  A[Start Oracle Updater] --> B[Build Aiken Contracts]
  B --> C[Copy plutus.json to Frontend]
  C --> D[Start Frontend]

Loading

Technical setup for dapp

flowchart LR

  E[Connect Wallet] --> F[Create Pool RAINFALL_EXCEEDED]

  F --> G[Pool Created and Premium Locked]

  G --> H1[Subscribe LP1 100 DJED]
  G --> H2[Subscribe LP2 150 DJED]

  H1 --> I[Pool Subscribed]
  H2 --> I

Loading

.

flowchart LR

  I[Settlement time] --> J[Refresh Oracle from UI]

  J --> L[Settle - Contract checks Oracle value and validity]

  L --> N{Event Occurred}

  N -->|Yes| O[Hedger gets coverage and LPs get premium]
  N -->|No| P[LPs get principal and premium]

  O --> Q[Settlement Complete]
  P --> Q

Loading

1. Start Oracle Updater (Refresh ODV Feed service)

cd oracle-updater

poetry env use /usr/bin/python3.11
poetry install

poetry run uvicorn app.main:app --reload --port 8000

Test API

Verify the API service is running:

curl http://localhost:8000/

Expected response:

{
  "status": "ok",
  "service": "oracle-updater"
}

---

2. Build Smart Contracts

cd contracts/aiken/parametrix

aiken check
aiken build

Copy contracts/aiken/parametrix/plutus.json → parametrix-fe/lib/plutus.json (required for frontend)

From project root:

cp contracts/aiken/parametrix/plutus.json parametrix-fe/lib/plutus.json

---

3. Run Frontend dApp (Pool Creation)

cd parametrix-fe

npm install && npm run build
npm start

Open: http://localhost:3000

In UI:

• Connect CIP-30 wallet (tested with Eternl)

• Create a pool:

  • Select event type: RAINFALL_EXCEEDED - This has been tested.
  • Other fields are prefilled for demo

• Submit transaction → pool initialized on-chain

---

4. Subscribe + Settle execution via CLI

Frontend currently handles pool creation and ODV oracle refresh

Custom build MeshJS based typescript CLI is used for subscription and settlement. UI integration for these endpoints need refinement.

Prerequisites:

• Deno installed
• Wallet JSON (mnemonic array)
• Funded wallet (ADA + DJED)
• Blockfrost key for Preprod access

---

Proceed after pool creation:

cd contracts/meshjs

Subscribe to Pool

deno run -A parametrix.ts subscribe <wallet.json> <poolId> <amount> DJED

deno run -A parametrix.ts subscribe wallet_7.json ce2-1776576767850 100 DJED

deno run -A parametrix.ts subscribe wallet_8.json ce2-1776576767850 150 DJED

Update Oracle (Required before settlement)

Use the Frontend UI → click "Refresh Oracle" Wait for success response and oracle details to be displayed in the UI

You can also view created pools, their subscription status, and other details directly in the frontend UI

Settle Pool

deno run -A parametrix.ts settle <wallet.json> <poolId> DJED
```bash

deno run -A parametrix.ts settle wallet_0.json ce2-1776576767850 DJED

---

Example Flow (Demo)

1. Start Oracle Updater

oracle-updater > poetry run uvicorn app.main:app --reload --port 8000
INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     Application startup complete.

---

2. Build & Verify Contracts

parametrix > aiken check
... 16 checks | 0 errors

parametrix > aiken build
... Generating project's blueprint (./plutus.json)

---

3. Start Frontend

parametrix-fe > npm start
✓ Ready in 673ms

Open UI → connect wallet → create pool (RAINFALL_EXCEEDED)

A hedger initializes a rainfall protection pool with the following parameters:

• Coverage: 250 DJED
• Threshold: 100
• Location: JAKARTA_ID
• Premium: 1000 bps

Story:

I am a crop farmer and my harvest season is approaching. Excess rainfall can damage yield and impact income. I am seeking protection against heavy rainfall during this period.

On submission, the pool is created on-chain:

• poolId: ce2-1776576767850
• txHash: 1919c1044b000938831a9d3a8c2e48da4e537f1599fe5834b58565b3cb1c7b10
• poolAddress: addr_test1wr8lp4skdx4fg4t93xwxewjadyfj9w3as58awg6jtw6emdqacv8y4

Premium is locked in the script and the pool is now open for subscriptions.

---

4. Subscribe (CLI)

Two LPs underwrite the pool:

meshjs > deno run -A parametrix.ts subscribe wallet_7.json ce2-1776576767850 100 DJED

=== SUBSCRIBED ===
Tx Hash: a70caa7b346d7d6a055cad2f7cb721b9969b2d45923153395bdae9a7e43938d5
Pool ID: ce2-1776576767850
Deposited: 100000000
Minted sPMX: 100
==================

meshjs > deno run -A parametrix.ts subscribe wallet_8.json ce2-1776576767850 150 DJED

=== SUBSCRIBED ===
Tx Hash: 7c215388a4dfa06ca01c822ff923256665529c8986bb5684a5fb3ca200b964f1
Pool ID: ce2-1776576767850
Deposited: 150000000
Minted sPMX: 150
==================

---

5. Oracle Update (Frontend)

Click "Refresh Oracle" in UI → oracle tx submitted

---

6. Settle (CLI)

meshjs > deno run -A parametrix.ts settle wallet_0.json ce2-1776576767850 DJED
[C3] Fetching UTxOs...
{ price: 0.2481, timestamp: 1776577770000, expiry: 1776578370000 }

SETTLEMENT CRITERIA
eventOccurred: true
event_type: RAINFALL_EXCEEDED
event_threshold: 100
scale oracle_price metric: 248100

--- paylouts ---
addr_test1... 10000000
addr_test1... 15000000
addr_test1... 250000000
========================

=== SETTLED ===
Tx Hash: ce7275d3857b6dd391e4fb2a80c7c7e51f78938e8c661d06eb698a900de39f01
Risk event occurred: true
================

---

Offchain CLI Module

• Built with Mesh SDK

• Uses compiled Aiken validators (plutus.json)

• Handles:

  • Subscription (liquidity provision)
  • Settlement (oracle evaluation + payouts)

---

Oracle API Service (FastAPI wrapper over Charli3 ODV Pull Client)

• /oracle/feeds → signed node data (debug)
• /oracle/aggregate → fetch → aggregate → build → submit tx

---

Key Design Decisions

• No claims layer → oracle is truth
• Deterministic settlement → price > threshold
• Reference inputs → efficient oracle reads
• CLI for critical flows → precise execution control
• Modular architecture → FE / CLI / oracle separation

---

What This Demonstrates

• Real-world data → on-chain execution
• Autonomous insurance primitive
• Composable risk markets on Cardano

---

A tagline

Hedge real-world uncertainty, on-chain.

Dependencies / Frameworks Used

• Aiken (smart contract development)
• Vodka (aiken helper lib)
• MeshJS (transaction building and off-chain integration)
• Charli3 ODV Pull Oracle Client
• FastAPI (oracle updater backend)
• Next.js (frontend)
• Deno (CLI execution)
• Blockfrost/Kois (API access)

Future Scope

• Contract Hardening

  • Expand test coverage (edge cases, boundary conditions)
  • Stress-test oracle validity, expiry, and malformed data handling

• Full UI Integration

  • Enable subscribe and settle flows directly from frontend
  • Remove CLI dependency for end users

• Custom Oracle Feeds

  • Support domain-specific feeds (weather APIs, flight data, etc.)
  • Map oracle values → real-world event semantics more explicitly

• KYC Layer (RealFi Readiness)

  • Integrate identity verification (e.g. Veridian)
  • Enable compliant participation for regulated use cases

• Partnerships & Deployment

  • Collaborate with data providers (weather, travel, etc.)
  • Launch pilot pools with real-world partners

• UI / UX Improvements

  • Better pool visualization (status, coverage, timelines)
  • Clearer transaction feedback and error states
  • Simplified onboarding for non-technical users