Fully On-Chain European Options Protocol with Black-Scholes Pricing Engine
Architecture • Getting Started • Contracts • Math Engine • Testing • Security • Contributing
MantissaFi is a fully on-chain European options protocol that computes Black-Scholes-Merton pricing, Greeks (Delta, Gamma, Theta, Vega), and the cumulative normal distribution function (Φ) entirely in Solidity — with provable accuracy bounds and gas efficiency.
- Gas-Optimized BSM Engine — Full Black-Scholes pricing in <80K gas using PRBMath SD59x18 with Rational Chebyshev approximation for Φ(x) achieving <0.0001% error
- Liquidity-Sensitive IV Surface (LSIVS) — On-chain implied volatility derived from realized volatility, skew modeling, and pool utilization — no off-chain IV oracle dependency
- On-Chain Greeks — Delta, Gamma, Theta, Vega computed fully on-chain with shared intermediate values
- Formally Verified — Certora/Halmos invariant proofs for solvency, put-call parity, pricing monotonicity, and CDF bounds
| Feature | Lyra/Derive | Dopex/Stryke | Panoptic | MantissaFi |
|---|---|---|---|---|
| Pricing model | BSM (off-chain IV) | BSM (off-chain IV) | Oracle-free (LP) | BSM (fully on-chain) |
| IV source | GWAV + Deribit | External | N/A | On-chain LSIVS |
| Greeks on-chain | ❌ | ❌ | Partial | ✅ Full suite |
| Formal verification | ❌ | ❌ | ❌ | ✅ Certora proofs |
| Gas per price | N/A (off-chain) | N/A (off-chain) | ~80K | < 80K |
┌─────────────────────────────────────────────────────────────────┐
│ MantissaFi Protocol │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌───────────────────────┐ │
│ │ OptionVault │ │ BSMEngine │ │ VolatilitySurface │ │
│ │ │ │ │ │ │ │
│ │ • mint() │──│ • price() │──│ • getIV() │ │
│ │ • exercise() │ │ • delta() │ │ • updateRealizedVol() │ │
│ │ • settle() │ │ • gamma() │ │ • skewAdjust() │ │
│ │ • liquidate()│ │ • theta() │ │ • utilizationAdjust() │ │
│ └──────┬───────┘ │ • vega() │ └───────────┬───────────┘ │
│ │ │ • cdf() │ │ │
│ │ └──────────────┘ │ │
│ ┌──────▼───────┐ ┌──────────────┐ ┌──────────▼────────────┐ │
│ │ LiquidityPool│ │ FixedPoint │ │ OracleAdapter │ │
│ │ │ │ MathLib │ │ │ │
│ │ • deposit() │ │ • exp() │ │ • Chainlink │ │
│ │ • withdraw() │ │ • ln() │ │ • Pyth │ │
│ │ • allocate() │ │ • sqrt() │ │ • TWAP │ │
│ │ • hedgeDelta │ │ • cdf() │ │ • RealizedVol │ │
│ └──────────────┘ │ • pdf() │ └───────────────────────┘ │
│ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌───────────────────────┐ │
│ │ OptionToken │ │ Settlement │ │ AccessControl │ │
│ │ (ERC-1155) │ │ Engine │ │ & Governance │ │
│ └──────────────┘ └──────────────┘ └───────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
git clone https://github.com/0xfandom/mantissa-fi.git
cd mantissa-fi
forge installforge build# Unit tests
forge test
# Fuzz tests (10,000 runs)
forge test --match-path "test/fuzz/*" -vvv
# Gas report
forge test --gas-report
# Fork tests (requires RPC URL)
FORK_URL=<your-rpc-url> forge test --match-path "test/fork/*" --fork-url $FORK_URLforge script script/Deploy.s.sol --rpc-url $RPC_URL --broadcast --verifysrc/
├── core/
│ ├── OptionVault.sol # Main entry — mint, exercise, settle options
│ ├── LiquidityPool.sol # LP deposits, withdrawals, delta hedging
│ ├── OptionToken.sol # ERC-1155 multi-token for option positions
│ └── Settlement.sol # Expiry settlement, ITM/OTM resolution
├── pricing/
│ ├── BSMEngine.sol # Black-Scholes-Merton pricing engine
│ ├── FixedPointMathLib.sol # exp, ln, sqrt optimized for BSM
│ ├── CumulativeNormal.sol # High-precision Φ(x) — Hart's approximation
│ └── Greeks.sol # Delta, Gamma, Theta, Vega computation
├── volatility/
│ ├── VolatilitySurface.sol # LSIVS — implied volatility surface
│ ├── RealizedVolOracle.sol # EWMA realized volatility from price feeds
│ └── SkewModel.sol # Strike-dependent IV adjustment
├── oracle/
│ ├── OracleAdapter.sol # Multi-oracle: Chainlink + Pyth + TWAP
│ └── PriceValidator.sol # Staleness & deviation checks
├── periphery/
│ ├── OptionRouter.sol # User-facing multicall helper
│ ├── OptionLens.sol # View functions for frontends
│ └── FeeController.sol # Dynamic fee model
└── libraries/
├── OptionMath.sol # Payoff calculations, moneyness helpers
├── TimeLib.sol # Timestamp → annualized time conversion
└── Constants.sol # Fixed-point constants (√2π, e, etc.)
C = S · Φ(d₁) - K · e^(-rT) · Φ(d₂)
d₁ = [ln(S/K) + (r + σ²/2) · T] / (σ · √T)
d₂ = d₁ - σ · √T
The cumulative normal distribution Φ(x) is computed using a 7-term rational polynomial achieving < 7.5 × 10⁻⁸ maximum error at approximately 8,000 gas.
| Operation | Target Gas |
|---|---|
| Φ(x) — CDF | < 10,000 |
| Full BSM price | < 80,000 |
| All 4 Greeks | < 100,000 |
| Mint option | < 150,000 |
| Exercise option | < 100,000 |
All pricing outputs are validated against scipy.stats.norm (Python) across 10,000+ fuzzed input vectors:
- CDF max error: < 1 × 10⁻⁵
- BSM price max relative error: < 0.01%
- Put-call parity deviation: < 0.001 USDC per option
| Category | Location | Description |
|---|---|---|
| Unit | test/unit/ |
Individual function correctness |
| Fuzz | test/fuzz/ |
Property-based with random inputs |
| Invariant | test/invariant/ |
Protocol-wide invariant testing |
| Integration | test/integration/ |
Full option lifecycle |
| Fork | test/fork/ |
Against mainnet state |
| Differential | test/differential/ |
Solidity vs Python reference |
| Gas | test/gas/ |
Gas benchmarking suite |
cd analysis/
pip install -r requirements.txt
python precision_test.py # Generates test vectors
cd ..
forge test --match-path "test/differential/*"| Invariant | Description | Status |
|---|---|---|
| Solvency | Pool assets ≥ max payoff obligations | 🔲 |
| Pricing Monotonicity | ∂C/∂S > 0, ∂P/∂S < 0, Vega > 0 | 🔲 |
| Put-Call Parity | C - P = S - K·e^(-rT) within ε | 🔲 |
| CDF Bounds | 0 ≤ Φ(x) ≤ 1, Φ(-x) = 1 - Φ(x) | 🔲 |
| No Value Extraction | profit ≤ intrinsic - premium | 🔲 |
slither src/
aderyn .See SECURITY.md for the complete threat model covering oracle manipulation, flash loan attacks, precision exploits, IV manipulation, and donation attacks.
- Phase 0: Project setup, repository structure
- Phase 1: Math engine (CDF, BSM, Greeks) — Weeks 1–3
- Phase 2: Protocol core (Vault, Pool, Settlement) — Weeks 4–7
- Phase 3: Volatility surface (LSIVS, EWMA, Skew) — Weeks 8–10
- Phase 4: Security & formal verification — Weeks 11–13
- Phase 5: Documentation, paper, presentation — Weeks 14–16
| Component | Technology |
|---|---|
| Language | Solidity ^0.8.25 |
| Framework | Foundry |
| Math Library | PRBMath v4 (SD59x18) |
| Token Standard | ERC-1155 (OpenZeppelin) |
| Oracle | Chainlink, Pyth, Custom TWAP |
| Formal Verification | Certora / Halmos |
| Static Analysis | Slither, Aderyn |
| Differential Testing | Python (scipy, numpy) |
Contributions are welcome! Please read CONTRIBUTING.md before submitting PRs.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Run tests (
forge test) - Commit changes (
git commit -m 'feat: add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License — see the LICENSE file for details.
- PRBMath — Fixed-point arithmetic
- SolStat — Statistical functions in Solidity
- OpenZeppelin — Security standards
- Black, F. & Scholes, M. (1973) — The Pricing of Options and Corporate Liabilities
- Abramowitz & Stegun (1964) — Handbook of Mathematical Functions