About Diffusal
On-chain options DEX with Black-Scholes pricing
Welcome to the Diffusal documentation. Diffusal is a decentralized options exchange built for EVM-compatible blockchains, featuring real-time Black-Scholes option pricing with Pyth Network oracle integration.
Overview
Diffusal enables trustless options trading with:
- Black-Scholes Pricing — Industry-standard option pricing with full Greeks calculation
- Event-Based Order Book — Gas-efficient order registration with off-chain matching
- RFQ Trading — Direct trades with Main Market Makers for instant execution
- Oracle Integration — Real-time price feeds from Pyth Network
- On-chain Settlement — All trades settled via smart contracts
- Permissionless — Anyone can price and trade options
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ DiffusalOptionsQuoter │
│ ───────────────────────────────────────────────────────────── │
│ • Main entry point for option pricing │
│ • Black-Scholes calculations with Greeks │
│ • Human-readable pair name queries │
└───────────────────────────────┬─────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ DiffusalOracle (Unified) │
│ ───────────────────────────────────────────────────────────── │
│ • Volatility (σ), Premium rates, Risk-free rate (r) │
│ • Multi-source price aggregation (Pyth + Chainlink + Native) │
│ • Named pair registration with human-readable identifiers │
│ • Admin-controlled parameters via role-based access │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ DiffusalOptionsOrderBook │
│ ───────────────────────────────────────────────────────────── │
│ • Event-based limit order book (off-chain matching) │
│ • Orders registered via events (no on-chain storage) │
│ • Backend indexes events and maintains order book state │
│ • Dynamic tick precision (2-12 decimals) based on spot price │
│ • Protocol fee system (maker, taker fees with rebates) │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ DiffusalOptionsRFQ │
│ ───────────────────────────────────────────────────────────── │
│ • EIP-712 signed RFQ quotes from Main Market Makers │
│ • Direct trades between users and MMMs │
│ • Instant execution with professional pricing │
│ • Partial fills and nonce-based quote invalidation │
│ • RFQ-specific fee structure │
└──────────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ DiffusalOptionsSeriesRegistry │
│ ───────────────────────────────────────────────────────────── │
│ • Series lifecycle management (create, validate, settle) │
│ • Lazy series registration on first trade │
│ • Settlement price tracking for expired options │
│ • TWAP-based settlement via DiffusalPriceHistory │
│ • Operator pattern for authorized updates │
└──────────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ DiffusalOptionsPositionManager │
│ ───────────────────────────────────────────────────────────── │
│ • Tracks user positions per option series (long/short) │
│ • Entry premium tracking for PnL calculations │
│ • Operator pattern for multi-source position updates │
│ • Main Market Maker (MMM) designation for non-liquidatable MMs │
│ • Position tracking via portfolio updates │
│ • Portfolio-aware position tracking (per user per portfolio) │
└──────────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ DiffusalPortfolioManager │
│ ───────────────────────────────────────────────────────────── │
│ • Multiple portfolios per user for gas-bounded liquidations │
│ • Cross-margin within portfolios (max 16 positions each) │
│ • Position transfer between portfolios │
│ • Default portfolio (0) auto-created on first deposit │
└──────────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ DiffusalCollateralVault │
│ ───────────────────────────────────────────────────────────── │
│ • USDC collateral deposits and withdrawals │
│ • Portfolio margin with SPAN-like stress testing │
│ • Equity = Deposit + Unrealized PnL │
│ • Initial/Maintenance margin enforcement │
│ • Liquidation health checks (Equity < MM) │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ DiffusalSettlementEngine │
│ ───────────────────────────────────────────────────────────── │
│ • Settles expired options at intrinsic value │
│ • Credits long holders, debits short holders │
│ • Single and batch settlement operations │
│ • Prevents double-settlement via position tracking │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ DiffusalLiquidationEngine │
│ ───────────────────────────────────────────────────────────── │
│ • Liquidates undercollateralized users (Equity < MM) │
│ • Closes positions at penalized mark price │
│ • Pays liquidator bounty (5% of debt) │
│ • External insurance fund covers shortfalls │
│ • Supports partial liquidation (debt/IM proportional) │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ DiffusalSettlementReadinessLiquidator │
│ ───────────────────────────────────────────────────────────── │
│ • Liquidates users lacking cash for expiring obligations │
│ • Waterfall: non-expiring longs → premium receivables │
│ • Partial position liquidation to hit exact target │
│ • Insurance-backed bounty for liquidators │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ DiffusalInsuranceFund │
│ ───────────────────────────────────────────────────────────── │
│ • Receives all protocol trading fees (feeRecipient) │
│ • Covers shortfalls when called by LiquidationEngine. │
│ • Owner-controlled withdrawals │
│ • Stores funds in CollateralVault deposit │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ DiffusalPriceHistory │
│ ───────────────────────────────────────────────────────────── │
│ • Stores price snapshots for TWAP calculations │
│ • 2-hour circular buffer with 240 snapshots (30s intervals) │
│ • 1-hour TWAP window for settlement price calculation │
│ • Operator-only snapshot taking │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ Extracted Helper Contracts │
│ ───────────────────────────────────────────────────────────── │
│ DiffusalMarginCalculator │
│ • Margin calculations extracted from CollateralVault │
│ • Equity, IM/MM, health, liquidatable status per portfolio │
│ │
│ DiffusalLiquidationCalculator │
│ • View functions extracted from LiquidationEngine │
│ • getLiquidationInfo, getLiquidatablePortfolios │
│ │
│ DiffusalLiquidationSettlement │
│ • Settlement logic extracted from LiquidationEngine │
│ • Handles collateral flows, bounties, insurance coverage │
│ │
│ DiffusalSettlementReadinessCalculator │
│ • View functions extracted from SettlementReadinessLiquidator │
│ • Settlement readiness info, liquidatable portfolios │
└─────────────────────────────────────────────────────────────────┘