defimath-lib

DeFiMath

Gas-optimized Solidity library for DeFi math. Black-Scholes option pricing at 2,708 gas, with a broad set of primitives across math, interest rates, statistics, and derivatives.

DeFiMath is a pure-Solidity library of DeFi math primitives. 40+ functions across four modules: low-level math, derivatives, interest rates, and statistics. No external runtime dependencies. MIT-licensed.

Why DeFiMath

• Unlocks new use cases. Gas-efficient enough to make real-time options pricing, on-chain IV solving on every quote, and risk-adjusted vault fees economically viable. Use cases that were previously off-chain workarounds now fit in a single transaction.
• Breadth. 40+ primitives spanning math (exp, ln, sqrt), derivatives (Black-Scholes + Greeks, binary options, IV solver), interest rates (compound, present value, IRR, YTM), and statistics (volatility, Sharpe, VaR, CVaR, max drawdown).
• Pure Solidity. ~16KB published, zero runtime dependencies, easy to audit.
• Validated precision. Sub-1e-10 absolute error on options pricing. Every math primitive carries an explicit, enforced error bound — from 2e-18 (sqrt) to 1e-11 (pow) — measured as relative error where the result is ≥ 1 and absolute error near a root or for bounded functions like stdNormCDF and erf; see the per-function tables below. Validated against simple-statistics, black-scholes, greeks, and math-erf reference libraries.

Benchmarks

Every function is benchmarked against existing on-chain implementations. A representative comparison:

Function	DeFiMath	Next best	Multiple
callOptionPrice	2,708	13,360 (Derivexyz)	4.9×
putOptionPrice	2,718	13,363 (Derivexyz)	4.9×
binaryCallPrice	1,997	16,218 (Haptic)	8.1×
delta	1,703	8,621 (Derivexyz)	5.1×
vega	1,415	7,490 (Derivexyz)	5.3×
ln	373	518 (Solady)	1.4×
sqrt	197	384 (Solady)	1.9×
cbrt	340	550 (Solady)	1.6×
stdNormCDF	660	2,794 (SolStat)	4.2×

Full per-function tables in the defimath-compare README.

Install

Hardhat / npm

npm install defimath-lib

Foundry

forge install defimath-lib=MerkleBlue/defimath

Then add to remappings.txt:

defimath-lib/=lib/defimath-lib/

The defimath-lib= install alias plus this remapping make the same import "defimath-lib/contracts/derivatives/Options.sol" line work under both Foundry and Hardhat. Without the remapping, Foundry auto-detects contracts/ as the src directory and produces defimath-lib/=lib/defimath-lib/contracts/, which collides with the leading contracts/ segment in the import path.

Either way, your project must target Solidity ^0.8.31 and evmVersion: "osaka" (Fusaka). The library uses the clz Yul builtin (added in Solidity 0.8.31) which emits the CLZ opcode introduced in Osaka — both the compiler version and EVM target are hard requirements.

Usage

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.31;

import "defimath-lib/contracts/derivatives/Options.sol";

contract OptionsExchange {
    function quote(
        uint128 spot, uint128 strike, uint32 timeToExp,
        uint64 vol, uint64 rate
    ) external pure returns (uint256 callPx, uint256 putPx) {
        callPx = DeFiMathOptions.callOptionPrice(spot, strike, timeToExp, vol, rate);
        putPx  = DeFiMathOptions.putOptionPrice(spot, strike, timeToExp, vol, rate);
    }
}

All values use 18-decimal fixed-point (1e18 = 1.0). Time is in seconds. See module docs for full parameter conventions.

Functions

Math primitives — DeFiMath (Math.sol)

Function	Gas	Max abs error	Max rel error	Description
exp	327	5.0e-14	7.2e-14	Exponential function e^x
ln	390	1.0e-15	1.6e-15	Natural logarithm
log2	406	1.0e-15	1.6e-15	Base-2 logarithm
log10	406	1.0e-15	1.6e-15	Base-10 logarithm
pow	803	—	1.0e-11	Power function x^a
sqrt	197	1.0e-18	2.0e-18	Square root
cbrt	340	3.0e-16	2.0e-13	Cube root
expm1	407	1.5e-13	1.0e-13	e^x − 1 (precision-preserving for small x)
log1p	476	1.0e-15	1.6e-15	ln(1 + x) (precision-preserving for small x)
stdNormCDF	660	6.4e-15	—	Standard normal CDF Φ(x)
erf	691	2.0e-14	—	Error function
mulDiv	155	exact	exact	(a · b) / d with full 512-bit intermediate precision
mul	130	exact	exact	(a · b) / 1e18 — fixed-point multiply with denominator baked in
abs	17	exact	exact	Branchless |int256| (handles int256.min cleanly)
min	23	exact	exact	Branchless minimum of two uint256
max	23	exact	exact	Branchless maximum of two uint256
clamp	78	exact	exact	Clamp x into [lo, hi] (composed max then min)
avg	21	exact	exact	Overflow-safe (a + b) / 2 via (a & b) + ((a ^ b) >> 1)

