# Veritas Protocol

> Veritas Protocol is a binary prediction market protocol deployed on Arbitrum Sepolia. Users trade YES/NO outcomes across crypto, sports, weather, economic, commodity, and DeFi markets with on-chain settlement and yield-aware liquidity mechanics.

## Summary

Veritas combines an automated market maker (AMM) with an on-chain central limit order book (CLOB) for binary outcome trading, plus a next-gen Paradigm pm-AMM engine (VPME) with Gaussian CDF pricing and senior/junior LP tranches. Markets settle on-chain through oracle-based resolution. The protocol also includes permissionless market creation through Ignition and a treasury routing system for collateral management.

## Core Capabilities

- Binary prediction markets with YES/NO positions
- Hybrid execution through AMM liquidity and CLOB limit orders
- On-chain settlement via 8 oracle types (Chainlink, Binance, ESPN, Open-Meteo, FRED, Gold API, DeFiLlama, UMA Optimistic Oracle)
- Permissionless market creation through Ignition
- Treasury routing for idle collateral
- Yield distribution mechanics tied to reserves, gravity pool, and position yield

## Main Components

### v0.3.0 Core
- `VeritasFactory`: deploys and manages v0.3.0 markets
- `VeritasMarket`: market contract for AMM trading, LP accounting, and settlement
- `VeritasOrderBook` (OrderBook): on-chain order book for limit orders
- `VeritasDutchAuction` (DutchAuction): dutch auction mechanism for price discovery
- `SettlementManager`: settlement coordination across markets
- `VeritasIgnition`: permissionless market launch with virtual bonding curves
- `VeritasTreasuryRouter` (TreasuryRouter): routes idle USDC to yield-generating protocols
- `MorphoBondAdapter`: ERC-4626 style adapter for external yield routing

### VPME (v0.4.0) — Paradigm pm-AMM
- `VPMEBinaryMarket`: binary market with real Paradigm pm-AMM pricing (cost-function execution via Newton's method)
- `VPMEQuoteMath`: Gaussian CDF pricing — P=Φ(z), pool value V=L·φ(Φ⁻¹(P)), dynamic liquidity L_t=L₀·√T
- `VPMERiskController`: 4-mode risk system (Discovery → Guarded → Stressed → HardFloor)
- `VPMEYieldSidecar`: fee accounting (0.7% LP + 0.3% gravity + 0.5% protocol, coverage-gated)
- `VPMETrancheVault`: senior/junior LP capital with waterfall settlement (senior-first capital return)
- `VPMEFactory`: deploys full VPME market stacks with shared risk controller

### Oracles (8 types)
- `ChainlinkOracle`: crypto market oracle (ETH/USD, BTC/USD, ARB/USD)
- `CryptoOracle`: crypto price oracle (15 tokens via Binance API)
- `SportsOracle`: sports market oracle (ESPN, TheSportsDB)
- `WeatherOracle`: weather market oracle (Open-Meteo: 12 cities, 5 metrics)
- `EconomicOracle`: macro indicator oracle (FRED API: 10 series)
- `CommodityOracle`: commodity price oracle (Gold API: XAU, XAG, XPT, XPD, HG)
- `DefiOracle`: DeFi metrics oracle (DeFiLlama: TVL, DEX volume, stablecoin mcap)
- `UMAOracle`: UMA Optimistic Oracle V3 adapter (assert-challenge-resolve)

## Network And Stack

- Network: Arbitrum Sepolia
- Chain ID: `421614`
- Frontend: React, Vite, wagmi, viem, RainbowKit
- Smart contracts: Solidity, Hardhat
- Collateral asset: USDC on testnet deployment

## Market Categories

- Crypto Prices: BTC, ETH, SOL, LINK and 15+ tokens (Chainlink + Binance)
- Sports: match outcomes across major leagues (ESPN, TheSportsDB)
- Weather: temperature, rainfall, wind thresholds (Open-Meteo)
- Economic: GDP, CPI, unemployment, Fed rates, Treasury spreads (FRED API)
- Commodities: gold, silver, platinum, palladium, copper (Gold API)
- DeFi: protocol TVL, chain TVL, DEX volume, stablecoin market cap (DeFiLlama)
- Custom (UMA): permissionless binary claims resolved via UMA Optimistic Oracle V3

## Trading And Fees

Users buy YES or NO exposure with USDC.

Prices are determined by AMM reserves and available order book liquidity.

Trading fee: `1.5%` total, split as:

- `0.7%` to LP reserves (inverse-weighted: minority reserve gets more)
- `0.3%` to the gravity pool (distributed to LPs at settlement)
- `0.5%` to protocol treasury

## Ignition

Ignition is the permissionless market creation system.

- A proposer pays $50 USDC to create a market question
- The market begins in a virtual bonding curve phase (constant-product virtual reserves)
- Graduation requires $10,000 TVL and 30 unique participants before expiry (~30 days)
- On graduation: live AMM/CLOB market is deployed, early backers receive LP shares vested linearly over 14 days
- If thresholds are not met by expiry, participants get 100% USDC refund. Only the $50 proposal fee is retained by the protocol.

## Yield Mechanics

Veritas models multiple yield paths:

- LP reserve fee allocation
- Gravity pool accumulation and distribution
- Position-yield distribution sourced from treasury routing / harvest flows

RWA-style harvest yield is distributed to position-yield pools rather than to the gravity pool.

On testnet, yield is simulated at 4% APY via MockBondAdapter. On mainnet, this will connect to Morpho ERC-4626 lending vaults for real yield generation.

Pre-settlement: 50% of position yield is immediately claimable, 50% retained as completion bonus. Post-settlement: 100% claimable. Losing position holders forfeit position capital but keep all accrued yield.

## Status

- Current deployment status: testnet
- Current network: Arbitrum Sepolia
- Version: v0.4.0 (v0.3.0 core + VPME + UMA)
- Test suite: 618 smart contract tests (407 core + 148 VPME + 18 factory + 10 gas bench + 35 VSLH + 18 UMA), 91% statement coverage
- Keepers: 8 PM2 processes (settlement, sports, weather, economic, commodity, crypto, defi, uma)
- VPME gas: buyYes 196k (warm), settle 126k, redeem 42k, LP deposit 68k

## Canonical Links

- Website: https://veritas-mocha-two.vercel.app/
- Protocol overview: https://veritas-mocha-two.vercel.app/protocol
- Docs: https://veritas-mocha-two.vercel.app/docs
- Markets: https://veritas-mocha-two.vercel.app/markets
- Ignition: https://veritas-mocha-two.vercel.app/ignition
- GitHub: https://github.com/amaurydalleur-vh/Veritas
- Subgraph: https://api.studio.thegraph.com/query/1744349/veritas/v0.4.3-ignition-v2
- Machine-readable facts: https://veritas-mocha-two.vercel.app/protocol-facts.json