# DeFiMath

> Gas-optimized Solidity library for DeFi math: options pricing, Greeks, implied-volatility solver, interest rates, and portfolio statistics. Pure Solidity, MIT-licensed, no runtime dependencies. Validated by a two-layer test suite: 623 Hardhat correctness tests + 92 Foundry property-based fuzz tests (2.94M random executions per CI run). Built on the new CLZ opcode (EIP-7939, EVM Osaka) for headline gas wins: Black-Scholes call pricing in 2,708 gas (~4.9× cheaper than Derivexyz), binary call in 1,997 gas (~8× cheaper than Haptic), cube root in 340 gas (~37% cheaper than Solady's cbrtWad), and natural log in 390 gas at 18-decimal fixed-point precision.

Requires Solidity `^0.8.31` and `evmVersion: "osaka"`. Install: `npm install defimath-lib`.

## Math primitives

- [Math overview](https://defimath.com/docs/math/): `exp`, `ln`, `log2`, `log10`, `pow`, `sqrt`, `cbrt`, `stdNormCDF`, `erf`, `expm1`, `log1p` — all 18-decimal fixed-point
- [exp](https://defimath.com/docs/math/exp/): Exponential `e^x`, 327 gas, max rel error 7.2e-14 / max abs error 5.0e-14, three-stage range reduction + [2,2] Padé approximant
- [ln](https://defimath.com/docs/math/ln/): Natural logarithm, 390 gas, max rel error 1.6e-15 / max abs error 1.0e-15, CLZ range reduction + 10-term Mercator series
- [sqrt](https://defimath.com/docs/math/sqrt/): Square root, 197 gas, max rel error 2.0e-18, CLZ-derived power-of-two seed (2^floor(bits/2)) + 5 Newton iterations, full uint256 domain (no revert)
- [cbrt](https://defimath.com/docs/math/cbrt/): Cube root, 340 gas, max rel error 2.0e-13 / max abs error 3.0e-16, CLZ-derived initial guess + 6 Newton iterations, full uint256 domain (no revert)
- [erf](https://defimath.com/docs/math/erf/): Error function, 691 gas, max abs error 2.0e-14, West's rational approximation
- [stdNormCDF](https://defimath.com/docs/math/stdnormcdf/): Standard normal CDF Φ(x), 660 gas, max abs error 6.4e-15, same kernel as `erf` via `x/√2` substitution

## DeFi modules

- [Options](https://defimath.com/docs/options/): Black-Scholes European call/put pricing, full Greeks (delta, gamma, theta, vega), Newton-Raphson IV solver. `callOptionPrice` 2,708 gas, `putOptionPrice` 2,718 gas, `delta` 1,703 gas, `vega` 1,415 gas
- [Binary options](https://defimath.com/docs/binary/): Cash-or-nothing binary call/put + full Greeks. `binaryCallPrice` 1,997 gas, `binaryPutPrice` 2,002 gas (~8× cheaper than Haptic 16,218)
- [Futures](https://defimath.com/docs/futures/): Continuous-compounding futures pricing
- [Rates](https://defimath.com/docs/rates/): Compound interest, present value, log returns, APR↔APY conversions, yield to maturity, IRR. `internalRateOfReturn` solves Σ Cᵢ·e^(−r·tᵢ)=0 via Newton-Raphson
- [Statistics](https://defimath.com/docs/statistics/): `mean`, `stdDev`, `weightedAverage`, `historicalVolatility`, `sharpeRatio`, `maxDrawdown`, `valueAtRisk`, `conditionalValueAtRisk` (CVaR / expected shortfall)

## Testing

- [Testing approach](https://defimath.com/docs/#testing): Two independent test layers. Hardhat: 623 tests validating against external JS references (`Math`, `math-erf`, `black-scholes`, `greeks`, `simple-statistics`) with strict-equality gas-regression gates. Foundry: 92 mathematical properties organized into round-trips, monotonicity, identities, output bounds, and symmetries; 32,000 fuzz runs per property = 2.94M random executions per CI run, with automatic counterexample shrinking.

## Gas comparison vs other libraries

DeFiMath / Solady / PRBMath / ABDK / SolStat — lower is better:

- `exp`: 331 / 372 / 2,820 / 5,840 / —
- `ln`: 373 / 518 / 6,910 / 12,667 / —
- `sqrt`: 197 / 384 / 944 / 808 / —
- `cbrt`: 340 / 550 / — / — / —
- `stdNormCDF`: 660 / — / — / — / 2,794
- `erf`: 685 / — / — / — / 1,732
- `callOptionPrice`: 2,708 / — / — / — / — (vs Derivexyz 13,360 — 4.9× cheaper, Premia 20,623, Party1983 35,963, Dopex 88,969)
- `binaryCallPrice`: 1,997 (vs Haptic 16,218 — 8.1× cheaper)

## Blog

- [CLZ in Solidity: a one-opcode shortcut for fixed-point math](https://defimath.com/blog/clz-opcode-solidity/): How DeFiMath uses the EIP-7939 CLZ opcode to power `sqrt`, `cbrt`, and `ln`. Newton-Raphson initial guesses, log₂ range reduction in one instruction, full gas comparison vs PRBMath, ABDK, Solady. Includes the compounding effect: Black-Scholes option pricing is ~10% cheaper because `sqrt` and `ln` are inside the formula.

## Source

- [GitHub: defimath](https://github.com/MerkleBlue/defimath): Library source, tests, full docs
- [GitHub: defimath-compare](https://github.com/MerkleBlue/defimath-compare): Reproducible gas + precision benchmarks against PRBMath, ABDK, Solady, SolStat, Derivexyz, Premia, Party1983, Dopex, Haptic
- [npm: defimath-lib](https://www.npmjs.com/package/defimath-lib): Latest published package (currently v3.6.0)

## Optional

- [News](https://defimath.com/news/): Release notes and announcements
- [v3.6.0 release notes](https://defimath.com/news/2026-07-19-defimath-v3-6-0-released/): sqrt and cbrt handle the full uint256 domain (no more SqrtUpperBoundError / CbrtUpperBoundError). sqrt 245→197 gas (−20%), cbrt 368→340 gas (−8%) via a new CLZ-derived power-of-two seed (2^floor(bits/2)) + 5 Newton iterations for sqrt, and a two-branch structure for cbrt. Plus pow overflow bugfix (new MAX_POW_EXPONENT bound) and downstream savings in Rates and Statistics.
- [v3.5.0 release notes](https://defimath.com/news/2026-06-27-defimath-v3-5-0-released/): Extended boundaries release. sqrt upper bound widened to the full FP18-safe uint256 range (~1.21e42 → ~1.158e59). Options & Binary MAX_EXPIRATION extended from 2 years to 32 years — admits long-dated insurance, RWA bond options, and other long-horizon products. Same precision, same gas, no API change.
- [v3.4.0 release notes](https://defimath.com/news/2026-06-14-defimath-v3-4-0-released/): Foundry property-based fuzz testing layer added — 92 mathematical properties × 32,000 random runs per CI run = 2.94M random executions. Plus signed-int refactor of EXP_LOWER_BOUND saves 1–3 gas across every function calling exp.
- [v3.1.0 release notes](https://defimath.com/news/2026-05-27-defimath-v3-1-0-released/): cbrt function added — 368 gas, ~33% cheaper than Solady's cbrtWad at identical precision