Figures are the error bounds the test suite enforces — the constants in test/hardhat/Tolerances.test.mjs, asserted against a JS / decimal.js reference across each function's full documented domain. The metric follows the result magnitude: relative where |result| ≥ 1, absolute where |result| < 1. Relative error is undefined at a function's root (ln at x = 1, expm1/log1p at x = 0), where any nonzero error divides by ~0 — absolute is the meaningful bound there. Both are published wherever the suite bounds both. — marks a metric the suite does not bound: erf and stdNormCDF are bounded in [−1, 1] and [0, 1] so only absolute is meaningful; pow is relative-only for now. sqrt's absolute bound of 1.0e-18 is exactly 1 wei — it is correctly rounded below 1. log2, log10 and log1p inherit ln's bounds. exact denotes integer-arithmetic functions with no approximation error.

Derivatives — DeFiMathOptions, DeFiMathBinary, DeFiMathFutures

Function	Gas	Max abs error	Max rel error	Description
callOptionPrice	2,708	1.3e-10	—	European call (Black-Scholes)
putOptionPrice	2,718	1.3e-10	—	European put (Black-Scholes)
delta	1,703	1.2e-13	—	First derivative w.r.t. spot
gamma	1,475	3.2e-15	—	Second derivative w.r.t. spot
theta	3,269	1.9e-12	—	Time decay (per day)
vega	1,415	4e-13	—	Sensitivity to volatility
impliedVolatility	12,334	—	1.0e-6	IV via Newton-Raphson
binaryCallPrice	1,997	2e-12	—	Cash-or-nothing call
binaryPutPrice	2,002	2e-12	—	Cash-or-nothing put
binaryDelta	1,801	1e-13	—	Binary delta (signed)
binaryGamma	1,943	1e-15	—	Binary gamma (signed)
binaryTheta	3,329	1e-14	—	Binary theta (per day)
binaryVega	1,889	1e-14	—	Binary vega (signed)
futurePrice	442	1.2e-9	—	spot · e^(rt)

Bounds enforced by the test suite — the constants in test/hardhat/Tolerances.test.mjs. Absolute error is the metric throughout: option prices are quoted at a $1,000 spot (so 1.3e-10 is in dollars), binaries at unit payout, theta per day and vega per 1% vol. impliedVolatility is the exception — it is bounded by round-trip relative error against its Newton-Raphson convergence target.

Interest & rates — DeFiMathRates (Rates.sol)

Function	Gas	Max abs error	Max rel error	Description
compoundInterest	467	—	5.4e-14	Continuous compounding: P · e^(rt)
presentValue	519	—	5.4e-14	Discounting: FV · e^(−rt)
logReturn	600	—	1.6e-15	ln(currentPrice / previousPrice)
continuousToDiscrete	491	1e-15	—	e^apr − 1 (APR → APY)
discreteToContinuous	574	1e-15	—	ln(1 + apy) (APY → APR)
yieldToMaturity	736	—	5.4e-14	Zero-coupon YTM (closed form)
internalRateOfReturn	17k–49k	—	1e-9	IRR via Newton-Raphson (cost scales with cashflow count)

Bounds enforced by the test suite — the constants in test/hardhat/Tolerances.test.mjs. Compounding and discounting inherit exp's relative bound, logReturn inherits ln's. The two rate conversions are bounded absolutely (1e-15) because they run a Taylor branch through their root at r = 0, where relative error is undefined. internalRateOfReturn is bounded by its Newton-Raphson convergence tolerance.

Statistics — DeFiMathStats (Stats.sol)

Function	Gas	Max abs error	Max rel error	Description
geometricMean	284	—	2.2e-14	sqrt(a · b) — Uniswap V2 invariant
mean	6,980 @ 30 elem	—	1e-15	Arithmetic mean
stdDev	15,298 @ 30 elem	—	2.2e-14	Sample std. dev. (Bessel-corrected)
weightedAverage	15,687 @ 30 elem	—	1e-15	Σ(v·w) / Σ(w)
historicalVolatility	25,820 @ 30 prices	—	2.2e-14	Annualized vol from log returns
sharpeRatio	25,958 @ 30 prices	—	2.2e-14	Risk-adjusted return
maxDrawdown	15,470 @ 30 prices	—	1e-15	Peak-to-trough decline
valueAtRisk	34,531 @ 30 prices	—	2.2e-14	NumPy-compatible linear interpolation
conditionalValueAtRisk	31,889 @ 30 prices	—	2.2e-14	Expected shortfall (left tail mean)

Bounds enforced by the test suite — the constants in test/hardhat/Tolerances.test.mjs. All results are ≥ 1 in practice, so relative error is the metric throughout. 1e-15 marks arithmetic-only aggregation (essentially exact, at IEEE 754 machine epsilon); 2.2e-14 covers the multi-step paths (variance → vol → Sharpe) that accumulate rounding. valueAtRisk is validated against simple-statistics.

Testing

Two independent layers:

• Hardhat — 623 tests validating against external JavaScript references (Math, math-erf, black-scholes, greeks, simple-statistics) at concrete points across the operational domain, plus strict-equality gas-regression assertions on every performance test.
• Foundry — 92 mathematical properties × 32,000 random runs each = 2,944,000 random executions per CI run. Validates the algebraic structure (round-trips, monotonicity, identities, output bounds, symmetries) with automatic counterexample shrinking.

715 total tests. Run with npm test. Sources live at test/hardhat/ and test/foundry/. Per-module test breakdowns on the Documentation page.

Precision

Every function is validated against trusted JavaScript reference implementations: black-scholes, greeks, math-erf, and simple-statistics. Per-function error figures appear in the tables above; the full benchmark suite — including head-to-head precision vs. competing libraries — lives in defimath-compare.

License

MIT.