Skip to content

v4.0.0

Latest
Latest

Choose a tag to compare

View all tags
@nebojsakonsta nebojsakonsta released this 06 Aug 06:51
v4.0.0
6c87c4d

v4.0.0 - Black-76, and a cleaner API

The first major release since v3.0.0. It adds a Black-76 module for pricing European options on a future, and renames every library for a cleaner, prefix-free API. The renames change import paths and call sites, so this is a breaking release — see Migration below. No numeric result, signature, precision, or gas figure changed in the rename.

✨ New - Black-76 module

Black76 prices dated European options whose underlying is a future (options on commodity, rate, and crypto futures). Same surface as Black-Scholes — call, put, the four Greeks, and a Newton-Raphson impliedVolatility solver.

Function Gas Returns
call 2,552 call price
put 2,565 put price
delta 1,915 (Δcall, Δput)
gamma 1,704 Γ (call = put)
theta 3,255 (Θcall, Θput), per day
vega 1,659 ν (call = put), per 1% vol
impliedVolatility 11,760 / 11,802 IV from call / put price

Prices hold to 5e-12 relative error (1.3e-10 absolute deep-OTM), verified in CI against a black-scholes/greeks reference through the discounting identity price = e^(−rT)·BS(F, K, T, σ, 0).

⚠️ Breaking - library reorganization

Every library dropped its DeFiMath* prefix, the two derivative modules were renamed, and contracts/finance/ split into contracts/rates/ and contracts/statistics/.

v3.x v4.0.0
DeFiMath · math/Math.sol Math · math/Math.sol
DeFiMathOptions · derivatives/Options.sol BlackScholes · derivatives/BlackScholes.sol
DeFiMathBinary · derivatives/Binary.sol BinaryOptions · derivatives/BinaryOptions.sol
DeFiMathFutures · derivatives/Futures.sol Futures · derivatives/Futures.sol
DeFiMathRates · finance/Rates.sol Rates · rates/Rates.sol
DeFiMathStats · finance/Stats.sol Statistics · statistics/Statistics.sol
— Black76 · derivatives/Black76.sol (new)

Two function families were also renamed now that the library namespace carries the context:

  • Black-Scholes: callOptionPrice → call, putOptionPrice → put (Greeks unchanged: delta, gamma, theta, vega, impliedVolatility).
  • Binary options: the binary prefix is gone — binaryCallPrice → call, binaryPutPrice → put, binaryDelta → delta, binaryGamma → gamma, binaryTheta → theta, binaryVega → vega.

Migration

Upgrading is a find-and-replace on names and import paths — signatures, return types, and every numeric result are identical.

// v3.x
import "defimath-lib/contracts/derivatives/Options.sol";
import "defimath-lib/contracts/finance/Stats.sol";

uint256 px = DeFiMathOptions.callOptionPrice(spot, strike, timeToExp, vol, rate);
uint256 sd = DeFiMathStats.stdDev(data);

// v4.0.0
import "defimath-lib/contracts/derivatives/BlackScholes.sol";
import "defimath-lib/contracts/statistics/Statistics.sol";

uint256 px = BlackScholes.call(spot, strike, timeToExp, vol, rate);
uint256 sd = Statistics.stdDev(data);

🐛 Fixed

  • BlackScholes.delta expired-put sign. At expiry (timeToExp == 0) the put leg of an in-the-money option returned +1 instead of −1. Fixed, with a regression test that fuzzes moneyness at expiry and asserts the delta bounds and put-call delta parity. The new Black76 module handles this case correctly from the start.

📈 Improved

  • Full NatSpec on every derivative function — parameter semantics, error metric, and the enforced bound, matching the math primitives.
  • Where a function has both a relative and an absolute guarantee, both are now documented and published: relative error where |result| ≥ 1, absolute where |result| < 1.

🧪 Testing

  • 740 Hardhat correctness tests (Black-76 adds 100, validated against the discounting identity).
  • 114 Foundry properties × 32,000 runs = 3,648,000 random executions per CI run (Black-76 adds 16: put-call parity, delta parity δcall − δput = e^(−rT), discounted bounds, monotonicity, IV round-trips).

📦 Install

npm install defimath-lib
Assets 2
Loading